旋转目标检测OBB：从YOLOv5原理到C++多相机部署-平芜编程栈

1. 旋转目标检测：从一个“坑爹”的需求说起

如果只是做普通的目标检测，YOLOv5 的生态足够成熟，轮不到 OBB 这个变体出来折腾。但现实里总有那么一类场景，水平框根本扛不住——无人机俯拍的密集停车场、遥感图像里的任意朝向船只、工业质检里方向随机的零部件、还有机械臂抓取时工件的倾斜摆位。这些场景里，物体本身是长条形的，角度五花八门，你用常规的 axis-aligned 矩形框去框，一个框里可能同时塞进好几个目标，IoU 计算出来全是乱的，NMS 一压，检测结果直接崩掉。这就是旋转目标检测必须入场的时候。

YOLOv5_obb 说白了，就是在 YOLOv5 的检测头上多加了一个角度参数，把原来 (x, y, w, h) 的水平框升级成 (x, y, w, h, angle) 的旋转框。但别小看这一个参数，它牵一发动全身——损失函数要改、NMS 要改、数据标注要改、部署层的解码逻辑更要改。而且一旦上了 C/C++ 部署，还要面对 ONNX 算子兼容、多相机并发调度这些破事。我当初踩了一圈坑之后，把整个链路打通跑稳，今天就把这套东西从原理到实操完整拆一遍。

这篇内容的受众，我默认是已经在用 YOLOv5 做检测、现在被旋转检测需求找上门的开发者。CUDA、OpenCV、ONNX Runtime 这些基础我就不从头科普了，但你不需要已经写过 OBB 的部署代码——我会把角度定义、坐标解码、旋转 NMS 这些最容易炸的点讲透，保证你能直接照着落地。

2. 核心拆解：角度定义、模型结构和损失函数里的暗坑

2.1 旋转框的表示方式，第一步就得统一口径

刚开始接触旋转检测的人，九成会在角度定义上栽跟头。不同框架对角度有两种截然不同的定义方式，我在实际工程里同时遇到过，必须先说清楚。

第一种是 OpenCV 风格，角度范围 [-90°, 0°)，表示长边与 x 轴正方向的夹角，w 永远对应长边，h 永远对应短边。第二种是长边 90° 制，角度范围 [-90°, 90°) 或 [-90°, 90°]，直接用角度表示长边旋转了多少。YOLOv5_obb 官方用的是接近长边定义的方式，角度范围是 [-90°, 0°]，但距离最近边定义和长边定义在不同实现里还有细微差别。

我自己处理过一件特别典型的事。有一版模型从某个开源工具导出来，解码出来的框偶尔会突然转 90°，坐标看起来完全错位。后来排查发现是训练时用的角度定义和数据增强里旋转的角度范围对不上，图像旋转了 30°，标注框的角度值没有同步做归一化补偿。所以无论训练还是部署，第一步一定是把你的角度定义固定下来，并且在解码代码里写清楚注释，别靠脑子记。

2.2 模型结构差异：检测头的输出通道数变了

YOLOv5_obb 的 backbone 和 neck 跟原版 YOLOv5 基本一致，核心变化在检测头。普通 YOLOv5 每个 anchor 输出 5 + num_classes 个值，其中 5 是 x、y、w、h、objectness。OBB 版本每个 anchor 输出 6 + num_classes 个值，多的那一个就是 angle。所以如果你从零开始修改模型结构，输出通道要从(num_classes + 5) * anchor_num改成(num_classes + 6) * anchor_num。

这个改动看起来不大，但后续每一步都要跟着变。训练时的损失函数需要额外计算角度损失，我常用的做法是 Smooth L1 配合角度周期归一化。部署时解码层要严格按照新的通道顺序来拆分 tensor，不能沿用水平框的索引逻辑。

