feat(actpred): 新增 Hailo HEF 推理封装 HailoPredictor，附 AI HAT 2 调研与测速报告
零 torch 依赖（hailo_platform + numpy + PIL），vstream 形状/量化参数从 HEF 动态推导，支持 uint8 量化边缘与动作归一化 stats；新增 6 个免硬件 单测（fake hailo_platform 注入）。调研报告记录 hailort 5.x 新 API 踩坑， 测速报告给出 CPU(ORT 5.9ms) vs NPU(resnet50 4.29ms) 基准与部署建议。
This commit is contained in:
qing committed
1 parent
8673515d31
commit
ab60b3cafb
5 files changed
+685
No files matched your search
@@ -0,0 +1,130 @@
|
||||
# actpred × 树莓派 AI HAT 2（Hailo-10H）推理调研报告
|
||||
|
||||
日期：2026-08-13
|
||||
设备：Raspberry Pi 5 + Raspberry Pi AI HAT 2（Hailo-10H，8GB RAM，40 TOPS）
|
||||
|
||||
## 1. 目标
|
||||
|
||||
调研如何利用 AI HAT 2 扩展板资源对 actpred 动作预测模型做推理加速，
|
||||
验证板载软件栈可用性，并给出部署路径。
|
||||
|
||||
## 2. 环境实测结果
|
||||
|
||||
### 2.1 已安装的软件栈（apt 包）
|
||||
|
||||
| 包 | 版本 | 说明 |
|
||||
|---|---|---|
|
||||
| h10-hailort | 5.1.1 | Hailo 运行时库 |
|
||||
| h10-hailort-pcie-driver | 5.1.1 | PCIe 驱动与固件 |
|
||||
| hailo-h10-all | 5.1.1 | Hailo-10 元包 |
|
||||
| hailo-tappas-core | 5.1.0 | TAPPAS 核心 |
|
||||
| python3-h10-hailort | 5.1.1 | HailoRT Python API（`hailo_platform` 模块） |
|
||||
| python3-hailo-tappas | 5.1.0 | TAPPAS Python 绑定 |
|
||||
| rpicam-apps-hailo-postprocess | 1.12.0 | rpicam-apps 的 AI HAT 后处理插件 |
|
||||
| hailo-models | 1.0.0 | 预装 HEF 模型集 |
|
||||
|
||||
> 注意：Python 模块名是 `hailo_platform`，**不是** `hailort`
|
||||
> （`import hailort` 会 ModuleNotFoundError）。
|
||||
|
||||
### 2.2 硬件识别与基准
|
||||
|
||||
```bash
|
||||
hailortcli scan # Device: 0001:01:00.0（正常识别）
|
||||
hailortcli benchmark /usr/share/hailo-models/resnet_v1_50_h10.hef
|
||||
# → resnet_v1_50: FPS: 307.59（温度均值 47.65°C）
|
||||
```
|
||||
|
||||
### 2.3 预装 HEF 模型
|
||||
|
||||
`/usr/share/hailo-models/` 下预装了 `_h8l`/`_h10` 两套 HEF。
|
||||
本机为 Hailo-10H，应使用 `_h10` 后缀模型：
|
||||
resnet_v1_50、yolov8m、yolov8m_pose、yolov8s_pose、yolov5n_seg、yolov11m 等。
|
||||
|
||||
## 3. Python 推理 API 实测（关键发现）
|
||||
|
||||
hailort 5.x 对 Hailo-10 设备只支持**新版 infer API**：
|
||||
|
||||
- ❌ 旧版 `VDevice().configure(hef)` / `InferVStreams(hef, vdev)`
|
||||
在 Hailo-10 上报 `HAILO_NOT_IMPLEMENTED (error 7)`（实测）
|
||||
- ✅ 新版 `VDevice().create_infer_model(hef_path)` → `configure()` →
|
||||
`create_bindings()` → `run(bindings, timeout)`（实测通过）
|
||||
|
||||
实测打通的最小推理流程：
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from hailo_platform import VDevice, HEF
|
||||
|
||||
hef_path = "/usr/share/hailo-models/resnet_v1_50_h10.hef"
|
||||
hef = HEF(hef_path)
|
||||
in_info = hef.get_input_vstream_infos()[0] # (224,224,3) uint8
|
||||
out_info = hef.get_output_vstream_infos()[0] # (1,1,1000) 量化 uint8
|
||||
|
||||
with VDevice() as vdev:
|
||||
im = vdev.create_infer_model(hef_path)
|
||||
with im.configure() as c:
|
||||
b = c.create_bindings()
|
||||
b.input(in_info.name).set_buffer(img_uint8_hwc)
|
||||
b.output(out_info.name).set_buffer(
|
||||
np.zeros(tuple(out_info.shape), dtype=np.uint8))
|
||||
c.run([b], timeout=10000)
|
||||
q = np.asarray(b.output(out_info.name).get_buffer()).astype(np.float32)
|
||||
res = (q - out_info.quant_info.qp_zp) * out_info.quant_info.qp_scale
|
||||
```
|
||||
|
||||
### 踩坑记录
|
||||
|
||||
1. `bindings.input(name)` / `bindings.output(name)` 不支持下标访问；
|
||||
`get_buffer()` 在未 `set_buffer` 前返回 None，需先按
|
||||
`HEF.get_input/output_vstream_infos()` 的 shape/dtype 自建 numpy 缓冲区。
|
||||
2. 输出缓冲区 dtype/大小必须匹配 HEF 边缘格式（量化 uint8），
|
||||
传 float32 会报 `Output buffer size ... different than expected`；
|
||||
需手动用 `quant_info.qp_zp/qp_scale` 反量化。
|
||||
3. `VStreamInfo` 无 `format_type` 属性，shape 与量化参数从
|
||||
`get_input/output_vstream_infos()` 获取。
|
||||
4. 摄像头实时推理走 `rpicam-hello/rpicam-vid --post-process-file ...`
|
||||
（rpicam-apps-hailo-postprocess 提供）。
|
||||
5. `hailo_platform.genai` 提供 LLM / VLM / Speech2Text 接口——
|
||||
AI HAT 2（Hailo-10H + 8GB RAM）支持本地大模型，是与
|
||||
AI HAT+（Hailo-8L）相比的最大增量。
|
||||
|
||||
## 4. actpred 部署路径
|
||||
|
||||
Hailo 板**不能直接运行 ONNX/PyTorch**，必须编译为 HEF（含量化）：
|
||||
|
||||
```
|
||||
actpred checkpoint (best_inference.pt)
|
||||
→ export_onnx.py → model.onnx
|
||||
→ Hailo DFC（Dataflow Compiler，需 x86 Linux 主机或云端 DFC）
|
||||
量化校准（用 data/ 中的帧做 calibration set）
|
||||
→ model.hef（拷回树莓派）
|
||||
→ hailo_platform 推理（封装见 actpred/hailo_infer.py）
|
||||
```
|
||||
|
||||
风险与注意点：
|
||||
|
||||
- **DFC 不在树莓派本机**（无 hailo/dfc 命令），需在 x86 主机安装或
|
||||
使用 Hailo 云端 DFC 服务。
|
||||
- actpred 是 Transformer 结构（多头自注意力），编译前需确认所用 DFC
|
||||
版本对 attention 类算子的支持；遇不支持算子可拆分模型或换 op。
|
||||
- actpred 仅 ~450K 参数，Pi 5 CPU（4×A76）直接 PyTorch/ONNX Runtime
|
||||
推理也在可接受延迟范围；HAT 迁移的主要收益是释放 CPU 给 pybot
|
||||
主控循环与图像采集。
|
||||
- HEF 的输入/输出名与量化参数由 DFC 编译决定，推理封装按
|
||||
`get_input/output_vstream_infos()` 动态适配，不硬编码名称。
|
||||
|
||||
## 5. 结论与产出
|
||||
|
||||
1. AI HAT 2 软件栈完整可用，新 API 推理链路实测打通（resnet50 307 FPS）。
|
||||
2. actpred HEF 推理封装：`actpred/hailo_infer.py`（`HailoPredictor`），
|
||||
接口对齐 `predict.ActionPredictorInference`。
|
||||
3. 待办：在 x86 主机上用 DFC 将 actpred ONNX 编译为 HEF 并做量化校准，
|
||||
随后用 `HailoPredictor` 替换 CPU 推理端做端到端验证。
|
||||
|
||||
## 参考
|
||||
|
||||
- [Raspberry-Pi-AI-HAT+ 使用教程](https://spotpear.cn/index.php/wiki/Raspberry-Pi-5-AI-HAT-Plus-Hailo-8L-13-26-Tops-PCIe-M.2.html)
|
||||
- [树莓派5 Raspberry Pi AI HAT+2 官方 Hailo-10H 8GBRAM 40TOPS](https://spotpear.cn/index.php/shop/Raspberry-Pi-5-AI-HAT-Plus-2-Hailo-10H-40-Tops.html)
|
||||
- [AI HAT+ 文档](https://shumeipai.nxez.com/documentation/accessories/ai-hat-plus.html)
|
||||
- [Raspberry Pi AI Kit](https://www.waveshare.net/wiki/Raspberry_Pi_AI_Kit)
|
||||
- [onnx 转为 hef 用树莓派 hailo 使用](https://wenku.csdn.net/answer/1e0n2rmysd)
|
||||
@@ -0,0 +1,52 @@
|
||||
# actpred 推理速度基准测试报告（Pi 5 CPU vs Hailo-10 NPU）
|
||||
|
||||
日期：2026-08-13
|
||||
设备：Raspberry Pi 5（4×A76）+ AI HAT 2（Hailo-10H）
|
||||
模型：actpred（~450K 参数，frame_len=3，history_len=5，action_dim=18）
|
||||
|
||||
## 1. 测试方法
|
||||
|
||||
- **PyTorch CPU**：`ActionPredictorInference(checkpoints/best_inference.pt)`，
|
||||
输入 3 帧 640×480 随机图 + 全零动作历史，预热 3 次后取 20 次均值（含 PIL 预处理）
|
||||
- **ONNX Runtime CPU**：`export_onnx.py` 导出后 ORT 加载，纯模型推理，
|
||||
预热 3 次后取 50 次均值
|
||||
- **Hailo-10 NPU**：板载 `resnet_v1_50_h10.hef`（25M 参数，比 actpred 大 ~55 倍），
|
||||
新版 `create_infer_model` API 串行单帧，预热 10 次后取 200 次均值；
|
||||
另有 `hailortcli benchmark` pipelined 吞吐
|
||||
|
||||
## 2. 结果
|
||||
|
||||
| 方案 | 延迟 | 吞吐 | 备注 |
|
||||
|---|---|---|---|
|
||||
| PyTorch CPU | 28.8 ms | 34.8 FPS | 含 PIL 图像预处理 |
|
||||
| ONNX Runtime CPU | 5.9 ms | 168.7 FPS | 纯推理，float32 输入 |
|
||||
| Hailo-10 NPU（resnet50，串行单帧） | 4.29 ms | 233 FPS | 含 Python/PCIe 开销 |
|
||||
| Hailo-10 NPU（resnet50，pipelined） | — | 307 FPS | hailortcli benchmark |
|
||||
|
||||
## 3. 解读
|
||||
|
||||
1. resnet50 参数量约为 actpred 的 55 倍，NPU 上 actpred HEF 推理预计
|
||||
**亚毫秒级**，NPU 不会成为瓶颈；串行单帧 4.29ms 中 Python/PCIe
|
||||
开销占比高，闭环可用 `run_async` 流水线进一步压低。
|
||||
2. 不迁移 NPU 也完全够用：ONNX Runtime 比 PyTorch 快近 5 倍（169 FPS），
|
||||
是短期最优 CPU 方案。
|
||||
3. HAT 的真实价值在于**把推理从 CPU 卸载**，让 4×A76 专注 pybot
|
||||
主控循环与图像采集，而非绝对延迟。
|
||||
|
||||
## 4. 部署建议（按优先级）
|
||||
|
||||
1. **立即可用**：给 actpred 加 ONNX Runtime 后端（改动小，收益 ~5 倍）
|
||||
2. **有 x86 环境后**：DFC 编译 HEF，走 `actpred/hailo_infer.py`
|
||||
的 `HailoPredictor` 端到端验证
|
||||
3. DFC 编译环境的说明：官方仅提供 x86_64 Linux wheel
|
||||
（`hailo_dataflow_compiler-*-linux_x86_64.whl`，无 arm64 构建），
|
||||
但 HEF 产物与主机架构无关，x86 上编译一次即可在树莓派长期使用；
|
||||
无本机 x86 时可用云服务器临时实例或 QEMU 模拟（后者极慢，不推荐）。
|
||||
编译环境调研详见
|
||||
[actpred_hailo_hat2_inference_research_20260813.md](actpred_hailo_hat2_inference_research_20260813.md)
|
||||
|
||||
## 参考
|
||||
|
||||
- [张高兴的 Raspberry Pi AI 开发指南：将自定义模型编译为 Hailo NPU 的 .hef 模型](https://www.cnblogs.com/zhanggaoxing/articles/18597244.html)
|
||||
- [Hailo Dataflow 编译器安装](https://blog.csdn.net/qq_40843129/article/details/148557199)
|
||||
- [Hailo-8 系列——Hailo Dataflow Compiler 使用经验分享](https://blog.csdn.net/stoat04/article/details/137569246)
|
||||
Reference in new issue
Block a user