Bug_Factory_w/Misc-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Misc-NPU:MidnightRunner/Misc 模型集合昇腾 NPU 服务化推理

将 Hugging Face 仓库 MidnightRunner/Misc 中的 超分辨率 / 去噪 / SAM 分割模型迁移至本地昇腾 NPU(Ascend910 系列), 并提供统一的 HTTP 服务化推理能力。

NPU 设备调用


1. 项目概述

Misc 是 MidnightRunner 的"杂货工具箱"模型仓库,包含 119 个权重文件。本项目完成:

类别数量说明
🖼️ 超分 / 去噪模型32RealESRGAN / ESRGAN / SwinIR / OmniSR / RealPLKSR 等
🎯 SAM 分割模型7SAM vit_b/l/h、MobileSAM、SAM-HQ vit_b/l/h
📦 组件类模型80LoRA / Checkpoint / 文本编码器 / GGUF(需配套基础模型)
  • 推理框架:PyTorch 2.9.0 + torch_npu 2.9.0.post1
  • 硬件平台:Ascend910(8 卡,本服务默认使用 1 卡,64GB HBM)
  • 服务框架:FastAPI + Uvicorn
  • 迁移方式:torch_npu.contrib.transfer_to_npu 自动迁移 + spandrel 架构自动识别

2. 环境要求

组件版本备注
操作系统openEuler 22.03 (aarch64)其他昇腾支持系统亦可
昇腾硬件Ascend910 系列至少 1 卡
CANN25.5.0(≥ 8.0)/usr/local/Ascend/ascend-toolkit/set_env.sh
Python3.113.8–3.10 亦可
PyTorch2.9.0与 CANN 版本配套
torch_npu2.9.0.post1与 PyTorch 版本一致

依赖安装

# 1. 加载 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 2. 配置华为镜像源(国内加速)
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/

# 3. 安装依赖
pip install -r requirements.txt

# 4. 校验 NPU 可用性
python3 -c "import torch, torch_npu; print(torch.randn(3,4).npu() + torch.randn(3,4).npu())"

3. 目录结构

Misc-npu/
├── inference.py              # 服务化推理主入口(FastAPI 多模型服务)
├── model.py                  # RRDBNet 模型定义(RealESRGAN 架构)
├── sam_models.py             # SAM 家族模型加载模块
├── test_inference.py         # 服务化推理测试用例(7 项)
├── requirements.txt          # 运行环境依赖清单
├── README.md                 # 本文件(中文指引)
├── mobile_sam_modeling/      # MobileSAM TinyViT 源码(内置,含许可证)
│   ├── tiny_vit_sam.py
│   └── image_encoder.py
└── assets/                   # 验证截图
    ├── npu_device_call.png   # NPU 设备调用截图
    ├── model_result.png      # 测试结果截图
    └── agent_workflow.png    # 适配过程截图

4. 快速开始

4.1 启动服务

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0

python inference.py \
    --port 8000 \
    --models-dir /mnt/old_data/whl/models/4-2/MidnightRunner/Misc \
    --preload RealESRGAN_x4plus.pth,mobile_sam.pt

启动日志示例:

[Misc-NPU] 扫描完成: 共 119 个模型, 可服务化 39 个 (SR 32, SAM 7), 组件类 80 个
[Misc-NPU] 预加载完成: RealESRGAN_x4plus.pth (1.2s)
[Misc-NPU] 预加载完成: mobile_sam.pt (0.5s)
[Misc-NPU] 当前 NPU 显存占用: 109 MB / 62740 MB
INFO:     Uvicorn running on http://0.0.0.0:8000

说明:--preload 默认预热 2 个代表模型,启动后 npu-smi info 立即可见显存占用; 其余模型采用懒加载(首次请求时载入,LRU 缓存管理显存)。 传 --preload "" 可关闭预热。

4.2 运行测试用例

python test_inference.py --port 8000

预期输出(详见 测试结果截图):

== 1. 健康检查 ==
  [PASS] health 接口 device=npu:0
  [PASS] NPU 设备调用 npu_name=Ascend910_9382 npu_count=1
== 3. 超分推理 RealESRGAN_x4plus ==
  [PASS] RealESRGAN 4x 超分 输出 768x768, 耗时 0.0230s
...
===== 测试结果: 7 通过, 0 失败 =====
全部测试通过 ✅

5. HTTP 接口说明

5.1 GET / — 服务信息

curl http://127.0.0.1:8000/

