如何用 mlflow migrate-filestore 把 MLflow 文件存储（mlruns）迁移到 SQLite 数据库
【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow
如果你的 MLflow 元数据一直存放在文件后端（./mlruns目录），现在想把它们迁移到数据库后端，MLflow 内置了mlflow migrate-filestore迁移命令来完成这件事。文件存储后端目前处于维护模式、不再获得功能更新，MLflow 建议通过这条迁移路径把已有数据无损地转入数据库。这篇文章给出从执行迁移、启动服务到验证结果的完整操作路径。
前提条件
需要安装 MLflow 3.10 或更高版本。用以下命令升级：
pip install 'mlflow>=3.10'如果正在运行 MLflow tracking server，迁移前必须先停掉它。
执行迁移命令
mlflow migrate-filestore --source /path/to/mlruns --target sqlite:///path/to/mlflow.db两个参数都需要替换为你自己的值：
--source：包含mlruns/FileStore 数据的根目录。/path/to/mlruns替换为你的mlruns目录实际路径，例如fs2db/README.md中给出的./mlruns。--target：目标 SQLite URI，必须以sqlite:///开头，例如sqlite:///mlflow.db。URI 中数据库文件的父目录必须已经存在，否则命令会直接报Parent directory does not exist错误。
此外还有一个可选参数--progress/--no-progress，默认开启，迁移过程中按实验输出进度信息。
命令会读取指定目录中的全部数据并写入指定的 SQLite 数据库。迁移对已迁移的数据是原子的：如果过程中出现任何错误，所有已插入的行都会回滚、不提交任何迁移数据，因此你可以在修复问题后安全地重新执行该命令。
需要注意两点限制（见 migrate-from-file-store.mdx）：
- 目标数据库必须为空。工具拒绝写入已包含数据的数据库以防冲突。如果目标文件已经存在，会提示是否覆盖（见 CLI 实现）。
- 只支持 SQLite 作为目标。原因是 FileStore 会生成超出 PostgreSQL 和 MySQL 32 位整数上限的大型实验 ID，而 SQLite 可以原生处理这些 ID。
迁移了哪些数据
工具会迁移文件后端中的全部元数据：
| 类别 | 实体 |
|---|---|
| Experiments | 实验、实验 tags |
| Runs | run、params、metrics、latest metrics、tags |
| Datasets | 数据集、inputs、input tags |
| Run I/O | 模型输入（run → model）、模型输出（run → model） |
| Traces | trace 信息、trace tags、trace 请求元数据 |
| Assessments | 评估（feedback、expectations） |
| Logged Models | 日志模型及其 tags |
| Model Registry | 注册模型、模型版本、tags、别名 |
| Prompts | 提示词（以注册模型和模型版本形式存储） |
迁移是无损的：实验、run、trace、model 等所有 ID 原样保留，creation_time、start_time、end_time、last_update_time等时间戳保留原有的毫秒精度，.trash目录中已删除的实验和 run 也会带着deleted生命周期阶段一并迁移，artifact URI 保持不变。
不会迁移的内容：
- Artifacts（模型文件、图片等）留在原位置不动，数据库里存储的 artifact URI 仍指向原有文件。
- Trace spans以 artifact 文件形式存储，不进入数据库。
用新数据库启动服务并验证
迁移完成后，显式指定新数据库启动 tracking server：
mlflow server --backend-store-uri sqlite:///path/to/mlflow.db这里要显式指定--backend-store-uri是有原因的：如果没有显式设置，tracking server 在./mlruns中检测到已有文件后端实验数据时会优先使用./mlruns，否则回退到sqlite:///mlflow.db。依赖这种默认行为容易让服务继续读旧的文件存储，因此迁移后应始终显式指向新数据库。
启动后打开 MLflow UI，确认你的实验、runs 和模型都在，即表示迁移成功。
边界说明与相关路径
和
mlflow-export-import的区别：后者是另一个独立工具，用于在两个运行中的 MLflow server 之间复制对象（runs、实验、注册模型等）。它不保留原始 ID 和时间戳，且要求源和目标 server 都在运行。如果你要保留 ID 和时间戳、从文件存储迁到数据库，用migrate-filestore，而不是mlflow-export-import。确有必要继续用文件系统后端时的逃生口：在极少数无法迁移的场景（例如浏览从无法运行数据库的 HPC 集群同步过来的只读
mlruns数据，或用rsync在机器间共享目录快照），可以在启动 server 或运行客户端代码之前设置环境变量来关闭该异常：export MLFLOW_ALLOW_FILE_STORE=true mlflow server --backend-store-uri ./mlruns这个选项仅用于确实受约束的工作流，正常情况下仍应使用上面的迁移工具。
源码入口可参考 迁移命令 CLI 定义 与 fs2db/README.md。
如果遇到 PostgreSQL/MySQL 支持相关的问题或想反馈，文档指引到 MLflow 的 GitHub issue #18534（详见 migrate-from-file-store.mdx 的 Feedback 一节）。
【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
