Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Visão geral da geração de registros de conversas

Com o registro de conversas da análise conversacional, é possível registrar as conversas de um agente de dados em uma tabela do BigQuery no seu projeto para analisar a qualidade das respostas, acompanhar a adoção e monitorar os custos em todos os seus agentes de análise conversacional. 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).

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 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 que a linha seja 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 as que ocorrem no painel de prévia do BigQuery Studio. Para mais informações sobre plataformas de conversa sem suporte, consulte Limitações.

Como funciona a geração de registros de conversas

Quando um usuário conversa com um agente de dados que tem o registro de conversas ativado, a análise de conversas processa cada turno pelas seguintes etapas:

Configurar: o proprietário de um agente ativa a geração de registros de conversas e seleciona um conjunto de dados de destino e um nome de tabela no projeto do agente no BigQuery Studio.
Perguntar: um usuário envia uma pergunta ao agente. No BigQuery Studio, os usuários 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 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 Conversational Analytics do projeto (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.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 rodada, 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 falhe. A análise de conversação não informa falhas de registro na interface do chat ou no Cloud Logging.

Privacidade, governança de dados e segurança

Ao ativar a geração de registros de conversas para um agente, analise como os avisos ao usuário final, o acesso aos dados, a criptografia e os controles de rede 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 Conversational Analytics.
O que o registro contém e quem pode vê-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_id identifica o autor da 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-data e 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 possam ser 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 Conversational Analytics fique longe das outras tabelas. Conceda aos analistas roles/bigquery.dataViewer no 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 de linha à própria tabela de registros, como em content ou user_id. Esses controles de tabela de registros não afetam a verificação de privacidade da fonte de conhecimento.
- Registro de auditoria: as alterações em um agente de dados são registradas nos registros de auditoria de atividades do administrador. Nos registros de auditoria do BigQuery, a criação de tabelas e as atualizações de metadados pelo agente de serviço são registradas em bigquery.googleapis.com, e as adições de linhas pela API Storage Write (gRPC) são registradas em bigquerystorage.googleapis.com.
CMEK, VPC Service Controls e residência de dados: os seguintes controles de criptografia, perímetro e local 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.s3ns-system.iam.gserviceaccount.com) o papel roles/cloudkms.cryptoKeyEncrypterDecrypter na 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.com e bigquery.googleapis.com no 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 restringir bigquery.googleapis.com, adicione uma regra de entrada como a seguinte. Substitua PROJECT_NUMBER pelo número do projeto do agente:
```
- ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.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
```
  Para 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.

Limitações

A geração de registros de conversas tem as seguintes limitações:

O painel Prévia no editor de agentes do BigQuery Studio não é registrado.
As conversas diretas 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 gráficos de propriedades 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_ERROR e LLM_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 linhas LLM_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, ou se a verificação de privacidade não puder ser concluída. A verificação não analisa as visualizações das tabelas por trás delas.
Somente agentes de tabela do BigQuery são compatíveis. As fontes de dados do Looker, Data Studio, AlloyDB, 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 Amostra de perguntas e respostas de todos os agentes para análise).
A coluna agent contém o tipo de agente, e não o nome de exibição dele. Use o ID do agente de dados em attributes.
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 com 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_id para 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 BigQuery Storage Write (gRPC), 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.