# Paralelismo de contexto en 🤗`accelerate`

Esta guía cubrirá los fundamentos del uso de paralelismo de contexto en 🤗`accelerate`; para los lectores más curiosos, también abordaremos algunos detalles técnicos en las secciones posteriores.

Véase también la muy relacionada [Guía sobre paralelismo de secuencias](./sequence_parallelism).

## ¿Por qué el paralelismo de contexto?

Con el auge de los modelos de lenguaje de gran escala y, más recientemente, de los modelos de razonamiento, la longitud de la secuencia ha crecido rápidamente. Esto, combinado con la complejidad de memoria cuadrática de la atención, ha generado la necesidad de formas más eficientes para entrenar modelos con secuencias largas. Con una longitud de secuencia de 128k, el requisito de memoria de la matriz de atención es `128k * 128k * 2 bytes * num_heads = ~32 GB * num_heads` para precisión `bf16`, dado una implementación estándar de atención. Si bien, con el uso de `flash attention` o `SDPA`, que no materializan estos pesos de atención, esto disminuye drásticamente, el aumento en los requisitos de memoria sigue siendo considerable.

El paralelismo de contexto nos permite dividir las entradas del cálculo de atención a lo largo de la dimensión de la secuencia y calcular la atención en paralelo en varias GPU. Con esto, podemos entrenar modelos con secuencias largas, escalando potencialmente a una longitud de secuencia de más de 1M.

## Cómo usar el paralelismo de contexto?

```diff
from accelerate.utils import ParallelismConfig, TorchContextParallelConfig

+ cp_config = TorchContextParallelConfig(
+       cp_comm_strategy="alltoall", # no need to use cp_config at all, if you want to use the default "allgather"
+ )

+ parallelism_config = ParallelismConfig(
+     cp_size=8,
+     cp_handler=cp_config,  # or just cp_size=8, if you want to use the default "allgather"
+ )

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

Como con cualquier otra función de 🤗`accelerate`, también puedes habilitar el paralelismo de contexto pasando las banderas correspondientes a `accelerate launch`. En este caso, no hay diferencia:

```bash
accelerate launch --parallelism-config-cp-size 8 --parallelism-config-cp-comm-strategy [allgather|alltoall] ...
```

> [!Tip]
> También puede establecer `cp_size` y `cp_comm_strategy` en el comando `accelerate config`, lo que los guardará en su archivo de configuración de `accelerate`, de modo que no tenga que pasarlos cada vez que inicie su script.

> [!Tip]
> El paralelismo de contexto es compatible con otras estrategias de paralelismo, como el paralelismo de datos, el paralelismo de tensores y FSDP2. Puede combinarlas simplemente estableciendo los tamaños de paralelismo en los valores deseados, por ejemplo, `--parallelism-config-dp-size 8 --parallelism-config-tp-size 2 --parallelism-config-cp-size 8`. O puede usar la clase `ParallelismConfig` para establecerlos de forma programática.

> [!Warning]
> El paralelismo de contexto está estrechamente acoplado con `FSDP2`, sobre el cual puede obtener más información en la [introducción a FSDP2](fsdp1_vs_fsdp2). Esto significa que el paralelismo de contexto solo funciona si usa `FullyShardedDataParallelPlugin` o `--use-fsdp` con la versión establecida en 2 en su programa. Si no se usa `FSDP2`, se generará un error.

> [!Warning]
> El paralelismo de contexto solo funciona con [SDPA](https://docs.pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html) y solo sin máscara o con máscara causal. No podemos detectarlo correctamente por ti, por lo que es tu responsabilidad asegurarte de que estás usando `SDPA` sin máscara o con máscara causal. Si usas cualquier otra implementación de atención, se generará un error.

Tras habilitar el paralelismo de contexto con los métodos mencionados anteriormente, puedes aplicarlo a tu bucle de entrenamiento. Proporcionamos un envoltorio ligero alrededor de [`torch.distributed.tensor.experimental.context_parallel`](https://docs.pytorch.org/docs/stable/distributed.tensor.html#torch.distributed.tensor.experimental.context_parallel) que puedes utilizar en tu bucle de entrenamiento y que abstracte parte de la complejidad de su uso (más detalles sobre esto más adelante). Para minimizar los cambios que debes realizar en tu bucle de entrenamiento, proporcionamos un gestor de contexto que es un `noop` si el paralelismo de contexto no está habilitado, y aplica el paralelismo de contexto si lo está. De esta forma, puedes utilizarlo en tu bucle de entrenamiento sin cambiar ningún código en función de tu configuración de paralelismo. Puedes utilizarlo de la siguiente manera:

```python
for batch in dataloader:
    with accelerator.maybe_context_parallel(
        buffers=[batch["input_ids"], batch["attention_mask"]],
        buffer_seq_dims=[1, 1],
        no_restore_buffers={batch["input_ids"], batch["labels"]},
    ):
        outputs = model(**batch)
        ...
