UL_base_classification 昇腾 NPU 适配

1. 模型信息

模型名称：sharmajai901/UL_base_classification
模型来源：Hugging Face
模型类型：图像分类模型
模型结构：ViT-base-patch16-224
任务类别：房屋图片场景分类
分类标签：bedrooms、exterior、floorPlans、interior、others
推理框架：PyTorch + transformers + torch-npu
运行设备：Ascend NPU
适配目标：完成 UL_base_classification 模型在昇腾 NPU 环境下的图像分类推理验证，并与 CPU 推理结果进行误差对比。

本项目用于验证 sharmajai901/UL_base_classification 模型在 Ascend NPU 环境下的推理流程。项目完成了模型下载、测试图片准备、CPU 推理、NPU 推理、Top-K 分类输出、CPU/NPU 输出误差对比以及验证材料整理。

2. 项目说明

UL_base_classification 是一个基于 ViT-base-patch16-224 的图像分类模型，用于将输入图片分类为房屋相关场景类别。本项目使用一张测试图片 test.jpg 作为输入，分别在 CPU 与 Ascend NPU 上执行推理，并比较两端输出概率是否一致。

本次适配重点包括：

在 Ascend NPU Notebook 环境中加载模型；
准备测试图片 test.jpg；
分别执行 CPU 与 NPU 图像分类推理；
保存 CPU/NPU 的 Top-K 分类结果；
对 CPU 与 NPU 输出概率进行误差对比；
保存日志、截图和适配报告，用于赛道一模型适配验证提交。

3. 工程结构

.
├── README.md
├── adaptation_report.md
├── download_model.sh
├── inference.py
├── compare_cpu_npu.py
├── requirements.txt
├── test.jpg
├── cpu_result.json
├── cpu_result.txt
├── npu_result.json
├── npu_result.txt
├── compare_result.txt
├── run.log
└── screenshots/
    ├── npu_env.png
    ├── npu_result.png
    └── compare_result.png

其中：

download_model.sh：模型下载脚本；
inference.py：CPU/NPU 推理脚本；
compare_cpu_npu.py：CPU/NPU 输出误差对比脚本；
cpu_result.json：CPU 推理结构化结果；
cpu_result.txt：CPU 推理日志；
npu_result.json：NPU 推理结构化结果；
npu_result.txt：NPU 推理日志；
compare_result.txt：CPU/NPU 误差对比结果；
run.log：完整运行日志；
adaptation_report.md：适配报告；
screenshots/：验证截图材料。

4. 环境检查

在 Ascend NPU Notebook 中执行以下命令检查运行环境：

npu-smi info
python --version
python - <<'PY'
import torch
print("torch:", torch.__version__)
try:
    import torch_npu
    print("torch_npu import success")
    print("npu available:", torch.npu.is_available())
except Exception as e:
    print("torch_npu import failed:", repr(e))
PY

环境检查截图保存为：

screenshots/npu_env.png

该截图用于证明当前运行环境存在 Ascend NPU，并记录 NPU 型号、运行状态和 Python 版本信息。

5. 模型下载

运行：

bash download_model.sh

模型来源为 Hugging Face：

sharmajai901/UL_base_classification

模型文件会下载到：

./model

推理脚本通过 ./model 目录加载模型权重和配置文件。

6. 测试输入

本项目使用测试图片：

test.jpg

推理流程包括：

读取测试图片；
对图片进行模型要求的预处理；
构造模型输入张量；
输入 ViT 分类模型；
输出 5 个类别的分类概率；
保存 Top-K 分类结果。

本项目的分类标签包括：

bedrooms
exterior
floorPlans
interior
others

7. CPU 推理

运行：

python inference.py --device cpu --image test.jpg --output cpu_result.json 2>&1 | tee cpu_result.txt

CPU 推理输出文件：

cpu_result.json
cpu_result.txt

CPU 推理日志摘要如下：

Loading model: ./model
Using device: cpu

CPU Top-K 输出如下：

[
  {
    "label_id": 2,
    "label": "floorPlans",
    "score": 0.8987306356430054
  },
  {
    "label_id": 1,
    "label": "exterior",
    "score": 0.033997952938079834
  },
  {
    "label_id": 4,
    "label": "others",
    "score": 0.03273681923747063
  },
  {
    "label_id": 3,
    "label": "interior",
    "score": 0.023410990834236145
  },
  {
    "label_id": 0,
    "label": "bedrooms",
    "score": 0.011123541742563248
  }
]

8. NPU 推理

运行：

python inference.py --device npu --image test.jpg --output npu_result.json 2>&1 | tee npu_result.txt

NPU 推理输出文件：

npu_result.json
npu_result.txt

NPU 推理日志摘要如下：

Loading model: ./model
Using device: npu:0

NPU Top-K 输出如下：

[
  {
    "label_id": 2,
    "label": "floorPlans",
    "score": 0.8984941244125366
  },
  {
    "label_id": 1,
    "label": "exterior",
    "score": 0.03407783433794975
  },
  {
    "label_id": 4,
    "label": "others",
    "score": 0.03285509720444679
  },
  {
    "label_id": 3,
    "label": "interior",
    "score": 0.023427797481417656
  },
  {
    "label_id": 0,
    "label": "bedrooms",
    "score": 0.011145140044391155
  }
]

NPU 推理结果截图保存为：

screenshots/npu_result.png

日志末尾出现的：

path string is NULLpath string is NULL

属于 torch-npu / CANN 环境中的提示信息，不影响前面的模型加载、NPU 推理和结果保存。本次验证已经成功获得 NPU 分类输出。

