ComfyUI 的五个注意力实现参数怎么选，以及 xformers 在里面扮演什么角色

注意力实现这一组参数，是 ComfyUI 命令行里最容易被人乱抄的一块。论坛帖子里常见的写法是把 --use-pytorch-cross-attention 和 --use-sage-attention 一起贴上去，再顺手补一个 --use-split-cross-attention，仿佛加得越多越保险。实际上这五个参数在 comfy/cli_args.py 里属于同一个互斥组，互斥的意思就是命令行解析层面只准出现一个，多给会直接被 argparse 拒掉。

更麻烦的是，这五个里有两个的 help 文本自带一句附加条件，而这句条件跟一个根本不在这个互斥组里的东西有关：xformers。下面按 v0.31.0（2026-08-08）时点的 comfy/cli_args.py 与 comfy/model_management.py 口径，把这层关系拆开。

先看这五行原始 help

参数	help 原意
--use-split-cross-attention	使用 split cross attention 实现；Ignored when xformers is used
--use-quad-cross-attention	使用 sub-quadratic 的 cross attention 实现；Ignored when xformers is used
--use-pytorch-cross-attention	使用 pytorch 2.0 的 cross attention 实现
--use-sage-attention	使用 sage attention
--use-flash-attention	使用 flash attention

这张表要读的不是「哪个快」——官方 help 里对这五者一个字的性能对比都没给，我们也没有任何本机数据，所以谁快谁慢这件事本文不比。这张表真正的信息量在最右列的分布：只有前两行带了附加条件，后三行没有。

那句「Ignored when xformers is used」到底说了什么

它说的是一件很具体、也很容易被读反的事：当环境里的 xformers 处于被使用的状态时，你在命令行上写的 --use-split-cross-attention 或 --use-quad-cross-attention 不生效。参数不会报错，命令能正常起来，你甚至会觉得它已经在按 split 跑了——但 help 明说这时候它被忽略。

这就解释了一类很典型的困惑：有人为了绕开某个问题特意换成 split cross attention，换完现象一点没变，于是怀疑是自己参数拼错了，或者怀疑 ComfyUI 没读到命令行。这两条怀疑方向都会白费时间，真正的判断依据只有一条——先确认 xformers 在不在场。

确认动作不需要猜。comfy/model_management.py（v0.31.0）在启动时会打印 xformers version: {版本} 这一行日志。启动日志里有这行，说明 ComfyUI 检测到了 xformers；没有这行，那么「被忽略」这个前提就不成立，你的 split/quad 没生效是别的原因，得换方向查。这条日志和 Total VRAM {:0.0f} MB, total RAM {:0.0f} MB、Set vram state to: {名字} 是同一批启动期输出，都在最前面几屏里，翻上去看一眼就行。

顺带说一句读法上的坑：后三个参数的 help 里没写这句附加条件，只能理解成「官方没在 help 里给出这个限定」，不能反过来推成「它们一定不受 xformers 影响」。help 没写的行为就是没依据，别替源码补充语义。这是这一组参数最容易越界的地方。

--disable-xformers 不在互斥组里，它站在另一层

comfy/cli_args.py（v0.31.0）里还有一个独立参数 --disable-xformers。它不属于上面那个五选一的互斥组，是单独一条。

理解它的位置很关键：上面那五个是「选哪个实现」，而 --disable-xformers 是「要不要让 xformers 参与进来」。前者是选择题，后者是开关题，两者不在一个维度上。也正因为如此，一条命令里同时出现 --disable-xformers 和某个 --use-*-cross-attention，在参数解析层面并不冲突。

但接下来这一步我必须刹住车：关掉 xformers 之后，实际会落到哪个注意力实现上，--help 文本里没有写。 卡在这里的读者常见的做法是根据经验脑补一条「回退链」，然后当成结论传出去。本文不做这个脑补。能确定的只有两句：xformers 在场时 split 与 quad 的选择会被忽略；存在一个独立开关可以让 xformers 不参与。至于关掉之后的具体落点，以 python main.py --help 的实际输出和你自己启动日志里打印的内容为准。

xformers 那条黑图告警，是这块唯一一条明确的因果线索

comfy/model_management.py（v0.31.0）里有一条针对 xformers 的告警，原文是：

WARNING: This version of xformers has a major bug where you will get black images when generating high resolution images.

后面跟着一句处置提示：Please downgrade or upgrade xformers to a different version.

这条告警的价值在于，它是这一块里少见的、官方把「现象」和「原因」直接绑死的地方：检测到问题版本 → 高分辨率下会出黑图 → 处置是把 xformers 降级或升级到另一个版本。所以判断路径很短——你遇到高分辨率黑图，第一件事是回头翻启动日志有没有这条 WARNING。有，方向就明确了，处置照官方那句做；没有这条，就别把黑图往 xformers 身上赖。

