Windows 环境定制编译 SageAttention 适配版本从报错、诊断、编译到修复的完整复盘https://github.com/thu-ml/SageAttention如果无法实现编译Windows系统安装SageAttention详细教程Wheel文件安装指南环境速览环境项目版本/信息操作系统Windows 11 专业工作站版 Insider PreviewGPUNVIDIA RTX 3090 24GB驱动版本595.02Python3.12.11PyTorch2.7.1cu126CUDA 12.6PyTorch 内置 nvccCUDA 12.8系统 CUDA 版本v12.8 / v12.9 / v13.0 / v13.1SageAttention 编译版本2.2.0源码编译diffusers0.35.2triton-windows3.2.0.post19Visual Studio2022 专业版一、问题起源神秘的 headdim 报错在运行 ComfyUI 的 SeedVR2 Video Upscaler 工作流时遇到了如下报错AssertionError: headdim should be in [64, 96, 128]. File sageattention\core.py, line 82, in sageattn表面上看是 SageAttention 的限制但背后牵涉到整个软件栈的兼容性问题需要从根本上理解才能正确解决。二、架构差异Windows 编译与 Linux 的本质不同SageAttention 包含 CUDA 自定义算子需要在本地编译。Linux 和 Windows 的编译环境有根本性差异差异项LinuxWindowsC 编译器GCC系统自带MSVC需安装 Visual Studio编译工具链Make / CMakeMSBuild / NinjaCUDA 集成nvcc 直接可用需配置 VS 开发者环境变量预编译 wheel官方提供多版本极少通常需自行编译常见坑较少DLL 冲突、路径空格、环境变量缺失⚠️关键点Windows 下必须使用Visual Studio Developer PowerShell终端否则cl.exeMSVC 编译器不在 PATH 中编译必然失败。三、环境勘察多版本 CUDA 的优先级陷阱3.1 查询当前环境在 VS2022 Developer PowerShell 中激活虚拟环境后依次执行# 查看 PyTorch 使用的 CUDA 版本 python -c import torch; print(torch.version.cuda) # 输出12.6 # 查看 PyTorch 内置的 nvcc 版本关键 .venv\Lib\site-packages\torch\lib\bin\nvcc.exe --version # 输出release 12.8, V12.8.93 # 查看系统安装了哪些 CUDA 版本 Get-ChildItem C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA -Directory # 输出v12.8 v12.9 v13.0 v13.1 # 查看 PATH 中 nvcc 的优先级第一行即实际使用的版本 where.exe nvcc # 输出C:\...\CUDA\v13.1\bin\nvcc.exe ← 当前默认错误版本3.2 版本匹配原则这是整个编译过程最关键的认知概念说明本机值torch CUDA 版本torch 编译时链接的 CUDA Runtime 版本12.6cu126PyTorch 内置 nvcctorch 包内自带的 nvcc实际编译扩展时使用12.8系统 nvcc 优先级PATH 中排第一的 nvcc默认会被调用13.1错误需要切换到与 PyTorch 内置 nvcc 一致的系统 CUDAv12.8结论编译 SageAttention 时系统 nvcc 必须与PyTorch 内置 nvcc版本一致本机为 12.8而不是看 torch 的 cu126 标签。四、编译准备环境变量与工具配置4.1 必备前提Visual Studio 2022含 C 桌面开发工作负载CUDA Toolkit 12.8与 PyTorch 内置 nvcc 一致在 VS Developer PowerShell 中操作保证cl.exe可用验证工具链nvcc --version # 确认可调用 cl # 确认 MSVC 可用应显示Microsoft C/C 优化编译器4.2 临时切换 nvcc 到 12.8# 将 CUDA 12.8 插入 PATH 最前面覆盖 13.1 的优先级 $env:PATH C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin; $env:PATH $env:CUDA_HOME C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8 $env:CUDA_PATH C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8 # 确认切换成功必须显示 12.8 nvcc --version4.3 设置编译环境变量$env:DISTUTILS_USE_SDK 1 # 告知 setuptools 使用 SDK 中的 MSVC $env:MSSdk 1 # 标识 Microsoft SDK 环境 $env:USE_NINJA 0 # 禁用 Ninja使用 MSBuildWindows 更稳定 $env:MAX_JOBS 4 # 并行编译线程数4.4 卸载旧版本避免干扰pip uninstall sageattention4.4 克隆仓库并进入路径git clone https://github.com/thu-ml/SageAttention cd SageAttention git submodule update --init --recursive五、修改版本限制pyproject.toml 的上限问题直接编译会遇到依赖版本冲突ERROR Missing dependencies: setuptools75,62 packaging24,21 wheel0.44,0.38原因是 SageAttention 的pyproject.toml对构建工具设置了上限而虚拟环境中安装的是更新版本setuptools 81.0、packaging 26.0、wheel 0.46。直接降级这些包会导致大量依赖冲突正确做法是修改 pyproject.toml 去掉版本上限# 用 PowerShell 一次性替换三个版本限制 (Get-Content pyproject.toml) -replace setuptools62,75, setuptools62 -replace wheel0.38,0.44, wheel0.38 -replace packaging21,24, packaging21 | Set-Content pyproject.toml确认修改结果# 确认修改结果 Get-Content pyproject.toml修改后pyproject.toml内容[build-system] requires [ setuptools62, wheel0.38, packaging21, ] build-backend setuptools.build_meta六、编译与保存 Wheel6.1 为什么不用pip install -e .命令是否保留 wheel说明pip install -e .否开发模式编译后清理临时文件无 .whl 产出pip wheel . -w 目录是只编译生成 wheel不安装python -m build --wheel --no-isolation是标准方式输出到 dist/ 目录--no-isolation参数至关重要pip 默认会创建隔离的临时虚拟环境来编译该环境中没有 torch导致setup.py找不到 torch 而报错。加上--no-isolation后直接使用当前虚拟环境torch 正常可见。6.2 完整编译命令# 安装 build 工具 pip install build # 编译输出到 dist/ 目录 python -m build --wheel --no-isolation # 复制到备份目录日后重建环境直接用 Copy-Item .\dist\sageattention-2.2.0-cp312-cp312-win_amd64.whl H:\PythonProjects3\Win_ComfyUI\wheels\ # 安装 pip install .\dist\sageattention-2.2.0-cp312-cp312-win_amd64.whl --force-reinstall6.3 编译成功验证生成的 wheel 文件名包含完整的平台和版本信息sageattention-2.2.0-cp312-cp312-win_amd64.whl # ↑版本 ↑Python版本 ↑平台备份# 复制到备份目录日后重建环境直接用 Copy-Item .\dist\sageattention-2.2.0-cp312-cp312-win_amd64.whl H:\PythonProjects3\Win_ComfyUI\wheels\安装# 安装 pip install .\dist\sageattention-2.2.0-cp312-cp312-win_amd64.whl --force-reinstall验证# 必须切换出 SageAttention 源码目录再验证避免路径冲突导致假报错 cd H:\PythonProjects3\Win_ComfyUI python -c import sageattention; print(dir(sageattention)) pip show sageattention # Name: sageattention Version: 2.2.0 ✅⚠️注意验证时必须切换出源码目录否则 Python 会优先导入当前目录下的源码包产生循环导入的假报错。6.4 常见编译警告说明警告1ABI tag 可能不正确RuntimeWarning: Config variable Py_DEBUG is unset, Python ABI tag may be incorrect这是 setuptools 新版本的已知小问题原因是无法确认当前 Python 是否为 debug build。可以完全忽略生成的cp312-cp312-win_amd64tag 是正确的wheel 文件正常可用。警告2循环导入假报错在 SageAttention 源码目录下验证时会看到ImportError: cannot import name _fused from partially initialized module sageattention (most likely due to a circular import)这不是真实错误是 Python 在当前目录优先找到了源码包而非安装包导致的。切换到其他目录再验证即可消除。七、根本问题分析Monkey-Patch 引发的连环崩溃7.1 SageAttention 的全局替换机制SageAttention 安装后会执行一个全局替换torch.nn.functional.scaled_dot_product_attention sageattn这意味着整个 Python 进程中所有调用F.scaled_dot_product_attention的代码无论来自 diffusers、ComfyUI 自身还是任何自定义节点都会被 SageAttention 拦截处理。7.2 两类不兼容场景问题类型触发条件报错信息涉及节点head_dim 不支持attention 层 head_dim 不在 [64,96,128]ValueError: Unsupported head_dim: 512SeedVR2、LBM 等使用 VAE 的节点dtype 不支持输入张量为 float32AssertionError: Input tensors must be in dtype of fp16 or bf16Qwen VL 视觉编码器等7.3 为什么简单 fallback 会无限递归第一次尝试在 fallback 中调用F.scaled_dot_product_attention结果产生了RecursionError原因是sageattn 被调用 → head_dim512触发 fallback → 调用 F.scaled_dot_product_attention → 已被替换为 sageattn → 无限递归栈溢出正确做法是绕过被替换的F函数直接调用 PyTorch 的 C 底层实现import torch._C._nn as _C_nn out _C_nn.scaled_dot_product_attention( q, k, v, attn_maskNone, dropout_p0.0, is_causalis_causal, scale_sm_scale )八、最终修复方案core.py 通用 Fallback8.1 修复原则经过多次尝试在各节点文件打补丁最终确认最稳健的方案是在 SageAttention 的core.py入口处统一处理一次修复覆盖所有情况。方案优点缺点各节点文件单独打补丁影响范围小新节点出现仍需反复修改治标不治本core.py 通用 fallback最终方案一次修复永久生效覆盖所有调用方修改了 venv 中的包文件8.2 修改位置与内容文件路径.venv\Lib\site-packages\sageattention\core.py在sageattn函数体开头arch get_cuda_arch_versions()这行之前插入# ── 通用 fallbackdtype 或 head_dim 不支持时自动降级到原生 SDPA ── _SUPPORTED_DTYPES (torch.float16, torch.bfloat16) _SUPPORTED_HEAD_DIMS (64, 96, 128) head_dim q.size(-1) if q.dtype not in _SUPPORTED_DTYPES or head_dim not in _SUPPORTED_HEAD_DIMS: import torch._C._nn as _C_nn _sm_scale sm_scale if sm_scale is not None else head_dim ** -0.5 if tensor_layout NHD: q, k, v q.transpose(1, 2), k.transpose(1, 2), v.transpose(1, 2) out _C_nn.scaled_dot_product_attention( q, k, v, attn_maskNone, dropout_p0.0, is_causalis_causal, scale_sm_scale ) if tensor_layout NHD: out out.transpose(1, 2) return (out, None) if return_lse else out # ── fallback end ──8.3 验证三个场景python -c import torch, sageattention # 场景1head_dim512触发 fallback q torch.randn(1,1,16,512,dtypetorch.float16,devicecuda) k torch.randn(1,1,16,512,dtypetorch.float16,devicecuda) v torch.randn(1,1,16,512,dtypetorch.float16,devicecuda) out sageattention.sageattn(q,k,v) print(head_dim512 fp16 OK:, out.shape) # ✅ # 场景2float32触发 fallback q torch.randn(1,1,16,64,dtypetorch.float32,devicecuda) k torch.randn(1,1,16,64,dtypetorch.float32,devicecuda) v torch.randn(1,1,16,64,dtypetorch.float32,devicecuda) out sageattention.sageattn(q,k,v) print(head_dim64 float32 OK:, out.shape) # ✅ # 场景3正常路径走 SageAttention 加速 q torch.randn(1,1,16,128,dtypetorch.float16,devicecuda) k torch.randn(1,1,16,128,dtypetorch.float16,devicecuda) v torch.randn(1,1,16,128,dtypetorch.float16,devicecuda) out sageattention.sageattn(q,k,v) print(head_dim128 fp16 SageAttn OK:, out.shape) # ✅ 九、附加补丁其他文件的双重保险在确定 core.py 方案之前还对以下两个文件做了修改。保留这些修改不影响功能相当于双重保险。9.1 attn_video_vae.pySeedVR2 节点文件路径custom_nodes\ComfyUI-SeedVR2_VideoUpscaler\src\models\video_vae_v3\modules\attn_video_vae.py在 import 区域末尾添加上下文管理器from contextlib import contextmanager contextmanager def native_sdp_attention(): 临时绕过 SageAttention monkey-patch使用 PyTorch 原生 SDPA。 import torch.nn.functional as _F _original _F.scaled_dot_product_attention try: import torch._C._nn as _C_nn _F.scaled_dot_product_attention _C_nn.scaled_dot_product_attention yield finally: _F.scaled_dot_product_attention _original在forward方法的attn调用处包裹_head_dim hidden_states.shape[1] _needs_fallback _head_dim not in [64, 96, 128] with native_sdp_attention() if _needs_fallback else nullcontext(): hidden_states attn(hidden_states, tembtemb)9.2 comfy/ops.pyComfyUI 核心文件路径comfy\ops.py在scaled_dot_product_attention函数开头加 dtype 检查def scaled_dot_product_attention(q, k, v, *args, **kwargs): # SageAttention 只支持 fp16/bf16其他 dtype 用原生实现绕过 monkey-patch if q.dtype not in (torch.float16, torch.bfloat16): return torch._C._nn.scaled_dot_product_attention(q, k, v, *args, **kwargs) if q.nelement() 1024 * 128: return torch.nn.functional.scaled_dot_product_attention(q, k, v, *args, **kwargs) with sdpa_kernel(SDPA_BACKEND_PRIORITY, set_priorityTrue): return torch.nn.functional.scaled_dot_product_attention(q, k, v, *args, **kwargs)十、复盘总结与经验提炼10.1 完整解决路径步骤操作解决的问题1切换系统 nvcc 到 12.8nvcc 版本与 PyTorch 内置版本不一致2设置 DISTUTILS_USE_SDK 等环境变量Windows 下 MSVC 编译器无法被正确识别3修改 pyproject.toml 去掉版本上限构建依赖版本冲突4用python -m build --wheel --no-isolation编译pip 隔离环境找不到 torch5修改 core.py 加通用 fallback所有 head_dim / dtype 不支持的报错6修改 comfy/ops.py 加 dtype 检查Qwen VL float32 dtype 报错7设置 TRITON_PTXAS_PATH 环境变量Triton 自带 ptxas.exe DLL 初始化失败10.2 关键经验Windows 编译 CUDA 扩展必须用VS Developer 终端普通 PowerShell 缺少cl.exe多版本 CUDA 并存时PATH 优先级决定实际使用的 nvcc必须手动切换编译版本链系统 nvcc PyTorch 内置 nvcc12.8而非 PyTorch 的 CUDA Runtime12.6--no-isolation是在已有虚拟环境中编译 CUDA 扩展的必要参数SageAttention 的全局 monkey-patch 设计会影响整个进程fallback 必须调用C 底层实现避免递归pyproject.toml的版本上限可以安全去掉不要降级已安装的构建工具编译好的wheel 文件要及时备份文件名包含完整的环境信息可直接用于重建环境Windows 下 Triton 的包名是triton-windows而非tritonpip show triton会提示找不到需用pip show triton-windows查询10.3 附Triton ptxas.exe DLL 报错运行过程中还可能遇到另一个独立问题subprocess.CalledProcessError: Command [...triton\backends\nvidia\bin\ptxas.exe, --version] returned non-zero exit status 3221225794.错误码3221225794即0xC0000142是 Windows 的DLL 初始化失败原因是 triton-windows 自带的ptxas.exe与当前系统 CUDA 运行库不兼容。解决方法让 Triton 使用系统安装的 ptxas# 先验证系统 ptxas 是否正常 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin\ptxas.exe --version # 应正常输出版本信息 # 永久设置环境变量写入用户环境变量重启终端后生效 [System.Environment]::SetEnvironmentVariable( TRITON_PTXAS_PATH, C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin\ptxas.exe, User )设置后关闭当前 PowerShell 窗口重新打开再启动 ComfyUI 即可。10.4 日后重建环境完整步骤下次重建虚拟环境时按以下顺序操作第一步安装备份的 wheel无需重新编译pip install H:\PythonProjects3\Win_ComfyUI\wheels\sageattention-2.2.0-cp312-cp312-win_amd64.whl第二步重新应用 core.py 补丁打开文件.venv\Lib\site-packages\sageattention\core.py在sageattn函数体开头arch get_cuda_arch_versions()之前插入通用 fallback 代码见第八章 8.2 节。第三步重新应用 comfy/ops.py 补丁打开文件comfy\ops.py在scaled_dot_product_attention函数开头加入 dtype 检查见第九章 9.2 节。第四步确认 TRITON_PTXAS_PATH 环境变量已设置[System.Environment]::GetEnvironmentVariable(TRITON_PTXAS_PATH, User) # 应输出 CUDA 12.8 的 ptxas.exe 路径提示core.py和comfy/ops.py的补丁内容建议另存一份文本文件备用重建环境时直接复制粘贴省去重新查找的麻烦。如果本文对你有帮助欢迎点赞收藏。有问题欢迎在评论区交流。下一篇我们将尝试从源代码编译自己环境适配版的 Triton。