Embeddings
POST /v1/embeddings – Texte als Vektoren für semantische Suche, RAG und Klassifikation.
POST https://api.promodelhub.de/v1/embeddingsEin Embedding ist ein Zahlenvektor, der die Bedeutung eines Textes abbildet: Texte mit ähnlicher Bedeutung haben ähnliche Vektoren. Damit baust du semantische Suche, RAG (Retrieval Augmented Generation), Duplikaterkennung oder Klassifikation über Ähnlichkeit. Welche Embedding-Modelle es gibt, steht unter Modelle.
Beispiel
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.promodelhub.de/v1", api_key=os.environ["PRO_MODEL_HUB_API_KEY"])
result = client.embeddings.create(
model="qwen3-vl-embedding-8b",
input=["Wie kündige ich meinen Vertrag?", "Die Kündigung ist jederzeit zum Monatsende möglich."],
dimensions=1024,
)
vectors = [item.embedding for item in result.data]
print(len(vectors), len(vectors[0])) # 2 1024Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
model | string, Pflicht | API-ID des Embedding-Modells |
input | string oder array, Pflicht | ein Text oder eine Liste von Texten, höchstens 8.192 Token pro Text. Nur Text: Eine Bild-Data-URI wird als Text eingebettet und ergibt keinen sinnvollen Vektor |
dimensions | integer | Länge des Vektors (bei qwen3-vl-embedding-8b 64 bis 4096, Standard 4096). Kürzere Vektoren sparen Speicher im Vektorindex bei etwas geringerer Genauigkeit |
encoding_format | string | float (Standard) oder base64 |
instruction | string | Erweiterung: Aufgabenbeschreibung für das Modell, siehe unten |
Mehrere Texte in einem Request sind schneller als einzelne Requests. Die Reihenfolge in data entspricht der in input. Ein Request darf höchstens 300.000 Token enthalten, pro Minute gilt das Embedding-Limit deines Pakets (Limits).
Antwort
{
"object": "list",
"model": "qwen3-vl-embedding-8b",
"data": [
{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...] },
{ "object": "embedding", "index": 1, "embedding": [0.0789, 0.0012, ...] }
],
"usage": { "prompt_tokens": 42, "total_tokens": 42 }
}Berechnet werden nur Input-Token.
Instruction: Fragen und Dokumente
Das Modell erzeugt bessere Suchergebnisse, wenn es weiß, wofür ein Text steht. Mit dem Feld instruction gibst du eine kurze Aufgabenbeschreibung auf Englisch mit. Ohne Feld gilt Represent the user's input. – das ist gut für Dokumente und allgemeine Ähnlichkeit.
Für Suchanfragen in einem RAG-System lohnt sich eine eigene Anweisung, während die Dokumente ohne instruction eingebettet werden:
# Dokumente einmalig einbetten (ohne instruction)
docs = client.embeddings.create(model="qwen3-vl-embedding-8b", input=chunks)
# Suchanfrage mit Aufgabenbeschreibung
query = client.embeddings.create(
model="qwen3-vl-embedding-8b",
input="Wie kündige ich?",
extra_body={"instruction": "Given a customer question, retrieve relevant help-center passages."},
)instruction ist kein Feld der OpenAI-API. Im Python-SDK übergibst du es mit extra_body, in Node.js direkt im Request-Objekt (bei TypeScript mit Typ-Cast).
Ähnlichkeit berechnen
Vergleiche Vektoren über die Kosinus-Ähnlichkeit (bei normierten Vektoren gleich dem Skalarprodukt). Wichtig: Alle Vektoren eines Index müssen mit demselben Modell und derselben dimensions erzeugt sein.
import math
def cosine(a, b):
dot = sum(x * y for x, y in zip(a, b))
return dot / (math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)))
print(cosine(vectors[0], vectors[1]))