Error trying to use WD14 Captioning

快速结论：该报错通常发生在 Kohya SS 使用 WD14 模型进行自动标注时，优先排查模型文件是否下载完整，尤其是 model.onnx 文件是否真实存在于预期路径。

问题场景

用户在 Kohya SS 中运行 WD14 Captioning 功能时（直接运行或通过加速启动脚本），触发 onnx model not found 错误，导致标注流程中断。该问题在 Windows 11 原生环境和 Linux Docker 容器中均有出现。

报错原文

Exception: onnx model not found: wd14_tagger_model\SmilingWolf_wd-v1-4-convnext-tagger-v2/model.onnx, please redownload the model with --force_download / onnxモデルが見つかりませんでした。--force_downloadで再ダウンロードしてください

原因分析

可能原因：WD14 模型通过 Hugging Face 下载时，存储结构并非预期的扁平文件布局，而是包含哈希目录和 Blob 文件的 Hugging Face 缓存结构。Kohya SS 的代码在 tag_images_by_wd14_tagger.py 中硬编码了模型路径，未正确解析缓存目录内的符号链接或实际文件路径，导致无法找到 model.onnx。

环境排查

• 确认 Kohya SS 版本（是否为最新版，因为模型下载机制在不同版本间有变化）。
• 检查 wd14_tagger_model 目录下是否存在 SmilingWolf_wd-v1-4-convnext-tagger-v2 子目录，以及其内容是否为 Hugging Face 缓存结构（如 snapshots/xxx、blobs/ 等），而不是直接的 model.onnx 文件。
• 如果运行在 Docker 中，确认 Docker 镜像中是否安装了正确的依赖（如 ONNX Runtime）。

解决步骤

1. 手动下载模型：从 Hugging Face 仓库手动下载 SmilingWolf/wd-v1-4-convnext-tagger-v2 的 model.onnx 文件，并直接放置到报错中指定的路径（如 wd14_tagger_model/SmilingWolf_wd-v1-4-convnext-tagger-v2/model.onnx）。
   注意：Issue 中有用户尝试过此方法但未成功，可能是符号链接或权限问题。可优先尝试作为临时方案。
2. 使用 --force_download 参数：在 Kohya SS 的启动命令或 GUI 中启用强制重新下载模型，覆盖可能损坏或不完整的缓存。但 Issue 中多位用户反映此参数无效。
3. 清理缓存并重新安装：删除 wd14_tagger_model 目录下的全部内容，然后重新运行 WD14 Captioning，让工具从头下载模型。
4. 检查符号链接：如果 model.onnx 是软链接，确认链接目标是否存在且可读。Issue 中用户尝试过将软链接替换为实际文件，但仍失败。
5. Docker 环境额外步骤：对于 Docker 用户，Issue 中一位评论建议执行容器内更新（如 apt update），但未给出具体命令。可尝试升级容器内的系统包和 Python 依赖。

验证方法

重新运行 WD14 Captioning，观察控制台输出是否不再出现 onnx model not found 错误，并检查生成的标签文件中是否包含正确的 WD14 标注标签（Issue 中用户反馈会生成空白标签文件，这也是验证点之一）。

参考来源

bmaltais/kohya_ss #3178

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。