databricks-mlflow-evaluation

MLflow 3 GenAI 评估

与上游 mlflow/skills 的范围对比

开源的 mlflow/skills 仓库提供了 agent-evaluation 及相关技能（instrumenting-with-mlflow-tracing、analyze-mlflow-trace、retrieving-mlflow-traces、querying-mlflow-metrics），涵盖通用的 MLflow GenAI 评估工作流，包括 mlflow.genai.evaluate()、评分器/裁判、数据集、追踪设置以及 5 步评估循环。

此技能在该工作流之上叠加 Databricks 特定模式，而不是重复介绍该工作流。以下情况适合使用此技能：

• Unity Catalog 追踪数据摄取——将生产追踪数据写入 UC 表，并进行基于日志的监控（patterns-trace-ingestion.md）。
• 通过 UC SME 标注会话对齐 MemAlign 裁判——在 Databricks 中，根据领域专家收集的反馈对齐自定义裁判（patterns-judge-alignment.md）。
• optimize_prompts() GEPA 循环——Databricks 的自动化提示词优化驱动程序，在 UC 数据集上运行（patterns-prompt-optimization.md）。
• Databricks 风格的评分器/数据集模式——基于 UC 表的数据集，以及在 Databricks UI 中为追踪数据添加标签以便纳入（patterns-datasets.md、patterns-scorers.md）。

其他内容——通用的 mlflow.genai.evaluate() 调用、评分器编写模式、在 Databricks 之外创建数据集，以及不绑定 UC 表的 MLflow 追踪设置——以上游 mlflow/skills/agent-evaluation 技能为准。该技能是权威参考，并由 MLflow 团队持续更新。

编写任何代码之前

1. 阅读 GOTCHAS.md - 了解 15 个以上可能导致失败的常见错误
2. 阅读 CRITICAL-interfaces.md - 查看准确的 API 签名和数据架构

端到端工作流

根据目标选择以下工作流。每个步骤都注明了需要阅读的参考文件。

工作流 1：首次设置评估

适用于刚开始使用 MLflow GenAI 评估的用户，或为新 Agent 设置评估的用户。

步骤	操作	参考文件
1	明确评估对象	user-journeys.md（Journey 0: 策略）
2	学习 API 模式	GOTCHAS.md + CRITICAL-interfaces.md
3	构建初始数据集	patterns-datasets.md（Patterns 1-4）
4	选择/创建评分器	patterns-scorers.md + CRITICAL-interfaces.md（内置列表）
5	运行评估	patterns-evaluation.md（Patterns 1-3）

工作流 2：生产追踪数据 -> 评估数据集

适用于根据生产追踪数据构建评估数据集。

步骤	操作	参考文件
1	搜索和筛选追踪数据	patterns-trace-analysis.md（MCP 工具部分）
2	分析追踪质量	patterns-trace-analysis.md（Patterns 1-7）
3	为要纳入的追踪数据添加标签	patterns-datasets.md（Patterns 16-17）
4	根据追踪数据构建数据集	patterns-datasets.md（Patterns 6-7）
5	添加期望值/真实标注	patterns-datasets.md（Pattern 2）

工作流 3：性能优化

适用于排查 Agent 执行缓慢或成本高昂的问题。

步骤	操作	参考文件
1	按跨度分析延迟	patterns-trace-analysis.md（Patterns 4-6）
2	分析令牌用量	patterns-trace-analysis.md（Pattern 9）
3	检测上下文问题	patterns-context-optimization.md（Section 5）
4	应用优化	patterns-context-optimization.md（Sections 1-4, 6）
5	重新评估以衡量效果	patterns-evaluation.md（Pattern 6-7）

工作流 4：回归检测

用于比较 Agent 版本并发现回归问题。

步骤	操作	参考文件
1	建立基线	patterns-evaluation.md（模式 4：命名运行）
2	运行当前版本	patterns-evaluation.md（模式 1）
3	比较指标	patterns-evaluation.md（模式 6-7）
4	分析失败的追踪记录	patterns-trace-analysis.md（模式 7）
5	调试特定故障	patterns-trace-analysis.md（模式 8-9）

工作流 5：自定义评分器开发

用于创建项目专属的评估指标。

步骤	操作	参考文件
1	了解评分器接口	CRITICAL-interfaces.md（评分器部分）
2	选择评分器模式	patterns-scorers.md（模式 4-11）
3	对于多 Agent 评分器	patterns-scorers.md（模式 13-16）
4	使用评估进行测试	patterns-evaluation.md（模式 1）

工作流 6：Unity Catalog 追踪记录导入与生产监控

用于将追踪记录存储在 Unity Catalog 中、为应用添加检测功能，并启用持续生产监控。

