Suchen Sie nach der Open AI Embeddings API? Der Embeddings-Endpunkt von OpenAI wandelt Text in numerische Vektoren um, damit eine Anwendung verwandte Passagen abrufen kann. Die Anfrage ist nur der erste Schritt: Eine nützliche Suchfunktion benötigt außerdem stabile Dokument-IDs, einen konsistenten Vektorraum und einen Test, der zeigt, ob sich der Abruf verbessert hat.
Dieser Leitfaden erstellt ein kleines Python-Suchbeispiel, zeigt, was Sie neben jedem Vektor speichern sollten, und bietet Ihnen eine Checkliste, um das Experiment in ein Produkt zu überführen. Er verwendet OpenAI direkt. Gateway-Kompatibilität und Modellverfügbarkeit müssen für jeden Anbieter separat geprüft werden.
Open AI Embeddings API: die benötigte Anfrage
Senden Sie Text mit einem Embedding-Modell und einem API-Schlüssel an POST https://api.openai.com/v1/embeddings. Wählen Sie encoding_format="float", wenn Ihre Anwendung numerische Arrays erwartet. Verwenden Sie für einen Batch den index jedes Antwortelements, um den Vektor wieder seiner Eingabe zuzuordnen. Die Antwort enthält auch die Token-Nutzung. Die Option dimensions wird von Embedding-Modellen der dritten Generation unterstützt. OpenAI API-Referenz.
Ein Embedding ist keine generierte Antwort. In einer Retrieval-augmented-Anwendung wählt die Suche zunächst Quellpassagen aus; ein separater Generierungsaufruf kann anschließend anhand dieser Passagen antworten. Wenn Sie die Stufen getrennt halten, können Sie ein schlechtes Ergebnis diagnostizieren: Hat die Suche die falschen Belege abgerufen oder hat das Antwortmodell gute Belege falsch verwendet?
Wählen Sie ein Modell und halten Sie seine Konfiguration unverändert
Die dokumentierten Standardvektorlängen sind 1.536 für text-embedding-3-small und 3.072 für text-embedding-3-large. Diese Modelle unterstützen über dimensions kürzere Ausgabevektoren. Ein kürzerer Vektor verändert die Abwägungen bei Speicherung und Abruf; er ist kein Grund, die Evaluierung zu überspringen. OpenAI-Embeddings-Leitfaden.
Beginnen Sie mit einer Konfiguration und einer kleinen Gruppe repräsentativer Abfragen. Erfassen Sie zusammen mit dem Index das Modell, die angeforderte Dimensionsanzahl und die Textverarbeitungsversion. Dass zwei Vektoren dieselbe Länge haben, belegt nicht, dass sie aus kompatiblen Modellen stammen. Wenn Sie Modelle oder Verarbeitungsregeln ändern, erstellen Sie einen separaten Index und vergleichen Sie ihn, bevor Sie den Produktionsverkehr umstellen.
Ein minimales Python-Beispiel für semantische Suche
Installieren Sie openai in Ihrer Python-Umgebung und stellen Sie OPENAI_API_KEY über Ihren üblichen Secret Manager oder Ihre Umgebungskonfiguration bereit. Halten Sie den Schlüssel aus der Versionsverwaltung und aus Browser-Code heraus. Das offizielle Python-SDK liest diese Variable beim Erstellen von OpenAI().
Speichern Sie Folgendes als search_demo.py. Es verwendet drei erfundene Support-Dokumente, erstellt Embeddings für den Korpus und eine Abfrage und ordnet die Dokumente nach Kosinusähnlichkeit. Beim Ausführen werden kostenpflichtige API-Anfragen gestellt. Die Ausgabe hängt von der Serviceantwort ab; das Beispiel verspricht keinen bestimmten Score oder Rang.
import math
from openai import OpenAI
client = OpenAI(timeout=30.0, max_retries=2)
model = "text-embedding-3-small"
dimensions = 1536
documents = [
{"id": "key-rotation", "text": "Replace an exposed API key and revoke the old credential."},
{"id": "invoice-export", "text": "Download a monthly invoice from the billing workspace."},
{"id": "request-timeout", "text": "Record the request ID and retry temporary upstream timeouts."},
]
query = "What should I do after accidentally sharing a secret key?"
def embed(texts):
response = client.embeddings.create(
model=model, input=texts,
dimensions=dimensions, encoding_format="float",
)
ordered = sorted(response.data, key=lambda item: item.index)
if [item.index for item in ordered] != list(range(len(texts))):
raise ValueError("Unexpected embedding response indices")
vectors = [item.embedding for item in ordered]
if any(len(vector) != dimensions for vector in vectors):
raise ValueError("Unexpected vector dimensions")
print("Input tokens:", response.usage.prompt_tokens)
return vectors
def cosine(a, b):
if len(a) != len(b):
raise ValueError("Vector dimensions do not match")
denominator = math.sqrt(sum(x*x for x in a) * sum(y*y for y in b))
if not denominator:
raise ValueError("Cannot compare a zero vector")
return sum(x*y for x, y in zip(a, b)) / denominator
vectors = embed([document["text"] for document in documents])
query_vector = embed([query])[0]
ranked = sorted(
((cosine(query_vector, vector), document["id"])
for document, vector in zip(documents, vectors)),
reverse=True,
)
for score, document_id in ranked:
print(document_id, round(score, 4))
Führen Sie python search_demo.py aus. Bestätigen Sie, dass alle drei IDs jeweils einmal erscheinen und dass jedes Embedding die konfigurierte Länge hat. Ändern Sie dann die Abfrage so, dass sie nach Rechnungen fragt. Dies ist ein Smoke-Test des Datenflusses, kein Beweis dafür, dass das System für echten Support-Traffic bereit ist. Das Beispiel erstellt zur Verdeutlichung bei jeder Ausführung erneut Embeddings für den Korpus; ein bereitgestellter Dienst sollte Dokumentvektoren normalerweise dauerhaft speichern und nur neue oder geänderte Inhalte einbetten.
Machen Sie aus der Demo einen zuverlässigen Dokumentindex
Das folgende Datensatzlayout ist ein praktischer Ausgangspunkt. Es ist ein Beispiel für ein Anwendungsdesign und kein von OpenAI vorgeschriebenes Feldschema.
| Mit jedem Chunk speichern | Warum es wichtig ist |
|---|---|
document_id und chunk_id | Die richtigen Inhalte aktualisieren oder löschen, ohne sich auf die Array-Reihenfolge zu verlassen. |
| Quell-URL, Abschnittstitel und Quellrevision | Eine nützliche Quellenangabe anzeigen und veraltete Antworten nachverfolgen. |
| Inhalts-Hash und Verarbeitungsversion | Ermitteln, welche Chunks tatsächlich erneut eingebettet werden müssen. |
| Modell und Anzahl der Dimensionen | Eine versehentliche Mischung inkompatibler Vektorkonfigurationen verhindern. |
| Mandanten- und Zugriffskontrollmetadaten | Den Abruf auf Dokumente filtern, auf die der anfragende Benutzer zugreifen darf. |
| Text und Embedding | Die Quellpassage zurückgeben, nachdem ihr Vektor ausgewählt wurde. |
Teilen Sie Dokumente an sinnvollen Grenzen auf und prüfen Sie anschließend die Tokenlänge. Ein Abschnitt, der die Antwort auf die Frage enthält, sollte verständlich bleiben, wenn er allein abgerufen wird. Bewerten Sie Überlappungen bewusst: Zu starke Überlappung kann die Ergebnismenge mit wiederholten Versionen derselben Passage füllen.
Für das erste Experiment genügt die obige In-Memory-Schleife. Wenn der Korpus wächst, verwenden Sie einen Index oder Vektorspeicher, der das erforderliche Filter-, Lösch- und Abrufverhalten unterstützt. Testen Sie diese Vorgänge, bevor Sie sich auf Ähnlichkeitswerte verlassen. Eine hochähnliche Passage eines falschen Kunden darf niemals nur deshalb zurückgegeben werden, weil sie an erster Stelle rangiert.
Eingabe- und Batch-Limits getrennt prüfen
Die aktuelle Endpunktreferenz von OpenAI gibt ein Maximum von 8.192 Token pro Eingabe und ein aggregiertes Maximum von 300.000 Token über die Eingaben einer Anfrage hinweg an; außerdem dokumentiert sie maximal 2.048 Batch-Eingaben. Leerer Text ist ungültig. Zählen Sie Token statt Zeichen und lassen Sie beim Erstellen von Batches Spielraum unterhalb der Limits. Endpunktbeschränkungen.
Wenn Sie Azure OpenAI verwenden, haben Endpunktkonfiguration, Authentifizierung und Bereitstellungsbenennung eigene Anforderungen. Befolgen Sie für diesen Dienst die Anweisungen für Azure-Embeddings, statt anzunehmen, dass eine direkte OpenAI-Anfrage unverändert kopiert werden kann. Wenden Sie dieselbe Trennung bei der Verwendung eines Gateways an: Prüfen Sie zuerst dessen Endpunkt, Modellzugriff, unterstützte Parameter und Abrechnungskonto.
Kosten schätzen, ohne Index-Neuaufbauten zu verschleiern
Die Embedding-Kosten richten sich nach den Eingabe-Token. Zählen Sie daher Dokumentenaufnahme, geänderte Chunks und Query-Embeddings getrennt. Verwenden Sie den aktuellen Preis auf der jeweiligen Modellseite, beispielsweise text-embedding-3-small, und bestätigen Sie, ob der angegebene Tarif für Ihren Anfragemodus gilt.
Für ein Planungsbeispiel sei P Ihr verifizierter Preis pro Million Eingabe-Token:
Erste Aufnahme: 50.000 Chunks × 400 Token = 20 Millionen Token
Monatliche Änderungen: 5.000 Chunks × 400 Token = 2 Millionen Token
Monatliche Abfragen: 200.000 Abfragen × 20 Token = 4 Millionen Token
Kosten für erste Embeddings = 20 × P
Laufende Embedding-Kosten = (2 + 4) × P = 6 × P
Dies sind beispielhafte Annahmen zur Arbeitslast, keine Preise von Flatkey oder OpenAI. Addieren Sie Vektorspeicher, Suchinfrastruktur und sämtliche Aufrufe zur Antwortgenerierung separat. Wenn Sie das Embedding-Modell ändern, berücksichtigen Sie im Migrationsbudget einen vollständigen Neu-Embedding-Durchlauf. Eine Pipeline, die unveränderte Dokumente erneut einbettet, kann mehr kosten als dieselbe Arbeitslast mit einem größeren, aber korrekt gecachten Modell.
Fehler diagnostizieren, bevor Wiederholungen hinzugefügt werden
| Symptom | Erste nützliche Prüfung |
|---|---|
| Authentifizierungsfehler | Bestätigen Sie, dass der Schlüssel für den aufgerufenen Endpunkt und das Konto gültig ist. |
| Ungültige Anfrage | Prüfen Sie den Fehlertext, leere Zeichenfolgen, Tokenanzahlen und unterstützte Parameter. |
| Ratenlimit- oder Kontingentfehler | Unterscheiden Sie zwischen Druck durch die Anfragerate und ausgeschöpftem Kontingent des Kontos. |
| Vorübergehender Serverfehler oder Zeitüberschreitung | Bewahren Sie Anfragekennungen auf und verwenden Sie begrenztes Wiederholungsverhalten. |
| Dimensionsfehler im Vektorspeicher | Vergleichen Sie die Kollektionskonfiguration mit der tatsächlich zurückgegebenen Vektorlänge. |
| Plausible, aber irrelevante Ergebnisse | Prüfen Sie Chunk-Text, Modellkonsistenz und Abfragebeispiele, bevor Sie dem Netzwerk die Schuld geben. |
Die ersten vier Prüfungen folgen dem OpenAI-Fehlerleitfaden. Die letzten beiden betreffen Ihre Anwendung und Ihren Index. Beachten Sie die Wiederholungshinweise des Servers und berücksichtigen Sie SDK-Wiederholungen, bevor Sie eine weitere Wiederholungsschleife hinzufügen. Protokollieren Sie Betriebsmetadaten, ohne Anmeldedaten oder unnötigen privaten Dokumenttext aufzuzeichnen.
Den Abruf bewerten, bevor ein Antwortmodell ausgewählt wird
Erstellen Sie einen kleinen gelabelten Satz aus echten Benutzerfragen, einschließlich Paraphrasen, exakten Produktnamen, mehrdeutigen Fragen und Fragen, die Ihr Korpus nicht beantworten kann. Notieren Sie für jede beantwortbare Abfrage das erwartete Quelldokument, bevor Sie das System abstimmen.
Erfassen Sie für jede Kandidatenkonfiguration, ob in den ersten wenigen Ergebnissen eine akzeptable Quelle erscheint, wie viel doppeltes Material zurückgegeben wird, die Abruflatenz und die Kosten pro Abfrage. Prüfen Sie Fehler einzeln. Wenn eine Abfrage nach einem exakten Fehlercode fragt, kann ein Schlüsselworttreffer die semantische Ähnlichkeit ergänzen. Wenn die Quelle fehlt, können geänderte Embedding-Dimensionen sie nicht erfinden.
Behalten Sie einen zurückgehaltenen Teil der Fragen für den endgültigen Vergleich. Wählen Sie keinen Ähnlichkeitsschwellenwert aus der Demo mit drei Dokumenten und behandeln Sie ihn als universellen Vertrauenswert. Ein nützlicher Akzeptanztest berücksichtigt die Folgen eines falschen Abrufs in Ihrer eigenen Anwendung.
Wo Flatkey in die Anwendung passt
Flatkey bietet einen OpenAI-kompatiblen Modellrouter und ein aktuelles Modellverzeichnis. Nutzen Sie die Flatkey-Integrationsdokumentation, um die Modellerzeugungsseite Ihrer Anwendung zu bewerten. Die obigen Beispiele rufen OpenAI direkt auf; sie belegen nicht, dass ein Embedding-Modell oder jeder Embeddings-Parameter über Flatkey verfügbar ist.
Halten Sie bei einer Anwendung mit mehreren Anbietern die Retrieval-Konfiguration unabhängig von der Konfiguration Ihres Antwortmodells. So können Sie Antwortmodelle vergleichen, ohne den Dokumentindex für jedes Experiment neu zu erstellen. Lesen Sie bei der Planung von Routing, Kontosteuerungen und operativen Prüfungen die Leitfäden zur API-Architektur von Flatkey.
Häufig gestellte Fragen
Beantwortet die Embeddings-API Fragen eigenständig?
Sie gibt Vektoren zurück. Ihre Anwendung verwendet sie, um verwandte Inhalte auszuwählen; ein Antwortmodell ist eine separate Komponente, wenn Sie eine schriftliche Antwort benötigen.
Kann ich Vektoren verschiedener Embedding-Modelle vergleichen?
Gehen Sie nicht davon aus, dass sie einen aussagekräftigen gemeinsamen Koordinatenraum haben, selbst wenn ihre Dimensionen übereinstimmen. Behalten Sie modellspezifische Indizes bei und bewerten Sie Migrationen anhand derselben Fragen und Quelldokumente.
Sollte ich sofort das größte Embedding-Modell wählen?
Beginnen Sie mit einer Konfiguration, die Sie messen können. Vergleichen Sie Retrieval-Qualität, Latenz, Speicherbedarf und Kosten anhand Ihrer eigenen Abfragen, bevor Sie einen größeren Index oder ein anderes Modell akzeptieren.
Was sollte ich zuerst erstellen?
Verwenden Sie die Open AI Embeddings API, um einen kleinen, berechtigungssicheren Korpus einzubetten, die Dokument-zu-Vektor-Zuordnung zu überprüfen und das Retrieval mit annotierten Fragen zu testen. Erweitern Sie den Korpus, nachdem dieser Zyklus verlässliche Erkenntnisse liefert.
