Dateisuche: Dokumente indizieren und abfragen

Die Dateisuche ermöglicht es dem Modell, durch Ihre privaten Dokumente zu blättern. Sie laden Dateien in einen Vektorspeicher hoch, und das Modell fragt diese automatisch ab, sobald es spezifische Informationen benötigt. Dies ist das Fundament von RAG, das direkt in die OpenAI API integriert ist.

Vektorspeicher erstellen

Der Vektorspeicher ist die organisatorische Einheit für die Dateisuche. Die hier gewählte Struktur bleibt für eine lange Zeit bestehen. Ein einzelner Speicher für das gesamte Unternehmen ist einfach zu verwalten, mischt jedoch Dokumente mit unzusammenhängenden Vokabularen, was die Relevanz verschlechtert. Getrennte Speicher nach Team oder Domäne erfordern etwas mehr Verwaltung, machen aber jede Suche deutlich präziser. Zweifellos getrennt halten: Eine spätere Zusammenführung ist einfacher als das Entwirren eines Chaos.

from openai import OpenAI

client = OpenAI()

# Vektorspeicher erstellen
vector_store = client.vector_stores.create(
    name="produkt-dokumentation"
)
print(f"Vektorspeicher erstellt: {vector_store.id}")

Dateien hochladen und indizieren

Das Indizieren ist asynchron, und dies ist die häufigste Fehlerquelle beim ersten Versuch: Sie fügen Dateien hinzu, fragen sofort ab, und das Modell sagt, es habe nichts gefunden – nicht weil die Suche fehlgeschlagen ist, sondern weil noch nichts indiziert wurde. Prüfen Sie immer den Status, bevor Sie abfragen, wie im Abschnitt zum Lebenszyklus gezeigt.

Ein Wort zu Formaten: Die Liste ist breit, aber nicht alle Dateien sind gleichwertig. Eine PDF-Datei, die aus einem Textverarbeitungsprogramm generiert wurde, wird sauber extrahiert; ein gescanntes PDF ohne Textschicht bringt nichts hinzu, da es buchstäblich keine Wörter zum Indizieren gibt.

import os

# Eine einzelne Datei hochladen
with open("benutzerhandbuch.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

# An den Vektorspeicher anhängen
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id
)

# Batch-Upload
ordner = "./dokumentation/"
for dateiname in os.listdir(ordner):
    pfad = os.path.join(ordner, dateiname)
    if os.path.isfile(pfad):
        with open(pfad, "rb") as f:
            file_obj = client.files.create(file=f, purpose="assistants")
        client.vector_stores.files.create(
            vector_store_id=vector_store.id,
            file_id=file_obj.id
        )
        print(f"Indiziert: {dateiname}")

Abfragen mit Dateisuche

Der Aufruf ist absichtlich einfach gehalten: Sie deklarieren das Tool, stellen Ihre Frage, und das Modell entscheidet, ob es suchen soll. Alle RAG-Arbeiten – Chunking, Vektorisierung, Ranking und Einbettung in den Kontext – finden auf dem Server statt. Dies spart erhebliche Zeit beim Starten, und die nächste Lektion behandelt die Einstellungen, die Sie kennen müssen, wenn die Standards nicht ausreichen.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Was ist das Rückerstattungsverfahren für Premium-Kunden?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

print(response.output_text)

Das Modell durchsucht automatisch Ihre Dokumente und formuliert eine Antwort basierend auf dem gefundenen Inhalt.

Suchergebnisse prüfen

Annotationen sind das, was eine überprüfbare Antwort von einer bloßen Behauptung unterscheidet. Stellen Sie diese Ihren Nutzern zur Verfügung: Die Fähigkeit, auf einer internen Wissensdatenbank zurück zu den ursprünglichen Dokumenten zu verfolgen, verändert das Vertrauensniveau im System vollständig – und hilft Ihnen, Fälle zu erkennen, in denen das Modell den Nagel auf den Kopf getroffen hat.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Welche SLAs sind im Vertrag garantiert?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

