Konfiguracja źródeł synchronizacji¶

Źródła synchronizacji samodzielnie pobierają dokumenty z usług zewnętrznych (Google Drive, S3/MinIO, publiczna strona internetowa, repozytorium Git, witryna SharePoint albo OneDrive) do kolekcji wiedzy. Każde źródło przechowuje typ connectora, kolekcję docelową, ustawienia właściwe dla connectora, tryb synchronizacji, opcjonalny harmonogram oraz id sekretu w vault, który je uwierzytelnia - strona internetowa żadnego nie potrzebuje.

Gdy synchronizacja się uruchamia, connector wypisuje zdalne pliki, pobiera je do katalogu tymczasowego i przepuszcza przez standardowy potok przetwarzania (parsowanie, dzielenie na fragmenty, embedowanie, zapis). Gdy lista jest kompletna, dokumenty, które źródło wprowadziło wcześniej, a których już nie wypisuje, zostają usunięte. Wpis SyncLog odnotowuje wynik każdej operacji synchronizacji.

Architektura w skrócie¶

Komponent	Lokalizacja	Rola
`BaseSyncConnector`	`app/services/rag/connectors/__init__.py`	Abstrakcyjna baza wszystkich connectorów
`RemoteFile`	`app/services/rag/connectors/__init__.py`	Model Pydantic opisujący zdalny plik
`CONNECTOR_REGISTRY`	`app/services/rag/connectors/__init__.py`	Mapuje nazwy typów connectorów na klasy
`SyncSource` (model DB)	`app/db/models/sync_source.py`	Utrwala konfiguracje źródeł
`SyncLog` (model DB)	`app/db/models/sync_log.py`	Śledzi poszczególne operacje synchronizacji
`SyncSourceService`	`app/services/sync_source.py`	Logika biznesowa CRUD i wyzwalania
Komendy CLI dla RAG	`app/commands/rag.py`	Interfejs CLI do zarządzania źródłami
Trasy API dla RAG	`app/api/routes/v1/rag.py`	REST API do zarządzania źródłami

Szybki start -- CLI¶

Wypisz dostępne typy connectorów¶

# Shows all registered connectors (e.g. gdrive, s3, git, sharepoint)
uv run agenticos cmd rag-sources

Dodaj źródło Google Drive -- synchronizacja co 2 godziny¶

uv run agenticos cmd rag-source-add \
  --name "Legal docs" \
  --type gdrive \
  --org 0c8f2b1e-... \
  --collection legal \
  --config '{"folder_id": "1abc123def", "include_subfolders": true}' \
  --sync-mode new_only \
  --schedule 120

Dodaj źródło S3 -- tylko synchronizacja ręczna¶

uv run agenticos cmd rag-source-add \
  --name "Marketing" \
  --type s3 \
  --org 0c8f2b1e-... \
  --collection marketing \
  --config '{"bucket": "my-docs", "prefix": "marketing/"}' \
  --sync-mode full \
  --schedule 0

Dodaj źródło Git -- dokumentacja repozytorium, co noc¶

uv run agenticos cmd rag-source-add \
  --name "Handbook" \
  --type git \
  --org 0c8f2b1e-... \
  --collection handbook \
  --config '{"repository_url": "https://github.com/acme/handbook.git", "branch": "main", "path_prefix": "docs"}' \
  --sync-mode new_only \
  --schedule 1440

Następnie wybierz jego token dostępu jako poświadczenie źródła w interfejsie albo wyślij secret_id metodą PATCH — zobacz Konfiguracja repozytorium Git.

Dodaj źródło SharePoint -- jeden folder biblioteki, co 6 godzin¶

uv run agenticos cmd rag-source-add \
  --name "HR policies" \
  --type sharepoint \
  --org 0c8f2b1e-... \
  --collection hr \
  --secret-id <vault-secret-id> \
  --config '{"site_url": "https://contoso.sharepoint.com/sites/HR", "folder_path": "Policies"}' \
  --sync-mode new_only \
  --schedule 360

--secret-id to aplikacja Microsoft Entra w vault organizacji — zobacz Konfiguracja SharePoint i OneDrive.

Wyzwól synchronizację ręcznie¶

# Sync a single source by ID
uv run agenticos cmd rag-source-sync <source-id>

# Sync all active sources
uv run agenticos cmd rag-source-sync --all

Usuń źródło¶

uv run agenticos cmd rag-source-remove <source-id>

<source-id> to UUID wypisywany przy tworzeniu źródła i pokazywany na liście rag-sources.

Szybki start -- interfejs¶

Przejdź do Knowledge Base i otwórz zakładkę Sync.
Kliknij "+ Add Source".
Wybierz typ connectora (Google Drive, S3, Website, Git repository, SharePoint & OneDrive). Pola formularza są generowane ze schematu JSON Schema z CONFIG_MODEL connectora. Strona internetowa nie ma kroku poświadczenia.
Wypełnij pola konfiguracji właściwe dla connectora (na przykład folder ID, nazwę bucketa).
Wybierz kolekcję docelową, tryb synchronizacji i interwał harmonogramu.
Kliknij "Create Source".
Przyciskiem "Sync Now" wyzwolisz synchronizację natychmiast albo poczekasz, aż harmonogram zadziała sam.

Żeby później zmienić source, kliknij ołówek w jego wierszu. Otworzy się ten sam kreator z wypełnionymi wartościami source'a. Connectora nie da się zmienić, a "Save Changes" wysyła tylko pola, które zmieniłeś. Source zostaje w bazie wiedzy, w której jest.

Interfejs wywołuje to samo REST API, które opisano poniżej: cokolwiek zrobisz w interfejsie, zrobisz też przez curl lub dowolnego klienta HTTP.

Tryby synchronizacji¶

