MiniMax H3 接入 SageAttention 实测加速 <ComfyUI 启动 包含踩坑记录>

原凉是这样的丶
0 阅读13分钟

MiniMax H3 接入 SageAttention：CUDA 13.0 源码编译、实测加速

MiniMax H3 跑通以后，效果确实让人满意，但下一个念头也来得特别快：能不能再快一点？现场生成一段 5 秒、864×480 的视频，原生注意力单次耗时 113.89 秒。效果出来的那一刻很惊喜，可每次调提示词都要再等近两分钟，工作流一多，这个等待就很有存在感了。

于是我把 SageAttention 接了进来。同一类任务的现场单次耗时降到 64.58 秒，体感上不是“快了一点”，而是等待明显少了一截。当然，加速从来不是勾选一个选项就结束：CUDA Toolkit、RTX 4090 的 sm_89 内核、编译并发和 ComfyUI 启动参数，少对上一项都可能编译失败。

这篇文章就从这个真实需求出发：在 Ubuntu 24.04、RTX 4090 和 PyTorch 2.13.0+cu130 环境中源码编译 SageAttention 2.2.0，把它接入 MiniMax H3，再把启用验证、单次加速结果完整走一遍。

如果尚未完成模型、ComfyUI的下载 和 systemd 部署，请先阅读：MiniMax H3 量化版 Linux服务器部署实战 <ComfyUI启动 包含踩坑记录>MiniMax H3 量化版 - 掘金。

执行前请把命令中的 your-user 替换为服务器真实用户名。本文沿用第一篇的项目目录、虚拟环境和 comfyui.service。

代码块中以 # 开头的独立行是说明性注释，不参与执行，可以连同命令一起复制。为避免破坏多行命令，注释不会放在以 `` 结尾的续行中间。

一、SageAttention 加速了什么

标准注意力可以简化为：

 Attention(Q, K, V) = Softmax(QKᵀ / √d) V

SageAttention 2 会对 QKᵀ 等计算进行低比特量化和异常值平滑，并为不同 GPU 架构提供专门的 CUDA/Triton 内核。RTX 4090 属于 Ada Lovelace，计算能力为 8.9，源码构建时应明确指定：

 # 仅编译 RTX 4090 所需的 Ada sm_89 架构
 export TORCH_CUDA_ARCH_LIST=8.9

在这套环境中，ComfyUI 的自动入口会走 SageAttention 的 sm89 路径；出错堆栈中可以看到 sageattn_qk_int8_pv_fp8_cuda。它会使用 INT8 处理 QK，并在支持的 Ada 内核上使用 FP8 处理 PV。

这里说的“内核适配”是 CUDA kernel 针对 GPU 指令架构编译，不是把 nvidia-smi 里的 CUDA 数字直接填进架构变量：

项目本文取值含义
GPU 架构Ada LovelaceRTX 4090 所属架构
Compute Capability8.9PyTorch 构建变量使用的写法
CUDA binary targetsm_89nvcc 最终生成的目标架构
CUDA Toolkit13.0提供 nvcc 和头文件
PyTorch Runtimecu130与本次源码构建保持同一 CUDA 版本线

SageAttention 官方说明中，Ada 上的 FP8 路径要求 CUDA 12.4 或更高版本，CUDA 13.0 满足条件。当前源码的 SUPPORTED_ARCHS 已包含 8.9，因此 RTX 4090 不需要伪造或修改架构列表。TORCH_CUDA_ARCH_LIST=8.9 只让构建系统编译需要的架构，可以减少编译时间和产物体积；它不负责选择运行时使用哪张显卡。

需要强调两点：

  1. SageAttention 优化的是注意力部分，不会同比例缩短模型加载、VAE 解码和文件编码时间。
  2. 低精度注意力不是“无条件更快”。分辨率、序列形状、显存调度和内核兼容性都会影响最终结果。

二、先分清驱动、PyTorch Runtime 和 CUDA Toolkit

这是整个安装过程中最容易混淆的地方。

组件在本文中的作用如何确认
NVIDIA Driver操作系统驱动 GPUnvidia-smi
PyTorch CUDA Runtime运行 PyTorch/ComfyUI 的 CUDA 动态库python -c "import torch; print(torch.version.cuda)"
CUDA Toolkit提供 nvcc，用于编译 SageAttention CUDA 扩展nvcc --version

nvidia-smi 显示 CUDA Version: 13.0，表示当前驱动最高支持相应 CUDA 接口，并不表示 /usr/local/cuda-13.0 已经存在。

上一篇的 MiniMax H3 工作流只依赖 PyTorch wheel 自带的 Runtime，所以第一篇没有安装 Toolkit。源码编译 SageAttention 才需要系统中的 nvcc，并且 Toolkit 版本最好与 torch.version.cuda 一致。

