IOPaint/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

IOPaint 是一个免费开源的图像修复(inpainting)和扩展(outpainting)工具,基于最先进的 AI 模型。项目包括 Python 后端(FastAPI)和 React TypeScript 前端(Vite)。

关键特性:

• 支持多种 AI 模型:LaMa、Stable Diffusion、SDXL、BrushNet、PowerPaint、AnyText 等
• 插件系统:Segment Anything、RemoveBG、RealESRGAN、GFPGAN 等
• 批处理功能
• WebUI 界面和命令行界面
• 支持 CPU、GPU、Apple Silicon

常用命令

开发环境设置

前端开发:

cd web_app
npm install
npm run dev  # 开发服务器运行在 http://localhost:5173

前端构建:

cd web_app
npm run build
cp -r dist/ ../iopaint/web_app

后端开发:

pip install -r requirements.txt
python3 main.py start --model lama --port 8080 --device cpu

安装插件依赖:

iopaint install-plugins-packages

生产环境

安装并启动:

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

批处理图像:

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

下载模型:

iopaint download --model runwayml/stable-diffusion-inpainting

列出已下载的模型:

iopaint list

构建与发布

构建 Python 包:

bash publish.sh
# 会构建前端并打包成 wheel

构建 Docker 镜像:

bash build_docker.sh <version_tag>

架构概览

后端架构 (iopaint/)

入口点流程:

1. __init__.py::entry_point() - 主入口,处理 Windows PyTorch 修复
2. cli.py::typer_app - Typer CLI 应用,定义所有命令(start, run, download, list)
3. api.py::Api - FastAPI 应用,处理 WebUI 和 REST API
4. model_manager.py::ModelManager - 核心模型管理器,负责加载和切换模型

模型系统:

• model/base.py::InpaintModel - 所有模型的抽象基类
• 模型实现分为两类:
  • 擦除模型 (erase models): LaMa, MAT, MI-GAN, OpenCV2, Manga 等 - 用于移除物体、水印
  • 扩散模型 (diffusion models): SD, SDXL, ControlNet, BrushNet, PowerPaint, AnyText 等 - 用于替换物体或扩展图像
• 每个模型实现 forward() 方法,接收图像、mask 和 InpaintRequest 配置

插件架构:

• plugins/base_plugin.py::BasePlugin - 插件抽象基类
• 插件独立于主模型运行,可以启用/禁用
• 主要插件: InteractiveSeg, RemoveBG, AnimeSeg, RealESRGAN, GFPGAN, RestoreFormer

文件管理:

• file_manager/ - 处理图像浏览、存储后端(本地文件系统)

批处理:

• batch_processing.py::batch_inpaint() - 批量处理图像的主函数

前端架构 (web_app/)

• React + TypeScript + Vite
• 使用 Recoil/Zustand 进行状态管理
• TailwindCSS + Radix UI 组件
• Socket.IO 用于实时通信
• React Query 用于数据获取

数据流

WebUI 模式:

1. 用户在浏览器中操作(绘制 mask、选择模型、调整参数)
2. 前端通过 HTTP API 发送 InpaintRequest 到 FastAPI 后端
3. api.py 接收请求,调用 ModelManager
4. ModelManager.__call__() 预处理图像,调用模型的 forward()
5. 模型返回修复后的图像
6. 后端将结果返回给前端显示

批处理模式:

1. CLI 命令触发 batch_processing.py
2. 遍历输入目录中的图像和 mask
3. 为每个图像调用 ModelManager
4. 保存结果到输出目录

模型加载与管理

• download.py::scan_models() - 扫描本地和 HuggingFace 可用模型
• ModelManager.init_model() - 根据模型类型初始化相应的模型类
• 支持动态模型切换(通过 /api/v1/switch_model 端点)
• 模型文件缓存在 ~/.cache (可通过 --model-dir 修改)

关键配置模式

模型配置:

• SD/SDXL 模型使用 model/original_sd_configs/ 中的 YAML 配置
• AnyText 使用专门的 model/anytext/anytext_sd15.yaml

设备管理:

• 支持 CPU、CUDA、MPS(Apple Silicon)
• helper.py::switch_mps_device() - 处理 MPS 不兼容的模型
• model/utils.py::torch_gc() - 清理 GPU/CPU 内存

HD 策略:

• schema.py::HDStrategy - 处理高分辨率图像的策略(CROP, RESIZE, ORIGINAL)
• 大图像会被分块处理或调整大小

重要注意事项

添加新模型

1. 在 model/ 目录创建新的模型文件
2. 继承 InpaintModel 基类
3. 实现 init_model() 和 forward() 方法
4. 在 model/__init__.py 注册模型
5. 更新 const.py 中的 AVAILABLE_MODELS 或 DIFFUSION_MODELS

前端开发

• 前端代码修改后自动热重载
• 后端代码修改需要重启服务
• 创建 web_app/.env.local 文件配置后端地址:

  VITE_BACKEND=http://127.0.0.1:8080
  

性能优化选项

• --low-mem: 低内存模式,减少 VRAM 使用
• --cpu-offload: CPU 卸载,将部分模型移到 CPU
• --no-half: 禁用半精度(FP16),提高精度但增加内存使用
• --cpu-textencoder: 将文本编码器放在 CPU 上

环境变量

项目在 __init__.py 中设置了关键的 PyTorch 环境变量:

• PYTORCH_ENABLE_MPS_FALLBACK=1 - 启用 MPS 回退
• TORCH_CUDNN_V8_API_LRU_CACHE_LIMIT=1 - 防止 GPU 上的 CPU 内存泄漏

Docker 支持

• docker/CPUDockerfile - CPU 版本
• docker/GPUDockerfile - GPU 版本(需要 NVIDIA GPU)
• 使用 build_docker.sh 构建镜像

依赖管理

• requirements.txt - 生产依赖（已更新到最新兼容版本）
• requirements-dev.txt - 开发依赖(wheel, twine, pytest-loguru)
• web_app/package.json - 前端依赖
• PyTorch 版本: >= 2.0.0
• Python 版本: >= 3.7

包版本更新 (2025-11-28)

项目依赖已更新到最新稳定版本：

• diffusers: 0.27.2 → 0.35.2+
• huggingface_hub: 0.25.2 → 0.26.0+
• peft: 0.7.1 → 0.13.0+
• transformers: 4.39.1+ → 4.45.0+
• controlnet-aux: 0.0.3 → 0.0.9+
• fastapi: 0.108.0 → 0.115.0+
• gradio: 4.21.0 → 5.0.0+ (限制 < 6.0.0)
• python-socketio: 5.7.2 → 5.11.0+
• Pillow: 9.5.0 → 10.0.0+

代码修改:

• 修复了 iopaint/model/ldm.py:279 中 torch.cuda.amp.autocast() 的弃用警告，改为 torch.amp.autocast('cuda')

安装建议:

• 优先使用国内镜像源加速安装：

  pip3 install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
  

常见模式

图像处理流程

1. helper.py::load_img() - 加载图像
2. helper.py::decode_base64_to_image() - 解码 base64 图像
3. helper.py::adjust_mask() - 调整 mask 大小和格式
4. helper.py::pad_img_to_modulo() - 填充图像到模型要求的倍数
5. 模型处理
6. helper.py::pil_to_bytes() / numpy_to_bytes() - 转换输出格式

WebSocket 通信

• 使用 Socket.IO 进行实时通信
• 主要用于长时间运行的任务进度更新
• 定义在 api.py 的 Socket.IO 服务器中