使用 PyTorch Hub 加载 YOLOv5：模型加载、推理参数与结果处理完全指南-平芜编程栈

使用 PyTorch Hub 加载 YOLOv5：模型加载、推理参数与结果处理完全指南

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics

本文源自 docs/en/yolov5/tutorials/pytorch-hub-model-loading.md，讲解如何通过 PyTorch Hub 以「零克隆、自动下载」的方式加载 Ultralytics YOLOv5 预训练模型，完成单图/批量推理、推理参数调优、设备切换、多 GPU 并发，并系统梳理结果对象的多种消费形式（Tensor、Pandas、JSON、Base64、裁剪图等）。读完本文，你将掌握一条不克隆代码库即可落地 YOLOv5 推理的最小路径，也能将其平滑迁移到自定义模型与 TensorRT/ONNX/OpenVINO 等导出格式。

一、为什么要通过 PyTorch Hub 加载 YOLOv5

YOLOv5 是 Ultralytics 推出的第五代 "You Only Look Once" 实时目标检测系列。官方为其维护了两种典型使用路径：一种是克隆代码库后调用detect.py、train.py等脚本（可参考 YOLOv5 Quickstart）；另一种就是本文的核心 ——通过 PyTorch Hub 以模型名为入口直接加载。

PyTorch Hub 是 PyTorch 官方提供的模型分发与复用机制，只要目标仓库暴露了hubconf.py入口，使用者即可用一行代码完成模型代码拉取、权重下载与加载：

import torch model = torch.hub.load("ultralytics/yolov5", "yolov5s")

这种方式的优势在于：

无需克隆 YOLOv5 代码库。PyTorch Hub 会在首次调用时自动抓取指定仓库的代码并缓存到本地，'yolov5s'等模型权重与所需数据集也会自动从 YOLOv5 的最新 release 中下载；
入口统一、便于迭代升级。代码与权重跟随远程仓库版本更新，配合force_reload=True可随时刷新到最新版本；
与自定义权重无缝衔接。通过"custom"入口即可加载本地训练产出的best.pt，也可以加载 ONNX、TensorRT 等导出格式。

在当前仓库中，YOLOv5 的完整使用文档归档于 docs/en/yolov5/index.md，模型架构配置文件可见 ultralytics/cfg/models/v5，数据集配置见 ultralytics/cfg/datasets 下的coco*.yaml、VOC.yaml等文件。这些配置是理解模型加载后其名称、类别数量等默认行为的良好参照。

二、开始前的环境准备

官方要求的环境基线为：

Python >= 3.8.0
PyTorch >= 1.8

在满足上述版本的环境中使用如下命令安装 YOLOv5 运行时依赖（依赖清单以 YOLOv5 代码库维护的requirements.txt为准；若你只是借助 PyTorch Hub 做推理，克隆 YOLOv5 代码库并不是必需的，Hub 会自行拉取模型代码）：

pip install -r requirements.txt

关于依赖获取，有两类等价做法：

克隆 YOLOv5 代码库后，在其根目录执行pip install -r requirements.txt；
借助 PyTorch Hub 的自动拉取机制，仅需保证环境中已有torch及推理所需的图像处理库（如Pillow、opencv-python）。

在当前 Ultralytics 统一代码库中，若要直接以 Python 包方式使用现代 YOLO 系列，也可通过 pyproject.toml 中声明的构建配置执行pip install ultralytics或开发模式安装pip install -e .（该包要求requires-python = ">=3.8"，与本教程基线一致）。两种方式是并列存在的使用形态，下文全部示例均基于torch.hub.load("ultralytics/yolov5", ...)这一 YOLOv5 专用入口。

三、最简单的模型加载与推理

'yolov5s'是 YOLOv5 系列中体积最小、速度最快的预训练模型之一，最适合作为入门与原型验证的选择。其余可用模型规模（n/s/m/l/x 直至 x6 等）的预训练权重信息可参见 YOLOv5 主索引文档 docs/en/yolov5/index.md。

以下最小示例加载yolov5s模型并对一张网络图片执行推理：

