SageAttention 2.2 安装与使用
完全教程

装上 SageAttention 2.2.0 之后,你跑 MiniMax H3 视频生成时,KJNodes 自带的"Patch Sage Attention KJ"节点才能正常工作——能省掉相当一部分显存占用,RTX 4070 Ti SUPER 跑 H3 的关键组件,采样速度还有可观提升(SDXL/Flux 类工作流 3-5× 加速)。

不装的话,KJNodes 的 Sage 补丁节点会直接报错:sageattention is not new enough version or could not determine CUDA architecture(就是你日志里那条红字)。

这篇教程是给"懂点电脑 + 会复制粘贴命令"的人写的。但你不需要懂所有步骤:

• 教程里每一条命令、每一处文件路径,都设计成可以直接复制粘贴
• 遇到不懂的地方 → 把那一段 + 你电脑的实际错误信息,扔给 Codex / Claude Code / Hermes / ChatGPT / DeepSeek 任一 AI,让它一步步带你做
• AI 看不懂的地方,把你的报错截图发给 AI,它会告诉你哪一步错了

AI 工具推荐(任选):

• Codex — OpenAI 的命令行 AI Agent(可以直接帮你跑命令)
• Hermes — 跨平台的本地 AI(支持截图识别)
• Claude Code / Cursor / Copilot — IDE 内 AI
• DeepSeek / ChatGPT / Kimi — 网页 AI,把报错截图 + 描述发它

>

1.1 简单解释

SageAttention 是清华大学发表的注意力机制加速算法。在视频生成/图像生成里,Transformer 的"注意力计算"是显存消耗和计算时间的大头——用 SageAttention 重写后,显存占用显著降低,速度大幅提升。

1.2 装上之后你能拿到什么?

1.3 支持的显卡

• ✅ Ada 架构(40 系) — RTX 4070 Ti SUPER / 4090 等(本教程测试环境)
• ✅ Ampere 架构(30 系) — RTX 3090 / 3080 等
• ✅ Blackwell 架构(50 系) — RTX 5090 等
• ✅ Hopper 架构(H100) — 数据中心卡
• ⚠️ RTX 20 系(算力 sm75):会自动 fallback 到 Triton 内核(性能等同于 1.x),不影响使用

2.1 你需要满足的 5 个条件

2.2 一键自检脚本(我帮你写好了)

复制下面的全部代码,保存成 comfyui_check_env_sageattention.py:

"""
SageAttention 2.2 安装前环境自检脚本
用法:你的 ComfyUI 整合包 Python.exe 路径 + 这个脚本路径
例如:G:\ComfyUI\python_embeded\python.exe comfyui_check_env_sageattention.py
"""
import sys
import subprocess
import shutil
import os

print("=" * 60)
print("SageAttention 2.2 安装前环境自检")
print("=" * 60)

print(f"\n[1] Python 路径: {sys.executable}")
print(f"    Python 版本: {sys.version.split()[0]}")
print("    ✅ 满足(3.9+)" if sys.version_info >= (3, 9) else "    ❌ 需要 3.9+")

modules = ["torch", "sageattention"]
for mod in modules:
    try:
        m = __import__(mod)
        ver = getattr(m, "__version__", "已安装(无版本属性)")
        print(f"[2] {mod}: ✅ {ver}")
    except ImportError:
        print(f"[2] {mod}: ❌ 未安装")

try:
    import torch
    print(f"\n[3] PyTorch CUDA: {torch.version.cuda}")
    print(f"    PyTorch 版本: {torch.__version__}")
    print(f"    CUDA 可用: {torch.cuda.is_available()}")
    if torch.cuda.is_available():
        print(f"    GPU 名称: {torch.cuda.get_device_name(0)}")
        cap = torch.cuda.get_device_capability(0)
        arch = f"sm_{cap[0]}{cap[1]}"
        print(f"    GPU 算力: {arch}")
except Exception as e:
    print(f"[3] PyTorch 检查失败: {e}")

print("\n[4] 编译工具检查(用整合包 wheel 装不需要这些):")
for cmd in ["cmake", "ninja"]:
    path = shutil.which(cmd)
    if path:
        try:
            out = subprocess.run([cmd, "--version"], capture_output=True, text=True, timeout=5)
            ver = (out.stdout or out.stderr).strip().split("\n")[0]
            print(f"    {cmd}: ✅ {path} ({ver})")
        except Exception:
            print(f"    {cmd}: ⚠️ 路径存在但执行失败")
    else:
        print(f"    {cmd}: ❌ 未安装(不强制要求)")