还有一个点容易被忽略——OBB 模型的 anchor 本身不需要变，但匹配正样本的策略会受影响。因为旋转框之间的 IoU 计算方式变成了旋转 IoU（Skew IoU），两个旋转框的相交多边形需要做多边形裁剪才能算面积。这个计算量比水平框大得多，训练时如果开启在线难例挖掘或者多尺度训练，速度会明显下降。

2.3 损失函数里的角度连续性问题

角度回归最大的坑在于角度的周期性。89° 和 -89° 从数值上看差了 178°，但在物理空间里其实只差 2°。如果直接算 Smooth L1 损失，模型会被这种“假大误差”带偏，训练很难收敛。

常见的处理方式有三种。第一种是把角度预测改成分类问题，把 [-90°, 90°) 离散成 180 个 bin，用 CE Loss 训练，但这样精度受 bin 大小限制。第二种是用环形平滑标签（Circular Smooth Label），把角度误差映射到周期性平滑的分布上，YOLOv5_obb 官方实现用的就是这个思路。第三种是预测两个正交向量然后归一化，用向量的反正切还原角度，相当于先把角度问题转成回归两个无周期性的数值。

我实际工程里更偏向第二种方案，因为它是官方推荐的，调起来资料多，坑相对少。但需要注意，CSL 的半径参数要跟着数据集角度分布调，如果半径太大，相近角度的类别会混在一起，导致角度预测模糊。我之前在一批车牌识别数据上发现角度偏差普遍在 5° 左右，后来把 CSL 半径从 6 调到 3，角度误差直接降了将近一半。

2.4 数据标注和增强的连锁反应

旋转目标检测的数据标注工具需要支持旋转框，常见的有基于多边形标注后转旋转框、直接用中心点加长宽加角度标注。无论哪种，都要保证导出格式和你的角度定义一致。我遇到过标注工具导出的是四点坐标，而模型要的是中心点加角度，这里就需要做坐标转换。

数据增强同样是个大坑。普通的随机裁剪、平移还好，但随机旋转和随机缩放会直接改变框的角度值和长宽比。你必须保证增强后的框重新计算角度，并且在解码时用同样的变换参数去还原坐标。很多开源的 OBB 训练代码在这里写过 bug——训练集增强后角度分布变了，模型在验证集上指标看着还行，部署后一到特殊角度就漏检。这种问题特别隐蔽，排查起来要花很长时间。

3. C/C++ 部署环境搭建与模型转换

3.1 模型导出：ONNX 是必经之路，但不是终点

PyTorch 训练的模型跑 C++ 推理，最常规的路径是导出 ONNX，然后用 ONNX Runtime 或 TensorRT 加载。但 OBB 模型导出 ONNX 时有一些特有的坑。

第一个是角度相关算子的兼容性。模型里如果用到了 torch.atan2、torch.sin、torch.cos 这些算子，大部分 ONNX 导出版本都能转，但如果你用了自定义的旋转框解码层，或者训练代码里有些 PyTorch 特有的操作没有注册 ONNX 导出支持，导出就会失败或者行为不一致。我建议导出前先做一遍输入输出对齐测试——用同一张图跑 PyTorch 推理和 ONNX Runtime 推理，对比解码后的框坐标、角度和置信度，最大误差控制在 CPU 浮点波动范围内，如果差很多，优先检查自定义算子。

第二个是动态形状。如果你的应用是多相机不同分辨率输入，模型导出时最好把输入维度设成动态，比如dynamic_axes={'images': {0: 'batch', 2: 'height', 3: 'width'}}。但动态形状在某些推理引擎上会触发额外的内存分配和算子优化失效，性能有损耗。我的做法是固定一个常驻分辨率，比如 640x640 或 1280x1280，多相机输入先做 Letterbox 再统一送入模型，这样兼顾了性能和部署稳定性。

3.2 推理引擎选型：ONNX Runtime 还是 TensorRT

这里没有绝对答案，完全取决于你的硬件和场景。

