Die Embeddings-API: Modelle und Dimensionen

Lernziele

• Beherrschen Sie den Aufruf client.embeddings.create()
• Verstehen Sie die Unterschiede zwischen Embedding-Modellen
• Nutzen Sie Dimensionsreduktion

Der grundlegende Aufruf

Die gesamte Embeddings-API von OpenAI lässt sich in einer einzigen Methode zusammenfassen: client.embeddings.create(). Sie übergeben ihr einen Textstring und einen Modellnamen:

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    input="Hallo, wie geht es Ihnen?",
    model="text-embedding-3-large"
)

embedding = response.data[0].embedding
print(f"Typ: {type(embedding)}")        # Liste
print(f"Länge: {len(embedding)}")      # 3072
print(f"Auszug: {embedding[:3]}")        # [0.023, -0.041, 0.012]

Das zurückgegebene Objekt ist nicht der Vektor selbst, sondern eine Hülle, die mehrere Vektoren enthält, da die API für die Verarbeitung von Batches konzipiert ist. Innerhalb dieser Hülle finden Sie data, eine Liste von Objekten, bei denen jedes ein Feld embedding (der Vektor) und ein Feld index (die Position im gesendeten Batch) enthält; model, das tatsächlich verwendete Modell; und usage.prompt_tokens, die Anzahl der abgerechneten Tokens. Sie sollten dieses letzte Feld von Anfang an protokollieren: Es ist das einzige verlässliche Maß für Ihre Indexierungskosten.

Die beiden verfügbaren Modelle

text-embedding-3-large ist das Hochleistungsmodell. Seine 3.072 Dimensionen erfassen die feinsten semantischen Nuancen, was es ideal für die Suche in großen Korpora, anspruchsvolle RAG-Pipelines und allgemein für jeden Fall macht, bei dem Präzision die Kosten überwiegt. Wenn Benutzer Fragen indirekt formulieren oder Ihre Dokumente ein dichtes technisches Gebiet abdecken, werden Sie den Unterschied darin erkennen, wie die Ergebnisse gerankt werden.

text-embedding-3-small ist kompakter mit 1.536 Dimensionen und bietet ein hervorragendes Preis-Leistungs-Verhältnis. Es ist die richtige Wahl für Textklassifizierung, Empfehlungen, schnelles Prototyping und Hochvolumen-Anwendungen, bei denen das Ziel nicht darin besteht, zwischen zwei fast identischen Dokumenten zu unterscheiden, sondern klar getrennte Themen zu separieren. Ein einfacher Schleifendurchlauf verifiziert, was jedes Modell zurückgibt:

# Vergleich der beiden Modelle
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
    resp = client.embeddings.create(
        input="Künstliche Intelligenz",
        model=model_name
    )
    vec = resp.data[0].embedding
    print(f"{model_name}: {len(vec)} Dimensionen")

Batch-Embeddings

Sie indexieren kein echtes Korpus nacheinander Text für Text: Jeder HTTP-Aufruf kostet eine Netzwerk-Roundtrip, und die Verarbeitung von tausend Dokumenten einzeln bedeutet die Akkumulation von tausend Latenzen. Die API akzeptiert bis zu 2.048 Texte in einem einzigen Aufruf, und das Feld index ermöglicht es Ihnen, jeden Vektor wieder dem korrekten Dokument zuzuordnen.

texts = [
    "Maschinelles Lernen schreitet rasch voran",
    "Deep Learning revolutioniert die Computer Vision",
    "Vektordatenbanken speichern Embeddings",
    "Python ist die bevorzugte Sprache für Data Scientists"
]

response = client.embeddings.create(
    input=textes,
    model="text-embedding-3-large"
)

for item in response.data:
    print(f"Text {item.index}: Vektor mit {len(item.embedding)} Dimensionen")

print(f"Verbrauchte Tokens: {response.usage.prompt_tokens}")

In der Praxis gruppieren Sie Ihre Texte in Batches von 100 bis 2.048, abhängig von Ihrem Volumen: Kleinere Batches erleichtern die Wiederherstellung nach Fehlern, während größere Batches die Anzahl der Aufrufe reduzieren. Überwachen Sie usage.prompt_tokens bei jeder Iteration, um die Kosten schrittweise zu schätzen, anstatt sie erst auf der Rechnung zu entdecken, und implementieren Sie exponentielle Backoff-Retrys: Eine Überschreitung des Rate-Limits ist ein vorübergehender Fehler, kein Grund, eine dreistündige Indexierungsjob zu unterbrechen.

Dimensionsreduktion

Die text-embedding-3-*-Modelle akzeptieren einen dimensions-Parameter, der Vektoren zurückgibt, die kürzer sind als ihre native Größe:

# Vollständiger Vektor: 3072 Dimensionen
full = client.embeddings.create(
    input="Reduktions-Test",
    model="text-embedding-3-large"
)

# Reduzierter Vektor: 256 Dimensionen
reduced = client.embeddings.create(
    input="Reduktions-Test",
    model="text-embedding-3-large",
    dimensions=256
)

print(f"Voll: {len(full.data[0].embedding)} dim")    # 3072
print(f"Reduziert: {len(reduced.data[0].embedding)} dim")  # 256

Der Mechanismus ist einfach: Die Reduktion kürzt den Vektor und normalisiert ihn anschließend. Da die ersten Dimensionen die meisten Informationen tragen, bleibt die Verschlechterung sehr allmählich. Die folgende Tabelle bietet Standardbenchmarks für den Abwägungsprozess zwischen Qualität und Speicherplatz.

Denken Sie daran, dass Ihre Dimensionswahl verbindlich ist: Alle Vektoren in einem gegebenen Index müssen die gleiche Größe haben, und ein Wechsel der Meinung erfordert die Neuberechnung alles.

Token-Management

Embedding-Modelle haben ein Limit von 8.191 Tokens pro Text, und die API gibt einen Fehler zurück, wenn dieses Limit überschritten wird. Es ist besser, vor dem Senden zu messen, als eine Ausnahme mitten in einem Batch abzufangen:

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

text = "Ein potenziell langer Text..."
tokens = encoder.encode(text)

if len(tokens) > 8191:
    # Trunkierung
    truncated_text = encoder.decode(tokens[:8191])
    print(f"Text von {len(tokens)} auf 8191 Tokens gekürzt")

Trunkierung ist ein Sicherheitsnetz, keine Strategie: Ein gekürztes langes Dokument verliert sein Ende, und das Ende enthält oft die Antwort, nach der Sie suchen. Die richtige Handhabung großer Dokumente umfasst das Chunking, was wir später im Kurs behandeln werden.

Zusammenfassung

• client.embeddings.create() akzeptiert einen einzelnen Text oder eine Liste von Texten
• Verwenden Sie text-embedding-3-large (3.072 dim) für Präzision, text-embedding-3-small (1.536 dim) für Kosteneffizienz
• Der dimensions-Parameter ermöglicht es Ihnen, die Vektorgröße zu reduzieren
• Das Batchen von Texten ist effizienter als einzelne Aufrufe
• Limit von 8.191 Tokens pro Text