agent-platform-eval-flywheel

Agent Platform Eval Flywheel Skill

帮助用户使用 Agent Platform GenAI Evaluation SDK (google.genai / agentplatform) 评估并迭代提升 GenAI 模型与 Agent 的表现。

何时使用此 Skill

• 使用 Agent Platform GenAI Evaluation SDK (client.evals.evaluate()) 评估 GenAI Agent 或模型。
• 从会话 Trace、Pandas DataFrame 或合成生成数据中构建评估数据集。
• 挑选、配置或编写自定义评估指标（Evaluation Metrics）。
• 分析评分细则裁定结果（Rubric Verdicts）、损失模式（Loss Patterns）以及失败案例聚类。
• 根据评估结果，提出具体的代码或 Prompt 改进建议。
• 评估运行在 Agent Platform Endpoint（BYOM，自定义模型）或 Model-as-a-Service (MaaS) 上的模型（如有需要，可先进行模型部署）。这种情况下，请参考 references/deployment.md 并使用 endpoint_evaluation.py / maas_evaluation.py 脚本。

安全与确认分级（重要/CRITICAL）

在代表用户执行任何命令或脚本之前，必须严格遵守以下基于请求操作的安全分级规范：

1. Tier R：只读操作（inspect_results.py、compare_results.py、validate_dataset.py、parse_adk_traces.py、render_html_report.py）
   • 规则：无需确认。可以立即执行这些辅助脚本来检查数据、校验 Schema、解析 Trace 或对比评估结果。
2. Tier M：带算力成本的只读操作（client.evals.run_inference、client.evals.evaluate、client.evals.generate_user_scenarios、client.evals.generate_loss_clusters）
   • 规则：这些操作会调用 LLM 或远程评估服务，消耗算力资源并产生费用。必须进行包含 'Yes'/'No' 选项的交互式确认。用户授权一次后，后续评估无需重复询问。

环境配置（Setup）

脚本依赖 vertexai（来自 google-cloud-aiplatform[evaluation]）、google-genai、pandas 以及 requests。不要创建虚拟环境——新建的虚拟环境为空，会掩盖当前环境已有的包，导致不必要的重复安装。请先检测环境，仅安装缺失的包：

python3 -c "import vertexai, google.genai, pandas, requests" \
  || pip install 'google-cloud-aiplatform[evaluation]>=1.154.0' 'google-genai>=1.0.0'

版本指定符必须保留引号：如果不加引号，Bash 会把 >=1.154.0 误识别为重定向符号，静默写入一个空文件，而不会按版本约束安装。

需要配置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。优先检查环境变量；如果缺失，请询问用户。较新的 Gemini 模型通常需要设置 location="global"。

质量飞轮（The Quality Flywheel）

分为五个阶段。首次执行时请按顺序运行 1→5，之后在 2 → 5 之间循环迭代，直到达到质量目标。

踩坑提醒 / 浪费时间的“捷径”

投机取巧的做法	为什么行不通
“我把指标门槛调低一点，就能通过了。”	这只会掩盖真实的失败案例。应该修复 Agent，而不是调低标准。
“这个 Case 有点波动（flaky），我跳过吧。”	波动说明 Agent 存在不确定性。可以通过设置 temperature=0 或补充更严格的指令来修复。
“我只需要修评估数据集，不用改 Agent。”	如果预期输出一直在变，说明是 Agent 的行为出了问题。
“我直接看 Trace 就知道没问题，跳过第 3 阶段吧。”	自测感觉不可靠，无法泛化。一定要运行 evaluate() 并查看具体得分。
“迭代一次就够了。”	准备好迭代 5~10+ 次。过早停止会导致其他指标的回归问题未被发现。

1. 准备数据（Prepare Data）

生成一个 EvaluationDataset。有三种输入格式，请根据用户现有的数据类型选择对应格式：

• EvalCase 列表（单轮或多轮）：

  from agentplatform import types
  dataset = types.EvaluationDataset(eval_cases=[
      types.EvalCase(prompt="What is 2+2?", response="4", reference="4"),
      # 对于多轮 Agent Trace，请设置 agent_data 而不是 prompt/response。
  ])
  

  多轮 Agent Trace 会将每轮对话封装在 AgentData → ConversationTurn → AgentEvent 中。详见 references/dataset_schema.md 查看完整的类型层级。

• Pandas DataFrame（表格数据源——CSV、BigQuery、Sheets 等）：

  import pandas as pd
  from agentplatform import types
  
  df = pd.DataFrame({
      "prompt":    ["What is 2+2?", "Capital of France?"],
      "response":  ["4",            "Paris"],
      "reference": ["4",            "Paris"],
  })
  dataset = types.EvaluationDataset(eval_dataset_df=df)
  

  列名必须与所选指标要求的字段匹配（参见 references/dataset_schema.md 中的各指标要求对照表）。

