1. Win10 上用 VS2019 编译 YOLOv5:一套工具链解决什么问题
模型训练完,权重在 Python 里跑得挺欢,一交给 C++ 侧就卡住,这是把 YOLOv5 往桌面程序里塞的人最常遇到的场面。这套代码开发工具链的目标很明确:VS2019 负责编译 C++ 宿主程序,CMake 负责把 CUDA、TensorRT、OpenCV 三套路径一次性写进工程,TensorRT 负责把导出的 ONNX 权重变成 GPU 上能直接跑的引擎。它解决的核心问题是“模型能不能被一个没装 Python 的 exe 调起来”,并非“模型准不准”。适合手里已经有训练好的权重、要交付 Win10 桌面端或工控机检测程序的人。最反直觉的一点是,真正耗时间的往往不是推理代码本身,而是版本配套和 DLL 路径,这两件事会让你在编译器和加载器之间反复切换。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 七个开发工具的版本锁定:装什么、装哪、PATH 怎么排
在 Win10 上做这套部署,第一件事是确认工具版本,动手安装通常会放在后面。版本选错,后面的 CMake 配置和引擎构建都会白做;版本选对后,很多看起来像“代码问题”的报错根本不会出现。这一章把组件清单、安装顺序和环境变量讲清楚,后面两章才有稳定的基础。
2.1 版本为什么必须成套锁死
这套组合里,CUDA 10.2、cuDNN 7.6.5、TensorRT 7.0.0.11 是一组。TensorRT 7 的 lib 是对着 CUDA 10.2 编译的,cuDNN 7.6.5 是 CUDA 10.2 对应的深度神经网络库版本,三者的 ABI 要对得上。VS2019 要能编译 CUDA 10.2 的 host 代码,CMake 3.19.4 的生成器要认识 VS2019 的工程格式。Anaconda3 只负责隔离 Python 环境,避免和系统 Python 打架。OpenCV 3.4.0 负责读图、缩放和画框。
如果各装最新版,比如 TensorRT 8 配 CUDA 11 配 VS2022,那是另一条路线,YOLOv5 的 C++ 推理示例里的 API 名称、头文件路径、参数名都对不上,等于把教程重新写一遍。所以这里的原则是“成套”,并非“最新”。锁定版本的另一层意义是可复现:换一台机器,照着同一张表装,出问题的概率会低很多。
| 组件 | 版本 | 职责 | 装完怎么验证 |
|---|---|---|---|
| CUDA Toolkit | 10.2 | GPU 编程平台,提供 nvcc 和运行时 | nvcc --version |
| cuDNN | 7.6.5 | 加速卷积等算子 | where cudnn64_7.dll |
| TensorRT | 7.0.0.11 | 推理优化器与运行时 | where nvinfer.dll |
| Visual Studio | 2019 | 编译 C++ 宿主程序 | 能新建 C++ 空项目并编译 |
| OpenCV | 3.4.0 | 图像读写与预处理 | where opencv_world340.dll |
| Anaconda3 | 任意近期版本 | 隔离 Python 导出环境 | conda --version |
| CMake | 3.19.4 | 生成 VS2019 工程 | cmake --version |
这张表建议打印出来贴在工位上。装完一个组件就验证一次,不要全部装完再统一排查,那样出问题时你分不清是哪一步引入的。
2.2 安装顺序与 PATH 的三层排布
安装顺序是有讲究的。VS2019 先装,安装时勾选“使用 C++ 的桌面开发”工作负载,这一项不勾,后面 CUDA 装完也不会往 VS 里集成编译规则。然后装 CUDA 10.2,它会往 VS 里插入 CUDA 项目模板和 build customization。接着把 cuDNN 7.6.5 解压,把其中的 bin、include、lib 三个目录的内容覆盖进 CUDA 的安装目录,这是 cuDNN 的标准摆放方式。TensorRT 7 解压到一个独立目录,比如 D:\TensorRT-7.0.0.11,不要塞进 CUDA 目录里,混在一起以后升级很难拆。OpenCV 3.4.0 同样解压到独立目录。Anaconda3 装完后,最后装 CMake 3.19.4。
PATH 要分三层加:CUDA 的 bin 目录(nvcc、cudart 相关 DLL)、cuDNN 覆盖后的 bin 目录(cudnn64_7.dll)、TensorRT 的 lib 目录(nvinfer.dll、nvinfer_plugin.dll)、OpenCV 的 bin 目录(opencv_world340.dll)。把 TensorRT 的 lib 目录直接加进 PATH 是最省事的做法,省得每次编译完还要把一堆 DLL 手工拷到 exe 旁边。三层都加完后,开一个新的命令行窗口验证,老窗口的 PATH 是旧的,改了也不生效。
bash复制nvcc --version
输出里要能看到 release 10.2 字样。看不到说明 CUDA 的 bin 没进 PATH,或者装了多套 CUDA 但 PATH 里排在前面的不是 10.2。
bash复制where cudnn64_7.dll
where nvinfer.dll
where opencv_world340.dll
三条都能定位到具体路径,才算运行时依赖通了。where 只返回第一个命中,如果机器上有多份同名 DLL,用 where /R 在指定盘符下搜一遍,确认 PATH 里排前面的是你要的那份。
bash复制cmake --version
版本要显示 3.19.4。CMake 版本太老会不认识 VS2019 的生成器名,配置阶段就会报错。
2.3 Python 环境只承担导模型这一件事
Python 侧在这条链路里的任务很轻:加载训练好的权重,导出一个 ONNX 文件,然后就可以退场了。用 conda 建一个独立环境,避免污染系统 Python,也避免和别的项目抢 torch 版本。
bash复制conda create -n y5export python=3.8 -y
conda activate y5export
pip install torch torchvision opencv-python onnx
python export.py --weights yolov5s.pt --include onnx --img 640 --batch 1
--img 640 是网络输入尺寸,这个值必须和后面 C++ 侧预处理时的缩放尺寸一致,两边不一致的典型表现是框的位置整体偏移,而不是报错,查起来很费时间。--batch 1 是固定单张,先把单张链路跑通;要做批量推理时再导出 --batch N 或者开动态轴,但动态 batch 会让引擎构建时的显存规划和 workspace 估算复杂一档,第一步不建议开。
导出完成后确认目录里生成了 .onnx 文件,记下它的绝对路径,下一章配置 CMake 时要用。这里有个容易走偏的地方:不要在 Python 侧再装一份 TensorRT 的 pip 包来做转换。机器上会出现两套 TensorRT,一套在 conda 环境里,一套在 D:\TensorRT-7.0.0.11,版本稍有差异时,报错信息会指向错误的那一套,排查成本很高。转换统一放在 C++ 侧做。
3. CMake 生成 VS2019 工程:路径、宏和 Release 配置怎么给
YOLOv5 的 C++ 推理侧通常以 CMakeLists 组织源码,直接双击 sln 是行不通的,因为工程文件还没生成。CMake 在这里的价值是把 CUDA、TensorRT、OpenCV 三套路径一次性写进 VS 工程,避免在 VS 的属性页里逐个手工配 include 和 lib——那种配法一旦换机器就要重来一遍,而且极容易在 Debug 和 Release 之间配串。
3.1 为什么不直接改 VS 工程属性
手工在 VS 里配依赖,短期看快,长期是负担。三套库各有 include 目录和 lib 目录,加起来六七个路径,还要区分 x64 平台和 Debug/Release 配置。VS 的属性页有“所有配置”和“当前配置”两套作用域,改错作用域时,Release 能编过、Debug 报链接错误,或者反过来。CMake 把这些写进 CMakeLists,改一次全配置生效,换机器只要改几个变量。
生成器要选 Visual Studio 16 2019,平台指定 x64。这两个参数写错,后面编译出来的库位数不对,运行时会报“不是有效的 Win32 应用程序”,这个报错和 DLL 缺失长得完全不一样,但根因往往是平台选错。
3.2 CMakeLists 里必须写死的四组路径
CMakeLists 里要处理四组东西:CUDA 的工具链根目录、TensorRT 的头文件和库、OpenCV 的配置目录、以及 C++ 标准。下面是一段精简后的结构,实际工程里按自己的目录名调整。
cmake复制cmake_minimum_required(VERSION 3.19)
project(yolo_trt LANGUAGES CXX CUDA)
# C++14 起步,TensorRT 7 的头文件依赖它
set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# CUDA:指定 10.2 的工具链根目录
find_package(CUDA 10.2 REQUIRED)
include_directories(${CUDA_INCLUDE_DIRS})
# TensorRT:头文件和 lib 目录,路径用正斜杠
set(TENSORRT_ROOT "D:/TensorRT-7.0.0.11")
include_directories(${TENSORRT_ROOT}/include)
link_directories(${TENSORRT_ROOT}/lib)
# OpenCV:走 OpenCVConfig.cmake,避免手工拼 lib 名
find_package(OpenCV REQUIRED)
include_directories(${OpenCV_INCLUDE_DIRS})
add_executable(yolo_trt main.cpp trt_engine.cpp)
target_link_libraries(yolo_trt nvinfer nvinfer_plugin ${OpenCV_LIBS} ${CUDA_LIBRARIES})
find_package(CUDA 10.2 REQUIRED) 里的版本号是硬约束,机器上装了多套 CUDA 时,这一行能帮你确认 CMake 找到的是 10.2 而不是别的那套。link_directories 指向 TensorRT 的 lib,后面 target_link_libraries 里写 nvinfer 和 nvinfer_plugin 就能链上,插件库不能省,YOLOv5 的一些层要靠它。OpenCV 走 find_package 而不是手工拼 opencv_world340.lib,是因为 3.4.0 的安装包里带了 OpenCVConfig.cmake,让它自己解决依赖更稳。
路径写法上,CMake 里统一用正斜杠。Windows 的反斜杠在 CMake 字符串里会被当转义符,D:\TensorRT 里的 \T 会被吃掉,报错信息还看不出是路径问题。
3.3 配置命令与 Release 配置的一致性
在源码目录外建一个 build 目录,进去执行配置。路径里有空格时一定要加引号,CUDA 默认装在 C:\Program Files\... 下面,这一条几乎每次都会踩。
bash复制mkdir build
cd build
cmake -G "Visual Studio 16 2019" -A x64 ^
-DCUDA_TOOLKIT_ROOT_DIR="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v10.2" ^
-DTENSORRT_ROOT="D:/TensorRT-7.0.0.11" ^
-DOpenCV_DIR="D:/opencv/build" ^
..
-G 指定生成器,-A x64 指定平台,这两个参数决定生成的 sln 里是什么配置。-DOpenCV_DIR 指向的是包含 OpenCVConfig.cmake 的那个目录,通常是 opencv/build 而不是 opencv,指错一层会报找不到配置文件。
配置成功后,编译要用 --config Release。对 VS 生成器来说,CMAKE_BUILD_TYPE 是不生效的,那是 Makefile 生成器的概念;在 VS 下必须通过 --config 指定,否则默认走 Debug,而 TensorRT 的 lib 基本都是 release 版,Debug 配置下链接大概率失败。
bash复制cmake --build . --config Release --target yolo_trt -j 8
--target 指定只编某个目标,工程里目标多的时候能省时间。-j 8 是并行编译的任务数,按机器核数给,给太大会把内存吃满,编译过程被系统杀掉,现象是编译器无提示退出。
Release 配置下的运行库要选 /MD,Debug 选 /MDd。这一项和 TensorRT、OpenCV 的预编译库必须一致,混用时的表现是链接期报一堆 LNK2005 重复定义,或者运行期在第一个 TensorRT 调用处直接崩。CMake 默认会跟着配置走,但如果你在 CMakeLists 里手工加过 CMAKE_CXX_FLAGS_RELEASE,要确认没把 /MD 覆盖掉。
4. 从权重到 TensorRT 引擎:解析器、batch 与精度取舍
Python 侧导出的 ONNX 只是一个中间格式,真正在 GPU 上跑的是 TensorRT 序列化出来的引擎文件。这一步是整个链路里参数最密集的地方,workspace 给多少、精度开不开 FP16、batch 设多大,都会直接影响能不能构建成功以及构建出来的东西跑多快。
4.1 引擎构建这一步到底做了什么
TensorRT 拿到 ONNX 后做三件事:解析网络结构、做层融合和算子选择、按目标 GPU 的算力生成执行计划,最后序列化成一个二进制文件。层融合是它提速的主要来源,把卷积、BN、激活合成一个算子,减少显存往返。也正因为执行计划是按具体 GPU 生成的,引擎文件和 GPU 型号、TensorRT 版本是绑定的,换机器不能直接拷过去用。
构建阶段有两个参数要先定:最大 batch 和 workspace 大小。最大 batch 决定引擎支持的单次推理上限,workspace 是构建期允许 TensorRT 临时占用的显存,给太小会在某些层上构建失败,报的是内存分配相关的错误,但会让人误以为是模型问题。
4.2 解析器与构建参数的写法
下面这段是构建引擎的最小骨架,用的是 TensorRT 7 的接口。日志器需要自己实现一个 ILogger,这里省略实现,只保留调用链。
cpp复制#include <NvInfer.h>
#include <NvOnnxParser.h>
// 1. 创建 builder 和网络定义,显式 batch 必须打开
nvinfer1::IBuilder* builder = nvinfer1::createInferBuilder(gLogger);
const auto explicitBatch =
1U << static_cast<uint32_t>(nvinfer1::NetworkDefinitionCreationFlag::kEXPLICIT_BATCH);
nvinfer1::INetworkDefinition* network = builder->createNetworkV2(explicitBatch);
// 2. 解析 ONNX,严重级别调到 WARNING,避免刷屏
nvonnxparser::IParser* parser = nvonnxparser::createParser(*network, gLogger);
if (!parser->parseFromFile(onnxPath, static_cast<int>(nvinfer1::ILogger::Severity::kWARNING))) {
// 解析失败时把 parser->getNbErrors() 逐条打出来
}
// 3. 构建期参数:batch 上限、workspace、精度
builder->setMaxBatchSize(maxBatch);
builder->setMaxWorkspaceSize(1ULL << 30); // 1GB
builder->setFp16Mode(true); // 显卡支持时开 FP16
// 4. 构建并序列化
nvinfer1::ICudaEngine* engine = builder->buildCudaEngine(*network);
nvinfer1::IHostMemory* serialized = engine->serialize();
// serialized->data() / serialized->size() 写到 .engine 文件
createNetworkV2 的显式 batch 标志必须打开,YOLOv5 的导出模型带 batch 维,不开的话解析阶段就会报维度不匹配。setMaxWorkspaceSize(1ULL << 30) 是 1GB,这个值在中端显卡上够用,显存紧张时可以降到 512MB,但不要低于模型里最大单层所需的临时空间,否则构建会在那一层失败。setFp16Mode(true) 只在显卡支持 FP16 时有效,不支持的卡上这个调用不会报错,但也不会提速,容易被误判成“开了没效果”。
parseFromFile 返回 false 时不要只看一句“解析失败”,要把 parser->getNbErrors() 循环打出来,每条错误都带层名和原因。YOLOv5 换版本后导出结构变化,最常见的解析失败就是某个算子不被当前 TensorRT 版本支持,错误信息里会直接点名。
4.3 精度与 workspace 的取舍
三种精度的差别要提前想清楚,不要等到跑起来发现框飘了再回头改。
| 精度 | 相对速度 | 精度影响 | 前置条件 |
|---|---|---|---|
| FP32 | 基准 | 无 | 无 |
| FP16 | 明显更快 | 一般可接受 | 显卡支持 FP16 |
| INT8 | 最快 | 需要校准,影响较大 | 有代表性校准集 |
第一次跑通建议用 FP32,确认输出框和 Python 侧一致后再切 FP16 对比。FP16 在检测任务上多数情况够用,框的位置可能有小幅偏移,用同一张图对比两边的置信度和坐标就能看出来。INT8 需要准备一批有代表性的图片做校准,校准集和实际场景偏差大时,掉点会很明显,这一步不适合在链路还没跑通的时候做。
batch 的选择上,单张推理设 1 最简单。要提吞吐就往上加,但显存占用跟着涨,而且预处理和后处理都要按 batch 改写,改动量不小。比较稳的做法是先固定 batch 1 把引擎构建、序列化、加载、推理整条链路验证完,再把 batch 作为独立的一次改动去做。
workspace 的大小和 batch、精度是联动的。batch 调大后,同样的 workspace 可能不够,表现为构建阶段报显存分配失败。这时候先加 workspace,加完还不够再降 batch,顺序不要反。
5. 编译与运行期的常见问题:现象、原因、解决
这条链路的问题有个特点:编译期报错往往指向路径,运行期报错往往指向 DLL 和版本,引擎构建期报错往往指向参数。三类问题的排查入口完全不同,混在一起查会绕远路。下面五条是按实际出现频率排的。
5.1 编译通过,双击 exe 报找不到 cudnn64_7.dll
现象:VS 里按 F5 能跑,把 exe 拷到别的目录或者直接双击就弹窗说缺 DLL,有时缺的是 cudnn64_7.dll,有时是 nvinfer.dll。
原因:VS 调试时的工作目录和 PATH 继承了 IDE 的环境,而双击运行时用的是系统 PATH。cuDNN 和 TensorRT 的 DLL 如果只加在了用户变量里,或者加在了某个只在 IDE 里生效的位置,独立运行就找不到。
解决:把 cuDNN 的 bin、TensorRT 的 lib、OpenCV 的 bin 都加到系统 PATH,加完注销一次再登录。临时验证可以把这几个 DLL 直接拷到 exe 同目录,能跑起来就说明是 PATH 问题,不是依赖缺失。
5.2 nvcc 编译 host 代码时报不支持的编译器版本
现象:CMake 配置能过,编译 .cu 文件时报编译器版本不受支持,或者干脆在 host 代码编译阶段挂掉。
原因:CUDA 10.2 对 VS 的版本有配套范围,机器上装了更高版本的 VS 并被 nvcc 选中时,就会出现这个报错。这和代码无关,纯粹是工具链搭配问题。
解决:确认 VS2019 装好且带 C++ 桌面开发工作负载,把 CUDA 10.2 的 host 编译器指向 VS2019 的 MSVC 工具集。机器上有多套 VS 时,用 VS2019 的开发者命令行启动 CMake,让环境变量里的编译器路径唯一。
5.3 CMake 配置成功,但 VS 里找不到 TensorRT 头文件
现象:配置阶段没有报错,打开生成的 sln 编译时提示 NvInfer.h 找不到。
原因:TENSORRT_ROOT 写错,或者路径里带反斜杠被 CMake 当转义符吃掉,或者改了变量后没有清缓存重新配置。CMake 的缓存会记住上一次的变量值,直接重跑有时不生效。
解决:把路径统一改成正斜杠,带空格的加引号。改完删掉 build 目录重新配置,不要在原目录上反复试。确认 TENSORRT_ROOT/include 下面确实有 NvInfer.h 和 NvOnnxParser.h 两个文件。
5.4 构建引擎时报 workspace 不足或显存分配失败
现象:解析 ONNX 成功,走到 buildCudaEngine 时失败,日志里出现内存分配相关的错误。
原因:setMaxWorkspaceSize 给得太小,或者 batch 设得太大,构建期的临时显存超过了设定上限。这和推理时的显存占用是两回事,构建期往往更吃显存。
解决:先把 workspace 翻倍试,1GB 不够试 2GB。还不行就降 batch,单张先构建成功。同时关掉其他占显存的进程,构建期的显存是独占申请的。
5.5 换一台机器加载引擎直接失败
现象:在开发机上序列化好的 .engine 文件,拷到另一台机器上反序列化时报错,或者加载成功但推理结果全乱。
原因:引擎文件里是面向具体 GPU 算力生成的执行计划,和 GPU 型号、TensorRT 版本绑定。跨型号或跨版本加载不在支持范围内,表现可能是直接失败,也可能是加载成功但结果不可信,后者更危险。
解决:引擎文件不跨机器拷,在目标机器上用同一份 ONNX 重新构建。确实要分发的场景,分发 ONNX 加构建程序,首次启动时在本机构建并缓存。命名上把 GPU 型号和精度写进文件名,能避免拿错文件。
6. 验证推理结果与引擎复用:把一次性编译变成可重复流程
链路跑通之后,下一步是确认结果可信。最直接的办法是拿同一张图,在 Python 侧和 C++ 侧各跑一遍,对比框的数量、坐标和置信度。Python 侧用导模型时那个环境跑,C++ 侧跑刚编译出来的程序,两边预处理要保持一致:同样的缩放方式、同样的归一化、同样的 letterbox 填充策略。任何一处不一致,框的位置都会整体偏移,而且偏移量看起来很“合理”,容易被当成模型精度问题。
对比时不要只看第一张图。挑几张目标密集的、目标很小的、光照偏暗的各跑一遍,密集场景能暴露 NMS 阈值不一致的问题,小目标能暴露输入尺寸不一致的问题。
6.1 引擎序列化与启动加速
每次启动都重新构建引擎,在开发期无所谓,交付时不能接受,构建一次要几十秒到几分钟。正确做法是构建完立刻序列化落盘,程序启动时先找引擎文件,找到就直接反序列化,找不到再走构建流程。
cpp复制// 保存:构建完成后写文件
std::ofstream out(enginePath, std::ios::binary);
out.write(static_cast<const char*>(serialized->data()), serialized->size());
// 加载:启动时优先反序列化
std::ifstream in(enginePath, std::ios::binary);
std::vector<char> buf((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
nvinfer1::IRuntime* runtime = nvinfer1::createInferRuntime(gLogger);
nvinfer1::ICudaEngine* engine = runtime->deserializeCudaEngine(buf.data(), buf.size(), nullptr);
反序列化失败时返回空指针,不要直接往下用。失败原因通常是引擎文件损坏,或者换了 GPU。文件名里带上 GPU 型号和精度,比如 yolov5s_fp16_<型号>.engine,能省掉很多“为什么加载不了”的排查。
6.2 我现在的固定习惯
从那以后我每次配这套环境,都强制走一遍固定顺序:先 nvcc --version 和三条 where 确认依赖可见,再跑一次 CMake 配置并检查生成器是 VS2019、平台是 x64,然后编译 Release,最后拿同一张图做 Python 与 C++ 的双边对比。这四步里任何一步跳过,后面都要用更多时间补回来。版本表贴在工位上这件事,也是踩过几次“以为装的是 10.2 其实是另一套”之后才养成的。希望帮到你。
