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
Creare un guardrail
/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
Testarlo nella sandbox
input ed esegui. La sandbox mostra il
verdetto e il testo renderizzato — email me at [EMAIL] — senza inviare
nulla upstream.Collegare una chiave
/console/token, crea o modifica una chiave API e seleziona
pii-shield dal menu a tendina Guardrail. Il binding vive sulla chiave
nel gateway.Inviare una richiesta
[EMAIL] prima di inoltrare. Il modello
upstream non vede mai l’indirizzo.3. Concetti: guardrails, regole, stage, azioni
| Concetto | Definizione |
|---|---|
| Guardrail | Una policy nominata, con scope a livello di workspace. Identificatore: name (≤ 64 caratteri). Ha enabled, is_default e un blob JSON rules. |
| Regola | Un controllo all’interno di una policy: un type, uno stage, un’action, più campi specifici per tipo. Le regole girano in ordine. |
| Stage | input (la richiesta), output (la risposta del modello), o both. |
| Azione | block (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:- Collegamento della chiave — se la chiave ha un
guardrail_idesplicito, quel guardrail si applica (quando esiste ed è abilitato). Un collegamento esplicito non fa mai fallback silenzioso; disabilitarlo è l’interruttore di spegnimento. - Default del workspace — se la chiave non ha collegamento, si applica il
guardrail
is_defaultabilitato del workspace. - Nessuno dei due — nessuna applicazione. La richiesta è byte-identica a un workspace che non ha mai abilitato la feature.
Com’è fatto un block
Una richiesta bloccata restituisce HTTP 400 con codice di erroreguardrail_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).| Tipo | Gruppo | Cosa fa |
|---|---|---|
Keyword denylist (keyword) | Integrata | Corrisponde 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) | Integrata | Corrisponde a un pattern RE2 (tempo lineare, nessuna backreference). |
PII detection (pii) | Integrata | Rileva i tipi di entità integrati (e i tuoi personalizzati). Vedi §5. |
Maximum length (max_chars) | Integrata | Limita il numero di caratteri del testo in uno stage. |
External vendor (external) | Avanzata | Delega il controllo a un vendor connesso (Aporia, Averta, BYO-webhook, …). Vedi §9. |
LLM judge (llm_judge) | Avanzata | Esegue un controllo semantico contro un modello nel tuo workspace. Vedi §6. |
Contextual grounding (grounding) | Avanzata | Valuta la fedeltà della risposta rispetto alle sorgenti recuperate sulla richiesta (RAG). Vedi §7. |
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 regolapii 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;luhnvalida il match con l’algoritmo di Luhn (es. per numeri simili a carte).mask_with— sostituzione verbatim opzionale; per default[<UPPERCASE_NAME>].
Override di azione per entità
Una singola regola PII può applicare azioni diverse a entità diverse tramiteentity_actions. Una regola che maschera email / phone / IP per default ma
blocca su credit_card o ssn — invece di tre regole sovrapposte:
block / mask / flag. Il validator rifiuta qualsiasi altra cosa.
6. LLM judge
Una regolallm_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.
| Campo | Significato |
|---|---|
judge_model | Il modello o alias del router con cui valutare (es. gpt-4o-mini, orcarouter/cheap). Risolto contro i canali del tuo workspace. |
judge_rubric | Il system prompt che descrive cosa segnalare. |
judge_format | Uno tra yes_no, score o category (obbligatorio; la console pre-seleziona yes_no). |
judge_threshold | Per score: blocca/segnala quando il punteggio è pari o superiore a questo valore. |
judge_categories | Per category: l’elenco vietato. |
judge_timeout_ms | Limita la chiamata al judge. 0 → default del motore. |
judge_fail_open | true (default) → un errore del judge viene osservato ma la richiesta continua; false → tratta errore/timeout come un block. |
7. Contextual grounding
Una regolagrounding 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.
| Campo | Default | Significato |
|---|---|---|
grounding_model | scelta del workspace | Il modello a cui il runner risolve il controllo di fedeltà. |
grounding_rubric | integrata | Sovrascrive la rubric di fedeltà di default. |
grounding_threshold | 0.7 | Soglia minima di fedeltà, 0.0–1.0. Sotto di essa, l’azione scatta. |
grounding_strict | false | Quando true, “nessuna sorgente fornita” è trattato come un block (anziché l’allow di default). |
grounding_max_bytes | 100000 | Limita il contesto sorgente concatenato passato al judge. |
grounding_timeout_ms | 3000 | Limita 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.
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 regolaexternal 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
| Vendor | Che 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. |
- header di autenticazione + segreto HMAC.
Campi della regola
| Campo | Significato |
|---|---|
connection_id | L’integrazione connessa da usare (percorso consigliato — vendor + segreti si risolvono dall’integrazione del workspace a runtime). |
timeout_ms | Limita la singola chiamata al vendor. 0 → default. |
fail_open | true (default) → un errore del vendor viene osservato ma la richiesta continua; false → tratta errore di trasporto / timeout / provider sconosciuto come un block. |
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.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
| Superficie | Come si compone con i Guardrails? |
|---|---|
| Modelli | I guardrails sono agnostici rispetto al modello. La stessa policy viaggia su GPT-5, Claude, Gemini — filtra il testo, non la scelta del modello. |
| Routing | Indipendente. 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. |
| Prompts | Indipendenti 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 API | Una 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 Matches | Ogni 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’headerX-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 & path | Ruolo | Scopo |
|---|---|---|
GET /api/guardrail/ | Member | Elenca guardrails (con conteggi delle chiavi collegate). |
GET /api/guardrail/meta | Member | Vocabolario del motore — tipi di regola, stage, azioni, entità PII, preset, categorie di preset. |
GET /api/guardrail/my-permissions | Member | I permessi di guardrail del chiamante (per il gating dell’UI). |
GET /api/guardrail/:id | Member | Dettaglio di un singolo guardrail. |
GET /api/guardrail/:id/tokens | Member | Chiavi API collegate a questo guardrail (limitate, con totale reale). |
POST /api/guardrail/test | Member | Sandbox — 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/:id | Developer+ | Elimina un guardrail. |
History
| Metodo & path | Ruolo | Scopo |
|---|---|---|
GET /api/guardrail/:id/history | Member | Cronologia versioni (più recente per prima). |
GET /api/guardrail/:id/history/diff | Member | Confronta due versioni. |
GET /api/guardrail/:id/history/:version | Member | Una singola versione storica. |
POST /api/guardrail/:id/revert | Developer+ | Ripristina una versione più vecchia come nuova versione. |
Eval e corpora
| Metodo & path | Ruolo | Scopo |
|---|---|---|
POST /api/guardrail/:id/eval | Member | Esegui un eval su un corpus (nome incluso o JSONL caricato). |
GET /api/guardrail/:id/eval/runs | Member | Elenca le esecuzioni di eval per un guardrail (paginato). |
GET /api/guardrail/eval/runs/:run_id | Member | Dettaglio di una singola esecuzione di eval. |
GET /api/guardrail/eval/corpora | Member | Elenca i corpora del workspace + i corpora inclusi. |
POST /api/guardrail/eval/corpora | Developer+ | Carica un corpus JSONL. |
GET /api/guardrail/eval/corpora/:id | Member | Dettaglio del corpus. |
DELETE /api/guardrail/eval/corpora/:id | Developer+ | Elimina un corpus. |
Matches
| Metodo & path | Ruolo | Scopo |
|---|---|---|
GET /api/guardrail/match | Member | Elenca i match (con scope a livello di workspace). |
GET /api/guardrail/match/grouped | Member | Match raggruppati (es. per regola o guardrail). |
GET /api/guardrail/match/stats | Member | Stats dei match (supporta ?days= e ?group_by=). |
GET /api/guardrail/match/export | Member | Esporta i match come CSV. |
GET /api/guardrail/match/:id | Member | Dettaglio di un singolo match. |
POST /api/guardrail/match/:id/mark-fp | Admin | Segna un match come falso positivo (rate-limited). |
DELETE /api/guardrail/match/:id/mark-fp | Admin | Rimuovi il segno di falso positivo (rate-limited). |
Collegare una chiave
Impostaguardrail_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
Cosa succede se nessun guardrail si risolve su una richiesta?
Cosa succede se nessun guardrail si risolve su una richiesta?
Una richiesta bloccata costa quota?
Una richiesta bloccata costa quota?
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).Le regole di output (risposta) vengono applicate sullo streaming?
Le regole di output (risposta) vengono applicate sullo streaming?
Qual è la differenza tra mask e block?
Qual è la differenza tra mask e block?
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.I token dei prompt iniettati e i token del judge vengono fatturati?
I token dei prompt iniettati e i token del judge vengono fatturati?
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.Come vedo cosa una regola ha effettivamente matchato?
Come vedo cosa una regola ha effettivamente matchato?
Posso fare il rollback di una modifica a un guardrail?
Posso fare il rollback di una modifica a un guardrail?
Cosa succede se un vendor esterno o un judge va in timeout?
Cosa succede se un vendor esterno o un judge va in timeout?
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.