# 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](https://tokenlane.de/docs/guides/rerank.md?lang=de). Embeddings werden nie gestreamt.

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

### curl

```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

```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

```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

```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
| Feld | Wert |
|---|---|
| `model` | Pflicht. Ein Embedding-Modell. Ein Chat-Modell scheitert mit 404 `no_endpoint`. |
| `input` | Pflicht. 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_format` | `float` (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. |
| `dimensions` | Ganzzahl 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_type` | Für Modelle, die Anfragen und Dokumente unterschiedlich behandeln, zum Beispiel `search_query` oder `search_document`. Wird unverändert weitergereicht. |
| `provider`, `session_id`, `user` | Routing, 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:

```json
"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:

```js
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:

| Grenze | Wert | Bei Überschreitung |
|---|---|---|
| Eingaben je Anfrage | 2048 | 400 `invalid_parameter`; die Eingaben aufteilen |
| Länge einer Eingabe | der Kontext des Modells; die Prüfung schätzt 4 Bytes Text je Token | 400 `context_length_exceeded` |
| Request-Body | 50 MiB | 413 `payload_too_large` |
| Anbieterantwort und zusammengeführte Batch-Antwort | jeweils 32 MiB | 502 `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](https://tokenlane.de/models) 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](https://tokenlane.de/models). 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, Typ | Ursache und Abhilfe |
|---|---|
| 400 `invalid_parameter` | Fehlendes 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_exceeded` | Eine Eingabe ist länger als der Kontext des Modells. **Abhilfe:** Den Text in Abschnitte teilen. |
| 404 `no_endpoint` | Das 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_credits` | Die geschätzten Tokens übersteigen das Key-Limit oder das Guthaben. **Abhilfe:** Kleinere Batches senden oder Guthaben aufladen. |
| 429 `rate_limited` | Ein 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](https://tokenlane.de/docs/guides/rerank.md?lang=de) 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.
