背景与问题描述
最近给 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，需要从源码本地编译。
环境信息
| 项目 | 版本 |
|---|---|
| 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 源码
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 编译。
编译环境准备
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 升级到最新版本破坏现有环境。