Saltar para o conteúdo principal
Se seu app faz streaming, você precisa de uma resposta direta antes de confiar em uma política de conteúdo: o que de fato é aplicado em uma resposta SSE. Um guardrail que inspeciona uma resposta inteira é fácil de raciocinar; um guardrail que tem que agir sobre deltas conforme eles são enviados ao navegador não é. Esta página é a matriz de cobertura de guardrail em streaming — cada ação, nos estágios de input e output, em tráfego streaming e não-streaming — escrita para ser precisa sobre como cada célula se comporta em um stream ao vivo. Para o motor completo — cada tipo de regra, campo e rota — veja Guardrails. Para a mecânica de como um stream é cortado, veja regras stream-safe.

​
1. A pergunta de cobertura de guardrail em streaming

Uma regra de guardrail carrega um estágio (input, output ou both) e uma ação — uma de cinco: block, mask, flag, annotate ou spotlight. O estágio decide quando o gateway a roda; a ação decide o que ela faz. O único lugar onde o streaming muda a forma da resposta é o estágio de output — porque é o único estágio onde o gateway está encaminhando bytes ao seu cliente conforme chegam, sem chance de segurar o payload inteiro primeiro. Então a matriz tem duas células onde o streaming importa, e elas se comportam de forma diferente: o block de output é totalmente aplicado em um stream (o scanner o corta), mas o mask de output é aplicado apenas a respostas não-streaming. Em uma resposta com stream o scanner ainda detecta a correspondência e pode agir sobre uma decisão de block, mas não reescreve o texto mascarado no stream hoje — o mascaramento de output in-band em streaming está no roadmap.
O input nunca é o problema. As regras de estágio de input rodam antes do modelo — o gateway filtra (e, para mask, reescreve) sua requisição, depois encaminha a versão sanitizada upstream. Se a resposta fará streaming é irrelevante; a requisição é um payload completo que o gateway segura por inteiro. A varredura de input está totalmente ativa, mascaramento incluído, em cada requisição.

​
2. A matriz de cobertura

Leia isto de cima a baixo. Toda célula de block está ativa, streaming incluído — mas output + mask + streaming é a única célula que ainda não é aplicada no stream: uma regra de mask redige uma resposta não-streaming, e em uma resposta com stream ela detecta a correspondência sem reescrever o delta (o mascaramento de output in-stream está no roadmap).
Estágio · açãoNão-streamingStreaming
input · blockrejeita a requisiçãorejeita a requisição
input · maskreescreve a requisiçãoreescreve a requisição
output · blockrejeita a respostacorta o stream
output · maskredige a respostadetecta a correspondência; não redige in-stream (roadmap)
qualquer · flagapenas registraapenas registra
annotate e spotlight anexam uma nota (ou envolvem texto correspondente) sem rejeitar tráfego e são ações de estágio de input na prática, então não mudam as células de output/streaming acima; elas registram um match como qualquer outra regra.
As regras de estágio de input filtram a requisição antes de o modelo upstream rodar. Um block curto-circuita a chamada (HTTP 400 guardrail_blocked, antes da medição, então não custa cota). Um mask reescreve os campos correspondentes no prompt no lugar — o texto sanitizado é o que vai upstream, e o modelo nunca vê o original. Nada disso depende de a resposta fazer streaming.
Em uma resposta não-streaming o completion é filtrado por inteiro antes de retornar — um block aparece como HTTP 400 guardrail_blocked. Em uma resposta com stream um scanner de stream observa os deltas conforme fluem; quando uma regra de block dispara ele corta o stream — sela o scanner, emite um aviso curto de substituição no lugar do resto, e fecha o canal SSE antes que mais conteúdo bloqueado chegue ao cliente. Como os headers SSE 200 já foram enviados até então, um block de streaming não pode retornar um 400: ele entrega o block como um delta in-band final em vez de um erro HTTP.
Em uma resposta não-streaming uma regra de mask reescreve o completion — ex.: um email vira [EMAIL] — e o texto sanitizado é o que seu cliente recebe. Em uma resposta com stream o scanner de stream ainda detecta a correspondência e computa o mask, mas ele não encaminha o texto mascarado para o delta — o output mascarado é descartado e apenas uma decisão de block é executada. Então uma regra de mask não redige uma resposta com stream hoje; o mascaramento de output in-band em streaming está no roadmap. Se você precisa manter PII fora de uma resposta com stream agora, escreva a regra como block (o scanner corta o stream na correspondência) ou filtre não-streaming.
Uma regra de flag nunca altera o tráfego — ela registra um match e deixa os bytes passarem. Estágio e stream não mudam seu comportamento. Use-a para medir a taxa de acerto de uma regra antes de promovê-la para block.
A única linha para lembrar: o block de output é aplicado ao vivo nos dois transportes — streaming incluído — e o mascaramento de input está sempre ativo. O mask de output redige apenas respostas não-streaming; em um stream ele detecta a correspondência mas ainda não reescreve o delta (o mascaramento de output in-stream está no roadmap). Para manter PII fora de uma resposta com stream hoje, escreva a regra como block ou filtre não-streaming.

