Encontrando dados pessoais

Cerca de 47 minutos min de leitura, com 11 exemplos em 13 seções.

Edição 2026.11.31 Exemplos aprovados em 19 de nov de 2026 108 de 108 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.31. Leia o original

Ao final deste capítulo, você será capaz de encontrar dados pessoais em uma plataforma de dados automaticamente e de dizer quanto deles você deixa passar. Você vai propor uma classificação para cada coluna a partir do nome, do tipo e de uma amostra reproduzível de seus valores; encontrar dados pessoais dentro de texto livre, trecho por trecho; e medir cada detector contra dados rotulados antes que alguém dependa dele. Ao longo do caminho, você vai executar os reconhecedores de padrões do Presidio offline, com limiares escolhidos por medição, compará-los com as detecções registradas de um modelo treinado para encontrar dados pessoais e classificar novamente apenas as colunas que uma mudança de esquema acrescenta.

Toda coluna da plataforma já tem uma classificação. O Capítulo 2 registrou uma em governance/metadata.toml, um arquivo que as pessoas revisam, e um arquivo revisado registra o que seus revisores acreditam que uma coluna contém. Na plataforma de aprendizagem online cujo armazém de dados este livro governa, três dessas crenças nunca foram verificadas. billing.payments.card_number é uma coluna legada cuja descrição diz que ela guarda números de cartão completos, e ninguém a examinou. crm.learners.notes é um texto livre que os agentes de suporte digitam, então seu nome não diz nada sobre o que há nele. Os alunos escrevem o que quiserem em chamados de suporte e avaliações de cursos. Nenhuma classificação de uma coluna inteira consegue proteger esse texto. Antes que ele possa ser mascarado, a plataforma precisa encontrar cada nome, e-mail e número de telefone nele, trecho por trecho, como o Capítulo 9 faz com as avaliações antes que o assistente de curso aprenda com elas.

Este capítulo constrói o módulo compartilhado do livro para essa tarefa, lib.pii: regras sobre nomes de colunas, amostras com semente fixa dos valores de uma coluna, um detector do Presidio configurado para rodar offline e código que pontua qualquer detector contra dados rotulados. Todo detector deste capítulo é medido contra um único arquivo, que chamamos de referência: data/platform/pii_spans.parquet. O gerador de dados da plataforma o escreve ao lado dos chamados e das avaliações, com cada trecho de dado pessoal que ele colocou no texto e seu início e fim exatos. Números de fatura, números de pedido e a data em que um problema aconteceu permanecem sem rótulo, porque a plataforma não os trata como dados pessoais.

Números de telefone, números de cartão e IBANs neste livro são aleatórios, como diz a ficha de dados, e nenhum exemplo imprime um deles inteiro: ele mascara todos os dígitos, exceto os quatro últimos.

Classificar colunas pelo esquema

Última alteração na edição 2026.11.27

A evidência mais barata sobre uma coluna é o seu esquema: o seu nome e o seu tipo. Uma regra sobre nomes não lê dado algum, então roda sobre um catálogo inteiro em um pull request, e pega as colunas cujos nomes dizem o que elas guardam, como email ou date_of_birth. Ferramentas de catálogo começam do mesmo jeito: a classificação automática do OpenMetadata inicia com um escaneador de nomes de colunas que confere os nomes contra expressões regulares (documentação do OpenMetadata). O tipo decide o que vem depois. Os valores de uma coluna de texto podem ser amostrados e escaneados, mas um timestamp não pode conter um e-mail, e escanear um com um padrão de data sinalizaria cada linha. Por isso, números, datas, timestamps e booleanos são classificados apenas pelo nome.

A plataforma guarda suas regras em governance/pii.toml, que contém todas as configurações do seu detector e passa por revisão como os metadados. As regras são 8 expressões regulares sobre nomes de colunas em minúsculas, cada uma indicando a entidade que sugere, e vence a primeira que casar. O mesmo arquivo associa cada entidade a uma classificação: um número de telefone a personal, um número de cartão ou um IBAN a sensitive. lib.pii.by_name aplica as regras. As regras percorrem todas as colunas do catálogo, e os resultados ficam ao lado dos metadados revisados:

column-name-rules.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Runs the name rules over every column of the catalog and compares each column they mark with the reviewed metadata.The prose rests on the count of marked columns that agree, and on the personal columns no rule marks."""from pyiceberg.types import StringTypefrom lib import metadata, piifrom lib.catalog import open_catalogcatalog = open_catalog()described = metadata.load()                   # the reviewed metadata, keyed by table and then by field ID# every column as (table, field): the field carries the ID the metadata is keyed by, so a renamed column still matchescolumns = [(table, f) for (namespace,) in sorted(catalog.list_namespaces())           for _, name in sorted(catalog.list_tables(namespace))           for table in [f"{namespace}.{name}"] for f in catalog.load_table(table).schema().fields]print("columns in the catalog:", len(columns))print("name rules:", len(pii.NAME_RULES))named = [(table, f, pii.by_name(f.name)) for table, f in columns if pii.by_name(f.name)]print("columns a name rule marks:", len(named))for table, f, entity in named:    print(f"  {table}.{f.name}: {entity}, so {pii.CLASSIFICATION[entity]}")agree = sum(pii.CLASSIFICATION[entity] == described[table].columns[f.field_id].classification            for table, f, entity in named)print("of them, agreeing with the metadata:", agree)# Only text is sampled: numbers, dates, timestamps and booleans are classified by name alone.text = [(table, f) for table, f in columns if isinstance(f.field_type, StringType)]print("columns of text, whose values can be sampled:", len(text))# Columns the metadata, reviewed by people, calls personal or sensitive, that no name rule marks.missed = [f"{table}.{f.name}" for table, f in columns if not pii.by_name(f.name)          and described[table].columns[f.field_id].classification in ("personal", "sensitive")]print("personal columns no name rule marks:", ", ".join(missed))
Saídapython column-name-rules.py
columns in the catalog: 64
name rules: 8
columns a name rule marks: 11
  billing.payments.card_number: CREDIT_CARD, so sensitive
  crm.instructors.full_name: PERSON, so personal
  crm.instructors.email: EMAIL_ADDRESS, so personal
  crm.instructors.payout_iban: IBAN_CODE, so sensitive
  crm.learners.full_name: PERSON, so personal
  crm.learners.email: EMAIL_ADDRESS, so personal
  crm.learners.phone: PHONE_NUMBER, so personal
  crm.learners.city: LOCATION, so personal
  crm.learners.street_address: LOCATION, so personal
  crm.learners.date_of_birth: DATE_TIME, so personal
  learning.events.ip_address: IP_ADDRESS, so personal
of them, agreeing with the metadata: 11
columns of text, whose values can be sampled: 29
personal columns no name rule marks: crm.learners.notes, learning.reviews.body, support.tickets.body

As regras concordam com os metadados onde disparam, e deixam passar o texto livre. Das 64 colunas do catálogo, as regras marcam 11, e todas as 11 concordam com a classificação que as pessoas lhes deram. Elas deixam passar três colunas que os revisores classificaram como personal: crm.learners.notes, learning.reviews.body e support.tickets.body. As três são texto livre, em que o nome descreve o contêiner, não o conteúdo. A coluna marcada que mais preocupa a plataforma, billing.payments.card_number, recebe sensitive apenas pelo seu nome, sem que ninguém descubra o que ela guarda. Números de cartão inteiros, os últimos quatro dígitos ou um token de um provedor de pagamento casariam todos com card_?(number|num|no).

As regras por nome são frágeis de um modo conhecido. Os autores do Sherlock, um modelo para detectar tipos de colunas, relatam que a correspondência por nome não é robusta a dados sujos e detecta apenas alguns tipos (Hulsebos et al., 2019). Por isso, a plataforma também lê valores, nas 29 colunas de texto que o seu catálogo contém.

Regra prática: Execute as regras por nome sobre todas as colunas primeiro, porque são gratuitas, e deixe que elas elevem uma classificação, nunca que a rebaixem. Mantenha as regras curtas, em código, e revisadas como qualquer outra regra. Trate qualquer coluna de texto livre, qualquer que seja o seu nome, como uma coluna que precisa ter seus valores amostrados, e classifique as colunas de outros tipos apenas pelo nome.

Execute o Presidio offline

Última alteração na edição 2026.11.31

Para ler valores, a plataforma usa o Presidio, uma biblioteca de código aberto para encontrar e mascarar dados pessoais. O analisador do Presidio executa reconhecedores: expressões regulares com somas de verificação, análise de números de telefone e um modelo de entidades nomeadas acessado por meio de um mecanismo de PLN. O mecanismo de PLN faz dois trabalhos, o reconhecimento de entidades nomeadas e a extração de características para as regras, como as palavras de contexto que elevam uma pontuação. Seu modelo padrão é o en_core_web_lg do spaCy (documentação do Presidio). Com 2.2.366, o AnalyzerEngine() sem argumentos baixa esse modelo quando ele não está instalado (fonte). Assim, um pipeline sem acesso à rede falha na primeira linha, e um pipeline com acesso instala um modelo de cerca de 400 MB como efeito colateral (en_core_web_lg 3.8.0).

lib.pii.detector configura o próprio mecanismo, com NoOpNlpEngine, que não carrega nenhum modelo de linguagem (fonte). O custo disso é o contexto. Com um modelo, o Presidio eleva a pontuação de um padrão quando uma palavra como "telefone" aparece perto da correspondência, comparando o lema de cada palavra próxima com os termos de contexto de cada reconhecedor (tutorial do Presidio sobre contexto). Sem modelo não há lemas, então o mecanismo não consegue usar as palavras de contexto do texto de forma alguma. O mecanismo tem ainda outro caminho para a rede. Seu reconhecedor de e-mail verifica domínios com o tldextract, que baixa a Public Suffix List na primeira vez que é usado (README do tldextract 5.4.0). Importar o Presidio importa o tldextract, cujo README diz que um TLDEXTRACT_PUBLIC_SUFFIX_LIST_URLS vazio desativa a busca, se for definido antes da importação. Por isso, lib/__init__.py, que o Python executa antes de qualquer módulo de lib do livro, esvazia a variável. Se um exemplo importasse o Presidio primeiro, o mesmo arquivo substituiria o extrator compartilhado do tldextract por outro sem nenhuma URL. lib.pii se recusa a carregar se alguma restar, e o tldextract usa a cópia da lista que vem com ele, de modo que o mesmo texto dá a mesma resposta em qualquer máquina.

Os padrões são testados em texto real: carregue todos os reconhecedores predefinidos e execute-os em um dos tickets de suporte da plataforma, que contém um nome, um e-mail, um número de telefone e uma data:

presidio-offline-engine.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · spacy 3.8.18 · tldextract 5.4.0 Aprovado
"""Loads Presidio's predefined recognizers on an engine that loads no language model, and runs them on one supportticket. The prose's point rests on the detections printed under the ticket, and on the assert that the model isn'tinstalled."""import spacyfrom lib import piifrom lib.platform import load# AnalyzerEngine() with no arguments loads spaCy's en_core_web_lg, and downloads it when it isn't installed.installed = spacy.util.is_package("en_core_web_lg")assert installed is False       # the pipeline assumes no model: a machine that has one fails here, not silentlyprint("en_core_web_lg installed:", installed)print("URLs tldextract would fetch the Public Suffix List from:", len(pii.suffix_list_urls()))detector = pii.detector()              # every predefined recognizer, on an NLP engine that loads no modelnames = sorted(r.name for r in detector.registry.recognizers)print("recognizers loaded:", len(names))print("recognizers:", ", ".join(names))print("default score threshold:", detector.default_score_threshold)# The ticket holds a phone number, which may be in service: masked() prints it with only its last four digits.ticket = pii.texts("tickets")[1421]         # one ticket with a name, an email, a phone number and a date of the problemfound = sorted(pii.detect(detector, ticket))print("ticket 1421:", pii.masked(ticket))for start, end, entity, score in found:    print(f"  {entity} on {pii.masked(ticket[start:end])}: {score:.2f}")# Where is the phone number valid? The recognizer reads it in each of its regions.phone = next(ticket[start:end] for start, end, entity, _ in found if entity == "PHONE_NUMBER")[learner] = [row["learner_id"] for row in load("support.tickets").to_pylist() if row["ticket_id"] == 1421][country] = [row["country"] for row in load("crm.learners").to_pylist() if row["learner_id"] == learner]print("the learner's country:", country)# The recognizer's built-in regions, not the learner's country.print("default regions where it's valid:",      ", ".join(r for r in pii.PhoneRecognizer.DEFAULT_SUPPORTED_REGIONS if pii.valid_phone(phone, r)))
Saídapython presidio-offline-engine.py
en_core_web_lg installed: False
URLs tldextract would fetch the Public Suffix List from: 0
recognizers loaded: 17
recognizers: CreditCardRecognizer, CryptoRecognizer, DateRecognizer, EmailRecognizer, IbanRecognizer, IpRecognizer, MacAddressRecognizer, MedicalLicenseRecognizer, NhsRecognizer, PhoneRecognizer, UrlRecognizer, UsBankRecognizer, UsItinRecognizer, UsLicenseRecognizer, UsPassportRecognizer, UsSsnRecognizer, UuidRecognizer
default score threshold: 0
ticket 1421: I can't open the videos in Introduction to Design Systems, they stop after a few seconds. It happened on 12/03 around 9pm. My colleague Jennifer Abbott (jennifer.abbott@example.net) wants to enrol as well. You can reach me on •••••••0440 after 6pm.
  DATE_TIME on 12/03: 0.10
  EMAIL_ADDRESS on jennifer.abbott@example.net: 1.00
  URL on example.net: 0.50
  PHONE_NUMBER on •••••••0440: 0.40
  US_BANK_NUMBER on •••••••0440: 0.05
  US_DRIVER_LICENSE on •••••••0440: 0.01
