Metadati e campi personalizzati
In questa pagina
Il contesto che il documento non trasporta
Un rapporto tecnico non include sempre nel corpo del testo il nome dell’autore, l’anno di stesura o il livello di riservatezza. Eppure, sono proprio questi dettagli a fare la differenza tra una ricerca che trova il documento giusto e una che ne restituisce tre irrilevanti. Il sistema di metadati delle collezioni serve esattamente a questo: associare a ogni documento informazioni strutturate che la ricerca può sfruttare e che tu puoi utilizzare per filtrare i risultati.
Associare campi a un documento
Quando aggiungi un documento, il parametro fields accetta coppie chiave-valore che definisci liberamente:
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"
}
)
A questo livello non viene imposto alcuno schema: sei tu a scegliere i nomi dei campi. Questa libertà sembra comoda per il primo documento, ma diventa un problema al centesimo, quando author, auteur e Author coesistono nella stessa collezione senza che alcun filtro funzioni correttamente.
Stabilire regole a livello di collezione
È qui che entrano in gioco le field_definitions, dichiarate sulla collezione. Trasformano una convenzione orale in un vincolo verificato dall’API. Esistono tre impostazioni:
| Impostazione | Effetto |
|---|---|
required: true | Ogni documento deve contenere questo metadato |
unique: true | Due documenti non possono condividere lo stesso valore |
inject_into_chunk: true | Il metadato viene aggiunto al contenuto indicizzato |
Una definizione combina queste impostazioni campo per campo:
{
"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
}
]
}
Leggi questo esempio come una politica documentale: ogni documento ha un autore e un ID; quell’ID appartiene a un solo documento, il che blocca i duplicati in fase di ingestione; l’anno rimane opzionale per evitare di rifiutare elementi privi di data.
L’opzione che cambia la pertinenza
Di queste tre impostazioni, inject_into_chunk è l’unica che influisce sulla qualità delle risposte e merita un approfondimento. Durante l’indicizzazione, un documento viene suddiviso in frammenti (chunk) e l’attivazione di questa opzione copia il valore del campo in ciascuno di essi.
Concretamente, con author: "Marie Dupont" e inject_into_chunk: true, ogni chunk indicizzato porta con sé questo nome. Una domanda come «Cosa ha scritto Marie Dupont sulla latenza di rete?» ha allora buone probabilità di andare a segno, poiché il nome appare nel contenuto cercato. Senza iniezione, la stessa domanda si basa solo sul testo del rapporto, dove l’autore potrebbe comparire solo sulla copertina.
Attiva quindi l’iniezione per i campi che portano contesto: autore, dipartimento, anno, categoria. Lasciala disattivata per i campi amministrativi come un ID interno, la data di caricamento o lo stato di validazione, che aggiungerebbero solo rumore.
Tre schemi collaudati
I metadati utili non si inventano in astratto: derivano dalle domande poste al database. Una base di documentazione tecnica si organizza attorno a prodotto e versione, poiché la prima domanda di un utente è quasi sempre «quale versione?»:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Una base di conoscenze HR, invece, ragiona per categoria e data di efficacia, poiché l’errore più frequente in quel contesto è fornire una politica abrogata:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Infine, una base giuridica si struttura attorno alle parti, al tipo di contratto e alla scadenza, permettendoti di recuperare con una singola query gli accordi in procinto di scadere:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Mantenere uno schema coerente
La coerenza si perde sempre attraverso gli stessi canali e bastano poche abitudini per mantenerla. Standardizza il formato dei nomi dei campi: snake_case, in inglese, senza mescolare le lingue. Limitane il numero: da cinque a dieci campi coprono la maggior parte delle esigenze; oltre quella soglia, i costi di manutenzione superano i guadagni in pertinenza. Gestisci inject_into_chunk con discernimento, poiché ogni campo iniettato ingrandisce i chunk e, di conseguenza, i costi di archiviazione. Infine, documenta lo schema previsto per ogni collezione in un file accessibile al team: una volta che più persone alimentano il sistema, è quel file, e non la memoria del creatore, a garantire la coerenza.
Punti chiave
fieldsassocia metadati chiave-valore a ogni documentofield_definitionsa livello di collezione definiscono le regole: required, unique, inject_into_chunk- L’opzione
inject_into_chunkmigliora la pertinenza della ricerca aggiungendo i metadati al contenuto indicizzato - Standardizza i tuoi schemi di metadati per mantenere la coerenza della collezione