引擎	优点	缺点	适用场景
ONNX Runtime CPU	部署简单、跨平台、无 GPU 依赖	速度瓶颈明显，大模型 CPU 推理慢	原型验证、无 GPU 边缘设备
ONNX Runtime GPU	接入快，CUDA 加速开箱即用	相比 TensorRT 仍有优化空间	快速上线、GPU 服务器部署
TensorRT	推理速度极致、显存优化好	构建耗时、算子支持有限、调试困难	量产设备、性能要求苛刻
NCNN	移动端和嵌入式优化好	部分算子支持不完善	手机、开发板等 ARM 环境

我在多相机项目里最终选了 ONNX Runtime GPU 版本。原因有两条：一是我需要频繁迭代模型，TensorRT 每次换模型都要重新构建 engine，而 ONNX Runtime 直接加载 ONNX 文件就能跑；二是多相机并发的瓶颈主要在预处理和后处理线程的调度上，模型推理本身只占整个链路的一部分，ONNX Runtime 的 GPU 性能已经够用。

3.3 预处理细节：Letterbox 的参数要在训练和推理之间保持一致

预处理不一致是部署时最隐蔽的性能杀手之一。训练时你如果用了 640x640 输入，但做了随机缩放和随机裁剪，推理时却用固定的 Letterbox，那模型看到的尺寸分布完全不同，精度掉几个点是家常便饭。

我的标准做法是，训练时先用 Letterbox 把长边缩放到目标尺寸，同时记录缩放比例和填充偏移；推理时用完全相同的参数。关键代码就是把scale和pad值存下来，后处理还原坐标时要用它们把检测框映射回原图坐标。

多相机场景下，每路相机的输入尺寸如果不一样，预处理要分别计算缩放参数，不能图省事统一缩放，否则长宽比被拉伸，检测精度会严重下降。

4. 旋转解码与旋转 NMS 的实现与优化

4.1 解码层：从 cx, cy, w, h, angle 到四点坐标

模型输出的原始 tensor，需要经过 sigmoid 把 x、y、objectness 和 class scores 压到 (0,1) 区间，w、h 用 anchor 先验去解码，angle 则要根据训练时的定义还原成实际角度。这里的分步逻辑是：

把模型输出 reshape 成[batch, anchors, grid_h, grid_w, 6 + num_classes]
通过 sigmoid 处理 x、y、obj、cls
用 anchor 和 stride 把 (x, y) 还原到输入图像像素坐标
把 w、h 通过指数或者乘 anchor 的方式还原到像素尺寸
直接把 angle 从模型输出映射到实际角度范围
用cv::minAreaRect的思路把中心点、长宽、角度转成带角度的旋转矩形

还原坐标时有一个特别容易写错的点——解码后的 w、h 一定是原始像素单位，不是归一化坐标。后处理阶段如果直接拿解码结果做 NMS，OK；但如果要叠加到原图上，必须用之前算的 Letterbox 缩放参数反向映射。

4.2 一个能跑的旋转 NMS，比你想的复杂一点

旋转 NMS 和普通 NMS 的核心差异在于 IoU 计算。水平框 IoU 用矩形交集面积除以并集面积就行，两个旋转矩形的交集是两个任意多边形，需要先计算交点，再求多边形面积。

我当时看到网上有些实现直接用 OpenCV 的cv::rotatedRectangleIntersection，它返回交集点集和一个交集类型枚举，再用cv::contourArea算面积。这个方案能用，但在 CUDA 上跑不了，因为 OpenCV 的 GPU 模块不提供这个接口。

如果你需要 GPU 上的旋转 NMS，有两类路线。一类是近似法，把旋转框先转成外接水平框或者旋转后的轴对齐框，再用普通 NMS，但精度损失明显。另一类是在 CUDA kernel 里手动实现旋转矩形求交，计算所有顶点之间的交点，再用凸多边形面积公式求交集面积。后者代码量大，但它是唯一能在高帧率多路视频流场景里撑住的做法。

