运行离线评估

通过离线评估，您可以分析开发或生产期间捕获的历史数据，从而衡量代理的性能、安全性和质量。您可以根据一组预定义或自定义的指标来评估单个轨迹（单次执行路径）或完整的会话（多轮对话历史记录）。

轨迹与会话

  • 轨迹：代理行为的真实且不可变的记录，包括模型输入、响应和工具调用。轨迹表示单个执行路径。
  • 会话：涵盖用户与代理之间的整个多轮互动。您可以使用会话来评估一段时间内的上下文保留情况和对话流程。

准备工作

为确保您拥有离线评估所需的数据和环境，请完成以下操作：

  • 确保您已部署启用了 Cloud Trace 的正常运行的 Agent Runtime。
  • 设置一个 Cloud Storage 存储桶来存储评估结果。您只需提供一次此路径；系统会在以后的运行中预先填充此路径。
  • 如果您打算使用 Agent Platform SDK 进行评估，请按照评估代理中的说明初始化客户端。

遥测要求

离线评估需要您的代理导出特定的 OpenTelemetry 信号，以便为评估提供必要的上下文。这些要求与在线监控器的要求相同：

  1. 调用代理 span：必须包含以下属性：

    • gen_ai.agent.name：代理的标识符。
    • gen_ai.agent.description：代理用途的简要说明。
    • gen_ai.conversation.id：特定对话会话的唯一标识符。

  2. 推理事件：gen_ai.client.inference.operation.details 事件必须捕获：

    • gen_ai.input.messages：发送给智能体的提示。
    • gen_ai.output.messages：智能体生成的回答。
    • gen_ai.system_instructions：底层系统提示。
    • gen_ai.tool.definitions：有关代理可用的任何工具的元数据。

如果您使用的是 智能体开发套件，则必须通过设置以下环境变量来启用这些遥测功能：

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

在 Cloud Storage 中录制媒体

如果您的代理使用多模态数据（例如图片或大型文档），我们建议您将输入和输出记录在 Cloud Storage 存储桶中，而不是直接将其嵌入到轨迹 span 中。请配置以下环境变量以启用此功能：

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

如需了解详情，请参阅收集多模态提示和回答。

根据注册表创建评估

  1. 在 Google Cloud 控制台中，前往 Agent Platform > Agents > Evaluation 页面。

    前往“评估”页面

  2. 点击新建评估。

  3. 根据评估目标，选择轨迹或会话标签页。

  4. 使用过滤条件图标和时间选择器过滤数据（例如，按版本或“过去 2 周”过滤），然后选择要评估的特定 ID。

  5. 点击继续。

  6. （可选）在评估名称字段中，输入评估的名称，或使用预填充的默认名称。

  7. 在输出私有数据路径字段中，输入您的 Cloud Storage 存储桶 URI。首次使用后，系统会在后续运行中预先填充此路径。

  8. 默认情况下，系统会添加所有四项核心指标。您可以根据需要添加或移除指标。

  9. 点击评估代理。

评估单个轨迹或会话

您可以在检查各个执行路径时直接触发评估：

  1. 在 Google Cloud 控制台中，前往 Agent Platform > Agents 页面。
  2. 在左侧导航菜单中，选择部署。
  3. 选择您的代理。

    转到部署

  4. 选择轨迹标签页。
  5. 点击会话视图或轨迹视图，检查执行路径。
  6. 从表格中选择特定行，即可打开详细信息面板。
  7. 选择评估标签页。
  8. 如果轨迹或会话尚未评估，请点击评估以运行临时评估。

查看评估结果

评估完成后，您可以分析结果，找出性能差距和系统性问题：

  • 查看运行结果：在 Google Cloud 控制台中，前往Agent Platform > 代理 > 评估页面，然后选择评估标签页。点击评估名称即可查看详细报告。

    前往“评估”页面

  • 深入分析轨迹：在结果报告中，点击任意一行即可直接前往关联的轨迹，并检查得分背后的推理（理由）。

如需了解详情，请参阅分析评估结果。