Error trying to use WD14 Captioning

快速结论：这个报错通常出现在 Kohya SS 调用 WD14 Captioning 打标时，脚本在本地缓存目录里找不到 model.onnx，即使加了 --force_download 也会失败。优先排查 WD14 模型缓存目录是否完整、是否只有 HuggingFace 的哈希/软链接结构而没有真正的模型文件。

适用环境：Issue 中出现的环境包括：Windows 10/11 以及 Linux Docker；Python 3.10；通过 accelerate 启动 tag_images_by_wd14_tagger.py；使用 --onnx 与 --repo_id SmilingWolf/wd-v1-4-convnext-tagger-v2（也出现 wd-v1-4-convnextv2-tagger-v2）。未见明确确认的 CUDA、PyTorch 或显卡版本。

最快修复方案：暂无确认的一步修复方案。Issue 中有人尝试在 Dockerfile 加入 --noverify、手动移动 model.onnx、多次重装，均未确认成功；最终发帖者放弃 WD14，改用普通 captioning。

注意事项：手动移动 model.onnx 时若破坏软链接仍会失败；--force_download 在本问题中并未真正修复缓存结构。Docker 方案 --noverify 仅对部分用户有效，本 Issue 中报告无效。

问题场景

用户在 Kohya SS 的 WD14 Captioning 流程中执行打标脚本 sd-scripts/finetune/tag_images_by_wd14_tagger.py，使用 ONNX 模式（--onnx）并通过 --repo_id 指定 SmilingWolf/wd-v1-4-convnext-tagger-v2（或 wd-v1-4-convnextv2-tagger-v2）时触发报错。命令由 accelerate launch 拉起，最终子进程返回非零退出码。

报错原文

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で再ダウンロードしてください

subprocess.CalledProcessError: Command '['E:\\Dreambooth\\kohya_ss\\venv\\Scripts\\python.exe', 'E:/Dreambooth/kohya_ss/sd-scripts/finetune/tag_images_by_wd14_tagger.py', '--batch_size', '1', '--caption_extension', '.txt', '--caption_separator', ', ', '--debug', '--force_download', '--frequency_tags', '--max_data_loader_n_workers', '2', '--onnx', '--remove_underscore', '--repo_id', 'SmilingWolf/wd-v1-4-convnext-tagger-v2', 'E:/Dreambooth/kohya_ss/input/img/74_PKO Game']' returned non-zero exit status 1.

原因分析

脚本在 wd14_tagger_model\SmilingWolf_wd-v1-4-convnext-tagger-v2\model.onnx 这个路径下没有找到可用的 ONNX 模型文件。Issue 中多位用户复现，且即使用了 --force_download 仍报同一错误，说明问题可能不在“忘记下载”，而在于下载后的缓存结构不匹配脚本预期。

有用户给出的目录树显示，缓存目录采用的是 HuggingFace 新版结构，内容为 blobs、refs、snapshots 以及哈希命名快照目录，而不是脚本要求的直连 model.onnx 文件名。另有用户表示能在子目录找到 model.onnx 软链接，但手动把它移到报错路径后仍然失败——可能原因是软链接被破坏或脚本实际解析路径与预期不一致。

环境排查

确认操作系统：Windows 直装、Linux Docker 或其它部署方式。
确认 Python 版本（Issue 中出现 Python 3.10）。
确认 Kohya SS 与 sd-scripts 是否为该版本下的默认缓存路径。
检查 wd14_tagger_model 目录结构，看是否只有 blobs/refs/snapshots 与哈希文件，没有直接的 model.onnx。
确认实际使用的 --repo_id 是 wd-v1-4-convnext-tagger-v2 还是 wd-v1-4-convnextv2-tagger-v2，两者缓存目录名不同。
Docker 用户可核对是否按相关 Issue #3172 尝试过 --noverify。

解决步骤

先按报错提示尝试重新下载，即保留 --force_download 参数重跑打标脚本。若仍报 onnx model not found，说明仅重下不能解决。
打开报错路径 wd14_tagger_model\SmilingWolf_wd-v1-4-convnext-tagger-v2，检查是否存在脚本期望的 model.onnx。若只有 models--SmilingWolf--... 哈希目录结构，说明缓存布局与脚本预期不一致。
如能在 snapshots 子目录中找到 model.onnx 软链接，可优先尝试把真实模型文件复制到报错路径（不要只移动软链接）。Issue 中有用户尝试过移动但失败，因此此步骤不保证有效。
Docker 用户可优先尝试相关 Issue #3172 中的思路：在 Dockerfile 中加入 --noverify 并重建容器。注意：本 Issue 中有用户反馈该方案对自己无效。
若以上均无效，可参考发帖者做法，暂时改用普通 captioning 完成打标，绕开 WD14 ONNX 流程。

验证方法

重新运行 WD14 Captioning 后，若不再出现 onnx model not found，且每张图片生成的 .txt 中包含实际 WD14 生成的标签（而不仅是 Prefix），即可认为问题已解决。Issue 中有人指出失败时仍会生成 .txt，但里面只有 Prefix、没有 WD14 标签，这一点可作为验证依据。