Metadata och anpassade fält
På denna sida
Kontext som dokumentet inte bär på
En teknisk rapport innehåller inte alltid författarens namn, året den skrevs eller dess konfidentialitetsnivå i brödtexten. Ändå är det dessa detaljer som avgör skillnaden mellan en sökning som hittar rätt dokument och en som returnerar tre irrelevanta träffar. Systemet för samlingsmetadata tjänar exakt detta syfte: att koppla strukturerad information till varje dokument som sökningen kan utnyttja och som du kan filtrera efter.
Att koppla fält till ett dokument
När du lägger till ett dokument accepterar parametern fields nyckel-värde-par som du definierar fritt:
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"
}
)
Inget schema tillämpas på denna nivå: du väljer själv fältnamnen. Denna frihet känns bekväm för det första dokumentet men blir ett problem vid det hundrade, när author, auteur och Author samexisterar i samma samling utan att något filter fungerar.
Att fastställa regler på samlingsnivå
Här kommer field_definitions in i bilden, deklarerade på samlingen. De omvandlar en muntlig överenskommelse till en begränsning som verifieras av API:t. Tre inställningar finns tillgängliga:
| Inställning | Effekt |
|---|---|
required: true | Varje dokument måste innehålla denna metadata |
unique: true | Två dokument kan inte dela samma värde |
inject_into_chunk: true | Metadatan läggs till i det indexerade innehållet |
En definition kombinerar dessa inställningar fält för fält:
{
"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äs detta exempel som en dokumentpolicy: varje dokument har en författare och ett ID, det ID:t tillhör endast ett dokument – vilket blockerar dubbletter vid inmatning – och året förblir valfritt för att undvika att odaterade objekt avvisas.
Alternativet som ändrar relevansen
Av dessa tre inställningar är inject_into_chunk den enda som påverkar svarskvaliteten, och den förtjänar en närmare titt. Under indexering delas ett dokument upp i fragment – chunkar – och att aktivera detta alternativ kopierar fältvärdet till vart och ett av dem.
Konkret innebär det att med author: "Marie Dupont" och inject_into_chunk: true bär varje indexerad chunk detta namn. En fråga som “Vad skrev Marie Dupont om nätverkslatens?” har då en chans att träffa rätt, eftersom namnet förekommer i det sökta innehållet. Utan injektion förlitar sig samma fråga endast på rapporttexten, där författaren kanske bara förekommer på omslaget.
Aktivera alltså injektion för fält som bär kontext – författare, avdelning, år, kategori – och låt det vara inaktiverat för administrativa fält som ett internt ID, uppladdningsdatum eller valideringsstatus, vilket endast skulle lägga till brus.
Tre beprövade scheman
Användbar metadata hittas inte på abstrakt nivå: den härrör från de frågor som ställs till databasen. En bas för teknisk dokumentation organiseras kring produkt och version, eftersom en användares första fråga nästan alltid är “vilken version?”:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
En kunskapsbas för HR resonerar dock utifrån kategori och ikraftträdandedatum, eftersom felaktiga svar där oftast handlar om upphävda policyer:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Slutligen struktureras en juridisk bas kring parter, avtalstyp och utgångsdatum, vilket låter dig hämta avtal som närmar sig utgång i en enda fråga:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Att behålla ett konsekvent schema
Konsekvens går alltid förlorad via samma kanaler, och några få vanor räcker för att upprätthålla den. Standardisera formatet för fältnamn – snake_case, på engelska, utan att blanda språk. Begränsa antalet: fem till tio fält täcker de flesta behov; utöver det överstiger underhållskostnaderna vinsterna i relevans. Hantera inject_into_chunk med omdöme, eftersom varje injicerat fält ökar storleken på chunkarna och därmed lagringskostnaderna. Dokumentera slutligen det förväntade schemat för varje samling i en fil som är tillgänglig för teamet: när flera personer matar in data är det den filen, inte skaparens minne, som garanterar konsekvens.
Viktiga punkter
fieldskopplar nyckel-värde-metadata till varje dokumentfield_definitionspå samlingsnivå definierar regler: required, unique, inject_into_chunk- Alternativet
inject_into_chunkförbättrar sökresultatens relevans genom att lägga till metadata i det indexerade innehållet - Standardisera dina metadatascheman för att upprätthålla konsekvens i samlingen