PII Redaction

O plugin pii_redaction modifica diretamente o conteúdo da requisição e da resposta. Ele é executado em todas as requisições correspondentes, sem precisar de uma condição de regra separada.

Casos de uso

Manter nomes, e-mails e números de conta fora dos logs de provedores terceiros.
Atender a requisitos de tratamento de dados sem reescrever os prompts em cada serviço.
Enviar tickets de suporte sensíveis a um modelo preservando a resposta para o usuário final.
Excluir PII bruta do armazenamento de traces sem deixar de rastrear a requisição de ponta a ponta.

O plugin pii_redaction detecta informações de identificação pessoal na requisição, substitui cada valor por um placeholder antes que o provedor o veja e restaura os valores originais na resposta. O provedor recebe apenas placeholders como <EMAIL_ADDRESS_1> ou <PERSON_2>.

Esta funcionalidade está em Beta.

Início rápido

Adicione uma entrada pii_redaction ao array plugins.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Email the invoice to jane.doe@example.com",
    "plugins": [{ "id": "pii_redaction", "language": "en" }]
  }'

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Email the invoice to jane.doe@example.com',
  // @ts-ignore - Toqan Router extension
  plugins: [{ id: 'pii_redaction', language: 'en' }],
});

console.log(response.output_text);

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Email the invoice to jane.doe@example.com",
    extra_body={
        "plugins": [{"id": "pii_redaction", "language": "en"}]
    },
)

print(response.output_text)

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [
    { role: 'user', content: 'Email the invoice to jane.doe@example.com' },
  ],
  // @ts-ignore - Toqan Router extension
  plugins: [{ id: 'pii_redaction', language: 'en' }],
});

Redação no nível do workspace

Habilite a redação de PII para todas as requisições em Settings > Plugins, sem passar um array plugins em cada chamada. Depois de habilitado, o plugin do workspace é mesclado às requisições nas rotas que executam a redação de PII, e uma requisição não pode desativá-lo. Nas demais rotas, o conteúdo da requisição chega ao provedor sem redação. Quando o controle está ativado, um ícone aparece ao lado dele. Clique nele para abrir o painel de Configuração.

Uma requisição não pode desativar a redação do workspace.

Aplicar por routing rule

Anexe uma entrada pii_redaction a uma Routing Rule para executar a redação no tráfego que essa regra corresponde, com uma configuração própria por regra. Uma condição Project na regra restringe a regra às solicitações desse projeto.

Como funciona

O plugin executa um ciclo de redação em torno da geração:

Redigir: a PII detectada na requisição é substituída por placeholders tipados antes que a requisição saia do AI Gateway.
Gerar: o provedor processa o texto com placeholders e retorna uma resposta que mantém os placeholders intactos.
Restaurar: os valores originais são substituídos de volta na resposta antes que ela retorne ao chamador.

Rotas que executam o plugin

Rota	O que é redigido
Responses (`/v3/router/responses`)	O input da requisição, restaurado na resposta
Chat Completions (`/v3/router/chat/completions`)	As mensagens da requisição, restauradas na resposta
Completions (`/v3/router/completions`)	O prompt da requisição, restaurado na resposta
Embeddings (`/v3/router/embeddings`)	Apenas o input da requisição; a resposta não tem texto retornado para restaurar
Rerank (`/v3/router/rerank`)	A consulta e os documentos da requisição; os documentos retornados na resposta são restaurados
Images (`/v3/router/images/generations`)	Apenas o prompt da requisição; a geração de imagens não retorna texto
Anthropic Messages (`/v3/anthropic/v1/messages`)	As mensagens da requisição, restauradas na resposta
Web Search (`/v3/websearch`)	A consulta antes da chamada ao provedor e os campos de resultado na resposta

Nas rotas do gateway fora desta lista, o conteúdo da requisição chega ao provedor sem redação.

A detecção é executada no próprio modelo do Toqan Router, hospedado na infraestrutura do Toqan Router. O texto nunca é enviado a um serviço de terceiros para detecção de PII.

Rastreamento

A redação é rastreada no próprio processo como spans filhos da requisição: pii-redact para a passagem de entrada e pii-restore para a passagem de saída. Cada span traz o language configurado, a política de falha, a quantidade de entidades solicitadas, a quantidade de placeholders e o resultado. persist_redacted_to_traces controla se a forma redigida (com placeholders) ou o original restaurado é armazenado no conteúdo do trace; o padrão é true (forma redigida armazenada).

