agent-platform-autorater-customization

Agent Platform 评分器定制

此技能可帮助用户为 Agent 构建评分器，让评分器按照用户的判断方式进行评判。你负责阅读、编写和测试；由用户作出判断。最终会在 Agent Platform 评估服务中注册一组指标，每项用户关注的标准对应一个或多个指标。

请按顺序执行以下步骤。不要向用户总结这些步骤。

使用归因

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读并遵循使用归因中的说明。

设置

在首次调用评估之前逐项检查，并要求用户补齐缺失项。安装任何内容之前都要先征得用户同意，因为这会更改用户的环境。

1. Python SDK。 安装或升级 Agent Platform SDK，并添加 evaluation 扩展：

   pip install --upgrade 'google-cloud-aiplatform[evaluation]>=2.8.0,<3'
   

   保留引号；如果不加引号，Shell 会将 >= 视为重定向符。身份验证还需要 gcloud CLI；如果尚未安装，请指引用户前往 https://cloud.google.com/sdk/docs/install，而不要代为安装。

2. 项目和结算。 使用用户指定的项目，或请用户提供项目（gcloud config set project {project_id}）。项目必须关联有效的结算账号：评估调用会按模型用量计费。当前价格请参阅 https://cloud.google.com/pricing；不要引用具体数字。

3. API。 启用 Agent Platform API： gcloud services enable aiplatform.googleapis.com。

4. 身份验证。 对于 CLI，运行 gcloud auth login；对于 SDK 和脚本，运行 gcloud auth application-default login；或者将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号密钥文件的路径。

5. IAM。 用户或服务账号需要 roles/aiplatform.user 才能运行评估并注册指标。不要授予 roles/aiplatform.admin 等更宽泛的角色；如果缺少所需角色，请让用户申请权限范围更小的角色。

6. 区域。 除非用户需要其他区域，否则使用 us-central1（参阅 https://cloud.google.com/about/locations）。

与用户协作

• 每到 审批 环节，都要展示提案并询问：“您想修改什么内容，还是按此版本继续？”等待用户明确同意；沉默不代表同意。
• 对于设置选项（项目、区域、存储），请提供一个默认建议。
• 用户要审核的所有内容（案例、评分、指标定义）都应放在审核页面中，而不是聊天中；请参阅审核页面。在聊天中更新时，说明你完成了什么、相关数量，以及你需要用户提供什么。
• 在聊天中询问轨迹相关问题时，引用相关行。

输入

用户会提供一个轨迹文件夹：包括他们认为出错的轨迹，以及一些表现良好的轨迹。还可以提供每条轨迹的备注或评分（赞踩、人类评分、旧评分器的判定）、现有评分标准或参考答案。

• 使用全部轨迹，除非在评估服务中为它们评分会耗时或成本过高。若会耗时或成本过高，则与用户商定一个涵盖失败案例和若干良好案例的样本，并说明省略了哪些内容。
• 最佳格式为 AgentData JSONL；请参阅转换轨迹。如果无法有把握地将某种格式映射到 AgentData，不要猜测：说明需要将其转换为 AgentData，并请用户提供架构、转换器或一个手动映射的示例。然后检查转换后的每个案例。
• 构建数据集不属于此技能的职责。如果用户还没有文件夹，请帮助他们挑选并转换轨迹，然后继续。

术语

• **评估标准：**用户关注的 Agent 行为的一项要求：答案正确、调用了正确的工具、始终遵循系统指令。评估标准适用于整个数据集；每条轨迹或每轮对话都会根据该标准评分，某些情况下也可以标记为 N/A。
• **评分细则：**一项是非题检查。
• **指标：**评估服务中用于评估某项评估标准的内容：代码、一项评分细则或多项加权评分细则。一项评估标准可以根据需要设置多个指标，例如，为工具调用设置一项代码检查，再为答案设置一项评审。

预定义的多轮指标也会将意图转化为带有重要性权重的评分细则，但评分依据是通过的评分细则所占的未加权比例。自定义指标则会添加为用户的 Agent 编写的评分细则、权重、必过评分细则和通过阈值。

步骤

1. 确认输入内容

