Saltar para o conteúdo principal
Depois de ter um workspace e uma chave de API (veja Introdução), os guardrails são como você coloca uma política de conteúdo na frente de cada modelo. Esta página é a referência canônica para o motor de guardrails do OrcaRouter — o que é, como usá-lo e como ele se compõe com o resto do gateway.

1. O que é o motor de guardrails

Um guardrail é uma política de conteúdo nomeada e com escopo de workspace — uma lista ordenada de regras que o gateway executa contra a entrada da requisição e a saída do modelo. Você salva um guardrail uma vez, vincula qualquer chave de API a ele (ou define um como padrão do workspace), e o gateway filtra cada chamada antes e depois do modelo upstream. Cada regra decide uma coisa — o que procurar (um tipo de regra), onde procurar (um estágio: entrada da requisição ou saída do modelo) e o que fazer a respeito (uma ação: block, mask ou flag). O motor executa cada regra aplicável e consolida os resultados em uma única decisão. Editar um guardrail entra em vigor em cada chave vinculada a ele já na próxima chamada. Sem redeploy. Sem mudança de código. Sem upgrade de SDK. A política vive no gateway, não na sua aplicação — sua app continua chamando /v1/chat/completions exatamente como antes. O motor é determinístico e sem dependências para os tipos de regra embutidos: correspondência pura de string e regex sem chamada de rede, segura para rodar no caminho quente de relay. Regras avançadas (fornecedores externos, LLM judge, contextual grounding) fazem chamadas externas e são despachadas concorrentemente, de modo que uma verificação lenta nunca se serializa atrás de outra. Guardrails têm escopo de workspace — cada membro vê os guardrails do workspace; nada atravessa fronteiras de tenant.

2. Início rápido — filtre sua primeira requisição em 5 passos

1

Criar um guardrail

No console, vá em /console/guardrails e clique em New guardrail. Nomeie-o pii-shield. Adicione uma regra:
  • Tipo: PII detection
  • Estágio: Input (requisição)
  • Ação: Mask — redigir a correspondência
  • Entidades: email, phone, ssn
Salve.
2

Testar no sandbox

Abra a aba Test dentro do editor, cole “email me at jane@acme.com, escolha o estágio input e execute. O sandbox mostra o veredito e o texto renderizado — email me at [EMAIL] — sem enviar nada upstream.
3

Vincular uma chave

Vá em /console/token, crie ou edite uma chave de API e escolha pii-shield no menu Guardrail. O vínculo vive na chave dentro do gateway.
4

Enviar uma requisição

Usando essa chave, chame o OrcaRouter exatamente como antes:
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"}
    ]
  }'
O gateway mascara o email para [EMAIL] antes de encaminhar. O modelo upstream nunca vê o endereço.
5

Apertar a política

De volta em /console/guardrails, edite pii-shield — altere a ação de ssn para Block via override por entidade. Salve. A próxima requisição que contiver um SSN é rejeitada com HTTP 400 guardrail_blocked. Nenhuma mudança na aplicação.
Esse é o valor principal.

3. Conceitos: guardrails, regras, estágios, ações

ConceitoDefinição
GuardrailUma política nomeada, com escopo de workspace. Identificador: name (≤ 64 chars). Tem enabled, is_default e um blob JSON rules.
RegraUma verificação dentro de uma política: um type, um stage, uma action, mais campos específicos do tipo. As regras rodam em ordem.
Estágioinput (a requisição), output (a resposta do modelo) ou both.
Açãoblock (rejeita a chamada), mask (redige a correspondência) ou flag (apenas registra — observa sem alterar o tráfego).

Escopo e o padrão do workspace

Guardrails têm escopo exatamente como as chaves de API: compartilhados no workspace quando você tem um workspace ativo, por usuário caso contrário. Resolução para qualquer requisição:
  1. Vínculo da chave — se a chave tem um guardrail_id explícito, esse guardrail se aplica (quando existe e está habilitado). Um vínculo explícito nunca cai silenciosamente para outro; desabilitá-lo é o botão de desligar.
  2. Padrão do workspace — se a chave não tem vínculo, o guardrail is_default habilitado do workspace se aplica.
  3. Nenhum — sem enforcement. A requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
No máximo um guardrail por workspace pode ser o padrão. Promover um novo padrão rebaixa o antigo na mesma transação.
Fail-open por design. Se a resolução de guardrail encontrar um erro transitório (ex.: um soluço do DB), o gateway degrada para sem enforcement em vez de derrubar o tráfego. A segurança degrada; a disponibilidade é preservada.

Como é um block

