Vai al contenuto principale
Una volta che hai un workspace e una chiave API (vedi Introduzione), i guardrails sono il modo in cui metti una content policy davanti a ogni modello. Questa pagina è il riferimento canonico per il motore di guardrail di OrcaRouter — cos’è, come usarlo e come si compone con il resto del gateway.

1. Cos’è il motore di guardrail

Un guardrail è una content 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. Salvi un guardrail una volta, colleghi qualsiasi chiave API ad esso (o ne imposti uno come default del workspace), e il gateway filtra ogni chiamata prima e dopo il modello upstream. Ogni regola decide una cosa — cosa cercare (un tipo di regola), dove cercare (uno stage: input della richiesta o output del modello), e cosa farne (un’azione: block, mask o flag). Il motore esegue ogni regola applicabile e raccoglie i risultati in un’unica decisione. Modificare un guardrail ha effetto su ogni chiave ad esso collegata alla chiamata successiva. Nessun redeploy. Nessuna modifica al codice. Nessun upgrade dell’SDK. La policy vive nel gateway, non nella tua applicazione — la tua app continua a chiamare /v1/chat/completions esattamente come prima. Il motore è deterministico e privo di dipendenze per i tipi di regola integrati: puro matching di stringhe e regex senza chiamate di rete, sicuro da eseguire sull’hot path del relay. Le regole avanzate (vendor esterni, LLM judge, contextual grounding) effettuano chiamate verso l’esterno e vengono dispatchate in modo concorrente così che un controllo lento non si serializzi mai dietro un altro. I guardrails hanno scope a livello di workspace — ogni membro vede i guardrails del workspace; nulla attraversa i confini di tenant.

2. Quickstart — filtra la tua prima richiesta in 5 passi

1

Creare un guardrail

Nella console, vai su /console/guardrails e fai clic su New guardrail. Chiamalo pii-shield. Aggiungi una regola:
  • Type: PII detection
  • Stage: Input (richiesta)
  • Action: Mask — redige il match
  • Entities: email, phone, ssn
Salva.
2

Testarlo nella sandbox

Apri la tab Test all’interno dell’editor, incolla “email me at jane@acme.com, scegli lo stage input ed esegui. La sandbox mostra il verdetto e il testo renderizzato — email me at [EMAIL] — senza inviare nulla upstream.
3

Collegare una chiave

Vai su /console/token, crea o modifica una chiave API e seleziona pii-shield dal menu a tendina Guardrail. Il binding vive sulla chiave nel gateway.
4

Inviare una richiesta

Usando quella chiave, chiama OrcaRouter esattamente come prima:
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 maschera l’email in [EMAIL] prima di inoltrare. Il modello upstream non vede mai l’indirizzo.
5

Irrigidire la policy

Di nuovo in /console/guardrails, modifica pii-shield — cambia l’azione su ssn in Block tramite override per entità. Salva. La richiesta immediatamente successiva che contiene un SSN viene rifiutata con HTTP 400 guardrail_blocked. Nessuna modifica all’applicazione.
Questo è il valore principale.

3. Concetti: guardrails, regole, stage, azioni

ConcettoDefinizione
GuardrailUna policy nominata, con scope a livello di workspace. Identificatore: name (≤ 64 caratteri). Ha enabled, is_default e un blob JSON rules.
RegolaUn controllo all’interno di una policy: un type, uno stage, un’action, più campi specifici per tipo. Le regole girano in ordine.
Stageinput (la richiesta), output (la risposta del modello), o both.
Azioneblock (rifiuta la chiamata), mask (redige il match), o flag (solo log — osserva senza modificare il traffico).

Scoping e il default del workspace

