Metadati un pielāgoti lauki
Šajā lapā
Konteksts, ko dokuments nesatur
Tehniskajā ziņojumā ne vienmēr ir norādīts autora vārds, rakstīšanas gads vai konfidencialitātes līmenis pašā teksta saturā. Tomēr tieši šīs detaļas izšķir, vai meklēšana atradīs pareizo dokumentu, vai arī atgriezīs trīs nederīgus rezultātus. Kolekciju metadatu sistēma kalpo tieši šim mērķim: saistīt katru dokumentu ar strukturētu informāciju, ko meklēšanas algoritms var izmantot un pēc kuras tu vari filtrēt datus.
Lauku pievienošana dokumentam
Augšupielādējot dokumentu, parametrs fields pieņem tavas definētās atslēgu-vērtību pārus:
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"
}
)
Šajā līmenī shēma netiek piespiesta: lauku nosaukumus tu izvēlies brīvi. Šī brīvība pirmajam dokumentam šķiet ērta, bet kļūst par problēmu, sasniedzot simto dokumentu, kad vienā kolekcijā līdzās pastāv author, auteur un Author, un neviens filtrs vairs nedarbojas.
Noteikumu definēšana kolekcijas līmenī
Šeit nāk talkā field_definitions, kas tiek deklarēti kolekcijā. Tie pārvērš mutisku vienošanos par API pārbaudāmu ierobežojumu. Pastāv trīs iestatījumi:
| Iestatījums | Ietekme |
|---|---|
required: true | Katram dokumentam ir jābūt šiem metadatiem |
unique: true | Divi dokumenti nevar dalīt vienu un to pašu vērtību |
inject_into_chunk: true | Metadati tiek pievienoti indeksētajam saturam |
Definīcija apvieno šos iestatījumus katram laukam atsevišķi:
{
"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
}
]
}
Uztver šo piemēru kā dokumentu politiku: katram dokumentam ir jābūt autoram un ID; šis ID pieder tikai vienam dokumentam – kas novērš dublikātus ielādes brīdī – un gads paliek opcionāls, lai noraidītu nedatētus vienumus.
Opcija, kas maina rezultātu nozīmīgumu
No šiem trim iestatījumiem tikai inject_into_chunk ietekmē atbilžu kvalitāti, un tas ir pelnījis tuvāku aplūkojumu. Indeksēšanas laikā dokuments tiek sadalīts fragmentos – čunkos (chunks) – un, aktivizējot šo opciju, lauka vērtība tiek nokopēta katrā no tiem.
Konkrēti, ja author: "Marie Dupont" un inject_into_chunk: true, tad katrs indeksētais čunks satur šo vārdu. Jautājums „Ko Marija Duponta rakstījusi par tīkla latentumu?” tad iegūst iespēju trāpīt mērķī, jo vārds parādās meklētajā saturā. Bez injicēšanas tas pats jautājums paļautos tikai uz ziņojuma tekstu, kurā autors varētu būt minēts tikai uz vāka lapas.
Tāpēc aktivizē injicēšanu laukiem, kas nes kontekstu – autors, nodaļa, gads, kategorija – un atstāj to izslēgtu administratīviem laukiem, piemēram, iekšējam ID, augšupielādes datumam vai apstiprināšanas statusam, kas tikai radītu troksni.
Trīs pierādītas shēmas
Noderīgi metadati netiek izgudroti abstrakti: tie izriet no jautājumiem, kas tiek uzdoti datubāzei. Tehniskās dokumentācijas bāze organizējas ap produktu un versiju, jo lietotāja pirmais jautājums gandrīz vienmēr ir „kura versija?”:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Savukārt HR zināšanu bāze balstās uz kategoriju un spēkā stāšanās datumu, jo nepareiza atbilde tur visbiežāk ir atcelta politika:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Visbeidzot, juridiskā bāze strukturējas ap pusēm, līguma veidu un termiņa beigām, ļaujot vienā vaicājumā atlasīt līgumus, kuriem drīz beigsies termiņš:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Konsekventas shēmas uzturēšana
Konsekvence vienmēr tiek zaudēta vienādos veidos, un pietiek ar dažiem ieradumiem, lai to uzturētu. Standartizē lauku nosaukumu formātus – snake_case, angļu valodā, nejaukt valodas. Ierobežo to skaitu: pieci līdz desmit lauki aptver lielāko daļu vajadzību; pārsniedzot šo robežu, uzturēšanas izmaksas pārsniedz ieguvumus no rezultātu nozīmīguma. Ar inject_into_chunk rīkojies apdomīgi, jo katrs injicētais lauks palielina čunku apjomu un līdz ar to arī glabāšanas izmaksas. Visbeidzot, dokumentē paredzēto shēmu katrai kolekcijai failā, kas pieejams komandai: tiklīdz to papildina vairāki cilvēki, tieši šis fails, nevis izveidotāja atmiņa, garantē konsekvenci.
Galvenās atziņas
fieldssaista atslēgu-vērtību metadatus ar katru dokumentufield_definitionskolekcijas līmenī definē noteikumus: required, unique, inject_into_chunk- Opcija
inject_into_chunkuzlabo meklēšanas nozīmīgumu, pievienojot metadatus indeksētajam saturam - Standartizē savu metadatu shēmas, lai uzturētu kolekcijas konsekvenci