Metadaten und benutzerdefinierte Felder
Auf dieser Seite
Der Kontext, den das Dokument nicht trägt
Ein technischer Bericht enthält nicht immer im Fließtext den Namen des Autors, das Jahr der Erstellung oder das Vertraulichkeitsniveau. Diese Details machen jedoch den Unterschied zwischen einer Suche, die das richtige Dokument findet, und einer, die drei irrelevante Ergebnisse zurückgibt. Das Metadaten-System für Sammlungen erfüllt genau diesen Zweck: Es verknüpft strukturierte Informationen mit jedem Dokument, die die Suche ausnutzen und Sie nach Filtern durchsuchen können.
Felder an ein Dokument anhängen
Beim Hinzufügen eines Dokuments akzeptiert der Parameter fields Schlüssel-Wert-Paare, die Sie frei definieren:
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"
}
)
Auf dieser Ebene wird kein Schema durchgesetzt: Die Feldnamen sind Ihre Wahl. Diese Freiheit fühlt sich beim ersten Dokument komfortabel an, wird aber zum Problem beim hundertsten, wenn author, auteur und Author in derselben Sammlung koexistieren, ohne dass ein Filter funktioniert.
Regeln auf Sammlungsebene festlegen
Hier kommen die field_definitions ins Spiel, die auf der Sammlung deklariert werden. Sie verwandeln eine mündliche Vereinbarung in eine Einschränkung, die von der API überprüft wird. Es gibt drei Einstellungen:
| Einstellung | Wirkung |
|---|---|
required: true | Jedes Dokument muss dieses Metadatum tragen |
unique: true | Zwei Dokumente können denselben Wert nicht teilen |
inject_into_chunk: true | Das Metadatum wird dem indizierten Inhalt hinzugefügt |
Eine Definition kombiniert diese Einstellungen Feld für Feld:
{
"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
}
]
}
Lesen Sie dieses Beispiel als Dokumentenrichtlinie: Jedes Dokument hat einen Autor und eine ID; diese ID gehört nur einem einzigen Dokument – was Duplikate bei der Aufnahme blockiert – und das Jahr bleibt optional, um die Ablehnung von nicht datierten Artikeln zu vermeiden.
Die Option, die die Relevanz verändert
Von diesen drei Einstellungen ist nur inject_into_chunk diejenige, die die Antwortqualität beeinflusst, und sie verdient eine nähere Betrachtung. Während der Indizierung wird ein Dokument in Fragmente – Chunks – aufgeteilt. Wenn Sie diese Option aktivieren, wird der Feldwert in jedes einzelne kopiert.
Konkret führt author: "Marie Dupont" mit inject_into_chunk: true dazu, dass jeder indizierte Chunk diesen Namen trägt. Eine Frage wie „Was hat Marie Dupont über Netzwerklatenz geschrieben?” hat dann eine Chance, ins Schwarze zu treffen, da der Name im durchsuchten Inhalt erscheint. Ohne Injektion stützt sich dieselbe Frage nur auf den Berichtstext, in dem der Autor möglicherweise nur auf der Titelseite erwähnt wird.
Aktivieren Sie daher die Injektion für kontextbehaftete Felder – Autor, Abteilung, Jahr, Kategorie – und lassen Sie sie für administrative Felder wie eine interne ID, das Upload-Datum oder den Validierungsstatus deaktiviert, da diese nur Rauschen hinzufügen würden.
Drei bewährte Schemata
Nützliche Metadaten werden nicht im Abstrakten erfunden: Sie stammen aus den Fragen, die an die Datenbank gestellt werden. Eine technische Dokumentationsbasis organisiert sich um Produkt und Version, da die erste Frage eines Nutzers fast immer „welche Version?” lautet:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Eine HR-Wissensbasis hingegen schließt nach Kategorie und Gültigkeitsdatum ab, da die falsche Antwort dort am häufigsten eine aufgehobene Richtlinie ist:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Schließlich strukturiert eine Rechtsbasis nach Parteien, Vertragstyp und Ablaufdatum, sodass Sie Vereinbarungen, die bald ablaufen, in einer einzigen Abfrage abrufen können:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Ein konsistentes Schema wahren
Konsistenz geht immer über dieselben Kanäle verloren, und einige Gewohnheiten genügen, um sie zu erhalten. Standardisieren Sie die Formatierung der Feldnamen – snake_case, auf Englisch, ohne Mischungen von Sprachen. Begrenzen Sie deren Anzahl: Fünf bis zehn Felder decken die meisten Bedürfnisse ab; darüber hinaus wiegen die Wartungskosten schwerer als die Relevanzgewinne. Behandeln Sie inject_into_chunk mit Urteilsvermögen, da jedes injizierte Feld die Chunks vergrößert und somit die Speicherkosten erhöht. Dokumentieren Sie schließlich das erwartete Schema für jede Sammlung in einer Datei, die für das Team zugänglich ist: Sobald mehrere Personen Daten hineingeben, garantiert diese Datei, nicht das Gedächtnis des Erstellers, die Konsistenz.
Kernaussagen
fieldsverknüpft Schlüssel-Wert-Metadaten mit jedem Dokumentfield_definitionsauf Sammlungsebene definieren Regeln: required, unique, inject_into_chunk- Die Option
inject_into_chunkverbessert die Suchrelevanz, indem sie Metadaten dem indizierten Inhalt hinzufügt - Standardisieren Sie Ihre Metadaten-Schemata, um die Konsistenz der Sammlung zu gewährleisten