Hub documentation

Entrenar modelos en trabajos

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Entrenar modelos en trabajos

Esta página muestra cómo ajustar y entrenar modelos en Jobs, con el script de una biblioteca o con el tuyo. Cada ejemplo está limitado a una ejecución breve que termina en minutos en una sola A10G, por alrededor de $0.10 de cómputo. El Job se ejecuta en las máquinas de Hugging Face, por lo que continúa si cierras tu terminal o tu laptop. Si no has ejecutado un Job antes, Quickstart cubre la instalación del CLI, el inicio de sesión y los créditos que un Job necesita.

Una primera ejecución

Este comando ajusta un clasificador de imágenes con 2.000 imágenes de Food-101 y lo publica en tu espacio de nombres en el Hub, en unos tres minutos:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/transformers/main/examples/pytorch/image-classification/run_image_classification.py \
  --model_name_or_path google/vit-base-patch16-224-in21k \
  --dataset_name ethz/food101 \
  --do_train --do_eval \
  --remove_unused_columns False \
  --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 \
  --output_dir vit-food101 \
  --push_to_hub

La sección Transformers cubre la ejecución completa y los otros scripts de ejemplo.

Cómo se configura un Job de entrenamiento

El comando anterior tiene cinco partes, y todos los comandos de esta página tienen las mismas.

