ultralytics/yolov3 · 上手攻略

仓库：ultralytics/yolov3
链接：https://github.com/ultralytics/yolov3
分类：computer-vision / object-detection
作者：Tom
更新：2026-07-22

这是什么

ultralytics/yolov3 是 YOLOv3（You Only Look Once version 3）目标检测模型的 Ultralytics 官方 PyTorch 实现。原始 YOLOv3 由 Joseph Redmon 和 Ali Farhadi 在 2018 年提出（arXiv:1804.02767），Ultralytics 在此基础上添加了 YOLOv3-SPP、YOLOv3-tiny 两个变体，以及多格式模型导出（ONNX、TFLite、CoreML 等）、PyTorch Hub 一键加载等工程化能力。

当前（2026）该仓库推荐的模型已更新为 YOLOv3u 系列（yolov3u.pt、yolov3-tinyu.pt、yolov3-sppu.pt）——在原始 YOLOv3 架构基础上引入了 YOLOv8 的 anchor-free、objectness-free 分离检测头，在保持推理速度优势的同时提升了检测精度。

解决什么问题

目标检测是计算机视觉的基础任务之一：给定一张图片，找出其中所有感兴趣物体的类别和位置（bounding box）。YOLOv3 的核心创新是：

单阶段检测：将检测问题建模为单次回归，直接预测 bounding box 和类别概率，不需要 RCNN 系列的两阶段候选框提取，速度快
多尺度预测：在 13×13、26×26、52×52 三个不同尺度的特征图上做检测，兼顾大目标和小目标
多标签预测：每个 bounding box 可以同时属于多个类别（适合有重叠标签的场景）
Darknet-53 主干网络：53 层卷积网络，引入残差连接，精度与效率平衡良好

YOLOv3u 在此基础上用 YOLOv8 检测头替换了原来的 anchor-based head，进一步减少了对预定义 anchor 的依赖。

快速安装

# 基础安装（推荐，依赖 ultralytics 框架包）
pip install ultralytics

# 克隆源码 + 手动安装依赖（需要定制训练脚本时）
git clone https://github.com/ultralytics/yolov3
cd yolov3
pip install -r requirements.txt

环境要求： - Python ≥ 3.8 - PyTorch ≥ 1.8（需要 CUDA 支持以获得正常训练速度） - torchvision ≥ 0.9.0 - opencv-python ≥ 4.6.0 - 训练推荐 NVIDIA GPU（至少 6GB VRAM），YOLOv3-tiny 可在 CPU 上运行演示

⚠️ 注意：直接 pip install ultralytics 后，YOLOv3 的模型和工具通过 from ultralytics import YOLO 统一接口使用；仓库内的独立脚本（detect.py、train.py 等）在较新版本中可能已被 ultralytics 主包接管，建议优先使用 YOLO() API。

核心用法

PyTorch Hub 快速推理（最简方式）

import torch

# 加载预训练模型（权重自动下载）
# 可选：'yolov3', 'yolov3_spp', 'yolov3_tiny'
model = torch.hub.load("ultralytics/yolov3", "yolov3", pretrained=True)

# 推理（支持本地路径、URL、PIL Image、OpenCV 帧、numpy 数组）
results = model("https://ultralytics.com/images/zidane.jpg")

# 查看结果
results.print()   # 打印检测结果到控制台
results.show()   # 显示带标注的图像窗口
results.save()   # 保存到 runs/detect/exp/

训练自定义数据集

from ultralytics import YOLO

# 加载预训练模型（推荐用 yolov3u.pt）
model = YOLO("yolov3u.pt")

# 在自定义数据集上训练
# data 参数为数据集配置 YAML 路径（格式见下方说明）
results = model.train(
    data="path/to/your/data.yaml",  # 数据集配置
    epochs=100,                       # 训练轮数
    imgsz=640,                        # 输入图像尺寸
    batch=16,                         # batch size（GPU 内存不足可调小）
    device=0,                         # GPU 编号，多卡用 [0, 1]
    project="runs/train",             # 输出目录
    name="custom"
)

数据集配置 YAML 格式示例：

