Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Metadáta a vlastné polia

Lekcia 7 z 16 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Kontext, ktorý dokument sám o sebe neobsahuje
  2. Priradenie polí k dokumentu
  3. Nastavenie pravidiel na úrovni kolekcie
  4. Možnosť, ktorá mení relevanciu
  5. Tri overené schémy
  6. Udržiavanie konzistentnej schémy
  7. Kľúčové poznatky

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: trueKaždý dokument musí obsahovať tieto metadáta
unique: trueDva dokumenty nemôžu mať rovnakú hodnotu
inject_into_chunk: trueMetadá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

  • fields priraďuje ku každému dokumentu metadáta vo forme dvojíc kľúč-hodnota
  • field_definitions na úrovni kolekcie definujú pravidlá: required, unique, inject_into_chunk
  • Možnosť inject_into_chunk zlepš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