PyTorch YOLO

YOLOv3 的极简 PyTorch 实现，支持训练、推理和评估。

YOLOv4 和 YOLOv7 的权重也与此实现兼容。

安装

从源码安装

对于常规的训练和评估，我们建议使用 poetry 虚拟环境从源码安装该包。

git clone https://github.com/eriklindernoren/PyTorch-YOLOv3
cd PyTorch-YOLOv3/
pip3 install poetry --user
poetry install

在运行以下不带 poetry run 前缀的命令之前，您需要通过在此目录中运行 poetry shell 来进入虚拟环境。如果您希望在任何地方无需打开 poetry-shell 即可使用这些命令，请参阅其他安装方法。

下载预训练权重

./weights/download_weights.sh

下载 COCO 数据集

./data/get_coco_dataset.sh

通过 pip 安装

如果您希望将此包作为依赖项用于其他 Python 项目，则推荐使用此安装方法。此方法仅包含代码，隔离性较差，可能会与其他包发生冲突。权重和 COCO 数据集仍需按照上述说明下载。有关软件包 API 的更多信息，请参阅 API 部分。此外，它还使 CLI 工具 yolo-detect、yolo-train 和 yolo-test 在任何地方均可直接使用，无需额外命令。

pip3 install pytorchyolo --user

测试

在 COCO 测试数据集上评估模型。要下载此数据集以及权重，请参阅上方说明。

poetry run yolo-test --weights weights/yolov3.weights

模型	mAP (min. 50 IoU)
YOLOv3 608 (论文)	57.9
YOLOv3 608 (本实现)	57.3
YOLOv3 416 (论文)	55.3
YOLOv3 416 (本实现)	55.5

推理

使用预训练权重对图像进行预测。下表显示了输入图像缩放到 256x256 时的推理时间。ResNet 主干网络的测量结果取自 YOLOv3 论文。标有“本实现”的 Darknet-53 测量结果显示了我在 1080ti 显卡上的推理时间。

主干网络	GPU	FPS
ResNet-101	Titan X	53
ResNet-152	Titan X	37
Darknet-53 (论文)	Titan X	76
Darknet-53 (本实现)	1080ti	74

poetry run yolo-detect --images data/samples/

训练

有关参数说明，请查看 poetry run yolo-train --help。

示例（COCO）

要使用在 ImageNet 上预训练的 Darknet-53 后端在 COCO 数据集上训练，请运行：

poetry run yolo-train --data config/coco.data  --pretrained_weights weights/darknet53.conv.74

TensorBoard

在 TensorBoard 中跟踪训练进度：

• 初始化训练
• 运行以下命令
• 打开 http://localhost:6006/

poetry run tensorboard --logdir='logs' --port=6006

如果将日志存储在速度较慢的磁盘上，可能会显著降低训练速度。

您可以通过在运行 tensorboard 和 yolo-train 时使用 --logdir <path> 来调整日志目录。

自定义数据集训练

自定义模型

运行以下命令以创建自定义模型定义，将 <num-classes> 替换为您的数据集中的类别数。

cd config 
./create_custom_model.sh <num-classes>  # 将创建自定义模型 'yolov3-custom.cfg'

类别

将类别名称添加到 data/custom/classes.names 文件中。每个类别名称应占一行。

图像文件夹

将您的数据集图像移动到 data/custom/images/ 目录中。

标注文件夹

将您的标注文件移动到 data/custom/labels/ 目录中。数据加载器期望与图像 data/custom/images/train.jpg 对应的标注文件路径为 data/custom/labels/train.txt。标注文件中的每一行应定义一个边界框，格式为 label_idx x_center y_center width height。坐标应归一化到 [0, 1] 范围内，label_idx 应从零开始，并对应于 data/custom/classes.names 文件中类别名称的行号。

定义训练和验证集

在 data/custom/train.txt 和 data/custom/valid.txt 文件中，分别添加将用作训练和验证数据的图像路径。

训练

要使用自定义数据集进行训练，请运行：

poetry run yolo-train --model config/yolov3-custom.cfg --data config/custom.data

添加 --pretrained_weights weights/darknet53.conv.74 可以使用在 ImageNet 上预训练的后端进行训练。

API

如果您安装了 pip 包 pytorchyolo，则可以在自己的项目中导入此仓库中的模块。

以下是一个简单的 OpenCV Python 脚本中的预测调用示例：

import cv2
from pytorchyolo import detect, models

# 加载 YOLO 模型
model = models.load_model(
  "<PATH_TO_YOUR_CONFIG_FOLDER>/yolov3.cfg",
  "<PATH_TO_YOUR_WEIGHTS_FOLDER>/yolov3.weights")

# 将图像加载为 numpy 数组
img = cv2.imread("<PATH_TO_YOUR_IMAGE>")

# 将 OpenCV bgr 转换为 rgb
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

# 在图像上运行 YOLO 模型
boxes = detect.detect_image(model, img)

print(boxes)
# 输出将是如下格式的 numpy 数组：
# [[x1, y1, x2, y2, 置信度, 类别]]

有关更高级的用法，请参阅方法的文档字符串。

致谢

YOLOv3：一次渐进式改进

