Happy-LLM 学习与环境准备全指南：分章依赖、虚拟环境与第六章快速实践

Happy-LLM 学习与环境准备全指南：分章依赖、虚拟环境与第六章快速实践

【免费下载链接】happy-llm📚 从零开始构建大模型项目地址: https://gitcode.com/GitHub_Trending/ha/happy-llm

Happy-LLM 是一套「从零开始构建大模型」的系统性开源教程，覆盖 NLP 基础、Transformer 原理、LLM 训练到 RAG 与 Agent 应用。本文基于仓库中的 学习与环境准备 编写，给出完整的阅读路线、分章硬件建议、独立虚拟环境的搭建方法，并结合 第六章实践说明 与 第六章配套代码 展开一条可照做的快速实践路径。读完本文，你将能够独立完成 Happy-LLM 各章节的环境准备，并跑通第六章的模型下载、数据准备、小样本调试与 DeepSpeed 训练启动全流程。

1. 项目定位与总体环境策略

Happy-LLM 的定位是「教程阅读为主、代码实践为辅」。仓库内容横跨多个技术层次：

• 第 1～4 章：NLP 基础概念、Transformer 架构、预训练语言模型、大语言模型原理；
• 第 5 章：手写 LLaMA2、训练 Tokenizer、完成预训练与 SFT；
• 第 6 章：基于 Transformers 生态完成 Pretrain、SFT 与 PEFT 高效微调；
• 第 7 章：RAG 检索增强生成与 Agent 智能体应用。

由于不同章节依赖的技术栈差异较大（手写 PyTorch 实现、Transformers/DeepSpeed 训练框架、RAG 与 Agent 应用各自需要不同的第三方库），官方明确建议按章节分别准备依赖，而不是在同一个环境中安装全部依赖。这样能最大程度减少版本冲突，也更符合教程式学习场景。

注：仓库根目录不提供统一的依赖清单，这一设计是有意为之，具体原因见文末「常见问题」一节。

2. 阅读与实践建议

在正式动手前，先明确各章节的学习方式：

也就是说，即使没有多卡 GPU，你也可以完成核心学习目标——第 5 章的手写模型不依赖重量级训练框架，第 6 章可以先在小样本、单卡环境下把数据与训练流程调通，再考虑扩展规模。

3. 分章环境说明与硬件建议

各章节对应的依赖文件与硬件建议如下（依赖文件路径均已换算为仓库根目录相对路径）：

3.1 各章依赖清单速览

不同章节的依赖差异可以直接从 requirements 文件中读出：

• 第二章（手写 Transformer）：docs/chapter2/code/requirements.txt 锁定了torch==2.7.0、transformers==4.52.4、tokenizers==0.21.1等一套较新的固定版本，用于支撑手写实现与对照验证。
• 第五章（手写 LLaMA2 与 Tokenizer）：docs/chapter5/code/requirements.txt 依赖更广，包括torch==2.4.0、transformers==4.44.0、datasets==2.16.1、trl==0.11.3（用于 SFT）、sentence_transformers（文本表示）、simhash（数据去重）、nltk、matplotlib、swanlab（实验监控）等。
• 第六章（训练框架实践）：docs/chapter6/code/requirements.txt 十分精简，核心是transformers、datasets、torch、deepspeed、torchdata==0.9.0、pandas、swanlab。
• 第七章 RAG：docs/chapter7/RAG/requirements.txt 以openai==1.88.0、httpx、pypdf2、tiktoken、markdown等为主，用于接入 LLM 接口与解析文档。
• 第七章 Agent：docs/chapter7/Agent/requirements.txt 则包含streamlit==1.46.0（Web 演示界面）、wikipedia、gitpython、beautifulsoup4等工具链依赖。

正是这种「按章拆分」的粒度，让每一章的依赖都可以独立安装、互不污染。

4. 通用准备步骤：创建独立虚拟环境

官方建议使用Python 3.10 或 3.11，并为不同章节创建独立虚拟环境。以第六章为例，标准准备流程如下：

python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r ./docs/chapter6/code/requirements.txt

如果你需要复现其他章节，只需将最后一行中的依赖文件替换为该章节对应的requirements.txt（路径可参考上文分章环境说明表）。例如复现第五章时执行：

pip install -r ./docs/chapter5/code/requirements.txt

4.1 版本冲突规避技巧

由于第二章锁定torch==2.7.0、第五章锁定torch==2.4.0，而第六章未锁 torch 版本，强烈建议严格按章节隔离环境。若在同一环境中混装，pip 将很难同时满足多个固定版本约束。每个章节目录下都自带 requirements.txt，本身就是为「一章节一环境」的使用方式设计的。

