From a6e17811852f96aa815e07daa3dcf79badda375b Mon Sep 17 00:00:00 2001 From: qing <1776177662@qq.com> Date: Thu, 13 Aug 2026 12:22:41 +0800 Subject: [PATCH] =?UTF-8?q?docs(actpred):=20=E6=9B=B4=E6=96=B0=20Hailo=20?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3=E4=B8=8E=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=EF=BC=8C=E6=B8=85=E7=90=86=E8=BF=87=E6=97=B6=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: 部署工作流更新（224×224、pred-token-out、抖动校准、 连通性检查），首版 HEF 输入不敏感警告改为修复清单，ONNX 测速 数字更新为 224 实测 - hailo 调研报告：驱动 5.3.0、vstream 乱序踩坑、编译断连排查与 修复表、重编译待办 - 测速报告：新增 §6 Pi 5 224×224 复测 - 清理已删除报告的 4 处失效引用（审计报告/迁移文档/项目画像） --- actpred/README.md | 52 ++++++++--- ..._hailo_hat2_inference_research_20260813.md | 86 +++++++++++++------ ...pred_inference_speed_benchmark_20260813.md | 19 ++++ docs/reports/blackbird_project_profile.md | 2 +- .../bot4cj_python_migration_dev_doc.md | 1 - docs/reviews/actpred_CODE_AUDIT_20260812.md | 4 +- docs/reviews/bot4cj_CODE_AUDIT_20260808.md | 3 +- 7 files changed, 123 insertions(+), 44 deletions(-) diff --git a/actpred/README.md b/actpred/README.md index d513435..3ddf3ad 100644 --- a/actpred/README.md +++ b/actpred/README.md @@ -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)。 diff --git a/docs/reports/actpred_hailo_hat2_inference_research_20260813.md b/docs/reports/actpred_hailo_hat2_inference_research_20260813.md index fd14c95..0906c2a 100644 --- a/docs/reports/actpred_hailo_hat2_inference_research_20260813.md +++ b/docs/reports/actpred_hailo_hat2_inference_research_20260813.md @@ -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。 ## 参考 diff --git a/docs/reports/actpred_inference_speed_benchmark_20260813.md b/docs/reports/actpred_inference_speed_benchmark_20260813.md index 291de35..fd238b7 100644 --- a/docs/reports/actpred_inference_speed_benchmark_20260813.md +++ b/docs/reports/actpred_inference_speed_benchmark_20260813.md @@ -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) diff --git a/docs/reports/blackbird_project_profile.md b/docs/reports/blackbird_project_profile.md index a505ea6..7506627 100644 --- a/docs/reports/blackbird_project_profile.md +++ b/docs/reports/blackbird_project_profile.md @@ -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 安全评级演进 diff --git a/docs/reports/bot4cj_python_migration_dev_doc.md b/docs/reports/bot4cj_python_migration_dev_doc.md index 296f427..98c08e1 100644 --- a/docs/reports/bot4cj_python_migration_dev_doc.md +++ b/docs/reports/bot4cj_python_migration_dev_doc.md @@ -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 解析器先例） diff --git a/docs/reviews/actpred_CODE_AUDIT_20260812.md b/docs/reviews/actpred_CODE_AUDIT_20260812.md index fb8e7f4..879db09 100644 --- a/docs/reviews/actpred_CODE_AUDIT_20260812.md +++ b/docs/reviews/actpred_CODE_AUDIT_20260812.md @@ -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 轮深度复审（边界行为/资源管理/跨文件一致性） diff --git a/docs/reviews/bot4cj_CODE_AUDIT_20260808.md b/docs/reviews/bot4cj_CODE_AUDIT_20260808.md index 374db23..98543e4 100644 --- a/docs/reviews/bot4cj_CODE_AUDIT_20260808.md +++ b/docs/reviews/bot4cj_CODE_AUDIT_20260808.md @@ -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/) ### 审查人