Configurar a geração de registros de conversas

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:

  1. No seu Google Cloud projeto, ative as APIs necessárias para a API Análise conversacional e o BigQuery.
  2. Verifique se você tem os papéis necessários do Identity and Access Management (IAM).
  3. 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.
  4. 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.
  5. 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:

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

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No painel Explorer, expanda o projeto, clique em Conjuntos de dados e selecione o conjunto de dados de registro.

  3. Clique em Compartilhar > Gerenciar permissões.

  4. Clique em Adicionar principal.

  5. No campo Novos principais, insira o endereço de e-mail do agente de serviço: service-PROJECT_NUMBER@gcp-sa-geminidataanalytics..

    Substitua PROJECT_NUMBER pelo número do projeto que contém o agente de dados.

  6. Na lista Selecionar um papel, selecione Editor de dados do BigQuery.

  7. 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.";

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

  1. 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).
  2. Aguarde cerca de 10 segundos depois que o agente responder. Em seguida, no Cloud Shell ou em um terminal, execute o seguinte comando bq query para 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. Substitua PROJECT_ID pelo ID do projeto que contém o agente de dados e LOG_DATASET pelo 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_DATASET e 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., 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.) tem o papel roles/cloudkms.cryptoKeyEncrypterDecrypter na 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.dataEditor não é suficiente quando um perímetro de serviço restringe bigquery.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 por log_id("cloudaudit.googleapis.com/policy") em bigquery.googleapis.com (para pesquisa ou criação de tabelas) e bigquerystorage.googleapis.com (para anexos de linha) para confirmar o bloqueio. Confirme se geminidataanalytics.googleapis.com e bigquery.googleapis.com estão no perímetro e adicione uma regra de entrada para o agente de serviço em bigquery.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_ID pelo ID do projeto que contém o agente de dados.

A seguir