AB
AB
AiBoss站

全部分类

教程

IOPaint

教程

用 IOPaint 本地部署并完成图片去水印与物体擦除

IOPaint 是一款开源的 AI 图像修复工具，能在本地把水印、路人、瑕疵从图片里擦掉，也能做超分辨率、人脸修复和抠图。本文从环境准备讲到 pip 安装、服务启动、Web 界面涂抹蒙版、模型选择与常见故障处理，给出可直接复制的命令和一条完整跑通的示例。

IOPaint 是一款开源的 AI 图像修复与编辑工具，核心能力是「擦除」：在图片上涂抹出要处理的区域，由模型把这块区域重新生成，从而去掉水印、路人、杂物、文字或皮肤瑕疵。它同时集成了若干可插拔的增强功能，包括超分辨率、人脸修复和背景移除。适合需要在本地处理图片、不希望把素材上传到第三方服务的人，也适合想按自己的模型和硬件配置做二次开发的开发者。本文按「装好 → 启动 → 在界面里擦掉一块内容 → 换模型处理更复杂的场景」的顺序讲，命令都可以直接复制。站内还有 IOPaint 的工具条目，可以先看一眼它支持的能力范围再决定是否本地部署。

准备工作

硬件与系统

IOPaint 可以纯 CPU 运行，也可以在有 NVIDIA GPU 且 CUDA 环境配置正确时用 GPU 加速。CPU 模式对机器要求低，但处理速度慢；GPU 模式快很多，前提是驱动和 CUDA 已经装好。素材没有给出具体的显存门槛，实际能跑多大的图、能同时开几个插件，取决于所选模型和显卡，建议先用小图试跑再上大图。

Python 与依赖版本

IOPaint 通过 pip 分发，需要 Python 环境。素材列出的依赖版本要求如下，安装时如果遇到版本冲突，可以对照这张表排查：

依赖包版本要求
torch>=2.0.0
opencv-python未限定
diffusers==0.27.2
huggingface_hub==0.25.2
accelerate未限定
peft==0.7.1
transformers>=4.39.1
safetensors未限定
controlnet-aux==0.0.3
fastapi==0.108.0
uvicorn未限定
python-multipart未限定
python-socketio==5.7.2
typer未限定
pydantic>=2.5.2
rich未限定
loguru未限定
yacs未限定
piexif==1.1.3
omegaconf未限定
easydict未限定
gradio==4.21.0
typer-config==1.4.0
Pillow==9.5.0

这些版本号来自素材记录的某个发布版本，后续版本可能调整依赖约束，安装前建议以项目当前发布信息为准。

两种安装路线怎么选

  • pip 直接安装：适合想快速体验、不需要改前端或深度定制的人。一条命令装完就能启动。
  • 源码克隆安装：适合开发者，需要自定义前端界面，或者想用尚未发布到包管理器的开发版功能。代价是要额外装 Node.js 并自己构建前端。

如果只是想把水印擦掉，走第一条路线即可。

操作步骤

第一步：创建并激活虚拟环境

虚拟环境不是必须的，但能避免 IOPaint 的依赖和你机器上已有的 Python 包互相覆盖。命令按平台区分：

python -m venv iopaint_env

# Linux / macOS
source iopaint_env/bin/activate

# Windows
iopaint_env\Scripts\activate

激活后命令行提示符前通常会出现环境名，确认当前 pip 指向的是这个环境再继续。

第二步：安装 IOPaint

pip install iopaint

如果下载速度慢，可以指定一个就近的 PyPI 镜像源来装，例如：

pip install iopaint -i <镜像源地址>

镜像源地址请使用你所在网络环境下可用的那一个，本文不指定具体站点。安装过程会拉取 torch 等体积较大的包，耗时取决于网络。

第三步：启动 Web 服务

最基础的启动命令如下：

iopaint start --model=lama --device=cpu --port=8080

三个参数的含义：

  • --model：指定默认使用的模型。lama 是一个高效的擦除模型，速度快、效果自然，适合作为默认选择。
  • --device：计算设备。cpu 表示用 CPU；如果机器有 NVIDIA GPU 且 CUDA 配置正确，换成 cuda 会快很多。
  • --port：服务端口，默认 8080。端口被占用时改成别的值即可。

启动成功后，在浏览器访问 http://localhost:8080 就能打开操作界面。

第四步：按需启用插件

除了擦除，IOPaint 把超分辨率、人脸修复、抠图、交互式分割做成了插件，启动时显式打开才会出现在界面里：

iopaint start \
  --model=lama \
  --device=cuda \
  --port=8080 \
  --enable-interactive-seg \
  --enable-remove-bg \
  --enable-realesrgan \
  --enable-gfpgan

各开关对应的能力：

  • --enable-interactive-seg：交互式分割，用点选的方式快速圈出要处理的对象，省去手动涂抹。
  • --enable-remove-bg：移除背景，一键抠图。
  • --enable-realesrgan：超分辨率，放大图片的同时补充细节。
  • --enable-gfpgan：人脸修复，针对老照片或模糊人脸做高清还原。

