Il logging delle conversazioni ti consente di registrare le conversazioni di un agente per i dati dell'API Analisi conversazionale in una tabella BigQuery nel tuo progetto, in modo da poter esaminare la qualità delle risposte, monitorare l'adozione e controllare i costi. 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). Puoi attivare il logging per un agente per i dati le cui origini dati fanno riferimento alle tabelle BigQuery impostando i campi bigqueryAgentAnalyticsEnabled e bigqueryAgentAnalyticsTable. Per i passaggi, consulta Attiva il logging delle conversazioni.
Che cosa viene registrato
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 per i dati e l'ID conversazione (per la chat con un riferimento alla conversazione), in modo da poter analizzare più agenti in un'unica tabella.
Un identificatore dell'utente. Per saperne di più sugli identificatori dell'utente, 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 dei dati e dei grafici 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.
Le chiamate allo strumento dell'agente: ogni chiamata al 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 di fine.Feedback degli utenti: i feedback Mi piace o Non mi piace non vengono registrati.
Alcune conversazioni non vengono registrate affatto, ad esempio le chiamate API stateless senza un agente per i dati. 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 per i dati per cui è abilitata la registrazione delle conversazioni, l'analisi conversazionale elabora ogni turno attraverso le seguenti fasi:
Configurazione: un proprietario dell'agente attiva il logging delle conversazioni e specifica un set di dati di destinazione esistente e un nome della tabella nel progetto dell'agente utilizzando l'API Analisi conversazionale.
Domanda: un utente invia una domanda all'agente. Se chiami l'API Analisi conversazionale dalla tua applicazione, è tua responsabilità informare gli utenti. Gli utenti che chattano con l'agente in BigQuery Studio 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 fonti di conoscenza dell'agente (le sue origini dati BigQuery) 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 Analisi conversazionale del progetto (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) 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 un errore del 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 o della chiamata API. L'analisi conversazionale non segnala gli errori di logging nell'interfaccia di chat, nella risposta dell'API o in Cloud Logging.
Privacy, governance dei dati e sicurezza
Quando abiliti il logging delle conversazioni per un agente, esamina in che modo le notifiche per gli utenti finali, l'accesso ai dati, la crittografia, i controlli di rete e l'audit logging 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 per i 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 avvisi, 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 Analisi conversazionale.
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_ididentifica il chiamante che ha posto la domanda (consulta 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-datae 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 la tua policy di conservazione o governance vieta 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 Analisi conversazionale condiviso rimanga lontano dalle altre tabelle. Concedi agli analisti
roles/bigquery.dataViewersul 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
contentouser_id. Questi controlli della tabella di log non influiscono sul controllo della privacy delle fonti di conoscenza.Audit logging: le modifiche alla configurazione dell'agente per i dati e le operazioni sulle tabelle di log vengono registrate negli audit log. Per saperne di più, consulta Operazioni controllate.
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.iam.gserviceaccount.com) il ruoloroles/cloudkms.cryptoKeyEncrypterDecryptersulla chiave. La CMEK su un agente per i 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.comsiabigquery.googleapis.comnel 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 limitabigquery.googleapis.com, aggiungi una regola in entrata come la seguente. SostituisciPROJECT_NUMBERcon il numero di progetto dell'agente:- ingressFrom: identities: - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com 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_NUMBERPer 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).
Attribuzione dell'agente di servizio e del chiamante
L'agente di servizio dell'API Analisi conversazionale, non l'utente che chatta, crea e aggiorna la tabella di log e vi aggiunge righe. Per eseguire queste operazioni, l'agente di servizio deve avere il ruolo BigQuery Data Editor (roles/bigquery.dataEditor) nel set di dati di log.
Nelle voci di log degli audit log registrate da Cloud Audit Logs, il campo authenticationInfo.principalEmail (o authenticationInfo.principalSubject per le identità federate) identifica l'entità che ha eseguito ogni operazione:
Creazione di tabelle di log, aggiornamenti dello schema e aggiunte di righe: l'agente di servizio,
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.Richieste di configurazione dell'agente per i dati (
CreateDataAgent,CreateDataAgentSync,UpdateDataAgenteUpdateDataAgentSync): l'utente, il account di servizio o l'identità federata che chiama l'API. Quando vengono applicate le credenziali dell'account di servizio delegato, queste voci includono ancheauthenticationInfo.serviceAccountDelegationInfo.
Operazioni con audit
Cloud Audit Logs registra le modifiche alla configurazione del logging delle conversazioni e le operazioni sulle tabelle di log per i seguenti servizi:
API Analisi conversazionale: i seguenti metodi generano log di controllo in
geminidataanalytics.googleapis.com:CreateDataAgent,CreateDataAgentSync,UpdateDataAgenteUpdateDataAgentSyncgenerano audit log delle attività di amministrazione che registrano i campibigqueryAgentAnalyticsEnabledebigqueryAgentAnalyticsTabledi un agente, inclusi il progetto, il set di dati e la tabella di destinazione.SetAgentOpsObservabilitygenera audit log delle attività di amministrazione che registrano i campidataSourceType,telemetryEnabled,bqaaEnabledeupdateMaskdella richiesta.RetrieveAgentOpsObservabilitygenera log di controllo dell'accesso ai dati quando il tipo di log di controlloADMIN_READoDATA_READcorrispondente è abilitato pergeminidataanalytics.googleapis.com.
BigQuery: le operazioni dell'agente di servizio sulla tabella dei log e le query eseguite su di essa generano i seguenti audit log:
La creazione di tabelle di log e gli aggiornamenti dello schema generano audit log delle attività di amministrazione in
bigquery.googleapis.com.Le aggiunte di righe tramite l'API Storage Write (gRPC) generano audit log di accesso ai dati per il metodo
google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows, inclusi i metadatiTableDataChange(WRITE_API_APPEND_ROWS). Queste voci utilizzano il nome del serviziobigquery.googleapis.com, nonbigquerystorage.googleapis.com; solo gli audit log di Policy Denied utilizzanobigquerystorage.googleapis.com.Le query sulla tabella di log generano log di controllo dell'accesso ai dati in
bigquery.googleapis.com, ad esempio le vociJobInsertion,JobChangeeTableDataRead.
Per saperne di più, consulta Audit logging dell'API Analisi conversazionale e Panoramica degli audit log di BigQuery.
Limitazioni
Il logging delle conversazioni presenta le seguenti limitazioni:
Il riquadro Anteprima nell'editor degli agenti di BigQuery Studio non viene registrato.
Le chiamate API stateless senza un agente per i 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 solo i grafi delle proprietà BigQuery (senza tabelle BigQuery) come origini di conoscenza non vengono registrati.
SQL generato, chiamate allo strumento ed eventi di richiesta o strumento dell'Agent Development Kit (ADK) (
TOOL_STARTING,TOOL_COMPLETED,TOOL_ERROReLLM_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 righeLLM_RESPONSEe 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, incluse le policy dei dati associate direttamente alle colonne. I turni non vengono registrati nemmeno se il controllo della privacy non riesce a verificare queste policy, ad esempio quando l'utente che chatta non dispone dell'autorizzazione per ispezionare i metadati delle policy di una tabella o se il controllo va in timeout. Il controllo non esamina le viste per trovare le tabelle sottostanti.
Sono supportati solo gli agenti di tabelle BigQuery; le origini dati Looker, Data Studio, AlloyDB per PostgreSQL, 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; il campionamento viene eseguito al momento della query (consulta Campiona domande e risposte di tutti gli agenti per la revisione).
La colonna
agentcontiene il tipo di agente anziché il nome visualizzato dell'agente; utilizza l'ID dell'agente per i dati inattributes.I chiamanti 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 tentativi; i turni che non vengono scritti non vengono registrati e i tentativi possono occasionalmente produrre righe duplicate (utilizza
event_idper 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 con l'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.
Passaggi successivi
- Configura il logging delle conversazioni.
- Esplora lo schema del log delle conversazioni.
- Analizza i log delle conversazioni.