Il gattone guardone: monitoraggio del chatbot

Negli ultimi due post ho descritto due plugin per l’agente Cheshire Cat AI, realizzati per un chatbot che svolge il ruolo di help desk di primo livello per un sito di assistenza informatica.

Uno dei plugin introduce delle guardie che filtrano le domande in ingresso e le risposte in uscita [5], l’altro verifica lo stato dei servizi monitorati con il software Uptime Kuma [6].

Il sistema è stato testato sottoponendogli una serie di domande, tratte da richieste reali arrivate per e-mail all’Help Desk, di cui conoscevamo già la risposta, e valutando la qualità delle risposte ottenute. Ci siamo presto accorti che serviva un modo per tenere traccia delle risposte e del comportamento del chatbot, così da poterlo analizzare nel dettaglio.

Le guardie svolgevano il loro compito? I tool venivano invocati? L’integrazione con Uptime Kuma funzionava? Da quali documenti nasceva una risposta?

All’inizio abbiamo provato plugin come Langfuse Connector e Ragas Retriever Evaluator, ma serviva qualcosa di più specifico, anche per verificare che i due plugin realizzati funzionassero come previsto. È nato così questo sistema di monitoraggio.

Componenti del sistema

Il sistema è composto da tre parti:

RAG Interaction Logger [2]: un plugin per lo Stregatto che registra ogni interazione (una domanda e la relativa risposta) tra utente e chatbot. È un semplice osservatore: non modifica messaggi né risposte e scrive sul database in un thread separato, quindi un problema del database non rallenta né blocca la conversazione.
RAG Interaction Logger Monitor [1]: un plugin per WordPress che funziona da backoffice del sistema. Legge i dati registrati, calcola statistiche, evidenzia le anomalie e permette di esaminare le singole interazioni. Esegue solo query di lettura ed è accessibile solo agli amministratori del sito.
Un database MySQL o MariaDB con la tabella ril_interactions, in cui il primo plugin scrive e da cui il secondo legge.

Funzionalità del sistema

Per ogni interazione il logger salva una riga con:

data, durata, utente ed esito del turno: risposta generata dall’LLM, risposta fornita direttamente da un plugin senza passare dall’LLM, oppure turno incompleto;
la domanda, la risposta generata dall’LLM e la risposta consegnata all’utente: se differiscono, qualcosa è intervenuto tra la generazione e la consegna;
la presenza di RAG Guardrails e i verdetti delle guardie sulla domanda e sulla risposta;
il numero di documenti recuperati dalla memoria, il punteggio migliore e i metadati delle fonti (titolo, URL, ID WordPress, tipo), mai il loro testo;
i tool invocati e, se abilitati nelle impostazioni, il testo in ingresso e in uscita di ciascun tool.

Il backoffice su WordPress aggiunge il menu Monitor RAG, con queste sezioni:

Dashboard: numero di turni, durate, indicatori (risposte generate, risposte dirette, turni incompleti, blocchi delle guardie, recall, tool), utilizzo di ogni tool e blocchi per verdetto. Il riquadro Stato del test riassume l’ultima interazione registrata, la copertura delle guardie, la percentuale di blocchi e quella di invocazione dei tool.
Andamento: gli stessi dati nel tempo, raggruppati per giorno, settimana o mese a seconda del periodo scelto.
Interazioni: l’elenco paginato delle interazioni, con filtri e ricerca testuale.
Dettaglio: tutti i campi di una singola interazione, con il confronto tra risposta generata e risposta consegnata e l’elenco delle fonti usate.
Anomalie: viste predefinite che portano all’elenco già filtrato, ad esempio turni incompleti, turni senza guardie, blocchi in ingresso o in uscita, risposte modificate senza un blocco in uscita, risposte generate senza alcun documento recuperato, tool invocati in turni incompleti o bloccati.
Impostazioni: i parametri di connessione al database.

L’interfaccia è disponibile in italiano e in inglese.

Creazione del database su MySQL

Le due componenti si scambiano i dati tramite la tabella ril_interactions di un database MySQL (8.0 o 8.4) o MariaDB (10.4 o successivo), chiamato per default rag-interaction-logger-db. Il file database.md del plugin per lo Stregatto descrive la creazione del database, della tabella e degli utenti. La tabella può anche essere creata automaticamente dal plugin al primo collegamento.

