Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Metaadatok és egyéni mezők

7. lecke 16 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Kontextus, amit a dokumentum nem hordoz
  2. Mezők csatolása egy dokumentumhoz
  3. Szabályok definiálása gyűjtemény szinten
  4. A beállítás, ami megváltoztatja a relevanciát
  5. Három bevált séma
  6. Konzisztens séma fenntartása
  7. Főbb megállapítások

Kontextus, amit a dokumentum nem hordoz

Egy műszaki jelentés szövegtörzsében nem mindig szerepel a szerző neve, a készítés éve vagy a titkosítási szint. Pedig ezek a részletek döntik el, hogy a keresés megtalálja-e a megfelelő dokumentumot, vagy három irreleváns találatot ad vissza. A gyűjtemények metaadat-rendszere pontosan ezt a célt szolgálja: strukturált információkat társít minden dokumentumhoz, amelyeket a kereső kihasználhat, és amelyek alapján szűrhetsz.

Mezők csatolása egy dokumentumhoz

Dokumentum feltöltésekor a fields paraméter szabadon definiált kulcs-érték párokat fogad el:

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"
    }
)

Ezen a szinten nincs érvényesített séma: a mezőneveket te választod meg. Ez a szabadság az első dokumentumnál még kényelmesnek tűnik, de a századiknál már problémává válik, amikor ugyanabban a gyűjteményben az author, az auteur és az Author is egyszerre létezik, anélkül, hogy bármelyik szűrő működne.

Szabályok definiálása gyűjtemény szinten

Itt jönnek képbe a gyűjteményen deklarált field_definitions elemek. Ezek a szóbeli megállapodásokat az API által ellenőrzött kényszerekké alakítják. Három beállítás létezik:

BeállításHatás
required: trueMinden dokumentumnak tartalmaznia kell ezt a metaadatot
unique: trueKét dokumentum nem rendelkezhet ugyanazzal az értékkel
inject_into_chunk: trueA metaadat hozzáadódik az indexelt tartalomhoz

Egy definíció mezőről mezőre kombinálja ezeket a beállításokat:

{
  "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
    }
  ]
}

Olvasd ezt a példát dokumentum-szabályzatként: minden dokumentumnak van szerzője és azonosítója; az azonosító csak egy dokumentumhoz tartozik – ami blokkolja a duplikációkat a betöltéskor –, az év pedig opcionális marad, hogy elutasítás nélkül maradhassanak a dátum nélküli elemek.

A beállítás, ami megváltoztatja a relevanciát

E három beállítás közül az inject_into_chunk az egyetlen, amely befolyásolja a válaszok minőségét, ezért érdemes közelebbről is megvizsgálni. Indexelés során a dokumentum töredékekre (chunkokra) szakad, és ennek az opciónak a bekapcsolása másolja a mező értékét mindegyikbe.

Konkrétan: ha author: "Marie Dupont" és inject_into_chunk: true, akkor minden indexelt chunk tartalmazza ezt a nevet. Egy olyan kérdés, mint „Mit írt Marie Dupont a hálózati késleltetésről?“, így nagyobb eséllyel talál találatot, mivel a név szerepel a keresett tartalomban. Injektálás nélkül ugyanez a kérdés csak a jelentés szövegére támaszkodna, ahol a szerző neve esetleg csak a címlapon fordul elő.

Engedélyezd tehát az injektálást a kontextust hordozó mezőknél (szerző, osztály, év, kategória), és hagyd letiltva az adminisztratív mezőknél, mint például a belső azonosító, a feltöltés dátuma vagy a jóváhagyási státusz, mivel ezek csak zajt adnának hozzá.

Három bevált séma

A hasznos metaadatokat nem a levegőből kapjuk: az adatbázisnak feltett kérdésekből erednek. Egy műszaki dokumentációs bázis a termék és a verzió köré szerveződik, mivel a felhasználó első kérdése szinte mindig az, hogy „melyik verzió?“:

{
  "fields": {
    "product": "Grok API",
    "version": "v1",
    "type": "reference",
    "language": "en"
  }
}

Ezzel szemben egy HR-tudásbázis kategória és hatálybalépés dátuma szerint gondolkodik, mivel ott a rossz válasz leggyakrabban egy hatályon kívül helyezett szabályzat:

{
  "fields": {
    "category": "hr-policy",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Végül egy jogi bázis a felek, a szerződés típusa és a lejárat dátuma köré strukturálódik, lehetővé téve, hogy egyetlen lekérdezéssel kinyerd a hamarosan lejáró megállapodásokat:

{
  "fields": {
    "contract_type": "vendor",
    "party": "Acme Corp",
    "expiration": "2027-06-30",
    "jurisdiction": "France"
  }
}

Konzisztens séma fenntartása

A konzisztencia mindig ugyanazon csatornákon át vész el, és néhány szokás elég a megtartásához. Standardizáld a mezőnevek formátumát – snake_case, angolul, nyelvek keverése nélkül. Korlátozd a számukat: öt-tíz mező lefedi a legtöbb igényt; efölött a karbantartási költségek meghaladják a relevancia-növekedést. Bánj körültekintően az inject_into_chunk opcióval, mivel minden injektált mező növeli a chunkok méretét, és ezzel a tárolási költségeket is. Végül dokumentáld az egyes gyűjtemények elvárt sémáját egy, a csapat számára hozzáférhető fájlban: ha többen töltik fel az adatokat, ez a fájl – és nem a készítő emlékezete – garantálja a konzisztenciát.

Főbb megállapítások

  • A fields kulcs-érték metaadatokat társít minden dokumentumhoz
  • A gyűjtemény szintű field_definitions szabályokat definiál: required, unique, inject_into_chunk
  • Az inject_into_chunk opció javítja a keresés relevanciáját azáltal, hogy hozzáadja a metaadatokat az indexelt tartalomhoz
  • Standardizáld a metaadat-sémáidat a gyűjtemények konzisztenciájának megőrzése érdekében