插件开得越多，启动时加载的东西越多，首次使用还会触发模型下载。只开当前需要的即可。

第五步：在 Web 界面里完成一次擦除

界面操作的核心流程只有四步：

  1. 上传图片：点击 Upload，或者直接把图片拖进工作区。
  2. 涂抹蒙版：用左侧的画笔工具，在要去掉的水印、物体或瑕疵上涂满。被涂到的区域会以高亮色显示，方便确认范围。画笔大小可以用键盘上的 [ 和 ] 快速缩放。
  3. 选模型并执行：在右侧面板选择模型，点击 Run 开始处理。
  4. 保存结果：处理完成后点击 Save 下载修复后的图片。

涂抹范围要略大于目标本身，边缘留一点余量，模型才有足够上下文把这块区域补得自然；但也不要涂到不该改的地方，否则那部分也会被重新生成。

第六步：按场景选模型

IOPaint 集成了多种模型，选错模型是效果不理想最常见的原因。对应关系如下：

要解决的问题推荐模型 / 插件说明
去水印、去物体、去人物、修瑕疵LaMa速度快，补全结果自然，是最通用的擦除选择
在指定区域用文字描述生成或替换内容PowerPaint、Stable Diffusion Inpainting属于「智能内容替换」，需要输入文本提示
放大图片并提升清晰度RealESRGAN（插件）启动时加 --enable-realesrgan
修复老旧照片、模糊人脸GFPGAN（插件）启动时加 --enable-gfpgan
一键移除背景RemoveBG（插件）启动时加 --enable-remove-bg

如果只是去水印，LaMa 就够用；需要「把这块换成一只猫」这类生成式替换，才切到 PowerPaint 或 Stable Diffusion Inpainting。

第七步（可选）：从源码安装

需要改前端或跟进开发版时，走源码路线。先装好 Node.js 和 Python，然后：

git clone <仓库地址>
cd IOPaint
pip install -r requirements.txt
cd web_app
npm install
npm run build

后端依赖装完后，前端资源需要单独构建，构建产物会被后端服务读取。仓库地址请以项目当前公布的信息为准，本文不给出具体链接。

一个完整示例

下面从零开始，把一个带水印的图片处理干净，全程使用 CPU 和 LaMa，不启用任何插件，是最小可跑通的路径。

1. 建环境并安装

python -m venv iopaint_env
source iopaint_env/bin/activate
pip install iopaint

Windows 下把第二行换成 iopaint_env\Scripts\activate。

2. 启动服务

iopaint start --model=lama --device=cpu --port=8080

终端不再输出新的日志、并提示服务已在监听时，说明启动完成。首次启动可能会下载模型权重，需要等待。

3. 打开界面

浏览器访问 http://localhost:8080。

4. 处理图片

  • 把带水印的图片拖进工作区。
  • 用画笔把水印完整涂一遍，涂的时候按 [ 或 ] 调整笔刷，让笔刷略大于水印笔画宽度。
  • 确认右侧模型是 LaMa，点击 Run。
  • 观察结果，满意就点 Save 保存。

5. 效果不理想时

如果水印位置留下了明显的模糊块或颜色断层，先检查涂抹范围：范围太小时模型缺少上下文，范围过大时又会把周围正常内容一起重绘。调整后重新 Run。仍然不行，再换模型试。

6. 需要放大或修脸时

停掉服务，换成带插件的启动命令：

iopaint start --model=lama --device=cpu --port=8080 --enable-realesrgan --enable-gfpgan

重新打开界面，就能看到超分辨率与人脸修复的入口。

注意事项

模型下载与手动放置

首次使用某些模型时，IOPaint 会自动联网下载权重。如果下载缓慢或失败，可以手动下载模型文件，放到模型目录下，通常是 models\torch\hub\checkpoints。放好之后重启服务再试。

速度慢怎么办

  • 有 NVIDIA GPU 且 CUDA 配置正确时，把 --device=cpu 改成 --device=cuda，这是最直接的提速手段。
  • 配置较低的机器保持 CPU 模式，并选用 lama 这类轻量模型，可以减少内存占用。
  • 不需要的插件不要开，插件会额外占用内存和显存。

GFPGAN 插件的依赖冲突

安装人脸修复插件时可能遇到依赖冲突。可以拆开逐个安装它的依赖：

pip install facexlib
pip install tb-nightly
pip install gfpgan

如果某一步下载慢，同样可以指定就近的镜像源。

修复效果不佳的排查顺序

  1. 先看涂抹范围是否准确，边缘是否留了余量。
  2. 再换模型，去水印类问题优先试 LaMa，生成式替换再试 PowerPaint 或 Stable Diffusion Inpainting。
  3. 最后考虑图片本身分辨率是否过低，必要时先用超分辨率插件放大再处理。

版本与信息时效

本文涉及的依赖版本、模型名称、插件开关均以素材记录的发布版本为准。IOPaint 迭代较快，参数名、默认端口、可用模型和插件列表都可能变化，安装与使用前请以项目当前发布的信息为准。价格、算力配额等商业信息不在本文范围内，如需使用云 GPU 请自行核对服务商当前的计费规则。

返回