Embeddings-API: OpenAI-kompatible Vektoren, verarbeitet in der EU

POST /v1/embeddings erwartet ein model und einen input, also einen String oder ein Array von Strings, und liefert je Eingabe einen Vektor. Die Antwort enthält ein Array data, dessen Elemente einen index passend zur Position der Eingabe und ein embedding als Liste von Gleitkommazahlen tragen. usage meldet die verbrauchten prompt_tokens.

Mehrsprachige Modelle wie qwen3-embedding-8b legen einen deutschen, einen englischen und einen französischen Satz mit gleicher Bedeutung nah zusammen. Eine Frage in einer Sprache findet so Dokumente in einer anderen. Für europäische Unternehmen, deren Verträge, Tickets und Wikis selten einsprachig sind, ist das entscheidend.

Senden Sie Stapel statt eines Strings pro Anfrage: Ein Array von Eingaben wird gemeinsam verarbeitet und ist deutlich effizienter. Jede Eingabe muss in die maximale Eingabelänge des Modells passen, teilen Sie lange Dokumente also vorher in Abschnitte.

dimensions verkürzt den Vektor bei Modellen, die dafür trainiert sind, etwa der Qwen3-Embedding-Familie. Kürzere Vektoren brauchen weniger Speicher und beschleunigen die Suche bei geringem Genauigkeitsverlust; testen Sie 512 oder 1024 gegen die volle Länge mit Ihren eigenen Daten. encoding_format ist float oder base64, Letzteres verkleinert große Antworten. Nutzen Sie für Dokumente und Anfragen stets dasselbe Modell und dieselbe Dimension.

Eine typische Retrieval-Pipeline wandelt Dokumente in sauberen Text um, teilt ihn in überlappende Abschnitte von einigen hundert Tokens, bettet jeden Abschnitt ein und speichert die Vektoren samt Quelltext in einer Vektordatenbank wie pgvector, Qdrant oder Weaviate. Bei einer Anfrage betten Sie die Frage ein, holen die 20 bis 50 nächsten Abschnitte per Kosinus-Ähnlichkeit und lassen einen Reranker die besten fünf auswählen.

Diese Abschnitte erhält dann ein Chat-Modell als Kontext. Bei Qwen3-Embeddings stellen Sie Anfragen eine kurze Aufgabenbeschreibung voran, wie die Modellkarte empfiehlt, Dokumente betten Sie ohne ein. Die erste Indexierung großer Bestände läuft am besten über die Batch-API.

Eine Eingabe über dem Limit des Modells führt zu einem 400-Fehler und wird nicht stillschweigend gekürzt, teilen Sie also vorher auf. Leere Strings werden ebenfalls abgelehnt; filtern Sie sie heraus. Eine Chat-Modell-ID an diesem Endpunkt ergibt einen Fehler mit Hinweis auf den Modelltyp, eine unbekannte ID 404.

Vektoren verschiedener Modelle oder desselben Modells mit unterschiedlichem dimensions sind nicht vergleichbar. Ändern Sie eines davon, betten Sie den gesamten Bestand neu ein. Die meisten Modelle liefern normalisierte Vektoren, sodass Kosinus-Ähnlichkeit und Skalarprodukt dieselbe Reihenfolge ergeben. Wiederholen Sie 429-Antworten mit Backoff und nutzen Sie für große Indexierungen Batches.