mlflow-3

MLflow 3

面向开源 MLflow 3 的库参考技能——涵盖 6 个类别中的 24 条规则。MLflow 3 以模型作为一等实体重构了库，弃用了注册表阶段术语，替换了服务堆栈，并更改了存储和序列化默认值；在庞大的 MLflow 2 语料上训练的模型会流利地复现旧用法，而这正是每条规则存在的原因。对于有能力的模型本来就能正确处理的内容，我们不会制定规则。

范围为可自托管开源 MLflow 上的经典机器学习 MLOps。GenAI 功能（mlflow.genai、跟踪、提示词注册表、AI Gateway）仅在将它们与经典 API 混淆本身就是陷阱时才会出现。对于 Databricks/Unity Catalog 专属功能（Deployment Jobs），若模型可能会针对开源版搭建这些功能，则会标记为超出范围。

固定版本为 mlflow 3.15.1（Python ≥ 3.10）。API 声明已通过解包 mlflow / mlflow-skinny 3.15.1 wheel 进行验证。

适用场景

• 编写或审查使用 MLflow 记录模型、指标、参数或数据集的训练代码
• 注册模型版本并配置 dev/staging/prod 之间的晋级流程（别名、copy_model_version、标签、webhook）
• 搭建或加固 mlflow server——后端存储、制品存储、身份验证
• 评估候选模型并根据阈值决定是否晋级
• 提供模型服务——mlflow models serve、build-docker、/invocations 客户端、部署前验证
• 将 MLflow 2 时代的代码库（阶段、artifact_path、mlflow.evaluate、./mlruns）迁移到 MLflow 3

规则类别

#	类别	前缀	涵盖内容
1	模型记录与 LoggedModel	log-	使用 name= 而非 artifact_path、模型与运行解耦、由输入示例驱动的签名、记录时注册、skops/torch.export 序列化默认值、模型关联指标和 search_logged_models
2	模型注册表与晋级	reg-	以别名取代阶段、基于别名查找、使用 copy_model_version 按环境分别注册模型、在标签中保存门控状态、开源版 webhook 与 Databricks 专属 Deployment Jobs
3	跟踪后端与服务端	track-	默认使用 sqlite:///mlflow.db、仅数据库的服务端后端和 migrate-filestore、代理制品拓扑、关闭遥测、autolog 输入示例默认值
4	服务	serve-	FastAPI 评分服务器（已移除 MLServer）、/invocations 负载约定、部署前使用 mlflow.models.predict 验证、面向集群使用 build-docker
5	评估与门控	eval-	mlflow.models.evaluate 与 mlflow.genai.evaluate 的区别、移除 baseline_model 后使用 validate_evaluation_results 进行阈值门控
6	环境与可复现性	env-	将生成的环境文件作为服务端的事实来源、依赖固定与 uv 捕获、使用 code_paths 打包自定义代码

快速参考

1. 模型记录与 LoggedModel

• log-name-not-artifact-path — name= 会创建可搜索的 LoggedModel；artifact_path 已弃用并会发出警告
• log-models-are-not-run-artifacts — 无需 start_run；制品位于 models/<model_id>/ 下，通过 model_uri 进行寻址
• log-input-example-infers-signature — input_example= 会推断签名，并在记录时验证服务输入
• log-register-at-log-time — 使用 registered_model_name= 或 register_model(model_info.model_uri)，切勿拼接 runs:/ 路径
• log-serialization-defaults-changed — sklearn/lightgbm 会写入 skops，pytorch 会写入 torch.export，xgboost 会写入 UBJSON
• log-link-metrics-search-models — log_metric(model_id=, dataset=) 和 search_logged_models 无需运行记录管理即可对模型进行排序

2. 模型注册表与晋级

• reg-aliases-not-stages — set_registered_model_alias + models:/name@alias 取代已弃用的阶段 API
• reg-resolve-by-alias-not-latest-versions — 部署代码应解析指定的别名，绝不使用 get_latest_versions 或 /latest
• reg-per-environment-registered-models — 使用 dev.*/staging.*/prod.* 模型，并以 copy_model_version 作为晋级原语
• reg-gate-state-in-tags — validation_status 标签承载审核状态，这是阶段曾试图表达的内容
• reg-webhooks-oss-deployment-jobs-not — 注册表 Webhook 属于 OSS；Deployment Jobs 仅限 Databricks

3. 跟踪后端与服务端

• track-default-is-sqlite-not-mlruns — 本地默认值为 sqlite:///mlflow.db，而非 ./mlruns
• track-server-needs-database-backend — 自 3.13 起，文件存储会在服务端启动时引发错误；使用 migrate-filestore + db upgrade
• track-proxied-artifacts-one-credential — 服务端默认代理制品；客户端只需设置 MLFLOW_TRACKING_URI
• track-telemetry-on-by-default — 匿名遥测默认启用；在生产镜像中应显式禁用
• track-autolog-input-examples-off — 对候选部署模型使用 autolog(log_input_examples=True)

4. 服务

• serve-fastapi-scoring-server-only — FastAPI/uvicorn 是唯一的评分服务端；MLServer 和 Flask/gunicorn 均已移除
• serve-invocations-payload-keys — /invocations 接受 dataframe_split/dataframe_records/inputs/instances（以及签名声明的 params）
• serve-predict-before-deploy — mlflow.models.predict 会重建真实环境；validate_serving_input 已弃用
• serve-build-docker-for-clusters — build-docker 是容器构建方式；Helm chart 部署的是跟踪服务端，而非模型

5. 评估与门控

• eval-models-evaluate-split — 经典 ML 使用 mlflow.models.evaluate；mlflow.genai.evaluate 是不同的 API
• eval-gate-with-validate-evaluation-results — baseline_model 已移除；使用 validate_evaluation_results + MetricThreshold 实施门控

6. 环境与可复现性

• env-generated-files-drive-serving — 服务环境根据生成的文件重建；通过 pip_requirements/extra_pip_requirements/uv 固定依赖
• env-bundle-custom-code-paths — code_paths/infer_code_paths 会将导入依赖图随模型一同打包

使用方法

遇到相关决策时，请阅读对应的参考文件。每条规则都会指出其要纠正的错误默认做法，然后展示规范方式（只有在错误做法确实容易导致问题时，才会对比错误与正确做法）。

• 章节定义 — 类别结构
• 规则模板 — 用于添加新规则
• AGENTS.md — 自动生成的所有规则目录

相关技能

• mlflow-mlops-migration — 配套的组合工作流，可对任意 ML 代码库进行评估和重构，并搭建 dev/staging/prod MLflow 3 环境；各阶段都会引用这些规则

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和来源引用