评估代理

开发代理后，您可以使用 Gen AI Evaluation Service 评估代理在给定使用场景中完成任务和实现目标的能力。

定义评估指标

从一个空的指标列表（即 metrics = []）开始，然后向其中添加相关指标。如需添加其他指标，请执行以下操作：

最终回答

最终回答评估的流程与基于模型的评估相同。如需了解详情，请参阅定义评估指标。

完全匹配 

metrics.append("trajectory_exact_match")

如果预测轨迹与参考轨迹完全相同，工具调用的顺序也完全相同，则 trajectory_exact_match 指标会返回 1 分，否则返回 0 分。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

按顺序匹配

metrics.append("trajectory_in_order_match")

如果预测的轨迹包含参考轨迹中的所有工具调用（顺序相同），并且可能还包含额外的工具调用，则 trajectory_in_order_match 指标会返回 1 的得分，否则返回 0。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的预测轨迹。
  • reference_trajectory：智能体为满足查询而预期的预测轨迹。

任意顺序匹配

metrics.append("trajectory_any_order_match")

如果预测的轨迹包含参考轨迹中的所有工具调用，但顺序无关紧要，并且可能包含额外的工具调用，则 trajectory_any_order_match 指标会返回 1 的得分，否则返回 0。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

精确率 

metrics.append("trajectory_precision")

trajectory_precision 指标用于衡量预测轨迹中有多少工具调用根据参考轨迹实际上是相关或正确的。这是一个介于 [0, 1] 范围内的 float 值：得分越高，预测的轨迹越精确。

精确率的计算方式如下：统计预测轨迹中也出现在参考轨迹中的操作数量。将该数量除以预测轨迹中的操作总数。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

召回率 

metrics.append("trajectory_recall")

trajectory_recall 指标用于衡量参考轨迹中的基本工具调用有多少实际捕获在预测轨迹中。这是一个介于 [0, 1] 范围内的 float 值：得分越高，预测轨迹的召回率就越好。

召回率的计算方式如下：统计参考轨迹中也出现在预测轨迹中的操作数量。将该数量除以参考轨迹中的操作总数。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

使用单个工具

from vertexai.preview.evaluation import metrics

metrics.append(metrics.TrajectorySingleToolUse(tool_name='tool_name'))

trajectory_single_tool_use 指标用于检查预测的轨迹中是否使用了指标规范中指定的特定工具。它不会检查工具调用的顺序或工具的使用次数，只会检查工具是否存在。如果工具不存在，则值为 0；否则为 1。

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。

自定义

您可以按如下方式定义自定义指标：

from vertexai.preview.evaluation import metrics

def word_count(instance):
  response = instance["response"]
  score = len(response.split(" "))
  return {"word_count": score}

metrics.append(
  metrics.CustomMetric(name="word_count", metric_function=word_count)
)

结果中始终包含以下两个性能指标。您无需在 EvalTask 中指定它们：

  • latency (float)：客服人员的响应时间（以秒为单位）。
  • failure (bool)：如果代理调用成功，则为 0；否则为 1。

准备评估数据集

如需准备数据集以进行最终响应或轨迹评估，请执行以下操作：

最终回答

最终回答评估的数据架构与模型回答评估的数据架构类似。

完全匹配

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

按顺序匹配

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的预测轨迹。
  • reference_trajectory：智能体为满足查询而预期的预测轨迹。

任意顺序匹配

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

精确率

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

召回率

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。
  • reference_trajectory：智能体为满足查询而预期使用的工具。

使用单个工具

评估数据集需要提供以下输入：

输入参数：

  • predicted_trajectory：代理用于生成最终回答的工具调用列表。

为便于说明，以下是评估数据集的示例。

  import pandas as pd

  eval_dataset = pd.DataFrame({
    "predicted_trajectory": [
      [ # example 1
        {
          "tool_name": "set_device_info",
          "tool_input": {"device_id": "device_3", "updates": {"status": "OFF"}}
        },
      ],
      [ # example 2
        {
          "tool_name": "get_user_preferences",
          "tool_input": {"user_id": "user_z"},
        }, {
          "tool_name": "set_temperature",
          "tool_input": {"location": "Living Room", "temperature": 23},
        },
      ]
    ],
    "reference_trajectory": [
      [ # example 1
        {
          "tool_name": "set_device_info",
          "tool_input": {"device_id": "device_2", "updates": {"status": "OFF"}},
        },
      ],
      [ # example 2
        {
          "tool_name": "get_user_preferences",
          "tool_input": {"user_id": "user_y"},
        }, {
          "tool_name": "set_temperature",
          "tool_input": {"location": "Living Room", "temperature": 23},
        },
      ],
    ],
  })

示例数据集

我们提供了以下示例数据集，以演示如何评估代理：

  • "on-device"：设备端 Home Assistant 的评估数据集。该代理可帮助处理以下查询：“安排卧室的空调在晚上 11 点到早上 8 点之间开启，其余时间关闭。”

  • "customer-support"：客户支持代理的评估数据集。该代理可帮助处理“你能取消所有待处理的订单并上报所有未解决的支持服务工单吗？”等查询。

  • "content-creation"：营销内容创作代理的评估数据集。该代理可帮助处理以下查询：“将广告系列 X 重新安排为在社交媒体网站 Y 上投放的一次性广告系列，预算减少 50%，仅在 2024 年 12 月 25 日投放。”

如需导入示例数据集，请执行以下操作：

  1. 安装并初始化 gcloud CLI。

  2. 下载评估数据集。

    在设备上 

    gcloud storage cp gs://cloud-ai-demo-datasets/agent-eval-datasets/on-device/eval_dataset.json .

    客户支持 

    gcloud storage cp gs://cloud-ai-demo-datasets/agent-eval-datasets/customer-support/eval_dataset.json .

    内容创作

    gcloud storage cp gs://cloud-ai-demo-datasets/agent-eval-datasets/content-creation/eval_dataset.json .

  3. 加载数据集示例

    import json

eval_dataset = json.loads(open('eval_dataset.json').read())

生成评估结果

如需生成评估结果，请运行以下代码：

from vertexai.preview.evaluation import EvalTask

eval_task = EvalTask(dataset=eval_dataset, metrics=metrics)
eval_result = eval_task.evaluate(runnable=agent)

查看和解读结果

评估结果如下所示：

代理评估指标表

评估结果包含以下信息：

最终回答指标

逐行指标：

  • response：代理生成的最终回答。
  • latency_in_seconds：生成回答所用的时间（以秒为单位）。
  • failure：指示是否生成了有效回答。
  • score：针对指标规范中指定的回答计算出的得分。
  • explanation：指标规范中指定的分数的说明。

摘要指标：

  • mean：所有实例的平均得分。
  • standard deviation：所有得分的标准差。

轨迹指标

逐行指标：

  • predicted_trajectory：为获得最终回答，代理执行的一系列工具调用。
  • reference_trajectory：预期工具调用的序列。
  • score：针对指标规范中指定的预测轨迹和参考轨迹计算出的得分。
  • latency_in_seconds：生成回答所用的时间（以秒为单位）。
  • failure：指示是否生成了有效回答。

摘要指标：

  • mean：所有实例的平均得分。
  • standard deviation：所有得分的标准差。

后续步骤

不妨试试以下笔记本：