Deduplicação de entidades: de 50 milhões de pares a milhares com pipeline em três estágios

Por que uma similaridade de 0,91 engana

Duas linhas de fornecedor pontuam 0,91 de similaridade em embeddings. Uma é a mesma empresa cadastrada por dois times de compras com um ano de diferença; a outra são duas entidades jurídicas distintas — uma “Acme Industrial Supply” em Ohio e outra em Singapura — que a área financeira precisa manter separadas. Pontuação idêntica, decisão correta oposta. Essa distância é o problema central de quem coloca embeddings na frente de tudo.

A similaridade de cosseno entre dois embeddings é uma grandeza geométrica relativa, não uma probabilidade. Ela não tem unidade, não tem relação garantida com a chance de os registros serem o mesmo, e não tem significado estável entre implantações: o mesmo par pode cair em 0,86 com um modelo e 0,79 com outro. Por isso, o corte fixo de 0,85 que a maioria dos tutoriais entrega não se transfere entre projetos, modelos ou corpora. É esse o ponto de partida do guia de Tyler Brooks para construir um pipeline de deduplicação de entidades que funcione em produção.

O caso base: 10 mil fornecedores e 50 milhões de comparações

O guia percorre uma lista concreta de 10.000 fornecedores, com a bagunça típica de um cadastro alimentado por exportações de ERP, CRM e formulários escaneados de onboarding:

• Ruído de maiúsculas e espaços: “acme industrial supply ” versus “ACME Industrial Supply”;
• Abreviações: “Intl” versus “International”, “Mfg” versus “Manufacturing”;
• Variantes de sufixo legal: “Ltd”, “Limited”, “LLC”, “GmbH” e combinações;
• Erros de OCR: “Sunrise Logistcs” vindo de um W-9 escaneado;
• Uma marca com múltiplas entidades legais (matriz e subsidiárias por país) compartilhando nome normalizado.

Antes de qualquer pontuação, comparar cada registro com todos os outros gera 10.000 × 9.999 ÷ 2 = 49.995.000 pares únicos. A um milissegundo por comparação, são cerca de 14 horas só de pontuação — e com inferência de embeddings em cada par, a conta deixa de ser defensável. Cada estágio seguinte é julgado por um único critério contábil: quantas comparações processa, quantos novos matches verdadeiros encontra, e quanto custa na margem.

Estágio 1: normalização e hashing de chaves

Antes de casar qualquer coisa, normalize os nomes com regras determinísticas:

• Normalização Unicode (NFC ou NFKC) para que formas acentuadas e compostas deixem de parecer diferentes;
• Dobragem de caixa e colapso de espaços;
• Remoção de sufixos legais contra uma lista (“Ltd”, “LLC”, “Inc”, “GmbH”, “Pte Ltd”…);
• Expansão de abreviações a partir de um dicionário de domínio (“Intl” → “International”, “Mfg” → “Manufacturing”).

Depois, gere um hash da string normalizada e agrupe os registros por igualdade exata de chave. Isso é uma busca por hash, não um escaneamento par a par — o custo é efetivamente zero. Em muitas listas de fornecedores, esse único estágio captura a maior fatia dos duplicados verdadeiros (todas as variantes de espaço, caixa e sufixo). O que o hashing não alcança é o julgamento difuso: “Sunrise Logistcs” gera um hash diferente de “Sunrise Logistics”. Esse resíduo segue para o estágio 2.

Estágio 2: blocking e geração de candidatos

Blocking reduz as comparações pareadas atribuindo a cada registro uma ou mais chaves de bloco e comparando apenas dentro de cada bloco. Chaves práticas para fornecedores: os primeiros caracteres do nome normalizado, uma impressão digital de tokens ordenados (ordene os tokens alfabeticamente para a ordem das palavras deixar de importar) e geografia (código de país ou região). Um par cujos registros não compartilham nenhuma chave de bloco nunca é comparado — e aí mora o risco conhecido de recall: um registro com erro de digitação no campo que gera a chave pode cair em um bloco onde seu gêmeo não está. Use várias chaves sobrepostas para que o par precise colidir só uma vez.

Na lista de exemplo, três chaves de bloco tipicamente derrubam 50 milhões de pares para milhares de candidatos — quatro ordens de magnitude de redução ao custo de um group-by. Dentro dos blocos, pontuações difusas baratas fazem a triagem: distância de edição normalizada, Jaccard sobre conjuntos de tokens ou, se os dados vivem em Postgres, o operador pg_trgm. No fim, sobram três pilhas: pares decididos por concordância exata, pares claramente distintos e uma faixa ambígua no meio.

Estágio 3: embeddings só para a faixa ambígua

