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

快速结论：当 ComfyUI IPAdapter Plus 的 Load InsightFace 节点在日志中提示 CUDA 不可用、只能回退到 CPUExecutionProvider 时，通常说明 insightface 依赖的 onnxruntime 环境与 CUDA 版本、Python 版本或安装的 onnxruntime 包类型不匹配。优先检查是否只安装了一个版本的 onnxruntime（CPU 或 GPU），以及 onnxruntime-gpu 对 CUDA 版本的限制。

适用环境：Issue 中主要确认的是 Linux 环境；ComfyUI IPAdapter Plus 的 Load InsightFace 节点；Python 3.11 或 3.10；CUDA 11.8 与 onnxruntime-gpu；在 Windows 原生环境不适用该 Linux 修复路径，但在 WSL 中运行 ComfyUI 可参考。Issue 未确认具体显卡型号、torch 版本和 ComfyUI 版本。

最快修复方案：暂无确认的一步修复方案。Issue 中验证过的方向是：确保只安装 onnxruntime-gpu，而不是同时安装 onnxruntime 和 onnxruntime-gpu；并为 insightface 准备 CUDA 11.8 + CUDNN 环境；同时使用 Python 3.11 或 3.10。另有评论提到可用 pip install --upgrade protobuf 缩短首次加载时间，但这不解决 CUDA provider 不可用的问题。

注意事项：该 Issue 明确标注 Linux 指南，不适用于 Windows 原生环境；onnxruntime-gpu 当时仅支持 CUDA 11.8，CUDA 12 需要等 ONNX Runtime 1.17；在 import torch 之后再 import insightface 可能临时让 CUDA 可用，但这只是 workaround，不是正式修复；host 上直接安装 CUDA 11.8 和 CUDNN 容易破坏系统依赖，风险较高。

问题场景

用户在 ComfyUI 中使用 ComfyUI IPAdapter Plus 的 Load InsightFace 节点时，发现 InsightFace 没有使用 CUDA，而是回退到 CPU。部分用户即使机器上有 NVIDIA 显卡，日志仍显示可用 provider 只有 AzureExecutionProvider 和 CPUExecutionProvider。

报错原文

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

原因分析

可能原因包括：insightface 本身默认可以跑在 CPU 上，只有存在可用的 onnxruntime-gpu 且其 CUDA 能力正常时，才会使用 GPU；如果同时安装了 onnxruntime 和 onnxruntime-gpu，可能会继续走 CPU 模式；onnxruntime-gpu 当时限制在 CUDA 11.8，而用户环境可能是 CUDA 12 或其他版本；Python 3.12 与所需库不兼容；缺少 CUDNN 或其他 CUDA 辅助库。Issue 作者还发现，先 import torch 再 import insightface 可能让 CUDA 可用，是因为 torch 会把 CUDA/CUDNN 的 .so/.dll 库加载进 Python 进程，但这只是临时绕过。

环境排查

确认当前安装的是 onnxruntime 还是 onnxruntime-gpu，是否两者同时存在。
确认 Python 版本是否为 3.11 或 3.10，Issue 中明确 Python 3.12 不兼容所需库。
确认 CUDA 版本是否为 11.8，因为当时 onnxruntime-gpu 仅支持 CUDA 11.8。
确认是否安装并正确配置 CUDNN，以及 CUDA 相关辅助库是否能被 Python 找到。
确认运行环境是 Linux 还是 Windows；Issue 说明该 Linux 方法不适用于 Windows 原生环境，WSL 可参考。
确认 ComfyUI 日志中实际加载的 provider 列表，是否只有 CPUExecutionProvider。

解决步骤

只保留一个 onnxruntime 包：如果需要 GPU 加速，安装 onnxruntime-gpu；如果同时安装了 onnxruntime 和 onnxruntime-gpu，先卸载 CPU 版本，避免 CPU 模式被优先使用。
按 Issue 的 Linux 指南为 insightface 准备 CUDA 11.8 环境：需要 CUDA 11.8 库、CUDNN 以及 CUFFT 等 CUDA 辅助库。
使用 Python 3.11 或 3.10，不要用 Python 3.12，Issue 明确当时 3.12 与所需库不兼容。
如果在 Fedora 上希望把库装在 host 而不是 venv，评论中给出的 Fedora 专用步骤是：先添加 CUDA 11 Fedora 仓库，编辑 repo 文件并加入 exclude=kmod-* nvidia-*，再执行 sudo dnf install --refresh cuda-toolkit-11-8，然后手动下载安装 CUDNN。该步骤仅适用于 Fedora，其他发行版只能作为参考。
Issue 评论提到，如果希望减少 InsightFace 首次加载时间，可在 venv 中执行 pip install --upgrade protobuf，因为 Protobuf 3.x 加载较慢，4.x 加载较快。这不是 CUDA provider 修复步骤。
关注 ONNX Runtime 1.17 对 CUDA 12 的支持；Issue 评论指出 CUDA12 支持已在 onnxruntime v1.17 上线。

验证方法

重新运行 ComfyUI IPAdapter Plus 的 Load InsightFace 节点，观察日志中的 available provider 列表。如果 CUDA 正常，应不再只显示 CPUExecutionProvider，而是包含 CUDAExecutionProvider。如果仍显示 CPUExecutionProvider，说明环境仍未正确加载 CUDA provider。