Vai al contenuto principale
Ogni regola di guardrail risponde a tre domande — cosa cercare (un type), dove cercare (uno stage), e cosa farne (un’azione). Questa pagina riguarda quella terza scelta. L’azione di una regola è il campo più consequenziale su di essa: decide se un match ferma la richiesta, la riscrive silenziosamente, o lascia solo una briciola di pane. Il rule builder fa emergere cinque azioni in tutto — block, mask, flag, annotate e spotlight. Questa pagina copre le tre scelte di applicazione a cui ricorri per prime: block, mask e flag. Scegline una per regola (o, per una regola PII, instrada entità diverse verso azioni diverse; vedi §5). Le altre due sono azioni di prompt-shaping, non bloccanti: annotate inietta una nota di sicurezza upstream (vedi code security), e spotlight avvolge l’input non attendibile corrispondente in delimitatori così che il modello lo tratti come dati, non come istruzioni. Il roster completo vive nella panoramica dei Guardrails. Per il motore più ampio — tipi di regola, stage, collegare una policy a una chiave — parti dalla panoramica dei Guardrails o dal riferimento Guardrails completo.

​
1. La decisione guardrail block mask flag in una riga

block

Rifiuta la chiamata con HTTP 400 guardrail_blocked. Il modello non gira mai (stage di input) o la sua risposta non torna mai (stage di output).

mask

Redige ogni match — es. jane@acme.com → [EMAIL] — e lascia passare il testo sanitizzato. La richiesta continua.

flag

