在 GitHub 上编辑此页面 (EN)

排查常见 YOLO 问题

YOLO common training and deployment issues

介绍

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



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

常见问题

安装错误

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

  • 你正在使用推荐的 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 之前的 GPU 架构和计算能力 (SM) < 7.5。因此，如果你拥有较旧的 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 中，这可能在设置或配置文件中。

模型训练问题

本节将解决训练过程中遇到的常见问题，并提供相应的解释和解决方案。

配置设置验证

问题：你不确定在模型训练期间是否正确应用了 .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)

使用多 GPU 加速训练

问题：单 GPU 训练速度慢，你希望利用多个 GPU 加速过程。

解决方案：增加 batch size 可以加快训练速度，但必须考虑 GPU 显存容量。要通过多 GPU 加速训练，请按照以下步骤操作：

  • 确保你有多个可用的 GPU。

  • 修改你的 .yaml 配置文件以指定要使用的 GPU 数量，例如 gpus: 4。

  • 相应地增加 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)

持续监控参数

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

解决方案：虽然 loss 是一个关键的监控指标，但跟踪其他指标对于模型性能优化也至关重要。训练期间需要监控的一些关键指标包括：

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

跟踪训练进度的工具

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

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

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

这些工具中的每一个都有其各自的优势，因此在做出选择时，你可能需要考虑项目的具体需求。

如何检查训练是否在 GPU 上运行

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

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

device: 0

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

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

有效模型训练的关键注意事项

如果你遇到与模型训练相关的问题，请记住以下几点。

数据集格式和标签

  • 重要性：任何 机器学习 模型的基础都在于其所训练数据的质量和格式。
  • 建议：确保你的自定义数据集及其关联标签符合预期的格式。验证标注的准确性和高质量至关重要。不正确或低质量的标注可能会破坏模型的学习过程，导致不可预见的结果。

模型收敛

  • 重要性：实现模型收敛可确保模型已从训练数据中充分学习。
  • 建议：当从头开始（'from scratch'）训练模型时，确保模型达到令人满意的收敛水平至关重要。与微调现有模型相比，这可能需要更长的训练时间以及更多的 epoch。

学习率和 Batch Size

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

类别分布

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

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

  • 重要性：利用预训练权重可以为模型训练提供一个坚实的起点，尤其是在数据有限的情况下。
  • 建议：作为一种诊断步骤，考虑使用相同的数据训练你的模型，但用预训练权重进行初始化。如果这种方法产生了格式良好的混淆矩阵，则可能表明从头训练的模型可能需要进一步的训练或调整。

与模型预测相关的问题

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

获取 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

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

在 YOLO26 预测中过滤对象

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

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

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

了解 YOLO26 中的精度指标

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

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

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

部署挑战

GPU 部署问题

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

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

模型转换/导出问题

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

解决方案：

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

社区与支持

与志同道合的社区互动可以显著提高你在使用 YOLO26 时的体验和成功率。以下是你可能会觉得有帮助的一些频道和资源。

获取帮助的论坛和渠道

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

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

官方文档和资源

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

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

总结

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

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

常见问题 (FAQ)

如何解决 YOLO26 的安装错误？

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

为什么我的 YOLO26 模型在单个 GPU 上训练缓慢？

在单个 GPU 上训练可能会因批次大小过大或内存不足而变慢。要加快训练速度，请使用多个 GPU。确保你的系统有多个 GPU 可用，并调整你的 .yaml 配置文件以指定 GPU 数量，例如 gpus: 4。相应地增加批次大小，以在不超过内存限制的情况下充分利用 GPU。示例命令：

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

如何确保我的 YOLO26 模型正在 GPU 上进行训练？

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

device: 0

这会将训练过程设置为使用第一个 GPU。请参考 nvidia-smi 命令来确认你的 CUDA 设置。

如何监控和跟踪我的 YOLO26 模型训练进度？

通过 TensorBoard、Comet 和 Ultralytics Platform 等工具，可以有效地管理和可视化训练进度。这些工具允许你记录和可视化诸如 loss、precision、recall 和 mAP 等指标。基于这些指标实施提前停止也有助于取得更好的训练结果。

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

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

Contributors
在 GitHub 上编辑此页面 (EN)
GLglenn-jocher13RIRizwanMunawar4ARartest081PDpderrenger1AKakdanz1Y-Y-T-G1WIWillie Maddox1LALaughing-q1

评论