Configuração

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	Discriminador do plugin. Deve ser `pii_redaction`.
`language`	string	Não	Idioma do detector: `en`, `nl`, `de`, `es`, `fr`, `it` ou `auto` para detectá-lo por requisição. O padrão é `auto`. Consulte o conjunto atual em `GET /v2/pii/capabilities`.
`regions`	string[]	Não	Cobertura por região. Códigos ISO 3166-1 alfa-2 em minúsculas, ou `["all"]`. Redige todos os tipos de entidade vinculados às regiões listadas, além do catálogo base.
`entities`	string[]	Não	Cobertura explícita. Tipos de entidade em MAIÚSCULAS a serem redigidos. Sozinho, funciona como uma allowlist estrita; junto com `regions`, soma-se à cobertura das regiões. Omita ambos para redigir todas as regiões.
`entity_thresholds`	object	Não	Limites de confiança por entidade em `[0,1]`, indexados pelo tipo de entidade. Toda chave também deve aparecer em `entities`.
`on_failure`	string	Não	Comportamento quando a redação não está disponível: `block` ou `passthrough`. O padrão é `block`.
`threshold`	number	Não	Limite global de confiança do detector em `[0,1]`, aplicado a todos os tipos. O padrão é `0.5`.
`persist_redacted_to_traces`	boolean	Não	Armazena nos traces a forma redigida em vez do original restaurado. O padrão é `true`.

GET /v2/pii/capabilities é a fonte de verdade para o catálogo atual de entidades, as regiões compatíveis, o mapeamento de região para entidade (region_entities), os idiomas compatíveis e os limites padrão. O catálogo cresce com o serviço, portanto trate qualquer lista nesta página como um retrato do momento, e não como o conjunto completo.

Limite de detecção

O parâmetro threshold define a pontuação de confiança global, na primeira passagem, a partir da qual um valor detectado é considerado PII, e se aplica a todos os tipos. O intervalo vai de 0 a 1; o padrão é 0.5.

Valor	Comportamento
`1`	Confiança muito alta exigida: menos detecções, mais valores não detectados.
`0`	Quase nenhuma confiança exigida: mais detecções, mais falsos positivos.

As pontuações são reforçadas para formatos específicos de um idioma (por exemplo, um BSN holandês recebe uma pontuação maior quando o idioma detectado ou selecionado é o holandês). Ajuste o limite apenas quando houver um problema observado: diminua-o se PII real não estiver sendo detectada e aumente-o se muitos valores que não são PII estiverem sendo redigidos. Quando entity_thresholds nomeia um tipo, esse valor substitui threshold para o tipo e pode ficar acima ou abaixo dele. Um valor maior detecta menos ocorrências desse tipo, um valor menor detecta mais, e os tipos sem substituição permanecem em threshold.

Seleção de cobertura

A cobertura é selecionada de duas formas. regions cobre regiões inteiras: todos os tipos de entidade vinculados às regiões listadas são redigidos, além do catálogo base. entities é uma lista explícita de tipos de entidade a serem redigidos e, sozinho, é estrito — nada fora da lista é redigido. Defina ambos e os dois são unidos: a cobertura das regiões mais os tipos nomeados, de modo que entities amplia em vez de restringir. Omita ambos e todas as regiões são redigidas: não selecionar nada é a solicitação mais ampla, não a mais restrita. Esse padrão depende de entities estar vazio, portanto nunca pode afrouxar uma allowlist — entities sozinho continua estrito.

Regiões

Os códigos de região são ISO 3166-1 alfa-2 em minúsculas, por exemplo nl, gb, be, de, fr e us. O Reino Unido é gb, nunca uk. O valor ["all"] é exclusivo: cobre todas as regiões compatíveis e não pode ser combinado com outros códigos de região. Consulte o conjunto atual de regiões compatíveis e os tipos vinculados a cada uma em GET /v2/pii/capabilities.

Regions

{
  "id": "pii_redaction",
  "language": "en",
  "regions": ["nl", "gb"],
  "threshold": 0.6,
  "on_failure": "block"
}

Tipos de entidade

