Métadonnées et champs personnalisés

Le contexte que le document ne porte pas

Un rapport technique ne contient pas toujours, dans son corps, le nom de son auteur, son année de rédaction ou son niveau de confidentialité. Ces informations font pourtant la différence entre une recherche qui trouve et une recherche qui ramène trois documents hors sujet. Le système de métadonnées des collections sert exactement à cela : associer à chaque document des informations structurées que la recherche exploitera et sur lesquelles vous pourrez filtrer.

Attacher des champs à un document

À l’ajout d’un document, le paramètre fields accepte des paires clé-valeur que vous définissez librement :

await client.collections.upload_document(
    collection_id=collection_id,
    name="rapport-technique-q1",
    data=pdf_content,
    fields={
        "author": "Marie Dupont",
        "year": "2026",
        "department": "R&D",
        "document_type": "rapport",
        "confidentiality": "interne"
    }
)

Aucun schéma n’est imposé à ce niveau : les noms de champs sont les vôtres. Cette liberté est confortable au premier document et devient un problème au centième, lorsque author, auteur et Author coexistent dans la même collection sans qu’aucun filtre ne fonctionne.

Poser des règles au niveau de la collection

C’est le rôle des field_definitions, déclarées sur la collection, qui transforment une convention orale en contrainte vérifiée par l’API. Trois réglages existent :

Une définition combine ces réglages champ par champ :

{
  "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
    }
  ]
}

L’exemple se lit comme une politique documentaire : tout document a un auteur et un identifiant, cet identifiant n’appartient qu’à un seul document — ce qui bloque les doublons dès l’ingestion — et l’année reste facultative pour ne pas rejeter les pièces non datées.

L’option qui change la pertinence

De ces trois réglages, inject_into_chunk est le seul qui agisse sur la qualité des réponses, et il vaut la peine d’y regarder de près. Lors de l’indexation, un document est découpé en fragments — les chunks — et l’option active recopie la valeur du champ dans chacun d’eux.

Concrètement, avec author: "Marie Dupont" et inject_into_chunk: true, chaque chunk indexé porte ce nom. Une question du type « qu’a écrit Marie Dupont sur la latence réseau ? » a alors une chance de tomber juste, le nom figurant dans le contenu recherché. Sans l’injection, la même question ne s’appuie plus que sur le texte du rapport, où l’auteur n’apparaît peut-être qu’en page de garde.

Activez donc l’injection pour les champs porteurs de contexte — auteur, département, année, catégorie — et laissez-la désactivée pour les champs administratifs comme un identifiant interne, une date d’upload ou un statut de validation, qui n’ajouteraient que du bruit.

Trois schémas éprouvés

Les métadonnées utiles ne s’inventent pas dans l’abstrait : elles découlent des questions posées à la base. Une base documentaire technique s’organise autour du produit et de la version, la première question d’un utilisateur étant presque toujours « sur quelle version ? » :

{
  "fields": {
    "product": "Grok API",
    "version": "v1",
    "type": "reference",
    "language": "fr"
  }
}

Une base de connaissances RH raisonne en revanche par catégorie et par date d’entrée en vigueur, car la mauvaise réponse y est le plus souvent une politique abrogée :

{
  "fields": {
    "category": "politique-rh",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Une base juridique se structure enfin autour des parties, du type de contrat et de l’échéance, ce qui permet de sortir en une requête les accords arrivant à expiration :

{
  "fields": {
    "contract_type": "fournisseur",
    "party": "Acme Corp",
    "expiration": "2027-06-30",
    "jurisdiction": "france"
  }
}

Garder un schéma cohérent

La cohérence se perd toujours par les mêmes chemins, et quelques habitudes suffisent à l’entretenir. Standardisez la forme des noms de champs — snake_case, en anglais ou en français, mais sans mélange. Limitez leur nombre : cinq à dix champs couvrent la majorité des besoins, au-delà la maintenance coûte plus que le gain de pertinence. Maniez inject_into_chunk avec discernement, car chaque champ injecté grossit les chunks et donc le coût de stockage. Documentez enfin le schéma attendu par chaque collection dans un fichier accessible à l’équipe : dès que plusieurs personnes l’alimentent, c’est lui, et non la mémoire de son créateur, qui garantit la cohérence.

Points clés à retenir

• Les fields associent des métadonnées clé-valeur à chaque document
• Les field_definitions au niveau collection définissent les règles : required, unique, inject_into_chunk
• L’option inject_into_chunk améliore la pertinence des recherches en ajoutant la métadonnée au contenu indexé
• Standardisez vos schémas de métadonnées pour maintenir la cohérence de vos collections