NanoDet LibTorch C++ 推理部署指南:TorchScript 模型导出与 CMake 工程构建实战
NanoDet LibTorch C++ 推理部署指南:TorchScript 模型导出与 CMake 工程构建实战
NanoDet 是面向移动端与嵌入式场景的轻量级无锚框(anchor-free)目标检测模型,而 demo_libtorch/README.md 则专门讲解了如何脱离 Python 运行时,用 C++ 完成 NanoDet 的推理落地。本文以该文档为骨架,结合仓库内 tools/export_torchscript.py 与 demo_libtorch 目录下的完整 C++ 源码,带你走通「PyTorch 权重 → TorchScript 模型 → CMake 编译 → C++ 实时推理」的整条链路。读完本文,你将掌握 LibTorch 工程的环境搭建、模型导出命令的每个参数、四种演示运行模式,以及 NanoDet-Plus 检测头输出如何在 C++ 侧完成 DFL 解码与 NMS 后处理。
一、demo_libtorch 目录与整体流程
demo_libtorch 目录提供了一套基于 LibTorch(PyTorch C++ 接口)的 NanoDet 推理实现,文件构成如下:
| 文件 | 作用 |
|---|---|
| README.md | 构建与使用说明 |
| CMakeLists.txt | CMake 构建脚本,负责链接 Torch 与 OpenCV |
| nanodet_libtorch.h | NanoDet 类声明与 BoxInfo 结果结构体 |
| nanodet_libtorch.cpp | 预处理、前向推理、解码、NMS 的完整实现 |
| main.cpp | 命令行入口,支持图片、摄像头、视频、基准测试四种模式 |
整体部署流程分三步:安装依赖 → 用 export_torchscript.py 把 .ckpt/.pth 权重导出为 TorchScript 文件 → 用 CMake 编译 C++ 工程并运行。核心思路是:Python 侧只负责把模型结构「固化」成一份与 Python 无关的序列化模型,后续所有推理全部由 LibTorch 在 C++ 中完成,不依赖任何 Python 环境。
二、安装依赖:CMake、OpenCV 与 LibTorch
README 明确指出,工程正常运行需要 OpenCV(图像读取、缩放、绘制)与 CMake(构建系统),另外还需自行下载 LibTorch 预编译包。
在 Ubuntu 上,可用包管理器一次性安装 CMake 与 OpenCV 开发库:
sudo apt install cmake libopencv-dev
LibTorch 需要单独下载:从 PyTorch 官方渠道获取与你的本地 PyTorch(Python 侧)版本匹配的 LibTorch 预编译包,解压后记录其绝对路径,稍后在 cmake 命令中通过 -DCMAKE_PREFIX_PATH 指定。从 CMakeLists.txt 可以看到,工程正是通过 find_package(OpenCV REQUIRED) 与 find_package(Torch REQUIRED) 来定位这两项依赖,并把 TORCH_CXX_FLAGS 追加进编译选项:
find_package(OpenCV REQUIRED)
find_package(Torch REQUIRED)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS}")
注意:LibTorch 的版本应尽量与导出 TorchScript 模型所用的 PyTorch 版本保持一致,否则
torch::jit::load加载时可能遇到算子或序列化格式兼容问题。这是所有 TorchScript 部署工程的通用前提,nanodet_libtorch.cpp 中的加载逻辑即是torch::jit::load(model_path)后调用Net.eval()。
三、模型导出:export_torchscript.py 详解
README 给出的导出命令骨架为:
python ./tools/export_torchscript.py --cfg_path ${CONFIG_PATH} --model_path ${PYTORCH_MODEL_PATH} --input_shape ${MO}
其中 ${MO} 是原文档中的占位写法,实际应传形如 416,416 或 320,320 的以逗号分隔的宽高。对照 tools/export_torchscript.py 的参数解析逻辑,完整参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--cfg_path |
无(必填) | 模型结构对应的 .yml 配置文件路径,如 config/nanodet-plus-m_416.yml |
--model_path |
cfg.save_dir/model_best/model_best.ckpt |
待转换的 PyTorch 权重文件(.ckpt 或 .pth) |
--out_path |
nanodet.torchscript.pth |
TorchScript 模型输出路径 |
--input_shape |
cfg.data.train.input_size |
模型输入尺寸,格式如 416,416;不传则回退到配置文件中的训练输入尺寸 |
一个可直接复制的完整示例:
python ./tools/export_torchscript.py \
--cfg_path config/nanodet-plus-m_416.yml \
--model_path /path/to/your/model_best.ckpt \
--out_path nanodet.torchscript.pth \
--input_shape 416,416
3.1 导出过程做了什么
导出脚本的核心逻辑在 main 函数 中,依次完成四件事:
- 构建模型并加载权重:
build_model(config.model)按配置搭建网络,load_model_weight(model, checkpoint, logger)载入权重。 - RepVGG 特殊处理:若配置文件中的 backbone 为
RepVGG,会重建一份deploy: True的部署模型,并调用 nanodet/model/backbone/repvgg.py 中的repvgg_det_model_convert完成结构重参数化(多分支卷积合并为单分支),从而显著降低部署时的计算量。普通骨干网络(如 CustomCSPGhostNet)则跳过此步。 - TorchScript 追踪(tracing):在
torch.no_grad()下构造1×3×H×W的全零 dummy 输入,用torch.jit.trace静态追踪得到计算图。 - 保存:
model_traced.save(output_path)落盘,控制台打印Finished export to TorchScript与Model saved to: ...。
3.2 导出产物与检测头输出的对应关系
理解导出产物,需要知道 NanoDet-Plus 检测头的前向输出格式。查看 nanodet_plus_head.py 的 forward:每个 stride 层级经过堆叠卷积后,由 gfl_cls(1×1 卷积)输出通道数为 num_classes + 4 × (reg_max + 1) 的特征,再 flatten 并按通道拼接,最终得到形状为 [batch, num_points, num_classes + 4×(reg_max+1)] 的张量。其中:
- 前
num_classes个通道是各类别分类分数; - 后
4×(reg_max+1)个通道是四方向(左、上、右、下)的离散分布预测,reg_max=7时每个方向有 8 个 bin,需经 softmax 与积分(见第四节)才能换算成距离。
C++ 侧的 detect 函数 正是按这一约定对输出张量做切分:Slice(0, num_class_) 得到 cls_preds,Slice(num_class_, None) 得到 box_preds。因此在自定义导出或换用不同 num_classes/reg_max 配置时,这两处必须与 Python 侧保持一致。
四、构建 LibTorch 工程
4.1 Linux 构建
README 给出的构建步骤:
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=/absolute/path/to/libtorch ..
make
-DCMAKE_PREFIX_PATH 必须指向 LibTorch 解压根目录(含 include、lib、share/cmake 等子目录的上级),CMake 才能通过 find_package(Torch) 找到它。编译产物为可执行文件 nanodet_demo。
CMakeLists.txt 中 add_executable(nanodet_demo main.cpp nanodet_libtorch.cpp) 将入口与推理实现编进同一可执行文件,并链接 ${TORCH_LIBRARIES} 与 ${OpenCV_LIBS}。
4.2 Windows 构建
工程对 MSVC 也做了支持:CMakeLists 末尾通过 file(GLOB TORCH_DLLS "${TORCH_INSTALL_PREFIX}/lib/*.dll") 收集 LibTorch 动态库,并在构建后自动把 DLL 拷贝到可执行文件所在目录(copy_if_different),避免运行时因缺少 DLL 而报错。Windows 上同样需将 -DCMAKE_PREFIX_PATH 指向 LibTorch 解压目录。
4.3 模型放置位置
入口 main.cpp 中模型路径硬编码为 "../model/nanodet.torchscript.pth"。若在 build/ 目录下运行,该相对路径指向仓库根目录的 model/nanodet.torchscript.pth,因此需要先创建 model 目录并把第三步导出的 TorchScript 文件放进去,或按需修改这行路径。
五、运行:四种演示模式
编译出的 nanodet_demo 需要两个参数:<a href="https://link.gitcode.com/i/effb0d9584133adb970af8e6778d37c1" target="_blank">mode] [path]。根据 [main 函数 的 switch 分支,四种模式如下:
| mode | 功能 | path 含义 |
|---|---|---|
0 |
摄像头实时检测(webcam) | 摄像头编号(cam id) |
1 |
图片批量检测 | 图片路径,支持 glob 通配,如 xxx/xxx/*.jpg |
2 |
视频检测 | 视频文件路径 |
3 |
性能基准测试 | 任意值(示例中传 0) |
示例:
# 图片检测(glob 批量)
./nanodet_demo 1 ./test_images/*.jpg
# 摄像头实时检测(编号 0)
./nanodet_demo 0 0
# 视频检测
./nanodet_demo 2 /path/to/video.mp4
# 基准测试
./nanodet_demo 3 0
每种模式默认以 score_threshold=0.4、nms_threshold=0.5 调用 detector.detect(...)(见 main.cpp 等处),并在检测后通过 draw_bboxes 在 OpenCV 窗口绘制带类别与置信度的检测框。main.cpp 内置了 COCO 80 类别的名称表(person、bicycle、car……),绘制时用类别下标取色、显示 类名 + 置信度百分比。
5.1 图片/视频的统一缩放预处理
为了让任意分辨率的输入适配模型固定输入 416×416,resize_uniform 实现了「等比缩放 + 居中填充」:按宽高比将原图缩放到目标尺寸内,剩余区域补 0,并记录实际有效区域 effect_roi。绘制检测框时,坐标要先减去 effect_roi 的偏移、再按原图与有效区域的宽高比换算回原图坐标系(见 draw_bboxes)。
5.2 基准测试模式
benchmark 以 warm_up=4 次预热、loop_num=10 次计时的方式,对 416×416 的纯色图重复调用 detect,输出最小/最大/平均单帧耗时(毫秒):
nanodet min = xx.xx max = xx.xx avg = xx.xx
该模式可用于快速验证部署后的实际推理延迟,且不依赖真实图像输入。
六、NanoDet 类的推理实现解析
NanoDet 类持有关键配置常量:strides_{8, 16, 32, 64}(四个下采样层级)、input_size_=416、num_class_=80、reg_max_=7。整体推理流水线在 nanodet_libtorch.cpp 中分为四步:
6.1 预处理 preprocess
见 preprocess:将 OpenCV 的 H×W×3 图像通过 torch::from_blob 零拷贝包装为张量,permute 转成 NCHW,转 float 后执行 -116.28、×0.017429 的减均值乘缩放归一化(对应旧版 NanoDet 训练时的全局统计量,代码中留有 TODO: mean std per channel 的注释,表示尚未按通道精细化)。注意: 如果你使用的是 NanoDet-Plus 系列配置,其训练归一化(通常为 ImageNet 风格 mean/std)可能与 116.28 不一致,需要按所用配置核对并在该函数中调整,否则检测精度会受影响。
6.2 前向与输出切分
detect 中调用 Net.forward({input}) 得到 [1, N, C] 的输出,随后按 num_class_ 切出分类与框回归两部分,进入逐类别解码。
6.3 DFL 离散分布解码 disPred2Bbox
这是理解 NanoDet 边界框回归的关键。模型输出的不是直接的 ltrb 距离,而是每个方向上一个 reg_max+1=8 维的离散分布。C++ 侧在 disPred2Bbox 中:
- 对每个方向的 8 个 bin 做 softmax(数值稳定版,先减最大值);
- 按
dis += j * softmax[j]加权求和(即数学上的积分sum{P(y_i)·y_i}); - 结果乘以该层 stride,得到该方向距中心的距离;
- 由中心点
ct_x/ct_y = (x+0.5)·stride组合出xmin/ymin/xmax/ymax,并裁剪到输入尺寸内。
这一积分操作与 Python 侧 gfl_head.py 中的 Integral 模块 完全对应:Integral 用 torch.linspace(0, reg_max, reg_max+1) 注册权重向量,对 F.softmax 后的分布做 F.linear 加权求和,得到四方向距离。两侧实现殊途同归,可作为交叉验证。
6.4 逐层遍历与 NMS
decode_infer 按 strides_{8,16,32,64} 依次遍历四个特征层级,对每个网格点取类别分数最大值,大于阈值则解码入对应类别的结果集;特征图尺寸按 ceil(input_size / stride) 计算。最后对每个类别的结果单独执行基于面积的 IoU 抑制 nms:按分数降序排序,删除与其重叠度 ≥ NMS_THRESH 的低分框,汇总所有类别后返回 std::vector<BoxInfo>。
七、常见问题与调参建议
- 输出错乱/精度异常:优先核对
num_class_、reg_max_、strides_三个常量是否与导出所用配置文件一致。它们决定了输出张量的切分位置与解码方式,任何一处不匹配都会导致解析错误。 - 输入归一化不匹配:
preprocess中的均值/缩放为旧版默认值,使用 NanoDet-Plus 权重前请对照配置文件中的归一化参数修正,必要时改为按通道处理。 - LibTorch 版本不兼容:
torch::jit::load失败或算子缺失时,优先将 LibTorch 换成与 Python 侧 PyTorch 相同或更高的小版本。 - 模型路径问题:程序默认从
../model/nanodet.torchscript.pth加载,运行前确认模型已放置到位,或修改 main.cpp 中的路径。 - RepVGG 骨干导出:若使用 RepVGG 结构(如旧版 config/legacy_v0.x_configs/RepVGG/nanodet-RepVGG-A0_416.yml 所示配置),导出脚本会自动完成 deploy 模式转换,这一步是省不掉的,否则多分支结构在推理时会额外增加耗时。
- 输入尺寸一致性:
--input_shape与 C++ 侧input_size_(默认 416)以及resize_uniform的目标尺寸应保持一致,否则解码坐标将失去参照。
至此,从 tools/export_torchscript.py 的命令行导出,到 demo_libtorch 的 CMake 构建与四种运行模式,再到 DFL 解码与 NMS 的源码级原理,已经构成了一个完整可复用的 NanoDet C++ 部署参考实现。基于同一套 BoxInfo/NanoDet 结构,你还可以继续扩展为批量服务、视频流分析或嵌入式端推理程序。