Phikon-v2 on Ascend NPU

1. 简介

本文档记录 owkin/phikon-v2 在昇腾 910B4 NPU 上的适配与验证结果。

Phikon-v2 是 Owkin 发布的病理学基础模型，基于 DINOv2 ViT-Large 架构在 PANCAN-XL 数据集上预训练，专为组织病理学图像特征提取设计，广泛用于生物标志物预测、WSI 分类等下游任务。

属性	规格
架构	DINOv2 ViT-Large (ViT-L/16)
参数量	~303M
输入尺寸	224 × 224 RGB
输出维度	1024-dim 特征向量 (CLS token + LayerNorm)
权重格式	Safetensors (~1.2GB)

2. 验证环境

组件	版本
`CANN`	`8.5.1`
`torch`	`2.9.0+cpu`
`torch-npu`	`2.9.0.post1+gitee7ba04`
`transformers`	`4.57.6`

NPU：910B4 单卡
模型路径：../weight/phikon-v2
操作系统：Linux aarch64

3. 权重下载

使用 atomgit 命令行工具从 AtomGit 社区下载权重：

pip install atomgit
python3 -m atomgit download hf_mirrors/owkin/phikon-v2 -d ./weight/phikon-v2

下载完成后目录结构示例：

weight/phikon-v2/
├── config.json
├── model.safetensors          # ~1.2GB
├── preprocessor_config.json
└── README.md

4. 快速开始

4.1 安装依赖

pip install -r requirements.txt

依赖清单：

torch>=2.0.0
torch-npu>=2.9.0
transformers>=4.30.0
numpy>=1.24.0
Pillow>=9.0.0

4.2 单图推理

python inference.py \
  --model_path ../weight/phikon-v2 \
  --device npu \
  --batch_size 1 \
  --output output_features.npy

4.3 批量推理

python inference.py \
  --model_path ../weight/phikon-v2 \
  --device npu \
  --batch_size 8 \
  --output output_features.npy

[INFO] Loading model from: ../weight/phikon-v2
[INFO] Target device: npu:0
Using a slow image processor as `use_fast` is unset and a slow processor was saved with this model. `use_fast=True` will be the default behavior in v4.52, even if the model was saved with a slow processor. This will result in minor differences in outputs. You'll still be able to use a slow processor with `use_fast=False`.
[INFO] Model loaded successfully
[INFO] No image provided, using random generated images
[INFO] Warming up (3 iterations)...
[INFO] Running inference...
[INFO] Inference completed in 53.38 ms
[INFO] Output shape: (8, 1024)
[INFO] Output dtype: float32
[INFO] Feature sample (first 10 dims): [ 0.30236924 -0.04790726 -0.60215485  0.74291444 -0.04013106  0.09236915
  0.1826123  -0.8327827   0.02285304  1.00131   ]
[INFO] Features saved to: output_features.npy
[INFO] Metadata saved to: output_features.json

4.4 使用自定义图片

python inference.py \
  --model_path ../weight/phikon-v2 \
  --device npu \
  --image_path /path/to/tile.png \
  --batch_size 1 \
  --output output_features.npy

5. 推理脚本说明

inference.py 支持以下参数：

参数	说明	默认值
`--model_path`	本地模型目录路径	`../weight/phikon-v2`
`--device`	推理设备：`cpu` 或 `npu`	`npu`
`--image_path`	输入图像路径（为空则使用随机图）	`None`
`--batch_size`	推理批次大小	`1`
`--output`	输出特征文件路径	`output_features.npy`
`--warmup`	Warmup 迭代次数	`3`

输出文件：

output_features.npy：numpy 数组，shape 为 (batch_size, 1024)
output_features.json：推理元数据（设备、batch_size、耗时等）

6. 精度评测

6.1 评测方法

使用 eval_precision.py 对同一批随机图像分别在 CPU 和 NPU 上推理，对比输出特征向量的：

余弦相似度 (Cosine Similarity)
平均绝对误差 (MAE)
均方误差 (MSE)
最大绝对误差 (Max AE)

6.2 运行命令

python eval_precision.py \
  --model_path ../weight/phikon-v2 \
  --batch_size 8 \
  --rounds 5

6.3 评测结果

测试条件：batch_size=8，rounds=5，随机生成 224×224 RGB 图像。

指标	数值
`cosine_similarity`	`0.999998`
`MAE`	`1.044e-03`
`MSE`	`5.909e-06`
`Max AE`	`5.556e-02`

结论：NPU 输出与 CPU 参考输出高度一致，余弦相似度达到 0.999998，满足精度要求。

7. 性能参考

7.1 测试方法

使用 eval_performance.py 在 NPU 上测试不同 batch size 下的推理延迟与吞吐。

python eval_performance.py \
  --device npu \
  --batch_sizes 1 8 32 \
  --iterations 50 \
  --warmup 10

7.2 性能结果

测试条件：NPU 910B4，warmup=10，iterations=50。

batch_size	mean_latency_ms	p99_latency_ms	throughput_imgs/sec
`1`	`24.55`	`25.78`	`40.73`
`8`	`26.91`	`27.91`	`297.25`
`32`	`96.13`	`96.34`	`332.89`

结论：

单图推理延迟约 24.6ms，满足实时特征提取需求。
batch=8 时吞吐接近 300 imgs/sec，适合中等并发场景。
batch=32 时吞吐达到 ~333 imgs/sec，适合大规模离线处理。

8. 注意事项

首次推理耗时较长：NPU 首次运行需要执行图编译（ACL Graph），warmup 阶段请预留足够时间。
随机图像 vs 真实病理图：本验证使用随机生成的 224×224 图像作为输入；实际部署时请替换为真实的病理切片 tile。
LayerNorm 后处理：Phikon-v2 在 CLS token 后额外应用了 LayerNorm (apply_layernorm=true)，推理脚本已自动处理，无需手动干预。
NPU 显存占用：batch=32 时约占用 2.8GB HBM，请根据实际硬件调整 batch size。
CPU 基准对比：本环境 CPU 为 ARM 架构，运行 ViT-Large 模型较慢（约 50s/round），精度对比时 NPU 优势明显。

9. 目录结构

phikon-v2-ascend/
├── inference.py              # 推理脚本
├── eval_precision.py         # 精度评测脚本
├── eval_performance.py       # 性能评测脚本
├── requirements.txt          # Python 依赖
├── readme.md                 # 本文档
├── logs/                     # 运行日志
├── images/                   # 截图/示例图
└── .gitignore                # Git 忽略规则

10. 许可证

模型权重遵循 Owkin 原始许可证（非商业用途）。本适配脚本采用 MIT 许可证。