Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Panoramica del logging delle conversazioni

La registrazione delle conversazioni di analisi conversazionale ti consente di registrare le conversazioni di un agente di dati in una tabella BigQuery nel tuo progetto, in modo da poter esaminare la qualità delle risposte, monitorare l'adozione e i costi degli agenti di analisi conversazionale. Per ogni turno, il log acquisisce la domanda dell'utente, la risposta dell'agente, la latenza, l'utilizzo dei token del modello e gli identificatori necessari per raggruppare i turni per agente, conversazione e utente. Le righe vengono scritte utilizzando lo schema BigQuery Agent Analytics tramite l'API BigQuery Storage Write (gRPC).

Informazioni registrate nei log

Ogni turno registrato scrive più righe di eventi (events) nella tabella di destinazione che registrano le seguenti informazioni:

La domanda dell'utente.
La risposta dell'agente: il testo, gli insight, le ipotesi, le domande di follow-up suggerite, le fonti delle citazioni e i nomi di eventuali risultati o grafici dei dati.
Latenza per turno.
Utilizzo dei token del modello, versione del modello e motivo del completamento (perché il modello ha interrotto la generazione dei token) per ogni chiamata al modello.
L'ID agente dati e l'ID conversazione, in modo da poter analizzare più agenti in un'unica tabella.
Un identificatore dell'utente. Per saperne di più sugli identificatori degli utenti, consulta Identità utente.
Dettagli su stato ed errori.

Che cosa non viene registrato

Il logging delle conversazioni non registra quanto segue:

Le query SQL eseguite dall'agente: il log contiene la risposta finale e i nomi dei risultati e dei grafici dei dati di riferimento, ma non le query che li hanno generati. L'eccezione è quando un utente chiede esplicitamente all'agente di mostrare o spiegare l'SQL; in questo caso, l'SQL può apparire nel testo della risposta.
Chiamate dello strumento dell'agente: ogni chiamata del modello scrive una riga LLM_RESPONSE, incluse le chiamate in cui il modello decide di eseguire uno strumento. Prima che la riga venga scritta, l'output del modello viene rimosso, inclusi il nome e gli argomenti di qualsiasi strumento chiamato. Vengono conservati solo l'utilizzo dei token, la versione del modello e il motivo della fine.
Feedback degli utenti: i feedback Mi piace o Non mi piace non vengono registrati.

Alcune conversazioni non vengono registrate, ad esempio quelle nel riquadro di anteprima di BigQuery Studio. Per saperne di più sulle piattaforme di conversazione non supportate, consulta Limitazioni.

Come funziona il logging delle conversazioni

Quando un utente chatta con un agente di dati per cui è abilitato il logging delle conversazioni, l'analisi delle conversazioni elabora ogni turno attraverso le seguenti fasi:

Configurazione: un proprietario dell'agente attiva il logging delle conversazioni e seleziona un set di dati di destinazione e un nome di tabella esistenti nel progetto dell'agente in BigQuery Studio.
Domanda: un utente invia una domanda all'agente. In BigQuery Studio, gli utenti visualizzano un avviso che li informa che le loro conversazioni vengono registrate.
Controllo della privacy: prima che l'agente inizi a lavorare sul turno, un controllo della privacy legge i metadati delle tabelle delle origini di conoscenza dell'agente utilizzando le credenziali dell'utente che chatta. Questo controllo conferma che nessuna delle tabelle utilizza la sicurezza a livello di riga (policy di accesso alle righe), la sicurezza a livello di colonna (tag di policy) o il mascheramento dinamico dei dati. Se il controllo trova una policy o non può confermare che non ce ne siano, il turno non viene registrato e l'agente risponde comunque alla domanda dell'utente.
Risposta: l'agente risponde all'utente come di consueto.
Scrittura: l'agente di servizio dell'API Conversational Analytics del progetto (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.) scrive le righe di log nella tabella di destinazione tramite l'API Storage Write (gRPC). Al primo turno registrato, l'agente di servizio crea la tabella se non esiste già.
Query: le righe vengono in genere visualizzate entro pochi secondi dal completamento della risposta. I tempi di consegna non sono garantiti.

Gli errori di logging non causano mai il fallimento di un turno e il controllo della privacy e la scrittura dei log possono aggiungere latenza. Un'autorizzazione mancante nel set di dati di log, un set di dati che non esiste o una quota esaurita non causano l'errore della richiesta di chat. L'analisi conversazionale non segnala gli errori di logging nell'interfaccia di chat o in Cloud Logging.

Privacy, governance dei dati e sicurezza

Quando attivi il logging delle conversazioni per un agente, esamina in che modo le notifiche per gli utenti finali, l'accesso ai dati, la crittografia e i controlli di rete si applicano ai tuoi log.

Notifiche per gli utenti finali e contenuti registrati

