Saltar para o conteúdo principal
Quando você precisa mascarar dados sensíveis que um prompt de LLM carrega — emails, números de cartão, IDs nacionais, segredos — o gateway reescreve cada correspondência no lugar antes de o modelo vê-la. Um valor mascarado vira uma tag tipada (jane@acme.com → [EMAIL]), então o modelo ainda lê um prompt coerente enquanto o valor bruto nunca deixa seu workspace. Esta página é a visão focada sobre o que o mascaramento renderiza, como mudar a tag, e como mascarar algumas entidades enquanto bloqueia outras em uma única regra. Para o motor completo — cada tipo de regra, estágio e rota — veja a referência de Guardrails, e para mascaramento na requisição especificamente, Regras do estágio de input.

​
1. Mascarar dados sensíveis que prompts de LLM carregam, com tags tipadas

Uma regra pii com a ação mask detecta uma entidade e substitui cada correspondência por uma tag de redação tipada — um rótulo em maiúsculas entre colchetes que nomeia o que foi removido sem revelar o valor:
EntidadeTag renderizada
email[EMAIL]
credit_card[CREDIT_CARD]
ssn[SSN]
O conjunto completo de detectores embutidos — email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address, mais os regionais jp_mynumber, kr_rrn e cn_resident_id — renderiza cada um sua própria tag entre colchetes ([PHONE], [IBAN], [JP_MYNUMBER], e assim por diante). A tag é determinística: a mesma entidade sempre renderiza o mesmo rótulo, então os prompts downstream permanecem estáveis e seus logs se leem limpos.
Tags tipadas vencem um [REDACTED] genérico para a qualidade do modelo. O modelo ainda sabe que está olhando para um email vs. um número de conta vs. um número de telefone, então pode continuar raciocinando sobre o formato dos dados — “reply to [EMAIL]” continua uma instrução acionável — sem nunca segurar o valor real.
O mascaramento de input está totalmente ativo — o gateway reescreve o prompt antes de ele chegar ao modelo, streaming ou não. O mascaramento de output está ativo em respostas não-streaming também: uma regra mask no estágio de output reescreve a completion antes de ela retornar. Apenas o mascaramento de output em streaming está no roadmap; em uma resposta com stream, prefira block no estágio de output. Veja Cobertura de streaming para a matriz exata de estágio/stream.

​
2. Um exemplo concreto

Escreva a regra no console sob sua própria sessão — config de guardrail exige Developer+, não uma chave de relay. Adicione uma única regra pii a um guardrail chamado pii-shield: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ssn"]
}
Vincule-o a uma chave (defina guardrail_id, ou marque-o como o padrão do workspace — veja Vincular a uma chave), depois chame o gateway com essa chave de relay sk-orca-...: 
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 about her SSN 123-45-6789"}
    ]
  }'
O gateway reescreve o prompt para “Reply to [EMAIL] about her SSN [SSN]” antes de encaminhar. O modelo upstream nunca vê o endereço ou o número. Prove a renderização exata na aba Test do editor primeiro (sem chamada upstream, sem cota) — veja Teste e eval.

​
3. Sobrescreva a tag com mask_with

Entidades embutidas renderizam uma tag fixa. Entidades personalizadas — seus próprios detectores regex empilhados sobre o conjunto embutido — permitem definir o texto de substituição você mesmo com mask_with: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP-[0-9]{6}",
      "mask_with": "[STAFF_ID]"
    }
  ]
}
mask_with é a string de substituição verbatim para as correspondências daquela entidade. EMP-004217 vira [STAFF_ID]. Deixe vazio e a correspondência renderiza a tag padrão [<UPPERCASE_NAME>] — aqui, [EMPLOYEE_ID] — então um detector personalizado sempre produz uma redação legível e tipada mesmo sem override.
name (ASCII minúsculo / dígitos / underscore, deve começar com uma letra), pattern (um regex Go RE2 — tempo linear, sem backreferences), checksum opcional (luhn valida números em formato de cartão) e mask_with opcional. Até 25 entidades personalizadas por regra — cada uma é uma varredura sobre o texto completo, então o limite mantém o caminho quente linear. Veja Entidades de PII personalizadas.
Um name flui para os logs de auditoria e o feed de Matches sem aspas, então mantenha-o em letras ASCII minúsculas, dígitos e underscores começando com uma letra (ex.: employee_id, internal_ticket). O validador rejeita qualquer outra coisa.

​
4. Mascarar algumas entidades, bloquear outras — entity_actions

Uma única regra pii pode aplicar ações diferentes a entidades diferentes via entity_actions, em vez de empilhar três regras sobrepostas. O formato clássico: mascarar dados de contato de baixa sensibilidade, mas bloquear os campos de alta sensibilidade totalmente. 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Aqui email, phone e ip seguem o mask de nível superior da regra e renderizam [EMAIL] / [PHONE] / [IP]; uma correspondência de credit_card ou ssn em vez disso bloqueia a requisição inteira com HTTP 400 guardrail_blocked.
CampoRegra
ChavesDevem ser uma entidade declarada na regra (embutida ou personalizada).
Valoresblock, mask, flag ou annotate.
Uma requisição bloqueada não custa cota — um block no estágio de input dispara antes da medição. Uma requisição mascarada passa com o texto sanitizado. Então uma regra pode redigir silenciosamente os campos rotineiros e parar de vez os regulados, com um único vínculo e nenhuma mudança na aplicação.

​
5. Mask vs. block vs. flag

O mascaramento é uma das ações que uma regra (ou override por entidade) pode tomar. Escolha por quanto você quer perturbar o tráfego:

mask

Redige a correspondência para uma tag tipada e deixa a requisição passar com o texto sanitizado. O modelo nunca vê o valor bruto.

block

Rejeita a requisição inteira com HTTP 400 guardrail_blocked. Nada chega ao modelo. Use para dados que nunca devem transitar.

flag

Não muda nada no tráfego — apenas registra um match. Meça com que frequência uma regra dispararia antes de aplicá-la.
Uma boa adoção é flag → mask → block: flag para dimensionar o impacto, mask quando você confiar no detector, e reserve block para os campos que você não pode deixar passar de jeito nenhum. Veja Ações e Ajustar falsos positivos.

​
6. Verifique o que foi mascarado

Toda regra que dispara registra um match no feed de Matches do workspace — tipo de regra, ação, estágio e uma string de detalhe. A própria substring correspondente (o email bruto, o número de cartão real) é registrada apenas quando Log raw content está ligado, o que está desligado por padrão — a postura conservadora de privacidade, já que o objetivo é manter valores brutos fora dos seus logs.
Ligue Log raw content apenas quando você genuinamente precisa da substring para triagem, e apenas por guardrail. Com ele desligado, o feed prova que um [CREDIT_CARD] foi mascarado sem nunca armazenar o número. O toggle não é retroativo. Veja Logging e privacidade.

​
7. Para onde ir a seguir

Leia a referência de Guardrails para o motor completo, ou exposição de PII e vazamento de segredos para as ameaças que o mascaramento é construído para conter.