Meet YOLO26: next-gen vision AI.

Link to this section排查常见 YOLO 问题#

YOLO common training and deployment issues

Link to this section简介#

本指南旨在为你排查在使用 YOLO26 和 Ultralytics 项目时遇到的常见问题提供全面帮助。通过正确的指引，你能轻松解决这些问题，确保项目按计划进行，避免不必要的延误。



Watch: Ultralytics YOLO26 Common Issues | Installation Errors, Model Training Issues

Link to this section常见问题#

Link to this section安装错误#

安装错误可能由多种原因引起，例如版本不兼容、缺少依赖项或环境设置不正确。首先，请确保你已完成以下操作：

  • 你正在使用建议的 Python 3.8 或更高版本。
  • 确保已安装正确版本的 PyTorch（1.8 或更高版本）。
  • 考虑使用虚拟环境以避免冲突。
  • 请按步骤参考 官方安装指南。

此外，以下是用户遇到的一些常见安装问题及其相应的解决方案：

  • 导入错误或依赖项问题 - 如果你在导入 YOLO26 时遇到错误，或者遇到与依赖项相关的问题，请考虑以下排查步骤：

    • 全新安装：有时，通过全新安装可以解决意料之外的问题。尤其是对于像 Ultralytics 这样的库，更新可能会引入文件树结构或功能上的变更。

    • 定期更新：确保你使用的是该库的最新版本。旧版本可能与近期的更新不兼容，从而导致潜在的冲突或问题。

    • 检查依赖项：验证所有必需的依赖项是否已正确安装，且版本是否兼容。

    • 查看变更：如果你最初克隆或安装的是旧版本，请注意重大更新可能会影响库的结构或功能。务必查阅官方文档或更新日志，以了解任何重大变更。

    • 请记住，保持库和依赖项为最新状态对于获得流畅且无错误的使用体验至关重要。

  • 在 GPU 上运行 YOLO26 - 如果你在 GPU 上运行 YOLO26 时遇到困难，请考虑以下排查步骤：

    • 验证 CUDA 兼容性与安装：确保你的 GPU 支持 CUDA 且已正确安装 CUDA。使用 nvidia-smi 命令检查你的 NVIDIA GPU 状态和 CUDA 版本。

    • 检查 PyTorch 与 CUDA 的集成：通过在 Python 终端中运行 import torch; print(torch.cuda.is_available()) 来确保 PyTorch 可以使用 CUDA。如果返回“True”，则表示 PyTorch 已配置为使用 CUDA。

    • 检查 GPU 兼容性：自 cuDNN 9.11.0 起，已不再支持 Turing 架构之前且计算能力 (SM) < 7.5 的 GPU。因此，如果你使用的是旧款 GPU（例如 1080Ti），你可能需要使用基于旧版 CUDA/cuDNN 构建的 PyTorch 版本。你可以通过运行 import torch; cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0); cudnn = torch.backends.cudnn.version() or 0; ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"; print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}") 来进行检查。

    • 激活环境：确保你处于正确安装了所有必要包的环境中。

    • 更新你的包：过时的包可能与你的 GPU 不兼容。请保持它们更新。

    • 程序配置：检查程序或代码是否指定了 GPU 使用。在 YOLO26 中，这可能位于设置或配置中。

Link to this section模型训练问题#

本节将解决训练过程中遇到的常见问题及其解释和解决方案。

Link to this section验证配置设置#

问题：你不确定在模型训练期间，.yaml 文件中的配置设置是否已正确应用。

Solution: The configuration settings in the .yaml file should be applied when using the model.train() function. To ensure that these settings are correctly applied, follow these steps:

  • 确认指向你的 .yaml 配置文件的路径是否正确。

  • Make sure you pass the path to your .yaml file as the data argument when calling model.train(), as shown below:

    model.train(data="/path/to/your/data.yaml", batch=4)

Link to this section使用多 GPU 加速训练#

问题：单 GPU 训练速度缓慢，你想使用多个 GPU 来加快进程。