Linux 内核、NVIDIA 驱动模块和 CUDA Toolkit 也不能混为一谈。Toolkit 不会替换当前正在运行的 Linux 内核；真正与 Linux 内核交互的是 NVIDIA 驱动模块。安装前可以用下面几条命令分别核对：

 # Linux 内核与 NVIDIA 驱动模块
 uname -r
 modinfo nvidia | grep -E '^(version|vermagic):'
 ​
 # 驱动可见状态与 PyTorch 自带 Runtime 版本
 nvidia-smi
 python -c 'import torch; print(torch.__version__, torch.version.cuda)'

只要 nvidia-smi 正常、驱动模块已加载，安装不带驱动的 cuda-toolkit-13-0 通常不会改变当前驱动；这也是后文先用 apt-get -s 检查安装计划的原因。

CUDA 13.0、13.1、13.2 和 13.3 相差多久

CUDA 13 系列更新很快，但“最新”不等于“最适合当前服务器的扩展环境”。NVIDIA 官方发布信息对应的时间如下：

CUDA 版本官方发布日期与上一版本间隔
13.02025-08-06—
13.12025-12-04120 天
13.22026-03-0995 天
13.32026-05-2678 天

CUDA 13.3 Release Notes 中的 Linux Toolkit/Driver 对照表为：

CUDA Toolkit对应版本的最低 Linux 驱动
13.0 GA / Update 1 / Update 2580.65.06 / 580.82.07 / 580.95.05
13.1 GA / Update 1590.44.01 / 590.48.01
13.2 GA / Update 1595.45.04 / 595.58.03
13.3 GA / Update 1610.43.02

现场驱动 580.126.09 高于 CUDA 13.0 Update 2 的 580.95.05，因此本文使用 Toolkit 13.0。它低于 13.1、13.2 和 13.3 的直接配套驱动要求，所以不能升级到新版本 13.3 。

CUDA 13.x 支持同一大版本内的 Minor Version Compatibility，驱动 >=580 在一定条件下可以运行较新的 13.x 应用，但新特性可能受限，包含 PTX 的程序也可能要求更高驱动。源码扩展还会同时受到 PyTorch wheel、编译器和项目自身版本检查影响。因此本文选择“驱动 580 + PyTorch cu130 + Toolkit 13.0 + SageAttention 2.2.0”这一条已经通过官方验证的版本线，而不是只追逐 Toolkit 版本号。PyTorch 官方已有 cu132 wheel，但这仍不等于当前驱动和 SageAttention 构建链已经完成 cu132/13.3 回归。

安装前的服务器的现场状态如下：SageAttention 尚未安装，nvcc 也不存在。 ①.png

三、在 Ubuntu 24.04 安装 CUDA Toolkit 13.0

先确认系统和架构：

 # 确认发行版和 CPU 架构，以选择正确的 NVIDIA 软件源
 . /etc/os-release
 echo "$ID $VERSION_ID"
 dpkg --print-architecture

本文输出：

 ubuntu 24.04
 amd64

②.png

如果直接执行下面命令得到 Unable to locate package cuda-toolkit-13-0：

 sudo apt-get install -y cuda-toolkit-13-0

问题通常不是 CUDA 13.0 不支持 Ubuntu 24.04，而是 NVIDIA 软件源尚未加入，或者安装 keyring 后漏掉了 apt-get update。

③.png

安装 NVIDIA 官方 keyring：

 cd /tmp
 ​
 # 下载 Ubuntu 24.04 amd64 对应的 NVIDIA 仓库 keyring
 wget \
   https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb \
   -O cuda-keyring_1.1-1_all.deb
 ​
 # 注册仓库密钥并刷新 apt 索引；两条命令都必须成功
 sudo dpkg -i cuda-keyring_1.1-1_all.deb
 sudo apt-get update

注意：sudo dpkg -i ... 和 sudo apt-get update 必须是两条实际执行成功的命令。只安装 keyring 而没有刷新 apt 索引，apt-cache 仍然找不到新包。

④.png

确认候选版本：

 # 确认候选版本已经出现
 apt-cache policy cuda-toolkit-13-0

⑤.png

安装 Toolkit：

# 安装 Toolkit，不使用可能连带安装驱动的 cuda 元包
sudo apt-get install -y cuda-toolkit-13-0

⑥.png

这里安装的是 cuda-toolkit-13-0，不是会连带选择驱动的 cuda 元包。安装完成后验证：

# 直接使用固定版本路径验证 nvcc 和安装目录
/usr/local/cuda-13.0/bin/nvcc --version
ls -ld /usr/local/cuda-13.0