Os nomes dos tipos de entidade ficam em MAIÚSCULAS, por exemplo PERSON, EMAIL_ADDRESS e BSN. Um tipo específico de região que seja nomeado é detectado mesmo sem nomear sua região, de modo que os tipos de uma região podem ser escolhidos individualmente em vez de incluir a região inteira.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Contact Jane Doe at jane.doe@example.com",
    "plugins": [{
      "id": "pii_redaction",
      "language": "en",
      "entities": ["EMAIL_ADDRESS"]
    }]
  }'

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Contact Jane Doe at jane.doe@example.com',
  // @ts-ignore - Toqan Router extension
  plugins: [
    { id: 'pii_redaction', language: 'en', entities: ['EMAIL_ADDRESS'] },
  ],
});

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Contact Jane Doe at jane.doe@example.com",
    extra_body={
        "plugins": [{"id": "pii_redaction", "language": "en", "entities": ["EMAIL_ADDRESS"]}]
    },
)

Limites por entidade

entity_thresholds mapeia um tipo de entidade para um limite de confiança em [0,1]. Ele apenas ajusta a confiança; nunca altera quais tipos são redigidos. Toda chave também deve aparecer em entities: uma chave ausente de entities, ou qualquer chave quando entities está vazio, é rejeitada com um erro de validação. O ajuste por entidade se aplica aos tipos nomeados em entities. Para ajustar um tipo vinculado a uma região, nomeie esse tipo em entities — junto com regions, se o restante da região deve continuar coberto — e defina seu limite. region_entities em GET /v2/pii/capabilities lista os tipos vinculados a cada região.

Entity types with per-entity thresholds

{
  "id": "pii_redaction",
  "language": "en",
  "entities": ["PERSON", "EMAIL_ADDRESS", "BSN"],
  "entity_thresholds": {
    "PERSON": 0.85,
    "BSN": 0.7
  },
  "threshold": 0.5,
  "on_failure": "block"
}

Modos de falha

A política on_failure decide o que acontece quando o serviço de detecção não pode ser executado:

Modo	Comportamento
`block`	Falha fechada. A requisição é rejeitada e nada chega ao provedor. Padrão.
`passthrough`	Falha aberta. O texto original, sem redação, é enviado ao provedor.

Por padrão, o serviço de detecção aguarda até 90 segundos antes de exceder o tempo limite e aplicar a política on_failure.

O guardrail sempre falha fechado

on_failure pertence apenas ao plugin pii_redaction. O guardrail orq_pii_detection sempre falha fechado: se o serviço de detecção estiver indisponível ou a chamada de detecção apresentar erro, o texto é tratado como se contivesse PII e a requisição é bloqueada. Não há como fazer um guardrail falhar aberto, e definir on_failure nas options de um guardrail é rejeitado no momento da gravação em vez de ser ignorado silenciosamente: um controle de segurança cuja configuração armazenada não corresponde ao que ele faz é pior do que um sem nenhuma configuração. Use o plugin quando precisar de um comportamento de falha configurável. Vale a pena conhecer uma consequência antes de um incidente, e não durante: uma regra de guardrail sem projeto e sem expressão se aplica a todo o workspace e corresponde a todas as requisições. Uma indisponibilidade do serviço de detecção, portanto, bloqueia todo o tráfego de /responses, /chat/completions e /messages nesse workspace. Esse é o comportamento de falha fechada pretendido, não um defeito, mas significa que um guardrail de PII aplicado a todo o workspace vincula a disponibilidade da inferência à disponibilidade do serviço de detecção.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Email the invoice to jane.doe@example.com",
    "plugins": [{ "id": "pii_redaction", "language": "en", "on_failure": "passthrough" }]
  }'

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Email the invoice to jane.doe@example.com',
  // @ts-ignore - Toqan Router extension
  plugins: [{ id: 'pii_redaction', language: 'en', on_failure: 'passthrough' }],
});

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Email the invoice to jane.doe@example.com",
    extra_body={
        "plugins": [{"id": "pii_redaction", "language": "en", "on_failure": "passthrough"}]
    },
)

Tipos de entidade compatíveis

GET /v2/pii/capabilities é o catálogo atual e a única lista oficial: ele cresce com o detector, e languages, base_entities, all_entities, regions e region_entities vêm todos dele. As listas abaixo são um retrato do momento para orientação. Os tipos de entidade base não precisam de região: são detectados sempre que regions está definido. Não definir regions nem entities cobre todas as regiões, incluindo os tipos base. Os tipos regionais são detectados quando sua região é selecionada ou quando o tipo é nomeado em entities. Com apenas entities, nada é detectado além dos tipos nomeados, incluindo os tipos base.

A lista base é o que o catálogo classifica como independente de região, não o que uma determinada versão do detector emite na prática. Vários desses tipos têm reconhecedores mais restritos do que a entrada do catálogo sugere, então teste o detector antes de contar com a detecção de um tipo específico sem configuração.

Base (todas as regiões)

