Introduction

本仓库面向 DINOv3 在 AXERA 芯片（AX650）上的适配，主要提供两类能力：

1. 模型转换链路：从 safetensors 导出 ONNX，再将 ONNX 转换为可部署的 axmodel
2. 推理验证示例：基于 pyaxengine 提供三个独立脚本，帮助开发人员在板端快速确认 axmodel 是否工作正常

仓库目录说明：

• model_convert/ 保存模型转换脚本、依赖说明和 pulsar2 build 配置
• notebooks/ 保存原始 notebook，以及转换后的 pyaxengine 脚本示例
• assets/ 保存示例运行时所需的测试资源缓存

当前仓库围绕以下典型流程组织：

safetensors -> ONNX -> simplified ONNX -> axmodel -> pyaxengine validation

Quick Start

如果你希望最快跑通完整流程，可以直接按下面步骤执行。

1. 安装依赖

pip install -r model_convert/requirements.txt
pip install -r notebooks/requirements.txt

同时确认主机环境已经正确安装 pulsar2。

2. 一键完成模型转换

先修改构建配置文件中的 calibration_dataset，确保它指向当前机器上真实存在的校准数据集路径：

• model_convert/dinov3_vits16_lvd1689m_build_config_precision_tuning.json

如果你还不知道如何修改配置文件，可以参考配置文件详细说明.

MODEL_PATH=/path/to/model.safetensors \
RAW_ONNX_PATH=model_convert/onnx_out/dinov3_vits16_lvd1689m.onnx \
SIM_ONNX_PATH=model_convert/onnx_out/dinov3_vits16_lvd1689m_sim.onnx \
AXMODEL_OUTPUT_DIR=model_convert/onnx_out \
TARGET_HARDWARE=AX650 \
BUILD_CONFIG_PATH=model_convert/dinov3_vits16_lvd1689m_build_config_precision_tuning.json \
bash model_convert/run_pipeline.sh

3. 在主机侧验证 ONNX

按下面顺序打开 notebook 验证导出结果：

1. notebooks/foreground_segmentation_onnxruntime.ipynb
2. notebooks/pca_onnxruntime.ipynb
3. notebooks/dense_sparse_matching_onnxruntime.ipynb

4. 在板端验证 axmodel

将生成的 axmodel 拷贝到AX650设备后，可运行以下脚本验证：

python notebooks/foreground_segmentation_pyaxengine.py --model-path /path/to/compiled.axmodel
python notebooks/pca_pyaxengine.py --model-path /path/to/compiled.axmodel
python notebooks/dense_sparse_matching_pyaxengine.py --model-path /path/to/compiled.axmodel

如果你只关心快速跑通整条链路，建议先看：

• model_convert/run_pipeline.sh
• notebooks/dense_sparse_matching_pyaxengine.py
• notebooks/foreground_segmentation_pyaxengine.py
• notebooks/pca_pyaxengine.py

Export ONNX Guide

这一部分负责把 Hugging Face / DINOv3 的 model.safetensors 导出成静态输入尺寸的 ONNX。

依赖准备

先安装导出、简化和验证阶段的 Python 依赖：

pip install -r model_convert/requirements.txt
pip install -r notebooks/requirements.txt

说明：

• export_safetensors_to_onnx.sh 依赖 torch、transformers、onnx
• simplify_onnx.sh 依赖 onnxruntime、onnxsim
• build_axmodel.sh 依赖本机已正确安装并可执行的 pulsar2。

导出命令

导出脚本：

MODEL_PATH=/path/to/model.safetensors \
bash model_convert/export_safetensors_to_onnx.sh

更常见的使用方式是显式传入模型路径和导出路径：

MODEL_PATH=/path/to/model.safetensors \
ONNX_OUTPUT_PATH=/path/to/dinov3.onnx \
INPUT_HEIGHT=224 \
INPUT_WIDTH=224 \
OPSET_VERSION=17 \
bash model_convert/export_safetensors_to_onnx.sh

关键参数说明：

• MODEL_PATH 指向待导出的 model.safetensors
• ONNX_OUTPUT_PATH 原始 ONNX 输出路径
• INPUT_HEIGHT / INPUT_WIDTH 导出时固定的输入分辨率，当前默认 224 x 224
• OPSET_VERSION 当前默认值为 17

导出结果说明

当前导出的模型包含两个主要输出：

• last_hidden_state patch / token 级输出，适合前景分割、PCA 可视化、稠密匹配等任务
• pooler_output 整图级 embedding 输出

以当前 224 x 224、patch_size=16 的 DINOv3 模型为例，输出通常类似：

Session inputs:
  name=pixel_values, shape=[1, 3, 224, 224], type=float32
Session outputs:
  name=last_hidden_state, shape=[1, 201, 384], type=float32
  name=pooler_output, shape=[1, 384], type=float32

其中 201 个 token 一般由以下部分构成：

• 1 个 CLS token
• 4 个 register tokens
• 196 个 patch tokens

仓库中的 pyaxengine 示例已经兼容这种输出形式，会自动优先选择 last_hidden_state，并在需要时去掉前缀 token。

ONNX 简化

导出完成后，建议执行一次 onnxsim 简化并用 onnxruntime 做结果校验：

INPUT_ONNX_PATH=/path/to/dinov3.onnx \
OUTPUT_ONNX_PATH=/path/to/dinov3_sim.onnx \
ABS_TOL=3e-2 \
REL_TOL=5e-2 \
bash model_convert/simplify_onnx.sh

如果你希望快速跑完导出和简化，也可以直接查看：

• model_convert/export_safetensors_to_onnx.sh
• model_convert/simplify_onnx.sh
• model_convert/README.md

ONNX 验证示例