import torch # 模型：从 PyTorch Hub 加载预训练 YOLOv5s model = torch.hub.load("ultralytics/yolov5", "yolov5s") # 图片：可直接传入 URL 字符串 im = "https://ultralytics.com/images/zidane.jpg" # 推理 results = model(im) # 以 Pandas DataFrame 查看检测结果 results.pandas().xyxy[0] # xmin ymin xmax ymax confidence class name # 0 749.50 43.50 1148.0 704.5 0.874023 0 person # 1 433.50 433.50 517.5 714.5 0.687988 27 tie # 2 114.75 195.75 1095.0 708.0 0.624512 0 person # 3 986.00 304.00 1028.0 420.0 0.286865 27 tie

输出表格中每行代表一个检测框：xmin/ymin/xmax/ymax为归一化前的像素级边界框坐标（图片坐标系），confidence为置信度，class为类别索引（0 对应 person，27 对应 tie），name为类别名称。该模型默认使用 COCO 的 80 个类别。

四、详细示例：批量推理与多源输入

实际使用中往往需要同时处理多张图片，且输入来源可能是 PIL 图片或 OpenCV 读取的数组。YOLOv5 通过AutoShape()前向方法对输入做了统一封装：可以接收单张图片、图片列表，以及 URL、文件路径、PIL、OpenCV、numpy 数组等多种形式的混合输入。推理结果对象支持打印到控制台、保存到runs/hub目录、在支持的桌面环境弹窗显示，并可以转换为Tensor或Pandas DataFrame两种结构化形态。

import cv2 import torch from PIL import Image # 模型 model = torch.hub.load("ultralytics/yolov5", "yolov5s") # 图片：先下载两张示例图到本地 for f in "zidane.jpg", "bus.jpg": torch.hub.download_url_to_file(f"https://ultralytics.com/images/{f}", f) # 读取为不同格式：PIL 图片 / OpenCV 图片（BGR 转 RGB） im1 = Image.open("zidane.jpg") im2 = cv2.imread("bus.jpg")[..., ::-1] # 推理：传入图片列表即构成一个 batch，size 指定推理边长 results = model([im1, im2], size=640) # 结果输出 results.print() # 打印到控制台 results.save() # 保存到 runs/hub；在支持的桌面环境可改用 .show() 弹窗 results.xyxy[0] # 第 1 张图的预测结果（Tensor） results.pandas().xyxy[0] # 第 1 张图的预测结果（Pandas DataFrame） # xmin ymin xmax ymax confidence class name # 0 749.50 43.50 1148.0 704.5 0.874023 0 person # 1 433.50 433.50 517.5 714.5 0.687988 27 tie # 2 114.75 195.75 1095.0 708.0 0.624512 0 person # 3 986.00 304.00 1028.0 420.0 0.286865 27 tie

要点解读：

results.xyxy[0]返回的是 Tensor（第 0 张图），results.pandas().xyxy[0]返回同名 DataFrame，两者字段一致；
size=640指定送入网络的推理边长，YOLOv5 内部会按该边长做 letterbox 缩放，推理完成后坐标会被映射回原始图像尺寸；
混合 batch 允许 PIL 与 OpenCV 图像并存，AutoShape会自动完成格式归一化（含 BGR→RGB 转换、维度补齐）。

在现代统一代码库中，这一类「推理结果统一封装」的设计仍被延续：如 engine/results.py 中的Results类即统一承载检测、分割、姿态等任务的输出，并提供show、save、save_txt、save_crop、xyxy等能力，同时借助DataExportMixin扩展出to_df、to_json、to_csv等结构化导出接口，可视为 YOLOv5 结果对象思路的演进版本。

五、推理参数设置

加载后的 YOLOv5 模型对象上挂载了一系列可直接赋值的推理属性，用于控制 NMS（非极大值抑制）与输出行为。除下表所列属性外，size作为调用参数传入model(im, size=320)可临时指定自定义推理尺寸。

