Vai al contenuto principale
Il detector pii integrato copre le entità comuni — email, telefono, carta di credito, SSN, IBAN, JWT, chiavi cloud. Ma i tuoi dati sensibili sono tuoi: ID dipendente, numeri di caso interni, riferimenti di conto cliente, il formato d’ordine di un partner. Un’entità PII personalizzata ti permette di insegnare alla stessa regola di masking a riconoscere quelle forme, così che il gateway le rediga prima che il modello — o qualsiasi tool a valle — le veda mai. Questa pagina copre l’unica cosa che le entità personalizzate aggiungono alla regola di PII detection: i tuoi detector. Per il motore completo — ogni tipo di regola, stage e rotta — vedi il riferimento Guardrails.
Ogni passaggio qui è un’azione di console sul gateway gestito (api.orcarouter.ai). Scrivi il guardrail sotto la tua sessione; solo la chiamata /v1/* finale usa una chiave di relay sk-orca-.... Creare e modificare guardrails richiede Developer+ nel workspace.

​
1. Quando ti serve un guardrail di detector PII personalizzato LLM

L’insieme di entità integrate è chiuso e condiviso tra il motore, il validator e il rule builder. È lo strumento giusto per gli identificatori standard. Ricorri a un’entità personalizzata quando i dati che vuoi redigere hanno una forma prevedibile che nessun integrato copre:

Identificatori interni

ID dipendente (EMP482915), numeri di caso, riferimenti di ticket, SKU interni — qualsiasi cosa con un prefisso fisso e una sequenza di cifre.

Numeri di conto e d'ordine

Riferimenti di conto cliente o il formato d’ordine di un partner che non dovrebbe mai raggiungere un modello di terze parti verbatim.

Numeri con checksum

Numeri simili a carte o di iscrizione che passano un controllo Luhn — aggiungi il checksum per ridurre i falsi positivi su sequenze di cifre somiglianti.

Codici specifici di dominio

Numeri di polizza, ID di sinistro, seriali di dispositivo — qualsiasi token che il tuo settore tratta come sensibile ma che i detector generici non conoscono.
Un’entità personalizzata si sovrappone all’insieme integrato all’interno di una regola pii. Rileva i match e applica l’azione della regola — mask, block o flag — esattamente come fa un’entità integrata.

​
2. Anatomia di un’entità personalizzata

Un’entità personalizzata è tre piccoli campi più un mask tag opzionale. Li aggiungi nell’editor della regola pii sotto Custom entities:
CampoObbligatorioCosa fa
namesìID stabile, es. employee_id. ASCII minuscolo / cifre / _, deve iniziare con una lettera. Confluisce nel feed dei Matches e negli audit log.
patternsìUna regex Go RE2 (tempo lineare, nessuna backreference). Deve compilare.
checksumnoluhn valida ogni match con l’algoritmo di Luhn. Sono accettati solo "" (nessuno) o "luhn".
mask_withnoSostituzione verbatim su un’azione mask. Per default [<UPPERCASE_NAME>].
Il name segue la stessa convenzione di chiave del resto del gateway — minuscolo, inizia con una lettera, senza spazi o trattini. Scegline uno chiaro (case_number, partner_order_id); è ciò che vedrai nel feed dei Matches quando la regola scatta.

​
Il checksum Luhn opzionale

Molti identificatori “a forma di numero” — carte di pagamento, alcuni numeri di iscrizione e di conto — portano una cifra di controllo Luhn (mod-10). Una regex nuda come \d{16} corrisponde a qualsiasi sequenza di 16 cifre, inclusi numeri di telefono, timestamp e totali d’ordine. Impostare checksum: "luhn" fa scattare il detector solo quando le cifre corrispondenti passano anche il controllo Luhn, così le sequenze somiglianti passano in modo pulito e il tuo tasso di falsi positivi resta basso. Lascialo vuoto per token senza checksum come un ID dipendente.

​
Il tuo mask tag

Su un’azione mask, un’email integrata viene renderizzata come [EMAIL]. Un’entità personalizzata viene renderizzata come [<UPPERCASE_NAME>] per default — un match employee_id diventa [EMPLOYEE_ID]. Imposta mask_with per sovrascriverlo verbatim (es. <id> o ***) quando vuoi un token di sostituzione specifico nel testo che il modello riceve. Vedi Formati di masking per le regole di rendering tra i tipi di entità.

​
3. Un esempio concreto

Supponi che i tuoi prompt portino ID dipendente nella forma EMP seguito da sei cifre, e che tu voglia mascherarli nello stage di input così che il modello upstream non veda mai un ID reale. Aggiungi una singola entità personalizzata a una regola pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Quella regola maschera sia le email standard sia i tuoi ID dipendente nello stesso passaggio. Testala nella tab Test prima di collegare una chiave: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Nulla viene inviato upstream e nulla viene misurato. Poi collega il guardrail a una chiave (vedi Collega a una chiave) e chiama /v1/chat/completions esattamente come prima — il gateway maschera la richiesta prima di inoltrare, senza modifiche all’SDK.
Il masking gira in entrambi gli stage: una regola di input redige la richiesta prima che il modello la veda, e una regola di output redige la risposta del modello — incluse le risposte in streaming, dove lo scanner riscrive i match in-band. Le azioni di block sono applicate anche su entrambi gli stage. Per gestire le risposte del modello, vedi Regole dello stage di output.

​
Un esempio con checksum

Per un numero di iscrizione simile a una carta, aggiungi il controllo Luhn così che le sequenze di 16 cifre che non sono numeri validi non corrispondano: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Limiti e validazione

Il rule builder valida ogni entità personalizzata al salvataggio — un detector difettoso non raggiunge mai l’hot path.
Ogni entità personalizzata è una scansione regex su tutto il testo, quindi il limite per regola è 25. Il limite mantiene l’hot path lineare; i pattern compilati sono in cache tra le richieste. Ti servono più forme? Suddividile su più regole pii nello stesso guardrail.
pattern è una regex Go RE2 — tempo lineare, nessuna backreference. Il validator rifiuta un pattern che non compila, con l’entità incriminata nominata nell’errore.
Sono accettati solo "" (nessun controllo) e "luhn". Qualsiasi altra cosa — "sha256", "mod10", persino "LUHN" — è rifiutata al salvataggio.
Un name deve iniziare con una lettera e usare solo ASCII minuscolo, cifre e underscore. Due entità personalizzate in una regola non possono condividere un nome.

​
5. Override di azione per entità

Un’entità personalizzata partecipa alla stessa mappa entity_actions di un’entità integrata. Una regola pii può mascherare la maggior parte delle cose ma bloccare su un detector personalizzato ad alta sensibilità — riferisci l’entità tramite il suo 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"
  }
}
Le chiavi in entity_actions devono riferire un’entità integrata abilitata sulla regola o il name di un’entità personalizzata; i valori devono essere block, mask, flag o annotate. Il validator rifiuta qualsiasi altra cosa.

​
6. Dove andare dopo

PII Shield

La singola regola di masking su cui le entità personalizzate si sovrappongono — l’insieme di detector integrati e i mask tag tipizzati.

Formati di masking

Come ogni entità viene renderizzata su un’azione mask, e come mask_with la sovrascrive.

Regex detector

Quando una semplice regola regex si adatta meglio di un’entità PII tipizzata.

Tuning dei falsi positivi

Usa il feed dei Matches e il checksum per regolare la precisione.
Leggi il riferimento Guardrails per la regola PII completa — ogni campo, l’harness di eval e l’API completa — o Crea il tuo primo guardrail per percorrere il loop end-to-end da zero.