BrushNet：涂抹式图像修复模型部署指南
官方信息
| 项目名称 | BrushNet |
| 仓库地址 | https://github.com/TencentARC/BrushNet |
| 官方网站 | https://tencentarc.github.io/BrushNet/ |
| 最新更新 | 2024-12-17 |
| 项目定位 | 腾讯 ARC Lab 推出的插拔式双分支扩散模型，通过涂抹掩码精确控制图像修复区域，可嵌入任何预训练 Stable Diffusion 模型获得高质量修复效果 |
项目背景
传统图像修复（inpainting）模型有一个通病：你涂抹了一个区域让 AI 修复，结果 AI 把整张图都改了——原来好好的背景、物体边缘全部被重绘，和原图"两张皮"。这是因为传统方法把整个图片连同掩码一起送入扩散模型，模型无法区分哪些区域该保留、哪些该重绘。
BrushNet 由腾讯 ARC Lab 开发，核心创新是双分支架构：一个分支处理完整图像（保留原始内容），另一个分支处理掩码图（知道哪里需要修复），两个分支的特征在去噪过程中逐步融合。这样就能做到"只改涂抹区域，其他地方纹丝不动"。而且 BrushNet 是插拔式的——任何基于 Stable Diffusion 的模型（SD1.5、SDXL、各种 fine-tune）都可以挂上 BrushNet 立刻获得精确修复能力。
项目在 GitHub 上收获超过 4K Star，论文发表于 CVPR 2024，是图像修复领域的前沿研究。
核心特性
- 精确修复：只重绘涂抹区域，其他部分完全保留
- 插拔式设计：可嵌入任何 SD1.5/SDXL 基础模型
- 双分支架构：图像分支 + 掩码分支特征融合
- 提示词引导：支持文本提示词控制修复内容
- 多种修复场景：物体擦除、内容生成、局部修改、外扩
- ComfyUI 集成：有现成节点可直接使用
- Gradio Demo：提供网页界面
- 开源协议：Apache 2.0，可商用
环境要求
- 操作系统：Ubuntu 20.04+/Windows 10+
- Python：3.10
- 显卡：NVIDIA GPU（8GB 显存以上，推荐 12GB）
- CUDA：11.8+
- 内存：16GB 以上
- 磁盘空间：约 10GB（含 SD 基础模型 + BrushNet 权重）
详细部署步骤
方式一：源码部署（Gradio Demo）
第 1 步：克隆仓库
git clone https://github.com/TencentARC/BrushNet.git
cd BrushNet第 2 步：创建虚拟环境
conda create -n brushnet python=3.10 -y
conda activate brushnet第 3 步：安装 PyTorch
pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118第 4 步：安装依赖
pip install -r requirements.txt第 5 步：下载模型权重
# 国内用户先设置镜像
export HF_ENDPOINT=https://hf-mirror.com
# 创建模型目录
mkdir -p models/brushnet
# 下载 BrushNet 权重（约 4GB）
# 从 https://huggingface.co/dustysys/BrushNet 下载：
# - brushnet-seedinet.ckpt （基础模型）
# 或从 release 页面下载
# 同时需要 Stable Diffusion 1.5 基础模型
# 从 https://huggingface.co/runwayml/stable-diffusion-v1-5 下载 v1-5-pruned-emaonly.safetensors
# 放到 models/ 目录下第 6 步：启动 Gradio Demo
python gradio_brushnet.py \
--brushnet_checkpoint ./models/brushnet/brushnet-seedinet.ckpt \
--sd_checkpoint ./models/v1-5-pruned-emaonly.safetensors启动后访问 http://localhost:7860。
方式二：ComfyUI 集成（推荐）
BrushNet 最常用的方式是作为 ComfyUI 节点：
# 进入 ComfyUI 自定义节点目录
cd ComfyUI/custom_nodes/
# 克隆 BrushNet ComfyUI 节点
git clone https://github.com/jiaxiangcui/ComfyUI-BrushNet.git
cd ComfyUI-BrushNet
pip install -r requirements.txt
# 下载 BrushNet 权重到 ComfyUI/models/brushnet/ 目录
# 重启 ComfyUI 即可在节点列表找到 BrushNet 节点ComfyUI 工作流要点：
- 加载 SD1.5 基础模型
- 加载 BrushNet 权重节点
- 输入原图 + 掩码图（白色为需要修复区域）
- 输入提示词描述修复后内容
- 运行生成
方式三：IOPaint 集成
IOPaint（前面介绍的图像修复工具）已经内置 BrushNet 模型：
# 安装 IOPaint 后直接指定 brushnet 模型启动
iopaint start --model=brushnet --device=cuda --port=8080
# 浏览器打开 http://localhost:8080
# 上传图片，涂抹要修复的区域，输入提示词，点击生成使用方法
Gradio 界面操作
- 打开 http://localhost:7860
- 上传原始图片
- 用画笔在图片上涂抹要修复的区域（白色掩码）
- 输入提示词（Prompt）描述希望生成的内容：
- 擦除物体：Prompt 留空或写 "empty, blank"
- 替换内容：写 "a red car"、"a forest landscape" 等
- 调整参数：
- BrushNet Condition Scale：掩码控制力（默认 1.0）
- Guidance Scale：提示词遵循度（默认 7.5）
- Steps：去噪步数（默认 20~30）
- 点击"Run"生成
- 对比原图和结果，满意后下载
Python 推理示例
import torch
from diffusers import StableDiffusionPipeline
from brushnet import BrushNetModel
# 加载 SD 管线
pipe = StableDiffusionPipeline.from_pretrained(
"runwayml/stable-diffusion-v1-5",
torch_dtype=torch.float16
).to("cuda")
# 加载 BrushNet
brushnet = BrushNetModel.from_pretrained(
"dustysys/BrushNet",
subfolder="brushnet",
torch_dtype=torch.float16
)
pipe.brushnet = brushnet.to("cuda")
# 准备输入
from PIL import Image
init_image = Image.open("input.jpg").resize((512, 512))
mask_image = Image.open("mask.png").resize((512, 512)) # 白色=修复区
# 生成
result = pipe(
prompt="a beautiful garden",
image=init_image,
mask_image=mask_image,
brushnet_conditioning_scale=1.0,
num_inference_steps=25,
guidance_scale=7.5,
).images[0]
result.save("output.png")常见问题 FAQ
Q1：和普通 SD Inpaint 有什么区别？
A：普通 SD Inpaint 会重绘整个图片的潜空间，导致未涂抹区域也发生变化。BrushNet 的双分支架构保证未涂抹区域完全保留，修复区域与原图融合更自然。
Q2：需要多少显存？
A：SD1.5 + BrushNet 约需 8GB 显存。显存不足可以开启 xFormers 或用 --medvram 参数降低占用。
Q3：支持 SDXL 吗？
A：官方主要支持 SD1.5。社区有适配 SDXL 的版本，但效果不如 SD1.5 成熟。建议先用 SD1.5 体验。
Q4：修复边缘有明显接缝怎么办？
A：(1) 涂抹掩码时边缘稍微羽化（模糊 5~10 像素）；(2) 降低 BrushNet Condition Scale 到 0.8~0.9；(3) 多生成几次选最好的结果。
Q5：模型权重从哪里下载？
A：HuggingFace 仓库 dustysys/BrushNet。国内用户用 hf-mirror.com 镜像加速。
跳转链接
- GitHub 仓库：https://github.com/TencentARC/BrushNet
- 项目主页：https://tencentarc.github.io/BrushNet/
- HuggingFace 模型：https://huggingface.co/dustysys/BrushNet
- ComfyUI 节点：https://github.com/jiaxiangcui/ComfyUI-BrushNet
- IOPaint 集成：https://www.iopaint.com