TRL documentation

Entrenamiento con más de 1M de tokens

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Entrenamiento con más de 1M de tokens

Un agente es capaz de trabajar en una tarea durante horas: leyendo archivos, ejecutando comandos y llevando cada turno de la sesión hacia adelante. Esa sesión acumulada llega a cientos de miles de tokens, por lo que los modelos de frontera ahora anuncian ventanas de contexto de un millón de tokens.

Lograr que un modelo sea bueno con tanto contexto significa entrenarlo en secuencias de esa longitud, y ahí es donde se complica: una secuencia de un millón de tokens no cabe en una GPU, ni siquiera en ocho, sin ayuda.

El ejemplo de esta guía entrena con exactamente una secuencia de este tipo por paso, en un único nodo de 8 GPUs.

Ejecútalo

Se necesita un nodo con 8 H100 (o mejores) y transformers>=5.17.0: el ejemplo utiliza offload del checkpointing de gradientes, añadido en esa versión.

torchrun --nproc_per_node 8 examples/sft_qwen3_8b_1m_context/sft_qwen3_8b_1m_context.py

El script realiza el ajuste fino de Qwen3-8B con libros de PG-19, unidos de extremo a extremo hasta que cada uno tenga aproximadamente un millón de tokens. Después de unos diez minutos de carga y tokenización, se completa el primer paso:

{'loss': 4.311, 'grad_norm': 29.25, 'num_tokens': 1049000.0, 'epoch': 0.25}
  8%|▊ | 1/12 [06:20<1:09:41, 380.10s/it]

Tres cifras merecen la pena leer:

  • num_tokens es 1.049e6. Es una sola secuencia, no un lote de secuencias cortas. Cada token atiende a todos los tokens anteriores, a lo largo del millón completo.
  • La pérdida comienza en 4.3, que es una pérdida inicial normal. Una ejecución configurada de forma sutilmente incorrecta para contexto largo comienza alrededor de 10, y volveremos a explicar por qué.
  • 380 s por paso. Un paso es una secuencia, por lo que son un poco más de seis minutos por secuencia.

De forma ingenua, esta secuencia requiere 288 GB por GPU. El resto de esta guía cuenta cómo se reduce a 56.

Lo que acaba de ocurrir

Todo lo que sigue se construye a partir de una configuración que ya conocemos: una GPU y unos pocos miles de tokens por secuencia. Los problemas comienzan a surgir a medida que la secuencia crece, y lo hacen en un orden fijo.

La pérdida es lo primero que se rompe

Toma Qwen3-4B en una sola tarjeta de 80 GB y aumenta la secuencia. Lo primero en agotar la memoria no es el modelo. Es la pérdida. Revisa el perfil de memoria.

Memory through one training step, with a large block of memory between the forward and backward passes

El pico se encuentra entre las pasadas hacia adelante y hacia atrás, que es donde se calcula la pérdida. Para entender por qué el pico está allí, necesitamos examinar qué hacen las últimas etapas de la decodificación y cómo se construye la pérdida a partir de ellas.

Hidden states times the lm_head weights giving a logits matrix of sequence by vocabulary, then the per-token loss

La última capa del decodificador produce un estado oculto de formaL×H L \times H , dondeL L es la longitud de la secuencia yH H es el tamaño oculto. Este estado oculto se multiplica entonces por los pesos de la cabeza de modelado de lenguaje para producir una matriz de logits de formaL×V L \times V , dondeV V es el tamaño del vocabulario. Esta matriz es enorme, porque la secuencia es larga y el vocabulario es grande (más de cien mil entradas). La pérdida se calcula entonces con una función de entropía cruzada a partir de esa matriz y las etiquetas objetivo, y materializarla es precisamente lo que causa el pico.

¿Podemos calcular la pérdida sin materializar toda la matriz de logits? Sí, podemos proceder por bloques.

La enorme matriz de logits: divídela