9. CPU/NPU 误差对比

运行：

python compare_cpu_npu.py --cpu cpu_result.json --npu npu_result.json 2>&1 | tee compare_result.txt

对比脚本会读取 CPU 与 NPU 的分类概率输出，并计算：

CPU/NPU Top-K 顺序是否一致；
最大绝对误差；
最大相对误差百分比；
每个类别的 CPU 分数；
每个类别的 NPU 分数；
每个类别的绝对误差；
每个类别的相对误差百分比；
是否通过 1% 阈值验证。

对比结果保存为：

compare_result.txt

10. 自验证结果

本次 UL_base_classification 适配验证的 CPU/NPU 误差结果如下：

指标	结果
CPU Top-1	`floorPlans`
NPU Top-1	`floorPlans`
CPU/NPU Top-K 顺序是否一致	`true`
最大绝对误差	`0.00023651123046875`
最大相对误差百分比	`0.36129950841645786`
是否通过 1% 阈值	`true`

各类别 CPU/NPU 分数对比如下：

label_id	label	CPU score	NPU score	abs diff	rel diff percent
0	bedrooms	0.011123541742563248	0.011145140044391155	0.000021598301827907562	0.19416749024515792
1	exterior	0.033997952938079834	0.03407783433794975	0.00007988139986991882	0.23495944010336767
2	floorPlans	0.8987306356430054	0.8984941244125366	0.00023651123046875	0.02631614202174557
3	interior	0.023410990834236145	0.023427797481417656	0.000016806647181510925	0.07178955944458766
4	others	0.03273681923747063	0.03285509720444679	0.00011827796697616577	0.36129950841645786

对应的 compare_result.txt 内容如下：

{
  "same_topk_order": true,
  "max_abs_diff": 0.00023651123046875,
  "max_rel_diff_percent": 0.36129950841645786,
  "pass_1_percent_threshold": true,
  "details": [
    {
      "label_id": 0,
      "label": "bedrooms",
      "cpu_score": 0.011123541742563248,
      "npu_score": 0.011145140044391155,
      "abs_diff": 2.1598301827907562e-05,
      "rel_diff_percent": 0.19416749024515792
    },
    {
      "label_id": 1,
      "label": "exterior",
      "cpu_score": 0.033997952938079834,
      "npu_score": 0.03407783433794975,
      "abs_diff": 7.988139986991882e-05,
      "rel_diff_percent": 0.23495944010336767
    },
    {
      "label_id": 2,
      "label": "floorPlans",
      "cpu_score": 0.8987306356430054,
      "npu_score": 0.8984941244125366,
      "abs_diff": 0.00023651123046875,
      "rel_diff_percent": 0.02631614202174557
    },
    {
      "label_id": 3,
      "label": "interior",
      "cpu_score": 0.023410990834236145,
      "npu_score": 0.023427797481417656,
      "abs_diff": 1.6806647181510925e-05,
      "rel_diff_percent": 0.07178955944458766
    },
    {
      "label_id": 4,
      "label": "others",
      "cpu_score": 0.03273681923747063,
      "npu_score": 0.03285509720444679,
      "abs_diff": 0.00011827796697616577,
      "rel_diff_percent": 0.36129950841645786
    }
  ]
}

根据上述结果，CPU 与 NPU 的 Top-1 预测均为 floorPlans，Top-K 顺序一致，最大相对误差百分比为 0.36129950841645786，低于 1% 阈值。因此，本次 UL_base_classification 昇腾 NPU 推理验证通过。

11. 验证截图材料

11.1 NPU 环境截图

npu_env

该截图展示 Ascend NPU Notebook 环境、npu-smi info 输出和 Python 版本信息。

11.2 NPU 推理结果截图

npu_result

该截图展示 NPU 推理日志，包括模型加载、运行设备、测试图片和 Top-K 分类输出。

11.3 CPU/NPU 误差对比截图

compare_result

该截图展示 CPU/NPU 分类概率误差对比结果，包括 Top-K 一致性、最大绝对误差、最大相对误差以及各类别分数差异。

12. 运行日志与提交材料

本项目提交材料包括：

README.md
adaptation_report.md
download_model.sh
inference.py
compare_cpu_npu.py
requirements.txt
test.jpg
cpu_result.json
cpu_result.txt
npu_result.json
npu_result.txt
compare_result.txt
run.log
screenshots/npu_env.png
screenshots/npu_result.png
screenshots/compare_result.png

完整运行日志可查看：

run.log

CPU 推理日志可查看：

cpu_result.txt

NPU 推理日志可查看：

npu_result.txt

CPU/NPU 误差对比结果可查看：

compare_result.txt

13. 适配说明

本项目的适配工作包括：

在 Ascend NPU 环境中完成依赖安装；
编写模型下载脚本；
使用本地 ./model 目录加载模型；
编写 CPU/NPU 统一推理脚本；
支持测试图片输入和图像预处理；
保存 CPU 与 NPU 的结构化分类结果；
编写 CPU/NPU 分类概率误差对比脚本；
计算 Top-K 一致性、最大绝对误差和最大相对误差百分比；
输出完整日志、截图和适配报告。

14. 结论

本项目完成了 sharmajai901/UL_base_classification 模型在 Ascend NPU 环境下的图像分类推理适配验证。

验证结果表明，NPU 推理能够正常完成模型加载、图像预处理和 Top-K 分类输出。CPU 与 NPU 的 Top-1 预测均为 floorPlans，Top-K 顺序一致，最大相对误差百分比为 0.36129950841645786，并通过 1% 阈值验证。本项目可作为赛道一模型适配提交材料。