Metaadatok és egyéni mezők
Ezen az oldalon
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ás | Hatás |
|---|---|
required: true | Minden dokumentumnak tartalmaznia kell ezt a metaadatot |
unique: true | Két dokumentum nem rendelkezhet ugyanazzal az értékkel |
inject_into_chunk: true | A 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
fieldskulcs-érték metaadatokat társít minden dokumentumhoz - A gyűjtemény szintű
field_definitionsszabályokat definiál: required, unique, inject_into_chunk - Az
inject_into_chunkopció 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