Docs›Embeddings

Embeddings

PII-schwärzender Embeddings-Endpunkt. OpenAI-kompatibler Passthrough, der sensible Daten aus der Eingabe entfernt, bevor der Vektor erzeugt wird — PII landet nie in Ihrem Vektorspeicher.

Überblick

POST /v1/embeddings ist ein OpenAI-kompatibler Passthrough, der PII in der Eingabe erkennt und schwärzt, bevor an OpenAI weitergeleitet wird. Der zurückkommende Vektor — den Sie in Pinecone, pgvector, Weaviate oder einem anderen Vektorspeicher ablegen — wird aus geschwärztem Text abgeleitet. Ein PII-Leck in den Vektorspeicher wird damit strukturell unmöglich.

Anders als Chat-Completions sind Embeddings dauerhafte Angriffsfläche. Sobald ein Vektor mit roher PII im Speicher liegt, kann er nicht selektiv gelöscht werden, wird per k-NN abgefragt und über RAG zurück in Prompts injiziert. Dieser Endpunkt löst das auf der Ingest-Seite.

Endpunkt

POST https://proxy.grepture.com/v1/embeddings

Identische Request- und Response-Struktur wie OpenAIs /v1/embeddings. Drop-in überall dort, wo ein OpenAI-Embeddings-Client zum Einsatz kommt — einfach die Base-URL auf Grepture zeigen.

Authentifizierung

Zwei Schlüssel sind beteiligt:

• +Grepture-API-Key — im Authorization: Bearer grp_...-Header. Identifiziert Ihr Team für Logging und Rate-Limits.
• +OpenAI-API-Key — für den Upstream-Call. Auflösung in dieser Reihenfolge:
  1. +Vom Aufrufer (BYOK): x-grepture-auth-forward: Bearer sk-.... Der Aufrufer zahlt direkt an OpenAI.
  2. +Gespeicherter Provider-Key: ohne Header nutzt Grepture den OpenAI-Key Ihres Teams aus Integrationen → Provider Keys.
  3. +Keiner von beiden: liefert 400 no_openai_key.

Grundlegende Nutzung

curl -X POST https://proxy.grepture.com/v1/embeddings \
  -H "Authorization: Bearer grp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "mailen Sie mir an john.doe@example.com zur Bestellung #45192"
  }'

Antwort ist die Standard-OpenAI-Struktur, plus zwei Header:

x-grepture-redactions: 1
x-grepture-pii-categories: email

Der zurückgegebene Embedding-Vektor wurde aus "mailen Sie mir an [EMAIL_REDACTED] zur Bestellung #45192" berechnet — dem Platzhalter, nicht der Original-E-Mail.

Request-Body

Header

Was wird erkannt

Zwei Erkennungsschichten laufen auf jeder Eingabe, je nach Tarif:

Regex (alle Tarife) — E-Mail, Telefon, SSN, Kreditkarte, IP-Adresse, Straßen-Adresse, Geburtsdatum.

NER (ab Pro) — Personennamen, Orte, Organisationen. Wird über die Regex-Schicht gelegt; Matches werden positionsbasiert zusammengeführt und dedupliziert.

Jede Erkennung hat eine category und einen Positions-Span. Alle erkannten Kategorien werden im x-grepture-pii-categories-Header zurückgegeben.

Schwärzungs-Strategien

Die Strategie steuert, wie Matches vor der Weiterleitung ersetzt werden.

placeholder (Default, empfohlen) — ersetzt Matches durch stabile Strings wie [EMAIL_REDACTED]. Jede E-Mail wird zum gleichen Token, sodass zwei RAG-Dokumente über „Probleme bei der E-Mail-Zustellung“ weiterhin zu nahezu identischen Vektoren einbetten. Die einzige Strategie, die k-NN-Clustering bewahrt. Standardmäßig nutzen, außer es gibt einen konkreten Grund dagegen.

hash — ersetzt Matches durch ein 12-stelliges SHA-256-Präfix. Jeder distinkte Wert wird ein distinkter Token, was Ähnlichkeits-Retrieval bricht — "E-Mail user1@x.com" und "E-Mail user2@x.com" landen in unterschiedlichen Regionen des Vektorraums. Nur sinnvoll, wenn Sie den Hash separat speichern und korrelieren wollen.

