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.
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.
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.
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
Python
1
2
3const results = await client.vectorStores.search(vector_store.id, { query: "How many woodchucks are allowed per passenger?",});
1
2
3
4results = client.vector_stores.search(vector_store_id=vector_store.id,query="How many woodchucks are allowed per passenger?",)
1
2
3
4
5
6
7
8require "openai"client = OpenAI::Client.newresults = client.vector_stores.search( "vs_123", query: "How many woodchucks are allowed per passenger?")puts(results.data&.first&.content)
Ergebnisse
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42{"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
1
2
3
4
5{"type": "eq"|"ne"|"gt"|"gte"|"lt"|"lte"|"in"|"nin", // comparison operators"key": "attributes_key", // attributes key"value": "target_value"// value to compare against}
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.
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.
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.
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.
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
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.
Für MIME-Typen mit dem Präfix text/ muss die Zeichenkodierung utf-8, utf-16 oder ascii sein.
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
Python
1
2
3
4
5
6
7
8
9import OpenAI from "openai";const client = new OpenAI();const userQuery = "What is the return policy?";const results = await client.vectorStores.search(vector_store.id, { query: userQuery,});
1
2
3
4
5
6
7
8require "openai"client = OpenAI::Client.newresults = client.vector_stores.search( "vs_123", query: "What is the return policy?")puts(results.data)
Antwort aus den Suchergebnissen generieren
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22const formattedResults = formatResults(results.data);// Join the text content of all resultsconst textSources = results.data .map((result) => result.content.map((c) => c.text).join("\n")) .join("\n");const completion = await 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: `Sources: ${formattedResults}\n\nQuery: '${userQuery}'`, }, ],});console.log(completion.choices[0].message.content);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20# 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46package mainimport ( "context" "fmt" "strings" "github.com/openai/openai-go/v3")func main() { client := openai.NewClient() userQuery := "What is the return policy?" results, err := client.VectorStores.Search(context.Background(), "vs_123", openai.VectorStoreSearchParams{ Query: openai.VectorStoreSearchParamsQueryUnion{OfString: openai.String(userQuery)}, }) if err != nil { panic(err) } completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{ Model: "gpt-6-astra", Messages: []openai.ChatCompletionMessageParamUnion{ openai.DeveloperMessage("Produce a concise answer to the query based on the provided sources."), openai.UserMessage(fmt.Sprintf("Sources: %s\n\nQuery: %q", formatResults(results.Data), userQuery)), }, }) if err != nil { panic(err) } fmt.Println(completion.Choices[0].Message.Content)}func formatResults(results []openai.VectorStoreSearchResponse) string { var sources strings.Builder sources.WriteString("<sources>") for _, result := range results { fmt.Fprintf(&sources, "<result file_id=%q file_name=%q>", result.FileID, result.Filename) for _, content := range result.Content { fmt.Fprintf(&sources, "<content>%s</content>", content.Text) } sources.WriteString("</result>") } sources.WriteString("</sources>") return sources.String()}