Vai al contenuto principale
Il modo più rapido per mettere una content policy davanti a ogni chiamata al modello è un guardrail — una policy nominata, con scope a livello di workspace, che scrivi una volta nella console e colleghi a una chiave API. Il gateway poi filtra l’input della richiesta e l’output del modello alla chiamata successiva, senza redeploy e senza modifiche all’SDK. Questa pagina percorre il loop end-to-end: crea un guardrail, aggiungi una regola, testala nella sandbox, collegala a una chiave e invia una richiesta reale. Per il riferimento completo del motore — ogni tipo di regola, campo e rotta — vedi il riferimento Guardrails.
Ogni passaggio qui è un’azione di console sul gateway gestito (api.orcarouter.ai). La configurazione dei guardrail gira sotto la tua sessione; solo la chiamata /v1/* finale usa una chiave di relay sk-orca-.... Creare e modificare guardrails richiede Developer+ nel workspace.

​
1. Come aggiungere guardrails LLM in cinque passi

Ecco l’intero loop a colpo d’occhio — ogni passo è ampliato sotto.
1

Crea un guardrail

Nella console, apri Guardrails e fai clic su New guardrail. Dagli un nome (≤ 64 caratteri), es. pii-shield.
2

Aggiungi una regola

Aggiungi una regola PII detection nello stage input con l’azione mask.
3

Testala nella sandbox

Apri la tab Test, incolla un campione ed esegui la policy localmente — nessuna chiamata upstream, nessuna quota.
4

Collegala a una chiave

Modifica una chiave API e scegli il guardrail dal menu a tendina Guardrail. Il binding vive sulla chiave.
5

Invia una richiesta

Chiama /v1/chat/completions con quella chiave. Il gateway applica la policy prima di inoltrare.

​
2. Crea il guardrail

Nella console, apri Guardrails e fai clic su New 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. Chiamalo pii-shield e salva.
Lo split-button New guardrail apre anche direttamente su un template. Il preset PII Shield è una singola regola pii che maschera email, phone, ssn, credit_card e ip. Applicare un preset è un seme, non un lucchetto — modificalo liberamente dopo. Sfoglia i template preset per altri punti di partenza.

​
3. Aggiungi una regola

Ogni regola decide tre cose — cosa cercare (un tipo di regola), dove cercare (uno stage) e cosa fare (un’azione). Aggiungi una regola:
  • Type: PII detection (pii)
  • Stage: Input (la richiesta)
  • Action: Mask — redige il match
  • Entities: email, phone, ssn
Su un’azione mask, ogni match viene sostituito con un tag tipizzato — un’email diventa [EMAIL], un SSN diventa [SSN]. I sette tipi di regola (keyword, regex, pii, max_chars, external, llm_judge, grounding) e le cinque azioni (block, mask, flag, annotate, spotlight) sono coperti nel riferimento. Per questo primo guardrail, una regola di masking è sufficiente.
Il masking è attivo su entrambi gli stage. Le regole dello stage di input mascherano la richiesta prima che il modello la veda; le regole dello stage di output mascherano la risposta del modello — sulle risposte non in streaming e chunk-per-chunk su quelle in streaming — prima che il client la riceva. Block è applicato su entrambi gli stage. Se vuoi gestire le risposte del modello, imposta lo stage della regola su output (o both); vedi Regole dello stage di output.

​
4. Testala nella sandbox

Prima di collegare il guardrail a qualsiasi chiave, dimostra che fa ciò che ti aspetti. Apri la tab Test all’interno dell’editor, incolla un campione, scegli lo stage input ed esegui: 
Reply to jane@acme.com please
La sandbox valuta la policy corrente localmente e restituisce il verdetto più il testo renderizzato: 
Reply to [EMAIL] please
Nulla viene inviato upstream e nulla viene misurato. Per una griglia A/B contro un corpus di input, l’harness di eval vive una tab più in là.

​
5. Collegala a una chiave

Un guardrail non fa nulla finché una chiave non punta a esso. Due modi per legarlo:

Per chiave

Modifica una chiave API e scegli il guardrail dal menu a tendina Guardrail. Questo imposta guardrail_id sulla chiave. Vedi Collega a una chiave.

Default del workspace

Marca il guardrail come default del workspace così che ogni chiave senza un collegamento esplicito lo erediti. Vedi Default di account.
La risoluzione è esplicita e prevedibile:
OrdineCosa si applica
1Il guardrail_id esplicito della chiave (se esiste ed è abilitato).
2Il default del workspace (se la chiave non ha collegamento).
3Nessuno — la richiesta è byte-identica a un workspace senza policy.
Un collegamento esplicito non fa mai fallback silenzioso. Disabilitare un guardrail collegato è l’interruttore di spegnimento — non scende al default del workspace. (Le policy del firewall differiscono qui; vedi Guardrails vs. firewall.)

​
6. Invia una richiesta

Usando una chiave legata a pii-shield, chiama OrcaRouter esattamente come prima — nessuna modifica all’SDK, nessun nuovo header: 
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. Cambia l’azione della regola in block e la richiesta immediatamente successiva che contiene l’entità viene rifiutata con HTTP 400 guardrail_blocked. Una richiesta bloccata non costa quota (un block di input scatta prima della misurazione; un block di output rimborsa la quota pre-consumata) ed è marcata skip-retry. Vedi l’ errore guardrail_blocked per la forma completa della risposta.

​
7. Dove andare dopo

Ogni regola che scatta registra un match — type, action, stage e una stringa di detail. La sottostringa corrispondente viene registrata solo quando Log raw content è attivo (disattivato per default). Vedi il Feed dei match e Logging e privacy.
La PII detection copre email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address (più le entità regionali), e puoi scrivere le tue. Vedi PII Shield, Entità PII personalizzate e Formati di masking.
Aggiungi un blocker di segreti o il preset basi di prompt-injection — quest’ultimo segnala frasi di jailbreak comuni per la review. Per catturare l’intento di injection in modo semantico anziché per frase, aggiungi una regola llm_judge accanto a esso.
Ogni modifica scrive una riga di cronologia versionata. Apri History per confrontare e ripristinare. Vedi Versioning.
I guardrails filtrano il contenuto. Per governare le chiamate a tool di un agent — negare azioni distruttive, limitare il costo, richiedere approvazione — usa il Firewall. Parti da Proteggere gli agent AI e dalla minaccia delle chiamate a tool pericolose.
Leggi il riferimento Guardrails per il motore completo — campi delle regole, external vendor, l’harness di eval e l’API completa — o il quickstart di sicurezza per collegare guardrails e firewall insieme per un baseline di agent.