Metagegevens en aangepaste velden
Op deze pagina
Context die het document niet bevat
Een technisch rapport bevat niet altijd de naam van de auteur, het jaar van opstellen of het vertrouwelijkheidsniveau in de lopende tekst. Toch maken deze details het verschil tussen een zoekopdracht die het juiste document vindt en een die drie irrelevante resultaten retourneert. Het metagegevenssysteem voor collecties dient precies dit doel: het koppelen van gestructureerde informatie aan elk document, zodat de zoekfunctie deze kan benutten en u erop kunt filteren.
Velden aan een document koppelen
Bij het toevoegen van een document accepteert de parameter fields sleutel-waardeparen die u vrij kunt definiëren:
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"
}
)
Op dit niveau wordt geen schema afgedwongen: u kiest zelf de veldnamen. Deze vrijheid voelt comfortabel bij het eerste document, maar wordt bij het honderdste een probleem wanneer author, auteur en Author naast elkaar bestaan in dezelfde collectie zonder dat filters werken.
Regels op collectieniveau instellen
Hier komen field_definitions om de hoek kijken, gedeclareerd op de collectie. Ze zetten een mondelinge afspraak om in een door de API gecontroleerde beperking. Er zijn drie instellingen mogelijk:
| Instelling | Effect |
|---|---|
required: true | Elk document moet deze metagegevens bevatten |
unique: true | Twee documenten kunnen niet dezelfde waarde delen |
inject_into_chunk: true | De metagegevens worden toegevoegd aan de geïndexeerde inhoud |
Een definitie combineert deze instellingen per veld:
{
"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
}
]
}
Lees dit voorbeeld als een documentbeleid: elk document heeft een auteur en een ID, die ID behoort toe aan slechts één document—wat duplicaten bij ingestie blokkeert—en het jaar blijft optioneel om te voorkomen dat items zonder datum worden geweigerd.
De optie die relevantie verandert
Van deze drie instellingen is inject_into_chunk de enige die de kwaliteit van het antwoord beïnvloedt, en deze verdient een nadere blik. Tijdens het indexeren wordt een document opgesplitst in fragmenten—chunks—en het inschakelen van deze optie kopieert de veldwaarde naar elk daarvan.
Concreet betekent dit dat bij author: "Marie Dupont" en inject_into_chunk: true, elke geïndexeerde chunk deze naam bevat. Een vraag als “Wat heeft Marie Dupont geschreven over netwerklatentie?” maakt dan kans om raak te schieten, omdat de naam voorkomt in de doorzochte inhoud. Zonder injectie vertrouwt dezelfde vraag alleen op de tekst van het rapport, waar de auteur misschien alleen op de voorpagina staat.
Schakel injectie dus in voor velden die context dragen—auteur, afdeling, jaar, categorie—en laat het uitgeschakeld voor administratieve velden zoals een intern ID, uploaddatum of validatiestatus, die alleen ruis zouden toevoegen.
Drie bewezen schema’s
Nuttige metagegevens worden niet in het abstract bedacht: ze vloeien voort uit de vragen die aan de database worden gesteld. Een technische documentatiebase organiseert zich rond product en versie, omdat de eerste vraag van een gebruiker bijna altijd “welke versie?” is:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Een HR-kennisbase redeneert daarentegen per categorie en ingangsdatum, omdat het verkeerde antwoord daar vaak een ingetrokken beleid is:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Tot slot structureert een juridische base zich rond partijen, contracttype en vervaldatum, waardoor u overeenkomsten die bijna verlopen in één query kunt ophalen:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Een consistent schema behouden
Consistentie gaat altijd via dezelfde kanalen verloren, en een paar gewoonten volstaan om deze te behouden. Standaardiseer de formaten van veldnamen—snake_case, in het Engels, zonder talen te mengen. Beperk het aantal: vijf tot tien velden dekken de meeste behoeften; daarboven wegen de onderhoudskosten zwaarder dan de winst in relevantie. Ga verstandig om met inject_into_chunk, aangezien elk geïnjecteerd veld de chunks vergroot en daarmee de opslagkosten. Documenteer ten slotte het verwachte schema voor elke collectie in een bestand dat toegankelijk is voor het team: zodra meerdere personen het voeden, garandeert dat bestand, en niet het geheugen van de maker, de consistentie.
Belangrijkste punten
fieldskoppelt sleutel-waarde-metagegevens aan elk documentfield_definitionsop collectieniveau definiëren regels: required, unique, inject_into_chunk- De optie
inject_into_chunkverbetert de zoekrelevantie door metagegevens aan de geïndexeerde inhoud toe te voegen - Standaardiseer uw metagegevensschema’s om de consistentie van de collectie te behouden