Vai al contenuto principale
Un guardrail è il layer di content-policy del gateway OrcaRouter. Scrivi una policy nominata nel tuo workspace, la colleghi a una chiave API, e ogni chiamata /v1/* fatta da quella chiave viene filtrata — prima che il modello veda il prompt e dopo che il modello risponde — senza redeploy e senza modifiche all’SDK. Questa pagina è l’hub della sezione Guardrails: cos’è un guardrail, i tipi di regola, gli stage e le azioni, e come una policy si collega a una chiave. Ogni spoke approfondisce. Per il riferimento completo del motore, vedi Guardrails.

​
1. Cosa fanno i guardrails AI sul gateway

La maggior parte dei team ricorre ai guardrails per tenere i dati sensibili fuori dai prompt (PII, segreti), per gestire contenuti non sicuri (jailbreak, intento di prompt-injection), o per soddisfare un controllo di compliance. Un guardrail è la risposta del gateway: una policy nominata, con scope a livello di workspace — un elenco ordinato di regole che il gateway esegue sull’input della richiesta e sull’output del modello. Poiché il binding vive sulla chiave API nel gateway — non nella tua applicazione — modificare un guardrail sposta ogni chiave collegata alla chiamata successiva. Il tuo codice continua a chiamare /v1/chat/completions esattamente come prima.
I guardrails sono una policy di contenuto (testo in entrata, testo in uscita). L’Agent Firewall complementare è una policy di tool — governa quali chiamate a tool un agent può effettuare. I due si compongono; vedi Guardrails vs. firewall.

​
2. Un esempio concreto

Crea un guardrail chiamato pii-shield nella console (/console/guardrails), aggiungi una singola regola PII — stage input, azione mask, entità email, ssn — e collegala a una chiave. Da quel momento in poi: 
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 please"}
    ]
  }'
Il gateway riscrive il prompt in Reply to [EMAIL] please prima di inoltrare — il modello upstream non vede mai l’indirizzo. Porta quell’entità ssn su block e la richiesta successiva che contiene un SSN viene rifiutata con HTTP 400. Nessuna modifica all’applicazione.
La scrittura è un’azione di console / management-API sulla tua sessione — la chiave di relay sk-orca-... serve solo per il traffico /v1/*, mai per modificare la policy. Creare o modificare un guardrail richiede il ruolo Developer+.

​
3. Regole: type, stage, action

Ogni regola risponde a tre domande. Il motore esegue tutte le regole applicabili e le ripiega in un’unica decisione.
Sette tipi di regola. Quelli integrati sono deterministici (pure stringa/regex, nessuna rete); quelli avanzati effettuano chiamate verso un modello o vendor e girano in modo concorrente.
  • keyword — denylist letterale, match per sottostringa senza distinzione tra maiuscole e minuscole.
  • regex — un pattern RE2 (tempo lineare, nessuna backreference).
  • pii — detector di entità integrati più i tuoi. Vedi §5.
  • max_chars — limita il numero di caratteri in uno stage.
  • external — delega a un vendor connesso (Aporia, Averta, o il tuo webhook).
  • llm_judge — un controllo semantico contro un modello nel tuo workspace.
  • grounding — valuta la fedeltà della risposta rispetto alle sorgenti recuperate sulla richiesta (RAG).
input (la richiesta), output (la risposta del modello), o both. Le regole di input girano prima della chiamata upstream; le regole di output girano dopo che il modello risponde. Vedi input stage e output stage.
Cinque azioni emergono nel rule builder:
  • block — rifiuta la chiamata con HTTP 400.
  • mask — redige il match e lascia passare il testo sanitizzato.
  • flag — non cambia nulla del traffico; registra solo il match.
  • annotate — lascia il testo intatto ma inietta una nota di sicurezza upstream (es. un avviso CVE prima che il modello risponda).
  • spotlight — avvolge il testo non attendibile corrispondente in delimitatori e dice al modello di trattarlo come dati, non come istruzioni.
Vedi Azioni. Usa flag per misurare una regola sul traffico reale prima di applicarla.

​
4. Come un guardrail si collega e si risolve

Un guardrail si lega a una chiave tramite guardrail_id, oppure un workspace può marcare un guardrail come suo default. Per ogni richiesta il gateway risolve in quest’ordine:
  1. Collegamento esplicito — se il guardrail_id della chiave punta a un guardrail che esiste ed è abilitato, si applica quello. Un collegamento esplicito non fa mai fallback: disabilitarlo è l’interruttore di spegnimento.
  2. Default del workspace — se la chiave non ha collegamento, si applica il guardrail di default abilitato.
  3. Nessuno dei due — nessuna applicazione; la richiesta è byte-identica a un workspace che non ha mai attivato la feature.
Questo differisce dal firewall. Una policy del firewall collegata e disabilitata fa fallback al default del workspace; un guardrail collegato e disabilitato va a nessuno. L’interruttore di spegnimento è letterale per i guardrails.
Walkthrough: crea il tuo primo guardrail, collega a una chiave, imposta un default di account.

​
5. PII detectors

Una regola pii porta un insieme chiuso 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. Su un’azione mask ogni match diventa un tag tipizzato — un’email viene renderizzata come [EMAIL], un SSN come [SSN]. Puoi sovrapporre fino a 25 entità personalizzate per regola (una regex con checksum Luhn opzionale), e instradare entità diverse verso azioni diverse in una sola regola tramite override per entità.
Il punto di partenza chiavi-in-mano è il preset PII Shield — una singola regola pii, mask, stage both. Il masking nello stage di input riscrive la richiesta prima del modello (in streaming o meno); il masking dell’output riscrive la risposta solo sulle risposte non in streaming — la riscrittura in-stream dell’output è nella roadmap. Vedi PII Shield, entità personalizzate e formati di masking.

​
6. Il selettore di preset

New guardrail apre direttamente su un template. I preset sono creati lato server, così la console, la sandbox e questi docs descrivono lo stesso comportamento. Il selettore li raggruppa in categorie:
CategoriaPreset di esempioSpoke
pii / secretsPII Shield, blocker di credenziali segreteblock secrets
safetyprompt-injection, jailbreak, autolesionismoprompt injection
complianceGDPR, PCI, HIPAA, compliance loggercompliance logger
brand / costturpiloquio, menzioni di concorrenti, limiti di dimensionebrand safety · cost
agentfiltri URL / shell-tool / SQL-nell’outputagentic
code_securityblock di file segreti, review di licenze copyleftcode security
Un preset è un seme, non un lucchetto — applicalo, poi modificalo liberamente. Altri punti di partenza vivono sotto templates.

​
7. Quando un guardrail blocca

Una richiesta bloccata restituisce HTTP 400 con codice di errore guardrail_blocked e un messaggio che nomina il guardrail e la regola che ha scattato.
  • Nessuna quota viene addebitata. Un block nello stage di input scatta prima della misurazione; un block nello stage di output rimborsa la quota pre-consumata.
  • La richiesta è marcata skip-retry — rieseguire lo stesso prompt si limiterebbe a bloccarlo di nuovo, quindi il gateway non sprecherà un retry su un altro canale.
Sullo streaming, block viene applicato best-effort — uno scanner mette in buffer un piccolo lookahead e interrompe lo stream quando una regola scatta, così i byte già emessi non possono essere ritirati. Mask sull’output si applica solo alle risposte non in streaming — su una risposta in streaming il gateway calcola la maschera ma non inoltra il testo redatto; la riscrittura in-stream dell’output è nella roadmap. (Il masking nello stage di input è attivo sia in streaming che non.) Vedi l’errore guardrail_blocked e streaming coverage.

​
8. Dopo che è attivo

Feed dei match

Ogni regola che scatta registra type, action, stage e detail. Raggruppa, filtra, esporta e scendi in profondità su un singolo match.

Logging e privacy

La sottostringa corrispondente viene registrata solo quando Log raw content è attivo — disattivato per default, la postura conservativa sulla privacy.

Versioning

Ogni modifica scrive una riga di cronologia. Confronta due versioni qualsiasi e ripristina come nuova versione — la cronologia non viene mai mutata.

Testing ed eval

Una tab Test sandbox valuta la policy corrente senza chiamata upstream, e un harness di eval la valuta contro corpora inclusi o personalizzati.
Un falso positivo è un segnale di tuning, non un motivo per disabilitare la regola. Segnalalo nel feed dei Matches e restringi il pattern — vedi tuning dei falsi positivi.

​
9. Dove andare dopo

Guardrails — ogni campo, ogni rotta, le regole LLM-judge e grounding, e gli external vendor in profondità.