3. 模型交付总览

在旭日X3/X5的实际交付中，模型交付并不是“把权重文件拷过去”这么简单。它是一条从训练框架出发、经过算子与图结构适配、量化编译、板端部署验证的完整链路。任何一个环节的产物缺失或版本错配，都会导致模型无法在BPU上高效运行，甚至无法加载。因此，理解这条链路上的关键产物与交付物清单，是保证项目可复现、可维护、可验收的基础。

一、核心原理：模型交付的本质是“跨栈转换”

训练框架（PyTorch、TensorFlow、ONNX等）关注的是数值精度与训练效率，而地平线BPU关注的是定点计算、算子融合与内存布局。模型交付的本质，是把一个浮点训练图，逐步转换为可在X3/X5上执行的定点部署图。这个过程包含三个关键转换：

• 图结构转换：将训练框架模型导出为ONNX，再通过地平线工具链转换为可编译的中间表示。
• 数值精度转换：通过校准数据集完成量化，把FP32权重与激活值映射为INT8，并生成量化参数。
• 执行形态转换：编译生成BPU可执行的.hbm模型，同时生成板端运行时所需的配置与后处理描述。

这三步转换分别对应三类关键产物：ONNX模型、量化校准产物、以及.hbm与部署配置。它们共同构成模型交付的最小闭环。

二、方法流程：从训练到板端的五步链路

下面给出一个可落地的标准流程，适用于X3与X5平台。流程中的每一步都对应明确的输入与输出，便于在交付时逐项核对。

1. 训练框架导出ONNX：固定输入shape，去除训练专用节点，确保算子版本与工具链兼容。
2. 模型检查与图优化：使用地平线工具链进行模型检查，识别不支持的算子并替换或拆分。
3. 量化校准：准备校准数据集，运行校准脚本，生成量化配置与校准缓存。
4. 编译生成.hbm：根据目标平台（X3或X5）选择对应编译配置，生成BPU可执行模型。
5. 板端部署与验证：将.hbm、配置文件、后处理脚本部署到板端，运行推理并比对精度与性能。

三、关键产物与交付物清单

为了让交付物可追溯，建议按“模型文件、配置与脚本、验证报告”三类整理。下表给出一个完整的交付物清单示例，可直接作为项目验收的检查表。

类别	交付物	说明	是否必需
模型文件	model.onnx	训练框架导出的中间模型，用于工具链转换	必需
模型文件	model.hbm	BPU可执行模型，X3/X5平台专用	必需
量化产物	calibration_cache.bin	校准缓存，保证量化结果可复现	必需
量化产物	quant_config.json	量化配置，记录校准方法与参数	建议
配置与脚本	deploy_config.json	板端运行时配置，含输入输出节点信息	必需
配置与脚本	postprocess.py	后处理脚本，负责解码与NMS等	必需
验证报告	accuracy_report.md	浮点与定点精度对比，含逐层误差分析	建议
验证报告	perf_report.md	板端推理耗时、内存占用与帧率	建议

四、案例场景：一个分类模型的交付实例

假设我们有一个基于PyTorch的ResNet18分类模型，需要部署到X3上。训练完成后，首先导出ONNX：

torch.onnx.export(
    model,
    dummy_input,
    "resnet18.onnx",
    input_names=["input"],
    output_names=["output"],
    opset_version=11
)

接着使用地平线工具链进行模型检查与量化校准。校准数据集建议从验证集中随机抽取100~200张，覆盖主要类别。校准完成后编译生成.hbm：

hb_mapper makertbin \
  --config resnet18_config.yaml \
  --model-type onnx

板端部署时，需要将.hbm、deploy_config.json与postprocess.py一并放入部署目录。运行推理后，对比浮点与定点输出，若Top-1精度下降超过1%，则需要检查校准集分布或调整量化敏感层。

五、误区与复盘

在实际交付中，最常见的误区有三个：

• 只交付.hbm，不交付ONNX与校准缓存：导致后续无法复现量化结果，模型迭代时只能重新训练。
• 忽略目标平台差异：X3与X5的算子支持与编译参数不同，混用会导致模型加载失败或性能骤降。
• 后处理脚本与模型输出不匹配：模型输出节点名称或shape变更后，后处理未同步更新，导致推理结果错乱。

复盘时，建议把“模型文件、配置脚本、验证报告”作为三个独立检查项，逐项确认版本一致性与完整性。只有这三类产物齐备且相互匹配，模型交付才算真正完成。

总结来说，模型交付总览的核心在于“链路清晰、产物齐备、版本一致”。从训练框架到地平线部署，每一步都有明确的输入输出；把ONNX、.hbm、校准缓存、部署配置与验证报告作为标准交付物，才能让X3/X5项目在迭代与验收中保持可控。