the learner's country: US
default regions where it's valid: BR

Os padrões do Presidio, neste mecanismo, encontram o e-mail e o número de telefone, e deixam passar o nome do colega. en_core_web_lg não está instalado, então um AnalyzerEngine() simples tentaria baixá-lo, e o tldextract tem 0 URLs de onde buscar sua lista. O mecanismo sem modelo carrega 17 reconhecedores, e nenhum deles procura nomes, então Jennifer Abbott, a colega do ticket, passa despercebida. Seu e-mail é encontrado com pontuação 1.00, e o domínio dele é encontrado de novo como URL, com 0.50. O número de telefone do aluno, um número de 11 dígitos digitado sem separadores, é encontrado três vezes: como número de telefone com 0.40, como número de conta bancária dos EUA com 0.05 e como carteira de motorista dos EUA com 0.01. Mesmo o número de telefone é encontrado por acaso. O país do aluno é US, mas entre as regiões padrão do Presidio, incluindo os EUA, os dígitos só são válidos em BR. A data do problema, 12/03, também é lida como data, o que não diz nada sobre ninguém.

Essas pontuações não são probabilidades. Cada padrão tem uma pontuação constante, e padrões fracos recebem pontuações baixas, como explica o tutorial do Presidio para um CEP de cinco dígitos (documentação do Presidio). Um número de conta bancária dos EUA é qualquer sequência de 8 a 17 dígitos (entidades suportadas), e o FAQ admite que uma carteira de motorista "pode ser qualquer número de 9 dígitos" (FAQ). O limiar padrão do analisador é 0, então toda correspondência fraca é retornada.

Regra prática: Configure o mecanismo do Presidio explicitamente: NoOpNlpEngine quando você executar apenas padrões, ou um modelo fixado que você mesmo instale quando precisar de seus nomes. Nunca chame AnalyzerEngine() sem argumentos em um pipeline, e fixe tudo o que um reconhecedor baixaria, como a Public Suffix List. Leia cada pontuação como uma constante definida para o seu padrão, nunca como uma probabilidade.

Amostre os valores de uma coluna da mesma forma em cada execução

Última alteração na edição 2026.11.27

Varrer cada valor de cada coluna de texto é lento demais para qualquer armazém de dados, então as ferramentas amostram. O fluxo de trabalho do OpenMetadata amostra linhas e as verifica com um mecanismo de reconhecimento de entidades (documentação do OpenMetadata). Uma amostra exige três decisões. Quais linhas: uma amostra aleatória, e não as primeiras linhas nem um bloco a partir de um início aleatório. O Sensitive Data Protection, do Google, oferece um modo de início aleatório, RANDOM_START, que começa em uma linha aleatória e segue adiante (documentação do Google Cloud). Em uma tabela ordenada pela data de cadastro, esse bloco é uma coorte de aprendizes. As mesmas linhas em cada execução, para que uma classificação possa ser reproduzida e uma mudança nela signifique que os dados mudaram. E quantas, conforme o quão raro é o dado que você precisa capturar.

A amostragem por reservatório do DuckDB aceita uma semente, mas ela só produz uma amostra reproduzível quando o DuckDB roda em uma única thread, como alerta a documentação do DuckDB 2.0.0. lib.pii.sample define uma única thread, filtra os NULLs e depois sorteia uma amostra por reservatório com semente.

Um valor raro exige uma amostra maior, e a aritmética mostra quanto maior. Chame de p a proporção de valores que contêm dados pessoais. A chance de que n valores amostrados incluam pelo menos um é

chance = 1 − (1 − p)ⁿ

e o n que dá 99% de chance é ln(0.01) / ln(1 − p). Trata-se de uma regra prática: ela considera os sorteios independentes, o que uma amostra sem reposição de milhares de linhas quase é.

Aplique a fórmula: sorteie 20 notas de crm.learners duas vezes e compare as chances sobre todas as linhas com as chances sobre apenas as notas.