# Annotationen durchlaufen
for item in response.output:
    if item.type == "message":
        for block in item.content:
            if hasattr(block, "annotations"):
                for ann in block.annotations:
                    if ann.type == "file_citation":
                        print(f"Datei: {ann.file_id}")
                        print(f"Position: {ann.start_index}-{ann.end_index}")

Suche konfigurieren

Anzahl der Ergebnisse

Das Erhöhen der Anzahl der Passagen verbessert die Antwort nicht mechanisch. Jenseits von etwa zehn verwässern schwach relevante Auszüge die guten und verbrauchen den abgerechneten Kontext. Erhöhen Sie diesen Wert nur, wenn die Antwort offensichtlich unvollständig ist, nicht als Prinzip.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Listen Sie alle Vertragsstrafenklauseln im Vertrag auf",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 20  # Standard: 5, Maximum: 50
    }]
)

Metadaten-Filterung

Metadaten sind der am wenigsten genutzte Hebel für Präzision. Das Filtern nach Jahr, Abteilung oder Dokumenttyp vor der Vektorsuche eliminiert Rauschen, das sonst vom Ranking herausgefiltert werden müsste. Dies ermöglicht es Ihnen auch, nach „laut dem aktuellen Verfahren” zu antworten, anstatt drei aufeinanderfolgende Versionen desselben Dokuments zu vermischen.

# Hochladen mit Metadaten
with open("vertrag-2026.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id,
    attributes={
        "doc_type": "vertrag",
        "year": 2026,
        "client": "acme-corp"
    }
)

# Gefilterte Suche
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Was ist der Fälligkeitsdatum?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "eq",
            "key": "doc_type",
            "value": "vertrag"
        }
    }]
)

Komposite Filter

Kombinieren Sie mehrere Kriterien mit logischen Operatoren:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Fassen Sie die vertraglichen Verpflichtungen für 2026 zusammen",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "and",
            "filters": [
                {"type": "eq", "key": "doc_type", "value": "vertrag"},
                {"type": "gte", "key": "year", "value": 2026}
            ]
        }
    }]
)

Lebenszyklus des Vektorspeichers verwalten

Indizierungsstatus überwachen

# Vektorspeicher-Status prüfen
vs = client.vector_stores.retrieve(vector_store.id)
print(f"Status: {vs.status}")
print(f"Dateien: {vs.file_counts.completed} indiziert, "
      f"{vs.file_counts.in_progress} in Bearbeitung, "
      f"{vs.file_counts.failed} fehlgeschlagen")

Veraltete Dateien entfernen

# Dateien im Vektorspeicher auflisten
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
    print(f"{f.id} - {f.status}")

# Datei lösen
client.vector_stores.files.delete(
    vector_store_id=vector_store.id,
    file_id="file_abc123"
)

Komplettes Beispiel: Dokumentations-Assistent

def dokumentations_assistenten(frage: str, vs_id: str) -> dict:
    """Assistent, der basierend auf interner Dokumentation antwortet."""
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=(
            "Sie sind ein Dokumentationsassistent. Beantworten Sie ausschließlich "
            "aufgrund der bereitgestellten Dokumente. Wenn die Informationen nicht "
            "in den Dokumenten enthalten sind, stellen Sie dies klar dar. "
            "Nennen Sie Ihre Quellen."
        ),
        input=frage,
        tools=[{
            "type": "file_search",
            "vector_store_ids": [vs_id],
            "max_num_results": 10
        }]
    )

    return {
        "answer": response.output_text,
        "model": response.model,
        "tokens": response.usage.total_tokens
    }

Kernaussagen

Erstellen Sie einen Vektorspeicher und laden Sie Ihre Dateien hoch, um die Dateisuche zu ermöglichen
Das Modell entscheidet eigenständig, wann es Dokumente durchsuchen soll
max_num_results steuert die Suchtiefe
Metadaten und Filter ermöglichen eine gezielte Suche
Überwachen Sie den Indizierungsstatus, bevor Sie abfragen