Tryb	Zachowanie
`full`	Synchronizuje wszystko od nowa. Wszystkie pliki są (ponownie) przetwarzane, istniejące dokumenty zastępowane.
`new_only`	Dodaje nowe pliki i aktualizuje zmienione. Zmiany wykrywa po skrócie SHA-256 — pliki bez zmian są pomijane.
`update_only`	Aktualizuje wyłącznie pliki już obecne w kolekcji. Nowe pliki są pomijane. Skrót SHA-256 pomija pliki bez zmian.

new_only do większości zastosowań

Dodaje nowe pliki i aktualizuje zmienione, pomijając te bez zmian — to najszybsza synchronizacja przyrostowa. update_only odświeża istniejące dokumenty, nie dodając nowych; full to za każdym razem czysty import od nowa.

Co usuwa synchronizacja¶

W każdym trybie synchronizacja usuwa dokumenty, które jej źródło wprowadziło wcześniej, a których już nie wypisuje: stronę zdjętą z witryny, plik skasowany z folderu na Drive, obiekt usunięty z bucketa. Log synchronizacji liczy je w polu removed.

Nie usuwa niczego, jeśli lista nie była kompletna. Crawl, który zatrzymał się na limicie stron albo nie zdołał odczytać jednej z nich, nie widział tego, czego nie wypisuje. Taki przebieg zachowuje wszystkie dokumenty i mówi o tym w komunikacie logu synchronizacji. Następna synchronizacja z kompletną listą usuwa to, czego już nie ma. Dokument, którego nie udało się usunąć, liczy się jako nieudany plik, a następna synchronizacja próbuje ponownie.

Jedno źródło ma naraz tylko jedną synchronizację. Synchronizacja uruchomiona, gdy inna synchronizacja tego samego źródła wciąż trwa, nie startuje, a jej log mówi o tym.

Usuwane są wyłącznie dokumenty samego źródła. Przesłany plik ani dokument, który do tej samej kolekcji wprowadziło inne źródło, nigdy nie są ruszane. Gdy dwa źródła jednej kolekcji wymieniają ten sam dokument, zostaje on, dopóki oba nie przestaną go wymieniać. Dokument przetworzony, zanim źródło zaczęło to odnotowywać (wrzesień 2026), zostaje zachowany, dopóki synchronizacja źródła znowu go nie wymieni.

Co robi druga synchronizacja¶

Każda synchronizacja po pierwszej robi tak mało, jak pozwala na to źródło:

Niezmieniony plik kosztuje pobranie, nie embedowanie. Jego SHA-256 zgadza się ze skrótem zapisanego dokumentu, więc jest liczony jako skipped i nigdy nie jest ponownie parsowany ani embedowany.
Niezmienione źródło kosztuje jedno zapytanie. Connector, który potrafi powiedzieć, w jakim stanie jest cała jego zawartość — w przypadku gałęzi Git jest to jej commit na czubku (head), a w przypadku biblioteki SharePoint jej strumień zmian — zapisuje tę wartość po każdym przebiegu, który zakończył się bez żadnego błędu. Następny przebieg new_only albo update_only, który zastanie tę samą wartość przy tej samej konfiguracji, zatrzymuje się, zanim cokolwiek wypisze: jego log nie pokazuje żadnych przetworzonych plików, a przebieg niczego nie usuwa. Zmiana konfiguracji, kolekcji albo trybu sprawia, że następny przebieg czyta wszystko od nowa, a full nigdy nie kończy się wcześniej.
Plik, który przerwana synchronizacja zostawiła w połowie, zostaje naprawiony. Worker zatrzymany po zapisaniu wektorów pliku, a przed ich odnotowaniem, zostawia je bez śledzącego wiersza. Następna synchronizacja tego źródła usuwa to, czego nic nie śledzi, i ponownie przetwarza plik; dopóki taki plik czeka, nie kończy się wcześniej.

Przebieg z plikiem, którego nie udało się przetworzyć, nie zapisuje stanu, więc następny przebieg czyta źródło w całości i ponawia próbę.

Harmonogram¶

Pole schedule_minutes decyduje, jak często źródło synchronizuje się samoczynnie:

Wartość	Znaczenie
`0` (lub `null`)	Tylko ręcznie -- wyzwalane z CLI lub interfejsu
`30`	Co 30 minut
`120`	Co 2 godziny
`1440`	Raz dziennie

Harmonogram wymaga workera

Harmonogram dispatch-due-syncs budzi się co 60 sekund i kolejkuje synchronizację każdego źródła, którego termin nadszedł, więc bez kontenera worker, który startuje make dev, schedule_minutes nie robi nic. Bez niego ręczne wyzwolenie (CLI, API lub interfejs) też kolejkuje swoją synchronizację, która również czeka na workera. Jedno źródło nigdy nie ma dwóch synchronizacji naraz.

Konfiguracja Google Drive¶

1. Utwórz konto usługi¶

Wejdź do Google Cloud Console.
Utwórz nowy projekt (albo wybierz istniejący).
Włącz Google Drive API.
Przejdź do IAM & Admin > Service Accounts i utwórz nowe konto usługi.
Utwórz dla niego klucz JSON i pobierz go.

Otwórz Google Drive i przejdź do folderu, który chcesz synchronizować.
Kliknij Share i dodaj adres e-mail konta usługi (wygląda tak: name@project.iam.gserviceaccount.com).
Przyznaj co najmniej dostęp Viewer.

3. Przekaż źródłu klucz¶

Wklej zawartość pliku z kluczem JSON w pole Service Account JSON źródła. Źródło gdrive działa na poświadczeniu, które niesie jego własna konfiguracja, i na niczym innym — nie ma zapasowego poświadczenia obowiązującego dla całego deploymentu, bo pozwoliłoby ono, żeby folder_id źródła decydowało o tym, co zostanie wypisane spod konta usługi operatora.

GOOGLE_DRIVE_CREDENTIALS_FILE w .env służy wyłącznie komendzie CLI rag-sync-gdrive.

4. Odczytaj folder ID¶

Folder ID to ostatni segment adresu URL folderu Google Drive:

