Metadate și câmpuri personalizate
Pe această pagină
Contextul pe care documentul nu îl conține
Un raport tehnic nu include întotdeauna numele autorului, anul redactării sau nivelul de confidențialitate în corpul textului. Totuși, aceste detalii fac diferența dintre o căutare care găsește documentul corect și una care returnează trei rezultate irelevante. Sistemul de metadate al colecțiilor servește exact acestui scop: asocierea de informații structurate fiecărui document, pe care motorul de căutare le poate exploata și după care dumneavoastră puteți filtra.
Atașarea câmpurilor la un document
La adăugarea unui document, parametrul fields acceptă perechi cheie-valoare pe care le definiți liber:
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"
}
)
La acest nivel nu se impune nicio schemă: numele câmpurilor sunt la latitudinea dumneavoastră. Această libertate pare confortabilă pentru primul document, dar devine o problemă la al o sutalea, când author, auteur și Author coexistă în aceeași colecție fără ca niciun filtru să funcționeze corect.
Stabilirea regulilor la nivelul colecției
Aici intervin field_definitions, declarate la nivelul colecției. Ele transformă o convenție orală într-o constrângere verificată de API. Există trei setări:
| Setare | Efect |
|---|---|
required: true | Fiecare document trebuie să conțină aceste metadate |
unique: true | Două documente nu pot avea aceeași valoare |
inject_into_chunk: true | Metadatele sunt adăugate la conținutul indexat |
O definiție combină aceste setări câmp cu câmp:
{
"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
}
]
}
Citiți acest exemplu ca pe o politică pentru documente: fiecare document are un autor și un ID, acel ID aparține unui singur document – ceea ce blochează duplicatele la ingestie – iar anul rămâne opțional pentru a evita respingerea elementelor nedatate.
Opțiunea care schimbă relevanța
Dintre aceste trei setări, inject_into_chunk este singura care afectează calitatea răspunsurilor și merită o analiză atentă. În timpul indexării, un document este divizat în fragmente (chunks), iar activarea acestei opțiuni copiază valoarea câmpului în fiecare dintre ele.
Concret, cu author: "Marie Dupont" și inject_into_chunk: true, fiecare fragment indexat va conține acest nume. O întrebare precum „Ce a scris Marie Dupont despre latența rețelei?“ are atunci șanse să nimerască ținta, deoarece numele apare în conținutul căutat. Fără injectare, aceeași întrebare se bazează doar pe textul raportului, unde autorul ar putea apărea doar pe pagina de copertă.
Prin urmare, activați injectarea pentru câmpurile care poartă context – autor, departament, an, categorie – și lăsați-o dezactivată pentru câmpurile administrative, cum ar fi un ID intern, data încărcării sau statutul de validare, care ar adăuga doar zgomot.
Trei scheme dovedite
Metadatele utile nu sunt inventate în abstract: ele derivă din întrebările adresate bazei de date. O bază de documentație tehnică se organizează în jurul produsului și al versiunii, deoarece prima întrebare a unui utilizator este aproape întotdeauna „ce versiune?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
O bază de cunoștințe pentru resurse umane, în schimb, raționează pe categorii și data intrării în vigoare, deoarece răspunsul greșit acolo este cel mai adesea o politică abrogată:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
În final, o bază juridică se structurează în jurul părților implicate, tipului de contract și al expirării, permițându-vă să extrageți acordurile care se apropie de expirare într-o singură interogare:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Menținerea unei scheme coerente
Coerența se pierde întotdeauna pe aceleași căi, iar câteva obiceiuri sunt suficiente pentru a o menține. Standardizați formatele numelor de câmpuri – snake_case, în engleză, fără amestecarea limbilor. Limitați numărul lor: cinci până la zece câmpuri acoperă majoritatea nevoilor; dincolo de acest prag, costurile de mentenanță depășesc câștigurile de relevanță. Gestionați inject_into_chunk cu discernământ, deoarece fiecare câmp injectat mărește dimensiunea fragmentelor și, implicit, costurile de stocare. În final, documentați schema așteptată pentru fiecare colecție într-un fișier accesibil echipei: odată ce mai multe persoane îl alimentează, acel fișier, nu memoria creatorului, garantează coerența.
Puncte cheie
fieldsasociază metadate de tip cheie-valoare fiecărui documentfield_definitionsla nivelul colecției definesc reguli: required, unique, inject_into_chunk- Opțiunea
inject_into_chunkîmbunătățește relevanța căutării prin adăugarea metadatelor la conținutul indexat - Standardizați schemele de metadate pentru a menține coerența colecției