Metadáta a vlastné polia
Na tejto strane
Kontext, ktorý dokument sám o sebe neobsahuje
Technická správa nemusí vždy obsahovať meno autora, rok vyhotovenia ani úroveň dôvernosti priamo v hlavnom texte. Práve tieto detaily však rozhodujú o tom, či vyhľadávanie nájde ten správny dokument, alebo vráti tri irelevantné výsledky. Systém metadát kolekcie slúži presne na tento účel: priradiť ku každému dokumentu štruktúrované informácie, ktoré môže vyhľadávanie využiť a podľa ktorých môžeš filtrovať.
Priradenie polí k dokumentu
Pri pridávaní dokumentu parameter fields akceptuje dvojice kľúč-hodnota, ktoré si definuješ úplne voľne:
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 tejto úrovni sa nevynucuje žiadna schéma: názvy polí si vyberáš sám. Táto sloboda sa pri prvom dokumente zdá pohodlná, no pri stovtom sa stane problémom, keď v tej istej kolekcii koexistujú author, auteur a Author bez toho, aby fungoval akýkoľvek filter.
Nastavenie pravidiel na úrovni kolekcie
Tu prichádzajú na rad field_definitions, ktoré sa deklarujú priamo na kolekcii. Menia ústnu dohodu na obmedzenie overované API. Existujú tri nastavenia:
| Nastavenie | Účinok |
|---|---|
required: true | Každý dokument musí obsahovať tieto metadáta |
unique: true | Dva dokumenty nemôžu mať rovnakú hodnotu |
inject_into_chunk: true | Metadáta sa pridajú do indexovaného obsahu |
Definícia kombinuje tieto nastavenia 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 príklad čítaj ako politiku pre dokumenty: každý dokument musí mať autora a ID, pričom toto ID patrí len jednému dokumentu – čo blokuje duplikáty už pri nahrávaní – a rok zostáva voliteľný, aby sa neodmietali položky bez dátumu.
Možnosť, ktorá mení relevanciu
Z týchto troch nastavení je inject_into_chunk jediným, ktoré ovplyvňuje kvalitu odpovedí, a zaslúži si bližší pohľad. Počas indexovania sa dokument rozdelí na fragmenty – chunky – a povolenie tejto možnosti skopíruje hodnotu poľa do každého z nich.
Konkrétne, pri author: "Marie Dupont" a inject_into_chunk: true nesie každý indexovaný chunk toto meno. Otázka typu „Čo napísala Marie Dupontová o oneskorení v sieti?“ má potom šancu trafiť cieľ, keďže sa meno nachádza priamo vo vyhľadávanom obsahu. Bez injektáže sa tá istá otázka spolieha len na text správy, kde sa autor môže vyskytovať iba na titulnej strane.
Injektáž teda povoľ pre polia nesúce kontext – autor, oddelenie, rok, kategória – a nechaj ju vypnutú pre administratívne polia, ako sú interné ID, dátum nahratia alebo stav schválenia, ktoré by len pridávali šum.
Tri overené schémy
Užitočné metadáta nevznikajú v abstrakte: vychádzajú z otázok, ktoré kladieš databáze. Báza technickej dokumentácie sa organizuje okolo produktu a verzie, keďže prvá otázka používateľa je takmer vždy „ktorá verzia?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Báza znalostí pre ľudské zdroje však uvažuje podľa kategórie a dátumu účinnosti, keďže nesprávna odpoveď tu najčastejšie znamená zrušenú politiku:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Napokon, právna báza sa štruktúruje okolo strán, typu zmluvy a dátumu exspirácie, čo ti umožňuje jediným dopytom vytiahnuť zmluvy blížiacie sa ku koncu platnosti:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Udržiavanie konzistentnej schémy
Konzistencia sa vždy stráca rovnakými spôsobmi a na jej udržanie stačí niekoľko návykov. Štandardizuj formát názvov polí – snake_case, v angličtine, bez miešania jazykov. Obmedz ich počet: päť až desať polí pokryje väčšinu potrieb; nad touto hranicou náklady na údržbu prevyšujú prínos pre relevanciu. S inject_into_chunk zaobchádzaj uvážlivo, keďže každé injektované pole zväčšuje chunky, a tým aj náklady na úložisko. Napokon zdokumentuj očakávanú schému pre každú kolekciu do súboru dostupného pre celý tím: akonáhle do nej prispeje viacero ľudí, práve tento súbor, a nie pamäť tvorcu, garantuje konzistenciu.
Kľúčové poznatky
fieldspriraďuje ku každému dokumentu metadáta vo forme dvojíc kľúč-hodnotafield_definitionsna úrovni kolekcie definujú pravidlá: required, unique, inject_into_chunk- Možnosť
inject_into_chunkzlepšuje relevanciu vyhľadávania pridaním metadát do indexovaného obsahu - Štandardizuj svoje schémy metadát, aby si udržal konzistenciu kolekcie