属性	示例默认值	作用说明
`model.conf`	`0.25`	NMS 置信度阈值，低于该值的检测框会被过滤
`model.iou`	`0.45`	NMS 的 IoU 阈值，控制重叠框的抑制强度
`model.agnostic`	`False`	是否启用类别无关（class-agnostic）NMS
`model.multi_label`	`False`	每个框是否允许保留多个类别标签
`model.classes`	`None`	类别过滤白名单，如`[0, 15, 16]`表示只保留 COCO 的 person、cat、dog
`model.max_det`	`1000`	每张图片的最大检测框数量上限
`model.amp`	`False`	是否启用自动混合精度（AMP）推理
`size`（调用参数）	`640`	自定义推理输入边长

示例：

model.conf = 0.25 # NMS 置信度阈值 model.iou = 0.45 # NMS IoU 阈值 model.agnostic = False # 是否类别无关 NMS model.multi_label = False # 每个框是否允许多标签 model.classes = None # （可选列表）按类别过滤，如 = [0, 15, 16] 对应 COCO 的 person、cat、dog model.max_det = 1000 # 每张图最大检测数量 model.amp = False # 自动混合精度推理 results = model(im, size=320) # 自定义推理尺寸

六、设备选择与迁移

YOLOv5 模型本质上是torch.nn.Module，因此创建后可以自由迁移到任意设备：

model.cpu() # CPU model.cuda() # GPU model.to(device) # 例如 device=torch.device(0)

也可以在加载时直接指定目标设备，让权重就地加载到对应硬件：

model = torch.hub.load("ultralytics/yolov5", "yolov5s", device="cpu") # 直接在 CPU 上加载

提示：无论模型位于何种设备，推理前输入图片都会被自动迁移到模型所在设备，无需手动to(device)。

七、静默加载输出

PyTorch Hub 加载时默认会打印下载与初始化日志。在脚本或服务化场景中若希望保持输出干净，可传入_verbose=False：

model = torch.hub.load("ultralytics/yolov5", "yolov5s", _verbose=False) # 静默加载

八、自定义输入通道数（channels）

默认预训练模型输入为 3 通道 RGB。若要处理 4 通道输入（例如带红外或深度通道的图像），可在加载时通过channels指定：

model = torch.hub.load("ultralytics/yolov5", "yolov5s", channels=4)

此时模型会复用除第一个输入层以外的全部预训练权重；由于首层输入形状与预训练权重不匹配，该层会保持随机初始化，需要你在自己的数据上重新训练使其收敛。

九、自定义类别数量（classes）

默认预训练模型输出 COCO 的 80 类。若你的任务只有 10 个类别，可指定classes=10加载结构匹配的模型：

model = torch.hub.load("ultralytics/yolov5", "yolov5s", classes=10)

与 channels 同理：此时模型由预训练权重组成，但输出层形状与预训练权重不一致，输出层保持随机初始化，需基于自己的数据集微调。

十、强制刷新缓存（force_reload）

PyTorch Hub 会在本地缓存拉取过的仓库代码与权重。若遇到加载异常、或希望强制使用远程最新版本，可传入force_reload=True，它会丢弃既有缓存并重新下载最新的 YOLOv5 版本：

model = torch.hub.load("ultralytics/yolov5", "yolov5s", force_reload=True) # 强制重载

缓存副本存放在~/.cache/torch/hub目录下，手动删除该目录也能达到同样的刷新效果。

十一、对桌面屏幕截图做推理

借助PIL.ImageGrab可对桌面屏幕实时截图并送入模型，适合构建「所见即所得」的演示工具：

import torch from PIL import ImageGrab # 模型 model = torch.hub.load("ultralytics/yolov5", "yolov5s") # 图片：抓取当前屏幕 im = ImageGrab.grab() # 推理 results = model(im)

十二、多 GPU 并行推理

YOLOv5 支持将模型分别加载到多张 GPU，并通过多线程各自独立执行推理。由于每个线程持有独立的模型实例，天然避免了单模型并发推理的线程安全问题：

import threading import torch def run(model, im): """对给定图片执行推理并保存结果；要求 model 支持 .save() 方法。""" results = model(im) results.save() # 模型：分别加载到 GPU 0 与 GPU 1 model0 = torch.hub.load("ultralytics/yolov5", "yolov5s", device=0) model1 = torch.hub.load("ultralytics/yolov5", "yolov5s", device=1) # 推理：两个线程各自独立跑一张图 threading.Thread(target=run, args=[model0, "https://ultralytics.com/images/zidane.jpg"], daemon=True).start() threading.Thread(target=run, args=[model1, "https://ultralytics.com/images/bus.jpg"], daemon=True).start()

