Shield konfigurieren & nutzen

Noirdoc Shield prüft eingehende Prompts zustandslos auf den Endpunkten /v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings und /v1/rerank sowie eigenständig über POST /v1/shield/inspect (+0,40 € je 1 Mio. geprüfter Eingabe-Tokens). Wie die fünf Schutzfilter und die Vorrangfolge im Detail arbeiten, erklärt Noirdoc Shield.

1. Standard-Einstellung und Schutzfilter im Portal einrichten

   Admins Ihrer Organisation verwalten Noirdoc Shield unter Models → Shield. Wählen Sie dort zunächst die Standard-Einstellung (mode):

   Im Portal	API-Wert	Wirkung ohne Schlüssel-, Tag- oder Header-Vorgabe
   Auf Abruf	default_off	Shield ist aus (Standard für neue Organisationen)
   Standardmäßig aktiv	default_on	Shield prüft jede unterstützte Anfrage
   Erzwungen	enforced	Shield ist immer aktiv und nicht abschaltbar

   Passen Sie darunter die fünf Schutzfilter an:

   • Geheimnisse & API-Schlüssel (secrets, Standard: block, Platzhalter [SECRET])
   • Finanz- & Kontaktdaten (pii, Standard: redact, Platzhalter wie [IBAN], [EMAIL], [PHONE])
   • Personennamen & Adressen (ner, Standard: redact, Platzhalter [PERSON], [ADDRESS])
   • Prompt-Injection (injection, nur off oder block, Standard: block, prüft user- und tool-Segmente)
   • Eigene Sperrbegriffe (custom, Standard: redact, Platzhalter [CUSTOM]): bis zu 100 Einträge mit je 2 bis 256 Zeichen. Einfache Zeichenfolgen wie "Projekt Helios" greifen unabhängig von Groß- und Kleinschreibung als Teilstring; Einträge mit dem Präfix re: wie "re:AZ-[0-9]{4}-[0-9]{5}" werden als reguläre Ausdrücke mit linearer Laufzeit ausgewertet (ohne Lookaround oder Rückreferenzen, kein leerer Treffer).

   Ergebnis: Ihre Organisation hat eine feste Grundrichtlinie und aktive Schutzfilter. Alternativ verwalten Sie die Richtlinie per API über /v1/shield/policy (setzt am Schlüssel Shield-Richtlinie per API verwalten voraus, siehe Shield (/v1/shield)).

2. Shield pro Anfrage mit X-Noirdoc-Shield steuern

   Übergeben Sie X-Noirdoc-Shield: on oder off (Groß- und Kleinschreibung spielt keine Rolle), um Shield für eine einzelne Anfrage ein- oder auszuschalten, sofern die Organisation nicht auf enforced steht. Vor der Weiterleitung an den Anbieter entfernt das Gateway den Header.

   Auf Organisationen mit Noirdoc Shield funktioniert X-Noirdoc-Mask weiterhin als kompatibler Alias. Auf Bestandsorganisationen im Übergangsbetrieb wählt X-Noirdoc-Shield: on gezielt Noirdoc Shield aus, während X-Noirdoc-Mask die klassische Maskierung steuert.

   Ergebnis: Das Modell erhält geschwärzte Platzhalter wie [PERSON] oder [IBAN], und die Antwort fließt ohne Verzögerung direkt zurück. In den Antwort-Headern bestätigt X-Noirdoc-Shield: redacted=<n> die Anzahl der Schwärzungen neben X-Noirdoc-Masked: true.

   curl Python TypeScript

   Shell

   curl -si https://api.noirdoc.de/v1/chat/completions \
     -H "Authorization: Bearer $NOIRDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Noirdoc-Shield: on" \
     -d '{
       "model": "qwen3.8-27b",
       "messages": [{
         "role": "user",
         "content": "Anna Schmidt, DE89 3704 0044 0532 0130 00"
       }]
     }'

   Python

   import os
   from openai import OpenAI
   
   client = OpenAI(
       base_url="https://api.noirdoc.de/v1",
       api_key=os.environ["NOIRDOC_API_KEY"],
   )
   
   prompt = "Anna Schmidt, DE89 3704 0044 0532 0130 00"
   raw = client.chat.completions.with_raw_response.create(
       model="qwen3.8-27b",
       messages=[{"role": "user", "content": prompt}],
       extra_headers={"X-Noirdoc-Shield": "on"},
   )
   print(raw.headers.get("x-noirdoc-shield"))  # "redacted=2"
   completion = raw.parse()

   TypeScript

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "https://api.noirdoc.de/v1",
     apiKey: process.env.NOIRDOC_API_KEY,
   });
   
   const prompt = "Anna Schmidt, DE89 3704 0044 0532 0130 00";
   const { data, response } = await client.chat.completions
     .create(
       {
         model: "qwen3.8-27b",
         messages: [{ role: "user", content: prompt }],
       },
       { headers: { "X-Noirdoc-Shield": "on" } },
     )
     .withResponse();
   
   console.log(response.headers.get("x-noirdoc-shield"));

