Accelerate documentation

Paralelismo de sequência no 🤗 accelerate

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Paralelismo de sequência no 🤗 accelerate

Este guia abordará os fundamentos do uso de paralelismo de sequência no 🤗accelerate.

Veja também o muito relacionado Context Parallelism.

Por que paralelismo de sequência?

Com o advento dos grandes modelos de linguagem e, recentemente, dos modelos de raciocínio, o comprimento da sequência tem crescido rapidamente. Isso, combinado com a complexidade de memória quadrática da atenção, gerou a necessidade de formas mais eficientes de treinar modelos com sequências longas. Com um comprimento de sequência de 128k, o requisito de memória da matriz de atenção é 128k * 128k * 2 bytes * num_heads = ~32 GB * num_heads para precisão bf16, dado uma implementação vanilla de atenção. Concedido que, com o uso de flash attention ou SDPA, que não materializam esses pesos de atenção, isso diminui drasticamente, mas o crescimento nos requisitos de memória ainda é considerável.

O paralelismo de sequência Ulysses permite dividir as entradas do cálculo de atenção ao longo da dimensão da sequência e calcular a atenção normalmente, mas usando apenas uma fatia das cabeças de atenção em cada GPU. Com isso, é possível treinar modelos com sequências longas, com algumas ferramentas adicionais, escalando para comprimento de sequência de 15M+. Para ver como aumentar o Ulysses SP com TiledMLP, Liger-Kernel, offload de checkpoint de ativação para CPU e alguns outros truques, consulte o artigo: Arctic Long Sequence Training: Scalable And Efficient Training For Multi-Million Token Sequences.

Como o Ulysses SP é diferente do FSDP CP

No documento Context Parallelism, você pode aprender sobre o uso de outra tecnologia chamada Context Parallelism, que também faz o fatiamento na dimensão da sequência, mas usa Ring Attention em vez de fatiar na dimensão da cabeça.

Os artigos a seguir apresentam uma explicação muito detalhada das diferenças entre as duas tecnologias:

Um resumo rápido adaptado de um dos artigos:

  • O Ulysses SP tem um overhead de comunicação relativamente baixo, mas é limitado pelo número de Attention Heads e, portanto, possui certos requisitos para a topologia da rede (o número de attention heads deve ser divisível pelo número de GPUs participantes para uma única réplica). A comunicação all-to-all é sensível à latência e requer Deepspeed.
  • A comunicação em anel P2P do Ring-Attention do FSDP CP não possui os requisitos de divisibilidade mencionados anteriormente, mas tem um volume de comunicação maior.

Por fim, deve ser possível combinar SP + CP, conforme explicado no artigo USP: A Unified Sequence Parallelism Approach for Long Context Generative AI, para suportar um comprimento de sequência ainda maior, embora isso ainda não esteja integrado ao 🤗accelerate.

Backends de paralelismo de sequência suportados

Atualmente, o único backend de paralelismo de sequência é o deepspeed, que deriva do Ulysses SP modernizado, parte da tecnologia Arctic Long Sequence Training. Há também um tutorial caso você queira integrá-lo diretamente ao seu próprio código.

Como usar paralelismo de sequência?

from accelerate.utils import ParallelismConfig, DeepSpeedSequenceParallelConfig

+# Example: 4 GPUs with sp_size=4, dp_shard_size=1
+# Ensure: dp_replicate_size × dp_shard_size × sp_size = 1 × 1 × 4 = 4 GPUs
parallelism_config = ParallelismConfig(
+     sp_backend="deepspeed",
+     sp_size=4,
+     dp_shard_size=1,  # Explicit: no data parallelism
+     sp_handler=DeepSpeedSequenceParallelConfig(
+         sp_seq_length_is_variable: true,
+         sp_attn_implementation="sdpa",
+     ),
+ )

accelerator = Accelerator(
    ...,
    parallelism_config=parallelism_config,
)

Como em qualquer outro recurso do 🤗accelerate, você também pode habilitar o paralelismo de sequência passando as flags correspondentes para accelerate launch. Neste caso, não há diferença:

accelerate launch --parallelism-config-sp-size 8  ...

Você também pode definir o sp_size e outras configurações no comando accelerate config, que as salvará no seu arquivo de configuração do accelerate, para que você não precise passá-las toda vez que executar seu script.

O paralelismo de sequência é combinado com o paralelismo de dados. Ele não requer GPUs adicionais. Portanto, se você tiver 8 GPUs, pode executar: --parallelism-config-dp-shard-size 8 --parallelism-config-sp-size 8. Ou você pode usar a classe ParallelismConfig para configurá-los programaticamente.

Importante: você deve garantir que dp_replicate_size × dp_shard_size × sp_size = num_processes. Por exemplo, com 8 GPUs e sp_size=8, é necessário dp_shard_size=1 (pois 1 × 1 × 8 = 8). Com 4 GPUs e sp_size=2, você pode usar dp_shard_size=2 (pois 1 × 2 × 2 = 4) para paralelismo 2D.

