YOLOv5 detect.py参数详解：从配置到优化的全流程指南

一、detect.py核心功能与参数架构

YOLOv5的detect.py是目标检测任务的核心入口脚本，负责加载预训练模型、处理输入数据（图像/视频/流）、执行推理并输出检测结果。其参数设计遵循模块化原则，主要分为四大类：模型配置、输入处理、推理控制和输出可视化。通过解析这些参数，开发者可灵活控制检测流程的精度、速度和展示效果。

1.1 参数分类与调用逻辑

脚本通过argparse库实现命令行参数解析，核心参数包括：

• 模型相关：weights、device、half
• 输入相关：source、imgsz、conf_thres、iou_thres
• 输出相关：save_txt、save_conf、save_crop、project、name
• 增强功能：augment、agnostic_nms、classes

调用时，参数通过parser.add_argument()定义，例如：

parser.add_argument('--weights', nargs='+', type=str, default='yolov5s.pt', help='model.pt path(s)')
parser.add_argument('--source', type=str, default='data/images', help='source')

二、模型配置参数详解

2.1 权重文件（--weights）

• 作用：指定预训练模型路径，支持单模型（yolov5s.pt）或多模型（['yolov5s.pt', 'yolov5m.pt']）并行推理。
• 原理：模型通过torch.load()加载，权重文件需与代码版本匹配（如YOLOv5 v6.0+的.pt文件包含模型结构和权重）。
• 实用建议：
  • 自定义训练后，将runs/train/exp/weights/best.pt作为权重输入。
  • 多模型推理时，结果会按模型顺序输出，适合对比不同模型的性能。

2.2 设备选择（--device）

• 作用：指定推理设备（cpu/0/cuda:0），默认自动检测可用设备。
• 原理：通过torch.cuda.is_available()判断GPU可用性，若指定device='cpu'则强制使用CPU。
• 性能优化：
  • GPU推理时，建议设置device=0（单卡）或device='0,1'（多卡并行）。
  • CPU推理可通过half=False禁用半精度加速，避免兼容性问题。

2.3 半精度加速（--half）

• 作用：启用FP16半精度推理，减少显存占用并提升速度（约30%加速）。
• 限制：需GPU支持（如NVIDIA Tensor Core），部分旧卡可能不兼容。
• 代码示例：

  if device.type != 'cpu' and half:
    model.half()  # 转换为半精度

三、输入处理参数解析

3.1 输入源（--source）

• 支持类型：
  • 图像：data/images/bus.jpg
  • 视频：data/videos/street.mp4
  • 目录：data/images/（处理目录下所有文件）
  • 流媒体：rtsp://example.com/stream（需FFmpeg支持）
  • 屏幕截图：screen（实时捕获屏幕）
• 处理流程：输入源通过cv2.VideoCapture()或PIL.Image.open()读取，统一转换为torch.Tensor。

3.2 图像尺寸（--imgsz）

• 作用：调整输入图像尺寸（如640或1280），影响模型感受野和推理速度。
• 原理：图像按比例缩放至imgsz x imgsz，长边填充至方形（保持长宽比）。
• 调优建议：
  • 小目标检测：增大imgsz（如1280）以保留细节。
  • 实时应用：减小imgsz（如320）以提升帧率。

3.3 置信度阈值（--conf-thres）

• 作用：过滤低置信度预测（默认0.25），值越高结果越精确但可能漏检。
• 数学原理：对每个预测框的类别概率应用阈值，低于阈值的框被丢弃。
• 案例分析：
  • 高精度场景（如医疗检测）：设为0.5以上。
  • 实时监控：可降低至0.2以捕捉更多潜在目标。

四、推理控制与后处理

4.1 非极大值抑制（NMS）

• 参数：--iou-thres（IOU阈值，默认0.45）、--agnostic-nms（类别无关NMS）。
• 原理：合并高度重叠的预测框，保留置信度最高的框。
• 优化技巧：
  • 密集场景（如人群检测）：降低iou-thres至0.3。
  • 多类别检测：启用agnostic-nms避免同类框误删。

4.2 类别过滤（--classes）

• 作用：仅检测指定类别（如--classes 0 2 3对应人、车、卡车）。
• 实现方式：通过索引过滤模型输出，减少无关检测。
• 应用场景：
  • 交通监控：仅检测车辆和行人。
  • 工业质检：聚焦特定缺陷类别。

五、输出可视化与结果保存

5.1 结果保存路径（--project/--name）

• 结构：结果保存至runs/detect/project/name/目录，包含：
  • 图像/视频标注结果（vis/）
  • 文本格式检测框（labels/，若save_txt=True）
  • 裁剪后的目标区域（crops/，若save_crop=True）
• 自定义路径：通过project='my_project'和name='exp'指定。

5.2 可视化增强（--line-thickness）

• 作用：调整检测框线条粗细（默认3），提升可视化效果。
• 代码示例：

  cv2.rectangle(img, pt1, pt2, color, thickness=args.line_thickness)

六、高级参数与调优实践

6.1 数据增强推理（--augment）

• 作用：启用测试时增强（TTA），通过翻转和缩放生成多尺度输入，提升鲁棒性。
• 性能影响：推理时间增加约2-3倍，但mAP可提升1-2%。
• 适用场景：对精度要求极高的关键任务（如自动驾驶）。

6.2 多线程加速（--workers）

• 作用：指定数据加载线程数（默认8），加速批量推理。
• 调优建议：
  • 高性能CPU（如16核）：设为16。
  • 低配设备：设为2-4避免资源竞争。

七、完整参数调用示例

python detect.py \
    --weights yolov5s.pt \
    --source data/videos/test.mp4 \
    --imgsz 1280 \
    --conf-thres 0.4 \
    --iou-thres 0.5 \
    --save-txt \
    --project runs/custom \
    --name exp1 \
    --device 0 \
    --half

此命令使用YOLOv5s模型在GPU 0上以1280分辨率处理视频，保存检测框文本结果至runs/custom/exp1/labels/。

八、总结与实用建议

1. 精度优先：增大imgsz、提高conf-thres、启用augment。
2. 速度优先：减小imgsz、禁用half=False（CPU）、降低workers。
3. 定制化检测：通过classes和agnostic-nms聚焦特定目标。
4. 结果复用：利用save_txt和save_crop为后续分析提供结构化数据。

通过深入理解detect.py的参数逻辑，开发者可针对不同场景（实时监控、工业检测、自动驾驶等）实现高效的目标检测解决方案。