FAQ/GUIDE: I’ve figured out why CUDA isn’t available in Insightface!

快速结论：这个报错通常发生在使用 ComfyUI IPAdapter Plus 或 Reactor 节点时，Insightface 无法启用 CUDA GPU 加速。优先排查是否同时安装了 onnxruntime（CPU）和 onnxruntime-gpu（GPU），应仅保留 onnxruntime-gpu；其次确认 onnxruntime-gpu 版本是否与 CUDA 版本匹配（目前限于 CUDA 11.8）。

问题场景

用户在运行 ComfyUI 下的 IPAdapter Plus 或 Reactor 节点时，期望使用 GPU 加速，但 Insightface 模型只回退到 CPU 执行。常见表现为加载缓慢（首次加载耗时数十秒）或直接提示 CUDA 不可用。

报错原文

UserWarning: Specified provider 'CUDAExecutionProvider' is not in available provider names.Available providers: 'AzureExecutionProvider, CPUExecutionProvider'
Applied providers: ['CPUExecutionProvider'], with options: {'CPUExecutionProvider': {}}

原因分析

Insightface 本身是模型，依赖 onnxruntime-gpu 实现 GPU 加速。核心原因包括：

同时安装了 onnxruntime（CPU）和 onnxruntime-gpu，导致实际使用的是 CPU 模式。
onnxruntime-gpu 目前（截止 2024-01）只支持 CUDA 11.8，系统 CUDA 版本更高则无法启用 CUDA。
系统缺少 CUDA 11.8 所需的运行时库（如 CUDNN、CUFFT 等），且 Python 版本建议为 3.10 或 3.11（3.12 不兼容）。
Linux 上可以通过加载 Torch 的 CUDA 库来临时“借用”，但这不是可靠方案。
Windows 上（非 WSL）CUDA 库加载机制不同，该指南方法不适用于原生 Windows。

环境排查

Python 版本：确认是否为 3.10 或 3.11（不支持 3.12）。
CUDA 版本：系统 CUDA 版本（nvidia-smi）应为 11.8。
onnxruntime 安装：确认只安装了 onnxruntime-gpu，且未同时安装 onnxruntime。
onnxruntime-gpu 版本：检查版本是否匹配 CUDA 11.8（早期版本）或更新版本（如 v1.17 开始支持 CUDA 12）。
Linux 运行时库：检查系统是否安装了 CUDA 11.8 Toolkit 和 CUDNN 库（.so 文件）。
Windows 环境：若原生 Windows，该方法不适用；可尝试 WSL。

解决步骤

卸载冲突包：在虚拟环境中执行 pip uninstall onnxruntime（仅保留 onnxruntime-gpu）。
安装兼容的 onnxruntime-gpu：
- 若使用 CUDA 11.8：安装 onnxruntime-gpu 相应版本（如 1.16 或更早）。
- 若使用 CUDA 12：安装 onnxruntime-gpu v1.17 或更高（注：2024-01 时刚发布，需要验证兼容性）。
安装 CUDA 11.8 运行时库（Linux 用户推荐）：作者提到可使用 NVIDIA 官方 Docker 容器或直接在宿主机安装。对于 Fedora 用户，可执行以下操作（其他发行版仅作参考）：
- 添加 CUDA 11.8 repo：仅运行 sudo dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/fedora35/x86_64/cuda-fedora35.repo。
- 编辑 repo 文件（如 /etc/yum.repos.d/cuda-fedora35.repo），在末尾添加 exclude=kmod-* nvidia-* 以避免与最新驱动冲突。
- 安装 CUDA Toolkit：sudo dnf install --refresh cuda-toolkit-11-8。
- 手动下载并安装 CUDNN（NVIDIA 官网提供 CUDNN 安装包）。
更新 protobuf：在虚拟环境中执行 pip install --upgrade protobuf 以加快 Insightface 首次加载速度（避免 33 秒等待）。
重启 ComfyUI：确保所有路径正确加载，重新运行工作流。

验证方法

运行 ComfyUI 后，检查终端输出是否包含 CUDAExecutionProvider 在可用提供程序列表中，且不再出现 UserWarning。同时观察节点首次加载速度：若从 30 秒缩短至 1 秒左右，则 protobuf 更新成功。也可在 Python 环境中直接测试 import onnxruntime as ort; print(ort.get_available_providers())，确认包含 CUDAExecutionProvider。