AGE, API_KEY, BANK_ROUTING, BIC, BIOMETRIC_ID, BLOOD_TYPE, CREDIT_CARD, CRYPTO, DATE_TIME, DEVICE_ID, EDUCATION_LEVEL, EMAIL_ADDRESS, EMPLOYMENT_STATUS, GENDER, HEALTH_PLAN_ID, HTTP_COOKIE, IBAN_CODE, ID, IMEI, IP_ADDRESS, JOB_TITLE, JWT, LANGUAGE, LICENSE_NUMBER, LICENSE_PLATE, LOCATION, MAC_ADDRESS, MEDICAL_RECORD, NRP, ORGANIZATION, PASSPORT, PASSWORD, PERSON, PHONE_NUMBER, PIN, POLITICAL_VIEW, RACE_ETHNICITY, RELIGIOUS_BELIEF, SEXUALITY, TAX_ID, URL, UUID, VEHICLE_ID

Bélgica (be)

BE_ENTERPRISE_NUMBER, BE_NATIONAL_NUMBER

Alemanha (de)

DE_TAX_ID, DE_VAT_NUMBER

França (fr)

FR_INSEE, FR_SIREN

Reino Unido (gb)

GB_NHS, GB_NINO

Países Baixos (nl)

BSN, KVK_NUMBER, NL_DRIVER_LICENSE, NL_ONDERWIJSNUMMER, NL_PAYROLL_TAX_ID, NL_RSIN

Estados Unidos (us)

MEDICAL_LICENSE, US_BANK_NUMBER, US_DRIVER_LICENSE, US_ITIN, US_PASSPORT, US_SSN

Nomes de tipos de entidade que mudaram

Estas chaves foram renomeadas ou removidas. Uma requisição que nomeia uma chave antiga é rejeitada. Configurações de PII armazenadas (padrões do workspace, regras de roteamento e de guardrail, MCP gateways, guardrails orq_pii_detection) que ainda contêm uma delas são lidas como a substituta. Salve-as com a nova chave; o painel faz isso por você quando você abre e salva as configurações:

Chave antiga	Substituta
`JOBTITLE`	`JOB_TITLE`
`UK_NHS`	`GB_NHS`
`TITLE`	nenhuma: o tipo deixou de existir
`ID_CARD`	`ID`

JOBTITLE, UK_NHS e TITLE mudaram quando o catálogo passou a ser organizado por região. ID_CARD foi mesclado em ID; os dois nomes descreviam a mesma coisa. Números de documentos de identidade continuam sendo redigidos, mas retornam como ID. Se um cliente lê entity_type ou nomes de placeholders como <ID_CARD_1> nas respostas, use ID na correspondência. ID também abrange outros identificadores, como números de clientes e de funcionários, portanto uma seleção salva contendo apenas ID_CARD agora também os redige. Um limite salvo para ID_CARD é mantido apenas quando ID tem um limite próprio e, nesse caso, aplica-se o menor dos dois; sozinho, ele é descartado, então ID usa o limite padrão em vez de um mínimo definido apenas para documentos de identidade. Os tipos dos EUA mantêm seus nomes, mas agora são vinculados à região us em vez de language: en; portanto, uma configuração que dependia do inglês para selecioná-los precisa de regions: ["us"] ou de uma lista entities explícita.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Casos de uso

Início rápido

Redação no nível do workspace

Aplicar por routing rule

Como funciona

Rotas que executam o plugin

Rastreamento

Configuração

Limite de detecção

Seleção de cobertura

Regiões

Tipos de entidade

Limites por entidade

Modos de falha

O guardrail sempre falha fechado

Tipos de entidade compatíveis

Nomes de tipos de entidade que mudaram

​Casos de uso

​Início rápido

​Redação no nível do workspace

​Aplicar por routing rule

​Como funciona

​Rotas que executam o plugin

​Rastreamento

​Configuração

​Limite de detecção

​Seleção de cobertura

​Regiões

​Tipos de entidade

​Limites por entidade

​Modos de falha

​O guardrail sempre falha fechado

​Tipos de entidade compatíveis

​Nomes de tipos de entidade que mudaram

Casos de uso

Início rápido

Redação no nível do workspace

Aplicar por routing rule

Como funciona

Rotas que executam o plugin

Rastreamento

Configuração

Limite de detecção

Seleção de cobertura

Regiões

Tipos de entidade

Limites por entidade

Modos de falha

O guardrail sempre falha fechado

Tipos de entidade compatíveis

Nomes de tipos de entidade que mudaram