Windows + RTX 5090 + ComfyUI 桌面版 安装 SageAttention 完全手册

使用前必读：路径替换指南

本手册使用 占位符 表示路径，使用前请替换为你的实际路径：

快速定位你的路径

# 1. 找到 ComfyUI 桌面版主目录
#    通常在你创建项目时的位置，或查看桌面快捷方式属性

# 2. 确认虚拟环境 Python 路径（关键！）
dir <COMFYUI_ROOT>.venvScriptspython.exe
#  应显示文件存在

# 3. 确认模型目录（根据 extra_models_config.yaml 配置）
type %APPDATA%ComfyUIextra_models_config.yaml

一、我的环境与目标（供参考）

硬件/软件配置

安装目标

 安装 triton-windows 3.6.0.post26（Windows 专用构建）
 安装 SageAttention 1.0.6（稳定版，2.x 兼容性不佳）
 让 kjnodes 的 "Model Optimization" 节点能启用 "sage" 后端加速
 不影响现有 PyTorch/CUDA 环境稳定性

️ 二、踩坑总结（血泪教训）

坑 1：(base) Conda 环境干扰

现象：命令行显示 (base)，pip 安装到 Conda 环境而非 .venv
后果：ComfyUI 找不到包，报 ModuleNotFoundError
 解决：始终执行 conda deactivate，或直接用完整路径调用 .venv 的 python

坑 2：uv 处理 .dist-info 元数据问题

现象：uv pip install 报 "failed to read metadata" 或 "拒绝访问"
后果：核心包损坏，环境崩溃
 解决：核心包（torch/numpy/triton）用标准 pip 安装，不用 uv

坑 3：Windows CMD 多行命令/通配符限制

现象：-c "多行 Python 代码" 执行失败；if exist numpy-*.dist-info 不匹配
后果：验证脚本无法运行，清理文件失败
 解决：验证用单行命令；清理用具体文件名；复杂脚本用 .py 文件

坑 4：第三方自动安装器可能损坏环境

现象：安装器自动卸载了 PyTorch，导致环境崩溃
后果：前功尽弃，需紧急恢复
 解决：手动分步安装，每步验证，不依赖自动化脚本

坑 5：文件被进程锁定

现象：安装时报 "拒绝访问 (os error 5)"
后果：包安装失败
 解决：安装前 taskkill 终止 python/uv 进程，临时关闭 Windows Defender

坑 6：SageAttention 2.x 在 Windows+Python3.12 兼容性不佳

现象：安装器提示 "No pre-built wheel available"
后果：无法安装 2.x 版本
 解决：降级使用 1.0.6 稳定版，功能足够且兼容性好

️ 三、安装步骤（复制即用，记得替换路径！）

步骤 0：准备工作

# 1. 退出 Conda base 环境（关键！）
conda deactivate
# 确认命令行前缀 (base) 消失

# 2. 确认当前 Python 指向 .venv（替换为你的实际路径）
where python
#  预期输出应包含：
# <COMFYUI_ROOT>.venvScriptspython.exe

步骤 1：安装 triton-windows

# 使用标准 pip（非 uv）安装 triton-windows
# ️ 请将 <VENV_PYTHON> 替换为你的实际路径
<COMFYUI_ROOT>.venvScriptspython.exe -m pip install ^
  triton-windows==3.6.0.post26 ^
  --no-cache-dir

验证：

<COMFYUI_ROOT>.venvScriptspython.exe -c "import triton; print(' Triton:', triton.__version__)"

预期输出： Triton: 3.6.0

步骤 2：安装 SageAttention 1.0.6

# 安装稳定版 SageAttention（指定 PyTorch CUDA 源）
<COMFYUI_ROOT>.venvScriptspython.exe -m pip install ^
  sageattention==1.0.6 ^
  --extra-index-url  ^
  --no-cache-dir

验证：

<COMFYUI_ROOT>.venvScriptspython.exe -c "from sageattention import sageattn; print(' SageAttention: OK')"

预期输出： SageAttention: OK

步骤 3：完整环境验证

# 单行命令验证三组件
<COMFYUI_ROOT>.venvScriptspython.exe -c "import torch, triton; from sageattention import sageattn; print(' PyTorch:', torch.__version__); print(' Triton:', triton.__version__); print(' All OK')"

