README_zh-CN.md

# Blackwell4ComfyUI

[English](README.md) | **简体中文**

面向 **ComfyUI Windows 环境与 NVIDIA Blackwell（RTX 50 系列）显卡**整理的注意力加速扩展预编译包集合。项目当前提供适配 Python 3.11、PyTorch 2.9.1 与 CUDA 13.0 的 Windows x64 wheel，省去本地配置 Visual Studio、CUDA 编译工具链以及长时间编译的过程。

## 包含组件

| 组件 | 包名 | 版本 | 用途 |
| --- | --- | --- | --- |
| Block Sparse Attention | `block_sparse_attn` | 0.0.1 | 提供密集、流式和块稀疏注意力内核，可降低长序列注意力计算开销 |
| SpargeAttention | `spas_sage_attn` | 0.1.0 | 基于 SageAttention2 的免训练稀疏注意力实现，适用于语言、图像和视频模型推理 |
| SageAttention | `sageattention` | 2.2.0 | 通过量化注意力内核加速推理，同时兼顾计算精度 |
| FlashAttention | `flash_attn` | 2.8.4 | 内存高效的精确注意力内核，可加速模型训练与推理 |

## 当前兼容环境

- 操作系统：Windows x64
- Python：CPython 3.11
- PyTorch：2.9.1
- CUDA：13.0
- GPU：主要面向 NVIDIA Blackwell / RTX 50 系列

wheel 属于与运行环境紧密绑定的二进制包。Python、PyTorch、CUDA 或系统架构不匹配时，可能无法安装，或在导入、运行阶段出现动态库及 CUDA 内核错误。

## 目录结构

```text
Blackwell4ComfyUI/
├─ Block-Sparse-Attention/
│  └─ cp311-torch2.9.1-cu130-win/
│     └─ block_sparse_attn-0.0.1-...-win_amd64.whl
├─ FlashAttention/
│  └─ cp311-torch2.9.1-cu130-win/
│     └─ flash_attn-2.8.4-...-win_amd64.whl
├─ SageAttention/
│  └─ cp311-torch2.9.1-cu130-win/
│     └─ sageattention-2.2.0-...-win_amd64.whl
└─ SpargeAttn/
   └─ cp311-torch2.9.1-cu130-win/
      └─ spas_sage_attn-0.1.0-...-win_amd64.whl
```

## 安装

请使用 **ComfyUI 实际使用的 Python 解释器**执行安装，而不是系统中另一个 Python。先确认环境版本：

```powershell
python -c "import sys, torch; print(sys.version); print(torch.__version__); print(torch.version.cuda)"
```

确认输出与上述兼容环境一致后，安装所需 wheel：

```powershell
python -m pip install ".\Block-Sparse-Attention\cp311-torch2.9.1-cu130-win\block_sparse_attn-0.0.1-cp311-cp311-torch2.9.1-cu130-win_amd64.whl"

python -m pip install ".\SpargeAttn\cp311-torch2.9.1-cu130-win\spas_sage_attn-0.1.0-cp311-cp311-torch2.9.1-cu130-win_amd64.whl"

python -m pip install ".\SageAttention\cp311-torch2.9.1-cu130-win\sageattention-2.2.0-cp311-cp311-torch2.9.1-cu130-win_amd64.whl"

python -m pip install ".\FlashAttention\cp311-torch2.9.1-cu130-win\flash_attn-2.8.4-cp311-cp311-torch2.9.1-cu130-win_amd64.whl"
```

Block Sparse Attention 还声明了以下运行依赖：`torch`、`einops`、`packaging` 和 `ninja`。安装 wheel 时，pip 通常会自动处理缺失依赖；为了避免替换 ComfyUI 已配置好的 PyTorch，建议安装前检查 pip 给出的依赖变更信息。

安装后可以验证模块是否能够导入：

```powershell
python -c "import block_sparse_attn; print('block_sparse_attn: OK')"
python -c "import spas_sage_attn; print('spas_sage_attn: OK')"
python -c "import sageattention; print('sageattention: OK')"
python -c "import flash_attn; print('flash_attn: OK')"
```

## 使用提示

- 安装或升级前建议备份 ComfyUI 的 Python 环境。
- 不要让 pip 自动升级或降级现有的 PyTorch/CUDA 组件，除非明确知道环境兼容关系。
- “能够导入”只代表扩展已加载；仍应在目标工作流中实际运行一次，以验证显卡架构和 CUDA 内核兼容性。
- 这些包是底层 Python/CUDA 扩展，本身不是 ComfyUI 自定义节点。是否生效取决于对应节点或模型代码是否调用其 API。

## 上游项目

- [Block Sparse Attention](https://github.com/mit-han-lab/Block-Sparse-Attention)
- [SpargeAttention](https://github.com/thu-ml/SpargeAttn)
- [SageAttention](https://github.com/thu-ml/SageAttention)
- [FlashAttention](https://github.com/Dao-AILab/flash-attention)

各组件的源代码、许可证、接口说明及论文引用以对应上游项目为准。本项目仅整理特定 Windows/ComfyUI 环境所需的预编译产物。

## 许可证

本仓库的原创内容采用 [Apache License 2.0](https://huggingface.co/FengCoding/BlackwellWheels/blob/main/LICENSE) 许可。

仓库内随附的第三方 wheel 及其内容仍遵循各自的上游许可证。Apache-2.0 不替代或修改这些许可证；重新分发前请查阅包元数据及对应的上游项目。