3. Shield je API-Schlüssel, Request-Tag oder SDK-Client festlegen

   Statt den Header bei jedem Aufruf mitzusenden, können Sie Shield dauerhaft für eine Anwendung oder einen Mandanten hinterlegen:

   • Pro API-Schlüssel: Stellen Sie unter Models → API-Schlüssel das Feld Noirdoc Shield (shield_mode) auf Aktiv (on) oder Aus (off). Standard (inherit) überlässt die Entscheidung Tags, Header und Organisationsstandard.
   • Pro Request-Tag: Hinterlegen Sie unter Models → Tags oder über /v1/tags ein shield_mode je Tag (siehe Request-Tags (Preview)). Bei mehreren Tags in X-Noirdoc-Tags gewinnt on vor off.
   • Am SDK-Client: Übergeben Sie default_headers (Python) bzw. defaultHeaders (TypeScript) beim Erstellen des Clients. Da Shield neben /v1/chat/completions, /v1/responses und /v1/messages auch /v1/embeddings und /v1/rerank prüft, können Sie denselben Client für Chat und Retrieval verwenden. Für Bildgenerierung (/v1/images/generations) nutzen Sie einen eigenen Client ohne diesen Header (dort antwortet X-Noirdoc-Shield: on mit 403 masking_not_supported_for_endpoint); Audio und /v1/files prüft Shield nicht.

   Ergebnis: Alle unterstützten Aufrufe des Schlüssels, Tags oder Clients werden einheitlich durch Shield geprüft.

   Python TypeScript

   Python

   shield_client = OpenAI(
       base_url="https://api.noirdoc.de/v1",
       api_key=os.environ["NOIRDOC_API_KEY"],
       default_headers={"X-Noirdoc-Shield": "on"},
   )
   
   # Gilt für Chat, Responses, Messages, Embeddings und Rerank
   emb = shield_client.embeddings.create(
       model="text-embedding-3-small",
       input="Notiz zu Anna Schmidt, Akte AZ-2026-00142",
   )

   TypeScript

   const shieldClient = new OpenAI({
     baseURL: "https://api.noirdoc.de/v1",
     apiKey: process.env.NOIRDOC_API_KEY,
     defaultHeaders: { "X-Noirdoc-Shield": "on" },
   });
   
   // Gilt für Chat, Responses, Messages, Embeddings und Rerank
   const emb = await shieldClient.embeddings.create({
     model: "text-embedding-3-small",
     input: "Notiz zu Anna Schmidt, Akte AZ-2026-00142",
   });

4. Texte eigenständig über POST /v1/shield/inspect prüfen

   Bevor Ihre Anwendung Freitext in einer eigenen Vektordatenbank speichert, in Suchindizes übernimmt oder an externe Werkzeuge übergibt, können Sie ihn ohne Modellaufruf über POST /v1/shield/inspect prüfen (1 bis 64 nicht leere Strings, zusammen höchstens 256 KB UTF-8, berechnet mit 0,40 € je 1 Mio. Eingabe-Tokens).

   Der Endpunkt antwortet auch bei einem Block-Treffer mit 200 OK und liefert action ("pass", "redact" oder "block"), den geschwärzten Text in output sowie alle Einzelfunde in findings. Über policy können Sie für diesen Aufruf eigene Regeln und custom_patterns übergeben – etwa literale Projektnamen und re:-Muster –, solange eine enforced-Richtlinie der Organisation dadurch nicht abgeschwächt wird (403 shield_policy_enforced).

   Ergebnis: Sie erhalten den bereinigten Text und die erkannten Kategorien vor jeder Weiterverarbeitung.

   curl Python TypeScript

   Shell

   curl https://api.noirdoc.de/v1/shield/inspect \
     -H "Authorization: Bearer $NOIRDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "input": "Projekt Helios (AZ-2026-00418), Anna Schmidt",
       "role": "user",
       "policy": {
         "rules": { "custom": "redact" },
         "custom_patterns": [
           "Projekt Helios",
           "re:AZ-[0-9]{4}-[0-9]{5}"
         ]
       }
     }'

   Python

   import os
   import httpx
   
   key = os.environ["NOIRDOC_API_KEY"]
   patterns = ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"]
   
   resp = httpx.post(
       "https://api.noirdoc.de/v1/shield/inspect",
       headers={"Authorization": f"Bearer {key}"},
       json={
           "input": "Projekt Helios (AZ-2026-00418), Anna Schmidt",
           "role": "user",
           "policy": {
               "rules": {"custom": "redact"},
               "custom_patterns": patterns,
           },
       },
   )
   resp.raise_for_status()
   data = resp.json()
   if data["action"] == "block":
       raise RuntimeError("Eingabe durch Shield blockiert")
   clean_text = data["output"]

   TypeScript

   const url = "https://api.noirdoc.de/v1/shield/inspect";
   const patterns = ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"];
   
   const resp = await fetch(url, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       input: "Projekt Helios (AZ-2026-00418), Anna Schmidt",
       role: "user",
       policy: {
         rules: { custom: "redact" },
         custom_patterns: patterns,
       },
     }),
   });
   
   const data = await resp.json();
   if (data.action === "block") {
     throw new Error("Eingabe durch Shield blockiert");
   }
   const cleanText: string = data.output;