5. 第六章快速开始：一条可复现的实践链路

第六章正文聚焦Pretrain、SFT 与 PEFT 高效微调三条主线，是连接手写实现与工业界训练框架的桥梁章节。官方推荐将正文与 第六章实践说明 一起阅读，代码全部位于 docs/chapter6/code。

5.1 推荐实践顺序

按以下顺序动手，可以避免「一上来就跑多卡训练」的高门槛：

1. 先阅读 第六章实践说明，明确模型、数据和脚本入口；
2. 使用 docs/chapter6/code/download_model.py 下载基座模型；
3. 使用 docs/chapter6/code/download_dataset.py 下载或准备训练数据；
4. 先用小样本调试 docs/chapter6/code/pretrain.py 或 docs/chapter6/code/finetune.py；
5. 最后再结合 docs/chapter6/code/pretrain.sh 与 docs/chapter6/code/finetune.sh 进行完整训练。

5.2 下载基座模型

docs/chapter6/code/download_model.py 的实现非常简单：先通过环境变量HF_ENDPOINT指定 HuggingFace 镜像站，再调用huggingface-cli download拉取 Qwen2.5-1.5B：

import os # 设置环境变量 os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' # 下载模型 os.system('huggingface-cli download --resume-download Qwen/Qwen2.5-1.5B --local-dir autodl-tmp/qwen-1.5b')

要点说明：

• --resume-download支持断点续传，网络中断后可继续；
• --local-dir将模型保存到本地目录（示例为autodl-tmp/qwen-1.5b）；
• autodl-tmp是 AutoDL 云主机上的示例路径，本地环境请替换为实际路径。

5.3 下载训练数据

docs/chapter6/code/download_dataset.py 同时处理预训练数据与 SFT 数据：

import os import json from tqdm import tqdm # 下载预训练数据集 # os.system("modelscope download --dataset ddzhu123/seq-monkey mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2 --local_dir ./autodl-tmp/dataset/pretrain_data") # # 解压预训练数据集 # os.system("tar -xvf ./autodl-tmp/dataset/pretrain_data/mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2") # 设置环境变量 os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' # 下载SFT数据集 os.system(f'huggingface-cli download --repo-type dataset --resume-download BelleGroup/train_3.5M_CN --local-dir ./autodl-tmp/dataset/sft_data/BelleGroup')

从源码结构可以看到两类数据的准备方式：

• 预训练数据（注释掉的部分）：通过 ModelScope 下载mobvoi_seq_monkey_general_open_corpus数据集的 jsonl 压缩包，再用tar解压；
• SFT 数据：通过 HuggingFace 镜像下载BelleGroup/train_3.5M_CN（350 万条中文指令数据），注意--repo-type dataset指明这是数据集仓库。

实践建议：正式跑训练前，先用 1～2 条样本打印检查数据格式——Pretrain 与 SFT 的数据构造与 loss 计算逻辑不同，格式直接决定训练效果。

5.4 小样本调试训练脚本

官方推荐先用小样本（small 数据集）、较小 batch size 在单卡上跑通 docs/chapter6/code/pretrain.py 与 docs/chapter6/code/finetune.py，再进入多卡完整训练。调试阶段的重点是验证模型路径、数据路径、输出目录是否与实际环境一致。

5.5 完整训练：DeepSpeed 启动脚本

调试通过后，即可使用 DeepSpeed 启动完整训练。预训练启动示例 docs/chapter6/code/pretrain.sh：

CUDA_VISIBLE_DEVICES=0,1 deepspeed pretrain.py \ --config_name autodl-tmp/qwen-1.5b \ --tokenizer_name autodl-tmp/qwen-1.5b \ --train_files autodl-tmp/dataset/pretrain_data/mobvoi_seq_monkey_general_open_corpus_small.jsonl \ --per_device_train_batch_size 16 \ --gradient_accumulation_steps 4 \ --do_train \ --output_dir autodl-tmp/output/pretrain \ --evaluation_strategy no \ --learning_rate 1e-4 \ --num_train_epochs 1 \ --warmup_steps 200 \ --logging_dir autodl-tmp/output/pretrain/logs \ --logging_strategy steps \ --logging_steps 5 \ --save_strategy steps \ --save_steps 100 \ --preprocessing_num_workers 10 \ --save_total_limit 1 \ --seed 12 \ --block_size 2048 \ --bf16 \ --gradient_checkpointing \ --deepspeed ./ds_config_zero2.json \ --report_to swanlab # --resume_from_checkpoint ${output_model}/checkpoint-20400 \