Le seguenti informative e regole stabiliscono cosa viene registrato dal logging delle conversazioni e chi può visualizzare i dati registrati:

Avviso per l'utente finale in BigQuery Studio: quando il logging delle conversazioni è attivato per un agente, gli utenti che chattano con l'agente in BigQuery Studio visualizzano il seguente avviso ogni volta che il logging delle conversazioni è abilitato, anche nella schermata della nuova conversazione prima che l'utente invii un primo prompt:

Tutti i prompt e le risposte vengono registrati in BigQuery e sono accessibili agli utenti con autorizzazioni per il set di dati.
Le tue responsabilità quando utilizzi l'API: se attivi il logging delle conversazioni (logging di traccia) su un agente di dati e lo rendi disponibile agli utenti finali tramite la tua applicazione o integrazione, Google non può mostrare un avviso a questi utenti. Sei responsabile di eventuali comunicazioni, informative o consensi applicabili alle conversazioni registrate ai sensi della legge vigente e dei tuoi contratti con gli utenti finali. Per saperne di più, consulta Sicurezza, privacy, rischio e conformità per l'API Conversational Analytics.
Contenuto del log e chi può visualizzarlo: la tabella di destinazione memorizza i contenuti di domande e risposte in base alle seguenti regole sulla privacy:
- Domande e risposte complete: le risposte possono includere valori restituiti dalle tue fonti di conoscenza. Chiunque possa leggere la tabella di log può visualizzare i dati restituiti dall'agente a un utente, inclusi i dati che non può leggere nelle tabelle di origine. Concedi l'accesso in lettura al set di dati dei log solo alle persone che devono visualizzare questi contenuti.
- Identificatori dell'utente e posizione di scrittura: la colonna user_id identifica il chiamante che ha posto la domanda (vedi Identità utente) e le righe vengono scritte solo nella destinazione configurata nel progetto dell'agente.
- Tabelle con sicurezza a livello di riga, sicurezza a livello di colonna o mascheramento dei dati: se le origini di conoscenza di un agente utilizzano la sicurezza a livello di riga (policy di accesso alle righe), la sicurezza a livello di colonna (tag di policy) o il mascheramento dinamico dei dati, i suoi turni non vengono registrati. Il controllo della privacy ignora le tabelle in bigquery-public-data e prende in considerazione solo le tabelle e le viste che selezioni come fonti di conoscenza, non le tabelle dietro una vista:
  - Una vista su una tabella che utilizza queste policy può superare il controllo, quindi i suoi turni possono essere registrati. Prima di attivare il logging, assicurati che le tabelle alla base delle viste non utilizzino policy di accesso alle righe, tag di policy o mascheramento dei dati.
  - Se in un secondo momento aggiungi una di queste policy a una tabella di origine, le righe che erano già state registrate rimangono nella tabella di log. Se le tue policy di conservazione o governance vietano la conservazione di queste righe, eliminale.

Controllo degli accessi, crittografia e sicurezza di rete

Puoi gestire la conservazione, l'accesso, la crittografia e la sicurezza perimetrale dei log delle conversazioni utilizzando le seguenti impostazioni:

Conservazione e controllo dell'accesso nel set di dati dei log: configura la conservazione, i ruoli del set di dati, le policy delle tabelle e gli audit log per la tabella di destinazione:
- Conservazione: Google non elimina le righe dei log. Imposta una scadenza della partizione sul set di dati o sulla tabella dei log che corrisponde alla tua policy (ad esempio, 90 giorni).
- Privilegio minimo: mantieni il set di dati di log separato dagli altri set di dati in modo che l'accesso in scrittura dell'agente di servizio dell'API Conversational Analytics condiviso rimanga lontano dalle altre tabelle. Concedi agli analisti roles/bigquery.dataViewer sul set di dati dei log o concedi loro l'accesso solo alle viste autorizzate o ai set di dati autorizzati.
- Controlli a livello di colonna e di riga sulla tabella di log: puoi applicare tag di policy, mascheramento dei dati o policy di accesso alle righe alla tabella di log stessa, ad esempio su content o user_id. Questi controlli della tabella di log non influiscono sul controllo della privacy della fonte di conoscenza.
- Audit logging: le modifiche a un agente di dati vengono registrate negli audit log delle attività di amministrazione. Negli audit log di BigQuery, la creazione di tabelle e gli aggiornamenti dei metadati da parte dell'agente di servizio vengono registrati in bigquery.googleapis.com, mentre le aggiunte di righe tramite l'API Storage Write (gRPC) vengono registrate in bigquerystorage.googleapis.com.
CMEK, Controlli di servizio VPC e residenza dei dati: i seguenti controlli di crittografia, perimetro e località si applicano al logging delle conversazioni:
- CMEK: se il set di dati di log utilizza chiavi Cloud KMS gestite dal cliente (CMEK), concedi al account di servizio di crittografia BigQuery (bq-PROJECT_NUMBER@bigquery-encryption.) il ruolo roles/cloudkms.cryptoKeyEncrypterDecrypter sulla chiave. La CMEK su un agente dati cripta la risorsa dell'agente, non la tabella di log (consulta Chiavi di crittografia gestite dal cliente).
- Controlli di servizio VPC: se utilizzi un perimetro di servizio, includi sia geminidataanalytics.googleapis.com sia bigquery.googleapis.com nel perimetro che contiene il progetto dell'agente. L'agente di servizio scrive nella tabella di log dall'infrastruttura gestita da Google, quindi se il perimetro limita bigquery.googleapis.com, aggiungi una regola in entrata come la seguente. Sostituisci PROJECT_NUMBER con il numero di progetto dell'agente:
```
- ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.
    sources:
    - accessLevel: "*"
  ingressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - permission: bigquery.tables.get
      - permission: bigquery.tables.create
      - permission: bigquery.tables.update
      - permission: bigquery.tables.updateData
    resources:
    - projects/PROJECT_NUMBER
```
  Per saperne di più, consulta Configura la sicurezza del perimetro con i Controlli di servizio VPC.
