一、项目背景从 Lama Cleaner 到 IOPaintIOPaint 的前身是 GitHub 上广为人知的Lama Cleaner——一个基于 SOTA AI 模型的图像擦除与修复工具由国内开发者 Sanster 创建并维护。2024 年起项目正式更名为IOPaintIO 取 Input/Output 之意名称的变更不只是换个马甲背后伴随着一次彻底的前后端重构。这次重构的动因在于 Lama Cleaner 随着功能堆叠代码日渐臃肿难以添加新特性。重构后的技术栈全面升级模块旧技术栈新技术栈前端构建WebpackViteCSS 框架自研样式TailwindCSS状态管理React ContextZustandUI 组件自研组件shadcn/ui后端框架FlaskFastAPI Typer重构后的 IOPaint 架构更清晰、扩展性更强同时新增了 CLI 批量处理命令、完善的 RESTful API 文档以及更丰富的模型与插件支持。截至 2025 年项目在 GitHub 已累计超过 900 次提交Star 数稳步增长社区活跃。GitHub 仓库GitHub - Sanster/IOPaint: Image 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. · GitHub官网文档https://www.iopaint.com二、IOPaint 是什么IOPaint 是一款完全免费开源、可自托管的 AI 图像修复与编辑工具。它的核心能力可以概括为四个字擦、换、写、扩。擦Erase基于 LaMa 等专业擦除模型智能移除照片中的水印、瑕疵、路人、文字等不需要的元素修复效果自然无痕。换Replace利用 PowerPaint 等扩散模型通过文本描述或参考图在指定区域生成新内容实现物体替换。写Draw Text集成 AnyText 模型在图像任意位置生成与场景光影、纹理自然融合的文字支持中英文及多语种。扩Out-painting智能扩展画幅边界AI 自动生成新像素填充扩展区域保持风格一致。除此之外IOPaint 还提供丰富的插件生态Segment AnythingSAM精准分割、RemoveBG 一键去背景、RealESRGAN 超分辨率重建、GFPGAN 人脸修复等几乎覆盖了日常图像后处理的全部需求。三、核心特性一览3.1 完全本地自托管所有模型下载到本地图像处理全程离线完成。图片不会上传到任何服务器适合处理私密照片、商业素材和敏感内容。3.2 全硬件兼容硬件支持情况CPU完全支持仅速度较慢NVIDIA GPU (CUDA)完整加速支持AMD GPU (ROCm)仅 Linux 下可用Apple Silicon (M1/M2/M3)原生支持普通笔记本的 CPU 即可流畅运行高端显卡可实现秒级出图。3.3 双模式操作WebUI 可视化界面浏览器打开即用拖拽上传 → 画笔涂抹 → 一键生成零学习成本。CLI 命令行模式支持批量处理大量图片可接入脚本、定时任务和自动化流水线。3.4 Windows 一键安装包官方提供 Windows 平台的一键安装程序无需配置 Python 环境安装即用。3.5 macOS / iOS 原生应用OptiClean开发者还推出了面向 macOS 和 iOS 的原生应用 OptiClean专门提供物体擦除功能适合移动端场景。四、模型体系深度解析IOPaint 的模型分为三大类擦除模型、扩散模型和其他专用模型。4.1 擦除模型Erase Models专用于移除不需要的物体、缺陷、水印和人物模型特点适用场景LaMa经典擦除模型速度快效果好通用去水印、去路人MAT基于 Transformer 架构对大面积修复更优大面积遮挡修复Manga Inpainting针对漫画/线稿优化动漫、漫画修复FCF快速修复模型轻量级擦除MIGAN针对人物面部优化人像瑕疵修复4.2 扩散模型Diffusion Models用于物体替换和图像扩展支持加载 HuggingFace 上的任意 Stable Diffusion Inpainting 模型runwayml/stable-diffusion-inpaintingdiffusers/stable-diffusion-xl-1.0-inpainting-0.1andregn/Realistic_Vision_V3.0-inpaintingLykon/dreamshaper-8-inpaintingSanster/anything-4.0-inpainting同时支持加载本地的.ckpt/.safetensors单文件模型只需放入model_dir/stable_diffusion或model_dir/stable_diffusion_xl目录即可。4.3 其他专用模型模型功能PowerPaint / PowerPaintV2任务感知的图像编辑文本引导替换、形状引导生成、物体移除、外扩BrushNet可将任意 SD1.5 模型转化为 Inpainting 模型AnyText在图像上生成风格融合的文字中/英文Paint by Example用示例图引导指定区域的内容生成InstructPix2Pix用自然语言指令编辑图像Kandinsky结合 DALL-E 2 和 Latent Diffusion 优势的生成模型4.4 高级特性Cropper裁剪器仅对选定区域执行修复减少计算量。Expander扩展器放大图像尺寸以进行外扩Outpainting。ControlNet可在 Web 界面中启用并选择 ControlNet 模型进行精细化控制。LCM LoRA通常在 2-8 步内完成高质量图像生成大幅提升扩散模型推理速度。Mask Blur蒙版模糊模糊蒙版边缘使修复边界更自然。Match Histograms直方图匹配将修复结果直方图与原始图像匹配增强生成结果的真实感。五、插件生态IOPaint 采用插件化架构启动时通过命令行参数按需启用。启用后的插件会出现在 WebUI 左上角。插件功能启用命令示例Segment Anything (SAM)点击/框选实现精准物体分割--enable-interactive-seg --interactive-seg-devicecudaRemoveBG一键移除图像背景生成透明底--enable-remove-bgAnime Segmentation动漫/二次元专用背景分割--enable-anime-segRealESRGAN图像超分辨率重建提升清晰度--enable-realesrganGFPGAN人脸修复与增强优化五官画质--enable-gfpganRestoreFormer另一种人脸修复方案--enable-restoreformerFileManager浏览本地图片并直接保存到输出目录--enable-file-manager六、安装与启动从零上手6.1 方式一Windows 一键安装推荐新手从 GitHub Releases 下载最新的 Windows 安装包双击运行按向导完成安装。桌面快捷方式启动后自动打开浏览器界面。所有依赖和模型自动配置无需手动干预。6.2 方式二pip 安装推荐开发者前置条件Python 3.8 环境。# 第一步安装 PyTorch如需 GPU 加速 # NVIDIA GPU 用户 pip3 install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118 # AMD GPU 用户仅 Linux pip3 install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/rocm5.6 # 如果仅用 CPU可跳过 PyTorch GPU 版本安装pip install iopaint 会自动拉取 CPU 版 torch # 第二步安装 IOPaint pip3 install iopaint # 第三步启动服务 iopaint start --modellama --devicecpu --port8080启动后在浏览器访问http://localhost:8080即可使用。模型首次启动时自动下载可通过--model-dir指定下载目录。6.3 启用插件启动# 启用交互式分割SAM 人脸修复 iopaint start \ --modellama \ --devicecuda \ --port8080 \ --enable-interactive-seg \ --interactive-seg-devicecuda \ --enable-gfpgan \ --enable-realesrgan \ --enable-remove-bg6.4 使用扩散模型启动# 使用 Stable Diffusion 1.5 Inpainting 模型 iopaint start --modelrunwayml/stable-diffusion-inpainting --devicecuda --port8080 # 使用 PowerPaint iopaint start --modelSanster/PowerPaint-V1-stable-diffusion-inpainting --devicecuda --port8080 # 使用本地 safetensors 文件需先放入 model_dir iopaint start --modelsd-v1-5-inpainting.safetensors --model-dir/path/to/models --devicecuda6.5 方式三从源码构建高级用户git clone https://github.com/Sanster/IOPaint.git cd IOPaint # 安装前端依赖并构建 cd web_app npm install npm run build cp -r dist/ ../iopaint/web_app cd .. # 安装后端依赖并启动 pip install -r requirements.txt python3 main.py start --model lama --port 8080七、实战场景7.1 WebUI 交互式擦除启动服务后在浏览器打开http://localhost:8080。上传目标图片使用画笔工具涂抹要移除的区域。点击生成按钮AI 自动填充被涂抹区域。可调整画笔大小、切换不同擦除模型获得最佳效果。7.2 CLI 批量处理# 批量擦除image 目录下所有图片 mask 目录下对应蒙版 → output 目录 iopaint run \ --modellama \ --devicecuda \ --image/home/user/photos/ \ --mask/home/user/masks/ \ --output/home/user/output/ # 所有图片使用同一张蒙版文件 iopaint run \ --modellama \ --devicecpu \ --image/home/user/photos/ \ --mask/home/user/common_mask.png \ --output/home/user/output/--image为输入图片目录--mask为对应蒙版目录或单个蒙版文件--output为输出目录。7.3 物体替换切换到 PowerPaint 模型后在 WebUI 中涂抹目标区域输入文本描述如 a red sports carAI 会在指定位置生成描述的内容并与背景自然融合。7.4 图像外扩在 WebUI 中选择 Expander 模式拖拽扩展边界AI 自动填充新像素实现无缝画幅扩展。八、RESTful API 集成IOPaint 基于 FastAPI 构建启动后自动生成 OpenAPI 文档。访问http://localhost:8080/docs即可查看所有接口的详细信息并进行在线调试。核心 API 示例import requests # 擦除接口 url http://localhost:8080/api/v1/inpaint files { image: open(input.jpg, rb), mask: open(mask.png, rb), } data {model: lama} response requests.post(url, filesfiles, datadata) # 将返回的图片保存 with open(output.png, wb) as f: f.write(response.content)有了 API 支持可以将 IOPaint 的 AI 修图能力嵌入到自己的 Web 应用、自动化流水线或后端服务中。九、常见问题与排查9.1 pip 安装依赖冲突使用官方提供的国内源安装脚本Windowsscripts/user_scripts/win_setup_cn.bat该脚本已配置清华镜像源和 PyTorch 国内下载地址可解决大多数依赖问题。9.2 显存不足# 启用低内存模式 iopaint start --modelsd --devicecuda --low-mem # 启用 CPU 卸载将部分计算放到 CPU释放显存 iopaint start --modelsd --devicecuda --cpu-offload # 禁用半精度减少显存占用但可能降低生成质量 iopaint start --modelsd --devicecuda --no-half # 指定 GPU 设备 CUDA_VISIBLE_DEVICES0 iopaint start --modelsd --devicecuda9.3 端口被占用# 查看端口占用Windows netstat -ano | findstr 8080 # 指定其他端口 iopaint start --port80819.4 模型下载慢模型默认从 HuggingFace 下载国内用户可能出现下载缓慢的情况。可通过以下方式加速设置 HuggingFace 镜像export HF_ENDPOINThttps://hf-mirror.com手动下载模型到--model-dir指定目录十、总结IOPaint 不是 Lama Cleaner 的简单改名而是一次从架构到体验的全面升级。它在保持完全免费开源、本地自托管的基础上集成了更丰富的模型、更完善的插件系统和更现代的 CLI 工具让 AI 图像修复从玩具真正走向生产力工具。无论是电商图片批量去背景、老照片修复、自媒体配图制作还是将 AI 修图能力通过 API 嵌入到自己的产品中IOPaint 都提供了从零到生产级的完整方案。