前言¶

在 RDK 系列板端部署模型时，训练侧多为 FP32，板端 BPU 通常需要 INT8 定点模型。OpenExplorer 工具链、hb_compile 与 YAML 配置项较多，校准数据、板端 stride 对齐、后处理等环节也容易踩坑。若每次都在文档与论坛帖之间来回翻，对话式开发很难形成稳定流程。

SkillHub 上的 RDK模型量化工具（RDK S100）（坐标 @user_a793e4ac/rdk-model-quantization，版本 1.0.0，社区来源）把 PyTorch/ONNX 到 BPU（.hbm）的脚本、配置模板与排障说明打包成通用 SKILL.md 格式，供 Cursor 等 Agent 在安装后按步骤引导执行。Skill 包内文档主要面向 RDK S100P / S600 与对应 march 配置，与 SkillHub 标题中的「RDK S100」并存，使用时以包内 README.md 与配置为准。

这是什么¶

一句话：面向地平线 BPU 的模型量化与部署工作流 Skill，由社区发布者 user_a793e4ac（SkillHub 页面显示作者「地瓜橙」）维护，分类为 dev-programming，不需要 API Key（requires_api_key=false）。

它解决的问题是：在主机 Docker 工具链环境中完成 ONNX 导出、校准数据生成、量化编译与精度验证，并给出板端部署与常见精度问题的处理思路。实践案例以 Paraformer-large 语音识别 为主线，目录中含 export_onnx.py、quantize_model.py 等可执行脚本及 templates/encoder_config.template.yaml。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md、README.md 与 QUICKSTART.md，可按路径复现。

1. 五步量化流水线：导出 ONNX → 生成校准数据 → 按 YAML 量化 → 验证余弦相似度 → scp 将 .hbm 传到板端。
2. 配套脚本（scripts/）：
   - export_onnx.py：PyTorch 转 ONNX；
   - generate_calibration_data.py：生成 PTQ 校准集；
   - quantize_model.py：调用工具链执行量化；
   - verify_quantization.py：对比原模型与量化结果；
   - correction_factor_cleanup.py：Predictor 尾部多余 token 的后处理。
3. 配置与文档：templates/encoder_config.template.yaml；docs/best_practices.md、docs/troubleshooting.md；examples/simple_quantization.py、examples/paraformer_quantization.md。
4. 关键技术说明（包内总结，附 Paraformer 实测数据）：stride-aware 输入拷贝、校准类型 default 与多种方法对比、correction_factor 后处理；文档中记载 Encoder/Predictor 的 Cosine 与加速比等指标，供你对照自家模型验证，而非保证通用结论。

安装与启用¶

安装 SkillHub CLI¶

若本机尚未安装，可先检查版本：

command -v skillhub && skillhub --version

未安装时可按 SkillHub 官方说明执行（完整安装示例）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安装本 Skill¶

SkillHub 页面给出的方式是：阅读 SkillHub 安装说明，安装坐标 @user_a793e4ac/rdk-model-quantization。

CLI 安装时需用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。常见路径如下：

在 Cursor 中可执行：

skillhub install rdk-model-quantization --namespace user_a793e4ac --dir ~/.cursor/skills/

安装完成后重启或刷新 Agent，使 Skill 被加载。官方 API 入口：https://api.skillhub.cn/user_a793e4ac/rdk-model-quantization；展示页：https://www.skillhub.cn/skills/user_a793e4ac/rdk-model-quantization。

典型用法¶

下面介绍 Skill 包内 快速入门 与主机侧环境约定；量化须在地平线 OE Docker 内进行。

1. 准备 OE Docker 环境¶

Skill 文档指定镜像 ai_toolchain_ubuntu_22_s100_s600_cpu:v3.7.0（需自行准备对应 tar 并 docker load）：

docker load -i ai_toolchain_ubuntu_22_s100_s600_cpu_v3.7.0.tar

docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  ai_toolchain_ubuntu_22_s100_s600_cpu:v3.7.0 \
  bash

pip install -r requirements.txt

2. 导出 ONNX¶

python3 scripts/export_onnx.py \
    --model-path models/your_model.pt \
    --output-path models/your_model.onnx \
    --input-shape 1,300,560

3. 生成校准数据¶

python3 scripts/generate_calibration_data.py \
    --data-dir audio_data/ \
    --output-dir calibration_data/ \
    --num-samples 50

快速入门建议至少约 50 条代表性样本；README.md 中亦提到约 50–100 条。

4. 编写量化配置并编译¶

QUICKSTART.md 示例（注意 march：S100P 用 nash-m，S600 用 nash-p）：

model_parameters:
  onnx_model: 'models/your_model.onnx'
  march: "nash-m"
  output_dir: 'output/'

calibration_parameters:
  cal_data_dir: 'calibration_data/'
  calibration_type: 'default'
  num_samples: 50

compiler_parameters:
  optimize_level: 'O2'

执行量化：

python3 scripts/quantize_model.py \
    --config configs/my_model_config.yaml \
    --output-dir output/

也可从模板复制：cp templates/encoder_config.template.yaml configs/encoder_config.yaml 再编辑。

5. 验证并部署¶

python3 scripts/verify_quantization.py \
    --original-model models/your_model.onnx \
    --quantized-model output/your_model.hbm \
    --test-data calibration_data/ \
    --max-samples 5

快速入门期望平均余弦相似度约 0.959（Cosine ≥ 0.95 视为良好，以你本地输出为准）。

scp output/your_model.hbm root@<board-ip>:/root/models/

在 Agent 对话中，可将上述步骤与本地模型路径、板端 IP 交给已安装的 Skill，让其按 docs/troubleshooting.md 排查 Cosine 偏低或板端推理异常。

适用场景与注意¶

适合谁

• 已在 RDK S100P / S600 上部署 INT8 模型，需要 PTQ 流程脚本与配置模板的开发者；
• 做 Transformer 类模型（文档以 Paraformer、BERT 等为例）BPU 量化，并愿意按 Skill 内最佳实践准备校准数据；
• 希望在 Cursor 等环境中用固定工作流减少重复查文档的成本。

限制与注意

• 需自备 OE 工具链 Docker 镜像与开发板；Skill 不替代官方工具链安装与授权流程。
• README.md 要求模型已能导出 ONNX、输入形状相对固定、体积小于约 2GB；主机为 x86_64，板端为文档所列 RDK 型号。
• SkillHub 元数据：评分 100000、下载 854（抓取时统计），与页面展示可能随时间变化。
• 包内性能与 Cosine 数字来自 Paraformer-large 案例，迁移到其他结构须重新跑 verify_quantization.py 与业务指标。
• 板端若 Cosine 骤降，文档强调检查 stride 对齐 与特征提取（CMVN/LFR 等）是否与训练一致；语音识别场景还需关注 correction_factor 后处理。

结尾¶

RDK模型量化工具（RDK S100） 把 BPU 量化从环境、脚本到排障文档串成可安装 Skill，适合在 Agent 会话里按步骤推进。核实版本、安装与社区信息请以 SkillHub 为准：

• API：https://api.skillhub.cn/user_a793e4ac/rdk-model-quantization
• 页面：https://www.skillhub.cn/skills/user_a793e4ac/rdk-model-quantization