Prima di toccare il codice: decisioni che condizionano tutto
Integrare un modello linguistico in un sito web non inizia installando un SDK. Inizia rispondendo a tre domande che determinano il resto della checklist: quale compito specifico risolve l’LLM, dove viene eseguita l’inferenza e chi si assume il costo per token. Se non hai una risposta definitiva per tutte e tre, qualsiasi integrazione finirà per essere un prototipo costoso che nessuno mantiene.
Questa lista di controllo è ordinata per fasi reali di progetto. Non è una guida teorica: ogni punto include il motivo per cui esiste e l’errore tipico che evita. Alcuni punti non si applicano a tutti i casi e lo indico esplicitamente.
Fase 1. Definizione del caso d’uso (non saltare questa parte)
1.1. Scrivi il compito in una frase verificabile
«Migliorare l’esperienza dell’utente» non è un compito. «Classificare i ticket di supporto in entrata in cinque categorie con un’etichetta di affidabilità» invece lo è. Se non puoi misurare se la risposta del modello è corretta, non puoi integrarlo con garanzie.
1.2. Verifica se un LLM è davvero necessario
Molti compiti che vengono attribuiti agli LLM si risolvono con regole, espressioni regolari o un classificatore classico più economico e deterministico. Un LLM eccelle nel linguaggio libero, nell’ambiguità e nella generazione; fallisce nei calcoli esatti, nella logica rigorosa e nei dati che cambiano ogni minuto. Se il tuo caso è «estrarre un importo da una fattura con formato fisso», probabilmente non hai bisogno di un modello generativo.
1.3. Definisci il costo massimo accettabile per interazione
I prezzi per milione di token variano molto tra fornitori e tra modelli della stessa famiglia. Prima di integrare, calcola: lunghezza media del prompt + lunghezza media della risposta × volume giornaliero stimato. Un chatbot che riceve 3.000 richieste al giorno con prompt da 2.000 token può costare più dell’hosting annuale del sito. Tieni quel numero prima di scrivere la prima riga.
Fase 2. Architettura e sicurezza
2.1. La chiave API non viaggia mai verso il browser
Questo è l’errore più comune e il più costoso. Qualsiasi chiamata dal JavaScript del client espone la chiave negli strumenti di sviluppo. La chiamata al fornitore deve partire dal tuo server o da una funzione edge. Se hai bisogno di streaming verso il browser, usa un proxy nel tuo backend che inoltri i chunk.
2.2. Scegli tra API esterna e modello self-hosted
API esterna: rapida da implementare, senza infrastruttura, ma dipendi dalla disponibilità e dai prezzi del fornitore, e i dati escono dal tuo ambiente. Modello self-hosted (ad esempio, pesi aperti serviti con strumenti di inferenza locali): controllo totale e costo fisso, ma richiede GPU, manutenzione e know-how. Per siti piccoli o medi, l’API è di solito la decisione sensata; per dati sensibili con requisiti rigorosi di residenza, il self-hosting può essere obbligatorio.
2.3. Filtra e minimizza i dati che invii
Prima di inviare un prompt, elimina identificatori personali, email e dati di pagamento che il modello non necessita. Non è solo conformità normativa: riduce i token e migliora la qualità della risposta eliminando il rumore.
2.4. Protezione contro il prompt injection
Se l’LLM elabora contenuti controllati dall’utente (commenti, descrizioni di prodotti, testi incollati), presupponi che quel contenuto possa contenere istruzioni malevole. Mitigazioni pratiche: separa le istruzioni di sistema e il contenuto dell’utente con delimitatori chiari, valida l’output contro uno schema e non lasciare mai che l’output del modello attivi azioni distruttive senza conferma umana.
Fase 3. Progettazione del prompt e dell’output
3.1. Istruzione di sistema stabile e versionata
Salva il prompt di sistema in un file con controllo di versione. Quando cambi una parola, potrai confrontare i risultati. I prompt che vivono dentro il codice mescolati con la logica di business sono impossibili da verificare.
3.2. Output strutturato ogni volta che è possibile
Se il risultato alimenta un database o un’interfaccia, chiedi JSON con uno schema definito e valida la risposta con un parser rigoroso. Se il modello restituisce testo libero e tu fai split per virgole, si romperà non appena il modello cambierà formato. La maggior parte dei fornitori attuali offre modalità di output strutturato; usale.
3.3. Includi esempi nel prompt (few-shot)
Due o tre esempi di input-output corretto di solito migliorano il risultato più di paragrafi di istruzioni. Costano token, quindi riservali a compiti in cui il formato conta.
3.4. Definisci il comportamento in caso di dubbio
Indica esplicitamente cosa deve fare il modello quando non sa: restituire un campo confidenza: bassa, una frase specifica di trasferimento a un umano, o una risposta vuota che la tua interfaccia interpreti. Senza questa istruzione, il modello inventerà con totale sicurezza.
Fase 4. Integrazione nel frontend
4.1. Stati di caricamento e annullamento
Le risposte generative richiedono secondi. L’interfaccia necessita di uno stato di attesa visibile e di un pulsante di annullamento che interrompa la richiesta. Se usi lo streaming, mostra il testo man mano che arriva: riduce notevolmente la percezione di lentezza.
4.2. Accessibilità del componente
Il contenitore delle risposte deve avere aria-live=»polite» affinché i lettori di schermo annuncino il nuovo testo. Lo streaming senza gestione dell’accessibilità genera esperienze rotte per gli utenti con lettori di schermo.
4.3. Limiti nel client e nel server
Limita la lunghezza dell’input su entrambi i lati. Un campo di testo senza limite è una via diretta a prompt giganteschi che gonfiano la tua fattura. Aggiungi anche un limite di richieste per sessione o per IP.
Fase 5. Qualità, valutazione e monitoraggio
5.1. Set di test con risposte attese
Prima di pubblicare, raccogli tra 30 e 100 casi rappresentativi con la risposta corretta annotata a mano. Esegui il prompt su di essi ogni volta che lo modifichi. Senza questo banco di prova, ogni modifica è una scommessa.
5.2. Registro delle richieste e delle risposte (con attenzione)
Salva il prompt, la risposta e la latenza per poter fare debug. Anonimizza prima di archiviare e definisci un periodo di conservazione. Un log senza politica di conservazione diventa una passività.
5.3. Avvisi di costo e di latenza
Configura una soglia di spesa giornaliera che ti avvisi prima che la fattura sfugga di mano. Un ciclo infinito nel client o un bot che ripete richieste possono moltiplicare il consumo in poche ore.
Fase 6. SEO e visibilità
6.1. Il contenuto generato non si indicizza per magia
Se l’LLM genera pagine o frammenti che vuoi posizionare, necessitano di URL propria, titolo, meta descrizione e rendering lato server. Un widget che genera testo dentro un div dopo un’interazione dell’utente non apporta nulla alla scansione.
6.2. Non generare contenuto massivo senza revisione
Le politiche di qualità dei motori di ricerca disincentivano il contenuto prodotto su larga scala senza valore aggiunto. Se usi l’LLM per scrivere, usalo come bozza con revisione editoriale. Secondo la documentazione ufficiale dei principali motori di ricerca, il criterio resta l’utilità per l’utente, non il metodo di produzione.
6.3. Blocca o marca le rotte interne dell’assistente
Gli endpoint della tua API e le rotte di generazione non devono essere scansionabili né indicizzabili. Aggiungi noindex e restrizioni nel robots.txt dove opportuno.
Fase 7. Lancio e manutenzione
7.1. Distribuzione progressiva
Attiva la funzione per una percentuale di utenti prima. Misura tasso di errore, latenza e soddisfazione prima di aprirla a tutto il traffico.
7.2. Piano di degradazione
Cosa succede se il fornitore restituisce errori 429 o 500? Definisci una risposta di riserva: messaggio di indisponibilità, modulo di contatto o risposta in cache. Un assistente che rompe la pagina quando l’API fallisce è peggio che non avere un assistente.
7.3. Revisione periodica del modello
I fornitori ritirano versioni dei modelli con avvisi preventivi. Annota la data di deprecazione della versione che usi e prova la migrazione prima che sia forzata. I prompt messi a punto per una versione possono comportarsi diversamente nella successiva.
Un caso concreto e la sua lezione
In un progetto di assistente per un negozio di componenti, il team ha testato il prompt con domande di catalogo e funzionava bene. Al momento della pubblicazione, gli utenti hanno iniziato a chiedere informazioni sulle compatibilità tra pezzi. Il modello rispondeva con sicurezza su combinazioni che non esistevano nel catalogo. La causa: il prompt includeva un campione di prodotti, non il catalogo completo, e il modello riempiva i vuoti con plausibilità. La soluzione non è stata un prompt migliore, ma recuperare i prodotti rilevanti dal database e passarli come contesto in ogni richiesta. Lezione: se la risposta dipende da dati che cambiano, il modello necessita di accesso a quei dati al momento della richiesta, non di un campione statico nel prompt.
Cosa non risolve questa checklist
Non c’è garanzia che il modello risponda correttamente a tutto. Gli LLM allucinano, e nessuna configurazione elimina completamente questo comportamento. Non esiste nemmeno un prompt perfetto: ciò che funziona oggi può degradarsi con il successivo aggiornamento del fornitore. E ci sono compiti in cui un LLM non è lo strumento adatto: ricerche esatte, calcoli finanziari, filtri deterministici. Riconoscerlo in tempo fa risparmiare budget e frustrazione.
Se ripercorri queste fasi in ordine e metti per iscritto le decisioni di ciascuna, avrai qualcosa di più prezioso di un’integrazione funzionante: avrai un’integrazione che puoi mantenere quando cambierà il modello, il fornitore o il team.