mlflow-mlops-migration

MLflow MLOps 迁移

一套分阶段、带门禁的工作流，可将任意 ML 代码库（无论结构多么混乱）改造为生产级的开源 MLflow 3方案，覆盖完整的 MLOps 周期：实验跟踪、按领域建模的注册表、dev/staging/prod 环境隔离、由评估门禁控制的晋级，以及模型服务。此工作流旨在与没有 MLflow 3 使用经验的开发者共同推进：每个阶段都会先产出可供审核的成果，再进行任何更改；所有 API 决策均遵循同级的 mlflow-3 规则包（该规则包固定使用 mlflow 3.15.1，并指出本迁移旨在移除的 MLflow 2 时代惯用法）。

适用场景

在以下情况使用此技能：

• 团队想采用 MLflow（或已有混乱、不完整的 MLflow 2 配置），需要了解如何构建生产级 MLflow 3 部署，而不只是修复 API。
• 已有训练代码，但实验未跟踪、模型通过复制文件交付，或者所谓的“部署”只是把 pickle 文件放进存储桶。
• 有人请你设计或审核 dev/staging/prod 模型晋级方案。
• MLflow 2 → 3 迁移涉及基础设施（阶段、./mlruns 文件存储、MLServer），而不仅是客户端代码。

单个 API 问题不适用此技能——请直接阅读相关的 mlflow-3 规则。

工作流概览

0 assess ─▶ 1 domain-model ─▶ 2 environments ─▶ 3 instrument ─▶ 4 promote ─▶ 5 serve ─▶ 6 operate
  audit        registry           tracking per      training code    eval-gated    validate,     retrain loop,
  report       naming, alias      env (dev local,   → MLflow 3       copy_model_   serve,        challenger,
  (script,     + gate design      stg/prod DB+S3    idioms (rule     version +     smoke-test    maintenance
  read-only)   (interview)        + auth)           pack)            alias flip    /invocations  (gated)

阶段	操作	交付成果	风险
0	运行 scripts/00-assess.sh <codebase> — 只读审计	mlflow-assessment.md 报告	只读
1	访谈 + 领域建模	注册表领域文档（名称、别名、门禁）	只读
2	按环境搭建跟踪；通过 scripts/scaffold-dev-tracking.sh 配置 dev	可访问的跟踪服务（一个或多个），已填写的 config.json	写入
3	按 MLflow 3 惯用法重构训练代码（同级规则包）	重构后的代码，注册的首批 LoggedModels	写入
4	接入晋级流程 — 评估门禁、标签、copy_model_version、别名切换	晋级脚本/CI 任务	写入
5	提供服务 — mlflow.models.predict，然后执行 serve/build-docker，并对 /invocations 进行冒烟测试	每个环境都有已提供服务的模型	写入
6	运维 — 重新训练、挑战者评估、维护（参见工作流）	操作手册惯例、计划任务	写入
✓	在阶段 2–5 后运行 scripts/verify.sh	通过/失败断言报告	只读

各阶段按顺序执行——每个阶段的进入/退出条件见 references/workflow.md，scripts/verify.sh 是基础设施阶段的退出门禁。重新运行任何阶段都是安全的：00-assess.sh 只会重新生成自己的报告（不会覆盖其他内容），scaffold-dev-tracking.sh 会拒绝覆盖（退出码 2 = 已完成），verify.sh 只会读取数据。唯一不可幂等的步骤是晋级中的 copy_model_version — 如何恢复而不是重新复制，请参阅 references/promotion.md。

风险级别：写入

此工作流会编辑训练代码、写入基础设施文件并启动服务。防护措施：

• 阶段 0–1 不会修改任何内容——触碰代码或基础设施前，务必先完成这两个阶段。
• 在执行以下操作前，先征得用户确认：启动/替换任何跟踪服务、重写训练入口点、切换 prod 的 @champion 别名（dev/staging 的切换可由阶段 4 的流水线自动完成），以及将服务端点暴露到 localhost 之外。
• 两条维护命令具有破坏性，只有在用户明确确认并说明理由后才能运行：mlflow gc（永久删除软删除的运行和实验——不会触及注册表实体）和 mlflow db upgrade（不可逆的架构迁移——请先创建数据库快照）。hooks/hooks.json 中的 PreToolUse 钩子会阻止这两条命令运行，除非为该命令设置 MLFLOW_MAINTENANCE_ACK=yes，因此不会意外地在未经确认时运行。

要求

• 项目环境中需安装 Python ≥ 3.10 和 mlflow==3.15.1
• bash、curl、jq — 脚本会用到它们
• uv — 服务阶段会使用 --env-manager uv，以便快速重建隔离环境 （如果没有 uv，请将所有地方的 uv 替换为 virtualenv）
• Docker + docker-compose — 用于开发环境跟踪栈和 build-docker 服务镜像
• 每个共享环境（staging/prod）都需要数据库 + 对象存储 — PostgreSQL/MySQL 和 S3/GCS/Azure；开发环境使用搭建好的本地栈
• 同级的 mlflow-3 skill — 第 3 阶段会引用其中的规则；如果未安装，请改为阅读 MLflow 3 迁移指南（工作流仍可运行，但需要进行更多手动验证）

设置

config.json 初始为空。第 2 阶段会填入配置（各环境的跟踪 URI、注册表命名空间、 模型名称、服务 URL）。如果脚本需要某些字段时它们仍为空，脚本会指出具体字段 — 请通过文件中的 _setup_instructions 填写。

快速参考

我需要……	前往
审查代码库目前的功能	scripts/00-assess.sh <dir> + references/assessment.md
确定模型名称 / 别名 / 门禁	references/domain-modelling.md
用一条命令启动开发环境跟踪	scripts/scaffold-dev-tracking.sh <dir>
设计 staging/prod 跟踪拓扑	references/environments.md
重写 log_model / 阶段 / evaluate 调用	同级 mlflow-3 规则（log-*、reg-*、eval-*）
构建晋级流水线	references/promotion.md
提供模型服务并进行冒烟测试	references/serving.md
检查设置是否确实有效	scripts/verify.sh
查看每个阶段的进入 / 退出标准	references/workflow.md

注意事项

请参阅 gotchas.md — 运行此工作流时发现的故障点，包括 仅支持 SQLite 的 migrate-filestore 目标，以及基本身份验证的引导凭据。

相关技能

• mlflow-3 — 同级的库参考规则包，本工作流在每项 API 决策中都会引用它