seeded-column-sample.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Draws the same twenty notes twice from a seeded reservoir sample, then counts the notes that hold personal data, to seehow many sampled values a rare value needs. The prose rests on the assert that the draws match, the two chances and the sample sizes."""import mathfrom lib import piifrom lib.catalog import open_catalogfrom lib.warehouse import connectcon = connect(open_catalog(["crm.learners"]))first = pii.sample(con, "crm.learners", "notes", rows=20)second = pii.sample(con, "crm.learners", "notes", rows=20)     # the same call: the seed and one thread (set in lib.pii.sample) make the draws matchassert second == firstprint("second draw, same notes as the first:", "yes" if second == first else "no")# Notes can hold a phone number, which may be in service: masked() prints it with only its last four digits.print("first sampled notes:", " | ".join(pii.masked(note) for note in first[:3]))# How rare is personal data in the column? Run the detector over every note, once, to know.detector = pii.platform_detector()[(rows, notes)] = con.sql("select count(*), count(notes) from crm.learners").fetchall()   # count(notes) skips NULLsevery_note = [note for (note,) in con.sql("select notes from crm.learners where notes is not null").fetchall()]holding = sum(bool(pii.detect(detector, note)) for note in every_note)print("learners:", f"{rows:,}")print("learners with notes:", notes)print("notes holding personal data the detector finds:", holding)# The chance that n sampled values hold at least one of them is 1 - (1 - p)^n, for a share p of the values.for unit, p in (("rows", holding / rows), ("notes", holding / notes)):   # p counted over all learners, then over the notes    print(f"chance 20 sampled {unit} catch one:", f"{1 - (1 - p) ** 20:.1%}")    print(f"sampled {unit} needed for a 99% chance:", math.ceil(math.log(0.01) / math.log(1 - p)))   # solves for nprint("values the platform samples per text column:", pii.ROWS)# The rarest share p that a sample of ROWS values still catches 99% of the time, printed as 1 in a whole number.print("rarest share that sample catches 99% of the time:", f"1 in {math.floor(1 / (1 - 0.01 ** (1 / pii.ROWS)))}")
Saídapython seeded-column-sample.py
second draw, same notes as the first: yes
first sampled notes: VIP: bought a team licence. | Asked about invoices for their employer. | Called about a refund, call back on (•••)•••-1366x•••.
learners: 5,000
learners with notes: 527
notes holding personal data the detector finds: 138
chance 20 sampled rows catch one: 42.9%
sampled rows needed for a 99% chance: 165
chance 20 sampled notes catch one: 99.8%
sampled notes needed for a 99% chance: 16
values the platform samples per text column: 200
rarest share that sample catches 99% of the time: 1 in 43

Os sorteios se repetem, então a amostra pode ser auditada. Com a mesma semente, o segundo sorteio devolve as mesmas 20 notas, e a terceira nota já contém um número de telefone, que a saída mascara.

Dos 5,000 aprendizes, 527 têm notas, e 138 dessas contêm dados pessoais que o detector da plataforma, ajustado mais adiante neste capítulo, encontra. Os NULLs diluem a amostra, pois um NULL não pode conter dados pessoais. Vinte linhas amostradas capturam dados pessoais em 42.9% dos casos, e uma chance de 99% exige 165 linhas. Contadas apenas as notas que existem, vinte capturam esses dados em 99.8% dos casos, e 16 bastam para 99%.

Regra prática: Amostre valores não nulos, com semente fixa, em uma única thread, e guarde a semente junto com o resultado. Dimensione a amostra a partir do dado pessoal mais raro que você precisa capturar, com n = ln(0.01) / ln(1 − p) para 99%. A plataforma amostra 200 valores por coluna de texto, definido em governance/pii.toml, o que captura dados pessoais presentes em 1 in 43 valores ou mais em 99% das vezes. Para algo mais raro, varra a coluna inteira ou a classifique por regra.

Classificar colunas a partir de seus valores

Última alteração na edição 2026.11.28

As regras de nome e uma amostra reproduzível se combinam em uma proposta por coluna. lib.pii.classify adota a classificação mais restritiva que qualquer uma das duas sustenta: a entidade que o nome sugere e cada entidade encontrada em qualquer valor amostrado. Uma coluna sem evidência recebe internal, porque um detector que não encontrou nada não mostrou nada, e só uma pessoa decide que uma coluna é public.

Adotar a mais restritiva é uma escolha. A ferramenta própria do Presidio para tabelas, Presidio structured, atribui a cada coluna uma única entidade, e seu padrão, Most Common, escolhe a entidade que ocorre com mais frequência (documentação do Presidio). Isso serve para escolher como mascarar uma coluna. Para classificá-la, uma coluna que contém um número de cartão em 200 valores continua contendo números de cartão.

As propostas para todas as colunas do catálogo, feitas pelo detector da plataforma, cujos reconhecedores uma seção posterior escolhe, mostram onde cada uma difere dos metadados revisados:

classify-sampled-columns.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Proposes a classification for every column, the strictest of what its name and its sampled values support, and compareseach proposal with the reviewed metadata. The prose's table rests on the proposed and found lines of each column, andits counts on the totals printed after them."""from lib import metadata, piifrom lib.catalog import open_catalogfrom lib.warehouse import connectcatalog = open_catalog()findings = pii.classify(catalog, connect(catalog), pii.platform_detector())    # the platform's tuned detector, not the defaultsprint("columns classified:", len(findings))print("columns sampled:", sum(f.sampled > 0 for f in findings))holding = [f for f in findings if f.found]          # columns where sampled values hold personal dataprint("columns whose sampled values hold personal data:", len(holding))# A column counts when its values hold an entity other than the one its name suggests (named is None when no rule matches).print("of them, holding something their name doesn't suggest:", sum(set(f.found) != {f.named} for f in holding))for f in holding:    print(f"{f.table}.{f.column}, proposed: {f.classification}")    print(f"{f.table}.{f.column}, found: " + ", ".join(f"{e} in {n} of {f.sampled}" for e, n in f.found.most_common()))[cards] = [f for f in findings if f.column == "card_number"]     # the one card_number column in the catalog# The card recognizer's count: values that match its pattern and pass its Luhn check, out of the values sampled.print("sampled card numbers the card recognizer accepts:", f"{cards.found['CREDIT_CARD']} of {cards.sampled}")# Classifications the values raise above what the name alone gives: the floor is used for a name no rule matches.named_only = [f for f in findings if pii.CLASSIFICATION.get(f.named, pii.FLOOR) != f.classification]print("columns the values classify more strictly than the name:", ", ".join(f"{f.table}.{f.column}" for f in named_only))# Compare with the metadata people reviewed. A column the detector found nothing in proposes only the floor, internal.described = metadata.load()evidenced = [f for f in findings if f.named or f.found]print("columns with evidence:", len(evidenced))print("of them, equal to the metadata:",      sum(f.classification == described[f.table].columns[f.field_id].classification for f in evidenced))for f in evidenced:    reviewed = described[f.table].columns[f.field_id].classification    if metadata.stricter(f.classification, reviewed) != reviewed:     # the stricter of the two: a lower proposal prints nothing        print(f"stricter than the metadata, {f.table}.{f.column}: {f.classification}, reviewed as {reviewed}")
Saídapython classify-sampled-columns.py
columns classified: 64
columns sampled: 29
columns whose sampled values hold personal data: 9
of them, holding something their name doesn't suggest: 5
billing.payments.card_number, proposed: sensitive
billing.payments.card_number, found: CREDIT_CARD in 151 of 200, PHONE_NUMBER in 3 of 200
crm.instructors.email, proposed: personal
crm.instructors.email, found: EMAIL_ADDRESS in 50 of 50
crm.instructors.payout_iban, proposed: sensitive
crm.instructors.payout_iban, found: IBAN_CODE in 50 of 50
crm.learners.email, proposed: personal
crm.learners.email, found: EMAIL_ADDRESS in 200 of 200
crm.learners.phone, proposed: personal
crm.learners.phone, found: PHONE_NUMBER in 175 of 200
crm.learners.notes, proposed: personal
crm.learners.notes, found: PHONE_NUMBER in 29 of 200, EMAIL_ADDRESS in 18 of 200
learning.events.ip_address, proposed: personal
learning.events.ip_address, found: IP_ADDRESS in 200 of 200, PHONE_NUMBER in 39 of 200
learning.reviews.body, proposed: personal
learning.reviews.body, found: EMAIL_ADDRESS in 4 of 200
support.tickets.body, proposed: sensitive
support.tickets.body, found: EMAIL_ADDRESS in 47 of 200, PHONE_NUMBER in 37 of 200, DATE_TIME in 29 of 200, IBAN_CODE in 21 of 200, CREDIT_CARD in 12 of 200
sampled card numbers the card recognizer accepts: 151 of 200
columns the values classify more strictly than the name: crm.learners.notes, learning.reviews.body, support.tickets.body
columns with evidence: 14
of them, equal to the metadata: 13
stricter than the metadata, support.tickets.body: sensitive, reviewed as personal

Os valores resolvem o que os nomes deixam em aberto. Algumas das 9 colunas cujas amostras contêm dados pessoais contêm apenas o que o nome diz, como crm.learners.email. As outras 5 contêm algo que o nome não sugere, ou têm um nome que não sugere nada:

Coluna Proposta Encontrado na amostra
billing.payments.card_number sensitive CREDIT_CARD in 151 of 200, PHONE_NUMBER in 3 of 200
crm.learners.notes personal PHONE_NUMBER in 29 of 200, EMAIL_ADDRESS in 18 of 200
support.tickets.body sensitive EMAIL_ADDRESS in 47 of 200, PHONE_NUMBER in 37 of 200, DATE_TIME in 29 of 200, IBAN_CODE in 21 of 200, CREDIT_CARD in 12 of 200
learning.reviews.body personal EMAIL_ADDRESS in 4 of 200
learning.events.ip_address personal IP_ADDRESS in 200 of 200, PHONE_NUMBER in 39 of 200

A descrição da coluna legada de cartão diz que ela "Should not be stored at all", e a amostra mostra que ela contém números de cartão completos, sobre os quais team-billing, dono da tabela, pode agir. Dos números de cartão amostrados, 151 of 200 correspondem ao padrão de cartão do Presidio e passam na soma de verificação de Luhn que ele confere (fonte), e os demais são formatos que o padrão não cobre (veja onde os padrões falham). As notas são personal apenas com base em seus valores. O texto dos chamados é sensitive, porque os alunos colam números de cartão e IBANs nos chamados, o que o torna a única proposta mais restritiva que os metadados, nos quais as pessoas o revisaram como personal. Das 14 colunas com alguma evidência, 13 coincidem com a classificação revisada.

Leia a evidência, não apenas o veredito. Alguns endereços IP também são lidos como números de telefone. Isso não muda nada aqui, porque um endereço IP é personal de qualquer forma, mas o rótulo de um detector diz como um valor se parece, não o que ele é.

Regra prática: Proponha a classificação mais restritiva que o nome ou qualquer valor amostrado sustente, tendo internal como piso, e mostre a evidência junto com a proposta. Uma proposta mais restritiva que os metadados revisados é um achado para o dono da tabela, que eleva a classificação ou registra o motivo de não fazê-lo; nunca deixe um detector rebaixar uma classificação. O OpenMetadata ignora qualquer coluna que já tenha uma tag de PII; recomendamos amostrar toda coluna de texto em cada execução, porque o que está sendo verificado é justamente a tag revisada.

Meça um detector contra trechos rotulados

Última alteração na edição 2026.11.31

Uma resposta no nível da coluna basta para classificar support.tickets.body, mas não para mascará-la: o mascaramento substitui cada span de dado pessoal em cada texto, e um span que o detector deixa passar continua legível. Para saber o que um detector deixa passar, compare seus spans com a verdade, os spans rotulados de cada chamado e avaliação. Duas regras de correspondência são padrão, e lib.pii aplica ambas.

A correspondência exata, da tarefa compartilhada CoNLL-2003, conta uma entidade como "correta apenas se for uma correspondência exata da entidade correspondente no arquivo de dados" (Tjong Kim Sang e De Meulder, 2003). A correspondência por sobreposição exige apenas um caractere em comum, com um rótulo do tipo correto, o que a tarefa SemEval-2013 sobre interações medicamentosas chama de "Type matching" (Segura-Bedmar et al., 2013). Nenhuma das duas credita um span escondido sob outro rótulo, por isso lib.pii acrescenta uma terceira medida, a cobertura: se cada caractere de um span rotulado está dentro de alguma detecção, qualquer que seja o rótulo. A correspondência exata pergunta se o detector rotulou o span inteiro corretamente, a de sobreposição se ele percebeu o span como aquilo que é, e a cobertura se o mascaramento das suas detecções esconde o span.

lib.pii.score calcula as correspondências exata e por sobreposição como revocação, a parcela dos spans rotulados de cada tipo que um detector encontra com um rótulo desse tipo, e como precisão, a parcela das detecções de cada rótulo que correspondem a um span rotulado. lib.pii.coverage indica a parcela dos spans de cada tipo que está coberta. score também conta os textos em que cada caractere rotulado cai dentro de alguma detecção, os textos que o mascaramento deixaria sem nenhum dado pessoal. O Text Anonymization Benchmark só protege uma pessoa quando todas as suas menções são mascaradas (Pilán et al., 2022), e a plataforma conta textos inteiros, o que é mais rigoroso. A revocação vem primeiro: o guia de avaliação do Presidio diz que ela costuma importar mais do que a precisão, porque deixar passar dado pessoal é o erro a evitar (documentação do Presidio).

Os padrões do Presidio, pontuados contra os spans rotulados de cada chamado e avaliação, dão a linha de base que o restante do capítulo melhora:

measure-pattern-recognizers.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Runs Presidio with its defaults over every ticket and review, and scores its detections against the truth's labelledspans. The prose rests on the recall and precision lines, the count of texts left with nothing personal, and the twodate lines that test the truth's limits."""import refrom lib import piilabelled = pii.truth()print("texts:", f"{sum(len(pii.texts(source)) for source in pii.SOURCES):,}")print("labelled spans:", f"{len(labelled):,}")detector = pii.detector()                 # Presidio's defaults: every recognizer, threshold 0found = pii.find(detector)# scoring needs a label of the span's type; coverage doesn'tscores, covered = pii.score(found, labelled), pii.coverage(found, labelled)print("detections:", f"{len(found):,}")for entity, (n, exact, overlap) in scores.recall.items():    print(f"{entity}, labelled: {n:,}")    print(f"{entity}, recall, exact: {exact / n:.2f}")    print(f"{entity}, recall, overlap: {overlap / n:.2f}")    print(f"{entity}, covered, any label: {covered[entity][1] / n:.2f}")    # covered[entity] is (spans, covered), so n is the same countfor label, (n, exact, overlap) in scores.precision.items():     # precision is per label: what each detection was called    print(f"{label}, detections: {n:,}")    print(f"{label}, precision, exact: {exact / n:.2f}")# every bank number and driver's licence detection is a false alarm: none matches a labelled spanassert all(scores.precision[entity][1] == 0 for entity in ("US_BANK_NUMBER", "US_DRIVER_LICENSE"))print("precision of all detections, exact:", f"{pii.precision_overall(scores):.2f}")print("texts holding personal data:", f"{scores.texts:,}")print("texts with every labelled span masked:", f"{scores.masked:,}")# The truth's limits. The generator builds every text from a few sentence templates, and writes every date of birth# one way. Presidio's date patterns don't read every way of writing one.print("sentence templates the texts are built from:", len(pii.templates()))births = [pii.text_of(s) for s in labelled if s.entity == "DATE_TIME"]    # the truth's dates are the dates of birth: dates of a problem are unlabelledwritten_ymd = sum(re.fullmatch(r"\d{4}-\d\d-\d\d", d) is not None for d in births)   # year first, the generator's one formassert written_ymd == len(births)           # so every date of birth is written this wayprint("dates of birth written like 1985-03-12:", written_ymd)for written in ("1985-03-12", "12 March 1985"):    text = f"My date of birth on the account is wrong, it should be {written}."     # a sentence in the generator's shape    print(f"dates found in a date of birth written {written}:", sum(e == "DATE_TIME" for _, _, e, _ in pii.detect(detector, text)))
Saídapython measure-pattern-recognizers.py
texts: 5,000
labelled spans: 4,292
detections: 3,902
CREDIT_CARD, labelled: 213
CREDIT_CARD, recall, exact: 0.71
CREDIT_CARD, recall, overlap: 0.71
CREDIT_CARD, covered, any label: 0.89
DATE_TIME, labelled: 196
DATE_TIME, recall, exact: 1.00
DATE_TIME, recall, overlap: 1.00
DATE_TIME, covered, any label: 1.00
EMAIL_ADDRESS, labelled: 543
EMAIL_ADDRESS, recall, exact: 1.00
EMAIL_ADDRESS, recall, overlap: 1.00
EMAIL_ADDRESS, covered, any label: 1.00
IBAN_CODE, labelled: 236
IBAN_CODE, recall, exact: 1.00
IBAN_CODE, recall, overlap: 1.00
IBAN_CODE, covered, any label: 1.00
LOCATION, labelled: 210
LOCATION, recall, exact: 0.00
LOCATION, recall, overlap: 0.00
LOCATION, covered, any label: 0.00
PERSON, labelled: 2,455
PERSON, recall, exact: 0.00
PERSON, recall, overlap: 0.00
PERSON, covered, any label: 0.00
PHONE_NUMBER, labelled: 439
PHONE_NUMBER, recall, exact: 0.78
PHONE_NUMBER, recall, overlap: 0.79
PHONE_NUMBER, covered, any label: 0.91
CREDIT_CARD, detections: 151
CREDIT_CARD, precision, exact: 1.00
DATE_TIME, detections: 421
DATE_TIME, precision, exact: 0.47
EMAIL_ADDRESS, detections: 543
EMAIL_ADDRESS, precision, exact: 1.00
IBAN_CODE, detections: 236
IBAN_CODE, precision, exact: 1.00
MEDICAL_LICENSE, detections: 18
MEDICAL_LICENSE, precision, exact: 0.00
PHONE_NUMBER, detections: 384
PHONE_NUMBER, precision, exact: 0.89
UK_NHS, detections: 8
UK_NHS, precision, exact: 0.00
URL, detections: 751
URL, precision, exact: 0.00
US_BANK_NUMBER, detections: 689
US_BANK_NUMBER, precision, exact: 0.00
US_DRIVER_LICENSE, detections: 683
US_DRIVER_LICENSE, precision, exact: 0.00
US_ITIN, detections: 2
US_ITIN, precision, exact: 0.00
US_PASSPORT, detections: 8
US_PASSPORT, precision, exact: 0.00
US_SSN, detections: 8
US_SSN, precision, exact: 0.00
precision of all detections, exact: 0.38
texts holding personal data: 2,586
texts with every labelled span masked: 425
sentence templates the texts are built from: 30
dates of birth written like 1985-03-12: 196
dates found in a date of birth written 1985-03-12: 1
dates found in a date of birth written 12 March 1985: 0
Tipo de entidade Rotulados Revocação, exata Revocação, sobreposição Coberto
PERSON 2,455 0.00 0.00 0.00
EMAIL_ADDRESS 543 1.00 1.00 1.00
PHONE_NUMBER 439 0.78 0.79 0.91
IBAN_CODE 236 1.00 1.00 1.00
CREDIT_CARD 213 0.71 0.71 0.89
LOCATION 210 0.00 0.00 0.00
DATE_TIME 196 1.00 1.00 1.00

Os padrões encontram todos os e-mails, IBANs e datas de nascimento, a maioria dos números de telefone e de cartão, e nenhum nome ou endereço de rua, que é a maior parte do que os chamados contêm. A maioria do que eles sinalizam está errada: 0.38 de todas as detecções correspondem a um span rotulado. Os 689 números de conta bancária dos EUA, as 683 carteiras de motorista e as 751 URLs estão todos errados. Números de telefone, de cartão e de fatura, que são sequências de dígitos, saem como números bancários e carteiras, e pedaços de e-mails e alguns endereços saem como URLs. Um rótulo errado ainda esconde os dígitos, por isso números de telefone e de cartão são cobertos com mais frequência do que são encontrados.

O mascaramento deixaria dado pessoal na maioria dos textos que o contêm. Apenas 425 dos 2,586 textos sairiam sem nenhum dado pessoal restante.

A verdade também tem seus limites, porque o texto é gerado. Cada chamado e avaliação é montado a partir de 30 modelos de frase em prep/generate.py, por isso cada caso difícil é uma única moldura de frase, e todas as 196 datas de nascimento estão escritas como 1985-03-12. A revocação de datas de 1.00 mede, portanto, um único formato: na frase própria do gerador, o Presidio encontra 1 data quando a data de nascimento está escrita como 1985-03-12, e 0 quando está escrita como 12 March 1985. Uma medida sobre este texto diz como um detector se comporta nestas formas, não como ele se sairá no seu.

Regra prática: Meça todo detector contra spans rotulados antes que ele mascare qualquer coisa: revocação por tipo de entidade, pela correspondência exata e pela de sobreposição, ambas com um rótulo do tipo certo; cobertura, qualquer que seja o rótulo; precisão por rótulo; e a parcela de textos sem nenhum dado pessoal restante. Pese a revocação primeiro. Antes de confiar em um detector no seu texto, rotule à mão algumas centenas de registros reais e meça também sobre eles.

Ajuste os reconhecedores com base no gabarito

Última alteração na edição 2026.11.28

Os padrões do Presidio retornam toda correspondência fraca. O FAQ cita dois remédios, alterar o limiar de aceitação e remover os reconhecedores de que um conjunto de dados não precisa, e observa um compromisso entre falsos positivos e falsos negativos (FAQ). O Presidio 2.2.364 acrescentou limiares de pontuação por reconhecedor e por entidade, com o padrão do analisador como valor de reserva (changelog, notas de versão). O reconhecedor de telefone tem mais uma configuração que importa em uma plataforma cujos alunos vivem em muitos países: as regiões cujos planos de numeração ele lê (código-fonte).

governance/pii.toml mantém 6 reconhecedores, para os identificadores que o texto da plataforma pode conter, cada um com seu próprio limiar. As regiões de telefone não são uma configuração: lib.pii.countries lê dos dados de crm.learners os países em que os alunos vivem, então as regiões acompanham os dados. Quatro configurações são avaliadas contra o mesmo gabarito:

tune-pattern-recognizers.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Scores four detector settings against the same truth: Presidio's defaults, one threshold for every recognizer, the keptrecognizers with their own thresholds, and those with phone numbers read in the learners' countries. The prose rests onthe precision, phone recall, coverage and fully masked texts of each setting."""from lib import piilabelled = pii.truth()print("recognizers kept:", len(pii.THRESHOLDS))                  # read from governance/pii.tomlprint("recognizers kept, with their thresholds:", ", ".join(f"{name} {t}" for name, t in pii.THRESHOLDS.items()))print("phone regions, Presidio's default:", ", ".join(pii.PhoneRecognizer.DEFAULT_SUPPORTED_REGIONS))   # Presidio's own listprint("phone regions, the learners' countries:", ", ".join(pii.countries()))   # read from crm.learners# In the order the prose builds them: the defaults, one threshold, the kept recognizers, then their regions.settings = {    "Presidio's defaults": pii.detector(),    "one threshold of 0.5": pii.detector(default_threshold=0.5),    "kept recognizers, own thresholds": pii.detector(pii.THRESHOLDS),    "kept recognizers, learners' phone regions": pii.platform_detector(),}for name, detector in settings.items():    found = pii.find(detector)    scores, covered = pii.score(found, labelled), pii.coverage(found, labelled)    n, exact, _ = scores.recall["PHONE_NUMBER"]         # the table reads exact recall, so the overlap count is left out    print(f"{name}, detections: {len(found):,}")    print(f"{name}, precision, exact: {pii.precision_overall(scores):.2f}")    print(f"{name}, phone recall, exact: {exact / n:.2f}")    # coverage takes a detection under any label    for entity, short in (("PHONE_NUMBER", "phones"), ("CREDIT_CARD", "cards")):        print(f"{name}, {short} covered, any label: {covered[entity][1] / covered[entity][0]:.2f}")    print(f"{name}, texts with every labelled span masked: {scores.masked:,}")
Saídapython tune-pattern-recognizers.py
recognizers kept: 6
recognizers kept, with their thresholds: EmailRecognizer 0.5, PhoneRecognizer 0.4, CreditCardRecognizer 0.5, IbanRecognizer 0.5, DateRecognizer 0.5, IpRecognizer 0.5
phone regions, Presidio's default: US, GB, DE, FR, IL, IN, CA, BR
phone regions, the learners' countries: AU, BR, CA, DE, ES, FR, GB, IN, JP, MX, PL, US
Presidio's defaults, detections: 3,902
Presidio's defaults, precision, exact: 0.38
Presidio's defaults, phone recall, exact: 0.78
Presidio's defaults, phones covered, any label: 0.91
Presidio's defaults, cards covered, any label: 0.89
Presidio's defaults, texts with every labelled span masked: 425
one threshold of 0.5, detections: 1,903
one threshold of 0.5, precision, exact: 0.59
one threshold of 0.5, phone recall, exact: 0.00
one threshold of 0.5, phones covered, any label: 0.01
one threshold of 0.5, cards covered, any label: 0.71
one threshold of 0.5, texts with every labelled span masked: 284
kept recognizers, own thresholds, detections: 1,510
kept recognizers, own thresholds, precision, exact: 0.97
kept recognizers, own thresholds, phone recall, exact: 0.78
kept recognizers, own thresholds, phones covered, any label: 0.78
kept recognizers, own thresholds, cards covered, any label: 0.72
kept recognizers, own thresholds, texts with every labelled span masked: 394
kept recognizers, learners' phone regions, detections: 1,539
kept recognizers, learners' phone regions, precision, exact: 0.97
kept recognizers, learners' phone regions, phone recall, exact: 0.84
kept recognizers, learners' phone regions, phones covered, any label: 0.84
kept recognizers, learners' phone regions, cards covered, any label: 0.72
kept recognizers, learners' phone regions, texts with every labelled span masked: 405
Medida Padrões Um limiar, 0.5 Reconhecedores mantidos E regiões dos alunos
Detecções 3,902 1,903 1,510 1,539
Precisão, exata 0.38 0.59 0.97 0.97
Revocação de telefones, exata 0.78 0.00 0.78 0.84
Telefones cobertos 0.91 0.01 0.78 0.84
Cartões cobertos 0.89 0.71 0.72 0.72
Textos totalmente mascarados 425 284 394 405

