Panoramica del logging delle conversazioni

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:

  1. 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.

  2. 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.

  3. 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.

  4. Risposta: l'agente risponde all'utente come di consueto.

  5. 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à.

  6. 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_id identifica 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-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 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.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 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 ruolo roles/cloudkms.cryptoKeyEncrypterDecrypter sulla 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.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.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_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).

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, UpdateDataAgent e UpdateDataAgentSync): 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 anche authenticationInfo.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, UpdateDataAgent e UpdateDataAgentSync generano audit log delle attività di amministrazione che registrano i campi bigqueryAgentAnalyticsEnabled e bigqueryAgentAnalyticsTable di un agente, inclusi il progetto, il set di dati e la tabella di destinazione.

    • SetAgentOpsObservability genera audit log delle attività di amministrazione che registrano i campi dataSourceType, telemetryEnabled, bqaaEnabled e updateMask della richiesta.

    • RetrieveAgentOpsObservability genera log di controllo dell'accesso ai dati quando il tipo di log di controllo ADMIN_READ o DATA_READ corrispondente è abilitato per geminidataanalytics.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 metadati TableDataChange (WRITE_API_APPEND_ROWS). Queste voci utilizzano il nome del servizio bigquery.googleapis.com, non bigquerystorage.googleapis.com; solo gli audit log di Policy Denied utilizzano bigquerystorage.googleapis.com.

    • Le query sulla tabella di log generano log di controllo dell'accesso ai dati in bigquery.googleapis.com, ad esempio le voci JobInsertion, JobChange e TableDataRead.

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_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, 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 agent contiene il tipo di agente anziché il nome visualizzato dell'agente; utilizza l'ID dell'agente per i dati in attributes.

  • 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_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 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