IOPaint：AI图像修复擦除工具部署指南

官方信息

项目背景

拍照时不小心闯入路人、截图上有讨厌的水印、老照片上有划痕污渍、想把图片边缘扩展做成壁纸——这些场景用 Photoshop 的内容识别填充虽然能做，但效果不稳定，而且要装几百 MB 的软件。

IOPaint（前身叫 Lama Cleaner）由 Sanster 开发，把当前最先进的图像修复模型（LaMa、LDM、ZITS、MAT、FcF、SD1.5/2 inpaint、BrushNet 等）全部整合到一个 Web 界面里。你上传图片，用画笔涂抹要擦除的区域，AI 自动根据周围内容智能填充。除了擦除，还支持外扩（Out-painting）扩展画幅、文字生成（Draw Text）、对象替换等高级功能。

项目在 GitHub 上收获超过 25K Star，是图像修复领域最受欢迎的开源工具，被广泛用于电商修图、照片修复、设计素材处理等场景。

核心特性

• 多模型集成：内置 LaMa、LDM、ZITS、MAT、FcF、SD Inpaint、BrushNet 等 10+ 模型
• 一键擦除：画笔涂抹要去除的物体/水印/路人，AI 自动修复
• 外扩扩图：把图片边缘向外扩展，比如 4:3 照片扩成 16:9 壁纸
• 文字生成：在涂抹区域用 AI 生成指定文字
• 对象替换：用提示词把涂抹区域替换成新物体
• Web 界面：浏览器操作，无需专业软件
• GPU/CPU 双模式：N 卡加速，CPU 也能跑基础模型
• Windows 一键安装包：小白用户也能轻松上手

环境要求

• 操作系统：Windows 10+/macOS 12+/Ubuntu 20.04+
• Python：3.9 ~ 3.11
• 显卡：NVIDIA GPU 推荐（4GB 显存以上），CPU 可跑 LaMa 模型
• CUDA：11.6+
• 内存：最低 8GB，推荐 16GB
• 磁盘空间：约 5GB（含模型权重）

详细部署步骤

方式一：pip 安装（推荐）

第 1 步：创建虚拟环境

conda create -n iopaint python=3.10 -y
conda activate iopaint

第 2 步：安装 PyTorch（GPU 版）

# CUDA 11.8
pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118

# CPU 版本
pip install torch torchvision

第 3 步：安装 IOPaint

pip install iopaint

第 4 步：启动服务

# 使用 LaMa 模型启动（默认，效果好速度快）
iopaint start --model=lama --device=cuda --port=8080

# CPU 模式
iopaint start --model=lama --device=cpu --port=8080

# 使用 SD Inpaint 模型（需要更多显存）
iopaint start --model=sd15 --device=cuda --port=8080

# 启动后访问 http://localhost:8080

方式二：Windows 一键安装包

1. 前往 Releases 页面
2. 下载 Windows 安装包（如 iopaint-win-x64.zip）
3. 解压后双击 install.bat 自动安装依赖
4. 安装完成后双击 start.bat 启动
5. 浏览器自动打开 http://localhost:8080

方式三：Docker 部署

# 拉取镜像
docker pull sanster/iopaint:latest

# 启动服务（GPU 版本）
docker run -d --gpus all -p 8080:8080 \
  -v ~/.cache/iopaint:/root/.cache/iopaint \
  sanster/iopaint:latest \
  start --model=lama --host=0.0.0.0 --port=8080

# CPU 版本
docker run -d -p 8080:8080 \
  -v ~/.cache/iopaint:/root/.cache/iopaint \
  sanster/iopaint:latest \
  start --model=lama --device=cpu --host=0.0.0.0 --port=8080

方式四：源码部署

git clone https://github.com/Sanster/IOPaint.git
cd IOPaint

conda create -n iopaint python=3.10 -y
conda activate iopaint

pip install -e .
iopaint start --model=lama --port=8080

使用方法

基本擦除操作

1. 浏览器打开 http://localhost:8080
2. 上传要处理的图片
3. 在左侧工具栏选择画笔大小（Brush Size）
4. 用画笔涂抹要擦除的区域（比如水印、路人）
5. 点击"Process"按钮，AI 自动修复
6. 结果满意后点击"Download"下载

模型选择建议

外扩（Out-painting）扩图

1. 在右上角模式切换到"Out-painting"
2. 拖动滑块选择上下左右扩展的像素数
3. 点击"Process"，AI 自动生成边缘内容

常见问题 FAQ

Q1：首次启动模型下载很慢？
A：模型默认从 HuggingFace 下载。国内用户可以设置环境变量：export HF_ENDPOINT=https://hf-mirror.com，使用国内镜像加速。

Q2：macOS M1/M2 报"illegal hardware instruction"？
A：这是 PyTorch MPS 后端的已知问题。在启动时加 --device=cpu 使用 CPU 模式，速度稍慢但稳定。

Q3：擦除效果不理想怎么办？
A：(1) 画笔不要涂太多，刚好覆盖要擦除的物体即可；(2) 尝试切换模型，不同模型擅长不同场景；(3) 大区域分多次擦除，每次只处理一小块。

Q4：如何更新到最新版本？
A：pip 用户执行 pip install -U iopaint；Windows 安装包用户重新运行 install.bat。

Q5：支持批量处理吗？
A：Web 界面目前是单张处理。可以通过 IOPaint 的 Python API 编写脚本批量处理：from iopaint.model_manager import ModelManager。

跳转链接

• GitHub 仓库：https://github.com/Sanster/IOPaint
• 官方文档：https://www.iopaint.com
• Releases 下载：https://github.com/Sanster/IOPaint/releases
• HuggingFace 镜像：https://hf-mirror.com