/grpo-rl-training

description: Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific
  model training
version: 1.0.0
author: Orchestra Research
license: MIT
dependencies:
- transformers>=4.47.0
- trl>=0.14.0
- datasets>=3.2.0
- peft>=0.14.0
- torch
metadata:
  catalog:
    tags:
    - Post-Training
    - Reinforcement Learning
    - GRPO
    - TRL
    - RLHF
    - Reward Modeling
    - Reasoning
    - DPO
    - PPO
    - Structured Output

Kheish Compatibility

This skill is repo-local and stays inactive until explicitly activated.

When the original instructions refer to legacy tool names, use these Kheish mappings:

• `terminal` => `bash`
• `web_extract` => `web_fetch`, plus `web_search` when discovery is needed
• `search_files` => `grep_search` and `glob_search`
• `browser_*` tools require a browser-capable surfaced tool or MCP; if none is available, use the closest available surface and say so explicitly

When the instructions mention local helper files, resolve them from `${KHEISH_SKILL_DIR}`.

GRPO/RL Training with TRL

Expert-level guidance for implementing Group Relative Policy Optimization (GRPO) using the Transformer Reinforcement Learning (TRL) library. This skill provides battle-tested patterns, critical insights, and production-ready workflows for fine-tuning language models with custom reward functions.

When to Use This Skill

Use GRPO training when you need to:

• **Enforce specific output formats** (e.g., XML tags, JSON, structured reasoning)
• **Teach verifiable tasks** with objective correctness metrics (math, coding, fact-checking)
• **Improve reasoning capabilities** by rewarding chain-of-thought patterns
• **Align models to domain-specific behaviors** without labeled preference data
• **Optimize for multiple objectives** simultaneously (format + correctness + style)

**Do NOT use GRPO for:**

• Simple supervised fine-tuning tasks (use SFT instead)
• Tasks without clear reward signals
• When you already have high-quality preference pairs (use DPO/PPO instead)

---

Core Concepts

1. GRPO Algorithm Fundamentals

**Key Mechanism:**

• Generates **multiple completions** for each prompt (group size: 4-16)
• Compares completions within each group using reward functions
• Updates policy to favor higher-rewarded responses relative to the group

**Critical Difference from PPO:**

• No separate reward model needed
• More sample-efficient (learns from within-group comparisons)
• Simpler to implement and debug

**Mathematical Intuition:**

For each prompt p:
  1. Generate N completions: {c₁, c₂, ..., cₙ}
  2. Compute rewards: {r₁, r₂, ..., rₙ}
  3. Learn to increase probability of high-reward completions
     relative to low-reward ones in the same group

2. Reward Function Design Philosophy

**Golden Rules:** 1. **Compose multiple reward functions** - Each handles one aspect (format, correctness, style) 2. **Scale rewards appropriately** - Higher weight = stronger signal 3. **Use incremental rewards** - Partial credit for partial compliance 4. **Test rewards independently** - Debug each reward function in isolation

**Reward Function Types:**

| Type | Use Case | Example Weight | |------|----------|----------------| | **Correctness** | Verifiable tasks (math, code) | 2.0 (highest) | | **Format** | Strict structure enforcement | 0.5-1.0 | | **Length** | Encourage verbosity/conciseness | 0.1-0.5 | | **Style** | Penalize unwanted patterns | -0.5 to 0.5 |

---

Implementation Workflow

Step 1: Dataset Preparation

**Critical Requirements:**

• Prompts in chat format (list of dicts with 'role' and 'content')
• Include system prompts to set expectations
• For verifiable tasks, include ground truth answers as additional columns

**Example Structure:**

from datasets import load_dataset, Dataset

SYSTEM_PROMPT = """
Respond in the following format:
<reasoning>
[Your step-by-step thinking]
</reasoning>
<answer>
[Final answer]
</answer>
"""

def prepare_dataset(raw_data):
    """
    Transform raw data into GRPO-compatible format.

    Returns: Dataset with columns:
    - 'prompt': List[Dict] with role/content (system + user messages)
    - 'answer': str (ground truth, optional but recommended)
    """
    return raw_data.map(lambda x: {
        'prompt': [
            {'role': 'system', 'content': SYSTEM_PROMPT},
            {'role': 'user', 'content': x['question']}
        ],
        'answer': extract_answer(x['raw_answer'])
    })

**Pro Tips:**

• Use one-shot or few-shot examples in system prompt for complex formats
• Keep prompts concise (max_prompt_length: 256-512 tokens)
• Validate data quality before training (garbage in = garbage out)

Step 2: Reward Function Implementation

**Template Structure:**

def reward_function_name(
    prompts,        # List[List[Dict]]: Original prompts
    completions,    # List[List[Dict]]: Model generations
    answer=None,    # Optional: Ground truth from dataset
    **kwargs        # Additional dataset columns
) -> list[float]:
    """
    Evaluate completions and return rewards.

    Returns: List of floats (one per completion)
    """
    # Extract completion text
    responses = [comp[0]['content'] for comp in completions]

    # Compute rewards
    rewards = []
    for response in responses:
        score = compute_score(response)
        rewards.append(score)

    return rewards

**Example 1: Correctness Reward (Math/Coding)**

def correctness_reward(prompts, completions, answer, **kwargs):
    """Reward correct answers with high score."""
    responses = [comp[0]['content'] for comp in completions]
    extracted = [extract_final_answer(r) for r in responses]
    return [2.0 if ans == gt else 0.0
            for ans, gt in zip(extracted, answer)]

**Example 2: Format Reward (Structured Output)**

import re

def format_reward(completions, **kwargs):
    """Reward XML-like structured format."""
    pattern = r'<reasoning>.*?</reasoning>\s*<answer