我第一版在 CPU 上用 OpenCV 实现了旋转 NMS，单路 640x640 输入、目标数量 40 个左右，NMS 本身耗了 12ms，整条链路加上推理要 45ms，勉强能跑。后来改成自定义 CUDA kernel，目标数量在 100 个时，NMS 耗时压缩到 2ms 以内，总延迟才有余量分配给多相机调度。

4.3 类别过滤与 TopK 剪枝的工程优化

旋转 NMS 因为 IoU 计算贵，特别依赖输入数量。如果模型解码后输出几千个候选框，逐对算旋转 IoU，那即使 GPU 并行也会被内存和核函数调度拖垮。

工程上我做了三刀剪枝：

第一刀是置信度过滤。所有候选框先按 objectness 乘以 class score 得到最终置信度，低于阈值直接丢弃。OBB 场景我一般把阈值设在 0.25 到 0.4 之间，太低候选框太多，太高容易漏检。

第二刀是按类别分组。每个类别的候选框单独做 NMS，不同类别的框即使空间重叠也不互相抑制。这在目标密集场景特别关键，比如道路上并排的两辆车，类别相同但确实需要保留各自框。

第三刀是 TopK。按置信度排序，只取前 200 或 300 个候选框进入旋转 NMS。这一步在大分辨率输入下收益巨大，因为大部分低置信度框根本不会进 NMS，对精度几乎没有影响。

这三刀做完，整条链路的耗时大头稳稳落在模型推理上，后处理基本不会成为瓶颈。

5. 多相机并发：架构设计和踩坑实录

5.1 线程模型怎么设计

多相机“同时检测”，核心不是把多路图像拼成一个 batch 送进模型，而是要做到各路视频流的采集、预处理、推理、后处理互不阻塞。我最开始踩过的坑，就是简单地开多个线程，每个线程独立做“取帧 -> 预处理 -> 推理 -> 后处理”，结果 GPU 推理被多个线程争抢，CUDA context 切换频繁，整体吞吐反而比单线程还低。

后来我优化成两级管线。第一级是采集线程，每个相机一个线程，只负责从相机拉帧、转成 RGB、推入环形缓冲区。第二级是处理线程池，从队列里取帧做预处理和推理。推理引擎内部维护 CUDA stream，多个推理请求可以通过 stream 并发提交，但必须避免同一个 stream 里的并发。

这个模型的峰值吞吐，我之前实测下来，三路 1080p 输入、每路 25fps，整条链路能在一台 2080Ti 上稳定跑，CPU 占用率大约是百分之六十左右，显存占用 3.5GB。如果相机数量继续增加到八路甚至更多，就需要引入批处理机制。

5.2 批处理调度：把多路帧拼成一个 batch

ONNX Runtime 和 TensorRT 都支持动态 batch。你在模型导出时把 batch 维度设为动态，然后在推理时把多路相机的帧拼成一个 batch，一次推理输出多路检测结果。这种方式能把 GPU 利用率拉满，但调度复杂度显著上升。

我的做法是设计一个批处理收集器。每个相机线程把预处理好的输入帧放入一个队列，后台线程每隔一个固定时间窗口（比如 10ms）或者收集满固定 batch size（比如 4 或 8）时，把所有帧拼成一个[batch, 3, H, W]的输入，一次推理，然后按 batch 索引把结果拆回各路相机。

要注意的是，batch 内每帧如果分辨率不同，无法直接拼接。所以要么你强制所有相机统一到相同分辨率，要么在拼 batch 之前都先做 Letterbox 到统一尺寸。另一个细节是 batch 里如果某路相机暂时没有新帧，不能一直等，否则会阻塞其他路。我的策略是设置超时时间，超时后有多少帧就拼多少帧，哪怕 batch 不满也直接推理。

5.3 同步与异步的取舍

多相机链路的每路相机，输出结果的顺序可能不一样。有的相机帧率 30fps，有的只有 15fps，如果后处理结果直接推给下游，下游可能因为时序问题出现乱序。