• 冷启动（完全没有数据）： 使用 client.evals.generate_user_scenarios(...) 配合 UserScenarioGenerationConfig（设置 user_scenario_count、simulation_instruction、environment_data）在服务端合成场景，第 2 阶段会对其进行模拟演练。

对于 ADK Session Dump 数据，请直接使用 scripts/parse_adk_traces.py，无需手动编写转换代码。

2. 运行推理（Run Inference）

在数据集上填充模型/Agent 的输出（Response/Trace）。如果 Trace 已经是完整状态（例如生产环境日志或重放数据），可跳过此阶段。

# Agent 评估 — 传入包裹了用户 ADK Agent/App 的可调用对象（callable）
client.evals.run_inference(model=agent_callable, src=dataset)

# 模型评估 — 直接传入模型 ID
client.evals.run_inference(model="gemini-2.5-flash", src=dataset)

# 合成场景 — 让模拟器自动驱动运行
client.evals.run_inference(
    model=agent_callable,
    src=dataset,
    user_simulator_config=UserSimulatorConfig(max_turn=10),
)

# src= 同样支持传入 DataFrame — 无需额外包装 EvalCase
client.evals.run_inference(model="gemini-2.5-flash", src=df)

3. 打分（Grade，必须运行）

result = client.evals.evaluate(dataset=dataset, metrics=[...])

根据衡量需求挑选指标。 完整目录请查阅 references/metric_registry.md。

Agent 指标（多轮对话，自适应 Rubric 评分） —— Agent 评估优先从这里开始。

目标	指标
Agent 是否完成了用户的目标？	multi_turn_task_success
推理路径是否合乎逻辑且高效？	multi_turn_trajectory_quality
跨多轮的 Tool/Function 调用质量	multi_turn_tool_use_quality
整体对话质量	multi_turn_general_quality
最终回答质量（无需 Golden Reference 参考答案）	final_response_quality
最终回答对比 Golden Reference	final_response_match
单轮工具调用	tool_use_quality

通用质量指标（单轮，自适应 Rubric 评分） —— 用于模型评估。

目标	指标
整体回答质量（推荐的起点指标）	general_quality
语言质量（流畅度、连贯性、语法）	text_quality
特定约束/指令的遵循情况	instruction_following

静态 Rubric 指标（固定评判标准） —— 与上述指标配合使用。

目标	指标
捕获幻觉断言（RAG、事实性问答）	hallucination
基于给定上下文的事实性 / 一致性	grounding
安全策略合规性	safety

内置指标无法覆盖的领域特定检查： 编写自定义指标。

• 预定义（Predefined）： types.RubricMetric.<NAME> —— 服务端 AutoRater，无需裁判模型。
• 自定义 LLM 裁判（Custom LLM-as-a-judge）： 带有 prompt_template 的 types.LLMMetric，或者使用 types.MetricPromptBuilder 构建结构化 Rubric。
• 自定义代码（Custom code）： 使用 types.CodeExecutionMetric，传入包含 def evaluate(instance: dict) 的 custom_function 字符串进行远程沙箱执行；或使用 types.Metric 配套 custom_function=<callable> 进行本地执行。

务必持久化保存评估结果，以便第 4 和第 5 阶段读取。同时保存 JSON（机器可读，支持 Diff）和 HTML（人类可读，方便分享链接）：

import datetime
from pathlib import Path

from agentplatform._genai import _evals_visualization

out_dir = Path("artifacts/grade_results")
out_dir.mkdir(parents=True, exist_ok=True)
ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")

result_json = result.model_dump_json()
(out_dir / f"results_{ts}.json").write_text(result_json)

html = _evals_visualization.get_evaluation_html(result_json)
(out_dir / f"results_{ts}.html").write_text(str(html))

或者在事后生成：scripts/render_html_report.py --type evaluation 或 scripts/inspect_results.py --save-html。

4. 分析失败案例（Analyze Failures）

读取 summary_metrics 和 eval_case_results —— 绝不要捏造得分。使用 scripts/inspect_results.py --failing-only 过滤出失败案例。

对于每个未达标的指标，请参阅 references/failure_patterns.md 获取更深入的诊断指引。简要映射关系如下：

未达标指标	优化方向
multi_turn_task_success 偏低	Agent 未能完成目标 —— 修复编排逻辑（Orchestration）、补充遗漏的工具调用、避免过早终止或选错工具。
multi_turn_trajectory_quality 偏低	Agent 达成路径效率低下 —— 优化 Planning Prompt，剔除冗余的工具调用。
multi_turn_tool_use_quality 偏低	优化工具描述、参数 Docstring，或调整 Agent 在工具选择上的 Prompt 指令。
final_response_quality 偏低	检查自动生成的 Rubric 裁定结果；针对得分最差的评判标准优化 Prompt 指令。
final_response_match 偏低	Agent 最终回答与 Golden Reference 不匹配 —— 调整回答格式或更新 Reference。
hallucination 偏低	强化指令约束，确保回答严格基于事实和上下文

<!-- truncated for translation batch; full body continues in source -->