Individui le proprietà dello schema che potrebbero porre più di una domanda: veda affiancate le letture in competizione e fissi ogni proprietà a un unico significato prima che i dati vengano raccolti.
Entity Enricher tratta gli LLM come basi di conoscenza interrogabili, e il nome di una proprietà è la domanda che lei pone. Quando il nome ammette più letture, ogni modello ne sceglie una in silenzio: così size riferito a un'azienda torna come numero di dipendenti da un modello, come fatturato da un altro e come superficie da un terzo. I modelli non erano in disaccordo su un fatto: hanno risposto a domande diverse, e la sua colonna contiene ora un misto di risposte che nessun consumatore a valle è in grado di distinguere.
Fissare il significato è ciò che rende un arricchimento confrontabile tra modelli e stabile nel tempo. Inoltre semplifica tutto ciò che ne dipende a valle: la fusione multi-modello smette di rilevare conflitti che in realtà sono due domande distinte, e i confronti di benchmark smettono di penalizzare i modelli per aver interpretato lo schema diversamente dal riferimento.
Un dato che semplicemente cambia nel tempo non è un'ambiguità. Uno schema è un contratto duraturo: una proprietà chiamata semplicemente ceo indica “il CEO al momento dell'arricchimento” e rieseguire lo schema il prossimo anno dovrebbe restituire il nuovo. Il controllo non propone mai di fissare una data nel nome: comprometterebbe ogni esecuzione futura.
L'intero controllo si riduce a una sola domanda, posta per ogni proprietà: leggendone il nome nel contesto dell'oggetto padre, quante cose distinte potrebbe chiedere? Il conteggio è il verdetto.
| Interpretazioni | Verdetto | Che cosa significa |
|---|---|---|
| Esattamente una | Cancella | Tutti i modelli cercano la stessa cosa. Nessun badge, nulla da correggere. |
| Due o più | Ambigua | Ogni modello si assesta sulla propria lettura, così la colonna mescola silenziosamente risposte a domande diverse. Il controllo individua le letture in competizione e propone una formulazione che ne conserva una sola. |
| Nessuno | Non mappabile | Il nome non designa nulla che l'oggetto padre possieda, quindi il modello non può cercare un valore: lo inventa. Le interpretazioni elencate sono quelle che l'analizzatore ha preso in considerazione e scartato; il rimedio è una rinomina o una rimozione: nessuna descrizione può dare a un'entità una proprietà che non ha. |
Una proprietà che designa una cosa sola può comunque essere segnalata quando il valore non è inquadrato: si capisce che cosa viene chiesto, ma non in quali termini verrà restituito. Ecco le forme ricorrenti:
| Sotto-caso | Esempio | Che cosa resta aperto |
|---|---|---|
| Referente poco chiaro | Companysize | Il nome rimanda a più fatti distinti che il padre possiede davvero — organico, ricavi, superficie. Nulla nel nome permette di scegliere. |
| Misura o unità poco chiara | Companyannual_revenue | Un solo dato, ma senza valuta, senza periodo e senza distinzione lordo/netto: una risposta plausibile può sbagliare di tre ordini di grandezza ed essere comunque "corretta". |
| Scala o direzione poco chiara | Supplierrisk_score | Nessun intervallo dichiarato e nessuna polarità dichiarata: 0–10 o 0–100? E un numero alto indica maggiore sicurezza o maggiore rischio? Due modelli possono invertirsi a vicenda. |
| Ambito o confine poco chiaro | Companyemployees | Quale sottoinsieme, quale livello di aggregazione, quale prospettiva — l'intero gruppo o questa sede, numero di persone o equivalenti a tempo pieno, collaboratori esterni inclusi o esclusi. |
| Non mappabile | Authorrelease_year | Un autore non ha un anno di uscita: ce l'hanno i suoi libri. Il modello non può reperire questo dato, quindi lo inventa. Rinomini la proprietà con qualcosa che appartenga all'oggetto padre, oppure la sposti sull'oggetto che la possiede. |
Le proprietà testuali — description, summary, notes, bio — non vengono mai segnalate. La loro formulazione varia ovviamente da un modello all'altro, ma la domanda posta è perfettamente chiara, ed è tutto ciò che questo controllo valuta. L'ambiguità riguarda la domanda, mai quanto le risposte si somiglino.
Un verdetto da solo (“non è chiaro”) lascia indovinare che cosa avesse in mente l'analizzatore. Per questo ogni rilievo riporta le proprie interpretations: da due a quattro letture brevi e distinte che la proprietà ammette, a partire dalla più probabile. Quell'elenco è il rilievo: se l'analizzatore non riesce a indicare due letture, il rilievo viene scartato come rumore anziché essere mostrato.
annual_revenue su un'AziendaAccanto a esse compare una descrizione suggerita che ne conserva esattamente una: qui, “fatturato totale di gruppo in USD per l'ultimo esercizio fiscale chiuso, al lordo dei resi”. Applicarla non costa nulla: la descrizione raggiunge il modello di arricchimento esattamente come il nome, ma la proprietà mantiene il proprio nome, quindi nessun contratto dati viene modificato. Quando è il nome stesso a trarre in inganno, il rilievo riporta anche i nomi suggeriti.
Vedere le interpretazioni esplicitate di solito chiarisce la proprietà più in fretta di qualsiasi spiegazione: si riconosce quella che si intendeva, e le altre sono quelle che si stavano ricevendo senza accorgersene.
Dopo la generazione di un campione, l'analizzatore ne esamina i nomi delle proprietà e restituisce un report di ambiguità. Le ridenominazioni non ambigue vengono applicate automaticamente alle chiavi inventate dall'AI (mai ai campi nominati da lei), così il campione che le viene sottoposto risulta già più leggibile. Vengono inoltre segnalate le proprietà troppo specializzate — tratti filtrati dall'istanza di esempio che si adattano solo a un sottotipo (le medaglie di un atleta su una Person generica) — con la proposta di un tipo di entità più circoscritto. Il controllo di ambito dell'identità viene eseguito qui come chiamata a sé, subito dopo: definisce la forma degli elementi correlati prima che lei esamini il campione. I campioni basati su documenti allegati vengono esclusi: i loro valori provengono dal documento di origine, non dalla memoria del modello.
Una volta salvato uno schema generato, un passaggio successivo annota ogni proprietà con il relativo verdetto di ambiguità e suggerisce rinomine per quelle ancora aperte. A quel punto i punti di relazione sono già annotati — la generazione ne valuta autonomamente l'ambito di identità, come uno dei propri passaggi — quindi il passaggio successivo riguarda solo i nomi delle proprietà. Si tratta di un passaggio best-effort: se fallisce, la generazione non ne risente.
Il pulsante Ricontrolla esegue entrambi i controlli — nomi delle proprietà e punti di relazione — come due chiamate parallele. È l'unico punto in cui viene suggerita una riscrittura della descrizione anziché una rinomina. Analizza solo ciò che non è ancora annotato e passa a una rianalisi completa quando tutto è annotato.
Il JSON di esempio incollato per la creazione di uno schema può essere analizzato senza stato: si ottiene un report dei nomi di proprietà ambigui o non mappabili e degli elementi correlati che mescolano fatti dell'entità e fatti dell'abbinamento, senza che nulla venga modificato.
Lo stesso rilievo suggerisce una rinomina in un punto e una descrizione in un altro: vale la pena sapere perché. Al momento della generazione la descrizione non esiste ancora in modo indipendente — viene scritta a partire dal nome, quindi non può che ripeterne l'ambiguità. Il nome è l'unica cosa che si possa correggere, e nulla ne dipende ancora. Per questo sia la generazione dei campioni sia il passaggio successivo alla generazione dello schema propongono rinomine.
Una volta che lo schema è attivo, rinominare una proprietà sposta colonne, interrompe query e ri-indicizza le tabelle sincronizzate, mentre una descrizione più precisa raggiunge il modello in modo altrettanto diretto senza cambiare nient'altro. La regola è dunque semplice: finché nulla dipende dallo schema, rinominare; una volta attivo, fissare la descrizione — tenendo la rinomina in riserva per i casi in cui il problema sia il nome stesso.
Il controllo è puramente consultivo. Nulla analizza gli schemi salvati in background: viene eseguito alla generazione e quando si preme Ricontrolla. Non blocca mai la generazione, non rifiuta mai un arricchimento e le sue annotazioni vengono rimosse da ogni prompt inviato ai modelli di arricchimento: informa l'utente, non l'AI.
Le proprietà segnalate mostrano un badge “ambiguous” nel Workflow Editor: ambra quando le letture coincidono in larga parte e differiscono solo nei casi limite, rosso quando le letture in competizione produrrebbero dati sostanzialmente diversi. Le proprietà giudicate chiare non presentano alcun badge. Passando il puntatore sul badge compaiono la nota dell'analizzatore, le letture in competizione individuate e la descrizione o i nomi suggeriti: la valutazione e la correzione si trovano così nello stesso tooltip.
Il verdetto viene emesso sul nome e sulla descrizione di una proprietà considerati insieme: rinominare una proprietà o modificarne la descrizione ne elimina l'annotazione. L'editor evidenzia queste proprietà come non più aggiornate e propone un nuovo controllo, che analizza soltanto ciò che manca. È esattamente ciò che serve dopo aver applicato una correzione suggerita: il nuovo controllo conferma se la nuova formulazione fissa davvero un'unica lettura.
L'ambito di identità è un secondo controllo, eseguito come chiamata al modello a sé stante insieme alla passata sull'ambiguità e riportato insieme a essa. Esamina ogni punto di relazione — gli elementi di un array correlato e gli oggetti annidati: quando uno di essi mescola dati sull'entità correlata in sé (il suo nome, il suo Paese) con dati sull'abbinamento (un ruolo ricoperto per questo padre, una designazione specifica del padre), entrambi condividono un'unica identità — e i nuovi arricchimenti sovrascrivono i dati dell'abbinamento tra i vari padri. Questi punti riportano un chip “dati misti” di colore ambra il cui tooltip mostra la struttura consigliata: i campi propri dell'entità annidati in un sotto-oggetto e i campi dell'abbinamento mantenuti sull'elemento. Se l'elemento contiene già un sotto-oggetto di questo tipo, la correzione è più contenuta: i campi fuori posto vengono spostati in quello già presente.
La divisione viene applicata durante la generazione del campione, prima che lei approvi il campione: la struttura viene definita sul primo campione, ogni punto ristrutturato è elencato negli avvisi di generazione e gli altri campioni del batch vengono generati in base alla struttura definita. Perciò gli schemi generati da un campione nuovo risultano di norma puliti. I campioni basati su documenti allegati restano come implicato dalle rispettive fonti e ricevono invece il chip.
La generazione dello schema non ristruttura mai il campione approvato: valuta gli stessi punti e riporta ciò che rileva. Su uno schema esistente o scritto a mano la correzione risiede quindi nel chip, che propone una divisione con un clic in grado di ristrutturare il campione e rigenerare lo schema a partire da esso. La struttura è il contratto: la si modifica rigenerandola da un nuovo campione, mai correggendola sul posto. Un punto che sceglie di non dividere continua a funzionare — mantiene semplicemente un'unica identità condivisa, e il chip. Il chip scompare da solo quando cambia l'insieme dei campi dell'elemento.
Il controllo può essere disattivato per singolo schema dal menu di overflow dell'Editor del workflow. Quando è disattivato, il passaggio post-generazione viene saltato, i chip, il pulsante Ricontrolla e gli avvisi di annotazioni obsolete restano nascosti e gli endpoint di analisi rispondono con un errore ambiguity_check_disabled. Le annotazioni esistenti vengono conservate (solo nascoste) e riattivando il controllo su uno schema mai analizzato l'analisi viene eseguita automaticamente.
Ogni schema generato parte con il controllo attivo, inclusi gli schemi generati da documenti allegati. L'ambiguità è una proprietà del modo in cui lo schema è formulato, non della provenienza dei valori di una singola esecuzione: il documento ha fissato quei valori una volta sola, mentre lo schema continua a essere riutilizzato su entità che non copriva affatto. Ciò che il documento cambia davvero è il passaggio di esempio: i nomi delle sue proprietà provengono dal vocabolario del documento di origine, quindi non vengono mai rinominati nel codice, ed è lo schema costruito a partire da essi a portare il controllo.
“Il fatturato annuo dell'azienda” non aggiunge alcuna informazione che il nome non contenesse già: l'analizzatore tratta quindi una descrizione di questo tipo come se fosse assente e valuta il solo nome. Una descrizione si giustifica quando indica l'unità, il periodo, la scala o il perimetro.
Le note dell'analizzatore e le interpretazioni sono redatte nella lingua della sua interfaccia: un utente francese vede letture in francese, un utente giapponese in giapponese. I nomi di proprietà suggeriti restano in inglese, in linea con le convenzioni di denominazione degli schemi.
Ogni analisi è una vera chiamata al modello (poco costosa): due chiamate, eseguite in parallelo, quando ci sono anche punti di relazione di cui definire l'ambito. Ciascuna viene registrata come prompt a sé sul record, con il tipo ambiguity_analysis, e scalata dai crediti come qualsiasi altro utilizzo dell'AI. I controlli incrementali fanno pagare solo le proprietà e i punti effettivamente analizzati.
La generazione dei campioni e degli schemi è essa stessa istruita a nominare una sola cosa per proprietà e a scrivere descrizioni che indichino l'unità, la scala e il limite — e, per gli elenchi discutibili, un limite massimo nella descrizione anziché un conteggio forzato nel nome. Per questo la maggior parte degli schemi risulta pulita e l'analizzatore deve intercettare solo i casi residui.
Il controllo è disponibile a livello programmatico:
| Superficiale | Descrizione |
|---|---|
POST /api/schema/analyze-sample | Analizza il JSON di campione incollato — entrambi i controlli in parallelo dietro un'unica richiesta, report stateless, nulla viene modificato |
POST /api/schema/saved/{id}/analyze | Analizza uno schema salvato e scrive le annotazioni di entrambi i controlli — incrementale per impostazione predefinita, force=true rianalizza tutto |
POST /api/schema/scoping-split | Applica una divisione "fatti misti" a un insieme di campioni — deterministica, gratuita, nulla viene salvato; reimmetta i campioni restituiti nella generazione dello schema |
analyze_sample | Strumento MCP — lo stesso report stateless sul campione, entrambi i controlli, da Claude o da qualsiasi client MCP |
analyze_schema | Strumento MCP — annota uno schema salvato; da combinare con update_schema per applicare una descrizione suggerita o una rinomina |
I rilievi vengono restituiti con un kind (ambiguous o unmappable), un level, una nota, l'elenco interpretations e la correzione suggerita. Su uno schema salvato sono memorizzati su ciascuna proprietà come ambiguity; la generazione del campione li restituisce sotto ambiguity_report.
Consultate il Riferimento API e la guida al server MCP per l'autenticazione e il catalogo completo degli strumenti.