Matriz de versões da pilha de aceleração do ComfyUI

TL;DR

• xformers no Windows: instale via wheels do PyPI para PyTorch ≥2.10.0 com pip install -U xformers --index-url https://download.pytorch.org/whl/cu128 para CUDA 12.8, ou cu126 para CUDA 12.6. A alegação de que o xformers precisa do PyTorch 2.5.1 está desatualizada; os wheels atuais exigem 2.10.0.
• Triton no Windows: use o fork woct0rdho/triton-windows, pip install triton-windows==3.3.1.post19, emparelhado com PyTorch 2.9+ e CUDA 12.8. O toolchain MSVC v143 deve estar no PATH do sistema.
• SageAttention vs. FlashAttention: SageAttention exige torch≥2.3.0 e triton≥3.0.0; FlashAttention 2 exige torch≥2.2+ e CUDA≥12.0. Ambos podem coexistir com xformers no mesmo ambiente, mas a ordem de instalação importa — xformers primeiro se quiser wheels, depois SageAttention, por último FlashAttention compilado do código-fonte.

Para guias de configuração relacionados, veja ComfyUI no Windows do zero, PyTorch nightly vs stable e Matriz de compatibilidade NVIDIA driver CUDA.

Matriz de versões da pilha de aceleração do ComfyUI

O problema central é que cada biblioteca na pilha de aceleração do ComfyUI — Triton, SageAttention, FlashAttention, xformers — traz seus próprios wheels binários ou requisitos de build que prendem a versões específicas de PyTorch e CUDA. Desalinhar essas versões cria falhas silenciosas ou erros de compilação que podem consumir uma tarde inteira.

Qual build CUDA do PyTorch você realmente precisa?

Biblioteca | Min PyTorch | Versão CUDA | Wheels Windows | Comando de instalação | Fonte

|---------|-------------|--------------|----------------|---------------------|------

xformers stable (0.0.35) | 2.10.0 | 11.8, 12.6, 12.8, 13.0 | Sim (PyPI) | pip install -U xformers --index-url https://download.pytorch.org/whl/cu128 | xformers README xformers 0.0.31 | 2.7.1 | 11.8, 12.6, 12.8 | Sim (PyPI) | pip install xformers==0.0.31 | xformers CHANGELOG Triton Windows | 2.9+ | 12.8 recomendado | Sim (fork) | pip install triton-windows==3.3.1.post19 | Artigo 17252, Triton Windows releases SageAttention 2.2.0 | 2.3.0 | ≥12.0 (≥12.8 para Blackwell/SageAttention2++) | Apenas código-fonte | pip install sageattention==2.2.0 --no-build-isolation | SageAttention README FlashAttention 2 | 2.2+ | ≥12.0 | Apenas compilação; correções manuais de template necessárias no Windows | Veja seção de erros abaixo | FlashAttention README, Issue #595 PyTorch stable atual | — | 11.8, 12.6, 12.8 | Sim | pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 | pytorch.org/get-started [Fonte: verificada contra documentação primária de cada projeto para as linhas acima]

Como ler a matriz

O canal stable do PyTorch (2.7.0 na data desta escrita) fornece wheels para CUDA 11.8, 12.6 e 12.8 ^[1]. O canal nightly adiciona builds CUDA 12.8 para PyTorch 2.9 ^[2]. O xformers atualmente constrói wheels apenas contra PyTorch ≥2.10.0, então se você está no PyTorch 2.7 stable deve compilar do código-fonte ou usar um release mais antigo do xformers ^[3]. O SageAttention suporta um floor mais amplo de PyTorch (≥2.3.0) e é a opção mais tolerante para instalações antigas ^[4].

O que cada biblioteca realmente faz no ComfyUI

O que o Triton faz no pipeline de atenção?

O Triton fornece kernels de GPU escritos em uma DSL similar a Python que compilam para PTX personalizado. No ComfyUI, o Triton impulsiona o backend Triton para SageAttention (sageattn_qk_int8_pv_fp16_triton). No Windows, o Triton requer o fork woct0rdho/triton-windows porque o projeto upstream não publica wheels Windows para a maioria das versões. O fork entrega wheels pré-construídos como triton-windows==3.3.1.post19 ^[5].

O que o SageAttention substitui?

O SageAttention é um drop-in plug-and-play para torch.nn.functional.scaled_dot_product_attention (a atenção built-in do PyTorch). Ele quantiza QKᵀ para INT8 e acumula PV em INT8 ou FP8, obtendo speedups em GPUs Ampere (RTX 30xx), Ada (RTX 40xx) e Hopper (H100) sem perda de precisão. Instale via pip install sageattention==2.2.0 --no-build-isolation ou compile do código-fonte com MAX_JOBS definido ^[4].

