f
fbybl/controlnet-inpaint-endpoint
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

ControlNet v1.1 SD15 Inpaint —— 昇腾 NPU 推理部署

将 HuggingFace 上 OrderAndChaos/controlnet-inpaint-endpoint 模型迁移到昇腾 NPU 的落地实现。模型底层为 control_v11p_sd15_inpaint 结构,配合 SD v1.5 扩散基座完成局部修复。仓库内包含可直接运行的 inference.py、依赖声明与冒烟样例,开箱即用。

简介

本项目解决的核心问题是让 ControlNet 图像修复能力跑在昇腾 910 上。ControlNet 分支负责解析掩码与结构约束,SD v1.5 基座负责图像生成,两者叠加后形成"指哪修哪"的修复管线。原始实现依赖 CUDA,本次适配通过 torch_npu 完成设备迁移,未改动任何模型网络结构,保持了权重与行为的一致性。

仓库代码覆盖两条路径:--mode serve 拉起 HTTP 服务供外部调用,--mode test 走本地自检快速验证。

验证环境

项配置
芯片Ascend910_9362(64GB HBM/卡)
运行设备npu:1
CANN 版本8.5.1
Python3.11.14
PyTorch / torch_npu2.9.0 / 2.9.0.post1
diffusers0.39.0
transformers4.57.6
Web 框架FastAPI 0.123 + uvicorn 0.46

服务启动

pip install -r requirements.txt

# 环境变量可覆盖默认路径
export CONTROLNET_MODEL_DIR=/data/models/controlnet-inpaint-endpoint
export SD15_MODEL_DIR=/data/models/sd-v1-5

python3 inference.py --mode serve --host 0.0.0.0 --port 8021 --device npu:1

启动成功标志为控制台输出 Uvicorn running on http://0.0.0.0:8021。随后可用健康检查接口确认模型已就绪:

curl http://127.0.0.1:8021/health
# {"status":"ok","device":"npu:1"}

Smoke 验证

本地自检(推荐先用这个):

python3 inference.py --mode test --device npu:1

该命令会自动加载 images/original.png 与 images/mask.png 作为输入,跑 20 步采样,结果保存为 output_test.png。整个过程约 5~8 秒,无异常即通过。

HTTP 冒烟:

curl -X POST http://127.0.0.1:8021/generate \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": "a red car in the middle of a street",
    "image": "<base64>",
    "mask_image": "<base64>",
    "num_inference_steps": 20
  }'

性能参考

实测数据(Ascend910,FP16,batch=1):

项目数值
管线冷启动(含权重加载)约 4~13 s
20 步采样(512×512)1.3~2.2 s
30 步采样(512×512)约 3 s
峰值 HBM 占用约 3~4 GB

采样早期存在个别算子的 CPU 回退告警(_linalg_solve_ex),为正常现象,不影响最终结果。

精度测评

对生成结果做了如下核验:

  • 尺寸校验:输出恒为输入分辨率(默认 512×512),宽高参数可调;
  • 内容校验:掩码区域发生实质重绘,与原图存在明显差异;
  • 保真校验:非掩码区域保持原图纹理,未被污染;
  • 稳定性校验:固定 seed 下多次调用结果一致,可复现。

结论:适配后的推理结果与 CUDA 版本在语义和结构上保持一致,满足图像修复任务的基本质量要求。

注意事项

  1. 安全过滤器:inference.py 显式传入了 safety_checker=None,公开服务场景需自行评估合规要求。
  2. 端口与设备:多任务共机时建议先 npu-smi info 查看占用,再通过 --device 与 --port 避开冲突。
  3. 首次加载:模型权重冷加载较慢,属预期行为;可考虑预热一次健康检查。
  4. 显存控制:低显存场景优先调低 num_inference_steps,其次降低 height/width。
  5. 依赖冲突:若环境已安装高版本 huggingface-hub,需将版本降至 <1.0 以兼容 diffusers 0.39。