使用 Neptune 进行实验跟踪

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

Ultralytics YOLO11 与 Neptune 集成，以简化实验跟踪。这种集成允许您自动记录训练指标、可视化模型预测并存储模型工件，而无需编写自定义日志代码。

主要功能

• 自动化日志记录: 自动记录关键训练指标，例如边界框损失、分类损失和 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 令牌和 项目名称。

1. 获取您的凭据

1. 登录 Neptune.ai。
2. 创建一个新项目（或选择一个现有项目）。
3. 前往您的用户菜单并获取您的API 令牌。

2. 设置环境变量

处理凭据最安全的方式是通过环境变量。请注意，Ultralytics Neptune回调会读取YOLO project 参数，并且不使用 NEPTUNE_PROJECT。传递完整的Neptune slug（例如， workspace/name) 通过 project= 在您的训练命令中；否则Neptune将尝试使用字面默认值 "Ultralytics" 否则运行将失败。

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

$Env:NEPTUNE_API_TOKEN = "your_long_api_token_here"  # required

import os

os.environ["NEPTUNE_API_TOKEN"] = "your_long_api_token_here"
os.environ["NEPTUNE_PROJECT"] = "your_workspace/your_project"

用法

配置完成后，您可以开始训练您的 YOLO11 模型。当...时，Neptune 集成会自动工作 neptune 包已安装且集成已在设置中启用。

训练示例

from ultralytics import YOLO

# Load a model
model = YOLO("yolo11n.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")

# Train via CLI
# project must be the Neptune slug (workspace/name); otherwise run creation will fail
yolo 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 等）都记录在配置部分。
2. 配置/模型：模型架构和定义。
3. 指标:
   • 训练: box_loss, cls_loss, dfl_loss, lr (学习率)。
   • 指标: precision, recall, mAP50, mAP50-95.
4. 图像:
   • Mosaic：显示数据增强的训练批次。
   • Validation：验证数据上的真实标签和模型预测。
   • Plots：混淆矩阵、精确率-召回率曲线。
5. 权重：最终训练好的模型（best.pt) 上传到 weights 在 Neptune 运行中的文件夹。

高级用法

组织运行

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

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

自定义日志记录

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

常见问题

如何禁用 Neptune 日志记录？

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

# Disable Neptune integration
yolo settings neptune=False

我的图片无法上传。出了什么问题？

确保您的网络允许连接到 Neptune 的服务器。此外，图像日志记录通常在特定时间间隔发生（例如，每个 epoch 结束或训练结束时）。如果您提前中断训练，使用 Ctrl+C，一些最终的工件，例如混淆矩阵或最佳模型权重，可能不会被上传。

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

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

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

在您的Neptune仪表板中，导航到 工件 或 所有元数据 部分。您会找到一个 weights 包含您的...的文件夹 best.pt 文件，您可以下载用于部署。

📅创建于12天前 ✏️更新于12天前

评论