5.2 GET /health — 健康检查 / NPU 设备状态

curl http://127.0.0.1:8000/health
# {"status":"ok","device":"npu:0","torch_npu_available":true,"npu_name":"Ascend910_9382",...}

5.3 GET /models — 模型注册表(全部 119 个模型及服务化状态)

curl http://127.0.0.1:8000/models | python3 -m json.tool

5.4 POST /infer/sr/{model_name} — 超分 / 去噪推理

curl -X POST http://127.0.0.1:8000/infer/sr/RealESRGAN_x4plus.pth \
     -F "file=@input.png" -o output.png
模型示例倍率
RealESRGAN_x4plus.pth / RealESRGAN_x4.pth / RealESRGAN_x4plus_anime_6B.pth4x
RealESRGAN_x2plus.pth / 2x-UltraSharp2x
SwinIR_4x.pth4x
OmniSR_X2/X3/X4_DIV2K.safetensors2x/3x/4x
8x_NMKD-Superscale_150000_G.pth8x
1xDeNoise_realplksr_otf.pth1x(去噪)

5.5 POST /infer/sam/{model_name} — SAM 全图自动分割

curl -X POST http://127.0.0.1:8000/infer/sam/mobile_sam.pt \
     -F "file=@photo.png"
# {"model":"mobile_sam.pt","mask_count":2,"masks":[{"bbox":[...],"area":...,"predicted_iou":...}]}

6. 昇腾 NPU 适配说明

本项目依据 ascend-model-agent-plugin(ai4s-basic)迁移流程完成,关键适配点:

  1. 自动迁移注入:inference.py 顶部导入
    import torch_npu
    from torch_npu.contrib import transfer_to_npu   # cuda API 自动映射 npu
  2. 统一设备路由:get_device() 优先 npu:0,无 NPU 时回退 CPU。
  3. 模型架构自动识别:spandrel(纯 PyTorch)自动探测 RRDBNet / SwinIR / OmniSR / RealPLKSR 等架构,无需为每个权重手写网络定义;model.py 内置 RRDBNet 参考实现。
  4. SAM 家族:官方 segment-anything + 内置 MobileSAM(TinyViT 骨干,源码随项目分发); SAM-HQ 权重以 non-strict 兼容方式加载(encoder 完整,HQ 增强头忽略)。
  5. 算子兼容性:全部算子均为标准 PyTorch 算子,Ascend910 原生支持; 唯一 CPU 回退为 SAM 后处理的 torchvision::nms(仅影响毫秒级开销)。
  6. 显存管理:服务懒加载 + LRU 缓存(SR 模型上限 4 个,SAM 保留最近 1 个)。

实测性能(NPU 卡 0,预热后)

任务模型输入耗时
4x 超分RealESRGAN_x4plus192×192 → 768×7680.023 s
4x 超分SwinIR_4x192×192 → 768×7681.08 s
自动分割MobileSAM256×2560.65 s

7. 模型服务化范围说明

可独立服务化(39 个):超分 / 去噪类 32 个 + SAM 分割类 7 个,见第 5 节接口。

组件类模型(80 个,需配套基础模型),本服务将其登记在 /models 注册表中并明确标注:

类别示例需配套
LoRAwan_cowgirl_v1.3、fluxmania_kreamania、W25_Realistic 系列对应基础扩散模型
CheckpointcyberrealisticPony、realismByStableYogi、reijalitySDXL / FLUX 完整管线
文本编码器t5xxl_fp16、CLIP-ViT-bigG、umt5_xxl对应多模态管线
LLM 权重Qwen2.5-VL-7B GGUF 系列llama.cpp / vLLM-Ascend
配置/负嵌入Astraali JSON、zPDXL-*.pt相应工作流

8. 常见问题

问题解决方案
No module named 'decorator'pip install decorator(torch_npu 运行时依赖)
显存占用为 0服务为懒加载设计,用 --preload 预热或先发一次推理请求
torchvision::nms CPU 回退警告SAM 后处理正常现象,不影响正确性
单卡 OOM减小输入图片尺寸或调低 MAX_SR_CACHE
华为镜像缺包临时 --index-url https://pypi.org/simple/

9. 许可证

  • 适配代码:Apache-2.0
  • MobileSAM(TinyViT)源码:MIT(ChaoningZhang/MobileSAM),随项目分发于 mobile_sam_modeling/
  • 模型权重:遵循各自原始来源许可证(详见 MidnightRunner/Misc)