高频错误
SageAttention 缺失
ComfyUI 启动时出现 SageAttention 警告的原因和解决方法
你看到的日志
ComfyUI 启动时,终端日志中出现:
Warning: Could not load sageattention: No module named 'sageattention'
这是什么
SageAttention 是清华大学开发的注意力量化加速库 (ICLR 2025),通过对 attention 计算做 INT8/FP8 量化,实现比 FlashAttention 快 2-5 倍的推理速度,且不影响生成质量。
部分 ComfyUI 自定义节点 (如 TeaCache、CogVideoX Wrapper 等) 会尝试加载它。缺少时 ComfyUI 回退到默认的注意力实现,功能完全正常。
严重程度
低 — 这是一条警告,不是错误。ComfyUI 可以正常运行。
是否值得安装
先说结论: 在 Windows 上安装 SageAttention 有一定难度,对大多数用户来说收益有限。
实际加速效果取决于显卡和工作流:
- RTX 4000/5000 系列: SageAttention 2 的 CUDA kernel 对 Ada/Blackwell 架构有专门优化 (sm89/sm120),可带来 30-40% 的速度提升,收益最大。
- RTX 3000 系列: 使用 Triton kernel 回退路径 (等同于 SageAttention 1),加速约 10-15%。
- RTX 2000 系列 (Turing): 也走 Triton 回退路径,加速幅度类似但更小。历史版本有兼容问题,需要使用新版 wheel。
- GTX 16 系列及更老: 不建议尝试,收益极小且兼容性差。
如果你日常只是跑 Stable Diffusion 出图,不使用视频生成等重度工作流,忽略这条警告是最稳妥的选择。
解决方法
方法一: 忽略 (推荐)
不需要做任何事情。这条警告不影响 ComfyUI 的功能和出图质量。
方法二: 安装 SageAttention
在 Windows 上,pip install sageattention 会尝试从源码编译 CUDA kernel,通常会失败 (需要 Visual Studio C++ 编译工具链)。推荐使用社区提供的预编译 wheel。
前提条件:
- NVIDIA 显卡 (GTX 16 系列或更新)
- PyTorch >= 2.6,且必须是 CUDA 版本 (不是 CPU 版本)
- Python >= 3.9
- 已安装 triton-windows (SageAttention 依赖 Triton)
步骤 1: 确认环境
在 Wonderful Launcher 的终端中执行:
python -c "import torch; print(f'PyTorch {torch.__version__}, CUDA {torch.version.cuda}')"
记下输出的 PyTorch 版本号和 CUDA 版本号,后续选择 wheel 时需要匹配。
步骤 2: 安装 Triton
SageAttention 依赖 Triton。如果尚未安装:
pip install triton-windows
步骤 3: 安装预编译 wheel
前往 woct0rdho/SageAttention Releases 页面,下载与你的 PyTorch 版本和 CUDA 版本匹配的 .whl 文件,然后安装:
pip install sageattention-2.2.0+cu128torch2.8.0.post2-cp39-abi3-win_amd64.whl
上面的文件名仅为示例,请根据你的实际 PyTorch/CUDA 版本选择对应的 wheel。选择要点:
cu128/cu126等对应你的 CUDA 版本torch2.8.0/torch2.6.0等对应你的 PyTorch 版本 (小版本号可以有差异)cp39-abi3表示兼容 Python 3.9 及以上
步骤 4: 验证安装
python -c "from sageattention import sageattn; print('SageAttention OK')"
步骤 5: 重启 ComfyUI
重启后警告应消失。
常见安装失败
| 错误信息 | 原因和解决方法 |
|---|---|
No module named 'triton' |
Triton 未安装。执行 pip install triton-windows |
error: Microsoft Visual C++ 14.0 or greater is required |
你执行了 pip install sageattention 从源码编译。改用预编译 wheel |
RuntimeError: CUDA 12.8 or higher is required |
wheel 的 CUDA 版本高于你的环境。选择匹配的 wheel 或升级 PyTorch |
AttributeError 涉及 triton.jit |
Triton 缓存损坏。删除 C:\Users\你的用户名\.triton\ 文件夹后重试 |
安装成功但 ComfyUI 仍报 No module named 'sageattention' |
安装到了错误的 Python 环境。确认用 ComfyUI 的 Python 执行 pip |
方法三: 使用 ComfyUI 自定义节点自动安装
社区有一些自动安装节点,如 ComfyUI_EasySageAttention,可以自动检测环境并安装匹配的 wheel。如果你不想手动操作,可以试试这类方案。但请注意这些是第三方项目,不在我们的支持范围内。
联系我们
如果安装过程中遇到上述表格中未列出的错误,或安装后 ComfyUI 出现其他异常,请通过应用内的「联系我们」按钮联系技术支持。
Wonderful Launcher 文档