print("\n" + "=" * 60)
print("自检完成。torch + CUDA 正确显示 GPU 后,可以装 SageAttention。")
print("=" * 60)

使用方式(Win+R 输入 cmd,或者在整合包根目录右键打开 PowerShell):

你的整合包路径\python.exe comfyui_check_env_sageattention.py

本教程用户的预期输出:

[1] Python 路径: E:\ComfyUI\python_embeded\python.exe
    Python 版本: 3.12.x
[2] torch: ✅ 2.13.0+cu130
[2] sageattention: ❌ 未安装   ← 还没装,正常
[3] PyTorch CUDA: 13.0
    GPU 算力: sm_89  ← 4070 Ti SUPER

0️⃣ 最简单的方法(小白首选):直接用老许的 ComfyUI 整合包

如果你用的是老许(@老许爱吃肉丶)发布的 ComfyUI 整合包,直接跳到第 4 章——整合包里已经预装好了 SageAttention 2.2,你不用做任何事。

下载:见 B站 / 个人站 / 微信公众号 GaryAigo(进群交流)

1️⃣ 自己装(其他整合包用户):下载 wheel + pip install 一行命令

#### 步骤 1:下载 wheel 文件(30 秒)

打开浏览器,访问:

https://github.com/woct0rdho/SageAttention/releases

找到最新的 v2.2.0-windows.postX 系列(目前最新 post4),往下翻到 Assets。

认准这两个条件:

• 文件名里有 cp39-abi3-win_amd64(Windows 64 位通用 wheel,你的 Python 3.9/3.10/3.11/3.12/3.13 都能用,不用挑版本)
• 文件名里有 cu130torch2.9.0andhigher(CUDA 13.0+,torch 2.9+,兼容几乎所有现代环境)

点那个最大的 .whl 文件下载(大概 5-30 MB)。

不知道点哪个?→ 🤖 把这个页面截图发给 Codex / Hermes / ChatGPT,让它帮你选对的文件

#### 步骤 2:把 wheel 文件放到整合包根目录

下完后,把那个 .whl 文件拖到你的 ComfyUI 整合包根目录(就是有 python_embeded 文件夹的那个目录)。

#### 步骤 3:打开命令行(整合包根目录)

• 方法 1(推荐):按住 Shift,右键整合包根目录空白处 → "在此处打开 PowerShell 窗口"
• 方法 2:Win+R 输入 cmd,然后 cd 你的整合包路径

#### 步骤 4:跑这条命令(改文件名)

PowerShell(文件名有 +,必须加引号):

.\python_embeded\python.exe -m pip install ".\sageattention-2.2.0+cu130torch2.9.0andhigher.post4-cp39-abi3-win_amd64.whl"

cmd(同样要引号):

python_embeded\python.exe -m pip install ".\sageattention-2.2.0+cu130torch2.9.0andhigher.post4-cp39-abi3-win_amd64.whl"

看到类似:

Successfully installed sageattention-2.2.0+cu130torch2.9.0andhigher.post4

就是装好了。整个过程10 秒搞定。

#### 步骤 5:重启 ComfyUI

关掉 ComfyUI 窗口,重新双击 启动启动.bat。SageAttention 已生效。

2️⃣ 其他装法(选了解)

#### 装 1.x 版本(不推荐,性能较弱)

如果你只是要"能跑",可以用 1.x(简单 pip install):

.\python_embeded\python.exe -m pip install sageattention

但 1.x 没有 CUDA 内核,加速效果远不如 2.2。

#### 源码编译(性能极限,但麻烦,Windows 不推荐)

不推荐——需要 Visual Studio 2022 + CUDA Toolkit 12.8+,编译 10-30 分钟。完整步骤见官方仓库 thu-ml/SageAttention 的 README。

4.1 基础验证

跑这条命令:

.\python_embeded\python.exe -c "import sageattention; print('sageattention 路径:', sageattention.__file__)"

期望输出(路径在整合包的 site-packages):

sageattention 路径: E:\ComfyUI\python_embeded\Lib\site-packages\sageattention\__init__.py

