Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Metadati e campi personalizzati

Lezione 7 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Il contesto che il documento non trasporta
  2. Associare campi a un documento
  3. Stabilire regole a livello di collezione
  4. L’opzione che cambia la pertinenza
  5. Tre schemi collaudati
  6. Mantenere uno schema coerente
  7. Punti chiave

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:

ImpostazioneEffetto
required: trueOgni documento deve contenere questo metadato
unique: trueDue documenti non possono condividere lo stesso valore
inject_into_chunk: trueIl 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

  • fields associa metadati chiave-valore a ogni documento
  • field_definitions a livello di collezione definiscono le regole: required, unique, inject_into_chunk
  • L’opzione inject_into_chunk migliora la pertinenza della ricerca aggiungendo i metadati al contenuto indicizzato
  • Standardizza i tuoi schemi di metadati per mantenere la coerenza della collezione