https://drive.google.com/drive/folders/1abc123def456ghi
                                        ^^^^^^^^^^^^^^^
                                        This is the folder ID

5. Pola konfiguracji connectora Google Drive¶

Pole	Typ	Wymagane	Domyślnie	Opis
`folder_id`	string	Tak	--	Folder ID Google Drive z adresu URL
`include_subfolders`	boolean	Nie	`true`	Rekurencyjnie obejmuje pliki z podfolderów

Samo konto usługi nie jest polem konfiguracji. Dodaj je do vault jako poświadczenie rodzaju gcp_service_account i wskaż je źródłu przez secret_id: zostaje zapisane raz i jest przywoływane przez każde źródło, które go potrzebuje, zamiast być wklejane do każdego z osobna (#937). Przesłanie go pod config jest odrzucane.

folder_id może zawierać wyłącznie to, co wydaje Google — litery, cyfry, - i _. Cokolwiek innego jest odrzucane przy tworzeniu źródła, bo id trafia przez interpolację do zapytania Drive, a pojedynczy apostrof w nim poszerza to, co zapytanie wypisuje.

Google Docs, Sheets i Slides są przy pobieraniu samoczynnie eksportowane do formatów przenośnych (PDF, XLSX, PPTX). Plik, którego nazwa na Drive zawiera separatory ścieżki, zapisywany jest jako jeden plik wewnątrz katalogu synchronizacji, nigdy pod ścieżką, którą literuje jego nazwa.

Konfiguracja S3 / MinIO¶

1. Skonfiguruj środowisko¶

Dodaj do swojego pliku .env następujące zmienne:

S3_RAG_ENDPOINT=https://s3.amazonaws.com   # or your MinIO URL, e.g. http://localhost:9000
S3_RAG_ACCESS_KEY=your-access-key
S3_RAG_SECRET_KEY=your-secret-key
S3_RAG_REGION=us-east-1                    # required for AWS, optional for MinIO

W MinIO endpoint ma zwykle postać http://minio:9000 (Docker) albo http://localhost:9000 (lokalnie).

2. Pola konfiguracji connectora S3¶

Pole	Typ	Wymagane	Domyślnie	Opis
`bucket`	string	Tak	--	Nazwa bucketa S3
`prefix`	string	Nie	`""`	Prefiks kluczy zawężający zakres synchronizacji (np. `documents/legal/`). Zostaw pusty, aby objąć cały bucket.

Konfiguracja strony internetowej¶

Źródło web czyta publiczną stronę internetową, zwykle witrynę z dokumentacją produktu. Nie potrzebuje poświadczenia ani wpisu w vault. Podaj mu początkowy adres URL, a będzie albo podążać za linkami z tej strony, albo czytać strony wypisane w sitemapie.

uv run agenticos cmd rag-source-add \
  --name "Product docs" \
  --type web \
  --org 0c8f2b1e-... \
  --collection product-docs \
  --config '{"root_url": "https://docs.example.com/guide/", "max_depth": 3}' \
  --sync-mode new_only \
  --schedule 1440

Pola konfiguracji connectora strony internetowej¶

Pole	Typ	Wymagane	Domyślnie	Opis
`root_url`	string	Tak	--	Strona, od której zaczyna się crawl. Jej host jest jedynym hostem, który źródło czyta.
`max_depth`	integer	Nie	`2`	Na ile linków od początkowego adresu URL podążać, od `0` do `10`. `0` czyta tylko stronę początkową.
`path_prefix`	string	Nie	folder początkowego adresu URL	Czytane są tylko strony, których ścieżka zaczyna się od tej wartości. `https://docs.example.com/guide/intro` domyślnie czyta `/guide/`; ustaw `/`, aby objąć cały host.
`sitemap_url`	string	Nie	--	Czyta strony wypisane w tej sitemapie zamiast podążać za linkami. Musi leżeć na hoście początkowego adresu URL i używać `https://`, gdy używa go początkowy adres URL. Indeks sitemap jest rozwijany do jego sitemap.
`max_pages`	integer	Nie	`500`	Crawl zatrzymuje się po odczytaniu tylu stron, od `1` do `5000`.

Co ogranicza crawl¶

Jeden host i jedna ścieżka. Linki do innych hostów i do ścieżek spoza path_prefix nie są śledzone. Przekierowanie, które je opuszcza, także nie. Początkowy adres URL na https:// nigdy nie jest opuszczany na rzecz http://: link ani przekierowanie do strony bez szyfrowania nie są śledzone.
Sieć deploymentu jest poza zasięgiem. Każde żądanie - robots.txt, sitemapa, każda strona i każde przekierowanie - jest sprawdzane według tej samej polityki SSRF co webhooki i serwery MCP. Wysyłane jest na adres, który przeszedł sprawdzenie. Początkowy adres URL, który rozwiązuje się na adres prywatny, loopback, link-local albo metadanych chmury, jest odrzucany przy zapisie źródła.
robots.txt jest przestrzegany dla sitemap i stron, łącznie z Crawl-delay do dziesięciu sekund. Crawler przedstawia się jako AgenticOS-Crawler. Między żądaniami czeka co najmniej pół sekundy, a strona oznaczona noindex lub nofollow jest respektowana. Strona, którą sitemapa wciąż wypisuje, choć jest oznaczona noindex albo już nie istnieje, jest usuwana z kolekcji.
Rozmiar i czas. Strona większa niż 5 MB nie jest czytana. Crawl zatrzymuje się na max_pages. Synchronizacja przestaje czytać witrynę po sześciu godzinach, a synchronizacja, która się zatrzymała, niczego nie usuwa.

Każda strona jest zapisywana jako dokument Markdown zawierający jej tekst i adres URL, z którego pochodzi, bez query stringa. Nawigacja, nagłówki, stopki i skrypty są pomijane. Strona jest embedowana ponownie tylko wtedy, gdy zmieni się jej tekst. Nowy znacznik builda albo skrypt śledzący w znacznikach HTML nie liczy się jako zmiana.

Kto może czytać to, co importuje¶

Źródło strony internetowej nie ma poświadczenia, więc jego zasięg to wszystko, co strona pokazuje każdemu w internecie. Nigdy nie przechodzi przez logowanie. Wszystko, co importuje, może przeszukiwać każdy, kto może przeszukiwać zasilaną przez nie kolekcję, tak jak w przypadku każdego innego źródła. Zobacz kto ostatecznie może czytać to, co źródło przetworzyło.

Importowane są wyłącznie strony HTML. PDF ani inny plik podlinkowany ze strony nie jest pobierany.

Konfiguracja repozytorium Git¶

Źródło git czyta dokumentację repozytorium przez HTTPS — z GitHuba, GitLaba albo dowolnego innego hosta, który serwuje git przez HTTPS. Potrzebuje adresu URL do klonowania i tokena dostępu, a nie API którejkolwiek z tych platform.

1. Wystaw token dla jednego repozytorium¶

Zasięg tokena to zasięg źródła. Wszystko, co źródło przetworzy, staje się możliwe do przeszukania przez każdego, kto może czytać kolekcję, więc token, który może czytać każde prywatne repozytorium swojego właściciela, to token, który może je wszystkie opublikować tym odbiorcom. Zobacz kto ostatecznie może czytać to, co przetworzyło źródło.

GitHub: fine-grained personal access token, Only select repositories, z tym jednym repozytorium i Contents: Read-only jako jedynym uprawnieniem.
GitLab: project access token w tym jednym projekcie, rola Reporter, wyłącznie zakres read_repository.

Nadaj mu datę wygaśnięcia. Gdy wygaśnie, następna synchronizacja źródła kończy się błędem the repository refused the source's token, a naprawą jest nowy token w tym samym sekrecie w vault.

2. Dodaj go do vault¶

Dodaj token do vault jako Git access token, razem z hostem, do którego należy: github.com, gitlab.com albo własny serwer, na przykład git.example.com:8443. Host z literami spoza ASCII wpisuje się w postaci zakodowanej, na przykład xn--bcher-kva.example dla bücher.example. Potem wybierz token w kroku poświadczenia źródła. Jest wysyłany jako nagłówek HTTP Authorization, nigdy w adresie URL i nigdy w wierszu poleceń, który mógłby odczytać inny proces.

Host należy do tokena, nie do źródła. Adres URL repozytorium wybiera ten, kto edytuje źródło, a token jest wysyłany wyłącznie do hosta, z którym został dodany. Edycja źródła nie może więc skierować tokena organizacji na inny serwer, a żadnego innego rodzaju klucza, na przykład klucza API dostawcy modelu, nie da się w ogóle wybrać dla źródła Git.

3. Pola konfiguracji connectora Git¶

Pole	Typ	Wymagane	Domyślnie	Opis
`repository_url`	string	Tak	--	Adres URL klonowania przez HTTPS, np. `https://github.com/acme/handbook.git`. Bez nazwy użytkownika i tokena.
`branch`	string	Nie	`main`	Gałąź do odczytu.
`path_prefix`	string	Nie	--	Katalog wewnątrz repozytorium, np. `docs`. Zostaw pusty, aby objąć całe repozytorium.
`include`	lista stringów	Nie	`*/.md`, `*/.txt`	Które pliki przetwarzać, jako wzorce w stylu `.gitignore` względem `path_prefix`.

Domyślnie jest to dokumentacja, a nie całe drzewo: kod źródłowy repozytorium nie jest korpusem, a jego przetworzenie wypełnia bazę wiedzy kodem, którego nikt nie chciał przeszukiwać. Dodaj wzorzec taki jak **/*.pdf dla innego formatu, który czyta parser kolekcji. Wzorzec nie może zaczynać się od !.

Każdy plik jest dokumentem o adresie git://<host>/<owner>/<repo>@<branch>/<path>, z :<port> po hoście, gdy port nie jest 443. Gałąź jest częścią adresu, więc dwa źródła czytające dwie gałęzie jednego repozytorium do jednej kolekcji mają osobne dokumenty.

4. Co przesyła synchronizacja¶

Pierwszym zapytaniem każdej synchronizacji jest git ls-remote dla gałęzi — około kilobajta. Gdy commit na czubku gałęzi nie przesunął się od ostatniego czystego przebiegu, synchronizacja na tym się kończy. Gdy się przesunął, connector wykonuje płytki, częściowy i rzadki (sparse) klon: jeden commit i wyłącznie pliki pasujące do wzorców include. Dokumentacja monorepo kosztuje więc tyle, co dokumentacja, a nie całe drzewo źródeł.

Zanim klon zapisze cokolwiek na dysk workera, connector mierzy każdy plik, który by zapisał. Plik większy niż limit dokumentu bazy wiedzy (MAX_UPLOAD_SIZE_MB, domyślnie 50 MB) albo łącznie ponad 512 MB plików zostaje odrzucony i nic nie jest zapisywane.

Dowiązania symboliczne i submoduły nie są śledzone, a dowiązanie nie jest przetwarzane jako dokument.

Reguły sieciowe¶

Adres URL musi zaczynać się od https://. Jego host jest rozwiązywany raz i sprawdzany tak jak każdy inny adres wybrany przez tenanta: host, który rozwiązuje się na adres prywatny, loopback albo link-local, jest odrzucany przy zapisie źródła i ponownie przy synchronizacji, a git łączy się wyłącznie z adresami, które ta kontrola zatwierdziła. Przekierowania nie są śledzone. Deployment za proxy wyjściowym (HTTPS_PROXY) nadal z niego korzysta; proxy rozwiązuje wtedy host samo.

Obraz workera zawiera git. Worker zbudowany z innego obrazu potrzebuje git w wersji 2.37 lub nowszej na swoim PATH.

Konfiguracja SharePoint i OneDrive¶

Źródło sharepoint czyta jedną bibliotekę dokumentów przez Microsoft Graph: bibliotekę witryny SharePoint albo OneDrive konkretnej osoby, który Microsoft 365 przechowuje jako osobną witrynę. Może czytać całą bibliotekę albo jeden folder w niej. Loguje się jako rejestracja aplikacji Microsoft Entra, którą administrator Twojego tenanta tworzy jednorazowo.

1. Zarejestruj aplikację w Microsoft Entra¶

W Microsoft Entra admin center otwórz App registrations → New registration. Nadaj jej nazwę, na przykład AgenticOS sync, zostaw Accounts in this organizational directory only i nie wypełniaj redirect URI. Źródło loguje się jako sama aplikacja, a nie jako osoba.

Na stronie Overview aplikacji zanotuj Application (client) ID oraz Directory (tenant) ID. W Certificates & secrets dodaj client secret i skopiuj jego Value. Wartość jest pokazywana tylko raz. ID sekretu to nie jest to, czego potrzebuje źródło.

2. Przyznaj jej jedną witrynę, nie cały tenant¶

Zasięg aplikacji to zasięg źródła. Wszystko, co źródło przetworzy, staje się możliwe do przeszukania przez każdego, kto może czytać zasilaną przez nie kolekcję. Zobacz kto ostatecznie może czytać to, co przetworzyło źródło.

W API permissions dodaj uprawnienie Microsoft Graph typu application Sites.Selected i udziel dla niego zgody administratora (admin consent). Samo Sites.Selected nie pozwala niczego odczytać. Administrator przyznaje następnie aplikacji dostęp do odczytu tej jednej witryny, którą czyta źródło:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [
    {"application": {"id": "<client-id>", "displayName": "AgenticOS sync"}}
  ]
}

To wywołanie wymaga Sites.FullControl.All, więc administrator wykonuje je z Graph Explorer albo poleceniem PnP PowerShell Grant-PnPAzureADAppSitePermission, a nie samą aplikacją. GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/HR?$select=id zwraca id witryny. OneDrive przyznaje się tak samo, przez jego witrynę: contoso-my.sharepoint.com:/personal/jane_contoso_com.

Files.Read.All albo Sites.Read.All otwiera do odczytu każdą bibliotekę w tenancie

Na te uprawnienia zgoda jest udzielana dla całego tenanta. Źródło, które je ma, nadal czyta wyłącznie bibliotekę, którą wskazuje. Ale ten, kto może edytować źródło, może skierować jego adres URL witryny na dowolną witrynę albo dowolny OneDrive w organizacji, a następna synchronizacja udostępni tę bibliotekę do przeszukiwania każdemu, kto może czytać kolekcję. Nic w tym produkcie nie potrafi rozpoznać, jakie uprawnienie dostała aplikacja, bo token tego nie mówi. Używaj Sites.Selected i przyznawaj jedną aplikację na jedną grupę odbiorców.

3. Dodaj ją do vault¶

Dodaj aplikację do vault jako Microsoft Entra app: tenant id (albo domenę tenanta, na przykład contoso.onmicrosoft.com), client id oraz wartość client secretu. Potem wybierz ją w kroku poświadczenia źródła. Sekret jest wysyłany wyłącznie do login.microsoftonline.com, w celu zalogowania.

Client secret wygasa, najpóźniej po dwóch latach. Gdy wygaśnie, następna synchronizacja kończy się błędem Microsoft Entra refused the app registration's credentials (invalid_client). Dodaj aplikacji nowy sekret i podmień wartość w tym samym sekrecie w vault. Każde źródło, które z niego korzysta, pobierze nową wartość przy następnej synchronizacji.

4. Pola konfiguracji connectora SharePoint¶

Pole	Typ	Wymagane	Domyślnie	Opis
`site_url`	string	Tak	--	Witryna, np. `https://contoso.sharepoint.com/sites/HR`, albo OneDrive, np. `https://contoso-my.sharepoint.com/personal/jane_contoso_com`. Wyłącznie witryna: adres URL biblioteki lub strony skopiowany z przeglądarki jest odrzucany.
`library`	string	Nie	domyślna biblioteka witryny	Nazwa biblioteki tak, jak pokazuje ją SharePoint, np. `Documents`. OneDrive ma wyłącznie swoją bibliotekę domyślną.
`folder_path`	string	Nie	--	Folder wewnątrz biblioteki, np. `Policies/HR`. Zostaw pusty, aby objąć całą bibliotekę.
`include_subfolders`	boolean	Nie	`true`	Czy czytać foldery poniżej `folder_path`.
`extensions`	lista stringów	Nie	`.pdf`, `.docx`, `.md`, `.txt`	Które typy plików przetwarzać. Dodaj `.pptx`, `.xlsx` albo inny typ tylko wtedy, gdy czyta go parser kolekcji: plik, którego parser nie potrafi odczytać, liczy się jako nieudany plik przy każdej synchronizacji.

Każdy plik jest dokumentem o adresie sharepoint://<drive-id>/<item-id>. Adres podąża za plikiem, a nie za jego ścieżką, więc plik, którego nazwę zmieniono albo który przeniesiono wewnątrz biblioteki, zachowuje swój dokument. Dokument zachowuje nazwę pliku z chwili przetworzenia, dopóki nie zmieni się zawartość pliku.

Notesy OneNote i pliki innych typów nie są przetwarzane.

5. Co przesyła synchronizacja¶

Każda synchronizacja zaczyna się od strumienia zmian Microsoft Graph dla biblioteki. Gdy od ostatniego czystego przebiegu nic w bibliotece się nie zmieniło, synchronizacja na tym się kończy: jedno zapytanie i żadnego wypisywania. Strumień obejmuje całą bibliotekę, bo Graph udostępnia go wyłącznie dla korzenia biblioteki. Zmiana w innym folderze tej samej biblioteki sprawia więc, że następna synchronizacja ponownie wypisuje folder źródła.

Gdy coś się zmieniło, synchronizacja wypisuje folder i pobiera każdy plik skonfigurowanych typów. Plik, którego zawartość się nie zmieniła, jest następnie pomijany przed embedowaniem, więc embedowanie kosztują wyłącznie pliki nowe i zmienione. Plik jest pobierany z adresu, który podaje dla niego Graph, bez tokena aplikacji. Plik większy niż limit dokumentu bazy wiedzy (MAX_UPLOAD_SIZE_MB, domyślnie 50 MB) nie jest pobierany i liczy się jako nieudany plik.

Graph spowalnia klienta, który czyta szybko. Zapytanie, które Graph dławi (HTTP 429) albo które kończy się błędem 5xx lub błędem sieci, jest próbowane łącznie cztery razy, a synchronizacja czeka tak długo, jak prosi Retry-After z Graph, najwyżej minutę. Folder, którego nadal nie da się wypisać, jest wymieniany w logu synchronizacji, a ta synchronizacja niczego nie usuwa, bo pliki w tym folderze nie zostały zobaczone. Pliki z pozostałych folderów są nadal przetwarzane.

Plik usunięty po wypisaniu, a przed pobraniem, jest usuwany tak jak plik, którego lista nie wymieniła.

Sieć¶

Worker potrzebuje wyjściowego HTTPS do login.microsoftonline.com, graph.microsoft.com oraz hostów *.sharepoint.com Twojego tenanta. Nic, co wpisze osoba edytująca źródło, nie staje się adresem, z którym łączy się worker: adres URL witryny to tylko nazwa, którą wyszukuje Graph. Chmury krajowe Microsoftu, takie jak US Government i Chiny, używają innych hostów i nie są obsługiwane.

Dokumentacja API¶

Wszystkie endpointy źródeł synchronizacji leżą pod /api/v1/rag/sync/. Wypisanie listy wymaga collections:view, a wszystko, co zmienia źródło, wymaga collections:edit — w obu przypadkach wobec kolekcji, do której źródło należy; rola administratora w tym nie występuje. Zobacz kto może sięgnąć do kolekcji.

CRUD źródeł synchronizacji¶

Metoda	Endpoint	Opis
`GET`	`/api/v1/rag/sync/sources`	Wypisuje wszystkie skonfigurowane źródła synchronizacji
`POST`	`/api/v1/rag/sync/sources`	Tworzy nowe źródło synchronizacji
`PATCH`	`/api/v1/rag/sync/sources/{id}`	Zmienia istniejące źródło synchronizacji
`DELETE`	`/api/v1/rag/sync/sources/{id}`	Usuwa źródło synchronizacji
`POST`	`/api/v1/rag/sync/sources/{id}/trigger`	Ręcznie wyzwala synchronizację

Connectory i logi¶

Metoda	Endpoint	Opis
`GET`	`/api/v1/rag/sync/connectors`	Wypisuje dostępne typy connectorów wraz ze schematami konfiguracji
`GET`	`/api/v1/rag/sync/logs`	Wypisuje historię synchronizacji (filtrowaną po `collection_name`)

Przykład: utworzenie źródła przez API¶

curl -X POST http://localhost:8000/api/v1/rag/sync/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal Drive",
    "connector_type": "gdrive",
    "collection_name": "legal",
    "config": {
      "folder_id": "1abc123def",
      "include_subfolders": true
    },
    "sync_mode": "new_only",
    "schedule_minutes": 120
  }'

Przykład: wyzwolenie synchronizacji przez API¶

curl -X POST http://localhost:8000/api/v1/rag/sync/sources/{source_id}/trigger \
  -H "Authorization: Bearer $TOKEN"

Przykład: sprawdzenie historii synchronizacji¶

curl http://localhost:8000/api/v1/rag/sync/logs?limit=10 \
  -H "Authorization: Bearer $TOKEN"

Przykład: wykrycie dostępnych connectorów¶

curl http://localhost:8000/api/v1/rag/sync/connectors \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź zawiera config_schema każdego connectora, na podstawie którego frontend renderuje dynamiczne formularze. Przydaje się też przy programowym budowaniu integracji.

Zmiana źródła¶

Metodą PATCH możesz zmienić dowolny podzbiór pól istniejącego źródła:

curl -X PATCH http://localhost:8000/api/v1/rag/sync/sources/{source_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_mode": "full",
    "schedule_minutes": 60,
    "is_active": false
  }'

Pola, które można zmienić: name, config, sync_mode, schedule_minutes, is_active, collection_name.

Ustaw is_active na false, aby wstrzymać źródło bez usuwania go.

Monitorowanie operacji synchronizacji¶

Każda synchronizacja tworzy wpis SyncLog z następującymi polami:

Pole	Opis
`source`	Typ connectora albo `"local"` dla przetwarzania z CLI
`collection_name`	Kolekcja docelowa
`status`	`running`, `done` albo `error`
`mode`	`full`, `new_only` albo `update_only`
`total_files`	Liczba znalezionych plików
`ingested`	Poprawnie przetworzone (nowe)
`updated`	Poprawnie przetworzone ponownie (zastąpione)
`skipped`	Pominięte (już obecne lub bez zmian)
`failed`	Nieudane przetworzenie, łącznie ze stronami lub plikami, których lista nie zdołała odczytać, oraz dokumentami, których nie udało się usunąć
`removed`	Usunięte, bo źródło już ich nie wypisuje (zobacz co usuwa synchronizacja)
`error_message`	Co poszło nie tak albo dlaczego nic nie usunięto. Przebieg może mieć status `done` i mimo to komunikat, na przykład gdy crawl zatrzymał się na limicie stron
`started_at`	Kiedy synchronizacja się zaczęła
`completed_at`	Kiedy synchronizacja się skończyła

Logi obejrzysz w wyjściu CLI albo przez API:

curl http://localhost:8000/api/v1/rag/sync/logs?collection_name=legal&limit=5 \
  -H "Authorization: Bearer $TOKEN"

Dodawanie własnych connectorów¶

Aby dodać nowy typ connectora (na przykład Notion, Confluence, Dropbox), zobacz Dodaj connector synchronizacji.

W skrócie:

Utwórz klasę dziedziczącą po BaseSyncConnector w app/services/rag/connectors/.
Zaimplementuj list_files(), _fetch() i opcjonalnie validate_config().
Zadeklaruj SECRET_KIND — rodzaj sekretu w vault, który go uwierzytelnia — oraz CONFIG_MODEL, model Pydantic mówiący, jak odnaleźć dokumenty. Poświadczenie nigdy nie jest jednym z jego pól.
Zarejestruj go w CONNECTOR_REGISTRY w app/services/rag/connectors/__init__.py.

Po zarejestrowaniu connector pojawia się samoczynnie w CLI, API i w interfejsie.

Rozwiązywanie problemów¶

"No sync sources configured"¶

Nie utworzono jeszcze żadnego źródła. Utwórz je poleceniem rag-source-add (CLI) albo POST /api/v1/rag/sync/sources (API).

"Unknown connector type"¶

Podany typ connectora nie występuje w CONNECTOR_REGISTRY. Sprawdź dostępne typy poleceniem rag-sources albo GET /api/v1/rag/sync/connectors. Google Drive (gdrive) jest dostępny. S3 (s3) jest dostępny. Strona internetowa (web) jest dostępna. Git (git) jest dostępny.

Google Drive: "this source has no credential"¶

Pole secret_id źródła jest puste albo sekret w vault, który wskazywało, został usunięty. Dodaj JSON konta usługi do vault i wybierz go w kroku poświadczenia źródła — GOOGLE_DRIVE_CREDENTIALS_FILE go nie zastępuje, a to ustawienie czyta wyłącznie komenda CLI rag-sync-gdrive.

"A Google Drive source needs a service account credential"¶

secret_id wskazuje poświadczenie niewłaściwego rodzaju — na przykład parę kluczy AWS. Źródło Drive przyjmuje gcp_service_account, a źródło S3 parę aws_credentials; kreator proponuje wyłącznie pasujące, więc ten przypadek osiągalny jest przez API.

Google Drive: "folder ID may contain only letters, digits, '-' and '_'"¶

Wartość nie jest identyfikatorem folderu Drive. Weź ją z adresu URL folderu: to ostatni segment, a nic innego z tego adresu do tego pola nie należy.

Google Drive: "Cannot access folder"¶

Upewnij się, że udostępniono folder adresowi e-mail konta usługi. Konto usługi potrzebuje co najmniej dostępu Viewer.

S3: "Cannot access bucket"¶

Sprawdź, czy S3_RAG_ACCESS_KEY, S3_RAG_SECRET_KEY i S3_RAG_ENDPOINT są poprawnie ustawione w .env. W MinIO upewnij się, że endpoint zawiera port (na przykład http://localhost:9000).

Website: "resolves to private/internal address"¶

Początkowy adres URL albo sitemapa wskazuje do wnętrza sieci deploymentu albo jego nazwa się tam rozwiązuje. Źródło strony internetowej czyta wyłącznie adresy publiczne. Aby zaindeksować wewnętrzną witrynę, opublikuj jej strony gdzieś publicznie albo prześlij pliki bezpośrednio.

Website: "The site's robots.txt could not be read, so it was not crawled"¶

/robots.txt na hoście początkowego adresu URL trzy razy z rzędu przekroczył limit czasu albo odpowiedział błędem serwera (5xx). Crawler nie zgaduje, na co pozwoliłby nieosiągalny robots.txt, więc przebieg się zatrzymuje. Brakujący robots.txt (404) albo zabroniony (403) oznacza brak reguł i crawl rusza.

Website: "The start URL … did not lead to an HTML page"¶

Początkowy adres URL odpowiedział 404, przekierował na inny host albo poza path_prefix, albo zwrócił coś innego niż HTML. Otwórz go w przeglądarce, a potem użyj adresu, pod którym się kończy, jako root_url.

Website: "robots.txt does not allow the start URL"¶

Witryna prosi crawlery, by trzymały się z dala od tej ścieżki. Wybierz początkowy adres URL, na który witryna pozwala, albo poproś jej właściciela o dopuszczenie AgenticOS-Crawler.

Website: "… answered HTTP 403" or "… could not be reached"¶

Strona wymaga logowania albo witryna odmówiła crawlerowi. Jeśli odpowiedzią był przekroczony limit czasu, 429 albo 5xx, strona zawiodła po trzech próbach. Każda taka strona liczy się jako nieudany plik. W tym przebiegu nic nie jest usuwane, bo strony za nią nie zostały zobaczone.

"The source could not be listed completely, so documents it may no longer hold were kept"¶

Lista urwała się przed końcem: crawl osiągnął max_pages, części stron nie udało się odczytać albo nie udało się wypisać folderu SharePoint. To, co znaleziono, zostało przetworzone, a nic nie usunięto. W przypadku strony internetowej zwiększ max_pages albo zawęź crawl przez path_prefix, aż przebieg skończy się bez tego komunikatu. W przypadku SharePoint zobacz wpis dotyczący tego folderu poniżej.

Git: "The repository refused the source's token"¶

Token wygasł, został unieważniony albo nie może czytać tego repozytorium. Wystaw nowy zgodnie z opisem w Konfiguracja repozytorium Git i podmień wartość sekretu w vault, którego używa źródło; każde źródło korzystające z tego sekretu pobierze ją przy następnej synchronizacji.

Git: "The repository was not found, or the source's token cannot see it"¶

Najpierw sprawdź adres URL klonowania. Prywatne repozytorium odpowiada tokenowi, który nie może go czytać, not found zamiast forbidden, więc fine-grained token wystawiony dla innego repozytorium wygląda właśnie tak.

Git: "The repository has no branch named …"¶

Pole branch wskazuje gałąź, której repozytorium nie ma. Domyślnie jest to main; w starszym repozytorium gałęzią domyślną może być master.

Git: "… is … MB, and a synced file may be at most … MB"¶

Plik pasujący do wzorców include jest większy niż limit dokumentu bazy wiedzy. Zawęź include albo path_prefix tak, by ten plik został pominięty. W tej synchronizacji nic nie zostało zapisane.

Git: "… over the … MB one sync may check out"¶

Wszystkie pliki pasujące do wzorców include mają łącznie ponad 512 MB. Zawęź include albo path_prefix albo podziel repozytorium na kilka źródeł, każde z własnym prefiksem.

Git: "This token was added for …, and the repository is on …"¶

Repozytorium źródła jest na innym hoście niż ten, z którym dodano jego token. Albo adres URL jest błędny, albo źródło potrzebuje tokena dodanego dla tego hosta. Do hosta repozytorium nic nie zostało wysłane.

Git: "A Git source needs a Git access token"¶

Źródło wskazuje sekret innego rodzaju, na przykład API key. Dodaj token jako Git access token, razem z jego hostem, i wybierz właśnie ten.

"Another sync of this source is still running"¶

Przebieg został wyzwolony, gdy trwał inny przebieg tego samego źródła, więc nie wystartował. Trwający przebieg kończy się normalnie; wyzwól synchronizację ponownie po nim, jeśli źródło w międzyczasie się zmieniło.

Git: "… resolves to a private address"¶

Host repozytorium rozwiązuje się na adres wewnątrz sieci deploymentu, więc źródło jest odrzucane. Źródło synchronizacji nie może dotrzeć do samodzielnie hostowanego serwera Git pod adresem wewnętrznym.

Git: "git is not installed on this worker"¶

Worker działa z obrazu bez git. Dostarczany backend/Dockerfile go instaluje; do własnego obrazu trzeba go dodać.

Git: synchronizacja zakończyła się bez przetworzonych plików¶

Commit na czubku gałęzi jest tym samym, który przeczytał ostatni czysty przebieg, przy tej samej konfiguracji, więc nie było nic do zrobienia. Przełącz źródło na full na jeden przebieg, aby mimo to przeczytać wszystko od nowa.

SharePoint: "Microsoft Entra refused the app registration's credentials (…)"¶

Microsoft Entra nie zalogował aplikacji. invalid_client zwykle oznacza, że client secret wygasł albo vault przechowuje ID sekretu zamiast jego wartości. unauthorized_client albo invalid_request zwykle oznacza błędny tenant id albo client id. Porównaj te trzy wartości z Overview i Certificates & secrets aplikacji i podmień je w sekrecie w vault.

SharePoint: "Microsoft Graph did not accept the app's token for …"¶

Aplikacja się zalogowała, ale jej token nie niesie żadnego uprawnienia Microsoft Graph. Dodaj uprawnienie typu application Sites.Selected, a nie delegowane, i udziel zgody administratora, zgodnie z opisem w kroku 2.

SharePoint: "Microsoft Graph denied the app access to … (accessDenied)"¶

Aplikacja ma Sites.Selected, ale żadnego przyznania na tej witrynie. Przyznaj jej read na witrynie, zgodnie z opisem w kroku 2. Jeśli komunikat wymienia folder poniżej folderu źródła, ten folder ma własne uprawnienia, które wykluczają aplikację. Reszta biblioteki została przetworzona, a nic nie usunięto.

SharePoint: "There is no SharePoint site at …, or the app cannot see it"¶

Najpierw sprawdź adres URL witryny: to własny adres witryny, na przykład https://contoso.sharepoint.com/sites/HR, a nie biblioteka czy strona wewnątrz niej. Przy Sites.Selected tak samo może odpowiedzieć witryna, na której aplikacja nie ma przyznania.

SharePoint: "The site has no document library named …"¶

Komunikat wymienia biblioteki, które aplikacja widzi. Skopiuj jedną z tych nazw do library albo zostaw library puste, aby użyć domyślnej biblioteki witryny. Domyślna biblioteka jest nazwana w języku witryny, na przykład Documents albo Dokumente.

SharePoint: "The library has no folder …" or "… is a file, not a folder"¶

folder_path nie wskazuje folderu w bibliotece. Jest podawany względem najwyższego poziomu biblioteki, np. Policies/HR, i nie powtarza nazwy biblioteki.

SharePoint: "The folder … could not be listed: …"¶

Nie udało się odczytać folderu poniżej folderu źródła. Przyczyna następuje po dwukropku. Pozostałe foldery zostały przetworzone, a w tym przebiegu nic nie usunięto.

SharePoint: "Microsoft 365 stayed unavailable or kept throttling … after 4 attempts"¶

Graph nadal dławił zapytania albo zwracał błędy po czterech próbach. Następna synchronizacja zaczyna od nowa. Jeśli dzieje się tak przy każdej synchronizacji, planuj źródło rzadziej albo podziel bardzo dużą bibliotekę na kilka źródeł, każde z własnym folder_path.

SharePoint: "A SharePoint source needs a Microsoft Entra app credential"¶

Źródło wskazuje sekret innego rodzaju, na przykład API key. Dodaj aplikację do vault jako Microsoft Entra app i wybierz właśnie tę.

SharePoint: synchronizacja zakończyła się bez przetworzonych plików¶

Od ostatniego czystego przebiegu przy tej samej konfiguracji nic w bibliotece się nie zmieniło, więc nie było nic do zrobienia. Przełącz źródło na full na jeden przebieg, aby mimo to przeczytać wszystko od nowa.

Zaplanowane synchronizacje nie działają¶

Musi działać system zadań w tle. Sprawdź, czy proces workera jest aktywny:

Bez workera zadziałają wyłącznie ręczne wyzwolenia z CLI lub API.