Text-to-SQL locale: interrogare il database aziendale senza spedire i dati in cloud

Hai un database con le vendite, gli ordini e i clienti, e ogni settimana ti servono risposte: "quanti ordini abbiamo preso il mese scorso, divisi per regione". Oggi questa domanda o la rispondi tu scrivendo SQL, o la metti in coda al reparto dati, o chiedi a un'API cloud di parlarci. C'è una quarta via: far leggere lo schema del database a un modello di linguaggio che gira sul tuo hardware, fargli generare la query, farla eseguire sul posto e ricevere il risultato. I dati — i fatturati, gli indirizzi, i margini — non lasciano mai la tua infrastruttura. È il text-to-SQL in locale, ed è il caso d'uso che più di altri rende tangibile la differenza tra un'IA che si affitta e una che si possiede.

Cos'è il text-to-SQL locale

Il text-to-SQL trasforma una domanda in linguaggio naturale in una query SQL eseguibile, e restituisce i risultati. Il flusso in locale è un anello chiuso che gira dentro il tuo perimetro:

1. La domanda — la scrivi in italiano, come la diresti a un collega.
2. Lo schema — il modello riceve nomi di tabelle, colonne, tipi e descrizioni. Non riceve i dati.
3. La query — il modello genera l'SQL.
4. L'esecuzione — la query gira sul tuo database, che può essere un SQLite da pochi megabyte o un Postgres aziendale.
5. La risposta — i risultati tornano a te, pronti per il report o la dashboard.

Il punto che conta per la privacy: in questo schema il modello vede solo lo schema e la domanda, mai le righe. Il calcolo avviene sul tuo database. Niente fatturati, niente client list, niente margini attraversano un gateway di un provider. Per chi gestisce dati di cliente, è la differenza tra mostrare il foglio delle celle e mostrare i fogli stessi.

Dove si rompe davvero: l'ambiguità

Qui servano numeri, e i numeri vengono da un benchmark uscito a metà ottobre: ARCS (Ambiguity Resolution Corpus for SQL), il primo benchmark di text-to-SQL costruito su ambiguità naturali in database reali, pubblicato da Megagon Labs (paper su arXiv). Contiene 101 domande su 6 database, con ogni punto di ambiguità annotato insieme a tutte le interpretazioni possibili e le query corrette per ciascuna.

Prendi una domanda del corpus, tratta da un database di retail: "Report the total revenue for each nation in 1995". Sembra una domanda banale. Nel benchmark ne porta quattro distinte:

• "total revenue" — lordo o netto, dopo gli sconti?
• "for each nation" — nazione del cliente o nazione del fornitore?
• "in 1995" — data dell'ordine, dell'impegno, della spedizione o della ricezione?
• include o esclude i resi?

Ogni combinazione produce una query diversa, tutte plausibili, tutte eseguibili. ARCS riporta che il modello chiuso più performante misurato, gpt-6-sol, arriva a un'accuratezza end-to-end del 51%, e che nessun modello open source supera il 27% (dataset).

Fonte	Accuratezza end-to-end su domande ambigue
gpt-6-sol (chiuso)	51%
Migliore modello open source	27% (nessuno supera questa soglia)

Due cose emergono da questa tabella. La prima: anche con il modello migliore che puoi pagare, quasi metà delle risposte su domande realistiche è sbagliata. La seconda: il divario tra modelli aperti e chiusi resta ampio, ma il collo di bottiglia non è la conoscenza del modello — è l'ambiguità della domanda. Il modello indovina un'interpretazione invece di chiedere, e l'errore non sbatte: restituisce un numero che sembra giusto. È l'insidioso per eccellenza nel text-to-SQL, peggio di un errore lampante.

Non sono casi da laboratorio. Dallo stesso corpus:

• "For each team that Marcus Williams played for…" — in un database di basket esistono due giocatori Marcus Williams (nati nel 1985 e nel 1986): senza chiedere, il modello sceglie uno.
• "Find posts with many related posts" — "many" è una soglia non definita. Il modello la inventa.
• "Which events had a low budget remaining…" — "low" rispetto a cosa? Ancora una soglia che il modello decide da solo.

La soluzione proposta: disambiguazione strutturata

Il paper introduce un paradigma che vale la pena capire perché cambia il modo di costruire il sistema: invece di far conversare il modello in dialogo libero, l'ambiguità si risolve con interazioni esplicite e vincolate. Il flusso diventa:

1. Il modello identifica i punti ambigui della domanda.
2. Per ognuno elenca le interpretazioni plausibili — le stesse annotazioni che trovi in ARCS.
3. Tu scegli, tra opzioni chiuse, quella che intendevi.
4. Con l'interpretazione fissata, il modello genera la query.

