注意力后端与 offload 参数对显存的影响：xformers / SageAttention / flash-attention / async-offload / pinned memory

--use-split-cross-attention   Use the split cross attention optimization. Ignored when xformers is used.
--use-quad-cross-attention    Use the sub-quadratic cross attention optimization . Ignored when xformers is used.
--use-pytorch-cross-attention Use the new pytorch 2.0 cross attention function.
--use-flash-attention         Use FlashAttention.
--async-offload               Use async weight offloading. An optional argument controls the amount of offload streams. Default is 2. Enabled by default on Nvidia.
--disable-pinned-memory       Disable pinned memory use.

现象与触发场景

常见触发场景：

• AMD/ROCm 用户（源码中 pytorch attention 在 AMD 上默认关闭，注释写明 'enabling pytorch attention on AMD currently causes crash when doing high res'）
• 显存紧张时想用 split/quad attention 换显存
• 内存小于显存的机器启用 pinned memory 后系统变卡

根因

• 不同注意力实现的内存复杂度不同：split / sub-quadratic 用时间换显存，pytorch SDPA 与 flash-attention 更依赖硬件特性。
• xformers 优先级很高，启用后会让 --use-split-cross-attention / --use-quad-cross-attention 直接被忽略（help 原文 'Ignored when xformers is used'）。
• 异步权重卸载（async offload）在 NVIDIA 上默认开启，会额外使用显存做流式缓冲，--disable-async-offload 可关掉；pinned memory 会锁定一部分系统内存，内存小的机器上可能适得其反。

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 确定当前实际使用的注意力后端，再决定是否覆盖
   启动日志会打印注意力后端（例如 'Using pytorch attention'、'Using split attention in VAE'）。只有在默认后端不合适时才显式指定；显式指定前先确认没有装 xformers，否则 split/quad 参数会被忽略。
   # 先看启动日志中的 attention 相关行
   python main.py --use-pytorch-cross-attention
   python main.py --use-split-cross-attention
   python main.py --use-flash-attention
2. 显存不足时优先试 split attention，而不是一味降分辨率
   --use-split-cross-attention 的分块注意力在显存紧张时能显著降低峰值；官方 issue #9547 中 AMD 用户实测 --use-flash-attention --bf16-vae 是当时可用的组合，另一个用户给出 --use-split-cross-attention --disable-smart-memory --cache-none。参数效果与平台强相关，需要自己对比。
   python main.py --use-split-cross-attention --disable-smart-memory
   python main.py --use-flash-attention --bf16-vae
3. 内存吃紧时关掉 pinned memory，必要时调整异步卸载流数量
   pinned memory 会锁定系统内存不可换出，小内存机器上会让整体更卡甚至触发系统内存不足；用 --disable-pinned-memory 关闭。异步权重卸载的流数量可用 --async-offload N 减少缓冲占用，或用 --disable-async-offload 完全关闭（代价是变慢）。
   python main.py --disable-pinned-memory
   python main.py --async-offload 1
   python main.py --disable-async-offload

验证是否修好

补充说明

SageAttention 属于第三方安装包，需自行编译/安装且对显卡架构有要求，其与 ComfyUI 的兼容性随版本变化较大，本条目未给出具体安装命令以避免版本错配。[未核实] SageAttention 在当前版本的最优参数组合未核实。

来源

1. [35] （官方文档）　ComfyUI/comfy/cli_args.py（参数与 help 原文）　https://github.com/Comfy-Org/ComfyUI/blob/master/comfy/cli_args.py
2. [41] （官方 issue）　VAE decoding on AMD works first time only ... · Issue #9547　https://github.com/Comfy-Org/ComfyUI/issues/9547
3. [58] （官方文档）　Performance Optimization - ComfyUI　https://mintlify.wiki/Comfy-Org/ComfyUI/guides/performance-optimization
4. [59] （官方 issue）　Fix/tweak pinned memory accounting (PR #13221)　https://github.com/Comfy-Org/ComfyUI/pull/13221

这条报错要用到的东西

按本条报错所属的类别（显存与内存不足（OOM））列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库