预期输出：

 PyTorch: 2.11.0+cu130
 Triton: 3.6.0
 All OK

步骤 4：重启并测试 ComfyUI

# 1. 清理残留进程
taskkill /F /IM python.exe 2>nul

# 2. 重启 ComfyUI 桌面版

# 3. 检查启动日志关键行：
 pytorch version: 2.11.0+cu130
 Device: cuda:0 NVIDIA GeForce RTX 5090
 SeedVR2 optimizations check: SageAttention  | Triton 

步骤 5：网页界面启用加速

1. 打开 ComfyUI: 
2. 找到 "Patch Model" 或 "Model Optimization" 节点（来自 kjnodes）
3. 将参数设置为：
   - Attention Backend: sage
   - Sage Attention Mode: auto
4. 运行工作流，观察日志

预期成功日志：

 Using sage attention mode: auto
 Prompt executed in XX.XX seconds (无 Exception)

四、成功标志速查表

五、最简洁建议（黄金法则）

 1. 始终用完整路径调用 .venv Python：
   <COMFYUI_ROOT>.venvScriptspython.exe -m pip install xxx

 2. 核心包用标准 pip，不用 uv（避免元数据问题）

 3. 每步安装后立即单行验证，不要连续执行多条命令

 4. 安装前终止进程 + 临时关闭杀毒软件（防文件锁定）

 5. 重要操作前备份环境：
   <VENV_PYTHON> -m pip freeze > <COMFYUI_ROOT>backup.txt

 6. SageAttention 选 1.0.6 稳定版，2.x 在 Windows+Py3.12 兼容性不佳

 7. 避免第三方自动安装器，手动分步更可控

六、常见问题速查

验证时仍报 No module named 'xxx'

# 确认包安装到了正确环境（替换路径）
<COMFYUI_ROOT>.venvScriptspython.exe -m pip list | findstr xxx

# 如未显示，强制重装
<VENV_PYTHON> -m pip install xxx --force-reinstall --no-cache-dir

安装时报 "拒绝访问 (os error 5)"

# 1. 终止相关进程
taskkill /F /IM python.exe
taskkill /F /IM uv.exe

# 2. 临时关闭 Windows Defender 实时保护

# 3. 重试安装

ComfyUI 日志仍显示 SageAttention

→ 确认工作流中优化节点的 "Attention Backend" 设为 "sage"
→ 检查是否使用了支持 SageAttention 的模型（DiT 架构如 Wan2.2/Flux）
→ 首次运行需编译 kernel，第二次应更快

加速效果不明显

→ 尝试更高分辨率（≥1024×1024）或更长序列
→ 对比测试：相同工作流分别用 "pytorch" 和 "sage" 后端运行
→ 确认节点配置正确，插件版本最新

七、写在最后

 环境稳定是高效创作的基础
 先跑通，再优化
 祝你生成愉快！

附录：一键复制命令模板（替换占位符后使用）

:: ===== 使用前请替换所有 <COMFYUI_ROOT> 为你的实际路径 =====

:: 1. 退出 Conda 环境
conda deactivate

:: 2. 安装 triton-windows
<COMFYUI_ROOT>.venvScriptspython.exe -m pip install triton-windows==3.6.0.post26 --no-cache-dir

:: 3. 验证 triton
<COMFYUI_ROOT>.venvScriptspython.exe -c "import triton; print(' Triton:', triton.__version__)"

:: 4. 安装 SageAttention 1.0.6
<COMFYUI_ROOT>.venvScriptspython.exe -m pip install sageattention==1.0.6 --extra-index-url  --no-cache-dir

:: 5. 验证 SageAttention
<COMFYUI_ROOT>.venvScriptspython.exe -c "from sageattention import sageattn; print(' SageAttention: OK')"

:: 6. 完整环境验证
<COMFYUI_ROOT>.venvScriptspython.exe -c "import torch, triton; from sageattention import sageattn; print(' PyTorch:', torch.__version__); print(' Triton:', triton.__version__); print(' All OK')"

:: 7. 清理进程并重启
taskkill /F /IM python.exe 2>nul
:: 然后手动重启 ComfyUI 桌面版

收藏备用，祝你一次成功！