YOLOv10 与 MLflow 集成实战：实验跟踪、指标记录与产物管理的完整指南

YOLOv10 与 MLflow 集成实战：实验跟踪、指标记录与产物管理的完整指南

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10

导读

本文基于当前仓库的 MLflow 集成实现，系统讲解如何为 YOLOv10（以及仓库中同样适用的 YOLOv8 等检测模型）接入 MLflow 实验追踪平台。你将掌握 MLflow 的安装与启用、实验名与运行名配置、本地 Tracking Server 的启动与关闭、训练过程中指标/参数/产物的自动记录原理，以及自定义指标与运行生命周期控制的进阶用法，让每一次训练都能沉淀为可复现、可对比的实验记录。

MLflow 是什么？为什么 YOLO 训练需要它

MLflow 是开源的机器学习全生命周期管理平台，提供实验跟踪、代码打包为可复现运行、模型共享与部署等能力，设计上兼容任意机器学习库与编程语言。对于 YOLO 这类需要反复调节数据集、模型结构、超参数与训练时长的任务，实验跟踪的价值在于：

• 可复现性：每次训练的超参数、环境信息与权重产物被完整归档，可随时回溯；
• 高效调优：通过曲线与表格对比不同实验的 mAP、loss 等指标，快速定位有效方向；
• 问题排查：训练中断或性能异常时，可从日志与指标序列中定位原因。

本仓库已在 ultralytics/utils/callbacks/mlflow.py 中内置了完整回调实现，无需额外编写业务代码，训练即可自动上报三类核心数据：

• 指标记录（Metrics Logging）：每个 epoch 结束时记录学习率、训练损失等指标，训练结束前记录最终指标；
• 参数记录（Parameter Logging）：训练启动时记录全部训练参数；
• 产物记录（Artifacts Logging）：训练结束时上传权重文件与配置文件等产物。

安装与启用 MLflow

安装 MLflow

pip install mlflow

在 Ultralytics 设置中启用 MLflow

MLflow 的启用开关由 Ultralytics 设置中的mlflow键控制。该键由 设置管理器 统一管理，默认值为True，设置文件位于用户配置目录下的settings.yaml，首次运行时会自动生成。可通过 Python API 或 CLI 两种方式修改。

Python 方式：

from ultralytics import settings # 更新设置，开启 MLflow settings.update({'mlflow': True}) # 重置设置为默认值 settings.reset()

CLI 方式：

# 更新设置（此处以修改 runs_dir 为例展示语法，mlflow 同理） yolo settings runs_dir='/path/to/runs' # 重置设置为默认值 yolo settings reset

注意：文档原文中的设置键写作mflow，仓库实际实现中该键为mlflow，请以仓库实现为准。可以运行yolo settings查看当前设置，或直接查看settings.yaml文件确认mlflow键的值。

核心实现：回调机制与记录时序

MLflow 的日志记录由on_pretrain_routine_end、on_train_epoch_end、on_fit_epoch_end、on_train_end四个回调函数承担，它们会在训练流程的对应阶段被自动调用。从源码看，这些回调在 mlflow.py 中以字典形式导出：

callbacks = ( { "on_pretrain_routine_end": on_pretrain_routine_end, "on_train_epoch_end": on_train_epoch_end, "on_fit_epoch_end": on_fit_epoch_end, "on_train_end": on_train_end, } if mlflow else {} )

关键在于：仅当环境变量与设置满足条件时，回调才会注册。模块导入时通过assert SETTINGS["mlflow"] is True与import mlflow验证集成是否启用，任一条件不满足则mlflow = None，回调字典为空，训练流程完全不感知 MLflow 的存在（mlflow.py）。此外，单元测试运行期间默认不会写入日志，除非当前 pytest 用例名为test_mlflow。

回调的注册链路为：训练器初始化时调用add_integration_callbacks（base.py），从clearml、comet、dvc、mlflow、neptune、raytune、tensorboard、wb等模块合并回调；执行阶段则由训练循环在对应节点调用self.run_callbacks(...)触发（见 trainer.py 中on_pretrain_routine_end、on_train_epoch_end、on_fit_epoch_end、on_train_end等调用点）。

四个回调各司其职，时序如下：

其中on_fit_epoch_end的注释明确说明 "fit = train + val"，即该回调覆盖了训练与验证两个阶段合并后的指标快照。

运行配置：实验名、运行名与 Tracking Server

设置实验名（Project / Experiment）

• 环境变量方式：

export MLFLOW_EXPERIMENT_NAME=<your_experiment_name>

• 训练参数方式：使用project=<project>参数，例如yolo train project=my_project。

从源码（mlflow.py）可见优先级为：MLFLOW_EXPERIMENT_NAME环境变量 >trainer.args.project> 默认值/Shared/YOLOv8。

设置运行名（Run Name）

• 环境变量方式：

export MLFLOW_RUN=<your_run_name>

• 训练参数方式：使用name=<name>参数，例如yolo train project=my_project name=my_name。