Uma requisição bloqueada retorna HTTP 400 com o código de erro guardrail_blocked e uma mensagem nomeando o guardrail e a regra que disparou. Uma requisição bloqueada não custa cota — um block no estágio de input dispara antes da medição, e um block no estágio de output reembolsa a cota pré-consumida — e é marcada como skip-retry (reexecutar o mesmo prompt apenas bloquearia de novo).

4. Tipos de regra

As regras se dividem em dois grupos: embutidas (determinísticas, sem rede) e avançadas (fazem chamada a um modelo ou fornecedor).
TipoGrupoO que faz
Keyword denylist (keyword)EmbutidaCorresponde a qualquer um de uma lista de termos literais — sem distinção entre maiúsculas e minúsculas, correspondência por substring (portanto class também corresponde a classic).
Regular expression (regex)EmbutidaCorresponde a um padrão RE2 (tempo linear, sem backreferences).
PII detection (pii)EmbutidaDetecta tipos de entidade embutidos (e os seus próprios personalizados). Veja §5.
Maximum length (max_chars)EmbutidaLimita a contagem de caracteres do texto em um estágio.
External vendor (external)AvançadaDelega a verificação a um fornecedor conectado (Aporia, Averta, BYO-webhook, …). Veja §9.
LLM judge (llm_judge)AvançadaRoda uma verificação semântica contra um modelo no seu workspace. Veja §6.
Contextual grounding (grounding)AvançadaPontua a fidelidade da resposta em relação às fontes recuperadas na requisição (RAG). Veja §7.
Um guardrail mistura qualquer número de regras de quaisquer tipos. Regras avançadas (external, llm_judge, grounding) são despachadas concorrentemente para que uma verificação lenta não se serialize atrás de outra.

5. PII detection em profundidade

Uma regra pii detecta entidades sensíveis e aplica a ação da regra a cada correspondência. O conjunto de detectores embutidos é fechado e compartilhado pelo motor, pelo validador e pelo construtor de regras: email, phone, credit_card, ssn, ip, iban, mac_address, api_key_openai, aws_access_key, jwt, bitcoin_address. Em uma ação mask, cada correspondência é substituída por uma tag tipada — um email vira [EMAIL], um SSN vira [SSN], e assim por diante.

Entidades personalizadas

Adicione seus próprios detectores sobre o conjunto embutido. Uma entidade personalizada é:
  • name — ASCII minúsculo / dígitos / underscore, deve começar com uma letra (ex.: employee_id). Flui para os logs de auditoria e a telemetria sem aspas.
  • pattern — um regex Go RE2 (tempo linear, sem backreferences).
  • checksum — opcional; luhn valida a correspondência com o algoritmo de Luhn (ex.: para números semelhantes a cartões).
  • mask_with — substituição verbatim opcional; o padrão é [<UPPERCASE_NAME>].
Até 25 entidades personalizadas por regra (cada uma é uma varredura regex sobre o texto completo, então o limite mantém o caminho quente linear). Padrões compilados são cacheados entre requisições.

Overrides de ação por entidade

Uma única regra PII pode aplicar ações diferentes a entidades diferentes via entity_actions. Uma regra que mascara emails / phones / IPs por padrão mas bloqueia em credit_card ou ssn — em vez de três regras sobrepostas:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
As chaves devem ser uma entidade habilitada na regra; os valores devem ser block / mask / flag. O validador rejeita qualquer outra coisa.

6. LLM judge

Uma regra llm_judge roda uma verificação semântica contra um modelo que seu workspace já pode chamar. Use-a para políticas difusas que nenhum regex captura — toxicidade, assédio, fora de tópico, intenção de prompt-injection.
CampoSignificado
judge_modelO modelo ou alias de roteador com o qual avaliar (ex.: gpt-4o-mini, orcarouter/cheap). Resolvido contra os canais do seu workspace.
judge_rubricO system prompt que descreve o que sinalizar.
judge_formatUm entre yes_no, score ou category (obrigatório; o console pré-seleciona yes_no).
judge_thresholdPara score: bloqueia/sinaliza quando o score está neste valor ou acima dele.
judge_categoriesPara category: a lista negada.
judge_timeout_msLimita a chamada do judge. 0 → padrão do motor.
judge_fail_opentrue (padrão) → um erro do judge é observado mas a requisição continua; false → trata erro/timeout como um block.
A chamada do judge roteia através dos canais do seu workspace, então seus tokens são cobrados e atribuídos como qualquer outra chamada (como uma sub-linha de judge). O motor anexa um apêndice de JSON-schema ao seu rubric para que o modelo retorne saída parseável.

7. Contextual grounding

