C-RADIOv2-B on Ascend NPU
1. 简介
本文档记录 nvidia/C-RADIOv2-B 在昇腾 NPU（Ascend 910B3）环境的适配部署与精度验证结果。
C-RADIOv2-B 是 NVIDIA 发布的 RADIO（Reduce All Domains Into One）视觉基础模型系列之一，Base 规模（~90M 参数）。该模型通过多教师知识蒸馏（CLIP、SigLIP、DINOv2、SAM）训练，输出全局 summary 特征和局部 spatial 特征，适用于分类、分割、检索等下游任务。本项目完成该模型在昇腾 NPU 上的推理适配，并验证 NPU 与 CPU 推理结果的精度误差 < 1%。
相关地址：
2. 验证环境
| 组件 | 版本 |
|---|
| 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) |
3. 模型信息
| 项目 | 值 |
|---|
| 模型架构 | RADIOModel（自定义，trust_remote_code） |
| 参数量 | ~90M |
| 骨干网络 | ViT-Base (patch16) |
| Hidden Size | 768 |
| 输出 summary | 全局特征向量 (1, C) |
| 输出 features | 局部空域特征 (1, T, D) |
| 权重格式 | safetensors |
| 权重大小 | 342MB |
| 原始框架 | PyTorch (transformers + trust_remote_code) |
| 训练方法 | 多教师特征蒸馏（CLIP + SigLIP + DINOv2 + SAM） |
| 许可证 | NVIDIA Open Model License |
4. Conda 环境安装
创建独立的 conda 环境并安装依赖（使用华为云 PyPI 镜像加速）：
# 创建 conda 环境
conda create -n c-radio python=3.11 -y
# 激活环境
conda activate c-radio
# 安装 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/
5. 推理执行
单张图像推理
# NPU 推理（默认）
python3 inference.py \
--model_path /path/to/C-RADIOv2-B \
--image_path /path/to/image.jpg \
--device npu:0
# CPU 推理
python3 inference.py \
--model_path /path/to/C-RADIOv2-B \
--image_path /path/to/image.jpg \
--device cpu
精度与性能评测
# 自动生成测试图像，对比 NPU 与 CPU 推理精度
python3 eval.py \
--model_path /path/to/C-RADIOv2-B \
--npu_device npu:0
评测结果日志将输出到 log.txt。
6. 参数说明
inference.py 参数
| 参数 | 说明 | 默认值 |
|---|
--model_path | 模型权重路径 | 必需 |
--image_path | 输入图像路径 | 必需 |
--device | 运行设备（npu:0 或 cpu） | npu:0 |
--no_warmup | 跳过预热阶段 | False |
--warmup_image | 预热用图像路径 | 同 --image_path |
eval.py 参数
| 参数 | 说明 | 默认值 |
|---|
--model_path | 模型权重路径 | 模型路径 |
--image_path | 测试图像路径（默认自动生成） | 自动生成 |
--npu_device | NPU 设备 ID | npu:0 |
--num_warmup | NPU 预热轮数 | 3 |
7. 精度评测结果
评测方法
使用同一张测试图像分别在 CPU（FP32）和 NPU（FP32）上运行推理，对比 RADIO 输出的 summary（全局特征）和 features（空域特征）的差异。
评价指标说明
| 指标 | 含义 | 判定阈值 |
|---|
| 向量级相对误差 | ` | |
| 余弦相似度 | NPU 与 CPU 输出向量间的方向一致性 | > 0.99 |
| 最大/平均绝对误差 | 逐元素差值统计，反映数值偏差的绝对量级 | — |
| 绝对误差分位数 | 误差分布特征（P50/P90/P95/P99） | — |
精度结果
| 输出张量 | 向量级相对误差 | 余弦相似度 | 最大绝对误差 | 平均绝对误差 |
|---|
| summary | 0.697624% | 0.9999759197 | 7.23e-03 | 1.27e-03 |
| features | 0.612049% | 0.9999764562 | 1.89e-02 | 1.52e-03 |
绝对误差分布：
| 输出张量 | P50 | P90 | P95 | P99 |
|---|
| summary | 9.94e-04 | 2.79e-03 | 3.37e-03 | 4.68e-03 |
| features | 1.24e-03 | 3.17e-03 | 3.87e-03 | 5.23e-03 |
判定结论
| 指标 | 实测值 | 阈值 | 状态 |
|---|
| 向量级相对误差（summary） | 0.697624% | < 1% | ✅ PASS |
| 向量级相对误差（features） | 0.612049% | < 1% | ✅ PASS |
8. 性能数据
| 操作 | 耗时 |
|---|
| CPU 推理时间（FP32） | 0.2433s |
| NPU 推理时间（FP32，3轮预热后） | 0.2282s |
| 加速比 (CPU / NPU) | 1.07x |
9. 注意事项
- trust_remote_code：该模型使用自定义 RADIOModel 架构，加载时需要设置
trust_remote_code=True。自定义代码已包含在权重目录中。
- 图像处理器：该模型使用
CLIPImageProcessor 进行预处理，而非默认的 AutoImageProcessor。预处理不包含归一化（该模型内部处理），do_resize=True 将输入缩放至 432 像素最短边。
- 多教师特征：RADIO 输出两个张量：
summary（全局特征，类似于 CLS token）和 features（空域特征，适用于密集预测任务），两者均需对比精度。
- NPU 预热：NPU 首次推理包含算子编译优化，需 1-2 轮预热才能达到稳定性能。脚本默认开启 3 轮预热。
- 精度：本模型使用 FP32 精度，NPU 与 CPU 输出误差极小（远小于 1%），不影响下游任务效果。
- 权重文件：模型权重（.safetensors）不包含在适配仓库中，需单独下载。