源码优先级为：MLFLOW_RUN环境变量 >trainer.args.name（未设置时run_name为None，由 MLflow 自动生成）。

启动本地 MLflow Server

mlflow server --backend-store-uri runs/mlflow

该命令默认在http://127.0.0.1:5000启动本地服务，并将所有日志保存到runs/mlflow目录。如需指定其他 URI，可设置环境变量：

export MLFLOW_TRACKING_URI=<your_tracking_uri>

未显式设置时，仓库实现默认将 tracking URI 指向RUNS_DIR / "mlflow"（即全局 runs 目录下的mlflow子目录），对应设置项runs_dir（mlflow.py）。训练启动时若检测到该目录为本地目录，控制台会打印提示，指引你用mlflow server --backend-store-uri <uri>在http://127.0.0.1:5000查看结果。

关闭 MLflow Server 实例

ps aux | grep 'mlflow' | grep -v 'grep' | awk '{print $2}' | xargs kill -9

该命令查找所有包含mlflow的进程、剔除 grep 自身，提取 PID 并强制结束。请确认执行环境为类 Unix 系统，且确实需要结束所有 MLflow 相关进程。

进阶用法：自定义指标与运行生命周期控制

记录自定义指标

文档提供的官方扩展点在trainer.metrics字典：在on_fit_epoch_end被调用之前向其中追加键值，即可让该指标随每个 fit epoch 一并上报。结合源码可知，on_fit_epoch_end会调用SANITIZE(trainer.metrics)，其中SANITIZE会将键中的左右括号移除（如metrics/mAP50-95变为metrics/mAP5095）并转为浮点数（mlflow.py），因此自定义指标名应避免使用括号。对应地，on_train_epoch_end使用trainer.lr与trainer.label_loss_items(...)记录学习率与逐组件训练损失。

使用MLFLOW_KEEP_RUN_ACTIVE控制 run 生命周期

默认情况下训练结束时 run 会自动结束（mlflow.end_run()）。若希望训练结束后继续向该 run 写入数据（例如事后补充指标或对比），可设置：

export MLFLOW_KEEP_RUN_ACTIVE=True

此时训练结束后 run 保持活跃，控制台会提示用mlflow.end_run()手动关闭。该行为在仓库测试 test_integrations.py 中有完整验证：设True时 run 状态为RUNNING，设False或不设置时状态为FINISHED。

一个端到端的最小示例

# 1. 安装依赖 pip install mlflow # 2. 启用集成（默认已开启，此处显式确认） yolo settings mlflow=True # 3. 指定实验与运行名 export MLFLOW_EXPERIMENT_NAME=yolov10-experiments export MLFLOW_RUN=first-run # 4. 启动本地 Tracking Server（后台） mlflow server --backend-store-uri runs/mlflow & # 5. 开始训练（训练结束会自动上报指标、参数与产物） yolo train data=coco8.yaml model=yolov10n.yaml epochs=50 imgsz=640

训练完成后，打开http://127.0.0.1:5000，选择实验与对应 run 即可查看指标曲线、超参数表格以及上传的权重和配置文件等产物。

查看实验结果

查看实验（Experiment）

在 MLflow 界面（默认http://127.0.0.1:5000）中选择实验，可看到该实验下所有 run 的指标对比。

查看运行（Run）

实验内的每个 Run 对应一次独立的模型训练。点击 Run 进入详情页，可查看该次训练的完整记录，包括上传的产物与模型权重（best.pt、last.pt等）。

禁用 MLflow

需要关闭集成时执行：

yolo settings mlflow=False

由于回调注册依赖SETTINGS["mlflow"] is True（mlflow.py），关闭后 MLflow 回调字典为空，训练全程不会产生任何 MLflow 日志，对训练流程零侵入。

测试验证与源码阅读指引

仓库通过 test_integrations.py 覆盖 MLflow 集成：test_mlflow开启设置后直接训练分类模型验证日志链路可用；test_mlflow_keep_run_active验证 run 生命周期控制。若需深入理解实现，建议按以下顺序阅读：

1. 回调定义与注册：ultralytics/utils/callbacks/mlflow.py
2. 回调合并机制：ultralytics/utils/callbacks/base.py
3. 设置管理（mlflow键与默认值）：ultralytics/utils/init.py
4. 训练循环中的回调触发点：ultralytics/engine/trainer.py

总结

MLflow 与 Ultralytics YOLO 的集成通过四个训练阶段回调实现了参数、指标与产物的全自动记录：训练前自动初始化跟踪环境并上报超参数，训练中逐 epoch 上报学习率与损失、逐 fit epoch 上报整体指标，训练结束时归档权重与配置文件。配合MLFLOW_EXPERIMENT_NAME、MLFLOW_RUN、MLFLOW_TRACKING_URI等环境变量和project/name训练参数，即可搭建一套完整、可复现、可对比的实验追踪体系，为 YOLO 模型的持续迭代提供数据支撑。

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10