配置对话日志记录

借助对话式分析 API,您可以为数据智能体开启或关闭对话日志记录,并选择用于存储其日志的 BigQuery 表。如需查看用户的问题和代理的回答,请查询该表。

准备工作

在为数据智能体配置对话日志记录之前,请完成以下任务:

  1. 在 Google Cloud 项目中,启用 Conversational Analytics API 和 BigQuery 所需的 API。
  2. 验证您是否具有所需的 Identity and Access Management (IAM) 角色。
  3. 确保您有一个数据智能体,其数据源引用了 BigQuery 表。如需了解未记录的代理配置,请参阅限制。
  4. 在数据智能体的项目中规划一个仅包含日志的 BigQuery 数据集。项目中的所有数据智能体都共享一个服务代理,而专用数据集会限制其对日志的写入权限。
  5. 决定哪些人可以读取日志。这些日志包含用户的完整问题和智能体的回答。如果用户通过您自己的应用与代理聊天,您需要负责提供适用于记录的对话的任何通知、披露信息或征得用户同意。如需了解详情,请参阅隐私、数据治理和安全。

所需的角色

如需获得为数据智能体配置对话日志记录和查询日志所需的权限,请让您的管理员为您授予以下 IAM 角色:

  • 创建日志数据集:针对项目的 BigQuery User (roles/bigquery.user) 角色
  • 向服务代理授予对日志数据集的访问权限:针对日志数据集的 BigQuery Data Owner (roles/bigquery.dataOwner) 角色
  • 更改数据智能体的对话日志记录设置:针对数据智能体或项目的 Gemini 数据分析 Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) 角色
  • 查询日志:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如果您创建了日志数据集,系统会自动为您授予该数据集的 BigQuery Data Owner 角色。如果您创建了数据代理,系统会自动向您授予该代理的 Gemini Data Analytics Data Agent Owner 角色 (roles/geminidataanalytics.dataAgentOwner),该角色包含更改其对话日志记录设置的权限。

与数据智能体聊天的用户无需额外角色即可进行对话日志记录。如果系统未记录某些用户的对话,请参阅排查对话记录问题。

服务代理角色

对话式分析 API 服务代理 (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) 会写入日志。将 PROJECT_NUMBER 替换为包含数据智能体的项目的编号。

为确保对话式分析 API 服务代理具有创建日志表并将对话日志写入该表所需的权限,请让管理员为对话式分析 API 服务代理授予日志数据集的 BigQuery Data Editor (roles/bigquery.dataEditor) IAM 角色。

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您的管理员还可以通过自定义角色或其他预定义角色向对话式分析 API 服务代理授予所需的权限。

启用会话日志记录

对话日志记录需要一个服务代理可以写入的数据集。请先创建数据集并授予访问权限,然后为数据智能体启用日志记录功能。

创建日志数据集

在数据智能体的项目中创建一个数据集,用于存储日志。服务代理会在第一个记录的回合中在此数据集中创建日志表。如需创建数据集,请在 bq 命令行工具中使用 bq mk --dataset 命令。您可以在 Cloud Shell 或安装了 Google Cloud CLI 的本地终端中运行 bq 工具命令。

bq --location=LOCATION mk --dataset PROJECT_ID:LOG_DATASET

按如下所示替换示例值:

  • LOCATION:日志数据集的 BigQuery 位置,例如 US。
  • PROJECT_ID:包含数据智能体的项目的 ID。
  • LOG_DATASET:要创建的数据集的 ID。

如需了解创建数据集的其他方式,请参阅创建数据集。

向服务代理授予对数据集的访问权限

仅向服务代理授予日志数据集的 BigQuery Data Editor 角色 (roles/bigquery.dataEditor)。

从下列选项中选择一项:

控制台

  1. 在 Google Cloud 控制台中,前往 BigQuery 页面。

    转到 BigQuery

  2. 在探索器窗格中,展开您的项目,点击数据集,然后选择日志数据集。

  3. 依次点击共享 > 管理权限。

  4. 点击添加主账号。

  5. 在新的主账号字段中,输入服务代理的邮箱:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com。

    将 PROJECT_NUMBER 替换为包含数据智能体的项目的编号。

  6. 在选择角色列表中,选择 BigQuery Data Editor。

  7. 点击保存。

SQL

在 BigQuery 查询编辑器中,将查询位置设置为日志数据集的位置,然后运行以下 GRANT 语句:

GRANT `roles/bigquery.dataEditor`
ON SCHEMA `PROJECT_ID`.LOG_DATASET
TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com";

按如下所示替换示例值:

  • PROJECT_ID:包含数据智能体和日志数据集的项目 ID。
  • LOG_DATASET:日志数据集的 ID。
  • PROJECT_NUMBER:包含数据智能体的项目的编号。

如需了解其他授予访问权限的方法,请参阅授予对数据集的访问权限。 如果由于服务代理不存在而导致授权失败,请参阅由于服务代理不存在,授予数据集访问权限失败。

为数据智能体开启日志记录

