ModuleNotFoundError: No module named ‘tqdm’

问题场景

用户在 Kohya_ss 的 GUI 中使用 BLIP captioning 给训练图片目录自动打标，触发路径为 finetune/make_captions.py。命令行参数里带有 --beam_search 且 --num_beams 大于 1 时，程序在加载完 BLIP 模型、开始逐批处理图片后崩溃。Issue 正文中的截图显示崩溃发生在 make_captions.py 的 run_batch(b_imgs) 调用处。另有用户在执行到 captioning 阶段时遇到 ModuleNotFoundError: No module named 'tqdm'。

报错原文

A matching Triton is not available, some optimizations will not be enabled.
Error caught was: No module named 'triton'

BLIP loaded
  0%|                                                                                           | 0/58 [00:07<?, ?it/s]
╭─────────────────────────────── Traceback (most recent call last) ────────────────────────────────╮
│ D:\Data\kohya\kohya_ss-21.8.3\finetune\make_captions.py:200 in <module>                          │
│ ❱ 200 │   main(args)                                                                             │
│ D:\Data\kohya\kohya_ss-21.8.3\finetune\make_captions.py:144 in main                              │
│ ❱ 144 │   │   │   │   run_batch(b_imgs)                                                          │

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'

原因分析

Issue 中有用户指出该问题很可能与 salesforce/BLIP #165 相关，推测是 BLIP 的 beam search 与较新版本 transformers 之间存在兼容性问题。表现上，num_beams 大于 1 时必崩，设为 1 可以绕过，说明问题集中在 beam search 路径，而不是模型加载或图片读取本身。降级 transformers 后可恢复正常，进一步支持该推断。

另外，ModuleNotFoundError: No module named 'tqdm' 是另一类依赖缺失问题，通常出现在虚拟环境依赖未安装完整，或编辑 requirements.txt 后没有重新安装依赖的情况下。

环境排查

• 确认 Kohya_ss 版本：Issue 覆盖 v21.8.2、v21.8.3、v21.8.5，较新的 21.8.5 仍有用户复现。
• 确认是否使用虚拟环境，以及 venv 中是否安装 tqdm。
• 确认 transformers 当前版本，以及 requirements.txt 中锁定的版本。
• 确认 Torch、CUDA：Issue 中为 Torch 2.0.1+cu118、CUDA 11.8、cuDNN 8700。
• 确认 BLIP captioning 参数中 --num_beams 是否大于 1；大于 1 属于触发条件。
• 确认 GPU 显存是否足够，Issue 中出现 6GB 与 16GB 两种显卡。

解决步骤

1. 先做快速验证：把 BLIP captioning 的 beam 数量设为 1，确认报错是否消失。这只能作为临时绕过，issue 中反馈生成的 caption 会非常简单。
2. 打开 Kohya_ss 的 requirements.txt，找到 transformers==x.x.x 这一行。
3. 把版本改为 transformers==4.25.1。
4. 重新安装依赖。Issue 中验证过的两种方式：其一是在 kohya_ss GUI 目录下重新运行 setup.bat；其二是执行 pip install -r requirements.txt。
5. 如果过程中出现 ModuleNotFoundError: No module named 'tqdm'，确认当前虚拟环境里已安装 tqdm，再重新执行 captioning。
6. 重新启动 kohya_ss GUI，再次运行 BLIP captioning，并把 num_beams 设回大于 1 的测试值。

验证方法

在 num_beams 大于 1 的情况下重新对同一图片目录执行 BLIP captioning，若能正常完成、不再出现 BLIP beam search traceback，并且生成的 .txt caption 内容合理，即说明该问题已解决。Issue 中有用户在降级 transformers 后确认 beam 数大于 1 可正常工作。

参考来源

bmaltais/kohya_ss #1236
salesforce/BLIP #165

AI 工具推荐

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

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

了解 GamsGo AI

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