C-RADIOv2-G 昇腾 NPU 适配部署文档

模型: C-RADIOv2-G (NVIDIA RADIO 视觉基础模型，~1.6B 参数)
硬件: Huawei Ascend NPU (Atlas 800 A2)
状态: ✅ 已适配，精度验证通过

1. 简介

本文档记录 C-RADIOv2-G 在华为昇腾 NPU 上的推理适配与精度验证结果。

C-RADIOv2-G 是基于 ViT-bigG (patch14, embed_dim=1664, depth=48) 的视觉基础模型，可输出图像级别的 summary 特征与空间级别的 spatial 特征，适用于图像分类、语义分割、深度估计及多模态 LLM 的视觉编码器等下游任务。

相关获取地址：

• 权重下载地址（ModelScope）：https://modelscope.cn/models/nv-community/C-RADIOv2-G
• 权重下载地址（HuggingFace）：https://huggingface.co/nvidia/C-RADIOv2-g
• 原始项目（GitCode）：https://gitcode.com/zhaortiang/C-RADIOv2-G_npu

2. 验证环境

• NPU：Ascend910_9362 (2 逻辑卡)
• 操作系统：Linux 5.10.0 (aarch64)
• 数据类型：float32

3. 快速开始

3.1 安装依赖

pip install -r requirements.txt

3.2 下载模型权重

从 ModelScope 或 HuggingFace 镜像下载：

# ModelScope
modelscope download --model nv-community/C-RADIOv2-G --local_dir ./model_cache/nv-community/C-RADIOv2-G

# 或 HuggingFace 镜像
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download nv-community/C-RADIOv2-G --local-dir ./model_cache/nv-community/C-RADIOv2-G

权重共约 7GB，请确保磁盘空间充足。

3.3 运行推理

python3 inference.py

预期输出：

============================================================
C-RADIOv2-G 昇腾 NPU 推理
============================================================
PyTorch:   2.9.0+cpu
torch_npu: 2.9.0.post1+gitee7ba04
NPU 数量:  2
使用设备:  npu:0
模型目录:  /opt/atomgit/model_cache/nv-community/C-RADIOv2-G
Backbone:  vit_bigG_patch14_224
状态: 创建模型...
No pretrained configuration specified for vit_bigG_patch14 model. Using a default. Please add a config to the model pretrained_cfg registry or pass explicitly.
状态: 加载 safetensors 权重...
[INFO]   model-00001-of-00002.safetensors
[INFO]   model-00002-of-00002.safetensors
[INFO] 已加载 678 个张量
[INFO] pos_embed 插值: (1, 16384, 1664) -> (1, 21316, 1664)
[INFO] cls_token 适配: (9, 1664) -> (8, 1664)
状态: 切换到推理模式...
总参数: 1632.5M
设备: npu:0

输入形状: (1, 3, 224, 224)
状态: 预热推理 (3 iter)...
摘要特征:  (1, 3328)
空间特征:  (1, 1664, 16, 16)  (NCHW 格式)

============================================================
✓ C-RADIOv2-G 已在昇腾 NPU 上成功运行！
============================================================

4. 推理步骤

4.1 代码逻辑概要

inference.py 的执行流程：

1. 读取配置 — 使用 AutoConfig.from_pretrained() 加载模型配置
2. 修正 backbone — 权重实际对应 vit_bigG_patch14_224 (embed_dim=1664, patch_size=14)，脚本自动将配置中的 vit_giant_patch16_224 修正为匹配的 backbone
3. 创建模型 — 使用 AutoModel.from_config() 构建 RADIOModel 实例
4. 加载权重 — 读取 safetensors 分片，逐参数赋值（绕过 PyTorch load_state_dict 中 LayerScale._load_from_state_dict 的 KeyError bug）
5. 适配特殊层 — 对 pos_embed 进行形状插值，裁剪 cls_token 以匹配配置中的 patch 数
6. 推理部署 — 调用 model.switch_to_deploy() 切换到推理模式，移至 NPU
7. 前向计算 — 执行一次带预热的推理，输出 Summary 和 Spatial 特征