询问文件夹所在位置，以及是否有任何轨迹附带备注或评分。

2. 提出评估标准（审批）

阅读轨迹和用户备注，提出数据所支持的评估标准，并尽量精简，只覆盖用户关心的问题。评估标准可以涵盖轨迹的任意部分：最终答案、工具调用及其参数、是否遵循系统指令，以及对错误或澄清请求的处理。在多 Agent 系统中，评估标准可以针对整个系统（路由、最终答案），也可以针对某个子 Agent；请说明具体针对哪一方。对于每项标准，提供：

• 一句陈述，并说明其对该 Agent 的重要性；
• 存在问题的案例数量，以及一个引用示例；
• 计划为其构建的指标（见步骤 4），并用一句话说明原因。

不得提出无法从数据或用户备注中找到依据的评估标准。对于存疑的评估标准，请说明原因（例如，由于工具结果被截断而无法评分）。同时指出现有评分中的问题：评审未看到 Agent 可访问的数据、轨迹中的证据被截断，或黄金答案从未运行。

此步骤不会调用评估服务。如果用户希望找出 10 个或更多失败案例中的模式，可以使用 MULTI_TURN_TASK_SUCCESS 为其评分，并在步骤 3 后运行 client.evals.generate_loss_clusters。Loss clusters 仅适用于 global 区域以及 multi_turn_task_success 和 multi_turn_tool_use_quality，不适用于自定义指标。

将已批准的评估标准保存为 criteria.md。

3. 商定数据规则和支出（审批）

询问是否可以将轨迹发送到评估服务、费用计入哪个项目，以及输出可以存储在哪里。说明调用次数（案例数 × 指标数 × 样本数 × 轮次数；对于按步骤计算的指标，每个步骤调用一次），并提供费用参考链接：https://cloud.google.com/pricing。执行任何超出该范围的运行前，须再次询问。

4. 构建指标

使用能够评估该标准的最简单形式：形式越简单，成本越低，结果越一致，也越值得信赖。

可通过以下方式评估标准	形式	SDK
输出或轨迹中的精确规则（工具名称、格式、数字）	代码	types.CodeExecutionMetric（在服务中运行；可注册）
每个案例都适用的单项判断	LLM，单项评分标准	types.LLMMetric，通过是/否检查并使用参考
多项检查，且重要性各不相同	LLM，加权评分标准	types.StepBasedLLMMetric：一个评审步骤；由代码计算加权分数
每个案例的检查各不相同，且没有合适的参考	生成的检查清单	types.StepBasedLLMMetric：一个步骤根据对话编写检查项，另一个步骤评估这些检查项
较长或多轮的轨迹、逐轮判定或多个评审阶段	分步骤、多阶段	types.StepBasedLLMMetric
多 Agent 系统中的单个子 Agent	分步骤、单个 Agent	types.StepBasedLLMMetric，配合仅保留该 Agent 事件的代码预处理器

从指标模板中的模板开始构建每项指标；每个模板都会说明它无法检测的内容。对于加权评分标准，提出评分标准、每项的权重、必须通过的评分标准和通过阈值，并将权重保存在解析器代码中，这样评审方就会逐项评估各个评分标准。请按编写 LLM 检查项中的说明编写检查项。对于多轮对话，请根据每项标准决定是评估每一轮还是整个对话；请参阅多轮对话。

5. 评估并展示结果

通过评估服务，使用 scripts/run_metrics.py 评估这些案例，然后使用 scripts/build_review_page.py 构建审核页面。将每项指标的通过阈值作为 --threshold 传入，以确保页面上的 PASS 和 FAIL 与该指标一致。

可选：如果用户已有自动评分器，或希望与内置指标（例如 MULTI_TURN_TASK_SUCCESS）比较，也可以使用它进行评估，并将其作为基线展示。这样会增加调用次数，而且内置指标评估的是整体任务成功情况，而不是用户的标准。

6. 可选：根据用户评分调整指标

询问用户是否愿意为案例标记评分，以便你改进指标；每个案例约需一分钟。如果不愿意，则跳到第 7 步。