实测 nvcc 为 CUDA compilation tools 13.0，目录 /usr/local/cuda-13.0 已创建。

⑦.png

四、为什么直接安装 SageAttention 2.2.0 会失败

在部分 PyPI 镜像或包索引中执行：

uv pip install --no-build-isolation "sageattention==2.2.0"

可能得到：

No solution found when resolving dependencies
Because there is no version of sageattention==2.2.0 ...

⑧.png

这只能说明当前索引没有暴露目标发行包，不代表官方源码不存在 2.2.0。SageAttention 官方仓库的 setup.py 明确声明版本为 2.2.0，因此本文改为从官方源码构建。SageAttention v2.2.0

五、使用保守并发编译 SageAttention 2.2.0

进入 ComfyUI 的同一个虚拟环境。必须安装到这个 .venv，否则 systemd 启动的 ComfyUI 无法导入 SageAttention。

cd /home/your-user/projects/comfyui-minimax-h3
source .venv/bin/activate

# 构建与验证过程只使用物理 GPU1
export CUDA_VISIBLE_DEVICES=1

# 让 PyTorch 扩展找到 CUDA 13.0 编译器和头文件
export CUDA_HOME=/usr/local/cuda-13.0
export PATH="$CUDA_HOME/bin:$PATH"
export TORCH_CUDA_ARCH_LIST=8.9

# 限制构建并发，降低 48GB 主存环境中的 OOM 风险
export MAX_JOBS=4
export EXT_PARALLEL=1
unset NVCC_APPEND_FLAGS

如果不想每次手工输入，可以把这些仅用于源码编译的变量保存为项目根目录的 sage-build.env：

cd /home/your-user/projects/comfyui-minimax-h3

cat > sage-build.env <<'EOF'
# 运行 GPU 与 CUDA 13.0 Toolkit
export CUDA_VISIBLE_DEVICES=1
export CUDA_HOME=/usr/local/cuda-13.0
export PATH="$CUDA_HOME/bin:$PATH"

# RTX 4090 对应 sm_89
export TORCH_CUDA_ARCH_LIST=8.9

# 保守编译并发，不追加额外 nvcc flags
export MAX_JOBS=4
export EXT_PARALLEL=1
unset NVCC_APPEND_FLAGS
EOF

# 限制配置文件权限，然后加载到当前 Shell
chmod 600 sage-build.env
source sage-build.env

sage-build.env 与运行 ComfyUI 的 .env 分开管理：前者控制一次源码构建，后者控制服务监听地址、端口和运行 GPU。编译完成后，MAX_JOBS、EXT_PARALLEL 等变量不需要写入 systemd 服务。

这些变量控制的是编译期资源，不会决定视频生成时使用多少 GPU：

变量作用本文取值
CUDA_VISIBLE_DEVICES限制构建/验证进程可见的 GPU1
TORCH_CUDA_ARCH_LIST只编译 RTX 4090 所需的 sm_898.9
MAX_JOBS底层 C++/CUDA 编译任务并发数4
EXT_PARALLEL同时构建的扩展模块数1
NVCC_APPEND_FLAGS额外附加给 nvcc 的参数不设置

MAX_JOBS 控制 Ninja/C++/CUDA 构建任务数，EXT_PARALLEL 控制同时构建多少个扩展模块，而 setup.py 中的 --threads=8 是单个 nvcc 进程使用的主机编译线程。三者叠加后会放大 CPU 与系统内存压力，但不会占用同等倍数的生成显存，也不会让安装完成后的视频推理自动变快。

官方示例中的 MAX_JOBS=32、EXT_PARALLEL=4 和 nvcc --threads=8 偏向高核心数、大内存构建机，并不是每台服务器的“默认正确值”。本文服务器已有 48GB 内存，仍采用 4 × 1 的保守配置，避免多个扩展和 nvcc 子任务同时争抢主存。如果构建仍因 OOM 被杀，先把 MAX_JOBS 降到 2；确认仍是单个 nvcc 进程过重后，再考虑修改 --threads。

克隆官方仓库并记录 commit：

# 将第三方源码集中放入项目内，便于后续追踪版本
mkdir -p third_party

git clone \
  --depth 1 \
  https://github.com/thu-ml/SageAttention.git \
  third_party/SageAttention

# 记录实际 commit，并核对源码声明的包版本
git -C third_party/SageAttention rev-parse HEAD
grep -n "version=" third_party/SageAttention/setup.py

⑨.png

是否需要修改 setup.py 中的 --threads=8

不需要把它当作默认步骤。--threads=8 是单个 nvcc 调用的编译线程设置，不是运行时推理线程，也不会让生成任务直接占用八倍显存。

只有在编译过程中出现系统内存不足、Killed、cc1plus 被终止时，才考虑把它降到 2：