- Residenza dei dati: le righe di log e la tabella creata automaticamente vengono archiviate nella località del set di dati di log, in cui si applicano le policy dell'organizzazione relative alla località delle risorse (gcp.resourceLocations).

Limitazioni

Il logging delle conversazioni presenta le seguenti limitazioni:

Il riquadro Anteprima nell'editor degli agenti di BigQuery Studio non viene registrato.
Le conversazioni dirette senza un agente di dati non vengono registrate.
Gli agenti che utilizzano un ambito di ricerca anziché tabelle specifiche o che non dichiarano tabelle BigQuery non vengono registrati. Gli agenti che configurano i grafi delle proprietà di BigQuery come origini di conoscenza non vengono registrati.
L'SQL generato, le chiamate degli strumenti e gli eventi di richiesta o dello strumento Agent Development Kit (ADK) (TOOL_STARTING, TOOL_COMPLETED, TOOL_ERROR e LLM_REQUEST) non vengono registrati; vengono registrati solo la risposta e i nomi dei risultati dei dati e dei grafici. I turni con risposta diretta da una query verificata non scrivono righe LLM_RESPONSE e i turni con query verificata non riusciti non vengono registrati.
Il feedback degli utenti con Mi piace o Non mi piace non viene registrato.
I turni non vengono registrati se le fonti di conoscenza utilizzano policy di accesso alle righe, sicurezza a livello di colonna (tag di policy) o mascheramento dei dati oppure se il controllo della privacy non può essere completato. Il controllo non esamina le viste per trovare le tabelle sottostanti.
Sono supportati solo gli agenti delle tabelle BigQuery; le origini dati Looker, Data Studio, AlloyDB, Spanner e Cloud SQL non sono supportate.
Il set di dati di destinazione deve già esistere nello stesso progetto dell'agente.
Le modifiche allo schema delle tabelle esistenti sono solo additive; un tipo o una modalità di colonna in conflitto interrompe le scritture in quella tabella.
Ogni turno idoneo viene registrato senza un'impostazione di campionamento; campiona invece al momento della query (vedi Campiona domande e risposte di tutti gli agenti per la revisione).
La colonna agent contiene il tipo di agente anziché il nome visualizzato dell'agente; utilizza l'ID agente dati in attributes.
I chiamanti dell'API che utilizzano un account di servizio per molti utenti finali vedono l'indirizzo email dell'account di servizio in ogni riga.
I valori di testo più lunghi di 512.000 caratteri (500 * 1,024) vengono tagliati con il suffisso ...[TRUNCATED] e la parte rimossa non può essere recuperata.
Le scritture vengono eseguite secondo il principio del "best effort" con un numero limitato di nuovi tentativi. I turni che non vengono scritti non vengono registrati e i nuovi tentativi possono occasionalmente produrre righe duplicate (utilizza event_id per deduplicare).
Un agente non eredita l'impostazione di osservabilità a livello di progetto.

Prezzi

L'analisi conversazionale non addebita costi separati per il logging delle conversazioni. Il tuo progetto paga i prezzi standard di BigQuery per l'importazione dei dati dell'API BigQuery Storage Write (gRPC), l'archiviazione e le query di analisi. L'importazione dell'API BigQuery Storage Write (gRPC) include 2 TiB di utilizzo senza costi al mese per ogni account di fatturazione, condivisi tra l'utilizzo dell'API Storage Write (gRPC). Filtra le query su timestamp per ridurre i byte analizzati. Il controllo della privacy prima della rotazione legge i metadati della tabella ed esegue query dry run senza costi.