使用 Neptune 进行实验跟踪

Neptune 是一个用于 MLOps 的元数据存储库，专为进行大量实验的团队构建。它为你提供了一个统一的地方，用于记录、存储、显示、组织、比较和查询你所有的模型构建元数据。

Ultralytics YOLO26 与 Neptune 集成，以简化实验跟踪。通过此集成，你无需编写自定义日志代码即可自动记录训练指标、可视化模型预测并存储模型制品。

主要特性

• 自动日志记录：自动记录关键训练指标，例如 box loss、classification loss 和 mAP。
• 图像可视化：直接在 Neptune 仪表板中查看训练马赛克图和验证预测结果。
• 模型检查点：在训练结束时自动上传并版本控制你训练好的模型权重（best.pt）。
• 超参数跟踪：记录所有配置参数，以确保实验的完全可重复性。
• 交互式图表：可视化混淆矩阵和精确率-召回率曲线，以分析模型性能。

安装

要将 Neptune 与 Ultralytics 一起使用，你需要安装 neptune 客户端包以及 ultralytics。

# Install the required packages
pip install ultralytics neptune

# Enable Neptune integration in Ultralytics settings
yolo settings neptune=True

配置

在开始训练之前，你需要将本地环境连接到你的 Neptune 项目。你需要从 Neptune 仪表板获取 API Token 和 Project Name。

获取你的凭据

1. 登录到 Neptune.ai。
2. 创建一个新项目（或选择一个现有项目）。
3. 转到用户菜单并获取你的 API Token。

设置环境变量

The securest way to handle credentials is via environment variables. Note that the Ultralytics Neptune callback reads the YOLO project argument and does not use NEPTUNE_PROJECT. Pass the full Neptune slug (e.g., workspace/name) via project= in your training command; otherwise Neptune will try to use the literal default "Ultralytics" and the run will fail.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

使用方法

配置完成后，你就可以开始训练 YOLO26 模型了。当安装了 neptune 包且在设置中启用了集成时，Neptune 集成会自动工作。

训练示例

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")

# Train the model
# Pass the Neptune project slug as the 'project' argument (workspace/name)
results = model.train(data="coco8.yaml", epochs=10, project="my-workspace/my-project", name="experiment-1")

了解集成

下图展示了 Ultralytics 训练流水线如何与 Neptune 交互以记录各种制品和指标。

graph LR
    A[YOLO Training Loop] --> B{Neptune Callback}
    B -->|Log Scalars| C[Loss, mAP, LR]
    B -->|Log Images| D[Mosaics, Preds]
    B -->|Log Artifacts| E[Model Weights]
    B -->|Log Metadata| F[Hyperparameters]

    C --> G[Neptune Server]
    D --> G
    E --> G
    F --> G

    G --> H[Neptune Web Dashboard]

记录了什么？

当你运行训练命令时，Neptune 集成会自动在你的运行中捕获以下数据结构：

1. 配置/超参数：所有训练参数（epochs、lr0、optimizer 等）都记录在 Configuration 部分下。
2. 配置/模型：模型架构和定义。
3. 指标：
   • 训练：box_loss、cls_loss、dfl_loss、lr（学习率）。
   • 指标：precision、recall、mAP50、mAP50-95。
4. 图像：
   • Mosaic：显示数据增强的训练批次。
   • Validation：验证数据上的真实标签和模型预测。
   • Plots：混淆矩阵、精确率-召回率曲线。
5. 权重：最终训练的模型（best.pt）被上传到 Neptune 运行中的 weights 文件夹。

高级用法

组织运行

你可以使用标准的 Ultralytics project 和 name 参数来组织你在 Neptune 中的运行。

• project：必须是 Neptune 项目 slug workspace/name；这是回调传递给 neptune.init_run 的内容。
• name：充当特定运行的标识符。

自定义日志记录

如果你需要在自动记录的同时记录额外的自定义指标，可以访问 Neptune 运行实例。请注意，由于 Ultralytics 集成在内部处理运行生命周期，你需要修改训练器逻辑或创建自定义回调来访问特定的运行对象。

常见问题 (FAQ)

如何禁用 Neptune 日志记录？

如果你已经安装了 neptune 但希望为特定会话或全局禁用日志记录，你可以修改 YOLO 设置。

# Disable Neptune integration
yolo settings neptune=False

我的图像没有上传。出了什么问题？

确保你的网络允许连接到 Neptune 的服务器。此外，图像日志记录通常在特定间隔（例如 epoch 结束或训练结束）进行。如果你使用 Ctrl+C 提前中断训练，一些最终制品（如混淆矩阵或最佳模型权重）可能无法上传。

我可以记录到特定的 Neptune 运行 ID 吗？

当前的集成会自动为每个训练会话创建一个新的运行。要恢复记录到现有的运行，你通常需要在 Python 代码中手动处理 Neptune 初始化，这超出了自动集成的范围。不过，Ultralytics 支持在本地恢复训练，这将会在 Neptune 中创建一个新的运行来跟踪恢复的 epoch。

我在哪里可以在 Neptune 中找到模型权重？

In your Neptune dashboard, navigate to the Artifacts or All Metadata section. You will find a weights folder containing your best.pt file, which you can download for deployment.