IOPaint AI修图模型自动下载与本地缓存机制详解【免费下载链接】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/IOPaintIOPaint 是基于 AI 模型的图像修复工具擦除和重绘都依赖本地模型文件。本文面向刚接触 IOPaint 的用户讲清三件事模型什么时候被自动下载、模型缓存在哪里、出问题时怎么查。读完你可以独立把模型目录挪到指定磁盘并用命令验证缓存状态。启动时如何判定缺模型并触发下载缓存目录的三类模型存储位置与类型判定规则用XDG_CACHE_HOME和--model-dir迁移模型目录的方法模型已下载但不被识别、下载中断的排查步骤自动下载模型什么时候触发触发时机只有一个iopaint start --modelxxx启动时。程序先调用scan_models()扫描缓存目录只有当指定模型不在扫描结果里才会打印not found in ...并执行下载第二次启动同一命令时这一步被跳过所以不会重复下载。擦除模型与Diffusion模型走两条下载通道内置擦除模型AVAILABLE_MODELS中的 lama、mat、fcf、manga 等由模型类自己的download()完成。以 LaMa 为例download()按固定 URL 下载并校验 MD5is_downloaded()只检查缓存路径下文件是否存在。Diffusion 模型走 Hugging Face 通道cli_download_model调用DiffusionPipeline.download并优先指定variantfp16。下载失败时handle_from_pretrained_exceptions会依次降级先试revisionfp16再试revisionmain如果报网络错误Max retries exceeded日志会直接提示设置代理或加--local-files-only。下载 fp16 variant - 失败则 revisionfp16 - 再失败则 revisionmain本地模型缓存目录结构与类型识别规则缓存放什么、放在哪全由 download.py 的scan_models()决定它拼起来四路结果scan_inpaint_models内置擦除模型逐个调用is_downloaded()scan_single_file_diffusion_models单文件模型scan_diffusers_modelsHugging Face 缓存里的 diffusers 目录结构模型scan_converted_diffusers_models转换后的 diffusers 模型单文件模型必须放在模型目录下stable_diffusion/SD1.5或stable_diffusion_xl/SDXL里且扩展名是.safetensors或.ckpt其他一律忽略。模型类型如何判定并缓存到iopaint_cache.json识别顺序是文件名里含 inpaint 直接归类为 inpainting 模型不含的话就临时加载一次用 UNet 输入通道数9 通道即 inpainting4 通道即 base判定。判定结果写进对应目录下的iopaint_cache.json下次扫描直接读缓存不再加载模型。diffusers 目录结构模型则从HF_HUB_CACHE扫描靠model_index.json里的_class_name识别文件夹名models--org--name会被还原成org/name展示。WebUI 模型列表就是这份扫描结果来源见 model_manager.py。如何把IOPaint模型目录挪到大容量磁盘默认模型目录取XDG_CACHE_HOME环境变量未设置时是~/.cache见 const.py 的DEFAULT_MODEL_DIR。迁移有两种方式export XDG_CACHE_HOME/data/disk/iopaint_cache iopaint start --modellama或者每次启动加--model-dir /data/disk/iopaint_cache。注意setup_model_dirruntime.py会把这个路径同时写入U2NET_HOME和XDG_CACHE_HOME分割插件的模型也落在同一处。一个实际影响XDG_CACHE_HOME是系统级变量改它会影响其他遵守 XDG 规范的程序建议只在启动 IOPaint 的终端里临时设置不要写进全局 profile。验证与排查确认模型缓存状态用iopaint list列出已识别的模型iopaint list输出的每一行就是一个可加载模型。WebUI 下拉框和这份列表同源所以下拉框里没有的模型这条命令里也查不到。模型已下载但缓存目录不被识别的排查步骤先确认文件放对了位置单文件模型不在stable_diffusion/或stable_diffusion_xl/目录下、或扩展名不是.safetensors/.ckpt会被静默跳过diffusers 结构模型要求缓存里存在可解析的model_index.json。其次是类型判定失败删除对应目录下的iopaint_cache.json让系统重新判定再跑iopaint list确认。下载中断后的恢复方法与离线模式网络不通时典型报错是 Max retries exceeded日志会提示两条路给终端配置代理或手动下载文件放入缓存目录对应子目录。如果模型其实已经下完、只是想不再联网检查启动时加--local-files-only它会设置HF_HUB_OFFLINE和TRANSFORMERS_OFFLINE加载全程只读本地文件。一张清单收尾IOPaint 的模型管理只有三条规则启动先扫描、缺什么才下载、类型判定结果落盘缓存。你现在就可以运行iopaint list对照 WebUI 的模型下拉框验证一遍扫描结果。参考链接下载与扫描逻辑iopaint/download.py模型类型识别与HF下载降级iopaint/model/utils.py模型管理器iopaint/model_manager.py【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考