解决方案：增加 batch size 可以加快训练速度，但必须考虑 GPU 显存容量。要使用多个 GPU 加速训练，请遵循以下步骤：

  • 确保你有多个 GPU 可用。

  • 将 device 参数设置为 GPU 索引列表，例如 device=[0,1,2,3]。

  • 相应地增加 batch size，以充分利用多个 GPU，同时不超过显存限制。

  • 修改你的训练命令以利用多个 GPU：

    # Adjust the batch size and other settings as needed to optimize training speed
model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Link to this section持续监控参数#

问题：你想知道除了损失（loss）之外，在训练期间应该持续监控哪些参数。

解决方案：虽然损失是需要监控的关键指标，但为了优化模型性能，跟踪其他指标同样重要。训练期间需要监控的一些关键指标包括：

你可以从训练日志中获取这些指标，或使用 TensorBoard 或 wandb 等工具进行可视化。根据这些指标实施提前停止（early stopping）有助于你获得更好的结果。

Link to this section跟踪训练进度的工具#

问题：你正在寻找跟踪训练进度的工具建议。

解决方案：要跟踪和可视化训练进度，你可以考虑使用以下工具：

  • TensorBoard：TensorBoard 是可视化训练指标（包括损失、准确率等）的热门选择。你可以将其与你的 YOLO26 训练过程集成。
  • Comet：Comet 提供了一套用于实验跟踪和对比的完整工具包。它允许你跟踪指标、超参数，甚至模型权重。与 YOLO 模型的集成也非常简单，为你提供了实验周期的完整概览。
  • Ultralytics Platform: Ultralytics Platform 为跟踪 YOLO 模型提供了专门的环境，为你提供了一个管理指标、数据集甚至与团队协作的一站式平台。鉴于其对 YOLO 的定制化关注，它提供了更个性化的跟踪选项。

这些工具各有优势，因此在选择时，你可能需要考虑项目的具体需求。

Link to this section如何检查训练是否在 GPU 上进行#

问题：训练日志中的 'device' 值为 'null'，你不确定训练是否正在 GPU 上运行。

解决方案：'device' 值为 'null' 通常意味着训练进程被设置为自动使用可用的 GPU，这是默认行为。要确保训练在特定 GPU 上进行，你可以手动在 .yaml 配置文件中将 'device' 值设置为 GPU 索引（例如，'0' 表示第一个 GPU）：

device: 0

这将明确将训练进程分配给指定的 GPU。如果你希望在 CPU 上训练，请将 'device' 设置为 'cpu'。

密切关注 'runs' 文件夹中的日志和指标，以有效地监控训练进度。

Link to this section高效模型训练的关键考量#

如果你在模型训练相关方面遇到问题，这里有一些需要牢记的事项。

数据集格式与标签

  • 重要性：任何 机器学习 模型的基础都取决于其训练数据的质量和格式。
  • 建议：确保你的自定义数据集及其相关标签符合预期格式。验证标注是否准确且高质量至关重要。错误或次优的标注可能会阻碍模型的学习过程，导致不可预测的结果。

模型收敛

  • 重要性：实现模型收敛可确保模型已充分从 训练数据 中学习。
  • 建议：在“从零开始”训练模型时，确保模型达到令人满意的收敛水平至关重要。与微调现有模型相比，这可能需要更长的训练时间和更多的 轮次。

学习率 与 Batch Size

  • 重要性：这些超参数在决定模型训练期间如何更新其权重方面起着关键作用。
  • 建议：定期评估所选的学习率和 batch size 是否针对你的特定数据集进行了优化。与数据集特征不匹配的参数可能会阻碍模型的性能。

类别分布

  • 重要性：数据集中类别的分布会影响模型的预测倾向。
  • 建议：定期评估数据集中各类别的分布情况。如果存在类别不平衡，模型就有偏向多数类的风险。这种偏差在混淆矩阵中可以体现出来，即模型可能会主要预测多数类。

