企业官网建设流程全解析

YOLOv10 仓库完全指南：无 NMS 端到端实时目标检测的安装、训练、推理与导出实战

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10

导读

本指南围绕当前仓库（YOLOv10: Real-Time End-to-End Object Detection，NeurIPS 2024 官方 PyTorch 实现）展开，系统讲解该模型的端到端无 NMS 检测范式、六大预训练模型（N/S/M/B/L/X）的性能差异、conda 环境安装、Gradio 本地 Demo、训练/验证/推理/导出（ONNX、TensorRT）的完整命令行与 Python 用法，并结合仓库源码剖析v10Detect检测头、v10postprocess后处理与双分支损失的真实实现。读完本文，你将能独立完成 YOLOv10 从环境搭建到模型部署的全流程实战。

一、模型背景与核心设计理念

YOLOv10 由清华等团队提出，论文发表于 NeurIPS 2024（arXiv 编号 2405.14458）。它在传统 YOLO 系列"计算成本与检测性能平衡"的范式之上，从后处理与模型架构两个层面同时推进性能-效率边界：

1. 一致双重分配（Consistent Dual Assignments）实现 NMS-free 训练：通过为训练引入"一对多（one2many）"与"一对一（one2one）"两套标签分配，在训练时用一对多分支监督充分学习，推理时只用一对一分支直接输出，从而摆脱非极大值抑制（NMS）后处理，既保持竞争力又降低推理延迟。
2. 效率-精度驱动的整体模型设计：对 YOLO 的各组件从效率与精度双维度全面优化，显著减少计算冗余、增强模型能力，由此得到新一代实时端到端检测器 YOLOv10。

论文中报告（Abstract 原文），在 COCO 上相似 AP 条件下，YOLOv10-S 比 RT-DETR-R18 快 1.8 倍，参数量与 FLOPs 少 2.8 倍；与 YOLOv9-C 相比，YOLOv10-B 在同等性能下延迟低 46%、参数量少 25%。这些均为论文声明数据，可作为模型设计动机的参考。

仓库使用提示：本仓库代码基座构建于 ultralytics 与 RT-DETR（见 README 的 Acknowledgement 章节），并基于 Hugging Face Hub 提供from_pretrained权重加载能力。注意，YOLOv10 的 License 为 AGPL-3.0（见 ultralytics/models/yolov10/card.py 中的模型卡片元数据）。

二、性能概览（COCO 基准）

README 的 Performance 章节给出六个尺度模型在 COCO 验证集上的官方数据（Test Size 640）：

六个尺度在参数量 2.3M～29.5M、FLOPs 6.7G～160.4G 的区间内呈梯度覆盖，AP 从 38.5% 提升至 54.4%，可根据算力与精度要求按需选择。对应网络结构配置文件位于 ultralytics/cfg/models/v10/ 目录（yolov10n/s/m/b/l/x.yaml）。

三、环境安装

官方推荐使用conda虚拟环境，Python 版本 3.9：

conda create -n yolov10 python=3.9 conda activate yolov10 pip install -r requirements.txt pip install -e .

• requirements.txt中已锁定核心依赖版本，包括torch==2.0.1、torchvision==0.15.2、onnx==1.14.0、onnxruntime==1.15.1、pycocotools==2.0.7、gradio==4.31.5、opencv-python==4.9.0.80、huggingface-hub==0.23.2等（见 requirements.txt）。
• pip install -e .以可编辑模式安装当前包，使ultralytics与YOLOv10可直接导入。pyproject.toml位于仓库根目录，负责构建与依赖声明。
• 如需从远端克隆，可使用git clone https://gitcode.com/GitHub_Trending/yo/yolov10后再执行上述安装步骤。

四、快速体验：本地 Gradio Demo

仓库根目录的 app.py 提供了一个开箱即用的 Gradio 交互界面，支持图片与视频两种输入：

