本文档记录 dinov3-vits16-pretrain-lvd1689m 在昇腾 NPU（Ascend 910B3）环境的适配部署与精度验证结果。
DINOv3 ViT-Small（ViT-S/16）是一种轻量级视觉基础模型，参数量约 21.6M，输出图像特征向量可用于图像分类、检索、分割等下游任务。本项目完成该模型在昇腾 NPU 上的推理适配，并验证 NPU 与 CPU 推理结果的精度误差 < 1%。
相关地址：
| 组件 | 版本 |
|---|---|
| Python | 3.11.15 |
| PyTorch | 2.10.0+cpu |
| torch_npu | 2.10.0 |
| transformers | 5.8.1 |
| CANN | 8.5.1 |
| NPU 驱动 | 25.5.2 |
| NPU 硬件 | Ascend 910B3 (8卡) |
| 操作系统 | Linux (aarch64) |
| 项目 | 值 |
|---|---|
| 模型架构 | DINOv3ViTModel |
| 参数量 | ~21.6M |
| Hidden Size | 384 |
| Layers | 12 |
| Attention Heads | 6 |
| Patch Size | 16 |
| 输入尺寸 | 3×224×224 |
| 输出 pooler_output | (1, 384) |
| 输出 last_hidden_state | (1, 201, 384) |
| 权重格式 | safetensors |
| 原始框架 | PyTorch |
创建独立的 conda 环境并安装依赖（使用华为云 PyPI 镜像加速）：
# 创建 conda 环境
conda create -n dinov3-vits16-pretrain-lvd1689m python=3.11 -y
# 激活环境
conda activate dinov3-vits16-pretrain-lvd1689m
# 安装 PyTorch 及相关依赖（华为云镜像）
pip install torch==2.10.0 torchvision==0.25.0 --index-url https://repo.huaweicloud.com/repository/pypi/simple/
# 安装 torch_npu（根据环境选择对应版本）
pip install torch_npu==2.10.0 --index-url https://repo.huaweicloud.com/repository/pypi/simple/
# 安装 transformers 及其他依赖
pip install transformers safetensors pillow --index-url https://repo.huaweicloud.com/repository/pypi/simple/如果 HuggingFace 网络不通，设置镜像：
export HF_ENDPOINT=https://hf-mirror.com/# NPU 推理（默认）
python3 inference.py \
--model_path /path/to/dinov3-vits16-pretrain-lvd1689m \
--image_path /path/to/image.jpg \
--device npu:0
# CPU 推理
python3 inference.py \
--model_path /path/to/dinov3-vits16-pretrain-lvd1689m \
--image_path /path/to/image.jpg \
--device cpu# 自动生成测试图像，对比 NPU 与 CPU 推理精度
python3 eval.py \
--model_path /path/to/dinov3-vits16-pretrain-lvd1689m \
--npu_device npu:0评测结果日志将输出到 log.txt。
| 参数 | 说明 | 默认值 |
|---|---|---|
--model_path | 模型权重路径（包含 config.json, model.safetensors） | 必需 |
--image_path | 输入图像路径 | 必需 |
--device | 运行设备，可选 npu:0 或 cpu | npu:0 |
--no_warmup | 跳过预热阶段 | False |
--warmup_image | 预热用图像路径 | 同 --image_path |
| 参数 | 说明 | 默认值 |
|---|---|---|
--model_path | 模型权重路径 | 模型路径 |
--image_path | 测试图像路径（默认自动生成） | 自动生成 |
--npu_device | NPU 设备 ID | npu:0 |
--num_warmup | NPU 预热轮数 | 3 |
精度验证使用同一张图像分别在 CPU 和 NPU 上运行推理，比较 pooler_output 和 last_hidden_state 的输出差异。
评价指标：
|NPU - CPU| / |CPU|（逐元素），要求最大值 < 1%| 输出 | 向量级相对误差 (%) | 余弦相似度 | 最大绝对误差 | 平均绝对误差 |
|---|---|---|---|---|
| pooler_output | 0.248442 | 0.9999968410 | 3.61e-03 | 9.26e-04 |
| last_hidden_state | 0.223244 | 0.9999989271 | 4.18e-03 | 6.98e-04 |
| 指标 | 实测值 | 阈值 | 状态 |
|---|---|---|---|
| 向量级相对误差 | 0.25% | < 1% | PASS |
| 余弦相似度 | 0.999997 | > 0.99 | PASS |
| 操作 | 耗时 |
|---|---|
| CPU 推理时间 | 5.14s |
| NPU 推理时间（预热后） | 0.23s |
| 加速比 | 22.03x |
| 指标 | 值 |
|---|---|
| 模型参数量 | ~21.6M |
| 推理时间 (CPU, FP32) | 5.14s |
| 推理时间 (NPU, FP32) | 0.23s |
| 加速比 | 22.03x |