线程设为daemon=True意味着主进程结束后线程随之退出，适合嵌入已有服务程序的场景。

十三、用 Hub 加载做训练

通过 PyTorch Hub 加载的模型默认包了一层推理用AutoShape。若目标是训练而非推理，须传入autoshape=False以拿到裸模型；若要从零开始训练（随机初始化权重），再加pretrained=False：

import torch model = torch.hub.load("ultralytics/yolov5", "yolov5s", autoshape=False) # 加载预训练裸模型 model = torch.hub.load("ultralytics/yolov5", "yolov5s", autoshape=False, pretrained=False) # 加载随机初始化裸模型

从零训练需要自行编写训练脚本。完整的自定义数据集训练流程（数据集组织、YAML 配置、训练命令与调优建议）请阅读 YOLOv5 自定义数据训练教程。

十四、结果对象的进阶消费方式

YOLOv5 推理返回的results是一个功能丰富的封装对象，除.print()、.save()、.show()外，还支持以下常见的数据导出形态。

1. Base64 编码结果（适合 API 服务）

调用results.render()会把带框标注的图像写回results.ims，再逐帧编码为 JPEG 并转 Base64，即可直接放进 JSON 响应体中。与 REST API（如 Flask）结合即可构建检测服务：

import base64 from io import BytesIO from PIL import Image results = model(im) # 推理 results.ims # 送入推理的原始图像数组（np array） results.render() # 将检测框与标签绘制回 results.ims for im in results.ims: buffered = BytesIO() im_base64 = Image.fromarray(im) im_base64.save(buffered, format="JPEG") print(base64.b64encode(buffered.getvalue()).decode("utf-8")) # 输出带结果的 Base64 图片

2. 裁剪检测目标（Cropped Results）

results.crop(save=True)会把每个检测框内的目标单独裁剪保存，返回裁剪结果字典，适合后续做车牌识别、物体检索等下游任务：

results = model(im) # 推理 crops = results.crop(save=True) # 保存裁剪出的检测目标

3. Pandas DataFrame

results.pandas()把底层数据转换为 Pandas DataFrame，便于进一步做数据分析与筛选：

results = model(im) # 推理 results.pandas().xyxy[0] # Pandas DataFrame

展开查看输出示例：

Pandas 输出（点击展开）

print(results.pandas().xyxy[0]) # xmin ymin xmax ymax confidence class name # 0 749.50 43.50 1148.0 704.5 0.874023 0 person # 1 433.50 433.50 517.5 714.5 0.687988 27 tie # 2 114.75 195.75 1095.0 708.0 0.624512 0 person # 3 986.00 304.00 1028.0 420.0 0.286865 27 tie

4. 按列排序（Sorted Results）

DataFrame 支持按任意列排序，例如把车牌号数字检测按xmin从左到右排列，从而得到正确的读序：

results = model(im) # 推理 results.pandas().xyxy[0].sort_values("xmin") # 按 xmin 从左到右排序

5. JSON 序列化（JSON Results）

将.pandas()得到的 DataFrame 再用.to_json()序列化即可获得 JSON；orient参数可控制 JSON 的组织形式（如"records"输出对象数组）：

results = model(ims) # 推理 results.pandas().xyxy[0].to_json(orient="records") # 第 1 张图的 JSON 预测

展开查看 JSON 输出示例：

JSON 输出（点击展开）

[ { "xmin": 749.5, "ymin": 43.5, "xmax": 1148.0, "ymax": 704.5, "confidence": 0.8740234375, "class": 0, "name": "person" }, { "xmin": 433.5, "ymin": 433.5, "xmax": 517.5, "ymax": 714.5, "confidence": 0.6879882812, "class": 27, "name": "tie" }, { "xmin": 115.25, "ymin": 195.75, "xmax": 1096.0, "ymax": 708.0, "confidence": 0.6254882812, "class": 0, "name": "person" }, { "xmin": 986.0, "ymin": 304.0, "xmax": 1028.0, "ymax": 420.0, "confidence": 0.2873535156, "class": 27, "name": "tie" } ]

