Zpracování, synchronizace a řešení potíží
Rozsah zdroje určuje, co do kolekce vstoupí. Processing určuje, jak se obsah stane prohledávatelným. Retrieval určuje, které chunky dostane agent. Výchozí hodnoty měňte pouze proti opakovatelnému evaluation setu.
JSON Features a JSON Metadata Definitions
Když datový zdroj importuje JSON, tato dvě nastavení určují roli pojmenovaných polí:
| Nastavení | Praktická otázka | Doporučené použití | Typické klíče |
|---|---|---|---|
| JSON Features | Z jakého obsahu má AI čerpat? | Významový text, který má podporovat vyhledávání a odpovědi | title, description, summary, content, normalizovaný text komentářů |
| JSON Metadata Definitions | Podle čeho má systém dokument poznat, zařadit nebo případně filtrovat? | Stabilní identifikátory a řízené klasifikační hodnoty | id, category, author, language, createdAt, customerId |
Pole jsou dostupná v aktuálních formulářích pro vytvoření Manual Upload, Google Drive, OneDrive, SharePoint, Azure Storage Account a Azure File Share. Stejný klíč nevkládejte do obou seznamů bez konkrétního důvodu a retrieval testu.
Připravte JSON kontrakt
Před konfigurací kteréhokoli seznamu shromážděte:
- jeden až tři reprezentativní JSON objekty,
- příklady otázek, které budou uživatelé pokládat,
- klasifikace nebo filtry, které chtějí používat,
- příklady vnořených, volitelných nebo strukturálně nekonzistentních objektů.
Pro features upřednostněte stručný text s obchodním významem, pro metadata stabilní a normalizované skalární hodnoty. Vynechte binární obsah, přístupové tokeny nebo podepsané URL, interní hodnoty zpracování, duplicitní text a rozsáhlé objekty bez jasného přínosu pro retrieval.
Vnořené objekty, seznamy, chybějící hodnoty a klíč, který mezi záznamy mění datový typ, vyžadují stabilní upstream kontrakt. Vnořené hodnoty zploštěte do zdokumentovaných klíčů, normalizujte data a identifikátory a užitečné seznamy nebo komentáře v případě potřeby spojte do záměrného textového pole. Nepředpokládejte, že neotestovaná vnořená cesta bude interpretována požadovaným způsobem.
Příklad konfigurace
Uvažujte tento reprezentativní objekt:
{
"id": "policy-1042",
"title": "Password reset policy",
"summary": "Rules for resetting an employee account password.",
"content": "After a reset, the employee must create a new password and confirm multifactor authentication.",
"category": "Identity",
"author": "Security Operations",
"language": "en",
"createdAt": "2026-08-01T09:30:00Z",
"_etag": "internal-revision-value"
}
Doporučené hodnoty:
JSON Features: title, summary, content
JSON Metadata Definitions: id, category, author, language, createdAt
| Klíč | Seznam | Důvod a očekávaný dopad |
|---|---|---|
title | Features | Přidá předmět a terminologii dokumentu do prohledávatelného obsahu. |
summary | Features | Poskytne stručný popis, který může zlepšit retrieval u obecných otázek. |
content | Features | Obsahuje fakta, ze kterých se mají vytvářet odpovědi. |
id | Metadata | Poskytne stabilní identifikátor logického záznamu. |
category | Metadata | Klasifikuje záznam pro kontrolu a zamýšlené filtrování podle kategorie. |
author | Metadata | Zaznamená odpovědný zdroj nebo tým. |
language | Metadata | Poskytne normalizovanou jazykovou klasifikaci pro zamýšlené filtrování. |
createdAt | Metadata | Zachová seřaditelné normalizované časové razítko, pokud je RAG služba podporuje. |
_etag | Ani jeden | Jde o interní hodnotu zpracování bez přínosu pro uživatelské vyhledávání. |
Toto rozdělení má podporovat obsahovou otázku například „Co musí zaměstnanec udělat po resetování hesla?“ a je zamýšlené pro filtr například „Dokumenty k identitě v angličtině“. Než se na toto chování spolehnete, otestujte obojí proti nasazené RAG službě.
Frontend zobrazuje obě nastavení jako opakovatelné seznamy názvů polí a před vytvořením datového zdroje odstraňuje položky, jejichž obsah tvoří pouze mezery. Aplikační backend neověřuje, že název existuje v importovaném JSON, a přijaté seznamy beze změny předává do vlastností JsonFeatures a MetadataDefinitions RAG klienta.
Aplikační backend odesílá tyto hodnoty při vytvoření datového zdroje. Samostatně je neukládá do své databáze, nevrací je v aktuálním detailu datového zdroje ani je nepřijímá přes současný update endpoint. Seznamy definujte a otestujte před vytvořením produkčního zdroje.
Aplikace ani backend neurčují přesně, jak samostatná RAG služba indexuje vybrané features, aplikuje metadata filtry, vyhodnocuje vnořené cesty, zpracovává chybějící hodnoty nebo smíšené datové typy ani jak řeší klíč přítomný v obou seznamech. Výše uvedená doporučení považujte za kvalifikovaný výchozí bod. Pilotně importujte reprezentativní záznamy, zkontrolujte extrahované dokumenty a chunky a otestujte alespoň jednu obsahovou otázku a jeden zamýšlený metadata filtr.
Společná pole integračních zdrojů
Každý připojený zdroj vyžaduje Name, volitelný Description, Connection ID a frekvenci synchronizace. Connection ID vybírá uloženou autentizaci; nikdy není polem pro secret.
Frekvence synchronizace
| Frekvence | Použití |
|---|---|
| On Demand | Podepsané politiky, kontrolovaná vydání, čtvrtletní exporty |
| Daily | Provozní dokumentace, aktivní projekty a měněné sdílené složky |
| Weekly | Udržované, ale neurgentní znalosti |
| Monthly | Pomalu měněné archivy a reference |
Manual Upload nemá upstream systém k synchronizaci. Vyšší frekvence není automaticky lepší: spotřebuje kapacitu poskytovatele i zpracování a dříve zpřístupní nezkontrolované změny.
Retriever settings
Většina formulářů nabízí Skip query rewrite, Skip LLM ranking a Maximum result count (1 až 15). Query rewrite může zlepšit vybavení při konverzačních otázkách, zatímco vypnutí pomáhá přesným identifikátorům. LLM ranking může zlepšit relevanci za cenu latence. Výchozí hodnoty ponechte, dokud měření neprokáže opak.
OneDrive a Confluence aktuálně nezobrazují stejnou Retriever sekci.
Processing settings
Podle zdroje UI nabízí filtry typů souborů, advanced extraction, JSON Features a JSON Metadata Definitions, strategii chunkingu, velikost vektoru a kvantizaci. Aktuální formuláře mají výchozí vector size 3072 a quantization None.
- Jira a Firecrawl nenabízejí filtr typů souborů.
- Confluence nenabízí volbu chunkingu.
- Manual Upload aktuálně volbu chunkingu skrývá.
- OneDrive nemá společnou Retriever sekci.
Advanced extraction může pomoci tabulkám, layoutu a obrázkům, ale musí se otestovat. Změna vektorů či chunkingu může vyžadovat nové zpracování a zneplatnit předchozí porovnání kvality.
Kontrola před produkcí
V Overview zkontrolujte plán, počty a poslední/příští sync; ve Files dokumenty a příznaky indexed/readable; v Logs výsledky běhů; v detailu dokumentu extrahované chunky.
Otestujte známou přítomnou odpověď, známou chybějící odpověď, rozporné verze, nedávno změněnou položku a očekávanou výjimku.
Řešení potíží
| Příznak | První kontrola |
|---|---|
| Connection ID je prázdné | Kompatibilní Connection existuje a je správně viditelné či sdílené |
| Úspěšný zdroj má nula souborů | Pravopis selektoru/cesty/klíče, oprávnění účtu, typy souborů |
| Chybí Google složka | Folder ID, Shared Drive/subfolder přepínače a přístup účtu |
| Chybí Microsoft složka | Přesná relativní cesta, drive/site/library a přístup účtu |
| Azure zdroj je prázdný | Selektor blobu nebo přesný share name a platnost credentials |
| Jira nebo Confluence je prázdná | Project/Space Key a oprávnění servisního účtu |
| Firecrawl obsahuje balast | Zúžit include regex, přidat výjimky, snížit limit |
| Dokument existuje, ale agent jej nepoužije | Indexed/Readable, chunky, přiřazení kolekce, retrieval settings |
| Plánovaný refresh se zastavil | Stav Connection, expirace tokenu, Logs, schedule a kvóta |
Pokud chybný obsah představuje významné riziko, odpojte kolekci od produkčních agentů, zachovejte netajné diagnostické podklady, určete zda selhalo oprávnění, selektor, sync, extrakce, indexace či retrieval, opravte na testovacím agentovi a před obnovením znovu spusťte evaluation set.