cd /home/your-user/projects/comfyui-minimax-h3/third_party/SageAttention

# 备份 setup.py 后，只降低单个 nvcc 进程的线程数
cp setup.py setup.py.bak
sed -i 's/"--threads=8"/"--threads=2"/' setup.py

# 确认修改已经生效
grep -n -- '--threads' setup.py

只修改线程参数，不要删除编译架构校验或随意修改 SUPPORTED_ARCHS。当前官方源码已经支持 8.9。

⑩.png

从本地源码安装：

cd /home/your-user/projects/comfyui-minimax-h3
source .venv/bin/activate

# 使用当前虚拟环境已有的 PyTorch，而不是隔离构建环境
uv pip install \
  --no-build-isolation \
  ./third_party/SageAttention

完成后验证包版本和导入：

# 验证 Python 可以从当前虚拟环境导入 SageAttention
python - <<'PY'
import sageattention
from sageattention import sageattn

print("SageAttention path:", sageattention.__file__)
print("sageattn import: OK")
PY

# 显示安装版本、位置和包元数据
uv pip show sageattention

实测编译约 5 分钟，安装结果为 sageattention==2.2.0。

11.png

六、在 ComfyUI 中启用 SageAttention

ComfyUI 官方给出了两种接入方式：

方式适用场景
启动参数 --use-sage-attention整个 ComfyUI 实例统一使用，服务端部署最直接
KJNodes 的 SageAttention Patch 节点只给指定工作流或模型打补丁

本文使用全局启动参数，不要求安装 KJNodes。在第一篇创建的 start-comfyui-h3.sh 中，把最后一段改成：

exec "$PROJECT_DIR/.venv/bin/python" main.py \
  --listen "$LISTEN_ADDRESS" \
  --port "$LISTEN_PORT" \
  --extra-model-paths-config "$APP_DIR/extra_model_paths.yaml" \
  --input-directory /data/comfyui-h3/input \
  --output-directory /data/comfyui-h3/output \
  --temp-directory /data/comfyui-h3/temp \
  --use-sage-attention

这里只改了启动脚本，没有修改 /etc/systemd/system/comfyui.service，因此不需要 daemon-reload，重启服务即可：

# 重启服务，让启动脚本中新加入的参数生效
sudo systemctl restart comfyui.service

# 从最近日志中验证实际选择了 SageAttention
journalctl -u comfyui.service \
  -n 200 \
  --no-pager \
  | grep -F "Using sage attention"

只有 systemd unit 文件发生变化时，才需要先执行：

sudo systemctl daemon-reload

启动日志中出现下面这一行，才说明 ComfyUI 已真正选择 SageAttention：

[INFO] Using sage attention

12.png

MiniMax H3 的部分层如果不是 FP16/BF16，可能会看到回退到 PyTorch attention 的提示。官方文档说明这是预期行为：不兼容的层回退，其他兼容层仍可使用 SageAttention。

七、现场单次结果：113.89 秒降到 64.58 秒

现场使用同一段提示词、5 秒时长和 MiniMax H3 FL2VA INT8 工作流，得到以下单次结果：

注意力实现单次任务耗时
ComfyUI 原生注意力113.89 秒
SageAttention64.58 秒

按这两次记录计算：

耗时下降 = (113.89 - 64.58) / 113.89 ≈ 43.3%
速度倍率 = 113.89 / 64.58 ≈ 1.76×

image.png

sageattention 加速器配置后 同样的条件下 生成时长为65s.png

八、回滚方案

SageAttention 是可选依赖。发生兼容性问题时，不需要删除 MiniMax H3 权重或重装 ComfyUI：

  1. 从启动脚本移除 --use-sage-attention。
  2. 需要稳定性优先时加入 --use-pytorch-cross-attention。
  3. 执行 sudo systemctl restart comfyui.service。
  4. 从日志确认不再出现 Using sage attention。

系统 CUDA Toolkit 也只用于编译扩展，不决定基础 ComfyUI 能否运行。即使暂时停用 SageAttention，已经安装的 PyTorch cu130 和 MiniMax H3 权重仍可继续使用。

九、结语

SageAttention 的安装难点不在一条 pip install，而在于确保 PyTorch Runtime、系统 CUDA Toolkit、目标 GPU 架构和编译并发彼此匹配。启用后的确可以观察到明显加速，但高分辨率非法内存访问也说明，性能优化必须保留随时回退到 PyTorch attention 的能力。

对于生产环境，最稳妥的顺序仍然是：先跑通原生工作流，保存同条件基线，再安装加速组件，最后用固定 seed 和多轮中位数验证收益。

参考资料

avatar
文章
阅读
粉丝