Configuração do backend ALST/Ulysses SP

ALST/UlyssesSP implementa paralelismo de sequência usando paralelismo de cabeças de atenção, conforme explicado em este artigo. Para simplificar, reutilizamos o conceito e a configuração do paralelismo de sequência, que, do ponto de vista do usuário, é o mesmo: múltiplas GPUs são usadas para processar um único lote.

Para ter uma noção do que o ALST tornou possível — ele nos permitiu treinar em bf16 com 500K tokens em uma única GPU H100, 3,7M em um único nó e 15M no Llama-8B usando apenas quatro nós. Essa funcionalidade do HF Accelerate habilita apenas 1 dos 3 componentes do ALST, portanto, o comprimento de sequência alcançável será menor. Você precisaria habilitar TiledMLP, Activation checkpoint offload to CPU e algumas outras coisas para obter todo o poder do ALST. Para mais detalhes, consulte este tutorial.

Para configurar o backend deepspeed:

# Example: 4 GPUs with sp_size=4, dp_shard_size=1
# Ensure: dp_replicate_size × dp_shard_size × sp_size = 1 × 1 × 4 = 4 GPUs
parallelism_config = ParallelismConfig(
    sp_backend="deepspeed",
    sp_size=4,
    dp_shard_size=1,  # Explicit: no data parallelism
    sp_handler=DeepSpeedSequenceParallelConfig(
        sp_seq_length=256,
        sp_seq_length_is_variable=True,
        sp_attn_implementation="sdpa",
    ),
)
accelerator = Accelerator(
    ...,
    parallelism_config=parallelism_config,
)
  • sp_backend: defina como deepspeed aqui
  • sp_size é o grau do paralelismo de sequência - no exemplo acima, é 4, portanto, 4 GPUs serão usadas para processar um único lote (enquanto se faz DP=4 nas mesmas GPUs)
  • sp_seq_length e sp_seq_length_is_variable são usados para lidar com os comprimentos de sequência. Se sp_seq_length_is_variable=True, o backend trabalhará com um comprimento de sequência que pode mudar entre lotes, caso em que o valor de sp_seq_length pode ser definido como qualquer valor divisível pelo grau de paralelismo de sequência ou não definido. Nesse caso, a cada forward, as variáveis de sequência serão derivadas da entrada. Se False, então seq_length precisa corresponder à dimensão do comprimento de sequência do lote, que então terá que ser preenchida para ser sempre a mesma. O padrão é True.
  • sp_attn_implementation é um de sdpa, flash_attention_2 ou flash_attention_3. Esta implementação de paralelismo de sequência usa position_ids em vez de attention_mask; portanto, eager não pode funcionar aqui até que suporte o uso de position_ids. Além disso, observe que sdpa não trata corretamente múltiplas amostras combinadas em uma; ele prestará atenção a toda a amostra como uma única. Se as amostras não forem combinadas, sdpa funcionará corretamente. Portanto, o Flash Attention deve ser a escolha ideal, pois sempre funciona.
  • sp_allow_recurrent_layers: modelos com camadas de atenção linear (por exemplo, Gated DeltaNet) são recusados por padrão, pois essas camadas carregam um estado recorrente ao longo da sequência que cada rank reiniciaria a partir de zero. Defina como True apenas se o modelo trocar esse estado entre os ranks de paralelismo de sequência por conta própria. O padrão é False.
  • sp_disable_in_eval: se True, o paralelismo de sequência é desativado no modo de avaliação e cada rank executa a sequência inteira. Defina como False para mantê-lo ativado para sequências de avaliação longas; o dataloader de avaliação deve, nesse caso, ser fragmentado da mesma forma que o de treinamento. O valor padrão é True.

Em vez de definir esses valores no objeto DeepSpeedSequenceParallelConfig, você também pode usar as variáveis de ambiente para obter o mesmo resultado - aqui estão elas, correspondendo ao final da lista acima.

  • PARALLELISM_CONFIG_SP_BACKEND
  • PARALLELISM_CONFIG_SP_SEQ_LENGTH
  • PARALLELISM_CONFIG_SP_SEQ_LENGTH_IS_VARIABLE
  • PARALLELISM_CONFIG_SP_ATTN_IMPLEMENTATION
  • PARALLELISM_CONFIG_SP_ALLOW_RECURRENT_LAYERS
  • PARALLELISM_CONFIG_SP_DISABLE_IN_EVAL

Se não for passado no código, sp_size pode ser definido via argumento de CLI --parallelism_config_sp_size. O mesmo vale para os outros argumentos. Você também pode fazer a configuração no estilo do arquivo de configuração do accelerate, por exemplo, para 2 GPUs:

distributed_type: DEEPSPEED
deepspeed_config:
  deepspeed_config_file: path/to/ds_config.json
