ModuleNotFoundError: No module named ‘tqdm’

快速结论：该报错出现在 Kohya SS 使用 BLIP 批量生成图片描述（Captioning）时，当 num_beams 大于 1（即启用 beam search）且 transformers 库版本过高时，会触发此错误。优先排查 transformers 版本并降级到 4.25.1。

问题场景

用户在 Kohya SS（版本 v21.8.3 及多个其他版本）中运行 BLIP captioning 功能时，设置 num_beams 大于 1（如 12）并启用 --beam_search，导致脚本崩溃并返回 ModuleNotFoundError: No module named 'tqdm' 错误。即使在较早版本（如 v21.5.10、v21.7.14 等）中也会出现此问题。

报错原文

Traceback (most recent call last):
  File "E:\sd\kohya_ss\finetune\make_captions.py", line 10, in <module>
    from tqdm import tqdm
ModuleNotFoundError: No module named 'tqdm'

原因分析

可能原因是高版本的 transformers 库与 BLIP 的 beam search 模式不兼容。当 num_beams 设置为大于 1 的值时，BLIP 会调用 Hugging Face 的 transformers 库进行 beam search 解码，而新版 transformers 引入了某些依赖或路径变更，导致脚本在导入 tqdm 时失败。社区用户确认该问题与 Salesforce/BLIP Issue #165 相关。注意：tqdm 本身在 Kohya SS 虚拟环境中是已安装的，但 beam search 路径下可能有额外的导入问题。

环境排查

确认 Kohya SS 版本（如 v21.8.3 等）及 Python 虚拟环境路径
检查当前安装的 transformers 版本——可通过虚拟环境下的 pip list 查看
检查虚拟环境下 tqdm 是否存在——通常已安装，但可能在子进程（如 beam search 路径）中无法正确加载
验证 num_beams 设置：是否大于 1

解决步骤

（可优先尝试） 临时将 captioning 设置中的 num_beams 改为 1，并使用 --beam_search 参数（仅设置 beam=1 可绕过该问题）。注意：此方案生成的描述可能较简单，且如果同时设置了较大的 --min_length，描述会出现重复词汇。
（推荐的长期修复方案） 在 Kohya SS 安装目录下找到 requirements.txt 文件，将其中 transformers 的行修改为 transformers==4.25.1（即降级到该版本）。
修改后，在对应的终端（Windows 下用管理员模式打开命令提示符或 PowerShell）中运行 pip install -r requirements.txt（注意需要在虚拟环境激活状态下执行，或者直接重新运行 Kohya SS 目录下的 setup.bat 脚本来重新安装依赖）。
重启 Kohya SS 的 WebUI，重新运行 BLIP captioning，此时 num_beams 大于 1 即可正常使用。

验证方法

在 Kohya SS 的 BLIP captioning 界面中，设置 num_beams 为大于 1 的值（如 12），启动 captioning 任务。如果任务顺利完成，没有报错且输出文件中有合理的描述文本（无重复词汇），则问题已解决。

参考来源

bmaltais/kohya_ss #1236

AI 工具推荐

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

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

了解 GamsGo AI

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

ModuleNotFoundError: No module named ‘tqdm’