@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/mlops/training/trl-fine-tuning/references/grpo-training.md

@@ -0,0 +1,504 @@
+# GRPO (Group Relative Policy Optimization) — 深度指南
+
+使用 TRL 的 `GRPOTrainer` 和自定义奖励函数微调语言模型的专家级模式、关键见解和生产就绪工作流。这是主技能中总结的 GRPO 工作流的深度参考。
+
+## 何时使用 GRPO
+
+在以下情况使用 GRPO：
+- **强制特定输出格式**（XML 标签、JSON、结构化推理）
+- **教授可验证的任务**，具有客观正确性指标（数学、代码、事实核查）
+- **通过奖励思维链模式提升推理能力**
+- **将模型对齐到特定领域行为**，而无需标注偏好数据
+- **同时优化多个目标**（格式 + 正确性 + 风格）
+
+**不要将 GRPO 用于：**
+- 简单的监督微调任务 → 使用 SFT
+- 没有明确奖励信号的任务
+- 当你已经有高质量偏好对时 → 使用 DPO/PPO
+
+## 核心概念
+
+### 1. GRPO 算法基础
+
+**关键机制：**
+- 为每个 prompt 生成**多个 completion**（组大小：4–16）
+- 使用奖励函数比较每个组内的 completion
+- 更新 policy 以偏向相对于该组获得更高奖励的响应
+
+**与 PPO 的关键区别：**
+- 不需要单独的 reward model
+- 样本效率更高（从组内比较中学习）
+- 实现和调试更简单
+
+**数学直觉：**
+```
+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. 奖励函数设计理念
+
+**黄金法则：**
+1. **组合多个奖励函数** —— 每个函数处理一个方面（格式、正确性、风格）
+2. **适当缩放奖励** —— 权重越高 = 信号越强
+3. **使用增量奖励** —— 部分合规获得部分分数
+4. **独立测试奖励** —— 独立调试每个奖励函数
+
+**奖励函数类型：**
+
+| 类型 | 使用场景 | 示例权重 |
+|------|----------|----------------|
+| **正确性** | 可验证任务（数学、代码） | 2.0（最高） |
+| **格式** | 严格结构强制要求 | 0.5–1.0 |
+| **长度** | 鼓励详尽/简洁 | 0.1–0.5 |
+| **风格** | 惩罚不需要的模式 | −0.5 到 0.5 |
+
+## 实现工作流
+
+### 步骤 1：数据集准备
+
+**关键要求：**
+- 采用聊天格式的 prompt（包含 `role` 和 `content` 的字典列表）
+- 包含 system prompt 以设定预期
+- 对于可验证任务，将真实答案作为附加列包含在内
+
+```python
+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'])
+    })
+```
+
+**专业提示：**
+- 对于复杂格式，在 system prompt 中使用单样本或少样本示例
+- 保持 prompt 简洁（max_prompt_length：256–512 tokens）
+- 在训练前验证数据质量（垃圾进 = 垃圾出）
+
+### 步骤 2：奖励函数实现
+
+**模板结构：**
+```python
+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 (one per completion)."""
+    responses = [comp[0]['content'] for comp in completions]
+    rewards = []
+    for response in responses:
+        score = compute_score(response)
+        rewards.append(score)
+    return rewards
+```
+
+**示例 1：correctness reward（数学/代码）**
+```python
+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)]
+```
+
+**示例 2：format reward（结构化输出）**
+```python
+import re
+
+def format_reward(completions, **kwargs):
+    """Reward XML-like structured format."""
+    pattern = r'<reasoning>.*?</reasoning>\s*<answer>.*?</answer>'
+    responses = [comp[0]['content'] for comp in completions]
+    return [1.0 if re.search(pattern, r, re.DOTALL) else 0.0
+            for r in responses]
+```
+
+**示例 3：incremental format reward（部分分数）**
+```python
+def incremental_format_reward(completions, **kwargs):
+    """Award partial credit for format compliance."""
+    responses = [comp[0]['content'] for comp in completions]
+    rewards = []
+
+    for r in responses:
+        score = 0.0
+        if '<reasoning>' in r:  score += 0.25
+        if '</reasoning>' in r: score += 0.25
+        if '<answer>' in r:     score += 0.25
+        if '</answer>' in r:    score += 0.25
+        # Penalize extra text after closing tag
+        if r.count('</answer>') == 1:
+            extra_text = r.split('</answer>')[-1].strip()
+            score -= len(extra_text) * 0.001
+        rewards.append(score)
+
+    return rewards
+```
+
+**关键见解：** 组合 3–5 个奖励函数以实现稳健训练。顺序的重要性不如信号的多样性。
+
+### 步骤 3：训练配置
+
+**内存优化配置（小型 GPU）**
+```python
+from trl import GRPOConfig
+
+training_args = GRPOConfig(
+    output_dir="outputs/grpo-model",
+
+    # Learning rate
+    learning_rate=5e-6,          # Lower = more stable
+    adam_beta1=0.9,
+    adam_beta2=0.99,
+    weight_decay=0.1,
+    warmup_ratio=0.1,
+    lr_scheduler_type='cosine',
+
+    # Batch settings
+    per_device_train_batch_size=1,
+    gradient_accumulation_steps=4,  # Effective batch = 4
+
+    # GRPO-specific
+    num_generations=8,            # Group size: 8–16 recommended
+    max_prompt_length=256,
+    max_completion_length=512,
+
+    # Training duration
+    num_train_epochs=1,
+    max_steps=None,
+
+    # Optimization
+    bf16=True,                    # Faster on A100/H100
+    optim="adamw_8bit",          # Memory-efficient optimizer
+    max_grad_norm=0.1,
+
+    # Logging
+    logging_steps=1,
+    save_steps=100,
+    report_to="wandb",
+)
+```
+
+**高性能配置（大型 GPU）**
+```python
+training_args = GRPOConfig(
+    output_dir="outputs/grpo-model",
+    learning_rate=1e-5,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=2,
+    num_generations=16,           # Larger groups = better signal
+    max_prompt_length=512,
+    max_completion_length=1024,
+    num_train_epochs=1,
+    bf16=True,
+    use_vllm=True,                # Fast generation with vLLM
+    logging_steps=10,
+)
+```
+
+**关键超参数：**
+
+| 参数 | 影响 | 调参建议 |
+|-----------|--------|---------------|
+| `num_generations` | 比较的组大小 | 从 8 开始，如果 GPU 允许增加到 16 |
+| `learning_rate` | 收敛速度/稳定性 | 5e-6（安全），1e-5（更快，风险较高） |
+| `max_completion_length` | 输出详尽程度 | 与你的任务匹配（推理 512，简短回答 256） |
+| `gradient_accumulation_steps` | 有效 batch size | 如果 GPU 内存有限则增加 |
+
+### 步骤 4：模型设置与训练
+
+**标准设置（Transformers + TRL）**
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import LoraConfig
+from trl import GRPOTrainer
+
+model_name = "Qwen/Qwen2.5-1.5B-Instruct"
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype=torch.bfloat16,
+    attn_implementation="flash_attention_2",  # 2–3× faster
+    device_map="auto",
+)
+
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+tokenizer.pad_token = tokenizer.eos_token
+
+# Optional: LoRA for parameter-efficient training
+peft_config = LoraConfig(
+    r=16,
+    lora_alpha=32,
+    target_modules=[
+        "q_proj", "k_proj", "v_proj", "o_proj",
+        "gate_proj", "up_proj", "down_proj",
+    ],
+    task_type="CAUSAL_LM",
+    lora_dropout=0.05,
+)
+
+trainer = GRPOTrainer(
+    model=model,
+    processing_class=tokenizer,
+    reward_funcs=[
+        incremental_format_reward,
+        format_reward,
+        correctness_reward,
+    ],
+    args=training_args,
+    train_dataset=dataset,
+    peft_config=peft_config,   # Remove for full fine-tuning
+)
+
+trainer.train()
+trainer.save_model("final_model")
+```
+
+**Unsloth 设置（快 2–3 倍）**
+```python
+from unsloth import FastLanguageModel
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name="google/gemma-3-1b-it",
+    max_seq_length=1024,
+    load_in_4bit=True,
+    fast_inference=True,
+    max_lora_rank=32,
+)
+
+model = FastLanguageModel.get_peft_model(
+    model,
+    r=32,
+    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
+                    "gate_proj", "up_proj", "down_proj"],
+    lora_alpha=32,
+    use_gradient_checkpointing="unsloth",
+)
+
+# Rest is identical to the standard setup
+trainer = GRPOTrainer(model=model, ...)
+trainer.train()
+```
+
+## 关键训练见解
+
+### 1. 损失行为（预期模式）
+- **损失从接近 0 开始并在训练期间上升** —— 这是正确的
+- 损失衡量与初始 policy 的 KL 散度；模型正在学习（偏离原始行为以优化奖励）
+- **通过监控奖励指标而非损失来判断进度**
+
+### 2. 奖励跟踪
+
+需要关注的关键指标：
+- `reward` —— 所有 completion 的平均值
+- `reward_std` —— 组内多样性（应保持 > 0）
+- `kl` —— 与参考的 KL 散度（应适度增长）
+
+**健康模式：**
+```
+Step   Reward    Reward_Std   KL
+100    0.5       0.3          0.02
+200    0.8       0.25         0.05
+300    1.2       0.2          0.08  ← Good progression
+400    1.5       0.15         0.12
+```
+
+**警告信号：**
+- `reward_std` → 0（模型坍缩到单一响应）
+- `kl` 爆炸（> 0.5）—— 偏差过大，降低 LR
+- 奖励停滞 —— 奖励函数过于苛刻或模型容量问题
+
+### 3. 常见陷阱与解决方案
+
+| 问题 | 症状 | 解决方案 |
+|---------|---------|----------|
+| **模式坍缩** | 所有 completion 相同 | 增加 `num_generations`，添加多样性惩罚 |
+| **没有学习** | 奖励持平 | 检查奖励函数逻辑，增加 LR |
+| **OOM 错误** | GPU 内存溢出 | 减少 `num_generations`，启用 gradient checkpointing |
+| **训练缓慢** | < 1 it/s | 启用 `use_vllm=True`，使用 Unsloth，减少序列长度 |
+| **忽略格式** | 模型不遵循结构 | 增加格式奖励权重，添加增量奖励 |
+
+## 高级模式
+
+### 1. 多阶段训练
+
+对于复杂任务，分阶段训练：
+
+```python
+# Stage 1: Format compliance
+trainer_stage1 = GRPOTrainer(
+    model=model,
+    reward_funcs=[incremental_format_reward, format_reward],
+    ...
+)
+trainer_stage1.train()
+
+# Stage 2: Correctness
+trainer_stage2 = GRPOTrainer(
+    model=model,
+    reward_funcs=[format_reward, correctness_reward],
+    ...
+)
+trainer_stage2.train()
+```
+
+### 2. 自适应奖励缩放
+
+```python
+class AdaptiveReward:
+    def __init__(self, base_reward_func, initial_weight=1.0):
+        self.func = base_reward_func
+        self.weight = initial_weight
+
+    def __call__(self, *args, **kwargs):
+        rewards = self.func(*args, **kwargs)
+        return [r * self.weight for r in rewards]
+
+    def adjust_weight(self, success_rate):
+        """Increase weight if model struggling, decrease if succeeding."""
+        if success_rate < 0.3:
+            self.weight *= 1.2
+        elif success_rate > 0.8:
+            self.weight *= 0.9
+```
+
+### 3. 自定义数据集集成
+
+```python
+def load_custom_knowledge_base(csv_path):
+    import pandas as pd
+    df = pd.read_csv(csv_path)
+    return Dataset.from_pandas(df).map(lambda x: {
+        'prompt': [
+            {'role': 'system', 'content': CUSTOM_SYSTEM_PROMPT},
+            {'role': 'user', 'content': x['question']}
+        ],
+        'answer': x['expert_answer']
+    })
+```
+
+## 部署与推理
+
+### 保存与合并 LoRA
+```python
+if hasattr(trainer.model, 'merge_and_unload'):
+    merged_model = trainer.model.merge_and_unload()
+    merged_model.save_pretrained("production_model")
+    tokenizer.save_pretrained("production_model")
+```
+
+### 推理
+```python
+from transformers import pipeline
+
+generator = pipeline("text-generation", model="production_model", tokenizer=tokenizer)
+
+result = generator(
+    [
+        {'role': 'system', 'content': SYSTEM_PROMPT},
+        {'role': 'user', 'content': "What is 15 + 27?"},
+    ],
+    max_new_tokens=256,
+    do_sample=True,
+    temperature=0.7,
+    top_p=0.9,
+)
+print(result[0]['generated_text'])
+```
+
+## 最佳实践清单
+
+**训练前：**
+- [ ] 验证数据集格式（prompt 为 List[Dict]）
+- [ ] 在样本数据上测试奖励函数
+- [ ] 从数据中计算预期的 `max_prompt_length`
+- [ ] 根据 GPU 内存选择 `num_generations`
+- [ ] 设置日志记录（推荐 wandb）
+
+**训练中：**
+- [ ] 监控奖励进展（应增加）
+- [ ] 检查 `reward_std`（应保持 > 0.1）
+- [ ] 注意 OOM 错误（如有需要，减少 batch size）
+- [ ] 每 50–100 步抽样生成结果
+- [ ] 在留存集上验证格式合规性
+
+**训练后：**
+- [ ] 如果使用 PEFT，合并 LoRA 权重
+- [ ] 在多样化 prompt 上进行测试
+- [ ] 与基线模型进行比较
+- [ ] 记录奖励权重和超参数
+- [ ] 保存可复现的配置
+
+## 故障排查
+
+### 调试工作流
+1. **隔离奖励函数** —— 独立测试每个函数
+2. **检查数据分布** —— 确保 prompt 的多样性
+3. **降低复杂性** —— 从单一奖励开始，逐渐增加
+4. **监控生成结果** —— 每 N 步打印样本
+5. **验证提取逻辑** —— 确保答案解析正常工作
+
+### 快速 debug reward
+```python
+def debug_reward(completions, **kwargs):
+    responses = [comp[0]['content'] for comp in completions]
+    for i, r in enumerate(responses[:2]):
+        print(f"Response {i}: {r[:200]}...")
+    return [1.0] * len(responses)
+
+# Test without training
+trainer = GRPOTrainer(..., reward_funcs=[debug_reward])
+trainer.generate_completions(dataset[:1])
+```
+
+## 模板
+
+生产就绪的训练脚本位于 **`../templates/basic_grpo_training.py`**。它在 GSM8K 上使用 Qwen 2.5-1.5B-Instruct 结合 LoRA 以及三个奖励函数（增量格式、严格格式、正确性）。复制并调整以下内容：
+1. `get_dataset()` —— 替换为你的数据加载器
+2. 奖励函数 —— 根据你的任务进行调整
+3. `SYSTEM_PROMPT` —— 与你的输出格式匹配
+4. `GRPOConfig` —— 为你的 GPU 调整超参数
+
+## 参考资料与资源
+
+- TRL GRPO Trainer：https://huggingface.co/docs/trl/grpo_trainer
+- GRPO 论文：https://arxiv.org/abs/2402.03300
+- DeepSeek R1 论文：https://arxiv.org/abs/2501.12948
+- Open R1 实现：https://github.com/huggingface/open-r1
+- TRL 示例：https://github.com/huggingface/trl/tree/main/examples
+- Unsloth（更快的训练）：https://docs.unsloth.ai/
+
+## 关键提醒
+
+- **训练期间损失会上升** —— 这是正常的（它是 KL 散度）
+- **使用 3–5 个奖励函数** —— 单一奖励通常会失败
+- **训练前测试奖励** —— 独立调试每个函数
+- **监控 `reward_std`** —— 应保持在 > 0.1（避免模式坍缩）
+- **从 `num_generations=4–8` 开始** —— 如果 GPU 允许则增加

package/extensions/skills/optional/mlops/training/trl-fine-tuning/references/online-rl.md

@@ -0,0 +1,82 @@
+# Online RL 方法
+
+PPO、GRPO、RLOO 和 OnlineDPO 的在线强化学习指南。
+
+## 概览
+
+Online RL 在训练过程中生成 completions，并根据 rewards 进行优化。
+
+## PPO (Proximal Policy Optimization)
+
+用于 LLM 对齐的经典 RL 算法。
+
+### 基础 用途
+
+```bash
+python -m trl.scripts.ppo \
+    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
+    --reward_model_path reward-model \
+    --dataset_name trl-internal-testing/descriptiveness-sentiment-trl-style \
+    --output_dir model-ppo \
+    --learning_rate 3e-6 \
+    --per_device_train_batch_size 64 \
+    --total_episodes 10000 \
+    --num_ppo_epochs 4 \
+    --kl_coef 0.05
+```
+
+### 关键参数
+
+- `kl_coef`: KL penalty (0.05-0.2)
+- `num_ppo_epochs`: 每个 batch 的 epochs (2-4)
+- `cliprange`: PPO clip (0.1-0.3)
+- `vf_coef`: Value function 系数 (0.1)
+
+## GRPO (Group Relative Policy Optimization)
+
+内存高效的 online RL。
+
+### 基础 用途
+
+```python
+from trl import GRPOTrainer, GRPOConfig
+from datasets import load_dataset
+
+# 定义奖励函数
+def reward_func(completions, **kwargs):
+    return [len(set(c.split())) for c in completions]
+
+config = GRPOConfig(
+    output_dir="model-grpo",
+    num_generations=4,  # 每个 prompt 的 completions
+    max_new_tokens=128
+)
+
+trainer = GRPOTrainer(
+    model="Qwen/Qwen2-0.5B-Instruct",
+    reward_funcs=reward_func,
+    args=config,
+    train_dataset=load_dataset("trl-lib/tldr", split="train")
+)
+trainer.train()
+```
+
+### 关键参数
+
+- `num_generations`: 2-8 个 completions
+- `max_new_tokens`: 64-256
+- Learning rate: 1e-5 到 1e-4
+
+## 内存比较
+
+| 方法 | Memory (7B) | 速度 | 适用场景 |
+| -------- | ------------- | ------- | ---------- |
+| PPO | 40GB | 中等 | 最大化控制 |
+| GRPO | 24GB | 快 | **内存受限** |
+| OnlineDPO | 28GB | 快 | 无需 reward model |
+
+## 参考资料
+
+- PPO 论文: https://arxiv.org/abs/1707.06347
+- GRPO 论文: https://arxiv.org/abs/2402.03300
+- TRL 文档: https://huggingface.co/docs/trl/

package/extensions/skills/optional/mlops/training/trl-fine-tuning/references/reward-modeling.md

@@ -0,0 +1,122 @@
+# Reward Modeling
+
+使用 TRL 为 RLHF pipeline 训练 reward model 的指南。
+
+## 概览
+
+Reward model 根据人类偏好对 completion 进行评分。常用于：
+- PPO training（RL feedback）
+- GRPO online RL
+- Completion ranking
+
+## 基础 Training
+
+```python
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+from trl import RewardTrainer, RewardConfig
+from datasets import load_dataset
+
+# 加载模型 (num_labels=1 用于单一奖励分数)
+model = AutoModelForSequenceClassification.from_pretrained(
+    "Qwen/Qwen2.5-0.5B-Instruct",
+    num_labels=1
+)
+tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
+
+# 加载偏好数据集 (chosen/rejected 对)
+dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
+
+# 配置
+config = RewardConfig(
+    output_dir="Qwen2.5-Reward",
+    per_device_train_batch_size=2,
+    num_train_epochs=1,
+    learning_rate=1e-5
+)
+
+# 训练
+trainer = RewardTrainer(
+    model=model,
+    args=config,
+    processing_class=tokenizer,
+    train_dataset=dataset
+)
+trainer.train()
+```
+
+## Dataset Format
+
+必填字段：
+```json
+{
+  "prompt": "Question or instruction",
+  "chosen": "Better response",
+  "rejected": "Worse response"
+}
+```
+
+## Bradley-Terry Loss
+
+默认 loss function：
+```
+loss = -log(sigmoid(reward_chosen - reward_rejected))
+```
+
+学习为 chosen 评分高于 rejected。
+
+## 使用 Reward Models
+
+### Inference
+
+```python
+from transformers import pipeline
+
+# 加载训练好的 reward model
+reward_pipe = pipeline("text-classification", model="Qwen2.5-Reward")
+
+# 为 completion 评分
+texts = ["Good answer", "Bad answer"]
+scores = reward_pipe(texts)
+print(scores)  # 分数越高 = 越好
+```
+
+### 在 PPO 中
+
+```python
+from trl import PPOTrainer, PPOConfig
+
+config = PPOConfig(
+    reward_model_path="Qwen2.5-Reward"  # 使用训练好的 reward model
+)
+
+trainer = PPOTrainer(
+    model=policy_model,
+    config=config,
+    # Reward model 会自动加载
+)
+```
+
+## Hyperparameters
+
+| Model Size | Learning Rate | Batch Size | Epochs |
+| ------------ | --------------- | ------------ | -------- |
+| <1B | 2e-5 | 4-8 | 1-2 |
+| 1-7B | 1e-5 | 2-4 | 1 |
+| 7-13B | 5e-6 | 1-2 | 1 |
+
+## Evaluation
+
+检查 reward 分离情况：
+```python
+# chosen 的得分应该高于 rejected
+chosen_rewards = model(**chosen_inputs).logits
+rejected_rewards = model(**rejected_inputs).logits
+
+accuracy = (chosen_rewards > rejected_rewards).float().mean()
+print(f"Accuracy: {accuracy:.2%}")  # 目标: >80%
+```
+
+## 参考资料
+
+- InstructGPT 论文: https://arxiv.org/abs/2203.02155
+- TRL 文档: https://huggingface.co/docs/trl/reward_trainer