Uma regra grounding mede a resposta do assistente em relação às fontes recuperadas na requisição (seu contexto RAG) e sinaliza ou bloqueia respostas que não sejam fiéis a elas. Ela reutiliza a costura do judge — mesmos canais do workspace, mesma atribuição de custo.
CampoPadrãoSignificado
grounding_modelescolha do workspaceO modelo para o qual o runner resolve a verificação de fidelidade.
grounding_rubricembutidoSobrescreve o rubric de fidelidade padrão.
grounding_threshold0.7Piso de fidelidade, 0.01.0. Abaixo dele, a ação dispara.
grounding_strictfalseQuando true, “nenhuma fonte fornecida” é tratado como um block (vs. o padrão de permitir).
grounding_max_bytes100000Limita o contexto de fontes concatenado entregue ao judge.
grounding_timeout_ms3000Limita a chamada do judge.

8. Templates, o sandbox e o eval harness

Biblioteca de templates

O split-button New guardrail abre direto em um template, e a biblioteca completa fica a um clique de distância. Os presets são escritos no servidor para que o console, o sandbox e estes docs descrevam exatamente o mesmo comportamento. As categorias incluem:
  • PII (pii) — PII Shield, PII Blocker (strict), Contact-Info Redactor, redator de PII de resposta.
  • Secrets (secrets) — bloqueadores de credenciais AWS / OpenAI / GitHub, chaves privadas e tokens de nuvem, carteiras de cripto, segredos na saída.
  • Compliance (compliance) — GDPR (PII da UE), PCI (block total de cartão), HIPAA (PHI), dados financeiros, logger de compliance, enforcement de aviso legal.
  • Brand (brand) — palavrões (block / mask / multilíngue), menções a concorrentes, palavras-chave de segurança infantil.
  • Safety (safety) — prompt-injection, jailbreak, vazamento de system-prompt, automutilação.
  • Cost (cost) — limites de tamanho de prompt/resposta e limites de tokens.
  • Agent (agent) — filtros de URL, imagem-markdown, chamada-de-ferramenta-shell e SQL-injection na saída.
Aplique um preset como ponto de partida, depois edite livremente — um preset é uma semente, não uma trava.

O sandbox de testes

Todo editor tem uma aba Test. Cole uma amostra, escolha um estágio e rode a política atual localmente — sem chamada upstream, sem cota. O sandbox retorna o veredito e (para regras de mask) o texto renderizado, para que você prove que uma regra faz o que você espera antes de vincular uma chave.

Eval / red-team harness

A aba Eval roda um guardrail contra um corpus de entradas e relata como ele pontuou — útil para ajustar um judge rubric ou provar que uma política pega ataques conhecidos antes de você publicá-la.
  • Corpora empacotados acompanham o gateway — conjuntos adversariais e de red-team (prompts de comportamento prejudicial, injeção de ferramentas, red-teaming multilíngue) mais conjuntos benignos para medir falsos positivos.
  • Corpora personalizados — faça upload do seu próprio JSONL para testar contra as formas reais do seu tráfego.
  • Runs são listadas com suas pontuações; abra uma run para inspecionar as falhas amostra por amostra.

9. External vendors

Uma regra external delega a verificação a um fornecedor conectado. Conecte um fornecedor uma vez em Integrations (o CTA do cabeçalho na página Guardrails), depois referencie a conexão a partir de uma regra.

Fornecedores suportados

FornecedorO que é
Aporia Guardrails (aporia)Motor de políticas baseado em ensemble de SLM para prompts e respostas.
Averta (averta)Endpoint genérico de classificador SLM (POST de texto → safe / unsafe + reescrita opcional).
BYO Webhook (webhook)Sua própria URL — recebe prompts e retorna veredictos allow / block / mask / flag.
Aporia e Averta recebem uma URL base + chave de API; o webhook recebe uma URL + cabeçalho de autenticação + segredo HMAC.

Campos da regra

CampoSignificado
connection_idA integração conectada a usar (caminho recomendado — fornecedor + segredos resolvem a partir da integração do workspace em tempo de execução).
timeout_msLimita a única chamada ao fornecedor. 0 → padrão.
fail_opentrue (padrão) → um erro do fornecedor é observado mas a requisição continua; false → trata erro de transporte / timeout / provedor desconhecido como um block.
Os segredos são armazenados criptografados e mascarados na leitura. A chamada de verificação carrega o cancelamento da requisição de relay, de modo que uma requisição cancelada não deixa uma chamada ao fornecedor pendurada.

10. Observabilidade

Guardrails deixam migalhas sobre as quais você pode agir.

