Salt la conținutul principal
Română— Alege o limbă
Meniu

Metadate și câmpuri personalizate

Lecția 7 din 16 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Contextul pe care documentul nu îl conține
  2. Atașarea câmpurilor la un document
  3. Stabilirea regulilor la nivelul colecției
  4. Opțiunea care schimbă relevanța
  5. Trei scheme dovedite
  6. Menținerea unei scheme coerente
  7. Puncte cheie

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:

SetareEfect
required: trueFiecare document trebuie să conțină aceste metadate
unique: trueDouă documente nu pot avea aceeași valoare
inject_into_chunk: trueMetadatele 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

  • fields asociază metadate de tip cheie-valoare fiecărui document
  • field_definitions la 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