C 部署 YOLOv5 这件事我从最早用 OpenCV DNN 硬扛到后来切到 ONNX Runtime中间踩的坑能写满两页纸。标题里这几个词——C、ONNX Runtime、YOLOv5、CUDA 加速——单拎出来都不难难的是把它们串成一条能跑通、能复现、还能上生产的链路。这篇就按我实际落地的顺序把整条链路拆开讲清楚模型怎么导出、C 侧怎么搭推理骨架、CUDA 加速到底在哪一步生效、前后处理怎么写才不出错以及那些文档里不会写、只有真跑过才知道的细节。先说清楚这篇适合谁看。如果你是会一点 C、想把训练好的检测模型塞进桌面端或边缘设备的开发者这篇能直接抄作业如果你只是想在 Python 里跑个 demo那没必要折腾 C直接用现成脚本更省事。C 部署的价值在于低延迟、低依赖、可嵌入——没有 Python 运行时、没有 GIL 拖累、内存可控配合 CUDA 能把单帧推理压到毫秒级。代价是你要自己管内存、自己写前后处理、自己处理模型输入输出的形状对齐。下面按模块往下走。1. 整体方案设计与技术选型拆解1.1 为什么是 ONNX Runtime 而不是别的推理框架部署 YOLOv5 的 C 路线其实有好几条OpenCV DNN、TensorRT、LibTorch、ONNX Runtime。我挨个试过最后稳定用 ONNX Runtime理由很实在。OpenCV DNN 最省事readNetFromONNX一行就能加载但它对动态 shape 和某些算子支持不稳YOLOv5 的 Focus 层早期版本和某些 slice/concat 组合在旧版本 OpenCV 上会直接报错而且 CUDA 后端需要自己编译带 CUDA 的 OpenCV编译一次半小时起步劝退。TensorRT 性能最强但绑定 NVIDIA 生态、序列化引擎和显卡型号强相关换张卡就得重新 build工程上不够灵活。LibTorch 依赖重一个 lib 几百兆打包发布很痛苦。ONNX Runtime 的甜点在于跨平台、依赖轻、CUDA/TensorRT/CPU 多后端可切换、API 稳定。同一份 C 代码编译时链接 CPU 版就是纯 CPU 推理链接 GPU 版就自动走 CUDA业务代码几乎不用改。这对需要同时覆盖有卡和无卡设备的项目来说省下的适配成本非常可观。提示ONNX Runtime 的 GPU 包和 CPU 包是分开的Windows 下分别是onnxruntime.dll和onnxruntime_providers_cuda.dll这一套发布时别漏拷 provider 相关的动态库否则会静默回退到 CPU性能差一个数量级还查不出原因。1.2 YOLOv5 导出 ONNX 的关键取舍模型导出这一步决定了后面 C 侧好不好写。YOLOv5 官方export.py支持导出 ONNX但有几个参数必须想清楚。第一是opset 版本。opset 太低比如 9某些算子表达不了太高又可能和你的 ONNX Runtime 版本不匹配。我一般用 opset 12兼容性好ONNX Runtime 1.10 以上都吃得下。第二是动态 batch 还是固定 batch。如果推理时 batch 固定为 1就导出静态 shape图优化更彻底、速度更快如果要做多路视频流合并推理就开 dynamic axes。我建议先按静态 batch1 导出跑通需要再改。第三也是最容易忽略的输出层要不要带 NMS。YOLOv5 导出时可以加--include nms把非极大值抑制也塞进 ONNX 图里这样 C 侧拿到就是最终框省掉手写 NMS。但带 NMS 的图对动态输入支持差且 NMS 参数置信度阈值、IoU 阈值被固化进模型调参就得重新导出。我的做法是导出不带 NMS 的原始输出NMS 在 C 里自己写灵活可控几十行代码的事。导出命令大致长这样python export.py --weights yolov5s.pt --include onnx --opset 12 --img 640 640 --batch 1导出的模型输入是1x3x640x640的 float32输出是一个1x25200x85的张量以 640 输入、COCO 80 类为例。这个 25200 是三个尺度特征图网格数之和80x80 40x40 20x20 6400 1600 400 8400再乘以每个网格 3 个 anchor8400 x 3 25200。85 是 4 个坐标 1 个 objectness 80 个类别分数。这个形状一定要记牢后面 C 解析全靠它。1.3 CUDA 加速在链路中的位置很多人以为“用了 CUDA 就快”但实际加速效果取决于你把哪部分放到 GPU 上。整条链路分三段预处理图像 resize、归一化、HWC 转 CHW、推理前向计算、后处理解码、NMS。ONNX Runtime 的 CUDA provider 只加速推理这一段。预处理如果在 CPU 上做一张 1080p 图 resize 加归一化可能就要几毫秒推理再快也被拖累。所以我的方案是预处理用 CUDA 做或者至少用高效的 CPU 实现推理交给 ONNX Runtime CUDA provider后处理因为涉及大量分支判断和排序放 CPU 反而更合适。这个分工不是拍脑袋是实测出来的——把 NMS 放 GPU 上小目标多的时候 kernel 启动开销和同步开销反而拖慢整体。2. 环境搭建与依赖配置的实操细节2.1 ONNX Runtime GPU 包的获取与链接ONNX Runtime 官方提供预编译包直接下对应平台的压缩包解压即可不用自己编译。Windows 下拿onnxruntime-win-x64-gpu-1.xx.x.zipLinux 下拿对应的.tgz。解压后目录结构是include/放头文件lib/放库和动态库。CMake 里链接要注意GPU 版需要链接onnxruntime主库运行时还需要onnxruntime_providers_cuda.dll、onnxruntime_providers_shared.dll以及 CUDA 自己的cudart、cublas、cudnn系列。这里有个坑ONNX Runtime 版本和 CUDA/cuDNN 版本是强绑定的。比如某个 ORT 版本要求 CUDA 11.8 cuDNN 8.6你装成 CUDA 12 就可能加载 provider 失败。下包之前一定去官方文档查版本对应表别凭感觉装。CMakeLists 里核心就几行find_package(onnxruntime REQUIRED) target_link_libraries(your_target PRIVATE onnxruntime::onnxruntime)如果官方包没带 CMake config就手动指定set(ORT_ROOT path/to/onnxruntime) target_include_directories(your_target PRIVATE ${ORT_ROOT}/include) target_link_directories(your_target PRIVATE ${ORT_ROOT}/lib) target_link_libraries(your_target PRIVATE onnxruntime)2.2 CUDA provider 的初始化与验证加载模型后第一件事是确认 CUDA provider 真的挂上了。ONNX Runtime 的 session 创建时通过SessionOptions追加 providerOrt::SessionOptions session_options; session_options.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL); OrtCUDAProviderOptions cuda_options; cuda_options.device_id 0; session_options.AppendExecutionProvider_CUDA(cuda_options); Ort::Session session(env, model_path, session_options);AppendExecutionProvider_CUDA这个调用如果失败会抛异常所以能创建成功基本说明 provider 加载了。但“加载了”不等于“真的在用”我见过 provider 加载成功但因为某个算子不支持 CUDA 而自动回退到 CPU 的情况。验证办法是打印 session 的 provider 列表或者干脆用Ort::Session::GetProfilingStartTimeNs配合 profiling 看每个节点的执行设备。最土但最有效的办法跑一次推理用nvidia-smi看显存有没有涨、GPU 利用率有没有跳涨了跳了就是真在用。注意device_id在多卡机器上要显式指定默认 0 不一定是你想要的那张卡。另外 CUDA provider 的 arena 配置cuda_mem_limit、arena_extend_strategy在长时间运行的服务里值得调默认策略在显存碎片化场景下可能越跑越慢。2.3 输入输出张量的形状核对模型加载后别急着写推理先把输入输出的名字和形状打出来核对。ONNX Runtime 的 API 可以拿到GetInputNameAllocated、GetInputTypeInfo把 shape 打印出来。我踩过的坑是导出时用了--img 640 640但实际推理时喂了 1280 的图结果输出形状对不上解码全乱。输入尺寸必须和导出时一致除非你导出了动态 shape。输出形状1x25200x85里的 25200 和 85 也要在代码里做成常量或从模型元信息读别硬编码散落各处。我一般定义一个结构体把num_anchors、num_classes、input_w、input_h集中管理改模型只改一处。3. 推理核心流程的代码实现3.1 预处理从 cv::Mat 到模型输入张量预处理的目标是把一张任意尺寸的 BGR 图变成1x3x640x640的 float32 CHW 张量且保持宽高比letterbox。步骤是算缩放比例、resize、填充灰边、BGR 转 RGB、归一化到 0~1、HWC 转 CHW。letterbox 的缩放比例取min(640/w, 640/h)新尺寸new_w round(w*scale)、new_h round(h*scale)然后cv::resize再copyMakeBorder补到 640x640填充值用 114YOLO 惯例的灰。这里有个细节padding 的左右上下要记录偏移量后处理把框映射回原图时要用。偏移量是pad_x (640 - new_w) / 2、pad_y (640 - new_h) / 2注意取整方式要和 resize 时的 round 保持一致否则框会有半像素偏移。归一化就是除以 255.0然后减均值除方差YOLOv5 默认只做/255不做 ImageNet 的 mean/std 归一化这点别搞错搞错了置信度会整体偏低。HWC 转 CHW 用三层循环或者cv::split都行追求性能就写个连续内存的循环编译器能自动向量化。// 简化示意实际要处理 letterbox 和偏移 cv::Mat blob; cv::dnn::blobFromImage(resized, blob, 1.0/255.0, cv::Size(640,640), cv::Scalar(), true, false);用blobFromImage省事但它内部会做 swapRB 和归一化参数要对swapRBtrue表示 BGR 转 RGBcropfalse。不过blobFromImage不做 letterboxletterbox 得自己先做。追求极致性能的话可以自己写 CUDA kernel 把 resize 归一化 CHW 转换一次做完省掉中间的内存拷贝这个在 1080p 输入下能省 2~3ms。3.2 构造输入张量并执行推理ONNX Runtime 的输入用Ort::Value::CreateTensor创建需要传入内存指针、形状、元素个数。内存可以用Ort::Allocator分配也可以直接传blob的data指针要保证生命周期覆盖推理调用。std::arrayint64_t, 4 input_shape{1, 3, 640, 640}; auto memory_info Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault); Ort::Value input_tensor Ort::Value::CreateTensorfloat( memory_info, blob_data, blob_size, input_shape.data(), input_shape.size()); const char* input_names[] {images}; const char* output_names[] {output0}; auto outputs session.Run(Ort::RunOptions{nullptr}, input_names, input_tensor, 1, output_names, 1);输入名和输出名必须和模型里的一致用 Netron 打开 onnx 文件看一眼就知道别猜。Run返回的是std::vectorOrt::Value取outputs[0]拿输出张量用GetTensorMutableDatafloat()拿数据指针GetTensorTypeAndShapeInfo().GetShape()拿形状。这里有个性能细节每次推理都创建Ort::Value和MemoryInfo有开销在循环里跑的话把MemoryInfo提到循环外输入张量如果内存复用也可以只创建一次。我实测在 30fps 场景下这个优化能省 0.5ms 左右不算大但白捡的。3.3 后处理解码 25200 个候选框后处理是整条链路最容易写错的地方。输出1x25200x85每一行是[cx, cy, w, h, obj, cls0, cls1, ..., cls79]。注意 YOLOv5 导出的坐标是相对于 640 输入的中心点加宽高单位是像素已经乘过 stride不是归一化的。这点和 YOLOv8 不同别混。解码逻辑对每个候选先看obj分数低于阈值比如 0.25直接跳过然后取类别分数最大值和对应类别score obj * cls_score再和阈值比过了就还原框x1 cx - w/2、y1 cy - h/2、x2 cx w/2、y2 cy h/2。然后减去 letterbox 的 pad、除以 scale映射回原图坐标最后 clamp 到图像边界。NMS 按类别做还是跨类别做YOLOv5 默认按类别做class-wise NMS因为不同类别的框重叠是合理的。实现上就是按类别分组每组内按 score 排序贪心抑制 IoU 大于阈值的框。IoU 阈值一般 0.45。手写 NMS 注意两点排序用std::sort对索引排别对框本身排拷贝开销大抑制时用标记数组而不是真的删除元素。struct Detection { float x1, y1, x2, y2, score; int cls; }; // 解码 阈值过滤 按类 NMS输出 std::vectorDetection后处理在 CPU 上跑25200 个候选的循环加排序单帧大概 1~2ms可以接受。如果类别多、候选多可以考虑用 SIMD 优化打分那一段但一般没必要。4. 性能调优与常见问题排查4.1 CUDA 加速效果实测与瓶颈定位我在一张中端显卡上实测过 yolov5s、640 输入、单帧纯 CPU多线程推理约 40~60msCUDA provider 约 8~12ms加速比 4~6 倍。但端到端含预处理和后处理只从 55ms 降到 20ms 左右因为预处理和后处理没被加速。这就是为什么前面强调预处理也要上 GPU——把预处理也搬到 CUDA 后端到端能压到 12ms 上下。定位瓶颈的办法很简单在预处理、推理、后处理三段各打时间戳跑 100 帧取平均。哪段占比大就优化哪段。我见过有人推理 10ms、预处理 30ms还在那调 provider 参数方向就错了。提示第一次推理会包含 CUDA context 初始化和 cuDNN 算法选择耗时可能是后续的几十倍。做性能测试一定要先 warmup 跑 10~20 帧再计时否则数据完全不可信。4.2 常见问题速查表现象可能原因排查与解决创建 session 抛异常provider 动态库缺失或版本不匹配检查onnxruntime_providers_cuda.dll是否在同目录核对 CUDA/cuDNN 版本对应表推理结果全是低分或乱框预处理归一化方式错、BGR/RGB 搞反确认只做/255确认 swapRB 正确框位置整体偏移letterbox 偏移量没还原或取整不一致记录 pad_x/pad_y映射时减掉再除 scale输出形状对不上输入尺寸和导出尺寸不一致打印输入输出 shape统一常量GPU 利用率低、速度没提升provider 静默回退 CPU用 profiling 或 nvidia-smi 确认实际执行设备长时间运行显存持续上涨arena 策略导致碎片累积调整arena_extend_strategy或限制cuda_mem_limit多线程调用崩溃Session 非线程安全每线程独立 Session或加锁串行化4.3 几个只有真跑过才知道的坑第一个坑OpenCV 的cv::Mat内存不一定是连续的。如果图是从 ROI 裁剪出来的isContinuous()可能是 false直接拿data指针喂给模型会读到错位数据。喂之前要么clone()要么检查连续性。第二个坑模型输出的数据指针在outputs生命周期结束后失效。有人把GetTensorMutableData的指针存到全局下次推理再用结果数据是脏的。正确做法是在outputs作用域内完成所有后处理或者把数据拷贝出来。第三个坑多线程下 Session 共享。ONNX Runtime 的Ort::Session本身线程安全Run可以并发调用但如果你在Run外面共享了输入输出 buffer就会数据竞争。我的做法是每个推理线程持有独立的输入 bufferSession 共享这样既省内存又安全。第四个坑动态库搜索路径。Windows 下把 ORT 的 dll 和你的 exe 放同目录最省事Linux 下要么设LD_LIBRARY_PATH要么在 CMake 里设 rpath。发布时漏拷一个 dll程序启动就报找不到模块而且报错信息往往不告诉你是哪个 dll得用依赖查看工具挨个查。5. 工程化封装与扩展思路5.1 把推理封装成可复用的类跑通 demo 和能上生产是两回事。我一般封装一个YoloDetector类构造时传模型路径、是否用 GPU、阈值参数内部持有Ort::Env、Ort::Session、MemoryInfo和预分配的 buffer。对外只暴露一个detect(const cv::Mat)返回std::vectorDetection。这样业务层完全不感知 ONNX Runtime 的存在换模型、换后端都不影响调用方。封装时注意Ort::Env的生命周期要长于所有 Session一般做成单例或类成员。Ort::Env构造时传日志级别生产环境用ORT_LOGGING_LEVEL_WARNING别用 verbose否则日志刷屏还拖慢速度。5.2 从单图到视频流的扩展单图推理跑通后扩展到视频流要注意帧率和延迟的平衡。我的做法是解码和推理分线程用有界队列缓冲帧队列满了丢最旧的帧而不是阻塞——实时场景下丢帧比卡顿体验好。batch 推理能提升吞吐但会增加单帧延迟看场景取舍离线批处理用大 batch实时流用 batch1。如果要做多路视频每路一个推理线程、共享一个 Session或者用 batch 把多路拼一起推理。后者吞吐高但实现复杂要处理不同路输入尺寸不一致的问题一般先做前者。5.3 模型迭代时的兼容性处理模型会更新类别数会变输入尺寸可能变。封装时把类别数、输入尺寸、输出形状都从模型元信息读或者做成配置文件别硬编码。我吃过亏模型从 80 类换成 20 类代码里num_classes80没改后处理越界读内存程序随机崩溃查了两天才定位到。现在我的习惯是加载模型后先校验输出形状的最后一维是否等于5 num_classes不等就直接报错退出把问题暴露在启动阶段而不是运行阶段。另外模型文件建议做版本标记配置里记录模型 hash 或版本号出问题时能快速定位是哪版模型导致的。这个习惯在多人协作的项目里尤其重要。最后分享一个我常用的调试技巧把预处理后的张量 dump 成图片反归一化后保存和后处理画框的结果一起看。如果预处理图就花了问题在预处理如果预处理正常但框乱问题在后处理。这个二分法能砍掉一大半排查时间。模型部署这活儿八成的问题都出在前后处理的形状和坐标对齐上推理本身反而很少出错。