artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/post-training-torchforge
torchforge-rl-training
VerifiedFornece orientação para treinamento RL agentico nativo do PyTorch usando torchforge, biblioteca da Meta que separa infraestrutura de algoritmos. Use quando você quer abstrações limpas de RL, fácil experimentação de algoritmos, ou treinamento escalável com Monarch e TorchTitan.
torchforge: Biblioteca RL Agentica Nativa do PyTorch
torchforge é a biblioteca RL nativa do PyTorch da Meta que separa infraestrutura de algoritmos. Permite pesquisa rápida em RL deixando você focar em algoritmos enquanto cuida do treinamento distribuído, inference e sincronização de pesos automaticamente.
Quando Usar torchforge
Escolha torchforge quando você precisa:
- Separação limpa entre algoritmos RL e infraestrutura
- Abstrações nativas do PyTorch (sem dependência Ray)
- Fácil experimentação de algoritmos (GRPO, DAPO, SAPO em ~100 linhas)
- Treinamento escalável com sistema de atores Monarch
- Integração com TorchTitan para model parallelism
Considere alternativas quando:
- Você precisa de estabilidade pronta para produção → use miles ou verl
- Você quer treinamento nativo do Megatron → use slime
- torchforge é experimental e APIs podem mudar
Funcionalidades Principais
- Isolamento de algoritmo: Implemente algoritmos RL sem tocar infraestrutura
- Escalabilidade: De GPU única para milhares via Monarch
- Stack moderno: TorchTitan (treinamento), vLLM (inference), TorchStore (sincronização)
- Funções de perda: GRPO, DAPO, CISPO, GSPO, SAPO embutidas
Visão Geral da Arquitetura
┌─────────────────────────────────────────────────────────┐
│ Application Layer (Your Code) │
│ - Define reward models, loss functions, sampling │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ Forge API Layer │
│ - Episode, Group dataclasses │
│ - Service interfaces (async/await) │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ Distributed Services (Monarch) │
│ ├── Trainer (TorchTitan FSDP) │
│ ├── Generator (vLLM inference) │
│ ├── Reference Model (frozen KL baseline) │
│ └── Reward Actors (compute rewards) │
└─────────────────────────────────────────────────────────┘
Instalação
# Create environment
conda create -n forge python=3.12
conda activate forge
# Install (handles PyTorch nightly + dependencies)
./scripts/install.sh
# Verify
python -c "import torch, forge, vllm; print('OK')"
Instalação ROCm
./scripts/install_rocm.sh
Início Rápido
Treinamento SFT (2+ GPUs)
python -m apps.sft.main --config apps/sft/llama3_8b.yaml
Treinamento GRPO (3+ GPUs)
python -m apps.grpo.main --config apps/grpo/qwen3_1_7b.yaml
Workflow 1: Treinamento GRPO para Raciocínio Matemático
Use este workflow para treinar modelos de raciocínio com vantagens relativas ao grupo.
Checklist de Pré-requisitos
- 3+ GPUs (GPU0: trainer, GPU1: ref_model, GPU2: generator)
- Modelo do HuggingFace Hub
- Dataset de treinamento (GSM8K, MATH, etc.)
Passo 1: Criar Configuração
# config/grpo_math.yaml
model: "Qwen/Qwen2.5-7B-Instruct"
dataset:
path: "openai/gsm8k"
split: "train"
streaming: true
training:
batch_size: 4
learning_rate: 1e-6
seq_len: 4096
dtype: bfloat16
gradient_accumulation_steps: 4
grpo:
n_samples: 8 # Responses per prompt
clip_low: 0.2
clip_high: 0.28
beta: 0.1 # KL penalty coefficient
temperature: 0.7
services:
generator:
procs: 1
num_replicas: 1
with_gpus: true
trainer:
procs: 1
num_replicas: 1
with_gpus: true
ref_model:
procs: 1
num_replicas: 1
with_gpus: true
Passo 2: Definir Função de Recompensa
# rewards.py
# Reward functions are in forge.data.rewards
from forge.data.rewards import MathReward, ThinkingReward
import re
# Or define your own reward function
class CustomMathReward:
def __call__(self, prompt: str, response: str, target: str) -> float:
# Extract answer from response
match = re.search(r'\\boxed{([^}]+)}', response)
if not match:
return 0.0
answer = match.group(1).strip()
return 1.0 if answer == target else 0.0
Passo 3: Iniciar Treinamento
python -m apps.grpo.main --config config/grpo_math.yaml
Passo 4: Monitorar Progresso
- Verificar dashboard W&B para curvas de perda
- Verificar que entropia está diminuindo (política ficando mais determinística)
- Monitorar divergência KL (deve permanecer limitada)
Workflow 2: Função de Perda Customizada
Use este workflow para implementar novos algoritmos RL.
Passo 1: Criar Classe de Perda
# src/forge/losses/custom_loss.py
import torch
import torch.nn as nn
class CustomLoss(nn.Module):
def __init__(self, clip_range: float = 0.2, beta: float = 0.1):
super().__init__()
self.clip_range = clip_range
self.beta = beta
def forward(
self,
logprobs: torch.Tensor,
ref_logprobs: torch.Tensor,
advantages: torch.Tensor,
padding_mask: torch.Tensor,
) -> torch.Tensor:
# Compute importance ratio
ratio = torch.exp(logprobs - ref_logprobs)
# Clipped policy gradient
clipped_ratio = torch.clamp(
ratio,
1 - self.clip_range,
1 + self.clip_range
)
pg_loss = -torch.min(ratio * advantages, clipped_ratio * advantages)
# KL penalty
kl = ref_logprobs - logprobs
# Apply mask and aggregate
masked_loss = (pg_loss + self.beta * kl) * padding_mask
loss = masked_loss.sum() / padding_mask.sum()
return loss
Passo 2: Integrar na Aplicação
# apps/custom/main.py
from forge.losses.custom_loss import CustomLoss
loss_fn = CustomLoss(clip_range=0.2, beta=0.1)
# In training loop
loss = loss_fn(
logprobs=logprobs,
ref_logprobs=ref_logprobs,
advantages=advantages,
padding_mask=padding_mask,
)
Workflow 3: Treinamento Distribuído Multi-GPU
Use este workflow para escalar para múltiplas GPUs ou nós.
Configuração para Distribuído
# config/distributed.yaml
model: "meta-llama/Meta-Llama-3.1-8B-Instruct"
parallelism:
tensor_parallel_degree: 2 # Split model across GPUs
pipeline_parallel_degree: 1
data_parallel_shard_degree: 2
services:
generator:
procs: 2 # 2 processes for TP=2
num_replicas: 1
with_gpus: true
trainer:
procs: 2
num_replicas: 1
with_gpus: true
Lançar com SLURM
# Submit job
sbatch --nodes=2 --gpus-per-node=8 run_grpo.sh
Lançar Localmente (Multi-GPU)
# 8 GPU setup
python -m apps.grpo.main \
--config config/distributed.yaml \
--trainer.procs 4 \
--generator.procs 4
Referência da API Principal
Formato de Batch de Treinamento
torchforge usa batches baseados em dicionário para treinamento:
# inputs: list of dicts with torch.Tensor values
inputs = [{"tokens": torch.Tensor}]
# targets: list of dicts with training signals
targets = [{
"response": torch.Tensor,
"ref_logprobs": torch.Tensor,
"advantages": torch.Tensor,
"padding_mask": torch.Tensor
}]
# train_step returns loss as float
loss = trainer.train_step(inputs, targets)
Completion
Saída gerada do vLLM:
@dataclass
class Completion:
text: str # Generated text
token_ids: list[int] # Token IDs
logprobs: list[float] # Log probabilities
metadata: dict # Custom metadata
Funções de Perda Embutidas
Funções de Perda
Funções de perda estão no módulo forge.losses:
from forge.losses import SimpleGRPOLoss, ReinforceLoss
# SimpleGRPOLoss for GRPO training
loss_fn = SimpleGRPOLoss(beta=0.1)
# Forward pass
loss = loss_fn(
logprobs=logprobs,
ref_logprobs=ref_logprobs,
advantages=advantages,
padding_mask=padding_mask
)
ReinforceLoss
from forge.losses.reinforce_loss import ReinforceLoss
# With optional importance ratio clipping
loss_fn = ReinforceLoss(clip_ratio=0.2)
Problemas Comuns e Soluções
Problema: GPUs Insuficientes
Sintomas: Erro "Insufficient GPU resources"
Soluções:
# Reduce service requirements
services:
generator:
procs: 1
with_gpus: true
trainer:
procs: 1
with_gpus: true
# Remove ref_model (uses generator weights)
Ou use CPU para modelo de referência:
ref_model:
with_gpus: false
Problema: OOM Durante Geração
Sintomas: CUDA OOM no vLLM
Soluções:
# Reduce batch size
grpo:
n_samples: 4 # Reduce from 8
# Or reduce sequence length
training:
seq_len: 2048
Problema: Sincronização de Pesos Lenta
Sintomas: Pausas longas entre treinamento e geração
Soluções:
# Enable RDMA (if available)
export TORCHSTORE_USE_RDMA=1
# Or reduce sync frequency
training:
sync_interval: 10 # Sync every 10 steps
Problema: Colapso de Política
Sintomas: Entropia cai para zero, recompensa para de melhorar
Soluções:
# Increase KL penalty
grpo:
beta: 0.2 # Increase from 0.1
# Or add entropy bonus
training:
entropy_coef: 0.01
Recursos
- Documentation: https://meta-pytorch.org/torchforge
- GitHub: https://github.com/meta-pytorch/torchforge
- Discord: https://discord.gg/YsTYBh6PD9
- TorchTitan: https://github.com/pytorch/torchtitan
- Monarch: https://github.com/meta-pytorch/monarch
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |