Chapter 17
学习与环境准备
学习与环境准备
Happy-LLM 以教程阅读为主、代码实践为辅。为了降低环境冲突，建议读者按照章节分别准备依赖，而不是在同一个环境中安装全部依赖。
第八章使用 PyTRIO 完成远端模型采样、前向反向传播和参数更新，本地程序负责数据处理、搜索环境、代码执行环境与训练调度。因此，第八章可以在可联网的 CPU 设备上学习和试跑，但需要 TRIO 账号、稳定的网络连接与可用额度。
1. 阅读与实践建议
- 第 1 章到第 4 章以原理学习为主，推荐先完整阅读正文，再选择性复现代码。
- 第 5 章到第 8 章以实践为主，建议结合章节正文、代码目录和对应依赖一起学习。
- 如果你的设备资源有限，建议优先复现第 5 章的手写实现，以及第 6 章中的数据处理与单卡调试流程。
- 学习第 8 章时，建议先运行 GRPO 与 OPD 的同步版，再进入 Search-R1 和 ReTool 的多文件 Agentic RL 工程。
2. 分章环境说明
| 章节 | 主要内容 | 依赖文件 | 硬件建议 |
|---|---|---|---|
| 第二章 Transformer 架构 | Transformer 手写实现 | ./chapter2/code/requirements.txt | CPU 或单卡 GPU |
| 第五章 动手搭建大模型 | 手写 LLaMA2、Tokenizer、预训练与 SFT | ./chapter5/code/requirements.txt | 单卡 GPU，部分步骤可先在 CPU 调试 |
| 第六章 大模型训练流程实践 | Transformers、DeepSpeed、PEFT 训练实践 | ./chapter6/code/requirements.txt | 建议多卡 GPU，最小可从小样本和单卡调试开始 |
| 第七章 大模型应用 - RAG | 检索增强生成 | ./chapter7/RAG/requirements.txt | CPU 可体验，向量检索建议预留更多内存 |
| 第七章 大模型应用 - Agent | 智能体与工具调用 | ./chapter7/Agent/requirements.txt | CPU 可体验，联网能力按具体工具配置 |
| 第八章 Agentic-RL | GRPO、OPD、Search-R1、ReTool | ./chapter8/requirements.txt | 本地 CPU 与稳定网络即可；需要 TRIO 账号，ReTool 需隔离执行环境 |
3. 通用准备步骤
第 2 章到第 7 章建议优先使用 Python 3.10 或 3.11；第 8 章配套代码使用 Python 3.13，并通过 ./chapter8/requirements.txt 固定 PyTRIO 等依赖。请为不同章节创建独立虚拟环境。以第六章为例，可以按如下方式准备：
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r ./docs/chapter6/code/requirements.txt如果你需要复现其他章节，请将最后一行中的依赖文件替换为该章节对应的 requirements.txt。
4. 第六章快速开始
第六章正文聚焦 Pretrain、SFT 和高效微调三条主线，建议和 ./chapter6/readme.md 一起阅读。代码目录位于 ./chapter6/code。
推荐按以下顺序实践：
- 先阅读
./chapter6/readme.md，明确模型、数据和脚本入口。 - 使用
./chapter6/code/download_model.py下载基座模型。 - 使用
./chapter6/code/download_dataset.py下载或准备训练数据。 - 先用小样本调试
./chapter6/code/pretrain.py或./chapter6/code/finetune.py。 - 最后再结合
./chapter6/code/pretrain.sh与./chapter6/code/finetune.sh进行完整训练。
需要注意的是，脚本中的 autodl-tmp 路径、显卡编号和 DeepSpeed 参数都是示例配置，正式运行前请根据本地环境自行调整。
5. 第八章快速开始
第八章正文位于 ./chapter8/第八章 大模型强化学习.md，公共依赖位于 ./chapter8/requirements.txt。以下命令均应从 Happy-LLM 仓库根目录执行。
费用提示： PyTRIO 会在远端执行模型采样与训练，并按照实际使用量产生费用。第一次运行请保留各示例 README 中的单步、小 batch 和短轨迹配置，确认完整链路后再扩大实验规模。
安全提示： ReTool 会在本地执行模型生成的 Python 代码。配套
sandbox.py只能限制部分资源，无法提供可信隔离。请使用一次性容器、低权限虚拟机或专用沙箱服务，并移除环境中的 API Key、SSH 配置和云服务凭证。
5.1 创建独立环境
推荐为第八章单独创建 Python 3.13 环境：
uv venv --python 3.13
source .venv/bin/activate
uv pip install -r docs/chapter8/requirements.txt如果尚未安装 uv，可以先执行 python -m pip install --upgrade uv。Windows PowerShell 使用 .\.venv\Scripts\Activate.ps1 激活环境。安装完成后，可以确认本章锁定的 PyTRIO 版本：
python -c "from importlib.metadata import version; print(version('pytrio'))"5.2 登录并验证连接
登录 TRIO 后，读取当前服务支持的模型列表：
trio login
python -c "import pytrio as trio; print(trio.ServiceClient().get_supported_models())"能够正常打印模型列表，说明 PyTRIO 安装、账号认证和网络连接均已就绪。只有需要在线记录实验时才需要额外执行 swanlab login；使用示例中的 --swanlab-mode disabled 可以先关闭远端实验记录。安装或登录遇到问题时，可以参考 PyTRIO 官方快速开始。
5.3 推荐实践顺序
| 模块 | 建议入口 | 额外准备 |
|---|---|---|
| GRPO | ./chapter8/grpo/README.md | 先运行同步版一步试验；GSM8K 会在首次运行时下载 |
| OPD | ./chapter8/opd/README.md | 先使用一个 DeepMath 分片，并确认 Student 与 Teacher 模型当前可用 |
| Search-R1 | ./chapter8/search-r1/README.md | 先准备数据并使用无需 API Key 的 Wikipedia 后端验证多轮搜索链路 |
| ReTool | ./chapter8/retool/README.md | 先准备数据和隔离执行环境，再运行一步 PPO 训练 |
正文重点讲解 GRPO 与 OPD 的同步版，异步版保留相同算法和数据对齐方式；Search-R1 与 ReTool 按数据、协议、环境、rollout、训练和评测拆成多文件工程。想继续学习更多 Agentic RL 算法与实验，可以阅读作者持续维护的 agentic-rl-lab；该仓库更新更快，并会持续补充新的训练代码与实践记录。
6. 常见问题
6.1 为什么不提供统一的根目录依赖？
本项目覆盖从原理实现到训练框架、再到 RAG 与 Agent 应用的完整链路，不同章节的依赖差异较大。按章节拆分依赖，能够减少版本冲突，也更符合教程式学习场景。
6.2 没有多卡 GPU 是否还能学习第六章？
可以。建议先阅读正文理解训练流程，再使用小样本、较小 batch size 或单卡环境调试数据处理和训练脚本。即便无法完整复现多卡训练，也不影响掌握整体思路。
6.3 第八章是否需要本地 GPU？
不需要。第八章的模型采样、logprob 计算、LoRA 前向反向传播和参数更新由 PyTRIO 远端完成。本地设备需要运行数据处理与环境交互，其中 Search-R1 依赖联网搜索，ReTool 还需要安全隔离的代码执行环境。
6.4 从哪一章开始动手最合适？
如果你偏向理解底层实现，建议从第 5 章开始；如果你更关注工业界常用训练框架，建议先完成第 1 章到第 4 章的基础阅读，再进入第 6 章和第 7 章。学习 Agentic RL 时，可以在完成强化学习与 Agent 基础后进入第 8 章，按照 GRPO、OPD、Search-R1、ReTool 的顺序实践。