J6 Hbdk Compile

J6 HBDK Compile - 通用模型编译 Skill

版本: 1.1.8

概述

本 skill 基于 YAML 配置文件驱动模型编译流程：

1. 解析用户指令 -> 生成配置文件
2. 用户确认配置文件 -> 是否需要修改
3. 加载配置并执行编译 -> 检查 CPU 算子 -> 校验产物 -> hbm_perf -> 生成报告

交互原则（Step 2 为默认强制门禁）：

• 默认：Step 1 生成或写出 compile_config_*.yaml 后，必须先执行 Step 2，向用户展示配置路径与关键字段摘要，并结束本轮回复、等待用户下一条消息。在用户给出明确肯定（如「直接编译」「确认」「可以」）之前，禁止运行 compile_model.py -c 或任何等价编译命令。
• 唯一例外：用户在同一条用户消息中已写明可跳过确认（如「直接编译」「跳过确认」「按上述配置立刻编译」「生成配置后马上编」），才允许在同一轮助手流程中连续执行 Step 1→3。
• 仍须单独确认（不得默认继续）：缺少模型路径；pyramid/resizer 的 mean/std 等关键项与用户描述不符或需用户拍板；检测到 CPU 算子后是否继续；编译失败后的重试或改配策略。
• 模型合法性校验失败：立即终止本 skill 流程；禁止修改 compile_model.py 或用旁路脚本绕过检查（详见下文「模型合法性检查」）。

默认配置：

• 目标平台: nash-e
• 输出目录: 模型同级目录下的 compile_<timestamp> 文件夹（带时间戳避免覆盖）
• 删除 QDQ 节点: 通过 remove_node_type: ["Quantize"]（remove_all_qdq 已废弃）
• debug: true

模型合法性检查（加载阶段）

compile_model.py 在首次加载模型时（含 --generate-config 拉取 IO 与正式编译的 load_model）会执行以下检查，不通过则立即终止（异常或非零退出）并输出明确错误信息；不得在同一轮任务里继续执行后续编译步骤或假装已加载成功。

硬门禁（校验失败 = 停止本 skill 工作流）
任一检查失败时，你必须立刻停止：不得继续跑 -c、不得在未换模型的情况下反复「试编译」、不得替用户编造已通过校验的结论。应原样引用终端/日志中的错误信息，并明确告知用户需在模型或环境侧完成的动作（例如改回 qat.bc、换用带 HzCalibration 的 PTQ ONNX、对齐 hbdk4 与导出工具链版本）。

对 Agent 的禁止事项（严禁绕过校验）

• 禁止为通过检查而修改 compile_model.py（包括注释、删除或改写 assert_supported_model_suffix、load_bc_model_validated、assert_bc_is_qat_phase、assert_onnx_has_hz_calibration 及调用它们的代码路径）。
• 禁止编写或使用其它脚本 / 临时 Python，在不做同等语义校验的情况下加载模型，仅为生成 IO、写 yaml 或推进编译。
• 禁止向用户建议通过删断言、sed 去掉检查、环境变量关闭校验等方式绕过。
• 唯一合规做法：用户更换为满足上表的模型或环境后，再重新执行本仓库中的 compile_model.py（含 Docker 场景下同步到容器内的同一份脚本，亦不得删减校验）。

说明：--generate-config 与 -c 使用相同校验；若仅想改 yaml 而暂时无合法模型，可先生成空模板（不传 -m）或先解决模型路径/类型问题。

触发条件

显式触发

用户明确提出以下意图时触发：

• "编译 xxx 模型"
• "导出 hbm"
• "生成上板产物"
• "compile 模型"
• "在 docker 里编译 xxx 模型"
• "docker 中导出 hbm"

隐式触发

用户虽然没直接说 compile，但目标明显是拿到可部署产物时触发：

• "生成可部署模型"
• "拿到 hbm 文件"

如果是隐式触发，先用一句话说明"该目标通常需要执行 compile 才能得到 .hbm"，然后再开始流程。

Docker 环境模式

当用户提到以下关键词时，启用 Docker 环境模式：

• "在 docker 里运行"
• "docker 中编译"
• "容器里运行"
• "docker 路径"

Docker 模式工作流

Step 0: Docker 环境准备（仅 Docker 模式）
Step 1: 解析用户指令并生成配置文件
Step 2: 用户确认/修改配置文件
Step 3: 加载配置并执行编译流程
Step 4: 检查 CPU 算子
Step 5: 校验 HBM 产物
Step 6: 执行 hbm_perf
Step 7: 生成编译报告

Step 0: Docker 环境准备

1. 确认 Docker 工作路径：

   • 如果用户提供了 docker 路径，使用该路径
   • 如果用户提到 docker 但未提供路径，从模型路径推断或询问用户

2. 生成 compile_model.py 到 Docker 工作路径：

   • 使用 Write 工具直接在 Docker 工作路径下生成脚本
   • 脚本路径: <docker_work_path>/compile_model.py
   • 内容来源: 读取 ~/.claude/skills/j6-hbdk-compile/compile_model.py 并写入

