1. Duas classes de verificação
Cada regra de guardrail e cada avaliação de firewall se enquadra em uma das duas classes.Verificações embutidas / determinísticas
As regras de guardrail de keyword denylist (keyword), expressão regular
(regex), detecção de PII (pii) e comprimento máximo (max_chars) são
operações puras de string e regex locais — sem chamada de modelo, sem
salto de rede, nada que possa expirar. A avaliação de regras de firewall
(correspondência de glob de nome de ferramenta, predicados de argumento,
escopo de egress) é a mesma: determinística e local.
Para fins práticos, essas verificações adicionam latência negligenciável à
sua requisição. Elas são seguras para rodar no caminho quente e é do que os
templates de guardrail embutidos são feitos.
Verificações avançadas / semânticas
As regrasllm_judge, grounding e external de fornecedor delegam a
verificação a um modelo ou fornecedor. Elas custam uma ida e volta. Três
propriedades limitam esse custo:
- Dispatch concorrente. Se sua política tem múltiplas regras avançadas, elas são despachadas em paralelo — uma verificação lenta nunca se serializa atrás de outra.
- Timeout por regra. Cada regra avançada tem um timeout
(
judge_timeout_ms/grounding_timeout_ms/timeout_ms). A verificação de grounding tem padrão de ~3 000 ms; o judge usa um valor configurável (0 → padrão do motor). A regra é limitada — ela não pode travar indefinidamente. - Fail-open por padrão. Quando uma regra expira ou seu fornecedor retorna
um erro, o evento é registrado mas a requisição continua. Defina
judge_fail_open: false(judge) oufail_open: false(external) para mudar para fail-closed.
2. Visão geral
| Tipo de verificação | Adiciona latência? | Como é limitada |
|---|---|---|
Denylist keyword | Negligenciável — varredura de string local | Sem rede; sem timeout necessário |
regex | Negligenciável — correspondência RE2 local | Sem rede; sem timeout necessário |
Detecção pii | Negligenciável — varredura de regex/entidade local | Sem rede; sem timeout necessário |
max_chars | Negligenciável — contagem de caracteres | Sem rede; sem timeout necessário |
| Avaliação de regra de firewall | Negligenciável — correspondência de glob + predicado | Sem rede; sem timeout necessário |
llm_judge | Uma chamada de modelo limitada | judge_timeout_ms; fail-open por padrão |
grounding | Uma chamada de modelo limitada | grounding_timeout_ms (padrão ~3 000 ms); fail-open por padrão |
Fornecedor external | Uma chamada de fornecedor limitada | timeout_ms; fail_open por padrão |
| Múltiplas regras avançadas | Uma ida e volta limitada (dispatch concorrente) | Pior caso = maior timeout individual, não soma |
3. Onde no ciclo de vida da requisição as verificações são executadas
O enforcement não acontece tudo no mesmo ponto. A inspeção de entrada e saída adiciona tempo em lugares diferentes:llm_judge que verifica injeção de prompt)
adiciona uma chamada de modelo limitada antes que a chamada ao modelo
principal comece.
Guardrails de saída rodam depois que o modelo responde. Uma regra de saída
embutida adiciona overhead negligenciável na cauda. Uma regra de saída avançada
(ex.: grounding verificando fidelidade do RAG) adiciona uma chamada limitada
depois que você já tem a resposta do modelo.
A avaliação de regras do Firewall é determinística e acontece inline no
roteamento de chamadas de ferramenta — negligenciável, como observado acima.
Uma requisição bloqueada não custa tokens de modelo e não adiciona latência
upstream para bloqueios no estágio de entrada. Um bloqueio de entrada dispara
antes da medição e antes da chamada upstream, então você não paga nem cota
nem tempo de ida e volta upstream. Um bloqueio no estágio de saída reembolsa
a cota pré-consumida após a resposta ser rejeitada.
4. Como timeouts e fail-open limitam o pior caso
As regras avançadas têm dois controles: Timeout — o tempo de parede máximo permitido para a verificação. A requisição espera no máximo este tempo por essa regra. O dispatch concorrente significa que este limite se aplica por regra, não por política. Se você tem três regrasllm_judge, cada uma com um timeout de 2 000 ms, todas as três
rodam de uma vez e o tempo total de espera é ~2 000 ms, não ~6 000 ms.
Fail-open vs fail-closed — o que fazer quando a regra não completa a
tempo (ou o fornecedor retorna erro):
| Configuração | Comportamento no timeout / erro |
|---|---|
fail_open: true (padrão) | Registra o evento; deixa a requisição continuar como se a verificação tivesse passado |
fail_open: false | Trata o timeout / erro como um bloqueio; retorna HTTP 400 guardrail_blocked |
5. Orientação prática
Mantenha regras do caminho quente como embutidas. Se sua preocupação principal é PII, vazamento de credenciais, comprimento de prompt ou keyword denylist — todos esses são regras embutidas. Elas não adicionam latência mensurável e devem ser sua escolha padrão para qualquer verificação que a correspondência de texto possa tratar. Usellm_judge e grounding onde você precisa de semântica. Toxicidade,
assédio, detecção fora de tópico, intenção de injeção de prompt e fidelidade
de RAG são genuinamente difusos — nenhum regex os captura de forma confiável.
Esses são os casos certos para uma regra avançada. Aceite que cada uma adiciona
uma chamada de modelo extra limitada.
Ajuste os timeouts para o seu orçamento de latência. Se o seu alvo de
ponta a ponta é 1 000 ms, defina judge_timeout_ms: 800 (ou menos) para que
o judge não possa consumir todo o seu orçamento. O timeout padrão do motor é
um bom ponto de partida; reduza-o se você tiver requisitos mais rígidos.
Para grounding de saída, a chamada ao modelo já foi feita. A verificação
de grounding roda depois que o modelo upstream responde — a latência extra
está apenas na cauda, não no caminho crítico para o primeiro token. Isso o
torna um lugar de baixo risco para adicionar enforcement semântico.
Múltiplas regras avançadas? Distribua o trabalho. Como as regras avançadas
rodam concorrentemente, empilhar três regras llm_judge custa aproximadamente
o mesmo que uma — o timeout individual mais longo determina o tempo de parede,
não a contagem. Use isso para compor verificações semânticas sem custo aditivo.
Modos de enforcement
Fail-open vs fail-closed — a referência completa para ajustar o
comportamento da sua política em condições de timeout e erro.
Guardrails
Tipos de regra, campos do judge, thresholds de grounding e a referência
completa de configuração de guardrail.