I guardrails hanno scope esattamente come le chiavi API: condivisi a livello di workspace quando hai un workspace attivo, per-utente altrimenti. Risoluzione per ogni richiesta:
  1. Collegamento della chiave — se la chiave ha un guardrail_id esplicito, quel guardrail si applica (quando esiste ed è abilitato). Un collegamento esplicito non fa mai fallback silenzioso; disabilitarlo è l’interruttore di spegnimento.
  2. Default del workspace — se la chiave non ha collegamento, si applica il guardrail is_default abilitato del workspace.
  3. Nessuno dei due — nessuna applicazione. La richiesta è byte-identica a un workspace che non ha mai abilitato la feature.
Al massimo un guardrail per workspace può essere il default. Promuovere un nuovo default declassa il vecchio nella stessa transazione.
Fail-open by design. Se la risoluzione del guardrail incontra un errore transitorio (es. un singhiozzo del DB), il gateway degrada a nessuna applicazione anziché mettere giù il traffico. La sicurezza degrada; la disponibilità è preservata.

Com’è fatto un block

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. Una richiesta bloccata non ti costa quota — un block nello stage di input scatta prima della misurazione, e un block nello stage di output rimborsa la quota pre-consumata — ed è marcata come skip-retry (rieseguire lo stesso prompt si limiterebbe a bloccarlo di nuovo).

4. Tipi di regola

Le regole rientrano in due gruppi: integrate (deterministiche, nessuna rete) e avanzate (effettuano chiamate verso un modello o vendor).
TipoGruppoCosa fa
Keyword denylist (keyword)IntegrataCorrisponde a uno qualsiasi di un elenco di termini letterali — senza distinzione tra maiuscole e minuscole, con corrispondenza per sottostringa (quindi class corrisponde anche a classic).
Regular expression (regex)IntegrataCorrisponde a un pattern RE2 (tempo lineare, nessuna backreference).
PII detection (pii)IntegrataRileva i tipi di entità integrati (e i tuoi personalizzati). Vedi §5.
Maximum length (max_chars)IntegrataLimita il numero di caratteri del testo in uno stage.
External vendor (external)AvanzataDelega il controllo a un vendor connesso (Aporia, Averta, BYO-webhook, …). Vedi §9.
LLM judge (llm_judge)AvanzataEsegue un controllo semantico contro un modello nel tuo workspace. Vedi §6.
Contextual grounding (grounding)AvanzataValuta la fedeltà della risposta rispetto alle sorgenti recuperate sulla richiesta (RAG). Vedi §7.
Un guardrail mescola un numero qualsiasi di regole di qualsiasi tipo. Le regole avanzate (external, llm_judge, grounding) sono dispatchate in modo concorrente così che un controllo lento non si serializzi dietro un altro.

5. PII detection in dettaglio

Una regola pii rileva entità sensibili e applica l’azione della regola a ogni match. L’insieme di detector integrati è chiuso e condiviso dal motore, dal validator e dal rule builder: email, phone, credit_card, ssn, ip, iban, mac_address, api_key_openai, aws_access_key, jwt, bitcoin_address. Su un’azione mask, ogni match viene sostituito con un tag tipizzato — un’email diventa [EMAIL], un SSN diventa [SSN], e così via.

Entità personalizzate

Sovrapponi i tuoi detector all’insieme integrato. Un’entità personalizzata è:
  • name — ASCII minuscolo / cifre / underscore, deve iniziare con una lettera (es. employee_id). Confluisce negli audit log e nella telemetria senza virgolette.
  • pattern — una regex Go RE2 (tempo lineare, nessuna backreference).
  • checksum — opzionale; luhn valida il match con l’algoritmo di Luhn (es. per numeri simili a carte).
  • mask_with — sostituzione verbatim opzionale; per default [<UPPERCASE_NAME>].
Fino a 25 entità personalizzate per regola (ognuna è una scansione regex su tutto il testo, quindi il limite mantiene l’hot path lineare). I pattern compilati sono in cache tra le richieste.

Override di azione per entità