python app.py # 访问 http://127.0.0.1:7860

界面功能与默认值（可从 app.py 源码确认）：

• 模型选择：下拉框内置yolov10n / yolov10s / yolov10m / yolov10b / yolov10l / yolov10x六个选项，默认yolov10m；
• Image Size：滑动条 320～1280，步长 32，默认 640；
• Confidence Threshold：滑动条 0.0～1.0，步长 0.05，默认 0.25；
• 内置示例为仓库图片资源 ultralytics/assets/bus.jpg 与 ultralytics/assets/zidane.jpg，配合yolov10s、imgsz=640、conf=0.25可一键演示。

Demo 的后端逻辑会通过YOLOv10.from_pretrained(f'jameslahm/{model_id}')从 Hugging Face Hub 拉取权重，逐帧调用model.predict()并用results[0].plot()绘制标注框，视频场景下按原始 FPS 与分辨率写回带标注的视频。

五、推理（Prediction）

5.1 命令行方式

yolo predict model=jameslahm/yolov10{n/s/m/b/l/x}

其中{n/s/m/b/l/x}代表六个尺度，例如jameslahm/yolov10s。

5.2 Python 方式

from ultralytics import YOLOv10 model = YOLOv10.from_pretrained('jameslahm/yolov10{n/s/m/b/l/x}') # 或者先手动下载权重： # wget https://github.com/THU-MIG/yolov10/releases/download/v1.1/yolov10{n/s/m/b/l/x}.pt # model = YOLOv10('yolov10{n/s/m/b/l/x}.pt') model.predict()

5.3 小目标/远处目标检测建议

README 特别提示：检测小目标或远处目标时，可以设置更低的置信度阈值（confidence threshold），例如conf=0.1甚至更低。这与 ultralytics/models/yolov10/predict.py 中的后处理逻辑直接相关——模型输出的候选框会先经topk截取前max_det（默认 300）个高响应候选，再按置信度阈值过滤；阈值越低，保留的弱响应目标越多。

5.4 无 NMS 后处理的源码印证

从源码看，YOLOv10 的推理后处理完全抛弃了 NMS：

• 检测头 ultralytics/nn/modules/head.py 中v10Detect.forward在非导出、非训练模式下返回{"one2many": one2many, "one2one": one2one}字典；
• 预测器 ultralytics/models/yolov10/predict.py 的postprocess直接取出preds["one2one"]，调用ops.v10postprocess完成 top-k 候选筛选（ultralytics/utils/ops.py 中v10postprocess实现），再用conf与classes参数做阈值/类别过滤，最后scale_boxes将坐标映射回原图尺寸生成Results；
• v10postprocess的做法是：对每个位置取各类别分数的最大值，torch.topk先取前max_det个位置，再展平后二次topk得到最终的 boxes/scores/labels——全程无 NMS 迭代。

六、训练（Training）

6.1 命令行方式

yolo detect train data=coco.yaml model=yolov10n/s/m/b/l/x.yaml epochs=500 batch=256 imgsz=640 device=0,1,2,3,4,5,6,7

• data=coco.yaml指向 COCO 数据集配置（仓库内置 ultralytics/cfg/datasets/coco.yaml，其他数据集配置如 coco8.yaml、VOC.yaml 亦在该目录）；
• model=yolov10n/s/m/b/l/x.yaml使用结构配置文件而非预训练权重，从零开始训练；
• 示例中device=0,1,2,3,4,5,6,7为 8 卡分布式训练，单卡环境请改为device=0，并根据显存调整batch与imgsz。

6.2 Python 方式

from ultralytics import YOLOv10 model = YOLOv10() # 若希望使用预训练权重微调，可加载权重： # model = YOLOv10.from_pretrained('jameslahm/yolov10{n/s/m/b/l/x}') # 或手动下载后： # wget https://github.com/THU-MIG/yolov10/releases/download/v1.1/yolov10{n/s/m/b/l/x}.pt # model = YOLOv10('yolov10{n/s/m/b/l/x}.pt') model.train(data='coco.yaml', epochs=500, batch=256, imgsz=640)

