企业官网建设流程全解析

本项目 agentic-rl-lab 用 Qwen3.5-4B + PyTRIO 完整复现了 Search-R1 强化学习算法：把 160 GB 的本地检索库换成 DeepSeek 官方 Search API，让大模型在推理过程中自主决定何时搜索、搜什么、何时停止搜索并作答。下文带你用极小的算力与金钱成本，把这套 Agentic RL 训练闭环从数据准备、多轮搜索 rollout 到评测一次跑通。

Search-R1 是什么：让"边搜边想"学进参数里

传统 RAG 的流程是固定的：问题 → 检索一次 → 把结果塞进 prompt → 回答。这对简单事实题够用，但面对多跳问题就不行了。比如问"《小王子》的作者出生在哪个国家？"，模型需要：

1. 先搜The Little Prince author，得到作者 Antoine de Saint-Exupéry；
2. 再搜Antoine de Saint-Exupéry birthplace country，才能回答 France。

Search-R1 的核心变化一句话概括：搜索从回答前的固定步骤，变成了模型在整条推理轨迹中可以反复选择的动作。模型自己生成 query、读取搜索结果、判断信息够不够、决定是否继续搜，最后才作答。

训练时只根据最终答案给 reward：答对得分高、答错得分低、格式不对再扣分。然后同一道题的多条轨迹放在一起比较，比组内平均好的被鼓励、差的被压低——这就是 group-relative advantage（GRPO 家族的思路）。


上图即本项目的 Search-R1 训练总览：上半部分是"多轮搜索 rollout"，Qwen3.5-4B（LoRA 可训练）与固定的搜索引擎交替交互；下半部分是"组相对策略更新"，每道题 8 条轨迹、共 64 条，计算 reward 与 advantage 后用 PyTRIO 更新参数。

注意一个容易误解的点：训练对象是模型的 LoRA 权重，搜索引擎作为固定环境保留。模型学的是"什么时候调用工具、怎么构造 query、怎么用返回的证据"。

为什么选 DeepSeek 官方搜索 API 作为搜索环境

原版 Search-R1 依赖本地 Wikipedia 语料 + E5 检索器：下载解压后约160 GB，检索服务运行还需要约180 GB 内存。对第一次学习 Search-R1 的人来说，还没碰到 reward 和 advantage，就先卡在 Faiss 启动失败、retriever OOM 这些工程问题上。

而 Search-R1 算法本身只要求存在这样一个接口：search(query) → observations。所以本项目把本地检索器替换成可切换的在线搜索服务，实现在 search.py：

DeepSeek 后端直接调用官方POST /v1/tools/search，每次默认取 Top 3 的snippet短摘要（缺失时回退summary），不额外调用模型整理证据、不 Fetch 页面。两个后端共用同一个search(query) → observations接口，对训练算法本身完全透明——模型仍然负责生成 query、判断证据、追加搜索和输出答案。

Search-R1 训练流程如何快速复现：5 步跑通

完整目录与说明见 start.md（快速启动）和 readme.md。

第一步：获取代码并配置环境

git clone https://gitcode.com/gh_mirrors/ag/agentic-rl-lab.git cd agentic-rl-lab uv sync trio login # 登录 PyTRIO 远端训练服务 swanlab login # 实验记录

训练与采样由 PyTRIO 远端完成，本地只需要 CPU 环境，训练侧按实际处理的训练 Token 计费——模型等待搜索 API 的 GPU 空转时间不产生费用，非常适合"环境交互时间长、有效训练时间短"的 Agentic RL 任务。

第二步：下载并整理数据

uv run python 03-search-r1/prepare_data.py

脚本 prepare_data.py 会生成训练集（NQ 79,168 题 + HotpotQA 90,447 题，合计 169,615 题）和固定 70 题的评测集。数据里没有人工标注的搜索 query，也没有写好的推理轨迹——模型只拿到问题，搜索路径由策略自己探索，这是 RL 与 SFT 模仿学习的关键区别。

第三步：配置搜索后端

cp 03-search-r1/.env.example 03-search-r1/.env

在03-search-r1/.env中填入DEEPSEEK_API_KEY=你的key（也兼容DEEPSEEK_KEY）即可使用默认的 DeepSeek 后端；想免密钥运行则加参数--search-backend wikipedia即可。

工具协议定义在 protocol.py：search(query)只有一个字符串参数，system prompt 要求模型"需要证据才搜索、每轮至多调用一次、最终以Answer: <short answer>一行作答"。

第四步：启动 20-step 小规模训练

uv run python 03-search-r1/train.py \ --max-steps 20 \ --questions-per-batch 8 \ --group-size 8 \ --save-every 5 \ --base-model Qwen/Qwen3.5-4B \ --search-backend deepseek \ --swanlab-mode online

每个 step = 8 道题 × 每题 8 条真实多轮搜索轨迹 = 64 条轨迹。关键超参（train.py）：LoRA rank 32、最大搜索 4 次、最大 assistant turns 6、单条轨迹上限 8192 tokens，loss 用importance_sampling。

第五步：评测 Base 与训练后的 checkpoint

