mlflow-evaluation

Agent 评估

• 根据请求、项目和配置，明确目的、重要成果、已知失败、数据/追踪记录选择和已达成一致的评分器。只询问尚未解决的决策。

• 复用明确的标准和实现。对于任何评分器设计请求，请阅读 scorer design；如果请求涉及对齐，也请阅读 judge alignment。

• 对于仅涉及评分器的请求，构建并验证评分器，然后停止。除非收到请求，否则不要创建数据集或运行评估。

• 使用 mlflow.genai.datasets、内置评分器 / @scorer / make_judge 和 mlflow.genai.evaluate()；不要使用其他评估框架。

• 接受现有记录/DataFrame；通过 GenAI 数据集 API 持久化新建的可复用数据集。

步骤 1：复用设置并选择执行模式

• 保留 MLFLOW_TRACKING_URI、MLFLOW_EXPERIMENT_ID、提供方凭据和已配置的裁判模型。如果 两个 MLflow 变量都已设置，则跳过设置：不要更换后端、创建新实验或覆盖 .env。 如果缺少配置，且 mlflow-onboarding 可用，则使用它。
• 使用项目环境（由 uv 管理的项目使用 uv run）。检查 MLflow 是否为 3.8 或更高版本，并检查所需 API 的已安装签名。 捕获结构化 stdout 时，将 stderr 分开。
• **重新运行模式：**检查实际的 Agent 入口点及其配置。mlflow-trace-instrumentation 可用时，用它进行埋点；复用现有可用的追踪。运行一个有代表性的调用，在预期实验中刷新并获取其持久化追踪记录。如果追踪缺失或不可用，应先修复并验证，再进行评估；不要添加重复的框架 span。
• 预计算模式：在不使用 predict_fn 的情况下，评估提供的 inputs 和 outputs，或现有追踪记录。不要调用 Agent、修改已存储的记录或创建替代数据集。根据现有证据检查评分器的数据要求；最终输出评分器不需要新增埋点。

步骤 2：复用并注册评分器

• 列出已注册的评分器：mlflow scorers list -x "$MLFLOW_EXPERIMENT_ID"。复用评分器套件、模型和定义；只添加尚未达成一致的评分器。

• 阅读 scorers.md，了解模型选择、注册和检索。在评估前注册新的评分器；确认它们已注册到预期实验中。

• 检查已安装的 required_columns 和追踪记录要求：Correctness 需要真实答案；检索评分器需要 RETRIEVER，而不只是 TOOL span。

• 聚合布尔值、数字或 "yes"/"no"。已存储的 "pass"/"fail" 分数可能不会出现在聚合结果中。

• 对于自定义评分器或缺失分数，请阅读 scorers-constraints.md。

步骤 3：发现并绑定数据

• 创建数据前，先使用已安装的数据集发现 API。检查候选数据集；复用合适的数据集或明确指定的数据集。发现失败不代表不存在数据集。
• 对于 UC，使用预期的全限定表名和后端支持的发现方式。只有在选择不明确时才询问。

创建、调整或合成记录时，请阅读 dataset-preparation.md。检查实际的记录键和预测器签名：

# MLflow calls predict_fn(**record["inputs"]). Nested values stay nested.
record = {"inputs": {"query": "Where is order 42?", "context": {"order_id": 42}}}
def predict(query, context):
    return agent(query=query, context=context)  # bind project config here as needed

• 仅当数据集具有该输入键时，才将 inputs 作为封装参数接受。
• 将真实答案放在 expectations 下，例如 expectations.expected_response。保留多键输入和源 ID。
• 根据任务/覆盖范围设置数据规模；不要求扩展到 100 个问题，也不依赖合成。

如需合成语料库，请使用 RAGAS recipe。

第 4 步：试运行：完整评估前的必做步骤

使用完整运行的模式、封装器和评分器，评估 三个有代表性的记录，或用户明确指定的更小预算。只进行一次试运行，不要分别进行健全性检查和试运行。检查每一行：

• 预测器是否完成，必需的工具／检索是否执行，以及可用输出是否持久化？对于问候语或其他不需要工具的情况，工具不必运行。

• 每个适用的评分器是否都返回了有效评估，且没有错误？检查行级值／理由和汇总统计是否纳入了结果；仅有成功的跟踪状态或运行并不足够。

• 零、False 和 "no" 都是有效的质量失败。 对照实际响应和已知的良好／不良案例，调查可疑的统一评分；绝不要要求非零评分，也不要为了制造通过结果而更改评分标准。

• 在完整运行前停止：遇到身份验证／工具失败、预测失败、重新运行的响应为空，或评分缺失／仅有错误时。进行诊断，在范围内修复，然后重复试运行。

• 将损坏的预计算输出作为证据保留。区分评分为负的结果与评分器／基础设施故障。

• 保留试运行的运行 ID，并在支持时将其标记为试运行。除非用户要求，否则不要删除运行。

• 如果无法修复，请报告阻碍因素。绝不要编造凭据，也不要切换提供商重试。

第 5 步：执行并检查

• 重新运行：mlflow.genai.evaluate(data=selected_data, predict_fn=predict, scorers=registered_scorers)。预计算：省略 predict_fn。
• 根据试运行的吞吐量估算时长。对于耗时较长的运行，请阅读 吞吐量指南；遵守资源限制和主机支持的执行方式。
• 等待运行完成。保留退出状态、运行 ID／URL、耗时和行级产物路径；仅启动运行不代表成功。

验证

• 确认在预期实验中完成了全新运行，且每条所选记录和适用的评分器都有行级结果。

• 保留输出、跟踪 ID、值、理由和评估错误。

• 报告已评估、失败、缺失、跳过和出错的数量；不要在通过率的分母中隐去缺失行。仅有指标的运行和空评分表都不算成功。

• 分别总结各项标准；将有代表性的失败关联到证据，并说明小样本的局限性。可选的报告大纲。

• 对照原始类型化评分／错误检查汇总；生成的等级／建议不能作为确定根本原因的依据。

• 用户要求修复行为时：将结果交给 mlflow-agent-improvement。

参考资料

• 基础设施、架构或评分器故障：故障排除。

• 生产跟踪数据整理、版本比较或持续评估： 高级评估。

• Databricks 生产评分： databricks-online-monitoring.md；仅注册不会启动监控。

• 评审者意见不一致、领域专家标注、Review App 或 MemAlign：mlflow-evaluation 及其对齐参考资料。

• 已注册提示词的优化／GEPA：提示词优化。

• API 详情：评估快速入门或参考资料中的确切主题链接。检查与已安装版本的兼容性。

• 页面缺失／已移动：llms.txt。

• 文档／技能不可用：使用本地说明和已安装 API 的自省；停止并说明尚未解决的正确性问题。不要悄悄替换为旧版 API、后端或提供商。