Entrenamiento con Jobs

Hugging Face Jobs ejecuta tu entrenamiento en GPUs de Hugging Face. Tú eliges el hardware para cada ejecución y solo pagas por los segundos que se ejecuta. Con --push_to_hub, el modelo entrenado se sube al Hub al final.

En esta guía, aprenderás a:

Lanza un script de entrenamiento de TRL con un solo comando
Sigue una ejecución y observa sus curvas de pérdida
Ejecuta tu propio script, con sus ajustes de hardware en el archivo
Guardar puntos de control y reanudar una ejecución interrumpida
Entrenar en varias GPU

Para saber cómo funcionan los Jobs en general, incluido el hardware y los precios, consulte la documentación de Jobs.

Requisitos

Una cuenta de Hugging Face con un saldo de crédito positivo. Los trabajos son de pago por uso: solo pagas por los segundos que utilices.
Iniciado en el Hugging Face Hub (hf auth login)

Una primera ejecución

Este comando realiza el ajuste fino de Qwen2-0.5B-Instruct en el conjunto de datos de chat Capybara con el script SFT de TRL y luego sube el modelo a tu cuenta:

bash

python

Tarda unos minutos y cuesta mucho menos de 1 dólar en a10g-small. Las opciones antes de -- son para Jobs: el hardware, un límite de tiempo y el token utilizado para publicar el modelo. --secrets HF_TOKEN envía el token con el que iniciaste sesión. En Python, pasa el propio token. Los argumentos después de la URL del script van al script. hf jobs uv run ejecuta un script de Python con uv. sft.py lista sus dependencias en un encabezado al inicio del archivo, por lo que Jobs instala TRL antes de que comience el script. El Job se detiene cuando el script termina y la facturación se detiene con él.

--max_steps 100 mantiene esta primera ejecución breve. Elimínalo para la ejecución completa: tres épocas, el valor predeterminado del script, tardan unas pocas horas en a10g-small, por lo que aumente --timeout para que coincida, por ejemplo --timeout 3h. Jobs detiene una ejecución cuando alcanza su tiempo de espera, que es de 30 minutos por defecto. Una GPU más grande, como a100-large, termina antes. Consulte Hardware para ver los sabores y sus precios.

Sigue la ejecución

hf jobs uv run transmite los registros y mantiene tu terminal abierta hasta que la ejecución termina. Ctrl+C detiene solo el flujo de registros: el Job sigue ejecutándose. Añade --detach para obtener el ID del Job de inmediato y luego:

hf jobs logs -f <job_id>   # stream the logs
hf jobs ps                 # list your running Jobs
hf jobs inspect <job_id>   # status, and the error message if it failed
hf jobs cancel <job_id>    # stop it

Consulte Manage Jobs para obtener más información.

Para las curvas de pérdida, TRL registra en Trackio. Añade --env TRACKIO_SPACE_ID=<your-username>/trackio antes de -- para nombrar un Space para el panel de control, y --report_to trackio después de la URL del script. Trackio crea el Space y un bucket para las métricas si no existen. Ambos son públicos por defecto. También funcionan otros trackers que Transformers admite. Para Weights & Biases, añade --with wandb --secrets WANDB_API_KEY antes de -- y --report_to wandb después de la URL del script. --secrets WANDB_API_KEY lee el valor de WANDB_API_KEY en tu entorno local. Consulta variables de entorno y secretos para otras formas de pasarlos.

Ejecuta tu propio script

Escribe tu código de entrenamiento en un archivo de Python (por ejemplo, train.py). Enumera sus dependencias al inicio del archivo, en un encabezado de script, de la misma manera que lo hacen los scripts de TRL. Jobs los instala antes de que comience el script:

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

dataset = load_dataset("trl-lib/Capybara", split="train")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
    args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT", max_steps=100),
)
trainer.train()
trainer.push_to_hub()

Luego, inícialo con la CLI hf jobs o la API de Python:

bash

python

Para un script sin encabezado, enumera las dependencias en el momento de la ejecución con --with, una vez por paquete: --with trl --with peft (dependencies=["trl", "peft"] en Python). El script también puede ser una URL, como un enlace raw de GitHub, un Gist o un archivo en un repositorio público de Hub.

La configuración de lanzamiento también puede estar en el script. Una tabla [tool.hf-jobs] en la cabecera establece el hardware, el tiempo de espera y los secretos:

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run train.py ya no requiere opciones, y una opción que se pase sigue sobrescribiendo al script. El script contiene todo lo necesario para ejecutarse, por lo que se puede compartir o volver a él más adelante sin tener que recordar qué GPU y timeout necesita. hf jobs uv run --dry-run train.py muestra la configuración resuelta y marca los valores que provienen del script. La tabla solo la lee la CLI de hf: run_uv_job() la ignora. Consulte Definir la configuración de lanzamiento en el script.

Ejecutar cualquier script de TRL

El mismo patrón se aplica a todos los scripts de los entrenadores de TRL (SFT, DPO, GRPO, modelado de recompensas y otros) y a los ejemplos independientes .py del Índice de ejemplos. Cada uno declara sus dependencias en la cabecera del script. Un ejemplo que lee otros archivos ubicados en la misma carpeta requiere que su carpeta esté montada en el Job. Consulte Directorios locales. Los ejemplos exclusivos de notebooks no pueden enviarse de esta manera. Los argumentos del script son los mismos que cuando se ejecuta localmente.