Una singola regola PII può applicare azioni diverse a entità diverse tramite entity_actions. Una regola che maschera email / phone / IP per default ma blocca su credit_card o ssn — invece di tre regole sovrapposte:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Le chiavi devono essere un’entità abilitata sulla regola; i valori devono essere block / mask / flag. Il validator rifiuta qualsiasi altra cosa.

6. LLM judge

Una regola llm_judge esegue un controllo semantico contro un modello che il tuo workspace può già chiamare. Usala per policy sfumate che nessuna regex cattura — tossicità, molestie, fuori tema, intento di prompt-injection.
CampoSignificato
judge_modelIl modello o alias del router con cui valutare (es. gpt-4o-mini, orcarouter/cheap). Risolto contro i canali del tuo workspace.
judge_rubricIl system prompt che descrive cosa segnalare.
judge_formatUno tra yes_no, score o category (obbligatorio; la console pre-seleziona yes_no).
judge_thresholdPer score: blocca/segnala quando il punteggio è pari o superiore a questo valore.
judge_categoriesPer category: l’elenco vietato.
judge_timeout_msLimita la chiamata al judge. 0 → default del motore.
judge_fail_opentrue (default) → un errore del judge viene osservato ma la richiesta continua; false → tratta errore/timeout come un block.
La chiamata al judge passa per i canali del tuo workspace, quindi i suoi token sono fatturati e attribuiti come qualsiasi altra chiamata (come una sub-riga del judge). Il motore aggiunge un’appendice JSON-schema alla tua rubric così che il modello restituisca output parseabile.

7. Contextual grounding

Una regola grounding misura la risposta dell’assistant rispetto alle sorgenti recuperate sulla richiesta (il tuo contesto RAG) e segnala o blocca risposte che non vi sono fedeli. Riutilizza il seam del judge — stessi canali del workspace, stessa attribuzione di costo.
CampoDefaultSignificato
grounding_modelscelta del workspaceIl modello a cui il runner risolve il controllo di fedeltà.
grounding_rubricintegrataSovrascrive la rubric di fedeltà di default.
grounding_threshold0.7Soglia minima di fedeltà, 0.01.0. Sotto di essa, l’azione scatta.
grounding_strictfalseQuando true, “nessuna sorgente fornita” è trattato come un block (anziché l’allow di default).
grounding_max_bytes100000Limita il contesto sorgente concatenato passato al judge.
grounding_timeout_ms3000Limita la chiamata al judge.

8. Template, la sandbox e l’harness di eval

Libreria di template

Lo split-button New guardrail apre direttamente su un template, e la libreria completa è a un clic di distanza. I preset sono creati lato server così che la console, la sandbox e questi docs descrivano lo stesso identico comportamento. Le categorie includono:
  • PII (pii) — PII Shield, PII Blocker (strict), Contact-Info Redactor, response PII redactor.
  • Secrets (secrets) — blocker di credenziali AWS / OpenAI / GitHub, chiavi private e token cloud, wallet crypto, secret nell’output.
  • Compliance (compliance) — GDPR (PII UE), PCI (block completo delle carte), HIPAA (PHI), dati finanziari, compliance logger, enforcement di disclaimer legali.
  • Brand (brand) — turpiloquio (block / mask / multilingue), menzioni di concorrenti, keyword di sicurezza dei minori.
  • Safety (safety) — prompt-injection, jailbreak, system-prompt-leak, autolesionismo.
  • Cost (cost) — limiti di dimensione di prompt/risposta e limiti di token.
  • Agent (agent) — filtri URL, markdown-image, shell-tool-call e SQL-injection nell’output.
Applica un preset come punto di partenza, poi modificalo liberamente — un preset è un seme, non un lucchetto.

La sandbox di test

Ogni editor ha una tab Test. Incolla un campione, scegli uno stage ed esegui la policy corrente localmente — nessuna chiamata upstream, nessuna quota. La sandbox restituisce il verdetto e (per le regole mask) il testo renderizzato, così puoi dimostrare che una regola fa ciò che ti aspetti prima di collegare una chiave.

