对话日志记录概览

借助对话式分析对话日志记录功能，您可以将数据智能体的对话记录在项目中的 BigQuery 表中，以便查看回答质量、跟踪采用情况并监控各个对话式分析智能体的费用。对于每个轮次，日志都会捕获用户的问题、智能体的回答、延迟时间、模型词元用量，以及按智能体、对话和用户对轮次进行分组所需的标识符。系统会通过 BigQuery Storage Write API (gRPC)，使用 BigQuery Agent Analytics 架构写入行。

系统会记录的内容

每个记录的回合都会向目标表写入多个事件行 (events)，这些行会记录以下信息：

  • 用户的问题。

  • 智能体的回答：文本、数据分析、假设、建议的后续问题、引用来源以及任何数据结果或图表的名称。

  • 每轮延迟时间。

  • 每次模型调用的模型 token 用量、模型版本和完成原因（模型停止生成 token 的原因）。

  • 数据智能体 ID 和对话 ID，以便您在一个表中分析多个智能体。

  • 用户标识符。如需详细了解用户标识符，请参阅用户身份。

  • 状态和错误详情。

系统不会记录的内容

对话日志记录不会记录以下内容：

  • 智能体运行的 SQL 查询：日志包含最终回答以及引用的数据结果和图表的名称，但不包含生成这些结果和图表的查询。例外情况是，当用户明确要求代理显示或解释 SQL 时，SQL 可以出现在回答文本中。

  • 智能体的工具调用：每次模型调用都会写入一个 LLM_RESPONSE 行，包括模型决定运行工具的调用。在写入行之前，模型的输出会被移除，包括它调用的任何工具的名称和参数。系统只会保留 token 用量、模型版本和完成原因。

  • 用户反馈：“我喜欢”或“不喜欢”反馈不会记录。

某些对话根本不会记录，例如 BigQuery Studio 预览窗格中的对话。如需详细了解不支持的对话界面，请参阅限制。

对话日志记录的运作方式

当用户与启用了对话日志记录功能的数据智能体聊天时，对话分析会通过以下阶段处理每个轮次：

  1. 配置：代理所有者启用对话日志记录，并在 BigQuery Studio 中选择代理项目中的现有目标数据集和表名称。

  2. 提问：用户向智能体发送问题。在 BigQuery Studio 中，用户会看到一条通知，告知其对话会被记录。

  3. 隐私检查：在代理开始处理对话轮次之前，隐私检查会使用聊天用户的凭据读取代理知识源表的元数据。此检查可确认没有任何表使用行级安全性（行访问权限政策）、列级安全性（政策标记）或动态数据遮盖。如果检查发现存在政策或无法确认不存在政策，则系统不会记录该轮对话，但智能体仍会回答用户的问题。

  4. 回答：代理照常回答用户。

  5. 写入：项目的 Conversational Analytics API 服务代理 (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.) 通过 Storage Write API (gRPC) 将日志行写入目标表。在第一个记录的轮次中，如果该表尚不存在，服务代理会创建该表。

  6. 查询：行通常会在回答完成后几秒钟内显示。送货时间无法保证。

日志记录错误绝不会导致回合失败，而隐私检查和日志写入可能会增加延迟时间。如果日志数据集缺少权限、数据集不存在或配额用尽，对话请求不会失败。对话式分析不会在聊天界面或 Cloud Logging 中报告日志记录失败。

隐私权、数据治理和安全性

为代理启用对话日志记录后，请查看最终用户通知、数据访问、加密和网络控制如何应用于您的日志。

最终用户通知和记录的内容

以下声明和规则规定了对话日志记录的内容以及谁可以查看记录的数据：

  • BigQuery Studio 中的最终用户通知：为代理启用对话日志记录后，在 BigQuery Studio 中与该代理对话的用户会在启用对话日志记录时看到以下通知，包括在用户发送第一个提示之前的新对话界面上：

    所有提示和回答都会记录到 BigQuery 中，拥有数据集权限的用户可以访问这些记录。

  • 使用 API 时的责任：如果您在数据智能体上启用对话日志记录（轨迹日志记录），并通过您自己的应用或集成将该智能体提供给最终用户，Google 无法向这些用户显示通知。根据适用法律以及您与最终用户达成的协议，您有责任就记录的对话提供任何适用的通知、披露或征得同意。如需了解详情，请参阅 Conversational Analytics API 的安全性、隐私权、风险和合规性。

  • 日志包含的内容以及谁可以查看日志：目标表会根据以下隐私规则存储问答内容：

    • 完整问题和回答：回答可以包含从知识源返回的值。任何可以读取日志表的人都可以看到智能体返回给用户的数据，包括他们无法在源表中读取的数据。仅向应该看到此内容的人员授予对日志数据集的读取权限。

    • 用户标识符和写入位置：user_id 列标识提出问题的调用方（请参阅用户身份），并且行仅写入您在代理项目中配置的目标位置。

    • 具有行级安全性、列级安全性或数据遮盖的表：如果智能体的知识来源使用行级安全性（行访问权限政策）、列级安全性（政策标记）或动态数据遮盖，则不会记录其对话轮次。隐私检查会跳过 bigquery-public-data 中的表，仅查看您选择作为知识来源的表和视图，而不会查看视图背后的表：

      • 基于使用这些政策的表的视图可以通过检查，因此可以记录其轮次。在启用日志记录之前，请确保视图背后的表不使用行访问权限政策、政策标记或数据遮盖。

      • 如果您稍后将其中一项政策添加到源表，则已记录的行会保留在日志表中。如果您的保留或治理政策禁止保留这些行，请将其删除。

