Vai al contenuto principale
Un guardrail dello stage di input filtra la richiesta del chiamante prima che raggiunga il modello. È il posto più economico dove applicare una content policy: il gateway ispeziona il prompt in entrata, e se una regola blocca, la richiesta viene rifiutata prima della misurazione — non paghi nulla per la chiamata. È qui che fermi un segreto trapelato, un campo PII o un tentativo di injection dal raggiungere mai il modello upstream. Per il motore completo — ogni tipo di regola, campo e rotta — vedi il riferimento Guardrails. Questa pagina è la trattazione focalizzata sullo stage di input: cosa gira prima del modello, e perché un block qui non costa quota.

​
1. Guardrails di input per app LLM, prima del modello

Ogni regola di guardrail porta uno stage — input, output o both. Una regola input gira sul testo della richiesta nel momento in cui arriva, in viaggio verso il modello upstream: 
caller → [ input guardrail ] → metering → model → [ output guardrail ] → caller
Quell’ordinamento è il punto. Una regola di input vede il prompt prima che il gateway pre-consumi qualsiasi quota, quindi un block in questo stage è gratuito — la richiesta non raggiunge mai il modello e non fattura mai. Confronta lo stage di output, che filtra la risposta del modello dopo che torna (un block di output rimborsa invece la quota pre-consumata).
Le regole di input filtrano la richiesta del chiamante. Se usi anche i prompt del registry, il messaggio di sistema iniettato viene aggiunto più tardi nel routing — quindi le regole di input vedono i messaggi inviati dalla tua app, non il prompt iniettato. Le regole di output filtrano la risposta in entrambi i casi.

​
2. Cosa puoi eseguire nello stage di input

Qualsiasi tipo di regola può girare in input. I motivi più comuni per gestire la richiesta prima del modello:

Maschera la PII nel prompt

Una regola pii con l’azione mask riscrive le entità in tag tipizzati (jane@acme.com → [EMAIL]) così che il modello upstream non veda mai il valore grezzo. Vedi PII Shield.

Blocca i segreti prima che trapelino

Una richiesta che porta una chiave API o una credenziale cloud viene rifiutata alla porta — pre-misurazione, nessuna chiamata upstream. Vedi Block secrets.

Ferma i tentativi di injection

Il preset basi di prompt-injection abbina detector keyword/regex a una regola llm_judge per l’intento di injection. Vedi Prompt injection.

Limita la dimensione del prompt

Una regola max_chars rifiuta un prompt sovradimensionato prima che fatturi qualsiasi token. Vedi Cost guardrails.
I sette tipi di regola — keyword, regex, pii, max_chars, external, llm_judge, grounding — e le cinque azioni block, mask, flag, annotate e spotlight si applicano tutti qui. (spotlight avvolge il testo non attendibile corrispondente in delimitatori così che il modello lo tratti come dati, non come istruzioni — una difesa di prompt-injection nello stage di input; annotate allega una nota senza cambiare il traffico.) Un’eccezione che vale la pena conoscere: grounding misura la risposta rispetto alle sorgenti recuperate, quindi è intrinsecamente un controllo dello stage di output. Tutto il resto si adatta naturalmente allo stage di input.
Il masking nello stage di input è attivo oggi — in streaming o meno. Il gateway riscrive la richiesta prima che il modello la veda su ogni percorso. Il mask di output redige solo le risposte non in streaming; la riscrittura in-stream dell’output è nella roadmap, quindi una regola mask non redige ancora una risposta in streaming. Il block di output, al contrario, è applicato in entrambi i casi — streaming e non streaming (vedi Streaming coverage).

​
3. Un esempio concreto

Scrivi la regola nella console (sotto la tua sessione — la config dei guardrail richiede Developer+), non con una chiave di relay. Aggiungi una singola regola input a un guardrail chiamato secrets-shield: 
{
  "type": "regex",
  "stage": "input",
  "action": "block",
  "pattern": "sk-[A-Za-z0-9]{20,}"
}
Collega il guardrail a una chiave (imposta guardrail_id, o marcalo come default del workspace — vedi Collega a una chiave), poi chiama il gateway con quella chiave di relay sk-orca-...: 
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": "Debug this: OPENAI_API_KEY=sk-abcdefghij1234567890"}
    ]
  }'
La richiesta corrisponde nello stage di input ed è rifiutata con HTTP 400 guardrail_blocked prima che il gateway inoltri qualsiasi cosa upstream: 
{
  "error": {
    "type": "guardrail_blocked",
    "message": "request blocked by guardrail \"secrets-shield\": regex(...)"
  }
}
Vedi l’errore guardrail_blocked per la forma completa della risposta.

​
4. Perché un block di input non costa quota

Questo è il vantaggio strutturale di catturare le cose in entrata. Un block nello stage di input sta prima del pre-consume, quindi:
ProprietàBlock nello stage di input
Stato HTTP400 guardrail_blocked
Quota addebitataNessuna — scatta prima della misurazione
Chiamata upstreamMai effettuata
RetryMarcato skip-retry — rieseguire blocca di nuovo
Poiché la richiesta non raggiunge mai un canale, un block di input è marcato skip-retry: rieseguire lo stesso prompt contro un altro canale si limiterebbe a bloccarlo di nuovo e sprecherebbe lavoro. Lo stage di output differisce — un block lì rimborsa la quota che il gateway aveva già pre-consumato. Stesso 400, contabilità diversa.

​
5. Risoluzione e fallback

Una regola dello stage di input gira solo se un guardrail si risolve davvero sulla richiesta. La risoluzione è esplicita:
  1. Il guardrail_id esplicito della chiave, se esiste ed è abilitato.
  2. Altrimenti il guardrail default del workspace.
  3. Altrimenti nessuno — 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 si comportano diversamente qui; vedi Guardrails vs. firewall.)

​
6. Dimostralo prima di metterlo in produzione

Non collegare una regola di input bloccante al traffico reale per fede. Due modi per validare prima:
Apri la tab Test nell’editor del guardrail, incolla un campione, scegli lo stage input ed esegui. La sandbox valuta la policy corrente localmente — nessuna chiamata upstream, nessuna quota — e restituisce il verdetto più (per le regole mask) il testo renderizzato. Vedi Testing ed eval.
Imposta prima l’azione su flag. Un flag non cambia nulla del traffico — registra solo un match — così puoi misurare quanto spesso una regola scatterebbe su input reale prima di portarla su block. Vedi Tuning dei falsi positivi.
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.

​
7. Dove andare dopo

Lo stage di input ferma l’input cattivo dal raggiungere il modello. Per gestire la risposta del modello, abbinalo allo stage di output; per governare le chiamate a tool di un agent, usa il firewall. Leggi il riferimento Guardrails per il motore completo, o il quickstart di sicurezza per collegare i guardrails di input e il firewall insieme per un baseline di agent.