# data.yaml
path: ./datasets/mydata      # 数据集根目录
train: images/train          # 训练集图像目录
val: images/val              # 验证集图像目录
nc: 3                        # 类别数量
names: ['cat', 'dog', 'bird']  # 类别名称列表

验证（Validation）

from ultralytics import YOLO

model = YOLO("yolov3u.pt")

# 在验证集上评估
metrics = model.val(data="path/to/data.yaml")
print(metrics.box.map)  # mAP@0.5:0.95

导出为其他格式

from ultralytics import YOLO

model = YOLO("yolov3u.pt")

# 导出为 ONNX（最通用）
model.export(format="onnx")

# 导出为 TFLite（移动端）
model.export(format="tflite")

# 导出为 CoreML（Apple 生态）
model.export(format="coreml")

# 导出为 PyTorch TorchScript
model.export(format="torchscript")

命令行推理

# 图像推理
yolo detect predict model=yolov3u.pt source='path/to/image.jpg'

# 视频推理
yolo detect predict model=yolov3u.pt source='path/to/video.mp4'

# 摄像头实时推理
yolo detect predict model=yolov3u.pt source=0

典型适用场景

场景	推荐模型
实时目标检测（视频流、摄像头）	YOLOv3-tinyu（速度优先，FPS 高）
精度优先的通用检测	YOLOv3u / YOLOv3-SPPu（mAP 更高）
边缘设备部署	YOLOv3-tinyu + TFLite/ONNX 导出
自定义数据集训练	YOLOv3u + 自行标注数据
PyTorch 研究改进	原始 YOLOv3 cfg + darknet53 权重

坑与注意

Python 版本：官方推荐 Python ≥ 3.8，Python 3.12+ 可能存在某些依赖兼容问题（opencv-python、torch 特定版本需手动解决）
GPU 内存：标准 YOLOv3 训练默认 batch=16，至少需要 6GB VRAM；batch=8 可在 4GB 显卡上勉强运行
模型权重下载：PyTorch Hub 自动下载，如遇网络问题可提前手动下载 .pt 文件到 ~/.cache/torch/hub/checkpoints/
anchor 机制：YOLOv3 使用预定义 anchor，训练自定义数据时建议用 model.train(anchor_tuning=True) 或用 K-means 对新数据集重新聚类 anchor
数据标注格式：仅支持 YOLO TXT 格式（class_id x_center y_center width height，坐标归一化到 0-1），不支持 VOC XML / COCO JSON（需转换）
训练中断恢复：Ultralytics YOLO 支持自动保存 best checkpoint，但恢复训练需指定 model.train(resume=True)
版本差异：该仓库的 YOLOv3 与 ultralytics 主包的 YOLOv3 接口略有不同（主包 ultralytics.models.yolo 下），实际使用中优先用 from ultralytics import YOLO 而非直接跑 detect.py

与同类对比

维度	YOLOv3 / YOLOv3u	YOLOv5（Ultralytics）	YOLOv8	YOLO-NAS
发布年份	2018 / 2023（u版）	2020	2023	2023
检测精度	中等（mAP ~ 55）	中高（mAP ~ 63）	高（mAP ~ 68+）	最高
推理速度	快（tiny版极快）	快	快	中等
预训练生态	COCO + 自定义	COCO + 很多	COCO + 很多	COCO
导出格式	ONNX/TFLite/CoreML/TorchScript	全格式	全格式 + 更多	有限
易用性	较成熟，文档老旧	最佳（成熟生态）	最佳（活跃维护）	一般
适合场景	嵌入式/老项目/教学	通用首选	通用首选	精度敏感场景

选择建议：新项目优先选 YOLOv8（精度/速度比 YOLOv3 明显更好）。但 YOLOv3 的价值在于：嵌入式设备上 tiny 版本速度快、对 PyTorch 底层理解有帮助、以及大量现存 YOLOv3 部署案例需要维护。

一句话推荐结论

YOLOv3 是目标检测领域的经典单阶段模型，Ultralytics 的实现使其拥有了现代化的训练/推理/导出流水线；对于资源受限场景或学习目的 YOLOv3-tinyu 仍是性价比之选，但新项目建议直接上 YOLOv8——两者上手接口完全一致，精度提升显著。