Ostatnia aktualizacja: 2026-11-16
- Wybierz sposób wykrywania zmian dostępny w źródle: webhook, mechanizm delta albo harmonogram.
- Używaj stabilnego identyfikatora dokumentu i zapisuj stan jego przetwarzania.
- Obsłuż osobno zmianę, usunięcie, przeniesienie i błąd dostępu.
- Po aktualizacji sprawdź status indeksu oraz pytanie, na które zmieniony dokument powinien wpływać.
Sposób wykrywania zmian zależy od możliwości systemu źródłowego. Może on wysyłać powiadomienia o zdarzeniach, udostępniać historię zmian albo pozwalać jedynie na okresowe sprawdzanie dokumentów. Niezależnie od wariantu proces powinien obejmować również usunięcia, błędy dostępu i końcową weryfikację.
Aktualizacja bazy wiedzy to proces, nie sam import pliku
W typowej integracji automatyczna aktualizacja obejmuje wykrycie zmiany, pobranie lub przetworzenie dokumentu, aktualizację indeksu i sprawdzenie statusu.[1][2][4] Kolejność oraz nazwy tych etapów mogą różnić się między systemami.
Dokument źródłowy, przetworzona treść i wpis w indeksie to odrębne stany. Repozytorium przechowuje plik, natomiast indeks zawiera reprezentację używaną do wyszukiwania lub tworzenia odpowiedzi. W systemach z oddzielnym etapem indeksowania zmiana źródła musi więc zostać doprowadzona do zakończenia przetwarzania indeksu. Niektóre platformy ukrywają ten etap i wykonują go automatycznie.[2][4]
- Wykrycie zmiany: proces otrzymuje zdarzenie albo sam sprawdza stan źródła.
- Identyfikacja dokumentu: zmiana zostaje powiązana z właściwym dokumentem i jego wersją.
- Pobranie treści: system odczytuje aktualny materiał ze źródła.
- Przetworzenie: dokument przechodzi etap wymagany przez używaną bazę wiedzy.
- Aktualizacja indeksu: nowa treść zastępuje poprzedni wpis lub zostaje dodana jako nowy dokument.
- Weryfikacja: status procesu i pytanie testowe potwierdzają dostępność nowej wiedzy.
Taki model pozwala wskazać, na którym etapie zatrzymała się aktualizacja. Sam fakt zapisania nowego pliku nie potwierdza jeszcze, że użytkownik otrzyma aktualną odpowiedź.
Jak wykrywać zmiany: webhook, delta query czy harmonogram?
Mechanizm wykrywania należy dobrać do funkcji udostępnianych przez źródło. Webhook może uruchamiać synchronizację po zdarzeniu, natomiast model pull sprawdza repozytorium na żądanie lub według harmonogramu. Jeżeli źródło obsługuje mechanizm delta, można pobierać tylko elementy zmienione od poprzedniej synchronizacji.[1][3]
| Mechanizm | Kiedy ma zastosowanie | Mocna strona | Ograniczenie, które trzeba obsłużyć |
|---|---|---|---|
| Webhook | Źródło wysyła powiadomienia o zdarzeniach | Może uruchomić proces bez oczekiwania na kolejny cykl sprawdzania | Ponowienia, duplikaty, opóźnienia i kontrola kompletności |
| Mechanizm delta | Źródło udostępnia stan zmian od poprzedniej synchronizacji | Pobiera elementy zmienione zamiast całej kolekcji | Zachowanie tokenu stanu i ograniczenie do obsługiwanych zasobów |
| Harmonogram odpytywania | Źródło pozwala na okresowe sprawdzanie dokumentów | Może działać bez mechanizmu zdarzeniowego | Odstęp między sprawdzeniami i konieczność porównania stanu |
| Pełne porównanie lub manifest zmian | Źródło nie udostępnia wiarygodnych zdarzeń ani historii zmian | Pozwala okresowo skontrolować kompletność | Wymaga odczytu szerszego zakresu danych |
Webhook: kiedy źródło umie powiadomić o zdarzeniu
Webhook jest powiadomieniem wysyłanym po wystąpieniu określonego zdarzenia. Może uruchomić pobranie dokumentu, ale nie należy traktować go jako gwarancji kompletnej synchronizacji. Proces nadal musi obsługiwać ponowienia, zdublowane zdarzenia, opóźnienia i kontrolę tego, czy wszystkie zmiany zostały przetworzone.[3]
Delta query: pobieranie zmian od poprzedniej synchronizacji
Delta query to oficjalna nazwa mechanizmu Microsoft Graph dostępnego dla obsługiwanych zasobów. Pozwala śledzić nowe, zmienione i usunięte elementy od poprzedniego punktu synchronizacji. Nie jest to jednak funkcja uniwersalna: inne repozytoria mogą wymagać webhooka, znacznika wersji albo porównania stanu.[1]
Harmonogram i porównanie: rozwiązanie dla uboższych źródeł
Gdy źródło nie oferuje zdarzeń ani mechanizmu delta, proces może okresowo sprawdzać dokumenty i porównywać ich zapisany stan. Harmonogram należy traktować jako sposób uruchamiania kontroli, a nie dowód, że każda zmiana została prawidłowo przetworzona.
Aktualizacja przyrostowa ma sens, gdy system potrafi wiarygodnie ustalić zakres zmiany. W dokumentacji technicznej można wtedy aktualizować dotknięte elementy zamiast przetwarzać wszystko od początku. Wniosku tego nie należy przedstawiać jako gwarantowanej oszczędności dla każdej firmowej bazy wiedzy ani każdego wdrożenia.[7][8]
Co zrobić po wykryciu zmiany dokumentu?
Po wykryciu zmiany trzeba pobrać aktualną treść, powiązać ją ze stabilnym identyfikatorem dokumentu, przetworzyć i zaktualizować właściwy wpis w indeksie. Nazwa pliku lub ścieżka nie powinny być jedyną podstawą tego powiązania, ponieważ proces musi poprawnie zinterpretować również przeniesienie dokumentu.
Identyfikator, wersja i hash: co zapisać przy zmianie
Projektując synchronizację, zachowuj stabilny identyfikator, numer lub znacznik wersji oraz historię operacji. Jeżeli wdrożenie posługuje się hashem, może on pełnić rolę technicznego znacznika w tym procesie. Źródła potwierdzają poszczególne elementy śledzenia zmian, wersji i audytu w różnych systemach, ale nie ustanawiają jednego uniwersalnego standardu.[1][5][6]
Aktualizacja wpisu w indeksie
W indeksie trzeba rozróżnić dodanie lub zastąpienie dokumentu od jego usunięcia. Operacja typu upsert dodaje wpis, jeśli go nie ma, albo aktualizuje istniejący, lecz konkretne nazwy i zachowanie zależą od technologii. Określeń używanych przez Azure AI Search, takich jak mergeOrUpload, nie należy przenosić bezpośrednio na inne silniki.[2]
Statusy i bezpieczne ponowienie operacji
Status powinien wskazywać, czy zadanie zostało przyjęte, czy dokument został przetworzony oraz czy aktualna treść jest już dostępna w indeksie. Ponowienie nie powinno tworzyć niezależnej kopii tego samego dokumentu, dlatego musi korzystać z tego samego stabilnego identyfikatora.
- Odczytaj identyfikator dokumentu oraz jego aktualny znacznik wersji.
- Pobierz treść odpowiadającą wykrytej zmianie.
- Przetwórz dokument zgodnie z wymaganiami używanego systemu.
- Dodaj albo zaktualizuj właściwy wpis w indeksie.
- Zapisz status operacji i informację o błędzie, jeśli przetwarzanie się nie zakończyło.
- Przekaż dokument do testu dostępności dopiero po zakończeniu indeksowania.
Usunięcia, przeniesienia i konflikty wersji wymagają osobnych reguł
Synchronizacja musi obsługiwać nie tylko zmianę treści, lecz także usunięcie, przeniesienie i utratę dostępu do dokumentu. Wycofanie może oznaczać fizyczne usunięcie z indeksu, dezaktywację albo oznaczenie materiału jako nieaktualnego. Wybór zależy od możliwości systemu i polityki organizacji.[1][3][5]
Kiedy brak dokumentu nie oznacza jeszcze usunięcia
Nieudany odczyt może wynikać z przeniesienia pliku, utraty uprawnień albo chwilowej niedostępności źródła. Proces powinien więc rozróżniać potwierdzone usunięcie od błędu dostępu. Pozwala to uniknąć wycofywania treści wyłącznie na podstawie pojedynczego nieudanego sprawdzenia.
Priorytet źródeł i kanoniczna wersja
Jeżeli baza korzysta z wielu źródeł, dodaj mechanizm wykrywania duplikatów i konfliktów oraz reguły wskazujące aktualne źródło. Nie każda platforma rozstrzyga takie konflikty automatycznie, a w części przypadków potrzebna jest akceptacja człowieka. Wniosek ten opiera się na funkcjach opisanych dla platformy obsługującej wiele źródeł FAQ, więc nie należy przypisywać identycznego mechanizmu każdemu systemowi.[6]
Historia zmian oraz możliwość wycofania błędnej aktualizacji
Historia operacji powinna pozwalać powiązać aktywną wiedzę ze źródłem i znacznikiem wersji. Zachowanie poprzedniego stanu ułatwia wycofanie błędnej zmiany, jeśli dany system oferuje taką możliwość. Nie istnieje jednak jeden wspólny standard wersjonowania obejmujący wszystkie repozytoria i bazy wiedzy.
- Czy każdy dokument ma stabilny identyfikator niezależny od nazwy i ścieżki?
- Czy zapisywany jest numer albo znacznik wersji oraz historia operacji?
- Czy proces rozróżnia usunięcie, przeniesienie i błąd dostępu?
- Czy istnieje polityka dezaktywacji lub wycofania nieaktualnego dokumentu?
- Czy zdefiniowano priorytet źródeł i sposób obsługi konfliktów?
- Czy przed większym zakresem usunięć działa dodatkowa kontrola bezpieczeństwa?
- Czy możliwe jest przywrócenie poprzedniego stanu, jeśli aktualizacja okaże się błędna?
Jak potwierdzić, że użytkownik korzysta już z nowej wiedzy?
O powodzeniu nie świadczy samo zakończenie przesyłania pliku. Trzeba sprawdzić status przetwarzania oraz wykonać zapytanie testowe, ponieważ przesyłanie, indeksowanie i udostępnienie treści mogą następować asynchronicznie.[2][3][4]
Test końcowy powinien obejmować otwarcie dokumentu, sprawdzenie zakresu dostępu i pytanie, na które zmieniona treść powinna wpływać. Zakres testów należy dopasować do krytyczności dokumentu oraz sposobu używania bazy. Procedura pochodzi z praktyki opisanej dla konkretnej platformy, dlatego nie wyznacza jednego obowiązkowego modelu dla wszystkich rozwiązań.[5]
- Otwórz źródło i potwierdź, że zawiera właściwą wersję dokumentu.
- Sprawdź, czy system zakończył przetwarzanie i aktualizację indeksu.
- Zweryfikuj zakres dostępu odpowiadający docelowemu użytkownikowi.
- Zadaj reprezentatywne pytanie, na które zmiana powinna mieć wpływ.
- Zapisz wynik testu oraz status operacji w historii procesu.
Test wykonany wyłącznie z uprawnieniami administratora może nie odzwierciedlać sytuacji zwykłego użytkownika. Końcowa weryfikacja powinna więc uwzględniać nie tylko treść odpowiedzi, ale też właściwy zakres dostępu.
Najczęstsze pytania
Czy webhook wystarczy do aktualizowania bazy wiedzy?
Nie zawsze. Może uruchamiać proces po zdarzeniu, ale nadal trzeba obsłużyć ponowienia, duplikaty, opóźnienia i kontrolować status przetwarzania.
Czy po usunięciu pliku należy od razu usunąć go z indeksu?
Tylko gdy usunięcie jest potwierdzone. Brak pliku może wynikać z przeniesienia, utraty dostępu albo chwilowej niedostępności źródła.
Czy aktualizacja przyrostowa eliminuje potrzebę pełnej kontroli?
Nie. Jest użyteczna, gdy można wiarygodnie wskazać zmienione elementy, lecz proces nadal powinien uwzględniać kompletność danych i usunięcia.
Jak sprawdzić, czy chatbot korzysta z nowej wersji dokumentu?
Po zakończeniu przetwarzania wykonaj pytanie testowe, na które zmieniona treść powinna wpływać. Test przeprowadź przy uprawnieniach odpowiadających użytkownikowi końcowemu.
Źródła
- Use delta query to track changes in Microsoft Graph data, Microsoft Learn.
- Aktualizowanie lub ponowne kompilowanie indeksu, Microsoft Learn.
- Webhooks, Infus AI Documentation.
- Wprowadzenie do interfejsu API bazy wiedzy, Adobe.
- Konfigurowanie i zarządzanie bazą wiedzy, AI-Corporate.
- Baza wiedzy (FAQ) — DM Champ Docs, DM Champ Docs.
- Wait, wasn’t that code here before? Detecting Outdated Software Documentation, arXiv.
- RepoDoc: A Knowledge Graph-Based Framework to Automatic Documentation Generation and Incremental Updates, arXiv.
+Artykuł Sponsorowany+