​
3. Um exemplo concreto — manter PII fora de uma resposta com stream

Digamos que o modelo possa trazer à tona o email de um cliente do contexto RAG, e seu app faz streaming. O mask de output não redige no stream hoje (o mascaramento de output in-stream está no roadmap) — então para manter PII fora de uma resposta com stream, escreva a regra de output como block: o scanner mata o stream no momento em que uma correspondência aparece. (O mask de output de fato redige em uma resposta não-streaming.) Editar política é uma ação de gerenciamento na sua sessão do console (gateada para Developer+); a chave de relay sk-orca-... só envia tráfego /v1/* e nunca edita política.
  • Abra /console/guardrails, New guardrail, nomeie-o stream-pii-out.
  • Adicione uma regra:
    • Tipo: PII detection
    • Estágio: output
    • Ação: block ← corta o stream na correspondência; em um stream mask apenas detecta (ele redige respostas não-streaming)
  • Salve, depois vincule-o em /console/token via o menu Guardrail da chave.
Agora chame o gateway com stream: true, 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",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Email the customer from the record above"}
    ]
  }'
Se um delta corresponde, o scanner corta o stream, emite um aviso de substituição e fecha o canal — o cliente nunca recebe o resto. Se a resposta está limpa, cada delta passa intacto.
Um block de streaming detém tudo após a correspondência, mas não pode desfazer o envio de bytes já enviados antes de a correspondência cair. Se sua política exige que nem um byte ofensivo jamais chegue ao cliente, filtre a requisição não-streaming, onde o completion inteiro é segurado até a política o liberar.

​
4. PII Shield ao longo da matriz

O preset PII Shield é uma única regra pii, ação mask, estágio both. Mapeie-o na matriz e a cobertura é exatamente o que você esperaria de §2:
  • Estágio de input — totalmente ativo, streaming ou não. A requisição é mascarada antes de o modelo vê-la (o valor principal do mascaramento de input).
  • Estágio de output, não-streaming — o completion é mascarado antes de retornar.
  • Estágio de output, streaming — o scanner de stream detecta a correspondência mas não reescreve o delta hoje, então a forma mascarada não chega a um cliente com stream (o mascaramento de output in-stream está no roadmap).
Então o preset de mask não cobre PII fora de uma resposta com stream sozinho. Para manter PII fora de uma resposta com stream, escreva aquela regra como block (ou chame não-streaming) para que o stream seja cortado na correspondência. Veja PII Shield e formatos de mascaramento.

​
5. O que um block de streaming custa

Um block de streaming carrega a mesma contabilidade de qualquer block de output — o modelo já rodou, então o gateway cuida do reembolso para você:
  • Em uma resposta não-streaming a chamada retorna HTTP 400 guardrail_blocked nomeando o guardrail e a regra que disparou. Em uma resposta com stream os headers SSE 200 já estão na linha, então o block chega como um delta de substituição in-band final e um fechamento de canal limpo em vez de um 400.
  • Nenhuma cota é cobrada. Um block de input dispara antes da medição; um block de output (streaming ou não) reembolsa a cota pré-consumida uma vez que a resposta é rejeitada. De qualquer forma o chamador não paga nada.
  • A requisição é marcada como skip-retry — reexecutar o mesmo prompt apenas bloquearia de novo, então o gateway não queima um retry em outro canal.
Toda regra de output que dispara também registra um match no feed Matches do workspace (GET /api/guardrail/match, aberto a qualquer Member); a substring correspondente é capturada apenas quando o toggle Log raw content do guardrail está ligado (desligado por padrão). O detalhe completo vive em o erro guardrail_blocked e no feed de matches.

​
6. Prove seu combo de estágio/ação antes de publicar

Não adivinhe qual célula da matriz se aplica à sua política — verifique. Ambas as ferramentas rodam na sua sessão do console via a API de gerenciamento:

Aba Test

Cada editor de guardrail tem uma aba Test: cole uma amostra, escolha o estágio e rode a política atual sem chamada upstream e sem cota. Veja o veredito e, para regras de mask, o texto renderizado. O sandbox Test é gateado para Developer+ (ele pode disparar chamadas pagas de judge/grounding e requisições de integração outbound).

Aba Eval

A aba Eval pontua um guardrail contra corpora JSONL empacotados ou personalizados — útil para confirmar que uma regra de block pega um vazamento conhecido antes de você vincular uma chave. Rodar um eval precisa apenas de acesso de leitura (viewer+).
Veja testes e eval e ajustar falsos positivos para profundidade.

​
7. Para onde ir a seguir

Regras stream-safe

Como o scanner corta um stream SSE em pleno voo, e como escrever uma política que se sustenta em tráfego streaming.

Estágio de output

Filtragem da resposta do modelo — block vs. mask, o reembolso de cota e grounding.

Estágio de input

Filtragem da requisição antes do modelo — mascaramento incluído, streaming ou não.

Ações

block, mask, flag, annotate e spotlight em profundidade — quando cada um é a escolha certa.
Guardrails — cada tipo de regra, campo e rota, incluindo grounding e o LLM judge.