Treinar Modelos em Jobs

Esta página mostra como fazer fine-tuning e treinar modelos em Jobs, usando o script de uma biblioteca ou o seu próprio. Cada exemplo é limitado a uma execução curta que termina em minutos em um único A10G, por cerca de US$ 0,10 de computação. O Job é executado nas máquinas do Hugging Face, então continua rodando se você fechar o terminal ou o notebook. Se você nunca executou um Job antes, o Quickstart cobre a instalação do CLI, o login e os créditos necessários para um Job.

Uma primeira execução

Este comando faz o ajuste fino de um classificador de imagens em 2.000 imagens do Food-101 e o envia para seu namespace no Hub, em cerca de três 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

A seção Transformers abrange a execução completa e os outros scripts de exemplo.

Como um Job de treinamento é montado

O comando acima tem cinco partes, e todos os comandos desta página têm as mesmas.

• O que é executado. Ou um script uv, iniciado com hf jobs uv run: um script Python que declara suas dependências em um bloco de comentário perto do topo (# /// script, o formato PEP 723), que o uv instala em um ambiente novo. A seção TRL mostra um exemplo. Ou a imagem Docker de uma biblioteca, iniciada com hf jobs run, que usa a biblioteca já instalada na imagem. Comece com um script uv quando a biblioteca for instalada com pip. Use a imagem quando a biblioteca fornecer uma com dependências compiladas, ou quando sua documentação indicar. Veja Usando imagens Docker para o trade-off.
• Um token. Os jobs não recebem um token do Hugging Face por padrão. -s HF_TOKEN encaminha o seu como um segredo, permitindo que a execução faça o push do modelo e leia entradas com restrição ou privadas. Outros segredos seguem o mesmo caminho, por exemplo -s WANDB_API_KEY.
• Hardware e tempo. --flavor seleciona a GPU. --timeout define o limite de tempo, que é de 30 minutos por padrão. Uma execução que atinge o limite de tempo é interrompida, portanto, defina --timeout acima do tempo de execução esperado. Consulte Hardware flavor e Timeout.
• Um -- entre as flags hf e o script. As flags antes de -- são para o hf jobs. Depois dele vêm o caminho do script e os próprios argumentos do script. Sem ele, um argumento do script que compartilhe o nome de uma flag do hf, como --timeout ou --token, é interpretado pelo hf. No formato de imagem, o que vem depois de -- é o comando a ser executado no container.
• Onde a saída é gravada. Cada biblioteca abaixo pode enviar o modelo finalizado para um repositório do Hub, e cada exemplo mostra a opção correspondente. Para Transformers e TRL, o repositório recebe o nome de --output_dir. Uma execução também pode gravar em um bucket montado à medida que avança, usando -v para montar um no container. Veja Após o término.

Seu próprio código de treinamento. Use a forma mais simples que se encaixe:

• Um arquivo. Declare suas dependências no cabeçalho do script e execute hf jobs uv run train.py. A seção TRL mostra um exemplo.

• Uma pasta de projeto com imports locais, um pyproject.toml ou arquivos de configuração. O hf jobs uv run faz upload apenas do arquivo de script, então monte a pasta. A montagem é somente leitura, portanto o comando copia o projeto para um diretório gravável e o executa lá, como você faria localmente:

  Copiado

  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 as dependências de pyproject.toml ou do cabeçalho do script, e as importações locais e os caminhos relativos funcionam sem alterações. Consulte Local directories.

• Código que requer pacotes de sistema ou um toolkit CUDA. Crie uma imagem uma vez e execute-a com hf jobs run. Consulte Crie sua própria imagem com um Docker Space.

Um script também pode carregar sua própria configuração de lançamento em uma tabela [tool.hf-jobs] no cabeçalho do script, como a seção TRL mostra. Consulte Definir a configuração de lançamento no script. Os mesmos comandos estão disponíveis a partir do Python como run_uv_job() e run_job(), abordados em Configuração.

Verificações antes de uma execução longa

Antes de remover as tampas, algumas verificações evitam uma execução desperdiçada.

• Faça um teste rápido primeiro. Execute o comando com um limite de passos em uma variante pequena, como nos exemplos desta página. Isso comprova que as dependências são instaladas, os dados são carregados, o modelo é ajustado e o push funciona. Em seguida, remova o limite e inicie a execução completa.
• Verifique se os dados cabem. Cada sabor tem um disco fixo, listado na coluna Ephemeral Storage em Pricing and Billing. Os pesos, o dataset e os checkpoints salvos compartilham esse espaço. Um dataset grande demais para o disco pode ser transmitido por streaming ou montado em vez de baixado. Consulte Process Large Datasets.
• Estime o tempo de execução. As métricas finais de train_* do teste de fumaça incluem train_steps_per_second, e o trainer exibe o número total de etapas ao iniciar. Juntos, eles fornecem o tempo de treinamento da execução completa. Defina --timeout com folga acima desse valor, pois o Job também gasta tempo instalando dependências e baixando o modelo. As taxas por sabor estão em Pricing and Billing.
• Em uma instância multi-GPU, inicie um processo por GPU. Instâncias que terminam em x2, x4 ou x8 oferecem várias GPUs em uma única máquina. Certifique-se de que a forma como você inicia o uso delas. Transformers e TRL precisam de accelerate launch, conforme mostrado na seção do TRL. Axolotl faz isso por conta própria. Um simples python train.py usa uma GPU, e um Trainer recorre ao DataParallel, que é mais lento do que um processo por GPU.
• Fixe se for reexecutar. Fixe a URL de um script a um commit em vez de main, e uma imagem a uma tag específica em vez de latest. Uma reexecução então obtém o mesmo software. As URLs de script abaixo acompanham main, então fixe o commit antes de reexecutar um.
• Verifique pontos de controle em execuções longas em um bucket montado, para que um tempo limite excedido ou uma falha não perca a execução. Consulte Após o término.

Enquanto ele executa

Tanto o hf jobs run quanto o hf jobs uv run transmitem os logs e mantêm seu terminal ocupado até o término da execução. Ctrl+C interrompe apenas o fluxo de logs. O Job continua em execução até ser finalizado ou até você cancelá-lo com hf jobs cancel <job_id>.

Para execuções mais longas, passe -d (detach) para obter o ID do Job imediatamente e, em seguida, acompanhe a execução com hf jobs logs -f <job_id> e confirme que a GPU está ocupada com hf jobs stats <job_id>. Após uma execução destacada, hf jobs wait <job_id> bloqueia até o Job terminar e sai com código não zero se ele falhar, o que é o que um script ou um loop de agente precisa. Uma execução não destacada já faz isso. Veja Gerenciar Jobs.

Os logs do trabalho imprimem os valores de perda como texto. Para curvas, aponte o trainer para um rastreador de experimentos, como trackio, e, para um rastreador hospedado, como Weights & Biases, passe sua chave como um segundo segredo.

Após o término

O disco de um Job é descartado quando o Job termina, seja por conclusão, falha ou tempo limite excedido. Qualquer coisa que você queira manter precisa sair do container antes disso.

Envie o modelo para um repositório do Hub. Todas as bibliotecas desta página têm uma opção para isso: --push_to_hub para Transformers, TRL e Diffusers, --output-repo para os scripts do Unsloth, hub_model_id em um YAML do Axolotl. No final da execução, a biblioteca faz o upload dos pesos, do tokenizer e de um model card gerado que registra o modelo base e os argumentos de treinamento. O repositório é criado se não existir. Para torná-lo privado, crie-o primeiro com hf repos create <name> --private. Um token de granularidade fina precisa de acesso de escrita e criação ao repositório do modelo. Sem ele, a execução treina até o fim e então falha no upload.

Escreva em um bucket conforme avança. Para uma execução que leva horas, monte um Storage Bucket existente com leitura e escrita (crie um com hf buckets create) e aponte o diretório de saída da biblioteca para ele. Os checkpoints são gravados no bucket à medida que são salvos, de modo que um timeout ou uma falha não perde a execução, e o próximo Job pode retomar a partir deles. O mesmo caminho funciona para saídas de avaliação, logs e qualquer outra coisa que não seja um 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

Os scripts de Transformers, TRL e Diffusers aceitam --output_dir. O Axolotl usa output_dir no YAML. Se você também passar --push_to_hub, defina também --hub_model_id, ou o repositório será nomeado com base na última parte do caminho de saída (run-01). Para continuar uma execução interrompida, monte o mesmo bucket novamente e passe a opção de retomada da biblioteca, como --resume_from_checkpoint para um Trainer de Transformers. Consulte Volumes para as opções de montagem.

Leia a execução com falha. Um Job que falha mantém seus logs: hf jobs logs <job_id> funciona após o término, e hf jobs inspect <job_id> fornece o status final e a mensagem de erro. hf jobs logs -f retorna quando o fluxo de logs termina, independentemente de a execução ter tido sucesso ou não, portanto, verifique inspect antes de assumir que funcionou.

Transformers

Os scripts de exemplo no repositório Transformers declaram suas dependências no cabeçalho do script, portanto, eles são executados em Jobs diretamente a partir da URL do GitHub. Os argumentos após a URL são passados para o script. Uma primeira execução usa o script de classificação de imagens.

Para a execução completa, remova --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 desse comando: três épocas sobre as 75.000 imagens de treinamento do Food-101 levam cerca de uma hora em a10g-small, aproximadamente US$ 1 na taxa desse flavor, e atingem 90% de precisão. Aumente --timeout para 2h antes de iniciá-lo. --push_to_hub faz o upload do modelo no seu namespace usando o nome do diretório de saída. Existem scripts para classificação de texto, sumarização, tradução, classificação de tokens, reconhecimento de fala e mais.

TRL

TRL possui um script pronto para execução para cada trainer (SFT, DPO, GRPO e outros), cada um declarando suas próprias dependências, para que sejam executados em Jobs diretamente pela URL, assim como os scripts do Transformers. Este comando faz o fine-tuning de um modelo pequeno em um chat dataset:

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

Isso termina em cerca de seis minutos. Remova --max_steps para a execução completa: três epochs de Capybara, o padrão do script, levam cerca de 2 h 20 min em a10g-small, então aumente --timeout com ele. Os próprios docs do TRL usam a100-large, que é mais rápido.

O guia completo, incluindo a criação do seu próprio script TRL e a execução da imagem huggingface/trl, é Training with Jobs na documentação do TRL.

Para várias GPUs, alterne para a imagem TRL, que inclui accelerate, e deixe-a iniciar um processo 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

Sem --max_steps, a execução completa (três épocas do Capybara, o padrão do script) leva cerca de 1 h 35 min em duas A10Gs.

Ao escrever seu próprio script TRL, a configuração de lançamento pode viajar com ele. Uma tabela [tool.hf-jobs] no cabeçalho define o sabor, o tempo limite e os segredos:

# /// 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 então não precisa de flags, e uma flag que você passar ainda tem prioridade. Veja Definir a configuração de lançamento no script.

Unsloth

Unsloth fornece scripts prontos para execução no dataset unsloth/jobs, um para cada família de modelos. Eles instalam o Unsloth a partir do cabeçalho do script e recebem o dataset e o repositório de saída 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

Isso termina em cerca de cinco minutos e faz o push de um adaptador LoRA. Para uma época completa, substitua --max-steps 50 por --num-epochs 1 e aumente --timeout. O passo a passo é Fine-tune with Unsloth on Jobs no blog do Hugging Face.

Axolotl

Axolotl recebe uma configuração YAML e é executado a partir da sua própria imagem Docker, portanto esta seção usa hf jobs run com uma tag fixa e sincroniza a configuração a partir de um diretório local com -v. Salve uma configuração dos Axolotl examples como ./configs/lora.yml e adicione as chaves mostradas após o comando. Este exemplo usa examples/phi/lora-3.5.yaml, um fine-tune LoRA do Phi-3.5-mini, sem outras alterações. A imagem já contém o 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 faz o upload do diretório local configs para o seu bucket privado jobs-artifacts (criado para você no primeiro uso) e o monta somente leitura no container, de modo que o YAML no seu disco é o YAML que a execução usa. A saída é definida no YAML. Essas chaves fazem o push do modelo no final da execução, e max_steps limita essa execução de teste:

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

Isso termina em cerca de sete minutos e envia o adaptador para hub_model_id, como um repositório privado. Remova max_steps para a execução completa. Os formatos de tag de imagem são descritos em Guia do Docker do Axolotl.

Para mais GPUs, altere o flavor e nada mais: no a10g-largex4, o axolotl train inicia um processo por GPU por conta própria. DeepSpeed e FSDP são então uma questão de chaves YAML, abordadas em o guia de multi-GPU do Axolotl.

Para mais detalhes, consulte o guia de empregos da Hugging Face na documentação do Axolotl.

Diffusers

A maioria dos scripts de DreamBooth LoRA no repositório Diffusers declara suas dependências no cabeçalho do script, de modo que eles são executados em Jobs diretamente da URL do GitHub, assim como os scripts do Transformers. Este comando treina um LoRA para FLUX.2 [klein] 4B em cinco fotos de um cachorro:

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

Isso termina em cerca de cinco minutos e faz o push do LoRA. Aumente --max_train_steps para uma execução real; o FLUX.2 README usa 500. Os outros READMEs naquela pasta cobrem os modelos restantes e suas opções de memória. Verifique o topo de um script em busca de um bloco # /// script: scripts sem um, como o script do SDXL, precisam ter suas dependências passadas com --with.

Indo além

• Use Serve Models para colocar o modelo que você treinou atrás de um endpoint temporário, para uma execução de avaliação ou uma demonstração. Inference Endpoints executa um que permanece ativo.
• Configuração para segredos, variáveis de ambiente, volumes e a tabela [tool.hf-jobs] que permite a um script carregar seu próprio sabor e tempo limite.
• Gerenciar Jobs para listar, inspecionar, depurar e cancelar Jobs.
• Processar grandes conjuntos de dados para transmitir e montar dados que não cabem no disco.
• Agendar Jobs para executar um comando de treinamento em um cronômetro.
• Exemplos e tutoriais para artigos da comunidade, incluindo ajuste fino de visão-linguagem e streaming de grandes conjuntos de dados para uma execução de treinamento.
• Use Jobs from a coding agent: a skill hf da CLI permite que o Claude Code, o Codex e o Cursor iniciem e monitorem essas execuções para você.