Link to this section使用 Neptune 进行实验跟踪#

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

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

Link to this section主要特性#

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

Link to this section安装#

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

# Install the required packages
pip install ultralytics neptune

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

Link to this section配置#

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

Link to this section获取你的凭据#

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

Link to this section设置环境变量#

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

Link to this section使用方法#

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

Link to this section训练示例#

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")

Link to this section了解集成#

下图展示了 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]

Link to this section记录了什么？#

当你运行训练命令时，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 文件夹。

Link to this section高级用法#

Link to this section组织运行#

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

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

Link to this section自定义日志记录#

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

Link to this section常见问题 (FAQ)#

Link to this section如何禁用 Neptune 日志记录？#

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

# Disable Neptune integration
yolo settings neptune=False

Link to this section我的图像没有上传。出了什么问题？#

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

Link to this section我可以记录到特定的 Neptune 运行 ID 吗？#

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

Link to this section我在哪里可以在 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.