Saltar para o conteúdo principal
O detector pii embutido cobre as entidades comuns — email, telefone, cartão de crédito, SSN, IBAN, JWT, chaves de nuvem. Mas seus dados sensíveis são seus: IDs de funcionário, números de caso internos, referências de conta de cliente, o formato de pedido de um parceiro. Uma entidade de PII personalizada permite ensinar a mesma regra de mascaramento a reconhecer esses formatos, para que o gateway os redija antes de o modelo — ou qualquer ferramenta downstream — sequer vê-los. Esta página cobre a única coisa que as entidades personalizadas adicionam à regra de detecção de PII: seus próprios detectores. Para o motor completo — cada tipo de regra, estágio e rota — veja a referência de Guardrails.
Cada passo aqui é uma ação de console no gateway hospedado (api.orcarouter.ai). Você escreve o guardrail sob sua própria sessão; apenas a chamada /v1/* final usa uma chave de relay sk-orca-.... Criar e editar guardrails exige Developer+ no workspace.

​
1. Quando você precisa de um guardrail detector de PII personalizado para LLM

O conjunto de entidades embutidas é fechado e compartilhado pelo motor, pelo validador e pelo construtor de regras. É a ferramenta certa para identificadores padrão. Recorra a uma entidade personalizada quando os dados que você quer redigir têm um formato previsível que nenhum embutido cobre:

Identificadores internos

IDs de funcionário (EMP482915), números de caso, refs de ticket, SKUs internos — qualquer coisa com um prefixo fixo e uma sequência de dígitos.

Números de conta e pedido

Referências de conta de cliente ou o formato de pedido de um parceiro que nunca deveria chegar a um modelo de terceiros verbatim.

Números com checksum

Números semelhantes a cartões ou de associação que passam um check de Luhn — adicione o checksum para cortar falsos positivos em sequências de dígitos parecidas.

Códigos específicos de domínio

Números de apólice, IDs de sinistro, seriais de dispositivo — qualquer token que seu setor trate como sensível mas os detectores genéricos não conhecem.
Uma entidade personalizada empilha sobre o conjunto embutido dentro de uma regra pii. Ela detecta correspondências e aplica a ação da regra — mask, block ou flag — exatamente como uma entidade embutida faz.

​
2. Anatomia de uma entidade personalizada

Uma entidade personalizada são três campos pequenos mais uma tag de máscara opcional. Você os adiciona no editor da regra pii em Custom entities:
CampoObrigatórioO que faz
namesimID estável, ex.: employee_id. ASCII minúsculo / dígitos / _, deve começar com uma letra. Flui para o feed de Matches e os logs de auditoria.
patternsimUm regex Go RE2 (tempo linear, sem backreferences). Deve compilar.
checksumnãoluhn valida cada correspondência com o algoritmo de Luhn. Apenas "" (nenhum) ou "luhn" são aceitos.
mask_withnãoSubstituição verbatim em uma ação de mask. O padrão é [<UPPERCASE_NAME>].
O name segue a mesma convenção de chave do resto do gateway — minúsculo, começa com uma letra, sem espaços ou hífens. Escolha um claro (case_number, partner_order_id); é o que você verá no feed de Matches quando a regra disparar.

​
O checksum de Luhn opcional

Muitos identificadores “em formato de número” — cartões de pagamento, alguns números de associação e conta — carregam um dígito verificador de Luhn (mod-10). Um regex simples como \d{16} corresponde a qualquer sequência de 16 dígitos, incluindo números de telefone, timestamps e totais de pedido. Definir checksum: "luhn" faz o detector disparar apenas quando os dígitos correspondentes também passam o check de Luhn, então sequências parecidas escapam de forma limpa e sua taxa de falsos positivos permanece baixa. Deixe vazio para tokens sem checksum como um ID de funcionário.

​
Sua própria tag de máscara

Em uma ação mask, um email embutido é renderizado como [EMAIL]. Uma entidade personalizada é renderizada como [<UPPERCASE_NAME>] por padrão — uma correspondência de employee_id vira [EMPLOYEE_ID]. Defina mask_with para sobrescrever isso verbatim (ex.: <id> ou ***) quando você quer um token de substituição específico no texto que o modelo recebe. Veja Formatos de mascaramento para as regras de renderização entre tipos de entidade.

​
3. Um exemplo concreto

Suponha que seus prompts carreguem IDs de funcionário na forma EMP seguido de seis dígitos, e você quer que sejam mascarados no estágio de input para que o modelo upstream nunca veja um ID real. Adicione uma única entidade personalizada a uma regra pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Essa regra mascara tanto emails padrão quanto seus IDs de funcionário na mesma passagem. Teste-a na aba Test antes de vincular uma chave: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Nada é enviado upstream e nada é medido. Depois vincule o guardrail a uma chave (veja Vincular a uma chave) e chame /v1/chat/completions exatamente como antes — o gateway mascara a requisição antes de encaminhar, sem mudança de SDK.
O mascaramento roda em ambos os estágios: uma regra de input redige a requisição antes de o modelo vê-la, e uma regra de output redige a resposta do modelo — incluindo respostas streaming, onde o scanner reescreve as correspondências in-band. As ações de block também são aplicadas em ambos os estágios. Para gatear as respostas do modelo, veja Regras do estágio de output.

​
Um exemplo com checksum

Para um número de associação semelhante a cartão, adicione o check de Luhn para que sequências de 16 dígitos que não são números válidos não correspondam: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Limites e validação

O construtor de regras valida cada entidade personalizada ao salvar — um detector ruim nunca chega ao caminho quente.
Cada entidade personalizada é uma varredura regex sobre o texto completo, então o limite por regra é 25. O limite mantém o caminho quente linear; padrões compilados são cacheados entre requisições. Precisa de mais formatos? Divida-os entre múltiplas regras pii no mesmo guardrail.
pattern é um regex Go RE2 — tempo linear, sem backreferences. O validador rejeita um padrão que não compila, com a entidade ofensora nomeada no erro.
Apenas "" (nenhum check) e "luhn" são aceitos. Qualquer outra coisa — "sha256", "mod10", até "LUHN" — é rejeitada ao salvar.
Um name deve começar com uma letra e usar apenas ASCII minúsculo, dígitos e underscores. Duas entidades personalizadas em uma regra não podem compartilhar um nome.

​
5. Overrides de ação por entidade

Uma entidade personalizada participa do mesmo mapa entity_actions que uma entidade embutida. Uma regra pii pode mascarar a maioria das coisas mas bloquear em um detector personalizado de alta sensibilidade — referencie a entidade pelo seu name: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
As chaves em entity_actions devem referenciar uma entidade embutida habilitada na regra ou o name de uma entidade personalizada; os valores devem ser block, mask, flag ou annotate. O validador rejeita qualquer outra coisa.

​
6. Para onde ir a seguir

PII Shield

A única regra de mascaramento sobre a qual as entidades personalizadas empilham — o conjunto de detectores embutidos e as tags de máscara tipadas.

Formatos de mascaramento

Como cada entidade é renderizada em uma ação de mask, e como mask_with a sobrescreve.

Detectores regex

Quando uma regra regex simples se encaixa melhor que uma entidade PII tipada.

Ajustar falsos positivos

Use o feed de Matches e o checksum para calibrar a precisão.
Leia a referência de Guardrails para a regra de PII completa — cada campo, o eval harness e a API completa — ou Crie seu primeiro guardrail para percorrer o loop de ponta a ponta do zero.