```

> [!Warning]
> Este gestor de contexto debe recrearse en cada paso de entrenamiento, como se muestra en el ejemplo anterior. Es crucial hacerlo.

Esto puede escalar el tamaño de su contexto a una longitud de secuencia de más de 1M. A continuación, mostramos la velocidad y el uso de memoria del paralelismo de contexto para un tamaño de contexto de hasta 256k. Podemos ver que, al duplicar el tamaño del contexto y el número de GPUs, podemos lograr un uso de memoria constante, lo que potencialmente permite escalar la longitud del contexto de forma ilimitada.

  
  
  Figura 1: Uso de memoria y velocidad del paralelismo de contexto para un tamaño de contexto de hasta 256k.

> [!Tip]
> Estos ejemplos se crearon con un script que puedes encontrar [en la carpeta de ejemplos](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py). Para ejecutar el ejemplo en 8 GPUs H100 (longitud de secuencia de 128k), puedes usar el siguiente comando:
> ```bash
> accelerate launch --use-fsdp --fsdp-activation-checkpointing=TRUE examples/torch_native_parallelism/nd_parallel.py --cp-size=8 --sequence-length=128000
> ```

## La interfaz de Accelerate

El gestor de contexto acepta varios argumentos que se utilizan para configurar el paralelismo de contexto.

- `buffers`: Esta es una lista de tensores que se van a fragmentar a lo largo de la dimensión de secuencia. Estos tensores suelen ser ids de entrada, etiquetas y máscara de atención.
- `buffer_seq_dims`: Es una lista de enteros que especifica la dimensión de secuencia de los buffers, en el orden de la lista `buffers`. Si pasas `buffers=[input_ids, shift_labels]` y ambos tienen forma `[batch_size, sequence_length]`, pasarías `buffer_seq_dims=[1, 1]`, ya que la dimensión de secuencia es la segunda dimensión de los tensores. Esto es necesario para el cálculo correcto de las salidas del modelo.
- `no_restore_buffers`: La implementación de la paralelización de contexto modifica los buffers in-place, convirtiéndolos en `torch.distributed.tensor.Dtensor`. Después de que el gestor de contexto finalice, sería necesario lanzar un kernel de comunicación para restaurar los buffers a su estado original (generalmente all-gather). Esto toma algo de tiempo, por lo que se recomienda pasar los mismos tensores que en el argumento `buffers`, para evitar comunicaciones innecesarias, a menos que estés seguro de que necesitas usar los buffers después de que el gestor de contexto finalice.

> [!Warning]
> El paralelismo de contexto no es compatible con `labels` que sean una copia de `input_ids`, ya que los modelos de 🤗 transformers pueden desplazarlos por sí mismos para habilitar el modelado de lenguaje causal. Imagina este caso: labels = [l1, l2, l3, l4, ... li] si aplicamos paralelismo de contexto, cada rank terminaría con una parte de labels, como esta: labels_rank_0 = [l1, l2], labels_rank_1 = [l3, l4], ... después de que el código de modelado de transformers desplace las labels, terminaría con: labels_rank_0 = [l2, PAD], labels_rank_1 = [l3, PAD], ... donde `PAD` es un token de relleno. Esto resultaría en un cálculo de pérdida incorrecto, ya que las labels ya no están alineadas con las entradas. Por esta razón, es necesario desplazar manualmente las labels antes de pasarlas al modelo

## Opciones configurables
Accelerate solo ofrece una opción para configurar el paralelismo de contexto (excepto `cp_size`)

- `cp_comm_strategy`: El método de rotación a utilizar para los fragmentos. Recomendamos encarecidamente mantenerlo como `"allgather"`, ya que es muy probable que supere a `"alltoall"` en la mayoría de los casos.

El tamaño de paralelismo de contexto es bastante autoexplicativo: es el número de ranks sobre los que se van a fragmentar las entradas. La rotación de fragmentos de paralelismo de contexto define cómo se rotan los fragmentos de las entradas entre los ranks. Abordaremos las 2 opciones con más detalle en la siguiente sección.

Puede ver un ejemplo de extremo a extremo en el archivo [ND parallel example](https://github.com/huggingface/accelerate/blob/main/examples/torch_native_parallelism/nd_parallel.py), donde puede entrenar un modelo de 8B con una longitud de contexto de hasta 128k en un único nodo 8xH100. Utilizando el entrenamiento multinodo, puede escalar esto a una longitud de secuencia de más de 1M en varias GPU. También puede combinarlo sin problemas con otras estrategias de paralelismo para adaptarse a sus necesidades.

## Detalles técnicos

> [!Tip]
> Esta sección es bastante técnica, así que si no necesitas conocer los detalles internos del paralelismo de contexto, puedes omitirla y empezar a construir 🚀

Vamos a usar la palabra `shard` extensivamente en las siguientes secciones, así que definámosla primero. Si decimos que un tensor está `sharded` a lo largo de la dimensión `Dth`, a lo largo de `N` ranks, significa que este tensor se divide en `N` partes, donde cada parte del tensor tiene forma `[..., D//N, ...]`.

## Entonces, ¿cómo funciona?

El paralelismo de contexto funciona fragmentando las matrices `Q, K and V` a lo largo de la dimensión de la secuencia. Cada rank tiene su fragmento asignado de `Q`, llamémoslo `Q_i`. Esta matriz permanece solo en este rank durante todo el cálculo. De manera similar, cada rank tiene su propio fragmento de `K` y `V`, llamémoslos `K_i` y `V_i`. A continuación, cada rank calcula la atención con su propio fragmento de `Q_i`, `K_i` y `V_i`, llamémoslo `attn_i`. Durante este cálculo, se lanza un kernel de comunicación para recopilar los `Ks` y `Vs` de todos los demás ranks. La primitiva de comunicación que se utiliza depende de la opción `context_parallel_shard_rotation`. De esta forma, cada rank puede calcular la atención local, primero con `Q_i`, `K_i` y `V_i`, y luego con `K_j` y `V_j` de todos los demás ranks. Dado que cada rank mantiene matrices `Q, K and V` fragmentadas a lo largo de la dimensión de la secuencia, las matrices resultantes son más pequeñas y pueden caber en una sola GPU.

Podemos formalizar esto en el siguiente pseudocódigo:
```python
comm_kernel = {"allgather": allgather, "alltoall": alltoall}[context_parallel_shard_rotation]
Qi, Ki, Vi = shard(Q, K, V, seq_dim)
attn[i] = attn(Qi, Ki, Vi)
for j in range(context_parallel_size):
    Kj, Vj = comm_kernel()
    attn[j] = attn(Qi, Kj, Vj) # [batch, num_heads, seq_len // context_parallel_size, head_dim]

final_attn = combine(attn)
```

## all-to-all frente a all-gather

### all-gather
Entonces, ¿cuál es la diferencia entre all-to-all y all-gather? Con all-gather, la comunicación es muy simple. Después (bueno, antes, ya que normalmente tarda más) de calcular la atención local `attn_i`, lanzamos un all-gather para reunir todos los demás `Ks` y `Vs` de todos los demás ranks. Una vez completada esta comunicación, cada rank tiene todos los `Ks` y `Vs` de los demás ranks y puede calcular la atención con ellos de forma secuencial. En un escenario ideal, el all-gather termina en el momento exacto en que finaliza el cálculo de `attn_i`. Sin embargo, esto nunca ocurre en la práctica, por lo que la superposición real ideal se logra cuando el `attn_i` completo se superpone con una parte de la comunicación, y luego, para comenzar el cálculo con `K_j` y `V_j`, esperamos a que termine el all-gather.

### all-to-all
All-to-all, a veces llamado `ring-rotation`, utiliza un patrón de comunicación en forma de anillo. Tras concluir el cálculo de `attn_i`, se inicia un all-to-all para enviar `K_i` y `V_i` a los ranks vecinos. Luego, repetimos esto `context_parallel_size-1` veces, de modo que cada rank vea una vez todos los fragmentos de `K` y `V` de todos los demás ranks. En un escenario ideal, preobtenemos los fragmentos `K_i+1` y `V_i+1` del rank vecino y esta comunicación se superpone exactamente con el cálculo de nuestro `attn_i` actual. Nuevamente, en la realidad, esta superposición perfecta nunca ocurre. Dada la naturaleza de este enfoque, si no logramos una superposición perfecta, el penalización es mucho mayor que con all-gather.

## Cómo elegir el método de rotación adecuado
En teoría, all-to-all debería ser la mejor opción. Sin embargo, en la práctica, rara vez lo es. Por lo tanto, usamos all-gather por defecto, ya que es más probable que logre un mejor rendimiento. Amplios [benchmarks](https://discuss.pytorch.org/t/distributed-w-torchtitan-breaking-barriers-training-long-context-llms-with-1m-sequence-length-in-pytorch-using-context-parallel/215082) del equipo de `torchtitan` también muestran que all-to-all rara vez supera a all-gather. Aun así, seguimos ofreciendo ambas opciones, ya que es posible que una de ellas sea mejor para su caso de uso.

Puede ver directamente este problema en la salida del perfilador en la imagen siguiente:

  
  
  Figura 1: En rojo se puede ver el tiempo de inactividad mientras esperamos a que termine el kernel all-to-all. Resaltado en la primera barra azul, se observa que tarda ~250us en terminar, lo cual se repite N-1 veces para cada llamada de atención, donde N es el tamaño de paralelismo de contexto.

## ¿Por qué solo FSDP2?

Solo admitimos paralelismo de contexto con `FSDP2`, ya que creamos una malla conjunta de `context_parallel_size` y `dp_shard_size` para aprovechar todo su potencial. El funcionamiento es el siguiente: fragmentamos el modelo en la malla conjunta de tamaño `cp_size*dp_shard_size`, lo que maximiza el ahorro de memoria. Esto es, en cierto modo, una ventaja gratuita, ya que la comunicación de `FSDP` se superpone por completo con el cálculo de la atención, como se muestra en las imágenes siguientes.

  
  
  Figura 2: En los rectángulos azules (Stream 23), se puede ver que la pre-carga del fragmento de `FSDP` se superpone por completo con el cálculo de la atención (Stream 7), mientras que en los rectángulos rojos (Stream 24), se observa que el kernel de all-gather genera una burbuja de tiempo inactivo, en la que nuestro stream de cálculo (7) permanece inactivo.

En la figura anterior, también se puede observar la diferencia entre all-to-all y all-gather. Mientras que en all-to-all (Figura 1) se lanza un kernel de comunicación N-1 veces para cada llamada de atención, en all-gather (Figura 2) se lanza un kernel de comunicación solo una vez. Esto da lugar a una burbuja más grande, pero solo ocurre una vez por llamada de atención, mientras que en all-to-all ocurre N-1 veces.

## Despacho de datos en malla conjunta

Nos aseguramos de enviar el mismo lote de datos a todo el subgrupo `cp`, para que los resultados sean correctos. (Es decir, cada rango en el subgrupo `cp` recibe el mismo lote de datos). Sin embargo, también enviamos lotes diferentes a cada rango del grupo `dp_shard`. Imagínalo de esta manera:
```
# 8 GPUS, --dp_shard_size 4, --cp_size 2
# mesh = [[0, 1], [2, 3], [4, 5], [6, 7]]
# model is sharded across the whole mesh (each GPU holds 1/8 of the model)
# GPUs 0,1 = batch 0
# GPUs 2,3 = batch 1
... and so on.
```

