Vai al contenuto principale
Quando hai bisogno di mascherare i dati sensibili che un prompt llm porta — email, numeri di carta, ID nazionali, segreti — il gateway riscrive ogni match sul posto prima che il modello lo veda. Un valore mascherato diventa un tag tipizzato (jane@acme.com → [EMAIL]), così il modello legge comunque un prompt coerente mentre il valore grezzo non lascia mai il tuo workspace. Questa pagina è la trattazione focalizzata su cosa renderizza il masking, come cambiare il tag e come mascherare alcune entità mentre se ne bloccano altre su una singola regola. Per il motore completo — ogni tipo di regola, stage e rotta — vedi il riferimento Guardrails, e per il masking sulla richiesta in particolare, Regole dello stage di input.

​
1. Maschera i dati sensibili che i prompt llm portano, con tag tipizzati

Una regola pii con l’azione mask rileva un’entità e sostituisce ogni match con un tag di redazione tipizzato — un’etichetta in maiuscolo tra parentesi quadre che nomina cosa è stato rimosso senza rivelare il valore:
EntitàTag renderizzato
email[EMAIL]
credit_card[CREDIT_CARD]
ssn[SSN]
L’insieme completo di detector integrati — email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address, più i regionali jp_mynumber, kr_rrn e cn_resident_id — renderizza ciascuno il proprio tag tra parentesi ([PHONE], [IBAN], [JP_MYNUMBER], e così via). Il tag è deterministico: la stessa entità renderizza sempre la stessa etichetta, così i prompt a valle restano stabili e i tuoi log si leggono in modo pulito.
I tag tipizzati battono un generico [REDACTED] per la qualità del modello. Il modello sa ancora che sta guardando un’email vs. un numero di conto vs. un numero di telefono, quindi può continuare a ragionare sulla forma dei dati — “reply to [EMAIL]” resta un’istruzione azionabile — senza mai detenere il valore reale.
Il masking di input è completamente attivo — il gateway riscrive il prompt prima che raggiunga il modello, in streaming o meno. Il masking di output è attivo sulle risposte non in streaming anch’esso: una regola mask nello stage di output riscrive la completion prima che torni. Solo il masking dell’output in streaming è nella roadmap; su una risposta in streaming, preferisci block nello stage di output. Vedi Streaming coverage per la matrice esatta stage/stream.

​
2. Un esempio concreto

Scrivi la regola nella console sotto la tua sessione — la config dei guardrail richiede Developer+, non una chiave di relay. Aggiungi una singola regola pii a un guardrail chiamato pii-shield: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ssn"]
}
Collegala a una chiave (imposta guardrail_id, o marcala come default del workspace — vedi Collega a una chiave), poi chiama il gateway con quella chiave di relay sk-orca-...: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com about her SSN 123-45-6789"}
    ]
  }'
Il gateway riscrive il prompt in “Reply to [EMAIL] about her SSN [SSN]” prima di inoltrare. Il modello upstream non vede mai l’indirizzo o il numero. Dimostra prima il rendering esatto nella tab Test dell’editor (nessuna chiamata upstream, nessuna quota) — vedi Testing ed eval.

​
3. Sovrascrivi il tag con mask_with

Le entità integrate renderizzano un tag fisso. Le entità personalizzate — i tuoi detector regex sovrapposti all’insieme integrato — ti permettono di impostare tu stesso il testo di sostituzione con mask_with: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP-[0-9]{6}",
      "mask_with": "[STAFF_ID]"
    }
  ]
}
mask_with è la stringa di sostituzione verbatim per i match di quell’entità. EMP-004217 diventa [STAFF_ID]. Lascialo vuoto e il match renderizza il tag di default [<UPPERCASE_NAME>] — qui, [EMPLOYEE_ID] — così un detector personalizzato produce sempre una redazione leggibile e tipizzata anche senza override.
name (ASCII minuscolo / cifre / underscore, deve iniziare con una lettera), pattern (una regex Go RE2 — tempo lineare, nessuna backreference), checksum opzionale (luhn valida i numeri a forma di carta), e mask_with opzionale. Fino a 25 entità personalizzate per regola — ognuna è una scansione su tutto il testo, quindi il limite mantiene l’hot path lineare. Vedi Entità PII personalizzate.
Un name confluisce negli audit log e nel feed dei Matches senza virgolette, quindi mantienilo a lettere ASCII minuscole, cifre e underscore iniziando con una lettera (es. employee_id, internal_ticket). Il validator rifiuta qualsiasi altra cosa.

​
4. Maschera alcune entità, blocca altre — entity_actions

Una singola regola pii può applicare azioni diverse a entità diverse tramite entity_actions, invece di impilare tre regole sovrapposte. La forma classica: mascherare i dati di contatto a bassa sensibilità, ma bloccare del tutto i campi ad alta sensibilità. 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Qui email, phone e ip seguono il mask di primo livello della regola e renderizzano [EMAIL] / [PHONE] / [IP]; un match credit_card o ssn invece blocca l’intera richiesta con HTTP 400 guardrail_blocked.
CampoRegola
ChiaviDevono essere un’entità dichiarata sulla regola (integrata o personalizzata).
Valoriblock, mask, flag o annotate.
Una richiesta bloccata non costa quota — un block nello stage di input scatta prima della misurazione. Una richiesta mascherata passa con il testo sanitizzato. Quindi una regola può redigere silenziosamente i campi di routine e fermare in modo rigido quelli regolamentati, con un singolo collegamento e nessuna modifica all’applicazione.

​
5. Mask vs. block vs. flag

Il masking è una delle azioni che una regola (o override per entità) può intraprendere. Scegli in base a quanto vuoi disturbare il traffico:

mask

Redige il match in un tag tipizzato e lascia passare la richiesta con il testo sanitizzato. Il modello non vede mai il valore grezzo.

block

Rifiuta l’intera richiesta con HTTP 400 guardrail_blocked. Nulla raggiunge il modello. Usalo per dati che non devono mai transitare.

flag

Non cambia nulla del traffico — registra solo un match. Misura quanto spesso una regola scatterebbe prima di applicarla.
Un buon rollout è flag → mask → block: flag per dimensionare l’impatto, mask una volta che ti fidi del detector, e riserva block per i campi che non puoi lasciar passare affatto. Vedi Azioni e Tuning dei falsi positivi.

​
6. Verifica cosa è stato mascherato

Ogni regola che scatta registra un match nel feed Matches del workspace — tipo di regola, azione, stage e una stringa di detail. La sottostringa corrispondente stessa (l’email grezza, il numero di carta effettivo) viene registrata solo quando Log raw content è attivo, che è disattivato per default — la postura conservativa sulla privacy, dato che tutto il punto è tenere i valori grezzi fuori dai tuoi log.
Attiva Log raw content solo quando ti serve genuinamente la sottostringa per il triage, e solo per ciascun guardrail. Con esso disattivato, il feed dimostra che un [CREDIT_CARD] è stato mascherato senza mai memorizzare il numero. Il toggle non è retroattivo. Vedi Logging e privacy.

​
7. Dove andare dopo

Leggi il riferimento Guardrails per il motore completo, o esposizione di PII e fuga di segreti per le minacce che il masking è costruito per contenere.