训练架构

训练循环

rl_train_epoch() 一个 batch 的处理分四个阶段。与普通 GRPO 相比，核心差异在 Phase 1（多轮 Rollout）和 Phase 2（工具感知奖励）：

# Phase 1: 多轮 Rollout（与GRPO的最大区别）
with torch.no_grad():
    results = rollout_batch(
        rollout_engine, tokenizer, messages_batch,
        tools_batch, num_generations=4, max_turns=3)

# Phase 2: 工具感知奖励（不只是RM打分）
rewards = calculate_rewards(
    prompts, completions, gt_batch, tools_batch,
    num_generations, reward_model)

# Phase 3: 优势计算（与GRPO相同：组内标准化）
advantages = (rewards - mean) / (std + 1e-4)

# Phase 4: CISPO策略更新（与GRPO类似）
# 用 completion_mask 只更新模型生成的 token
# mask=0的工具结果 token 被排除在 loss 之外

精确控制梯度

# 构建流程：
# 1. response_mask 标记: mask=1(模型生成), mask=0(工具结果)
# 2. 找到 EOS 位置，mask 掉 EOS 之后的 token
# 3. 最终：completion_mask = response_mask ∩ (位置<=EOS)

# 效果：只有绿色部分参与梯度
# [prompt(0) | Turn1生成(1) | 工具结果(0) | Turn2生成(1) | ... ]

此外，超长序列会从右侧截断（保留最近的 token，通常是最终回答部分）。所有序列 pad 到 batch 内最大长度后组成 batch 张量。

关键超参数

训练命令

python trainer/train_agent.py \
    --data_path ../dataset/agent_rl.jsonl \
    --from_weight full_sft \
    --save_weight agent \
    --epochs 1 \
    --batch_size 2 \
    --num_generations 4 \
    --learning_rate 3e-7 \
    --loss_type cispo \
    --thinking_ratio 0.1

注意事项：

• --from_weight full_sft：从 SFT 模型开始，不是从 RL 模型开始
• --batch_size 2：因为每个样本要生成 4 次 rollout，实际计算量是 8 倍
• --learning_rate 3e-7：远小于 SFT 的学习率，防止灾难性遗忘

Batch 生命周期

Part 7: 扩展实战

如何添加新工具、评估模型、诊断常见错误。

添加新工具

要添加新工具，需要修改 train_agent.py 中的四个位置：

# 第一步：在 TOOLS 列表中添加工具定义
TOOLS.append({
    "type": "function",
    "function": {
        "name": "search_web",
        "description": "搜索网页",
        "parameters": {"type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]}
    }
})

# 第二步：在 MOCK_RESULTS 中添加执行函数
MOCK_RESULTS["search_web"] = lambda args: {
    "results": [f"搜索结果: {args.get('query')} 的相关信息..."]
}

# 第三步：在 CHECK_ARGS 中添加参数校验
CHECK_ARGS["search_web"] = lambda a: bool(a.get("query"))

# 第四步：更新训练数据 agent_rl.jsonl
# 在 system.tools 中包含新工具的定义，gt 中包含期望答案

扩展注意

评估方法

# 本地模型评估
python scripts/eval_toolcall.py \
    --backend local \
    --load_from ../model \
    --weight agent \
    --hidden_size 768 \
    --num_hidden_layers 8

# API 模式评估（OpenAI 兼容接口）
python scripts/eval_toolcall.py \
    --backend api \
    --api_base_url http://localhost:11434/v1 \
    --api_model jingyaogong/minimind-3:latest

测试用例

常见错误诊断

更多排错

Debug 模式

训练脚本内置了 debug 模式，可以打印每个样本的完整信息：

python trainer/train_agent.py \
    --debug_mode \
    --debug_interval 20 \
    ...

Debug 日志输出示例：

============================== [DEBUG] gen[0][0] CONTEXT_BEGIN ==============================
[系统提示 + 用户问题 + 工具定义]
=============================== [DEBUG] gen[0][0] CONTEXT_END ================================
[DEBUG] gen[0][0] prompt_len=45, seq_len=312
============================ [DEBUG] gen[0][0] COMPLETION_BEGIN [45:312] ============================