步骤	操作	参考文件
1	将 UC 架构关联到实验	patterns-trace-ingestion.md（模式 1-2）
2	设置追踪记录目标位置	patterns-trace-ingestion.md（模式 3-4）
3	为应用添加检测功能	patterns-trace-ingestion.md（模式 5-8）
4	配置追踪记录来源（Apps/Serving/OTEL）	patterns-trace-ingestion.md（模式 9-11）
5	启用生产监控	patterns-trace-ingestion.md（模式 12-13）
6	查询和分析 UC 追踪记录	patterns-trace-ingestion.md（模式 14）

工作流 7：使用 MemAlign 对评审器进行对齐

用于调整 LLM 评审器，使其符合领域专家的偏好。经过良好对齐的评审器能提升所有下游用途的效果：评估准确性、生产监控信号和提示词优化质量。此工作流本身也很有价值，不依赖提示词优化。

步骤	操作	参考文件
1	使用 make_judge 设计基础评审器（任意反馈类型）	patterns-judge-alignment.md（模式 1）
2	运行 evaluate()，为成功的追踪记录添加标签	patterns-judge-alignment.md（模式 2）
3	构建 UC 数据集 + 创建 SME 标注会话	patterns-judge-alignment.md（模式 3）
4	标注完成后，使用 MemAlign 对齐评审器	patterns-judge-alignment.md（模式 4）
5	将对齐后的评审器注册到实验	patterns-judge-alignment.md（模式 5）
6	使用对齐后的评审器重新评估（基线）	patterns-judge-alignment.md（模式 6）

工作流 8：使用 GEPA 自动优化提示词

用于使用 optimize_prompts() 自动改进已注册的系统提示词。此工作流适用于任何评分器；搭配已对齐的评审器（工作流 7）可获得最准确的领域信号。如需了解结合对齐与优化的完整端到端流程，请参阅 user-journeys.md 中的 Journey 10。

步骤	操作	参考文件
1	构建优化数据集（输入 + 预期结果）	patterns-prompt-optimization.md（模式 1）
2	使用 GEPA 和评分器运行 optimize_prompts()	patterns-prompt-optimization.md（模式 2）
3	注册新版本，并根据条件进行推广	patterns-prompt-optimization.md（模式 3）

参考文件速查

参考文件	用途	阅读时机
GOTCHAS.md	常见错误	编写代码前务必先阅读
CRITICAL-interfaces.md	API 签名、架构	编写任何评估代码时
patterns-evaluation.md	运行评估、进行比较	执行评估时
patterns-scorers.md	创建自定义评分器	内置评分器无法满足需求时
patterns-datasets.md	构建数据集	准备评估数据时
patterns-trace-analysis.md	调试追踪记录	分析 Agent 行为时
patterns-context-optimization.md	令牌／延迟优化	Agent 速度慢或成本高时
patterns-trace-ingestion.md	UC 追踪记录设置、监控	设置追踪记录存储或生产监控时
patterns-judge-alignment.md	MemAlign 评判器对齐、标注会话、SME 反馈	让评判器与领域专家偏好保持一致时
patterns-prompt-optimization.md	GEPA 优化：构建数据集、optimize_prompts()、推广	运行自动化提示词改进时
user-journeys.md	高层级工作流、完整的领域专家优化循环	启动新的评估项目或运行完整的对齐 + 优化流程时

关键 API 事实

• 使用： mlflow.genai.evaluate()（不要使用 mlflow.evaluate()）
• 数据格式： {"inputs": {"query": "..."}}（必须使用嵌套结构）
• predict_fn： 接收 **unpacked kwargs（而非字典）
• MemAlign： 与评分器无关（适用于任何 feedback_value_type，包括 float、bool、categorical）；嵌入模型会大量消耗令牌，因此请显式设置 embedding_model
• 标签架构名称匹配： 标注会话中的标签架构 name 必须与 evaluate() 中使用的评判器 name 匹配，align() 才能配对分数
• 对齐后的评判器分数： 可能低于未对齐的评判器分数，这是预期情况，意味着评判器现在更准确，而不是 Agent 退步了
• GEPA 优化数据集： 每条记录都必须同时包含 inputs 和 expectations（与评估数据集不同）
• 情景记忆： 延迟加载——在首次使用评判器前，打印 get_scorer() 结果不会显示情景记忆
• optimize_prompts： 需要 MLflow >= 3.5.0
• UC 模型服务评判器模型： databricks:/system.ai.<model> 评判器／评分器 URI 需要满足最低版本要求，并可能遇到 404（旧客户端）或 403（旧版端点名称）错误——有关版本、确切错误文本和修复方法，请参阅 GOTCHAS.md -> "Custom Judge Model Format"

完整列表请参阅 GOTCHAS.md。

相关技能

• databricks-docs - Databricks 文档通用参考
• databricks-model-serving - 将模型和 Agent 部署到服务端点
• databricks-agent-bricks - 构建可使用此技能进行评估的 Agent
• databricks-python-sdk - 与 MLflow API 配合使用的 SDK 模式
• databricks-unity-catalog - 用于托管评估数据集的 Unity Catalog 表