Non cambia nulla del traffico. Registra un match nel feed e prosegue. Solo osservazione.
Queste sono le tre azioni di applicazione. Qualunque imposti è onorata ovunque la regola giri — il rule builder della console, la sandbox di Test, e il percorso di relay /v1/* reale leggono tutti lo stesso valore block / mask / flag.

​
2. Un esempio concreto — tre regole, tre azioni

Ecco un singolo guardrail le cui tre regole scelgono ciascuna un’azione diversa. Lo scrivi nella console (/console/guardrails) sulla tua sessione — la chiave di relay sk-orca-... serve solo per le chiamate /v1/*, mai per modificare la policy. Creare o modificare un guardrail richiede il ruolo Developer+. 
{
  "rules": [
    { "type": "keyword", "stage": "input",  "action": "block",
      "keywords": ["internal-only", "do-not-share"] },
    { "type": "pii",     "stage": "input",  "action": "mask",
      "entities": ["email", "phone"] },
    { "type": "regex",   "stage": "output", "action": "flag",
      "pattern": "(?i)acme\\s+confidential" }
  ]
}
Cosa fa ogni regola su una richiesta:
  • La regola block rifiuta qualsiasi prompt che contiene uno di quei termini letterali — HTTP 400, il modello non gira mai.
  • La regola mask riscrive email e numeri di telefono in [EMAIL] / [PHONE] nel prompt prima che il modello lo veda.
  • La regola flag osserva l’output del modello per un marcatore confidenziale e registra un match senza alterare la risposta — così puoi misurare quanto spesso appare prima di decidere di applicare.
Il motore esegue ogni regola applicabile e ripiega i risultati in un unico verdetto. Se una qualsiasi regola blocca, la richiesta è bloccata.

​
3. block — rifiuta con HTTP 400

Un’azione block rifiuta l’intera chiamata. Il chiamante riceve HTTP 400 con codice di errore guardrail_blocked e un messaggio che nomina il guardrail e la regola che ha scattato.
Un block nello stage di input scatta prima della misurazione, quindi nulla viene consumato. Un block nello stage di output rimborsa la quota pre-consumata dopo aver rifiutato la risposta. In entrambi i casi il chiamante non paga nulla per una chiamata bloccata.
Un risultato guardrail_blocked è skip-retry — rieseguire lo stesso prompt contro un altro canale si limiterebbe a bloccarlo di nuovo, quindi il gateway non sprecherà un retry. Vedi l’errore guardrail_blocked.
Su una risposta non in streaming la risposta viene filtrata prima che torni. Su una risposta in streaming uno scanner interrompe lo stream a metà ed emette un messaggio sostitutivo prima che qualsiasi contenuto bloccato raggiunga il client. Vedi streaming coverage.
Ricorri a block quando un match significa che la richiesta non deve procedere — segreti in un prompt, un tentativo di jailbreak, una linea di compliance rigida.

​
4. mask — redige e continua

Un’azione mask redige ogni match e lascia passare la richiesta con il testo sanitizzato. Il modello upstream non vede mai l’originale. Su una regola PII, ogni match viene sostituito con un tag tipizzato derivato dall’entità — un’email diventa [EMAIL], un SSN diventa [SSN], una carta di credito [CREDIT_CARD], e così via. (Puoi sovrascrivere la stringa di sostituzione per entità personalizzata; vedi formati di masking.)
Il masking nello stage di input è attivo su ogni stream. Riscrive la richiesta prima che il modello giri, in streaming o meno. Il masking nello stage di output si applica solo alle risposte non in streaming — il testo mascherato viene inoltrato dopo che la risposta completa è filtrata. Su una risposta in streaming il gateway calcola la maschera ma non inoltra ancora il testo redatto, quindi una regola mask non redige una risposta in streaming oggi; il masking dell’output in-stream è nella roadmap. (Un block di output interrompe comunque uno stream a metà — vedi §3.) Dimostra prima la tua specifica combinazione stage/stream nella sandbox. Vedi streaming coverage.
Ricorri a mask quando il contenuto va bene ma una sottostringa non dovrebbe raggiungere il modello — la redazione di PII è il caso canonico. Il punto di partenza chiavi-in-mano è il preset PII Shield; vedi PII Shield.

​
5. flag — registra solo, non cambia nulla

Un’azione flag è solo osservazione: la richiesta è byte-identica a una senza alcuna regola, eccetto che un match è registrato nel feed dei Matches. Nulla è bloccato, nulla è redatto.
flag è il modo in cui misuri una regola prima di applicarla. Metti in produzione una nuova keyword o regex come flag, osserva il feed dei Matches per qualche giorno per vedere il suo tasso di veri-vs-falsi positivi sul traffico reale, poi promuovila a mask o block una volta che ti fidi. Mettere a punto un pattern rumoroso con flag attivo batte lo scoprire i falsi positivi in produzione con block attivo. Vedi tuning dei falsi positivi.
Un match segnalato registra il tipo di regola, l’azione, lo stage e una stringa di detail — e la sottostringa corrispondente solo se Log raw content è attivo per quel guardrail (disattivato per default, la postura conservativa sulla privacy). Vedi logging e privacy.

​
6. Override di azione per entità

Una singola regola PII può instradare entità diverse verso azioni diverse tramite entity_actions, invece di impilare regole sovrapposte. Ogni valore di override deve essere uno tra block / mask / flag / annotate, e deve riferirsi a un’entità che la regola già dichiara — il validator rifiuta qualsiasi altra cosa. 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Questa unica regola maschera email, telefoni e IP ma blocca del tutto la richiesta su un numero di carta o un SSN. Vedi entità PII personalizzate per sovrapporre i tuoi detector sotto lo stesso modello di override.

​
7. Scegliere l’azione giusta

Se vuoi…UsaEffetto
Fermare del tutto la richiestablockHTTP 400, nessuna quota, skip-retry
Rimuovere una sottostringa, mantenere la chiamatamaskTesto redatto inoltrato
Osservare senza toccare il trafficoflagSolo match registrato
Le azioni si compongono con gli stage. La stessa azione si comporta leggermente diversamente su input vs output — un block di input risparmia quota in anticipo; un block di output la rimborsa; il masking di output si applica solo alle risposte non in streaming, mentre un block di output interrompe sia le risposte in streaming che quelle non in streaming. Leggi stage di input e stage di output accanto a questa pagina.

​
8. Dove andare dopo

L'errore guardrail_blocked

Com’è fatto un 400, perché non costa quota e come funziona lo skip-retry.

Formati di masking

Tag tipizzati, stringhe di sostituzione personalizzate, e com’è un prompt mascherato per il modello.

Streaming coverage

Esattamente quali combinazioni azione × stage × stream sono applicate oggi.

Modalità di enforcement

Come block / mask / flag si mappano sul modello di enforcement più ampio del gateway, incluso il verdetto di audit del firewall.
Il firewall ha il proprio vocabolario di verdetti (allow, audit, deny, sanitize, e altri) per la policy di tool — distinto da queste azioni di contenuto. Vedi guardrails vs. firewall.