Encontre propriedades de esquema que possam estar a fazer mais do que uma pergunta — veja as leituras concorrentes lado a lado e fixe cada propriedade num único significado antes de os dados serem recolhidos.
O Entity Enricher trata os LLM como bases de conhecimento consultáveis, e o nome de uma propriedade é a pergunta que está a fazer. Quando o nome admite várias leituras, cada modelo escolhe discretamente uma — e assim size numa empresa devolve um número de colaboradores num modelo, um valor de receita noutro e uma área útil num terceiro. Os modelos não discordaram sobre um facto. Responderam a perguntas diferentes, e a sua coluna contém agora uma mistura de respostas que nenhum consumidor a jusante consegue distinguir.
Fixar o significado é o que torna um enriquecimento comparável entre modelos e estável ao longo do tempo. Também melhora tudo o que vem a jusante: a fusão multimodelo deixa de ver conflitos que são, na verdade, duas perguntas, e as comparações de benchmark deixam de penalizar modelos por lerem o seu esquema de forma diferente da referência.
Um facto que simplesmente muda ao longo do tempo não é ambiguidade. Um esquema é um contrato duradouro, pelo que um ceo com este nome simples significa “o CEO no momento do enriquecimento”, e voltar a executar o esquema no próximo ano deve devolver o novo. A verificação nunca propõe fixar uma data no nome — isso quebraria todas as execuções futuras.
Toda a verificação se resume a uma pergunta, feita a cada propriedade: ao ler o seu nome no contexto do respetivo objeto pai, quantas coisas distintas poderia estar a pedir? A contagem é o veredicto.
| Interpretações | Veredicto | O que significa |
|---|---|---|
| Exatamente uma | Limpar | Todos os modelos procuram a mesma coisa. Sem chip, nada a corrigir. |
| Duas ou mais | Ambíguo | Cada modelo opta pela sua própria leitura, pelo que a coluna mistura silenciosamente respostas a perguntas diferentes. A verificação identifica as leituras concorrentes e propõe uma formulação que mantém apenas uma. |
| Nenhum | Não mapeável | O nome não designa nada que o objeto pai possua, pelo que o modelo não consegue procurar um valor — inventa-o. As interpretações listadas são as que o analisador considerou e rejeitou, e a solução é mudar o nome ou remover: nenhuma descrição pode dar a uma entidade uma propriedade que ela não tem. |
Uma propriedade que designa exatamente uma coisa pode ainda assim ser assinalada quando o valor não está enquadrado — o leitor sabe o que está a ser perguntado, mas não em que termos vem a resposta. Estes são os padrões recorrentes:
| Subcaso | Exemplo | O que está em aberto |
|---|---|---|
| Referente pouco claro | Companysize | O nome aponta para vários factos distintos que o pai realmente tem — número de colaboradores, receita, área útil. Nada no nome faz a escolha. |
| Medida ou unidade pouco clara | Companyannual_revenue | Um único facto, mas sem moeda, sem período e sem enquadramento bruto/líquido — uma resposta plausível pode errar por três ordens de grandeza e continuar a ser "correta". |
| Escala ou direção pouco clara | Supplierrisk_score | Sem intervalo indicado nem polaridade indicada: 0–10 ou 0–100, e um número alto é mais seguro ou mais arriscado? Dois modelos podem inverter-se mutuamente. |
| Âmbito ou limite pouco claro | Companyemployees | Que subconjunto, que nível de agregação, que perspetiva — todo o grupo ou apenas este local, número de pessoas ou equivalentes a tempo inteiro, prestadores de serviços incluídos ou excluídos. |
| Não mapeável | Authorrelease_year | Um autor não tem ano de lançamento — os seus livros é que têm. O modelo não consegue consultar esta informação, por isso inventa-a. Mude o nome para algo que pertença ao elemento pai ou mova-a para o objeto que a possui. |
As propriedades de texto livre — description, summary, notes, bio — nunca são assinaladas. A redação varia, como é óbvio, de modelo para modelo, mas a pergunta feita é perfeitamente clara, e é só isso que esta verificação avalia. A ambiguidade diz respeito à pergunta, nunca ao grau de semelhança entre as respostas.
Um veredicto isolado (“isto não é claro”) obriga-o a adivinhar o que o analisador tinha em mente. Por isso, cada deteção inclui as suas interpretations: duas a quatro leituras curtas e distintas que a propriedade admite, começando pela mais provável. Essa lista é a deteção — se o analisador não conseguir indicar duas leituras, a deteção é descartada como ruído em vez de lhe ser apresentada.
annual_revenue numa EmpresaA par delas surge uma descrição sugerida que mantém exatamente uma — neste caso, “receita total do grupo em USD referente ao último exercício fiscal concluído, antes de devoluções”. Aplicá-la não custa nada: a descrição chega ao modelo de enriquecimento tal como o nome, mas a propriedade mantém o nome, pelo que nenhum contrato de dados se altera. Quando é o próprio nome que induz em erro, a deteção inclui também nomes sugeridos.
Ver as interpretações explicitadas costuma resolver a propriedade mais depressa do que qualquer explicação: reconhece aquela que pretendia, e as restantes são o que tem estado a receber sem dar por isso.
Depois de gerada uma amostra, o analisador revê os nomes das suas propriedades e devolve um relatório de ambiguidade. As renomeações inequívocas são aplicadas automaticamente às chaves inventadas pela IA (nunca aos campos que o próprio nomeou), pelo que a amostra que revê já se lê melhor. Também assinala propriedades demasiado especializadas — traços que se infiltraram a partir da instância de exemplo e que só se aplicam a um subtipo (as medalhas de um atleta numa Person genérica) — e sugere um tipo de entidade mais restrito. A verificação de âmbito de identidade é executada aqui como uma chamada própria, logo a seguir: define a forma dos itens relacionados antes de rever a amostra. As amostras baseadas em documentos anexados são ignoradas — os seus valores provêm do documento de origem e não da memória do modelo.
Assim que um esquema gerado é guardado, uma passagem posterior anota cada propriedade com o respetivo veredicto de ambiguidade e sugere novos nomes para as que continuam em aberto. Nessa altura, os pontos de relação já estão anotados — a própria geração avalia o seu âmbito, como um dos seus passos —, pelo que a passagem posterior abrange apenas os nomes das propriedades. Este passo é de melhor esforço: se falhar, a geração em si não é afetada.
O botão Verificar de novo executa ambas as verificações — nomes de propriedades e pontos de relação — como duas chamadas paralelas. É o único sítio que sugere uma descrição reescrita em vez de uma mudança de nome. Analisa apenas o que ainda não tem anotação e passa a uma reanálise completa assim que tudo estiver anotado.
O JSON de amostra que cola para criar um esquema pode ser analisado sem estado — recebe um relatório dos nomes de propriedades ambíguos e não mapeáveis, e dos itens relacionados que misturam factos da entidade com factos de emparelhamento, sem que nada seja modificado.
A mesma deteção sugere uma mudança de nome num sítio e uma descrição noutro, e vale a pena perceber porquê. No momento da geração, a descrição ainda não existe de forma independente — é escrita a partir do nome, pelo que só pode repetir a ambiguidade. O nome é a única coisa que pode ser corrigida e ainda nada depende dele. É por isso que tanto a geração de amostras como a passagem posterior à geração do esquema propõem mudanças de nome.
Depois de o esquema estar em produção, mudar o nome de uma propriedade desloca colunas, quebra consultas e refaz as chaves das tabelas sincronizadas, ao passo que uma descrição mais precisa chega ao modelo com a mesma eficácia e não altera mais nada. Por isso, a regra é simples: antes de algo depender do esquema, mude o nome; depois de estar em produção, fixe a descrição — e guarde a mudança de nome para os casos em que o problema é o próprio nome.
A verificação é meramente indicativa. Nada analisa os seus esquemas guardados em segundo plano: é executada na geração e quando prime Verificar de novo. Nunca bloqueia a geração, nunca rejeita um enriquecimento e as suas anotações são removidas de todos os prompts enviados aos modelos de enriquecimento — informa-o a si, não à IA.
As propriedades assinaladas apresentam um chip “ambíguo” no Editor de Workflows: âmbar quando as leituras se sobrepõem na maior parte e apenas diferem em casos-limite; vermelho quando as leituras concorrentes produziriam dados substancialmente diferentes. As propriedades consideradas claras não têm chip. Ao passar o cursor sobre o chip, vê a nota do analisador, as leituras concorrentes encontradas e a descrição ou os nomes sugeridos — assim, a decisão e a correção ficam na mesma dica.
O veredicto é emitido sobre o nome e a descrição de uma propriedade em conjunto — por isso, renomear uma propriedade ou editar a sua descrição elimina a respetiva anotação. O editor destaca essas propriedades como desatualizadas e propõe uma nova verificação, que analisa apenas o que está em falta. É exatamente isto que quer depois de aplicar uma correção sugerida: a nova verificação confirma se a nova formulação fixa mesmo uma única leitura.
O âmbito de identidade é uma segunda verificação, executada como uma chamada de modelo própria a par da análise de ambiguidade e reportada com ela. Analisa todos os pontos de relação — os itens de um array relacionado e os objetos aninhados: quando um deles mistura factos sobre a própria entidade relacionada (o nome, o país) com factos sobre o emparelhamento (um cargo desempenhado para este elemento pai, uma designação específica de cada pai), ambos partilham uma única identidade — e os novos enriquecimentos sobrepõem os factos do emparelhamento entre elementos pai. Esses pontos apresentam, a âmbar, um chip «factos misturados» cuja dica mostra a estrutura recomendada: os campos da própria entidade aninhados num subobjeto e os campos do emparelhamento mantidos no item. Quando o item já inclui um subobjeto desses, a correção é menor — os campos mal colocados passam para o que já existe.
A divisão é aplicada durante a geração da amostra, antes de você aprovar a amostra: a estrutura é fixada na primeira amostra, todos os pontos reestruturados são listados nos avisos de geração e as restantes amostras do lote são geradas de acordo com a estrutura fixada. Por isso, os esquemas gerados a partir de uma amostra nova saem normalmente limpos. As amostras baseadas em documentos anexados ficam como as suas fontes indicavam e recebem antes o chip.
A geração do esquema nunca reestrutura a amostra que você aprovou — avalia os mesmos pontos e reporta o que encontra. Num esquema existente ou escrito à mão, é portanto no chip que está a correção: oferece uma divisão com um só clique que reestrutura a amostra e regenera o esquema a partir dela. A estrutura é o contrato, por isso é alterada regenerando a partir de uma nova amostra, nunca corrigida no lugar. Um ponto que você opte por não dividir continua a funcionar — apenas mantém uma identidade partilhada, e o chip. O chip desaparece por si quando o conjunto de campos do item muda.
A verificação pode ser desativada por esquema a partir do menu adicional do Editor de Fluxos de Trabalho. Quando está desativada, a passagem pós-geração é ignorada, os chips, o botão Verificar de novo e os avisos de desatualização ficam ocultos, e os endpoints de análise respondem com um erro ambiguity_check_disabled. As anotações existentes são mantidas (apenas ocultas) e reativar a verificação num esquema que nunca foi analisado executa-a automaticamente.
Todos os esquemas gerados começam com a verificação ativa, incluindo os esquemas gerados a partir de documentos anexados. A ambiguidade é uma propriedade da forma como o esquema está redigido, não da origem dos valores de uma execução: o documento fixou esses valores uma vez, mas o esquema continua a ser reutilizado com entidades que nunca abrangeu. O que o documento altera é o passo de amostra — os nomes das suas propriedades vêm do vocabulário do próprio documento de origem, pelo que nunca são renomeados em código, sendo o esquema construído a partir deles que passa a ter a verificação.
“A receita anual da empresa” não acrescenta qualquer informação que o nome já não transmitisse, pelo que o analisador trata essa descrição como se estivesse ausente e avalia apenas o nome. Uma descrição justifica-se quando indica a unidade, o período, a escala ou o limite.
As notas e as interpretações do analisador são redigidas no idioma da sua interface — um utilizador francês vê leituras em francês; um japonês, em japonês. Os nomes de propriedades sugeridos permanecem em inglês, de acordo com as convenções de nomenclatura de esquemas.
Cada análise é uma chamada real (e barata) ao modelo — duas, executadas em paralelo, quando também há pontos de relação a delimitar. Cada uma fica registada como um prompt próprio no registo, sob o tipo ambiguity_analysis, e é descontada dos créditos como qualquer outra utilização de IA. As verificações incrementais pagam apenas as propriedades e os pontos de relação efetivamente analisados.
A geração de amostras e de esquemas é, ela própria, instruída para nomear uma só coisa por propriedade e para escrever descrições que indiquem a unidade, a escala e o limite — e, no caso de listas discutíveis, um limite máximo na descrição em vez de uma contagem imposta no nome. Assim, a maioria dos esquemas sai limpa e o analisador só tem de apanhar os casos restantes.
A verificação está disponível programaticamente:
| Superfície | Descrição |
|---|---|
POST /api/schema/analyze-sample | Analisar JSON de amostra colado — ambas as verificações em paralelo num único pedido, relatório sem estado, nada é modificado |
POST /api/schema/saved/{id}/analyze | Analisar um esquema guardado e escrever as anotações de ambas as verificações — incremental por predefinição, force=true reanalisa tudo |
POST /api/schema/scoping-split | Aplicar uma divisão de "factos misturados" a um conjunto de amostras — determinista, gratuita, nada é guardado; reencaminhe as amostras devolvidas para a geração do esquema |
analyze_sample | Ferramenta MCP — o mesmo relatório de amostra sem estado, com ambas as verificações, a partir do Claude ou de qualquer cliente MCP |
analyze_schema | Ferramenta MCP — anotar um esquema guardado; combine com update_schema para aplicar uma descrição sugerida ou uma mudança de nome |
As deteções são devolvidas com um kind (ambiguous ou unmappable), um level, uma nota, a lista de interpretations e a correção sugerida. Num esquema guardado, ficam armazenadas em cada propriedade como ambiguity; a geração de amostras devolve-as sob ambiguity_report.
Consulte a Referência da API e o guia do MCP Server para autenticação e o catálogo completo de ferramentas.