> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # PII Redaction > Redija informações de identificação pessoal com o plugin pii_redaction antes que as requisições cheguem ao provedor de LLM e, depois, restaure os valores na resposta. 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 `` ou ``. > [!NOTE] > > Esta funcionalidade está em Beta. ## Início rápido Adicione uma entrada `pii_redaction` ao array `plugins`. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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" }] }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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) ``` ```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](#routes-that-run-the-plugin), 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](#configuration). > [!NOTE] > > 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](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) para executar a redação no tráfego que essa regra corresponde, com uma configuração própria por regra. Uma [condição](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#conditions) **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: 1. **Redigir**: a PII detectada na requisição é substituída por placeholders tipados antes que a requisição saia do **AI Gateway**. 2. **Gerar**: o provedor processa o texto com placeholders e retorna uma resposta que mantém os placeholders intactos. 3. **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**](/docs/pt-BR/ai-gateway/features/responses-api.md) (`/v3/router/responses`) | O input da requisição, restaurado na resposta | | [**Chat Completions**](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) (`/v3/router/chat/completions`) | As mensagens da requisição, restauradas na resposta | | [**Completions**](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) (`/v3/router/completions`) | O prompt da requisição, restaurado na resposta | | [**Embeddings**](/docs/pt-BR/ai-gateway/features/embeddings.md) (`/v3/router/embeddings`) | Apenas o input da requisição; a resposta não tem texto retornado para restaurar | | [**Rerank**](/docs/pt-BR/ai-gateway/features/rerank-and-moderations.md#rerank) (`/v3/router/rerank`) | A consulta e os documentos da requisição; os documentos retornados na resposta são restaurados | | [**Images**](/docs/pt-BR/ai-gateway/features/multimodal.md) (`/v3/router/images/generations`) | Apenas o prompt da requisição; a geração de imagens não retorna texto | | [**Anthropic Messages**](/docs/pt-BR/ai-gateway/features/anthropic-messages-api.md) (`/v3/anthropic/v1/messages`) | As mensagens da requisição, restauradas na resposta | | [**Web Search**](/docs/pt-BR/ai-gateway/features/web-search.md) (`/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. > [!NOTE] > > 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`. | > [!NOTE] > > `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`. ```json Regions theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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"] }] }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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'] }, ], }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```json Entity types with per-entity thresholds theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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" }] }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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' }], }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. > [!NOTE] > > 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. > [accordion] 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` > [accordion] Bélgica (be) > > `BE_ENTERPRISE_NUMBER`, `BE_NATIONAL_NUMBER` > [accordion] Alemanha (de) > > `DE_TAX_ID`, `DE_VAT_NUMBER` > [accordion] França (fr) > > `FR_INSEE`, `FR_SIREN` > [accordion] Reino Unido (gb) > > `GB_NHS`, `GB_NINO` > [accordion] Países Baixos (nl) > > `BSN`, `KVK_NUMBER`, `NL_DRIVER_LICENSE`, `NL_ONDERWIJSNUMMER`, > `NL_PAYROLL_TAX_ID`, `NL_RSIN` > [accordion] 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 `` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.