使用预训练权重进行交叉检查

  • 重要性：利用预训练权重可以为模型训练提供良好的起点，特别是在数据有限的情况下。
  • 建议：作为诊断步骤，考虑使用相同数据训练模型，但使用预训练权重进行初始化。如果这种方法产生了形状良好的混淆矩阵，则可能暗示“从零开始”的模型可能需要进一步训练或调整。

Link to this section与模型预测相关的问题#

本节将解决模型预测期间遇到的常见问题。

Link to this section使用 YOLO26 自定义模型获取边界框预测#

问题：在使用自定义 YOLO26 模型进行预测时，边界框坐标的格式和可视化存在挑战。

解决方案：

  • 坐标格式：YOLO26 提供绝对像素值的边界框坐标。要将它们转换为相对坐标（范围从 0 到 1），你需要除以图像尺寸。例如，假设你的图像大小为 640x640。那么你需要执行以下操作：

    # Convert absolute coordinates to relative coordinates
x1 = x1 / 640  # Divide x-coordinates by image width
x2 = x2 / 640
y1 = y1 / 640  # Divide y-coordinates by image height
y2 = y2 / 640

  • 文件名：要获取你正在预测的图像的文件名，请直接从预测循环内的结果对象访问图像文件路径。

Link to this section在 YOLO26 预测中过滤对象#

问题：在使用 Ultralytics 库运行 YOLO26 时，遇到关于如何仅在预测结果中过滤和显示特定对象的问题。

解决方案：要检测特定类别，请使用 classes 参数来指定你想要包含在输出中的类别。例如，只检测汽车（假设 'cars' 的类别索引为 2）：

yolo task=segment mode=predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

Link to this section了解 YOLO26 中的精度指标#

问题：对 YOLO26 中边界框精度、掩码精度和 混淆矩阵 精度之间的区别感到困惑。

解决方案：边界框精度使用 IoU (交并比) 作为指标，衡量预测边界框与实际真值框的准确度。掩码精度评估预测分割掩码与像素级对象分类中真值掩码之间的一致性。另一方面，混淆矩阵精度侧重于所有类别上的整体分类准确度，并不考虑预测的几何精度。需要注意的是，即使类别预测错误，边界框 也可以在几何上是准确的（真阳性），这会导致边界框精度和混淆矩阵精度之间的差异。这些指标评估了模型性能的不同方面，反映了在不同任务中需要不同评估指标的需求。

Link to this section在 YOLO26 中提取对象尺寸#

问题：在 YOLO26 中检索检测到的对象的长度和高度有困难，特别是当图像中检测到多个对象时。

解决方案：要检索边界框尺寸，首先使用 Ultralytics YOLO26 模型检测图像中的对象。然后，从预测结果中提取边界框的宽度和高度信息。

from ultralytics import YOLO

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

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

Link to this section部署挑战#

Link to this sectionGPU 部署问题#

问题： 在多 GPU 环境中部署模型有时会导致意外行为，如意外的显存使用、跨 GPU 结果不一致等。

解决方案： 检查默认的 GPU 初始化。某些框架（如 PyTorch）可能会在过渡到指定 GPU 之前在默认 GPU 上初始化 CUDA 操作。为了绕过意外的默认初始化，请在部署和预测期间直接指定 GPU。然后，使用工具监控 GPU 利用率和显存使用情况，以实时识别任何异常。此外，确保你使用的是框架或库的最新版本。

Link to this section模型转换/导出问题#

问题： 在将机器学习模型转换或导出为不同格式或平台的过程中，用户可能会遇到错误或意外行为。

解决方案：

  • 兼容性检查：确保你使用的库和框架版本彼此兼容。版本不匹配可能会导致转换期间出现意外错误。
  • 环境重置：如果你使用的是 Jupyter 或 Colab 等交互式环境，请考虑在进行重大变更或安装后重启你的环境。重新开始有时可以解决潜在问题。
  • 官方文档：务必查阅你所使用的工具或库的官方文档进行转换。它通常包含有关模型导出的具体指导和最佳实践。
  • 社区支持：查看该库或框架的官方仓库，了解其他用户报告的类似问题。维护者或社区可能已经在讨论区提供了解决方案或变通方法。
  • 定期更新：确保你使用的是工具或库的最新版本。开发者会经常发布更新，修复已知 Bug 或改进功能。
  • 增量测试：在执行完整转换之前，先用较小的模型或数据集测试该过程，以便尽早发现潜在问题。

