SmolVLM-PTQ: D-Robotics PTQ Deployment

针对RDK系列开发板，对 SmolVLM 视觉语言模型进行高效部署的后训练量化 (PTQ) 解决方案。

该项目提供了从模型导出、精度校验、数据准备到最终量化部署的脚本和详细指南，旨在帮助开发者快速将SmolVLM落地到嵌入式平台。

📋 目录

• 🛠️ 工作流程概览
• 🚀 快速开始
  • 第1步：环境准备与安装
  • 第2步：导出ONNX模型
  • 第3步：ONNX模型精度验证 (可选)
  • 第4步：生成PTQ校准数据
  • 第5步：执行PTQ量化
• 🙏 致谢
• 📜 许可证

🛠️ 工作流程概览

本项目的核心工作流程如下图所示，共分为五个主要步骤：

1. 环境准备：安装一个被我们修改过的、适配ONNX导出的 transformers 库。
2. 导出ONNX：将预训练的SmolVLM模型的视觉部分转换为ONNX格式。
3. 精度验证：对比原始PyTorch模型和ONNX模型的输出，确保转换过程无精度损失。
4. 生成校准数据：为PTQ过程准备校准数据集。
5. PTQ量化：使用地平线工具链将ONNX模型量化为可在硬件上部署的格式。

🚀 快速开始

请遵循以下步骤完成模型的量化部署。

第1步：环境准备与安装

我们的方案需要对 transformers 库的底层代码进行修改以适配ONNX的导出。因此，请不要直接通过pip安装官方版本，而是按照以下步骤进行源码安装。

1. 克隆官方 transformers 仓库的指定版本：

   git clone https://github.com/huggingface/transformers.git -b v4.51.3

2. 替换模型文件：

   将本项目中的 modeling_smolvlm.py 文件复制并覆盖到 transformers 源码的对应位置：

   transformers/src/transformers/models/smolvlm/modeling_smolvlm.py

3. 以可编辑模式安装：

   进入 transformers 源码的根目录，执行以下命令进行安装。

   cd transformers
   python -m pip install -e .

⚠️ 重要提示

由于我们使用了可编辑模式（-e），您对 transformers 库中代码的任何修改都会立刻生效。但如果您移动了 transformers 文件夹的位置，或在新的环境中，您必须重新执行上述 pip install -e . 命令来重建索引，否则修改将不会被应用。

第2步：导出ONNX模型

1. 下载SmolVLM官方权重：

   您可以从Hugging Face Hub下载权重。权重地址如下

   # 示例模型，请根据您的需求选择500M以及256M的模型
   https://huggingface.co/HuggingFaceTB/SmolVLM2-500M-Video-Instruct

2. 执行导出脚本：

   打开 export_smolvlm.py 文件，修改其中的 model_path 指向您刚刚下载的本地权重路径。然后运行脚本：

   python export_smolvlm.py

   运行成功后，您将在当前目录下得到 XXX.onnx 模型文件。

第3步：ONNX模型精度验证 (可选)

这是一个推荐步骤，用于确保ONNX模型的输出与原始PyTorch模型保持高度一致。

1. （可选）创建一个干净的Python环境，或者在当前环境中卸载我们修改过的transformers库。

2. 安装官方原版transformers库：

   python -m pip install transformers==4.51.3

3. 运行比对脚本：

   修改 onnx_diff.py 脚本，配置您的本地SmolVLM权重路径以及刚刚导出的ONNX文件路径。然后运行：

   python onnx_diff.py

   脚本会计算并打印原始模型与ONNX模型推理结果之间的差异值（difference）。通常情况下，该值应小于 1e-4。

第4步：生成PTQ校准数据

PTQ（Post-Training Quantization）过程需要少量有代表性的数据来校准量化参数。

1. 准备校准图片：

   创建一个文件夹，并放入50-100张具有代表性的图片（例如，从COCO数据集中随机抽取）。

2. 运行生成脚本：

   打开 generate_calibra_data.py，配置以下个路径：

   • INPUT_IMAGE_DIR: 您存放图片的文件夹路径。
   • OUTPUT_NPY_DIR: 生成npy格式的校准文件的输出路径。
   • OUTPUT_BIN_DIR: 生成bin格式的校准文件的输出路径。

   然后执行脚本：

   python generate_calibra_data.py

   脚本将生成两个子文件夹：

   • calib_npy: 存放 .npy 格式的校准数据，推荐用于 S100。
   • calib_bin: 存放 .bin 格式的校准数据，推荐用于 RDK X5 (理论上也兼容S100)。

第5步：执行PTQ量化

一切准备就绪，现在可以使用地平线官方工具链进行最终的量化。

请注意重要‼

尽管SmolVLM2的500M和256M尺寸模型使用visual encoder Siglip规格一致，但是由于训练时都需要激活Siglip的参数一起训练，所以500M和256M模型的视觉部分onnx要分别导出并进行PTQ量化，
不是说我导出了一个500M的siglip.bin,256M的模型就也可以一起使用的

• 对于 RDK X5 平台：

  使用 hb_mapper 工具和 siglip_smolvlm_x5.yaml 配置文件。

  hb_mapper makertbin --config siglip_smolvlm_x5.yaml --model-type onnx

  记得进入配置文件siglip_smolvlm_x5.yaml，修改其中的onnx模型路径，以及校验数据路径。
  成功后将生成用于RDK X5部署的 .bin 文件。

• 对于 S100 平台：

  使用 hb_compile 工具和 siglip_smolvlm_S100.yaml 配置文件。

  hb_compile -c siglip_smolvlm_S100.yaml

  记得进入配置文件siglip_smolvlm_S100.yaml，修改其中的onnx模型路径，以及校验数据路径。
  成功后将生成用于S100部署的 .hbm 文件。

💡 性能提示

完整的PTQ量化过程耗时较长（可能需要3小时左右）。如果您只是想快速验证整个流程是否能跑通，可以在编译命令中加入 --fast-pref 参数（请参考地平线官方文档），这将大大缩短编译时间。

🙏 致谢

• 感谢 Hugging Face 团队开源了强大的 Transformers 库，并提供了SmolVLM 的研究者们如此优秀且小巧的视觉语言模型。
• 感谢 地瓜机器人（D-Robotics） 和 地平线（Horizon Robotics） 提供了高效的AI芯片和配套的开发工具链。

📜 许可证

本项目采用 Apache License 2.0 许可证。