这一页是进入仓库的第一站:装好环境、注册两个账号、跑通第一次训练,顺带把读后续章节需要的几个概念讲清楚。对应 Datawhale 组队学习的 Task01。
全程不需要 GPU。训练和采样跑在 PyTRIO 的云端 GPU 上,你的电脑只负责数据、reward 和训练循环,一台能够联网的笔记本电脑就足够了。
Windows 用户先看: 下面的命令默认按 macOS / Linux 的 bash 写。Windows 推荐装 Git for Windows,用自带的 Git Bash 直接照抄;继续用 PowerShell 也可以,环境变量、激活和续行的写法在文中单独标注,其余命令一致。
0. 先搞清楚谁在干什么
| 组件 | 跑在哪 | 负责什么 |
|---|---|---|
PyTRIO(pytrio==0.2.9) | 云端 | 前向、反向、优化器更新、采样、权重保存 |
SwanLab(swanlab==0.10.4) | 云端 + 本地日志 | 指标曲线、超参数、终端输出 |
| 本仓库的代码 | 本地 | 数据集、tokenizer、reward、训练循环,把上面两家串起来 |
本地依赖里的 torch 是 CPU 版(pyproject.toml 指定了 pytorch-cpu 源),不要装 CUDA 版。而且它只在写自定义损失函数时才用得上:cross_entropy、importance_sampling、ppo 这些内置 loss 全程在云端算,不碰本地 torch;走 forward_backward_custom(grpo 里的 cispo、DAPO、GSPO 等)时 loss 在本地跑 autograd,才需要它。仓库把 torch 放进基础依赖,是因为好几个章节用自定义 loss,且这些脚本在文件头就 import torch;自己写脚本只用内置 loss 的话,可以不装。
所以你要准备的东西只有三样:一个 Python >= 3.13 的环境(使用 uv 管理)、一个 PyTRIO 账号、一个 SwanLab 账号。
1. 装 uv,同步依赖
安装 uv(装过就跳过):
bash# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows(PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"brew install uv(macOS)或pip install uv也可以。clone 仓库并同步依赖:
bashgit clone https://github.com/datawhalechina/agentic-rl-lab.git cd agentic-rl-lab uv syncuv sync按uv.lock创建.venv并装好全部依赖,版本和仓库完全一致。本地 Python 低于 3.13 时 uv 会自动下载一个合适的版本,不用手动装。记住一件事:仓库里的命令都加
uv run前缀,或者先激活虚拟环境:bash# macOS / Linux source .venv/bin/activate # Windows Git Bash source .venv/Scripts/activate # Windows PowerShell .venv\Scripts\Activate.ps1 # Windows CMD .venv\Scripts\activate.battrio、swanlab这两个可执行文件在.venv里,在系统终端直接敲会报 command not found。PowerShell 提示「禁止运行脚本」时,执行一次Set-ExecutionPolicy -Scope CurrentUser RemoteSigned;也可以不激活,所有命令都用uv run。验证版本:
bashuv run python -c "from importlib.metadata import version; print(version('pytrio'), version('swanlab'))"输出应该是
0.2.9 0.10.4,大于这个版本的都可以~额外依赖按需装:跑 ALFWorld、TEMPO、AgentOPSD 三章需要
uv sync --extra alfworld,其余章节不用。这个 extra 依赖的textworld官方只提供 macOS / Linux 版本;ReTool 的本地沙箱和 Tournament-GRPO 的文件锁也用了 POSIX API。所以这几章在 Windows 原生环境跑不了,需要 WSL2(安装文档);其余章节可以原生运行。
网络不顺畅时(顺畅就跳过):
uv sync慢:uv sync --default-index https://mirrors.cernet.edu.cn/pypi/web/simple。这个参数在 macOS、Linux 和 PowerShell 里写法相同。GSM8K 下载超时:设置镜像后重跑。
bash# macOS / Linux export HF_ENDPOINT=https://hf-mirror.com # Windows PowerShell $env:HF_ENDPOINT = "https://hf-mirror.com"这些环境变量只对当前终端窗口生效;想长期保留,Windows 可以执行
setx HF_ENDPOINT https://hf-mirror.com后重开终端。部分章节的数据走 ModelScope,不需要翻墙,以各章start.md为准。
2. PyTRIO:注册、登录、验证
PyTRIO 是远程后训练服务:本地脚本把数据和 loss 发过去,云端算梯度、更新权重、返回采样结果,思路接近 Tinker 的 Train API。仓库里所有 RL 算法都跑在它上面。
注册和拿 key:
- 打开官网 pytrio.com 用邮箱注册,免费。
pytrio.cn会跳转到这里,是同一个服务。 - 登录后进控制台 pytrio.com/dashboard,复制你的 API Key。
登录:
uv run trio login终端会打印 key 的获取地址和粘贴提示。粘贴 key 时屏幕上什么都不显示,这是正常的,不是卡了,粘完直接回车。成功时长这样:
trio: Login successfully. Hi, <your username>!凭据保存在本地,这台机器之后不用再登录。注意命令是 trio,不是 pytrio。
CI 或脚本等不方便交互的场景,两种替代:
uv run trio login -k YOUR_API_KEY或者直接设置环境变量:
# macOS / Linux
export PYTRIO_API_KEY=YOUR_API_KEY
# Windows PowerShell
$env:PYTRIO_API_KEY = "YOUR_API_KEY"部分章节的评测脚本(如 medical-opd)从自己目录下的 .env 读 PYTRIO_API_KEY;Search-R1 的 DeepSeek 搜索后端还需要 DEEPSEEK_API_KEY,Tournament-GRPO 需要 judge 模型的 key。这些都在各章 start.md 里写明,.env 已被 gitignore,别把 key 提交进仓库。
验证连接(几乎不消耗额度):
uv run python -c "import pytrio as trio; print(*trio.ServiceClient().get_supported_models(), sep='\n')"这一行在 Git Bash、PowerShell 和 CMD 里都能直接粘贴运行。
能打印出 Qwen/Qwen3.5-4B 一类的模型清单就说明通了,清单以服务端实际提供为准。
关于额度:训练和采样消耗 PyTRIO 账户额度,余额和用量在控制台看。本仓库的 demo 都是小参数(几道题、几个采样、十几步),目的是做算法级复现。
卡住了先看官方文档 docs.pytrio.com,从快速开始读起。
3. SwanLab:注册、登录、选模式
SwanLab 负责实验记录:reward 和 loss 曲线、超参数、终端输出都进它。章节之间对比 loss、组队学习交训练记录,靠的都是它。国内服务,不用翻墙。
在 swanlab.cn 注册账号。
登录后到个人设置页复制 API Key:https://swanlab.cn/space/~/settings#development(登录命令也会打印这个地址)。
登录并检查:
bashuv run swanlab login uv run swanlab verify粘贴 key 时同样不回显。上传失败或模式意外回退时,先
uv run swanlab ping查网络。
swanlab.init(mode=...) 有四种模式:
| 模式 | 数据去向 | 什么时候用 |
|---|---|---|
online | 本地 + 云端 | 默认,需要登录 |
local | 仅本地,用 swanlab watch 看 | 不想注册账号 |
offline | 仅本地,之后可 swanlab sync 补传 | 机器暂时没网 |
disabled | 不记录 | 纯跑训练,不看曲线 |
各训练脚本的 --swanlab-mode 可选值略有差别:多数章节四种都有,grpo 的三个脚本只有 online 和 disabled,以 --help 为准。默认都是 online。
组队学习建议直接用 online:作业评审要训练记录链接,离线日志没法直接交。
uv run swanlab watch experiments/grpo/swanlog浏览器打开 http://127.0.0.1:5092。
4. 基础概念:读懂代码的最小词汇表
这里只讲到能读代码的程度,推导和对比在各章正文里。
SFT 与 RL。 SFT 给标准答案,模型按 cross_entropy 学;RL 让模型自己作答,用 reward 打分,把好的回答强化、差的压下去。GRPO 往后的章节都是 RL 或蒸馏,SFT 只在 Spec-o3、Medical OPD 等章节作为热启动出现。
policy、rollout、on-policy。 policy 就是当前正在训练的权重;从 prompt 出发生成一次回答叫一条 rollout。on-policy 指训练数据由当前权重采样而来,所以 demo 每个 step 先存权重拿 sampler、采完再更新。用旧权重采的数据是 off-policy,两者之间的偏差靠下面的重要性比率补偿。
reward。 给一条回答打的分。GSM8K 是 0/1(boxed 答案是否匹配);Search-R1 会加上格式和搜索行为;ALFWorld 看任务是否完成。reward 设计往往比算法本身更影响结果,各章 readme 都会单独解释自己的 reward。
advantage 与组。 GRPO 对同一道题采 group_size 个回答,advantage = reward - 组内平均 reward:比平均好的被鼓励,比平均差的被压低。不需要额外训一个 critic 模型,这是 GRPO 相对 PPO 最大的简化。整组 reward 全相同(全对或全错)时 advantage 全 0,这一组就白采了,也就是日志里的 degenerate group。
old logprobs 与重要性比率。 logprob 是每个 token 的对数概率。同一 token 在新旧 policy 下的概率之比就是重要性采样比率,RL loss 基本都在对这个比率乘 advantage 做文章:ppo 给比率加 clip,cispo 换了 clip 的位置。直觉解释在 Loss Functions 一章,建议读 GRPO 之前先读它。
LoRA 与权重。 不动 base model,只训一个低秩适配器(demo 里 rank 32)。训练结束保存的就是这份适配器:save_weights_for_sampler 存给采样和评测用,save_state 存完整 checkpoint 用于续训。权重地址是 trio:// 形式。
OPD(On-Policy Distillation)。 同样用 student 自己采样的回答,但信号不是 reward:teacher 模型对 student 的回答逐 token 算 logprobs,用 student 与 teacher 的差(reverse KL)当 advantage,相当于老师逐 token 批改。OPSD 再进一步,teacher 就是 step 0 的自己,只是 prompt 里多给了参考解答。见 General OPD、OPSD 两章。
多轮与 observation mask。 Agentic RL 让模型在回答中途调工具:搜索、代码解释器、TextWorld 环境。工具返回的内容(observation)拼进上下文给模型看,但不参与 loss——环境说的话不是模型的动作,不该被强化。代码里体现为这些 token 的 logprobs 和 advantages 填 0。见 Search-R1、ReTool、ALFWorld 三章。
附:命令速查
uv sync # 装 / 恢复依赖
uv run trio login # PyTRIO 登录
uv run swanlab login # SwanLab 登录
uv run swanlab verify # 检查 SwanLab 凭据
uv run python experiments/grpo/01-demo-sync.py --steps 10 --batch-size 4 --group-size 8 --max-tokens 512 --swanlab-mode online # 第一次训练
uv run swanlab watch experiments/grpo/swanlog # 看本地日志训练命令写成一行,是为了在 PowerShell、CMD 和 bash 里都能直接粘贴;bash 里想换行的话用 \,PowerShell 里用反引号 `。