Conservar puntos de control

El disco de un Job se elimina cuando el Job termina, incluido cuando alcanza su tiempo de espera o falla. Para una ejecución prolongada, guarda los puntos de control fuera del Job para que sobrevivan a su finalización.

La forma más sencilla es enviar cada punto de control al repositorio del modelo de salida a medida que se guarda:

bash

python

Con --hub_strategy checkpoint, el punto de control más reciente, incluido el estado del optimizador, se conserva en una carpeta last-checkpoint del repositorio. Para continuar una ejecución interrumpida, monte el repositorio en un nuevo Job y reanude desde esa carpeta: lance el mismo comando con --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous antes de -- y --resume_from_checkpoint /previous/last-checkpoint después de la URL del script.

Para mantener varios puntos de control fuera del repositorio del modelo, escríbalos en un Storage Bucket en su lugar. Cree uno con hf buckets create <your-username>/checkpoints --private, munte el bucket en el Job y apunte --output_dir a él:

bash

python

Para continuar una ejecución interrumpida, vuelve a lanzar el mismo comando con --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>. Consulte Write to a bucket as you go para más información y Volumes para las opciones de montaje.

Cada punto de control contiene el estado del modelo y del optimizador, lo que ocupa varias veces el tamaño del modelo. Añade --save_total_limit 2 para conservar solo los más recientes. Si también pasas --push_to_hub, configura --hub_model_id, o el repositorio se nombrará según la última parte de la ruta de salida.

Varias GPU

Un sabor con varias GPUs acorta la ejecución. Para ello, usa hf jobs run, que ejecuta un comando en una imagen de Docker en lugar de un script, con la imagen huggingface/trl, que tiene TRL y Accelerate instalados. Luego, inicia un proceso por GPU. Esto funciona para los scripts de TRL y para tu propio código de entrenamiento.

Acelerar un script de TRL

La ejecución de SFT desde el inicio de esta guía, en cuatro GPUs:

bash

python

El trl CLI pasa --num_processes a accelerate launch. Establécelo en el número de GPUs del flavor, en este caso cuatro L4. Cada proceso toma su propio batch, por lo que el tamaño de batch efectivo es cuatro veces el de una ejecución con una sola GPU. Esta ejecución tarda unos minutos. Sin --max_steps, los tres epochs completos tardan aproximadamente una hora, así que aumenta --timeout, por ejemplo a 2h.

Tu propio script

No se limita a los scripts de TRL. El código de entrenamiento que se ejecuta con accelerate launch localmente funciona de la misma manera en Jobs, siempre que la imagen tenga los paquetes necesarios. Por ejemplo, guarde un script de GRPO con su propia función de recompensa como train_grpo.py en una carpeta y monte la carpeta en el Job. Jobs sube la carpeta a un bucket privado y la monta de solo lectura:

bash

python

El script se ejecuta con TRL instalado en la imagen, por lo que no necesita encabezado de script. GRPOTrainer genera completados con transformers de forma predeterminada, por lo que esto se ejecuta en un solo Job sin servidor vLLM. Para una generación más rápida, consulte vLLM Integration. La siguiente sección explica cómo hf jobs run utiliza la imagen.

Imágenes de Docker

Jobs ejecuta tu script con uv, que instala las dependencias declaradas en su cabecera # /// script en un entorno nuevo. Por lo tanto, la librería TRL que tu script importa proviene de esa cabecera, no de la imagen, y los ejemplos de hf jobs uv run anteriores no necesitan --image en absoluto.

Hay una imagen de Docker con TRL preinstalada disponible en huggingface/trl. Al pasarla a hf jobs uv run, el trabajo recibe la capa de sistema de la imagen, como su cadena de herramientas CUDA, lo cual es importante para las dependencias que se compilan contra ella:

bash

python

Para ejecutar el TRL que está instalado en la imagen, use hf jobs run en su lugar. Ejecuta un comando directamente en la imagen, sin encabezado de script que resolver, por lo que el TRL propio de la imagen es el que se ejecuta. -- separa el comando de las opciones de Jobs, lo cual es necesario siempre que el propio comando tome opciones:

bash

python

La imagen se publica con tres tipos de etiqueta:

Etiqueta	Contenido
`X.Y.Z`	La versión de TRL de esa versión, construida cuando se publica esa versión
`latest`	La versión más reciente
`dev`	La rama `main`, reconstruida en cada fusión

Use dev para ejecutar la versión de desarrollo, que es útil para probar una corrección que ya está en main pero que aún no se ha publicado:

bash

python

Las etiquetas solo seleccionan lo que está instalado en la imagen, por lo que son relevantes para hf jobs run. Con hf jobs uv run, la versión proviene del encabezado del script, y la etiqueta no tiene ninguna diferencia en qué TRL se importa.

Combinar ambos, de modo que uv resuelva la cabecera del script mientras algunas importaciones siguen provienen de la imagen, requiere banderas adicionales. Consulta Reutiliza los paquetes de la imagen y añade dependencias con UV para ese formato y las rutas que requiere.

Jobs se ejecuta en una imagen de Docker de Hugging Face Spaces o Docker Hub, por lo que también puedes especificar cualquier imagen personalizada:

bash

python

El envoltorio TRL Jobs inicia los scripts de TRL en Jobs con configuraciones preestablecidas para algunos modelos, por ejemplo trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara.

Update on GitHub