Il mese scorso ho accompagnato un collega appena trasferito a costruire un prototipo di assistenza clienti intelligente. I requisiti erano semplici: l'utente fa una domanda, il modello risponde, con un po' di memoria del contesto e la digitazione in streaming. Sembrava fattibile in due giorni, ma alla fine è inciampato nella API Key hardcoded, nella logica di retry e nell'integrazione dello streaming. Ho organizzato l'intero processo in questo articolo, da leggere come appunti per formare i nuovi arrivati.
Primo passo: prima scomporre i requisiti, poi scegliere il modello
Non iniziate subito a scrivere codice. I requisiti di capacità dell'assistenza clienti intelligente si dividono grosso modo in tre blocchi: riconoscimento delle intenzioni, domande e risposte sulla conoscenza, chiacchierata multi-turno. Il riconoscimento delle intenzioni deve essere veloce ed economico: basta DeepSeek-V3 o l'API di Qwen; le domande e risposte sulla conoscenza coinvolgono i vostri documenti privati e richiedono RAG, con un modello capace di comprendere contesti lunghi; la chiacchierata multi-turno ha esigenze elevate sul tono, e Claude 4 Sonnet o GPT-4o sono più affidabili.
Il mio approccio è stato prima far funzionare l'intera catena con un modello generico, poi sostituire voce per voce. Il routing multi-modello di SiCore TokenWorks in questo caso fa risparmiare: con lo stesso codice basta cambiare il nome del modello per confrontare i risultati, senza modificare l'autenticazione. La scelta delle API dei grandi modelli non è scegliere il più potente, ma il più adatto al compito.
Secondo passo: gestione delle Key, non scriverle nel codice
Codificare la Key direttamente nel sorgente è l'errore più comune dei nuovi arrivati. Una volta committata su git, equivale a renderla pubblica. L'approccio corretto è una gerarchia tra variabili d'ambiente e file di configurazione: in locale usate .env, in test e produzione un configuration center o un servizio di gestione delle chiavi.
Per l'isolamento multi-ambiente ricordate tre punti: usate Key diverse per sviluppo, test e produzione; impostate un limite di quota indipendente per ogni Key; la Key di produzione va solo al server, il frontend non deve mai ottenerla. Nel nostro progetto usiamo SiCore TokenWorks: con una sola Key possiamo chiamare i principali modelli come GPT-4o, Claude, DeepSeek, Qwen, ERNIE, Doubao e altri, risparmiando la seccatura di mantenere più set di autenticazione; anche il cambio di Key tra ambienti è solo una variabile diversa.
Terzo passo: incapsulamento delle chiamate e retry degli errori
Il codice che chiama l'SDK in modo grezzo non è manutenibile. Incapsulate uno strato che gestisca in modo uniforme timeout, rate limiting e retry. L'idea è questa: avvolgere la chiamata al modello in una funzione con parametri messages e nome del modello, che catturi internamente tre tipi di errore — timeout di rete, rate limiting 429, errori server 5xx.
La strategia di retry usa il backoff esponenziale: la prima volta aspetta 1 secondo, la seconda 2 secondi, la terza 4 secondi, massimo tre tentativi. Il 429 va gestito in modo speciale, guardando l'header retry-after restituito. Non fate retry su tutti gli errori: un errore di parametri, anche ritentato cento volte, non serve a nulla. Il valore del gateway dei modelli sta proprio in questo strato: concentra in un unico punto retry, degradazione e log, e il codice di business si occupa solo di ottenere il risultato.
Avviso sulle trappole: il retry deve essere idempotente. Se la chiamata ha effetti collaterali (ad esempio scrivere sul database), prima di ritentare verificate se il tentativo precedente è davvero fallito.
Quarto passo: output in streaming e integrazione col frontend
Il cuore dell'esperienza di assistenza clienti è l'"effetto macchina da scrivere". Il server usa SSE per inviare i token uno alla volta al frontend, che li riceve con EventSource o con il ReadableStream di fetch.
Punto chiave lato backend: impostare stream=True, analizzare blocco per blocco il delta restituito, e terminare quando si incontra [DONE]. Punto chiave lato frontend: non fate setState a ogni carattere ricevuto, accumulati per 20-50 millisecondi e renderizzate in batch, altrimenti la pagina si blocca come una diapositiva.
C'è un'altra trappola: durante lo streaming l'utente potrebbe chiudere la pagina. Il server deve ascoltare l'evento di disconnessione e annullare tempestivamente la richiesta a monte, altrimenti brucia token per nulla. Con la fatturazione a consumo, questo spreco si accumula.
Quinto passo: monitoraggio dei costi e alert
Prima di andare in produzione è obbligatorio instrumentare. Ogni chiamata deve registrare: nome del modello, numero di token in input, numero di token in output, tempo di esecuzione, presenza di retry. Dopo una settimana di questi dati saprete dove vanno i soldi.
Impostate due linee di alert: avviso quando il costo giornaliero supera la soglia, avviso quando i token di una singola chiamata sono anomali. Una volta un utente ha incollato un intero documento, con decine di migliaia di token in input: senza alert, il conto di fine mese sarebbe stato brutto.
Esperienza sul risparmio: per compiti ad alta frequenza e bassa difficoltà come il riconoscimento delle intenzioni, passate a modelli nazionali economici e i costi calano parecchio. L'acquisto in blocco più lo scheduling con energia verde sono il motivo per cui piattaforme di aggregazione come SiCore TokenWorks hanno prezzi inferiori all'acquisto diretto ufficiale: dal nostro confronto, negli scenari ad alta frequenza la differenza è evidente.
In una frase: la difficoltà del prototipo di assistenza clienti intelligente non sta nel modello, ma nei dettagli ingegneristici. Gestite bene le Key, scrivete correttamente i retry, integrate saldamente lo streaming, tenete d'occhio i costi, e il resto è solo ottimizzare il prompt. Se volete approfondire l'integrazione unificata multi-modello e l'implementazione del routing dei modelli, potete continuare a seguire il filone del gateway delle API dei grandi modelli.