Saltar para o conteúdo principal
Você vinculou um guardrail e agora quer ver o que ele pegou. O feed de Matches é o log de correspondências de guardrail do OrcaRouter — toda vez que uma regra dispara (block, mask, flag, annotate ou spotlight), o gateway registra um match que você pode revisar no console ou puxar pela API. É como você responde “o que a regra de PII redigiu ontem?”, “qual chave aciona o bloqueador de segredos?” e “esta regra está disparando no tráfego real ou é só ruído?”. Esta página é o guia focado em ler e triar correspondências. Para como as regras são escritas e o que cada ação faz, veja a referência de Guardrails.

​
1. O que o log de correspondências de guardrail registra

Toda regra disparada escreve um match em um feed com escopo de workspace (GET /api/guardrail/match, aberto a qualquer Member). O feed é separado do seu log de requisição — ele armazena apenas o que um guardrail fez, não o corpo completo da requisição. Cada match registra:
rule_type (keyword, regex, pii, max_chars, external, llm_judge, grounding), a action efetiva (block / mask / flag / annotate / spotlight) e o stage (input ou output) — para que você possa dizer instantaneamente o que disparou e o que ela fez.
guardrail_name, o rule_label que disparou, mais o contexto da requisição: model_name, o token no qual ela chegou, o ip do chamador e o request_id que se junta de volta ao seu log de requisição.
detail — a nota curta legível por humanos do motor para a violação (ex.: qual entidade ou padrão acionou), sempre registrada.
matched é preenchido apenas quando o toggle Log raw content do guardrail está ligado. Está desligado por padrão, então por padrão o feed diz que uma regra disparou e por quê, mas nunca armazena a própria string sensível.
O conteúdo bruto é opt-in e não retroativo. Com Log raw content desligado (o padrão), o campo matched permanece vazio — o feed registra o veredito e o detail, nunca o endereço de email, segredo ou PII que acionou a regra. Ligue-o por guardrail apenas quando precisar da substring para triagem; ele se aplica a matches registrados depois de você habilitá-lo. Veja Logging e privacidade.

​
2. Liste e filtre o log de correspondências

A visão de lista padrão é paginada por cursor, do mais novo primeiro, e com escopo do seu workspace. Estreite-a com query params — o console os expõe como chips de filtro:
ParamFiltra por
guardrail_id, rule_type, action, stageO veredito
token_id, model_name, request_idO contexto da requisição
days / start_at + end_at, hide_fpJanela e estado de falso positivo
Uma leitura típica de “me mostre tudo o que o guardrail de segredos bloqueou esta semana”, usando seu token de sessão do console: 
curl "https://api.orcarouter.ai/api/guardrail/match?guardrail_id=42&action=block&days=7" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Rotas de gerenciamento como /api/guardrail/* autenticam com seu token de sessão / acesso do console, não uma chave de relay. As chaves sk-orca-... servem apenas para chamadas de modelo /v1/*. No uso diário você lerá o feed direto da aba Matches na página Guardrails.

​
3. Agrupe por requisição

Uma única requisição pode acionar várias regras de uma vez — um mask de PII de input e um limite de comprimento máximo, digamos. A visão agrupada (GET /api/guardrail/match/grouped, Member) colapsa matches por request_id para que você veja uma linha por requisição ofensora com seus matches dobrados inline, em vez de rolar por cinco linhas para a mesma chamada. Ajuste quantos matches aparecem inline por grupo com inline_limit (padrão 5).

​
4. Estatísticas e a tira de tendência

O endpoint de estatísticas (GET /api/guardrail/match/stats, Member) alimenta a tira de contagem e o gráfico na aba Matches — totais sobre uma janela de days, opcionalmente quebrados com group_by:
group_byQuebra
(omitido)Apenas totais
rule_typeQuais tipos de regra disparam mais
guardrail_idQual guardrail responde pela atividade
Passe request_id para obter uma contagem de matches em tempo constante para uma requisição (usado pelo cross-link do log de requisição). É aqui que vivem o uso por guardrail, o mix de ações e a taxa de falsos positivos — fatie-o em vez de paginar a lista bruta.

​
5. Exporte para um rastro de auditoria

Quando você precisa de matches fora do console — um pacote de evidências, uma planilha, um SIEM downstream — GET /api/guardrail/match/export (Member) transmite seu conjunto de filtros atual como CSV ou JSON: 
curl "https://api.orcarouter.ai/api/guardrail/match/export?format=csv&guardrail_id=42&days=30" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "X-Workspace-Id: <workspace-id>" \
  -o guardrail-matches.csv
A exportação carrega as mesmas colunas que o feed registra — hora, guardrail, tipo e label de regra, estágio, ação, modelo, token, detalhe, a substring correspondente (apenas se a captura de conteúdo bruto estava ligada no momento do registro), id da requisição, ip e o timestamp de falso positivo.
O CSV é seguro contra injeção de fórmula: qualquer célula que de outra forma seria lida como uma fórmula de planilha é neutralizada, então abrir uma exportação no Excel ou Sheets não pode executar um payload contrabandeado por uma substring correspondente.

​
6. Trie falsos positivos

Nem todo match é um acerto real. Quando uma regra dispara em tráfego benigno, um Admin do workspace pode marcar o match como falso positivo (POST /api/guardrail/match/:id/mark-fp); o inverso DELETE /api/guardrail/match/:id/mark-fp o desmarca. A marcação é somente Admin mesmo que o resto do feed seja legível por Member — a triagem é uma ação privilegiada. Marcar um falso positivo faz duas coisas: marca o match (para que hide_fp=true o filtre fora do feed) e lembra a descoberta para que a mesma regra no mesmo conteúdo seja pulada em requisições futuras. Desmarque para restaurar o enforcement. Para o fluxo mais amplo de ajustar uma regra ruidosa, veja Ajustar falsos positivos.
Um match é dado de diagnóstico, não uma decisão de enforcement. Se uma requisição foi bloqueada, mascarada ou meramente sinalizada já está resolvido pela ação no momento da requisição — o feed é o registro após o fato. Marcar um falso positivo muda o comportamento futuro, nunca a chamada que já aconteceu.

​
7. De onde vêm os matches

Os matches são produzidos pelo motor de guardrail no caminho de relay, então o feed reflete exatamente o que suas políticas vinculadas fizeram:
  • Matches de estágio de input registram o que o gateway filtrou antes de o modelo vê-lo — veja Estágio de input.
  • Matches de estágio de output registram o que ele filtrou na resposta — veja Estágio de output.
  • Uma requisição bloqueada também aparece como um HTTP 400 guardrail_blocked para o chamador; o match é o registro server-side dela.
Se nenhum guardrail resolve em uma requisição, nada é filtrado e nada cai no feed — o comportamento é idêntico ao de um workspace que nunca habilitou o recurso. Veja Vincular a uma chave e Padrão de conta para como uma política fica na frente do tráfego em primeiro lugar.

​
8. Relacionados

Referência de Guardrails

O motor completo: tipos de regra, estágios, ações, presets, eval harness.

Logging e privacidade

O toggle Log raw content e o que o feed armazena — e não armazena.

Ajustar falsos positivos

Use o feed para encontrar e silenciar regras ruidosas sem enfraquecer a política.

Versionamento

Faça o diff e reverta um guardrail quando o feed mostra que uma mudança falhou.
Para o panorama maior de como o gateway inspeciona o tráfego, veja Como o OrcaRouter inspeciona e Guardrails vs firewall.