Come strumentare un’applicazione di IA per analizzare errori, latenza e consumi

1. Parti dalle domande operative, non dai campi

L’osservabilità di un’applicazione di IA consiste nel poter ricostruire il suo comportamento a partire da segnali correlati: quale richiesta è arrivata, quali fasi sono state eseguite, che cosa è andato storto e quanto è durata ogni parte. In un’applicazione che già chiama un modello tramite API, strumentare non significa copiare ogni input e risposta in un registro. Significa raccogliere abbastanza contesto per rispondere alle domande operative in modo ripetibile, con un ambito e una politica sui dati ben definiti.

Prima di scegliere una libreria o creare una dashboard, metti per iscritto le domande a cui il team deve poter rispondere durante un incidente. Per esempio: quale versione dell’applicazione e del prompt ha gestito questa richiesta? Il modello è stato chiamato una volta o ci sono stati tentativi successivi? Quale strumento è stato eseguito e quanto è durato? Il ritardo si è verificato nell’applicazione, nella rete, nel modello o in uno strumento? Quale uso ha comunicato l’API? Queste domande definiscono il progetto: i campi che non aiutano a rispondere non dovrebbero essere aggiunti per abitudine.

È utile distinguere l’osservabilità dalla valutazione dei contenuti. Questo articolo si concentra sul percorso tecnico e operativo di una richiesta: errori, latenza, tentativi successivi e consumi comunicati. Non propone un metodo per decidere se una risposta è vera, scegliere un fornitore o progettare un flusso conversazionale. Mantenere chiaro questo confine aiuta a contenere i registri ed evita di presentare un segnale tecnico come prova di qualità.

2. Disegna il ciclo e definisci come correlare gli eventi

Una richiesta che nell’interfaccia sembra una singola chiamata può includere diverse operazioni: convalida dell’input, costruzione del prompt, chiamata al modello, elaborazione della risposta e, talvolta, chiamata a uno strumento. Se ci sono nuovi tentativi, ciascuno deve risultare visibile come operazione distinta. Il registro deve permettere di riunire questi eventi senza dipendere da identificativi che l’API esterna non garantisce.

Genera un identificativo della richiesta nella tua applicazione quando questa viene ricevuta e propagalo tra i componenti che controlli. Aggiungi identificativi secondari o numeri di fase per distinguere le chiamate al modello e agli strumenti. Se il fornitore restituisce un identificativo della richiesta, conservalo come campo aggiuntivo per facilitare eventuali verifiche o richieste di assistenza, ma non usarlo come unico collegamento: potrebbe non essere disponibile per tutti gli errori o i percorsi di esecuzione.

Definisci anche i limiti temporali di ogni misurazione. La durata totale inizia quando l’applicazione accetta la richiesta e termina quando la risposta viene consegnata o viene registrato l’errore finale. La durata di una chiamata al modello va dall’avvio della chiamata alla ricezione della risposta o dell’errore. Una chiamata a uno strumento ha i propri tempi di inizio e fine. Registrare millisecondi senza precisare questi limiti produce dati che non possono essere confrontati con sicurezza.

3. Definisci uno schema minimo e registra ciò che l’API restituisce davvero

Uno schema minimo deve distinguere i dati generati dalla tua applicazione dai campi ricevuti dal fornitore. Tra i campi interni possono esserci l’identificativo della richiesta, la fase, il numero del tentativo, lo stato, i timestamp e le versioni del codice e del prompt. Il modello richiesto, la configurazione e l’identificativo restituito dal fornitore possono aiutare a ricostruire l’esecuzione, ma la loro origine deve essere indicata chiaramente.

L’uso comunicato da un’API non è un dato universale. Può variare a seconda dell’endpoint, del modello, della modalità, della versione o del tipo di risposta; può inoltre mancare in caso di errori o risposte parziali. La documentazione disponibile per questa guida non identifica un fornitore specifico e non consente di affermare che esista un elenco universale di campi. Implementa quindi un adattatore per ogni API e consulta la relativa documentazione primaria aggiornata per verificare nomi, unità e condizioni. Memorizza il risultato come «uso segnalato dall’API», indicando quali campi erano presenti; non trasformare un valore mancante in zero senza distinguerlo.