6.3 训练阶段的双分支损失

ultralytics/models/yolov10/train.py 中YOLOv10DetectionTrainer.get_validator定义了六个损失项：

box_om, cls_om, dfl_om, box_oo, cls_oo, dfl_oo

其中om（one2many）与oo（one2one）分别对应训练时两套标签分配分支的 box 回归损失、类别损失与 DFL 损失，最终二者加权构成总损失。模型侧由 ultralytics/nn/tasks.py 中YOLOv10DetectionModel.init_criterion返回v10DetectLoss（实现见 ultralytics/utils/loss.py）。这就是"一致双重分配"在训练代码层面的落地：一对多分支在训练中提供充分监督，一对一分支则服务于推理阶段的免 NMS 输出。

七、验证（Validation）

在 COCO 上验证预训练模型的精度：

yolo val model=jameslahm/yolov10{n/s/m/b/l/x} data=coco.yaml batch=256

Python 方式：

from ultralytics import YOLOv10 model = YOLOv10.from_pretrained('jameslahm/yolov10{n/s/m/b/l/x}') # 或 # wget https://github.com/THU-MIG/yolov10/releases/download/v1.1/yolov10{n/s/m/b/l/x}.pt model = YOLOv10('yolov10{n/s/m/b/l/x}.pt') model.val(data='coco.yaml', batch=256)

ultralytics/models/yolov10/val.py 中的YOLOv10DetectionValidator.postprocess与预测器逻辑一致：从 dict 结果中取one2one分支，经v10postprocess得到端到端输出；若输入已是导出后的 6 维格式（xyxy, conf, cls）则直接透传。同时，当验证数据为 COCO 时（self.is_coco），验证器会自动开启save_json，便于后续用 COCO 官方脚本评估 mAP。

八、模型导出（Export）与端到端部署

YOLOv10 的杀手锏是端到端导出：导出的 ONNX / TensorRT 模型在推理时已内嵌 top-k 后处理，不需要任何 NMS 逻辑，可直接对接部署框架。

8.1 端到端 ONNX

# 导出 yolo export model=jameslahm/yolov10{n/s/m/b/l/x} format=onnx opset=13 simplify # 用 ONNX 模型推理 yolo predict model=yolov10n/s/m/b/l/x.onnx

8.2 端到端 TensorRT

# 方式一：通过 yolo export yolo export model=jameslahm/yolov10{n/s/m/b/l/x} format=engine half=True simplify opset=13 workspace=16 # 方式二：通过 trtexec 直接构建（先导出 ONNX 再用） trtexec --onnx=yolov10n/s/m/b/l/x.onnx --saveEngine=yolov10n/s/m/b/l/x.engine --fp16 # 用 TensorRT 引擎推理 yolo predict model=yolov10n/s/m/b/l/x.engine

参数说明：

• format=onnx/engine：目标格式；opset=13指定 ONNX 算子集版本；simplify启用 onnxslim 简化（requirements.txt 中已包含onnxslim==0.1.31）；
• TensorRT 导出中half=True开启 FP16 量化、workspace=16指定 16GB 工作空间；trtexec --fp16是等价的原生 TensorRT 构建方式；
• 仓库 Note（2024/05/31）明确指出：进行 benchmark 时必须使用导出后的格式。原因在于非导出（PyTorch）格式下，v10Detect中不必要的cv2/cv3操作在推理时仍会被执行，导致速度测量偏慢。从 head.py 的v10Detect.forward可以看到：导出模式下只执行one2one分支，并在图内直接调用ops.v10postprocess拼装最终输出；而非导出模式下需要同时计算one2many分支用于训练/验证，这正是速度偏差的来源。

8.3 Python 导出