En lugar de calcular los logits para toda la secuencia de una vez, tomamos unas pocas cientos de filas a la vez, calculamos la pérdida para esas y sumamos las piezas. La matriz completa de logits nunca se mantiene en memoria de una sola vez. Las filas son la dimensión que se divide de forma limpia: la pérdida es una suma sobre las filas, y el softmax dentro de ella se ejecuta a lo largo del vocabulario de una fila, por lo que un bloque de filas contiene todo lo que su propia pérdida necesita.

The same computation one chunk of rows at a time, each chunk freed before the next, summing into the same loss

Una gran multiplicación se convierte en varias más pequeñas, y el ahorro de memoria es lo suficientemente grande como para que la pérdida ya no sea el pico. TRL utiliza 256 filas por bloque, lo que mantiene cada multiplicación lo suficientemente grande para aprovechar bien la GPU.

El nuevo perfil se ve así.

The same step with the chunked loss, where the memory stays flat throughout

La punta ha desaparecido.

¿Cómo se habilita esto en TRL? No hay nada que hacer: la pérdida por fragmentos es la predeterminada. Si desea optar por la pérdida simple, establezca loss_type="nll" en SFTConfig.

¿Hasta dónde nos permite esto extender la secuencia? En términos de memoria, este único cambio nos lleva de 32k tokens a 160k.

Peak memory against sequence length, the plain loss running out of memory far earlier than the chunked loss

El modelo nunca ha visto la posición 100.000: reescala las posiciones con YaRN

Ahora podemos ajustar 160k tokens en la memoria. Pero ¿puede el modelo leerlos realmente?

Qwen3-4B se entrenó con secuencias de 40.960 tokens. La configuración lo indica:

>>> from transformers import AutoConfig
>>> AutoConfig.from_pretrained("Qwen/Qwen3-4B").max_position_embeddings
40960

Cada posición más allá de esa es una posición que el modelo nunca ha encontrado. Nada se rompe, pero la ejecución simplemente entrena con tokens que el modelo no puede ubicar. Aquí está la pérdida en cada token de una secuencia de 160k tokens:

Per-token loss along a 160k-token sequence, flat for most of it then climbing steeply near the end

El modelo no se desmorona en 40.960. Continúa durante un tiempo y solo empieza a perder el hilo a partir de las 70k aproximadamente. Desde ahí, la métrica asciende de forma constante, terminando por encima de la entropía de unigramas del mismo texto (6,45): un resultado peor que el de un modelo que ignora por completo el contexto y predice únicamente a partir de las frecuencias de los tokens.

The trained range of positions, the much longer range we ask for, and the same range rescaled to fit inside the trained one

Cada token viene con su posición, y el modelo aprendió qué significan las posiciones entre 0 y 40.960. Si le preguntas por la posición 100.000, no tiene nada en qué basarse.

La solución es no proporcionarle nunca una posición que no conozca. Reescalamos: la posición 100.000 se convierte en la posición 25.000, y cada posición de la secuencia vuelve a caer dentro del rango que el modelo conoce. Los tokens no cambian, solo la posición que se les asigna. Esto es lo que hace YaRN, y el factor es simplemente cuánto más lejos vamos: 40.960 entrenados, 163.840 deseados, por lo tanto 4.

¿Cómo habilitar esto en TRL? Pasa la configuración de RoPE al cargar el modelo:

training_args = SFTConfig(
    ...,
    model_init_kwargs={
        "rope_parameters": {
            "rope_type": "yarn",
            "rope_theta": 1_000_000,  # has to match what the model ships with
            "factor": 4.0,
            "original_max_position_embeddings": 40960,
        },
    },
)

La misma medición, con la ejecución reescalada en la parte superior:

The same per-token loss with a second run using rescaled positions, which stays flat where the first one climbs

La ejecución reescalada se mantiene plana hasta las 160k. En los últimos 20k tokens, promedia una pérdida de 2,8, frente a 7,3 sin el reescalado.

Lo que queda son las activaciones: descárgalas

Con la pérdida fragmentada y las posiciones reescaladas, una GPU nos lleva hasta 160k tokens. Luego vuelve a quedarse sin espacio. ¿Qué está llenando la tarjeta esta vez?

Memory through one step at 96k tokens, with one red band per layer stacking up through the forward and draining through the backward