Separa anche il tempo misurato dall’applicazione dall’eventuale durata comunicata dal fornitore. Il primo misura il percorso nel tuo sistema; il secondo, se esiste, segue la definizione del fornitore. Indica sempre le unità, per esempio millisecondi per le durate, e stabilisci se i timestamp sono salvati in UTC. Convenzioni costanti permettono di confrontare le richieste e individuare variazioni senza mescolare orologi o intervalli diversi.

4. Strumenta eventi strutturati dall’inizio alla fine

I registri strutturati sono più semplici da filtrare e raggruppare rispetto ai messaggi in prosa. Definisci nomi stabili per eventi, stati e campi; evita che ogni componente usi un’etichetta diversa per lo stesso concetto. Per iniziare non serve scegliere una piattaforma di osservabilità specifica: puoi emettere eventi JSON dall’applicazione ed esportarli nella piattaforma già usata dal team.

Un modello utile consiste nell’emettere un evento di inizio e uno di fine per ogni fase, oppure un solo evento di chiusura che includa inizio, fine ed esito quando la fase è breve e non occorre un aggiornamento in tempo reale. Per le operazioni lunghe, l’evento finale deve mantenere il collegamento con la richiesta originaria. Se utilizzi tracce distribuite, propaga il relativo contesto attraverso i servizi e le code che controlli; verifica che l’identificativo non vada perso nel passaggio da un’attività sincrona a una asincrona.

L’esempio seguente è pseudocodice schematico, non un’integrazione eseguibile con un’API: i nomi dei campi per risposte ed errori dipendono dall’SDK e dal fornitore. Nell’implementazione effettiva, adatta l’estrazione dei dati di utilizzo e degli errori alla documentazione aggiornata e assicurati che il blocco delle eccezioni non registri automaticamente contenuti che potrebbero includere dati sensibili.

5. Riduci al minimo i dati sensibili prima di salvarli o esportarli

L’osservabilità non richiede di conservare prompt completi, risposte integrali o argomenti degli strumenti per ogni richiesta. Questi contenuti possono includere dati personali, segreti, informazioni commerciali o materiale non necessario per rispondere a domande operative. Inizia con metadati e segnali derivati: identificativi opachi, versioni, lunghezze, categorie di errore, stati e tempi.

Decidi, campo per campo, quale trattamento applicare: escludere, redigere, trasformare oppure conservare con accesso limitato e tempi di conservazione ridotti. Per correlare un evento a un’entità aziendale può bastare una chiave pseudonimizzata o un riferimento interno che solo un sistema autorizzato può risolvere. Un hash non garantisce l’anonimato se il valore originale è prevedibile o confrontabile con un elenco: non considerarlo automaticamente una soluzione di privacy.

Verifica la redazione prima di abilitare la registrazione in produzione. Usa esempi sintetici che includano casi tipici e varianti: un indirizzo email nell’input, un token in un’intestazione o un dato riservato nella risposta di uno strumento. Controlla sia l’evento in uscita dall’applicazione sia quello che arriva all’archivio: una regola applicata soltanto nella dashboard, o dopo l’esportazione, lascia i dati esposti durante il trasferimento.

6. Crea dashboard e avvisi per indagare, non per accumulare grafici

Una dashboard utile risponde a una domanda e chiarisce quale azione può seguirne. Inizia con tre viste: stato delle richieste, distribuzione della latenza e uso segnalato. Per lo stato, mostra richieste completate, fallite e prive di esito finale, suddivise per categoria di errore. Per la latenza, mostra la durata totale e quella di ogni fase, usando percentili oltre alle medie, perché una media può nascondere una coda di richieste lente. Per l’uso, mostra soltanto i campi disponibili e suddividi i dati per modello, versione o tipo di richiesta quando ciò aiuta a individuare variazioni.