SFT 启动示例 docs/chapter6/code/finetune.sh 结构类似，主要差异是：

• 使用--model_name_or_path autodl-tmp/qwen-1.5b加载基座模型（而非--config_name+--tokenizer_name重建）；
• 数据源改为autodl-tmp/dataset/sft_data/BelleGroup/train_3.5M_CN.json；
• --num_train_epochs 3（SFT 训练轮数多于预训练的 1 轮）。

关键参数含义速查：

其中CUDA_VISIBLE_DEVICES=0,1指定可见 GPU 编号（当前示例使用 0、1 两张卡），autodl-tmp路径均为示例配置，正式运行前必须按本地环境调整。

5.6 DeepSpeed 配置解析

两套启动脚本都引用了 docs/chapter6/code/ds_config_zero2.json，这是一份ZeRO Stage 2配置：

• zero_optimization.stage: 2：将优化器状态分片到多张卡，显著降低显存占用；
• offload_optimizer.device: "none"：不把优化器状态卸载到 CPU/磁盘（如需进一步省显存可改为"cpu"）；
• allgather_partitions: true、reduce_scatter: true、contiguous_gradients: true：启用通信与梯度归约优化；
• allgather_bucket_size/reduce_bucket_size: 2e8：控制通信分桶大小；
• overlap_comm: true：通信与计算重叠，提升多卡效率；
• optimizer与scheduler的参数均设为"auto"，即从训练脚本的命令行参数（--learning_rate、--warmup_steps等）自动继承；
• fp16.enabled与bf16.enabled也设为"auto"，实际精度由训练脚本中的--bf16开关决定；
• train_batch_size、train_micro_batch_size_per_gpu、gradient_accumulation_steps均为"auto"，由 DeepSpeed 依据命令行参数自动推导。

这份配置文件中的"auto"设计意味着：训练超参只需要在启动脚本里声明一次，DeepSpeed 会自动同步，避免了多处配置不一致的问题。

5.7 关于 SwanLab 监控

第六章依赖中包含swanlab，启动脚本通过--report_to swanlab将 loss、学习率等训练指标上报到 SwanLab 看板，便于可视化对比 Pretrain 与 SFT 的收敛曲线。该能力同样被 第五章的手写实现 复用（其依赖中也包含swanlab），贯穿教程的训练监控环节。

6. 常见问题解答

6.1 为什么不提供统一的根目录依赖？

本项目覆盖从原理实现到训练框架、再到 RAG 与 Agent 应用的完整链路，不同章节的依赖差异较大（例如第二章锁定torch==2.7.0、第五章锁定torch==2.4.0）。按章节拆分依赖，能够减少版本冲突，也更符合教程式学习场景。

6.2 没有多卡 GPU 是否还能学习第六章？

可以。建议先阅读正文理解训练流程，再使用小样本、较小 batch size 或单卡环境调试数据处理和训练脚本。即便无法完整复现多卡训练，也不影响掌握整体思路——第六章实践说明 也给出了同样的建议：先调通路径，再扩大规模。

6.3 从哪一章开始动手最合适？

如果你偏向理解底层实现，建议从第 5 章开始；如果你更关注工业界常用训练框架，建议先完成第 1 章到第 4 章的基础阅读，再进入第 6 章和第 7 章的实践部分。

7. 更进一步的参考资料

• 第五章 动手搭建大模型：手写 LLaMA2、Tokenizer 训练与小型 LLM 预训练，代码位于 docs/chapter5/code；
• 第六章 大模型训练流程实践：Transformers、DeepSpeed、PEFT 训练实践，代码位于 docs/chapter6/code；
• 第七章 大模型应用：模型评测、RAG 检索增强与 Agent 智能体，代码分别位于 docs/chapter7/RAG 与 docs/chapter7/Agent；
• 第六章偏好对齐专题补充：在完成 Pretrain/SFT/PEFT 主线后，可继续阅读 RLHF、DPO、KTO 与奖励模型相关内容。

动手前请再次确认：脚本中的autodl-tmp路径、显卡编号和 DeepSpeed 参数都是示例配置，正式运行前请根据本地环境自行调整；仓库中 docs/学习与环境准备.md 是最权威的环境准备说明，本文内容均以其与第六章配套代码为准。

【免费下载链接】happy-llm📚 从零开始构建大模型项目地址: https://gitcode.com/GitHub_Trending/ha/happy-llm