Servono due utenti distinti:

un utente per il logger (es. ril_logger), con i permessi di creazione, scrittura e cancellazione sul database;
un utente per il monitor (es. ril_monitor), con il solo permesso di lettura (SELECT) sulla tabella.

I dati da annotare per configurare i due plugin sono: host, porta e nome del database, nome della tabella (default: ril_interactions), se il server richiede SSL (ovviamente meglio che lo sia), e username e password dei due utenti.

Installazione del plugin per Cheshire Cat AI

Il plugin è stato sviluppato per Cheshire Cat AI 1.9.2 [4] ed è disponibile nel registro dei plugin dello Stregatto:

nel pannello di amministrazione aprire la sezione Plugins e cercare RAG Interaction Logger;
installarlo e attivarlo;
aprire le impostazioni del plugin e inserire db_host, db_port, db_name, db_user e db_password dell’utente ril_logger, lasciando attivo db_require_ssl se il server usa SSL, poi salvare;
controllare che nel log dello Stregatto compaia il messaggio RAG Interaction Logger: Database check passed;
fare una domanda al chatbot e verificare che sia stata registrata:
```
SELECT * FROM ril_interactions ORDER BY id DESC LIMIT 1;
```

Tra le altre impostazioni ci sono log_tool_input e log_tool_output, disattivate per default, per salvare anche i testi scambiati con i tool, e retention_days, per cancellare automaticamente le righe più vecchie di un certo numero di giorni (con 0 si conservano tutte).

Installazione e configurazione del plugin per WordPress

Il plugin richiede WordPress 7.1 o successivo e PHP 8.3 con l’estensione sodium. Non è pubblicato sulla directory ufficiale dei plugin, quindi bisogna generare il pacchetto a partire dal repository (serve PHP con l’estensione zip):

git clone https://github.com/ScuolaNormaleSuperiore/rag-interaction-logger-monitor.git
cd rag-interaction-logger-monitor
composer build

Il comando crea il file dist/rag-interaction-logger-monitor-<versione>.zip. A questo punto:

in WordPress andare su Plugin → Aggiungi nuovo plugin → Carica plugin, selezionare lo zip, installarlo e attivarlo;
aprire Monitor RAG → Impostazioni e inserire host, porta, nome del database, nome della tabella e le credenziali dell’utente ril_monitor.

La password viene salvata cifrata e non viene più mostrata. In alternativa, i parametri possono essere definiti come costanti in wp-config.php, che hanno la precedenza sui valori della pagina delle impostazioni:

define( 'ICT_RAG_MONITOR_DB_HOST', 'db.example.org' );
define( 'ICT_RAG_MONITOR_DB_USER', 'ril_monitor' );
define( 'ICT_RAG_MONITOR_DB_PASSWORD', '<password>' );

Se l’utente del database richiede SSL, bisogna definire anche MYSQL_CLIENT_FLAGS in wp-config.php, perché il plugin usa le impostazioni di connessione del sito.

Conclusioni

Il sistema di monitoraggio non dipende da RAG Guardrails né da Uptime Kuma Connector, quindi può essere usato con qualunque chatbot basato su Cheshire Cat AI 1.9.2. Se le guardie sono presenti, i loro verdetti vengono registrati; altrimenti quei campi restano vuoti.

Nel nostro caso è servito proprio a rispondere alle domande da cui eravamo partiti: il confronto tra risposta generata e risposta consegnata mostra quando e perché una guardia è intervenuta, l’elenco dei tool invocati conferma se la verifica dei servizi con Uptime Kuma è stata usata, e le fonti recuperate spiegano da dove nasce una risposta.

Il sistema è pensato per le fasi di test e di debug, non per la produzione. La scrittura è asincrona e senza tentativi successivi, quindi se il database non è raggiungibile alcune interazioni possono andare perse. Inoltre domande e risposte possono contenere dati personali: è bene limitare l’accesso alla tabella e definire un periodo di conservazione con retention_days.

È possibile testare facilmente tutto il sistema in locale con Cheshire Cat AI su Docker e WordPress installato su Local.