BrushNet 图像修复快速入门30 分钟从零跑通第一次 Inpainting【免费下载链接】BrushNet[ECCV 2024] The official implementation of paper BrushNet: A Plug-and-Play Image Inpainting Model with Decomposed Dual-Branch Diffusion项目地址: https://gitcode.com/GitHub_Trending/br/BrushNet先说结论BrushNet 是 ECCV 2024 提出的即插即用plug-and-play无需重训基座模型文本引导图像修复模型把它挂到任意 Stable Diffusion 上就能抹掉一块、按文字描述补回来。适合刚接触扩散模型、想在 30 分钟内看到修复效果的新手。读完你能收获✅ 环境 依赖的三步安装命令✅ 模型下载与目录落位的完整路径✅ 一个能直接复现效果的最小示例脚本为什么选它BrushNet 的核心思路是把被遮住的图像特征和加噪潜变量分到两条支路处理再通过逐像素控制接入整个预训练 UNet——基座模型完全不动加一个轻量网络就能获得接近原生训练的修复能力。它的差异化在于不用为修复任务重新训练 Stable Diffusion同一套权重既支持分割掩码贴合物体轮廓也支持随机掩码任意形状擦除SD 1.5 和 SDXL 都有官方 checkpoint。动手前的检查你的机器满足下面这行配置就能开始官方实测环境是 Python 3.9 PyTorch 1.12.1。组件最低要求推荐配置Python3.83.9PyTorch1.12.12.0GPU 显存8GB16GBCUDA11.611.8如果显存低于 8GB后面的enable_model_cpu_offload()可以兜底但首次运行会明显变慢。安装 BrushNet 的三步命令第 1 步克隆仓库git clone https://gitcode.com/GitHub_Trending/br/BrushNet cd BrushNet做完后应看到仓库目录其中 examples/brushnet/ 下有train_brushnet.py、test_brushnet.py、app_brushnet.py等脚本。第 2 步建环境并装 PyTorchconda create -n brushnet python3.9 -y conda activate brushnet python -m pip install --upgrade pip # CUDA 11.6 环境其他版本请按官方指引替换 pip install torch1.12.1cu116 torchvision0.13.1cu116 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu116做完后运行python -c import torch; print(torch.cuda.is_available())应输出True。如果输出False多半是 CUDA 驱动与 whl 版本不匹配处理换成与nvidia-smi里 CUDA 版本对应的 torch whl。第 3 步装 diffusers 与示例依赖# 安装本仓库修改过的 diffusers含 BrushNet 模型与 pipeline pip install -e . # 安装示例脚本依赖 cd examples/brushnet pip install -r requirements.txt做完后运行python -c from diffusers import StableDiffusionBrushNetPipeline, BrushNetModel; print(ok)应输出ok。如果报ImportError多半是第 2 步的 torch 没装进当前 conda 环境处理确认conda info --envs高亮的是brushnet再重装依赖。模型目录怎么放需要两类权重一个 SD 1.5 基座模型 一个 BrushNet checkpoint统一放到data/ckpt/下。checkpoint 可从项目 README 给出的官方模型文件区下载免费申请基座模型官方示例用的是realisticVisionV60B1_v51VAECivitai 的 SD 1.5 模型也可换成runwayml/stable-diffusion-v1-5。落位后的目录结构data/ └── ckpt/ ├── realisticVisionV60B1_v51VAE/ # SD 1.5 基座含 model_index.json、vae/ 等子目录 ├── segmentation_mask_brushnet_ckpt/ # 分割掩码版 BrushNetSD 1.5 ├── random_mask_brushnet_ckpt/ # 随机掩码版 BrushNetSD 1.5 ├── segmentation_mask_brushnet_ckpt_sdxl_v0/ # SDXL 分割掩码版 └── random_mask_brushnet_ckpt_sdxl_v0/ # SDXL 随机掩码版两个 mask 版本怎么选segmentation_mask在轮廓贴合物体的掩码上效果最稳适合去物体random_mask泛化更广适合任意形状擦除。可以写个占位脚本提醒落位把下载好的压缩包解压到data/ckpt/即可mkdir -p data/ckpt # 将下载好的基座模型与 brushnet checkpoint 解压/复制到 data/ckpt/ 下对应目录 ls data/ckpt/ # 应看到 5 个模型目录第一次跑通最小示例仓库自带测试图examples/brushnet/src/test_image.jpg与test_mask.jpg白色区域为修复区不用自己准备数据直接运行 examples/brushnet/test_brushnet.py 即可。核心流程只有 5 段from diffusers import StableDiffusionBrushNetPipeline, BrushNetModel, UniPCMultistepScheduler import torch, cv2, numpy as np from PIL import Image # 1. 加载模型BrushNet 权重 SD 1.5 基座 brushnet BrushNetModel.from_pretrained( data/ckpt/segmentation_mask_brushnet_ckpt, torch_dtypetorch.float16 ) pipe StableDiffusionBrushNetPipeline.from_pretrained( data/ckpt/realisticVisionV60B1_v51VAE, brushnetbrushnet, torch_dtypetorch.float16 ) # 2. 换更快的采样调度器并开启显存优化低显存 GPU 必开 pipe.scheduler UniPCMultistepScheduler.from_config(pipe.scheduler.config) pipe.enable_model_cpu_offload() # 把模型按需在 CPU/GPU 间搬运省显存 # 3. 准备输入原图 掩码白色要修复的区域 init_image cv2.imread(examples/brushnet/src/test_image.jpg)[:, :, ::-1] mask_image 1 * (cv2.imread(examples/brushnet/src/test_mask.jpg).sum(-1) 255)[:, :, np.newaxis] init_image init_image * (1 - mask_image) # 把修复区域从原图中挖掉 init_image Image.fromarray(init_image.astype(np.uint8)).convert(RGB) mask_image Image.fromarray((mask_image * 255).astype(np.uint8).repeat(3, -1)).convert(RGB) # 4. 推理caption 描述要补什么内容 image pipe( A cake on the table., init_image, mask_image, num_inference_steps50, # 步数越多质量越好、越慢 generatortorch.Generator(cuda).manual_seed(1234), brushnet_conditioning_scale1.0 # BrushNet 条件强度越小越依赖文字描述 ).images[0] # 5. 保存结果 image.save(output.png)运行python examples/brushnet/test_brushnet.py几分钟后在当前目录得到output.png。对比原图与仓库里展示的效果样例如examples/brushnet/src/example_4.jpeg对应的修复结果examples/brushnet/src/example_4_result.png修复区域应与 caption 一致且边缘过渡自然。如果生成的修复内容和文字描述无关多半是brushnet_conditioning_scale开太大、BrushNet 特征压过了文本处理降到 0.5~0.8 再试。避坑清单现象CUDA out of memory。原因fp16 全流程仍超出显存。处理保留enable_model_cpu_offload()并加一行pipe.enable_attention_slicing()SDXL 模型建议显存 16GB。现象from_pretrained报路径或格式错误。原因目录名写错或缺少model_index.json。处理ls data/ckpt/模型目录确认基座目录下有model_index.json、vae/、unet/等子目录。现象装依赖时报版本冲突。原因requirements 锁定了accelerate0.20.3、Pillow9.5.0等旧版本。处理在干净 conda 环境里按torch →pip install -e .→ requirements.txt顺序重装别混用系统 python。现象开了enable_xformers_memory_efficient_attention()后报错。原因xformers 与 torch 2.0 不兼容。处理删掉该行脚本里默认就是注释掉的。现象修复区域没生效输出和原图几乎一样。原因掩码约定是白色为修复区黑底白区的掩码反了。处理确认test_mask.jpg中待修复部分是纯白。性能优化建议方法收益适用场景UniPC 调度器采样提速质量基本不变所有推理enable_model_cpu_offload()显存需求大幅降低8~12GB 显存enable_attention_slicing()分段计算注意力进一步省显存高分辨率图减少num_inference_steps直接线性提速快速预览/调参下一步可以继续做的事换 SDXL 模型把路径与 pipeline 换成StableDiffusionXLBrushNetPipelinesegmentation_mask_brushnet_ckpt_sdxl_v0参考 examples/brushnet/test_brushnet_sdxl.py。起一个网页交互界面python examples/brushnet/app_brushnet.py用 Gradio 上传图片、掩码和 prompt 在线修复。量化评估python examples/brushnet/evaluate_brushnet.py在 BrushBench 上算 CLIPScore、LPIPS、PSNR 等指标。用自己的数据微调按 README 的数据目录格式准备data/BrushData用accelerate launch examples/brushnet/train_brushnet.py训练工业场景如商品图、虚拟试穿建议这么做。容器化部署用pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime作基础镜像pip install -e .后再装示例依赖即可。三步装好环境、五个模型目录落位、一份最小脚本你就完成了第一次 BrushNet 图像修复——现在就去output.png里看看效果吧。【免费下载链接】BrushNet[ECCV 2024] The official implementation of paper BrushNet: A Plug-and-Play Image Inpainting Model with Decomposed Dual-Branch Diffusion项目地址: https://gitcode.com/GitHub_Trending/br/BrushNet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/23 4:43:48 · 阅读 1.2k BrushNet 图像修复快速入门：30 分钟从零跑通第一次 Inpainting
BrushNet 图像修复快速入门30 分钟从零跑通第一次 Inpainting【免费下载链接】BrushNet[ECCV 2024] The official implementation of paper BrushNet: A Plug-and-Play Image Inpainting Model with Decomposed Dual-Branch Diffusion项目地址: https://gitcode.com/GitHub_Trending/br/BrushNet先说结论BrushNet 是 ECCV 2024 提出的即插即用plug-and-play无需重训基座模型文本引导图像修复模型把它挂到任意 Stable Diffusion 上就能抹掉一块、按文字描述补回来。适合刚接触扩散模型、想在 30 分钟内看到修复效果的新手。读完你能收获✅ 环境 依赖的三步安装命令✅ 模型下载与目录落位的完整路径✅ 一个能直接复现效果的最小示例脚本为什么选它BrushNet 的核心思路是把被遮住的图像特征和加噪潜变量分到两条支路处理再通过逐像素控制接入整个预训练 UNet——基座模型完全不动加一个轻量网络就能获得接近原生训练的修复能力。它的差异化在于不用为修复任务重新训练 Stable Diffusion同一套权重既支持分割掩码贴合物体轮廓也支持随机掩码任意形状擦除SD 1.5 和 SDXL 都有官方 checkpoint。动手前的检查你的机器满足下面这行配置就能开始官方实测环境是 Python 3.9 PyTorch 1.12.1。组件最低要求推荐配置Python3.83.9PyTorch1.12.12.0GPU 显存8GB16GBCUDA11.611.8如果显存低于 8GB后面的enable_model_cpu_offload()可以兜底但首次运行会明显变慢。安装 BrushNet 的三步命令第 1 步克隆仓库git clone https://gitcode.com/GitHub_Trending/br/BrushNet cd BrushNet做完后应看到仓库目录其中 examples/brushnet/ 下有train_brushnet.py、test_brushnet.py、app_brushnet.py等脚本。第 2 步建环境并装 PyTorchconda create -n brushnet python3.9 -y conda activate brushnet python -m pip install --upgrade pip # CUDA 11.6 环境其他版本请按官方指引替换 pip install torch1.12.1cu116 torchvision0.13.1cu116 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu116做完后运行python -c import torch; print(torch.cuda.is_available())应输出True。如果输出False多半是 CUDA 驱动与 whl 版本不匹配处理换成与nvidia-smi里 CUDA 版本对应的 torch whl。第 3 步装 diffusers 与示例依赖# 安装本仓库修改过的 diffusers含 BrushNet 模型与 pipeline pip install -e . # 安装示例脚本依赖 cd examples/brushnet pip install -r requirements.txt做完后运行python -c from diffusers import StableDiffusionBrushNetPipeline, BrushNetModel; print(ok)应输出ok。如果报ImportError多半是第 2 步的 torch 没装进当前 conda 环境处理确认conda info --envs高亮的是brushnet再重装依赖。模型目录怎么放需要两类权重一个 SD 1.5 基座模型 一个 BrushNet checkpoint统一放到data/ckpt/下。checkpoint 可从项目 README 给出的官方模型文件区下载免费申请基座模型官方示例用的是realisticVisionV60B1_v51VAECivitai 的 SD 1.5 模型也可换成runwayml/stable-diffusion-v1-5。落位后的目录结构data/ └── ckpt/ ├── realisticVisionV60B1_v51VAE/ # SD 1.5 基座含 model_index.json、vae/ 等子目录 ├── segmentation_mask_brushnet_ckpt/ # 分割掩码版 BrushNetSD 1.5 ├── random_mask_brushnet_ckpt/ # 随机掩码版 BrushNetSD 1.5 ├── segmentation_mask_brushnet_ckpt_sdxl_v0/ # SDXL 分割掩码版 └── random_mask_brushnet_ckpt_sdxl_v0/ # SDXL 随机掩码版两个 mask 版本怎么选segmentation_mask在轮廓贴合物体的掩码上效果最稳适合去物体random_mask泛化更广适合任意形状擦除。可以写个占位脚本提醒落位把下载好的压缩包解压到data/ckpt/即可mkdir -p data/ckpt # 将下载好的基座模型与 brushnet checkpoint 解压/复制到 data/ckpt/ 下对应目录 ls data/ckpt/ # 应看到 5 个模型目录第一次跑通最小示例仓库自带测试图examples/brushnet/src/test_image.jpg与test_mask.jpg白色区域为修复区不用自己准备数据直接运行 examples/brushnet/test_brushnet.py 即可。核心流程只有 5 段from diffusers import StableDiffusionBrushNetPipeline, BrushNetModel, UniPCMultistepScheduler import torch, cv2, numpy as np from PIL import Image # 1. 加载模型BrushNet 权重 SD 1.5 基座 brushnet BrushNetModel.from_pretrained( data/ckpt/segmentation_mask_brushnet_ckpt, torch_dtypetorch.float16 ) pipe StableDiffusionBrushNetPipeline.from_pretrained( data/ckpt/realisticVisionV60B1_v51VAE, brushnetbrushnet, torch_dtypetorch.float16 ) # 2. 换更快的采样调度器并开启显存优化低显存 GPU 必开 pipe.scheduler UniPCMultistepScheduler.from_config(pipe.scheduler.config) pipe.enable_model_cpu_offload() # 把模型按需在 CPU/GPU 间搬运省显存 # 3. 准备输入原图 掩码白色要修复的区域 init_image cv2.imread(examples/brushnet/src/test_image.jpg)[:, :, ::-1] mask_image 1 * (cv2.imread(examples/brushnet/src/test_mask.jpg).sum(-1) 255)[:, :, np.newaxis] init_image init_image * (1 - mask_image) # 把修复区域从原图中挖掉 init_image Image.fromarray(init_image.astype(np.uint8)).convert(RGB) mask_image Image.fromarray((mask_image * 255).astype(np.uint8).repeat(3, -1)).convert(RGB) # 4. 推理caption 描述要补什么内容 image pipe( A cake on the table., init_image, mask_image, num_inference_steps50, # 步数越多质量越好、越慢 generatortorch.Generator(cuda).manual_seed(1234), brushnet_conditioning_scale1.0 # BrushNet 条件强度越小越依赖文字描述 ).images[0] # 5. 保存结果 image.save(output.png)运行python examples/brushnet/test_brushnet.py几分钟后在当前目录得到output.png。对比原图与仓库里展示的效果样例如examples/brushnet/src/example_4.jpeg对应的修复结果examples/brushnet/src/example_4_result.png修复区域应与 caption 一致且边缘过渡自然。如果生成的修复内容和文字描述无关多半是brushnet_conditioning_scale开太大、BrushNet 特征压过了文本处理降到 0.5~0.8 再试。避坑清单现象CUDA out of memory。原因fp16 全流程仍超出显存。处理保留enable_model_cpu_offload()并加一行pipe.enable_attention_slicing()SDXL 模型建议显存 16GB。现象from_pretrained报路径或格式错误。原因目录名写错或缺少model_index.json。处理ls data/ckpt/模型目录确认基座目录下有model_index.json、vae/、unet/等子目录。现象装依赖时报版本冲突。原因requirements 锁定了accelerate0.20.3、Pillow9.5.0等旧版本。处理在干净 conda 环境里按torch →pip install -e .→ requirements.txt顺序重装别混用系统 python。现象开了enable_xformers_memory_efficient_attention()后报错。原因xformers 与 torch 2.0 不兼容。处理删掉该行脚本里默认就是注释掉的。现象修复区域没生效输出和原图几乎一样。原因掩码约定是白色为修复区黑底白区的掩码反了。处理确认test_mask.jpg中待修复部分是纯白。性能优化建议方法收益适用场景UniPC 调度器采样提速质量基本不变所有推理enable_model_cpu_offload()显存需求大幅降低8~12GB 显存enable_attention_slicing()分段计算注意力进一步省显存高分辨率图减少num_inference_steps直接线性提速快速预览/调参下一步可以继续做的事换 SDXL 模型把路径与 pipeline 换成StableDiffusionXLBrushNetPipelinesegmentation_mask_brushnet_ckpt_sdxl_v0参考 examples/brushnet/test_brushnet_sdxl.py。起一个网页交互界面python examples/brushnet/app_brushnet.py用 Gradio 上传图片、掩码和 prompt 在线修复。量化评估python examples/brushnet/evaluate_brushnet.py在 BrushBench 上算 CLIPScore、LPIPS、PSNR 等指标。用自己的数据微调按 README 的数据目录格式准备data/BrushData用accelerate launch examples/brushnet/train_brushnet.py训练工业场景如商品图、虚拟试穿建议这么做。容器化部署用pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime作基础镜像pip install -e .后再装示例依赖即可。三步装好环境、五个模型目录落位、一份最小脚本你就完成了第一次 BrushNet 图像修复——现在就去output.png里看看效果吧。【免费下载链接】BrushNet[ECCV 2024] The official implementation of paper BrushNet: A Plug-and-Play Image Inpainting Model with Decomposed Dual-Branch Diffusion项目地址: https://gitcode.com/GitHub_Trending/br/BrushNet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考