> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.
# BlockSparseAttention - ComfyUI Built-in Node Documentation
> Block Sparse Attention 节点会修改模型，使其注意力层仅关注输入中最相关的部分，而不是一次性处理所有内容，从而减少长序列所需的计算量。
**Block Sparse Attention** 节点会修改模型，使其注意力层仅关注输入中最相关的部分，而不是一次性处理所有内容，从而减少长序列所需的计算量。序列越长，节省越多，因为短序列通常使用普通（稠密）注意力更快。
## 输入
### 通用输入
| 参数 | 描述 | 数据类型 | 必需 | 范围 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -- | ---------------------------------------------------- |
| `model` | 要修补的模型。 | MODEL | 是 | N/A |
| `selection` | 用于为完整 token 级注意力选择关键块的方法（显示为 `method`）。
`sol-attn`：稀疏在线注意力（Sparsifying Online Attention）为每个注意力头和查询块使用免训练的自适应阈值。
`sla`：稀疏线性注意力（Sparse-Linear Attention）保留固定百分比的最高分关键块；仅与为此模式训练的模型权重一起使用。
`vsa`：视频稀疏注意力（Video Sparse Attention，FastVideo）使用 3D 视频立方体分块和学习到的粗注意力分支；需要 FastH3 模型权重。 | DYNAMIC\_COMBO | 是 | `"sol-attn"`
`"sla"`
`"vsa"` |
| `start_percent` | 稀疏注意力开始的百分比位置。在此点之前，注意力保持稠密。默认值：0.2。 | FLOAT | 否 | 最小：0.0，最大：1.0，步长：0.01 |
| `end_percent` | 稀疏注意力结束的百分比位置。在此点之后，注意力恢复为稠密。默认值：1.0。 | FLOAT | 否 | 最小：0.0，最大：1.0，步长：0.01 |
| `dense_blocks` | 始终以稠密方式运行的 Transformer 块，例如 '0, 1, 47-49'。默认值：""（空）。高级输入。 | STRING | 否 | 默认值："" |
| `min_tokens` | 短于此长度的序列保持稠密。默认值：12288。高级输入。 | INT | 否 | 最小：0，最大：1048576，步长：512 |
| `extra_tokens` | 每个查询块在其选定块之外额外关注的高分 token 数。值越接近稠密，注意力时间越长；推荐 256，0 表示禁用。对 VSA 忽略。默认值：256。高级输入。 | INT | 否 | 最小：0，最大：256，步长：64 |
| `sink_conditioning` | 仅适用于 MiniMax-H3。`exact_kv`：每个查询精确关注打包的文本/音频/参考行（约 3% 开销）。`exact_kv_and_rows`：额外将目标音频查询行以稠密方式运行（保持生成的音频完整）。`off` 禁用此行为。默认值："exact\_kv\_and\_rows"。高级输入。 | COMBO | 否 | `"exact_kv"`
`"exact_kv_and_rows"`
`"off"` |
| `verbose` | 记录每个注意力形状是使用了稀疏注意力，还是为何保持稠密。默认值：False。高级输入。 | BOOLEAN | 否 | 默认值：False |
### sol-attn 输入
| 参数 | 描述 | 数据类型 | 必需 | 范围 |
| ----- | ------------------------------------------------------------------ | ----- | -- | --------------------- |
| `tau` | 分数分布标准差中的阈值。值越高越稀疏：1.0 保留约 16% 的关键块精确，1.5 约 7%，2.0 约 2.7%。默认值：1.3。 | FLOAT | 否 | 最小：0.0，最大：4.0，步长：0.05 |
### sla 输入
| 参数 | 描述 | 数据类型 | 必需 | 范围 |
| -------------- | ---------------------------------------------------------------------------------- | ----- | -- | --------------------- |
| `keep_percent` | 每个查询块精确保留的关键块百分比（sink 和对角线额外保留）。SLA 风格 LoRA 的蒸馏选择依据；如果没有此类 LoRA，值越高越接近稠密。默认值：10.0。 | FLOAT | 否 | 最小：0.5，最大：95.0，步长：0.5 |
### vsa 输入
| 参数 | 描述 | 数据类型 | 必需 | 范围 |
| -------------- | ---------------------------------------------------------------------------------------- | ----- | -- | --------------------- |
| `keep_percent` | 每个查询立方体保留的视频立方体百分比；FastH3-VSA 检查点在 10 处训练。当存在时，使用模型的 `to_gate_compress` 层作为粗分支。默认值：10.0。 | FLOAT | 否 | 最小：0.5，最大：95.0，步长：0.5 |
**注意：** 界面中仅显示属于当前所选方法的参数。
## 输出
| 输出名称 | 描述 | 数据类型 |
| ------- | ------------- | ----- |
| `model` | 已应用块稀疏注意力的模型。 | MODEL |
## 约束与限制
* 短于 `min_tokens` 的序列、`dense_blocks` 中列出的块，以及采样步长在 `start_percent` 到 `end_percent` 窗口之外时，会回退到由 Model Attention Backend 节点选择的稠密模型注意力后端。
* 选择 `vsa` 方法时，`extra_tokens` 会被忽略。由于 VSA 权重是针对其稀疏模式训练的，因此会记录一条消息。
* `vsa` 方法需要 MiniMax-H3 模型；任何其他模型都会引发错误。如果模型缺少 `to_gate_compress` 层，精细阶段将在没有粗分支的情况下运行，并记录一条警告。
* 对于不报告块索引的模型，`dense_blocks` 会被忽略；当启用 `verbose` 时，日志中会注明这一点。
* `sink_conditioning` 仅适用于报告与当前序列长度匹配的布局的 MiniMax-H3 模型。
> 本文档由 AI 生成。如果您发现任何错误或有改进建议，欢迎贡献！ [在 GitHub 上编辑](https://github.com/Comfy-Org/embedded-docs/blob/main/comfyui_embedded_docs/docs/BlockSparseAttention/zh.md)
***
**Source fingerprint (SHA-256):** `0c34876b49a04db0ab265526e2bb5f784e150591aab631713ad2ab420a3327c4`