A API Análise conversacional permite ativar ou desativar o registro de conversas para um agente de dados e escolher a tabela do BigQuery que armazena os registros. Para analisar as perguntas dos usuários e as respostas do agente, consulte essa tabela.
Antes de começar
Antes de configurar a geração de registros de conversas para um agente de dados, conclua as seguintes tarefas:
- No seu Google Cloud projeto, ative as APIs necessárias para a API Análise conversacional e o BigQuery.
- Verifique se você tem os papéis necessários do Identity and Access Management (IAM).
- Verifique se você tem um agente de dados com fontes de dados que referenciam tabelas do BigQuery. Para configurações de agente que não são registradas, consulte Limitações.
- Planeje um conjunto de dados do BigQuery no projeto do agente de dados que contenha apenas os registros. Todos os agentes de dados no projeto compartilham um agente de serviço, e um conjunto de dados dedicado limita o acesso de gravação aos seus registros.
- Decida quem pode ler os registros. Os registros contêm as perguntas completas dos usuários e as respostas do agente. Se os usuários conversarem com o agente pelo seu próprio aplicativo, você será responsável por todos os avisos, divulgações ou consentimentos que se aplicam às conversas registradas. Para mais informações, consulte Privacidade, governança de dados e segurança.
Funções exigidas
Para receber as permissões necessárias para configurar a geração de registros de conversas de um agente de dados e consultar os registros, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Criar o conjunto de dados de registro:
Usuário do BigQuery (
roles/bigquery.user) no seu projeto -
Conceda ao agente de serviço acesso ao conjunto de dados de registro:
Proprietário de dados do BigQuery (
roles/bigquery.dataOwner) no conjunto de dados de registro -
Mudar as configurações de registro de conversas de um agente de dados:
Editor do agente de dados do Gemini Data Analytics (
roles/geminidataanalytics.dataAgentEditor) no agente de dados ou no projeto -
Consulte os registros:
- Visualizador de Dados do BigQuery (
roles/bigquery.dataViewer) no conjunto de dados de registro - Usuário de jobs do BigQuery (
roles/bigquery.jobUser) no seu projeto
- Visualizador de Dados do BigQuery (
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Se você criar o conjunto de dados de registro, receberá automaticamente o papel de proprietário de dados do BigQuery nele. Se você criou o agente de dados, recebe automaticamente
o papel de proprietário do agente de dados do Gemini Data Analytics
(roles/geminidataanalytics.dataAgentOwner), que inclui permissão para
mudar as configurações de registro de conversas.
Os usuários que conversam com o agente de dados não precisam de outros papéis para o registro de conversas. Se as conversas não forem registradas para alguns usuários, consulte Resolver problemas de registro de conversas.
Papel de agente de serviço
O agente de serviço da API Análise conversacional
(service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com)
grava os registros. Substitua PROJECT_NUMBER pelo número
do projeto que contém o agente de dados.
Para garantir que o agente de serviço da API Análise conversacional tenha as permissões necessárias para criar a tabela de registros e gravar registros de conversas nela, peça ao administrador para conceder o papel do IAM de Editor de dados do BigQuery (roles/bigquery.dataEditor) ao agente de serviço da API Análise conversacional no conjunto de dados de registros.
O administrador também pode conceder ao agente de serviço da API Análise conversacional as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Ativar a geração de registros de conversas
A geração de registros de conversas precisa de um conjunto de dados em que o agente de serviço possa gravar. Primeiro, crie o conjunto de dados e conceda acesso a ele. Depois, ative a geração de registros para o agente de dados.
Criar o conjunto de dados de registro
Crie um conjunto de dados no projeto do agente de dados para armazenar os registros. O agente de serviço
cria a tabela de registros nesse conjunto de dados na primeira rodada registrada. Para criar o conjunto de dados, use o comando bq mk --dataset na ferramenta de linha de comando bq. É possível executar comandos da ferramenta bq no
Cloud Shell ou em um terminal local em que a Google Cloud CLI
esteja instalada.
bq --location=LOCATION mk --dataset PROJECT_ID:LOG_DATASET
Substitua os valores de exemplo da seguinte forma:
- LOCATION: o local do BigQuery para o conjunto de dados de registro, como
US. - PROJECT_ID: o ID do projeto que contém o agente de dados.
- LOG_DATASET: o ID do conjunto de dados a ser criado.
Para outras maneiras de criar um conjunto de dados, consulte Criar conjuntos de dados.
Conceder ao agente de serviço acesso ao conjunto de dados
Conceda ao agente de serviço o papel de Editor de dados do BigQuery (roles/bigquery.dataEditor) apenas no conjunto de dados de registro.
Selecione uma das seguintes opções:
Console
No console do Google Cloud , acesse a página BigQuery.
No painel Explorer, expanda o projeto, clique em Conjuntos de dados e selecione o conjunto de dados de registro.
Clique em Compartilhar > Gerenciar permissões.
Clique em Adicionar principal.
No campo Novos principais, insira o endereço de e-mail do agente de serviço:
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.Substitua
PROJECT_NUMBERpelo número do projeto que contém o agente de dados.Na lista Selecionar um papel, selecione Editor de dados do BigQuery.
Clique em Salvar.
SQL
No editor de consultas do BigQuery, defina o local da consulta como o local do conjunto de dados de registro e execute a seguinte instrução GRANT:
GRANT `roles/bigquery.dataEditor`
ON SCHEMA `PROJECT_ID`.LOG_DATASET
TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com";
Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID: o ID do projeto que contém o agente de dados e o conjunto de dados de registro.
- LOG_DATASET: o ID do conjunto de dados de registro.
- PROJECT_NUMBER: o número do projeto que contém o agente de dados.
Para outras maneiras de conceder acesso, consulte Conceder acesso a um conjunto de dados. Se a concessão falhar porque o agente de serviço não existe, consulte A concessão de acesso ao conjunto de dados falha porque o agente de serviço não existe.
Ativar a geração de registros para o agente de dados
Para ativar a geração de registros em um agente de dados, defina os campos bigquery_agent_analytics_enabled e bigquery_agent_analytics_table do agente (bigqueryAgentAnalyticsEnabled e bigqueryAgentAnalyticsTable em solicitações HTTP) e inclua os dois campos na máscara de atualização. A atualização altera apenas
os campos na máscara de atualização. O agente de serviço grava linhas de registro somente quando você
ativa a geração de registros e define uma tabela de registros.
Execute os exemplos a seguir no ambiente do Python que você configurou em
Definir as configurações e inicializar
clientes
(SDK do Python) ou Definir as configurações iniciais e a
autenticação
(HTTP), como um notebook do Colaboratory. As amostras do SDK para Python nesta página
exigem a versão 0.13.4 ou mais recente do google-cloud-geminidataanalytics.
SDK do Python
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = True
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(
paths=["bigquery_agent_analytics_enabled", "bigquery_agent_analytics_table"]
)
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
Substitua os valores de exemplo da seguinte forma:
- DATA_AGENT_ID: o ID do agente de dados.
- LOG_DATASET: o ID do conjunto de dados de registro.
- LOG_TABLE: o ID da tabela de registros, como
agent_events. Se a tabela não existir, o agente de serviço vai criá-la na primeira vez que um turno for registrado.
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsEnabled": True,
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {
"updateMask": "bigqueryAgentAnalyticsEnabled,bigqueryAgentAnalyticsTable"
}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
if body.get("bigqueryAgentAnalyticsEnabled") and body.get(
"bigqueryAgentAnalyticsTable"
):
print("Conversation logging is turned on.")
else:
print("Logging isn't turned on. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Substitua os valores de exemplo da seguinte forma:
- DATA_AGENT_ID: o ID do agente de dados.
- LOG_DATASET: o ID do conjunto de dados de registro.
- LOG_TABLE: o ID da tabela de registros, como
agent_events. Se a tabela não existir, o agente de serviço vai criá-la na primeira vez que um turno for registrado.
O método retorna o agente de dados atualizado. Confirme se a geração de registros está ativada e se a tabela de registros está definida.
Para ativar a geração de registros ao criar um agente de dados, inclua os mesmos campos na solicitação de criação. Para a solicitação de criação, consulte Criar um agente de dados (SDK do Python ou HTTP). Em um corpo de solicitação HTTP, os campos são assim:
"bigqueryAgentAnalyticsEnabled": true,
"bigqueryAgentAnalyticsTable": {
"projectId": "PROJECT_ID",
"datasetId": "LOG_DATASET",
"tableId": "LOG_TABLE"
}
Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID: o ID do projeto que contém o agente de dados.
- LOG_DATASET: o ID do conjunto de dados de registro.
- LOG_TABLE: o ID da tabela de registros.
Verificar se as conversas são registradas
- Envie uma solicitação de chat para o agente de dados. Para ver exemplos, consulte Usar a API para fazer perguntas (SDK do Python ou HTTP).
Aguarde cerca de 10 segundos depois que o agente responder. Em seguida, no Cloud Shell ou em um terminal, execute o seguinte comando
bq querypara ver as perguntas e respostas recentes. Também é possível executar o SQL no editor de consultas do BigQuery.bq query --use_legacy_sql=false ' SELECT timestamp, event_type, JSON_VALUE(content, "$.text_summary") AS text FROM `PROJECT_ID.LOG_DATASET.LOG_TABLE` WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) AND event_type IN ("USER_MESSAGE_RECEIVED", "AGENT_RESPONSE") ORDER BY timestamp DESC LIMIT 20'Substitua os valores de exemplo da seguinte forma:
- PROJECT_ID: o ID do projeto que contém o agente de dados.
- LOG_DATASET: o ID do conjunto de dados de registro.
- LOG_TABLE: o ID da tabela de registros.
Se a consulta retornar sua pergunta e a resposta do agente, o registro de conversas está funcionando corretamente. Se a tabela não existir ou estiver vazia, consulte Resolver problemas de registro de conversas.
Mudar a tabela de destino
Para gravar registros em uma tabela diferente, atualize o campo bigquery_agent_analytics_table do agente de dados (bigqueryAgentAnalyticsTable em solicitações HTTP) e inclua o campo na máscara de atualização. A nova tabela precisa estar no
projeto do agente de dados, e o agente de serviço precisa ter o papel de Editor de dados do BigQuery
no conjunto de dados da nova tabela.
Execute o exemplo a seguir no mesmo ambiente de Ativar a geração de registros para o agente de dados.
SDK do Python
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_table"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
Substitua os valores de exemplo da seguinte forma:
- DATA_AGENT_ID: o ID do agente de dados.
- NEW_LOG_DATASET: o ID do novo conjunto de dados de registro.
- NEW_LOG_TABLE: o ID da nova tabela de registro.
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {"updateMask": "bigqueryAgentAnalyticsTable"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
table = body.get("bigqueryAgentAnalyticsTable", {})
if table.get("datasetId") == log_dataset and table.get("tableId") == log_table:
print("Log table updated.")
else:
print("The log table didn't change. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Substitua os valores de exemplo da seguinte forma:
- DATA_AGENT_ID: o ID do agente de dados.
- NEW_LOG_DATASET: o ID do novo conjunto de dados de registro.
- NEW_LOG_TABLE: o ID da nova tabela de registro.
As linhas que já foram registradas permanecem na tabela anterior. A mudança entra em vigor na próxima curva.
Desativar o registro de conversas
Para desativar o registro de conversas de um agente de dados, defina o campo bigquery_agent_analytics_enabled do agente (bigqueryAgentAnalyticsEnabled em solicitações HTTP) como false e inclua o campo na máscara de atualização.
Execute o exemplo a seguir no mesmo ambiente de Ativar a geração de registros para o agente de dados.
SDK do Python
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = False
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_enabled"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
except Exception as e:
print(f"Error updating data agent: {e}")
Substitua DATA_AGENT_ID pelo ID do agente de dados.
HTTP
data_agent_id = "DATA_AGENT_ID"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {"bigqueryAgentAnalyticsEnabled": False}
params = {"updateMask": "bigqueryAgentAnalyticsEnabled"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
print("Conversation logging is turned off.")
print(json.dumps(data_agent_response.json(), indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Substitua DATA_AGENT_ID pelo ID do agente de dados.
A mudança entra em vigor na próxima curva. Uma rodada que já está em execução é concluída com as configurações que estavam em vigor quando ela começou.
Para interromper a geração de registros de todos os agentes de dados que gravam em um conjunto de dados de registro, revogue o papel de Editor de dados do BigQuery do agente de serviço no conjunto de dados. A geração de registros permanece ativada para cada agente, mas o agente de serviço não pode mais gravar linhas.
A desativação do registro mantém as linhas que já foram registradas. Para remover dados registrados, exclua linhas, partições ou a tabela de registros.
Resolver problemas de registro de conversas
Use as informações a seguir para resolver problemas comuns com o registro de conversas da análise de conversação no BigQuery. Como os erros de geração de registros nunca interrompem uma conversa e não são informados no chat, na resposta da API ou no Cloud Logging, uma tabela de destino vazia ou ausente é o principal sinal de um problema de configuração ou permissão.
A tabela de registros está ausente ou vazia
Se a tabela de destino não for criada ou permanecer vazia após uma conversa, verifique as seguintes causas possíveis:
A geração de registros de conversas não está ativada. Confirme se a geração de registros de conversas está ativada e se a tabela de destino está configurada no agente de dados.
O conjunto de dados de destino está ausente ou em um projeto diferente. Confirme se o conjunto de dados de destino já existe no mesmo projeto que o agente de dados. Para verificar se o conjunto de dados existe, execute
bq show PROJECT_ID:LOG_DATASET. SubstituaPROJECT_IDpelo ID do projeto que contém o agente de dados eLOG_DATASETpelo ID do conjunto de dados de destino. O agente de serviço cria a tabela de registros na primeira vez que um registro é feito, mas não cria o conjunto de dados.O conjunto de dados de destino é somente leitura, como um conjunto de dados vinculado. Um conjunto de dados vinculado de BigQuery Sharing ou um conjunto de dados externo (por exemplo, um conjunto de dados federado do AWS Glue) é somente leitura e não pode armazenar registros de conversas. Para verificar o tipo de conjunto de dados, execute
bq show --format=prettyjson PROJECT_ID:LOG_DATASETe inspecione o campo"type"("LINKED"ou"EXTERNAL"). Escolha um conjunto de dados gravável padrão no mesmo projeto do agente de dados.Permissões do agente de serviço ou da CMEK ausentes. Confirme se o agente de serviço da API Análise conversacional (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com, usando o número do projeto do agente em vez do ID do projeto) tem o papel de Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados de registro. Se o conjunto de dados usar chaves do Cloud KMS gerenciadas pelo cliente (CMEK), confirme se a conta de serviço de criptografia do BigQuery (bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) tem o papelroles/cloudkms.cryptoKeyEncrypterDecrypterna chave.O perímetro do VPC Service Controls bloqueia gravações. O agente de serviço da API Análise conversacional grava na tabela de registros da infraestrutura gerenciada pelo Google. Portanto, conceder apenas
roles/bigquery.dataEditornão é suficiente quando um perímetro de serviço restringebigquery.googleapis.com. Ao contrário de outras causas nesta lista, um bloqueio de perímetro registra registros de auditoria de política negada no Cloud Logging no projeto do agente. Filtre porlog_id("cloudaudit.googleapis.com/policy")embigquery.googleapis.com(para pesquisa ou criação de tabelas) ebigquerystorage.googleapis.com(para anexos de linha) para confirmar o bloqueio. Confirme segeminidataanalytics.googleapis.comebigquery.googleapis.comestão no perímetro e adicione uma regra de entrada para o agente de serviço embigquery.googleapis.com. Para ver um exemplo de regra de entrada, consulte Controle de acesso, criptografia e segurança de rede. Para orientações gerais sobre a configuração de perímetros, consulte Configurar a segurança de perímetros com o VPC Service Controls.A plataforma de conversa ou a configuração do agente não é compatível. As conversas no painel de pré-lançamento do BigQuery Studio e as chamadas de API sem estado sem um agente de dados não são registradas. Para testar, envie uma solicitação de chat ao agente de dados pela API. Os agentes que usam um escopo de pesquisa em vez de tabelas específicas do BigQuery, que configuram apenas gráficos de propriedades do BigQuery (sem tabelas do BigQuery) como fontes de conhecimento ou que não declaram nenhuma tabela do BigQuery não são registrados. Saiba mais em Limitações.
As tabelas de fontes de conhecimento usam políticas de acesso. Se alguma tabela de fonte de conhecimento (uma tabela do BigQuery nas fontes de dados do agente) usar políticas de acesso no nível da 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.
Conflito de esquema em uma tabela de destino atual. Se você configurou uma tabela atual como destino e uma coluna tem o mesmo nome de uma coluna do esquema de registro de conversas, mas tem um tipo ou modo diferente, o BigQuery não grava linhas nessa tabela.
As linhas geralmente aparecem alguns segundos após a conclusão de uma rodada. Se as linhas ainda não aparecerem depois de alguns minutos, atualize o conjunto de dados.
As conversas de alguns usuários não são registradas
Causa
Antes de cada turno, a verificação de privacidade usa as credenciais do usuário que está conversando para verificar se as tabelas de fonte de conhecimento do agente não têm políticas de segurança no nível da linha, segurança no nível da coluna ou mascaramento de dados. Se um usuário não tiver permissão para executar essa verificação, as interações dele não serão registradas.
Resolução
Conceda a todos os usuários do chat o papel de Leitor de dados do BigQuery (roles/bigquery.dataViewer) nas tabelas de fonte de conhecimento e o papel de Usuário de jobs do BigQuery (roles/bigquery.jobUser) no projeto que executa as consultas ou conceda uma função personalizada com as permissões bigquery.tables.get e bigquery.rowAccessPolicies.list nas tabelas de fonte de conhecimento.
A criação ou atualização do agente falha com um erro INVALID_ARGUMENT
Mensagem de erro
The BigQuery Agent Analytics table must be in the same project as the agent (agent project: ..., table project: ...).BigQuery Agent Analytics can only be enabled on agents whose datasource is BigQuery. Remove bigquery_agent_analytics_enabled and bigquery_agent_analytics_table, or point the agent at a BigQuery datasource.
Causa
O conjunto de dados de destino está em um projeto diferente do agente de dados ou a fonte de dados do agente não é o BigQuery.
Resolução
Especifique um conjunto de dados de destino no mesmo projeto do agente de dados ou configure o agente de dados com uma fonte de dados do BigQuery.
A concessão de acesso ao conjunto de dados falha porque o agente de serviço não existe
Mensagem de erro
Service account service-PROJECT_NUMBER@gcp-sa-geminidataanalytics... does not exist
Causa
O agente de serviço da API Conversational Analytics ainda não foi provisionado no projeto.
Resolução
Escolha uma destas opções:
Configure o destino do registro no agente primeiro e, em seguida, conceda o papel novamente.
Provisione a identidade de serviço executando o seguinte comando:
gcloud beta services identity create \ --service=geminidataanalytics.googleapis.com \ --project=PROJECT_ID
Substitua
PROJECT_IDpelo ID do projeto que contém o agente de dados.
A seguir
- Analise o esquema do registro de conversas.
- Analisar registros de conversas.
- Analise a segurança, a privacidade, o risco e a conformidade da API de Análise conversacional.
- Configure a geração de registros de conversas no BigQuery Studio.