跳到正文
EN

LAB 00 / 开始之前

Getting Started环境配置与基础概念

装好 uv 环境,注册并登录 PyTRIO 与 SwanLab,跑通第一次训练,补齐读懂后续章节所需的基础概念。

查看代码 ↗

这一页是进入仓库的第一站:装好环境、注册两个账号、跑通第一次训练,顺带把读后续章节需要的几个概念讲清楚。对应 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,同步依赖 ​

  1. 安装 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 也可以。

  2. clone 仓库并同步依赖:

    bash
    git clone https://github.com/datawhalechina/agentic-rl-lab.git
    cd agentic-rl-lab
    uv sync

    uv sync 按 uv.lock 创建 .venv 并装好全部依赖,版本和仓库完全一致。本地 Python 低于 3.13 时 uv 会自动下载一个合适的版本,不用手动装。

  3. 记住一件事:仓库里的命令都加 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.bat

    trio、swanlab 这两个可执行文件在 .venv 里,在系统终端直接敲会报 command not found。PowerShell 提示「禁止运行脚本」时,执行一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned;也可以不激活,所有命令都用 uv run。

  4. 验证版本:

    bash
    uv run python -c "from importlib.metadata import version; print(version('pytrio'), version('swanlab'))"

    输出应该是 0.2.9 0.10.4,大于这个版本的都可以~

  5. 额外依赖按需装:跑 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:

  1. 打开官网 pytrio.com 用邮箱注册,免费。pytrio.cn 会跳转到这里,是同一个服务。
  2. 登录后进控制台 pytrio.com/dashboard,复制你的 API Key。

登录:

bash
uv run trio login

终端会打印 key 的获取地址和粘贴提示。粘贴 key 时屏幕上什么都不显示,这是正常的,不是卡了,粘完直接回车。成功时长这样:

text
trio: Login successfully. Hi, <your username>!

凭据保存在本地,这台机器之后不用再登录。注意命令是 trio,不是 pytrio。

CI 或脚本等不方便交互的场景,两种替代:

bash
uv run trio login -k YOUR_API_KEY

或者直接设置环境变量:

bash
# 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 提交进仓库。

验证连接(几乎不消耗额度):

bash
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、组队学习交训练记录,靠的都是它。国内服务,不用翻墙。

  1. 在 swanlab.cn 注册账号。

  2. 登录后到个人设置页复制 API Key:https://swanlab.cn/space/~/settings#development(登录命令也会打印这个地址)。

  3. 登录并检查:

    bash
    uv 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:作业评审要训练记录链接,离线日志没法直接交。

bash
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 三章。

附:命令速查 ​

bash
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 里用反引号 `。

开放代码,记录实验,也记录边界。