El modelo y su optimizador ocupan 22 GB fijos, independientemente de la longitud de la secuencia. Por encima de eso, cada banda roja es la activación guardada de una capa, de 0,47 GB cada una. Se apilan a medida que la propagación hacia adelante las escribe, permanecen ahí y se retiran una a una a medida que la propagación hacia atrás las consume. El gris en la parte superior es todo lo que se recalcula y se descarta en milisegundos.

TRL ya los reduce por ti y está activado de forma predeterminada. El checkpointing de gradientes conserva solo lo que entra en cada capa y descarta todo lo que la capa calcula internamente: las puntuaciones de atención, el intermedio amplio del MLP y las normalizaciones. Cuando la pasada inversa los necesita, ejecuta la capa una segunda vez para recuperarlos. Lo que sobrevive es un tensor guardado por capa, de sequence x hidden cada uno, y con longitudes de secuencia largas, eso sigue siendo lo más grande en la tarjeta.

La observación útil es que esos tensores no se necesitan en absoluto durante la pasada hacia adelante. Se escriben, se dejan solos y se leen mucho después. Por lo tanto, no tienen que permanecer en la GPU mientras tanto: pueden moverse a la memoria de la CPU y volver a traerlos cuando la pasada hacia atrás los alcance.

training_args = SFTConfig(..., gradient_checkpointing_kwargs={"offload": True})
The same step with the activations offloaded, where almost no red bands remain resident

Mismo paso, misma longitud: en lugar de que se apilen 38 bandas, solo 4 están residentes a la vez, y el pico baja de 59,9 GB a 48,8 GB. Lo que permite aumentar la longitud de la secuencia:

Peak memory against sequence length with and without activation offload, the offload line running lower and reaching further

Por debajo de 48k, ambos son iguales, porque a esa longitud apenas hay nada que mover. A partir de ahí, la ejecución con offload se mantiene más baja, y donde la secuencia solía detenerse en 160k, ahora alcanza 256k en la misma tarjeta.

Esta no es gratuita. Cada activación guardada se transfiere al host y de vuelta, y ese tráfico debe caber entre el cómputo que lo acompaña.

Una GPU no es suficiente: divide la secuencia en varias

Pérdida por bloques, activaciones descargadas: una tarjeta ahora entrena con 256k tokens. ¿Cómo llegar a un millón? Para ver qué se interpone, observa el interior de una sola capa durante la pasada inversa (picos grises en el perfil anterior).

El checkpointing de gradientes significa que el paso hacia adelante apenas conserva nada: cada capa almacena su entrada y descarta el resto. La capa se recalcula más tarde, cuando el paso hacia atrás llega a ella, y ese es el momento en que todo existe a la vez. En el MLP, una línea del modelo,

down_proj(act_fn(gate_proj(x)) * up_proj(x))

Se construyen cuatro tensores a la anchura intermedia completa, y la implementación estándar mantiene los cuatro hasta que la propagación hacia atrás los ha superado. Con un millón de tokens, en un modelo cuyo MLP ensancha cada token de 2560 a 9728:

gate_proj(x)                             19 GB = 1,048,576 x 9728 x 2 bytes
act_fn(gate_proj(x))                     19 GB
up_proj(x)                               19 GB
act_fn(gate_proj(x)) * up_proj(x)        19 GB
                                  total  76 GB

76 GB, dentro de una sola capa, en una tarjeta que tiene 80 y ya ha entregado 30 al modelo y su optimizador. En este punto, la respuesta no es almacenar la secuencia de manera más inteligente. Es darle a cada GPU menos de ella.

A sequence of tokens overflowing a single GPU and running out of memory, then the same sequence cut into four slices that each fit on one GPU

Asigne a cada GPU una porción de la secuencia. Con cuatro de ellas, cada GPU almacena 262.144 tokens en lugar de 1.048.576. Los cuatro tensores se reducen en consecuencia: 19 GB en lugar de 76, lo que, junto con los 30 GB del modelo, cabe en la tarjeta.

