Embeddings

POST /v1/embeddings — OpenAI-kompatible Text-Embeddings. In dieser Phase ohne PII-Maskierung.

Überblick

Der Endpunkt POST /v1/embeddings erzeugt Vektor-Embeddings für Text — OpenAI-kompatibel, über dieselbe Base-URL https://api.noirdoc.de/v1 und denselben px--Key wie alle anderen Proxy-Endpunkte. Als model verwenden Sie die Modell-ID aus dem Katalog (GET /v1/models oder Portal); das Modell muss ein Embedding-Modell sein.

Anfrage

curl -X POST https://api.noirdoc.de/v1/embeddings \
  -H "Authorization: Bearer px-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "input": ["Erster Satz.", "Zweiter Satz."]
  }'

Mit dem OpenAI-SDK genügt es wie gewohnt, base_url und api_key zu tauschen:

from openai import OpenAI

client = OpenAI(base_url="https://api.noirdoc.de/v1", api_key="px-...")

response = client.embeddings.create(
    model="<model-id>",
    input="Die Kündigungsfrist beträgt drei Monate.",
)

print(response.data[0].embedding[:5])

Request-Body:

Feld	Typ	Erforderlich	Beschreibung
model	string	Ja	Modell-ID aus dem Katalog — muss ein Embedding-Modell sein
input	string | string[]	Ja	Der einzubettende Text — ein String oder ein Array von Strings

Weitere OpenAI-Felder (z. B. encoding_format, dimensions) reicht der Proxy unverändert an den Provider durch; ob sie unterstützt werden, hängt vom jeweiligen Modell und Provider ab.

Hinweis: Das Feld stream wird für Embeddings nicht unterstützt; eine Anfrage mit "stream": true wird mit HTTP 400 und dem Code streaming_not_supported_for_endpoint abgelehnt.

Antwort

Die Antwort ist das OpenAI-kompatible Embedding-Objekt, wie es der Upstream-Provider liefert — Noirdoc reicht sie unverändert durch:

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.012, -0.031, 0.044] },
    { "object": "embedding", "index": 1, "embedding": [0.007, 0.058, -0.019] }
  ],
  "model": "<model-id>",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}

Keine PII-Maskierung in dieser Phase

Die Maskierung gilt in dieser Phase nicht für /v1/embeddings. Konkret bedeutet das:

• Der Eingabetext erreicht den Modell-Provider im Klartext. Die PII-Pipeline (Erkennung, Pseudonymisierung, Wiederherstellung) wird für Embeddings-Anfragen vollständig übersprungen. Ein expliziter X-Noirdoc-Mask: on-Header wird stattdessen mit HTTP 403 abgelehnt, um zu verhindern, dass Maskierung stille übersprungen wird.
• Das Audit-Log bleibt aktiv und vermerkt für jede Embeddings-Anfrage mask_applied=false.
• Organisationen mit der Richtlinie enforced können den Endpunkt nicht nutzen. Statt eine Anfrage unmaskiert weiterzuleiten, blockiert der Proxy sie mit HTTP 403:

{
  "error": {
    "type": "proxy_error",
    "code": "masking_not_supported_for_endpoint",
    "message": "Masking is not available on '/v1/embeddings', and this tenant's mask policy requires masking on all traffic. Contact your administrator."
  }
}

Maskierte Embeddings — mit konsistenten Platzhaltern, sodass semantische Suche über pseudonymisierte Texte funktioniert — sind geplant, aber noch nicht verfügbar. Bis dahin gilt: Senden Sie keine personenbezogenen Daten an diesen Endpunkt, oder pseudonymisieren Sie den Text vorab selbst über POST /v1/pseudonymize.

Modell und Endpunkt müssen zusammenpassen

Jedes Katalog-Modell gehört zu genau einer Endpunkt-Familie — chat oder embeddings. Passen Modell und Endpunkt nicht zusammen, gibt die API 400 mit dem Code wrong_endpoint_for_model zurück. Das gilt in beide Richtungen:

• ein Chat-Modell auf /v1/embeddings → 400
• ein Embedding-Modell auf /v1/chat/completions oder /v1/responses → 400

{
  "error": {
    "type": "proxy_error",
    "code": "wrong_endpoint_for_model",
    "message": "Model '<model-id>' cannot be called from this endpoint; use the endpoint matching its provider's API format."
  }
}

Welche Modelle Embedding-Modelle sind, zeigt der Katalog-Endpunkt GET /v1/models bzw. das Portal.

Nächste Schritte

• Maskierung — wie die Pseudonymisierung bei Chat-Anfragen funktioniert und wie Sie sie steuern
• Proxy-Endpunkte — alle unterstützten Pfade, inklusive /v1/pseudonymize zur eigenständigen Pseudonymisierung
• Fehlercodes — alle Fehlercodes der API