Guardrails

Visão Geral

Guardrails são regras de validação configuráveis que rodam em toda requisição que passa pelo gateway. Diferente do LLM Firewall que foca em bloquear prompts maliciosos, guardrails aplicam as políticas de conteúdo da sua organização — tanto nos inputs (antes do LLM receber) quanto nos outputs (antes da resposta chegar ao usuário).

Cada regra pode bloquear a requisição (retornar erro) ou sinalizar (logar a violação mas permitir que prossiga). Regras são avaliadas em ordem de prioridade, e regras de bloqueio interrompem na primeira falha.

Guardrails requerem o plano Pro (feature flag has_guardrails).

Tipos de Regra

max_length

Valida que o texto não excede um limite de caracteres.

• Estágio: input, output ou all
• Ação: block ou flag
• Config:

{ "max_chars": 5000 }

Use para evitar prompts excessivamente longos que consomem tokens ou respostas muito grandes retornadas aos usuários.

keyword_block

Bloqueia texto contendo qualquer um dos termos configurados. Usa correspondência case-insensitive — nenhum padrão regex é compilado a partir de input do usuário.

• Estágio: input, output ou all
• Ação: block ou flag
• Config:

{ "terms": ["nome_concorrente", "codinome_interno", "frase proibida"] }

Use para evitar vazamento de terminologia interna, bloquear menções a concorrentes ou aplicar diretrizes de marca.

pii_detect

Detecta informações pessoalmente identificáveis usando os mesmos padrões regex do scrubber de PII do gateway.

• Estágio: input, output ou all
• Ação: block ou flag
• Padrões disponíveis: email, cpf, ssn, credit_card, phone, api_key
• Config:

{ "patterns": ["email", "cpf", "credit_card", "phone"] }

Apenas os padrões listados na config são verificados. Nomes de padrões desconhecidos são silenciosamente ignorados.

json_schema

Valida que a resposta é JSON válido conformando a um JSON Schema fornecido. Útil para enforcement de output estruturado.

• Estágio: output apenas
• Ação: block ou flag
• Config:

{
  "schema": {
    "type": "object",
    "required": ["answer", "confidence"],
    "properties": {
      "answer": { "type": "string" },
      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
    }
  }
}

O texto é primeiro parseado como JSON, depois validado contra o schema. Se a resposta não for JSON válido, a regra falha.

toxicity

Atualmente um pass-through no-op. A implementação anterior chamava o modelo ONNX Prompt-Guard local de forma síncrona. Com o firewall agora baseado em LLM via BackendRouter, a interface síncrona da chamada não cabe mais — chamadas ao router são assíncronas. Levar async para o trait sync Validator (ou dividi-lo) ficou para um follow-up; o próprio firewall continua sendo o portão de segurança principal.

custom_llm

Em breve. Avalia texto usando um prompt LLM customizado para políticas específicas do domínio.

• Estágio: output apenas (validador lento — requer chamada LLM)

Estágios de Avaliação

Regras são atribuídas a um de três estágios:

Importante: Tipos de regra lentos (toxicity, json_schema, custom_llm) só podem rodar no estágio output. Essa restrição é aplicada no banco de dados.

Block vs Flag

• Block: A requisição é rejeitada com erro 400 GuardrailBlocked. O motivo é incluído na resposta. Para regras de input, a requisição nunca chega ao LLM. Para regras de output, a resposta é descartada.
• Flag: A violação é logada no ClickHouse (tabela guardrail_events) e visível no dashboard, mas a requisição/resposta prossegue normalmente. Use para monitorar antes de aplicar.

Para respostas streaming, guardrails de output rodam assincronamente após o stream completar. Como a resposta já foi enviada, regras de bloqueio se comportam como flags — a violação é logada e sinalizada mas não pode ser retratada.

Prioridade

Regras são avaliadas em ordem crescente de prioridade (número menor = roda primeiro). Se duas regras têm a mesma prioridade, a ordem de avaliação não é garantida. Use prioridade para garantir que regras críticas (como detecção de PII) rodem antes de regras menos importantes (como keyword blocking).

Eventos de Guardrail

Toda avaliação de regra que resulta em block ou flag é logada no ClickHouse. Cada evento inclui:

• Request ID
• Organization ID
• Rule ID e tipo
• Estágio de avaliação (input/output)
• Ação tomada (block/flag)
• Motivo da falha
• Preview do texto (primeiros 200 caracteres)

Visualize eventos no dashboard em Guardrails > Eventos.

Gerenciando Regras

Criando uma Regra

1. Vá em Guardrails no dashboard.
2. Clique em Criar Regra.
3. Configure:
   • Nome — label descritivo para a regra
   • Tipo — selecione entre os tipos disponíveis
   • Estágio — input, output ou all
   • Ação — block ou flag
   • Prioridade — ordem de avaliação (menor roda primeiro)
   • Config — configuração JSON específica do tipo
4. Clique em Salvar. A regra fica ativa imediatamente.

Editando uma Regra

Clique na regra no dashboard, modifique os campos e salve. Mudanças têm efeito após o TTL do cache Redis expirar (normalmente em segundos).

Desativando uma Regra

Alterne o switch Ativo para desativar uma regra sem deletá-la. Regras desativadas não são avaliadas.

Deletando uma Regra

Apenas owners da organização podem deletar regras de guardrail. Esta ação é permanente.

Comportamento na API

Quando um guardrail bloqueia uma requisição, o gateway retorna:

{
  "error": {
    "message": "Text length 8500 exceeds maximum of 5000 characters",
    "type": "guardrail_blocked",
    "code": 400
  }
}

O campo message contém o motivo específico do validador. Sua aplicação deve tratar erros guardrail_blocked e apresentar uma mensagem amigável.

Guardrails vs Firewall

Ambos os sistemas rodam independentemente. Uma requisição deve passar pelo firewall primeiro, depois os guardrails são avaliados.