La objeción obvia es la atención. Cada token debe atender a todos los tokens anteriores, y ninguna GPU tiene los tokens anteriores. Por lo tanto, las GPUs intercambian lo que les falta, y lo que sale es exactamente lo que una GPU enorme habría calculado.

Hay dos formas de ejecutar ese intercambio: el paralelismo de contexto (CP) y el paralelismo de secuencia de Ulysses (SP).

CPSP
FSDP2✅❌
DeepSpeed❌✅
Configuracióncp_sizesp_size
Lo que se dividelos tokenslas cabezas de atención
Hasta dónde escalacualquier número de GPUshasta el número de cabezas KV, 8 en este caso
AtenciónSDPA, solo causalSDPA o FlashAttention
Requisitosaccelerate 1.11accelerate 1.12, DeepSpeed 0.18.1

En FSDP2, usa CP. Cada GPU conserva su propia porción y las demás porciones llegan a ella por turnos, de modo que cada token acaba viendo todos los tokens anteriores.

from accelerate import ParallelismConfig

training_args = SFTConfig(..., fsdp=True, parallelism_config=ParallelismConfig(cp_size=4))

En DeepSpeed, use SP. En lugar de mover fragmentos, reorganiza el lote justo antes de la atención para que cada GPU contenga todos los tokens pero solo una cuarta parte de las cabezas de atención, y luego lo reorganiza de vuelta.

training_args = SFTConfig(
    ..., deepspeed="examples/deepspeed_configs/zero3.json", parallelism_config=ParallelismConfig(sp_size=4, sp_backend="deepspeed")
)

Los dos parámetros no se solapan hoy en día: cp_size requiere FSDP2 y sp_size solo se ejecuta con DeepSpeed. Se elige el backend y el método queda determinado. El resto de esta sección sigue el camino de FSDP2, que es lo que utiliza el ejemplo en la parte superior de esta guía: sus GPUs no son trabajadores independientes en lotes separados, sino un único grupo que comparte una sola secuencia.

Dos cosas cambian una vez que está activado:

  1. Las secuencias deben rellenarse hasta un múltiplo de cp_size * 2, por lo que pad_to_multiple_of=8 (en SFTConfig) para cuatro GPUs.
  2. El requisito de causal-SDPA descarta el empaquetado (packing), que depende de una máscara diagonal por bloques para evitar que los documentos se lean entre sí, y TRL genera un error si se solicitan ambos. También descarta los modelos cuyas capas utilizan atención de ventana deslizante o atención por fragmentos, que accelerate rechaza: OpenAI GPT-OSS, Gemma 3 y 4, Qwen3.5 y posteriores. Qwen3 y Qwen3-MoE utilizan atención completa en todo el modelo, por lo que son los modelos utilizados aquí.

Pasar las porciones de un lado a otro cuesta menos de lo que se podría esperar. Con 131k tokens en un solo nodo, un paso tarda 34,6 s en dos GPUs, 17,8 s en cuatro y 9,5 s en ocho. Cada duplicación del grupo reduce el tiempo del paso a la mitad, y pasar de dos a ocho recupera 3,7x de los 4x posibles.

Y ese es el último de los cuatro palancas:

Peak memory against sequence length on one GPU and on four with context parallelism, the four-GPU line reaching a million tokens where the single GPU stops just past 256k

Una sola tarjeta se detiene justo después de 256k. Cuatro de ellas abarcan el millón completo, situándose en 63,6 GB con margen de sobra. La secuencia con la que se abrió esta guía cabe.

Establezca PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True. Con un millón de tokens, la ejecución anterior requiere 63,6 GB en una tarjeta de 80 GB y, aun así, falla sin esta configuración: los tensores que solicita son grandes y contiguos, y el asignador no puede encontrar espacio para ellos entre los bloques que ya mantiene.

Lecturas adicionales

  • Paralelismo de contexto, la guía de Accelerate sobre cp_size y la malla de dispositivos que construye.
  • Ulysses y ring attention, sobre cómo difieren los dos intercambios y qué cuesta cada uno en términos de comunicación.
  • YaRN, el reescalado de posiciones utilizado en la sección de RoPE.
Update on GitHub