È esattamente il modo in cui lavora un buon commercialista: non calcola sul primo impulso, chiede prima la definizione — "fatturato lordo o netto?" — e poi fa i conti. Il vantaggio rispetto al chiarimento conversazionale è pratico: ogni domanda di chiarimento è breve e a scelta multipla, costa pochi token, e la conversazione non si allunga. E funziona meglio con i modelli locali, che nei dialoghi lunghi perdono più filo che in scambi corti e vincolati.

Costruirlo in locale: schema-first e limiti del modello

Il pattern che funziona — e che riflette la struttura del benchmark stesso — è lo schema-first: il contesto che passa al modello è lo schema con i nomi delle colonne e le loro descrizioni, non i dati. ARCS distribuisce proprio questo: column_meanings.json, una descrizione per colonna (dataset). Nel tuo caso, per un database piccolo (fino a qualche decina di tabelle) basta descrivere le colonne in una frase; per uno grande, serve prima un filtro che porti al modello solo le tabelle rilevanti per la domanda.

Per il modello, il criterio di selezione è lo stesso che usi per il RAG sui tuoi documenti: memoria e contesto, non "il più intelligente". Il contesto qui è schema + domanda + eventuali esempi, quindi servono pochi token di contesto; la dimensione giusta è quella che sta nella VRAM con margine. Una regola pratica già vista sulla guida hardware per l'IA locale: a Q4 i parametri contano in gigabyte quasi uno a uno (14B ≈ 7–8 GB di pesi), poi aggiungi il margine per il contesto. Un modello da 8–14B quantizzato è un punto di partenza sensato per database piccoli; sopra i 32B entri in un'altra fascia di hardware.

Un'osservazione onesta sui numeri: ARCS misura il comportamento su domande ambigue e database di benchmark, non sulla tua domanda tipica. Se le tue domande sono semplici ("conteggio clienti attivi", "somma vendite per mese"), il tuo modello open locale farà molto meglio del 27% citato. Se sono ricche di termini di dominio ("margine su prodotti in promo, escludendo resi"), ti avvicinerai a quel numero. Il benchmark serve a capire il meccanismo del fallimento, non a prevedere la tua accuratezza esatta.

E i limiti?

• L'accuratezza sul reale è il tuo da misurare. Il 51% e il 27% di ARCS sono su domande ambigue per definizione. Costruisci un set di una decina di domande su cui conosci la risposta giusta e misura lì: è l'unico numero che conta.
• Le soglie implicite restano un buco. "Molti", "bassi", "recenti" non hanno un valore nel database. La disambiguazione strutturata li espone, ma chi deve fissarli sei tu.
• SQL generato = codice eseguito. Senza un guardrail, un modello che sbaglia può eseguire una query sbagliata — raramente distruttiva (limita l'esecuzione a SELECT), ma capace di restituire numeri che nessuno contesta perché "è uscito dal sistema".
• Schema grande = contesto lungo. Oltre un centinaio di tabelle, lo schema non sta in un contesto sensato e serve un routing preliminare delle tabelle.

Dove ha senso iniziare oggi

Il caso d'uso SMB più concreto che il text-to-SQL locale offre oggi non è sostituire il reparto dati: è dare a chi non sa scrivere SQL un primo accesso ai numeri, con i dati che restano in casa. Parti da un database limitato (vendite, inventario, ticket), dallo schema descritto in modo pulito, e dal layer di disambiguazione prima di fidarti delle risposte. Il modello lo tratti come un analista junior: veloce, sempre disponibile, ma da revisionare. Non come il commercialista che firma il bilancio. La differenza tra i due usi è tutta qui.

Fonti

• ARCS: Towards Precise Text-to-SQL via Structured Disambiguation (arXiv 2610.09396)
• Dataset megagonlabs/arcs su Hugging Face

In sintesi: il text-to-SQL locale chiude l'anello della domanda in linguaggio naturale dentro il tuo perimetro — schema e domanda al modello, esecuzione sul tuo database, risultati a te, dati che non viaggiano. Il benchmark ARCS mostra il vero collo di bottiglia: l'ambiguità delle domande reali, su cui anche i modelli chiusi superano appena il 50% e gli open restano sotto il 27%. La risposta è la disambiguazione strutturata — chiarimenti a scelta multipla prima della query — e un test su domande tue, con le risposte che conosci. Parti piccolo, misura sul tuo, e trattalo da analista junior.

Articolo generato con IA