timm/vit_small_patch16_dinov3.lvd1689m on Ascend NPU

1. 简介

本文档记录 timm/vit_small_patch16_dinov3.lvd1689m 在 Ascend NPU 环境的推理适配与验证结果。该模型为 TIMM (PyTorch Image Models) 库收录的 DINOv3 ViT-S/16 变体，基于 timm 库直接加载推理，通过 runtime monkey-patch 方式将 torch.cuda 调用透明转发至 torch.npu，无需修改原始模型代码即可完成 NPU 适配。

与 transformers 版本的 facebook/dinov3-vits16 相比，TIMM 版本默认输入尺寸为 256x256，全局池化策略为 avg，输出维度一致为 384。

2. 权重下载方式

推荐使用以下方式下载模型权重：

AtomGit 下载

python3 -m atomgit download hf_mirrors/timm/vit_small_patch16_dinov3.lvd1689m -d /opt/atomgit/weight/vit_small_patch16_dinov3.lvd1689m

下载完成后，目录下应包含 pytorch_model.bin（或 model.safetensors）及 config.json 等文件。

3. 环境依赖安装

在运行验证脚本前，请确保已安装以下依赖：

pip install torch==2.9.0+cpu timm
pip install torch-npu==2.9.0.post1

torch 与 torch-npu 版本需与当前 CANN 版本匹配
timm 用于加载 TIMM 模型与图像预处理

4. 验证环境

组件	版本
`Python`	`3.11.14`
`PyTorch`	`2.9.0+cpu`
`torch-npu`	`2.9.0.post1+gitee7ba04`
`timm`	`1.0.27`
`CANN`	`8.0.RC2`

NPU：2 逻辑卡（Ascend910）
模型路径：/opt/atomgit/weight/vit_small_patch16_dinov3.lvd1689m

5. 推理验证

运行单图特征提取推理，验证模型在 NPU 上的基础前向传播能力。

推理使用的样本图片：

sample_image

python3 inference.py

验证输出：

[INFO] Applied NPU monkey-patch (torch.cuda -> torch.npu)
[INFO] Loading image from: /opt/atomgit/vit_small_patch16_dinov3.lvd1689m/data/val2017/000000000139.jpg
[INFO] Loading model: vit_small_patch16_dinov3.lvd1689m
[INFO] Model moved to NPU device: Ascend910_9362
[INFO] Input shape: torch.Size([1, 3, 256, 256])
[INFO] Device: npu:0
[INFO] Warm-up inference...
[INFO] Running timed inference...

============================================================
Inference Results
============================================================
Device:        NPU (Ascend910_9362)
Latency:       17.09 ms
Pooled output shape:   torch.Size([1, 384])
Features shape:        torch.Size([1, 261, 384])
Pooled output dtype:   torch.float32
Pooled output device:  npu:0
Pooled output first 5 values: [-0.11498719  0.5135      0.2316902  -0.56788355 -0.16675997]
============================================================

验证结论：

模型成功加载至 NPU 设备
单张 256x256 图像推理延迟约 17.09 ms（首次加载含图编译开销）
输出特征维度符合预期（pooled [1, 384]，features [1, 261, 384]）
261 个 token 对应 1 cls + 4 registers + 256 patches（256/16 = 16，16x16 = 256）

6. 性能评测

使用 benchmark.py 对 NPU 推理进行延迟与吞吐量压测：

python3 benchmark.py

6.1 延迟测试结果

指标	数值
`iterations`	`20`
`mean_ms`	`7.93 ms`
`stddev_ms`	`0.29 ms`
`min_ms`	`7.58 ms`
`max_ms`	`8.40 ms`
`p50_ms`	`7.75 ms`
`p90_ms`	`8.33 ms`
`p99_ms`	`8.40 ms`

6.2 吞吐量测试结果

batch_size	throughput_ips	avg_latency_ms
`1`	`127.76`	`7.83`
`2`	`255.19`	`7.84`
`4`	`509.84`	`7.85`
`8`	`1005.98`	`7.95`

验证结论：

稳定态单图平均延迟约 ~8 ms
Batch=8 时吞吐达到 1005.98 images/sec，突破千张/秒
小 batch 场景下延迟几乎无增长，适合高并发实时特征提取

7. 精度评测

使用 accuracy.py 对 NPU 输出与 CPU 基线进行精度对比，评估指标为向量级相对误差与余弦相似度：

python3 accuracy.py

验证输出：

============================================================
Accuracy Validation Results
============================================================

