AI Gate39 · Documentazione interna

RAG Service: come funziona

Come risponde alle domande. Il motore che risponde in linguaggio naturale ancorando ogni risposta alla conoscenza di Gate39 — combinando tre livelli: il testo grezzo dei documenti, il wiki curato e, in prospettiva, i dati gestionali.

RAG sta per Retrieval-Augmented Generation: prima il servizio recupera i pezzi di conoscenza pertinenti alla domanda, poi li passa a un modello linguistico (LLM) che genera la risposta basandosi su quei pezzi, non sulla sua memoria generica.

La conseguenza pratica è la più importante da capire: la conoscenza vive fuori dal modello. Le risposte sono verificabili (si sa da quali fonti vengono) e aggiornabili (cambi i documenti o il wiki, cambiano le risposte) — senza ri-addestrare nulla.

Architettura in breve

Le fonti (documenti grezzi e wiki curato) confluiscono in un solo indice. Una domanda viene instradata — testo o numeri — recuperata da quell'indice o interrogata sullo store analitico, e trasformata in risposta dall'LLM. Due modalità: sincrona (immediata) e analisi approfondita (un agente, per i casi complessi).

Ingestione

Documentidocx/pdf · default/faq/llama

Wiki curato

→

Indice unicogrezzo + curato

Query

Domanda

→

Routertesto o numeri?

→

Filtro facetopzionale, salvo i ruoli

→

Retrievaldall'indice unico

→

Contesto

→

LLM

→

Risposta

Store analitico — query di catalogo

⇢

Contesto

Grezzo e curato in un solo indice; il ramo numerico interroga lo store analitico (query di catalogo); il filtro facet (tratteggiato) è opzionale — tranne dove delimita ciò che un ruolo può vedere, e lì è obbligatorio.

I tre livelli di conoscenza

La stessa domanda può richiedere tipi di conoscenza diversi. Il servizio li tiene separati ma cooperanti.

1 Embeddings grezzi In produzione

Il verbatim — il testo dei documenti, così com'è

Cos'è: I documenti aziendali (analisi di mercato, contesti, domande — in docx/pdf) spezzati in frammenti (“chunk”) e trasformati in vettori numerici (“embedding”) che ne catturano il significato.
Come si cerca: La domanda viene trasformata nello stesso spazio vettoriale; il servizio trova i chunk semanticamente più vicini e li usa come contesto.
A cosa serve: L'ancoraggio ai fatti come sono scritti nella fonte. È la verità grezza, non interpretata.

2 LLM-wiki curato In produzione

La sintesi — conoscenza strutturata da una persona

Cos'è: Un wiki in markdown (repo gate39-knowledge) in cui pagine curate sintetizzano e organizzano la conoscenza di un dominio — per esempio una pagina per ogni mercato vinicolo. Le pagine non duplicano i documenti: li riferiscono.
Come entra: Un processo di sync indicizza le pagine wiki negli stessi embeddings del livello 1, sullo stesso canale tematico. Da lì wiki e grezzo competono insieme per pertinenza.
Il bilanciamento: Le sintesi curate tendono a vincere (sono dense e mirate), ma una regola di “pavimento” garantisce sempre alcuni frammenti grezzi nel risultato: il verbatim non sparisce mai.
Aggiornamento: Si cura il wiki → si pubblica su GitLab → il servizio si riallinea da solo ogni giorno (e a mano per i carichi grossi).

3 SQL gestionali In produzione

I numeri — i dati esatti dai gestionali