Gli avvisi devono rappresentare condizioni che qualcuno può indagare o correggere. Un tasso di errore che supera il livello abituale per un intervallo definito può giustificare un avviso; un singolo errore può rimanere nel registro senza richiedere l’intervento immediato di un team. Le soglie dipendono dal volume e dalle aspettative del servizio, quindi non è opportuno fissare un valore universale senza dati. Aggiungi la finestra di osservazione, il responsabile e il collegamento alla query o alla procedura di risposta.

Non presentare come importo fatturato una stima di costo basata sull’uso segnalato. Per una stima interna, moltiplica le unità disponibili per i prezzi e le regole applicabili allo specifico account e alla relativa configurazione; etichetta il risultato come stima. Gli importi effettivi possono dipendere da condizioni che non si ricavano dal solo evento di risposta: per qualsiasi riconciliazione, verifica la documentazione ufficiale aggiornata e i dati di fatturazione del fornitore pertinente.

7. Analizza una richiesta non riuscita in modo riproducibile

Quando arriva una segnalazione, individua prima l’ID interno della richiesta e verifica che corrisponda all’ambiente e al periodo corretti. Raccogli gli eventi e ordinali per orario e fase. Prima di interpretare il risultato, verifica che la traccia sia completa: sono presenti gli eventi di inizio e chiusura? Mancano fasi relative agli strumenti? Il registro indica un errore terminale o soltanto un tentativo fallito? Un’esecuzione incompleta può sembrare un errore del modello quando, in realtà, è semplicemente mancata la registrazione dei dati.

Ricostruisci poi versioni e sequenza: codice dell’applicazione, versione del prompt, modello richiesto ed eventuale modello effettivamente osservato, numero di tentativi, strumenti e relativi stati. Confronta la durata totale con la somma delle fasi, tenendo conto dell’elaborazione locale, delle code e dei tempi non strumentati. Se la somma non torna, annotalo come lacuna della telemetria, non come prova di una causa.

Infine, separa i fatti dalle ipotesi. Un timeout del fornitore può essere registrato come esito di un tentativo, ma da solo non dimostra perché si sia verificato. Uno strumento lento può spiegare una parte del tempo misurato, ma non necessariamente il risultato finale. Registra ciò che si sa, ciò che manca e quale verifica permetterebbe di distinguere le diverse ipotesi. Questo metodo evita di attribuire cause che il registro non dimostra.

8. Verifica la strumentazione e ampliala per fasi

Anche la strumentazione richiede test: l’applicazione può funzionare pur perdendo gli ID, omettendo l’evento di chiusura o registrando dati che avrebbero dovuto essere redatti. Esegui test controllati per esito positivo, errore, timeout, nuovo tentativo e chiamata a uno strumento. Per ciascun caso, controlla l’intera sequenza dall’evento in ingresso all’esito finale, oltre ai permessi e alla redazione prima dell’esportazione.

Inizia con un percorso di produzione circoscritto e verifica che le query rispondano a domande reali. Controlla il volume generato e verifica che il team riesca a trovare una richiesta senza cercare manualmente in sistemi diversi. Adegua la selezione degli eventi e i tempi di conservazione prima di estendere la copertura. L’obiettivo non è massimizzare il volume della telemetria, ma mantenere evidenze sufficienti e consultabili per gestire il sistema.

Le convenzioni di telemetria e i campi di utilizzo delle API possono cambiare. Assegna una versione al tuo schema interno e convalida gli adattatori quando cambiano SDK, API o configurazione. Se il fornitore modifica una risposta, il livello di normalizzazione dovrebbe consentire di adattarsi senza obbligare ogni dashboard e query a dipendere dai nomi esterni. I principi generali di osservabilità possono aiutare a organizzare segnali e tracce, ma non sostituiscono la documentazione tecnica primaria per i campi o la fatturazione di uno specifico fornitore.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.