Feed de matches

Toda regra que dispara registra um match — tipo de regra, ação, uma string de detalhe, o estágio e (quando habilitado) a substring correspondente. A aba Matches na página Guardrails é o feed de todo o workspace: listar, agrupar, filtrar, detalhar um único match, exportar para CSV e marcar falsos positivos.
A captura de conteúdo bruto é opt-in. O toggle Log raw content de um guardrail vem desligado por padrão — a postura conservadora de privacidade. Com ele desligado, o feed de Matches registra que uma regra disparou e sua meta-string de detalhe, mas não a substring correspondente em si (ex.: o próprio endereço de email). Ligue-o por guardrail quando precisar da substring para triagem; a configuração não é retroativa.

Stats

O feed de Matches alimenta as estatísticas por guardrail — cada card de guardrail mostra um sparkline e uma contagem de matches de 7 dias, e a aba Matches traz um total do workspace. Para segmentar a atividade por política, use a visão agrupada e os filtros do feed de Matches (por guardrail, tipo de regra, ação) — é ali que vivem o uso por guardrail, o mix de ações e a taxa de falsos positivos.

Histórico de versões e auditoria

Cada criação, atualização e exclusão escreve uma linha de histórico versionada na mesma transação que a mudança. Abra History na linha de um guardrail para:
  • Ver cada versão com quem a alterou e quando.
  • Diff entre quaisquer duas versões.
  • Revert para uma versão mais antiga (registrado como uma nova versão — o histórico nunca é mutado).

11. Relacionamento com o resto do gateway

SuperfícieComo se compõe com os Guardrails?
ModelosGuardrails são agnósticos a modelo. A mesma política anda sobre GPT-5, Claude, Gemini — ela filtra texto, não a escolha do modelo.
RoteamentoIndependente. O roteamento decide qual modelo/canal atende à requisição; os guardrails filtram o mesmo texto de requisição/resposta independentemente disso e nunca sobrepõem a seleção de modelo. A filtragem de input roda antes da chamada upstream, a filtragem de output depois que o modelo responde. As regras de judge e grounding resolvem seu próprio modelo através dos canais do seu workspace, separadamente do roteamento da requisição.
PromptsIndependentes e complementares. Prompts injetam uma mensagem de sistema; guardrails inspecionam e gateiam conteúdo. Ambos podem se aplicar a uma requisição e os guardrails sempre rodam. A ordem importa: as regras de input filtram a requisição do chamador antes que um prompt do registro seja injetado (a injeção acontece depois, na etapa de roteamento), então as regras de input veem as mensagens do chamador, não o prompt de sistema injetado; as regras de output filtram a resposta do modelo de qualquer forma.
Chaves de APIUma chave se vincula a um guardrail via guardrail_id. O vínculo vive na chave dentro do gateway, então editar o guardrail desloca todas as chaves vinculadas de uma vez; nenhum vínculo cai para o padrão do workspace.
Feed de MatchesToda regra que dispara cai no feed de Matches do workspace (seu próprio armazenamento, separado do log de requisição). Agrupe e filtre por guardrail, tipo de regra e ação para ver uso, mix de ações e taxa de falsos positivos por guardrail.

12. Referência da API

Todas as rotas têm escopo de workspace via o header X-Workspace-Id. RBAC é aplicado de maneira consistente: leituras e o sandbox de testes são abertos a cada membro; escritas exigem Developer+ (e a permissão guardrails:write); mudanças de tráfego de produção (delete, revert, configuração de fornecedor) são gateadas adequadamente.

Guardrails

Método e pathPapelPropósito
GET /api/guardrail/MemberLista guardrails (com contagens de chaves vinculadas).
GET /api/guardrail/metaMemberVocabulário do motor — tipos de regra, estágios, ações, entidades PII, presets, categorias de preset.
GET /api/guardrail/my-permissionsMemberAs permissões de guardrail do chamador (para gating de UI).
GET /api/guardrail/:idMemberDetalhe de um único guardrail.
GET /api/guardrail/:id/tokensMemberChaves de API vinculadas a este guardrail (limitado, com o total verdadeiro).
POST /api/guardrail/testMemberSandbox — avalia uma política sobre texto de amostra em um estágio. Nada é persistido.
POST /api/guardrail/Developer+Cria um guardrail.
PUT /api/guardrail/Developer+Atualiza um guardrail (escreve uma nova versão de histórico).
DELETE /api/guardrail/:idDeveloper+Deleta um guardrail.

History

