SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-evaluation

agent-evaluation

智能体与模型

查看项目

更新于 10-16 07:51

技能介绍

用途

Agent Evaluation with MLflow 是一个用于评估、改进或优化现有 LLM 智能体输出质量的技能，覆盖完整的 GenAI 智能体评估工作流，也可单独使用其中某个环节，例如追踪设置、环境配置、数据集创建、评分器定义或评估执行。

主要能力

该技能强调必须使用 MLflow 原生 API，而非自建评估框架：

  • 数据集：使用 mlflow.genai.datasets.create_dataset()，而非自定义测试用例文件
  • 评分器：使用 mlflow.genai.scorers 和 mlflow.genai.judges.make_judge()，而非自定义评分函数
  • 评估：使用 mlflow.genai.evaluate()，而非自定义评估循环
  • 脚本：使用提供的 scripts/ 目录模板，而非自定义 evaluation/ 目录

原因在于 MLflow 会在实验中追踪一切（数据集、评分器、追踪记录、结果），自建框架会绕过这些能力并失去可观测性。

使用方式

命令约定

始终使用 uv run 执行 MLflow 和 Python 命令：

  • uv run mlflow --version
  • uv run python scripts/xxx.py
  • uv run python -c "..."

捕获 CLI 输出时需将 stderr 与 stdout 分开重定向，例如：

uv run mlflow traces evaluate ... --output json > results.json 2> evaluation.log

文档访问协议

所有 MLflow 文档需通过 llms.txt 访问：从 https://mlflow.org/docs/latest/llms.txt 开始，用具体提示查询主题；若 llms.txt 引用其他文档，则用 WebFetch 访问该 URL。不要使用 WebSearch。

环境预检

先检查 MLFLOW_TRACKING_URI 和 MLFLOW_EXPERIMENT_ID 是否已设置。若两者均已设置，则跳过安装与配置步骤，直接进入追踪集成和评估工作流，不要运行 setup_mlflow.py、不要创建 .env 文件、不要覆盖这些值。

若环境未预配置，则需：安装 MLflow（版本 >=3.8.0）、配置环境（追踪 URI 与实验）、集成追踪（autolog 和 @mlflow.trace 装饰器）。追踪设置需使用 instrumenting-with-mlflow-tracing 技能，并在实现后运行 scripts/validate_tracing_runtime.py 验证。追踪必须正常工作后才能进行评估。

验证脚本：

  • uv run python scripts/validate_environment.py
  • uv run python scripts/validate_auth.py

评估工作流

步骤 1：智能体访谈（必需）

在继续之前需向用户询问：智能体的用途（1-2 句）、最需要做对的 2-3 件事、已注意到的常见失败模式。答案用于推导评分器名称与标准、编写 agent_description 参数、设定评估优先级。自动化模式下可从代码库（SKILL.md、README 或主入口 docstring）读取智能体用途，但仍需向用户确认。

步骤 2：定义质量评分器

检查实验中已注册的评分器：uv run mlflow scorers list -x $MLFLOW_EXPERIMENT_ID。若实验中已有注册评分器，则必须使用它们。选择适用的内置评分器，并按需用 make_judge() API 创建自定义评分器。

关键约束：评分器必须指示 LLM 裁判返回 "yes" 或 "no"（或布尔值/数值）。返回 "pass" 或 "fail" 会被 _cast_assessment_value_to_float 静默转换为 None 并从 results.metrics 中排除，且无错误或警告。

新评分器必须在评估前通过 Python API 注册：

from mlflow.genai.judges import make_judge from mlflow.genai.scorers import BuiltinScorerName import os

scorer = make_judge(...) # 或 scorer = BuiltinScorerName() scorer.register()

注册后验证：uv run mlflow scorers list -x $MLFLOW_EXPERIMENT_ID

步骤 3：准备评估数据集

始终先发现已有数据集：

  • uv run python scripts/list_datasets.py
  • uv run python scripts/list_datasets.py --format json
  • uv run python scripts/list_datasets.py --help

向用户展示发现的数据集及其特征，询问是否使用已有数据集。

若创建新数据集，采用两阶段方法：

阶段 A：健全性检查（5 个问题，始终先运行）。从步骤 1 访谈答案手动创建最小 5 问题数据集，确认流水线端到端可用。

阶段 B：正式评估数据集（100+ 问题，阶段 A 通过后运行）。从智能体实际语料生成问题：

  • 在 Databricks 上：使用 generate_evals_df 从文档语料合成问题，可用 estimate_synthetic_num_evals 估算合适的 num_evals。
  • 在 OSS MLflow 上：使用 RAGAS TestsetGenerator 从文档语料生成。
  • 若无文档语料：请用户提供 50–100 条来自生产日志或使用历史的代表性查询。

数据集规模指导：<30 问题不具统计意义；50–100 问题足以捕捉回归，适合多数智能体；200+ 问题推荐用于比较模型变体或多维度评分。

步骤 3.5：干跑（完整评估前必需）

在完整运行前，先对数据集中的 3 个问题运行评估，以尽早发现工具故障、评分器配置错误和认证失败。检查：工具调用（需要检索的问题是否调用了工具）、响应质量（是否为空或通用）、评分器输出（是否全为 0 或 None）。

决策门：若干跑显示工具失败或空响应，停止并修复底层问题；若 3 个评分器输出全为 0 或 None，停止并调试评分器返回值后重新注册；若通过，则报告并继续。

步骤 4：运行评估

4a. 先估算运行时间：统计数据集问题数，按每个问题运行智能体一次和裁判评分器一次计算。Opus 级裁判模型约 45–90 秒/问题，Sonnet 级约 20–45 秒/问题，多评分器按比例增加时间。估算时间 = N 问题 × 30–60 秒 ÷ 并行因子（通常 4–8x）。

4b. 生成评估脚本：

uv run python scripts/run_evaluation_template.py
--module mlflow_agent.agent
--entry-point run_agent

生成的脚本创建包装函数，接受与数据集输入键匹配的关键字参数，提供智能体所需的额外参数，运行 mlflow.genai.evaluate(data=df, predict_fn=wrapper, scorers=registered_scorers)，并将结果保存到 evaluation_results.csv。

关键：包装函数签名必须与数据集输入键匹配。

适用场景

适用于需要评估或改进现有 LLM 智能体输出质量的场景，包括提升工具选择准确率、答案质量等。可用于完整评估工作流，也可单独使用追踪设置、数据集创建、评分器定义或评估执行等环节。

限制

  • 必须使用 MLflow 原生 API，不得创建自定义评估框架。
  • 追踪必须正常工作后才能进行评估；若追踪失败需停止并排查。
  • 评分器返回值必须为 "yes"/"no"（或布尔值/数值），"pass"/"fail" 会被静默丢弃。
  • 评分器必须在评估前注册，未注册的内联评分器不会出现在 mlflow scorers list 中且不可复用。
  • 完整评估前必须进行干跑验证。
  • 文档必须通过 llms.txt 访问，不使用 WebSearch。
  • 关于具体收费、价格、平台支持范围等信息，资料中暂未提供。