Zum Hauptinhalt springen
Der eingebaute pii-Detektor deckt die gängigen Entities ab — E-Mail, Telefon, Kreditkarte, SSN, IBAN, JWT, Cloud-Keys. Aber Ihre sensiblen Daten gehören Ihnen: Mitarbeiter-IDs, interne Fallnummern, Kunden-Kontoreferenzen, das Bestellformat eines Partners. Eine benutzerdefinierte PII-Entity lässt Sie dieselbe Masking-Regel lehren, diese Formen zu erkennen, sodass das Gateway sie redigiert, bevor das Modell — oder irgendein nachgelagertes Tool — sie je sieht. Diese Seite behandelt die eine Sache, die benutzerdefinierte Entities zur PII-detection-Regel hinzufügen: Ihre eigenen Detektoren. Für die vollständige Engine — jeder Regeltyp, jede Stage, jede Route — siehe die Guardrails-Referenz.
Jeder Schritt hier ist eine Konsolen-Aktion auf dem gehosteten Gateway (api.orcarouter.ai). Sie verfassen das Guardrail unter Ihrer eigenen Session; nur der finale /v1/*-Aufruf verwendet einen sk-orca-...-Relay-Key. Das Erstellen und Bearbeiten von Guardrails erfordert Developer+ im Workspace.

​
1. Wann Sie ein Guardrail mit benutzerdefiniertem PII-Detektor für LLMs brauchen

Der eingebaute Entity-Satz ist geschlossen und wird über die Engine, den Validator und den Rule-Builder geteilt. Er ist das richtige Werkzeug für Standard-Identifier. Greifen Sie zu einer benutzerdefinierten Entity, wenn die Daten, die Sie redigieren möchten, eine vorhersehbare Form haben, die kein eingebauter abdeckt:

Interne Identifier

Mitarbeiter-IDs (EMP482915), Fallnummern, Ticket-Refs, interne SKUs — alles mit einem festen Präfix und einer Ziffernfolge.

Konto- & Bestellnummern

Kunden-Kontoreferenzen oder das Bestellformat eines Partners, das ein Drittanbieter-Modell nie wortwörtlich erreichen sollte.

Prüfsummen-Nummern

Karten- oder mitgliedschaftsähnliche Nummern, die eine Luhn-Prüfung bestehen — fügen Sie die Prüfsumme hinzu, um Fehlalarme bei ähnlich aussehenden Ziffernfolgen zu reduzieren.

Domänenspezifische Codes

Policennummern, Claim-IDs, Geräteseriennummern — jedes Token, das Ihre Branche als sensibel behandelt, das die generischen Detektoren aber nicht kennen.
Eine benutzerdefinierte Entity schichtet sich über den eingebauten Satz innerhalb einer pii-Regel. Sie erkennt Treffer und wendet die Action der Regel an — mask, block oder flag — genau wie es eine eingebaute Entity tut.

​
2. Anatomie einer benutzerdefinierten Entity

Eine benutzerdefinierte Entity besteht aus drei kleinen Feldern plus einem optionalen Mask-Tag. Sie fügen sie im pii-Regel-Editor unter Custom entities hinzu:
FeldErforderlichWas es tut
namejaStabile ID, z. B. employee_id. Kleinbuchstaben-ASCII / Ziffern / _, muss mit einem Buchstaben beginnen. Fließt in den Matches-Feed und Audit-Logs.
patternjaEine Go-RE2-Regex (lineare Zeit, keine Backreferences). Muss kompilieren.
checksumneinluhn validiert jeden Treffer mit dem Luhn-Algorithmus. Nur "" (keine) oder "luhn" werden akzeptiert.
mask_withneinWortwörtlicher Ersatz bei einer Mask-Action. Standard ist [<UPPERCASE_NAME>].
Der name folgt derselben Key-Konvention wie der Rest des Gateways — Kleinbuchstaben, beginnt mit einem Buchstaben, keine Leerzeichen oder Bindestriche. Wählen Sie einen klaren (case_number, partner_order_id); er ist das, was Sie im Matches-Feed sehen, wenn die Regel feuert.

​
Die optionale Luhn-Prüfsumme

Viele „nummernförmige” Identifier — Zahlungskarten, manche Mitgliedschafts- und Kontonummern — tragen eine Luhn-Prüfziffer (mod-10). Eine nackte Regex wie \d{16} matcht jede 16-stellige Ziffernfolge, einschließlich Telefonnummern, Zeitstempel und Bestellsummen. checksum: "luhn" zu setzen lässt den Detektor nur feuern, wenn die gematchten Ziffern auch die Luhn-Prüfung bestehen, sodass ähnlich aussehende Folgen sauber durchrutschen und Ihre Fehlalarmrate niedrig bleibt. Lassen Sie es leer für Tokens ohne Prüfsumme wie eine Mitarbeiter-ID.

​
Ihr eigener Mask-Tag

Bei einer mask-Action rendert eine eingebaute E-Mail als [EMAIL]. Eine benutzerdefinierte Entity rendert standardmäßig als [<UPPERCASE_NAME>] — aus einem employee_id-Treffer wird [EMPLOYEE_ID]. Setzen Sie mask_with, um das wortwörtlich zu überschreiben (z. B. <id> oder ***), wenn Sie ein bestimmtes Ersatz-Token im Text wollen, den das Modell empfängt. Siehe Masking-Formate für die Rendering-Regeln über Entity-Typen hinweg.

​
3. Ein konkretes Beispiel

Angenommen, Ihre Prompts tragen Mitarbeiter-IDs in der Form EMP gefolgt von sechs Ziffern, und Sie möchten sie an der input-Stage maskiert, sodass das Upstream-Modell nie eine echte ID sieht. Fügen Sie einer pii-Regel eine einzelne benutzerdefinierte Entity hinzu: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Diese Regel maskiert sowohl Standard-E-Mails als auch Ihre Mitarbeiter-IDs in demselben Durchlauf. Testen Sie sie im Tab Test, bevor Sie einen Key anhängen: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Nichts wird nach Upstream gesendet und nichts gemessen. Hängen Sie dann das Guardrail an einen Key an (siehe An einen Key anhängen) und rufen Sie /v1/chat/completions genau wie zuvor auf — das Gateway maskiert die Anfrage vor dem Weiterleiten, ohne SDK-Änderung.
Masking läuft an beiden Stages: eine input-Regel redigiert die Anfrage, bevor das Modell sie sieht, und eine output-Regel redigiert die Antwort des Modells — einschließlich streamender Responses, bei denen der Scanner Treffer in-band umschreibt. Block-Actions werden ebenfalls auf beiden Stages durchgesetzt. Um Modell-Antworten zu gaten, siehe Output-Stage-Regeln.

​
Ein Beispiel mit Prüfsumme

Für eine kartenähnliche Mitgliedsnummer fügen Sie die Luhn-Prüfung hinzu, sodass 16-stellige Folgen, die keine gültigen Nummern sind, nicht matchen: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Limits und Validierung

Der Rule-Builder validiert jede benutzerdefinierte Entity beim Speichern — ein schlechter Detektor erreicht nie den heißen Pfad.
Jede benutzerdefinierte Entity ist ein Regex-Scan über den vollständigen Text, daher ist das Pro-Regel-Limit 25. Das Limit hält den heißen Pfad linear; kompilierte Muster werden über Requests hinweg gecacht. Brauchen Sie mehr Formen? Teilen Sie sie über mehrere pii-Regeln im selben Guardrail auf.
pattern ist eine Go-RE2-Regex — lineare Zeit, keine Backreferences. Der Validator lehnt ein Muster ab, das nicht kompiliert, mit der anstößigen Entity im Fehler benannt.
Nur "" (keine Prüfung) und "luhn" werden akzeptiert. Alles andere — "sha256", "mod10", sogar "LUHN" — wird beim Speichern abgelehnt.
Ein name muss mit einem Buchstaben beginnen und nur Kleinbuchstaben-ASCII, Ziffern und Unterstriche verwenden. Zwei benutzerdefinierte Entities in einer Regel können sich keinen Namen teilen.

​
5. Pro-Entity-Action-Overrides

Eine benutzerdefinierte Entity nimmt an derselben entity_actions-Map teil wie eine eingebaute Entity. Eine pii-Regel kann die meisten Dinge maskieren, aber bei einem hochsensiblen benutzerdefinierten Detektor blockieren — referenzieren Sie die Entity über ihren name: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
Keys in entity_actions müssen eine auf der Regel aktivierte eingebaute Entity oder den name einer benutzerdefinierten Entity referenzieren; Werte müssen block, mask, flag oder annotate sein. Der Validator lehnt alles andere ab.

​
6. Wohin als Nächstes

PII Shield

Die einzelne Masking-Regel, über die benutzerdefinierte Entities sich schichten — der eingebaute Detektor-Satz und die typisierten Mask-Tags.

Masking-Formate

Wie jede Entity bei einer Mask-Action rendert und wie mask_with es überschreibt.

Regex-Detektoren

Wann eine einfache regex-Regel besser passt als eine typisierte PII-Entity.

Fehlalarme tunen

Verwenden Sie den Matches-Feed und die Prüfsumme, um die Präzision einzustellen.
Lesen Sie die Guardrails-Referenz für die vollständige PII-Regel — jedes Feld, das Eval-Harness und die vollständige API — oder Ihr erstes Guardrail erstellen, um die End-to-End-Schleife von Grund auf zu durchlaufen.