Vai al contenuto principale
Se il tuo agent gestisce dati dei clienti, i due posti dove le PII trapelano sono i prompt che invii a monte e i log che conservi. Questa ricetta collega il logging PII-safe end to end: una regola di mask PII ripulisce la richiesta prima del modello, il contenuto grezzo corrispondente resta fuori dal tuo feed di match per default, e la retention dei request-log è limitata così nulla si attarda. Tutto quanto segue è configurazione del workspace nella console — la tua app continua a chiamare /v1/chat/completions invariata.
Ogni passaggio di config è role-gated. Scrivere un guardrail richiede Developer+; cambiare la retention o la residency di compliance richiede Admin del workspace. Leggere il feed Matches è aperto a qualsiasi Member.

​
1. La pipeline di logging PII-safe in tre mosse

Una pipeline PII-safe è tre controlli indipendenti, ciascuno un interruttore che abbassi una volta per l’intero workspace:

Maschera al bordo

Una regola di guardrail pii redige email, SSN, carte e altro in tag tipizzati prima che il modello a monte veda mai la richiesta.

Non loggare contenuto grezzo

Il toggle Log raw content del guardrail è disattivato per default, così il feed di match registra che una regola è scattata, mai la sottostringa corrispondente.

Limita la retention

La retention dei request-log è di default 30 giorni ed è clampata lato server a un massimo rigido di 180 giorni — di breve durata per design.
Il resto di questa pagina collega tutti e tre insieme con un esempio concreto.

​
2. Maschera le PII prima che il modello le veda

Crea un guardrail con una singola regola pii sullo stage input e l’azione mask. Su un’azione mask ogni match viene sostituito con un tag tipizzato — un’email diventa [EMAIL], un SSN diventa [SSN] — così il modello a monte riceve una richiesta sanitizzata, non l’originale. 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ssn", "credit_card", "ip"]
}
Nella console: Guardrails → New guardrail, aggiungi la regola sopra (o parti dal preset PII Shield sotto la categoria PII), poi salva. Collegalo a una chiave API tramite il dropdown Guardrail della chiave, o impostalo come default del workspace così ogni chiave lo eredita.
Vuoi alcune entità mascherate ma altre respinte del tutto? Una sola regola può portare override per-entità — maschera email/phone ma block su ssn/credit_card — tramite entity_actions. Vedi Guardrails per l’insieme completo di entità PII, le entità regex custom e la sintassi degli override per-entità.
Invia una richiesta con quella chiave e l’email viene redatta in volo: 
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": "Draft a reply to jane@acme.com about her SSN 123-45-6789"}
    ]
  }'
Il modello vede Draft a reply to [EMAIL] about her SSN [SSN]. I valori originali non lasciano mai il gateway.
Il masking allo stage di input è ciò su cui una pipeline PII-safe si basa — ripulisce la richiesta prima della chiamata a monte. Il masking allo stage di output funziona sia sulle risposte non-streaming sia su quelle streaming (lo streaming riscrive ogni chunk sul posto), così puoi anche redigere le PII che il modello emette.

​
3. Tieni il contenuto grezzo fuori dai tuoi log

Ogni regola che scatta registra un match — il suo tipo, azione, stage e una stringa di dettaglio. Se il match memorizza anche la sottostringa corrispondente (l’indirizzo email effettivo, l’SSN effettivo) è gestito dal toggle Log raw content del guardrail, che è disattivato per default — la postura conservativa sulla privacy.
Con Log raw content disattivato, il feed Matches mostra che una regola pii ha mascherato un’email allo stage input, ma mai l’indirizzo stesso. Questo è esattamente ciò che vuoi per una pipeline PII-safe: auditabilità piena di cosa è scattato, zero PII conservate. Lascialo disattivato in produzione; attivalo per-guardrail solo per triage di breve durata. Il toggle è non-retroattivo.
Leggi il feed in Guardrails → Matches (GET /api/guardrail/match, Member). Raggruppa e filtra per guardrail, tipo di regola e azione per vedere il tuo tasso di masking senza mai far emergere un valore reale. Marcare un match come falso positivo è un’azione Admin (POST /api/guardrail/match/:id/mark-fp).

​
4. Limita per quanto vivono i request-log

La cattura dei request-log è una feature di troubleshooting opt-in, e quando è attiva, la retention è limitata:
ImpostazioneValoreComportamento
Retention di default30 giorniApplicata quando non è impostato alcun valore per-workspace.
Massimo rigido180 giorniQualsiasi valore più lungo viene clampato lato server.
Non puoi superare il tetto dei 180 giorni — è applicato al momento della scrittura, non è un suggerimento. Combinato con il masking del §2, anche i log catturati contengono testo sanitizzato, e invecchiano su un orologio fisso.
Tratta i request-log catturati come una leva di debug, non uno store di dati. Abilita la cattura durante un incidente, tieni stretta la finestra di retention, e affidati al feed Matches (che non contiene mai PII grezze quando Log raw content è disattivato) per l’osservabilità a regime.

​
5. Diritto alla cancellazione e residency

Altri due controlli completano una pipeline conforme:
Un’auto-cancellazione dell’utente entra in una finestra di grace di 30 giorni, dopo la quale le PII vengono ripulite e una purga a cascata rimuove insieme i request-log, i guardrail match e i firewall event di quell’utente — così nessun artefatto sopravvive alla richiesta di cancellazione.
Imposta la regione a cui sono fissati gli artefatti dei report di compliance (us, eu, uk, ap, cn, global) tramite PUT /api/compliance/residency (Admin). Le letture cross-region di un report sono negate. Questo fissa la regione dell’artefatto del report — non è geo-pinning dei dati di inferenza.

​
6. Verifica prima di spedire

Dimostra che il masking faccia ciò che ti aspetti prima che qualsiasi traffico ci dipenda:
1

Sandbox della regola

Apri il tab Test nell’editor del guardrail, incolla testo di esempio con un’email e un SSN dall’aspetto reale, scegli lo stage input ed esegui. La sandbox restituisce il verdetto e il testo renderizzato ([EMAIL], [SSN]) senza una chiamata a monte o alcuna spesa di quota.
2

Eval contro un corpus

Il tab Eval esegue la policy su corpora JSONL integrati o custom così puoi misurare il tasso di cattura e i falsi positivi prima di andare live.
3

Conferma che il feed resti pulito

Invia una richiesta reale, poi apri Matches e conferma che la voce mostri la regola scattata con nessuna sottostringa corrispondente — prova che Log raw content è disattivato.

​
Correlati

Riferimento Guardrails

L’insieme completo di entità PII, entità custom, override per-entità e il feed Matches.

Proteggere una pipeline RAG

Controlli di grounding e PII per agent retrieval-augmented.

Evidenza SOC 2

Trasforma l’attività dei guardrail e del firewall in report di audit firmati.

Esfiltrazione di dati

Il modello di threat dietro il tenere le PII fuori dal filo e dai log.