评估并迭代改进 AI Agent/模型质量时…

当你需要评估 GenAI Agent 或模型的质量、构建评测数据集、选择或编写评测指标、分析失败原因、对比修复前后效果时，可按此五阶段飞轮流程操作。

适用场景

解决思路

1. 先输出 <plan> 计划块，再分步写脚本、执行、等待输出、分析，不要一次性做完所有事。
2. 环境准备：不要创建虚拟环境（会遮蔽已有包），先用 `python3 -c "import vertexai, google.genai, pandas, requests"` 探测，缺失才安装 `pip install 'google-cloud-aiplatform[evaluation]>=1.163.0' 'google-genai>=1.0.0'`；版本号必须加引号，否则 bash 会把 >= 当重定向。
3. 配置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 环境变量，缺失则询问用户；较新的 Gemini 模型常需 location="global"。
4. 使用正确 SDK 入口：`import agentplatform; client = agentplatform.Client(project=..., location=...)`，调用 `client.evals.run_inference`、`client.evals.evaluate`、`client.evals.generate_conversation_scenarios`；不要用 `from agentplatform.types import evals`（会 ModuleNotFoundError，应 `from agentplatform import types`），也不要用已被取代的 `from vertexai.evaluation import ...`。
5. 遵守安全分级：只读脚本（inspect_results.py、compare_results.py、validate_dataset.py、parse_adk_traces.py、render_html_report.py）可直接执行；会产生计算费用的操作（run_inference、evaluate、generate_conversation_scenarios、generate_loss_clusters）必须先交互式确认 Yes/No，且不得在同一轮先打印预览再调用，必须结束本轮等待用户回复。
6. 阶段1 准备数据：按已有数据形态三选一——(a) EvalCase 列表，prompt/reference/response 是 Content 而非 str，用 UserContent/ModelContent 包装，多轮用 agent_data；(b) pandas DataFrame，列名须匹配所选指标期望字段，用 `types.EvaluationDataset(eval_dataset_df=df)`；(c) 冷启动用 `client.evals.generate_conversation_scenarios(agent=..., config=...)`，参数是 agent/agent_info 不是 agents，config 必填且类型为 `types.evals.UserScenarioGenerationConfig`，必须设置 user_scenario_count（1-100，默认 None 会被服务端 400 拒绝）。ADK 会话转储用 scripts/parse_adk_traces.py。
7. 阶段2 跑推理：若轨迹已完整（生产日志/回放）可跳过。Agent 评测传可调用对象 `client.evals.run_inference(model=agent_callable, src=dataset)`；模型评测直接传模型 ID；合成场景加 `user_simulator_config=UserSimulatorConfig(max_turn=10)`；DataFrame 可直接作 src；Managed Agent 传资源名并配 config。
8. 阶段3 打分（必做）：`result = client.evals.evaluate(dataset=dataset, metrics=[...])`，用 `result.show()` 看 HTML 报告。按目标选指标：Agent 多轮用 multi_turn_task_success、multi_turn_trajectory_quality、multi_turn_tool_use_quality、multi_turn_general_quality、final_response_quality、final_response_match、tool_use_quality；单轮通用质量用 general_quality、text_quality、instruction_following；静态评分用 hallucination、grounding、safety。内置不覆盖时写自定义指标：预定义 `types.RubricMetric.<NAME>`；自定义 LLM 裁判用 `types.LLMMetric`（必须设 judge_model，否则默认 None 会 400 JSON 解析失败）；自定义代码用 `types.CodeExecutionMetric`（远程沙箱，custom_function 字符串含 `def evaluate(instance: dict)`）或 `types.Metric`（本地可调用）。
9. 持久化结果供阶段4/5读取：同时保存 JSON 和 HTML，用 `result.model_dump_json(fallback=str)`（不加 fallback 会 PydanticSerializationError），HTML 用 `_evals_visualization.get_evaluation_html(result_json)`；也可事后用 scripts/render_html_report.py 或 scripts/inspect_results.py --save-html。
10. 阶段4 分析失败：读 summary_metrics 和 eval_case_results，绝不编造分数；用 `scripts/inspect_results.py --failing-only` 过滤失败。按失败指标对症下药：task_success 低修编排/缺失工具调用/过早终止/工具选择；trajectory_quality 低优化规划提示、去冗余工具调用；tool_use_quality 低修工具描述、参数文档、选择指令；final_response_quality 低读自动评分细则改最差项；final_response_match 低调响应格式或更新参考；hallucination 低收紧指令、核实工具返回；grounding 低加“仅引用上下文”指令；safety 低加护栏并查违规类别；general_quality/text_quality 低改系统指令措辞；instruction_following 低重述约束；调错工具修工具描述/指令/tool_config；调多余工具加停止指令或改用 multi_turn_tool_use_quality。
11. 同一指标失败 10+ 条时用 Error Analysis 服务聚类：`agentplatform.Client(project=..., location="global")` 后调 `client.evals.generate_loss_clusters(eval_result=result, metric="multi_turn_task_success", config={"max_top_cluster_count": 5})`（仅支持 multi_turn_task_success 和 multi_turn_tool_use_quality，服务在 global 区），保存 model_dump_json 并用 render_html_report.py --type loss-analysis 渲染。
12. 阶段5 优化迭代：针对失败指标应用修复，重跑阶段3，用 `scripts/compare_results.py --baseline <prev> --candidate <new>` 确认目标改善且其他指标无回归。用表格记录每轮各指标与改动，预期每个失败用例需 5-10+ 轮迭代，用例通过后再扩展更多评测用例。
13. 证明工作成果：只报告从真实 result 对象读到的结果；评测后打印 summary_metrics 表，修复后展示 compare_results.py 前后对比，宣布成功前确认所有用例通过而非只修的那一个；若无法提供证据（SDK 调用失败、结果截断、指标不支持）要明说，不要掩盖。
14. 不确定 SDK 类型或指标时查 SDK 源码，不要猜测或幻觉；使用标准 Python 导入，不用内部导入路径。

适用边界 · 注意事项

• 不适用于微调场景（应使用 agent-platform-tuning）和一般生产部署（应使用 agent-platform-deploy）。
• 不适用于没有 Google Cloud / Agent Platform 环境或账号的情况（依赖 google-cloud-aiplatform、agentplatform SDK 与云端评测服务）。
• 不要在轨迹已完整时重复跑推理阶段，也不要为让指标通过而调低阈值、跳过 flaky 用例或只改数据集不改 Agent。