A correção óbvia falha. Um limiar único de 0.5 remove as correspondências fracas e, com elas, todo número de telefone, porque um número de telefone recebe 0.40 quando nenhuma palavra de contexto pode elevar sua pontuação. Manter apenas os 6 reconhecedores, cada um com seu próprio limiar, e definir o limiar de telefone na pontuação que um número de telefone recebe, eleva a precisão para 0.97 e deixa a revocação de telefones onde estava. Ler números de telefone nas regiões dos alunos, em vez das regiões padrão do Presidio, eleva a revocação de telefones para 0.84.

Um número vai na direção errada: menos textos saem totalmente mascarados do que com os padrões. Os reconhecedores removidos haviam mascarado alguns números de telefone e de cartão com o rótulo errado, o que ainda oculta os dígitos. Sem eles, a cobertura cai de 0.91 para 0.78 nos números de telefone, e de 0.89 para 0.72 nos números de cartão. Julgamos que a precisão vale o custo, porque as detecções são a evidência que um revisor lê, e com os padrões os chamados e avaliações trazem 689 números bancários e 683 carteiras de habilitação, nenhum deles real. governance/pii.toml não associa nenhuma dessas entidades a uma classificação, de modo que elas não alteram proposta alguma, mas cada uma é um achado que alguém precisa ler e descartar. Remover os reconhecedores dos EUA também é uma afirmação sobre o texto da plataforma: o gabarito não contém números bancários ou de habilitação dos EUA. Se a plataforma um dia precisar de um deles, essa afirmação, e a medição, deverão mudar.

Regra prática: Não rode com o limiar padrão de 0 do Presidio, nem com um único limiar para todos os reconhecedores. Mantenha apenas os reconhecedores para os identificadores que seu texto pode conter, defina o limiar de cada um a partir de suas próprias pontuações e leia números de telefone nas regiões em que seus usuários vivem, derivadas dos seus dados. Coloque tudo isso em código e meça de novo sempre que algo mudar.

Veja onde os padrões falham

Última alteração na edição 2026.11.28

Os reconhecedores ajustados têm bom desempenho nos totais, e os totais escondem onde eles falham. Um detector baseado em padrões falha de três maneiras: não há padrão para a coisa em si, seu padrão ou sua validação rejeita o valor, ou ele encontra algo que apenas parece pessoal. Os tickets da plataforma incluem casos de cada tipo, como indica o seu data card: nomes digitados em minúsculas, iniciais, primeiros nomes que são palavras comuns, números de telefone digitados sem separadores, e números de fatura, números de pedido e datas de um problema, que o gabarito deixa sem rótulo. Conte cada caso com o detector da plataforma. Um caso conta como detectado quando alguma detecção se sobrepõe a ele, qualquer que seja o rótulo:

pattern-hard-cases.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Counts each hard case the tickets and reviews plant, and each look-alike number or date the platform's detector flags,then checks the card and phone numbers it misses. The prose rests on the caught counts for names and invoice numbers,and on the misses' lengths, first digits and validity."""from collections import Counterfrom lib import piifrom lib.platform import loadlabelled = pii.truth()found = pii.find(pii.platform_detector())cases = pii.hard_cases(labelled)               # a case is caught when some detection overlaps it, whatever its labelfor case, spans in cases.items():    print(f"{case}, labelled: {len(spans)}")    print(f"{case}, caught: {pii.caught(spans, found)}")print("hard cases of a name, caught:", pii.caught([s for spans in cases.values() for s in spans if s.entity == "PERSON"], found))# Look-alikes are numbers and dates that aren't personal data, so any detection on one is a false alarm.for kind, spans in pii.lookalikes().items():    print(f"{kind}, in the tickets: {len(spans)}")    print(f"{kind}, flagged as personal data: {pii.caught(spans, found)}")# Card numbers the card pattern misses: too short or long for its 13 to 17 digits, or a first digit it doesn't accept.# Out of range, the length is the reason; in range, the first digit is, since the pattern accepts only some of them.missed = pii.missed([s for s in labelled if s.entity == "CREDIT_CARD"], found, {"CREDIT_CARD"})why = lambda digits: f"{len(digits)} digits" if not 13 <= len(digits) <= 17 else f"{len(digits)} digits starting with {digits[0]}"print("CREDIT_CARD, missed:", len(missed))for reason, n in Counter(why(pii.text_of(s)) for s in missed).most_common():    print(f"CREDIT_CARD, missed, {reason}: {n}")print("IBAN_CODE, missed:", len(pii.missed([s for s in labelled if s.entity == "IBAN_CODE"], found, {"IBAN_CODE"})))# Are the phone numbers the patterns miss valid where the ticket's learner lives? Phones appear only in tickets,# so each phone's learner comes from its ticket.learner_of = {row["ticket_id"]: row["learner_id"] for row in load("support.tickets").to_pylist()}country_of = {row["learner_id"]: row["country"] for row in load("crm.learners").to_pylist()}phones = pii.missed([s for s in labelled if s.entity == "PHONE_NUMBER"], found, {"PHONE_NUMBER"})print("phone numbers missed:", len(phones))print("of them, invalid in the learner's country:",      sum(not pii.valid_phone(pii.text_of(s), country_of[learner_of[s.row_id]]) for s in phones))
Saídapython pattern-hard-cases.py
names in lowercase, labelled: 211
names in lowercase, caught: 0
initial and surname, labelled: 163
initial and surname, caught: 0
first names that are words, labelled: 187
first names that are words, caught: 0
instructors named in reviews, labelled: 798
instructors named in reviews, caught: 0
phones typed as digits only, labelled: 257
phones typed as digits only, caught: 220
hard cases of a name, caught: 0
invoice numbers, in the tickets: 224
invoice numbers, flagged as personal data: 31
order numbers, in the tickets: 212
order numbers, flagged as personal data: 0
dates of a problem, in the tickets: 225
dates of a problem, flagged as personal data: 0
CREDIT_CARD, missed: 62
CREDIT_CARD, missed, 19 digits: 23
CREDIT_CARD, missed, 12 digits: 22
CREDIT_CARD, missed, 16 digits starting with 2: 10
CREDIT_CARD, missed, 15 digits starting with 2: 7
IBAN_CODE, missed: 0
phone numbers missed: 65
of them, invalid in the learner's country: 63

Nomes são a lacuna, já que nenhum padrão reconhece um nome. Considerando os nomes em minúsculas, as iniciais com sobrenome, os primeiros nomes que são palavras comuns e os instrutores citados nas avaliações, os padrões detectam 0 deles. Telefones digitados apenas com números vão bem: 220 de 257. O preço são os casos que apenas parecem dados pessoais: 31 dos 224 números de fatura são sinalizados como dados pessoais.

O detector da plataforma sinaliza 0 dos 212 números de pedido e 0 das 225 datas de um problema. Com os padrões do Presidio, 12/03 foi lido como data em 0.10, e o reconhecedor de datas retornou 421 datas onde o gabarito rotula 196. O limiar em governance/pii.toml mantém essas correspondências fracas de fora.

A forma do padrão de cartão causa as falhas com cartões. Ele aceita de 13 a 17 dígitos começando com 1, 3, 4, 50 a 55 ou 6, mas nenhum número de 13 dígitos começando com 1 (fonte), e todo número de cartão nos dados passa na soma de verificação de Luhn, então a validação não rejeita nenhum. Dos 62 números de cartão que ele não detecta, 23 têm 19 dígitos e 22 têm 12, e os demais começam com 2, o que o padrão não aceita.

A validação causa as outras falhas. O reconhecedor de IBAN verifica o formato, o comprimento e os dígitos de controle de cada país (fonte). Todo IBAN rotulado passa, então ele deixa escapar 0 desses, mas um aluno que digita errado um dígito escreve um valor que ele rejeita. O reconhecedor de telefones aceita apenas números que a biblioteca python-phonenumbers considera válidos (fonte), e o gerador nem sempre escreve esses números. Dos 65 números de telefone que o detector não detecta, 63 não são válidos no país em que mora o aluno do ticket, então a maioria das falhas com telefone é do gerador, não do detector.

Regra prática: Leia as falhas de um detector por caso, não pelo total, e mantenha uma lista dos casos que o seu texto contém. Use padrões para o que tem uma forma verificável, como e-mails, IBANs, números de cartão, números de telefone e datas, e nunca para nomes ou endereços. Mantenha as somas de verificação e os planos de numeração, pois são eles que tornam os padrões precisos. Confira o padrão de cartão com os números de cartão emitidos pelo seu provedor de pagamentos, e os padrões de data com as formas como os seus usuários escrevem datas.

Compare um modelo de PII

Última alteração na edição 2026.11.27

Os padrões não têm nada para nomes ou endereços, e esses são a maior parte dos dados pessoais no texto da plataforma: 2,455 nomes e 210 endereços entre os 4,292 trechos rotulados. Encontrá-los exige um modelo que leia o contexto, e não um modelo geral de entidades nomeadas. Os autores do conjunto de dados SPY definem PII como as entidades que podem identificar, contatar ou localizar um indivíduo específico, e constataram que modelos dedicados de entidades nomeadas têm limites em contextos de PII (Savkin et al., 2025). Usamos um modelo de PII, treinado para informações pessoais identificáveis: o Privacy Filter da OpenAI, um modelo sob licença Apache-2.0 com oito rótulos fixos, como private_person, private_address e account_number (cartão do modelo).

Os rótulos são do próprio modelo. O cartão da OpenAI diz que as políticas de rótulos não podem ser definidas enquanto o modelo está em execução (OpenAI, 2026, seção 4.2). Escolhemos esse modelo em vez do GLiNER2-PII, o segundo colocado entre os modelos abertos de PII, por causa desses rótulos fixos. O GLiNER2-PII recebe, no momento da inferência, os rótulos a procurar, junto com um limiar (cartão do modelo), então uma gravação dele teria de fixar os dois. O Privacy Filter tem 1.5 bilhão de parâmetros, 50 milhões deles ativos, e roda em uma CPU.

Os exemplos do livro nunca executam um modelo; em vez disso, leem uma gravação da saída dele. A gravação, data/recorded/pii-entities/, que este capítulo e o capítulo 9 usam, contém cada trecho que o modelo encontrou em cada ticket e avaliação, com seus deslocamentos, seu texto e o rótulo do modelo. recordings/pii_entities.py a fez em uma CPU com o decodificador de referência do modelo, opf (código), que escolhe a melhor sequência de rótulos para um texto inteiro, de modo que a maioria dos trechos vem em um único bloco, e não token por token. Ela usou o ponto de operação padrão, com todos os seis vieses de transição em 0 (arquivo de calibração); o modelo também pode ser configurado "para maior recall" (seção 2.3.2). O manifesto fixa a revisão do modelo e o SHA-256 de seus pesos, de modo que qualquer pessoa pode gravar de novo e comparar, e lib.pii.recorded recusa trechos que não correspondem ao texto em seus deslocamentos. A gravação mantém os rótulos do modelo, e o exemplo mapeia esses rótulos para os tipos da verdade de referência, de modo que um mapeamento diferente nunca exige uma nova gravação. Avalie o modelo, os padrões da plataforma e os dois juntos, mascarando o que qualquer um deles encontrar:

privacy-filter-spans.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Scores the recorded spans of OpenAI's Privacy Filter against the truth, alone and beside the platform's patterns. Theprose rests on the recall lines for names, addresses, phones and cards, the precision lines, and the texts left withnothing personal."""from lib import pii# Privacy Filter's eight labels, mapped to the truth's entity types. A label the truth has no type for matches nothing.MATCHES = {"private_person": {"PERSON"}, "private_email": {"EMAIL_ADDRESS"}, "private_phone": {"PHONE_NUMBER"},           "private_address": {"LOCATION"}, "account_number": {"CREDIT_CARD", "IBAN_CODE"},           "private_date": {"DATE_TIME"}, "private_url": set(), "secret": set()}model, manifest = pii.recorded("pii-entities")      # the model's spans, from a recording: no model runs hereprint("model:", manifest["model"], "decoded with", manifest["settings"]["decode_mode"])labelled = pii.truth()detectors = {"patterns": pii.find(pii.platform_detector()), "model": model}# both lists joined: a span either one finds is masked, and a span both find is simply counted twicedetectors["both"] = detectors["patterns"] + modelfor name, found in detectors.items():    scores = pii.score(found, labelled, MATCHES)           # Presidio's labels aren't in MATCHES, so match themselves    print(f"{name}, detections: {len(found):,}")    for entity, (n, exact, overlap) in scores.recall.items():        print(f"{name}, {entity}, recall, exact: {exact / n:.2f}")        print(f"{name}, {entity}, recall, overlap: {overlap / n:.2f}")    print(f"{name}, precision, exact: {pii.precision_overall(scores):.2f}")    print(f"{name}, texts with every labelled span masked: {scores.masked:,} of {scores.texts:,}")# Precision by the model's own label: a label that's right for one truth type can still be wrong for anotherfor label, (n, exact, overlap) in pii.score(model, labelled, MATCHES).precision.items():    print(f"model, {label}, detections: {n:,}")    print(f"model, {label}, precision, exact: {exact / n:.2f}")    print(f"model, {label}, precision, overlap: {overlap / n:.2f}")
Saídapython privacy-filter-spans.py
model: openai/privacy-filter decoded with viterbi
patterns, detections: 1,539
patterns, CREDIT_CARD, recall, exact: 0.71
patterns, CREDIT_CARD, recall, overlap: 0.71
patterns, DATE_TIME, recall, exact: 1.00
patterns, DATE_TIME, recall, overlap: 1.00
patterns, EMAIL_ADDRESS, recall, exact: 1.00
patterns, EMAIL_ADDRESS, recall, overlap: 1.00
patterns, IBAN_CODE, recall, exact: 1.00
patterns, IBAN_CODE, recall, overlap: 1.00
patterns, LOCATION, recall, exact: 0.00
patterns, LOCATION, recall, overlap: 0.00
patterns, PERSON, recall, exact: 0.00
patterns, PERSON, recall, overlap: 0.00
patterns, PHONE_NUMBER, recall, exact: 0.84
patterns, PHONE_NUMBER, recall, overlap: 0.85
patterns, precision, exact: 0.97
patterns, texts with every labelled span masked: 405 of 2,586
model, detections: 4,424
model, CREDIT_CARD, recall, exact: 0.69
model, CREDIT_CARD, recall, overlap: 0.69
model, DATE_TIME, recall, exact: 0.97
model, DATE_TIME, recall, overlap: 0.97
model, EMAIL_ADDRESS, recall, exact: 1.00
model, EMAIL_ADDRESS, recall, overlap: 1.00
model, IBAN_CODE, recall, exact: 0.99
model, IBAN_CODE, recall, overlap: 1.00
model, LOCATION, recall, exact: 0.67
model, LOCATION, recall, overlap: 0.79
model, PERSON, recall, exact: 0.84
model, PERSON, recall, overlap: 0.84
model, PHONE_NUMBER, recall, exact: 0.94
model, PHONE_NUMBER, recall, overlap: 0.94
model, precision, exact: 0.84
model, texts with every labelled span masked: 2,095 of 2,586
both, detections: 5,963
both, CREDIT_CARD, recall, exact: 0.92
both, CREDIT_CARD, recall, overlap: 0.92
both, DATE_TIME, recall, exact: 1.00
both, DATE_TIME, recall, overlap: 1.00
both, EMAIL_ADDRESS, recall, exact: 1.00
both, EMAIL_ADDRESS, recall, overlap: 1.00
both, IBAN_CODE, recall, exact: 1.00
both, IBAN_CODE, recall, overlap: 1.00
both, LOCATION, recall, exact: 0.67
both, LOCATION, recall, overlap: 0.79
both, PERSON, recall, exact: 0.84
both, PERSON, recall, overlap: 0.84
both, PHONE_NUMBER, recall, exact: 0.99
both, PHONE_NUMBER, recall, overlap: 0.99
both, precision, exact: 0.88
both, texts with every labelled span masked: 2,120 of 2,586
model, account_number, detections: 746
model, account_number, precision, exact: 0.51
model, account_number, precision, overlap: 0.51
model, private_address, detections: 177
model, private_address, precision, exact: 0.79
model, private_address, precision, overlap: 1.00
model, private_date, detections: 384
model, private_date, precision, exact: 0.50
model, private_date, precision, overlap: 0.50
model, private_email, detections: 543
model, private_email, precision, exact: 1.00
model, private_email, precision, overlap: 1.00
model, private_person, detections: 2,110
model, private_person, precision, exact: 0.98
model, private_person, precision, overlap: 0.98
model, private_phone, detections: 464
model, private_phone, precision, exact: 0.89
model, private_phone, precision, overlap: 0.89
Medida Padrões Modelo Ambos
Recall, exato, PERSON 0.00 0.84 0.84
Recall, exato, LOCATION 0.00 0.67 0.67
Recall, exato, PHONE_NUMBER 0.84 0.94 0.99
Recall, exato, CREDIT_CARD 0.71 0.69 0.92
Recall, exato, IBAN_CODE 1.00 0.99 1.00
Precisão, exata 0.97 0.84 0.88
Textos totalmente mascarados 405 of 2,586 2,095 of 2,586 2,120 of 2,586

O modelo encontra a maior parte dos nomes e endereços que os padrões não conseguem, e os dois detectores se complementam nos números de cartão. O modelo e os padrões encontram aproximadamente a mesma parcela de cartões, 0.69 e 0.71, mas não os mesmos cartões, de modo que juntos encontram 0.92. Uma seção posterior mostra por que a parcela do modelo é baixa.

O modelo paga em precisão, 0.84 no conjunto, e apenas 0.51 para account_number e 0.50 para private_date. Isso mede em parte uma diferença de política de rótulos. A verdade de referência deixa números de fatura e datas de problema sem rótulo, e o cartão da OpenAI diz que políticas de rótulos adequadas podem diferir (seção 4.2).

Juntos, os dois detectores deixam 2,120 of 2,586 textos sem nada pessoal, contra 405 of 2,586 apenas com os padrões.

Leia os erros do modelo

Última alteração na edição 2026.11.27