Método e pathPapelPropósito
GET /api/guardrail/:id/historyMemberHistórico de versões (mais nova primeiro).
GET /api/guardrail/:id/history/diffMemberDiff entre duas versões.
GET /api/guardrail/:id/history/:versionMemberUma única versão histórica.
POST /api/guardrail/:id/revertDeveloper+Restaura uma versão mais antiga como uma nova versão.

Eval e corpora

Método e pathPapelPropósito
POST /api/guardrail/:id/evalMemberRoda um eval sobre um corpus (nome empacotado ou JSONL enviado).
GET /api/guardrail/:id/eval/runsMemberLista runs de eval para um guardrail (paginado).
GET /api/guardrail/eval/runs/:run_idMemberDetalhe de uma única run de eval.
GET /api/guardrail/eval/corporaMemberLista corpora do workspace + corpora empacotados.
POST /api/guardrail/eval/corporaDeveloper+Faz upload de um corpus JSONL.
GET /api/guardrail/eval/corpora/:idMemberDetalhe do corpus.
DELETE /api/guardrail/eval/corpora/:idDeveloper+Deleta um corpus.

Matches

Método e pathPapelPropósito
GET /api/guardrail/matchMemberLista matches (com escopo de workspace).
GET /api/guardrail/match/groupedMemberMatches agrupados (ex.: por regra ou guardrail).
GET /api/guardrail/match/statsMemberEstatísticas de matches (suporta ?days= e ?group_by=).
GET /api/guardrail/match/exportMemberExporta matches como CSV.
GET /api/guardrail/match/:idMemberDetalhe de um único match.
POST /api/guardrail/match/:id/mark-fpAdminMarca um match como falso positivo (rate-limited).
DELETE /api/guardrail/match/:id/mark-fpAdminDesmarca um falso positivo (rate-limited).

Vinculando uma chave

Defina guardrail_id na chave de API (via o editor de chave ou a API de token). 0/null significa nenhum vínculo explícito — a chave cai para o guardrail padrão do workspace, se houver um definido.

13. FAQ

O comportamento é byte-idêntico ao de um workspace que nunca habilitou o recurso. Se a chave não estiver vinculada e nenhum padrão de workspace estiver definido, o gateway não faz modificação alguma. Nada é bloqueado, mascarado ou registrado no feed de Matches.
Não. Um block no estágio de input dispara antes de o uso ser medido; um block no estágio de output reembolsa a cota pré-consumida depois que a resposta é rejeitada. De qualquer forma, o chamador não paga cota, recebe HTTP 400 guardrail_blocked e a requisição é marcada como skip-retry (reexecutar o mesmo prompt contra outro canal apenas bloquearia de novo).
Depende da ação. Block é aplicado nos dois casos: em uma resposta não-streaming a resposta é verificada antes de retornar, e em uma resposta streaming um scanner corta o stream em pleno voo e emite uma mensagem de substituição antes que qualquer conteúdo bloqueado chegue ao cliente. Mask no output atualmente se aplica apenas a respostas não-streaming — em uma resposta streaming o chunk original passa sem ser mascarado (a reescrita in-band do stream é uma melhoria planejada). Para mascaramento de output hoje, use requisições não-streaming ou confie no mascaramento no estágio de input. Prove sua combinação específica de estágio/stream no sandbox e com uma run de eval antes de confiar nela.
Mask redige a correspondência (ex.: jane@acme.com[EMAIL]) e deixa a requisição passar com o texto sanitizado — o modelo upstream nunca vê o original. Block rejeita a requisição inteira com HTTP 400. Flag não altera nada no tráfego e apenas registra um match — use-o para medir uma regra antes de aplicá-la.
Uma regra embutida (keyword / regex / PII / max_chars) não faz chamada a modelo e não cobra nada. Uma regra llm_judge ou grounding chama um modelo através dos canais do seu workspace, então esses tokens são cobrados e atribuídos como uma sub-linha de judge.
Ligue o Log raw content para o guardrail. Com ele desligado (o padrão), o feed de Matches registra que uma regra disparou e sua meta-string de detalhe mas não a substring correspondente — a postura conservadora de privacidade. O toggle não é retroativo: ele só afeta matches registrados depois que você o habilita.
Sim. Abra History no guardrail, faça o diff das versões e Revert para a que você quiser. Revert copia o conteúdo daquela versão para frente como uma nova versão — o histórico nunca é mutado — e a mudança entra em vigor na próxima requisição.
Por padrão, as regras avançadas falham aberto: um timeout ou erro de transporte é registrado como telemetria e a requisição continua. Defina fail_open (external) ou judge_fail_open (judge) como false para falhar fechado — tratar o erro como um block — em políticas onde uma verificação perdida é inaceitável.