A geração de registros de conversas permite gravar os dados de um agente de dados da API Análise conversacional em uma tabela do BigQuery no seu projeto para analisar a qualidade das respostas, acompanhar a adoção e monitorar os custos. Para cada turno, o registro captura a pergunta do usuário,
a resposta do agente, a latência, o uso de tokens do modelo e os identificadores necessários
para agrupar os turnos por agente, conversa e usuário. As linhas são gravadas usando
o esquema de análise de agentes do
BigQuery por meio da
API BigQuery Storage Write (gRPC). É possível
ativar a geração de registros para um agente de dados cujas fontes de dados referenciam
tabelas do BigQuery definindo os campos bigqueryAgentAnalyticsEnabled
e bigqueryAgentAnalyticsTable. Para ver as etapas, consulte Ativar a geração de registros de
conversas.
O que é registrado
Cada turno registrado grava várias linhas de evento (events) na tabela de destino que registram as seguintes informações:
A pergunta do usuário.
A resposta do agente: o texto, os insights, as suposições, as perguntas de acompanhamento sugeridas, as fontes de citação e os nomes de todos os resultados de dados ou gráficos.
Latência por turno.
Uso de tokens do modelo, versão do modelo e motivo de conclusão (por que o modelo parou de gerar tokens) para cada chamada de modelo.
O ID do agente de dados e o ID da conversa (para chat com uma referência de conversa), para que você possa analisar vários agentes em uma tabela.
Um identificador de usuário. Para mais informações sobre identificadores de usuário, consulte Identidade do usuário.
Detalhes de status e erro.
O que não é registrado
A geração de registros de conversas não registra o seguinte:
As consultas SQL executadas pelo agente: o registro contém a resposta final e os nomes dos resultados de dados e gráficos referenciados, mas não as consultas que os produziram. A exceção é quando um usuário pede explicitamente ao agente para mostrar ou explicar o SQL. Nesse caso, o SQL pode aparecer no texto da resposta.
As chamadas de ferramenta do agente: cada chamada de modelo grava uma linha
LLM_RESPONSE, incluindo chamadas em que o modelo decide executar uma ferramenta. Antes de a linha ser gravada, a saída do modelo é removida, incluindo o nome e os argumentos de qualquer ferramenta que ele tenha chamado. Somente o uso de tokens, a versão do modelo e o motivo da conclusão são mantidos.Feedback do usuário: o feedback de "Gostei" ou "Não gostei" não é registrado.
Algumas conversas não são registradas, como chamadas de API sem estado sem um agente de dados. Para mais informações sobre plataformas de conversa não compatíveis, consulte Limitações.
Como funciona a geração de registros de conversas
Quando um usuário conversa com um agente de dados que tem a geração de registros de conversas ativada, a Análise conversacional processa cada turno pelas seguintes etapas:
Configurar: o proprietário de um agente ativa a geração de registros de conversas e especifica um conjunto de dados de destino e um nome de tabela no projeto do agente usando a API Análise conversacional.
Perguntar: um usuário envia uma pergunta ao agente. Se você chamar a API de Análise conversacional do seu próprio aplicativo, será responsável por informar os usuários. Os usuários que conversam com o agente no BigQuery Studio recebem um aviso de que as conversas são registradas.
Verificação de privacidade: antes de o agente começar a trabalhar na vez, uma verificação de privacidade lê os metadados das tabelas de fonte de conhecimento do agente (as fontes de dados do BigQuery) usando as credenciais do usuário que está conversando. Essa verificação confirma que nenhuma das tabelas usa segurança no nível da linha (políticas de acesso à linha), segurança no nível da coluna (tags de política) ou mascaramento de dados dinâmicos. Se a verificação encontrar uma política ou não puder confirmar que não há nenhuma, a vez não será registrada, e o agente ainda responderá à pergunta do usuário.
Responder: o agente responde ao usuário normalmente.
Gravação: o agente de serviço da API Análise conversacional do projeto (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) grava as linhas de registro na tabela de destino usando a API Storage Write (gRPC). Na primeira vez que um turno é registrado, o agente de serviço cria a tabela, caso ela ainda não exista.Consulta: as linhas geralmente aparecem alguns segundos após a conclusão da resposta. O tempo de entrega não é garantido.
Os erros de registro nunca causam falhas em uma vez, e a verificação de privacidade e a gravação de registros podem adicionar latência. Uma permissão ausente no conjunto de dados de registro, um conjunto de dados que não existe ou uma cota esgotada não faz com que a solicitação de chat ou a chamada de API falhe. A Análise conversacional não informa falhas de geração de registros na interface do chat, na resposta da API ou no Cloud Logging.
Privacidade, governança de dados e segurança
Ao ativar o registro de conversas para um agente, analise como os avisos do usuário final, o acesso a dados, a criptografia, os controles de rede e o registro de auditoria se aplicam aos seus registros.
Avisos para usuários finais e conteúdo registrado
Os seguintes avisos e regras regem o que o registro de conversas registra e quem pode ver os dados registrados:
Aviso ao usuário final no BigQuery Studio: quando o registro de conversas está ativado para um agente, os usuários que conversam com ele no BigQuery Studio recebem o seguinte aviso, inclusive na tela de nova conversa antes que o usuário envie um primeiro comando:
Todos os comandos e respostas são registrados no BigQuery e podem ser acessados por usuários com permissões de conjunto de dados.
Suas responsabilidades ao usar a API: se você ativar o registro de conversas (registro de rastreamento) em um agente de dados e disponibilizar esse agente para os usuários finais pelo seu próprio aplicativo ou integração, o Google não poderá mostrar um aviso a esses usuários. Você é responsável por todos os avisos, divulgações ou consentimentos que se aplicam às conversas registradas de acordo com a legislação aplicável e seus contratos com os usuários finais. Para mais informações, consulte Segurança, privacidade, risco e compliance da API Análise conversacional.
O que o registro contém e quem pode acessá-lo: a tabela de destino armazena conteúdo de perguntas e respostas de acordo com estas regras de privacidade:
Perguntas e respostas completas: as respostas podem incluir valores retornados das suas fontes de conhecimento. Qualquer pessoa que possa ler a tabela de registros pode ver os dados que o agente retornou a um usuário, incluindo dados que não podem ser lidos nas tabelas de origem. Conceda acesso de leitura ao conjunto de dados de registro apenas para as pessoas que devem ver esse conteúdo.
Identificadores de usuário e local de gravação: a coluna
user_ididentifica o autor da chamada que fez a pergunta (consulte Identidade do usuário), e as linhas são gravadas apenas no destino configurado no projeto do agente.Tabelas com segurança no nível da linha, segurança no nível da coluna ou mascaramento de dados: se as fontes de conhecimento de um agente usarem segurança no nível da linha (políticas de acesso de linha), segurança no nível da coluna (tags de política) ou mascaramento de dados dinâmicos, as interações não serão registradas. A verificação de privacidade ignora as tabelas em
bigquery-public-datae analisa apenas as tabelas e visualizações que você seleciona como fontes de conhecimento, não as tabelas por trás de uma visualização:Uma visualização em uma tabela que usa essas políticas pode passar na verificação, para que as interações dela sejam registradas. Antes de ativar a geração de registros, verifique se as tabelas por trás das visualizações não usam políticas de acesso de linha, tags de política ou mascaramento de dados.
Se você adicionar uma dessas políticas a uma tabela de origem mais tarde, as linhas que já foram registradas vão permanecer na tabela de registros. Se a política de retenção ou governança proibir a manutenção dessas linhas, exclua-as.
Controle de acesso, criptografia e segurança de rede
É possível gerenciar a retenção, o acesso, a criptografia e a segurança do perímetro dos registros de conversa usando as seguintes configurações:
Retenção e controle de acesso no conjunto de dados de registro: configure a retenção, os papéis do conjunto de dados, as políticas de tabela e os registros de auditoria para a tabela de destino:
Retenção: o Google não exclui linhas de registro. Defina uma expiração de partição no conjunto de dados ou na tabela de registros que corresponda à sua política (por exemplo, 90 dias).
Privilégio mínimo: mantenha o conjunto de dados de registro separado dos outros conjuntos de dados para que o acesso de gravação do agente de serviço compartilhado da API Análise conversacional fique longe das outras tabelas. Conceda aos analistas
roles/bigquery.dataViewerno conjunto de dados de registro ou dê a eles acesso apenas a visualizações autorizadas ou conjuntos de dados autorizados.Controles no nível da coluna e da linha na tabela de registros: é possível aplicar tags de política, mascaramento de dados ou políticas de acesso à linha à própria tabela de registros, como em
contentouuser_id. Esses controles de tabela de registros não afetam a verificação de privacidade da fonte de conhecimento.Registro de auditoria: as mudanças na configuração do agente de dados e as operações da tabela de registros são registradas nos registros de auditoria. Para mais informações, consulte Operações auditadas.
CMEK, VPC Service Controls e residência de dados: os seguintes controles de criptografia, perímetro e localização se aplicam à geração de registros de conversas:
CMEK: se o conjunto de dados de registro usar chaves do Cloud KMS gerenciadas pelo cliente (CMEK), conceda à conta de serviço de criptografia do BigQuery (
bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) o papelroles/cloudkms.cryptoKeyEncrypterDecrypterna chave. A CMEK em um agente de dados criptografa o recurso do agente, não a tabela de registros (consulte Chaves de criptografia gerenciadas pelo cliente).VPC Service Controls: se você usar um perímetro de serviço, inclua
geminidataanalytics.googleapis.comebigquery.googleapis.comno perímetro que contém o projeto do agente. O agente de serviço grava na tabela de registros da infraestrutura gerenciada pelo Google. Portanto, se o perímetro restringirbigquery.googleapis.com, adicione uma regra de entrada como esta. SubstituaPROJECT_NUMBERpelo número do projeto do 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_NUMBERPara mais informações, consulte Configurar a segurança do perímetro com o VPC Service Controls.
Residência de dados: as linhas de registro e a tabela criada automaticamente são armazenadas no local do conjunto de dados de registro, onde as políticas da organização de local de recursos (
gcp.resourceLocations) são aplicadas.
Atribuição de agente de serviço e autor da chamada
O agente de serviço da API Análise conversacional, e não o usuário que está conversando, cria e atualiza a tabela de registros e adiciona linhas a ela. Para realizar essas operações, o agente de serviço precisa do papel de Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados de registro.
Nas entradas de registro de auditoria que os Registros de auditoria do Cloud registram, o campo authenticationInfo.principalEmail (ou authenticationInfo.principalSubject para identidades federadas) identifica o principal que realizou cada operação:
Registrar a criação de tabelas, as atualizações de esquema e as adições de linhas: o agente de serviço,
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.Solicitações de configuração do agente de dados (
CreateDataAgent,CreateDataAgentSync,UpdateDataAgenteUpdateDataAgentSync): o usuário, a conta de serviço ou a identidade federada que chama a API. Quando as credenciais da conta de serviço delegada se aplicam, essas entradas também incluemauthenticationInfo.serviceAccountDelegationInfo.
Operações auditadas
Os Registros de auditoria do Cloud registram as alterações na configuração de registro de conversas e as operações da tabela de registros para os seguintes serviços:
API de Análise conversacional: os métodos a seguir geram registros de auditoria em
geminidataanalytics.googleapis.com:CreateDataAgent,CreateDataAgentSync,UpdateDataAgenteUpdateDataAgentSyncgeram registros de auditoria de atividade do administrador que registram os camposbigqueryAgentAnalyticsEnabledebigqueryAgentAnalyticsTablede um agente, incluindo o projeto, o conjunto de dados e a tabela de destino.O
SetAgentOpsObservabilitygera registros de auditoria de atividade do administrador que registram os camposdataSourceType,telemetryEnabled,bqaaEnabledeupdateMaskda solicitação.O
RetrieveAgentOpsObservabilitygera registros de auditoria de acesso a dados quando o tipo de registro de auditoriaADMIN_READouDATA_READcorrespondente está ativado parageminidataanalytics.googleapis.com.
BigQuery: as operações do agente de serviço na tabela de registros e as consultas executadas nela geram os seguintes registros de auditoria:
A criação de tabelas de registros e as atualizações de esquema geram registros de auditoria de atividades do administrador em
bigquery.googleapis.com.As adições de linhas ao final pela API Storage Write (gRPC) geram registros de auditoria de acesso a dados para o método
google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows, incluindo metadadosTableDataChange(WRITE_API_APPEND_ROWS). Essas entradas usam o nome de serviçobigquery.googleapis.com, nãobigquerystorage.googleapis.com. Somente os registros de auditoria de política negada usambigquerystorage.googleapis.com.As consultas na tabela de registros geram registros de auditoria de acesso a dados em
bigquery.googleapis.com, como entradasJobInsertion,JobChangeeTableDataRead.
Para mais informações, consulte Registro de auditoria da API Análise conversacional e Visão geral dos registros de auditoria do BigQuery.
Limitações
A geração de registros de conversas tem as seguintes limitações:
O painel Visualização no editor de agentes do BigQuery Studio não é registrado.
As chamadas de API sem estado sem um agente de dados não são registradas.
Os agentes que usam um escopo de pesquisa em vez de tabelas específicas ou que não declaram tabelas do BigQuery não são registrados. Os agentes que configuram apenas gráficos de propriedades do BigQuery (sem tabelas do BigQuery) como fontes de conhecimento não são registrados.
O SQL gerado, as chamadas de ferramentas e os eventos de ferramentas ou solicitações do Kit de Desenvolvimento de Agente (ADK) (
TOOL_STARTING,TOOL_COMPLETED,TOOL_ERROReLLM_REQUEST) não são registrados. Somente a resposta e os nomes dos resultados de dados e gráficos são registrados. As interações respondidas diretamente de uma consulta verificada não gravam linhasLLM_RESPONSE, e as interações de consulta verificada com falha não são registradas.O feedback do usuário com Gostei ou Não gostei não é registrado.
As interações não serão registradas se as fontes de conhecimento usarem políticas de acesso por linha, segurança no nível da coluna (tags de política) ou mascaramento de dados, incluindo políticas de dados anexadas diretamente às colunas. As interações também não serão registradas se a verificação de privacidade não puder verificar essas políticas, como quando o usuário do chat não tiver permissão para inspecionar os metadados da política de uma tabela ou se a verificação expirar. A verificação não analisa as visualizações para as tabelas por trás delas.
Somente agentes de tabela do BigQuery são compatíveis. As fontes de dados do Looker, Data Studio, AlloyDB para PostgreSQL, Spanner e Cloud SQL não são compatíveis.
O conjunto de dados de destino já precisa existir no mesmo projeto que o agente.
As alterações de esquema em tabelas atuais são apenas aditivas. Um tipo ou modo de coluna conflitante interrompe as gravações nessa tabela.
Cada turno qualificado é registrado sem uma configuração de amostragem. Em vez disso, faça a amostragem no momento da consulta (consulte Exemplo de perguntas e respostas em todos os agentes para análise).
A coluna
agentcontém o tipo de agente, não o nome de exibição dele. Use o ID do agente de dados emattributes.Os autores de chamadas de API que usam uma conta de serviço para muitos usuários finais veem o e-mail dessa conta de serviço em todas as linhas.
Os valores de texto com mais de 512.000 caracteres (
500 * 1,024) são cortados com o sufixo...[TRUNCATED], e a parte removida não pode ser recuperada.As gravações são feitas com o melhor esforço e novas tentativas limitadas. As rodadas que não são gravadas não são registradas, e as novas tentativas podem, ocasionalmente, produzir linhas duplicadas (use
event_idpara eliminar duplicações).Um agente não herda a configuração de observabilidade para envolvidos no projeto.
Preços
A Análise conversacional não cobra separadamente pela geração de registros de conversas.
Seu projeto paga os preços padrão do BigQuery para
ingestão de dados da API Storage Write (gRPC) do BigQuery,
armazenamento e consultas de análise. A ingestão da API BigQuery Storage Write (gRPC)
inclui 2 TiB de uso sem custo financeiro por mês para cada conta de faturamento, compartilhados entre o uso da API Storage Write (gRPC). Filtre consultas em
timestamp para reduzir os bytes verificados. A verificação de privacidade pré-execução lê os metadados da tabela e executa consultas de simulação sem custos financeiros.
A seguir
- Configure a geração de registros de conversas.
- Analise o esquema do registro de conversas.
- Analisar registros de conversas.