pooled_output:
  Shape:                  (1, 384)
  Vector Relative Error:  0.001530 (PASS)
  Cosine Similarity:      0.999999 (PASS)
  MSE:                    0.0000001818
  Max Absolute Diff:      0.001186
  Overall:                PASS

features:
  Shape:                  (1, 261, 384)
  Vector Relative Error:  0.001713 (PASS)
  Cosine Similarity:      0.999998 (PASS)
  MSE:                    0.0000004136
  Max Absolute Diff:      0.003734
  Overall:                PASS

============================================================
OVERALL: PASS (vector-level relative error < 1% and cosine similarity > 0.999)
============================================================

指标	数值	阈值	结果
Pooled Output 向量相对误差	`0.15%`	`< 1%`	PASS
Pooled Output 余弦相似度	`0.999999`	`> 0.999`	PASS
Features 向量相对误差	`0.17%`	`< 1%`	PASS
Features 余弦相似度	`0.999998`	`> 0.999`	PASS

验证结论：

NPU 输出与 CPU 基线精度误差均 < 1%
余弦相似度均 > 0.999，特征空间一致性极高
整体精度验证通过

8. 注意事项

Monkey-patch 适配方式：当前采用运行时 torch.cuda -> torch.npu monkey-patch 实现适配，无需修改 timm 源码。若后续 timm 版本内部硬编码了 CUDA 特定调用，可能需要更新 patch 范围。
TORCH_COMPILE_DISABLE：脚本中已设置 TORCH_COMPILE_DISABLE=1，避免 torch.compile 在 NPU 上引发兼容问题。
输入尺寸差异：TIMM 版 DINOv3 ViT-S/16 默认输入尺寸为 256x256（transformers 版为 224x224），预处理参数通过 timm.data.resolve_model_data_config 自动解析，无需手动指定。
输出格式差异：TIMM 版 forward() 返回全局池化后的 [1, 384] 特征向量；forward_features() 返回完整的 [1, 261, 384] patch tokens（含 cls 与 register tokens）。若需与 transformers 版对齐，注意 token 数量差异（261 vs 201）源于输入分辨率不同。
本地权重加载：由于 TIMM 模型首次运行会自动从 HuggingFace Hub 下载，本脚本通过 pretrained=False + load_state_dict() 实现纯本地加载，适配离线环境。
输出产物：inference.py、benchmark.py、accuracy.py 的运行结果均保存至 output/ 目录，包含 JSON 结构化数据与文本日志，便于后续自动化采集。

timm/vit_small_patch16_dinov3.lvd1689m on Ascend NPU

1. 简介

与 transformers 版本的 facebook/dinov3-vits16 相比，TIMM 版本默认输入尺寸为 256x256，全局池化策略为 avg，输出维度一致为 384。

2. 权重下载方式

推荐使用以下方式下载模型权重：

AtomGit 下载

python3 -m atomgit download hf_mirrors/timm/vit_small_patch16_dinov3.lvd1689m -d /opt/atomgit/weight/vit_small_patch16_dinov3.lvd1689m

下载完成后，目录下应包含 pytorch_model.bin（或 model.safetensors）及 config.json 等文件。

3. 环境依赖安装

在运行验证脚本前，请确保已安装以下依赖：

pip install torch==2.9.0+cpu timm
pip install torch-npu==2.9.0.post1

torch 与 torch-npu 版本需与当前 CANN 版本匹配
timm 用于加载 TIMM 模型与图像预处理

4. 验证环境

组件	版本
`Python`	`3.11.14`
`PyTorch`	`2.9.0+cpu`
`torch-npu`	`2.9.0.post1+gitee7ba04`
`timm`	`1.0.27`
`CANN`	`8.0.RC2`

NPU：2 逻辑卡（Ascend910）
模型路径：/opt/atomgit/weight/vit_small_patch16_dinov3.lvd1689m

5. 推理验证

运行单图特征提取推理，验证模型在 NPU 上的基础前向传播能力。

推理使用的样本图片：

sample_image

python3 inference.py

验证输出：

[INFO] Applied NPU monkey-patch (torch.cuda -> torch.npu)
[INFO] Loading image from: /opt/atomgit/vit_small_patch16_dinov3.lvd1689m/data/val2017/000000000139.jpg
[INFO] Loading model: vit_small_patch16_dinov3.lvd1689m
[INFO] Model moved to NPU device: Ascend910_9362
[INFO] Input shape: torch.Size([1, 3, 256, 256])
[INFO] Device: npu:0
[INFO] Warm-up inference...
[INFO] Running timed inference...