如果是做实时画面叠加显示，乱序问题不大，因为每一帧画面和检测框都在同一个时刻刷新。但如果你把检测结果送给跟踪模块或者 PLC 做控制，就一定要给每个结果打上时间戳，并且按时间戳对齐。这就要求你在解码层多做一步：记录每路相机每一帧的时间戳，推理结果与时间戳绑定，后处理完成后送入一个按时间戳排序的输出队列。

这个排序逻辑看起来不起眼，但我真在项目里遇到过——两路相机画面里同一个目标，因为处理延时不同，跟踪模块把同一个目标当成两个目标，轨迹断裂。加了时间戳对齐之后问题马上消失。

5.4 多相机场景实测：不同硬件的表现差异

我在两种硬件上跑过同一套代码。一台是桌面级 GPU，2080Ti，三路 1080p，模型是 YOLOv5s_obb，单 batch 推理耗时大约 8ms，整条链路平均延迟 25ms 左右。另一台是嵌入式设备，用的是集显和 CPU 模式，模型换成 YOLOv5n_obb，单 batch 推理耗时飙升到 45ms，三路并发时帧率掉到 12fps 左右，只能靠降低输入分辨率和限制候选框数量来撑。

结论很直接：多相机并发的瓶颈大部分时候不是模型本身，而是内存带宽和预处理/后处理开销。你在嵌入式设备上跑多相机，最有效的优化不是换更强的模型，而是降分辨率、降帧率、限制 NMS 候选框数量，三个维度一起调。

6. 全程实战：从 ONNX 导出到 C++ 多相机推理的落地步骤

6.1 模型转换工作流

我的建议是建立一个可复现的转换脚本封装。每次模型更新，只需要替换 PyTorch 权重文件，执行一条命令就能生成优化后的 ONNX 和配置文件，避免手动操作带来的疏漏。

# 导出 ONNX，设置动态 batch python export.py --weights yolov5s_obb.pt --include onnx --dynamic # 用 ONNX Runtime 自带工具做图优化 python -m onnxruntime.transformers.optimizer --input yolov5s_obb.onnx --output yolov5s_obb_opt.onnx --model_type bert

后者虽然是为 NLP 模型设计的优化器，但很多通用图优化规则对检测模型同样有效，实测偶尔能带来 5% 到 10% 的延迟下降。效果因图而异，建议尝试。

6.2 C++ 代码骨架：一个低耦合的推理器

我习惯把推理逻辑封装成一个类，对外只暴露三个接口：初始化、推理、释放。多相机线程只需要调用推理接口，内部自动处理预处理、推理、后处理。下面是核心骨架，你可以直接套进自己的项目：

