【实战】Windows 下为 Stable Diffusion WebUI 编译 Flash-Attention 2.8.0 专属 Wheel（RTX 3090 sm_86）
【实战】Windows 下为 Stable Diffusion WebUI 编译 Flash-Attention 2.8.0 专属 Wheel（RTX 3090 sm_86）
系列：Windows AI 环境 “没有轮子（.whl）就自己造” 从零到一 · 第 N 期
难度：⭐⭐⭐⭐
适用场景：SD WebUI + xformers 0.0.31.post1 + flash-attn 版本冲突修复
适用场景：其他版本的 Flash-Attention 编译实战请见文末引用链接
一、背景与问题描述
彻底解决 Stable Diffusion WebUI 启动报错：AttributeError: ‘MessageFactory’ object has no attribute ‘GetProto
【SD WebUI踩坑】启动报错 Expecting value: line 1 column 1 (char 0) 的终极解决方案
最近给 Stable Diffusion WebUI（AUTOMATIC1111）加了一条启动参数：
--xformers-flash-attention
以开启 Flash-Attention 注意力加速。启动后，日志中出现以下报错：
*** Cannot import xformers ImportError: Requires Flash-Attention version >=2.7.1,<=2.8.0 but got 2.8.3. *** Error loading script: inpaint_anything.py ImportError: Requires Flash-Attention version >=2.7.1,<=2.8.0 but got 2.8.3. 根本原因：xformers 0.0.31.post1 对 flash-attn 有严格的版本上限要求（<=2.8.0），而环境中装的是 flash-attn 2.8.3，触发硬性版本检查导致导入失败，进而引发 inpaint_anything 等依赖 diffusers 的插件连锁崩溃。
解决思路：将 flash-attn 降级到 2.8.0。由于 flash-attn 官方没有 Windows 预编译 wheel，需要从源码本地编译。
快速查找 FlashAttention的预构建轮子（flash_attn wheels）：Windows/Linux 用户快速查找神器
二、环境信息
| 项目 | 版本 |
|---|---|
| OS | Windows 11 |
| GPU | RTX 3090（sm_86） |
| 驱动 | 595.02 |
| Python（venv） | 3.11.13 |
| PyTorch | 2.7.1+cu126 |
| xformers | 0.0.31.post1 |
| CUDA 编译器 | 13.1（nvcc V13.1.80） |
| Visual Studio | VS 2022 / VS 18 Insiders（MSVC 14.50.35717） |
| Windows SDK | 10.0.26100.0 |
| SD WebUI 路径 | G:\PythonProjects2\stable-diffusion-webui |
⚠️ 注意：PyTorch 内部 CUDA 版本是 12.6，但编译时需要用 CUDA 13.1，原因见第四节。
三、克隆 flash-attn 2.8.0 源码
Dao-AILab/flash-attention：快速且内存高效的精确注意力
cd G:\PythonProjects2\stable-diffusion-webui git clone https://github.com/Dao-AILab/flash-attention.git --branch v2.8.0 --depth 1 --depth 1 只拉最新一个 commit，节省流量和时间（约 5MB）。
四、为什么不用 CUDA 12.6 编译？
flash-attn 2.8.0 的 setup.py 在检测到 bare_metal_version >= 12.8 时会自动向架构列表追加 sm_100 和 sm_120（Blackwell 架构）：
# setup.py 第 186-189 行 if bare_metal_version >= Version("12.8") and "100" in cuda_archs(): ... if bare_metal_version >= Version("12.8") and "120" in cuda_archs(): ... 当用 CUDA 13.1（>= 12.8）时，这两行会触发；而 CUDA 12.6 的 nvcc 不支持 compute_120，导致：
nvcc fatal: Unsupported gpu architecture 'compute_120' 因此必须使用 CUDA 13.1 编译，同时通过 TORCH_CUDA_ARCH_LIST=8.6 限定只编译 RTX 3090 所需的架构，跳过 sm_100/sm_120 的实际 kernel 编译。
五、编译环境准备
Switch-CUDA 脚本来源详见：
Windows 多版本 CUDA + cuDNN 环境配置完全指南
5.1 切换 CUDA 版本
使用 Switch-CUDA 脚本切换到 CUDA 13.1：
. D:\Program\switch-cuda.ps1 Switch-CUDA 13.1 输出确认：
✅ 已切换到 CUDA 13.1 CUDA : C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1 Cuda compilation tools, release 13.1, V13.1.80 5.2 挂载 subst 虚拟盘（规避长路径）
subst Z: "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1" 5.3 设置编译环境变量
$env:CUDA_HOME = "Z:" $env:CUDA_PATH = "Z:" $env:CUDA_ROOT = "Z:" $env:CudaToolkitDir = "Z:" $env:TORCH_CUDA_ARCH_LIST = "8.6" # 仅编译 RTX 3090 所需架构 $env:FLASH_ATTN_CUDA_ARCHS = "86" # flash-attn 内部架构控制 $env:FLASH_ATTENTION_FORCE_BUILD = "TRUE" # 强制本地编译，跳过预编译 wheel 下载 $env:MAX_JOBS = "8" # 并行编译任务数 $env:NVCC_THREADS = "2" # nvcc 内部线程数 $env:DISTUTILS_USE_SDK = "1" # 强制使用 MSVC SDK $env:NVCC_PREPEND_FLAGS = "-allow-unsupported-compiler" # 绕过 nvcc VS 版本检查 5.4 配置 x64 MSVC 编译器
查找系统中可用的 x64 cl.exe：
Get-ChildItem "C:\Program Files\Microsoft Visual Studio" -Recurse -Filter "cl.exe" -ErrorAction SilentlyContinue | Where-Object {$_.FullName -like "*Hostx64\x64*"} | Select-Object FullName 将最新版本的 x64 cl.exe 加入 PATH 最前面（本例为 VS 18 Insiders 14.50.35717）：
$env:PATH = "C:\Program Files\Microsoft Visual Studio\18\Insiders\VC\Tools\MSVC\14.50.35717\bin\Hostx64\x64;" + $env:PATH 验证：
cl.exe 2>&1 | Select-Object -First 1 # 应输出：Microsoft (R) C/C++ Optimizing Compiler 19.50.xxxxx for x64 5.5 添加 Windows SDK rc.exe
链接阶段需要 rc.exe（Windows 资源编译器），通常不在默认 PATH 中：
$env:PATH = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64;" + $env:PATH where.exe rc.exe # 确认可找到 5.6 验证关键工具
where.exe nvcc # 应指向 CUDA 13.1 where.exe cl.exe # 应指向 x64 MSVC where.exe rc.exe # 应指向 Windows SDK 六、关键 Patch：绕过 PyTorch CUDA 版本检查
PyTorch 的 cpp_extension.py 会校验 nvcc 版本与 PyTorch 内部 CUDA 版本是否一致。由于 PyTorch 是 cu126 版本，而我们用 CUDA 13.1 的 nvcc 编译，会触发：
RuntimeError: The detected CUDA version (13.1) mismatches the version that was used to compile PyTorch (12.6). 定位问题行：
$file = "G:\PythonProjects2\stable-diffusion-webui\.venv\Lib\site-packages\torch\utils\cpp_extension.py" # 先用 Python 确认实际缩进（repr 显示原始字符） G:\PythonProjects2\stable-diffusion-webui\.venv\Scripts\python.exe -c " f = open(r'$file', encoding='utf-8') lines = f.readlines() f.close() for i, line in enumerate(lines[474:484], start=475): print(repr(line)) " 确认目标行内容后，用 Python 精确替换（避免 PowerShell 字符串编码问题）：
G:\PythonProjects2\stable-diffusion-webui\.venv\Scripts\python.exe -c " f = open(r'G:\PythonProjects2\stable-diffusion-webui\.venv\Lib\site-packages\torch\utils\cpp_extension.py', encoding='utf-8') content = f.read() f.close() old = ' raise RuntimeError(CUDA_MISMATCH_MESSAGE.format(cuda_str_version, torch.version.cuda))' new = ' pass # raise RuntimeError(CUDA_MISMATCH_MESSAGE.format(cuda_str_version, torch.version.cuda))' print('found:', old in content) content2 = content.replace(old, new) open(r'G:\PythonProjects2\stable-diffusion-webui\.venv\Lib\site-packages\torch\utils\cpp_extension.py', 'w', encoding='utf-8').write(content2) print('done') " 输出 found: True + done 即成功。
⚠️ 还原说明：编译完成后建议还原此文件，执行 pip install --force-reinstall --no-deps torch==2.7.1+cu126 --index-url https://download.pytorch.org/whl/cu126 即可覆盖还原。七、执行编译
# 清理上次失败的缓存（如有） Remove-Item -Recurse -Force G:\PythonProjects2\stable-diffusion-webui\flash-attention\build -ErrorAction SilentlyContinue # 进入源码目录 cd G:\PythonProjects2\stable-diffusion-webui\flash-attention # 开始编译 G:\PythonProjects2\stable-diffusion-webui\.venv\Scripts\python.exe setup.py bdist_wheel ` --dist-dir G:\PythonProjects2\stable-diffusion-webui\wheels 编译过程会大量刷屏（ninja 调用 nvcc 编译各 kernel），属正常现象。RTX 3090 + MAX_JOBS=8 约需 30~60 分钟。
编译成功标志：
adding 'flash_attn-2.8.0.dist-info/RECORD' removing build\bdist.win-amd64\wheel 
八、安装 Wheel
# 确认生成的 whl 文件 Get-ChildItem G:\PythonProjects2\stable-diffusion-webui\wheels\flash_attn*.whl # 安装进 SD WebUI venv（--no-deps 避免意外升级 torch） G:\PythonProjects2\stable-diffusion-webui\.venv\Scripts\pip.exe install ` G:\PythonProjects2\stable-diffusion-webui\wheels\flash_attn-2.8.0-cp311-cp311-win_amd64.whl ` --force-reinstall --no-deps 预期输出：
Successfully installed flash-attn-2.8.0 
九、验证
# 验证 xformers 可正常导入 G:\PythonProjects2\stable-diffusion-webui\.venv\Scripts\python.exe -c "import xformers; print('xformers OK:', xformers.__version__)" # 输出：xformers OK: 0.0.31.post1 
启动 SD WebUI，日志中应出现：
Applying attention optimization: xformers... done. 原来的两处报错全部消失：
- ✅
Cannot import xformers→ 消失 - ✅
Error loading script: inpaint_anything.py→ 消失
Flash-Attention 注意力加速开启成功 ✅
十、踩坑全记录
| # | 报错 | 原因 | 解决 |
|---|---|---|---|
| 1 | nvcc cannot find a supported version of Microsoft Visual Studio | 在普通 PowerShell 中运行，未初始化 VS 环境 | 手动将 VS x64 cl.exe 目录加入 PATH |
| 2 | fatal error C1189: You need C++17 to compile PyTorch | PATH 中的 cl.exe 是旧版 x86（VS 2019 14.16） | 将 VS 18 Insiders 14.50.35717\Hostx64\x64 加到 PATH 最前面 |
| 3 | RuntimeError: CUDA version (13.1) mismatches PyTorch (12.6) | PyTorch cpp_extension.py 的版本硬检查 | Python 直接替换文件，将 raise RuntimeError 改为 pass |
| 4 | nvcc fatal: Unsupported gpu architecture 'compute_120' | CUDA 12.6 不支持 sm_120；setup.py 在 CUDA≥12.8 时自动追加该架构 | 改用 CUDA 13.1 编译 |
| 5 | LINK: fatal error LNK1158: 无法运行"rc.exe" | Windows SDK rc.exe 不在 PATH | 将 Windows Kits\10\bin\10.0.26100.0\x64 加入 PATH |
| 6 | IndentationError: expected an indented block after 'if' statement | 注释掉 raise RuntimeError 后 if 块变空 | 用 pass 替换（同行注释形式，避免缩进问题） |
| 7 | PowerShell .Replace() 无法匹配文件内容 | 文件实际缩进（12空格）与肉眼估计（16空格）不符；PowerShell 字符串有编码问题 | 先用 Python repr() 查看原始内容，再用 Python 执行替换 |
十一、完整环境变量一览
# ============================== # Flash-Attn 2.8.0 编译环境设置 # 适用：Python 3.11 + PyTorch 2.7.1+cu126 + RTX 3090 # ============================== # 1. 切换 CUDA . D:\Program\switch-cuda.ps1 Switch-CUDA 13.1 # 2. subst 挂载 subst Z: /d # 先卸载旧挂载（如有） subst Z: "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.1" # 3. CUDA 环境变量 $env:CUDA_HOME = "Z:" $env:CUDA_PATH = "Z:" $env:CUDA_ROOT = "Z:" $env:CudaToolkitDir = "Z:" # 4. 编译控制 $env:TORCH_CUDA_ARCH_LIST = "8.6" $env:FLASH_ATTN_CUDA_ARCHS = "86" $env:FLASH_ATTENTION_FORCE_BUILD = "TRUE" $env:MAX_JOBS = "8" $env:NVCC_THREADS = "2" $env:DISTUTILS_USE_SDK = "1" $env:NVCC_PREPEND_FLAGS = "-allow-unsupported-compiler" # 5. MSVC x64 工具链 $env:PATH = "C:\Program Files\Microsoft Visual Studio\18\Insiders\VC\Tools\MSVC\14.50.35717\bin\Hostx64\x64;" + $env:PATH # 6. Windows SDK rc.exe $env:PATH = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64;" + $env:PATH 十二、小结
本文记录了在 Windows 11 + RTX 3090 环境下，为 Stable Diffusion WebUI 专属 venv（Python 3.11 + PyTorch 2.7.1+cu126）从源码编译 flash-attn 2.8.0 的完整过程。
核心要点：
- CUDA 版本选择：flash-attn 2.8.0 在 CUDA ≥ 12.8 时会自动加入 sm_100/sm_120，必须用能支持这些架构的 CUDA 13.1 编译，而不是与 PyTorch 版本一致的 CUDA 12.6。
- PyTorch 版本检查 patch：用 Python 直接操作文件，将
raise RuntimeError替换为pass，是绕过 CUDA 版本不匹配检查最可靠的方式（避免 PowerShell 字符串编码坑）。 - rc.exe 问题：Windows 编译 CUDA extension 时，链接阶段依赖 Windows SDK 的
rc.exe，需手动加入 PATH，这是 Linux 编译文档中不会提到的 Windows 专属坑。 --no-deps安装：安装 wheel 时务必加--no-deps，防止 flash-attn 的 setup.py 把 torch 升级到最新版本破坏现有环境。
十三、参考资料
【独家资源】Windows 本地部署微软 BitNet b1.58： Flash Attention + CUDA GPU 加速 (sm_86) + AVX2 优化 + 1.58bit 量化
手把手编译 Ollama 源码：启用 CUDA + Flash Attention 双加速（Windows + RTX 3090）
llama-cpp-python 编译 CUDA + Flash Attention 双加速 实战完整指南--Windows
Windows 强制编译 Flash Attention 完全指南：绕过 CUDA 版本地狱零、实战验证环境（已测试通过）
【高阶编译】Windows 环境下强制编译 Flash Attention：绕过 CUDA 版本不匹配高阶指南
快速查找 FlashAttention的预构建轮子（flash_attn wheels）：Windows/Linux 用户快速查找神器
Windows 下 Flash Attention “the provided PTX was compiled with an unsupported toolchain” 错误全面解决笔记
Z-Image-Turbo 项目 Windows 下从 CPU-only 到完整 CUDA + Flash Attention 部署教程（2026年1月回忆版）
Flash Attention 2.8.3 在 Windows + RTX 3090 上成功编译与运行复盘笔记（2026年1月版）
【笔记】Windows 下本地编译 Flash-Attention 2.8.3 后对 RTX 3090 (sm_86) Kernel 支持的完整验证
Windows 11 下再次成功本地编译 Flash-Attention 2.8.3 并生成自定义 Wheel（RTX 3090 sm_86 专属版）
Windows 11 下 Z-Image-Turbo 完整部署与 Flash Attention 2.8.3 本地编译复盘
Windows 下成功编译 Flash Attention 2.8.3 （flash-attn /flash_attn）个人复盘记录
Flash Attention 在 Windows 上编译成功复盘笔记
Windows 系统中安装 flash_attn （flash-attn）
本文是 Windows AI 开发环境系列的一部分，更多文章见 ZEEKLOG 主页。