Qué se ejecuta. Ya sea un script de uv, lanzado con hf jobs uv run: un script de Python que declara sus dependencias en un bloque de comentarios cerca del inicio (# /// script, el formato PEP 723), que uv instala en un entorno nuevo. La sección de TRL muestra uno. O la imagen Docker de una biblioteca, lanzada con hf jobs run, que utiliza la biblioteca ya instalada en la imagen. Comienza con un script de uv cuando la biblioteca se instala con pip. Usa la imagen cuando la biblioteca la proporciona con dependencias compiladas, o cuando su documentación lo indica. Consulta Uso de imágenes Docker para conocer las ventajas y desventajas.
Un token. Los trabajos no reciben un token de Hugging Face de forma predeterminada. -s HF_TOKEN reenvía el tuyo como un secreto, de modo que la ejecución pueda publicar su modelo y leer entradas con acceso restringido o privadas. Otros secretos se transmiten de la misma manera, por ejemplo -s WANDB_API_KEY.
Hardware y tiempo. --flavor selecciona la GPU. --timeout establece el límite de tiempo, que por defecto es de 30 minutos. Una ejecución que alcance el tiempo límite se detiene, por lo que configure --timeout por encima del tiempo de ejecución esperado. Consulte Hardware flavor y Timeout.
Un -- entre las banderas hf y el script. Las banderas antes de -- son para hf jobs. Después vienen la ruta del script y sus propios argumentos. Sin ella, un argumento del script que comparta nombre con una bandera de hf, como --timeout o --token, será tomado por hf. En la forma de imagen, lo que sigue a -- es el comando a ejecutar en el contenedor.
Dónde se guarda la salida. Cada biblioteca de la lista puede subir el modelo final a un repositorio del Hub, y cada ejemplo muestra la opción correspondiente. En el caso de Transformers y TRL, el repositorio toma el nombre de --output_dir. Una ejecución también puede escribir en un bucket montado a medida que avanza, utilizando -v para montar uno en el contenedor. Consulte Cuando termina.

Tu propio código de entrenamiento. Usa la forma más simple que se adapte:

Un solo archivo. Declara sus dependencias en la cabecera del script y ejecuta hf jobs uv run train.py. La sección de TRL muestra un ejemplo.
Una carpeta de proyecto con importaciones locales, un pyproject.toml o archivos de configuración. hf jobs uv run solo sube el archivo del script, por lo que debes montar la carpeta. La montaje es de solo lectura, por lo que el comando copia el proyecto a un directorio escribible y lo ejecuta allí, como lo harías localmente:
```
hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./my-project:/code ghcr.io/astral-sh/uv:python3.12-bookworm -- \
  bash -c "cp -r /code /tmp/project && cd /tmp/project && uv run train.py --config configs/run.yaml"
```
uv run instala las dependencias desde pyproject.toml o desde la cabecera del script, y las importaciones locales y las rutas relativas funcionan sin cambios. Consulte Directorios locales.
Código que requiere paquetes del sistema o un kit de herramientas de CUDA. Crea una imagen una vez y ejecútala con hf jobs run. Consulta Crea tu propia imagen con un Docker Space.

Un script también puede incluir su propia configuración de lanzamiento en una tabla [tool.hf-jobs] en la cabecera del script, como se muestra en la sección de TRL. Consulte Definir la configuración de lanzamiento en el script. Los mismos comandos están disponibles desde Python como run_uv_job() y run_job(), descritos en Configuración.

Comprobaciones antes de una ejecución larga

Antes de quitar las tapas, unas pocas comprobaciones evitan una ejecución desperdiciada.

Haz una prueba rápida primero. Ejecuta el comando con un límite de pasos en una variante pequeña, como hacen los ejemplos de esta página. Esto demuestra que las dependencias se instalan, que los datos se cargan, que el modelo cabe en memoria y que la publicación funciona. Luego, elimina el límite y lanza la ejecución completa.
Comprueba que los datos caben. Cada variante tiene un disco fijo, indicado en la columna Ephemeral Storage de Pricing and Billing. Los pesos, el conjunto de datos y los puntos de control guardados lo comparten. Un conjunto de datos demasiado grande para el disco puede transmitirse o montarse en lugar de descargarse. Consulta Process Large Datasets.
Estime el tiempo de ejecución. Las métricas finales de train_* de la prueba de humo incluyen train_steps_per_second, y el trainer imprime el número total de pasos al iniciar. Juntos, proporcionan el tiempo de entrenamiento de la ejecución completa. Establezca --timeout con un margen suficiente por encima de ese valor, ya que el Job también dedica tiempo a instalar dependencias y descargar el modelo. Las tarifas por sabor están en Pricing and Billing.
En una configuración con varias GPU, inicia un proceso por GPU. Las configuraciones que terminan en x2, x4 o x8 ofrecen varias GPU en una sola máquina. Asegúrate de que la forma en que lo lanzas las utilice. Transformers y TRL necesitan accelerate launch, como se muestra en la sección de TRL. Axolotl lo hace por sí solo. Un simple python train.py usa una GPU, y un Trainer recurre a DataParallel, que es más lento que un proceso por GPU.
Fija si vas a volver a ejecutar. Fija la URL de un script a un commit en lugar de main, y una imagen a una etiqueta específica en lugar de latest. De esta forma, una nueva ejecución obtiene el mismo software. Las URLs de los scripts de abajo siguen main, por lo que fija el commit antes de volver a ejecutar uno.
Guarda puntos de control de ejecuciones largas en un bucket montado para que un tiempo de espera agotado o un error no pierdan la ejecución. Consulta Después de que termine.

Mientras se ejecuta

Tanto hf jobs run como hf jobs uv run transmiten los registros y mantienen tu terminal abierta hasta que la ejecución termina. Ctrl+C detiene solo la transmisión de registros. El Job sigue ejecutándose hasta que finaliza o lo detienes con hf jobs cancel <job_id>.

Para ejecuciones más largas, pase -d (detach) para obtener el ID del Job de inmediato y luego siga la ejecución con hf jobs logs -f <job_id> y confirme que la GPU está ocupada con hf jobs stats <job_id>. Después de una ejecución detach, hf jobs wait <job_id> bloquea hasta que el Job termine y sale con un código no cero si falló, lo que es lo que necesita un script o un bucle de agente. Una ejecución no detach ya hace esto. Consulte Manage Jobs.

Los registros del trabajo imprimen los valores de pérdida como texto. Para las curvas, dirija el entrenador a un rastreador de experimentos como trackio y, para un rastreador alojado como Weights & Biases, pase su clave como un segundo secreto.

Después de que termine

El disco de un Job se descarta cuando el Job termina, ya sea que haya finalizado, fallado o haya expirado el tiempo de espera. Todo lo que quieras conservar debe salir del contenedor antes de eso.

Suba el modelo a un repositorio del Hub. Cada biblioteca de esta página tiene una opción para ello: --push_to_hub para Transformers, TRL y Diffusers, --output-repo para los scripts de Unsloth, hub_model_id en un YAML de Axolotl. Al final de la ejecución, la biblioteca sube los pesos, el tokenizer y una tarjeta de modelo generada que registra el modelo base y los argumentos de entrenamiento. El repositorio se crea si no existe. Para hacerlo privado, créelo primero con hf repos create <name> --private. Un token de grano fino necesita acceso de escritura y creación al repositorio del modelo. Sin él, la ejecución entrena hasta el final y luego falla en la subida.

Escribe en un bucket a medida que avanzas. Para una ejecución que dura horas, monta un Storage Bucket existente con permisos de lectura y escritura (créalo con hf buckets create) y apunta el directorio de salida de la biblioteca hacia él. Los checkpoints se guardan en el bucket a medida que se crean, por lo que un tiempo de espera agotado o un error no provoca la pérdida de la ejecución, y el siguiente Job puede reanudar desde ellos. La misma ruta funciona para las salidas de evaluación, los registros y cualquier otro elemento que no sea un modelo.

hf jobs uv run --flavor a10g-large --timeout 8h -s HF_TOKEN \
  -v hf://buckets/your-username/checkpoints:/ckpt -- \
  train.py --output_dir /ckpt/run-01

Los scripts de Transformers, TRL y Diffusers aceptan --output_dir. Axolotl toma output_dir en el YAML. Si también pasas --push_to_hub, configura también --hub_model_id, o el repositorio se nombrará según la última parte de la ruta de salida (run-01). Para continuar una ejecución interrumpida, monta el mismo bucket de nuevo y pasa la opción de reanudación de la librería, como --resume_from_checkpoint para un Trainer de Transformers. Consulta Volumes para las opciones de montaje.

Leer un trabajo fallido. Un Job que falla conserva sus registros: hf jobs logs <job_id> funciona después de que termina, y hf jobs inspect <job_id> proporciona el estado final y el mensaje de error. hf jobs logs -f devuelve el control cuando termina el flujo de registros, independientemente de si el trabajo tuvo éxito o no, por lo que comprueba inspect antes de asumir que funcionó.

Transformers

Los scripts de ejemplo del repositorio de Transformers declaran sus dependencias en la cabecera del script, por lo que se ejecutan en Jobs directamente desde su URL de GitHub. Los argumentos que siguen a la URL se pasan al script. Una primera ejecución utiliza el script de clasificación de imágenes.

Para la ejecución completa, elimina --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 de ese comando: tres épocas sobre las 75.000 imágenes de entrenamiento de Food-101 tardan aproximadamente una hora en a10g-small, alrededor de 1 USD a la tarifa de esa variante, y alcanzan un 90% de precisión. Aumenta --timeout a 2h antes de lanzarlo. --push_to_hub sube el modelo bajo tu espacio de nombres usando el nombre del directorio de salida. Existen scripts para clasificación de texto, resumen, traducción, clasificación de tokens, reconocimiento de voz y más.

TRL

TRL tiene un script listo para ejecutar para cada entrenador (SFT, DPO, GRPO y otros), cada uno declara sus propias dependencias, por lo que se ejecutan en Jobs directamente desde su URL, al igual que los scripts de Transformers. Este comando realiza el ajuste fino de un modelo pequeño en un conjunto de datos de chat:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

Esto termina en unos seis minutos. Elimina --max_steps para la ejecución completa: tres épocas de Capybara, el valor predeterminado del script, tardan unas 2 h 20 min en a10g-small, así que aumenta --timeout con ello. La documentación propia de TRL utiliza a100-large, que es más rápido.

La guía completa, que incluye la escritura de tu propio script de TRL y la ejecución de la imagen huggingface/trl, es Entrenamiento con Jobs en la documentación de TRL.

Para varias GPUs, cambia a la imagen de TRL, que incluye accelerate, y deja que inicie un proceso por GPU:

hf jobs run --flavor a10g-largex2 --timeout 30m -s HF_TOKEN huggingface/trl -- \
  accelerate launch --num_processes 2 -m trl.scripts.sft \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

Sin --max_steps, la ejecución completa (tres épocas de Capybara, el valor predeterminado del script) tarda aproximadamente 1 h 35 min en dos A10Gs.

Cuando escribes tu propio script de TRL, la configuración de lanzamiento puede viajar con él. Una tabla [tool.hf-jobs] en la cabecera establece el sabor, el tiempo de espera y los secretos:

# /// script
# dependencies = ["trl"]
#
# [tool.hf-jobs]
# flavor  = "a10g-small"
# timeout = "1h"
# secrets = ["HF_TOKEN"]
# ///
from trl import SFTConfig, SFTTrainer
...

hf jobs uv run train.py ya no necesita banderas, y una bandera que sí se pase sigue teniendo prioridad. Consulte Definir la configuración de inicio en el script.

Unsloth

Unsloth ofrece scripts listos para ejecutar en el dataset unsloth/jobs, uno por familia de modelos. Instalan Unsloth desde la cabecera de su script y toman el dataset y el repositorio de salida como argumentos:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://huggingface.co/datasets/unsloth/jobs/resolve/main/sft-lfm2.5.py \
  --dataset mlabonne/FineTome-100k \
  --max-steps 50 \
  --output-repo your-username/lfm-finetuned

Esto termina en unos cinco minutos y publica un adaptador LoRA. Para una época completa, reemplaza --max-steps 50 por --num-epochs 1 y aumenta --timeout. La guía es Fine-tune with Unsloth on Jobs en el blog de Hugging Face.

Axolotl

Axolotl toma una configuración YAML y se ejecuta desde su propia imagen de Docker, por lo que esta sección utiliza hf jobs run con una etiqueta fija y sincroniza la configuración desde un directorio local con -v. Guarda una configuración de los Axolotl examples como ./configs/lora.yml y añade las claves que se muestran después del comando. Este ejemplo utiliza examples/phi/lora-3.5.yaml, un ajuste fino LoRA de Phi-3.5-mini, sin otros cambios. La imagen ya contiene el comando axolotl.

hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./configs:/configs \
  axolotlai/axolotl:0.19.0-py3.12-cu130-2.13.0 -- \
  axolotl train /configs/lora.yml

-v ./configs:/configs sube el directorio local configs a tu cubo privado jobs-artifacts (creado para ti en el primer uso) y lo monta de solo lectura en el contenedor, de modo que el YAML en tu disco es el YAML que usa la ejecución. La salida se configura en el YAML. Estas claves empujan el modelo al final de la ejecución, y max_steps limita esta ejecución de prueba:

hub_model_id: your-username/my-adapter
hub_strategy: end
max_steps: 20

Esto termina en unos siete minutos y sube el adaptador a hub_model_id, como un repositorio privado. Elimina max_steps para la ejecución completa. Los formatos de la etiqueta de imagen se describen en la guía de Docker de Axolotl.

Para más GPUs, cambia el sabor y nada más: en a10g-largex4, axolotl train inicia un proceso por GPU por sí solo. DeepSpeed y FSDP son entonces una cuestión de claves YAML, cubierto en la guía de multi-GPU de Axolotl.

Para más detalles, consulte la guía de Hugging Face Jobs en la documentación de Axolotl.

Diffusers

La mayoría de los scripts de DreamBooth LoRA en el repositorio de Diffusers declaran sus dependencias en la cabecera del script, por lo que se ejecutan en Jobs directamente desde su URL de GitHub, al igual que los scripts de Transformers. Este comando entrena un LoRA para FLUX.2 [klein] 4B con cinco fotos de un perro:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
  --pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
  --dataset_name diffusers/dog-example \
  --instance_prompt "a photo of sks dog" \
  --resolution 512 --mixed_precision bf16 --guidance_scale 1 \
  --gradient_checkpointing --cache_latents \
  --optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
  --max_train_steps 20 --seed 0 \
  --output_dir /tmp/out \
  --push_to_hub --hub_model_id your-username/klein-dog-lora

Esto termina en unos cinco minutos y sube el LoRA. Aumenta --max_train_steps para una ejecución real; el FLUX.2 README usa 500. Los demás README de esa carpeta cubren los modelos restantes y sus opciones de memoria. Revisa la parte superior de un script para un bloque # /// script: los scripts sin uno, como el script de SDXL, necesitan pasar sus dependencias con --with.

Ir más allá

Serve Models para poner el modelo que entrenaste detrás de un endpoint temporal, para una ejecución de evaluación o una demostración. Inference Endpoints ejecuta uno que permanece activo.
Configuración de secretos, variables de entorno, volúmenes y la tabla [tool.hf-jobs] que permite a un script llevar su propio sabor y tiempo de espera.
Gestionar trabajos para listar, inspeccionar, depurar y cancelar trabajos.
Procesar conjuntos de datos grandes para transmitir y montar datos que no caben en el disco.
Programar trabajos para ejecutar un comando de entrenamiento en un temporizador.
Ejemplos y tutoriales para guías de la comunidad, que incluyen el ajuste fino de modelos de visión-lenguaje y la transmisión de conjuntos de datos grandes a una ejecución de entrenamiento.
Usar Jobs desde un agente de código: la habilidad hf de la CLI permite a Claude Code, Codex y Cursor iniciar y supervisar estas ejecuciones por ti.

Update on GitHub

←Servir modelos Ejemplos y tutoriales→