Harness di eval / red-team

La tab Eval esegue un guardrail contro un corpus di input e riporta come ha ottenuto il punteggio — utile per mettere a punto una rubric del judge o per dimostrare che una policy cattura attacchi noti prima di metterla in produzione.
  • I corpora inclusi sono forniti con il gateway — set avversariali e red-team (prompt di comportamento dannoso, tool-injection, red-teaming multilingue) più set benigni per misurare i falsi positivi.
  • Corpora personalizzati — carica il tuo JSONL per testare contro le forme reali del tuo traffico.
  • Le esecuzioni sono elencate con i loro punteggi; apri un’esecuzione per ispezionare i fallimenti campione per campione.

9. External vendors

Una regola external delega il controllo a un vendor connesso. Connetti un vendor una volta sotto Integrations (la CTA nell’header della pagina Guardrails), poi referenzia la connessione da una regola.

Vendor supportati

VendorChe cos’è
Aporia Guardrails (aporia)Motore di policy a ensemble di SLM per prompt e risposte.
Averta (averta)Endpoint generico di classificatore SLM (POST del testo → safe / unsafe + riscrittura opzionale).
BYO Webhook (webhook)Il tuo URL — ricevi i prompt e restituisci verdetti allow / block / mask / flag.
Aporia e Averta richiedono un URL base + chiave API; il webhook richiede un URL
  • header di autenticazione + segreto HMAC.

Campi della regola

CampoSignificato
connection_idL’integrazione connessa da usare (percorso consigliato — vendor + segreti si risolvono dall’integrazione del workspace a runtime).
timeout_msLimita la singola chiamata al vendor. 0 → default.
fail_opentrue (default) → un errore del vendor viene osservato ma la richiesta continua; false → tratta errore di trasporto / timeout / provider sconosciuto come un block.
I segreti sono memorizzati cifrati e mascherati in lettura. La chiamata di controllo porta la cancellazione della richiesta di relay, così che una richiesta cancellata non lasci una chiamata al vendor appesa.

10. Osservabilità

I guardrails lasciano briciole di pane su cui puoi agire.

Feed dei match

Ogni regola che scatta registra un match — tipo di regola, azione, una stringa di dettaglio, lo stage e (quando abilitata) la sottostringa corrispondente. La tab Matches sulla pagina Guardrails è il feed a livello di workspace: elenca, raggruppa, filtra, scendi in profondità su un singolo match, esporta in CSV e segnala i falsi positivi.
La cattura del contenuto grezzo è opt-in. Il toggle Log raw content di un guardrail è disattivato per default — la postura conservativa sulla privacy. Con esso disattivato, il feed dei Matches registra che una regola è scattata e la sua meta-stringa di dettaglio, ma non la sottostringa effettivamente corrispondente (es. l’indirizzo email stesso). Attivalo per ciascun guardrail quando ti serve la sottostringa per il triage; l’impostazione non è retroattiva.

Stats

Il feed dei Matches alimenta le stats per guardrail — ogni card di guardrail mostra una sparkline e un conteggio dei match a 7 giorni, e la tab Matches porta un totale di workspace. Per segmentare l’attività per policy, usa la vista raggruppata e i filtri del feed dei Matches (per guardrail, tipo di regola, azione) — è lì che vivono l’utilizzo per guardrail, il mix di azioni e il tasso di falsi positivi.

Cronologia delle versioni e audit

Ogni create, update e delete scrive una riga di cronologia versionata nella stessa transazione della modifica. Apri History su una riga di guardrail per:
  • Vedere ogni versione con chi l’ha modificata e quando.
  • Confrontare due versioni qualsiasi.
  • Ripristinare una versione più vecchia (registrata come nuova versione — la cronologia non viene mai mutata).

11. Relazione con il resto del gateway

