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-2b",
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 |
dimensions | integer | Länge des Vektors (bei qwen3-vl-embedding-2b 64 bis 2048, Standard 2048). 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.
Antwort
{
"object": "list",
"model": "qwen3-vl-embedding-2b",
"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-2b", input=chunks)
# Suchanfrage mit Aufgabenbeschreibung
query = client.embeddings.create(
model="qwen3-vl-embedding-2b",
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]))