企业官网建设流程全解析

IOPaint 图像修复快速上手指南：一条命令完成抹除、重绘与批量处理

【免费下载链接】IOPaintImage inpainting tool powered by SOTA AI Model. Remove any unwanted object, defect, people from your pictures or erase and replace(powered by stable diffusion) any thing on your pictures.项目地址: https://gitcode.com/GitHub_Trending/io/IOPaint

IOPaint 是一个免费开源的 AI 图像修复工具：用一条命令启动本地 Web 服务，就能抹掉照片里的水印、路人、文字，或用扩散模型把旧物体替换成新内容。仓库内置 8 个轻量擦除模型与 11 个可加载的扩散模型，CPU、NVIDIA GPU、Apple Silicon 都能跑，图片全程不离开本机。

它解决什么问题：先讲清三个修图场景

本节帮你判断"我这种需求它能不能干"，三个场景各对应一条真实工作流。

场景一：照片里有碍眼物体，只想擦掉。手工仿制容易糊边，而 IOPaint 让你用掩码圈住目标区域，交给 LaMa 等擦除模型重绘，默认模型就是lama，CPU 可跑：

场景二：擦掉之后还想换成别的内容。纯擦除只能"填空白"，扩散模型则能按文本提示重画，支持 outpainting 扩边。可选模型 ID 集中在 const.py 的DIFFUSION_MODELS列表中，如Sanster/PowerPaint-V1-stable-diffusion-inpainting、Sanster/AnyText。

场景三：一次要处理几百张图。网页一张张点太慢，改用run子命令批处理：--mask传目录时掩码须与原图同名，传单个文件则所有原图共用该掩码（说明出自 cli.py 参数 help 文本）。

核心原理一次看懂：主干 UNet 加一个零初始化旁路

本节用 10 分钟建立正确心智模型，之后看源码不迷路。

打个比方：补墙时粉刷工（主干 UNet）边刷边问手里拿着"原墙照片加破洞位置图"的监理（BrushNet 条件网络）要参考，每到一个施工高度就递一份备忘录。技术上，PowerPaint V2 让一个与主干同构的BrushNetModel并行前向，把各层降采样/上采样结果注入主干。

先看入口如何发起一次修复，power_paint_v2.py 的forward核心逻辑：

image = image * (1 - mask / 255.0) # 掩码区域先乘零抹黑 promptA, promptB, negative_promptA, negative_promptB = task_to_prompt( config.powerpaint_task ) output = self.model( image=image, mask=mask, promptA=promptA, promptB=promptB, promptU=config.prompt, tradoff=config.fitting_degree, brushnet_conditioning_scale=1.0, num_inference_steps=config.sd_steps, guidance_scale=config.sd_guidance_scale, )

两个细节值得注意：原始外观信息在编码前就被抹去，改由条件通道携带；任务类型经task_to_prompt映射成固定提示词，用户提示词走promptU。

条件又是如何进来的？看 BrushNet_CA.py 中BrushNetModel的三处关键代码：

brushnet_cond = torch.concat([sample, brushnet_cond], 1) # 噪声潜变量与条件图拼通道 sample = self.conv_in_condition(brushnet_cond) brushnet_block = zero_module(brushnet_block) # 各层注入头零初始化

类初始化里conditioning_channels=5，即"4 通道原图潜变量加 1 通道掩码"。零初始化是稳妥的工程设计：条件通路起点输出全零，主干行为与原始 SD 完全一致，条件能力只能"加分"不会先"拆房"。

装配关系在 model_manager.py 的init_model：请求开启enable_powerpaint_v2且模型support_powerpaint_v2时实例化PowerPaintV2，它通过 monkey patch 把主干 UNet 与各 down/up block 的forward换成可接收条件嵌入的版本。

快速上手：安装、启动与常用参数对照表

本节走完"装好、跑起来、看懂参数"三步，命令均可直接复制。

环境要求：Python 3 环境；GPU 用户建议先装 CUDA 版 PyTorch（README 给出的组合是torch==2.1.2配cu118）；依赖版本约束见 requirements.txt，其中diffusers==0.27.2、fastapi==0.108.0为固定版本。

安装与首次运行：

# GPU 用户先装 CUDA 版 PyTorch（README 原样注释） # pip3 install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu118 pip3 install iopaint iopaint start --model=lama --device=cpu --port=8080

启动后浏览器访问http://localhost:8080即可使用。模型在首次启动时自动下载；用--model-dir或设置XDG_CACHE_HOME环境变量可改下载目录。

批量处理：

iopaint run --model=lama --device=cpu \ --image=/path/to/image_folder \ --mask=/path/to/mask_folder \ --output=output_dir