3. 后续命令在 Docker 工作路径下执行：

   # 生成配置文件
   python <docker_work_path>/compile_model.py --generate-config -m <model_path>
   
   # 执行编译
   python <docker_work_path>/compile_model.py -c <config_path>
   

Docker 模式参数

Docker 模式示例

用户: "在 docker 里编译 /workspace/model.onnx，nash-m"

响应:

检测到 Docker 环境运行模式。

Step 0: 准备 Docker 环境
正在生成 compile_model.py 到 /workspace/ ...

Step 1: 生成配置文件...
python /workspace/compile_model.py --generate-config -m /workspace/model.onnx
...

工作流

严格按以下顺序执行。Step 2 不得被跳过（除非用户在同一条消息中已明确授权跳过，见上文「唯一例外」）；Agent 不得在仅完成 Step 1 后自动执行 Step 3。

Step 1: 解析用户指令并生成配置文件
Step 2: 用户确认/修改配置文件   ← 强制等待用户回复（默认）
Step 3: 加载配置并执行编译流程
Step 4: 检查 CPU 算子
Step 5: 校验 HBM 产物
Step 6: 执行 hbm_perf
Step 7: 生成编译报告

Step 1：解析用户指令并生成配置文件

1.1 参数提取

从用户输入中提取以下参数：

1.2 参数映射表

1.3 生成配置文件

调用编译脚本生成配置文件：

# 推荐：指定模型路径，自动创建编译产物目录并生成配置文件
python ~/.claude/skills/j6-hbdk-compile/compile_model.py --generate-config -m <model_path>

行为说明：

1. 自动创建编译产物目录：<模型同级目录>/compile_<timestamp>/
2. 配置文件生成到该目录下：compile_config_<模型名>.yaml
3. 配置文件中 output_dir 字段已填充编译产物目录路径

然后根据用户提供的参数修改配置文件内容。

1.4 PTQ Config 导入（新功能）

当用户传入 PTQ 配置文件时，自动提取输入预处理参数：

# 从 PTQ config 导入配置
python ~/.claude/skills/j6-hbdk-compile/compile_model.py --generate-config -m <model_path> --ptq-config <ptq_config.yaml>

PTQ 字段映射表：

norm_type 处理：

• PTQ yaml 中的 norm_type 字段被完全忽略
• norm 类型通过 mean_value、scale_value、std_value 组合推断：
  • mean + scale → data_mean_and_scale
  • mean + std → data_mean_and_std
  • scale → data_scale
  • std → data_std
  • mean → data_mean
  • 无参数 → no_preprocess
• scale_value 和 std_value 互斥，不能同时指定
• 不设置默认值：只有 PTQ config 中提供的参数才会被使用

预处理公式转换：

PTQ 预处理公式：norm_data = (data - mean_value) * scale_value

API 预处理公式：norm_data = (data - mean) / std

转换规则：std = 1 / scale_value

示例：

用户: "编译 model.onnx，使用 ptq 配置 mobilenet_config.yaml"

响应:

检测到 PTQ 配置文件，正在解析: mobilenet_config.yaml

从 PTQ config 提取:
  - march: nash-e
  - opt_level: 2
  - core_num: 1
  - jobs: 32
  - input_sources:
      - name: input
        source_type: pyramid
        data_type: bgr
        mean: [103.94, 116.78, 123.68]
        std: [58.82, 58.82, 58.82]

Step 1: 生成配置文件...
配置文件已生成: /path/to/compile_config_model.yaml

Step 2：用户确认/修改配置文件（Agent 强制遵守）

1. 门禁：完成 Step 1 后，除非当前用户消息已含「跳过确认 / 直接编译」类明确授权，否则禁止在同一轮对话中接着调用编译；必须先请用户确认。
2. 展示：给出 config_path，并摘要 model_path、march、output_dir、input_sources、remove_node_type、preserve_input_nodes、preserve_output_nodes 等会改变产物行为的字段（全文过长时可附「完整内容见该 yaml」）。
3. 结束本轮：用清晰问句收尾，等待用户下一条消息，例如：

   配置文件已就绪：/path/to/compile_config_xxx.yaml。请确认是否按此配置直接编译；若要改配置请说明字段，或回复「取消」终止。

4. 用户回复后的分支：
   • 肯定（如「直接编译」「确认」「可以」「编吧」）→ 进入 Step 3
   • 要改 → 用户改 yaml 或口述修改；Agent 更新后再回到本步展示与确认
   • 取消 → 不执行编译

Step 3：加载配置并执行编译流程

仅在 Step 2 取得用户明确肯定（或同条消息已授权跳过）后执行。调用编译脚本：

python ~/.claude/skills/j6-hbdk-compile/compile_model.py -c <config_path>

编译流程步骤：

1. 加载模型（含合法性检查，见上文「模型合法性检查」）

   • ONNX: onnx.load → 校验 HzCalibration → hbdk4.compiler.onnx.export()
   • BC: hbdk4.compiler.load（失败则提示 hbdk 版本兼容性）→ 校验非 quantized.bc（无 hbdk.target 等）→ 进入后续流程

