YOLO 常见问题排查#

本指南涵盖你使用 Ultralytics YOLO26 时最常遇到的问题，并按问题发生的位置分组：安装、模型训练、预测和部署。跳转到与你的错误匹配的类别，或查看 FAQ 获取快速解答。每个条目都会说明问题并提供可以直接应用的具体修复方法。

常见问题#

安装错误#

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

• 按照建议使用 Python 3.8 或更高版本。
• 确保已安装正确版本的 PyTorch（1.8 或更高版本）。
• 考虑使用虚拟环境来避免冲突。
• 按照官方安装指南逐步操作。

此外，以下是常见安装问题的解决方案。

导入错误或依赖项问题#

如果导入 YOLO26 时出现错误，或遇到依赖项冲突，请尝试以下步骤：

• 全新安装：从干净的安装开始可以解决意外问题，尤其是在更新改变了软件包结构或功能之后。
• 定期更新：使用最新版本的库，因为旧版本可能与近期更新不兼容。
• 检查依赖项：确认所有必需的依赖项都已正确安装，并且版本相互兼容。
• 查看变更：如果你安装的是旧版本，请参考官方文档或变更日志，了解是否发生了重大的结构变更。

在 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 不兼容。请保持软件包为最新版本。
• 程序配置：检查代码是否请求使用 GPU。运行训练或预测时，可以设置 device 参数（例如 device=0）。

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

模型训练问题#

下面介绍常见的训练问题及其修复方法。

验证配置设置#

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

解决方案：使用 model.train() 函数时，应应用 .yaml 文件中的配置设置。请按照以下步骤确保这些设置已正确应用：

• 确认 .yaml 配置文件的路径正确。

• 调用 model.train() 时，确保将 .yaml 文件的路径作为 data 参数传入，如下所示：

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

使用多个 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])

持续监控参数#

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

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

• 精确率
• 召回率
• 平均精度均值 (mAP)

你可以从训练日志中访问这些指标，或使用 TensorBoard 或 Weights & Biases 等工具进行可视化。基于这些指标实现早停可以帮助你取得更好的结果。

跟踪训练进度的工具#

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

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

• TensorBoard：TensorBoard 是用于可视化训练指标的常用工具，包括 loss、准确率等。你可以将它集成到 YOLO26 训练流程中。
• Comet：Comet 提供了用于实验跟踪和比较的完整工具包。它可以跟踪指标、超参数，甚至模型权重。它还可以轻松集成 YOLO 模型，让你全面了解实验周期。
• Ultralytics Platform：Ultralytics Platform 提供了用于跟踪 YOLO 模型的专业环境，让你可以在一个平台上管理指标、数据集，甚至与团队协作。由于专注于 YOLO，它提供了更多定制化的跟踪选项。

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

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

解决方案：'device' 值为 'null' 通常表示训练过程设置为自动选择可用的 GPU，这是默认行为。要在指定的 GPU 上训练，请在开始训练时设置 device 参数。device 是训练参数，因此在数据集 .yaml 中设置它不会生效：

from ultralytics import YOLO

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

# Use GPU 0; device=[0, 1] for multiple GPUs, device="cpu" for CPU
model.train(data="path/to/data.yaml", device=0)

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

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

如果你遇到与模型训练相关的问题，请注意以下事项。

数据集格式和标签

• 重要性：机器学习模型的基础在于其训练数据的质量和格式。
• 建议：确保你的自定义数据集及其相关标签符合预期格式。务必验证标注准确且质量良好。不正确或质量较差的标注可能会破坏模型的学习过程，导致不可预测的结果。

模型收敛

• 重要性：实现模型收敛可以确保模型已从训练数据中充分学习。
• 建议：从头开始训练模型时，务必确保模型达到令人满意的收敛程度。与微调现有模型相比，这可能需要更长的训练时间和更多的 epochs。

学习率和 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 segment predict 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 上初始化 CUDA 操作，然后再切换到指定的 GPU。要绕过意外的默认初始化，请在部署和预测期间直接指定 GPU。然后使用工具监控 GPU 利用率和内存使用情况，以实时识别异常。同时确保使用框架或库的最新版本。

模型转换/导出问题#

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

**解决方案：**查看导出模式文档中支持的格式和每种格式的选项，然后完成以下检查：

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

社区与支持#

通过以下渠道和资源获取帮助并分享解决方案。

获取帮助的论坛和渠道#

**GitHub Issues：**Ultralytics 在 GitHub 上的仓库有一个 Issues 标签页，你可以在这里提问、报告漏洞并建议新功能。社区和维护者在这里很活跃，这里是获得解决特定问题帮助的好地方。

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

官方文档和资源#

Ultralytics YOLO26 文档：官方文档全面介绍了 YOLO26，并提供安装、使用和故障排除指南。

结论#

大多数 YOLO26 问题都可以追溯到几个常见原因：版本不匹配、数据集格式问题和 GPU 配置问题。如果这里没有涵盖你的错误，请搜索 GitHub Issues 选项卡，或在 Discord 服务器上提问——很可能已经有人解决过这个问题。对于更深入的训练问题，请参阅模型训练技巧指南，了解如何为你的计算机视觉项目取得更好的结果。

常见问题#