# infer

**Repository Path**: dfhhdq/infer

## Basic Information

- **Project Name**: infer
- **Description**: python 版本的推理端程序，与c++ 的对应
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# infer

基于 ONNX Runtime / TensorRT 的 YOLO 推理引擎,支持 7 种检测任务
(Detect / Pose / Segment / Obb / MasterDetect / RfDetrDetect / RfDetrSegment),
附带人员入侵检测 Demo。

## 目录结构

```
infer/
├── infer/                      # 架构代码包
│   ├── core.py                 # ModelWrapper 基类(ONNX / TensorRT 双后端,动态模型)
│   ├── tools/                  # preprocess / postprocess / draw / env / logger
│   └── yolo/                   # 7 种检测类型的 wrapper(detect/pose/segment/obb/master/rfdetr×2)
├── test/
│   ├── test_interface/         # 接口测试(config 驱动:7 任务 × 17 图 × 4 变体)
│   └── test_algo/              # 业务逻辑测试(入侵检测 Demo)
├── scripts/                    # 排查脚本(跨任务交叉验证 / C++ 对比 / probe_models.py)
├── config/                     # 测试配置 test_config.json(仿 Interface_AI)
├── intrusion_detector.py       # 业务算法:人员入侵检测(暂留根目录)
├── data/                       # test/ 原图(git 跟踪),res/ 推理结果输出(git 忽略)
└── model/                      # static/ dynamic/ 为 junction → 参考项目(git 忽略)
```

## 安装与运行

```bash
uv sync
uv run --no-sync python test/test_interface/test_engines.py   # 全量验证(config 驱动,4 变体)
uv run --no-sync python test/test_algo/test_intrusion.py       # 入侵检测 Demo
```

> 清华镜像 403 时 `uv run` 构建会失败,用 `--no-sync` 跳过。机器相关路径
> (TRT 运行库/trtexec)放 `.env`(模板 `.env.example`),代码内 `load_dotenv()` 加载。

## 输出格式(与 Interface_AI DataStruct.h 对应)

| 任务 | 输出 tuple | 附加项 |
|---|---|---|
| Detect / Master / RfDetrDetect | `(x, y, w, h, class_id, score)` | — |
| Pose | `(x, y, w, h, class_id, score, kpts)` | kpts: 17 个 `(x, y, conf)` |
| Obb | `(x, y, w, h, class_id, score, rot)` | rot: `(cx, cy, w, h, angle_deg)` |
| Segment / RfDetrSegment | `(x, y, w, h, class_id, score, mask)` | mask: 原图尺寸 bool 数组 |

`(x, y, w, h)` 为框**中心点 + 宽高**(obb 为旋转框外接矩形)。

> ⚠️ **画框约定**:画框必须转左上角 `(cx-w/2, cy-h/2)`。曾发生把中心点当
> 左上角绘制、结果图框整体偏移半个身位(mask 正确、框错误)的 bug,已修复。

## 测试

| 脚本 | 覆盖 |
|---|---|
| `test_engines.py` | **唯一测试入口**,按 `config/test_config.json` 驱动:7 任务 × 全部 17 图 × 4 变体(onnx 静态/动态 + engine 静态/动态),357 项对比;输出全部结果图(476 张) |
| `test_dynamic.py` | 动态 onnx batch=1/2、动态 engine batch=2 一致性 |
| `scripts/test_one_image.py` | 排查脚本:指定图全任务验证 + **跨任务交叉验证**(detect/pose/segment 框应互相重合) |
| `scripts/test_compare_cpp.py` | 排查脚本:与 C++ 端(test_interface_ai.exe)逐框对比,102/102 OK |

输出命名:`变体_任务_图名`(如 `engine_static_detect_giraffe.jpg`;变体 =
`onnx_static` / `onnx_dynamic` / `engine_static` / `engine_dynamic`)。

配置项(仿 Interface_AI):每个测试组 = `task` + `enabled` + `engine`(模型文件,
onnx/engine 自动识别,`_static`/`_dynamic` 区分静动态)+ `image`(文件或文件夹)+ `batch`。
首个 onnx 变体为基准,其余变体与之对比。

### 对比容差(坑点速查)

- **fp16 噪声**:engine vs onnx 的 score 差 ~0.01-0.04,阈值(0.5)边缘框可能
  差 1 个,容忍 ±0.05;坐标容忍 <5px
- **C++ 端**:打印坐标 1 位小数(容忍 2px);static/dynamic engine 间有 ~1px 固有差异
- **RF-DETR 无 NMS**:同一物体可能多 query 命中 + 低置信度误检,是模型特性
- **跨任务交叉验证**:同图同人 detect/segment 框重合 0.0px、vs pose 2.8px,
  发现"框不对"先与同族任务对比,定位是推理还是画图问题

## 使用接口

```python
from infer import YOLOv11Wrapper, draw_boxes

model = YOLOv11Wrapper("model/static/yolo11m.onnx", confidence=0.5)
results = model.run(image)      # [(cx, cy, w, h, class_id, score), ...], 原图坐标
```

## 模型

```
model/
  ├─ static/    # 7 任务静态模型:*.onnx + *_static.engine
  ├─ dynamic/   # 7 任务动态模型:*.onnx + *_dynamic.engine
  ├─ person.onnx / person.engine    # 入侵检测 Demo 用
  └─ mechanical_v22.engine          # 预留
```

`static/`、`dynamic/` 是 junction → 参考项目 `Interface_AI\models\test\`(模型不拷贝,
参考项目更新自动同步)。重建:

```powershell
cmd /c mklink /J model\static  E:\00__demo\00__cxx\03_hh\Interface_AI\models\test\static
cmd /c mklink /J model\dynamic E:\00__demo\00__cxx\03_hh\Interface_AI\models\test\dynamic
```

trtexec 转换:`trtexec.exe --onnx=xxx.onnx --saveEngine=xxx.engine`(路径见 `.env` 的 `TRTEXEC_PATH`)。

## 扩展新检测类型

在 `infer/yolo/` 新增独立文件,继承 `ModelWrapper` 实现 `preprocess`/`postprocess`,
在 `infer/__init__.py` 导出;不修改其他检测类型文件。

详细约定与坑点见 [handoff.md](handoff.md)。