O ComfyUI expõe isso como a flag de lançamento --use-sage-attention, que roteia toda a atenção pelo kernel SageAttention ^[6].

O que é o xformers e por que precisa do próprio índice CUDA?

O xformers é uma biblioteca de kernels de atenção modulares e hackeáveis (atenção exata eficiente em memória, atenção esparsa, atenção block-sparse, camadas lineares fundidas) mantida pela Meta Research. Ele entrega wheels pré-construídos no PyPI, mas mira toolkits CUDA específicos via índice de wheels do PyTorch (cu118, cu126, cu128, cu130). O comando de instalação depende da sua versão CUDA — usar a URL de índice errada produz erro de dependência ausente na importação ^[3].

O FlashAttention ainda importa para o ComfyUI?

O FlashAttention 2 fornece o kernel de atenção exata mais rápido para GPUs NVIDIA (Ampere e mais novos). Ele compila do código-fonte usando o NVIDIA CUDA toolkit e requer a ferramenta de build ninja. No Windows, o FlashAttention 2 não é oficialmente suportado até a v2.3.2, e mesmo assim a compilação exige patch manual de arquivos de template C++ para resolver erros de referência constante em flash_fwd_launch_template.h e flash_bwd_launch_template.h ^[7][8]. Para a maioria dos usuários ComfyUI no Windows, SageAttention ou xformers são a escolha prática.

Ordem de instalação que realmente funciona

A sequência de instalação mais segura evita os rebuilds em cascata que ocorrem quando você instala xformers depois que o PyTorch já foi travado a um toolkit CUDA específico, ou quando o Triton tenta compilar contra um ABI do PyTorch que não casa.

1. Instale PyTorch primeiro, com CUDA 12.8

pip install torch==2.9.0.dev20250716+cu128 torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128

Builds nightly fornecem a compatibilidade mais recente com CUDA 12.8. Para stable, use PyTorch 2.7.0 com --index-url https://download.pytorch.org/whl/cu128 ^[1].

2. Instale xformers em seguida (se usando wheels)

pip install -U xformers --index-url https://download.pytorch.org/whl/cu128

Instalar o xformers aqui, antes das outras bibliotecas de atenção, garante que o contexto CUDA do PyTorch seja estabelecido corretamente. Se pular esta etapa e instalar do código-fonte depois, arrisca mismatches de ABI ^[3].

3. Instale o fork Triton Windows

pip install triton-windows==3.3.1.post19

O projeto Triton oficial não publica wheels Windows; o fork woct0rdho faz isso. Este fork é um espelho do Triton upstream com patches de build específicos para Windows ^[5].

4. Instale SageAttention

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

O SageAttention compila do código-fonte na instalação. A flag --no-build-isolation impede que o pip crie um ambiente de build isolado que duplicaria o PyTorch que você acabou de instalar ^[4].

5. FlashAttention 2 por último (opcional, Windows)

git clone https://github.com/Dao-AILab/flash-attention
cd flash-attention
pip install ninja
MAX_JOBS=4 pip install flash-attn --no-build-isolation

No Windows, espere falhas de compilação a menos que aplique os patches de template descritos na seção de erros abaixo ^[7][8].

Erros comuns e correções

Sintoma: ModuleNotFoundError: No module named 'triton' após pip install no Windows

Causa: o PATH do sistema não tem o diretório do compilador MSVC do Visual Studio. O build Windows do Triton requer C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat no ambiente, ou o diretório bin MSVC adicionado ao PATH manualmente ^[5].

Correção: rode vcvars64.bat antes de ativar seu virtual environment do ComfyUI, ou adicione o diretório MSVC Hostx64\x64 ao PATH do sistema e reinicie o terminal.

Sintoma: FlashAttention 2 falha ao compilar no Windows com erro C2975 em flash_fwd_launch_template.h

Causa: o código de template C++ referencia uma variável Headdim que o compilador MSVC rejeita como parâmetro de template não-tipo em certos contextos ^[8].

Correção: substitua identificadores Headdim nas instanciações de template por seus valores inteiros concretos (ex.: Flash_bwd_kernel_traits<128, 64, 128, ...> em vez de Flash_bwd_kernel_traits<Headdim, ...>). Os arquivos patchados completos estão disponíveis no GitHub issue #595 ^[8].

Sintoma: Triton falha em runtime com conflito de setuptools