约瑟夫·雷德蒙，阿里·法哈迪

摘要
我们对 YOLO 进行了一些更新！通过一系列小的设计改动使其性能更优。此外，我们还训练了一个非常出色的全新网络。它比之前的版本稍大一些，但精度更高。不过别担心，速度依然很快。在 320×320 分辨率下，YOLOv3 的推理时间为 22 毫秒，mAP 达到 28.2，与 SSD 精度相当，但速度快三倍。如果采用旧的 0.5 IoU mAP 检测指标，YOLOv3 的表现也非常出色。在 Titan X 显卡上，其 51 毫秒推理时间可达到 57.9 AP50，而 RetinaNet 在 198 毫秒内仅能取得 57.5 AP50，两者性能相近，但 YOLOv3 速度快了 3.8 倍。一如既往，所有代码均已公开，地址为：https://pjreddie.com/yolo/。

[论文] [项目主页] [作者实现]

@article{yolov3,
  title={YOLOv3: An Incremental Improvement},
  author={Redmon, Joseph and Farhadi, Ali},
  journal = {arXiv},
  year={2018}
}

其他

YOEO — 你只需编码一次

YOEO 在本仓库的基础上扩展了功能，增加了训练额外语义分割解码器的能力。该轻量级示例模型主要面向嵌入式实时应用。

PyTorch-YOLOv3 快速上手指南

本指南基于 PyTorch-YOLOv3 官方文档整理，旨在帮助开发者快速完成环境搭建、模型测试及自定义训练。该实现支持 YOLOv3、YOLOv4 及 YOLOv7 权重。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 需使用 WSL)
• Python: 3.6+ (推荐 3.8+)
• 深度学习框架: PyTorch (安装 poetry 时会自动处理依赖)
• 硬件: 推荐使用 NVIDIA GPU 以获得最佳推理和训练速度
• 工具: git, pip, poetry

国内加速建议：

• 克隆仓库时若速度慢，可使用 Gitee 镜像或配置 git 代理。
• 安装 Python 依赖时，建议指定清华或阿里镜像源：

  pip3 install poetry -i https://pypi.tuna.tsinghua.edu.cn/simple --user
  

2. 安装步骤

推荐使用 源码安装 配合 poetry 虚拟环境，以确保依赖隔离和环境稳定。

2.1 克隆项目并安装依赖

# 克隆仓库
git clone https://github.com/eriklindernoren/PyTorch-YOLOv3
cd PyTorch-YOLOv3/

# 安装 poetry (如已安装可跳过)
pip3 install poetry --user

# 安装项目依赖
poetry install

注意：执行后续命令前，需激活虚拟环境：

poetry shell

若不想每次激活，可在命令前加 poetry run 前缀。

2.2 下载预训练权重与数据集

# 下载 YOLOv3 预训练权重
./weights/download_weights.sh

# 下载 COCO 数据集 (用于测试和评估)
./data/get_coco_dataset.sh

提示：若脚本下载失败（网络原因），请手动访问相关链接下载权重文件至 weights/ 目录，并按脚本逻辑整理 COCO 数据至 data/coco/ 目录。

3. 基本使用

3.1 模型测试 (Test)

在 COCO 测试集上评估模型性能（mAP）。

poetry run yolo-test --weights weights/yolov3.weights

3.2 图像推理 (Inference)

使用预训练权重对图片进行目标检测。默认会检测 data/samples/ 目录下的图片并保存结果。

poetry run yolo-detect --images data/samples/

检测完成后，结果图片将保存在当前目录下，展示检测到的物体框及类别。

3.3 快速训练 (Train)

使用 COCO 数据集和 ImageNet 预训练的 Darknet-53 骨干网络进行训练。

poetry run yolo-train --data config/coco.data --pretrained_weights weights/darknet53.conv.74

查看训练进度 (TensorBoard)： 在新终端中运行以下命令，然后浏览器访问 http://localhost:6006/。

poetry run tensorboard --logdir='logs' --port=6006

3.4 自定义数据集训练简述

若需训练自己的数据集，请按以下步骤操作：

1. 创建模型配置：

   cd config
   ./create_custom_model.sh <类别数量>
   

2. 准备数据：
   • 类名存入 data/custom/classes.names (每行一个类名)。
   • 图片放入 data/custom/images/。
   • 标签文件 (.txt) 放入 data/custom/labels/，格式为：class_id x_center y_center width height (坐标归一化到 0-1)。
   • 在 data/custom/train.txt 和 valid.txt 中列出训练集和验证集图片的绝对路径。
3. 启动训练：

   poetry run yolo-train --model config/yolov3-custom.cfg --data config/custom.data
   

3.5 Python API 调用

您也可以直接在 Python 代码中调用该库进行推理：

import cv2
from pytorchyolo import detect, models

# 加载模型
model = models.load_model(
  "config/yolov3.cfg",
  "weights/yolov3.weights")

# 读取图片 (OpenCV 默认为 BGR，需转为 RGB)
img = cv2.imread("data/samples/giraffe.png")
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

# 执行检测
boxes = detect.detect_image(model, img)

print(boxes)
# 输出格式：[[x1, y1, x2, y2, confidence, class]]