Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Datenabruf

Durchsuche deine Daten anhand semantischer Ähnlichkeit.

Mit der Retrieval API kannst du deine Daten per semantischer Suche durchsuchen. Das Verfahren findet inhaltlich ähnliche Ergebnisse, auch wenn sie nur wenige oder gar keine Schlüsselwörter mit der Suchanfrage gemeinsam haben. Der Datenabruf ist schon für sich genommen nützlich. Besonders hilfreich ist er in Kombination mit unseren Modellen, die aus den Ergebnissen Antworten formulieren können.

Darstellung des Datenabrufs

Die Retrieval API verwendet Vektorspeicher als Indizes für deine Daten. In diesem Leitfaden erfährst du, wie du eine semantische Suche durchführst und wie Vektorspeicher funktionieren.

Schnellstart

  • Erstelle einen Vektorspeicher und lade Dateien hoch.

  • Vektorspeicher mit Dateien erstellen
    from openai import OpenAI
    
    client = OpenAI()
    
    vector_store = client.vector_stores.create(        # Create vector store
        name="Support FAQ",
    )
    
    client.vector_stores.files.upload_and_poll(        # Upload file
        vector_store_id=vector_store.id,
        file=open("customer_policies.txt", "rb")
    )
  • Sende eine Suchanfrage, um relevante Ergebnisse zu erhalten.

  • Suchanfrage
    user_query = "What is the return policy?"
    
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query=user_query,
    )

    Wie du die Ergebnisse mit unseren Modellen verwendest, erfährst du im Abschnitt Antworten aus Suchergebnissen generieren.

    Semantische Suche

    Die semantische Suche nutzt Vektor-Embeddings, um inhaltlich relevante Ergebnisse zu finden. Dazu gehören auch Treffer, die nur wenige oder gar keine Schlüsselwörter mit der Suchanfrage gemeinsam haben und die klassische Suchverfahren deshalb übersehen können.

    Die folgende Tabelle zeigt mögliche Ergebnisse für die Suchanfrage "When did we go to the moon?".

    Text Übereinstimmung der Schlüsselwörter Semantische Ähnlichkeit
    The first lunar landing occurred in July of 1969. 0 % 65 %
    The first man on the moon was Neil Armstrong. 27 % 43 %
    When I ate the moon cake, it was delicious. 40 % 28 %

    (Die Übereinstimmung der Schlüsselwörter wird mit dem Jaccard-Index berechnet, die semantische Ähnlichkeit mit der Kosinus-Ähnlichkeit auf Basis von text-embedding-3-small.)

    Das relevanteste Ergebnis erreicht bei der Übereinstimmung der Schlüsselwörter 0 %. Dank dieser Flexibilität eignet sich die semantische Suche für Wissensdatenbanken jeder Größe.

    Die semantische Suche basiert auf Vektorspeichern, auf die wir später genauer eingehen. In diesem Abschnitt erfährst du, wie die Suche funktioniert.

    Semantische Suche durchführen

    Mit der Funktion search kannst du einen Vektorspeicher durchsuchen. Gib dazu als query eine Suchanfrage in natürlicher Sprache an. Du erhältst eine Ergebnisliste. Jeder Treffer enthält die relevanten Textabschnitte (Chunks), die Ähnlichkeitswerte und die zugehörige Quelldatei.

    Suchanfrage
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query="How many woodchucks are allowed per passenger?",
    )
    Ergebnisse
    {
      "object": "vector_store.search_results.page",
      "search_query": "How many woodchucks are allowed per passenger?",
      "data": [
        {
          "file_id": "file-12345",
          "filename": "woodchuck_policy.txt",
          "score": 0.85,
          "attributes": {
            "region": "North America",
            "author": "Wildlife Department"
          },
          "content": [
            {
              "type": "text",
              "text": "According to the latest regulations, each passenger is allowed to carry up to two woodchucks."
            },
            {
              "type": "text",
              "text": "Ensure that the woodchucks are properly contained during transport."
            }
          ]
        },
        {
          "file_id": "file-67890",
          "filename": "transport_guidelines.txt",
          "score": 0.75,
          "attributes": {
            "region": "North America",
            "author": "Transport Authority"
          },
          "content": [
            {
              "type": "text",
              "text": "Passengers must adhere to the guidelines set forth by the Transport Authority regarding the transport of woodchucks."
            }
          ]
        }
      ],
      "has_more": false,
      "next_page": null
    }

    Standardmäßig enthält eine Antwort höchstens 10 Ergebnisse. Mit dem Parameter max_num_results kannst du die Obergrenze auf bis zu 50 erhöhen.

    Suchanfragen umformulieren

    Manche Formulierungen liefern bessere Suchergebnisse als andere. Deshalb kannst du deine Suchanfragen automatisch umformulieren lassen, um möglichst gute Ergebnisse zu erhalten. Setze dazu rewrite_query=true, wenn du search aufrufst.

    Die umformulierte Suchanfrage findest du im Feld search_query des Ergebnisses.

    Ursprüngliche Anfrage Umformulierte Anfrage
    Ich möchte wissen, wie hoch das Hauptbürogebäude ist. Höhe Hauptbürogebäude
    Welche Sicherheitsvorschriften gelten für den Transport von Gefahrgut? Sicherheitsvorschriften für Gefahrgut
    Wie reiche ich eine Beschwerde über ein Problem mit einer Dienstleistung ein? Verfahren für Beschwerden über Dienstleistungen

    Nach Attributen filtern

    Mit Attributfiltern kannst du die Ergebnisse anhand von Kriterien eingrenzen und die Suche beispielsweise auf einen bestimmten Zeitraum beschränken. In filters kannst du Kriterien definieren und kombinieren. So legst du vor der semantischen Suche anhand der Dateiattribute fest, welche Dateien durchsucht werden.

    Mit Vergleichsfiltern vergleichst du den Wert eines bestimmten Schlüssels (key) in den attributes einer Datei mit einem vorgegebenen value. Mit zusammengesetzten Filtern verknüpfst du mehrere Filter über and und or.

    Vergleichsfilter
    {
      "type": "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin",  // comparison operators
      "key": "attributes_key",                           // attributes key
      "value": "target_value"                             // value to compare against
    }
    Zusammengesetzter Filter
    {
      "type": "and" | "or",                                // logical operators
      "filters": [...]
    }

    Hier findest du einige Beispielfilter.

    Die Beispiele für Dateinamen filtern nach einem benutzerdefinierten Attribut namens filename. Dieses Attribut musst du für jede Datei im Vektorspeicher ausdrücklich setzen, etwa mit {"filename": "example.txt"}. Die Filter greifen nicht automatisch auf den Namen der hochgeladenen Datei zu.

    Nach Region filtern
    {
      "type": "eq",
      "key": "region",
      "value": "us"
    }

    Rangfolge der Ergebnisse

    Wenn die Treffer der Dateisuche nur bedingt zur Anfrage passen, kannst du mit ranking_options die Qualität der Antworten verbessern. Wähle dazu einen ranker wie auto oder default-2024-08-21 und setze score_threshold auf einen Wert zwischen 0,0 und 1,0. Ein höherer Wert für score_threshold beschränkt die Ergebnisse auf relevantere Chunks, kann aber auch potenziell nützliche Treffer ausschließen. Wenn du ranking_options.hybrid_search angibst, kannst du außerdem hybrid_search.embedding_weight (rrf_embedding_weight) und hybrid_search.text_weight (rrf_text_weight) anpassen. Damit steuerst du, wie stark die Reciprocal Rank Fusion beim Zusammenführen der Ranglisten semantische Treffer aus dem Embedding-Vergleich und Treffer aus der Schlüsselwortsuche mit dünn besetzten Vektoren gewichtet. Erhöhe das erste Gewicht, um semantische Ähnlichkeit stärker zu berücksichtigen, oder das zweite, um übereinstimmende Wörter stärker zu gewichten. Mindestens eines der beiden Gewichte muss größer als null sein.

    Vektorspeicher

    Vektorspeicher sind Container, die der Retrieval API und dem Tool für die Dateisuche als Grundlage für die semantische Suche dienen. Wenn du eine Datei zu einem Vektorspeicher hinzufügst, zerlegt die API sie automatisch in Chunks, erstellt daraus Embeddings und indexiert die Inhalte.

    Vektorspeicher enthalten Objekte vom Typ vector_store_file, denen jeweils ein file-Objekt zugrunde liegt.

    Objekttyp
    Beschreibung
    file Steht für Inhalte, die du über die Files API hochgeladen hast. Dieser Typ kommt häufig in Vektorspeichern zum Einsatz, aber auch beim Fine-Tuning und in anderen Anwendungsfällen.
    vector_store Container für durchsuchbare Dateien.
    vector_store.file Wrapper für ein file-Objekt, dessen Inhalt in Chunks zerlegt und in Embeddings umgewandelt wurde und das einem vector_store zugeordnet ist.
    Enthält in attributes die Schlüssel-Wert-Paare für die Filterung.

    Preise

    Die Kosten richten sich nach dem insgesamt belegten Speicherplatz in all deinen Vektorspeichern. Maßgeblich ist die Größe der beim Einlesen erzeugten Chunks und ihrer Embeddings.

    Speicherplatz Kosten
    Bis zu 1 GB (über alle Vektorspeicher hinweg) Kostenlos
    Über 1 GB 0,10 USD pro GB und Tag

    Im Abschnitt zu Ablaufrichtlinien erfährst du, wie du die Kosten möglichst gering hältst.

    Vektorspeicher verwalten

    Vektorspeicher erstellen
    client.vector_stores.create(
        name="Support FAQ",
        file_ids=["file_123"]
    )

    Dateien im Vektorspeicher verwalten

    Einige Vorgänge, etwa create für vector_store.file, laufen asynchron und können eine Weile dauern. Mit Hilfsfunktionen wie create_and_poll kannst du warten, bis der Vorgang abgeschlossen ist. Alternativ kannst du den Status abfragen. Beim Entfernen einer Datei aus einem Vektorspeicher wird der Suchindex mit einer Verzögerung aktualisiert. Daher können die Suchergebnisse kurzzeitig noch Inhalte aus der entfernten Datei enthalten.

    Für das Hinzufügen von Dateien gilt ein Ratenlimit pro Vektorspeicher-ID. Für Anfragen an /vector_stores/{vector_store_id}/files und /vector_stores/{vector_store_id}/file_batches sind pro Vektorspeicher insgesamt höchstens 300 Anfragen pro Minute zulässig.

    Datei im Vektorspeicher erstellen
    client.vector_stores.files.create_and_poll(
        vector_store_id="vs_123",
        file_id="file_123"
    )

    Dateien im Batch verarbeiten

    Batch erstellen
    client.vector_stores.file_batches.create_and_poll(
        vector_store_id="vs_123",
        files=[
            {
                "file_id": "file_123",
                "attributes": {"department": "finance"}
            },
            {
                "file_id": "file_456",
                "chunking_strategy": {
                    "type": "static",
                    "static": {
                        "max_chunk_size_tokens": 1200,
                        "chunk_overlap_tokens": 200
                    }
                }
            }
        ]
    )

    Beim Erstellen eines Batches kannst du file_ids angeben und bei Bedarf attributes, eine chunking_strategy oder beides ergänzen. Alternativ kannst du im Array files für jede Datei ein Objekt mit einer file_id übergeben und optional attributes und chunking_strategy festlegen. Die beiden Varianten schließen sich gegenseitig aus. Wähle die erste, wenn alle Dateien dieselben Einstellungen verwenden sollen, und die zweite, wenn du Einstellungen für einzelne Dateien überschreiben möchtest.

    Für einen höheren Durchsatz beim Einlesen von Dateien in einen einzelnen Vektorspeicher empfehlen wir, nach Möglichkeit Batches zu erstellen. Mit einem Batch kannst du bis zu 500 Dateien in einer Anfrage hinzufügen. Im Vergleich zu vielen Einzelanfragen konkurrieren dabei in der Regel weniger Anfragen um dieselben Ressourcen, und die Gesamtlatenz sinkt.

    Attribute

    Jedem Objekt vom Typ vector_store.file kannst du über attributes ein Wörterbuch mit Werten zuordnen. Auf diese Werte kannst du bei der semantischen Suche mit Attributfiltern zugreifen. Das Wörterbuch darf höchstens 16 Schlüssel enthalten. Jeder Schlüssel darf bis zu 64 Zeichen lang sein. Für Werte vom Typ String liegt die Obergrenze bei jeweils 512 Zeichen.

    Datei mit Attributen im Vektorspeicher erstellen
    client.vector_stores.files.create(
        vector_store_id="<vector_store_id>",
        file_id="file_123",
        attributes={
            "region": "US",
            "category": "Marketing",
            "date": 1672531200      # Jan 1, 2023
        }
    )

    Ablaufrichtlinien

    Für Objekte vom Typ vector_store kannst du mit expires_after eine Ablaufrichtlinie festlegen. Sobald ein Vektorspeicher abläuft, löscht die API alle zugehörigen Objekte vom Typ vector_store.file. Für diese Objekte fallen dann keine weiteren Kosten an.

    Ablaufrichtlinie für einen Vektorspeicher festlegen
    client.vector_stores.update(
        vector_store_id="vs_123",
        expires_after={
            "anchor": "last_active_at",
            "days": 7
        }
    )

    Größenbeschränkungen

    Eine Datei darf höchstens 512 MB groß sein und sollte maximal 5.000.000 Token enthalten. Die API berechnet die Tokenanzahl automatisch, wenn du die Datei hinzufügst.

    Dateien in Chunks aufteilen

    Standardmäßig hat max_chunk_size_tokens den Wert 800 und chunk_overlap_tokens den Wert 400. Für die Indexierung wird jede Datei in Chunks von 800 Token aufgeteilt. Aufeinanderfolgende Chunks überlappen sich um 400 Token.

    Du kannst die Aufteilung mit chunking_strategy anpassen, wenn du Dateien zum Vektorspeicher hinzufügst. Dabei gelten folgende Grenzen.

    • max_chunk_size_tokens muss zwischen 100 und 4.096 liegen, einschließlich beider Grenzwerte.
    • chunk_overlap_tokens muss mindestens null sein und sollte max_chunk_size_tokens / 2 nicht überschreiten.

    Antworten aus Suchergebnissen generieren

    Nach einer Suche kannst du aus den Ergebnissen eine Antwort generieren lassen. Übergib dazu die Suchergebnisse zusammen mit der ursprünglichen Anfrage an eines unserer Modelle. So erhältst du eine Antwort, die sich auf die gefundenen Inhalte stützt.

    Suchanfrage ausführen und Ergebnisse abrufen
    from openai import OpenAI
    
    client = OpenAI()
    
    user_query = "What is the return policy?"
    
    results = client.vector_stores.search(
        vector_store_id=vector_store.id,
        query=user_query,
    )
    Antwort aus den Suchergebnissen generieren
    # Use results and user_query from the preceding search step.
    formatted_results = format_results(results.data)
    
    "\n".join("\n".join(c.text for c in result.content) for result in results.data)
    
    completion = client.chat.completions.create(
        model="gpt-6-astra",
        messages=[
            {
                "role": "developer",
                "content": "Produce a concise answer to the query based on the provided sources.",
            },
            {
                "role": "user",
                "content": f"Sources: {formatted_results}\n\nQuery: '{user_query}'",
            },
        ],
    )
    
    print(completion.choices[0].message.content)
    "Our return policy allows returns within 30 days of purchase."

    Das Beispiel verwendet die Funktion format_results. Der folgende Code zeigt eine mögliche Implementierung.

    Beispielfunktion zum Formatieren der Ergebnisse
    def format_results(results):
        formatted_results = ""
        for result in results.data:
            formatted_result = (
                f"<result file_id='{result.file_id}' file_name='{result.filename}'>"
            )
            for part in result.content:
                formatted_result += f"<content>{part.text}</content>"
            formatted_results += formatted_result + "</result>"
        return f"<sources>{formatted_results}</sources>"