mask — ersetzt Matches durch erster*letzter-Stil-Masken (z. B. j****e@example.com). Teilsignal überlebt, k-NN-Verhalten ist unvorhersehbar. Selten die richtige Wahl für Embeddings.

Modi

redact (Default) — erkannte PII werden ersetzt, der Request wird weitergeleitet. Optimal für RAG-Workloads mit maximaler Trefferquote.

block — wird PII erkannt, liefert der Endpunkt 422 pii_detected und leitet nichts weiter. Für regulierte Workloads, in denen PII Ihre Anwendung nicht verlassen darf:

curl -X POST https://proxy.grepture.com/v1/embeddings \
  -H "Authorization: Bearer grp_live_..." \
  -H "x-grepture-on-pii: block" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"rufen Sie mich an unter 555-123-4567"}'

Antwort:

{
  "error": "pii_detected",
  "categories": ["phone"],
  "count": 1
}

Eine Zeile wird trotzdem in embedding_logs geschrieben mit blocked: true, damit das Dashboard zeigt, was erkannt wurde.

Eingabeformat

input akzeptiert entweder einen einzelnen String oder ein Array von Strings:

{ "input": "ein Dokument zum Einbetten" }
{ "input": ["Dok 1", "Dok 2", "Dok 3"] }

Vortokenisierte Eingaben (number[] oder number[][] — was OpenAI „Token-Arrays“ nennt) werden mit 400 tokenized_input_not_supported abgelehnt. Die Schwärzungs-Pipeline arbeitet auf Text; sobald ein String clientseitig tokenisiert wurde, gibt es keine Oberfläche mehr, auf der PII erkannt werden könnte.

Falls Ihr Client standardmäßig tokenisiert (selten), stellen Sie ihn auf String-Übergabe um.

SDK-Nutzung

Das @grepture/sdk-Paket stellt einen typisierten Wrapper bereit:

import { Grepture } from "@grepture/sdk";

const grepture = new Grepture({
  apiKey: process.env.GREPTURE_API_KEY!,
  proxyUrl: "https://proxy.grepture.com",
});

const { data, redactions } = await grepture.embeddings.create({
  model: "text-embedding-3-small",
  input: "mailen Sie mir an john@example.com zur Bestellung #12345",
});

console.log(redactions); // { count: 1, categories: ["email"] }

// `data` ist das Standard-OpenAI-Embeddings-Array — direkt an Pinecone/pgvector/Weaviate weitergeben.

Optionen auf embeddings.create():

block-Modus wirft einen Fehler mit status, code, categories und count als Attributen, wenn PII erkannt wird.

OpenAI-SDK-Drop-in

Wenn Sie bereits openai nutzen, einfach die Base-URL ändern und den Grepture-Key ergänzen — keine weiteren Codeänderungen:

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GREPTURE_API_KEY!,
  baseURL: "https://proxy.grepture.com/v1",
  defaultHeaders: {
    // Optional: eigenen OpenAI-Key pro Request übergeben
    "x-grepture-auth-forward": `Bearer ${process.env.OPENAI_API_KEY}`,
  },
});

const { data } = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "mailen Sie mir an john@example.com",
});

Die Header x-grepture-redactions und x-grepture-pii-categories werden weiterhin gesetzt, müssen aber bei direktem OpenAI-SDK-Einsatz manuell aus der Response gelesen werden — das typisierte redactions-Feld gibt es nur über @grepture/sdk.

Fehler

Observability

Jeder Call schreibt eine Zeile in embedding_logs, sichtbar im Dashboard unter Embeddings. Die Zeile speichert:

• +Modell, Eingabe-Anzahl, Gesamtzeichen, Token-Verbrauch, Dauer
• +Schwärzungs-Anzahl, erkannte Kategorien, Quelle (regex / ai / both)
• +Schwärzungs-Strategie, Blocked-Flag, Status-Code
• +Trace-ID, BYOK-Flag, Provider-Key-ID

Grepture speichert weder den Eingabetext noch die Response-Vektoren. Das ist Absicht: Sinn des Endpunkts ist, PII aus dem Vektorspeicher fernzuhalten — sie auf unserer Seite zu speichern würde das Feature negieren. Das Dashboard zeigt nur Zähler und Kategorien.

Hintergrundlektüre

Für das Warum hinter diesem Endpunkt siehe Ihr Vektorspeicher ist ein dauerhaftes PII-Leck.