在转换为 axmodel 之前，建议先用仓库内的 ONNX Runtime notebook 验证导出的 ONNX 是否符合预期。

可参考以下示例：

• notebooks/dense_sparse_matching_onnxruntime.ipynb
• notebooks/foreground_segmentation_onnxruntime.ipynb
• notebooks/pca_onnxruntime.ipynb

建议验证顺序：

1. 先确认 safetensors -> ONNX 导出成功
2. 用上述 notebook 在主机侧验证 ONNX 输出 shape 和可视化结果
3. 再执行 onnxsim 与 pulsar2 build
4. 最后在板端运行 pyaxengine 脚本验证 axmodel

Convert axmodel Guide

这一部分负责把简化后的 ONNX 转成 AXERA 可部署的 axmodel。

单步转换

执行转换脚本：

bash model_convert/build_axmodel.sh

在执行 pulsar2 build 之前，请先检查构建配置文件中的 calibration_dataset 字段。

这个字段通常是一个本地数据集路径，不同开发机和不同项目环境下都不一样，因此不能直接假设仓库里的默认值可用。你必须先把它改成自己机器上真实存在的校准数据集路径，再执行 build_axmodel.sh 或 run_pipeline.sh。

推荐显式指定输入与输出：

INPUT_ONNX_PATH=/path/to/dinov3_sim.onnx \
OUTPUT_DIR=/path/to/axmodel_out \
TARGET_HARDWARE=AX650 \
BUILD_CONFIG_PATH=/path/to/dinov3_build_config.json \
bash model_convert/build_axmodel.sh

该脚本本质上调用的是：

pulsar2 build \
  --target_hardware AX650 \
  --input /path/to/dinov3_sim.onnx \
  --output_dir /path/to/axmodel_out \
  --config /path/to/dinov3_build_config.json

关键参数说明：

• INPUT_ONNX_PATH 经过简化和校验的 ONNX
• OUTPUT_DIR pulsar2 build 输出目录
• TARGET_HARDWARE 目标芯片平台，当前默认 AX650
• BUILD_CONFIG_PATH pulsar2 构建配置文件

配置文件注意事项：

• BUILD_CONFIG_PATH 指向的 JSON 文件中，calibration_dataset 必须按本地环境手动修改
• 如果 calibration_dataset 路径不存在，pulsar2 build 通常会直接失败，或者使用错误的数据做量化校准
• 建议先打开 model_convert/dinov3_vits16_lvd1689m_build_config_precision_tuning.json 确认相关路径

一键跑完整链路

如果你希望从 safetensors 一路生成 axmodel，可以直接执行：

MODEL_PATH=/path/to/model.safetensors \
bash model_convert/run_pipeline.sh

更通用的调用方式：

MODEL_PATH=/path/to/model.safetensors \
RAW_ONNX_PATH=/path/to/dinov3.onnx \
SIM_ONNX_PATH=/path/to/dinov3_sim.onnx \
AXMODEL_OUTPUT_DIR=/path/to/axmodel_out \
TARGET_HARDWARE=AX650 \
BUILD_CONFIG_PATH=/path/to/dinov3_build_config.json \
INPUT_HEIGHT=224 \
INPUT_WIDTH=224 \
OPSET_VERSION=17 \
ABS_TOL=3e-2 \
REL_TOL=5e-2 \
bash model_convert/run_pipeline.sh

这个脚本会依次调用：

• export_safetensors_to_onnx.sh
• simplify_onnx.sh
• build_axmodel.sh

如何验证 axmodel 是否转换成功

仓库提供了 3 个基于 pyaxengine 的示例脚本，主要用于验证板端推理是否正常：

1. 稠密 / 稀疏匹配

python notebooks/dense_sparse_matching_pyaxengine.py \
  --model-path /path/to/compiled.axmodel

2. 前景分割

python notebooks/foreground_segmentation_pyaxengine.py \
  --model-path /path/to/compiled.axmodel

3. PCA 可视化

python notebooks/pca_pyaxengine.py \
  --model-path /path/to/compiled.axmodel

运行特性说明：

• 这三个脚本都已经去掉 torch / torchvision 依赖
• 图片默认优先从 assets/ 读取
• 如果本地缓存不存在，脚本会按 notebook 中原始 URI 下载并缓存到 assets/
• 输出结果会保存在脚本所在目录下的 outputs/ 子目录

如果你希望先在主机环境验证 ONNX，而不是直接在板端验证 axmodel，也可以使用对应的 notebook：

1. notebooks/foreground_segmentation_onnxruntime.ipynb
2. notebooks/pca_onnxruntime.ipynb
3. notebooks/dense_sparse_matching_onnxruntime.ipynb

建议验证顺序：

1. 先运行 foreground_segmentation_pyaxengine.py
2. 再运行 pca_pyaxengine.py
3. 最后运行 dense_sparse_matching_pyaxengine.py

原因：

• pca_pyaxengine.py 默认会读取前景分割脚本产出的 fg_classifier.pkl

如果你只想确认推理接口是否通了，可以在板端重点关注以下几项：

• session.get_inputs() 是否能正确打印输入名和形状
• session.get_outputs() 是否出现 last_hidden_state 与 pooler_output
• session.run(None, {input_name: input_tensor}) 是否能返回稳定输出
• 输出 shape 是否符合预期，例如 last_hidden_state=[1, 201, 384]

相关文件入口：

• model_convert/build_axmodel.sh
• model_convert/run_pipeline.sh
• notebooks/dense_sparse_matching_onnxruntime.ipynb
• notebooks/foreground_segmentation_onnxruntime.ipynb
• notebooks/pca_onnxruntime.ipynb
• notebooks/dense_sparse_matching_pyaxengine.py
• notebooks/foreground_segmentation_pyaxengine.py
• notebooks/pca_pyaxengine.py