如需为现有数据智能体启用日志记录功能,请设置智能体的 bigquery_agent_analytics_enabled 和 bigquery_agent_analytics_table 字段(HTTP 请求中的 bigqueryAgentAnalyticsEnabled 和 bigqueryAgentAnalyticsTable),并在更新掩码中包含这两个字段。更新操作仅会更改更新掩码中的字段。仅当您开启日志记录并设置日志表时,服务代理才会写入日志行。

在您在配置设置和初始化客户端 (Python SDK) 或配置初始设置和身份验证 (HTTP) 中设置的 Python 环境(例如 Colaboratory 笔记本)中运行以下示例。本页上的 Python SDK 示例需要 google-cloud-geminidataanalytics 0.13.4 版或更高版本。

Python SDK

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}")

按如下所示替换示例值:

  • DATA_AGENT_ID:数据智能体的 ID。
  • LOG_DATASET:日志数据集的 ID。
  • LOG_TABLE:日志表的 ID,例如 agent_events。如果该表不存在,服务代理会在首次记录对话轮次时创建该表。

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)

按如下所示替换示例值:

  • DATA_AGENT_ID:数据智能体的 ID。
  • LOG_DATASET:日志数据集的 ID。
  • LOG_TABLE:日志表的 ID,例如 agent_events。如果该表不存在,服务代理会在首次记录对话轮次时创建该表。

该方法会返回更新后的数据智能体。确认已启用日志记录,并且已设置日志表。

如需在创建数据智能体时启用日志记录,请在创建请求中添加相同的字段。如需了解创建请求,请参阅“创建数据智能体”(Python SDK 或 HTTP)。在 HTTP 请求正文中,这些字段如下所示:

"bigqueryAgentAnalyticsEnabled": true,
"bigqueryAgentAnalyticsTable": {
  "projectId": "PROJECT_ID",
  "datasetId": "LOG_DATASET",
  "tableId": "LOG_TABLE"
}

按如下所示替换示例值:

  • PROJECT_ID:包含数据智能体的项目的 ID。
  • LOG_DATASET:日志数据集的 ID。
  • LOG_TABLE:日志表的 ID。

验证对话是否已记录

  1. 向数据智能体发送对话请求。如需查看示例,请参阅“使用 API 提问”(Python SDK 或 HTTP)。
  2. 在智能体回答后,等待大约 10 秒。然后,在 Cloud Shell 或终端中,运行以下 bq query 命令以查看最近的问题和回答。您还可以在 BigQuery 查询编辑器中运行 SQL。

    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'
    

    按如下所示替换示例值:

    • PROJECT_ID:包含数据智能体的项目的 ID。
    • LOG_DATASET:日志数据集的 ID。
    • LOG_TABLE:日志表的 ID。

    如果查询返回了您的问题和智能体的回答,则表示对话日志记录功能正常运行。如果该表不存在或为空,请参阅排查对话日志记录问题。

更改目标表

如需将日志写入其他表,请更新数据智能体的 bigquery_agent_analytics_table 字段(HTTP 请求中的 bigqueryAgentAnalyticsTable),并将该字段包含在更新掩码中。新表必须位于数据智能体的项目中,并且服务代理必须对新表的父级数据集拥有 BigQuery Data Editor 角色。

在为数据智能体启用日志记录中的同一环境中运行以下示例。

Python SDK

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}")

按如下所示替换示例值:

  • DATA_AGENT_ID:数据智能体的 ID。
  • NEW_LOG_DATASET:新日志数据集的 ID。
  • NEW_LOG_TABLE:新日志表的 ID。

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)

按如下所示替换示例值:

  • DATA_AGENT_ID:数据智能体的 ID。
  • NEW_LOG_DATASET:新日志数据集的 ID。
  • NEW_LOG_TABLE:新日志表的 ID。

已记录的行会保留在之前的表中。更改会在下一轮生效。

关闭对话日志记录功能

如需为数据智能体关闭对话日志记录功能,请将智能体的 bigquery_agent_analytics_enabled 字段(HTTP 请求中的 bigqueryAgentAnalyticsEnabled)设置为 false,并将该字段添加到更新掩码中。

在为数据智能体启用日志记录中的同一环境中运行以下示例。

Python SDK

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}")

将 DATA_AGENT_ID 替换为数据智能体的 ID。

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)

将 DATA_AGENT_ID 替换为数据智能体的 ID。

更改会在下一轮生效。已在运行的轮次会采用启动时所用的设置完成。

如需停止为写入日志数据集的所有数据智能体记录日志,请撤消服务代理对该数据集的 BigQuery Data Editor 角色。每个代理的日志记录功能仍处于开启状态,但服务代理无法再写入行。

关闭日志记录功能后,系统会保留已记录的行。如需移除记录的数据,请删除行、分区或日志表。

排查对话日志记录问题

请参考以下信息,排查 BigQuery 中对话分析对话日志记录的常见问题。由于日志记录错误绝不会导致对话轮次失败,也不会在对话、API 响应或 Cloud Logging 中报告,因此目标表为空或缺失是配置或权限问题的主要信号。

