Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Metadata a vlastní pole

Lekce 7 z 16 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Kontext, který dokument sám o sobě nese
  2. Připojení polí k dokumentu
  3. Nastavení pravidel na úrovni kolekce
  4. Možnost, která mění relevanci
  5. Tři osvědčená schémata
  6. Udržování konzistentního schématu
  7. Klíčové poznatky

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: trueKaždý dokument musí toto metadata obsahovat
unique: trueDva dokumenty nemohou mít stejnou hodnotu
inject_into_chunk: trueMetadata 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

  • fields přiřazují ke každému dokumentu metadata ve formě dvojic klíč-hodnota
  • field_definitions na úrovni kolekce definují pravidla: required, unique, inject_into_chunk
  • Možnost inject_into_chunk zlepšuje relevanci vyhledávání přidáním metadat do indexovaného obsahu
  • Standardizuj svá schémata metadat pro udržení konzistence kolekce