qing/blackbird
3
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(actpred): 更新 Hailo 部署文档与报告，清理过时引用

Browse Source 
- README: 部署工作流更新（224×224、pred-token-out、抖动校准、
  连通性检查），首版 HEF 输入不敏感警告改为修复清单，ONNX 测速
  数字更新为 224 实测
- hailo 调研报告：驱动 5.3.0、vstream 乱序踩坑、编译断连排查与
  修复表、重编译待办
- 测速报告：新增 §6 Pi 5 224×224 复测
- 清理已删除报告的 4 处失效引用（审计报告/迁移文档/项目画像）
This commit is contained in:
qing committed 2026-08-13 12:22:41 +08:00
1 parent 14964b9574
commit a6e1781185
7 files changed
+123 -44
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

actpred/README.md
+38 -14
View File
@@ -158,9 +158,10 @@ action = predictor.predict(images, action_history) # np.ndarray (action_dim,)
`onnx_infer.py` 的 `OnnxPredictor` 走 ONNX Runtime CPU 推理，接口与
`ActionPredictorInference` 对齐，维度从 ONNX 输入元数据自动推导（无需
checkpoint）。Pi 5 实测 12ms/次含预处理（纯推理 5.9ms），比 PyTorch 快 ~5 倍，
与 torch 前向输出差异 <1e-5。数据见
[测速报告](../docs/reports/actpred_inference_speed_benchmark_20260813.md)。
checkpoint）。Pi 5 实测（224×224，2026-08-13 复测）11.4ms/次含预处理
（纯推理 10.7ms），PyTorch 21ms，约 2 倍加速，与 torch 前向输出差异
<1e-5。数据见
[测速报告](../docs/reports/actpred_inference_speed_benchmark_20260813.md) §6。
```bash
bash _run.sh export --model checkpoints/best_inference.pt --output model.onnx
@@ -184,25 +185,48 @@ python3 onnx_infer.py --model model.onnx --images f1.jpg f2.jpg f3.jpg \
训练态 ONNX（5D 输入、AdaptiveAvgPool、MultiheadAttention 的 head
reshape）**无法被 DFC 解析**，必须用 `export_deploy.py` 的部署版导出
（按帧展开 CNN、固定 kernel AvgPool、注意力按头展开为独立 Linear、
全程 (1,1,S,d) 无 transpose 布局，权重数值不变）：
全程 (1,1,S,d) 无 transpose 布局，权重数值不变）。
当前 NPU 目标分辨率为 **224×224**（pretrain checkpoint 配置），HEF 输入
为 frame0~2 各 (1,224,224,3) NHWC + action_history (1,1,5,18) +
pred_token (1,1,1,128)，形状与量化参数由 `hailo_infer.py` 从 vstream
info 自动推导，不硬编码。
```bash
# x86 主机（venv_dfc 内已装 hailo-sdk 5.3）：
# 1. 导出部署版 ONNX（输入 frame0~2 + action_history + pred_token）
python3 export_deploy.py --model checkpoints/pretrain_best_inference.pt
# 2. 生成校准集（合成数据；真实 episode 到位后应替换）
python3 gen_calibration.py --deploy
# 3. 一键编译（parser → optimize → compiler）
# 1. 导出部署版 ONNX + 学习到的 pred_token（推理端喂入用）
python3 export_deploy.py --model checkpoints/pretrain_best_inference.pt \
--pred-token-out checkpoints/actpred_deploy_pred_token.npy
# 2. 生成校准集（pred_token 按学习值 ±30% 抖动，避免常量量化退化）
python3 gen_calibration.py --deploy --model checkpoints/pretrain_best_inference.pt
# 3. 一键编译（parser → optimize → compiler，各步自动做输入连通性检查）
python3 dfc_compile.py # 产物 checkpoints/actpred_pretrain.hef
# 4. 将 HEF 拷回树莓派
# 4. 将 HEF + actpred_deploy_pred_token.npy 拷回树莓派
```
已验证：完整 110 层网络（含 matmul/softmax/layernorm 注意力）解析、
量化、编译全部通过；HEF 1.8MB，4 contexts，hailo10h 目标。
量化、编译全部通过；hailo10h 目标。
编译要点与踩坑记录见 `dfc_compile.py` 文档字符串。
树莓派端 `hailo_infer.py` 的 `HailoPredictor` 尚需适配新的 5 输入
HEF（frame0~2 各 (1,64,64,3) NHWC、action_history (1,1,5,18)、
pred_token (1,1,1,128) 常量），输出 predicted_action (1,1,18)。
> **警告（2026-08-13 树莓派实测）**：首版 HEF 在 NPU 上**输出对全部
> 5 个输入均不敏感**（全 0 / 全 255 / 真实数据输出完全一致，对照
> resnet HEF 同 API 验证输入通道有效）。驱动升级 5.3.0 后复测依旧，
> 判定为 DFC 编译侧问题（输入在编译图中被断开/常量化），并非推理封装
> 问题。**该 HEF 不可用于推理**。已做如下修复，待 x86 重编译后复验：
> - `_onnx_validate.py`：编译前数值验证 `actpred_deploy.onnx` 输入
> 敏感性与 PyTorch 一致性（本次已 PASS，差异 1.5e-5）
> - `dfc_compile.py`：parser/optimize 后自动检查输入层连通性，断开即报错
> - `gen_calibration.py`：pred_token 常量校准退化（scale=18571.7，任何
> 输入都被量化成 0）已改抖动校准，推理端喂学习值（`--pred-token`）
> - `hailo_infer.py`：帧输入按 input_layerN 排序绑定（vstream 报告顺序
> 实测为 1,5,4,3,2，按报告顺序绑定会 frame1/frame2 错位）
>
> 重编译后用 `_npu_test.py` 做 4 角输入敏感性复验（6.3ms/次的封装
> 性能基线已在新驱动 5.3.0 下测通）。
`hailo_infer.py` 的 `HailoPredictor` 适配 5 输入 HEF，输入布局与量化
参数（含负零偏→ImageNet 归一化识别）从 vstream info 自动推导，单元测试
含 fake hailo_platform 的 5 输入与乱序报告顺序用例。CLI 支持
`--pred-token` 喂入学习值、`--stats` 喂入归一化统计。
环境调研与 API 踩坑记录见
[docs/reports/actpred_hailo_hat2_inference_research_20260813.md](../docs/reports/actpred_hailo_hat2_inference_research_20260813.md)。
docs/reports/actpred_hailo_hat2_inference_research_20260813.md
+62 -24
View File
@@ -1,6 +1,6 @@
# actpred × 树莓派 AI HAT 2（Hailo-10H）推理调研报告
日期：2026-08-13
日期：2026-08-13（同日更新：驱动升级 5.3.0 与 DFC 编译闭环踩坑，见 §5）
设备：Raspberry Pi 5 + Raspberry Pi AI HAT 2（Hailo-10H，8GB RAM，40 TOPS）
## 1. 目标
@@ -10,18 +10,14 @@
## 2. 环境实测结果
### 2.1 已安装的软件栈（apt 包）
### 2.1 软件栈（2026-08-13 已升级 hailort 5.3.0）
| 包 | 版本 | 说明 |
| 组件 | 版本 | 说明 |
|---|---|---|
| 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 模型集 |
| hailort（运行时 + PCIe 驱动） | 5.3.0 | apt 包 h10-hailort* 5.1.1 → 升级 5.3.0（含固件） |
| 固件 | 5.3.0 | `hailortcli fw-control identify` 确认 |
| Python API | 5.3.0 | actpred venv 内 pip 安装 `hailort-5.3.0-cp313`（模块名 `hailo_platform`） |
| DFC（Dataflow Compiler） | 5.3 | 仅 x86 Linux，运行于 `venv_dfc` |
> 注意：Python 模块名是 `hailo_platform`，**不是** `hailort`
> （`import hailort` 会 ModuleNotFoundError）。
@@ -31,7 +27,7 @@
```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）
# → resnet_v1_50: FPS: 307.70（驱动 5.3.0 复测，温度均值 46.7°C）
```
### 2.3 预装 HEF 模型
@@ -82,9 +78,12 @@ with VDevice() as vdev:
需手动用 `quant_info.qp_zp/qp_scale` 反量化。
3. `VStreamInfo` 无 `format_type` 属性，shape 与量化参数从
`get_input/output_vstream_infos()` 获取。
4. 摄像头实时推理走 `rpicam-hello/rpicam-vid --post-process-file ...`
4. **vstream 报告顺序不可信**：实测 5 输入 HEF 的报告顺序为
`input_layer1,5,4,3,2`，按报告顺序绑定会 frame1/frame2 错位；
必须按 `input_layerN` 数字后缀排序（`hailo_infer.py` 已修复）。
5. 摄像头实时推理走 `rpicam-hello/rpicam-vid --post-process-file ...`
（rpicam-apps-hailo-postprocess 提供）。
5. `hailo_platform.genai` 提供 LLM / VLM / Speech2Text 接口——
6. `hailo_platform.genai` 提供 LLM / VLM / Speech2Text 接口——
AI HAT 2（Hailo-10H + 8GB RAM）支持本地大模型，是与
AI HAT+（Hailo-8L）相比的最大增量。
@@ -93,12 +92,14 @@ with VDevice() as vdev:
Hailo 板**不能直接运行 ONNX/PyTorch**，必须编译为 HEF（含量化）：
```
actpred checkpoint (best_inference.pt)
→ export_onnx.py → model.onnx
→ Hailo DFC（Dataflow Compiler，需 x86 Linux 主机或云端 DFC）
量化校准（用 data/ 中的帧做 calibration set）
actpred checkpoint (pretrain_best_inference.pt, 224×224)
→ export_deploy.py（DFC 友好改造：按帧展开 CNN、手工注意力、
(1,1,S,d) 布局）→ actpred_deploy.onnx + actpred_deploy_pred_token.npy
→ gen_calibration.py --deploy（合成帧 + .mt 动作历史 + pred_token
抖动校准）→ calibration_deploy.npz
→ dfc_compile.py（parser → optimize → compiler，含输入连通性检查）
→ model.hef（拷回树莓派）
→ hailo_platform 推理（封装见 actpred/hailo_infer.py）
→ hailo_infer.py（HailoPredictor，--pred-token 喂学习值）
```
风险与注意点：
@@ -113,13 +114,50 @@ actpred checkpoint (best_inference.pt)
- HEF 的输入/输出名与量化参数由 DFC 编译决定，推理封装按
`get_input/output_vstream_infos()` 动态适配，不硬编码名称。
## 5. 结论与产出
## 5. DFC 编译与实机验证踩坑（2026-08-13）
### 5.1 首版 HEF：输出对输入完全不敏感
首版 HEF（64×64 checkpoint 产物）在 NPU 上首跑即发现**输出对全部
5 个输入均不敏感**（全 0 / 全 255 / 真实数据输出完全一致，对照
resnet HEF 同 API 验证输入通道有效，排除封装问题）。
### 5.2 驱动升级复测：依旧不敏感
将 hailort 5.1.1 升级到 5.3.0（与编译用 SDK 5.3 对齐）后复测：
设备识别、resnet 基准（307.7 FPS）、actpred HEF 执行（6.3ms/次）
全部正常，但 4 角输入敏感性测试（真实/全零帧 × 真实/全零历史）
输出仍完全一致 → **判定为 DFC 编译侧问题（输入在编译图中被断开/
常量化），驱动版本不是根因**。
### 5.3 排查发现与修复（待重编译验证）
| 发现 | 证据 | 修复 |
|---|---|---|
| pred_token 常量校准量化退化 | HEF 边缘 `zp=123, scale=18571.7`，任何输入量化成 0 | `gen_calibration.py` 改为学习值 ±30% 抖动校准；推理端喂学习值（`export_deploy.py --pred-token-out` + `hailo_infer.py --pred-token`） |
| vstream 报告顺序乱序 | 5 输入 HEF 报告顺序 1,5,4,3,2 | `hailo_infer.py` 按 `input_layerN` 排序绑定 + 乱序单测 |
| 输入断开无任何报错 | 编译全流程通过但 HEF 恒定输出 | `dfc_compile.py` parser/optimize 后自动检查输入层下游连通性，断开即报错 |
| 编译前无数值门槛 | deploy ONNX 数值正确性未独立验证 | `_onnx_validate.py`：输入敏感性 + PyTorch 一致性（本次 PASS，差异 1.5e-5） |
### 5.4 待办
1. x86 主机重编译（`dfc_compile.py`，产物含 `_optimized.har`）；
2. 拷回 HEF + pred_token.npy，跑 `_npu_test.py` 4 角敏感性复验；
3. 若仍不敏感：检查 `_optimized.har` 输入层下游连通性，定位
optimize 断连的具体算子。
## 6. 结论与产出
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 推理端做端到端验证。
2. actpred HEF 编译链路已全流程打通（export_deploy → gen_calibration →
dfc_compile），但首版 HEF 因 DFC 编译侧输入断开不可用，修复方案
已落地，待重编译复验。
3. actpred HEF 推理封装：`actpred/hailo_infer.py`（`HailoPredictor`），
接口对齐 `predict.ActionPredictorInference`，单测含 fake hailo_platform
的 5 输入与乱序顺序用例。
4. CPU 侧性能基线（224×224，Pi 5）：ONNX Runtime 11.4ms / PyTorch
21ms，见
[测速报告](actpred_inference_speed_benchmark_20260813.md) §6。
## 参考
docs/reports/actpred_inference_speed_benchmark_20260813.md
+19
View File
@@ -80,6 +80,25 @@
3. 建议在 Pi 5 + HAT 2 环境补测 1920×1080（ONNX CPU / HEF NPU），
并据此确定量产部署分辨率。
## 6. 224×224 复测（2026-08-13，Pi 5，当前 NPU 部署分辨率）
NPU 部署轮次以 224×224 的 `pretrain_best_inference.pt` 为准（HEF 编译
目标分辨率），据此补测 Pi 5 CPU 基线（3 帧 + 全零历史；episode 原始
图像即 224×224，无重采样开销）：
| 方案 | 输入分辨率 | 延迟 | 备注 |
|---|---|---|---|
| PyTorch CPU | 224×224 | 21.0 ms | 含预处理，预热 3 次取 20 次均值 |
| ONNX Runtime CPU | 224×224 | 11.4 ms | 含预处理，预热 3 次取 50 次均值 |
| ONNX Runtime CPU | 224×224 | 10.7 ms | 纯 `session.run`（预缩放输入） |
| Hailo-10 NPU（actpred HEF，首版） | 64×64 | 6.3 ms | 含预处理 + 量化/反量化，驱动 5.3.0 |
注：本组 ONNX 纯推理（10.7ms）与 §2 的 5.9ms（同为 224 模型）存在
差异，未追根（torch≥2.12 dynamo 导出路径、系统负载、ORT 线程调度均
可能影响），以本组实测为准；ONNX 仍比 PyTorch 快约 2 倍。NPU 首版
HEF 因编译侧输入断开输出恒定，仅作封装性能基线，数值有效性待重编译
后复验（见 hailo 调研报告）。
## 参考
- [张高兴的 Raspberry Pi AI 开发指南：将自定义模型编译为 Hailo NPU 的 .hef 模型](https://www.cnblogs.com/zhanggaoxing/articles/18597244.html)
docs/reports/blackbird_project_profile.md
+1 -1
View File
@@ -318,7 +318,7 @@ systemctl start Nidus # 或 bash core/_run.sh
### 8.3 关键 dev docs 索引（`docs/reports/`）
core_service_registry_dev_doc（注册中心）、auth_service_plan（CA 模块）、aibox_open_dev_plan / aibox_file_network_cli_refactor（aibox 安全沙箱与 CLI 化）、libcrypt_CBC_deprecation_dev_doc（AES-GCM 迁移）、libhttp_remote_addr_dev_doc（X-Remote-Addr 透传）、captcha_cpp_rewrite / smtp_cpp_rewrite / confs2_cpp_rewrite（C++ 重写方案）、actpred_pretrain_test（预训练与推理测试）。
core_service_registry_dev_doc（注册中心）、auth_service_plan（CA 模块）、aibox_open_dev_plan / aibox_file_network_cli_refactor（aibox 安全沙箱与 CLI 化）、libcrypt_CBC_deprecation_dev_doc（AES-GCM 迁移）、libhttp_remote_addr_dev_doc（X-Remote-Addr 透传）、captcha_cpp_rewrite / smtp_cpp_rewrite / confs2_cpp_rewrite（C++ 重写方案）。
### 8.4 安全评级演进
docs/reports/bot4cj_python_migration_dev_doc.md
-1
View File
@@ -391,7 +391,6 @@ Python 不适用的边界（bot4cj 均不涉及）：主机 GPIO bit-bang 生成
- [bot4cj 代码审计报告](../reviews/bot4cj_CODE_AUDIT_20260808.md)（15 项发现）
- [bot4cj 深度分析报告](bot4cj_analysis_20260525_00.md)（D1-D29）
- [actpred 与 bot4cj 研究报告](actpred_bot4cj_research_20260809.md)
- [bot4cj README.robot.md](../../bot4cj/README.robot.md)
- [actpred mt_parser.py](../../actpred/mt_parser.py)（Python 解析器先例）
docs/reviews/actpred_CODE_AUDIT_20260812.md
+2 -2
View File
@@ -7,8 +7,8 @@
> 第 3 轮 — `91b3004 refactor(actpred): 模型输入尺寸 image_size → image_width/image_height`
>
> **与上轮审计的关系**：上一份报告 `actpred_CODE_AUDIT_20260808.md` 针对的是
> 旧架构（MLP/GRU 历史编码 + 融合头，~140K 参数）。此后模块经历了注意力架构重写
> （`docs/reports/actpred_attention_rewrite_test_20260809.md`），并新增了
> 旧架构（MLP/GRU 历史编码 + 融合头，~140K 参数）。此后模块经历了注意力架构重写，
> 并新增了
> .mt 预训练（`pretrain_mt.py`）、Hailo NPU 后端（`hailo_infer.py`）、
> ONNX Runtime 后端（`onnx_infer.py`）。本报告为架构重写后的**首轮全量审计**，
> 含三轮审查：第 1 轮整体审计 + 第 2 轮深度复审（边界行为/资源管理/跨文件一致性）
docs/reviews/bot4cj_CODE_AUDIT_20260808.md
+1 -2
View File
@@ -3,7 +3,7 @@
> 审查日期：2026-08-08 (Asia/Shanghai)
> 审查人：Automated Review
> 审查范围：`bot4cj/` 全模块（仓颉 Cangjie 机器人硬件脚本解析器）
> 参考文档：[深度分析报告](../reports/bot4cj_analysis_20260525_00.md)（D1-D29）、[actpred 与 bot4cj 研究报告](../reports/actpred_bot4cj_research_20260809.md)
> 参考文档：[深度分析报告](../reports/bot4cj_analysis_20260525_00.md)（D1-D29）
---
@@ -384,7 +384,6 @@ action_dim=8 的连续向量 10 舵机 + 2 云台角度
### 参考文档
- [bot4cj 深度分析报告](../reports/bot4cj_analysis_20260525_00.md)（28 章，1407 行，D1-D29）
- [actpred 与 bot4cj 研究报告](../reports/actpred_bot4cj_research_20260809.md)
- [仓颉编程语言](https://cangjie-lang.org/)
### 审查人