Causa: versões recentes do setuptools usam pkg_resources de forma que conflita com o sistema de build do Triton no Windows ^[9].

Correção: faça downgrade do setuptools: pip uninstall -y setuptools && pip install setuptools==78.1.1.

Sintoma: torch.cuda.is_available() retorna False após instalar build CUDA 12.8

Causa: o driver NVIDIA da sua GPU é muito antigo para suportar CUDA 12.8, ou a versão do CUDA toolkit no seu PATH não casa com o build do PyTorch.

Correção: verifique se sua GPU suporta CUDA 12.8 (RTX 30xx e mais novos suportam; GTX 10xx não), e garanta que nvcc --version reporte uma versão compatível do CUDA toolkit. Wheels do PyTorch embutem seu próprio runtime CUDA, mas algumas operações do Triton exigem o toolkit no PATH do sistema ^[1][5].

Perguntas frequentes (FAQ)

Qual versão do PyTorch funciona com FlashAttention no Windows?

O FlashAttention 2 exige PyTorch 2.2 ou posterior e CUDA 12.0 ou posterior. No Windows, o FlashAttention não é oficialmente suportado até v2.3.2, e relatórios da comunidade confirmam compilação no Windows 11 com PyTorch 2.2+cu121 e CUDA 12.2, mas apenas após aplicar patches de template para compatibilidade MSVC ^[7][8].

Posso usar Triton, SageAttention e xformers juntos?

Sim, mas eles servem a papéis diferentes e o ComfyUI roteia a atenção por um backend por vez. SageAttention (--use-sage-attention) e FlashAttention (--use-flash-attention) são mutuamente exclusivos no CLI. O xformers pode operar junto a qualquer um, mas é desabilitado por --disable-xformers ^[6]. A recomendação prática é escolher um backend de atenção primário (SageAttention para Windows, xformers para Linux) e usar Triton como camada de compilação de kernel apenas para SageAttention.

Qual versão do xformers funciona com minha versão do PyTorch?

O xformers entrega wheels pré-construídos para PyTorch ≥2.10.0 com CUDA 11.8, 12.6, 12.8 e 13.0 ^[3][10]. Releases mais antigos do xformers suportam versões antigas do PyTorch — por exemplo, xformers 0.0.31 exige PyTorch 2.7.1, e xformers 0.0.30 exige PyTorch ≥2.7 ^[10]. Se você está no PyTorch 2.7 stable, deve compilar xformers do código-fonte ou prender a um release mais antigo. Usar a versão errada do PyTorch com wheels do xformers resulta em erro de dependência ausente na importação ^[3].

Que GPU eu preciso para a pilha completa de aceleração?

GPUs NVIDIA a partir da série RTX 30xx (Ampere) são o mínimo prático. O SageAttention atinge seus melhores speedups em RTX 40xx (Ada) e H100/H20 (Hopper). O FlashAttention 2 suporta GPUs Ampere, Ada e Hopper. GPUs Turing (RTX 20xx, T4) não são suportadas pelo SageAttention, mas o FlashAttention mantém um repo separado flash-attention-turing com um subconjunto de recursos para Turing ^[7]. GTX 10xx (Pascal) não é suportado nem pelo FlashAttention 2 nem pelo SageAttention.

O que o --fast fp16_accumulation realmente faz no ComfyUI?

Ele alterna o recurso de performance fp16_accumulation, que usa fp16 em vez de fp32 para acumulação intermediária em nós de atenção e multiplicação de matriz. Isso reduz uso de VRAM e melhora throughput em GPUs NVIDIA, ao custo de precisão numérica menor. O CLI do ComfyUI o define como otimização não testada sob --fast ^[6]. ^[1]: https://pytorch.org/get-started/locally/ ^[2]: https://pytorch.org/get-started/previous-versions/ ^[3]: https://raw.githubusercontent.com/facebookresearch/xformers/main/README.md ^[4]: https://raw.githubusercontent.com/thu-ml/SageAttention/main/README.md ^[5]: https://civitai.com/articles/17252 ^[6]: https://raw.githubusercontent.com/comfyanonymous/ComfyUI/master/comfy/cli_args.py ^[7]: https://raw.githubusercontent.com/Dao-AILab/flash-attention/main/README.md ^[8]: https://github.com/Dao-AILab/flash-attention/issues/595 ^[9]: https://civitai.com/articles/9555 ^[10]: https://raw.githubusercontent.com/facebookresearch/xformers/main/CHANGELOG.md ^[11]: https://raw.githubusercontent.com/comfyanonymous/ComfyUI/master/requirements.txt ^[12]: https://civitai.com/articles/3656