Embeddings

Text in Vektoren für Suche, Retrieval und Clustering umwandeln: Anfrageformat, Grenzen, Kosten und Fehler.

Wann nutzen

Semantische Suche, Retrieval für Frage-Antwort-Systeme, Erkennung nahezu doppelter Inhalte, Clustering und Merkmale für Klassifikatoren. Ein Embedding ist ein Vektor; Texte mit ähnlicher Bedeutung haben Vektoren, die in dieselbe Richtung zeigen. Embeddings erzeugen keinen Text. Um eine Kandidatenliste nach Relevanz zu ordnen, dient Rerank. Embeddings werden nie gestreamt.

Minimalbeispiel

Ein kurzer Text, Vektoren als Zahlen. data[0].embedding ist der Vektor.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/embeddings' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "baai/bge-m3",
  "input": "A short sentence to compare.",
  "encoding_format": "float"
}'

node

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.embeddings.create({
  "model": "baai/bge-m3",
  "input": "A short sentence to compare.",
  "encoding_format": "float"
}, {});
console.log(response);

python

import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "model": "baai/bge-m3",
  "input": "A short sentence to compare.",
  "encoding_format": "float"
}''')
response = client.embeddings.create(
    model=body["model"],
    input=body["input"],
    encoding_format=body["encoding_format"]
)
print(response)

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "baai/bge-m3",
  "input": "A short sentence to compare.",
  "encoding_format": "float"
}`,
});
console.log(await response.text());

Anfrageformat

FeldWert
modelPflicht. Ein Embedding-Modell. Ein Chat-Modell scheitert mit 404 no_endpoint.
inputPflicht. Ein Text; ein Array von Texten (je ein Vektor, in Reihenfolge); Token-IDs eines Texts oder mehrerer; oder multimodale Eingaben. 1 bis 2048 Eingaben. Texte dürfen nicht leer sein. Alle Elemente eines Arrays müssen dieselbe Art sein.
encoding_formatfloat (Standard): Zahlenarrays. base64: der Vektor als Little-Endian-32-Bit-Floats in Base64, häufig kompakter als ein JSON-Zahlenarray. Funktioniert mit jedem Embedding-Modell: Liefert ein Anbieter Zahlen, kodiert das Gateway sie.
dimensionsGanzzahl ab 1, für Modelle, die ihre Vektoren kürzen können. Andere ignorieren es und nennen es in x-ignored-params; mit provider.require_parameters: true werden solche Routen übersprungen, und bleibt keine übrig, folgt 404 no_endpoint.
input_typeFür Modelle, die Anfragen und Dokumente unterschiedlich behandeln, zum Beispiel search_query oder search_document. Wird unverändert weitergereicht.
provider, session_id, userRouting, Gruppierung und Endnutzer-ID wie beim Chat.

Batch: "input": ["first text", "second text"] liefert zwei Einträge in data, jeweils mit index. Token-IDs: "input": [101, 2054, 102] ist eine Eingabe, "input": [[101, 2054], [101, 2129]] sind zwei. Multimodal, für Modelle mit Medieneingabe:

"input": [{ "content": [
  { "type": "text", "text": "A cat" },
  { "type": "image_url", "image_url": { "url": "https://example.com/cat.jpg" } }
] }]

Teile sind text, image_url (URL oder Data-URL), input_audio, input_video und input_file (jeweils mit data als Data-URL oder Base64 und format). Das Modell muss den Medientyp in architecture.input_modalities führen; sonst 404 no_endpoint.

Einen base64-Vektor in Node dekodieren:

const bytes = Buffer.from(entry.embedding, 'base64');
const vector = new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));

In Python: numpy.frombuffer(base64.b64decode(s), dtype='<f4').

Grenzen:

GrenzeWertBei Überschreitung
Eingaben je Anfrage2048400 invalid_parameter; die Eingaben aufteilen
Länge einer Eingabeder Kontext des Modells; die Prüfung schätzt 4 Bytes Text je Token400 context_length_exceeded
Request-Body50 MiB413 payload_too_large
Anbieterantwort und zusammengeführte Batch-Antwortjeweils 32 MiB502 provider_invalid_response; kleinere Batches senden

Ein Anbieter kann bei deutschem Text oder Code mehr Tokens zählen als die Schätzung und eine Eingabe ablehnen, die die Prüfung durchließ; das ist ein nicht wiederholbarer 400. Ist ein Batch größer, als ein Anbieter je Aufruf annimmt, teilt das Gateway ihn auf.

Modell wählen

Den Katalog nach Ausgabe Embeddings filtern. Vergleichen:

  • context_length: die längste Eingabe.
  • pricing.prompt: EUR je Eingabe-Token.
  • supported_parameters: dimensions für kürzere Vektoren, input_type, encoding_format.
  • architecture.input_modalities: mehr als text bedeutet multimodale Eingabe.

Die Vektorlänge hängt vom Modell ab; sie aus der ersten Antwort lesen (data[0].embedding.length) und mit dem Index speichern. Eine Route kann sich bei Kontextlänge oder Preis von den anderen unterscheiden; die Modellseite listet sie je Anbieter.

Kosten

Berechnet werden nur Eingabe-Tokens: usage.prompt_tokens mal Prompt-Preis, ausgewiesen als usage.cost in EUR. Es gibt keine Ausgabekosten. Meldet ein Anbieter keine Tokenzahl, fehlt cost, es ist nicht null.

Beispiel: 1.000 Abschnitte à 500 Tokens sind 500.000 Eingabe-Tokens, berechnet zum Prompt-Preis des Modells; die aktuellen Preise stehen auf jeder Modellseite im Katalog. Ein neues Modell braucht einen neuen Index, also dieselbe Tokenmenge noch einmal einplanen.

Die Reservierung ist die geschätzte Tokenzahl des Batches; große Batches brauchen also Guthaben für die ganze Menge.

Häufige Fehler

Status, TypUrsache und Abhilfe
400 invalid_parameterFehlendes oder leeres input, ein leerer String, gemischte Elementarten, eine negative Token-ID, mehr als 2048 Eingaben, dimensions unter 1, encoding_format außer float oder base64. Abhilfe: Jeden Pfad in issues korrigieren.
400 context_length_exceededEine Eingabe ist länger als der Kontext des Modells. Abhilfe: Den Text in Abschnitte teilen.
404 no_endpointDas Modell ist kein Embedding-Modell, Medieneingabe wird nicht unterstützt, oder für dimensions mit require_parameters gibt es keine Route. Abhilfe: Ein Modell aus remedy_hint wählen.
402 insufficient_creditsDie geschätzten Tokens übersteigen das Key-Limit oder das Guthaben. Abhilfe: Kleinere Batches senden oder Guthaben aufladen.
429 rate_limitedEin Token- oder Anfragelimit des Keys oder Anbieters. Abhilfe: Retry-After abwarten, dann in kleineren Schritten senden.

Bewährte Praxis

  • Nach Struktur (Absatz oder Abschnitt) auf etwa 200 bis 800 Tokens aufteilen, mit kleiner Überlappung. Ein Vektor für ein ganzes Dokument verwischt die Bedeutung.
  • Bis zu 2048 Eingaben je Anfrage bündeln, statt einen Aufruf je Text zu senden.
  • Für Dokumente und Suchanfragen eines Index dasselbe Modell und dieselben dimensions verwenden. Unterscheidet das Modell Eingaberollen, gilt input_type: search_document für gespeicherte Abschnitte und search_query für Suchanfragen; die unterstützten Werte des Modells beachten. Modell-ID, Dimensionen und Dokument-Eingabetyp am Index speichern.
  • Vektoren mit Kosinus-Ähnlichkeit vergleichen. Beim Speichern einmal normalisieren.
  • Den Vektor über einen Hash des Texts cachen: Gleiche Eingabe und gleiches Modell ergeben denselben Vektor.
  • Zuerst den Index durchsuchen, dann die besten 50 bis 200 Treffer mit Rerank neu ordnen und nur die ersten wenigen an das Chat-Modell geben.
  • Mit base64 lässt sich der Vektortransport häufig verkleinern. Die Grenze der Anbieterantwort bleibt bestehen: Liefert der Anbieter weiterhin ein großes Zahlenarray, kleinere Batches senden.
  • Keine Geheimnisse einbetten: Vektoren können den Text verraten, aus dem sie stammen.

Für KI-Agenten

  • Endpunkt: [POST /embeddings](https://tokenlane.de/docs/gateway/post-L2VtYmVkZGluZ3M.md?lang=de).
  • Pflicht: model (ein Embedding-Modell aus GET /v1/models), input (String, Array von Strings, Token-IDs oder multimodale Objekte mit content).
  • Optional: encoding_format (float oder base64), dimensions (Ganzzahl ab 1), input_type, provider.
  • Antwort: data[i].embedding und data[i].index, usage.prompt_tokens, usage.cost (EUR), model.
  • Grenzen: 2048 Eingaben; jede Eingabe innerhalb des Kontexts des Modells (geschätzt 4 Bytes Text je Token); Body 50 MiB; kein Streaming.
  • Fehler: 400 invalid_parameter und context_length_exceeded, 404 no_endpoint, 402 insufficient_credits, 429. Vor einer Wiederholung issues lesen.