• ✅ 路径在你的整合包 site-packages → 装对了
• ❌ 路径在别的位置(比如 C:\Users\...\AppData\...)→ 装到系统 Python 了,得重装
• ❌ ModuleNotFoundError → 装失败,看 第五章

4.2 完整验证(看 CUDA 内核在不在)

跑这条命令(需要 10-30 秒,要看 GPU):

.\python_embeded\python.exe -c "import torch, sageattention; q = torch.randn(1, 8, 64, device='cuda', dtype=torch.float16); k = torch.randn(1, 8, 64, device='cuda', dtype=torch.float16); v = torch.randn(1, 8, 64, device='cuda', dtype=torch.float16); from sageattention import sageattn; o = sageattn(q, k, v); print('OK, output shape:', o.shape)"

• ✅ 输出 OK, output shape: torch.Size([1, 8, 64]) → 完全 OK,CUDA 内核能跑
• ❌ 任何报错 → 你的显卡/CUDA 不兼容这个 wheel

4.3 进阶:看具体编译产物

进入 python_embeded\Lib\site-packages\sageattention\,确认这些文件齐全:

_qattn_sm89.pyd    ← 你的 GPU 架构(4070 Ti SUPER)编译产物
_fused.pyd
core.py
quant.py
triton/  (文件夹)

这些文件齐全 = 安装成功、编译产物正确。

5.1 "找不到 python.exe"

症状:

.\python_embeded\python.exe : 无法识别...

原因:你的整合包根目录没有 python_embeded 文件夹,或你不在整合包根目录。

解决:

dir python_embeded

• 看到了 → 文件夹在,你 cd 错位置了
• 没看到 → 整合包损坏或下错版本。整合包必须有 python_embeded

5.2 "ERROR: ... is not a supported wheel on this platform"

症状:

ERROR: sageattention-2.2.0+cu130torch2.9.0andhigher.post4-cp39-abi3-win_amd64.whl is not a supported wheel on this platform.

原因:wheel 文件和你的环境不匹配(Windows 选了 Linux 的 wheel,或选了 32 位 wheel)。

解决:

5.3 "ImportError: DLL load failed"

症状:

ImportError: DLL load failed while importing sageattention

原因:通常是 torch 版本和 wheel 不匹配,或 CUDA 运行库缺失。

解决:

1. 重新核对 torch 版本和 wheel 文件名
2. 确认 torch.version.cuda ≥ 12.8(否则 wheel 里的 CUDA 内核不兼容)
3. 如果是 RTX 20 系(算力 sm75),理论上 Triton 会兜底;真要 CUDA 内核需要 fork 的 sm75 分支——一般用户不用管

5.4 pip 报"权限错误"

症状:

PermissionError: [WinError 5] 拒绝访问

解决:

1. 关掉正在跑的 ComfyUI(打开的窗口、命令行启动的实例)
2. 不要装到 C:\Program Files\ 等系统目录
3. 重试

5.5 "pip install sageattention 装错了,装成 1.x"

症状:基础验证找不到路径,或路径里只有 1.0.6 的内容。

原因:pip install sageattention(不带文件路径)只会从 PyPI 装,而 PyPI 只有 1.0.6。

解决:

1. 卸载错误的:

```powershell

.\python_embeded\python.exe -m pip uninstall sageattention -y

```

1. 按第 3 章装正确的 2.2 wheel 文件

6.1 启动 ComfyUI

照常启动你的整合包(双击 启动启动.bat 或运行 main.py)。

6.2 工作流里启用 Sage Attention 节点

节点位置(任选其一):

1. 右键画布 → Add Node → 搜索 "Patch Sage Attention"
2. 或者在节点搜索框输入 MiniMaxH3MemoryEfficientSageAttentionPatch(完整名字)

插入位置:

MiniMax H3 模型加载器 → Patch Sage Attention KJ → 采样器

6.3 节点选项详解(KJNodes 插件)

6.4 不同场景的推荐配置

6.5 启用 Verbose = True

强烈建议首次使用开 Verbose,ComfyUI 日志会打印:

Using SageAttention backend: sageattn_qk_int8_pv_fp8_cuda

看到这一行 = 加速生效。

6.6 验证加速生效

跑同一个 prompt(同样的模型 + 同样的 seed),对比:

如果你想退回 SageAttention 1.x 或完全卸载:

