timm/res2net50_48w_2s.in1k on Ascend NPU

1. 简介

本工程将 timm/res2net50_48w_2s.in1k 图片分类模型适配为可在华为昇腾 NPU（Ascend910B4）上单卡运行的推理工程。

模型来源：ModelScope 魔搭社区
模型页面：https://www.modelscope.cn/models/timm/res2net50_48w_2s.in1k
模型类型：图片分类（Image Classification）
模型架构：Res2Net-50，48w 2s 变体
输入尺寸：224x224
输出类别：1000 类（ImageNet-1k）

2. 验证环境

项目	版本/型号
NPU	Ascend910B4
npu-smi	25.5.1
Python	3.11.14
torch	2.9.0+cpu
torchvision	0.24.0
torch_npu	可用（昇腾容器提供）
transformers	4.57.6
timm	1.0.27
modelscope	1.35.3
safetensors	0.7.0
CANN	8.5.1

3. 推理运行

安装依赖

pip install -r requirements.txt

注：torch_npu 通常由昇腾容器环境预装，不在 requirements.txt 中固定版本。

运行推理

python inference.py

输入图片：assets/test.jpg
NPU 设备：npu:0
输出：Top-5 预测结果（保存至 logs/prediction.txt）
日志：logs/inference.log

运行精度验证

python eval_accuracy.py

CPU 与 NPU 推理输出对比
日志：logs/accuracy.log

运行性能基准测试

python benchmark.py

预热 2 次 + 正式测试 10 次
日志：logs/benchmark.log

4. Smoke 验证

torch.npu.is_available(): True
torch.npu.device_count(): 1
torch.npu.get_device_name(0): Ascend910B4

推理结果示例（Top-5）：

排名	标签	索引	概率
1	class_526	526	0.043855
2	class_623	623	0.035825
3	class_674	674	0.029818
4	class_673	673	0.028700
5	class_836	836	0.027049

说明：该模型未提供 id2label 映射文件，使用 class_0 ~ class_999 作为标签。

5. 性能参考

在 Ascend910B4 上的单张图片推理性能：

指标	数值
avg latency	34.225 ms
min latency	32.303 ms
max latency	37.754 ms
p50 latency	34.008 ms
p90 latency	37.754 ms
p95 latency	37.754 ms
images/sec	29.22

6. 精度评测

CPU vs NPU Smoke 一致性验证结果：

指标	数值
max_abs_diff (logits)	5.3619e-03
mean_abs_diff (logits)	1.3311e-03
prob_max_diff	8.3957e-05
Top-1 match	Yes (526)
Top-5 match	Yes

结论：CPU/NPU 一致性良好（max_abs_diff < 1e-2）。注意：本验证为 CPU/NPU smoke consistency，非 ImageNet 官方数据集精度评测。

7. 自验证截图

见 screenshots/self_verification.png 和 screenshots/self_verification.txt。

8. 日志文件

文件	说明
`logs/inference.log`	推理日志（模型加载、Top-5 输出）
`logs/accuracy.log`	精度验证日志（CPU vs NPU 对比）
`logs/benchmark.log`	性能基准测试日志
`logs/prediction.txt`	预测结果文本

9. 注意事项

模型下载方式：本工程使用 modelscope snapshot_download 从 ModelScope 魔搭社区下载模型，未使用 HuggingFace Hub 直连下载。
模型加载方式：使用 timm.create_model('res2net50_48w_2s.in1k', pretrained=False) 创建模型结构，然后从 ModelScope 本地缓存加载 model.safetensors 权重文件。严格禁止 pretrained=True，避免触发 HuggingFace Hub 自动下载。
预处理：使用 timm.data.resolve_model_data_config + timm.data.create_transform 构建预处理 pipeline，与 timm 官方推荐方式一致。
标签说明：该模型未提供 id2label.json 或 labels 文件，因此使用 class_0 ~ class_999 作为标签占位。实际部署时可通过 ImageNet 标签映射文件替换。
测试图片：assets/test.jpg 为从 picsum.photos 下载的公开测试图片。如网络不可用，脚本会自动创建占位图并生成说明文件。
显存与内存：Res2Net-50 约 96.7M 权重，单卡推理显存占用较低。若出现 OOM，可检查是否有其他进程占用 NPU 显存。
Exit code 137：若进程被系统终止（OOM Killer），请减少 batch size 或关闭其他 NPU 进程。
权重文件：本仓库不包含模型权重文件（.safetensors、.bin、.pth 等已在 .gitignore 中排除）。首次运行时会自动从 ModelScope 下载到本地缓存。
NPU 自动产物：运行后可能生成 fusion_result.json 和 kernel_meta/ 目录，这些已加入 .gitignore，不会提交到仓库。

10. 标签

#NPU #Ascend #timm #Res2Net #ImageClassification #ModelScope