O cartão da OpenAI indica onde o modelo falha: ele deixa passar nomes raros, nomes de outras tradições de nomes, iniciais, nomes acompanhados de títulos e identificadores específicos de um domínio, e marca em excesso entidades públicas, locais e substantivos comuns quando o contexto local não está claro (OpenAI, 2026, seção 4.3). Confira essa lista com os casos difíceis que os tickets incluem:

privacy-filter-hard-cases.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Counts how many of each hard case the model's recorded spans catch, and reads the names it misses by case and length.The prose rests on the missed-name counts and on the first lowercase ticket that both detectors miss."""from collections import Counterfrom lib import piimodel, _ = pii.recorded("pii-entities")labelled = pii.truth()cases = pii.hard_cases(labelled)for case, spans in cases.items():    print(f"{case}, labelled: {len(spans)}")    print(f"{case}, caught by the model: {pii.caught(spans, model)}")for kind, spans in pii.lookalikes().items():    print(f"{kind}, flagged by the model: {pii.caught(spans, model)}")# The names the model misses, by case: read them before trusting a recall figure.missed = pii.missed([s for s in labelled if s.entity == "PERSON"], model, {"private_person"})print("names the model misses:", len(missed))for case in ("first names that are words", "instructors named in reviews"):    often = Counter(pii.text_of(s) for s in pii.missed(cases[case], model, {"private_person"})).most_common(3)    print(f"{case}, missed most often:", ", ".join(name for name, _ in often))# A first name on its own says less than a full name: how many of the misses are one word?print("missed names that are one word:", sum(len(pii.text_of(s).split()) == 1 for s in missed))print("missed names of two words or more:", sum(len(pii.text_of(s).split()) > 1 for s in missed))# islower() counts only names typed entirely in lowercase, so a name with a capital letter, such as "Jane", doesn't.print("of them, typed in lowercase:", sum(len(pii.text_of(s).split()) > 1 and pii.text_of(s).islower() for s in missed))# A lowercase name that neither the model nor the platform's patterns cover any part of, in the first ticket with one.# The model's spans and the patterns' together: a name is missed only when both miss it. The lowest ticket ID is taken,# so the same ticket is printed on every run.first = min(pii.missed(cases["names in lowercase"], model + pii.find(pii.platform_detector())), key=lambda s: s.row_id)print("first ticket with a lowercase name both detectors miss:", first.row_id)print("the name, as typed:", pii.text_of(first))
Saídapython privacy-filter-hard-cases.py
names in lowercase, labelled: 211
names in lowercase, caught by the model: 167
initial and surname, labelled: 163
initial and surname, caught by the model: 162
first names that are words, labelled: 187
first names that are words, caught by the model: 128
instructors named in reviews, labelled: 798
instructors named in reviews, caught by the model: 535
phones typed as digits only, labelled: 257
phones typed as digits only, caught by the model: 256
invoice numbers, flagged by the model: 224
order numbers, flagged by the model: 125
dates of a problem, flagged by the model: 188
names the model misses: 387
first names that are words, missed most often: Summer, Will, Hope
instructors named in reviews, missed most often: Marie, Lori, Augustin
missed names that are one word: 337
missed names of two words or more: 50
of them, typed in lowercase: 43
first ticket with a lowercase name both detectors miss: 19
the name, as typed: juan fonseca

Os erros são primeiros nomes que também são palavras e o primeiro nome de um instrutor, sozinho, em uma avaliação. O modelo identifica 128 dos 187 primeiros nomes que são palavras, e 535 dos 798 nomes de instrutores.

Iniciais não são o problema: o modelo identifica 162 de 163 iniciais acompanhadas de sobrenome, e nomes em minúsculas são em grande parte identificados, 167 de 211.

Com mais frequência, ele deixa passar as palavras Summer, Will, Hope e os nomes de instrutores Marie, Lori, Augustin. O modelo também sinaliza muito mais itens parecidos com dados pessoais do que os padrões ajustados: 224 números de fatura, 125 números de pedido e 188 datas de um problema, contra 31, 0 e 0.

O impacto dos erros depende do tamanho dos nomes. Dos 387 nomes que o modelo deixa passar, 337 são uma única palavra, um primeiro nome sozinho, e 50 são mais longos, 43 destes digitados em minúsculas. Os autores do Text Anonymization Benchmark fazem a mesma distinção: deixar de mascarar um identificador direto, como um nome completo, é muito mais prejudicial do que deixar de mascarar um quase-identificador (Pilán et al., 2022). Um primeiro nome sozinho ainda precisa ser mascarado, já que uma avaliação traz o ID do aluno, e o primeiro nome de um instrutor em uma avaliação do próprio curso aponta para uma única pessoa.

O cartão recomenda testar o modelo no seu próprio domínio, com as referências de política local, antes do uso em produção (seção 4.5). Ele também inclui a educação entre os contextos que exigem cuidado extra (seção 4.4), e descreve o modelo como "um auxílio à redação e à minimização de dados, não uma garantia de anonimização, conformidade ou segurança" (seção 4.1).

Regra prática: Mascare texto livre com um modelo de PII e com os padrões ajustados ao mesmo tempo, independentemente do que cada um encontrar: o modelo para nomes e endereços, e os checksums dos padrões para números de cartão e IBANs. Registre a saída do modelo com sua revisão, pesos e ponto de operação fixados, mantenha os rótulos próprios dele e faça o mapeamento no código. Meça no seu próprio texto, por caso difícil, antes do uso e depois de cada mudança no modelo; se ele deixar passar muita coisa, experimente um ponto de operação que privilegie o recall e registre novamente. Trate o texto mascarado como reduzido, nunca como anônimo.

Conte o custo de um rótulo errado

Última alteração na edição 2026.11.27

A comparação com os padrões avaliou o modelo por correspondência exata e por sobreposição, que exigem um rótulo do tipo do trecho. A mascaração não lê o rótulo: um número de cartão que o modelo rotula como private_phone continua sendo ocultado. A classificação lê, porque governance/pii.toml associa cada tipo de entidade a uma classificação: um número de telefone a personal, um número de cartão a sensitive. Meça a cobertura do modelo ao lado do seu recall, e os rótulos que ele atribui aos números de cartão, aos números de telefone e aos endereços da plataforma:

privacy-filter-labels.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Measures the model's coverage of card numbers, phone numbers and addresses whatever their label, and counts the labelsthat would misclassify them. The prose rests on the coverage lines, the mislabelled counts and the uncovered addresses."""from lib import pii# What the model's labels cost. A span is covered when every character of it is inside some detection, whatever its# label: that's what masking needs. Exact and overlap matching also need a label of the span's type.model, _ = pii.recorded("pii-entities")labelled = pii.truth()covered = pii.coverage(model, labelled)for entity in ("CREDIT_CARD", "PHONE_NUMBER", "LOCATION"):    n, fully = covered[entity]    print(f"{entity}, covered by the model, any label: {fully / n:.2f}")spans = {entity: [s for s in labelled if s.entity == entity] for entity in ("CREDIT_CARD", "PHONE_NUMBER", "LOCATION")}print("card numbers labelled private_phone:", pii.caught(spans["CREDIT_CARD"], model, {"private_phone"}))print("phone numbers labelled account_number:", pii.caught(spans["PHONE_NUMBER"], model, {"account_number"}))# For each address, the labels of the detections that overlap it, and the characters no detection covers.on = pii.labels_on(spans["LOCATION"], model)print("addresses with no detection at all:", sum(not labels for labels in on))print("addresses read, at least in part, as a person:", sum("private_person" in labels for labels in on))# A person label and no address label: the address was read as a name, which overlap matching can't credit.print("of them, with no address label:", sum({"private_person"} <= labels and "private_address" not in labels for labels in on))left = [pii.uncovered(address, model) for address in spans["LOCATION"]]print("addresses not fully covered:", sum(bool(chars) for chars in left))print("of them, with only spaces and punctuation left:", sum(bool(chars) and not any(c.isalnum() for c in chars) for chars in left))
Saídapython privacy-filter-labels.py
CREDIT_CARD, covered by the model, any label: 0.87
PHONE_NUMBER, covered by the model, any label: 1.00
LOCATION, covered by the model, any label: 0.67
card numbers labelled private_phone: 40
phone numbers labelled account_number: 27
addresses with no detection at all: 24
addresses read, at least in part, as a person: 28
of them, with no address label: 20
addresses not fully covered: 70
of them, with only spaces and punctuation left: 21

Um rótulo errado custa mais à classificação do que à mascaração. O modelo cobre 0.87 dos números de cartão, mas rotula 40 dos 213 como números de telefone, de modo que seu recall para cartões é de apenas 0.69. Se a plataforma classificasse colunas a partir dos rótulos do modelo, uma coluna desses números de cartão seria proposta como personal, e não como sensitive. É isso que os padrões acrescentam: a verificação de Luhn mantém como cartões os números rotulados como cartões.

O erro também ocorre no sentido inverso, em direção ao lado mais restritivo. O modelo rotula 27 números de telefone como account_number, que é associado a números de cartão e IBANs, de modo que sua cobertura de telefones é 1.00 e seu recall 0.94.

Os endereços mostram o que cada medida conta. O recall exato do modelo para eles é 0.67, seu recall por sobreposição é 0.79, e sua cobertura é 0.67. O modelo não encontra nada em 24 endereços.

O modelo lê parte de 28 endereços como se fossem nomes de pessoas, já que o Faker constrói muitos nomes de ruas a partir de sobrenomes, como observa a ficha de dados da plataforma. Ele não atribui a 20 desses endereços nenhum rótulo de endereço, de modo que a correspondência por sobreposição também os deixa passar. Outros endereços voltam em pedaços com o rótulo correto, como uma rua e uma cidade separadas por vírgula. A correspondência por sobreposição os considera, e a cobertura não. Dos 70 endereços não totalmente cobertos, 21 têm todas as letras e dígitos mascarados, restando apenas uma vírgula ou um espaço. A cobertura é a medida que a mascaração exige, e ela é rigorosa.

Regra prática: Informe a cobertura, qualquer que seja o rótulo, ao lado do recall com o rótulo correto: a mascaração exige a primeira, a classificação, o segundo. Leia quais rótulos um detector atribui a cada tipo de trecho, e mantenha um reconhecedor com soma de verificação para cada identificador cujo rótulo decide uma classificação, como os números de cartão.

Classifique de novo quando o esquema mudar

Última alteração na edição 2026.11.27