访问权限控制、加密和网络安全

您可以使用以下设置来管理对话日志的保留、访问、加密和边界安全：

  • 日志数据集的保留和访问权限控制：为目标表配置保留、数据集角色、表政策和审核日志：

    • 保留：Google 不会删除日志行。在日志数据集或表上设置符合您政策的分区到期时间（例如 90 天）。

    • 最小权限：将日志数据集与其他数据集分开，以便共享的 Conversational Analytics API 服务代理的写入权限不会影响其他表。向分析师授予对日志数据集的 roles/bigquery.dataViewer 权限，或仅向他们授予对授权视图或授权数据集的访问权限。

    • 日志表上的列级和行级控制：您可以将政策标记、数据遮盖或行访问权限政策应用于日志表本身，例如 content 或 user_id。这些日志表控件不会影响知识源隐私检查。

    • 审核日志记录：对数据智能体的更改会记录在管理员活动审核日志中。在 BigQuery 审核日志中，服务代理创建表和更新元数据的操作会记录在 bigquery.googleapis.com 下，通过 Storage Write API (gRPC) 附加行的操作会记录在 bigquerystorage.googleapis.com 下。

  • CMEK、VPC Service Controls 和数据驻留：以下加密、边界和位置控制适用于对话日志记录：

    • CMEK：如果日志数据集使用客户管理的 Cloud KMS 密钥 (CMEK)，请向 BigQuery 加密服务账号 (bq-PROJECT_NUMBER@bigquery-encryption.) 授予密钥的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。数据智能体上的 CMEK 会加密智能体资源，而不是日志表（请参阅客户管理的加密密钥）。

    • VPC Service Controls：如果您使用服务边界，请在包含代理项目的边界中同时添加 geminidataanalytics.googleapis.com 和 bigquery.googleapis.com。服务代理会从 Google 管理的基础设施写入日志表，因此，如果边界限制了 bigquery.googleapis.com，请添加如下所示的入站流量规则。将 PROJECT_NUMBER 替换为代理的项目编号：

      - ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.
    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

      如需了解详情，请参阅使用 VPC Service Controls 配置边界安全。

    • 数据驻留：日志行和自动创建的表存储在日志数据集的位置，其中应用了资源位置组织政策 (gcp.resourceLocations)。

限制

对话日志记录具有以下限制：

  • BigQuery Studio 代理编辑器中的预览窗格不会记录日志。

  • 系统不会记录没有数据智能体的直接对话。

  • 如果代理使用搜索范围而非特定表，或者未声明任何 BigQuery 表，则不会记录。系统不会记录将 BigQuery 属性图配置为知识来源的智能体。

  • 系统不会记录生成的 SQL、工具调用以及智能体开发套件 (ADK) 工具或请求事件（TOOL_STARTING、TOOL_COMPLETED、TOOL_ERROR 和 LLM_REQUEST），只会记录回答及其数据结果和图表的名称。直接通过经过验证的查询回答的轮次不会写入 LLM_RESPONSE 行，并且不会记录失败的经过验证的查询轮次。

  • 系统不会记录“我喜欢”或“不喜欢”的用户反馈。

  • 如果知识来源使用行访问权限政策、列级安全性（政策标记）或数据遮盖，或者隐私检查无法完成，则不会记录对话轮次。该检查不会通过视图查看其背后的表。

  • 仅支持 BigQuery 表代理；不支持 Looker、数据洞察、AlloyDB、Spanner 和 Cloud SQL 数据源。

  • 目标数据集必须已存在于智能体所在的项目中。

  • 对现有表的架构更改仅为附加更改；冲突的列类型或模式会停止对该表的写入。

  • 每个符合条件的轮次都会记录，无需设置采样；而是在查询时进行采样（请参阅对所有智能体中的问题和回答进行采样以供审核）。

  • agent 列包含智能体类型，而不是智能体显示名称；请使用 attributes 中的数据智能体 ID。

  • 如果 API 调用方为多个最终用户使用一个服务账号，则会在每一行中看到该服务账号的电子邮件。

  • 长度超过 512,000 个字符 (500 * 1,024) 的文本值会被截断并添加后缀 ...[TRUNCATED]，且被移除的部分无法恢复。

  • 写入操作会尽力而为，重试次数有限；写入失败的轮次不会记录，重试偶尔会产生重复行（使用 event_id 去重）。

  • 代理不会继承项目级可观测性设置。

价格

对话式分析不会单独收取对话日志记录费用。 您的项目需要为 BigQuery Storage Write API (gRPC) 数据注入、存储和分析查询支付标准 BigQuery 价格。BigQuery Storage Write API (gRPC) 注入包括每个结算账号每月 2 TiB 的免费用量，在 Storage Write API (gRPC) 用量中共享。对 timestamp 过滤查询，以减少扫描的字节数。预运行隐私权检查会读取表元数据并免费运行试运行查询。

后续步骤