说明：本文多处结果表格沿用官方文档中zidane.jpg的示例输出，实际数值取决于模型版本与推理设置，请以本机运行为准。

十五、加载自定义模型

对于自训练权重，使用"custom"入口并指定权重路径。第一个示例从 PyTorch Hub 加载本地best.pt（例如在 VOC 20 类数据上训练的模型）；第二个示例指定本地代码仓库作为 Hub 源，适合离线或二次开发场景：

import torch # 从 PyTorch Hub 拉取代码 + 加载本地权重（推荐） model = torch.hub.load("ultralytics/yolov5", "custom", path="path/to/best.pt") # 从本地代码仓库加载（本地 repo 需自带 hubconf 入口） model = torch.hub.load("path/to/yolov5", "custom", path="path/to/best.pt", source="local")

十六、加载 TensorRT / ONNX / OpenVINO 等导出模型

PyTorch Hub 还支持加载绝大多数 YOLOv5 导出格式的权重（含自训练模型），只需把path指向对应格式文件：

import torch model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.pt") # PyTorch model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.torchscript") # TorchScript model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.onnx") # ONNX model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s_openvino_model/") # OpenVINO model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.engine") # TensorRT model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.mlmodel") # CoreML（仅 macOS） model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s.tflite") # TFLite model = torch.hub.load("ultralytics/yolov5", "custom", path="yolov5s_paddle_model/") # PaddlePaddle

各导出格式的完整流程（含导出命令与校验方式）请阅读 YOLOv5 模型导出教程：TFLite / ONNX / CoreML / TensorRT。

性能层面，官方文档给出的经验结论是：TensorRT 在 GPU 上可比原生 PyTorch 快 2–5 倍；ONNX 与 OpenVINO 在 CPU 上可比 PyTorch 快 2–3 倍。此类数据来自官方基准测试文档，实际提速幅度取决于硬件、批大小与优化选项，应在你的目标平台上实测确认。

十七、支持的运行环境

Ultralytics 提供了一系列开箱即用的运行环境，均已预装 CUDA、cuDNN、Python、PyTorch 等核心依赖。面向 YOLOv5 的快速上手指南分散于仓库的 environments 目录，可按下述路径直接取用：

Google Cloud：GCP 快速入门
AWS：AWS 快速入门
Azure：AzureML 快速入门
Docker：Docker 快速入门，镜像构建配方亦见仓库根目录 docker 下的系列 Dockerfile（CPU、GPU、arm64、Jetson 等变体）

此外，仓库根目录的 examples/tutorial.ipynb 提供了可在云端笔记本中逐步运行的交互式演示。

十八、项目状态与回归保障

YOLOv5 通过持续集成（CI）测试保障跨平台的稳定性：自动化测试会周期性（每 24 小时及每次新提交时）在 macOS、Windows、Ubuntu 上对训练、验证、推理、导出、基准测试等核心链路进行回归验证，确保各功能在不同系统上保持可用。在本文所属的仓库中，与之对应的测试体系见 tests 目录（如 tests/test_cli.py、tests/test_python.py、tests/test_exports.py），可用于理解推理、导出等能力的自动化校验方式。

小结

本文围绕「PyTorch Hub 加载 YOLOv5」这一主线，依次覆盖了环境准备、单图/批量推理、推理属性调优（conf、iou、classes、max_det、amp等）、设备迁移、静默加载、通道与类别数定制、缓存强制刷新、屏幕截图推理、多 GPU 线程化推理、训练模式加载，以及结果对象在 Pandas、JSON、Base64、目标裁剪等场景下的消费方法，最后延伸到自定义权重与各导出格式（ONNX/TensorRT/OpenVINO 等）的统一加载。无论你是要快速验证一个检测想法，还是为服务架构挑选推理入口，torch.hub.load都是一条依赖最少、上手最快的 YOLOv5 接入路径。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考