class RotatedDetector { public: RotatedDetector(const std::string& model_path, int input_size); ~RotatedDetector(); // 输入是 cv::Mat RGB 图像，输出是旋转检测框列表 std::vector<RotatedBox> Detect(const cv::Mat& image, float conf_thres, float nms_thres); private: Ort::Session session_; int input_size_; float scale_; // Letterbox 缩放比例 int pad_w_, pad_h_; // Letterbox 填充偏移 cv::Mat Preprocess(const cv::Mat& image); std::vector<RotatedBox> Postprocess(const std::vector<float>& output, int num_anchors, int grid_h, int grid_w); };

这里的RotatedBox我是自定义的，包含 cx、cy、w、h、angle、score、label 七个字段。预处理和后处理都在类内部完成，多线程调用时只需要做好互斥保护。

6.3 解码和旋转 NMS 的完整实现逻辑

解码部分，我直接给出可运行的逻辑伪代码，核心思想是用 anchor 还原位置。

std::vector<RotatedBox> DecodeOutput( const float* data, int num_anchors, int grid_h, int grid_w, const std::vector<float>& anchors, int stride, float scale, int pad_w, int pad_h, float conf_thres) { std::vector<RotatedBox> boxes; int num_classes = 80; // 实际按模型配置 for (int a = 0; a < num_anchors; a++) { for (int i = 0; i < grid_h; i++) { for (int j = 0; j < grid_w; j++) { int offset = ((a * grid_h + i) * grid_w + j) * (6 + num_classes); float obj_conf = Sigmoid(data[offset + 4]); float max_cls = 0.0f; int best_cls = -1; for (int c = 0; c < num_classes; c++) { float cls_conf = Sigmoid(data[offset + 6 + c]); if (cls_conf > max_cls) { max_cls = cls_conf; best_cls = c; } } float final_conf = obj_conf * max_cls; if (final_conf < conf_thres) continue; RotatedBox box; box.cx = (Sigmoid(data[offset + 0]) * 2.0f - 0.5f + j) * stride; box.cy = (Sigmoid(data[offset + 1]) * 2.0f - 0.5f + i) * stride; box.w = powf(Sigmoid(data[offset + 2]) * 2.0f, 2.0f) * anchors[a * 2]; box.h = powf(Sigmoid(data[offset + 3]) * 2.0f, 2.0f) * anchors[a * 2 + 1]; box.angle = data[offset + 5]; // 根据训练定义范围做映射 box.score = final_conf; box.label = best_cls; // 还原到原图坐标 box.cx = (box.cx - pad_w) / scale; box.cy = (box.cy - pad_h) / scale; box.w /= scale; box.h /= scale; boxes.push_back(box); } } } return boxes; }

旋转 NMS 我用cv::rotatedRectangleIntersection或者自定义 CUDA kernel 两种方案。CPU 版本可以直接用 OpenCV：

cv::RotatedRect BoxToRotatedRect(const RotatedBox& box) { return cv::RotatedRect(cv::Point2f(box.cx, box.cy), cv::Size2f(box.w, box.h), box.angle); } float RotatedIoU(const RotatedBox& a, const RotatedBox& b) { cv::RotatedRect ra = BoxToRotatedRect(a); cv::RotatedRect rb = BoxToRotatedRect(b); cv::Point2f inter_pts[24]; int intersect_type; cv::rotatedRectangleIntersection(ra, rb, inter_pts, intersect_type); if (intersect_type == cv::INTERSECT_NONE) return 0.0f; float inter_area = cv::contourArea(cv::Mat(inter_pts)); // 注意只取有效点数 float union_area = ra.size.area() + rb.size.area() - inter_area; return inter_area / union_area; }

如果目标数量特别多，建议换成 GPU 版本的旋转 NMS。但初期先用 CPU 验证逻辑正确性，再切 GPU 优化，是一条降低调试成本的好路径。

7. 性能调优：让多相机推理跑得更稳更快的 5 个维度

7.1 输入分辨率与模型大小的匹配

OBB 模型的输入分辨率直接影响角度预测精度和真实框回归精度。我试过 640x640 和 1280x1280 两个配置，在同一批遥感数据集上，后者 mAP 大约能提升 4 到 6 个点，但推理耗时翻倍都不止。多相机场景不建议盲目上大分辨率，除非你的硬件确实有余量。

最佳实践是：先用 640x640 跑通整条链路，确认没有逻辑问题后，再根据帧率和延迟要求逐级调高分辨率。如果分辨率必须很高，同时还要多路并发，就考虑批处理 + TensorRT 的组合，否则 CPU 后处理会成为压垮系统的最后一根稻草。

7.2 线程池与 CPU 亲和性

ONNX Runtime 的 CPU 推理模式支持配置线程数。我一般把线程数设为实际物理核心数的一半，给预处理和后处理留出空间。GPU 推理模式下，线程数影响不大，但 CPU 亲和性设置可以减少 cache miss。

C++ 里可以用平台 API 设置线程亲和性，Windows 用SetThreadAffinityMask，Linux 用pthread_setaffinity_np。实测下来，绑定核心能减少约 10% 到 15% 的抖动，尤其在多路视频解码和多路检测线程同时运行的场景下效果更明显。

7.3 显存复用和内存池

多相机并发时，每路相机都在做预处理、推理、后处理，中间产生的临时缓冲区如果不复用，内存分配和释放会成为隐藏的瓶颈。我建议把所有固定尺寸的中间 buffer 在初始化阶段一次性分配，后续循环复用。比如输入图像预处理后的 buffer、模型输出 tensor 的 buffer、旋转 NMS 的交点数组，全部在初始化时分配好，避免每帧动态申请。

这里有一个很常见的细节：ONNX Runtime 的输入输出 tensor 每次推理都要封装Ort::Value，如果每次都从原数据拷贝一份，开销会积累。正确做法是用Ort::Value直接封装你已有的内存地址，通过Ort::MemoryInfo指定设备，避免不必要的内存拷贝。

7.4 CUDA Stream 并行处理

如果使用 GPU 推理，不要把多路相机的推理请求丢进同一个 CUDA stream。每路相机分配独立的 CUDA stream，推理请求通过 stream 并发提交，GPU 硬件调度器会把它们重叠执行，提升吞吐。ONNX Runtime 支持指定 stream 的接口，设置好之后可以明显减少排队时间。

我之前三路并发时，把所有请求丢到默认 stream，GPU 利用率只有百分之四十。改成每路相机一个 stream 后，利用率直接冲到百分之八十，整体吞吐提升了接近一半。这个优化性价比极高，而且代码改动非常小。

7.5 频率控制与丢帧策略

多相机检测不一定要每帧都做。很多场景下 15fps 或 10fps 就够用了，过高的检测频率只会白白消耗算力。我的做法是在采集线程做抽帧，比如相机输出 30fps，检测只做 15fps，隔一帧丢一帧。这样系统负载直接减半，但用户体验几乎无感。

如果某一时刻系统过载，不能无限积压帧队列，否则延迟会越攒越大，最后产生雪崩。我的策略是给每路相机的输入队列设定最大长度，比如 5 帧，满了就丢最老的帧，始终保持检测处理的是最新画面。这个“丢老保新”策略在实时监控场景几乎总是最优解。

8. 踩坑实录：角度错乱、乱框、性能塌方，这些我都遇到过

8.1 角度定义不一致导致的“框突然转 90 度”

这是我被坑得最惨的一次。训练好的模型，在 PyTorch 推理时一切正常，部署到 ONNX Runtime 后，一部分检测框的角度突然偏了 90 度。排查了很久，最后发现是训练代码在导出 ONNX 时，有一处自定义的 angle 解码逻辑没有跟随导出，导致 ONNX 图的输出和 PyTorch 原模型的行为不一致。

解决办法是，导出 ONNX 之后，一定要做一次“同图对比测试”：用同一张输入图分别跑 PyTorch 和 ONNX Runtime，把角度输出逐框对比。如果偏差超过 1°，基本可以确定是导出环节的问题。这个测试应该写进你的模型发布流程，每次换模型都必须跑一遍，我当时就是偷懒没跑，结果在客户现场被问题追着跑了两天。

8.2 旋转 NMS 的 IoU 计算分子分母写反

旋转 NMS 里 IoU 计算的常见 bug 是交集面积和并集面积算错。OpenCV 的cv::rotatedRectangleIntersection返回值里，inter_pts只有在INTERSECT_FULL或INTERSECT_PARTIAL情况下才有效，如果是INTERSECT_NONE直接返回 0。有人在INTERSECT_FULL时继续算contourArea，其实 FULL 时交集就是较小的那个框，面积可以直接取。但更隐蔽的问题是传入contourArea的点集必须是你用相交计算出来的有效点，如果传入包含无效点位的数组，面积会算错，NMS 表现就是一团乱麻。

我的建议是单独写一个单元测试，输入两个已知重叠比例的旋转矩形，验证 IoU 输出是否符合预期。这个测试代码十几行，但能救你后面至少一个通宵。

8.3 角度范围映射错误

训练时角度范围如果是 [-90°, 0°)，模型输出的原始值经过 sigmoid 或者线性映射后，要准确还原到这个范围。很多人在这一步直接写成angle = data[5] * 180，但模型输出根本没有归一化到 [-90, 0]，导致所有角度偏移。

我的做法是，导出模型前就在 PyTorch 里加一层角度映射作为模型的一部分，或者至少用一个明确的类封装角度转换。这样 ONNX 图里的输出就和训练时的定义完全对齐，部署端拿到的就是最终角度值，不需要再做范围变换，从根源上消除映射分歧。

8.4 显存泄漏：C++ 推理的隐形杀手

ONNX Runtime 的 C++ API 用起来相对直观，但每一步Ort::Value的创建、session.Run()的调用、tensor 的释放，如果管理不当，长时间跑多相机流会出现显存逐步增长。最典型的场景是：每次推理都创建一个新的输入Ort::Value，旧的不释放，显存被悄悄蚕食。

解决办法是把输入输出 tensor 的 buffer 全部复用，固定生命周期。我采用了对象池模式，初始化时创建 N 个Ort::Value，推理时从池里取，完事归还。跑两天两夜，显存占用纹丝不动，这几乎是多相机场景必须的优化。

8.5 CPU 后处理卡顿到影响视频流

旋转 NMS 如果候选框特别多，CPU 后处理会抢走大量算力，导致视频解码线程卡顿，画面出现撕裂。我的处理方案是把后处理也放到独立的线程池，并且跟采集、推理线程做优先级隔离。后处理线程不会阻塞相机采集，相机采集永远保持实时性，检测结果晚几毫秒到达下游是允许的。

实测下来，三路 1080p 相机，每路 25fps，后处理线程池设 4 个线程，CPU 占用率在百分之二十左右，整机依然能跑其他业务，没有掉链子。

9. 常见问题速查表与调试建议

现象	可能原因	排查方法
框的角度整体偏移 90 度	角度定义不一致	对比 PyTorch 与 ONNX 输出
个别框角度跳动很大	角度周期性处理缺失	检查 CSL 半径或角度归一化
NMS 后框大量重叠	旋转 IoU 计算错误	单元测试旋转 IoU 函数
多路相机只有一路有结果	批处理调度逻辑 bug	检查队列等待超时逻辑
长时间运行显存上涨	tensor 未释放或未复用	使用对象池复用 Ort::Value
帧率越低延迟越大	队列积压、丢帧策略缺失	设置最大队列长度并丢老帧
GPU 利用率低	多路请求共用一个 stream	每路相机独立 CUDA stream
小目标检测不到	输入分辨率不够	提高输入尺寸或使用更大模型

遇到任何诡异问题，第一件事永远是缩小范围——用单路相机、单帧图像、固定模型权重，逐步关掉并发和优化逻辑，确定问题出在哪一层，再针对性处理。多相机系统出 bug 最忌讳的就是在完整系统里凭感觉猜，八成会猜错。

最后说点实在的

我踩过最多的坑，从来不是模型本身，而是从 PyTorch 训练到 C++ 部署这中间的每一个“看起来小事一桩”的环节。角度定义差一点点，旋转 NMS 慢一点点，内存泄漏一点点，多路并发抖一点点，凑在一起就是线上事故。这套链路我做过三遍才彻底摸透，最想分享的经验只有一句话：每个环节都要留验证手段，不要相信任何一步“应该没问题”。

多相机 + 旋转目标检测的 C/C++ 部署，做到能稳定跑起来并不难，难的是在性能和稳定性上同时达标。如果你正在被 OBB 部署折磨，希望这篇能把问题拆解得够细，让你少熬几个夜。有问题直接在下面评论区交流，我看到了就会回。