学习与环境准备#

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 等依赖。请为不同章节创建独立虚拟环境。以第六章为例，可以按如下方式准备：

1
python -m venv .venv
2
source .venv/bin/activate
3
pip install --upgrade pip
4
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 环境：

1
uv venv --python 3.13
2
source .venv/bin/activate
3
uv pip install -r docs/chapter8/requirements.txt

如果尚未安装 uv，可以先执行 python -m pip install --upgrade uv。Windows PowerShell 使用 .\.venv\Scripts\Activate.ps1 激活环境。安装完成后，可以确认本章锁定的 PyTRIO 版本：

1
python -c "from importlib.metadata import version; print(version('pytrio'))"

5.2 登录并验证连接#

1
trio login
2
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 的顺序实践。