machine_rank: 0
num_machines: 1
num_processes: 2
parallelism_config:
  parallelism_config_dp_replicate_size: 1
  parallelism_config_dp_shard_size: 1  # Must satisfy: 1 × 1 × 2 = 2 num_processes
  parallelism_config_sp_size: 2
  parallelism_config_sp_backend: deepspeed
  parallelism_config_sp_seq_length_is_variable: true
  parallelism_config_sp_attn_implementation: sdpa

Conforme mencionado anteriormente, o paralelismo de sequência Ulysses normalmente é sobreposto ao paralelismo de dados - os mesmos ranks são usados para alimentar fluxos de dados únicos e também executam o Ulysses Sequence Parallelism. Mas você também pode criar réplicas da seguinte forma:

# Example: 4 GPUs with 2D parallelism (SP=2, DP=2)
# Ensure: dp_replicate_size × dp_shard_size × sp_size = 2 × 1 × 2 = 4 GPUs
parallelism_config = ParallelismConfig(
    dp_replicate_size=2,
    dp_shard_size=1,  # Explicit: no sharding within replicas
    sp_size=2,
    sp_backend="deepspeed",
    sp_handler=DeepSpeedSequenceParallelConfig(...),
)

Aqui usamos 4 gpus, com 2 réplicas de paralelismo de sequência. O Deepspeed-ZeRO é o que impulsiona o paralelismo de dados aqui.

Observe que muita mágica está oculta dentro de UlyssesSPDataLoaderAdapter. Ele é usado nos bastidores, envolvendo seu objeto DataLoader original, mas você deve estar ciente disso caso enfrente algum problema. Ele também injeta automaticamente o shift_labels correto no dicionário do batch, antes que o batch seja dividido entre os ranks participantes.

Agora, a única parte restante para começar a usar ALST/UlyssesSP é agregar a perda entre os ranks usando um all_gather diferenciável para obter os gradientes corretos. O código a seguir faz isso, excluindo também quaisquer tokens mascarados com -100, para obter a média correta:

sp_size = parallelism_config.sp_size if parallelism_config is not None else 1
if sp_size > 1:
    sp_group = accelerator.torch_device_mesh["sp"].get_group()
    sp_world_size = parallelism_config.sp_size

# Normal training loop
for iter, batch in enumerate(dl):
    optimizer.zero_grad()

    batch = move_to_device(batch, model.device)

    # The model automatically receives shift_labels via **kwargs and uses it for loss computation.
    # Both standard transformers models and Liger-patched models handle this correctly.
    outputs = model(**batch)
    loss = outputs.loss
    shift_labels = batch["shift_labels"]

    if sp_size > 1:
        # differentiable weighted per-shard-loss aggregation across ranks
        losses_per_rank = torch.distributed.nn.functional.all_gather(loss, group=sp_group)
        # special dealing with SFT that has prompt tokens that aren't used in loss computation
        good_tokens = (shift_labels != -100).view(-1).sum()
        good_tokens_per_rank = torch.distributed.nn.functional.all_gather(
            good_tokens, group=sp_group
        )
        # Skip ranks with zero valid tokens to avoid NaN contamination (NaN * 0 = NaN)
        total_loss = sum(
            losses_per_rank[rank] * good_tokens_per_rank[rank]
            for rank in range(sp_world_size)
            if good_tokens_per_rank[rank] > 0
        )
        total_good_tokens = sum(good_tokens_per_rank)
        loss = total_loss / max(total_good_tokens, 1)

    if rank == 0: accelerator.print(f"{iter}: {loss=}")
    accelerator.log(dict(train_loss=loss, step=iter))

    accelerator.backward(loss)
    optimizer.step()

Observe que os modelos tratam automaticamente de shift_labels quando ele está presente no lote. A passagem direta do modelo recebe shift_labels via **kwargs e o passa para a função de perda, que calcula corretamente a perda para paralelismo de sequência. Se você usar Liger Kernel, ele também trata shift_labels de forma transparente e calcula a perda de uma maneira muito eficiente em termos de memória. O Liger é altamente recomendado para comprimentos de sequência longos, pois libera memória de GPU ao usar operações fundidas (por exemplo, o cálculo fundido de logit-loss que nunca materializa o tensor completo de logits na memória).

Se você quiser ver o que o HF Accelerate fez nos bastidores, leia este tutorial completo de integração.

Para um exemplo de um loop de treinamento do Accelerate com ALST/UlyssesSP habilitado, veja examples/alst_ulysses_sequence_parallelism.

[!Aviso]

Esta API é bastante nova e ainda está em sua fase experimental. Embora nos esforcemos para fornecer uma API estável, algumas pequenas partes da API pública podem mudar no futuro.

Como este é um backend Deepspeed, a configuração usual do Deepspeed se aplica, portanto, você também pode combinar o paralelismo de sequência com o offloading de estados do otimizador e/ou pesos para liberar mais memória de GPU e habilitar um comprimento de sequência ainda maior. Esta tecnologia foi testada para funcionar com o DeepSpeed ZeRO estágio 2 e 3.

Update on GitHub