SpargeAttn

让视频生成模型推理提速数倍，无需重新训练。

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署视频生成 🍴 复刻 108 🐛 待处理 67 👀 关注 10

GitHub ↗

GitHub 星标 ★ 1267

维护状态低维护

是否开源开源

定价模式 🏷️完全免费开源项目，Apache-2.0许可证，完全免费，可自行部署使用。

项目预览

项目数据

分类视频生成

开发团队thu-ml

GitHubhttps://github.com/thu-ml/SpargeAttn

定价模式🏷️完全免费

价格说明开源项目，Apache-2.0许可证，完全免费，可自行部署使用。

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议Apache-2.0

主要语言Cuda

技术栈/模型ai-infra,attention,inference-acceleration,llm,mlsys,quantization,sageattention,sparse-attention,video-generation,vision-transformer,vit

GitHub 星标★ 1267

上线时间2025-02-25 00:00:00

代码更新2026-02-25

仓库体积69.0 MB

本站数据更新2026-11-07

维护状态低维护

收录时间2026-08-09

浏览次数5

项目介绍

SpargeAttn 是一个训练无关的稀疏注意力加速库，旨在加速任意模型（尤其是视频生成模型）的推理过程。它通过利用注意力分数中的稀疏性，动态跳过不重要的计算，从而在不降低生成质量的前提下显著提升速度。核心能力包括：支持多种模型架构（如 DiT、LLM 等）的即插即用集成，提供量化与稀疏化结合的内存优化，以及基于 CUDA 的高效内核实现。它解决了视频生成等长序列任务中注意力计算开销大、显存占用高的问题，使实时或近实时的高清视频生成成为可能。该库由 ICML 2025 论文提出，与 SageAttention 等技术协同，为 AI 推理优化提供了新的工具。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 1267

技术标签

ai-infra attention llm mlsys quantization

使用教程

ℹ 本教程由 AI 依据该项目 README 整理，个别步骤可能需要按你的环境微调。

难度：进阶约 10 分钟部署方式：库/依赖 7 步

环境要求

Python 环境与 PyTorch（示例代码使用 torch 张量）
支持 CUDA 的 GPU（库为 CUDA 内核实现）
先安装 ninja 以并行编译
需在项目源码根目录执行安装（依赖 setup.py）

安装与启动步骤

1安装编译依赖

ninja 用于并行编译 CUDA 扩展，必须先装，否则编译会变慢或失败。
```
pip install ninja
```
2源码安装本包

在 SpargeAttn 源码根目录执行，两种方式二选一，均可完成编译安装。
```
python setup.py install
```
3（备选）可编辑安装

需要修改源码或反复调试时，用可编辑模式安装替代上一步。
```
pip install -e .
```
4验证导入

能成功导入核心 API 即说明编译与安装通过。
```
python -c "from spas_sage_attn import spas_sage2_attn_meansim_topk_cuda"
```

5替换注意力调用

把原来的 scaled_dot_product_attention 换成 spas_sage2_attn_meansim_topk_cuda，参数保持一致。

from spas_sage_attn import spas_sage2_attn_meansim_topk_cuda
attn_output = spas_sage2_attn_meansim_topk_cuda(q, k, v, topk=0.5, is_causal=False)

6调节稀疏度

按需调整 topk：数值越高越精确，越低越稀疏、速度越快。
7（可选）自定义块稀疏

需要按注意力头指定稀疏掩码时，改用 block_sparse_sage2_attn_cuda 并传入 mask_id。
```
from spas_sage_attn import block_sparse_sage2_attn_cuda
attn_output = block_sparse_sage2_attn_cuda(q, k, v, mask_id=None)
```

关键配置

配置项	必填	说明	示例
`topk`	否	控制注意力精度与稀疏度平衡，越高越准、越低越快	`0.5`
`is_causal`	否	是否为因果注意力，可设为 True 或 False	`False`
`mask_id`	否	逐头块稀疏掩码，仅 block_sparse 接口使用，由 0/1 组成	`None`

如何确认成功

执行导入命令无报错；将模型中的 SDPA 替换为该 API 后推理输出正常且速度提升。

常见问题

Q：安装时编译很慢或卡住怎么办？

A：确认已先执行 pip install ninja，ninja 用于并行编译 CUDA 扩展，可显著加快编译。

Q：topk 应该设多少？

A：topk 越高注意力越准确、稀疏度越低；越低则越稀疏、加速越明显。可按需在 0.5 附近调节。

Q：需要重新训练模型吗？

A：不需要。SpargeAttn 是训练无关的稀疏注意力，可直接即插即用替换原有注意力调用。

Q：mask_id 的形状要求是什么？

A：形状为 (batch_size, num_heads, ⌈seq_len/128⌉, ⌈seq_len/64⌉)，取值 0 或 1，块大小为 128×64。

Q：能加速哪些模型？

A：可加速语言、图像与视频模型，只需将 scaled_dot_product_attention 替换为提供的 API。

注意事项

本库为训练无关方案，替换注意力调用即可，无需改动模型权重。
核心内核基于 CUDA，需在具备 GPU 的环境中编译与运行。
安装命令须在项目源码根目录执行，否则找不到 setup.py。
两种接口二选一：追求易用选 spas_sage2_attn_meansim_topk_cuda，需要自定义稀疏结构选 block_sparse_sage2_attn_cuda。