Uma classificação descreve uma coluna em um momento, e o capítulo 2 mostrou como os esquemas se movem sob ela. Então a pergunta é quando classificar de novo, e não a cada ID de esquema: no PyIceberg, editar a descrição de uma coluna gera um novo ID de esquema sem nenhuma coluna nova. O que precisa ser classificado é um ID de campo, o número que o Iceberg atribui a cada coluna, que os metadados nunca viram. O Iceberg dá um novo ID a cada coluna adicionada, e uma coluna renomeada mantém seu ID e, com ele, a classificação revisada. Os valores também podem mudar sem mudança de esquema, então as amostras de colunas de texto precisam ser executadas de novo periodicamente. Fornecedores prometem isso como serviço: o Databricks afirma que sua classificação analisa os dados de forma incremental e classifica novos dados sem configuração manual (documentação do Databricks), uma afirmação que não testamos.

A equipe de suporte quer um número para ligar de volta para os alunos em chamados abertos por telefone, então adiciona uma coluna chamada callback_number a support.tickets. A mudança ocorre em quatro etapas: editar uma descrição, adicionar a coluna, preenchê-la com os números de telefone dos alunos e, então, classificar apenas os IDs de campo que governance/metadata.toml não tem:

reclassify-new-columns.py Python 3.12.15 · duckdb 2.0.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · tldextract 5.4.0 Aprovado
"""Edits the tickets table twice, first a column's description and then a new column, and after each change counts the fieldIDs the metadata lacks. The prose rests on the schema IDs, the field counts and the proposal for the new column."""from pyiceberg.types import StringTypefrom lib import metadata, piifrom lib.catalog import fill_column, open_catalogfrom lib.platform import loadfrom lib.warehouse import connectcatalog = open_catalog(["support.tickets"])tickets = catalog.load_table("support.tickets")reviewed = metadata.load()["support.tickets"].columns           # field ID -> the column as people reviewed it# A field ID the reviewed metadata doesn't have: Iceberg gives each added column a new one.unclassified = lambda: {f.field_id for f in tickets.schema().fields if f.field_id not in reviewed}print("schema ID at the start:", tickets.schema().schema_id)with tickets.update_schema() as update:                         # a doc edit: a new schema, no new column    update.update_column("body", doc="What the learner wrote, as they wrote it.")print("schema ID after a doc edit:", tickets.schema().schema_id)print("fields to classify after the doc edit:", len(unclassified()))# The support team starts storing the number to call back for tickets opened by phone: the learner's phone number.with tickets.update_schema() as update:    update.add_column("callback_number", StringType(), doc="Where to call the learner back.")phone_of = {row["learner_id"]: row["phone"] for row in load("crm.learners").to_pylist()}# tickets from other channels have no callback number, so their value is Nonefill_column(tickets, "callback_number", lambda row: phone_of[row["learner_id"]] if row["channel"] == "phone" else None)print("schema ID after adding a column:", tickets.schema().schema_id)print("fields to classify after adding a column:", len(unclassified()))# only= keeps the proposals to the field IDs the metadata lacks.for f in pii.classify(catalog, connect(catalog), pii.platform_detector(), only={"support.tickets": unclassified()}):    found = ", ".join(f"{entity} in {n} of {f.sampled}" for entity, n in f.found.items())    print(f"{f.table}.{f.column}, field ID: {f.field_id}")    print(f"{f.table}.{f.column}, entity its name suggests: {f.named}")    print(f"{f.table}.{f.column}, found in its sampled values: {found}")    print(f"{f.table}.{f.column}, proposed classification: {f.classification}")
Saídapython reclassify-new-columns.py
schema ID at the start: 0
schema ID after a doc edit: 1
fields to classify after the doc edit: 0
schema ID after adding a column: 2
fields to classify after adding a column: 1
support.tickets.callback_number, field ID: 9
support.tickets.callback_number, entity its name suggests: None
support.tickets.callback_number, found in its sampled values: PHONE_NUMBER in 154 of 173
support.tickets.callback_number, proposed classification: personal

Uma edição de documentação move o esquema para um novo ID e deixa 0 campos para classificar, já que não adiciona coluna. Adicionar a coluna move o esquema para 2, com 1 campo para classificar: o ID de campo 9.

Nenhuma regra baseada em nomes corresponde a callback_number, já que ela não contém nenhuma das palavras que a regra de telefone procura, e é assim que uma regra de nome deixa escapar uma coluna para a qual ninguém a escreveu (uma coluna que ninguém previu ao escrever a regra). Os valores resolvem a questão. A amostra encontra PHONE_NUMBER in 154 of 173, e a proposta é personal.

O pull request que adiciona a coluna é onde pertence a sua classificação, ao lado da entrada de metadados de que precisa: o capítulo 10 reprova esse pull request até que a coluna tenha uma. Uma proposta a partir dos valores precisa de uma coluna que contenha valores, então esta vem da amostra agendada.

Regra prática: Classifique todo ID de campo que os metadados não tenham, no pull request que o adiciona, e não permita o merge sem uma classificação revisada. Baseie o gatilho em IDs de campo, nunca em IDs de esquema. Amostre de novo todas as colunas de texto periodicamente também, porque os valores mudam sem mudança de esquema.

O que dá errado em produção

Última alteração na edição 2026.11.27

A pior falha de um detector é a omissão, e a saída dele sempre tem a aparência de uma lista de achados: o que ele deixa de detectar nunca aparece nela:

  • Números de telefone lidos como números de conta bancária. Com os padrões do Presidio, toda sequência de 8 a 17 dígitos é um número de conta bancária dos EUA, e também todo número de telefone digitado sem separadores. As evidências da tabela de tickets listam 689 números bancários que não estão lá, um relatório de "números bancários em tickets" encaminha alguém para a equipe errada, e mapear essa entidade para uma classificação criaria colunas pelo motivo errado. Mantenha apenas os reconhecedores de que o seu texto precisa, cada um com seu próprio limiar, como a seção sobre ajuste faz, e conte as detecções por rótulo: um rótulo com centenas de ocorrências e nenhum trecho rotulado é um falso positivo.
  • Nomes em texto livre não detectados. Os padrões não encontram nomes, e o modelo deixa passar alguns nomes em minúsculas, primeiros nomes que também são palavras e primeiros nomes isolados. O ticket 19 ainda diz "this is juan fonseca, i still can't log in" depois que os dois detectores foram executados, e passa em todas as verificações que contam detecções. Você só percebe isso medindo a revocação contra texto rotulado, caso difícil por caso difícil, e lendo uma amostra da saída mascarada.
  • Dados pessoais em uma coluna chamada notes. Nenhuma regra de nome a marca, e um revisor que não a leu a classifica como internal. Amostre os valores de toda coluna de texto e trate as colunas de texto livre como pessoais até que uma amostra mostre o contrário.
  • Uma coluna mais sensível do que os seus metadados. Os alunos colam números de cartão nos tickets, então support.tickets.body contém dados sensitive sob uma classificação personal. Compare cada proposta com os metadados revisados e encaminhe uma proposta mais restritiva ao responsável pela tabela.
  • Um detector que acessa a rede. AnalyzerEngine() baixa um modelo, e o tldextract busca a Public Suffix List. Sem conexão, o pipeline falha; com conexão, o mesmo texto pode ser classificado de forma diferente em duas máquinas. Uma configuração lida na importação só vale se for feita antes de qualquer importação da biblioteca. Configure o motor, fixe o que ele buscaria, verifique que a configuração foi aplicada e execute os testes do detector com a rede desligada.
  • Verdade moldada pelo seu gerador. O texto da plataforma vem de 30 modelos de frase preenchidos pelo Faker, que escreve toda data de nascimento de um único jeito, números de telefone que não são válidos onde o aluno mora, e nomes de ruas formados a partir de nomes de pessoas. Leia as omissões antes de confiar em um índice de revocação, e meça de novo em amostras rotuladas do seu próprio texto.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • As colunas são classificadas pelo nome, pelo tipo e pelos valores. As regras de nome são aplicadas a todas as colunas; as colunas de texto são amostradas; a evidência mais restritiva prevalece, tendo internal como piso, e somente uma pessoa define public.
  • As amostras são reproduzíveis: 200 valores não nulos por coluna de texto, obtidos por uma amostra de reservatório com semente, em uma única thread do DuckDB.
  • O Presidio roda offline, sobre NoOpNlpEngine, com 6 reconhecedores, cada um com seu próprio limiar; as regiões de telefone são lidas a partir dos países dos alunos; e o tldextract usa sua própria cópia da Public Suffix List, verificada quando lib.pii é carregado.
  • Os detectores são medidos contra trechos rotulados: revocação por tipo de entidade, com correspondência exata e por sobreposição, exigindo um rótulo do tipo correto; cobertura, qualquer que seja o rótulo; precisão por rótulo; e textos sem nenhum dado pessoal. A revocação tem o maior peso.
  • Uma proposta mais restritiva que os metadados é um achado: support.tickets.body vai para team-support como sensitive, e billing.payments.card_number vai para team-billing, com a evidência de que ela contém números de cartão completos.
  • O texto livre é mascarado com dois detectores: o Privacy Filter da OpenAI, registrado em uma revisão fixada e em um ponto de operação fixado, para nomes e endereços; e os padrões ajustados para números de cartão, IBANs e números de telefone, cujas somas de verificação fazem com que números de cartão sejam rotulados como cartões. O mascaramento oculta tudo o que qualquer um dos dois encontrar; nenhum dos dois é considerado capaz de tornar um texto anônimo.
  • Nenhum exemplo imprime um número de telefone, de cartão ou um IBAN completo: lib.pii.masked mantém apenas os últimos quatro dígitos.
  • A reclassificação acompanha os IDs dos campos: todo campo que os metadados não possuem é classificado no pull request que o adiciona, e as colunas de texto são amostradas novamente em um cronograma. Um detector só é tão bom quanto a medição que está por trás dele, e o que ele deixa passar nunca aparece em sua saída. A medição é o que informa a uma equipe quais de suas classificações ela pode confiar e quais precisa verificar manualmente.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 202611 de 11 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.31.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 3 de 10: Encontrando dados pessoais

  1. Classificar colunas pelo esquema
  2. Execute o Presidio offline
  3. Amostre os valores de uma coluna da mesma forma em cada execução
  4. Classificar colunas a partir de seus valores
  5. Meça um detector contra trechos rotulados
  6. Ajuste os reconhecedores com base no gabarito
  7. Veja onde os padrões falham
  8. Compare um modelo de PII
  9. Leia os erros do modelo
  10. Conte o custo de um rótulo errado
  11. Classifique de novo quando o esquema mudar
  12. O que dá errado em produção
  13. O que este capítulo decidiu

Voltar ao topoTodos os capítulos