horizonrobotics 基础结构导出编译流程代码生成
目标
将校准或 QAT 训练后的模型导出并编译为可部署的 HBM 文件。本 Skill 接收量化流程产出的模型（calib_net 或 qat_net），完成从 export 到编译的全部流程。
本 Skill 覆盖的流程：
export QAT BC → convert → remove_io_op → statistics → compile HBM
前置条件
本 Skill 依赖 j6-plugin-quantization skill 的输出：
- 校准后或 QAT 训练后的模型（
calib_net或qat_net） - 示例输入（
example_input） - 目标平台 march
导入
from horizon_plugin_pytorch.quantization.hbdk4 import export
from hbdk4.compiler import convert, compile, statistics, save
导入路径严禁违反以下规则：
export必须从horizon_plugin_pytorch.quantization.hbdk4导入。 不得从horizon_plugin_pytorch.quantization或horizon_plugin_pytorch导入。convert, compile, statistics, save必须全部从hbdk4.compiler导入。 不得从horizon_plugin_pytorch.quantization或任何其他模块路径导入。- 不得使用其他导入路径替代上述路径。
注意： 当本 sub-skill 作为 j6-plugin-hbdk-generating（编排型 skill）的一部分被调用时，导入语句必须与量化子 skill 的导入合并到文件顶部的一个统一导入块中，格式严格遵循 references/full-pipeline-template.md。
Step 1: 导出 QAT BC
将量化模型导出为 BC 格式。先切换到 VALIDATION 状态，验证推理正常后再 export：
# model 为 calib_net 或 qat_net
model.eval()
set_fake_quantize(model, FakeQuantState.VALIDATION)
# 验证量化模型在 VALIDATION 状态下推理正常
with torch.no_grad():
model(example_input)
qat_bc = export(model, example_input)
Step 2: Convert — 转换为量化模型
将 QAT BC 转换为目标平台专用的量化模型：
quantized_model = convert(qat_bc, march)
save(quantized_model, "quantized.bc")
convert 调用严禁违反以下规则：
march参数不可省略。 必须写成convert(qat_bc, march)，禁止写成convert(qat_bc)或convert(exported_model)。
Step 3: Remove IO Op — 删除首尾 Quantize/Dequantize 算子
部署时输入输出不需要首尾的量化/反量化节点，必须删除。不删除会导致模型在 BPU 上无法正确运行：
func = quantized_model.functions[0]
func.remove_io_op(op_types=["Dequantize", "Quantize"])
save(quantized_model, "quantized_remove.bc")
remove_io_op 调用严禁违反以下规则：
- 必须先取
quantized_model.functions[0]得到 func，再对 func 调用remove_io_op。 禁止直接对quantized_model调用remove_io_op()（即converted_model.remove_io_op()是错误写法）。 - 必须指定
op_types=["Dequantize", "Quantize"]参数。 禁止省略op_types写成func.remove_io_op()，不指定 op_types 可能删除错误节点。 - remove_io_op 之后必须
save。 保存 remove_io_op 后的 BC 文件，便于对比和排查。
Step 4: Statistics — 检查 CPU 算子
如果模型中存在 CPU 算子（hbtl），说明有算子无法在 BPU 上运行，编译会失败或运行时回退 CPU。打印警告但继续执行后续流程：
stats = statistics(quantized_model)
if "hbtl" in str(stats).lower():
print("[WARNING] 模型中存在 CPU 算子 (hbtl)，编译可能失败或运行时回退 CPU")
# 可用 visualize(quantized_model, "debug.onnx") 排查具体哪个算子
else:
print("[OK] 无 CPU 算子")
常见 CPU 算子原因：
- 使用了 BPU 不支持的算子或参数配置
- 量化配置不正确导致部分算子无法量化
- 可用
visualize生成 onnx 文件定位问题算子
Step 5: Compile — 编译生成 HBM
将量化模型编译为最终部署产物：
hbm_name = "model.hbm"
compile(quantized_model, hbm_name, march, opt=2, jobs=64, progress_bar=True, debug=False)
compile 调用严禁违反以下规则：
- 所有参数不可省略。 禁止写成
compile(quantized_model)或compile(converted_model)，必须包含完整的参数列表：compile(quantized_model, hbm_name, march, opt=2, jobs=64, progress_bar=True, debug=False)。
compile 参数说明：
opt=2：优化等级，2 为最高jobs=64：并行编译线程数progress_bar=True：显示编译进度debug=False：不输出调试信息
输出产物
| 产物 | 说明 |
|---|---|
quantized.bc |
convert 后的量化 BC 文件 |
quantized_remove.bc |
remove_io_op 后的 BC 文件 |
*.hbm |
最终部署产物 |
常见问题
存在 CPU 算子 (hbtl)
- 使用
visualize(quantized_model, "debug.onnx")生成 onnx 文件排查 - 检查是否有不支持的算子或参数配置
- 检查量化配置是否正确
编译失败
- 检查 statistics 是否有 CPU 算子
- 确认 march 设置与目标平台一致
- 检查模型输入 shape 是否合理
快速自检清单
- export 前模型处于 VALIDATION 状态
- convert 使用正确的 march（
convert(qat_bc, march)，march 不可省略） - remove_io_op 通过
func = quantized_model.functions[0]+func.remove_io_op(op_types=["Dequantize", "Quantize"])调用（禁止直接对 model 调用，禁止省略 op_types） - statistics 检查无 CPU 算子 (hbtl)
- compile 生成 HBM 文件（所有参数完整，禁止只写
compile(model)） - save 保存中间 BC 文件