# 先评 Base Model uv run python 03-search-r1/eval.py --base-model Qwen/Qwen3.5-4B \ --search-backend deepseek --output eval_result/eval_results_base.jsonl # 再评训练出的 Step 20 权重（训练结束时终端会打印 sampler weights 路径） uv run python 03-search-r1/eval.py \ --model-path 'trio://RUN_ID/sampler_weights/STEP_20_WEIGHTS_NAME' \ --search-backend deepseek --output eval_result/eval_results_rl_step_20.jsonl

评测代码在 eval.py：Base 和 checkpoint 必须使用同一个搜索后端与搜索配置，对 7 个 benchmark 各 10 题计算 Macro EM（精确匹配）和 Format 合规率。想快速核对整条链路，可先加--limit 20。

训练闭环里的三个关键实现细节

细节一：第一轮共享 prompt，搜索后轨迹真正分叉

同一道题第一次采样时 8 条轨迹的 prompt 完全相同，可以一次sample_async(num_samples=8)搞定。但第一轮搜索后，8 条轨迹的 query、observation、下一轮 prompt 各不相同，就必须把每条未结束轨迹独立推进，用多个num_samples=1的请求并发执行。

Search-R1 group rollout 流程：共享根 prompt 与搜索后分叉的轨迹

这个状态机完整实现在 rollout.py：轨迹内部严格串行（生成 → 搜索 → 读 observation → 继续生成），不同轨迹之间并发。既保留了每条 Agent 轨迹的因果顺序，又不会让 64 条轨迹完全串行等待。

细节二：只用最终答案算 Reward，避免 reward hacking

reward.py 只有三档 reward，不给搜索次数、中间 query 加任何人工分数（给搜索次数奖励会诱导模型不停搜索）：

然后在一道题的 8 条轨迹内做 group-relative advantage：A_i = r_i − mean(r_group)。例如一组 reward 均值为 0.225 时，r=1.0的轨迹得到+0.775，r=-0.1的得到-0.325。若整组 reward 相同，所有 advantage 为 0，这一组不提供梯度、跳过更新。

细节三：搜索结果留在上下文，但不参与 Loss

多轮轨迹里混着四类 token：system/user、assistant 的 search(query)、tool observation、assistant 的最终 Answer。模型生成的 assistant token 是"动作"，要参与策略更新；搜索 API 返回的 observation 是"环境状态"，只能当上下文，不能当成模型生成的 token 去训练。

Search-R1 token-level loss mask：只有 assistant 动作 token 携带 advantage

train.py 的build_datum()里无需单独的 mask 字段，直接给 observation token 填零 advantage 和零 old logprob：system/user/tool 位置 advantage = 0，assistant 位置 advantage = 整条轨迹的 advantage。importance_samplingloss 只在 advantage ≠ 0 的位置产生贡献——搜索结果依然影响后续决策，却不会被错误地当成模型动作参与 policy loss。

30-step 训练后的评测结果：模型学会了什么

本次用 DeepSeek 官方 Search API 训练 30 步，在同一套固定 70 题、相同搜索配置下评测 Base 与 Step 30：

两点值得注意：格式合规的回答多了 6 题，说明模型学会了"适时停止搜索并按格式作答"；平均搜索次数从 1.76 升到 2.77，说明模型开始更充分地利用多跳证据。两次评测搜索成功率均为 100%，没有超时或 429。

一条真实 MuSiQue 轨迹的对比更有说服力：Base 模型搜了 4 次却一直没给出最终Answer（reward = -0.1）；Step 50 保留了完整的多跳实体链（John Cabot → child）答对；而 Step 200 搜索链变短后实体链断裂反而答错——搜索更少不等于更好：

Search-R1 真实轨迹对比：Base 与 RL checkpoints 的搜索行为差异

训练时最应该盯住哪些指标

Agentic RL 和纯数学 RL 最大的不同：数学题的 verifier 是确定的，但工具环境会超时、限流、返回空结果——环境质量本身就是实验变量。建议在 SwanLab 里重点盯这几项：

如果reward/correct下跌同时search/error_rate上升，先查环境，再下"模型退化"的结论。

小结：这条复现路径的边界在哪里

• 本文聚焦 Search-R1 核心算法闭环（问题、工具、环境交互、group-relative advantage、retrieved-token mask、policy update），未逐项还原原论文 160 GB 检索基础设施，绝对分数不能与论文直接比较；
• 评测集为固定 70 题，适合观察行为变化，正式结论需要更大评测集与多随机种子；
• DeepSeek 与 Wikipedia 后端、新旧 Evidence 接入属于不同搜索环境，只能在各自相同环境内比较 checkpoint。

在这些边界内，这套复现把 Search-R1 的入门门槛降到了普通开发者的水平：本地只需 CPU，写的是普通 Python（数据、工具环境、rollout 状态机、reward、advantage），采样与训练交给 PyTRIO 远端。当你真正需要论文级指标时，再把search(query)换回本地 Wikipedia retriever 即可——算法接口不变。

完整代码见 03-search-r1/ 目录：data.py、protocol.py、search.py、rollout.py、reward.py、train.py、eval.py、analyse.py，建议按 start.md 的顺序动手跑一遍。