SuperficieCome si compone con i Guardrails?
ModelliI guardrails sono agnostici rispetto al modello. La stessa policy viaggia su GPT-5, Claude, Gemini — filtra il testo, non la scelta del modello.
RoutingIndipendente. Il routing decide quale modello/canale serve la richiesta; i guardrails filtrano lo stesso testo di richiesta/risposta a prescindere e non sovrascrivono mai la selezione del modello. Il filtro di input gira prima della chiamata upstream, il filtro di output dopo che il modello ha risposto. Le regole di judge e grounding risolvono il proprio modello tramite i canali del workspace, separatamente dal routing della richiesta.
PromptsIndipendenti e complementari. Prompts iniettano un messaggio di sistema; i guardrails ispezionano e gestiscono il contenuto. Entrambi possono applicarsi a una stessa richiesta e i guardrails girano sempre. L’ordine conta: le regole di input filtrano la richiesta del chiamante prima che venga iniettato un prompt del registry (l’iniezione avviene più tardi, nella fase di routing), quindi le regole di input vedono i messaggi del chiamante, non il prompt di sistema iniettato; le regole di output filtrano la risposta del modello in entrambi i casi.
Chiavi APIUna chiave si collega a un guardrail tramite guardrail_id. Il binding vive sulla chiave nel gateway, quindi modificare il guardrail sposta tutte le chiavi collegate contemporaneamente; nessun collegamento fa fallback al default del workspace.
Feed dei MatchesOgni regola che scatta finisce nel feed dei Matches del workspace (un proprio store, separato dal request log). Raggruppalo e filtralo per guardrail, tipo di regola e azione per vedere utilizzo, mix di azioni e tasso di falsi positivi per guardrail.

12. Riferimento API

Tutte le rotte hanno scope a livello di workspace tramite l’header X-Workspace-Id. RBAC viene applicato in modo coerente: le letture e la sandbox di test sono aperte a ogni membro; le scritture richiedono Developer+ (e il permesso guardrails:write); le modifiche al traffico di produzione (delete, revert, configurazione vendor) sono gestite di conseguenza.

Guardrails

Metodo & pathRuoloScopo
GET /api/guardrail/MemberElenca guardrails (con conteggi delle chiavi collegate).
GET /api/guardrail/metaMemberVocabolario del motore — tipi di regola, stage, azioni, entità PII, preset, categorie di preset.
GET /api/guardrail/my-permissionsMemberI permessi di guardrail del chiamante (per il gating dell’UI).
GET /api/guardrail/:idMemberDettaglio di un singolo guardrail.
GET /api/guardrail/:id/tokensMemberChiavi API collegate a questo guardrail (limitate, con totale reale).
POST /api/guardrail/testMemberSandbox — valuta una policy su testo di esempio in uno stage. Nulla viene persistito.
POST /api/guardrail/Developer+Crea un guardrail.
PUT /api/guardrail/Developer+Aggiorna un guardrail (scrive una nuova versione di cronologia).
DELETE /api/guardrail/:idDeveloper+Elimina un guardrail.

History

Metodo & pathRuoloScopo
GET /api/guardrail/:id/historyMemberCronologia versioni (più recente per prima).
GET /api/guardrail/:id/history/diffMemberConfronta due versioni.
GET /api/guardrail/:id/history/:versionMemberUna singola versione storica.
POST /api/guardrail/:id/revertDeveloper+Ripristina una versione più vecchia come nuova versione.

Eval e corpora

Metodo & pathRuoloScopo
POST /api/guardrail/:id/evalMemberEsegui un eval su un corpus (nome incluso o JSONL caricato).
GET /api/guardrail/:id/eval/runsMemberElenca le esecuzioni di eval per un guardrail (paginato).
GET /api/guardrail/eval/runs/:run_idMemberDettaglio di una singola esecuzione di eval.
GET /api/guardrail/eval/corporaMemberElenca i corpora del workspace + i corpora inclusi.
POST /api/guardrail/eval/corporaDeveloper+Carica un corpus JSONL.
GET /api/guardrail/eval/corpora/:idMemberDettaglio del corpus.
DELETE /api/guardrail/eval/corpora/:idDeveloper+Elimina un corpus.

