彻底解决 ComfyUI Mixlab 插件 Whisper.available False 的报错

https://github.com/MixLabPro/comfyui-mixlab-nodes

---

彻底解决 ComfyUI Mixlab 插件 Whisper.available False 的报错

在 ComfyUI 中安装 Mixlab Nodes 插件后，控制台显示其他节点正常，便 Whisper.available False。即使环境里安装了 openai-whisper 和 faster-whisper，问题依然可能存在。

Whisper.available False

本文将分享如何通过修改 __init__.py 进行深度 Debug，并修复 Whisper.py 中的路径逻辑漏洞。

---

1. 深度排查：让报错"开口说话"

Mixlab 的默认日志只提示 False，不显示原因。为了抓出真凶，我们需要修改插件的入口文件：

• 文件路径 ：custom_nodes\comfyui-mixlab-nodes\__init__.py

Win_ComfyUI\custom_nodes\comfyui-mixlab-nodes\__init__.py

• 修改位置：约第 1455-1456 行（Whisper 检测块）。

• 操作 ：将原本沉默的 except 块改为打印完整堆栈。

# 修改前
except Exception as e:
    logging.info('Whisper.available False')

# 修改后 (增加 Traceback 打印)
except Exception as e:
    import traceback
    logging.info(f'Whisper.available False. Reason: {e}')
    traceback.print_exc()

修改后重启，控制台显露真凶：

FileNotFoundError: [WinError 3] 系统找不到指定的路径。: '...\\models\\whisper'

---

2. 核心原因：路径初始化崩溃

排查发现，该问题并非依赖缺失，而是 nodes/Whisper.py 的代码健壮性不足：

1. 代码在初始化时会强制扫描 models/whisper 文件夹。

2. 如果用户尚未创建该目录，os.listdir() 会直接抛出异常导致模块加载失败。

---

3. 终极解决方案

第一步：手动创建目录

在你的 ComfyUI 的 /models 目录下，手动新建文件夹：whisper。

---

第二步：修复源码逻辑漏洞

打开 custom_nodes\comfyui-mixlab-nodes\nodes\Whisper.py，在 model_sizes 扫描逻辑前加入自动创建目录的判断。

Win_ComfyUI\custom_nodes\comfyui-mixlab-nodes\nodes\Whisper.py

# 确保目录存在，防止 os.listdir 报错抛出 WinError 3
if not os.path.exists(whisper_model_path):
    os.makedirs(whisper_model_path)

# 此时再执行扫描逻辑，即使文件夹为空也只会返回空列表，不会导致加载失败
model_sizes = [
    d for d in os.listdir(whisper_model_path) 
    if os.path.isdir(os.path.join(whisper_model_path, d)) 
    and os.path.isfile(os.path.join(os.path.join(whisper_model_path, d), "config.json"))
]

---

第三步：正确放置 CTranslate2 模型

由于代码检查 config.json，我们需要下载 Faster-Whisper 格式的模型（如 Systran/faster-whisper-tiny）。

https://huggingface.co/collections/Systran/faster-whisper
https://huggingface.co/Systran/faster-whisper-tiny/tree/main

# Download the model
hf download Systran/faster-whisper-tiny

• 工具 ：可以使用 hf-mirror 镜像下载。

• 存放 ：将模型文件（model.bin, config.json 等）放在 models/whisper/faster-whisper-tiny/ 下。

正确的文件结构应该是：

H:\PythonProjects1\Win_ComfyUI\models\whisper\faster-whisper-tiny\
├── config.json
├── model.bin
├── tokenizer.json
├── vocabulary.txt
└── README.md (可选)

Mixlab 的这个节点通常支持以下两类模型：

• Faster-Whisper 模型：例如 tiny, base, small, medium, large-v3 的 CTranslate2 格式文件夹。

• OpenAI 原版模型：.pt 格式的文件。

可以先尝试方案 A，重启后看看控制台是否变成了 Whisper.available True。

---

确保环境里已经安装了 faster-whisper，接下来最关键的一步就是放置模型文件 。由于代码逻辑里有一个硬性条件：模型文件夹内必须包含 config.json，这意味着它需要 Faster-Whisper (CTranslate2) 格式的模型。

如何获取并放置模型？

1. 下载模型：

   https://huggingface.co/Systran

   你可以从 Hugging Face 的 Systran 页面 下载。常用的模型包括：

   • faster-whisper-tiny (体积小，速度极快)

   • faster-whisper-base (平衡性好)

   • faster-whisper-large-v3 (精度最高，中文识别强)

2. 正确的文件结构：

   需要将下载的文件夹解压到 H:\PythonProjects1\Win_ComfyUI\models\whisper 目录下。结构必须如下所示：

   H:\PythonProjects1\Win_ComfyUI\models\whisper\
   └── large-v3/              <-- 文件夹名随意，但里面必须有 json
       ├── config.json        <-- 必须存在，否则节点识别不到
       ├── model.bin
       ├── tokenizer.json
       └── vocabulary.json

3. 刷新节点：

   放好之后，你可以在 ComfyUI 中添加 Load Whisper Model ♾️Mixlab 节点，在下拉菜单里就能看到你刚放进去的文件夹名字了。

---

---

4. 验证修复

重启 ComfyUI 后查看控制台日志输出以验证修复：

Whisper.available

可以看到控制台显示 Whisper.available 后面没有 False（或者显示了 True），就说明模块已经绕过了路径检查，成功加载到了 ComfyUI 中。

---

5. 经验总结

在开发 ComfyUI 插件或维护 Python 环境（如 EPGF 框架）时：

1. Debug 优先 ：修改 __init__.py 打印 traceback 是定位插件加载问题的万能钥匙。

2. 路径防御性编程 ：使用 os.listdir 前必做 os.path.exists 或 os.makedirs。

---

博主： AITechLab

时间： 2026年1月16日

---