============================================================
Inference Results
============================================================
Device:        NPU (Ascend910_9362)
Latency:       17.09 ms
Pooled output shape:   torch.Size([1, 384])
Features shape:        torch.Size([1, 261, 384])
Pooled output dtype:   torch.float32
Pooled output device:  npu:0
Pooled output first 5 values: [-0.11498719  0.5135      0.2316902  -0.56788355 -0.16675997]
============================================================

验证结论：

模型成功加载至 NPU 设备
单张 256x256 图像推理延迟约 17.09 ms（首次加载含图编译开销）
输出特征维度符合预期（pooled [1, 384]，features [1, 261, 384]）
261 个 token 对应 1 cls + 4 registers + 256 patches（256/16 = 16，16x16 = 256）

6. 性能评测

使用 benchmark.py 对 NPU 推理进行延迟与吞吐量压测：

python3 benchmark.py

6.1 延迟测试结果

指标	数值
`iterations`	`20`
`mean_ms`	`7.93 ms`
`stddev_ms`	`0.29 ms`
`min_ms`	`7.58 ms`
`max_ms`	`8.40 ms`
`p50_ms`	`7.75 ms`
`p90_ms`	`8.33 ms`
`p99_ms`	`8.40 ms`

6.2 吞吐量测试结果

batch_size	throughput_ips	avg_latency_ms
`1`	`127.76`	`7.83`
`2`	`255.19`	`7.84`
`4`	`509.84`	`7.85`
`8`	`1005.98`	`7.95`

验证结论：

稳定态单图平均延迟约 ~8 ms
Batch=8 时吞吐达到 1005.98 images/sec，突破千张/秒
小 batch 场景下延迟几乎无增长，适合高并发实时特征提取

7. 精度评测

使用 accuracy.py 对 NPU 输出与 CPU 基线进行精度对比，评估指标为向量级相对误差与余弦相似度：

python3 accuracy.py

验证输出：

============================================================
Accuracy Validation Results
============================================================

pooled_output:
  Shape:                  (1, 384)
  Vector Relative Error:  0.001530 (PASS)
  Cosine Similarity:      0.999999 (PASS)
  MSE:                    0.0000001818
  Max Absolute Diff:      0.001186
  Overall:                PASS

features:
  Shape:                  (1, 261, 384)
  Vector Relative Error:  0.001713 (PASS)
  Cosine Similarity:      0.999998 (PASS)
  MSE:                    0.0000004136
  Max Absolute Diff:      0.003734
  Overall:                PASS

============================================================
OVERALL: PASS (vector-level relative error < 1% and cosine similarity > 0.999)
============================================================

指标	数值	阈值	结果
Pooled Output 向量相对误差	`0.15%`	`< 1%`	PASS
Pooled Output 余弦相似度	`0.999999`	`> 0.999`	PASS
Features 向量相对误差	`0.17%`	`< 1%`	PASS
Features 余弦相似度	`0.999998`	`> 0.999`	PASS

验证结论：

NPU 输出与 CPU 基线精度误差均 < 1%
余弦相似度均 > 0.999，特征空间一致性极高
整体精度验证通过

8. 注意事项

Monkey-patch 适配方式：当前采用运行时 torch.cuda -> torch.npu monkey-patch 实现适配，无需修改 timm 源码。若后续 timm 版本内部硬编码了 CUDA 特定调用，可能需要更新 patch 范围。
TORCH_COMPILE_DISABLE：脚本中已设置 TORCH_COMPILE_DISABLE=1，避免 torch.compile 在 NPU 上引发兼容问题。
输入尺寸差异：TIMM 版 DINOv3 ViT-S/16 默认输入尺寸为 256x256（transformers 版为 224x224），预处理参数通过 timm.data.resolve_model_data_config 自动解析，无需手动指定。
输出格式差异：TIMM 版 forward() 返回全局池化后的 [1, 384] 特征向量；forward_features() 返回完整的 [1, 261, 384] patch tokens（含 cls 与 register tokens）。若需与 transformers 版对齐，注意 token 数量差异（261 vs 201）源于输入分辨率不同。
本地权重加载：由于 TIMM 模型首次运行会自动从 HuggingFace Hub 下载，本脚本通过 pretrained=False + load_state_dict() 实现纯本地加载，适配离线环境。
输出产物：inference.py、benchmark.py、accuracy.py 的运行结果均保存至 output/ 目录，包含 JSON 结构化数据与文本日志，便于后续自动化采集。