2. 打印原始模型 IO 信息（干净输出，方便复制）

3. 配置输入源

   • 调用 insert_image_preprocess() 等方法配置 pyramid/resizer 输入

4. 转换模型

   • hbdk4.compiler.convert(model, march=march)

5. 删除节点（remove_node_type / preserve_* / remove_*_nodes，见配置说明）

   • remove_node_type 含 Quantize 且配置了 preserve_input_nodes 时：仅对「非保留、且非 pyramid/resizer 图像源」的入边尝试删相邻 Quantize。
   • pyramid/resizer：除配置里的根输入名外，convert 后可能出现的派生入边（如 {根名}_y、{根名}_uv）一律视为同一图像源，不会列入删除名单，避免 HBDK 报入边 Quantize unremovable 导致编译失败。
   • Dequantize / Cast 等按配置与 hbdk API 流程处理。

6. 打印删节点后模型 IO 信息（带 quant_info）

7. 编译模型

   • hbdk4.compiler.compile(model, path=hbm_path, march=march, **params)

8. 打印 HBM IO 信息（带 quant_info 和 strides）

IO 信息打印格式

编译过程会在以下阶段打印模型/产物的输入输出信息：

1. 原始模型加载后（干净输出，无 [INFO] 前缀）：

--- 原始模型输入 ---
  [0] input_name: shape=[1, 3, 224, 224], dtype=float32
--- 原始模型输出 ---
  [0] output_name: shape=[1, 1000], dtype=float32

2. 删节点后（带 quant_info）：

--- 删节点后模型输入 ---
  [0] input_name: shape=[1, 3, 224, 224], dtype=int8, quant_info=...
--- 删节点后模型输出 ---
  [0] output_name: shape=[1, 1000], dtype=int8, quant_info=...

3. HBM 编译完成后（带 quant_info 和 strides）：

--- HBM 输入 ---
  [0] input_name: shape=[1, 3, 224, 224], dtype=int8, quant_info=..., strides=[...]
--- HBM 输出 ---
  [0] output_name: shape=[1, 1000], dtype=int8, quant_info=..., strides=[...]

Step 4：检查 CPU 算子

检查方法：

• 调用 statistics(quantized_model) 获取算子统计
• 检查是否存在 hbtl 前缀的算子

判定标准：

• hbtl* 前缀 -> CPU 算子（警告）
• b30*, b30_vpu*, func*, hbdk* 前缀 -> 正常算子

处理规则：

• 未发现 CPU 算子 -> 继续流程
• 发现 CPU 算子 -> 列出具体算子名称，询问用户是否继续

不要只说"有 CPU 算子"，必须把具体名称列出来。

Step 5：校验 HBM 产物

检查以下文件是否生成：

• <model_name>.hbm - 最终编译产物

如果文件不存在或大小为 0，报告错误并排查日志。

中间产物

编译过程中会生成以下中间产物（保存在输出目录）：

Step 6：执行 hbm_perf

根据 perf_ip 配置：

• 有 perf_ip: 调用 hbm_perf(hbm_path, remote_ip=perf_ip)
• 无 perf_ip: 调用 hbm_perf(hbm_path)（不设置 remote_ip 参数）

生成 perf 报告 HTML 文件。

Step 7：生成编译报告

在输出目录下生成报告文件：compile_report_<model_name>_<timestamp>.md

报告内容：

• 基本信息：模型路径、输出目录、目标平台、HBDK 版本
• 配置摘要：所有编译参数
• 执行步骤：每步的执行状态
• CPU 算子检查结果
• 产物列表
• Perf 报告路径（如有）
• 错误信息（如有）

配置文件字段说明

基本配置

输入源配置 (input_sources)

data_type 说明：

• data_type 是模型训练时的数据格式，用于决定 insert_image_preprocess 的 mode 参数
• rgb -> mode="yuvbt601full2rgb"
• bgr -> mode="yuvbt601full2bgr"
• yuv444 -> mode=None
• 如果不是 rgb/bgr/yuv444 之一，会报错

节点删除配置

编译参数

性能测试配置

版本判断

常见错误处理

结果交付

完成后向用户简要汇报：

• 编译是否成功
• HBM 文件路径
• 编译耗时
• 是否存在 CPU 算子警告
• Perf 报告路径（如有）
• 编译报告路径

脚本路径

编译脚本位于：~/.claude/skills/j6-hbdk-compile/compile_model.py

# 生成配置文件模板（推荐指定模型路径）
python ~/.claude/skills/j6-hbdk-compile/compile_model.py --generate-config -m /path/to/model.bc

# 从 PTQ config 导入配置
python ~/.claude/skills/j6-hbdk-compile/compile_model.py --generate-config -m /path/to/model.bc --ptq-config /path/to/ptq_config.yaml

# 指定输出路径
python ~/.claude/skills/j6-hbdk-compile/compile_model.py --generate-config -m /path/to/model.bc -o my_config.yaml

# 使用配置文件编译
python ~/.claude/skills/j6-hbdk-compile/compile_model.py -c config.yaml