排查常见 YOLO 问题#

本指南介绍使用 Ultralytics YOLO26 时最常遇到的问题，并按问题出现的环节分类：安装、模型训练、预测和部署。跳转到与你遇到的错误对应的类别，或浏览常见问题，快速查找答案。每个条目都会说明问题，并提供可以直接应用的具体解决方法。

常见问题#

安装错误#

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

• 你使用的是推荐的 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 文件中的配置设置是否已正确应用。

解决方法：数据集设置和训练设置分别存储在不同的 .yaml 文件中，并通过 model.train() 的不同参数传入。要确保这些设置已正确应用，请按以下步骤操作：

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

• 将数据集 .yaml（路径、类别名称、数据集划分）作为 data 参数传入，并将自定义训练设置 .yaml（例如 epochs 或 lr0）作为 cfg 参数传入。直接传给 model.train() 的参数优先级高于这两者：

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

使用多块 GPU 加速训练#

问题：单块 GPU 上的训练速度很慢，你想使用多块 GPU 来加快训练。

解决方法：增大批次大小可以加快训练，但必须考虑 GPU 内存容量。要使用多块 GPU加快训练，请按以下步骤操作：

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

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

• 相应地增大批次大小，以充分利用多块 GPU，同时避免超出内存限制。

• 修改训练命令以使用多块 GPU：

  # 根据需要调整批次大小和其他设置，以优化训练速度
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

持续监控的参数#

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

解决方法：损失值是需要监控的重要指标，但跟踪其他指标对于优化模型性能也很重要。训练期间需要监控的一些关键指标包括：

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

你可以从训练日志中查看这些指标，也可以使用 TensorBoard 或 Weights & Biases 等工具进行可视化。根据这些指标实施提前停止，有助于获得更好的结果。

跟踪训练进度的工具#

问题：你想了解用于跟踪训练进度的工具推荐。

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

• TensorBoard：TensorBoard 是一种常用工具，可用于可视化训练指标，包括损失值、准确率等。你可以将它集成到 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

# 加载模型
model = YOLO("yolo26n.pt")

# 使用 GPU 0；多块 GPU 时使用 device=[0, 1]，使用 CPU 时使用 device="cpu"
model.train(data="path/to/data.yaml", device=0)

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

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

如果你遇到与模型训练相关的问题，以下几点值得注意。

数据集格式和标签

• 重要性：任何机器学习模型的基础，都在于其训练数据的质量和格式。
• 建议：确保你的自定义数据集及其相关标签符合预期格式。务必确认标注准确且质量高。错误或质量欠佳的标注会妨碍模型学习，导致不可预测的结果。

模型收敛

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

学习率和批次大小

• 重要性：这些超参数对于决定模型在训练期间如何更新权重起着关键作用。
• 建议：定期评估所选学习率和批次大小是否适合你的特定数据集。与数据集特征不匹配的参数可能会妨碍模型性能。

类别分布

• 重要性：数据集中的类别分布会影响模型的预测倾向。
• 建议：定期评估数据集中的类别分布。如果类别不平衡，模型就可能偏向样本更多的类别。这种偏差会体现在混淆矩阵中，例如模型可能主要预测为多数类。

与预训练权重交叉验证

• 重要性：利用预训练权重可以为模型训练提供良好的起点，尤其是在数据有限时。
• 建议：作为诊断步骤，可以考虑使用相同的数据训练模型，但以预训练权重初始化。如果这种方法生成了结构良好的混淆矩阵，这可能表明“从头开始”训练的模型需要进一步训练或调整。

模型预测相关问题#

以下介绍模型预测中常见的问题及其解决方法。

获取自定义 YOLO26 模型的边界框预测结果#

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

解决方案：

• 坐标格式：YOLO26 提供的边界框坐标以绝对像素值表示。要将其转换为相对坐标（范围为 0 到 1），需要除以图像尺寸。例如，假设图像尺寸为 640x640，那么可以按以下方式处理：

  # 将绝对坐标转换为相对坐标
  x1 = x1 / 640  # 将 x 坐标除以图像宽度
  x2 = x2 / 640
  y1 = y1 / 640  # 将 y 坐标除以图像高度
  y2 = y2 / 640

• 文件名：要获取正在预测的图像文件名，请在预测循环中从每个结果对象的 path 属性读取图像文件路径（例如 result.path）。

筛选 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 标签页，你可以在这里提问、报告 Bug 和建议新功能。社区成员和维护者都积极参与交流，这也是针对具体问题寻求帮助的好地方。

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

官方文档和资源#

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

结论#

大多数 YOLO26 问题都源于少数几个原因：版本不匹配、数据集格式和 GPU 配置。如果这里没有介绍你遇到的错误，可以搜索 GitHub Issues 标签页，或在 Discord 服务器中提问——很可能已经有人解决了这个问题。对于更复杂的训练问题，请参阅模型训练技巧指南，了解如何在计算机视觉项目中取得更好效果的实用建议。

常见问题#