VTP-Large-f16d64 on Ascend NPU (torch_npu)

1. 简介

本文档记录 VTP-Large-f16d64（MiniMax 视觉分词器预训练模型）在华为昇腾 Ascend910B4 上的适配、推理与精度性能验证结果。

VTP（Visual Tokenizer Pre-training）是一个统一视觉分词器预训练框架，联合优化图像-文本对比学习、自监督学习和重建损失。该模型支持三种使用模式：

• Auto-Encoder 图像重建（rFID=0.36）
• CLIP Zero-shot 分类（Zero-shot Acc=78.2）
• SSL 特征提取（Linear Probing=85.7）

相关获取地址：

• 权重下载地址（HuggingFace）：https://huggingface.co/MiniMaxAI/VTP-Large-f16d64
• 权重下载地址（HuggingFace 镜像）：https://hf-mirror.com/MiniMaxAI/VTP-Large-f16d64
• 原始代码仓库（GitHub）：https://github.com/MiniMax-AI/VTP
• 技术论文：https://arxiv.org/abs/2512.13687

2. 验证环境

• NPU：1 逻辑卡 Ascend910B4
• 模型路径：/opt/atomgit/VTP-Large-f16d64
• CANN：8.5.1

3. 环境准备

3.1 安装依赖

# 使用华为源加速
pip install -i https://repo.huaweicloud.com/repository/pypi/simple \
  torch torchvision torch_npu transformers \
  omegaconf tqdm timm scipy pytorch_fid pillow

3.2 获取 VTP 源码

git clone https://github.com/MiniMax-AI/VTP.git --depth 1

推理时将 VTP 源码路径加入 sys.path（inference.py 已通过 ../VTP 相对路径自动处理）。

3.3 下载模型权重

# 方式一：HuggingFace
git lfs clone https://huggingface.co/MiniMaxAI/VTP-Large-f16d64

# 方式二：HuggingFace 镜像（国内推荐）
git lfs clone https://hf-mirror.com/MiniMaxAI/VTP-Large-f16d64

# 方式三：ModelScope
git lfs clone https://modelscope.cn/models/MiniMaxAI/VTP-Large-f16d64

4. 推理测试

4.1 快速启动

cd /opt/atomgit/VTP-Large-f16d64

# 全部模式（重建 + CLIP + 特征提取）
python3 inference.py --mode all

# 仅重建
python3 inference.py --mode reconstruction

# 仅 CLIP Zero-shot
python3 inference.py --mode clip

# 仅特征提取
python3 inference.py --mode feature

# 指定自定义图像
python3 inference.py --mode all --image /path/to/your/image.png

4.2 验证结果

基础检查：

• 模型成功加载到 NPU（Ascend910B4）
• 参数量：Vision Encoder = 303.5M，Pixel Decoder = 303.6M，Text Encoder = 85.1M
• 各模式均可正常推理

4.3 性能参考（Warm 状态）

测试条件：单张 256×256 图像输入，单卡 Ascend910B4，Warm-up 后取 3 次平均。

5. 精度评测

使用本目录下的 accuracy_run_perf.py 对 NPU 输出与 CPU 输出进行逐层对比，计算相对误差（百分比）。

运行命令：

cd /opt/atomgit/VTP-Large-f16d64/VTP-Large-f16d64-ascend
python3 accuracy_run_perf.py --model_dir /opt/atomgit/VTP-Large-f16d64 --warmup_iters 2 --bench_iters 10

5.1 精度结果

5.2 结论

• 最终输出（重建图像、CLIP 特征、CLS Token）全部 < 1%：PASS ✅
• 内部中间层（latents、patch_tokens、intermediate features）误差 > 1%，为 NPU 卷积/bottleneck 算子精度差异导致，不影响模型实际使用效果

6. 适配说明

6.1 昇腾适配要点

1. 设备映射：torch.device("npu:0") 替代 torch.device("cuda:0")。
2. AMP 精度：torch.cuda.amp.autocast() 改为 torch.autocast(device_type="npu")。
3. 模型加载：自定义模型类型 vtp 未注册到 transformers 的 AutoConfig，需直接使用 VTPConfig.from_pretrained() + VTPModel.from_pretrained()。
4. 源码引用：VTP 模型代码以源码方式引用（无 pip 包），通过 sys.path.insert(0, VTP_SRC) 导入。

6.2 推理脚本 (inference.py)

单文件推理脚本，支持三种模式，参数说明：

6.3 精度性能评测脚本 (accuracy_run_perf.py)

自动完成 NPU vs CPU 精度对比和 NPU 性能基准测试，参数说明：

7. 注意事项

1. 模型权重路径：config.json 和 model.safetensors 需在同一目录。
2. VTP 源码依赖：推理需要 VTP 源码仓库（vtp/ 目录），inference.py 通过相对路径 ../VTP 引用，若 VTP 源码在其他位置需修改 VTP_SRC 变量。
3. AMP 精度：torch.autocast 在 Ascend NPU 上使用 device_type="npu"。若遇到精度问题可设置 torch.npu.config.allow_internal_format = False。
4. 首次推理：重建模式的 Encode 阶段（约 8s）包含模型 Warm-up 和 NPU 图编译，后续调用会更快。
5. 图像尺寸：模型输入为 256×256，预处理包含 Resize + Normalize。
6. CPU vs NPU 精度对比：精度评测脚本会分别在 CPU 和 NPU 上加载模型并运行推理，通过逐层输出对比计算相对误差。由于 CPU 推理较慢，建议使用较小的图像或减少 bench_iters。