.\python_embeded\python.exe -m pip uninstall sageattention -y

如果 wheel 文件还在,也可以手动删:

rmdir /s /q .\python_embeded\Lib\site-packages\sageattention
rmdir /s /q .\python_embeded\Lib\site-packages\sageattention-2.2.0+cu130torch2.9.0andhigher.post4.dist-info

装 SageAttention 前强烈建议备份环境,万一新版本出问题可以一键还原:

.\python_embeded\python.exe -m pip freeze > 整合包目录\env_backup_freeze.txt

还原方法:

新路径\python.exe -m pip install -r 整合包目录\env_backup_freeze.txt

Q1:为什么 pip install sageattention 装不到 2.2.0?

A:2.2.0 不在 PyPI!必须下载第三方 fork 的 wheel 文件安装。PyPI 只有 1.0.6。

Q2:不装 CUDA Toolkit 也能用 SageAttention 2.2 吗?

A:能。本教程推荐的 wheel 是预编译的,不需要你本地编译。直接 pip install 就用。

Q3:装完 SageAttention 还是 OOM?

A:SageAttention 省的是 attention 部分,不是全部显存。16G 卡跑 33B H3 必然要 CPU offload,SageAttention 主要作用是降显存 + 加速。还 OOM 的话降分辨率、关掉 SageAttention(它会占一点额外显存)、加 --lowvram 启动参数。

Q4:和我已有的 xformers 冲突吗?

A:会冲突!两者都 hook PyTorch 的 scaled_dot_product_attention,只能开一个。建议装 SageAttention 后关闭 xformers(启动 ComfyUI 时不加 --use-xformers 参数)。

Q5:RTX 20 系显卡能装吗?

A:能装,但 SageAttention 2 的 CUDA kernel 不支持 sm75(20 系),会自动 fallback 到 Triton 内核(等同于 1.x 性能)。一般用户直接装上就用,不影响。

Q6:实测 SageAttention 效果不好怎么办?

A:

Q7:可以和其他 attention 加速插件共存吗?

A:不建议。SageAttention 和 TeaCache、xformers 都会 hook 同一个函数,会互相覆盖。建议 SageAttention 装了就关闭其他 attention 加速插件。

Q8:wheel 文件名里的 cp39-abi3 是什么意思?

A:Python 稳定 ABI 标识。cp39-abi3 表示 Python 3.9+ 通用——你的 Python 3.10/3.11/3.12/3.13 都能装这个 wheel,不用选对应 Python 版本的。这是 SageAttention 2.2 wheel 的优势,省得挑版本。

Q9:我看到这一堆步骤就头大,真的有 AI 能帮我搞定吗?

A:能。把你当前卡住的那一步 + 你电脑的具体报错截图,发给 Codex / Hermes / ChatGPT 任一 AI,它们都能一步步带你做。

举例:你在"步骤 4 跑命令"卡住了,就把以下内容发给 AI:

我要用以下教程安装 SageAttention 2.2:

<粘贴教程第三章>
(或者你把当前卡住的章节标题告诉 AI,让 AI 自己搜教程)

我现在卡在 [步骤 X],执行以下命令:
.\python_embeded\python.exe -m pip install ".\sageattention-2.2.0+cu130torch2.9.0andhigher.post4-cp39-abi3-win_amd64.whl"

报错:
<把报错截图/文字贴这里>

我的环境:
- 整合包路径:E:\ComfyUI(替换成你的)
- Python 版本:3.12.x
- GPU:RTX 4070 Ti SUPER

请一步步教我接下来怎么做。

AI 工具推荐:

• Codex(codex命令行)— OpenAI 出的,可以直接帮你跑命令
• Hermes — 你正在用的 AI 桌面 App(支持截图识别)
• Claude Code / Cursor — IDE 内 AI,可以直接修改文件 + 跑命令
• DeepSeek / ChatGPT / Kimi — 网页 AI,把你截图 + 报错发它

Q10:复制教程给 AI,AI 会不会乱改?

A:不会。教程是只读的"参考资料",AI 看完后给你建议命令,但不会直接改你电脑的文件。除非你用 Codex / Claude Code 这种 Agent 模式 的 AI(它可以执行命令,但前提是你授权它跑)。

教程跑不通?某个步骤不清楚?直接评论区告诉我,我会更新教程。