Metaduomenys ir tinkinami laukai
Šiame puslapyje
Kontekstas, kurio dokumente nėra
Techninėje ataskaitoje ne visada būna nurodytas autoriaus vardas, parašymo metai ar konfidencialumo lygis pagrindiniame tekste. Tačiau šios detalės lemia, ar paieška ras tinkamą dokumentą, ar grąžins tris netinkamus. Kolekcijų metaduomenų sistema skirta būtent tam: susieti struktūrizuotą informaciją su kiekvienu dokumentu, kurią paieška gali išnaudoti, o tu – filtruoti.
Laukų pridėjimas prie dokumento
Pridedant dokumentą, parametras fields priima tavo apibrėžiamus rakto ir reikšmės porų rinkinius:
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"
}
)
Šiame lygmenyje schema neprivaloma: laukų pavadinimus renki pats. Ši laisvė pirmajam dokumentui atrodo patogi, tačiau šimtąjį dokumentą pasiekus tampa problema, kai toje pačioje kolekcijoje coegzistuoja author, auteur ir Author, o joks filtras neveikia.
Taisyklių nustatymas kolekcijos lygmenyje
Čia į pagalbą ateina field_definitions, deklaruojami kolekcijoje. Jie žodinį susitarimą paverčia API patikrinamu apribojimu. Yra trys nustatymai:
| Nustatymas | Poveikis |
|---|---|
required: true | Kiekvienas dokumentas privalo turėti šiuos metaduomenis |
unique: true | Du dokumentai negali turėti tos pačios reikšmės |
inject_into_chunk: true | Metaduomenys įtraukiami į indeksuojamą turinį |
Apibrėžimas šiuos nustatymai derina laukas po lauko:
{
"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
}
]
}
Šį pavyzdį skaityk kaip dokumentų politiką: kiekvienas dokumentas turi autorių ir ID, tas ID priklauso tik vienam dokumentui – tai blokuoja dublikatus įkeliant – o metai lieka neprivalomi, kad nebūtų atmesti nedatuoti elementai.
Parinktis, keičianti aktualumą
Iš šių trijų nustatymų tik inject_into_chunk daro įtaką atsakymų kokybei, todėl jis nusipelno atidesnio žvilgsnio. Indeksavimo metu dokumentas skaidomas į fragmentus – dalis (chunks) – ir įjungus šią parinktį, lauko reikšmė nukopijuojama į kiekvieną iš jų.
Konkrečiai kalbant, esant author: "Marie Dupont" ir inject_into_chunk: true, kiekvienas indeksuotas fragmentas turės šį vardą. Toks klausimas kaip „Ką Marie Dupont rašė apie tinklo delsą?“ tada turi šansų pataikyti į taikinį, nes vardas atsiranda ieškotame turinyje. Be injekcijos, tas pats klausimas remtųsi tik ataskaitos tekstu, kuriame autorius gali būti paminėtas tik viršelyje.
Todėl įjunk injekciją kontekstą nešantiems laukams – autoriui, skyriui, metams, kategorijai – ir palikite ją išjungtą administraciniams laukams, pvz., vidiniam ID, įkėlimo datai ar patvirtinimo būsenai, kurie tik pridėtų triukšmo.
Trys įrodytos schemos
Naudingi metaduomenys neišgalvojami abstrakčiai: jie kyla iš duomenų bazei užduodamų klausimų. Techninės dokumentacijos bazė organizuojama pagal produktą ir versiją, nes pirmasis naudotojo klausimas beveik visada yra „kuri versija?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Tuo tarpu žmogiškųjų išteklių žinių bazė mąsto kategorijomis ir įsigaliojimo data, nes neteisingas atsakymas ten dažniausiai yra panaikinta politika:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Galiausiai, teisinė bazė struktūruojama pagal šalis, sutarties tipą ir galiojimo pabaigą, leidžianti viena užklausa ištraukti artėjančius galiojimo pabaigai susitarimus:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Nuoseklios schemos išlaikymas
Nuoseklumas visada prarandamas tais pačiais būdais, ir pakanka kelių įpročių jį išlaikyti. Standartizuok laukų pavadinimų formatą – snake_case, anglų kalba, nemaišyk kalbų. Apribok jų skaičių: penki–dešimt laukų padengia daugumą poreikių; viršijus tai, priežiūros kaštai viršija aktualumo naudą. Su inject_into_chunk elkis apgalvotai, nes kiekvienas injekuotas laukas didina fragmentus, taigi ir saugojimo išlaidas. Galiausiai, dokumentuok numatomą kiekvienos kolekcijos schemą failo, prieinamo komandai, pavidalu: kai ją pildo keli žmonės, būtent tas failas, o ne kūrėjo atmintis, garantuoja nuoseklumą.
Svarbiausi punktai
fieldssusieja rakto ir reikšmės metaduomenis su kiekvienu dokumentufield_definitionskolekcijos lygmenyje apibrėžia taisykles: required, unique, inject_into_chunk- Parinktis
inject_into_chunkgerina paieškos aktualumą, pridėdama metaduomenis prie indeksuojamo turinio - Standartizuok savo metaduomenų schemas, kad išlaikytum kolekcijų nuoseklumą