harmony_timeflow开源团队的htf_inspect_2.0版本解读

harmony_timeflow/htf_inspect

htf_inspect_2.0是一款专为嵌入式AI部署和昇腾(Ascend)NPU生态设计的静态分析工具。它能在模型实际烧录到硬件之前，对ONNX模型进行深度“体检”，提前发现内存溢出、算子不支持、缓存配置错误等致命风险，大幅降低调试成本。

一. 环境配置方法

pip install -e .      //安装当前目录下的工具包

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc          

//将用户本地bin目录添加到环境变量,确保htf_inspect命令可用

source ~/.bashrc    //使环境变量立即生效

htf_inspect --help     //htf_inspect --help

二 .核心概念解析

Generic vs. Ascend 模式的区别：

🟢target generic :

– 使用通用的线性内存估算。

– 假设内存无限或仅受系统总 RAM 限制。

– 用途: 快速检查模型结构完整性、算子类型支持性。

🟢target Ascend :

– 启用昇腾特有的层级内存模型 (Global DRAM ➔ L1 Buffer ➔ L0 Buffer)。

– 模拟真实的 NPU 缓存行为，检测片上缓存溢出 (Buffer Overflow)。

– 分析算子是否适合在 Cube Unit (矩阵计算) 或 Vector Unit (向量计算) 上执行。

– 用途: 真实部署前的关键验证，防止在 NPU 上因内存不足导致运行时崩溃。

审计(audit)会检查什么？

开启审计后，工具不仅检查算子支持性，还会深度验证：

内存峰值估算: 计算推理过程中的最大临时内存占用 (Activation Memory)，确保不超过设备 SRAM 限制。

算子融合可行性: 检查是否有无法融合的算子序列导致额外的内存拷贝。

量化兼容性: 检查权重数据类型是否符合 NPU 加速要求 (如 int8 vs float16)。

结果判定: 通过显示 [PASS]，失败则列出具体的瓶颈（如 Memory Limit Exceeded 或 Unsupported Op）。

三. 使用案例：

htf_inspect <model_path> [选项]

3.1 基础分析(Generic模式)：

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx       

//快速检查模型结构同时不会绑定特定硬件。

3.2 昇腾(Ascend)硬件专项分析：

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx --target ascend

//针对昇腾NPU进行算子映射分析查看推荐执行单元(Cube/Vector)

3.3 开启详细日志(Verbose)：

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx --target ascend --verbose

//查看每个算子的详细分析数据，包括预估耗时和内存需求

3.4 嵌入式约束审计(Audit)：

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx --target ascend --audit

//检查模型是否符合嵌入式系统的严格限制

3.5 全功能组合 (分析 + 审计 + 详情 + 保存报告)：

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx \
  --target ascend \
  --audit \
  --verbose \
  --output report_ascend_audit.json

//推荐用法：一次性完成所有检查并生成JSON报告供后续查阅。

3.6 测试内存估算逻辑：

htf_inspect htf_inspect/demo/overflow_test.onnx --target generic --audit

ONNX模型进行昇腾(Ascend)硬件适配性分析、嵌入式约束审计以及详细算子级诊断

四.高级场景与压力测试

1. 混合算子模型全项诊断

模型:mixed_ops_demo.onnx(包含卷积、矩阵乘法等多种算子)

目的: 验证工具在处理复杂真实模型时的综合映射能力和审计准确性。

htf_inspect htf_inspect/demo/mixed_ops_demo.onnx --target ascend --audit --verbose

预期结果:输出较长的详细日志包含多种算子类型 (Cube/Vector)的推荐策略，审计结果应为 [PASS]。

2. SIMT 算子专项诊断：

模型: gather_simt_demo.onnx (专门测试 Gather 等不规则内存访问算子)

目的: 验证工具能否正确识别必须运行在SIMT (Single Instruction Multiple Threads)核心上的特殊算子，而非强行映射到Cube/Vector单元。

htf_inspect htf_inspect/demo/gather_simt_demo.onnx --target ascend --audit --verbose

预期结果: 日志中应明确标记相关算子为 SIMT Mode，并展示其特殊的调度策略。

3. 溢出测试模型的 Ascend 后端诊断：

模型: overflow_test.onnx (设计用于触发内存溢出的大算子模型)

目的: 关键测试。验证工具能否在昇腾严格的片上内存限制下，准确检测到设计用于触发溢出的大算子模型，从而提前拦截部署风险。

htf_inspect htf_inspect/demo/overflow_test.onnx --target ascend --audit --verbose

预期结果:

审计状态: 预计显示 [FAIL] 或 [WARNING]。
详细日志: --verbose 将展示具体的内存计算细节，例如：“算子需要 512KB L1 缓存，但目标设备仅剩 256KB”。
价值: 证明工具具备提前预警能力并防止在真实硬件上发生运行时崩溃。

4. 跨后端对比测试 (Generic vs Ascend)

目的: 直观展示不同后端对同一溢出模型的分析差异，证明指定 --target ascend 的必要性。

步骤 A: 使用 Generic 模式 (基准)

注意：由于Generic不检查片上缓存，这里可能会错误地显示通过。

htf_inspect htf_inspect/demo/overflow_test.onnx --target generic --audit

步骤 B: 使用 Ascend 模式 (真实硬件模拟)

注意：这里将准确捕获片上缓存溢出。

htf_inspect htf_inspect/demo/overflow_test.onnx --target ascend --audit --verbose