YOLOv9 detect_dual.py 命令详解，新手一看就懂
你刚拿到 YOLOv9 官方版训练与推理镜像，点开终端，看到python detect_dual.py这行命令——但参数一堆：--source、--img、--device、--weights……每个都像天书？别急，这不是考试，是上手实操。本文不讲梯度反向传播，不推公式，只说清楚一件事：这条命令里的每一个参数，到底在告诉模型“做什么”和“怎么做”。哪怕你昨天才第一次听说 YOLO，读完这篇，也能自己改参数、换图片、跑出结果，还能看懂为什么结果出现在那个文件夹里。
我们全程基于镜像真实环境操作：预装好环境、权重已就位、路径已固定。所有命令可直接复制粘贴运行，无需额外配置。
1. 先搞明白：detect_dual.py 是谁？它不是普通检测脚本
YOLOv9 的detect_dual.py不是detect.py的简单升级版，它是专为“双路径特征融合推理”设计的核心脚本——这也是 YOLOv9 区别于前代的关键技术亮点之一。所谓“dual”，指模型同时启用两条特征提取通路：一条专注语义信息（“这是什么”），另一条强化定位细节（“在哪、多大、多准”），最后动态加权融合，显著提升小目标、遮挡目标和边界模糊目标的检出率。
注意：这不是可选项，而是 YOLOv9 官方推理的默认且唯一推荐方式。你用
detect.py可能报错或结果异常，因为官方代码库已将主逻辑迁移至detect_dual.py。
镜像中该脚本位于/root/yolov9/detect_dual.py，它不是独立工具，而是深度绑定以下三要素：
- 模型结构定义（
models/detect/yolov9-s.yaml） - 预训练权重（
yolov9-s.pt，已预置在/root/yolov9/） - 输入输出规范（图片路径、尺寸、设备、保存位置）
理解这三点，你就抓住了整条命令的骨架。
2. 逐个拆解：命令中的每个参数都在干什么
我们从镜像文档里那条标准命令出发，一行一行剥开：
python detect_dual.py --source './data/images/horses.jpg' --img 640 --device 0 --weights './yolov9-s.pt' --name yolov9_s_640_detect2.1--source：告诉模型“看哪张图”或“看哪些图”
这是唯一必填参数，没有它，脚本直接退出。
- 支持类型：
- 单张图片路径：
./data/images/horses.jpg - 图片文件夹路径：
./data/images/（自动遍历所有.jpg/.png/.jpeg） - 视频文件路径：
./videos/test.mp4 - 摄像头编号：
0（调用默认摄像头）、1（第二摄像头）
- 单张图片路径：
- 路径规则：
- 相对路径以当前工作目录为基准（所以必须先
cd /root/yolov9） - 绝对路径以
/开头，如/home/user/my_img.jpg
- 相对路径以当前工作目录为基准（所以必须先
- 新手常见错误：
- 忘记引号：
--source ./data/images/horses.jpg在含空格路径下会崩 - 路径不存在：报错
FileNotFoundError: No such file or directory - 扩展名不支持：YOLOv9 默认只识别
.jpg,.jpeg,.png，.bmp需手动修改detect_dual.py中的IMG_FORMATS列表
- 忘记引号：
正确做法：始终用单引号包裹路径，确保路径真实存在。
2.2--img：决定“把图缩放到多大再看”
YOLO 系列必须将输入图像统一缩放到固定尺寸（如 640×640）才能送入网络。这个值不是越大越好，也不是越小越快，而是一个精度与速度的平衡点。
- 典型取值：
320、416、640、832、1024 - 影响什么：
--img 320：速度快（显存占用低），但小目标容易漏检，框不准--img 640：官方默认，COCO 验证集最优平衡点，适合大多数场景--img 1024：细节丰富，大图清晰，但显存翻倍，单卡可能 OOM
- 关键机制：
- 实际缩放采用保持宽高比的 letterbox 填充：先等比缩放，再用灰边（114,114,114）补足到指定尺寸，避免图像拉伸变形
- 最终送入网络的是
(3, 640, 640)张量，不是原始分辨率
新手建议：首次运行一律用--img 640，效果稳、速度可接受；确认流程通后再尝试调优。
2.3--device：指定“让哪块显卡干活”
YOLOv9 推理强烈依赖 GPU 加速。CPU 模式（--device cpu）仅用于调试，速度极慢，不推荐。
- 取值说明：
--device 0：使用第 1 块 GPU（索引从 0 开始）--device 0,1：并行使用两块 GPU（需模型支持多卡，YOLOv9 官方推理暂未启用）--device cpu：强制 CPU 运行（仅限无 GPU 环境测试）
- 如何查可用 GPU：
nvidia-smi -L # 输出示例：GPU 0: NVIDIA A10 (UUID: GPU-xxxx) - 常见问题：
- 报错
CUDA out of memory：显存不足，需降低--img或换小模型（如yolov9-t.pt） - 报错
Torch not compiled with CUDA enabled：未激活 conda 环境，漏执行conda activate yolov9
- 报错
新手务必确认：先nvidia-smi看卡是否识别，再conda activate yolov9，最后运行命令。
2.4--weights：加载“学过什么”的知识包
这就是模型的“大脑”——预训练权重文件。YOLOv9 镜像已预置yolov9-s.pt，位于/root/yolov9/目录下。
权重文件命名规则（官方提供）：
文件名 特点 适用场景 yolov9-s.ptSmall 版，约 15M，25.3 AP@0.5:0.95 新手入门、快速验证、中等算力 yolov9-m.ptMedium 版，约 32M，27.1 AP 平衡精度与速度 yolov9-c.ptCustom 版，更大更准，需更高显存 科研、高精度需求 yolov9-e.ptExtreme 版，SOTA 级别 A100/H100 环境 路径写法要点：
./yolov9-s.pt：相对路径（当前目录/root/yolov9下存在该文件 → ）yolov9-s.pt：无路径前缀 → ❌ 报错No such file/root/yolov9/yolov9-s.pt：绝对路径 → 但冗余
新手只需记住：镜像内权重就在当前目录，用./yolov9-s.pt最安全。
2.5--name：定义“结果存哪、叫啥名”
这是最被低估却最关键的参数。它不参与计算，但决定了你的结果能否被快速找到、复现、分享。
- 作用：指定输出文件夹名称，完整路径为
runs/detect/{name} - 默认值：若不加
--name，系统自动生成时间戳文件夹（如exp12），难以追溯 - 命名建议：
- 包含模型+尺寸+用途：
yolov9_s_640_horses（清晰表明：s 模型、640 尺寸、测试马图） - 避免空格和特殊字符：
yolov9-s-640，yolov9 s 640❌（shell 解析失败）
- 包含模型+尺寸+用途：
- 输出内容：
runs/detect/yolov9_s_640_detect/下包含：horses.jpg：带检测框和标签的可视化结果图labels/horses.txt：每行一个检测结果（class_id x_center y_center width height confidence）results.csv：汇总所有图片的 AP、FPS、延迟等指标（需开启--save-txt和--save-conf）
新手铁律：每次运行必加--name，用下划线连接关键词，拒绝默认exp*。
3. 进阶技巧：5 个让效率翻倍的实用组合
光会基础命令不够，真正提效靠组合技。以下全是镜像环境实测有效的技巧，无需改代码。
3.1 一次处理整个文件夹，批量出结果
python detect_dual.py \ --source './data/images/' \ --img 640 \ --device 0 \ --weights './yolov9-s.pt' \ --name yolov9_s_640_batch \ --conf 0.25 \ --iou 0.45--conf 0.25：置信度阈值设为 0.25（默认 0.25），过滤掉低质量预测--iou 0.45：NMS 阈值设为 0.45（默认 0.45），控制框重叠合并强度- 效果：
./data/images/下 100 张图，1 分钟内全部完成，结果按原图名保存
3.2 边看边存：实时摄像头流 + 自动截图
python detect_dual.py \ --source 0 \ --img 640 \ --device 0 \ --weights './yolov9-s.pt' \ --name webcam_live \ --view-img \ --save-txt \ --save-conf--view-img：弹出 OpenCV 窗口实时显示检测画面--save-txt：保存每帧的.txt标签文件--save-conf：在.txt中保留置信度（否则只存坐标）- 场景：安防巡检演示、课堂实时教学、机器人视觉调试
3.3 导出高清结果图，告别模糊截图
默认输出图是 640×640，但原始图可能是 4K。想保留细节？加这个：
python detect_dual.py \ --source './data/images/horses.jpg' \ --img 640 \ --device 0 \ --weights './yolov9-s.pt' \ --name yolov9_s_640_hd \ --line-thickness 3 \ --hide-labels False \ --hide-conf False--line-thickness 3：框线加粗到 3 像素（默认 2），打印/投影更清晰--hide-labels False：显示类别文字（默认 True，即隐藏）--hide-conf False：显示置信度数值（默认 True）- 输出图自带文字标签和概率，可直接用于汇报、论文插图
3.4 多尺度测试：同一张图，三种尺寸对比
for size in 320 640 1024; do python detect_dual.py \ --source './data/images/horses.jpg' \ --img $size \ --device 0 \ --weights './yolov9-s.pt' \ --name yolov9_s_${size}_horses done- 快速验证：小图快但漏检？大图准但慢？帮你找到项目最优尺寸
3.5 静默运行 + 日志记录，适合自动化脚本
nohup python detect_dual.py \ --source './data/images/' \ --img 640 \ --device 0 \ --weights './yolov9-s.pt' \ --name batch_auto_20240615 \ > detect_log.txt 2>&1 &nohup：后台运行，关闭终端也不中断> detect_log.txt 2>&1：标准输出和错误全部存入日志&：放入后台- 适合：夜间批量处理、CI/CD 流水线、无人值守服务器
4. 常见报错与秒级解决方案
新手跑不通，90% 卡在这几个地方。我们按报错信息反向定位：
| 报错信息 | 根本原因 | 一句话解决 |
|---|---|---|
ModuleNotFoundError: No module named 'torch' | 未激活 conda 环境 | 立即执行conda activate yolov9 |
FileNotFoundError: No such file or directory: './data/images/horses.jpg' | 图片路径错误或文件不存在 | 进入/root/yolov9后，用ls ./data/images/确认文件存在 |
CUDA out of memory | 显存不足 | 改--img 320或换yolov9-t.pt（更小模型） |
AssertionError: Image Not Found | --source指向空文件夹或非图片文件 | 检查文件夹内是否有.jpg/.png，删掉.DS_Store等隐藏文件 |
AttributeError: 'NoneType' object has no attribute 'shape' | OpenCV 读图失败（路径含中文/空格/编码问题） | 改用绝对路径，或重命名图片为英文+下划线 |
终极排查口诀：
一查环境（conda activate）→ 二查路径（ls 看得到）→ 三查显卡（nvidia-smi）→ 四查参数（--img/--weights 是否拼错）
5. 总结：你现在已经掌握的，远超一条命令
回看开头那条命令：
python detect_dual.py --source './data/images/horses.jpg' --img 640 --device 0 --weights './yolov9-s.pt' --name yolov9_s_640_detect现在你知道：
--source不是随便填的路径，而是模型的“眼睛”所见；--img不是数字游戏，而是精度与速度的物理权衡；--device不是选卡，而是告诉系统“把算力精准调度到哪块硬件”；--weights不是文件，而是经过 COCO 数据集千锤百炼的“视觉常识”；--name不是起名，而是构建可复现、可协作、可归档的工程习惯。
你不再需要背参数，因为你理解了每个参数背后的工程意图。接下来，你可以：
- 把
horses.jpg换成自己的产品图，30 秒生成质检报告； - 把
--img 640换成--img 320，部署到 Jetson Nano； - 把
--name改成项目代号，形成团队统一的输出规范。
YOLOv9 的强大，不在参数多，而在每个参数都直指业务本质。而你，已经拿到了那把钥匙。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
