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 num passo pós-enrichment, pelo que o modelo não o pode inventar. É um campo de passagem (os valores de entrada fluem sem alterações): é sempre uma string, nunca uma chave, nunca preserve, 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

Depois de o modelo devolver o resultado, o Entity Enricher resolve cada ID semântico em seis passos — do mais barato para o mais caro. Os quatro passos anteriores ao embedding são pura comparação de texto, por isso uma identidade resolvida nessa fase não tem qualquer custo:

Compor o texto de identidade

Junte os campos-chave que identificam o próprio objeto numa única cadeia de texto, no seu idioma principal. Um objeto aninhado que é, por direito próprio, uma entidade fica de fora: a sua chave identifica-o a ele, e não aquilo que lhe faz referência, e todos os irmãos que referenciem a mesma entidade teriam esse mesmo valor — duas missões que partilhassem um local de lançamento ficariam quase idênticas e correriam o risco de colapsar numa só. Os objetos aninhados que apenas agrupam campos continuam a contribuir; o mesmo acontece com a chave de uma entidade relacionada, caso a adicione manualmente. Os itens dentro de arrays nunca são incluídos: cada item do array tem a sua própria identidade. A lista participantes de identidade do editor de esquemas mostra exatamente que valores compõem o texto e permite reordená-los ou alterá-los — esquemas que escolham os mesmos participantes pela mesma ordem geram IDs idênticos. O texto é normalizado (convertido para minúsculas, conteúdo entre parênteses removido, espaços em branco reduzidos) para atenuar diferenças triviais. Se todos esses campos-chave vierem vazios, não há nada que identifique o objeto e não é possível atribuir qualquer ID — por isso o objeto é removido, em vez de ser mantido como um objeto anónimo sobre o qual nada pode ser agrupado, associado ou desduplicado: um objeto aninhado passa a null no objeto que o contém e um item dentro de uma lista é removido da lista. A entidade enriquecida em si nunca é removida; fica apenas sem ID.

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.

Corresponder por um código, se existir

Quando uma das chaves de identidade é um código — um campo restringido por um padrão, ou cujos exemplos parecem identificadores — é composto primeiro e comparado isoladamente. Uma correspondência exata de código resolve a identidade de imediato, seja qual for a redação em redor, pelo que LC-39A unifica todas as formas como o resto do texto foi escrito. Igualmente importante, funciona também no sentido inverso: um código diferente veta uma fusão que o passo de embedding teria aceitado, porque duas coisas com identificadores diferentes são duas coisas, por mais parecidas que sejam.

Corresponder pelas mesmas palavras em qualquer ordem

Antes de gastar um embedding, as próprias palavras são comparadas como conjunto: se as palavras de um texto estiverem contidas nas do outro, trata-se da mesma identidade escrita com extensões diferentes — “Boeing” e “The Boeing Company”. Isto apanha exatamente as diferenças de verbosidade que os embeddings medem como muito distantes, e não custa nada: tal como no passo de texto exato, uma correspondência aqui significa nenhuma chamada de embedding e nenhum custo.

Incorporar e comparar

Caso contrário, o texto é incorporado e comparado, por significado, com os conceitos existentes do mesmo tipo de conceito (o nome do tipo de entidade por predefinição — substituível no editor para que esquemas com nomes diferentes partilhem um mesmo espaço de conceitos) utilizando similaridade vetorial — para que “Acme Inc.” e“Acme Incorporated” fiquem lado a lado.

Reutilizar ou emitir

Se a correspondência mais próxima ficar acima do limiar de semelhança (por predefinição 0.92, ajustável por propriedade), o ID desse conceito é reutilizado. Caso contrário, é gerado um ID totalmente novo e guardado para a próxima vez. Há uma exceção que anula uma pontuação elevada: quando os dois textos são as mesmas palavras contadas de forma diferente — «segunda fase» e«terceira fase» — são tratados como coisas distintas, porque é precisamente a contagem que os distingue. O mesmo número escrito de duas formas (2 eII) continua a corresponder.

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 ID semântico, a plataforma gera um com os passos acima. A partir daí, esse ID passa a ser o identificador estável do objeto na base de dados da sua organização.

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 Definições → Organização → Predefinições como modelo de embedding predefinido da organização (uma definição condicionada pelo plano; consulte Modelos e Preços para saber que modelos suportam embeddings). Os vetores guardados não são comparáveis entre modelos, por isso, assim que existirem conceitos, a definição só pode ser limpa — mudar de modelo é executado como uma migração a partir da página IDs Semânticos, que volta a gerar o embedding de todos os conceitos e mantém os respetivos IDs. Sem um modelo, os IDs semânticos são simplesmente ignorados.

Adicionar IDs semânticos ao esquema

Duas formas, ambas no Editor de Fluxo de Trabalho:

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 de cada objeto), nos conceitos semânticos do detalhe do registo e todos juntos na página de IDs semânticos, onde o vocabulário que formam é consultado e curado. Use-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 Fluxo de Trabalho

Adicionar IDs semânticos a qualquer objeto

A página de IDs semânticos

Navegue, faça a curadoria e elimine duplicados no vocabulário resultante