Link to this section社区与支持#

与志同道合的社区成员互动可以极大地提升你在 YOLO26 方面的体验和成就。以下是一些你可能会觉得有用的渠道和资源。

Link to this section寻求帮助的论坛与频道#

GitHub Issues： YOLO26 GitHub 仓库有一个 Issues 标签页，你可以在那里提出问题、报告 Bug 并建议新功能。社区成员和维护者非常活跃，这是获取特定问题帮助的好地方。

Ultralytics Discord 服务器： Ultralytics 拥有一个 Discord 服务器，你可以在那里与其他用户和开发者进行交流。

Link to this section官方文档和资源#

Ultralytics YOLO26 文档：官方文档提供了对 YOLO26 的全面概述，以及安装、使用和故障排除指南。

这些资源将为解决故障和改进你的 YOLO26 项目，以及与 YOLO26 社区中的其他人建立联系提供坚实的基础。

Link to this section结论#

故障排除是任何开发过程中不可或缺的一部分，掌握正确的知识可以显著减少解决问题所花费的时间和精力。本指南旨在解决 Ultralytics 生态系统中 YOLO26 模型用户最常遇到的挑战。通过理解并解决这些常见问题，你可以确保项目进展更顺利，并在 computer vision 任务中取得更好的结果。

请记住，Ultralytics 社区是一份宝贵的资源。与同行开发者和专家交流可以提供标准文档中可能未涵盖的额外见解和解决方案。始终保持学习、实验并分享你的经验，为社区的集体知识做出贡献。

Link to this section常见问题解答#

Link to this section如何解决 YOLO26 的安装错误？#

安装错误通常是由于兼容性问题或缺少依赖项导致的。请确保你使用的是 Python 3.8 或更高版本，并安装了 PyTorch 1.8 或更高版本。使用虚拟环境来避免冲突是非常有益的。如需逐步安装指南，请参考我们的 官方安装指南。如果你遇到导入错误，请尝试全新安装或将库更新至最新版本。

Link to this section为什么我的 YOLO26 模型在单 GPU 上训练缓慢？#

在单 GPU 上训练可能会因为批量大小（batch size）过大或内存不足而变慢。为了加快训练速度，请使用多个 GPU。确保你的系统有多个 GPU 可用，并设置 device 参数，例如 device=[0,1,2,3]。相应地增加批量大小，以充分利用 GPU 而不超过内存限制。命令示例：

model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Link to this section如何确保我的 YOLO26 模型正在 GPU 上进行训练？#

如果训练日志中的 'device' 值显示为 'null'，这通常意味着训练过程被设置为自动使用可用的 GPU。要明确指定某个 GPU，请在你的 .yaml 配置文件中设置 'device' 值。例如：

device: 0

这会将训练过程设置在第一个 GPU 上。请参考 nvidia-smi 命令以确认你的 CUDA 设置。

Link to this section我该如何监控和跟踪我的 YOLO26 模型训练进度？#

跟踪和可视化训练进度可以通过 TensorBoard、Comet 和 Ultralytics Platform 等工具高效管理。这些工具允许你记录并可视化损失、precision、recall 和 mAP 等指标。基于这些指标实施 early stopping 也有助于获得更好的训练结果。

Link to this section如果 YOLO26 无法识别我的数据集格式，我该怎么办？#

确保你的数据集和标签符合预期格式。验证标注是否准确且质量高。如果你遇到任何问题，请参考 数据收集与标注 指南以了解最佳实践。如需更多针对数据集的指导，请查看文档中的 Datasets 部分。

贡献者
GLglenn-jocher14RIRizwanMunawar4ARartest081PDpderrenger1AKakdanz1Y-Y-T-G1WIWillie Maddox1LALaughing-q1

评论