from ultralytics import YOLOv10 model = YOLOv10.from_pretrained('jameslahm/yolov10{n/s/m/b/l/x}') # 或 # wget https://github.com/THU-MIG/yolov10/releases/download/v1.1/yolov10{n/s/m/b/l/x}.pt model = YOLOv10('yolov10{n/s/m/b/l/x}.pt') model.export(...) # 参数与命令行 yolo export 一致

九、将微调模型推送到 Hugging Face Hub

训练完成后，可选地将模型推送到 Hugging Face Hub 作为公开或私有模型：

# 假设你已微调了一个"作物检测"模型 model.push_to_hub("<your-hf-username-or-organization/yolov10-finetuned-crop-detection") # 传入 private=True 可设为私有模型 model.push_to_hub("<your-hf-username-or-organization/yolov10-finetuned-crop-detection", private=True)

ultralytics/models/yolov10/model.py 中YOLOv10类同时继承 ultralytics 的Model基类与 Hugging Face 的PyTorchModelHubMixin，重写的push_to_hub会在推送前自动把names（类别名）、yaml_file（模型结构配置路径）与task写入模型的config元数据，确保从 Hub 加载后类别信息完整可用——这与 README Note（2024/05/27）中"已更新带类别名的 checkpoints，便于使用"的说明相呼应。

十、架构层面的源码速览

为了让读者对"无 NMS"有一个更立体的理解，这里从源码结构层面补充关键链路：

• 模型入口ultralytics/models/yolov10/model.py：task_map将detect任务映射到YOLOv10DetectionModel/YOLOv10DetectionTrainer/YOLOv10DetectionValidator/YOLOv10DetectionPredictor四个组件；__init__支持传入names覆盖类别名。
• 检测头ultralytics/nn/modules/head.py 中v10Detect：在标准Detect基础上新增cv3、one2one_cv2、one2one_cv3分支；forward中one2one分支使用xi.detach()阻断梯度，训练时同时输出one2many与one2one两个 dict 项；bias_init对one2one分支的偏置做针对性初始化。
• 结构配置ultralytics/cfg/models/v10/yolov10n.yaml 等：backbone 在 C2f 基础上引入SCDown（下采样）、C2fCIB（C2f 与 CIB 的组合）与PSA（位置敏感注意力）等模块，head 末端统一使用v10Detect，并通过scales（depth/width/max_channels 复合缩放系数）生成 n/s/m/b/l/x 六个尺度。

十一、总结与使用建议

• 选型：追求极致实时性选 N/S，均衡性能与成本选 M/B，重精度轻延迟选 L/X；具体 AP 与延迟请以第二节表格为参考，并结合自身硬件实测。
• 测速：务必先导出 ONNX/TensorRT 再进行 benchmark，否则 PyTorch 非导出格式会因多余分支计算产生速度偏差（见 README Note）。
• 小目标检测：适当降低conf阈值可显著提升远处/小目标的召回，同时可配合max_det与更高分辨率输入使用。
• 部署：端到端导出使推理链完全免去 NMS，这在边缘设备与实时流水线中能直接简化后处理代码并降低延迟。

附录：引用

如果本仓库的代码或模型对你的工作有帮助，请按 README 提供的 BibTeX 引用：

@article{wang2024yolov10, title={YOLOv10: Real-Time End-to-End Object Detection}, author={Wang, Ao and Chen, Hui and Liu, Lihao and Chen, Kai and Lin, Zijia and Han, Jungong and Ding, Guiguang}, journal={arXiv preprint arXiv:2405.14458}, year={2024} }

进一步阅读：数据集的准备与各类配置可查看 ultralytics/cfg/datasets/；Docker 部署方案见 docker/Dockerfile 及同目录下的 CPU、ARM64、Jetson、Conda 等变体；推理/训练/导出相关的通用参数说明见 ultralytics/cfg/default.yaml。

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10