IDs semânticos — Documentação do Entity Enricher

IDs semânticos

Enriqueça o mesmo tipo de entidade uma e outra vez e continua a redescobrir as mesmas coisas do mundo real — a mesma empresa, o mesmo efeito secundário de um medicamento, a mesma pessoa — descritas com palavras ligeiramente diferentes de cada vez. Um ID semântico é um identificador estável, no âmbito da organização, que o Entity Enricher atribui a um objeto a partir dos seus campos-chave, para que esses quase-duplicados se reduzam a uma identidade pela qual pode agrupar, desduplicar e fazer junções.

O problema: a mesma coisa, palavras diferentes

A identidade de um objeto é construída a partir dos seus campos-chave — e pode haver um ou vários. Dois exemplos:

Uma chave

Um efeito secundário indexado por `name`

Aparece como Headache, Céphalée e Cephalalgia em diferentes execuções e idiomas. Um campo-chave, três grafias, um conceito real.

Duas chaves

Uma empresa indexada por `nome` + `país`

Acme Inc. · Estados Unidos e Acme Incorporated · Estados Unidos são a mesma empresa — enquanto Acme Inc. · Alemanha é uma diferente. A segunda chave desambigua; é por isso que um objeto pode ter mais do que uma.

A correspondência simples de cadeias de texto falha em todos estes casos; um humano sabe quais são iguais. Os IDs semânticos codificam esse juízo automaticamente.

O que é um semantic ID

•Uma única propriedade string num objeto (denominada id por predefinição), que contém um identificador opaco e estável.
•Estável e delimitado à organização — a mesma entidade do mundo real resolve para o mesmo ID em enriquecimentos, lotes e ao longo do tempo, apenas dentro da sua organização.
•Atribuído automaticamente, nunca pelo LLM — é calculado numa passagem pós-enriquecimento, por isso o modelo não o pode alucinar. É um campo de passagem direta (preserve): sempre uma string, nunca uma chave, nunca multilingue, no máximo um por objeto.
•Permitido em qualquer objeto — a entidade completa (raiz), um objeto aninhado 1-1 (por exemplo, um fabricante) ou cada item de um array (por exemplo, cada side_effect).

Como funciona

Após o modelo devolver o seu resultado, o Entity Enricher resolve cada ID semântico em quatro passos — começando pelo mais barato:

Compor o texto de identidade

Junte todos os campos-chave do objeto — mais as chaves de quaisquer objetos aninhados 1-1 que contenha — numa única string, no seu idioma principal. Os itens dentro de arrays não são incluídos: cada item de array tem a sua própria identidade. O texto é normalizado (convertido para minúsculas, parênteses removidos, espaços colapsados) para reduzir diferenças triviais.

Procurar uma correspondência exata

Se esse texto normalizado exato já tiver sido visto anteriormente na sua organization, o seu ID existente é reutilizado de imediato — sem chamada ao modelo, sem custo.

Incorporar e comparar

Caso contrário, o texto é incorporado e comparado, pelo significado, com os conceitos existentes do mesmo tipo através de similaridade vetorial — de modo que “Acme Inc.” e “Acme Incorporated” ficam lado a lado.

Reutilizar ou emitir

Se a correspondência mais próxima obtiver uma pontuação acima do limiar de similaridade (predefinição 0.92, ajustável por propriedade), o ID desse conceito é reutilizado. Caso contrário, é gerado um ID totalmente novo e armazenado para a próxima vez.

Compromisso do limiar: um limiar mais alto é mais rigoroso (menos fusões acidentais); um mais baixo é mais permissivo (deduplicação mais agressiva). Ajuste-o por propriedade quando o valor predefinido de 0,92 fundir a mais ou a menos.

IDs de entrada vs. IDs gerados

Se um ID é gerado depende de já existir um presente na entrada para esse objeto. É isto que lhe permite fazer round-trip: enriqueça uma vez para obter IDs e, depois, passe um ID conhecido em execuções posteriores para associar novos factos à mesma identidade — mais barato e sem ambiguidade.

ID já presente no input → mantido (consulta)

Se o objeto que envia já contém um semantic ID, é tratado como uma consulta: o ID é mantido tal como está, o record é associado a esse conceito existente e não há embedding — sem custo, sem match-or-mint. Está a dizer à plataforma “este objeto já está identificado na nossa base de dados”.

Sem ID na entrada → gerado

Se o objeto não tiver um semantic ID, a plataforma gera um com os quatro passos acima. Esse ID passa a ser, a partir daí, o identificador estável do objeto na base de dados da sua organization.

Um valor presente mas não reconhecível (que não é um ID de conceito real) é ignorado, sendo gerado um ID em vez disso.

Como ativá-lo

Escolha um modelo de embedding (uma vez por organização)

Um proprietário escolhe um modelo com capacidade de embedding em Gestão de Modelos como o modelo de embedding predefinido da organização. É quase imutável: assim que existirem conceitos, só pode ser limpo, não alterado (os vetores armazenados não são comparáveis entre modelos). Sem ele, os IDs semânticos são simplesmente ignorados.

Adicionar IDs semânticos ao esquema

Duas formas, ambas no Editor de Schema:

Automaticamente na geração — marque “Gerar IDs semânticos para tipos”; cada objeto com uma chave (a sua própria, ou uma num objeto aninhado 1-1) recebe um, incluindo a entidade raiz.
Manualmente — utilize o controlo “+ Adicionar ID semântico” em qualquer objeto ou no rodapé da entidade.

A resolução consome uma pequena quantidade de utilização de embeddings por enriquecimento (medida como qualquer chamada de modelo). A cache de correspondência exata torna as repetições gratuitas e os IDs fornecidos na entrada não têm qualquer custo.

Onde os IDs aparecem e o que fazer com eles

Os IDs resolvidos aparecem no JSON de saída do enriquecimento (o campo id em cada objeto) e nos conceitos semânticos do detalhe do registo. Utilize-os para:

•Desduplique linhas entre lotes e ao longo do tempo.
•Crie uma chave de junção estável para o seu data warehouse ou CRM.
•Reconcilie a mesma entidade observada em dias diferentes ou em idiomas diferentes.

Complementa a fusão de múltiplos modelos

A fusão reconcilia discordâncias entre modelos dentro de uma única execução; os IDs semânticos reconciliam a mesma entidade ao longo de execuções e do tempo. Os dois funcionam em conjunto.

Conceitos Fundamentais

Chaves de pesquisa e de fusão, sobre as quais os IDs semânticos se baseiam

Enriquecimento Multilingue

Unir grafias de diferentes idiomas numa só identidade

Fusão Multi-Modelo

Reconcilie entre modelos numa única execução

Editor de esquemas

Adicionar IDs semânticos a qualquer objeto