4.2 关键适配点

5. 精度验证

项目提供了自动化精度验证脚本 verify_accuracy.py，对比 CPU 和 NPU 的推理结果，计算误差指标。

5.1 运行验证

python3 verify_accuracy.py

5.2 验证流程

1. 在 CPU 上构建模型 + 推理（作为精度基准）
2. 在 NPU 上构建模型 + 推理（携带 3 次预热）
3. 逐分量计算余弦相似度、MSE、MAE、最大绝对误差、相对 L2 误差
4. 生成 JSON 报告 + 日志文件到 eval_logs/ 目录

5.3 精度判定标准

6. 验证结果

6.1 环境

6.2 CPU vs NPU 精度对比

224 × 224

378 × 378

448 × 448

6.3 性能对比

6.4 结论

✓ 精度验证通过。 所有测试分辨率下 Summary 和 Spatial 特征的余弦相似度均 > 0.99999，相对误差远低于 1% 阈值，NPU 推理相对 CPU 加速约 577~887 倍。

7. GPU 直接精度对比

经公开网络检索，目前 未检索到 C-RADIOv2-G 在 GPU 平台上与 CPU 的直接 embedding 精度对比数据（如余弦相似度、MSE、相对 L2 误差等逐层/逐输出量化指标）。

公开资料中可获取的信息包括：

• NVIDIA NGC Catalog 显示 C-RADIOv2 系列在 ImageNet 上的 Top-1/Top-5 精度（其中 C-RADIOv2-G 的具体数值未在检索到的页面中完整展示）。
• C-RADIOv2-G 的 GPU 推理验证硬件为 NVIDIA A100，支持 BF16、FP8、FP4 等多种精度模式。
• 下游 VLM（如 Nemotron Nano V2 VL）中使用 C-RADIOv2 编码器时，FP8 精度下的精度损失被描述为 "negligible"。

因此，本 README 中暂无法提供与 GPU 的直接精度对比数据。 如需 GPU 基线，建议在相同输入与相同 FP32 数据类型下，使用 NVIDIA A100/H100 运行 verify_accuracy.py 的 GPU 版本进行补充验证。

8. 项目结构

C-RADIOv2-G-npu/
├── inference.py          # 昇腾 NPU 推理脚本（主入口）
├── verify_accuracy.py    # CPU vs NPU 精度验证脚本
├── README.md             # 部署文档（本文档）
├── requirements.txt      # Python 依赖
├── .gitignore            # Git 忽略规则
└── eval_logs/            # 验证结果输出目录
    ├── report_*.json     # JSON 格式验证报告
    └── eval_*.log        # 详细日志

9. 注意事项

9.1 BF16 混合精度限制

当前 CANN 8.5.1 的 aclnnLayerNorm 算子在某些场景下对 BF16 权重与 FP32 输入的混合精度支持存在限制，可能报错：

Expected both tensors to have same dtype, but found weightOptional DT_BFLOAT16 and input DT_FLOAT

建议：当前版本优先使用 FP32 推理，或确保模型与输入统一为同一数据类型（均为 BF16 或均为 FP32）。

9.2 模型加载注意事项

• 必须设置 trust_remote_code=True
• 输入分辨率须为 patch_size (14) 的整数倍
• 模型权重文件较大（~7GB），加载时 NPU 显存占用约 6.5 GB（FP32）

9.3 OOM 处理

若出现显存不足：

• 改用 torch.bfloat16 减小显存占用（需验证精度）
• 减小输入分辨率
• 推理后及时 del model 并调用 torch.npu.empty_cache()

License

本项目基于原始模型 nvidia/C-RADIOv2-g 的 License 进行分发，仅包含昇腾适配代码和部署文档。