日志表缺失或为空

如果目标表未创建或在对话轮次后仍为空,请检查以下潜在原因:

  • 对话记录功能未开启。确认已启用对话日志记录,并且已在数据智能体上配置目标表。

  • 目标数据集缺失或位于其他项目中。确认目标数据集已存在于数据智能体所在的项目中。您可以通过运行 bq show PROJECT_ID:LOG_DATASET 来验证数据集是否存在。将 PROJECT_ID 替换为包含数据智能体的项目的 ID,并将 LOG_DATASET 替换为目标数据集的 ID。服务代理会在第一个记录的轮次中创建日志表,但不会创建数据集。

  • 目标数据集是只读数据集,例如关联的数据集。BigQuery Sharing 关联的数据集或外部数据集(例如 AWS Glue 联合数据集)是只读的,无法存储对话日志。如需检查数据集类型,请运行 bq show --format=prettyjson PROJECT_ID:LOG_DATASET 并检查 "type" 字段("LINKED" 或 "EXTERNAL")。选择与数据智能体位于同一项目中的标准可写数据集。

  • 缺少服务代理或 CMEK 权限。确认对话式分析 API 服务代理(service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com,使用代理项目的编号而非项目 ID)对日志数据集具有 BigQuery Data Editor (roles/bigquery.dataEditor) 角色。如果数据集使用客户管理的 Cloud KMS 密钥 (CMEK),请确认 BigQuery 加密服务账号 (bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) 具有该密钥的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。

  • VPC Service Controls 边界会阻止写入。对话式分析 API 服务代理会从 Google 管理的基础设施写入日志表,因此当服务边界限制 bigquery.googleapis.com 时,仅授予 roles/bigquery.dataEditor 是不够的。与此列表中的其他原因不同,边界屏蔽会在代理的项目中记录 Cloud Logging 中的“政策遭拒”审核日志;按 bigquery.googleapis.com 下的 log_id("cloudaudit.googleapis.com/policy")(用于表查找或创建)和 bigquerystorage.googleapis.com(用于行附加)进行过滤,以确认屏蔽。确认 geminidataanalytics.googleapis.com 和 bigquery.googleapis.com 都在边界内,并为 bigquery.googleapis.com 上的服务代理添加入站流量规则。如需查看入站规则示例,请参阅访问权限控制、加密和网络安全。如需了解一般边界设置指南,请参阅使用 VPC Service Controls 配置边界安全。

  • 对话平台或代理配置不受支持。BigQuery Studio 预览版窗格中的对话以及不使用数据智能体的无状态 API 调用不会被记录。如需进行测试,请通过 API 向数据智能体发送对话请求。如果代理使用搜索范围而非特定 BigQuery 表,仅将 BigQuery 属性图(不含 BigQuery 表)配置为知识源,或未声明任何 BigQuery 表,则不会记录其活动。如需了解详情,请参阅限制。

  • 知识源表使用访问权限政策。如果任何知识源表(代理数据源中的 BigQuery 表)使用行级访问权限政策、列级安全性(政策标记)或动态数据遮盖,则不会记录对话轮次。

  • 现有目标表上存在架构冲突。如果您将现有表配置为目标表,并且某个列与对话日志架构列同名但类型或模式不同,则 BigQuery 不会向该表写入行。

行通常会在一轮对话完成后几秒内显示。如果您在等待几分钟后仍未看到行,请刷新数据集。

部分用户的对话未记录

原因

在每个回合之前,隐私检查都会使用聊天用户的凭据来验证代理的知识源表是否具有行级安全性、列级安全性或数据遮盖政策。如果用户无权运行此检查,则系统不会记录其轮次。

解决方法

向所有聊天用户授予知识源表的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色,以及运行其查询的项目的 BigQuery Job User (roles/bigquery.jobUser) 角色,或者授予对知识源表具有 bigquery.tables.get 和 bigquery.rowAccessPolicies.list 权限的自定义角色。

创建或更新智能体失败,并显示 INVALID_ARGUMENT 错误

错误消息

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

原因

目标数据集与数据智能体位于不同的项目中,或者智能体的数据源不是 BigQuery。

解决方法

请在数据智能体所在的项目中指定一个现有的目标数据集,或为数据智能体配置 BigQuery 数据源。

由于服务代理不存在,因此无法授予数据集访问权限

错误消息

  • Service account service-PROJECT_NUMBER@gcp-sa-geminidataanalytics... does not exist

原因

尚未在项目中预配对话式分析 API 服务代理。

解决方法

执行下列其中一项操作:

  • 请先在代理上配置日志目标位置,然后再次授予该角色。

  • 运行以下命令来预配服务身份:

    gcloud beta services identity create \
        --service=geminidataanalytics.googleapis.com \
        --project=PROJECT_ID

    将 PROJECT_ID 替换为包含数据智能体的项目的 ID。

后续步骤