Treinamento TRL em Hugging Face Jobs

Guia Detalhado

Leia o guia detalhado antes de executar esta habilidade. Ele contém o procedimento completo e o material de referência. Trate seus requisitos de segurança, pré-requisitos e validação como obrigatórios. Para trabalho focado, carregue as seções relevantes; para trabalho de ponta a ponta, leia o guia completamente.

Quando Usar Esta Habilidade

Use esta habilidade quando os usuários quiserem:

• Ajustar modelos de linguagem em GPUs na nuvem sem infraestrutura local
• Treinar com métodos TRL (SFT, DPO, GRPO, etc.)
• Executar trabalhos de treinamento na infraestrutura Hugging Face Jobs
• Converter modelos treinados para GGUF para implantação local (Ollama, LM Studio, llama.cpp)
• Garantir que os modelos treinados sejam salvos permanentemente no Hub
• Usar fluxos de trabalho modernos com padrões otimizados

Quando Usar Unsloth

Use Unsloth (references/unsloth.md) em vez de TRL padrão quando:

• Memória de GPU limitada - Unsloth usa ~60% menos VRAM
• Velocidade importa - Unsloth é ~2x mais rápido
• Treinamento de modelos grandes (>13B) - a eficiência de memória é crítica
• Treinamento de Modelos Visão-Linguagem (VLMs) - Unsloth tem suporte FastVisionModel

Veja references/unsloth.md para a documentação completa do Unsloth e scripts/unsloth_sft_example.py para um script de treinamento pronto para produção.

Lista de Verificação de Pré-requisitos

Antes de iniciar qualquer trabalho de treinamento, verifique:

✅ Conta e Autenticação

• Conta Hugging Face com plano Pro, Team ou Enterprise (Jobs exigem plano pago)
• Login autenticado: Verifique com hf_whoami()
• HF_TOKEN para Push no Hub ⚠️ CRÍTICO - O ambiente de treinamento é efêmero, deve fazer push para o Hub ou TODOS os resultados de treinamento serão perdidos
• O token deve ter permissões de escrita
• DEVE passar secrets={"HF_TOKEN": "$HF_TOKEN"} na configuração do job para tornar o token disponível (a sintaxe $HF_TOKEN refere-se ao valor real do seu token)

✅ Requisitos do Conjunto de Dados

• O conjunto de dados deve existir no Hub ou ser carregável via datasets.load_dataset()
• O formato deve corresponder ao método de treinamento (SFT: "messages"/texto/prompt-completion; DPO: escolhido/rejeitado; GRPO: apenas prompt)
• SEMPRE valide conjuntos de dados desconhecidos antes do treinamento em GPU para evitar falhas de formato (veja a seção Validação de Conjunto de Dados abaixo)
• Tamanho apropriado para o hardware (Demo: 50-100 exemplos em t4-small; Produção: 1K-10K+ em a10g-large/a100-large)

⚠️ Configurações Críticas

• O tempo limite deve exceder o tempo de treinamento esperado - O padrão de 30 minutos é MUITO CURTO para a maioria dos treinamentos. Mínimo recomendado: 1-2 horas. O job falha e perde todo o progresso se o tempo limite for excedido.
• O push para o Hub deve estar habilitado - Configuração: push_to_hub=True, hub_model_id="username/model-name"; Job: secrets={"HF_TOKEN": "$HF_TOKEN"}

Scripts de Exemplo de Treinamento

Modelos prontos para produção com todas as melhores práticas:

Carregue estes scripts para corretamente:

• scripts/train_sft_example.py - Treinamento SFT completo com Trackio, LoRA, checkpoints
• scripts/train_dpo_example.py - Treinamento DPO para aprendizado de preferência
• scripts/train_grpo_example.py - Treinamento GRPO para RL online

Esses scripts demonstram o salvamento correto no Hub, integração com Trackio, gerenciamento de checkpoints e parâmetros otimizados. Passe o conteúdo deles inline para hf_jobs() ou use-os como modelos para scripts personalizados.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo do seu produto ou API upstream.
• Verifique comandos, comportamento da API, preços, cotas, credenciais e efeitos de implantação contra a documentação oficial atual antes de fazer alterações.
• Não trate exemplos gerados como substitutos para testes específicos do ambiente, revisão de segurança ou aprovação do usuário para ações destrutivas ou custosas.