BrushNet 快速上手：5 分钟跑通 ECCV 2024 即插即用图像修复模型-北京尧图网络

BrushNet 快速上手5 分钟跑通 ECCV 2024 即插即用图像修复模型【免费下载链接】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/BrushNetBrushNet 是论文《BrushNet: A Plug-and-Play Image Inpainting Model with Decomposed Dual-Branch Diffusion》ECCV 2024的官方实现一个即插即用的文本引导图像修复模型。这篇教程带你从环境搭建到跑通第一次图像修复只要 3 步、约 5 分钟全程只给跑通所必需的命令和参数并附高频报错避坑手册。一、价值主张它替你解决什么还在为图像修复头疼吗——擦掉照片里的路人边缘留下一圈鬼影想换掉背景一角补出来的纹理和周围对不上。传统做法要么重训整个扩散模型要么忍受边缘不自然、内容不连贯的结果。BrushNet 的思路是把修复任务拆成两条支路一条负责读懂原图里要保留的内容另一条负责往掩码区域填新内容两支路并联进现有的 Stable Diffusion UNet。因为只是插上一个独立模块你已有的基础模型SD 1.5 / SDXL一行都不用动这就是它即插即用的含义。读完本文你能带走✅ 一套 3 步跑通流程装环境 → 放模型 → 出第一张修复图✅ 5 个关键参数条件强度、推理步数、种子、混合融合等的调节依据✅ 4 个高频报错的现象 → 原因 → 解决排查路径✅ 从 Gradio 演示界面、Docker 部署到自定义训练的落地路线弄清了它是什么下面先把前置条件核一遍避免装到一半才发现硬件不达标。二、上手前准备一张表核对前置条件开始之前对照下表确认你的环境。最容易被忽略的是磁盘空间——基础模型加 BrushNet 权重加起来约 10GB。项目最低要求推荐配置Python3.83.9 ~ 3.10PyTorch1.12含 CUDA 支持2.0CUDA 11.8GPU 显存8GB需开启 CPU 卸载16GB磁盘空间10GBSD 1.5 模型组30GB含 SDXL 与训练数据操作系统Linux / Windows / macOSUbuntu 20.04条件齐了就可以进入真正动手的 3 步。三、跑通主流程3 步出第一张修复图步骤 1环境准备2 条命令装好依赖BrushNet 是基于diffusers修改的版本必须先装仓库里的diffusers再装示例依赖顺序反了容易出依赖冲突。# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/br/BrushNet.git cd BrushNet # 安装本仓库的 diffusers核心 pip install -e . # 安装 BrushNet 示例依赖含 accelerate、gradio、SAM 等 cd examples/brushnet pip install -r requirements.txt步骤 2放模型目录结构一次放对代码里默认从data/ckpt/读模型把模型按下面的结构放好后面所有脚本都不用改路径data/ └── ckpt/ ├── realisticVisionV60B1_v51VAE/ # 基础模型SD 1.5 格式需含 model_index.json ├── segmentation_mask_brushnet_ckpt/ # BrushNet 权重分割掩码版SD 1.5 ├── segmentation_mask_brushnet_ckpt_sdxl_v0/ # BrushNet 权重SDXL 版 └── sam_vit_h_4b8939.pth # Gradio 应用点选掩码用的 SAM 权重说明基础模型也可以直接用 Hugging Face 上的runwayml/stable-diffusion-v1-5等官方模型把脚本里的base_model_path改成对应 id 即可。BrushNet 权重则必须指向上面第 2 类目录。模型就位后直接跑仓库自带的测试脚本它用的就是仓库里现成的示例图和掩码。步骤 3第一次运行1 条命令出图# 回到仓库根目录 python examples/brushnet/test_brushnet.py跑完当前目录会生成output.png这就是第一次修复结果。脚本做的事可以用这张流程图概括脚本里 5 个关键参数第一次运行保持默认即可调优时再回来改参数默认值作用num_inference_steps50采样步数越大质量越好、越慢brushnet_conditioning_scale1.0BrushNet 条件强度越小越依赖原图generator种子1234固定种子保证结果可复现blendedFalse是否用模糊掩码融合结果去接缝torch_dtypefloat16半精度推理显存减半看到第一张图了接下来聊聊怎么判断效果、怎么再快一点。四、看效果与调优以仓库示例 4野外开车场景为例输入、掩码、输出三件套是这样的看效果的要点掩码白色区域按 prompt 重绘非掩码区域应基本保持原样如果修复区和保留区交界处有明显贴片感把blended打开脚本里已有高斯模糊融合的现成实现边缘会自然很多。跑通之后常见优化手段按这张表选方法收益适用场景UniPCMultistepScheduler测试脚本已启用⚡ 采样加速 2-3 倍所有推理场景pipe.enable_model_cpu_offload()测试脚本已启用显存占用大幅降低8GB 显存卡pipe.enable_xformers_memory_efficient_attention()显存再降约 20%已装 xformers 且 Torch 2.0pipe.enable_attention_slicing()注意力显存分段加载高分辨率输入blendedTrue模糊融合去除接缝伪影掩码边界与背景反差大时速度之外真正影响观感的其实还是参数选择下面几个坑基本覆盖了 90% 的翻车现场。五、避坑手册4 个高频问题排雷坑 1CUDA 内存不足现象torch.cuda.OutOfMemoryError: CUDA out of memory原因UNet BrushNet VAE 同时在显存里小显存卡放不下解决测试脚本已默认enable_model_cpu_offload()确认这行没被注释再叠加enable_attention_slicing()仍不够就降到 SD 1.5比 SDXL 省一半显存坑 2加载基础模型报错或权重乱码现象from_pretrained抛OSError或加载成功但出图全噪原因base_model_path指向的不是 diffusers 格式目录——单个.ckpt/.safetensors文件不行必须是含model_index.json、vae/、unet/子目录的完整文件夹解决用仓库 scripts/ 下的转换脚本如convert_ldm_original_checkpoint_to_diffusers.py把单文件权重转成 diffusers 格式再放入data/ckpt/坑 3依赖冲突装完 import 就报错现象pip install -r requirements.txt后import diffusers或import accelerate失败原因requirements.txt固定了accelerate0.20.3、Pillow9.5.0、gradio3.50.0与你环境里已有版本打架解决按纯净 conda 环境 →pip install -e .→ 再装 requirements的顺序重来不要先装最新 accelerate 再降级直接装 requirements 里的固定版本坑 4SDXL 版出图全是 NaN 黑斑现象跑test_brushnet_sdxl.py时 VAE 解码后图像出现大片黑色/NaN原因SDXL 的官方 VAE 在 fp16 下编码不稳定解决test_brushnet_sdxl.py 已经给出做法——换用madebyollin/sdxl-vae-fp16-fix作为pipe.vae排完这些坑你就可以把脚本级演示升级成日常能用的工具了。六、从演示到落地演示脚本跑通只是开始这几条路径能帮你把 BrushNet 变成日常工具① Gradio 交互界面最快出活python examples/brushnet/app_brushnet.py浏览器里上传照片、点选要修复的区域背后是 SAM 自动分割、填 prompt 即可出图注意提前把 SAM 权重放到data/ckpt/sam_vit_h_4b8939.pth。② Docker 部署仓库 docker/ 目录已提供多套 diffusers 官方 DockerfileCUDA / CPU / xformers / ONNX 等可以基于docker/diffusers-pytorch-cuda/Dockerfile叠加自己的模型层FROM pytorch/pytorch:2.0.1-cuda11.8-cudnn8-runtime WORKDIR /app COPY . . RUN pip install -e . pip install -r examples/brushnet/requirements.txt CMD [python, examples/brushnet/app_brushnet.py]③ 量化评测用 evaluate_brushnet.py 对整批结果打分Image Reward、HPS V2.1、PSNR、LPIPS、CLIP Similarity 等输出 CSV 汇总表适合调参数前后做 A/B 对比python examples/brushnet/evaluate_brushnet.py \ --brushnet_ckpt_path data/ckpt/segmentation_mask_brushnet_ckpt \ --image_save_path runs/evaluation_result \ --mapping_file data/BrushBench/mapping_file.json \ --base_dir data/BrushBench \ --mask_key inpainting_mask④ 用自己的数据微调训练脚本支持分割掩码和随机掩码两种模式数据为*.tar的 WebDataset 格式accelerate launch examples/brushnet/train_brushnet.py \ --pretrained_model_name_or_path runwayml/stable-diffusion-v1-5 \ --output_dir runs/logs/custom_brushnet \ --train_data_dir data/custom_dataset \ --resolution 512 \ --learning_rate 5e-6 \ --train_batch_size 2加上--random_mask即切换到随机掩码训练通用修复不加则默认分割掩码训练物体移除更稳。想要更高分辨率仓库同样提供了 SDXL 版推理 test_brushnet_sdxl.py 与训练 train_brushnet_sdxl.py。工具链到这里就齐了最后用 3 句话收个尾。七、总结与下一步BrushNet 的核心优势一句话各一条即插即用——不动基础模型一个模块并联进 UNet已有 SD 1.5/SDXL 直接复用双分支解耦——保留什么和填什么分开建模修复边缘更自然全链路开源——推理、Gradio 演示、批量评测、SD 1.5/SDXL 训练脚本一应俱全可以继续探索的方向用业务数据微调分割掩码版做垂类一键去物工具⚡ 结合 xformers CPU 卸载把 8GB 显存卡的出图压到可交互速度对比brushnet_conditioning_scale0.5/0.8/1.0 的出图差异建立自己的参数直觉现在就克隆仓库、放好模型跑通你的第一张修复图吧踩到文中没覆盖的坑欢迎在评论区贴报错交流觉得有用记得收藏关注后续更新 BrushNet 自定义数据集实战。【免费下载链接】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），仅供参考

BrushNet 快速上手：5 分钟跑通 ECCV 2024 即插即用图像修复模型

相关推荐

Codex-X 指令提示词注入完整指南：一句固定短语验证生效，离线自动降级

动态规划与滚动数组：LeetCode 712 最小ASCII删除和详解

【DL】模型微调方法总结

更多资讯

NLP训练前必做的5大文本数据分析方法

LLaMA-Factory实战指南：个人电脑也能玩转大模型微调

从状态机DP视角彻底搞懂买卖股票系列（LeetCode 121到714）

大模型代理合作与聚合平台：从技术原理到落地实战全解析

git remote prune：清理过期远程跟踪分支，解决仓库迁移后push失败

模式识别三层决策逻辑：不确定性建模、判别结构与优化求解

今日更新

Verilog实现FPGA密码锁：矩阵键盘与状态机设计实战

数据服务监控运维实战：从指标体系到告警治理与故障排查

FreeRTOS任务通知实战详解：内核原理、API与避坑指南

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？