1. 将约 20% 的案例留作保留集。构建审核页面时不包含这些案例。
2. 用户在审核页面上将每项判定标记为 Agree 或 Disagree；如果不同意，还需说明原因，并向你提供 labels.json。如果用户已有人工评分，请使用这些评分，并且只询问指标判定不一致的案例。
3. 使用 scripts/agreement.py 计算每项指标和每项评分标准的一致率。在采信更改之前，先测量评审噪声；请参阅噪声与一致率。
4. 自行修订指标（评分标准措辞、权重、必须通过的评分标准、阈值、参考、代码），将每一轮保存为新版本，再次评估，并向用户说明更改内容和新的一致率。如果某个标注与轨迹相矛盾，请引用相关行并询问用户。
5. 当一致率的提升不再超过噪声，或用户满意时停止。对保留集中的案例评估一次。不要根据这些案例进行修订；如果保留集中的案例评估失败，请报告过拟合并建议增加已标注案例。

7. 审核和注册（Approval）

注册指标是此技能的目标。请在审核页面中为每项指标添加：对应的标准、最终定义（评分细则、权重、必过评分细则、阈值、评审模型、样本数量）、评分结果、步骤 6 已执行时标注案例和留出案例上的一致性，以及待解决的问题。获得批准后，使用 create_evaluation_metric 注册每项指标；这会创建一个共享资源。

交付一个包含以下内容的输出文件夹：

• criteria.md：已批准的标准，并列出每项标准所对应的指标；
• metrics/：每项指标的最终定义，内容应与评估服务实际运行的文件一致（传递给 scripts/run_metrics.py 的指标文件），并包含其注册名称；
• metrics.md：每项指标各一条记录，包含对应标准、形式、评分细则、权重、必过评分细则、阈值、评审模型和样本数量，以及一段按注册名称运行指标的代码片段；
• labels.json 及较早版本（如果步骤 6 已执行）；
• report.md：数值和待解决的问题。

要在完整数据集上运行指标，请使用 agent-platform-eval-flywheel。

审核页面

每轮使用 scripts/build_review_page.py 构建一个独立的 HTML 页面，并将页面路径告知用户（或将其部署到用户浏览器可访问的位置）。对于每个案例，页面会显示用户的备注或评分、每项指标的 PASS/FAIL、得分、解释和评分细则判定、运行过的基线，以及工具结果已折叠的轨迹。用户可以为每项判定标记“同意”或“不同意”，并说明理由；标记会保存在浏览器中，“下载 labels.json”会按 scripts/agreement.py 可读取的格式导出标记。绝不要让用户在聊天中输入标签。

规则

• 所有评分都必须通过评估服务完成。标签只能由用户提供：不要用自己的模型调用或子 Agent 为轨迹评分或起草标签，因为将指标调优到另一个模型的标签，只会让一个模型学会认同另一个模型。
• 构建期间只对文件夹中的案例评分；完整数据集应在注册后使用。
• 所有报告的数值都必须来自结果文件。若多次运行的结果不同，请报告范围。
• 按用户指定的位置保存专有轨迹和输出，包括审核页面。绝不要将其粘贴到共享文档、问题单或聊天中。
• 使用名称前先阅读已安装 SDK 的源代码；不同版本可能有所差异。

清理

已注册的指标会一直保留在项目中，直到被删除。用户想移除不再使用的指标，或误注册的指标时，先向用户确认名称，然后运行 client.evals.delete_evaluation_metric(metric_resource_name={name})。使用 client.evals.list_evaluation_metrics() 列出指标。本地输出（结果、审核页面、标签）保留在用户选择的位置；结束时可询问是否要删除。

脚本

所有脚本都支持 --help。

• scripts/render_agent_data.py：将轨迹呈现为易读文本。
• scripts/run_metrics.py：使用 client.evals.evaluate() 运行 SDK 指标。
• scripts/build_review_page.py：构建审核页面并导出标签。
• scripts/agreement.py：按指标、评分细则或轮次计算一致性、Cohen's kappa 和分歧情况。

参考资料

• 转换轨迹
• 指标模板
• 编写 LLM 检查项
• 多轮对话
• 噪声与一致性
• SDK 注意事项