Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Metadaten und benutzerdefinierte Felder

Lektion 7 von 16 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Der Kontext, den das Dokument nicht trägt
  2. Felder an ein Dokument anhängen
  3. Regeln auf Sammlungsebene festlegen
  4. Die Option, die die Relevanz verändert
  5. Drei bewährte Schemata
  6. Ein konsistentes Schema wahren
  7. Kernaussagen

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:

EinstellungWirkung
required: trueJedes Dokument muss dieses Metadatum tragen
unique: trueZwei Dokumente können denselben Wert nicht teilen
inject_into_chunk: trueDas 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

  • fields verknüpft Schlüssel-Wert-Metadaten mit jedem Dokument
  • field_definitions auf Sammlungsebene definieren Regeln: required, unique, inject_into_chunk
  • Die Option inject_into_chunk verbessert die Suchrelevanz, indem sie Metadaten dem indizierten Inhalt hinzufügt
  • Standardisieren Sie Ihre Metadaten-Schemata, um die Konsistenz der Sammlung zu gewährleisten