Metadata a vlastní pole
Na této stránce
Kontext, který dokument sám o sobě nese
Technická zpráva nemusí vždy obsahovat jméno autora, rok vzniku ani úroveň důvěrnosti přímo ve svém textu. Přitom právě tyto detaily rozhodují o tom, zda vyhledávání najde ten správný dokument, nebo vrátí tři irelevantní výsledky. Systém metadat kolekcí slouží přesně k tomuto účelu: přiřazovat ke každému dokumentu strukturované informace, které může vyhledávání využít a podle kterých můžeš filtrovat.
Připojení polí k dokumentu
Při přidávání dokumentu přijímá parametr fields dvojice klíč-hodnota, které si libovolně definuješ:
await client.collections.upload_document(
collection_id=collection_id,
name="technical-report-q1",
data=pdf_content,
fields={
"author": "Marie Dupont",
"year": "2026",
"department": "R&D",
"document_type": "report",
"confidentiality": "internal"
}
)
Na této úrovni se nevynucuje žádné schéma: názvy polí si volíš sám. Tato svoboda působí u prvního dokumentu pohodlně, ale u stého se změní v problém, když v téže kolekci koexistují author, auteur a Author, aniž by fungoval jakýkoli filtr.
Nastavení pravidel na úrovni kolekce
Zde přicházejí na řadu field_definitions, deklarované přímo u kolekce. Mění nepsanou dohodu na omezení ověřované API. Existují tři nastavení:
| Nastavení | Efekt |
|---|---|
required: true | Každý dokument musí toto metadata obsahovat |
unique: true | Dva dokumenty nemohou mít stejnou hodnotu |
inject_into_chunk: true | Metadata se přidají do indexovaného obsahu |
Definice kombinuje tato nastavení pole po poli:
{
"field_definitions": [
{
"name": "author",
"required": true,
"inject_into_chunk": true
},
{
"name": "document_id",
"required": true,
"unique": true
},
{
"name": "year",
"required": false,
"inject_into_chunk": true
}
]
}
Tento příklad čti jako politiku pro dokumenty: každý dokument má autora a ID, přičemž toto ID patří pouze jednomu dokumentu – což blokuje duplikáty při ingestování – a rok zůstává volitelný, aby se neodmítaly položky bez data.
Možnost, která mění relevanci
Z těchto tří nastavení je pouze inject_into_chunk tím, které ovlivňuje kvalitu odpovědí, a zaslouží si bližší pohled. Během indexování se dokument rozdělí na fragmenty – chunky – a povolením této možnosti se hodnota pole zkopíruje do každého z nich.
Konkrétně: při author: "Marie Dupont" a inject_into_chunk: true nese každý indexovaný chunk toto jméno. Otázka typu „Co napsala Marie Dupontová o latenci sítě?“ pak má šanci zasáhnout cíl, protože se jméno objevuje ve vyhledávaném obsahu. Bez injektáže závisí stejná otázka pouze na textu zprávy, kde se autor může objevit jen na titulní straně.
Proto povol injektáž pro pole nesoucí kontext – autor, oddělení, rok, kategorie – a ponech ji vypnutou pro administrativní pole, jako je interní ID, datum nahrání nebo stav validace, která by pouze přidávala šum.
Tři osvědčená schémata
Užitečná metadata nevznikají v abstraktnu: vycházejí z otázek, které kladeš databázi. Báze technické dokumentace se organizuje kolem produktu a verze, protože první otázka uživatele je téměř vždy „která verze?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Báze znalostí pro lidské zdroje však uvažuje v kategoriích a datu účinnosti, protože špatná odpověď tam nejčastěji znamená zrušenou politiku:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Právní báze se konečně strukturuje kolem stran, typu smlouvy a data vypršení, což ti umožňuje jediným dotazem vytáhnout dohody blížící se konci platnosti:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Udržování konzistentního schématu
Konzistence se vždy ztrácí stejnými cestami a k jejímu udržení stačí několik návyků. Standardizuj formáty názvů polí – snake_case, v angličtině, bez míchání jazyků. Omez jejich počet: pět až deset polí pokryje většinu potřeb; nad touto hranicí převyšují náklady na údržbu přínosy pro relevanci. S inject_into_chunk zacházej rozumně, protože každé injektované pole zvětšuje chunky, a tím i náklady na úložiště. Nakonec zdokumentuj očekávané schéma pro každou kolekci do souboru přístupného celému týmu: jakmile do ní přispívá více lidí, garantuje konzistenci právě tento soubor, nikoliv paměť tvůrce.
Klíčové poznatky
fieldspřiřazují ke každému dokumentu metadata ve formě dvojic klíč-hodnotafield_definitionsna úrovni kolekce definují pravidla: required, unique, inject_into_chunk- Možnost
inject_into_chunkzlepšuje relevanci vyhledávání přidáním metadat do indexovaného obsahu - Standardizuj svá schémata metadat pro udržení konzistence kolekce