start常用参数对照表（取值来自 cli.py 选项定义与 const.py 帮助文本）：

插件类开关另有--enable-interactive-seg（Segment Anything 交互式分割）、--enable-remove-bg、--enable-gfpgan等，插件实现集中在 plugins/，全集可用iopaint start --help查看。

效果与数据：模型能力一览与官方样例对比

本节给你一张可核查的模型选择表，以及仓库自带样例图，按场景对号入座。

按 const.py 的AVAILABLE_MODELS与MPS_UNSUPPORT_MODELS整理：

仓库没有预置跑分结果，但自带基准工具 benchmark.py：测试条件固定为 512×512 随机图、sd_steps=5、ddim 采样，默认重复 10 次，逐轮记录耗时（ms）、内存（MB）、显存（MB），按"均值 ± 标准差"输出：

python -m iopaint.benchmark --name=lama --device=cuda --times=10

对比不同模型时把--name换掉即可；具体数值随显卡与驱动浮动，以自测输出为准。

效果样图（均为仓库assets/内的官方样例，同组左为修复前、右为修复后）：

进阶调优与避坑：显存、黑图、离线三个高频问题

按"问题—原因—解决办法"处理，三条都源自参数帮助文本与源码里的现成开关。

问题一：GPU 显存不够，跑扩散模型报 OOM。原因：SD 级模型权重加中间激活占显存大，默认全部常驻 GPU。 解决办法：按代价从小到大组合三个开关——--low-mem（attention slicing + VAE tiling）、--cpu-offload（权重卸载到 CPU 内存）、--cpu-textencoder（仅文本编码器放 CPU）。三个开关的帮助文本均在 const.py 中。

问题二：扩散模型出图总是全黑或全绿。原因：精度问题，半精度 fp16 在部分硬件上数值溢出。 解决办法：加--no-half强制 fp32 全精度。这是 NO_HALF_HELP 中写明对症的开关，代价是更慢、更占内存。

问题三：首次启动长时间卡在模型下载，或服务器无外网。原因：模型默认从 HuggingFace 自动拉取，慢网会显得像卡死。 解决办法：有网时先用iopaint download --model=<模型ID>预下载，iopaint list查看已下载清单；无网环境把权重放进模型目录后加--local-files-only，该开关会同时设置TRANSFORMERS_OFFLINE=1与HF_HUB_OFFLINE=1（逻辑见 cli.py 的start函数）。

补充一个软性问题：切换模型后旧权重不会立刻释放。model_manager.py 的switch方法会先del self.model再调用torch_gc()回收，且新模型加载失败时回滚到旧模型，所以网页里来回切模型是安全的。

生态与参与：插件、测试与前端构建入口

本节给你三条能直接上手的参与路径：写插件、跑测试、改前端。

• 插件扩展：Segment Anything、RemoveBG、RealESRGAN、GFPGAN、RestoreFormer 等以独立模块放在 plugins/（如 plugins/segment_anything2/），基类在 base_plugin.py，新插件对齐基类实现后在 cli.py 注册启动开关即可。
• 模型扩展：新模型参照 lama.py 的结构实现，再登记进 model/init.py 的models字典；请求字段统一在 schema.py 的InpaintRequest中。
• 测试：用例在 tests/ 目录，单文件可直接跑，例如：

python -m pytest iopaint/tests/test_load_img.py -v

• 前端：React + Vite 工程在 web_app/，构建流程为cd web_app && npm install && npm run build，把dist/复制到iopaint/web_app即被后端静态服务（README「Development」一节同款流程）；本地开发用npm run dev，并在web_app/.env.local里写VITE_BACKEND=http://127.0.0.1:8080。
• 部署：仓库附带 docker/ 下的 CPU 与 GPU 两种 Dockerfile，以及build_docker.sh。

写在最后

IOPaint 把"擦除—替换—扩边"三类图像修复任务收敛进同一个本地服务：lama负责抹，扩散模型负责画，PowerPaint V2 用 5 通道条件把两者接起来，批处理与插件把单图能力放大到产线。下一步建议很具体：用iopaint start --model=lama --port=8080打开网页，拿 assets/ 里的unwant_person.jpg练手一次掩码擦除；跑通后再把--model换成扩散模型，体会文本引导重绘的差异。

【免费下载链接】IOPaintImage inpainting tool powered by SOTA AI Model. Remove any unwanted object, defect, people from your pictures or erase and replace(powered by stable diffusion) any thing on your pictures.项目地址: https://gitcode.com/GitHub_Trending/io/IOPaint