企业官网建设流程全解析

如何玩转 IOPaint 模型自动下载与本地缓存：3 个配置技巧 + 速查表完整指南

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

IOPaint 的模型下载与模型缓存机制可以概括为一句话：首次用到新模型时自动下载，本地已有的直接跳过。下面讲清这套机制怎么运转，以及 3 个实用配置技巧。

第一次用新模型时发生了什么

整个过程无需手动干预，选完模型就能用。用户视角只有三步：

1. 选模型：在 WebUI 模型列表里点选，或启动时指定，例如iopaint start --model=lama；
2. 自动下载：系统判断该模型不在本地，开始下载。擦除模型（如 LaMa，一种轻量移除算法）走模型类自带的 download 方法，Diffusers 模型则通过 Hugging Face 的 DiffusionPipeline 拉取，相关逻辑在 iopaint/download.py；
3. 直接用：下载完成即加载模型，开始擦除或重绘。

触发判断的机制其实很简单：系统先查本地有没有这个模型，没有才发起下载。

💾 模型都存放在哪里

所有模型都落在一个统一的模型目录里，默认位置由DEFAULT_MODEL_DIR定义：未设置环境变量时就是系统的缓存目录（~/.cache）。Diffusion 类模型文件按系列分类存放：

.cache/ ├── stable_diffusion/ # SD 系列模型 │ ├── model1.safetensors │ └── iopaint_cache.json └── stable_diffusion_xl/ # SDXL 系列模型 └── iopaint_cache.json

两个细节值得注意：

• iopaint_cache.json：记录每个模型文件的类型（基础版还是重绘版）。它相当于索引，扫描时先查这份索引，命中就不用再逐个分析文件内容，启动更快；
• 两种格式都支持：.safetensors（基于安全张量库的权重格式，加载更安全）和.ckpt。SD 与 SDXL 各自分基础版/重绘版四类，基础版用于生成，重绘版（inpaint）专用于区域修复。

系统怎么判断"该不该下载"

判断逻辑就一条：已存在则跳过，避免重复下载。

常见的触发场景有三种：首次以指定模型启动、在 WebUI 切换未缓存的模型、通过 API 调用某模型参数。无论哪种场景，系统都会先调用该模型类自带的is_downloaded()方法——它检查默认模型目录下是否已有完整的模型文件，存在就跳过下载。

下载完之后，模型是怎么被"发现"的

模型列表不是实时现查的。系统启动时会调用scan_models()（由 iopaint/model_manager.py 中的模型管理器触发）汇总三类来源：已下载的擦除模型、单文件 Diffusers 模型、Hugging Face 缓存里的模型。扫描结果整理成ModelInfo列表（含模型名称、路径、类型），缓存在内存里，之后切换模型时直接读取，不用重复扫描磁盘。

三个实用配置技巧

每个技巧都是最短可执行步骤，按需取用。

技巧一：自定义缓存目录。想省事就两步——设置XDG_CACHE_HOME环境变量指向目标盘（如外置硬盘），然后正常启动 IOPaint：

export XDG_CACHE_HOME=/path/to/your/drive/iopaint_cache

这样模型就不会占用主盘空间，对 SSD 紧张的用户尤其实用。

技巧二：换设备迁移。把整个缓存目录原样复制到新设备，再设置相同的XDG_CACHE_HOME指向该目录，即可跳过全部重新下载。

技巧三：清理空间。不常用的模型直接删除缓存目录中对应的模型文件，下次使用时系统会重新下载。删除前先确认文件确实闲置，避免误删正在用的权重。

下载与识别问题速查

写在最后

IOPaint 的自动下载与本地缓存把模型管理的重复劳动交给系统：is_downloaded()保证不重复下载，scan_models()保证模型列表随时可用。把缓存目录规划好、遇到识别问题查一下速查表，模型这块基本不用操心。更多背景信息可参考官方文档 README.md。

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