{"id":"torchforge","name":"torchforge-rl-training","summary":"Metaのライブラリであるtorchforge(インフラとアルゴリズムを分離するライブラリ)を用いるPyTorchネイティブのエージェントRLのガイダンスを提供します。","body":"# torchforge: PyTorch-Native Agentic RL Library\n\ntorchforge is Meta's PyTorch-native RL library that separates infrastructure concerns from algorithm concerns. It enables rapid RL research by letting you focus on algorithms while handling distributed training, inference, and weight sync automatically.\n\n## When to Use torchforge\n\n**Choose torchforge when you need:**\n- Clean separation between RL algorithms and infrastructure\n- PyTorch-native abstractions (no Ray dependency)\n- Easy algorithm experimentation (GRPO, DAPO, SAPO in ~100 lines)\n- Scalable training with Monarch actor system\n- Integration with TorchTitan for model parallelism\n\n**Consider alternatives when:**\n- You need production-ready stability → use **miles** or **verl**\n- You want Megatron-native training → use **slime**\n- torchforge is experimental and APIs may change\n\n## Key Features\n\n- **Algorithm isolation**: Implement RL algorithms without touching infrastructure\n- **Scalability**: From single GPU to thousands via Monarch\n- **Modern stack**: TorchTitan (training), vLLM (inference), TorchStore (sync)\n- **Loss functions**: GRPO, DAPO, CISPO, GSPO, SAPO built-in\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Application Layer (Your Code)                           │\n│ - Define reward models, loss functions, sampling        │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n┌─────────────────────▼───────────────────────────────────┐\n│ Forge API Layer                                         │\n│ - Episode, Group dataclasses                           │\n│ - Service interfaces (async/await)                      │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n┌─────────────────────▼───────────────────────────────────┐\n│ Distributed Services (Monarch)                          │\n│ ├── Trainer (TorchTitan FSDP)                          │\n│ ├── Generator (vLLM inference)                          │\n│ ├── Reference Model (frozen KL baseline)               │\n│ └── Reward Actors (compute rewards)                    │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Installation\n\n```bash\n# Create environment\nconda create -n forge python=3.12\nconda activate forge\n\n# Install (handles PyTorch nightly + dependencies)\n./scripts/install.sh\n\n# Verify\npython -c \"import torch, forge, vllm; print('OK')\"\n```\n\n### ROCm Installation\n\n```bash\n./scripts/install_rocm.sh\n```\n\n## Quick Start\n\n### SFT Training (2+ GPUs)\n\n```bash\npython -m apps.sft.main --config apps/sft/llama3_8b.yaml\n```\n\n### GRPO Training (3+ GPUs)\n\n```bash\npython -m apps.grpo.main --config apps/grpo/qwen3_1_7b.yaml\n```\n\n---\n\n## Workflow 1: GRPO Training for Math Reasoning\n\nUse this workflow for training reasoning models with group-relative advantages.\n\n### Prerequisites Checklist\n- [ ] 3+ GPUs (GPU0: trainer, GPU1: ref_model, GPU2: generator)\n- [ ] Model from HuggingFace Hub\n- [ ] Training dataset (GSM8K, MATH, etc.)\n\n### Step 1: Create Configuration\n\n```yaml\n# config/grpo_math.yaml\nmodel: \"Qwen/Qwen2.5-7B-Instruct\"\n\ndataset:\n  path: \"openai/gsm8k\"\n  split: \"train\"\n  streaming: true\n\ntraining:\n  batch_size: 4\n  learning_rate: 1e-6\n  seq_len: 4096\n  dtype: bfloat16\n  gradient_accumulation_steps: 4\n\ngrpo:\n  n_samples: 8           # Responses per prompt\n  clip_low: 0.2\n  clip_high: 0.28\n  beta: 0.1              # KL penalty coefficient\n  temperature: 0.7\n\nservices:\n  generator:\n    procs: 1\n    num_replicas: 1\n    with_gpus: true\n  trainer:\n    procs: 1\n    num_replicas: 1\n    with_gpus: true\n  ref_model:\n    procs: 1\n    num_replicas: 1\n    with_gpus: true\n```\n\n### Step 2: Define Reward Function\n\n```python\n# rewards.py\n# Reward functions are in forge.data.rewards\nfrom forge.data.rewards import MathReward, ThinkingReward\nimport re\n\n# Or define your own reward function\nclass CustomMathReward:\n    def __call__(self, prompt: str, response: str, target: str) -> float:\n        # Extract answer from response\n        match = re.search(r'\\\\boxed{([^}]+)}', response)\n        if not match:\n            return 0.0\n\n        answer = match.group(1).strip()\n        return 1.0 if answer == target else 0.0\n```\n\n### Step 3: Launch Training\n\n```bash\npython -m apps.grpo.main --config config/grpo_math.yaml\n```\n\n### Step 4: Monitor Progress\n- [ ] Check W&B dashboard for loss curves\n- [ ] Verify entropy is decreasing (policy becoming more deterministic)\n- [ ] Monitor KL divergence (should stay bounded)\n\n---\n\n## Workflow 2: Custom Loss Function\n\nUse this workflow to implement new RL algorithms.\n\n### Step 1: Create Loss Class\n\n```python\n# src/forge/losses/custom_loss.py\nimport torch\nimport torch.nn as nn\n\nclass CustomLoss(nn.Module):\n    def __init__(self, clip_range: float = 0.2, beta: float = 0.1):\n        super().__init__()\n        self.clip_range = clip_range\n        self.beta = beta\n\n    def forward(\n        self,\n        logprobs: torch.Tensor,\n        ref_logprobs: torch.Tensor,\n        advantages: torch.Tensor,\n        padding_mask: torch.Tensor,\n    ) -> torch.Tensor:\n        # Compute importance ratio\n        ratio = torch.exp(logprobs - ref_logprobs)\n\n        # Clipped policy gradient\n        clipped_ratio = torch.clamp(\n            ratio,\n            1 - self.clip_range,\n            1 + self.clip_range\n        )\n        pg_loss = -torch.min(ratio * advantages, clipped_ratio * advantages)\n\n        # KL penalty\n        kl = ref_logprobs - logprobs\n\n        # Apply mask and aggregate\n        masked_loss = (pg_loss + self.beta * kl) * padding_mask\n        loss = masked_loss.sum() / padding_mask.sum()\n\n        return loss\n```\n\n### Step 2: Integrate into Application\n\n```python\n# apps/custom/main.py\nfrom forge.losses.custom_loss import CustomLoss\n\nloss_fn = CustomLoss(clip_range=0.2, beta=0.1)\n\n# In training loop\nloss = loss_fn(\n    logprobs=logprobs,\n    ref_logprobs=ref_logprobs,\n    advantages=advantages,\n    padding_mask=padding_mask,\n)\n```\n\n---\n\n## Workflow 3: Multi-GPU Distributed Training\n\nUse this workflow for scaling to multiple GPUs or nodes.\n\n### Configuration for Distributed\n\n```yaml\n# config/distributed.yaml\nmodel: \"meta-llama/Meta-Llama-3.1-8B-Instruct\"\n\nparallelism:\n  tensor_parallel_degree: 2    # Split model across GPUs\n  pipeline_parallel_degree: 1\n  data_parallel_shard_degree: 2\n\nservices:\n  generator:\n    procs: 2                   # 2 processes for TP=2\n    num_replicas: 1\n    with_gpus: true\n  trainer:\n    procs: 2\n    num_replicas: 1\n    with_gpus: true\n```\n\n### Launch with SLURM\n\n```bash\n# Submit job\nsbatch --nodes=2 --gpus-per-node=8 run_grpo.sh\n```\n\n### Launch Locally (Multi-GPU)\n\n```bash\n# 8 GPU setup\npython -m apps.grpo.main \\\n    --config config/distributed.yaml \\\n    --trainer.procs 4 \\\n    --generator.procs 4\n```\n\n---\n\n## Core API Reference\n\n### Training Batch Format\n\ntorchforge uses dictionary-based batches for training:\n\n```python\n# inputs: list of dicts with torch.Tensor values\ninputs = [{\"tokens\": torch.Tensor}]\n\n# targets: list of dicts with training signals\ntargets = [{\n    \"response\": torch.Tensor,\n    \"ref_logprobs\": torch.Tensor,\n    \"advantages\": torch.Tensor,\n    \"padding_mask\": torch.Tensor\n}]\n\n# train_step returns loss as float\nloss = trainer.train_step(inputs, targets)\n```\n\n### Completion\n\nGenerated output from vLLM:\n\n```python\n@dataclass\nclass Completion:\n    text: str              # Generated text\n    token_ids: list[int]   # Token IDs\n    logprobs: list[float]  # Log probabilities\n    metadata: dict         # Custom metadata\n```\n\n---\n\n## Built-in Loss Functions\n\n### Loss Functions\n\nLoss functions are in the `forge.losses` module:\n\n```python\nfrom forge.losses import SimpleGRPOLoss, ReinforceLoss\n\n# SimpleGRPOLoss for GRPO training\nloss_fn = SimpleGRPOLoss(beta=0.1)\n\n# Forward pass\nloss = loss_fn(\n    logprobs=logprobs,\n    ref_logprobs=ref_logprobs,\n    advantages=advantages,\n    padding_mask=padding_mask\n)\n```\n\n### ReinforceLoss\n\n```python\nfrom forge.losses.reinforce_loss import ReinforceLoss\n\n# With optional importance ratio clipping\nloss_fn = ReinforceLoss(clip_ratio=0.2)\n```\n\n---\n\n## Common Issues and Solutions\n\n### Issue: Not Enough GPUs\n\n**Symptoms**: \"Insufficient GPU resources\" error\n\n**Solutions**:\n```yaml\n# Reduce service requirements\nservices:\n  generator:\n    procs: 1\n    with_gpus: true\n  trainer:\n    procs: 1\n    with_gpus: true\n  # Remove ref_model (uses generator weights)\n```\n\nOr use CPU for reference model:\n```yaml\nref_model:\n  with_gpus: false\n```\n\n### Issue: OOM During Generation\n\n**Symptoms**: CUDA OOM in vLLM\n\n**Solutions**:\n```yaml\n# Reduce batch size\ngrpo:\n  n_samples: 4  # Reduce from 8\n\n# Or reduce sequence length\ntraining:\n  seq_len: 2048\n```\n\n### Issue: Slow Weight Sync\n\n**Symptoms**: Long pauses between training and generation\n\n**Solutions**:\n```bash\n# Enable RDMA (if available)\nexport TORCHSTORE_USE_RDMA=1\n\n# Or reduce sync frequency\ntraining:\n  sync_interval: 10  # Sync every 10 steps\n```\n\n### Issue: Policy Collapse\n\n**Symptoms**: Entropy drops to zero, reward stops improving\n\n**Solutions**:\n```yaml\n# Increase KL penalty\ngrpo:\n  beta: 0.2  # Increase from 0.1\n\n# Or add entropy bonus\ntraining:\n  entropy_coef: 0.01\n```\n\n---\n\n## Resources\n\n- **Documentation**: https://meta-pytorch.org/torchforge\n- **GitHub**: https://github.com/meta-pytorch/torchforge\n- **Discord**: https://discord.gg/YsTYBh6PD9\n- **TorchTitan**: https://github.com/pytorch/torchtitan\n- **Monarch**: https://github.com/meta-pytorch/monarch","author":"@Orchestra-Research","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/Orchestra-Research/AI-Research-SKILLs/tree/main/06-post-training/torchforge","license":"MIT","category":"research","lang":"en","tokens":2486,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/api-reference.md","size":8685,"sha256":"ee770cb0e8c3a78f1182cbe432b146d2c68c70c057f1ff8a7ccb72496bca9078"},{"path":"references/troubleshooting.md","size":6709,"sha256":"b920cf91a912f192c14f4ab343780a6abf35932ea419481d7f373f380f379803"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["discord.gg","meta-pytorch.org","pytorch.org"]}}