A faixa ambígua é o resíduo — pares como “Sunrise Logistcs Pte” contra “Sunrise Logistics Private”, onde as pontuações determinísticas ficam numa faixa média sem informação e a geografia é ausente ou não confiável. Os embeddings existem neste pipeline para adjudicar essa faixa e nada mais.

Essa posição é um argumento econômico, não uma preferência. O escore por embedding é a comparação mais cara do pipeline; apontado para os 50 milhões de pares, você paga a tarifa máxima pelo trabalho de menor valor. Apontado para a faixa, cada dólar de inferência compra uma decisão genuinamente contestada.

Como calibrar o limiar sem rótulos

Sem pares rotulados e sem orçamento de anotação, dá para escolher um limiar defensável em quatro movimentos:

1. Plote a distribuição dos escores. Pontue todos os pares da faixa ambígua e faça um histograma. Corpora bem-comportados costumam mostrar duas modas (prováveis matches e prováveis não-matches) com um vale entre elas. O vale — não as modas — é o corte candidato.
2. Cheque um conjunto semeado. Amostre de 20 a 50 pares, pesando o vale e os flancos dos dois lados, e rotule você mesmo. É uma hora de trabalho que converte “0,85 parece certo” em “o vale em 0,87 se sustentou em 40 pares checados”.
3. Coloque o corte com prioridade em precisão. Assuma que uma fusão falsa custa mais que um duplicado perdido (verdadeiro em cadastros de fornecedores, onde registros fundidos corrompem histórico de pagamento e trilhas de auditoria). Posicione o limiar acima do vale, no lado do match, para que pares limítrofes vão para revisão humana em vez de fusão automática.
4. Faça sanity check por fatias. Divida por sistema de origem ou região e confirme que distribuição e corte se mantêm. Um limiar que só funciona numa fatia indica que as fatias precisam de tratamento diferente.

O ledger de custo por estágio

O artefato que organiza tudo é uma tabela — uma linha por estágio, atualizada a cada execução. Os números abaixo são ilustrativos da forma, não um benchmark:

Se o seu ledger mostrar o estágio de embeddings custando múltiplos por match em relação ao trigrama para poucos achados marginais, você tem uma resposta defensável para “precisamos mesmo de embeddings aqui?” — com números anexados.

Modos de falha que os tutoriais ignoram

• Sobre-fusão transitiva. Você decide por pares, mas entidades são grupos: ao tomar o fecho transitivo, A casa com B, B casa com C e A não casa com C pelo seu próprio limiar — ainda assim os três colapsam numa entidade só, e cadeias longas podem arrastar registros que nenhuma decisão de par sustenta. Mitigue com restrições de concordância mínima no grupo, limite de cadeia ou roteando componentes grandes para revisão.
• Entidades legais distintas com nome normalizado igual. O estágio 1 remove sufixos legais, que é exatamente o que faz “Acme Ltd” e “Acme LLC” colidirem — mas um daqueles sufixos carregava informação real: jurisdição. É por isso que chaves de bloqueio devem incluir geografia e fusões de alta similaridade devem corroborar contra um campo secundário (CNPJ, registro, endereço) antes de cometer.
• Exigências de auditoria. Quando um revisor pergunta por que dois registros foram fundidos no trimestre, “cosseno era 0,91” não é resposta. Contextos de auditoria exigem um registro de fusão explicável: qual estágio disparou, qual regra ou limiar, sobre qual evidência de campo — com o limiar em vigor no momento da decisão e a fusão reversível.

Ordem de construção e checklist

1. Normalize, gere hash, agrupe. Meça rendimento e custo.
2. Adicione duas ou três chaves de bloco sobrepostas. Meça candidatos e risco de recall.
3. Pontue dentro dos blocos com métricas difusas baratas. Empilhe o restante na faixa ambígua.
4. Embeba só a faixa. Calibre sem rótulos: vale da distribuição, 20 a 50 checagens semeadas, corte com prioridade em precisão.
5. Agrupe com salvaguardas anti-cadeia, corrobore matches só-por-nome contra um campo secundário e registre uma decisão explicável para cada fusão.
6. Mantenha o ledger atualizado. Toda discussão de arquitetura termina quando alguém abre a tabela.

Recalibre quando o corpus mudar materialmente (novo sistema de origem, dados de um novo país), quando trocar o modelo de embeddings (escores são dependentes do modelo e o limiar antigo se anula) ou quando o vale da distribuição visivelmente se mover.

A lição é a mesma do par de 0,91 da abertura: um escore de similaridade não é um fato sobre dois registros — é evidência, não calibrada e dependente de contexto, à espera de um processo de decisão. Construa os estágios determinísticos que barateiam a evidência, reserve o adjudicador caro para o que só ele resolve e mantenha números sobre cada estágio para defender a ordem diante de qualquer um.