需要跟另一条黑图线索分清楚：comfy/cli_args.py 里 --fp16-vae 的 help 自带 might cause black images 的提示，那是精度组的事，属于 VAE 那条链路。两条线索指向不同的地方，日志里那条 WARNING 是区分它们最省事的判据。除这两处之外，官方 help 与源码告警里再没给别的黑图归因，卡外的原因本文不编。

两个 upcast 开关：读 help 的措辞比读功能更有用

跟注意力相关的还有一个互斥组，只有两个成员：

参数	help 原意
--force-upcast-attention	强制开启 attention upcasting，如果它修好了黑图，请上报
--dont-upcast-attention	关闭所有 upcasting，除调试之外应该没有必要

这两句 help 的写法很有信息量，值得逐句拆。

--force-upcast-attention 后面那句「如果它修好了黑图请上报」，语气上不是在推荐用法，而是在收集案例。它隐含的态度是：正常情况下不该需要你手动强开这个东西，如果强开之后问题消失了，那说明自动判定那一层可能有问题，官方想知道。所以这个开关更适合当成排查手段用——试一下，看现象变不变，然后把结果反馈回去，而不是当成一条长期挂在启动脚本里的「优化参数」。

--dont-upcast-attention 那句「除调试外应该没必要」更直白，基本等于官方在劝你别动。它存在是为了调试场景，不是为了提速或者省显存——help 没说它能省什么，我们也就不说。

判断依据落到实操上就是一句话：这两个开关都不属于日常配置，只在你正在排查某个具体现象、并且愿意做「加上去 / 去掉」对照的时候才碰。 一次只改一个，改完看现象是否变化，这是这类调试开关唯一有效的用法。

版本漂移：注意力后端在 v0.30.0 和 v0.31.0 连着动了两次

如果你打算把某篇教程里的注意力参数结论直接搬到自己机器上，先看一眼这两条 release notes 条目：

版本	日期	条目
v0.30.0	2026-08-03	Linux 上 flash attention 不可用时回退到 cudnn attention
v0.31.0	2026-08-08	恢复 SDPA 非 cudnn 的小注意力旁路（PR #15296）

两版之间只隔了五天，注意力后端相关的行为就被改了两次。这两条 release notes 都只是一句话的条目，没有给实现细节，我也不会替它们扩写——条目说明「改了这个」，没说明改成什么样、在什么条件下触发、影响哪些模型。任何在这两条之上加工出来的「原理解析」，都不是从官方口径来的。

但即便只有这一句话，对读者也有两个可以直接落地的结论：

第一，跨版本抄结论必须带版本号。 一篇没写版本号的注意力调参帖，很可能写在 v0.30.0 之前或之间，而你现在装的是 v0.31.0。这一块正好是近期改动最密集的区域之一，「以前这么配就好了」在这里的可信度比其它参数组更低。

第二，升级之后如果注意力相关的行为变了，先把版本区间对上，再去动参数。 顺序反了就会变成：一边改参数一边升级，最后分不清是哪一边造成的变化。ComfyUI 按 README 的 Release Process 大约每两周发一个 major stable 版本，而 stable tag 之外的 commit README 自己就写明「可能非常不稳定，会弄坏很多自定义节点」——所以如果你跟的是 master 而不是 tag，行为漂移的频率还要更高，遇到问题时这一条要先摆到台面上。

一条可执行的顺序

把上面几段合并成实际操作顺序，大致是这样：

1. 什么都不加先起一次，把启动日志前几屏留着。重点看有没有 xformers version: 这一行，以及有没有那条 xformers 黑图 WARNING。
2. 有 WARNING 且现象是高分辨率黑图 → 按 help 的提示处理 xformers 版本，别去动五个 --use-* 参数。
3. 要换注意力实现 → 从 --use-split-cross-attention、--use-quad-cross-attention、--use-pytorch-cross-attention、--use-sage-attention、--use-flash-attention 里只挑一个加上（它们互斥）；如果挑的是前两个，先确认第 1 步里 xformers 不在场，否则按 help 它会被忽略。
4. 两个 upcast 开关只在排查期使用，--force-upcast-attention 若真的改善了黑图，按 help 的意思去官方仓库上报。
5. 任何结论都记上你当时的版本号，v0.30.0 与 v0.31.0 在这一块连着改过两次，不带版本号的经验很快就会失效。

以上组合方式是按官方参数语义整理的使用顺序，未逐项实测，以官方文档与 python main.py --help 的实际输出为准。

延伸阅读

• ComfyUI 模型加载慢：能调的几个开关
• 读懂 DynamicVRAM：它什么时候会被悄悄关掉
• ComfyUI 五种缓存模式该选哪个：从 --cache-ram 的默认阈值倒推启动参数

---

本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、 release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0； 文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。 参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。