Matches

Metodo & pathRuoloScopo
GET /api/guardrail/matchMemberElenca i match (con scope a livello di workspace).
GET /api/guardrail/match/groupedMemberMatch raggruppati (es. per regola o guardrail).
GET /api/guardrail/match/statsMemberStats dei match (supporta ?days= e ?group_by=).
GET /api/guardrail/match/exportMemberEsporta i match come CSV.
GET /api/guardrail/match/:idMemberDettaglio di un singolo match.
POST /api/guardrail/match/:id/mark-fpAdminSegna un match come falso positivo (rate-limited).
DELETE /api/guardrail/match/:id/mark-fpAdminRimuovi il segno di falso positivo (rate-limited).

Collegare una chiave

Imposta guardrail_id sulla chiave API (tramite l’editor della chiave o la token API). 0/null significa nessun collegamento esplicito — la chiave fa fallback al guardrail di default del workspace, se ne è impostato uno.

13. FAQ

Il comportamento è byte-identico a un workspace che non ha mai abilitato la feature. Se la chiave non è collegata e nessun default di workspace è impostato, il gateway non effettua alcuna modifica. Nulla viene bloccato, mascherato o loggato nel feed dei Matches.
No. Un block nello stage di input scatta prima che l’utilizzo venga misurato; un block nello stage di output rimborsa la quota pre-consumata dopo che la risposta è stata rifiutata. In entrambi i casi il chiamante non paga quota, riceve HTTP 400 guardrail_blocked e la richiesta è marcata come skip-retry (rieseguire lo stesso prompt contro un altro canale si limiterebbe a bloccarlo di nuovo).
Dipende dall’azione. Il block viene applicato in entrambi i casi: su una risposta non in streaming la risposta viene esaminata prima di essere restituita, mentre 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. Il mask sull’output attualmente si applica solo alle risposte non in streaming — su una risposta in streaming il chunk originale passa senza essere mascherato (la riscrittura in-band dello stream è un miglioramento pianificato). Per il masking dell’output oggi, usa richieste non in streaming oppure affidati al masking nello stage di input. Dimostra la tua specifica combinazione stage/stream nella sandbox e con un’esecuzione di eval prima di fare affidamento su di essa.
Mask redige il match (es. jane@acme.com[EMAIL]) e lascia passare la richiesta con il testo sanitizzato — il modello upstream non vede mai l’originale. Block rifiuta l’intera richiesta con HTTP 400. Flag non cambia nulla del traffico e registra solo un match — usalo per misurare una regola prima di applicarla.
Una regola integrata (keyword / regex / PII / max_chars) non effettua alcuna chiamata al modello e non fattura nulla. Una regola llm_judge o grounding chiama un modello attraverso i canali del tuo workspace, quindi quei token sono fatturati e attribuiti come una sub-riga del judge.
Attiva Log raw content per il guardrail. Con esso disattivato (il default), il feed dei Matches registra che una regola è scattata e la sua meta-stringa di dettaglio ma non la sottostringa corrispondente — la postura conservativa sulla privacy. Il toggle non è retroattivo: influisce solo sui match registrati dopo che lo abiliti.
Sì. Apri History sul guardrail, confronta le versioni e Revert a quella che vuoi. Revert copia il contenuto di quella versione in avanti come una nuova versione — la cronologia non viene mai mutata — e la modifica ha effetto alla richiesta successiva.
Per default, le regole avanzate fanno fail open: un timeout o un errore di trasporto viene registrato come telemetria e la richiesta continua. Imposta fail_open (external) o judge_fail_open (judge) a false per fare fail closed — trattare l’errore come un block — per policy in cui un controllo mancato è inaccettabile.