IOPaint AI图像修复完整指南：从安装到批量处理的全流程上手教程-开发者社区

IOPaint AI图像修复完整指南：从安装到批量处理的全流程上手教程

【免费下载链接】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

AI 图像修复类工具最大的劝退点往往不在功能，而在环境：Python 版本、显卡依赖、模型文件下载，任何一步卡住都得推倒重来。IOPaint 是一款完全开源、可本地自托管的 AI 图像修复与扩图工具，抹掉照片里的物体、水印、路人，或用扩散模型替换、补全画面内容，都能在浏览器界面里完成。本文手把手带你从装好环境到跑通第一张修复图，并覆盖模型切换、批量处理与插件启用，全程以可验证的结果为准。

安装步骤：Windows 环境配置与启动

先确认硬件底线：Windows 10/11、内存 8 GB 以上（推荐 16 GB）；想跑扩散模型建议配 NVIDIA 显卡；首次启动会联网拉取模型文件，网络要通畅。

获取代码。克隆仓库并进入目录：
```
git clone https://gitcode.com/GitHub_Trending/io/IOPaint cd IOPaint
```
验证标准：目录下能看到scripts/、iopaint/、web_app/等文件夹。
双击运行scripts/user_scripts/win_setup_cn.bat。该脚本会在项目内创建 Python 虚拟环境并装好依赖：
脚本内部逻辑：激活虚拟环境 → 将 pip 全局源指向清华/Tencent 镜像 → 安装 CUDA 版 PyTorch（torch 2.1.2 + cu118）→pip3 install -U iopaint→ 执行iopaint install-plugins-packages预装插件依赖。
验证标准：命令窗口走完流程后停留在PAUSE，无红色报错。
双击运行scripts/user_scripts/win_start_cn.bat启动服务。
脚本会先设置HF_ENDPOINT=https://hf-mirror.com（用国内镜像加速 HuggingFace 模型下载），然后读取scripts/installer_config.json中的配置调用iopaint start。
浏览器打开 http://localhost:8080 ，出现 IOPaint 的编辑界面即代表部署成功。首次启动模型会自动下载，期间界面会等待，属正常现象。

不想用脚本的话，也可以在装好 Python 的环境里执行pip3 install iopaint，再运行iopaint start --model=lama --device=cpu --port=8080，效果等价。

上手任务：移除照片里多余的物体

目标：把下面这张图中悬挂的粉色灯笼抹掉，画面自动补全木纹与背景。

在界面左上角上传assets/unwant_object.jpg（任意照片都可以）。
选择画笔工具，调大笔刷，把粉色灯笼整个涂抹成遮罩；涂多了再擦掉一点，保证遮罩只覆盖要移除的部分。
右侧保持默认模型 Lama，直接点击"生成"。
等待约几秒，原图位置被擦除的灯笼由周围纹理补全，背景光斑自然衔接。
对结果不满意就重新涂抹再试；满意后点"保存"，文件会写入项目配置的输出目录。

第一次跑通这个流程，说明安装、模型、浏览器三条链路都已打通。

进阶用法：模型配置、批量处理与插件扩展

擦除模型与扩散模型怎么切换

日常"抹东西"用擦除模型即可，需要"生成新内容、替换物体、扩展画布"时才上扩散模型，二者速度差异很大：

任务类型	模型	特点	源码位置
移除物体、水印、缺陷	`lama`（默认）	速度快，CPU 可跑	iopaint/model/lama.py
内容替换、修复、扩图	`runwayml/stable-diffusion-inpainting`	依赖提示词，需 GPU 体验更好	iopaint/model/sd.py
在图中绘制文字	`Sanster/AnyText`	专攻文字生成	iopaint/model/anytext/
高质量修复与扩图	PowerPaint	基于 SD 微调	iopaint/model/power_paint/

切换只需改启动参数，例如iopaint start --model=sd --device=cuda；本地已有的 SD ckpt/safetensors 文件也能直接加载。已下载过的模型可用iopaint list查看。

批量处理用法

处理成批图片时不必开界面，用命令行一次跑完（--image指图片文件夹，--mask指与图片同名的遮罩文件夹，也可指定单张遮罩文件复用给所有图片）：

iopaint run --model=lama --device=cpu \ --image=input_images \ --mask=masks \ --output=output_results

实现在 iopaint/batch_processing.py，还可用--concat把原图、遮罩、结果拼成一张对照图。

启用插件

插件按需开启，启动参数即开关：--enable-interactive-seg交互式分割、--enable-remove-bg去背景、--enable-realesrgan超分、--enable-gfpgan人脸修复，并可用--gfpgan-device=cuda这类参数单独指定插件设备。全部插件入口在 iopaint/plugins/。

常见问题速查

8080 端口被占用：启动参数加--port=8081换端口，浏览器同步改地址。
显存不足：追加--low-mem（启用注意力切片与 VAE tiling），或--cpu-offload把权重放到内存，再不行就--device=cpu。
模型下载缓慢或中断：确认启动时设置了HF_ENDPOINT=https://hf-mirror.com（国内镜像），重启服务续传。
扩散模型出图全黑/全绿：加--no-half改用全精度推理。

IOPaint 的安装脚本、模型与插件都集中在仓库内，改任何一步都能对照源码确认。想继续深入，建议按顺序阅读：