Perché serve: Per le domande numeriche precise (“quanti progetti attivi?”, “totale speso per mercato?”, “residuo di budget del progetto X?”) il testo non basta e può essere impreciso — il retrieval semantico non sa contare né sommare: serve interrogare i dati gestionali.
Cos'è: Uno store analitico separato: una copia di sola lettura del database gestionale (GePO), aggiornata ogni notte. L'app non tocca mai il gestionale vero; interroga la copia, e solo attraverso viste che incapsulano le definizioni di business (cos'è un progetto “attivo”, cosa vuol dire “speso impegnato”).
Come funziona: Il modello riconosce la domanda numerica e chiama una query già pronta e testata scelta da un catalogo (function calling): estrae solo i parametri, non scrive SQL a mano. Ottiene il dato esatto e la risposta cita la query usata e la data dei dati. Se nessuna query del catalogo risponde, lo dichiara invece di inventare.
Stato: In produzione. Consumatore attuale è il playground interno; l'esposizione a GePO e ad altri client è il passo successivo.

Come entra un documento

Non tutto ciò che arriva diventa conoscenza interrogabile: prima si decide come un documento entra. La scelta segue una piccola tassonomia, con l'obiettivo di non versare rumore nell'indice né servire due verità in conflitto.

SKIP Non è conoscenza

Modulistica, ricevute, email di trasmissione: non entrano affatto.

CURATELA Cambia o contraddice il wiki

Passa dalla curatela umana (livello 2), non dal grezzo, così il sistema non serve una risposta grezza in conflitto con la sintesi curata.

GREZZO Entra nell'indice così com'è (livello 1)

Con una strategy di chunking scelta in base alla forma del file:

default prosa e tabelle: il testo è impacchettato in frammenti di dimensione sensata (né titoli-esca da una riga, né muri di testo); le tabelle non vengono mai spezzate.
faq documenti a domande e risposte: un frammento per coppia Domanda–Risposta, che non si spezza a metà nemmeno se attraversa più pagine.
llama PDF ostici (tabelle complesse): estrattore rinforzato.

La strategy si sceglie nel form di caricamento, guidata dall'estensione del file. Prima di indicizzare, l'estrazione dei PDF viene ripulita dal rumore ricorrente — timbri di protocollo, carta intestata, header/footer di pagina — che altrimenti finirebbe in ogni frammento.

Il collo di bottiglia non è tecnico. Il ramo CURATELA regge finché chi cura conosce la materia; sui temi che non padroneggia interviene il questionario per l'esperto di dominio: un file con le domande di merito rimaste aperte, ognuna già corredata della formulazione proposta — all'esperto si chiede di rivedere, non di redigere. La curatela non si ferma ad aspettarlo: la pagina entra comunque col suo dubbio dichiarato, che arriva fino alle risposte. Al ritorno è il grado di sicurezza dell'esperto a decidere se quel dubbio cade, si precisa o resta aperto. L'approvazione della modifica resta del curatore: gli agenti non pubblicano nulla da soli.

Come cooperano: il percorso di una domanda

Quando arriva una domanda, il router semantico capisce di che tipo è e sceglie il canale giusto (v. sezione dedicata sotto). I pezzi recuperati diventano il contesto passato all'LLM, che formula la risposta ancorata a quel contesto.

Domandain linguaggio naturale

→

Router semanticoclassifica e sceglie il canale

→

Filtro facetrestringe i documenti a monte (opzionale, salvo i ruoli)

→

Retrievalpool semantico: grezzo + wiki, o query dello store per i numeri

→

Contestoi frammenti più pertinenti

→

LLMgenera la risposta

→

Rispostaancorata alle fonti

Domanda analitica o concettuale → attinge al pool semantico (livelli 1 + 2). Domanda numerica → interroga il livello 3 (store analitico, query di catalogo). I livelli non si escludono: concorrono alla stessa risposta.

Due modi di rispondere — sincrono e analisi approfondita

Non tutte le domande hanno lo stesso peso. Il servizio offre due modalità, complementari, non alternative da indovinare.

Sincrona In produzione

Immediata — la risposta arriva subito

Secondi, costo di centesimi. È il percorso descritto finora: instrada, recupera i frammenti pertinenti (o interroga lo store per una domanda numerica) e genera la risposta in un colpo solo. Copre la stragrande maggioranza dei casi.

Analisi approfondita In produzione

Un agente — lavora qualche minuto sui casi complessi

Per un brief, una sintesi cross-mercato, un confronto tra fonti. Non fa una singola ricerca: naviga il wiki, incrocia più pagine, interroga lo store, ragiona per passi e cita le fonti. Costa di più (qualche decina di centesimi a job) e si attiva con un click consapevole, non di default.

La differenza non è “più intelligente vs meno intelligente”, ma profondità vs immediatezza: un gate interno ha misurato che l'agente vince su copertura e citazioni nelle analisi, il sincrono è pari o migliore (e più prevedibile) sui lookup di precisione. Per sicurezza l'agente lavora in un recinto: può leggere solo il wiki curato e gli strumenti di ricerca del servizio, mai file arbitrari del sistema.

Come una domanda trova il suo canale — il router semantico

L'indice non è un unico calderone: è partizionato in canali tematici (analisi di mercato, normativa dei bandi…). Prima di cercare, il servizio deve decidere in quale canale guardare.

Fino a poco fa lo decideva un elenco di parole chiave: se la domanda conteneva “mercato” andava sulle analisi di mercato, “bando” sulla normativa. Fragile per costruzione: bastava un fraseggio naturale (“Posso proporre Anguilla per la campagna 2026/2027?”) o un semplice plurale (“mercati” non contiene “mercato”) per non attivare nessun canale — e la risposta diventava “non ho trovato nulla” anche quando la conoscenza c'era.

Robusto al fraseggio. Plurali, sinonimi e giri di frase non lo ingannano: conta il significato, non le parole esatte.
Degrada allargando, non svuotando. Se la classificazione è incerta o il canale indicato non esiste, la ricerca si estende a tutto l'indice invece di tornare a mani vuote — mai più “zero evidenze” per un errore di instradamento.

Gli esempi per canale si curano dall'admin come il resto della configurazione: aggiungere un canale o affinarne il riconoscimento non richiede codice.

Un esempio concreto

Qual è il posizionamento del vino italiano nel mercato del Giappone?

Nel canale analisi_mercato, il servizio recupera i 5 frammenti più pertinenti:

wiki Sintesi curata del mercato Giappone mercato-vino-giappone
wiki Sintesi curata del mercato Giappone mercato-vino-giappone
wiki Sintesi curata del mercato Giappone mercato-vino-giappone
grezzo Documento sorgente originale CONTESTO_JPN.docx
grezzo Documento sorgente originale Giappone-contesto2024.docx

Le sintesi curate (wiki) risultano le più pertinenti e guidano la struttura della risposta; i due frammenti grezzi, garantiti dal “pavimento”, mantengono l'ancoraggio ai dati originali. L'LLM unisce le due cose in una risposta coerente e verificabile.

Restringere prima di cercare — il filtro facet

La ricerca semantica trova i frammenti più pertinenti in un canale. Ma a volte la pertinenza non basta: se il second brain contiene i bandi di venti regioni, una domanda sulla Lombardia non dovrebbe nemmeno vedere i bandi del Veneto. Deve però continuare a vedere il bando nazionale, che vale ovunque: ed è la ragione della regola qui sotto.

È un meccanismo generico per il second brain multi-tema, ma non universale: le facet hanno un registro, cioè un vocabolario condiviso fra chi carica i documenti e chi interroga. Serve a questo — se le due parti scrivessero Toscana e toscana, il filtro non troverebbe mai niente e nessuno se ne accorgerebbe. Attributi come l'annualità restano invece campi ordinari del documento: il loro elenco è aperto e cresce ogni anno, mentre un registro esiste per vocabolari chiusi.

Oggi il filtro è vivo: 81 documenti portano la loro regione, e le pagine del manuale utente portano il ruolo di chi può leggerle. Fino a poco fa era descritto come “predisposto ma dormiente”, ed era vero — per una ragione diversa da quella che sembrava: i dati c'erano, ma la facet veniva scartata da un elenco di parametri ammessi prima ancora di raggiungere la ricerca. Il payload la mostrava, il retrieval non la applicava. Ha resistito mesi perché tutti i controlli automatici partivano a valle del tratto rotto.

Il limite, dichiarato: il servizio non può verificare il ruolo di chi chiede — conosce il sistema che lo interroga, non la persona. La guardia impedisce di dimenticare il ruolo, non di dichiararne uno falso: chi integra il servizio deve passarlo dalla sessione, mai da ciò che l'utente può modificare.

La questione del dubbio Risolta in parte · luglio 2026

Quando la conoscenza sa di non sapere

Il wiki curato non contiene solo sintesi: contiene dubbi. Quando chi cura una pagina scopre che un dato non torna — un numero gonfiato da un'anomalia statistica, due elenchi normativi che si contraddicono, un mercato di ammissibilità incerta — non lo cancella e non lo aggiusta di nascosto: lo dichiara, con un marcatore ⚠.

Questi dubbi sono la cosa più preziosa che la curatela produce — e l'unica che i documenti grezzi non contengono: nascono dal confronto fra fonti, che è lavoro umano.

Il problema

Il servizio recupera frammenti, non pagine intere. E i dubbi stavano in fondo alla pagina, in una sezione dedicata, mentre l'affermazione dubbia compariva altrove. Veniva quindi recuperato il frammento con l'affermazione, non quello col dubbio: il sistema rispondeva con piena sicurezza un dato che la pagina stessa dichiarava inaffidabile.

Prima

“Il mercato indiano cresce del +53% medio annuo: domanda in forte espansione.”

Il dubbio era scritto nella pagina, in fondo: il +53% è gonfiato da un'anomalia del 2023, il valore realistico è ~+3,5%. Non è mai arrivato.

Adesso

“Le evidenze non consentono di fissare un unico tasso certo… userei +3,5/+5%, non il +53%.”

Stessa domanda, stessi documenti. Il dubbio viaggia col dato e il modello è tenuto a riportarlo.

Come l'abbiamo risolto (in parte)

Il dubbio viaggia col frammento. Ogni frammento di una pagina che contiene un ⚠ ora se lo porta dietro, qualunque frammento venga pescato. Senza inquinare la ricerca: il dubbio è aggiunto al testo che il modello legge, non a quello con cui il frammento viene cercato.
Al modello viene detto di non smussare. Quando il servizio ha fatto una ricerca documentale aggiunge istruzioni che chi lo interroga non può rimuovere: riporta le avvertenze senza attenuarle e, se non hai trovato nulla, dichiaralo invece di rispondere a memoria.

Nella prova reale il committente chiedeva esplicitamente uno stile “sintetico e assertivo”. Il pavimento ha vinto lo stesso.

Perché conta più di quanto sembri

Un dubbio che arriva alla risposta trasforma il non-sapere in informazione. Il sistema degrada con onestà invece che in silenzio: restituisce il problema invece di una soluzione errata. Ed è la proprietà che rende sicuro curare un dominio che non si padroneggia: se un dubbio resta irrisolto, non svanisce — viaggia fino a chi legge.

Cosa resta aperto

Il meccanismo è ottuso. Attacca tutti i dubbi di una pagina a tutti i suoi frammenti, anche a quelli che non c'entrano. Garantisce che il dubbio non si perda, non che sia mirato. Scriverlo accanto all'affermazione resta il modo di renderlo preciso — ma ora è mestiere, non emergenza.
Due modi silenziosi di rispondere a vuoto. Se il prompt supera i limiti le evidenze vengono scartate; se la ricerca fallisce il flusso prosegue comunque. Il modello ora lo dichiara, ma il sistema continua a farlo senza segnalarlo.
Il legame fra sintesi e documento non è verificato. È una stringa: se il documento viene aggiornato, nulla si accorge che la sintesi è invecchiata.

Glossario minimo

Chunk: Un frammento di documento (qualche paragrafo). L'unità che il servizio recupera.
Embedding: La rappresentazione numerica del significato di un testo, che permette la ricerca “per somiglianza” invece che per parole esatte.
Retrieval: La fase di recupero: trovare i frammenti pertinenti prima di generare la risposta.
Grezzo vs curato: Grezzo = testo verbatim dei documenti. Curato = sintesi scritta a mano nel wiki. Convivono nello stesso indice.
Pavimento: La regola che garantisce sempre un minimo di frammenti grezzi nel risultato, così il verbatim non viene mai soppresso dalle sintesi.
Canale (tipo documento): L'ambito tematico di una domanda (es. analisi_mercato): filtra dove cercare. Lo sceglie il router semantico.
Router semantico: Il classificatore che sceglie il canale confrontando (per embedding) la domanda con domande-esempio curate per canale; sotto la soglia di confidenza cerca su tutti i canali.
Strategy di chunking: Il modo in cui un documento grezzo viene spezzato: default (prosa+tabelle), faq (una coppia domanda-risposta per frammento), llama (PDF ostici).
Facet: Un attributo dichiarato di un documento (es. regione) usato per restringere la ricerca a monte, in modo deterministico.
Dubbio (⚠): Un'avvertenza dichiarata in una pagina curata: dato contestato, contraddizione fra fonti, ammissibilità incerta. Viaggia con ogni frammento della sua pagina.
Pavimento di onestà: Le istruzioni che il servizio aggiunge da sé quando ha fatto una ricerca: riporta i dubbi senza attenuarli, e dichiara quando non hai trovato nulla. Chi interroga non può rimuoverle. Vale anche per i numeri: usa solo i dati dello store, cita la query e la data, non inventa.
Store analitico: Una copia di sola lettura del database gestionale (GePO), aggiornata ogni notte, interrogata solo tramite viste e query pre-scritte. È la fonte dei numeri (livello 3), separata dal gestionale vero.
Catalogo di query: L'insieme delle query numeriche già pronte e testate (spesa per mercato, residuo di budget, progetti attivi…). Il modello sceglie quale usare e ne estrae i parametri; non scrive SQL a mano.
Freshness: La data a cui i dati dello store si riferiscono (l'ultimo aggiornamento notturno). Ogni risposta numerica la cita.
Analisi approfondita (agente): La modalità non-immediata: un agente che lavora qualche minuto su una richiesta complessa, naviga il wiki, incrocia fonti e interroga lo store, e cita le fonti.

In una frase: il RAG Service risponde recuperando la conoscenza giusta — verbatim grezzo, sintesi curata e numeri esatti dallo store — e lasciando che l'LLM la trasformi in risposta, subito o con un'analisi approfondita. La conoscenza resta fuori dal modello: aggiornabile, verificabile e onesta sui propri dubbi.

Le foto degli ordini, lette da un modello. Il servizio guarda le fotografie allegate a un ordine e dice cosa ci vede: quante persone, quante bottiglie, se c'è l'emblema europeo, se i prezzi esposti riguardano il vino. Non decide se la documentazione è a posto — quello resta a GePO e a chi rivede.

Su ogni foto girano due analisi separate, e capirlo evita quasi tutti i malintesi.

La prima guarda i dati nascosti nel file — data di scatto e coordinate GPS che la fotocamera scrive dentro l'immagine — e risponde a dove e quando. La seconda guarda i pixel, cioè la fotografia vera e propria, e risponde a cosa si vede.

La differenza non è solo di argomento, ed è quella che conta quando si legge un risultato. La prima misura: la data c'è o non c'è, cade nel periodo oppure no, e la stessa foto darà sempre la stessa risposta. La seconda interpreta: è la lettura di un modello, può sbagliare, può dire «non lo so», e sulla stessa fotografia due letture possono differire di poco. Sono anche due parti di programma diverse, che si guastano in modi diversi.

Sono indipendenti: una foto può avere data e luogo perfetti e non mostrare nulla di utile, oppure mostrare esattamente l'attività finanziata ma essere arrivata senza metadati perché è passata da WhatsApp. Quando qualcosa non torna, la prima domanda è sempre: quale dei due piani?

Questa pagina parla del secondo. Il piano dei metadati è in produzione dal 2025; quello sui pixel è più recente ed è in collaudo.

Cosa guarda, esattamente

I criteri sono dieci, approvati dai responsabili OCM. Non valgono tutti per ogni attività: una fiera e uno scaffale di supermercato pongono domande diverse, e ciascun tipo di attività ha il suo elenco.

L'elenco mescola i due piani, ed è normale: è fatto per descrivere cosa si controlla, non come. I primi tre appartengono alla parte che misura, dal quarto in poi a quella che interpreta. Sotto, ogni criterio dice a quale dei due appartiene.

1 · Data e luogo misura: Se lo scatto cade nel periodo dell'ordine e nel mercato dell'ordine. Legge i dati nascosti nel file, non la fotografia.
2 · Numero di foto misura + interpreta: Quanti scatti servono, in rapporto al periodo, al valore dell'ordine o ai punti vendita coinvolti. Contare gli scatti sarebbe una misura, e non è ancora attivo; quello che oggi funziona è il riconoscimento di quanti punti vendita distinti compaiono in un gruppo di foto, che è una lettura del modello.
3 · Controllo antifrode misura: Foto ricaricate più volte con i dati modificati. Non ancora attivo.
4 · Ambiente interpreta: Se lo scatto è al chiuso o all'aperto — e ammette di non saperlo, quando gli indizi non bastano.
5 · Persone interpreta: Se c'è qualcuno e quante persone si vedono. Sul gruppo di foto, anche il totale complessivo.
6 · Bottiglie e denominazioni interpreta: Se ci sono bottiglie e quante; se sono stappate; cosa si legge sulle etichette; e soprattutto se almeno una è attribuibile a un vino promosso dall'azienda dell'ordine.
7 · Prezzi interpreta: Se è esposto un prezzo, quali sono, e se riguardano il vino o altri prodotti sullo stesso scaffale.
8 · Cibo interpreta: Se sono visibili pietanze: piatti serviti, buffet, finger food. Vale per le attività dove il cibo fa parte dell'iniziativa.
9 · Loghi ed emblemi interpreta: L'emblema dell'Unione Europea — il cerchio di dodici stelle su fondo blu — e i marchi aziendali su allestimenti, insegne e materiali. Anche il testo che vi si legge.
10 · Testi e altri marchi interpreta: Le scritte su cartelli ed espositori, nella lingua in cui appaiono; le parole di sconto e promozione; i marchi diversi dal vino promosso.

Ogni criterio produce un fatto, non un giudizio: «tre persone», «prezzo visibile», «etichetta leggibile: Brunello di Montalcino». Nessuno di questi fatti dice «ammesso» o «respinto».

Come sa quale vino cercare

Il criterio più delicato è il sesto: riconoscere il vino promosso, non una bottiglia qualunque. Al momento dell'analisi il sistema prende dall'ordine l'elenco delle denominazioni promosse dall'azienda su quel mercato, e lo mette davanti al modello insieme alla foto.

Il giudizio si fa su denominazione e produttore insieme, perché sulla bottiglia i due si leggono in modo diverso: il nome del produttore è quasi sempre visibile, la denominazione spesso no — è scritta piccola, a volte solo sulla fascetta. Ne segue una regola che vale la pena conoscere:

si legge la denominazione promossa → sì;
si legge solo il produttore promosso, e nessun'altra denominazione in campo → sì;
si legge il produttore promosso ma accanto c'è una denominazione diversa → no: è un altro vino della stessa azienda;
non si legge niente di utile → non determinabile.

Se l'ordine non ha denominazioni promosse, la domanda non viene proprio posta: niente bersaglio, niente criterio, e in interfaccia quella riga non compare.

Alcune domande riguardano il gruppo, non la singola foto

Quando si carica un archivio di immagini, alcune domande non avrebbero senso su uno scatto solo:

le foto raccontano lo stesso evento, o sono un insieme scoordinato?
c'è almeno una foto d'insieme, o sono tutti dettagli ravvicinati?
quanti punti vendita distinti si riconoscono?

Sono una lettura a parte, fatta su tutte le immagini insieme e non sulla singola: riguardano il fascicolo, non lo scatto. Se una di queste risposte manca o non torna, non è colpa di una fotografia in particolare — e correggere una foto sola non la sistema.

È anche il motivo per cui una panoramica vale più di un dettaglio in più: senza, l'insieme resta muto su una domanda che gli viene posta.

«Non lo so» è una risposta

Ogni criterio può restare non determinabile, e non è un guasto: è la risposta corretta quando la foto non basta. Le bottiglie a scaffale sono troppe per contarle senza inventare; l'etichetta è sfocata; il prezzo si vede ma non si capisce a cosa si riferisca.

Un sistema che tirasse comunque un numero sarebbe peggiore, non migliore: chi rivede si fiderebbe di un dato inventato. Un campo vuoto si guarda; un campo sbagliato no.

Cosa puoi fare perché funzioni meglio

Come per le note spese, buona parte della qualità si decide prima del caricamento.

1Almeno una foto d'insieme per ogni ordine

Lo stand intero, la sala, lo scaffale nel suo contesto. I dettagli ravvicinati servono per le etichette, ma da soli non permettono di dire che l'attività c'è stata — ed è una domanda che il sistema pone davvero.

2JPEG, PNG o HEIC — non i formati grezzi

I file RAW e ProRAW dei telefoni (.dng) e le GIF vengono rifiutati, con la ragione scritta. Sull'iPhone il formato normale (HEIC) va benissimo: è il «RAW massima compatibilità» che non va.

3Trasferisci i file originali

Inoltrare le foto via chat o incollarle in un documento cancella i dati nascosti: il piano su data e luogo perde la sua materia prima. Il piano sui pixel continua a funzionare, ma metà dell'analisi sparisce.

4Etichette leggibili almeno in uno scatto

Il riconoscimento del vino promosso dipende da cosa si legge sulla bottiglia. Uno scatto ravvicinato su etichetta o fascetta, in un gruppo che per il resto racconta l'ambiente, vale più di dieci foto da lontano.

5Niente doppioni dello stesso scatto

La stessa fotografia caricata più volte non aggiunge prove e gonfia i totali del gruppo: le persone e le bottiglie vengono contate una volta per foto, quindi un duplicato le conta due volte.

Cosa può sbagliare, e come te ne accorgi

I conteggi: È l'errore più frequente. Persone e bottiglie vengono contate nell'inquadratura: in una corsia di supermercato o in una sala affollata il numero può discostarsi parecchio da quello che conteresti tu, che guardi i soggetti in primo piano.
Il testo letto in parte: Su una foto ricca di scritte il modello ne riporta le più evidenti, non tutte. L'assenza di una parola nell'elenco non prova che non ci fosse.
Lo stato delle bottiglie: Riconoscere una bottiglia stappata da una fotografia è difficile: se il tappo non si vede, il sistema tende a non pronunciarsi anche quando per una persona è evidente che si sta degustando.
I prezzi non attribuiti: Il sistema legge i prezzi ma può non sapere a quale prodotto appartengano, soprattutto in un lineare dove i cartellini sono di tutti.

In tutti questi casi il segnale è lo stesso: un valore che non torna con quello che vedi guardando la foto. La foto resta la fonte: il risultato dell'analisi è una lettura, e chi rivede ha sempre l'originale davanti.

Come lo sappiamo — la misura

Esiste un banco di prova: quaranta fotografie reali, annotate a mano una per una con quello che una persona ci vede, e tredici ordini di prova che le raggruppano come farebbe un caricamento vero. Il sistema le rilegge tutte e il risultato viene confrontato con l'annotazione.

Serve a due cose: sapere dove sbaglia — quali criteri, non «quanto è bravo in generale» — e accorgersi se una modifica peggiora qualcosa che prima funzionava.

Una precisazione onesta sul metodo: le annotazioni sono una lettura umana, non una verità assoluta. Quando sistema e annotazione divergono, a volte ha ragione il sistema, a volte l'annotazione, e a volte nessuno dei due perché la domanda era posta male. Distinguere i tre casi è parte del lavoro, ed è in corso.

Glossario minimo

Criterio: Una delle dieci cose che si possono chiedere a una foto. Approvati dai responsabili OCM; resta da stabilire quali valgono per quale attività.
Schema di analisi: L'elenco di criteri che vale per una famiglia di attività — fiere, eventi con cibo, esposizione in negozio. Dodici previsti, tre già scritti.
Denominazioni promosse: I vini che l'azienda dell'ordine promuove su quel mercato. Sono ciò che il sistema cerca nelle bottiglie fotografate.
Non determinabile: La risposta che il sistema dà quando la foto non basta a decidere. È prevista, ed è preferibile a un dato inventato.
Analisi d'insieme: La lettura fatta su tutte le foto di un ordine insieme, per le domande che sulla singola immagine non avrebbero senso.
Metadati: I dati che la fotocamera scrive dentro il file: data, ora, coordinate. Sono la materia prima del piano «dove e quando», e si perdono se la foto viene inoltrata o rielaborata.

Il servizio guarda le foto e riferisce cosa ci vede, criterio per criterio, ammettendo quando non è in grado di dirlo. Non stabilisce se la documentazione è sufficiente: le soglie e il verdetto restano al gestionale e a chi rivede. Le regole che diranno quali criteri valgono per quale attività sono l'ultimo pezzo mancante, e le sta definendo il gruppo OCM.

Dalle scansioni alle righe di spesa. Il servizio, nato specificamente per il gestionale GePO, legge le scansioni delle note spese — scontrini, ricevute, fatture — e ne ricava le righe: data, importo, valuta, città e natura della spesa. Chi rivede non ricopia più a mano: corregge.

Sembra un compito solo — «leggere gli scontrini» — ma sono due, e il difficile non è quello che ci si aspetta.

Leggere le parole stampate è il problema risolto. Un servizio specializzato restituisce il testo di una pagina con un'accuratezza fra il 93% e il 97%, e insieme al testo dice dove si trova ogni parola sul foglio. Capire dove finisce uno scontrino e comincia il prossimo è il problema vero: è lì che si gioca la qualità del risultato, ed è lì che il sistema ancora sbaglia.

Una conseguenza pratica, prima di tutto il resto: il servizio non decide se una spesa è ammissibile. Dice cosa c'è scritto sul documento e segnala quando qualcosa non torna col contesto della trasferta — una data fuori periodo, una valuta diversa da quella attesa. La decisione resta a chi rivede.

Il percorso di una scansione

Allegatoil PDF della nota spese

→

Letturatesto di ogni parola, e la sua posizione sul foglio

→

Separazionequante spese ci sono su questa pagina, e dove

→

Campidata, importo, valuta, città, natura

→

Aiuto del modellosolo sui campi che le regole non risolvono

→

Controllicoerenza col contesto della trasferta

→

Righe di spesaconsegnate a GePO

Il passaggio da capire è il terzo. La separazione non avviene guardando l'immagine e riconoscendo i bordi della carta, come farebbe una persona. Avviene sulle coordinate delle parole: il sistema sa dove sta ogni parola sul foglio e raggruppa quelle vicine. È il motivo per cui due scontrini attaccati diventano facilmente una riga sola.

Perché separare è più difficile che leggere

C'è un fatto misurato che spiega tutto, ed è controintuitivo: dentro un singolo scontrino gli spazi bianchi sono più larghi di quelli che separano due scontrini diversi. Fra l'intestazione e il corpo di una ricevuta ci può essere più vuoto che fra quella ricevuta e la successiva appoggiata sotto.

Quindi nessuna regola basata sullo spazio bianco può funzionare da sola. Il sistema aggiunge un criterio di buon senso: un blocco di testo è un documento di spesa se contiene un importo e, insieme, una parola come «totale» oppure una data. Quel che non lo soddisfa viene considerato un pezzo di qualcos'altro — un'intestazione, un piè di pagina — e riattaccato al documento vicino.

E qui sta la fragilità. «Una parola come totale» è una lista, e una lista può non conoscere la lingua giusta. Sulle note spese cinesi il sistema non riconosceva né 合计 come parola-totale né gli importi in yuan, che si scrivono senza decimali e senza simbolo di valuta: ricevute perfettamente leggibili venivano scambiate per frammenti e assorbite nello scontrino accanto. Non era il motore a essere debole: era cieco su una lingua.

Dove c'è l'intelligenza artificiale, e dove no

È la domanda che chiarisce tutto il resto — e la risposta sorprende: i modelli sono due, lavorano agli estremi opposti, e la parte più delicata in mezzo non è affidata a nessuno dei due.

1 Chi legge Google Cloud Vision

Le parole — e dove stanno sul foglio

Cos'è: Un servizio specializzato nel riconoscimento del testo. Restituisce ogni parola con la sua posizione e quanto è sicuro di averla letta bene.
Vede l'immagine?: Sì — è l'unico che la vede.
Cosa non fa: Non capisce cosa sta leggendo: non sa distinguere uno scontrino da un altro, né un totale da un numero di tavolo.

2 Chi separa Codice, non un modello

I confini — quante spese ci sono su questa pagina

Cos'è: Codice nostro, deterministico: raggruppa le parole vicine e applica il criterio del «importo più totale o data». Stessa pagina, stesso risultato, sempre.
Vede l'immagine?: No. Vede solo le coordinate delle parole.
Perché conta: È lo stadio che decide quante righe di spesa escono. Un errore qui non si recupera dopo: se due scontrini finiscono insieme, nessun modello a valle può separarli.

3 Chi interpreta GPT-4o

I campi incerti — quando le regole non bastano

Cos'è: Un modello linguistico che riceve il testo di un documento già separato e completa i campi che le regole non hanno risolto con sicurezza.
Vede l'immagine?: No — riceve solo testo. Ed è il fatto che spiega il suo difetto peggiore, qui sotto.
Quanto interviene: Su ogni riga, non solo sui casi difficili: la natura della spesa è sempre affidata a lui. È anche quasi tutto il tempo di attesa.
È l'unico possibile?: No. Accanto a GPT-4o è implementato e verificato Claude Sonnet 5, spento dietro un interruttore. Su questo stadio, e solo su questo, il modello è intercambiabile.

Chi sceglie il modello, e chi no. Non il chiamante. La richiesta che arriva da GePO può contenere un blocco che nomina provider e modello, ma sull'OCR quel blocco non ha alcun effetto: viene letto, normalizzato e mai riletto: la scelta è dentro il servizio, ed è per questo che la risposta dichiara il motore come managed. È una decisione presa — le scelte di motore non sono configurabili dal caller in questa versione — ma oggi è anche una trappola, per due motivi: sull'altro endpoint del servizio, quello delle domande, lo stesso identico blocco comanda davvero; e sul gestionale esiste un pannello che permette di scegliere il modello dell'OCR fra un catalogo, dove la scelta viaggia nella richiesta e non produce alcun effetto. Finché il campo resta lì, è una leva finta.

Cosa puoi fare perché funzioni meglio

Questa è la parte utile a chi prepara le scansioni, ed è la più efficace di tutte: siccome la separazione lavora sulla posizione delle parole, com'è fatto il foglio conta quanto il codice. Dei documenti che oggi il sistema ancora perde, nessuno chiede una lettura migliore: chiedono un foglio preparato meglio.

1Nella scansione solo documenti di spesa

Fuori carte d'imbarco, matrici di biglietto, ricevute di consegna. Una carta d'imbarco non riporta alcun importo: non è un documento di spesa e non lo diventerà mai — occupa spazio, si accosta a uno scontrino vero e se lo tira dentro.

2Niente scontrini di pagamento che duplicano una ricevuta già presente

Se lo scontrino della carta e la ricevuta della stessa transazione stanno entrambi sul foglio, il caso migliore è che il sistema li unisca. Il caso peggiore è che li separi bene: due righe dove la spesa è una, e il totale della nota raddoppia su quella voce. Attenzione al verso opposto: se lo scontrino della carta è l'unico documento di quella spesa, va scansionato.

3Tutti i documenti nello stesso verso

Una pagina che mescola documenti dritti e ruotati costa due volte: il servizio di lettura sceglie un orientamento e può ignorare fino a un quarto del foglio, e i documenti ruotati non si separano fra loro.

4Uno spazio bianco fra un documento e l'altro, e nessuna sovrapposizione

Ogni scontrino intero e visibile, nessun lembo che ne copre un altro, allineati in griglia e non a scaletta. Quanto spazio: più largo dell'interlinea di uno scontrino — a occhio un dito. Non è un consiglio generico: è la distanza che il sistema usa davvero per decidere.

Cosa può sbagliare, e come te ne accorgi

Non tutti gli errori si vedono allo stesso modo, e la differenza conta più della loro frequenza.

Errori che si vedono

Il campo esce come ?, oppure due scontrini finiscono in una riga sola con un totale che non torna.

Chi rivede se ne accorge e corregge. Sono i più frequenti, e i meno pericolosi.

Errori che non si vedono

Un valore plausibile ma falso: una spesa che sparisce del tutto, o un documento contato due volte.

Nessuno se ne accorge rileggendo, e nemmeno sommando. Sono i pochi che contano davvero.

Un caso vero, che vale come esempio di tutti. Sulla città il modello rispondeva quasi sempre — e su 50 documenti ne aveva inventate 17. Non a caso: erano tutte la città della trasferta. Sul taxi di Kyoto, che l'indirizzo lo stampa per esteso, scriveva «Osaka» in una scansione e «Tokyo» in un'altra copia della stessa pagina. Il motivo è strutturale: quel modello non vede l'immagine, e la città spesso sta dentro un logo; non trovandola nel testo, ripeteva il contesto. La soluzione non è stata chiedergli di fare meglio — gli è stata tolta la domanda. Ora la città la leggono le regole: 35 letture corrette invece di 27, e nessuna sbagliata.

Come lo sappiamo — la misura

Niente di quanto sta scritto sopra viene da un'impressione. Esiste un campione di riferimento: 108 documenti veri su 37 pagine, letti a vista e annotati uno per uno con i valori che dovrebbero uscire. Un comando riesegue la pipeline su quel campione e conta gli scarti — è così che si sa se una modifica migliora o peggiora, invece di discuterne.

Prima

Su 100 documenti, 36 non ottenevano una riga propria.

Quasi tutti finivano dentro la riga di un vicino: il sistema li aveva letti, non sapeva che fossero documenti a sé.

Dopo aver insegnato il cinese

Su 100 documenti, 25. E ogni campo migliora: i totali letti correttamente passano da 42 a 63.

Nessuna riga di codice sull'algoritmo di separazione: solo le parole e le forme di numero che gli mancavano.

Dove può ancora arrivare

Il passo successivo, progettato e non implementato, è far guardare la pagina a un modello — chiedergli dove sono i bordi dei fogli, invece di dedurli dalla posizione delle parole. Il candidato ha un nome, Gemini, e sarebbe il terzo modello del servizio: non leggerebbe niente e non compilerebbe niente, restituirebbe solo riquadri. Risolverebbe i casi che restano, e sarebbe l'unico modo per leggere una città stampata dentro un logo.

Il piano che lo riguarda è in due tempi, e l'ordine non è negoziabile: prima si misura il motore che già gira — quanti documenti perde davvero, su un campione annotato, con una soglia decisa in anticipo — e solo dopo si affianca l'alternativa, sulla stessa pagina e sulla stessa lettura, per confrontare due liste di riquadri invece di due impressioni. Senza il primo tempo, sostituire uno stadio è un atto di fede.

Il primo tempo è stato fatto, e la soglia superata. Il secondo è sospeso: guardando quali documenti restavano fuori, non uno chiedeva un modello che vede — erano carte d'imbarco senza importo, fogli ruotati, scontrini sovrapposti. Tutti coperti dalle quattro regole di scansione qui sopra, che costano una pagina di istruzioni invece di un modello nuovo. Si riapre se le pagine riscansionate secondo la regola perdono ancora troppo, oppure per lo scopo che la geometria non copre in nessun caso: la città dentro il logo.

Resta il prezzo, che vale la pena capire: si paga in tre monete — tempo di attesa, costo per pagina, e soprattutto imprevedibilità. Un modello che indica tre documenti oggi e due domani sulla stessa scansione non è utilizzabile dove qualcuno firma una nota spese, e questo un conteggio medio non lo mostra: va verificato a parte. Il codice deterministico, per quanto limitato, sullo stesso foglio dà sempre lo stesso risultato.

Glossario minimo

OCR: Il riconoscimento del testo stampato in un'immagine. Qui lo fa Google Cloud Vision, che restituisce anche la posizione di ogni parola.
Separazione: Capire quanti documenti di spesa distinti ci sono su una stessa pagina, e quali parole appartengono a ciascuno. Lo stadio più delicato.
Fusione: L'errore più frequente: due documenti finiscono in una riga sola. Il testo c'è, ma il totale non torna.
Riga di spesa: Ciò che il servizio consegna: data, importo, valuta, città, natura della spesa — più gli avvisi di incoerenza.
Campione di riferimento: 108 documenti reali annotati a mano con i valori attesi. Serve a misurare se una modifica migliora o peggiora davvero.
Natura della spesa: La categoria: alloggio, viaggio, vitto, trasporto locale — o «sconosciuto» per tutto ciò che non vi rientra. È l'unico campo sempre affidato al modello.

In una frase: un servizio legge le parole di una scansione, un pezzo di codice decide dove finisce uno scontrino e comincia il prossimo, e un secondo modello completa i campi incerti senza mai vedere l'immagine. La parte difficile non è leggere: è separare — e il modo più efficace per aiutarla non è un motore migliore, ma un foglio preparato con quattro accorgimenti.