YYPGD/BiRefNet
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

BiRefNet 昇腾NPU部署文档

1. 模型简介

模型名称: BiRefNet(ZhengPeng7/BiRefNet) 模型链接: https://ai.gitcode.com/hf_mirrors/ZhengPeng7/BiRefNet 模型描述: BiRefNet(Bilateral Reference for High-Resolution Dichotomous Image Segmentation)是面向高分辨率二分图像分割(DIS)的显著目标检测模型,通过全局到局部的双边参考(transformer 全局语义 + 局部图像细节引导)实现像素级高精度目标抠图,广泛用于高精度分割、背景移除等场景。本权重在 DIS5K+HRSOD+HRS10K 数据集上训练。 模型架构: Swin-V1-Large 编码器 + 多尺度压缩模块 + 含可变形注意力(ASPPDeformable)的级联解码器 + 双边参考细化,输出单通道显著性概率图。 参数规模: 约 220M(model.safetensors 约 445MB)

2. 环境依赖

依赖项版本要求说明
Python>= 3.10推荐 3.11
torch / torch_npu2.1.0+NPU 上需安装 torch_npu(系统预装)
transformers>= 4.40通过 auto_map + trust_remote_code 加载自定义结构
timm>= 1.0Swin Backbone 组件
kornia最新版Laplacian 细节提取算子
einops / opencv-python-headless / pillow / numpy最新版张量操作与图像处理

安装命令:

pip install --target /mnt/workspace/BiRefNet/libs -i https://pypi.tuna.tsinghua.edu.cn/simple transformers timm kornia einops opencv-python-headless pillow numpy

3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info
# 权重已就位
ls /home/developer/models/BiRefNet/   # config.json birefnet.py model.safetensors ...

3.2 运行推理

PYTHONPATH=/mnt/workspace/BiRefNet/libs python3 inference.py --model_path /home/developer/models/BiRefNet

3.3 推理参数说明

参数类型默认值说明
--model_pathstr/home/developer/models/BiRefNet本地权重目录
--devicestr自动(npu > cuda > cpu)推理设备
--input_sizeint1024输入分辨率(官方推荐 1024×1024)
--outputstrassets/model_result.png结果图保存路径

4. 测试样例及输出结果

样例 1:内置示例输入(合成渐变+中央圆盘图案)

输入:

python3 inference.py --model_path /home/developer/models/BiRefNet

输出:

[INFO] device = npu
[INFO] 模型加载完成 load_time=15.2s
[INFO] 推理完成 耗时/elapsed=1.8s (input=1024x1024, device=npu)
[INFO] 输出显著性掩码形状: (1024, 1024), 取值范围: [0.000, 1.000], 前景比例=0.196
[RESULT] status=ok device=npu 耗时/elapsed=1.8s

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

模型适配结果

6. 注意事项

  • 推理脚本通过 torch_npu 调用 NPU,设备自动选择 npu > cuda > cpu;
  • 模型为自定义结构,通过 AutoModelForImageSegmentation.from_pretrained(本地路径, trust_remote_code=True) 加载,local_files_only=True 保证推理全程离线;
  • 输入为 1024×1024 RGB 图像,按 ImageNet 统计量归一化,张量全程 float32(NPU 无 float64 算子);注意力为标准实现(非 flash_attention_2);
  • 输出取预测列表最后一项并做 sigmoid,得到 (H, W) 显著性概率图,>0.5 视为前景;
  • libs 目录中不安装 torch/torchvision,直接使用系统 torch + torch_nPU,避免版本遮蔽导致 torch_npu 不可用;
  • 如有精度差异请与官方 pipeline(ZhengPeng7/BiRefNet GitHub)输出对比确认。