5. Blockierungen und nicht prüfbare Anhänge im Code behandeln

   Auf Modell-Endpunkten meldet Noirdoc Shield zwei spezifische Ablehnungen vor der Weiterleitung:

   • 403 shield_violation: Ein Schutzfilter mit der Aktion block (standardmäßig secrets oder injection) hat angeschlagen; error.message nennt die ausgelöste Regel. Wiederholen Sie die Anfrage nicht unverändert, sondern weisen Sie die Person in Ihrer Oberfläche darauf hin oder bereinigen Sie die Eingabe.
   • 422 shield_uninspectable_content: Die Organisation steht auf enforced, und die Anfrage enthält Inhalte, die Shield nicht als Text lesen kann – etwa PDF-, DOCX- oder XLSX-Dateien, Bilder, Audio, Verweise per file_id/URL oder eingebettete Textdateien ab 4 MiB. Extrahieren Sie den Text aus Binärdokumenten vorab clientseitig und senden Sie ihn als Nachrichtentext oder als eingebettete UTF-8-Textdatei unter 4 MiB (Details unter Dateien).

   Unter default_on oder einzelner Aktivierung ohne enforced lässt das Gateway nicht prüfbare Anhänge passieren, prüft alle Textfelder der Anfrage und kennzeichnet die Antwort mit X-Noirdoc-Shield: partial; redacted=<n> und X-Noirdoc-Masked: false.

   Ergebnis: Ihre Anwendung unterscheidet sauber zwischen blockierten Inhalten und nicht prüfbaren Dateiformaten.

   Python TypeScript

   Python

   from openai import (
       PermissionDeniedError,
       UnprocessableEntityError,
   )
   
   try:
       response = client.chat.completions.create(
           model="qwen3.8-27b",
           messages=[{"role": "user", "content": user_prompt}],
           extra_headers={"X-Noirdoc-Shield": "on"},
       )
   except PermissionDeniedError as err:
       if getattr(err, "code", None) == "shield_violation":
           # Ausgelöste Regel steht in err.message
           handle_blocked_prompt(err.message)
       else:
           raise
   except UnprocessableEntityError as err:
       code = getattr(err, "code", None)
       if code == "shield_uninspectable_content":
           # Unter enforced: Text vorab aus PDF/Office lesen
           handle_uninspectable_attachment()
       else:
           raise

   TypeScript

   import OpenAI from "openai";
   
   try {
     const response = await client.chat.completions.create(
       {
         model: "qwen3.8-27b",
         messages: [{ role: "user", content: userPrompt }],
       },
       { headers: { "X-Noirdoc-Shield": "on" } },
     );
   } catch (err) {
     const code = err instanceof OpenAI.APIError ? err.code : null;
     if (code === "shield_violation") {
       handleBlockedPrompt((err as Error).message);
     } else if (code === "shield_uninspectable_content") {
       handleUninspectableAttachment();
     } else {
       throw err;
     }
   }

Umstieg von der klassischen Maskierung

Bestandsorganisationen mit klassischer Maskierung können diese noch während der Übergangsfrist bis zum 30. November 2026 (2026-11-30T23:59:59Z) nutzen. Bis dahin trägt jede klassisch maskierte Antwort die RFC-8594-Header Deprecation: true und Sunset: Mon, 30 Nov 2026 23:59:59 GMT.

Prüfen Sie vor der Umstellung vier Punkte in Ihrer Integration:

1. Einweg-Platzhalter statt Rückübersetzung: Noirdoc Shield ersetzt erkannte Werte dauerhaft durch [PERSON], [IBAN] oder [CUSTOM] statt <<PERSON_1>> und übersetzt Antworten oder Tool-Aufrufe nicht zurück. Benötigen lokale Tools echte Datensatz-Bezüge, übergeben Sie interne Datenbank-IDs statt Klartextnamen an das Modell.
2. Direktes Streaming: Da keine Rückübersetzung mehr stattfindet, entfällt der Satzpuffer beim Streaming vollständig.
3. Dateien in Anfragen: Shield prüft eingebettete UTF-8-Textdateien unter 4 MiB direkt. Wenn Sie bisher PDF-, DOCX- oder XLSX-Dateien als Base64 über die klassische Dateianalyse geschickt haben, extrahieren Sie deren Text vorab clientseitig – insbesondere bevor Sie enforced einschalten (422 shield_uninspectable_content).
4. Erweiterte Endpunkte & Abrechnung: Shield schützt zusätzlich /v1/embeddings und /v1/rerank und berechnet +0,40 € je 1 Mio. geprüfter Eingabe-Tokens (auch bei BYOK und bei 403 shield_violation).

# Gezielt Noirdoc Shield für eine einzelne Anfrage testen
curl https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Shield: on" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{
      "role": "user",
      "content": "Rückruf an Anna Schmidt: +49 30 1234567"
    }]
  }'

Fehler