Przejdź do głównej treści
Wbudowany detektor pii obejmuje typowe encje — email, telefon, kartę kredytową, SSN, IBAN, JWT, klucze chmurowe. Ale twoje wrażliwe dane są twoje: identyfikatory pracowników, wewnętrzne numery spraw, odwołania do kont klientów, format zamówień partnera. Niestandardowa encja PII pozwala nauczyć tę samą regułę maskowania rozpoznawania tych kształtów, więc brama redaguje je, zanim model — lub jakiekolwiek narzędzie poniżej — je w ogóle zobaczy. Ta strona obejmuje jedną rzecz, którą niestandardowe encje dodają do reguły wykrywania PII: twoje własne detektory. Pełny silnik — każdy typ reguły, etap i trasę — znajdziesz w referencji Guardrails.
Każdy krok tutaj to akcja konsoli na hostowanej bramie (api.orcarouter.ai). Autorzysz guardrail pod twoją własną sesją; tylko końcowe wywołanie /v1/* używa klucza relay sk-orca-.... Tworzenie i edycja guardrails wymaga Developer+ w przestrzeni roboczej.

​
1. Kiedy potrzebujesz niestandardowego guardrail detektora PII LLM

Wbudowany zestaw encji jest zamknięty i współdzielony przez silnik, walidator i konstruktor reguł. To właściwe narzędzie do standardowych identyfikatorów. Sięgaj po niestandardową encję, gdy dane, które chcesz zredagować, mają przewidywalny kształt, którego żaden wbudowany nie obejmuje:

Identyfikatory wewnętrzne

Identyfikatory pracowników (EMP482915), numery spraw, odwołania do zgłoszeń, wewnętrzne SKU — cokolwiek ze stałym prefiksem i ciągiem cyfr.

Numery kont i zamówień

Odwołania do kont klientów lub format zamówień partnera, który nigdy nie powinien dotrzeć do modelu zewnętrznego dosłownie.

Numery z sumą kontrolną

Numery przypominające karty lub członkostwa, które przechodzą sprawdzenie Luhna — dodaj sumę kontrolną, by uciąć fałszywie pozytywne na podobnych ciągach cyfr.

Kody specyficzne dla dziedziny

Numery polis, ID roszczeń, numery seryjne urządzeń — dowolny token, który twoja branża traktuje jako wrażliwy, a generyczne detektory go nie znają.
Niestandardowa encja nawarstwia się na wbudowanym zestawie wewnątrz jednej reguły pii. Wykrywa dopasowania i stosuje akcję reguły — mask, block lub flag — dokładnie jak wbudowana encja.

​
2. Anatomia niestandardowej encji

Niestandardowa encja to trzy małe pola plus opcjonalny tag maski. Dodajesz je w edytorze reguły pii pod Custom entities:
PoleWymaganeCo robi
nametakStabilny ID, np. employee_id. Małe litery ASCII / cyfry / _, musi zaczynać się od litery. Trafia do strumienia Matches i logów audytu.
patterntakRegex Go RE2 (liniowy czas, bez backreferencji). Musi się skompilować.
checksumnieluhn waliduje każde dopasowanie algorytmem Luhna. Akceptowane są tylko "" (brak) lub "luhn".
mask_withnieDosłowny zamiennik przy akcji mask. Domyślnie [<UPPERCASE_NAME>].
name podąża za tą samą konwencją kluczy co reszta bramy — małe litery, zaczyna się od litery, bez spacji i myślników. Wybierz wyrazisty (case_number, partner_order_id); to on pojawi się w strumieniu Matches, gdy reguła zadziała.

​
Opcjonalna suma kontrolna Luhna

Wiele identyfikatorów “w kształcie numeru” — karty płatnicze, niektóre numery członkostwa i kont — niesie cyfrę kontrolną Luhna (mod-10). Goły regex jak \d{16} dopasowuje dowolny ciąg 16 cyfr, w tym numery telefonów, znaczniki czasu i sumy zamówień. Ustawienie checksum: "luhn" sprawia, że detektor działa tylko, gdy dopasowane cyfry przejdą też sprawdzenie Luhna, więc podobne ciągi przechodzą czysto, a twój wskaźnik fałszywie pozytywnych pozostaje niski. Zostaw to puste dla tokenów bez sumy kontrolnej, jak identyfikator pracownika.

​
Twój własny tag maski

Przy akcji mask wbudowany email renderuje się jako [EMAIL]. Niestandardowa encja renderuje się jako [<UPPERCASE_NAME>] domyślnie — dopasowanie employee_id staje się [EMPLOYEE_ID]. Ustaw mask_with, by nadpisać to dosłownie (np. <id> lub ***), gdy chcesz konkretny token zamiennika w tekście, który otrzymuje model. Zobacz Formaty maskowania po reguły renderowania w różnych typach encji.

​
3. Jeden konkretny przykład

Załóżmy, że twoje prompty niosą identyfikatory pracowników w formie EMP poprzedzone sześcioma cyframi, a chcesz je maskować na etapie input, by model nadrzędny nigdy nie widział prawdziwego ID. Dodaj jedną niestandardową encję do reguły pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Ta reguła maskuje zarówno standardowe emaile, jak i twoje identyfikatory pracowników w tym samym przejściu. Przetestuj ją w zakładce Test, zanim powiążesz klucz: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Nic nie jest wysyłane w górę i nic mierzone. Potem powiąż guardrail z kluczem (zobacz Powiąż z kluczem) i wywołaj /v1/chat/completions dokładnie jak wcześniej — brama maskuje żądanie przed przesłaniem, bez zmiany SDK.
Maskowanie biegnie na obu etapach: reguła input redaguje żądanie, zanim model je zobaczy, a reguła output redaguje odpowiedź modelu — w tym odpowiedzi streamingowe, gdzie skaner przepisuje dopasowania w paśmie. Akcje block są egzekwowane na obu etapach też. Aby bramkować odpowiedzi modelu, zobacz Reguły na etapie wyjścia.

​
Przykład z sumą kontrolną

Dla numeru członkostwa przypominającego kartę dodaj sprawdzenie Luhna, by ciągi 16-cyfrowe, które nie są poprawnymi numerami, się nie dopasowały: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Limity i walidacja

Konstruktor reguł waliduje każdą niestandardową encję przy zapisie — zły detektor nigdy nie dociera do gorącej ścieżki.
Każda niestandardowa encja to skan regex po całym tekście, więc limit per-reguła to 25. Limit utrzymuje gorącą ścieżkę liniową; skompilowane wzorce są cache’owane między żądaniami. Potrzebujesz więcej kształtów? Rozdziel je na wiele reguł pii w tym samym guardrail.
pattern to regex Go RE2 — liniowy czas, bez backreferencji. Walidator odrzuca wzorzec, który się nie kompiluje, z obraźliwą encją nazwaną w błędzie.
Akceptowane są tylko "" (brak sprawdzenia) i "luhn". Cokolwiek innego — "sha256", "mod10", nawet "LUHN" — jest odrzucane przy zapisie.
name musi zaczynać się od litery i używać tylko małych liter ASCII, cyfr i podkreśleń. Dwie niestandardowe encje w jednej regule nie mogą dzielić nazwy.

​
5. Nadpisania akcji per-encja

Niestandardowa encja uczestniczy w tej samej mapie entity_actions co wbudowana encja. Jedna reguła pii może maskować większość rzeczy, ale blokować na wysoce wrażliwym niestandardowym detektorze — odwołaj się do encji przez jej 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"
  }
}
Klucze w entity_actions muszą odwoływać się do wbudowanej encji włączonej na regule lub do name niestandardowej encji; wartości muszą być block, mask, flag lub annotate. Walidator odrzuca wszystko inne.

​
6. Dokąd dalej

PII Shield

Pojedyncza reguła maskowania, na którą nawarstwiają się niestandardowe encje — wbudowany zestaw detektorów i typowane tagi maski.

Formaty maskowania

Jak każda encja renderuje się przy akcji mask i jak mask_with to nadpisuje.

Detektory regex

Kiedy zwykła reguła regex pasuje lepiej niż typowana encja PII.

Strojenie fałszywie pozytywnych

Użyj strumienia Matches i sumy kontrolnej, by dostroić precyzję.
Przeczytaj referencję Guardrails po kompletną regułę PII — każde pole, harness ewaluacyjny i pełne API — albo Utwórz swój pierwszy guardrail, aby przejść pełną pętlę od zera.