Update 第二章 Transformer架构.md

extra-chapter：text-data-processing

.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+.idea/
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+.history
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.DS_Store
+.obsidian

Extra-Chapter/Readme.md

@@ -0,0 +1,120 @@
+<div align="center">
+  <h2>🚀 Happy-LLM 扩展内容</h2>
+  <p><em>社区驱动的大语言模型学习资源</em></p>
+</div>
+
+---
+
+## 📖 为什么会有 Extra Chapter？
+
+&emsp;&emsp;在 Happy-LLM 主教程的基础上，我们发现社区中有许多优秀的学习者和实践者，他们在学习和使用大语言模型的过程中积累了宝贵的经验、独到的见解和实用的技巧。这些内容虽然不属于主教程的核心知识体系，但对于深入理解和应用大语言模型具有重要价值。
+
+**Extra Chapter 的设立目的：**
+
+- 🌟 **汇聚智慧**：收集社区成员的优秀学习笔记、实践经验和技术博客
+- 🔄 **持续更新**：保持内容的时效性，跟上大语言模型领域的快速发展
+- 🤝 **促进交流**：为社区成员提供分享和交流的平台
+- 📚 **补充完善**：对主教程内容进行有益的补充和扩展
+- 💡 **启发思考**：通过不同视角和实践案例，启发读者的深度思考
+
+**Extra Chapter 包含的内容类型：**
+
+- 📝 **学习笔记**：深度学习心得和知识总结
+- 🛠️ **实践案例**：真实项目中的应用经验
+- 🔬 **技术探索**：前沿技术的研究和实验
+- 💭 **思考感悟**：对大语言模型发展的独特见解
+- 🎯 **专题研究**：特定领域或问题的深入分析
+
+---
+
+## 📋 PR 贡献规范
+
+&emsp;&emsp;我们热烈欢迎社区成员为 Extra Chapter 贡献优质内容！为了保证内容质量和项目的整体性，请遵循以下规范：
+
+### 🗂️ 目录结构规范
+
+每个贡献的内容应按照以下目录结构组织：
+
+```
+Extra-Chapter/
+├── your-topic-name/                    # 你的主题文件夹
+│   ├── readme.md                       # 主要内容文件（必需）
+│   ├── images/                         # 图片资源文件夹（可选）
+│   │   ├── figure1.png
+│   │   └── figure2.jpg
+│   ├── code/                           # 代码文件夹（可选）
+│   │   ├── example.py
+│   │   └── requirements.txt
+│   ├── data/                           # 数据文件夹（可选）
+│   │   └── sample_data.json
+│   └── notebook.ipynb                  # Jupyter Notebook（如涉及代码必选）
+└── Readme.md                           # 本文件
+```
+
+### 📝 文件命名规范
+
+1. **主题文件夹命名**：
+   - 使用小写字母和连字符
+   - 名称要简洁明了，能够概括主题内容
+   - 例如：`why-fine-tune-small-large-language-models`、`rag-optimization-techniques`
+
+2. **主要内容文件**：
+   - 必须命名为 `readme.md`
+   - 使用 Markdown 格式编写
+
+3. **图片文件**：
+   - 统一放在 `images/` 文件夹下
+   - 使用描述性的文件名
+   - 支持格式：`.png`、`.jpg`、`.jpeg`、`.gif`、`.svg`
+
+4. **代码文件**：
+   - 如涉及代码，请尽量提供可直接运行的 Jupyter Notebook 文件
+   - 统一放在 `code/` 文件夹下
+   - 使用标准的文件扩展名
+   - 如有依赖，请提供 `requirements.txt`
+   - 如有 Jupyter Notebook 文件，请放在主文件夹下
+
+### ✍️ 内容质量要求
+
+1. **原创性**：
+   - 内容必须是原创或经过授权的
+   - 如引用他人内容，请注明出处
+
+2. **技术准确性**：
+   - 确保技术内容的准确性
+   - 代码示例应能正常运行
+   - 提供必要的环境说明
+
+3. **结构清晰**：
+   - 使用清晰的标题层次
+   - 合理使用列表、表格等格式
+   - 重要内容使用适当的强调
+
+4. **语言规范**：
+   - 使用规范的中文表达
+   - 技术术语使用准确
+   - 避免错别字和语法错误
+
+### PR commit messgae 内容
+
+请在 PR commit message 中 包含以下内容：
+
+- 新增的主题文件夹名称
+- 贡献内容的概述
+- 贡献内容的详细描述
+- 你的 Github 个人主页链接，及你的个人介绍
+- 个人 title 及工作经历 or 学校 or 研究方向
+
+如以下所示：
+
+```
+Extra Chapter: 你的主题名称
+
+详细描述你的贡献内容，包括新增的主题文件夹、文件内容和目录结构。
+
+- 新增的主题文件夹名称：your-topic-name
+- 贡献内容的概述：详细介绍你的贡献内容
+- 贡献内容的详细描述：详细描述你的贡献内容，包括新增的主题文件夹、文件内容和目录结构。
+- 你的 Github 个人主页链接及个人介绍：[你的个人主页链接](https://example.com)，介绍你的研究方向、技术专长等。
+- 个人 title 及工作经历 or 学校 or 研究方向：内容贡献者-xxxx学校，研究方向为自然语言处理。
+```

Extra-Chapter/transformer-architecture/readme.md

@@ -0,0 +1,344 @@
+# transformer-architecture
+
+当本节内容作为第二章 Transformer架构中2.2章节Encoder-Decoder的补充，结合Pytorch的API源码，从Transformer的整体设计上来解释Transformer的各个模块。
+
+## 从经典架构开始：Encoder-Decoder结构
+让我们先从经典架构图理解Transformer的整体设计思路。Transformer分为两个主要部分：左侧的编码器（Encoder）和右侧的解码器（Decoder）。那么这两块结构的输入和输出分别是什么？
+
+<div align='center'>
+    <img src="./images/trans-img-1.png" alt="alt text" width="90%">
+    <p>1.jpg</p>
+</div>
+
+Encoder的职责是接受完整的源序列输入，将其转换为一个富含语义信息的表示序列。想象一下，如果我们要做机器翻译，Encoder就像是一个深度理解原文的专家，它需要充分理解整个句子的含义、语法结构和上下文关系。
+
+Decoder则承担着更复杂的任务：它需要接受目标序列和编码器输出的表示序列，然后输出词汇/字符的概率分布。这就像是一个翻译专家，既要理解原文的含义（通过Encoder的输出），又要根据已经翻译的部分来决定下一个词应该是什么。
+
+## Positional Encoding：位置编码设计
+
+但这里有一个关键问题需要解决：Transformer本身对位置信息不敏感。比如"我爱你"和"你爱我"这两个句子，在没有位置信息的情况下，模型无法感知到这是语义完全不同的句子。这就像是一个人失去了对词语顺序的感知能力，显然无法正确理解语言。
+
+因此，我们需要一个带有位置信息的向量，将其添加到每个input embedding上，来对不同位置得到不同的表征。这个模块就是图中的**Positional Encoding**。
+
+### 位置编码的设计原则
+
+在设计编码模块时，有**三个重要的前提假设**，这些假设直接影响了最终的实现方案：
+
+**1. 确定性原则**：每个位置的编码应该是确定的数字，不同序列中相同位置的编码应该相同。
+
+为什么这个原则如此重要？让我们考虑一个反例：如果用等分的设计方法，将一个序列从0~1之间做均匀划分，那么序列长度不一样时，每个位置上的编码也就不一样。当序列长度为5时，位置编码可能是0、0.2、0.4、0.6、0.8，但如果序列长度为10，就变成了0、0.1、0.2...。同样对于第二个位置上的字符，在第一个序列中是0.2，在第二个序列中又是0.1，这样的编码就失去了确定性。
+
+**2. 相对关系一致性**：不同句子中，对于任意两个位置之间的相对距离，相对关系应该保持一致。
+
+这个目的是为了学习通用的语言关系，比如："修饰词在被修饰词前1个位置"是通用模式。以下面的长短句举例：
+
+```markdown
+- 长句子（10个词）
+  位置: 0  1  2  3  4  5  6  7  8  9
+  词汇: I  am learning about transformers today in class now
+
+- 短句子（6个词）
+  位置: 0  1  2  3  4  5
+  词汇: I  like deep learning models
+```
+
+在长句子中，位置1和位置4之间的编码关系，应该与短句子中位置2和位置5之间的编码关系完全相同，因为模型需要学会的是通用的相对位置关系。
+
+**3. 泛化能力**：位置序列应该能推广到没见过的更长序列。
+
+第三个假设希望位置编码可以推广到更长的测试句子。假如训练集中序列长度都是10以内的，但测试集中可能会有长度为15的句子，我们希望即使测试集中句子长度更长，在训练中没有见过，我们也能通过这样的position encoding推广过去。
+
+### 三角函数编码
+
+基于这些假设，Transformer采用了sin和cos的组合来表征绝对位置信息：
+
+```markdown
+- 向量维度为偶数：PE(pos, 2i) = sin(pos / 10000^(2i/d_model))
+- 向量维度为奇数：PE(pos, 2i+1) = cos(pos / 10000^(2i/d_model))
+```
+
+通过sin和cos的组合来表征绝对位置的好处是：`pe(pos+k)`可以写成`pe(k)`的线性组合（利用三角函数公式`sin(A + B) = sin(A)cos(B) + cos(A)sin(B)`）。这样做的意义是：即使测试集中出现了pos+k这种未见过的位置，我们也可以把它写成训练集中见过的位置的线性组合，而不用担心测试集中遇到更长的句子无法推广。
+
+### 位置信息的传递机制
+
+但位置编码是在最底层添加，会不会在深层网络中丢失？这个担心是多余的。通过**残差连接**，位置信息能够充分传递到上层网络。
+
+假设有一个N层的神经网络，输入为x₀（包含位置编码），那么：
+
+```markdown
+- 第1层: x₁ = x₀ + F₁(x₀)
+- 第2层: x₂ = x₁ + F₂(x₁) = x₀ + F₁(x₀) + F₂(x₁)
+- 第3层: x₃ = x₂ + F₃(x₂) = x₀ + F₁(x₀) + F₂(x₁) + F₃(x₂)
+- ...
+- 第N层: xₙ = x₀ + Σᵢ₌₁ⁿ Fᵢ(xᵢ₋₁)
+```
+
+可以看到，初始的位置信息x₀始终存在于每一层的输出中，这确保了位置信息不会随着网络层数的加深而消失。
+
+## 从PyTorch源码API来理解transformer的架构设计
+
+通过查看PyTorch的源码，来了解Encoder和Decoder中的架构实现。源码位于`/pytorch/torch/nn/modules/transformer.py`，此次借助的版本是v2.5.1。
+
+### 顶层Transformer类的设计
+
+首先，PyTorch定义了一个顶层的`Transformer`类，我们可以通过`torch.nn.Transformer`来调用它：
+
+```python
+# 使用示例
+transformer_model = nn.Transformer(d_model=512, nhead=8, num_encoder_layers=6)
+```
+
+<div align='center'>
+    <img src="./images/trans-img-2.png" alt="alt text" width="90%">
+    <p>2.jpg</p>
+</div>
+
+
+在`Transformer`的`__init__`函数中，主要有5个核心参数：
+
+1. **d_model**：整个Transformer的特征维度，在原论文中设置的是512。这个维度需要足够大以承载丰富的语义信息，但太大会导致计算复杂度过高。
+
+2. **nhead**：Multi-head attention的头数目。多头设计的目的是让模型可以捕捉到更多位置与位置之间的关系；
+
+3. **num_encoder_layers**：编码器encoder的block数目，encoder的每个block包含多头自注意力机制和前馈神经网络，这里默认block是6个；
+
+4. **num_decoder_layers**：decoder解码器中block数目，decoder的每个block包含多头自注意力机制、交叉注意力机制以及前馈神经网络；
+
+5. **dim_feedforward**：前馈神经网络层中间的特征维度，默认是2048。Multihead attention输出时，会**首先**映射到2048这个大的特征空间，然后再把它映射回来到512这样的空间。必须要保证输出的维度仍然是512，这样就可以进行残差连接；
+
+<div align='center'>
+    <img src="./images/trans-img-3.png" alt="alt text" width="90%">
+    <p>3.jpg</p>
+</div>
+
+
+### 模块化设计
+
+init函数的作用是实例化模块，第一个要实例化的模块就是encoder。
+
+<div align='center'>
+    <img src="./images/trans-img-4.png" alt="alt text" width="90%">
+    <p>4.jpg</p>
+</div>
+
+encoder通过TransformerEncoder的class去实现实例，在这个class中需要传入encoder_layer，在TransformerEncoderLayer的class中实现了Multihead self attention的调用、残差连接、层归一化、全连接层网络，主要是这些来构成一个encoder_layer。
+
+对于decode部分也是一样，传入decodeLayer参数，这个layer包含了自注意力机制、交叉注意力机制以及前馈神经网络。
+
+<div align='center'>
+    <img src="./images/trans-img-5.png" alt="alt text" width="90%">
+    <p>5.jpg</p>
+</div>
+
+总体上Transformer源码，就是由四个class所构成：
+- **TransformerEncoderLayer**：每一个编码层的实现
+- **TransformerEncoder**：负责把这些编码层串起来
+- **TransformerDecoderLayer**：每一个解码层的实现
+- **TransformerDecoder**：把这些解码层串起来
+
+这种模块化的设计体现了软件工程的最佳实践：单一职责原则和组合优于继承的思想。
+
+### Forward函数：编排计算流程
+
+在`forward`函数中，Transformer的计算流程非常清晰：
+
+<div align='center'>
+    <img src="./images/trans-img-6.png" alt="alt text" width="90%">
+    <p>6.jpg</p>
+</div>
+
+首先encoder输入是source句子以及padding_mask，encoder中的注意力机制不需要掩码，因此mask及is_causal参数不需要传入掩码。但需要对样本长度做掩盖，即**padding_mask**，这个mask表示每一个样本的长度。当我们做训练时，序列长度是不一样的，有些短的样本，在后面的一些位置上就是无效的，通过在softmax中把无效位置上的值转成负无穷，这样经过归一化后概率就变成0，使得在这些位置上，这些没有值的位置变得无效。
+
+decode输入第一个是target，也就是目标句子。第二个是memory，表示encoder输出，因为memory会输送到交叉注意力中。第三个是target mask，这个target mask是一个考虑因果的mask，在数学上是一个上三角矩阵。
+
+### 因果掩码mask
+
+每次预测时，decoder都会有一个输入句子，即：output embedding。但这个output embedding不能全部给它，如果全部给它的话，那它就变成了identity映射，相当于从x到x的关系我给你了，那预测出来的答案肯定是从x到x。
+
+我们需要保证output每次只根据当前要预测的单词的左边的所有单词，去预测这个单词。这个单词的本身和其他的右边的单词都不要输送到Output Embedding。这样的操作需要通过mask来实现，随着预测的字符往右进行，我们给到这个decoder中的output会越来越多，所以它就是一个上三角的矩阵。
+
+第四个memory mask，和source sentence的长度有关，在batch训练中source sentence每一个样本都不太一样，memory mask就是每一个输入源序列这个样本的一个长度。
+
+### Transformer框架
+
+这就是Transformer class总体上的构成框架，init函数去实例化encoder和decoder。在forward函数中基于source、target、source mask、target mask，分别入参到encoder和decoder中，最终得到output，即要预测字符的概率。
+
+<div align='center'>
+    <img src="./images/trans-img-7.png" alt="alt text" width="90%">
+    <p>7.jpg</p>
+</div>
+
+Transformer本质上是一个自回归的解码过程，不是并行的预测输出，而是每次只会预测一个，输出一个，然后不断的进行解码去预测出整体的target sentence。
+
+## Encoder编码器层
+
+接下来我们分别来看下init函数中的4个class，首先是**单个编码器**的实现：在`TransformerEncoderLayer`的`__init__`函数中，需要实例化四个关键组件：
+
+<div align='center'>
+    <img src="./images/trans-img-8.png" alt="alt text" width="90%">
+    <p>8.jpg</p>
+</div>
+
+先是init函数中的参数，和transformer中传入的一致，d_model是整个Transformer的特征维度512。nhead是Multi-head attention中多头自注意力机制中头的数目。
+
+### 多头注意力的设计
+
+为什么是多头？目的是让**模型可以捕捉到更多的位置与位置之间的关系**。多头会分为多组的query、key和value，每一组会单独地去计算attention的上下文的向量，最后把这个向量拼起来，再通过FFN得到最终的一个向量。
+
+这样做的话，对embedding的特征向量的维度会降低，比如说原来的特征向量维度是512，如果我们分为8个头，这时向量每一个头它向量的维度就会变成64（这里不是通过压缩，而是线性变换重组）。每个头独立计算注意力后，会得到8个64维的输出向量。然后通过拼接操作（concatenation），将这8个64维向量首尾相接，重新组合成一个512维的向量。最后再通过一个输出线性变换层，得到最终的512维输出。
+
+<div align='center'>
+    <img src="./images/trans-img-9.png" alt="alt text" width="90%">
+    <p>9.jpg</p>
+</div>
+
+### 前馈神经网络
+
+dimension feed forward是前馈神经网络FFN的维度，因为需要先从512到2048，再从2048到512，所以设定了两个全连接层。前馈神经网络它是对每个单独位置进行一个建模，并且不同位置的参数是共享的。类比1×1的pointwise卷积，对图像中每个像素位置的特征向量独立进行变换。参数共享就是为序列中的每个位置都设计相同的参数，目的是希望模型学会"如何处理特征"的通用能力，而不是"如何处理第x个位置的特征"的特定能力。
+
+FFN实际上做的是embedding相同位置不同维度间的融合，在每个位置内部对该位置的不同特征维度进行融合，注意力机制负责位置间的信息交流。
+
+### Encoder编码器层的组件实例化
+
+init函数中需要去实例化一些实例：
+1. 首先是Multi-head attention，本节着重整个框架；
+2. 实例FFN前馈神经网络中的两个Linear层，第一个Linear比较大，第二个Linear是重新这个投射到d_model的尺度；
+3. 实例layer norm，在self attention之后会经过层归一化，以及在前馈神经网络之后也会经过一个层归一；
+4. 实例两个dropout，dropout是为了使得这个网络具备集成学习的特点，即使我们在训练多个模提高泛化能力；
+
+### Encoder编码器前向传播forward: 编排计算流程
+
+forward函数中，encoder层的调用很简单。Transformer encoder layer的第一部分：通过self attention block得到一个表征(self._sa_block)，然后再加一个这个残差连接(就是和x加起来)，最后再经过一个层归一化。self attention的输入是序列x和pendding-mask，这里的序列x既充当了query，又充当了key和value。
+
+<div align='center'>
+    <img src="./images/trans-img-10.png" alt="alt text" width="90%">
+    <p>10.jpg</p>
+</div>
+
+第二部分是**feed forward block**，把第一部分输出经过每个位置独立的一个全连接层，再进行一个残差连接，输送到层归一化中就得到x。这个就是Transformer encoder中的每个layer的输出。
+
+原始论文的设计是层归一化在后，即else的设计。
+
+### Encoder编码器的串联
+
+`TransformerEncoder` class的作用是将多个编码器层串联起来：将上一层的输出作为下一层的输入，经过多层处理得到最终的编码器输出。
+
+<div align='center'>
+    <img src="./images/trans-img-11.png" alt="alt text" width="90%">
+    <p>11.jpg</p>
+</div>
+
+init主要是传入两个参数，一个是encoder_layer，表示TransformerEncoderLayer class的一个实例。第二个参数是num_layers，表示transformer encoder有多少层，层的含义就是block。encoder中自注意力机制+前馈神经网络这两块是一个block，也就是一层。
+
+## Decoder解码器
+
+解码器的实现比编码器更复杂，因为它包含三个子模块，需要处理更多的交互。
+
+在`TransformerDecoderLayer`中，我们需要实例化三套组件（**自注意力+交叉注意力+前馈神经网络**）：
+
+<div align='center'>
+    <img src="./images/trans-img-12.png" alt="alt text" width="90%">
+    <p>12.jpg</p>
+</div>
+
+在init参数中，第一个是d_model，表示transformer模型特征大小，默认512。第二个参数是nhead，是Transformer decoder的多头自注意力机制的头数。第三个参数是dimension feed forward，表示decoder中FFN前馈神经网络的维度。
+
+<div align='center'>
+    <img src="./images/trans-img-13.png" alt="alt text" width="90%">
+    <p>13.jpg</p>
+</div>
+
+
+### Decoder解码器两种注意力机制的区别
+
+init参数中，decoder和encoder不同的地方，就是需要实例化两个Multihead attention。
+
+第一个Multi-head attention，是**自注意力机制**，它是对decoder这个输入序列的，即：target sentence embedding作为输入序列的自身表征。
+
+第二个Multi-head attention是**交叉注意力机制**，我们想知道decoder multihead attention的输出和encoder输出状态的一个关联性，用该注意力机制跨越了encoder和decoder两个不同序列，不是decoder内部的自我关注，而是让decoder去关注encoder的信息。于是我们通过用decoder MHA（多头注意力）的一个输出作为query，然后用encoder的输出作为key和value来去算出一个上下文表征。
+
+同样Decoder要实现两个Linear层，第一个Linear层是比较大的，把我们交叉自注意力机制的输出，投射到一个更高维的空间，就是2048。然后再把它投射到低维的空间，就是从2048降成512。由于Decoder有三个模块（自注意力+交叉注意力+前馈神经网络），所以这里要实现3个norm和3个dropout。
+
+### Decoder解码器forward：编排流程
+
+解码器的`forward`函数体现了三个模块的协同工作：
+
+1. 第一个模块会把target sentence，也就是序列x和target mask输入到self._sa_block中，对target句子做自注意力机制的计算，结果放入到残差网络中，并且经过层归一化得到输出。
+
+2. 第二个模块依赖于第一个模块输出的x，再和encoder输出的memory做交叉注意力的计算，得到新的表征后，经过残差网络和归一化的norm输出；
+
+3. 把第二个模块的输出输送到FFN前馈神经网络，再次进行残差网络和归一化的norm，得到decoder的输出；
+
+<div align='center'>
+    <img src="./images/trans-img-14.png" alt="alt text" width="90%">
+    <p>14.jpg</p>
+</div>
+
+可以看下_sa_block和_mha_block各自的调用，它们都是调用的是Multihead attention，只不过它们的query、key、value是不一样的。
+
+<div align='center'>
+    <img src="./images/trans-img-15.png" alt="alt text" width="90%">
+    <p>15.jpg</p>
+</div>
+
+<div align='center'>
+    <img src="./images/trans-img-16.png" alt="alt text" width="90%">
+    <p>16.jpg</p>
+</div>
+
+self attention中query、key、value都是目标序列，自身对自身的求相关性的计算。但在交叉注意力机制中，query是decoder的一个输出，key和value是encoder的输出（始终是memory）。
+
+通过多个TransformerDecoderLayer，构成了TransformerDecoder，和TransformerEncoder实现类似，这里不重复赘述。
+
+## 注意力机制的核心计算
+
+最后看下注意力机制的核心计算，PyTorch的实际实现更加复杂和优化，但核心思想可以用论文版本来理解：
+
+<div align='center'>
+    <img src="./images/trans-img-17.png" alt="alt text" width="90%">
+    <p>17.jpg</p>
+</div>
+
+### 注意力机制的直观理解
+
+attention函数就是将一个query和一个由key和value形成的一对元素，建立一个连接，最终得到一个输出。比如：我们去百度搜索一个词条，这个词条就是query，然后百度的数据库里有很多词条信息，每个信息自身都有个key，value就是该词条的具体内容。我们通过这个query，百度就会给我们返回一个搜索结果。这个结果就可以理解为一个注意力机制--基于query和key+value计算出来的一个上下文。
+
+注意力机制的计算结果是Value的一个加权求和的结果，权重是基于Query和Key的相似度计算出来的。先算Query和每个Key的相似度，基于这个相似度进行Softmax归一化得到权重，再把这个权重与每个Key所对应的Value进行加权求和。
+
+### Scaled Dot-Product Attention
+
+在Transformer模型中，用的是"Scaled Dot-Product Attention"，这里有个scaled，可以看到公式中就是QK，会除以一个根号d_k，这个目的就是为了使得Softmax的输入分布会更加稳定一点，也就是使得它的方差会更小一点。
+
+这个Attention由三部分构成，分别是Q、K、V，它们都是三个向量。首先我们会把query和key进行一个矩阵相乘，如果我们单个样本来看就是向量内积，批量来看就是矩阵相乘。
+
+内积过后再除以一个根号d_K，把每个位置上的这个内积放到一起去做一个归一化。这样就可以得到每个位置上的一个概率的表示，因为Softmax它出来的结果就是它总和为1，然后每一个值都是在0到1之间，得到这样一个概率，然后我们把概率和每个位置上value进行一个加权求和，最终能得到attention的一个输出，这就是scaled dot product attention的计算逻辑。
+
+论文中讲的Multi-head self attention其实就是有很多个这样的自注意力机制同时计算，算完之后我们把每一个得到的结果给拼起来，得到了Multi-head self attention最终的输出。
+
+### 注意力计算的代码实现
+
+attention代码如下，这里我们用的是论文实现的简单版本。输入由query、key和value构成。
+
+<div align='center'>
+    <img src="./images/trans-img-18.png" alt="alt text" width="90%">
+    <p>18.jpg</p>
+</div>
+
+首先会把这个q跟k的转置进行一个矩阵相乘，那这样的话就能得到一个一✖️t的向量，把这个向量做一个mask。这里的mask就是把等于0的位置，填充一个非常非常小的一个数，负无穷的数，因为负无穷的数经过Softmax这个归一化之后，它就会变成0的概率，目的是希望那些不重要的位置上的概率赋为0。这里的mask，这里只有一个mask，所以你可以理解为那它这里是一个自注意力机制的一个实现，如果有两个mask，那就是交叉注意力机制的实现。
+
+得到这个p attention就概率分布之后，再把这个p attention跟value进行一个加权求和，得到最终自注意力机制的输出，这是单个自注意力机制的一个计算逻辑，如果是多头的话，最终把单个的输出拼起来就好。
+
+在Transformer模型中，不同的注意力机制有着不同的QKV来源和映射方式：
+
+1. **encoder层的query key和value**：在编码器中都是由word embedding加上position encoding后，通过三个独立的线性映射得到QKV；
+
+2. **在decoder中self attention层**：同样也是通过target sentence embedding+position encoding，通过三个独立的线性映射得到QKV；
+
+3. **在交叉attention中**：query是由decoder的输出经过一个线性映射得到的，key和value是编码器的输出memory分别经过两个映射得到；
+
+
+**参考资料：**
+
+1. [DataWhale HapplyLLM](https://datawhalechina.github.io/happy-llm/#/)
+2. [deep_thought](https://www.bilibili.com/video/BV1o44y1Y7cp/?vd_source=a957a54256d2af7f2a1778751c3855cb&spm_id_from=333.788.videopod.sections)
+3. [HandleNLP](https://nlp.seas.harvard.edu/2018/04/03/attention.html)

Extra-Chapter/why-fine-tune-small-large-language-models/readme.md

@@ -0,0 +1,388 @@
+# 大模型都这么厉害了，微调0.6B的小模型有什么意义？
+
+大家在日常使用Deepseek-R1或者是阿里新发布的Qwen3模型，他们的模型都是能力很强，所提供的API服也都可以满足大家的日常或者是公司开发所需。但大家也可以想一个简单的问题几个简单的问题，如下：
+
+1. 公司的数据是够敏感，是否需要保密？
+1. 日常使用大模型的任务是否很困难，对推理链是否刚需？
+1. 任务调用的大模型API并发量是多少？每日资金消耗有多少？
+
+对于问题1，如果公司数据敏感，那我建议不要调用供应商提供的大模型API。就算供应商保证不会拿你们数据做训练，但你们的数据还是泄漏了（会有不必要的风险），建议本地部署大模型。
+
+对于问题2，如果使用大模型的场景问题很困难并且刚需推理链，那可以使用供应商的API，这样可以保证推理链的上下文不会爆显存。如果问题很简单，没有刚需推理链，那建议本地部署小模型即可。
+
+对于问题3，如果任务很简单，且调用的大模型API并发量很高，那我建议微调一个特定任务的小模型，本地部署。这样可以满足高并发，并且可以减少资金消耗。（本地部署，默认硬件环境单卡4090）
+
+看到这里，想必大家已经思考完了以上三个问题，心中有了答案。那我给出一个小小的案例。
+
+## 微调模型的需求性
+
+假如你的公司有一个从投诉的文本中抽取用户信息的任务。比如，你需要从以下文本中抽取用户姓名、住址、邮箱、投诉的问题等等。
+
+> 这只是一个小小的案例，数据也是我用大模型批量制造的。真正的投诉数据不会这么“干净、整洁”。
+
+INPUT：
+```text
+龙琳，宁夏回族自治区璐市城东林街g座 955491，邮箱 nafan@example.com。小区垃圾堆积成山，晚上噪音扰人清梦，停车难上加难，简直无法忍受！
+```
+
+OUTPUT：
+```json
+{
+    "name": "龙琳",
+    "address": "宁夏回族自治区璐市城东林街g座 955491",
+    "email": "nafan@example.com",
+    "question": "小区垃圾堆积成山，晚上噪音扰人清梦，停车难上加难，简直无法忍受！"
+}
+```
+
+
+那你当然可以调用 Deepseek最强大的模型R1，也可以调用阿里最新发布最强大的模型 Qwen3-235B-A22B等等，这些模型的信息抽取效果也很非常的棒。
+
+但有个问题，如果你有几百万条这样的数据要处理，全部调用最新的，最好的大模型可能需要消耗几万块钱。并且，如果这些投诉数据，比如电信投诉数据，电网投诉数据，这些数据是敏感的不可以直接放到外网的。
+
+所以，综合数据敏感，和资金消耗。最好的选择就是微调一个小模型（如Qwen3-0.6B），既可以保证高并发，可以保证数据不泄漏，保证模型抽取的效果，还可以省钱！！！
+
+那下面，用一个小案例带大家实操一下，微调Qwen3-0.6B小模型完成文本信息抽取任务。
+
+
+
+## 配置环境 下载数据
+
+> Colab 文件地址：https://colab.research.google.com/drive/18ByY11KVhIy6zWx1uKUjSzqeHTme-TtU?usp=drive_link
+
+```python
+!pip install datasets swanlab -q
+```
+
+```python
+!wget --no-check-certificate 'https://docs.google.com/uc?export=download&id=1a0sf5C209CLW5824TJkUM4olMy0zZWpg' -O fake_sft.json
+```
+
+## 处理数据
+
+```python
+from datasets import Dataset
+import pandas as pd
+from transformers import AutoTokenizer, AutoModelForCausalLM, DataCollatorForSeq2Seq, TrainingArguments, Trainer, GenerationConfig
+from peft import LoraConfig, TaskType, get_peft_model
+import torch
+```
+
+```python
+# 将JSON文件转换为CSV文件
+df = pd.read_json('fake_sft.json')
+ds = Dataset.from_pandas(df)
+ds[:3]
+```
+
+```python
+model_id = "Qwen/Qwen3-0.6B"
+```
+
+```python
+tokenizer = AutoTokenizer.from_pretrained(model_id, use_fast=False)
+tokenizer
+```
+
+对大语言模型进行 `supervised-finetuning`（`sft`，有监督微调）的数据格式如下：
+
+```json
+{
+  "instruction": "回答以下用户问题，仅输出答案。",
+  "input": "1+1等于几?",
+  "output": "2"
+}
+```
+
+其中，`instruction` 是用户指令，告知模型其需要完成的任务；`input` 是用户输入，是完成用户指令所必须的输入内容；`output` 是模型应该给出的输出。
+
+有监督微调的目标是让模型具备理解并遵循用户指令的能力。因此，在构建数据集时，我们应针对我们的目标任务，针对性构建数据。比如，如果我们的目标是通过大量人物的对话数据微调得到一个能够 role-play 甄嬛对话风格的模型，因此在该场景下的数据示例如下：
+
+```json
+{
+  "instruction": "你父亲是谁？",
+  "input": "",
+  "output": "家父是大理寺少卿甄远道。"
+}
+```
+
+`Qwen3` 采用的 `Chat Template`格式如下：
+
+由于 `Qwen3` 是混合推理模型，因此可以手动选择开启思考模式
+
+不开启 `thinking mode`
+
+
+```python
+messages = [
+    {"role": "system", "content": "You are a helpful AI"},
+    {"role": "user", "content": "How are you?"},
+    {"role": "assistant", "content": "I'm fine, think you. and you?"},
+]
+
+text = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True,
+    enable_thinking=False
+)
+print(text)
+```
+```
+<|im_start|>system
+You are a helpful AI<|im_end|>
+<|im_start|>user
+How are you?<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+I'm fine, think you. and you?<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+``` 
+
+
+`LoRA`（`Low-Rank Adaptation`）训练的数据是需要经过格式化、编码之后再输入给模型进行训练的，我们需要先将输入文本编码为 `input_ids`，将输出文本编码为 `labels`，编码之后的结果是向量。我们首先定义一个预处理函数，这个函数用于对每一个样本，同时编码其输入、输出文本并返回一个编码后的字典：
+
+
+```python
+def process_func(example):
+    MAX_LENGTH = 1024 # 设置最大序列长度为1024个token
+    input_ids, attention_mask, labels = [], [], [] # 初始化返回值
+    # 适配chat_template
+    instruction = tokenizer(
+        f"<s><|im_start|>system\n{example['system']}<|im_end|>\n"
+        f"<|im_start|>user\n{example['instruction'] + example['input']}<|im_end|>\n"
+        f"<|im_start|>assistant\n<think>\n\n</think>\n\n",
+        add_special_tokens=False
+    )
+    response = tokenizer(f"{example['output']}", add_special_tokens=False)
+    # 将instructio部分和response部分的input_ids拼接，并在末尾添加eos token作为标记结束的token
+    input_ids = instruction["input_ids"] + response["input_ids"] + [tokenizer.pad_token_id]
+    # 注意力掩码，表示模型需要关注的位置
+    attention_mask = instruction["attention_mask"] + response["attention_mask"] + [1]
+    # 对于instruction，使用-100表示这些位置不计算loss（即模型不需要预测这部分）
+    labels = [-100] * len(instruction["input_ids"]) + response["input_ids"] + [tokenizer.pad_token_id]
+    if len(input_ids) > MAX_LENGTH:  # 超出最大序列长度截断
+        input_ids = input_ids[:MAX_LENGTH]
+        attention_mask = attention_mask[:MAX_LENGTH]
+        labels = labels[:MAX_LENGTH]
+    return {
+        "input_ids": input_ids,
+        "attention_mask": attention_mask,
+        "labels": labels
+    }
+
+```
+
+
+```python
+tokenized_id = ds.map(process_func, remove_columns=ds.column_names)
+tokenized_id
+```
+
+
+```python
+tokenizer.decode(tokenized_id[0]['input_ids'])
+```
+
+```python
+tokenizer.decode(list(filter(lambda x: x != -100, tokenized_id[1]["labels"])))
+```
+
+## 加载模型
+
+加载模型并配置LoraConfig
+
+```python
+model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto",torch_dtype=torch.bfloat16)
+model
+```
+
+
+```
+Qwen3ForCausalLM(
+  (model): Qwen3Model(
+    (embed_tokens): Embedding(151936, 1024)
+    (layers): ModuleList(
+      (0-27): 28 x Qwen3DecoderLayer(
+        (self_attn): Qwen3Attention(
+          (q_proj): Linear(in_features=1024, out_features=2048, bias=False)
+          (k_proj): Linear(in_features=1024, out_features=1024, bias=False)
+          (v_proj): Linear(in_features=1024, out_features=1024, bias=False)
+          (o_proj): Linear(in_features=2048, out_features=1024, bias=False)
+          (q_norm): Qwen3RMSNorm((128,), eps=1e-06)
+          (k_norm): Qwen3RMSNorm((128,), eps=1e-06)
+        )
+        (mlp): Qwen3MLP(
+          (gate_proj): Linear(in_features=1024, out_features=3072, bias=False)
+          (up_proj): Linear(in_features=1024, out_features=3072, bias=False)
+          (down_proj): Linear(in_features=3072, out_features=1024, bias=False)
+          (act_fn): SiLU()
+        )
+        (input_layernorm): Qwen3RMSNorm((1024,), eps=1e-06)
+        (post_attention_layernorm): Qwen3RMSNorm((1024,), eps=1e-06)
+      )
+    )
+    (norm): Qwen3RMSNorm((1024,), eps=1e-06)
+    (rotary_emb): Qwen3RotaryEmbedding()
+  )
+  (lm_head): Linear(in_features=1024, out_features=151936, bias=False)
+)
+```
+
+```python
+model.enable_input_require_grads() # 开启梯度检查点时，要执行该方法
+```
+
+
+## Lora Config
+
+`LoraConfig`这个类中可以设置很多参数，比较重要的如下
+
+- `task_type`：模型类型，现在绝大部分 `decoder_only` 的模型都是因果语言模型 `CAUSAL_LM`
+- `target_modules`：需要训练的模型层的名字，主要就是 `attention`部分的层，不同的模型对应的层的名字不同
+- `r`：`LoRA` 的秩，决定了低秩矩阵的维度，较小的 `r` 意味着更少的参数
+- `lora_alpha`：缩放参数，与 `r` 一起决定了 `LoRA` 更新的强度。实际缩放比例为`lora_alpha/r`，在当前示例中是 `32 / 8 = 4` 倍
+- `lora_dropout`：应用于 `LoRA` 层的 `dropout rate`，用于防止过拟合
+
+
+```python
+from peft import LoraConfig, TaskType, get_peft_model
+
+config = LoraConfig(
+    task_type=TaskType.CAUSAL_LM,
+    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
+    inference_mode=False, # 训练模式
+    r=8, # Lora 秩
+    lora_alpha=32, # Lora alaph，具体作用参见 Lora 原理
+    lora_dropout=0.1# Dropout 比例
+)
+config
+```
+
+
+```python
+model = get_peft_model(model, config)
+config
+```
+
+
+```python
+model.print_trainable_parameters()  # 模型参数训练量只有0.8395%
+```
+
+> trainable params: 5,046,272 || all params: 601,096,192 || trainable%: 0.8395
+
+
+## Training Arguments
+
+- `output_dir`：模型的输出路径
+- `per_device_train_batch_size`：每张卡上的 `batch_size`
+- `gradient_accumulation_steps`: 梯度累计
+- `num_train_epochs`：顾名思义 `epoch`
+
+
+```python
+args = TrainingArguments(
+    output_dir="Qwen3_instruct_lora",
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    logging_steps=1,
+    num_train_epochs=3,
+    save_steps=50,
+    learning_rate=1e-4,
+    save_on_each_node=True,
+    gradient_checkpointing=True,
+    report_to="none",
+)
+```
+
+## SwanLab 简介
+
+[SwanLab](https://github.com/swanhubx/swanlab) 是一个开源的模型训练记录工具，面向 AI 研究者，提供了训练可视化、自动日志记录、超参数记录、实验对比、多人协同等功能。在 `SwanLab` 上，研究者能基于直观的可视化图表发现训练问题，对比多个实验找到研究灵感，并通过在线链接的分享与基于组织的多人协同训练，打破团队沟通的壁垒。
+
+**为什么要记录训练**
+
+相较于软件开发，模型训练更像一个实验科学。一个品质优秀的模型背后，往往是成千上万次实验。研究者需要不断尝试、记录、对比，积累经验，才能找到最佳的模型结构、超参数与数据配比。在这之中，如何高效进行记录与对比，对于研究效率的提升至关重要。
+
+`(2) Use an existing SwanLab account` 并使用 private API Key 登录
+
+```python
+import swanlab
+from swanlab.integration.transformers import SwanLabCallback
+
+# 实例化SwanLabCallback
+swanlab_callback = SwanLabCallback(
+    project="Qwen3-Lora",  # 注意修改
+    experiment_name="Qwen3-8B-LoRA-experiment"  # 注意修改
+)
+```
+
+
+```python
+import swanlab
+from swanlab.integration.transformers import SwanLabCallback
+
+# 实例化SwanLabCallback
+swanlab_callback = SwanLabCallback(
+    project="Qwen3-Lora",
+    experiment_name="Qwen3-0.6B-extarct-lora-2"
+)
+```
+
+
+```python
+trainer = Trainer(
+    model=model,
+    args=args,
+    train_dataset=tokenized_id,
+    data_collator=DataCollatorForSeq2Seq(tokenizer=tokenizer, padding=True),
+    callbacks=[swanlab_callback]
+)
+```
+
+
+```python
+trainer.train()
+```
+
+
+## 测试文本
+
+
+```python
+prompt = "龙琳   ，宁夏回族自治区璐市城东林街g座 955491，nafan@example.com。小区垃圾堆积成山，晚上噪音扰人清梦，停车难上加难，简直无法忍受！太插件了阿萨德看见啊啥的健康仨都会撒娇看到撒谎的、"
+
+messages = [
+    {"role": "system", "content": "将文本中的name、address、email、question提取出来，以json格式输出，字段为name、address、email、question，值为文本中提取出来的内容。"},
+    {"role": "user", "content": prompt}
+]
+
+inputs = tokenizer.apply_chat_template(messages,
+                                       add_generation_prompt=True,
+                                       tokenize=True,
+                                       return_tensors="pt",
+                                       return_dict=True,
+                                       enable_thinking=False).to('cuda')
+
+gen_kwargs = {"max_length": 2500, "do_sample": True, "top_k": 1}
+with torch.no_grad():
+    outputs = model.generate(**inputs, **gen_kwargs)
+    outputs = outputs[:, inputs['input_ids'].shape[1]:]
+    print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+
+```json
+{
+    "name": "龙琳",
+    "address": "宁夏回族自治区璐市城东林街g座 955491",
+    "email": "nafan@example.com",
+    "question": "小区垃圾堆积成山，晚上噪音扰人清梦，停车难上加难，简直无法忍受！太插件了阿萨德看见啊啥的健康仨都会撒娇看到撒谎的、"
+}
+```

README.md

@@ -4,9 +4,15 @@
 </div>
 
 <div align="center">
-  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub stars"/>
-  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub forks"/>
-  <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=for-the-badge" alt="Language"/>
+  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub stars"/>
+  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub forks"/>
+  <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
+  <a href="https://github.com/datawhalechina/happy-llm"><img src="https://img.shields.io/badge/GitHub-Project-blue?style=flat&logo=github" alt="GitHub Project"></a>
+  <a href="https://swanlab.cn/@kmno4/Happy-LLM/overview"><img src="https://raw.githubusercontent.com/SwanHubX/assets/main/badge1.svg" alt="SwanLab"></a>
+</div>
+
+<div align="center">
+  <a href="https://trendshift.io/repositories/14175" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14175" alt="datawhalechina%2Fhappy-llm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
 <div align="center">
@@ -16,6 +22,7 @@
 </div>
 
 <div align="center">
+  <p><a href="https://datawhalechina.github.io/happy-llm/">📚 在线阅读地址</a></p>
   <h3>📚 从零开始的大语言模型原理与实践教程</h3>
   <p><em>深入理解 LLM 核心原理，动手实现你的第一个大模型</em></p>
 </div>
@@ -42,14 +49,42 @@
 
 | 章节 | 关键内容 | 状态 |
 | --- | --- | --- |
-| [前言](./docs/README.md) | 本项目的缘起、背景及读者建议 | ✅ |
+| [前言](./docs/前言.md) | 本项目的缘起、背景及读者建议 | ✅ |
 | [第一章 NLP 基础概念](./docs/chapter1/第一章%20NLP基础概念.md) | 什么是 NLP、发展历程、任务分类、文本表示演进 | ✅ |
 | [第二章 Transformer 架构](./docs/chapter2/第二章%20Transformer架构.md) | 注意力机制、Encoder-Decoder、手把手搭建 Transformer | ✅ |
 | [第三章 预训练语言模型](./docs/chapter3/第三章%20预训练语言模型.md) | Encoder-only、Encoder-Decoder、Decoder-Only 模型对比 | ✅ |
 | [第四章 大语言模型](./docs/chapter4/第四章%20大语言模型.md) | LLM 定义、训练策略、涌现能力分析 | ✅ |
 | [第五章 动手搭建大模型](./docs/chapter5/第五章%20动手搭建大模型.md) | 实现 LLaMA2、训练 Tokenizer、预训练小型 LLM | ✅ |
-| [第六章 大模型训练实践](./docs/chapter6/第六章%20大模型训练流程实践.md) | 预训练、有监督微调、LoRA/QLoRA 高效微调 | ✅ |
+| [第六章 大模型训练实践](./docs/chapter6/第六章%20大模型训练流程实践.md) | 预训练、有监督微调、LoRA/QLoRA 高效微调 | 🚧 |
 | [第七章 大模型应用](./docs/chapter7/第七章%20大模型应用.md) | 模型评测、RAG 检索增强、Agent 智能体 | ✅ |
+| [Extra Chapter LLM Blog](./Extra-Chapter/) | 优秀的大模型 学习笔记/Blog ，欢迎大家来 PR ！| 🚧 |
+
+### Extra Chapter LLM Blog
+
+- [大模型都这么厉害了，微调0.6B的小模型有什么意义？](./Extra-Chapter/why-fine-tune-small-large-language-models/readme.md) @[不要葱姜蒜](https://github.com/KMnO4-zx) 2025-7-11
+
+- [Transformer 整体模块设计解读](./Extra-Chapter/transformer-architecture/) @[ditingdapeng](https://github.com/ditingdapeng) 2025-7-14
+
+- [文本数据处理详解](./Extra-Chapter/text-data-processing/readme.md) @[蔡鋆捷](https://github.com/xinala-781) 2025-7-14
+
+> &emsp;&emsp;*如果大家在学习 Happy-LLM 项目或 LLM 相关知识中有自己独到的见解、认知、实践，欢迎大家 PR 在 [Extra Chapter LLM Blog](./Extra-Chapter/) 中。请遵守 Extra Chapter LLM Blog 的 [PR 规范](./Extra-Chapter/Readme.md)，我们会视 PR 内容的质量和价值来决定是否合并或补充到 Happy-LLM 正文中来。*
+
+### 模型下载
+
+| 模型名称 | 下载地址 |
+| --- | --- |
+| Happy-LLM-Chapter5-Base-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-base) |
+| Happy-LLM-Chapter5-SFT-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-sft) |
+
+> *ModelScope 创空间体验地址：[🤖 创空间](https://www.modelscope.cn/studios/kmno4zx/happy_llm_215M_sft)*
+
+
+### PDF 版本下载
+
+&emsp;&emsp;***本 Happy-LLM PDF 教程完全开源免费。为防止各类营销号加水印后贩卖给大模型初学者，我们特地在 PDF 文件中预先添加了不影响阅读的 Datawhale 开源标志水印，敬请谅解～***
+
+> *Happy-LLM PDF : https://github.com/datawhalechina/happy-llm/releases/tag/PDF*  
+> *Happy-LLM PDF 国内下载地址 : https://www.datawhale.cn/learn/summary/179*  
 
 ## 💡 如何学习
 
@@ -77,6 +112,11 @@
 - [邹雨衡-项目负责人](https://github.com/logan-zou) (Datawhale成员-对外经济贸易大学)
 - [朱信忠-指导专家](https://xinzhongzhu.github.io/)（Datawhale首席科学家-浙江师范大学杭州人工智能研究院教授）
 
+### Extra-Chapter 贡献者
+
+- [ditingdapeng](https://github.com/ditingdapeng)（内容贡献者-云原生基础架构工程师）
+- [蔡鋆捷](https://github.com/xinala-781)（内容贡献者-福州大学）
+
 ### 特别感谢
 - 感谢 [@Sm1les](https://github.com/Sm1les) 对本项目的帮助与支持
 - 感谢所有为本项目做出贡献的开发者们 ❤️
@@ -90,7 +130,7 @@
 ## Star History
 
 <div align='center'>
-    <img src="./images/star-history-202566.png" alt="Datawhale" width="90%">
+    <img src="./images/star-history-2025710.png" alt="Datawhale" width="90%">
 </div>
 
 <div align="center">

README_en.md

@@ -4,11 +4,12 @@
 </div>
 
 <div align="center">
-  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub stars"/>
-  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub forks"/>
-  <img src="https://img.shields.io/badge/language-English-brightgreen?style=for-the-badge" alt="Language"/>
+  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub stars"/>
+  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub forks"/>
+  <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
+  <a href="https://github.com/datawhalechina/happy-llm"><img src="https://img.shields.io/badge/GitHub-Project-blue?style=flat&logo=github" alt="GitHub Project"></a>
+  <a href="https://swanlab.cn/@kmno4/Happy-LLM/overview"><img src="https://raw.githubusercontent.com/SwanHubX/assets/main/badge1.svg" alt="SwanLab"></a>
 </div>
-
 <div align="center">
 
 [中文](./README.md) | [English](./README_en.md)
@@ -16,6 +17,7 @@
 </div>
 
 <div align="center">
+  <p><a href="https://datawhalechina.github.io/happy-llm/">📚 Online Reading</a></p>
   <h3>📚 A Comprehensive Tutorial on Large Language Model Principles and Practice from Scratch</h3>
   <p><em>Deep understanding of LLM core principles, hands-on implementation of your first large model</em></p>
 </div>
@@ -48,9 +50,26 @@
 | [Chapter 3: Pre-trained Language Models](./docs/chapter3/第三章%20预训练语言模型.md) | Comparison of Encoder-only, Encoder-Decoder, Decoder-Only models | ✅ |
 | [Chapter 4: Large Language Models](./docs/chapter4/第四章%20大语言模型.md) | LLM definition, training strategies, emergent ability analysis | ✅ |
 | [Chapter 5: Building Large Models from Scratch](./docs/chapter5/第五章%20动手搭建大模型.md) | Implementing LLaMA2, training Tokenizer, pre-training small LLM | ✅ |
-| [Chapter 6: Large Model Training Practice](./docs/chapter6/第六章%20大模型训练流程实践.md) | Pre-training, supervised fine-tuning, LoRA/QLoRA efficient fine-tuning | ✅ |
+| [Chapter 6: Large Model Training Practice](./docs/chapter6/第六章%20大模型训练流程实践.md) | Pre-training, supervised fine-tuning, LoRA/QLoRA efficient fine-tuning | 🚧 |
 | [Chapter 7: Large Model Applications](./docs/chapter7/第七章%20大模型应用.md) | Model evaluation, RAG retrieval enhancement, Agent intelligent agents | ✅ |
 
+### Model Downloads
+
+| Model Name | Download Link |
+| --- | --- |
+| Happy-LLM-Chapter5-Base-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-base) |
+| Happy-LLM-Chapter5-SFT-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-sft) |
+
+> *ModelScope Studio Experience: [🤖 Studio](https://www.modelscope.cn/studios/kmno4zx/happy_llm_215M_sft)*
+
+
+### PDF Version Download
+
+&emsp;&emsp;***This Happy-LLM PDF tutorial is completely open source and free. To prevent various marketing accounts from adding watermarks and selling to LLM beginners, we have pre-added Datawhale open source logo watermarks that do not affect reading in the PDF files. Please understand~***
+
+> *Happy-LLM PDF : https://github.com/datawhalechina/happy-llm/releases/tag/PDF*  
+> *Happy-LLM PDF Domestic Download: https://www.datawhale.cn/learn/summary/179*
+
 ## 💡 How to Learn
 
 &emsp;&emsp;This project is suitable for university students, researchers, and LLM enthusiasts. Before learning this project, it is recommended to have some programming experience, especially familiarity with the Python programming language. It's best to have knowledge of deep learning and understand concepts and terminology in the NLP field to learn this project more easily.
@@ -90,7 +109,7 @@ We welcome any form of contribution!
 ## Star History
 
 <div align='center'>
-    <img src="./images/star-history-202566.png" alt="Datawhale" width="90%">
+    <img src="./images/star-history-2025710.png" alt="Datawhale" width="90%">
 </div>
 
 <div align="center">
@@ -101,11 +120,17 @@ We welcome any form of contribution!
 
 <div align='center'>
     <img src="./images/datawhale.png" alt="Datawhale" width="30%">
-    <p>Scan the QR code to follow Datawhale WeChat Official Account for more quality open-source content</p>
+    <p>Scan the QR code to follow Datawhale WeChat Official Account for more quality open source content</p>
 </div>
 
 ---
 
 ## 📜 Open Source License
 
+This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+---
+
+## 📜 Open Source License
+
 This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).

docs/README.md

@@ -4,15 +4,15 @@
 </div>
 
 <div align="center">
-  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub stars"/>
-  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=for-the-badge&logo=github" alt="GitHub forks"/>
-  <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=for-the-badge" alt="Language"/>
+  <img src="https://img.shields.io/github/stars/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub stars"/>
+  <img src="https://img.shields.io/github/forks/datawhalechina/happy-llm?style=flat&logo=github" alt="GitHub forks"/>
+  <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
+  <a href="https://github.com/datawhalechina/happy-llm"><img src="https://img.shields.io/badge/GitHub-Project-blue?style=flat&logo=github" alt="GitHub Project"></a>
+  <a href="https://swanlab.cn/@kmno4/Happy-LLM/overview"><img src="https://raw.githubusercontent.com/SwanHubX/assets/main/badge1.svg" alt="SwanLab"></a>
 </div>
 
 <div align="center">
-
-[中文](./README.md) | [English](./README_en.md)
-
+  <a href="https://trendshift.io/repositories/14175" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14175" alt="datawhalechina%2Fhappy-llm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
 <div align="center">
@@ -42,14 +42,30 @@
 
 | 章节 | 关键内容 | 状态 |
 | --- | --- | --- |
-| [前言](./docs/README.md) | 本项目的缘起、背景及读者建议 | ✅ |
-| [第一章 NLP 基础概念](./docs/chapter1/第一章%20NLP基础概念.md) | 什么是 NLP、发展历程、任务分类、文本表示演进 | ✅ |
-| [第二章 Transformer 架构](./docs/chapter2/第二章%20Transformer架构.md) | 注意力机制、Encoder-Decoder、手把手搭建 Transformer | ✅ |
-| [第三章 预训练语言模型](./docs/chapter3/第三章%20预训练语言模型.md) | Encoder-only、Encoder-Decoder、Decoder-Only 模型对比 | ✅ |
-| [第四章 大语言模型](./docs/chapter4/第四章%20大语言模型.md) | LLM 定义、训练策略、涌现能力分析 | ✅ |
-| [第五章 动手搭建大模型](./docs/chapter5/第五章%20动手搭建大模型.md) | 实现 LLaMA2、训练 Tokenizer、预训练小型 LLM | ✅ |
-| [第六章 大模型训练实践](./docs/chapter6/第六章%20大模型训练流程实践.md) | 预训练、有监督微调、LoRA/QLoRA 高效微调 | ✅ |
-| [第七章 大模型应用](./docs/chapter7/第七章%20大模型应用.md) | 模型评测、RAG 检索增强、Agent 智能体 | ✅ |
+| [前言](./前言.md) | 本项目的缘起、背景及读者建议 | ✅ |
+| [第一章 NLP 基础概念](./chapter1/第一章%20NLP基础概念.md) | 什么是 NLP、发展历程、任务分类、文本表示演进 | ✅ |
+| [第二章 Transformer 架构](./chapter2/第二章%20Transformer架构.md) | 注意力机制、Encoder-Decoder、手把手搭建 Transformer | ✅ |
+| [第三章 预训练语言模型](./chapter3/第三章%20预训练语言模型.md) | Encoder-only、Encoder-Decoder、Decoder-Only 模型对比 | ✅ |
+| [第四章 大语言模型](./chapter4/第四章%20大语言模型.md) | LLM 定义、训练策略、涌现能力分析 | ✅ |
+| [第五章 动手搭建大模型](./chapter5/第五章%20动手搭建大模型.md) | 实现 LLaMA2、训练 Tokenizer、预训练小型 LLM | ✅ |
+| [第六章 大模型训练实践](./chapter6/第六章%20大模型训练流程实践.md) | 预训练、有监督微调、LoRA/QLoRA 高效微调 | 🚧 |
+| [第七章 大模型应用](./chapter7/第七章%20大模型应用.md) | 模型评测、RAG 检索增强、Agent 智能体 | ✅ |
+
+### 模型下载
+
+| 模型名称 | 下载地址 |
+| --- | --- |
+| Happy-LLM-Chapter5-Base-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-base) |
+| Happy-LLM-Chapter5-SFT-215M | [🤖 ModelScope](https://www.modelscope.cn/models/kmno4zx/happy-llm-215M-sft) |
+
+> *ModelScope 创空间体验地址：[🤖 创空间](https://www.modelscope.cn/studios/kmno4zx/happy_llm_215M_sft)*
+
+### PDF 版本下载
+
+&emsp;&emsp;***本 Happy-LLM PDF 教程完全开源免费。为防止各类营销号加水印后贩卖给大模型初学者，我们特地在 PDF 文件中预先添加了不影响阅读的 Datawhale 开源标志水印，敬请谅解～***
+
+> *Happy-LLM PDF : https://github.com/datawhalechina/happy-llm/releases/tag/PDF*  
+> *Happy-LLM PDF 国内下载地址 : https://www.datawhale.cn/learn/summary/179* 
 
 ## 💡 如何学习
 
@@ -90,7 +106,7 @@
 ## Star History
 
 <div align='center'>
-    <img src="./images/star-history-202566.png" alt="Datawhale" width="90%">
+    <img src="./images/star-history-2025710.png" alt="Datawhale" width="90%">
 </div>
 
 <div align="center">

docs/chapter1/第一章 NLP基础概念.md

@@ -67,9 +67,9 @@ NLP 的早期探索始于二战后，当时人们认识到将一种语言自动
 子词切分的方法有很多种，常见的有Byte Pair Encoding (BPE)、WordPiece、Unigram、SentencePiece等。这些方法的基本思想是将单词分解成更小的、频繁出现的片段，这些片段可以是单个字符、字符组合或者词根和词缀。
 
 ```
-输出：unhappiness
+输入：unhappiness
 
-不使用子词切分：整个单词作为一个单位：“unhappiness”
+不使用子词切分：整个单词作为一个单位，输出：“unhappiness”
 使用子词切分（假设BPE算法）：单词被分割为：“un”、“happi”、“ness”
 ```
 
@@ -219,6 +219,7 @@ vector = [0, 0, ..., 1, 0, ..., 1, 0, ..., 1, 0, ..., 1, 0, ..., 1, 0, ...]
 # 实际有效维度：仅5维（非零维度）
 # 稀疏率：(16384-5)/16384 ≈ 99.97%
 ```
+> 词汇表是一个包含所有可能出现的词语的集合。在向量空间模型中，每个词对应词汇表中的一个位置，通过这种方式可以将词语转换为向量表示。例如，如果词汇表大小为 16384 ，那么每个词都会被表示为一个 16384 维的向量，其中只有该词对应的位置为 1，其他位置都为 0。
 
 为了解决这些问题，研究者们对向量空间模型的研究主要集中在两个方面：一是改进特征表示方法，如借助图方法、主题方法等进行关键词抽取；二是改进和优化特征项权重的计算方法，可以在现有方法的基础上进行融合计算或提出新的计算方法.
 

docs/chapter2/code/transformer.py

@@ -25,7 +25,7 @@ class MultiHeadAttention(nn.Module):
         # args: 配置对象
         super().__init__()
         # 隐藏层维度必须是头数的整数倍，因为后面我们会将输入拆成头数个矩阵
-        assert args.n_embd % args.n_heads == 0
+        assert args.dim % args.n_heads == 0
         # 模型并行处理大小，默认为1。
         model_parallel_size = 1
         # 本地计算头数，等于总头数除以模型并行处理大小。
@@ -36,11 +36,11 @@ class MultiHeadAttention(nn.Module):
         # Wq, Wk, Wv 参数矩阵，每个参数矩阵为 n_embd x n_embd
         # 这里通过三个组合矩阵来代替了n个参数矩阵的组合，其逻辑在于矩阵内积再拼接其实等同于拼接矩阵再内积，
         # 不理解的读者可以自行模拟一下，每一个线性层其实相当于n个参数矩阵的拼接
-        self.wq = nn.Linear(args.n_embd, args.n_heads * self.head_dim, bias=False)
-        self.wk = nn.Linear(args.n_embd, args.n_heads * self.head_dim, bias=False)
-        self.wv = nn.Linear(args.n_embd, args.n_heads * self.head_dim, bias=False)
-        # 输出权重矩阵，维度为 n_embd x n_embd（head_dim = n_embeds / n_heads）
-        self.wo = nn.Linear(args.n_heads * self.head_dim, args.dim, bias=False)
+        self.wq = nn.Linear(args.n_embd, args.n_local_heads * self.head_dim, bias=False)
+        self.wk = nn.Linear(args.n_embd, args.n_local_heads * self.head_dim, bias=False)
+        self.wv = nn.Linear(args.n_embd, args.n_local_heads * self.head_dim, bias=False)
+        # 输出权重矩阵，维度为 dim x n_embd（head_dim = n_embeds / n_heads）
+        self.wo = nn.Linear(args.n_local_heads * self.head_dim, args.dim, bias=False)
         # 注意力的 dropout
         self.attn_dropout = nn.Dropout(args.dropout)
         # 残差连接的 dropout
@@ -103,7 +103,7 @@ class MultiHeadAttention(nn.Module):
 class LayerNorm(nn.Module):
     ''' Layer Norm 层'''
     def __init__(self, features, eps=1e-6):
-        super(LayerNorm, self).__init__()
+        super().__init__()
         # 线性矩阵做映射
         self.a_2 = nn.Parameter(torch.ones(features))
         self.b_2 = nn.Parameter(torch.zeros(features))
@@ -130,7 +130,6 @@ class MLP(nn.Module):
     def forward(self, x):
         # 前向传播函数
         # 首先，输入x通过第一层线性变换和RELU激活函数
-        # 然后，结果乘以输入x通过第三层线性变换的结果
         # 最后，通过第二层线性变换和dropout层
         return self.dropout(self.w2(F.relu(self.w1(x))))
     
@@ -215,7 +214,7 @@ class PositionalEncoding(nn.Module):
     def __init__(self, args):
         super(PositionalEncoding, self).__init__()
         # Dropout 层
-        self.dropout = nn.Dropout(p=args.dropout)
+        # self.dropout = nn.Dropout(p=args.dropout)
 
         # block size 是序列的最大长度
         pe = torch.zeros(args.block_size, args.n_embd)
@@ -233,7 +232,7 @@ class PositionalEncoding(nn.Module):
     def forward(self, x):
         # 将位置编码加到 Embedding 结果上
         x = x + self.pe[:, : x.size(1)].requires_grad_(False)
-        return self.dropout(x)
+        return x
 
 
 class Transformer(nn.Module):
@@ -268,7 +267,7 @@ class Transformer(nn.Module):
         n_params = sum(p.numel() for p in self.parameters())
         # 如果不统计 embedding 的参数，就减去
         if non_embedding:
-            n_params -= self.transformer.wpe.weight.numel()
+            n_params -= self.transformer.wte.weight.numel()
         return n_params
 
     '''初始化权重'''

docs/chapter2/第二章 Transformer架构.md

@@ -6,24 +6,24 @@
 
 随着 NLP 从统计机器学习向深度学习迈进，作为 NLP 核心问题的文本表示方法也逐渐从统计学习向深度学习迈进。正如我们在第一章所介绍的，文本表示从最初的通过统计学习模型进行计算的向量空间模型、语言模型，通过 Word2Vec 的单层神经网络进入到通过神经网络学习文本表示的时代。但是，从 计算机视觉（Computer Vision，CV）为起源发展起来的神经网络，其核心架构有三种：
 
-- 前馈神经网络（Feedforward Neural Network，FNN），即每一层的神经元都和上下两层的每一个神经元完全连接，如图2.1所示:
+- 全连接神经网络（Feedforward Neural Network，FNN），即每一层的神经元都和上下两层的每一个神经元完全连接，如图2.1所示:
 
 <div align="center">
-  <img src="../images/2-figures/1-0.png" alt="图片描述" width="90%"/>
-  <p>图2.1 前馈神经网络</p>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/1-0.png" alt="图片描述" width="90%"/>
+  <p>图2.1 全连接神经网络</p>
 </div>
 
-- 卷积神经网络（Convolutional Neural Network，CNN），即训练参数量远小于前馈神经网络的卷积层来进行特征提取和学习，如图2.2所示:
+- 卷积神经网络（Convolutional Neural Network，CNN），即训练参数量远小于全连接神经网络的卷积层来进行特征提取和学习，如图2.2所示:
 
 <div align="center">
-  <img src="../images/2-figures/1-1.png" alt="图片描述" width="90%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/1-1.png" alt="图片描述" width="90%"/>
   <p>图2.2 卷积神经网络</p>
 </div>
 
 - 循环神经网络（Recurrent Neural Network，RNN），能够使用历史信息作为输入、包含环和自重复的网络，如图2.3所示:
 
 <div align="center">
-  <img src="../images/2-figures/1-2.png" alt="图片描述" width="90%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/1-2.png" alt="图片描述" width="90%"/>
   <p>图2.3 循环神经网络</p>
 </div>
 
@@ -87,7 +87,7 @@ $$
 
 根据词向量的定义，语义相似的两个词对应的词向量的点积应该大于0，而语义不相似的词向量点积应该小于0。
 
-那么，我们就可以用点积来计算词之间的相似度。假设我们的 Query 为“fruit”，对应的词向量为 $q$；我们的 Key 对应的词向量为 $k = [v_{apple} v_{banana} v_{chair}]$,则我们可以计算 Query 和每一个键的相似程度：
+那么，我们就可以用点积来计算词之间的相似度。假设我们的 Query 为“fruit”，对应的词向量为 $q$ ；我们的 Key 对应的词向量为 $k = [v_{apple} v_{banana} v_{chair}]$ ,则我们可以计算 Query 和每一个键的相似程度：
 
 $$
 x = qK^T
@@ -155,7 +155,7 @@ def attention(query, key, value, dropout=None):
 
 但是，在我们的实际应用中，我们往往只需要计算 Query 和 Key 之间的注意力结果，很少存在额外的真值 Value。也就是说，我们其实只需要拟合两个文本序列。​在经典的 注意力机制中，Q 往往来自于一个序列，K 与 V 来自于另一个序列，都通过参数矩阵计算得到，从而可以拟合这两个序列之间的关系。例如在 Transformer 的 Decoder 结构中，Q 来自于 Decoder 的输入，K 与 V 来自于 Encoder 的输出，从而拟合了编码信息与历史信息之间的关系，便于综合这两种信息实现未来的预测。
 
-​但在 Transformer 的 Encoder 结构中，使用的是 注意力机制的变种 —— 自注意力（self-attention，自注意力）机制。所谓自注意力，即是计算本身序列中每个元素都其他元素的注意力分布，即在计算过程中，Q、K、V 都由同一个输入通过不同的参数矩阵计算得到。在 Encoder 中，Q、K、V 分别是输入对参数矩阵 $W_q、W_k、W_v$ 做积得到，从而拟合输入语句中每一个 token 对其他所有 token 的关系。
+​但在 Transformer 的 Encoder 结构中，使用的是 注意力机制的变种 —— 自注意力（self-attention，自注意力）机制。所谓自注意力，即是计算本身序列中每个元素对其他元素的注意力分布，即在计算过程中，Q、K、V 都由同一个输入通过不同的参数矩阵计算得到。在 Encoder 中，Q、K、V 分别是输入对参数矩阵 $W_q、W_k、W_v$ 做积得到，从而拟合输入语句中每一个 token 对其他所有 token 的关系。
 
 通过自注意力机制，我们可以找到一段文本中每一个 token 与其他所有 token 的相关关系大小，从而建模文本之间的依赖关系。​在代码中的实现，self-attention 机制其实是通过给 Q、K、V 的输入传入同一个参数实现的：
 
@@ -187,7 +187,7 @@ attention(x, x, x)
     <BOS>    I   【MASK】 【MASK】【MASK】
     <BOS>    I     like  【MASK】【MASK】
     <BOS>    I     like    you  【MASK】
-    <BoS>    I     like    you   </EOS>
+    <BOS>    I     like    you   </EOS>
 
 在每一行输入中，模型仍然是只看到前面的 token，预测下一个 token。但是注意，上述输入不再是串行的过程，而可以一起并行地输入到模型中，模型只需要每一个样本根据未被遮蔽的 token 来预测下一个 token 即可，从而实现了并行的语言模型。
 
@@ -222,7 +222,7 @@ scores = F.softmax(scores.float(), dim=-1).type_as(xq)
 在原论文中，作者也通过实验证实，多头注意力计算中，每个不同的注意力头能够拟合语句中的不同信息，如图2.4所示：
 
 <div align="center">
-  <img src="../images/2-figures/1-3.jpeg" alt="图片描述" width="90%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/1-3.jpeg" alt="图片描述" width="90%"/>
   <p>图2.4 多头注意力机制</p>
 </div>
 
@@ -252,7 +252,7 @@ class MultiHeadAttention(nn.Module):
         # args: 配置对象
         super().__init__()
         # 隐藏层维度必须是头数的整数倍，因为后面我们会将输入拆成头数个矩阵
-        assert args.n_embd % args.n_heads == 0
+        assert args.dim % args.n_heads == 0
         # 模型并行处理大小，默认为1。
         model_parallel_size = 1
         # 本地计算头数，等于总头数除以模型并行处理大小。
@@ -263,11 +263,11 @@ class MultiHeadAttention(nn.Module):
         # Wq, Wk, Wv 参数矩阵，每个参数矩阵为 n_embd x n_embd
         # 这里通过三个组合矩阵来代替了n个参数矩阵的组合，其逻辑在于矩阵内积再拼接其实等同于拼接矩阵再内积，
         # 不理解的读者可以自行模拟一下，每一个线性层其实相当于n个参数矩阵的拼接
-        self.wq = nn.Linear(args.dim, args.n_heads * self.head_dim, bias=False)
-        self.wk = nn.Linear(args.dim, args.n_heads * self.head_dim, bias=False)
-        self.wv = nn.Linear(args.dim, args.n_heads * self.head_dim, bias=False)
-        # 输出权重矩阵，维度为 n_embd x n_embd（head_dim = n_embeds / n_heads）
-        self.wo = nn.Linear(args.n_heads * self.head_dim, args.dim, bias=False)
+        self.wq = nn.Linear(args.dim, args.n_local_heads * self.head_dim, bias=False)
+        self.wk = nn.Linear(args.dim, args.n_local_heads * self.head_dim, bias=False)
+        self.wv = nn.Linear(args.dim, args.n_local_heads * self.head_dim, bias=False)
+        # 输出权重矩阵，维度为 dim x n_embd（head_dim = n_embeds / n_heads）
+        self.wo = nn.Linear(args.n_local_heads * self.head_dim, args.dim, bias=False)
         # 注意力的 dropout
         self.attn_dropout = nn.Dropout(args.dropout)
         # 残差连接的 dropout
@@ -337,7 +337,7 @@ class MultiHeadAttention(nn.Module):
 
 ### 2.2.1 Seq2Seq 模型
 
-Seq2Seq，即序列到序列，是一种经典 NLP 任务。具体而言，是指模型输入的是一个自然语言序列 $input = (x_1, x_2, x_3...x_n)$，输出的是一个可能不等长的自然语言序列 $output = (y_1, y_2, y_3...y_m)$。事实上，Seq2Seq 是 NLP 最经典的任务，几乎所有的 NLP 任务都可以视为 Seq2Seq 任务。例如文本分类任务，可以视为输出长度为 1 的目标序列（如在上式中 $m$ = 1）；词性标注任务，可以视为输出与输入序列等长的目标序列（如在上式中 $m$ = $n$）。
+Seq2Seq，即序列到序列，是一种经典 NLP 任务。具体而言，是指模型输入的是一个自然语言序列 $input = (x_1, x_2, x_3...x_n)$ ，输出的是一个可能不等长的自然语言序列 $output = (y_1, y_2, y_3...y_m)$ 。事实上，Seq2Seq 是 NLP 最经典的任务，几乎所有的 NLP 任务都可以视为 Seq2Seq 任务。例如文本分类任务，可以视为输出长度为 1 的目标序列（如在上式中 $m$ = 1）；词性标注任务，可以视为输出与输入序列等长的目标序列（如在上式中 $m$ = $n$ ）。
 
 机器翻译任务即是一个经典的 Seq2Seq 任务，例如，我们的输入可能是“今天天气真好”，输出是“Today is a good day.”。Transformer 是一个经典的 Seq2Seq 模型，即模型的输入为文本序列，输出为另一个文本序列。事实上，Transformer 一开始正是应用在机器翻译任务上的。
 
@@ -346,7 +346,7 @@ Seq2Seq，即序列到序列，是一种经典 NLP 任务。具体而言，是
 Transformer 中的 Encoder，就是用于上述的编码过程；Decoder 则用于上述的解码过程。Transformer 结构，如图2.5所示：
 
 <div align="center">
-  <img src="../images/2-figures/2-0.jpg" alt="图片描述" width="90%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/2-0.jpg" alt="图片描述" width="90%"/>
   <p>图2.5 编码器-解码器结构</p>
 </div>
 
@@ -373,7 +373,6 @@ class MLP(nn.Module):
     def forward(self, x):
         # 前向传播函数
         # 首先，输入x通过第一层线性变换和RELU激活函数
-        # 然后，结果乘以输入x通过第三层线性变换的结果
         # 最后，通过第二层线性变换和dropout层
         return self.dropout(self.w2(F.relu(self.w1(x))))
     
@@ -424,7 +423,7 @@ $$
 class LayerNorm(nn.Module):
     ''' Layer Norm 层'''
     def __init__(self, features, eps=1e-6):
-	super(LayerNorm, self).__init__()
+	super().__init__()
     # 线性矩阵做映射
 	self.a_2 = nn.Parameter(torch.ones(features))
 	self.b_2 = nn.Parameter(torch.zeros(features))
@@ -540,7 +539,7 @@ class DecoderLayer(nn.Module):
         norm_x = self.attention_norm_2(x)
         h = x + self.attention.forward(norm_x, enc_out, enc_out)
         # 经过前馈神经网络
-        out = h + self.feed_forward.forward(self.fnn_norm(h))
+        out = h + self.feed_forward.forward(self.ffn_norm(h))
         return out
 ```
 
@@ -568,7 +567,7 @@ class Decoder(nn.Module):
 
 在前两章，我们分别深入剖析了 Attention 机制和 Transformer 的核心——Encoder、Decoder 结构，接下来，我们就可以基于上一章实现的组件，搭建起一个完整的 Transformer 模型。
 
-### 2.3.1 Embeddng 层
+### 2.3.1 Embedding 层
 
 正如我们在第一章所讲过的，在 NLP 任务中，我们往往需要将自然语言的输入转化为机器可以处理的向量。在深度学习中，承担这个任务的组件就是 Embedding 层。
 
@@ -590,7 +589,7 @@ output: 2
 因此，Embedding 层的输入往往是一个形状为 （batch_size，seq_len，1）的矩阵，第一个维度是一次批处理的数量，第二个维度是自然语言序列的长度，第三个维度则是 token 经过 tokenizer 转化成的 index 值。例如，对上述输入，Embedding 层的输入会是：
 
 ```
-[[0,1,2]]
+[[[0],[1],[2]]]
 ```
 
 其 batch_size 为1，seq_len 为3，转化出来的 index 如上。
@@ -618,7 +617,7 @@ $$
 
 ​上式中，pos 为 token 在句子中的位置，2i 和 2i+1 则是指示了 token 是奇数位置还是偶数位置，从上式中我们可以看出对于奇数位置的 token 和偶数位置的 token，Transformer 采用了不同的函数进行编码。
 
-我们以一个简单的例子来说明位置编码的计算过程：假如我们输入的是一个长度为 4 的句子"I like to code"，我们可以得到下面的词向量矩阵$\rm x$，其中每一行代表的就是一个词向量，$\rm x_0=[0.1,0.2,0.3,0.4]$对应的就是“I”的词向量，它的pos就是为0，以此类推，第二行代表的是“like”的词向量，它的pos就是1：
+我们以一个简单的例子来说明位置编码的计算过程：假如我们输入的是一个长度为 4 的句子"I like to code"，我们可以得到下面的词向量矩阵 $\rm x$ ，其中每一行代表的就是一个词向量， $\rm x_0=[0.1,0.2,0.3,0.4]$ 对应的就是“I”的词向量，它的pos就是为0，以此类推，第二行代表的是“like”的词向量，它的pos就是1：
 
 $$
 \rm x = \begin{bmatrix} 0.1 & 0.2 & 0.3 & 0.4 \\ 0.2 & 0.3 & 0.4 & 0.5 \\ 0.3 & 0.4 & 0.5 & 0.6 \\ 0.4 & 0.5 & 0.6 & 0.7 \end{bmatrix}
@@ -671,13 +670,13 @@ $$
 \begin{equation}\tilde{f}(\cdots,\boldsymbol{x}_m,\cdots,\boldsymbol{x}_n,\cdots)=f(\cdots,\boldsymbol{x}_m + \boldsymbol{p}_m,\cdots,\boldsymbol{x}_n + \boldsymbol{p}_n,\cdots)\end{equation}
 $$
 
-这里加上的 $p_m$，$p_n$ 就是位置编码。接下来我们将 $f(...,x_m+p_m,...,x_n+p_n)$ 在 m,n 两个位置上做泰勒展开：
+这里加上的 $p_m$， $p_n$ 就是位置编码。接下来我们将 $f(...,x_m+p_m,...,x_n+p_n)$ 在 m,n 两个位置上做泰勒展开：
 
 $$
 \begin{equation}\tilde{f}\approx f + \boldsymbol{p}_m^{\top} \frac{\partial f}{\partial \boldsymbol{x}_m} + \boldsymbol{p}_n^{\top} \frac{\partial f}{\partial \boldsymbol{x}_n} + \frac{1}{2}\boldsymbol{p}_m^{\top} \frac{\partial^2 f}{\partial \boldsymbol{x}_m^2}\boldsymbol{p}_m + \frac{1}{2}\boldsymbol{p}_n^{\top} \frac{\partial^2 f}{\partial \boldsymbol{x}_n^2}\boldsymbol{p}_n + \underbrace{\boldsymbol{p}_m^{\top} \frac{\partial^2 f}{\partial \boldsymbol{x}_m \partial \boldsymbol{x}_n}\boldsymbol{p}_n}_{\boldsymbol{p}_m^{\top} \boldsymbol{\mathcal{H}} \boldsymbol{p}_n}\end{equation}
 $$
 
-可以看到第1项与位置无关，2～5项仅依赖单一位置，第6项（f 分别对 m、n 求偏导）与两个位置有关，所以我们希望第六项（$p_m^THp_n$）表达相对位置信息，即求一个函数 g 使得:
+可以看到第1项与位置无关，2～5项仅依赖单一位置，第6项（f 分别对 m、n 求偏导）与两个位置有关，所以我们希望第六项（ $p_m^THp_n$ ）表达相对位置信息，即求一个函数 g 使得:
 
 $$
 p_m^THp_n = g(m-n)
@@ -732,7 +731,7 @@ $$
 上述​编码结果，如图2.6所示：
 
 <div align="center">
-  <img src="../images/2-figures/3-0.png" alt="图片描述" width="90%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/3-0.png" alt="图片描述" width="90%"/>
   <p>图2.6 编码结果</p>
 </div>
 
@@ -747,7 +746,7 @@ class PositionalEncoding(nn.Module):
     def __init__(self, args):
         super(PositionalEncoding, self).__init__()
         # Dropout 层
-        self.dropout = nn.Dropout(p=args.dropout)
+        # self.dropout = nn.Dropout(p=args.dropout)
 
         # block size 是序列的最大长度
         pe = torch.zeros(args.block_size, args.n_embd)
@@ -765,7 +764,7 @@ class PositionalEncoding(nn.Module):
     def forward(self, x):
         # 将位置编码加到 Embedding 结果上
         x = x + self.pe[:, : x.size(1)].requires_grad_(False)
-        return self.dropout(x)
+        return x
 ```
 
 ### 2.3.3 一个完整的 Transformer
@@ -773,10 +772,12 @@ class PositionalEncoding(nn.Module):
 上述所有组件，再按照下图的 Tranfromer 结构拼接起来就是一个完整的 Transformer 模型了，如图2.7所示：
 
 <div align="center">
-  <img src="../images/2-figures/3-1.png" alt="图片描述" width="80%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/2-figures/3-1.png" alt="图片描述" width="80%"/>
   <p>图2.7 Transformer 模型结构</p>
 </div>
 
+但需要注意的是，上图是原论文《Attention is all you need》配图，LayerNorm 层放在了 Attention 层后面，也就是“Post-Norm”结构，但在其发布的源代码中，LayerNorm 层是放在 Attention 层前面的，也就是“Pre Norm”结构。考虑到目前 LLM 一般采用“Pre-Norm”结构（可以使 loss 更稳定），本文在实现时采用“Pre-Norm”结构。
+
 如图，经过 tokenizer 映射后的输出先经过 Embedding 层和 Positional Embedding 层编码，然后进入上一节讲过的 N 个 Encoder 和 N 个 Decoder（在 Transformer 原模型中，N 取为6），最后经过一个线性层和一个 Softmax 层就得到了最终输出。
 
 基于之前所实现过的组件，我们实现完整的 Transformer 模型：
@@ -812,7 +813,7 @@ class Transformer(nn.Module):
         n_params = sum(p.numel() for p in self.parameters())
         # 如果不统计 embedding 的参数，就减去
         if non_embedding:
-            n_params -= self.transformer.wpe.weight.numel()
+            n_params -= self.transformer.wte.weight.numel()
         return n_params
 
     '''初始化权重'''

docs/chapter3/第三章 预训练语言模型.md

@@ -26,7 +26,7 @@ BERT 是一个统一了多种思想的预训练模型。其所沿承的核心思
 BERT 的模型架构是取了 Transformer 的 Encoder 部分堆叠而成，其主要结构如图3.1所示：
 
 <div align="center">
-  <img src="../images/3-figures/1-0.png" alt="图片描述" width="100%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-0.png" alt="图片描述" width="100%"/>
   <p>图3.1 BERT 模型结构</p>
 </div>
 
@@ -35,30 +35,33 @@ BERT 是针对于 NLU 任务打造的预训练模型，其输入一般是文本
 模型整体既是由 Embedding、Encoder 加上 prediction_heads 组成：
 
 <div align="center">
-  <img src="../images/3-figures/1-1.png" alt="图片描述" width="70%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-1.png" alt="图片描述" width="70%"/>
   <p>图3.2 BERT 模型简略结构</p>
 </div>
 
 输入的文本序列会首先通过 tokenizer（分词器） 转化成 input_ids（基本每一个模型在 tokenizer 的操作都类似，可以参考 Transformer 的 tokenizer 机制，后文不再赘述），然后进入 Embedding 层转化为特定维度的 hidden_states，再经过 Encoder 块。Encoder 块中是对叠起来的 N 层 Encoder Layer，BERT 有两种规模的模型，分别是 base 版本（12层 Encoder Layer，768 的隐藏层维度，总参数量 110M），large 版本（24层 Encoder Layer，1024 的隐藏层维度，总参数量 340M）。通过Encoder 编码之后的最顶层 hidden_states 最后经过 prediction_heads 就得到了最后的类别概率，经过 Softmax 计算就可以计算出模型预测的类别。
 
+
+> BERT 采用 WordPiece 作为分词方法。WordPiece 是一种基于统计的子词切分算法，其核心在于将单词拆解为子词（例如，"playing" -> ["play", "##ing"]）。其合并操作的依据是最大化语言模型的似然度。对于中文等非空格分隔的语言，通常将单个汉字作为原子分词单位（token）处理。
+
 prediction_heads 其实就是线性层加上激活函数，一般而言，最后一个线性层的输出维度和任务的类别数相等，如图3.3所示：
 
 <div align="center">
-  <img src="../images/3-figures/1-5.png" alt="图片描述" width="20%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-5.png" alt="图片描述" width="20%"/>
   <p>图3.3 prediction_heads 结构</p>
 </div>
 
 而每一层 Encoder Layer 都是和 Transformer 中的 Encoder Layer 结构类似的层，如图3.4所示：
 
 <div align="center">
-  <img src="../images/3-figures/1-2.png" alt="图片描述" width="40%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-2.png" alt="图片描述" width="40%"/>
   <p>图3.4 Encoder Layer 结构</p>
 </div>
 
 如图3.5所示，已经通过 Embedding 层映射的 hidden_states 进入核心的 attention 机制，然后通过残差连接的机制和原输入相加，再经过一层 Intermediate 层得到最终输出。Intermediate 层是 BERT 的特殊称呼，其实就是一个线性层加上激活函数：
 
 <div align="center">
-  <img src="../images/3-figures/1-3.png" alt="图片描述" width="40%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-3.png" alt="图片描述" width="40%"/>
   <p>图3.5 Intermediate 结构</p>
 </div>
 
@@ -71,7 +74,7 @@ GELU 的核心思路为将随机正则的思想引入激活函数，通过输入
 BERT 的 注意力机制和 Transformer 中 Encoder 的 自注意力机制几乎完全一致，但是 BERT 将相对位置编码融合在了注意力机制中，将相对位置编码同样视为可训练的权重参数，如图3.6所示：
 
 <div align="center">
-  <img src="../images/3-figures/1-4.png" alt="图片描述" width="40%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/1-4.png" alt="图片描述" width="40%"/>
   <p>图3.6 BERT 注意力机制结构</p>
 </div>
 
@@ -161,7 +164,7 @@ RoBERTa 使用了更大量的无监督语料进行预训练，除去 BERT 所使
 
 #### （3）优化三：更大的 bpe 词表
 
-RoBERTa、BERT 和 Transformer 一样，都使用了 BPE 作为 Tokenizer 的编码策略。BPE，即 Byte Pair Encoding，字节对编码，是指以子词对作为分词的单位。例如，对“Hello World”这句话，可能会切分为“Hel，lo，Wor，ld”四个子词对。而对于以字为基本单位的中文，一般会按照 字节编码进行切分。例如，在 UTF-8 编码中，“我”会被编码为“E68891”，那么在 BPE 中可能就会切分成“E68”，“891”两个字词对。
+与 BERT 使用的 WordPiece 算法不同，RoBERTa 使用了 BPE 作为 Tokenizer 的编码策略。BPE，即 Byte Pair Encoding，字节对编码，是指以子词对作为分词的单位。例如，对“Hello World”这句话，可能会切分为“Hel，lo，Wor，ld”四个子词对。而对于以字为基本单位的中文，一般会按照字节编码进行切分。例如，在 UTF-8 编码中，“我”会被编码为“E68891”，那么在 BPE 中可能就会切分成“E68”，“891”两个字词对。
 
 一般来说，BPE 编码的词典越大，编码效果越好。当然，由于 Embedding 层就是把 token 从词典空间映射到隐藏空间（也就是说 Embedding 的形状为 (vocab_size, hidden_size)，越大的词表也会带来模型参数的增加。
 
@@ -175,11 +178,11 @@ BERT 原始的 BPE 词表大小为 30K，RoBERTa 选择了 50K 大小的词表
 
 #### （1）优化一：将 Embedding 参数进行分解
 
-BERT 等预训练模型具有远超传统神经网络的参数量，如前所述，BERT-large 具有 24层 Encoder Layer，1024 的隐藏层维度，总共参数量达 340M。而这其中，Embedding 层的参数矩阵维度为 $V*H$，此处的 V 为词表大小 30K，H 即为隐藏层大小 768，也就是 Embedding 层参数达到了 23M。而这样的设置还会带来一个更大的问题，即 Google 探索尝试搭建更宽（也就是隐藏层维度更大）的模型时发现，隐藏层维度的增加会带来 Embedding 层参数的巨大上升，如果把隐藏层维度增加到 2048，Embedding 层参数就会膨胀到 61M，这无疑是极大增加了模型的计算开销。
+BERT 等预训练模型具有远超传统神经网络的参数量，如前所述，BERT-large 具有 24层 Encoder Layer，1024 的隐藏层维度，总共参数量达 340M。而这其中，Embedding 层的参数矩阵维度为 $V*H$，此处的 V 为词表大小 30K，H 即为隐藏层大小 1024，也就是 Embedding 层参数达到了 30M。而这样的设置还会带来一个更大的问题，即 Google 探索尝试搭建更宽（也就是隐藏层维度更大）的模型时发现，隐藏层维度的增加会带来 Embedding 层参数的巨大上升，如果把隐藏层维度增加到 2048，Embedding 层参数就会膨胀到 61M，这无疑是极大增加了模型的计算开销。
 
 而从另一个角度看，Embedding 层输出的向量是我们对文本 token 的稠密向量表示，从 Word2Vec 的成功经验来看，这种词向量并不需要很大的维度，Word2Vec 仅使用了 100维大小就取得了很好的效果。因此，Embedding 层的输出也许不需要和隐藏层大小一致。
 
-因此，ALBERT 对 Embedding 层的参数矩阵进行了分解，让 Embedding 层的输出维度和隐藏层维度解绑，也就是在 Embedding 层的后面加入一个线性矩阵进行维度变换。ALBERT 设置了 Embedding 层的输出为 128，因此在 Embedding 层后面加入了一个 $128*768$ 的线性矩阵来将 Embedding 层的输出再升维到隐藏层大小。也就是说，Embedding 层的参数从 $V*H$ 降低到了 $V*E + E*H$，当 E 的大小远小于 H 时，该方法对 Embedding 层参数的优化就会很明显。
+因此，ALBERT 对 Embedding 层的参数矩阵进行了分解，让 Embedding 层的输出维度和隐藏层维度解绑，也就是在 Embedding 层的后面加入一个线性矩阵进行维度变换。ALBERT 设置了 Embedding 层的输出为 128，因此在 Embedding 层后面加入了一个 $128*1024$ 的线性矩阵来将 Embedding 层的输出再升维到隐藏层大小。也就是说，Embedding 层的参数从 $V*H$ 降低到了 $V*E + E*H$，当 E 的大小远小于 H 时，该方法对 Embedding 层参数的优化就会很明显。
 
 #### （2）优化二：跨层进行参数共享
 
@@ -230,14 +233,14 @@ T5 的大一统思想将不同的 NLP 任务如文本分类、问答、翻译等
 BERT 采用了 Encoder-Only 结构，只包含编码器部分；而 GPT 采用了 Decoder-Only 结构，只包含解码器部分。T5 则采用了 Encoder-Decoder 结构，其中编码器和解码器都是基于 Transformer 架构设计。编码器用于处理输入文本，解码器用于生成输出文本。编码器和解码器之间通过注意力机制进行信息交互，从而实现输入文本到输出文本的转换。其主要结构如图3.7所示：
 
 <div align="center">
-  <img src="../images/3-figures/2-1.png" alt="图片描述" width="100%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/2-1.png" alt="图片描述" width="100%"/>
   <p>图3.7 T5 模型详细结构</p>
 </div>
 
 如图3.8所示，从整体来看 T5 的模型结构包括 Tokenizer 部分和 Transformer 部分。Tokenizer 部分主要负责将输入文本转换为模型可接受的输入格式，包括分词、编码等操作。Transformer 部分又分为 EncoderLayers 和 DecoderLayers 两部分，他们分别由一个个小的 Block组成，每个 Block 包含了多头注意力机制、前馈神经网络和 Norm 层。Block 的设计可以使模型更加灵活，像乐高一样可以根据任务的复杂程度和数据集的大小来调整 Block 的数量和层数。
 
 <div align="center">
-  <img src="../images/3-figures/2-2.png" alt="图片描述" width="70%"/>
+  <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/2-2.png" alt="图片描述" width="70%"/>
   <p>图3.8 T5 模型整体结构</p>
 </div>
 
@@ -246,28 +249,28 @@ T5 模型的 Encoder 和 Decoder 部分都是基于 Transformer 架构设计的
 和 Encoder 不一样的是，在 Decoder 中还包含了 Encoder-Decoder Attention 结构，用于捕捉输入和输出序列之间的依赖关系。这两种 Attention 结构几乎完全一致，只有在位置编码和 Mask 机制上有所不同。如图3.9所示，Encoder 和 Decoder 的结构如下：
 
 <div align='center'>
-    <img src="../images/3-figures/2-3.png" alt="alt text" width="50%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/2-3.png" alt="alt text" width="50%">
     <p>图3.9 Encoder 和 Decoder</p>
 </div>
 
 T5 的 Self-Attention 机制和 BERT 的 Attention 机制是一样的，都是基于 Self-Attention 机制设计的。Self-Attention 机制是一种全局依赖关系建模方法，通过计算 Query、Key 和 Value 之间的相似度来捕捉输入序列中的全局依赖关系。Encoder-Decoder Attention 仅仅在位置编码和 Mask 机制上有所不同，主要是为了区分输入和输出序列。如图3.10所示，Self-Attention 结构如下：
 
 <div align='center'>
-    <img src="../images/3-figures/2-4.png" alt="alt text" width="50%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/2-4.png" alt="alt text" width="50%">
     </p>图3.10 Self-Attention 结构</p>
 </div>
 
-与原始 Transformer 模型不同，T5 模型的LayerNorm 采用了 RMSNorm，通过计算每个神经元的均方根（Root Mean Square）来归一化每个隐藏层的激活值。RMSNorm 的参数设置与Layer Normalization 相比更简单，只有一个可调参数，可以更好地适应不同的任务和数据集。RMSNorm函数可以用以下数学公式表示：
+与原始 Transformer 模型不同，T5 模型的LayerNorm 采用了 RMSNorm，通过计算每个神经元的均方根（Root Mean Square）来归一化每个隐藏层的激活值。RMSNorm 的参数设置与Layer Normalization 相比更简单，只有一个可学参数，可以更好地适应不同的任务和数据集。RMSNorm函数可以用以下数学公式表示：
 
 $$
-\text{RMSNorm}(x) = \frac{x}{\sqrt{\frac{1}{n}\sum_{i=1}^{n}w_i^2 + \epsilon}}
+\text{RMSNorm}(x) = \frac{x}{\sqrt{\frac{1}{n}\sum_{i=1}^{n}x_i^2 + \epsilon}} \cdot \gamma
 $$
 
 其中：
-- \( $x$ \) 是层的输入。
-- \( $w_i$ \) 代表层的权重。
-- \( $n$ \) 是权重的数量。
-- \( $\epsilon$ \) 是一个小常数，用于数值稳定性（以避免除以零的情况）。
+- $x_i$ 是输入向量的第 $i$ 个元素
+- $\gamma$ 是可学习的缩放参数
+- $n$ 是输入向量的维度数量
+- $\epsilon$ 是一个小常数，用于数值稳定性（以避免除以零的情况）
 
 这种归一化有助于通过确保权重的规模不会变得过大或过小来稳定学习过程，这在具有许多层的深度学习模型中特别有用。
 
@@ -298,7 +301,7 @@ T5通过大规模的文本数据进行预训练，然后在具体任务上进行
 我们可以通过图3.11，更加直观地理解 T5 的大一统思想：
 
 <div align='center'>
-    <img src="../images/3-figures/2-0.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/2-0.png" alt="alt text" width="90%">
     <p>图3.11 T5 的大一统思想</p>
 </div>
 
@@ -323,7 +326,7 @@ GPT，即 Generative Pre-Training Language Model，是由 OpenAI 团队于 2018
 #### （1） 模型架构——Decoder Only
 
 <div align='center'>
-    <img src="../images/3-figures/3-0.png" alt="alt text" width="100%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/3-0.png" alt="alt text" width="100%">
     <p>图3.12 GPT 模型结构</p>
 </div>
 
@@ -394,7 +397,7 @@ LLaMA模型是由Meta（前Facebook）开发的一系列大型预训练语言模
 与GPT系列模型一样，LLaMA模型也是基于Decoder-Only架构的预训练语言模型。LLaMA模型的整体结构与GPT系列模型类似，只是在模型规模和预训练数据集上有所不同。如图3.13是LLaMA模型的架构示意图：
 
 <div align='center'>
-    <img src="../images/3-figures/3-1.png" alt="alt text" width="100%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/3-1.png" alt="alt text" width="100%">
     <p>图3.13 LLaMA-3 模型结构</p>
 </div>
 
@@ -446,7 +449,7 @@ GLM 最初是由清华计算机系推出的一种通用语言模型基座，其
 
 2. 使用单个线性层实现最终 token 的预测，而不是使用 MLP；这样的结构更加简单也更加鲁棒，即减少了最终输出的参数量，将更大的参数量放在了模型本身；
 
-3. 激活函数从 ReLU 换成了 GeLUS。ReLU 是传统的激活函数，其核心计算逻辑为去除小于 0的传播，保留大于 0的传播；GeLUS 核心是对接近于 0的正向传播，做了一个非线性映射，保证了激活函数后的非线性输出，具有一定的连续性。
+3. 激活函数从 ReLU 换成了 GeLUs。ReLU 是传统的激活函数，其核心计算逻辑为去除小于 0的传播，保留大于 0的传播；GeLUs 核心是对接近于 0的正向传播，做了一个非线性映射，保证了激活函数后的非线性输出，具有一定的连续性。
 
 #### （2）预训练任务-GLM
 
@@ -460,7 +463,7 @@ GLM 通过优化一个自回归空白填充任务来实现 MLM 与 CLM 思想的
 通过将 MLM 与 CLM 思想相结合，既适配逐个 token 生成的生成类任务，也迫使模型从前后两个方向学习输入文本的隐含关系从而适配了理解类任务。使用 GLM 预训练任务产出的 GLM 模型，在一定程度上展现了其超出同体量 BERT 系模型的优越性能：
 
 <div align='center'>
-    <img src="../images/3-figures/3-2.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/3-2.png" alt="alt text" width="90%">
     <p>图3.14 alt text</p>
 </div>
 
@@ -479,7 +482,7 @@ ChatGLM3-6B 发布于 23年 10月，相对于二代在语义、数学、推理
 图3.15展示了 GLM 系列模型在基准集上的表现演进：
 
 <div align='center'>
-    <img src="../images/3-figures/3-3.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/3-figures/3-3.png" alt="alt text" width="90%">
     <p>图3.15 alt text</p>
 </div>
 

docs/chapter4/第四章 大语言模型.md

@@ -96,13 +96,13 @@ LLM 的强大能力也为其带来了跨模态的强大表现。随着 LLM 的
 在上一节，我们分析了 LLM 的定义及其特有的强大能力，通过更大规模的参数和海量的训练语料获得远超传统预训练模型的涌现能力，展现出强大的上下文学习、指令遵循及逐步推理能力，带来 NLP 领域的全新变革。那么，通过什么样的步骤，我们才可以训练出一个具有涌现能力的 LLM 呢？训练一个 LLM，与训练传统的预训练模型，又有什么区别？
 
 <div align='center'>
-    <img src="../images/4-figures/2-0.jpg" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/4-figures/2-0.jpg" alt="alt text" width="90%">
     <p>图4.1 训练 LLM 的三个阶段</p>
 </div>
 
 一般而言，训练一个完整的 LLM 需要经过图1中的三个阶段——Pretrain、SFT 和 RLHF。在这一节，我们将详细论述训练 LLM 的三个阶段，并分析每一个阶段的过程及其核心难点、注意事项，帮助读者们从理论上了解要训练一个 LLM，需要经过哪些步骤。
 
-### 4.2.2 Pretrain
+### 4.2.1 Pretrain
 
 Pretrain，即预训练，是训练 LLM 最核心也是工程量最大的第一步。LLM 的预训练和传统预训练模型非常类似，同样是使用海量无监督文本对随机初始化的模型参数进行训练。正如我们在第三章中所见，目前主流的 LLM 几乎都采用了 Decoder-Only 的类 GPT 架构（LLaMA 架构），它们的预训练任务也都沿承了 GPT 模型的经典预训练任务——因果语言模型（Causal Language Model，CLM）。
 
@@ -128,7 +128,7 @@ GPT-3|96|12288|96|175B|300B
 也正因如此，分布式训练框架也成为 LLM 训练必不可少的组成部分。分布式训练框架的核心思路是数据并行和模型并行。所谓数据并行，是指训练模型的尺寸可以被单个 GPU 内存容纳，但是由于增大训练的 batch_size 会增大显存开销，无法使用较大的 batch_size 进行训练；同时，训练数据量非常大，使用单张 GPU 训练时长难以接受。
 
 <div align='center'>
-    <img src="../images/4-figures/2-1.jpg" alt="alt text" width="60%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/4-figures/2-1.jpg" alt="alt text" width="60%">
     <p>图4.2 模型、数据并行</p>
 </div>
 
@@ -137,7 +137,7 @@ GPT-3|96|12288|96|175B|300B
 但是，当 LLM 扩大到上百亿参数，单张 GPU 内存往往就无法存放完整的模型参数。如图4.3所示，在这种情况下，可以将模型拆分到多个 GPU 上，每个 GPU 上存放不同的层或不同的部分，从而实现模型并行。
 
 <div align='center'>
-    <img src="../images/4-figures/2-2.jpg" alt="alt text" width="30%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/4-figures/2-2.jpg" alt="alt text" width="30%">
     <p>图4.3 模型并行</p>
 </div>
 
@@ -179,11 +179,11 @@ StackExchange|2.0%|78 GB
 
 目前，已有很多经过处理的高质量预训练语料和专用于预训练数据处理的框架。例如，有基于 LLaMA 思路收集、清洗的预训练数据集[RedPajama-1T](https://huggingface.co/datasets/togethercomputer/RedPajama-Data-1T)，以及在 RedPajama 基础上进行筛选去重的[SlimPajama-627B](https://huggingface.co/datasets/cerebras/SlimPajama-627B/tree/main/train)数据集，实验证明高质量的 627B Slimpajama 数据集能够获得比 1T 的 RedPajama 数据集更好的效果。
 
-### 4.2.3 SFT
+### 4.2.2 SFT
 
 预训练是 LLM 强大能力的根本来源，事实上，LLM 所覆盖的海量知识基本都是源于预训练语料。LLM 的性能本身，核心也在于预训练的工作。但是，预训练赋予了 LLM 能力，却还需要第二步将其激发出来。经过预训练的 LLM 好像一个博览群书但又不求甚解的书生，对什么样的偏怪问题，都可以流畅地接出下文，但他偏偏又不知道问题本身的含义，只会“死板背书”。这一现象的本质是因为，LLM 的预训练任务就是经典的 CLM，也就是训练其预测下一个 token 的能力，在没有进一步微调之前，其无法与其他下游任务或是用户指令适配。
 
-因此，我们还需要第二步来教这个博览群书的学生如何去使用它的知识，也就是 SFT——Supervisor Finetune，有监督微调。所谓有监督微调，其实就是我们在第三章中讲过的预训练-微调中的微调，稍有区别的是，对于能力有限的传统预训练模型，我们需要针对每一个下游任务单独对其进行微调以训练模型在该任务上的表现。例如要解决文本分类问题，需要对 BERT 进行文本分类的微调；要解决实体识别的问题，就需要进行实体识别任务的微调。
+因此，我们还需要第二步来教这个博览群书的学生如何去使用它的知识，也就是 SFT（Supervised Fine-Tuning，有监督微调）。所谓有监督微调，其实就是我们在第三章中讲过的预训练-微调中的微调，稍有区别的是，对于能力有限的传统预训练模型，我们需要针对每一个下游任务单独对其进行微调以训练模型在该任务上的表现。例如要解决文本分类问题，需要对 BERT 进行文本分类的微调；要解决实体识别的问题，就需要进行实体识别任务的微调。
 
 而面对能力强大的 LLM，我们往往不再是在指定下游任务上构造有监督数据进行微调，而是选择训练模型的“通用指令遵循能力”，也就是一般通过`指令微调`的方式来进行 SFT。
 
@@ -196,7 +196,7 @@ StackExchange|2.0%|78 GB
 
 首先是指令数据量及覆盖范围。为了使 LLM 能够获得泛化的指令遵循能力，即能够在未训练的指令上表现良好，需要收集大量类别各异的用户指令和对应回复对 LLM 进行训练。一般来说，在单个任务上 500~1000 的训练样本就可以获得不错的微调效果。但是，为了让 LLM 获得泛化的指令遵循能力，在多种任务指令上表现良好，需要在训练数据集中覆盖多种类型的任务指令，同时也需要相对较大的训练数据量，表现良好的开源 LLM SFT 数据量一般在数 B token 左右。
 
-为提高 LLM 的泛化能力，指令数据集的覆盖范围自然是越大越好。但是，多种不同类型的指令数据之间的配比也是 LLM 训练的一大挑战。OpenAI 训练的 InstructGPT（即 ChatGPT 前身）使用了源自于用户使用其 API 的十种指令：
+为提高 LLM 的泛化能力，指令数据集的覆盖范围自然是越大越好。**但是**，多种不同类型的指令数据之间的配比也是 LLM 训练的一大挑战。OpenAI 训练的 InstructGPT（即 ChatGPT 前身）使用了源自于用户使用其 API 的十种指令：
 
 指令类型|占比
 -------|-----
@@ -290,14 +290,14 @@ StackExchange|2.0%|78 GB
 
 显然可知，第一种方式会丢失大量中间信息，第二种方式造成了大量重复计算，只有第三种方式是最合理的多轮对话构造。我们之所以可以以第三种方式来构造多轮对话样本，是因为 LLM 本质还是进行的 CLM 任务，进行单向注意力计算，因此在预测时会从左到右依次进行拟合，前轮的输出预测不会影响后轮的预测。目前，绝大部分 LLM 均使用了多轮对话的形式来进行 SFT。
 
-## 4.2.4 RLHF
+### 4.2.3 RLHF
 
 RLHF，全称是 Reinforcement Learning from Human Feedback，即人类反馈强化学习，是利用强化学习来训练 LLM 的关键步骤。相较于在 GPT-3 就已经初见雏形的 SFT，RLHF 往往被认为是 ChatGPT 相较于 GPT-3 的最核心突破。事实上，从功能上出发，我们可以将 LLM 的训练过程分成预训练与对齐（alignment）两个阶段。预训练的核心作用是赋予模型海量的知识，而所谓对齐，其实就是让模型与人类价值观一致，从而输出人类希望其输出的内容。在这个过程中，SFT 是让 LLM 和人类的指令对齐，从而具有指令遵循能力；而 RLHF 则是从更深层次令 LLM 和人类价值观对齐，令其达到安全、有用、无害的核心标准。
 
 如图4.4所示，ChatGPT 在技术报告中将对齐分成三个阶段，后面两个阶段训练 RM 和 PPO 训练，就是 RLHF 的步骤：
 
 <div align='center'>
-    <img src="../images/4-figures/2-3.png" alt="alt text" width="100%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/4-figures/2-3.png" alt="alt text" width="100%">
     <p>图4.4 ChatGPT 训练三个的阶段</p>
 </div>
 
@@ -331,7 +331,7 @@ RM，Reward Model，即奖励模型。RM 是用于拟合人类偏好，来给 LL
 在具体 PPO 训练过程中，会存在四个模型。如图4.5所示，两个 LLM 和两个 RM。两个 LLM 分别是进行微调、参数更新的 actor model 和不进行参数更新的 ref model，均是从 SFT 之后的 LLM 初始化的。两个 RM 分别是进行参数更新的 critic model 和不进行参数更新的 reward model，均是从上一步训练的 RM 初始化的。
 
 <div align='center'>
-    <img src="../images/4-figures/2-4.jpg" alt="alt text" width="100%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/4-figures/2-4.jpg" alt="alt text" width="100%">
     <p>图4.5 PPO 训练流程</p>
 </div>
 
@@ -339,9 +339,9 @@ RM，Reward Model，即奖励模型。RM 是用于拟合人类偏好，来给 LL
 
 1. 从 SFT 之后的 LLM 初始化两个模型分别作为 Actor Model 和 Ref Model；从训练的 RM 初始化两个模型分别作为 Reward Model 和 Critic Model；
 2. 输入一个 Prompt，Actor Model 和 Ref Model 分别就 Prompt 生成回复；
-3. Actor Response 和 Ref Response 计算 KL 散度：$r_{KL} = -\theta_{KL}D_{KL}(\pi_{PPO}(y|x)||\pi_{base}(y|x))$其中，$\pi_{PPO}(y|x)$即为 Actor Model 的输出，而 $\pi_{base}(y|x)$即为 Ref Model 的输出，$theta_{KL}D_{KL}$即是计算 KL 散度的方法；
+3. Actor Response 和 Ref Response 计算 KL 散度： $r_{KL} = -\theta_{KL}D_{KL}(\pi_{PPO}(y|x)||\pi_{base}(y|x))$ 其中， $\pi_{PPO}(y|x)$ 即为 Actor Model 的输出，而 $\pi_{base}(y|x)$ 即为 Ref Model 的输出， $\theta_{KL}D_{KL}$ 即是计算 KL 散度的方法；
 4. Actor Response 分别输入到 Reward Model 和 Critic Model 进行打分，其中，Reward Model 输出的是回复对应的标量奖励，Critic Model 还会输出累加奖励（即从i位置到最后的累积奖励）；
-5. 计算的 KL 散度、两个模型的打分均输入到奖励函数中，计算奖励：$loss = -(kl_{ctl}*r_{KL} + \gamma * V_{t+1} - V_{t})logP(A_t|V_t)$，这里的 $kl_{ctl}是控制 KL 散度对结果影响的权重参数，$\gamma$ 是控制下一个时间（也就是样本）打分对结果影响的权重参数，$V_t$ 是 Critic Model 的打分输出，$A_t$ 则是 Reward Model 的打分输出;
+5. 计算的 KL 散度、两个模型的打分均输入到奖励函数中，计算奖励： $loss = -(kl_{ctl} \cdot r_{KL} + \gamma \cdot V_{t+1} - V_{t}) \log P(A_t|V_t)$ ，这里的 $kl_{ctl}$ 是控制 KL 散度对结果影响的权重参数， $\gamma$ 是控制下一个时间（也就是样本）打分对结果影响的权重参数， $V_t$ 是 Critic Model 的打分输出， $A_t$ 则是 Reward Model 的打分输出;
 6. 根据奖励函数分别计算出的 actor loss 和 critic loss，更新 Actor Model 的参数和 Critic Model 的参数；注意，Actor Model 和 Critic Model 的参数更新方法是不同的，此处就不再一一赘述了，感兴趣的读者可以深入研究强化学习的相关理论。
 
 在上述过程中，因为要使用到四个模型，显存占用会数倍于 SFT。例如，如果我们 RM 和 LLM 都是用 7B 的体量，PPO 过程中大概需要 240G（4张 80G A100，每张卡占用 60G）显存来进行模型加载。那么，为什么我们需要足足四个模型呢？Actor Model 和 Critic Model 较为容易理解，而之所以我们还需要保持原参数不更新的 Ref Model 和 Reward Model，是为了限制模型的更新不要过于偏离原模型以至于丢失了 Pretrain 和 SFT 赋予的能力。

docs/chapter5/code/dataset.py

@@ -6,7 +6,6 @@ import pandas as pd
 import numpy as np
 from torch.utils.data import Dataset, DataLoader
 import torch
-from sklearn.model_selection import train_test_split
 import os
     
 class PretrainDataset(Dataset):
@@ -56,7 +55,7 @@ class SFTDataset(Dataset):
     def generate_loss_mask(self, input_ids):
         # 生成 loss mask, 0 表示不计算损失, 1 表示计算损失
         mask = [0] * len(input_ids)
-        a_sequence = [3, 1074, 537, 500, 203]  # <|im_start|>assistant\n
+        a_sequence = self.tokenizer("<|im_start|>assistant\n")['input_ids']  # <|im_start|>assistant\n
         a_length = len(a_sequence)
         n = len(input_ids)
         i = 0
@@ -69,10 +68,10 @@ class SFTDataset(Dataset):
                     match = False
                     break
             if match:
-                # 从子序列结束的位置开始查找第一个4
+                # 从子序列结束的位置开始查找第一个 4 (eos_token_id)
                 j = None
                 for idx in range(i + a_length, n):
-                    if input_ids[idx] == 4:
+                    if input_ids[idx] == self.tokenizer.eos_token_id:
                         j = idx
                         break
                 if j is not None:

docs/chapter5/code/ddp_pretrain.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 import os
 import platform
 import argparse
@@ -17,176 +18,306 @@ from dataset import PretrainDataset
 
 import swanlab
 
+# 忽略警告信息
 warnings.filterwarnings('ignore')
 
 
 def Logger(content):
+    """
+    简单的日志记录函数
+    
+    Args:
+        content (str): 要打印的内容
+    """
     print(content)
 
 def get_lr(it, all):
-    warmup_iters = args.warmup_iters
-    lr_decay_iters = all
-    min_lr = args.learning_rate / 10
+    """
+    计算当前迭代的学习率，使用余弦退火调度策略
+    
+    学习率调度策略：
+    1. Warmup阶段：学习率从0线性增长到目标学习率
+    2. 余弦退火阶段：学习率按余弦函数衰减到最小学习率
+    3. 超出训练步数后：保持最小学习率
+    
+    Args:
+        it (int): 当前迭代步数
+        all (int): 总迭代步数
+        
+    Returns:
+        float: 当前步数对应的学习率
+    """
+    warmup_iters = args.warmup_iters  # 预热迭代次数
+    lr_decay_iters = all  # 学习率衰减的总迭代次数
+    min_lr = args.learning_rate / 10  # 最小学习率，为初始学习率的1/10
 
+    # Warmup阶段：线性增长
     if it < warmup_iters:
         return args.learning_rate * it / warmup_iters
     
+    # 超出训练步数：保持最小学习率
     if it > lr_decay_iters:
         return min_lr
     
+    # 余弦退火阶段
     decay_ratio = (it - warmup_iters) / (lr_decay_iters - warmup_iters)
     assert 0 <= decay_ratio <= 1
-    coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))
+    coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))  # 余弦系数
     return min_lr + coeff * (args.learning_rate - min_lr)
 
 def train_epoch(epoch):
-    start_time = time.time()
+    """
+    训练一个epoch的函数
+    
+    实现了完整的训练循环，包括：
+    1. 数据加载和设备转移
+    2. 动态学习率调整
+    3. 前向传播和损失计算
+    4. 梯度累积和反向传播
+    5. 梯度裁剪和优化器更新
+    6. 日志记录和模型保存
+    
+    Args:
+        epoch (int): 当前epoch编号
+    """
+    start_time = time.time()  # 记录开始时间
+    
+    # 遍历数据加载器中的每个batch
     for step, (X, Y, loss_mask) in enumerate(train_loader):
-        X = X.to(args.device)
-        Y = Y.to(args.device)
-        loss_mask = loss_mask.to(args.device)
+        # 将数据转移到指定设备（GPU/CPU）
+        X = X.to(args.device)  # 输入序列
+        Y = Y.to(args.device)  # 目标序列
+        loss_mask = loss_mask.to(args.device)  # 损失掩码，用于忽略padding token
 
+        # 计算当前步骤的学习率
         lr = get_lr(epoch * iter_per_epoch + step, args.epochs * iter_per_epoch)
+        # 更新优化器中所有参数组的学习率
         for param_group in optimizer.param_groups:
             param_group['lr'] = lr
 
+        # 使用混合精度训练上下文
         with ctx:
+            # 前向传播
             out = model(X, Y)
+            # 计算损失并除以累积步数（用于梯度累积）
             loss = out.last_loss / args.accumulation_steps
+            # 将loss_mask展平为一维
             loss_mask = loss_mask.view(-1)
+            # 应用掩码计算有效损失（忽略padding位置）
             loss = torch.sum(loss * loss_mask) / loss_mask.sum()
 
+        # 使用scaler进行混合精度的反向传播
         scaler.scale(loss).backward()
 
+        # 每accumulation_steps步执行一次优化器更新
         if (step + 1) % args.accumulation_steps == 0:
+            # 取消梯度缩放，准备梯度裁剪
             scaler.unscale_(optimizer)
+            # 梯度裁剪，防止梯度爆炸
             torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
 
+            # 执行优化器步骤
             scaler.step(optimizer)
+            # 更新scaler的缩放因子
             scaler.update()
 
+            # 清零梯度，set_to_none=True可以节省内存
             optimizer.zero_grad(set_to_none=True)
 
+        # 每log_interval步记录一次日志
         if step % args.log_interval == 0:
             spend_time = time.time() - start_time
+            # 打印训练进度信息
             Logger(
-                'Epoch:[{}/{}]({}/{}) loss:{:.3f} lr:{:.7f} epoch_Time:{}min:'.format(
+                'Epoch:[{}/{}]({}/{}) loss:{:.3f} lr:{:.7f} epoch_Time:{}min;'.format(
                     epoch + 1,
                     args.epochs,
                     step,
                     iter_per_epoch,
-                    loss.item() * args.accumulation_steps,
+                    loss.item() * args.accumulation_steps,  # 恢复真实的loss值
                     optimizer.param_groups[-1]['lr'],
                     spend_time / (step + 1) * iter_per_epoch // 60 - spend_time // 60))
+            
+            # 如果启用SwanLab，记录训练指标
             if args.use_swanlab:
                 swanlab.log({
                     "loss": loss.item() * args.accumulation_steps,
                     "lr": optimizer.param_groups[-1]['lr']
                 })
 
+        # 每save_interval步保存一次模型
         if (step + 1) % args.save_interval == 0:
-            model.eval()
+            model.eval()  # 切换到评估模式
+            # 构建检查点文件名
             ckp = f'{args.save_dir}/pretrain_{lm_config.dim}_{lm_config.n_layers}_{lm_config.vocab_size}.pth'
 
-            # 处理多卡保存
+            # 处理多卡保存：如果是DataParallel模型，需要访问.module属性
             state_dict = model.module.state_dict() if isinstance(model, torch.nn.DataParallel) else model.state_dict()
             torch.save(state_dict, ckp)
-            model.train()
+            model.train()  # 切换回训练模式
         
+        # 每20000步保存一个带步数标记的检查点
         if (step + 1) % 20000 == 0:
             model.eval()
+            # 构建带步数的检查点文件名
             ckp = f'{args.save_dir}/pretrain_{lm_config.dim}_{lm_config.n_layers}_{lm_config.vocab_size}_step{step+1}.pth'
 
+            # 保存模型状态字典
             state_dict = model.module.state_dict() if isinstance(model, torch.nn.DataParallel) else model.state_dict()
             torch.save(state_dict, ckp)
             model.train()
 
 
 def init_model():
+    """
+    初始化模型和分词器
+    
+    功能包括：
+    1. 加载预训练的分词器
+    2. 创建Transformer模型
+    3. 设置多GPU并行训练（如果可用）
+    4. 将模型移动到指定设备
+    5. 统计并打印模型参数量
+    
+    Returns:
+        tuple: (model, tokenizer) 初始化后的模型和分词器
+    """
     def count_parameters(model):
+        """
+        统计模型中可训练参数的数量
+        
+        Args:
+            model: PyTorch模型
+            
+        Returns:
+            int: 可训练参数总数
+        """
         return sum(p.numel() for p in model.parameters() if p.requires_grad)
 
+    # 从本地路径加载预训练的分词器
     tokenizer = AutoTokenizer.from_pretrained('./tokenizer_k/')
 
+    # 根据配置创建Transformer模型
     model = Transformer(lm_config)
     
-    # 多卡初始化
+    # 多卡初始化：检查可用GPU数量并设置DataParallel
     num_gpus = torch.cuda.device_count()
     if num_gpus > 1:
         Logger(f"Using {num_gpus} GPUs with DataParallel!")
+        # 使用DataParallel包装模型以支持多GPU训练
         model = torch.nn.DataParallel(model)
     
+    # 将模型移动到指定设备（GPU或CPU）
     model = model.to(args.device)
+    
+    # 计算并打印模型参数量（以百万为单位）
     Logger(f'LLM总参数量：{count_parameters(model) / 1e6:.3f} 百万')
     return model, tokenizer
 
 
 if __name__ == "__main__":
+    # ==================== 命令行参数解析 ====================
     parser = argparse.ArgumentParser(description="Tiny-LLM Pretraining")
-    parser.add_argument("--out_dir", type=str, default="base_monkey_215M", help="Output directory")
-    parser.add_argument("--epochs", type=int, default=1, help="Number of epochs")
-    parser.add_argument("--batch_size", type=int, default=64, help="Batch size")
-    parser.add_argument("--learning_rate", type=float, default=2e-4, help="Learning rate")
-    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="Device to use")
-    parser.add_argument("--dtype", type=str, default="bfloat16", help="Data type")
-    parser.add_argument("--use_swanlab", type=bool, default=True, help="Use Weights & Biases")
-    parser.add_argument("--num_workers", type=int, default=8, help="Number of workers for data loading")
-    parser.add_argument("--data_path", type=str, default="", help="Path to training data")
-    parser.add_argument("--accumulation_steps", type=int, default=8, help="Gradient accumulation steps")
-    parser.add_argument("--grad_clip", type=float, default=1.0, help="Gradient clipping threshold")
-    parser.add_argument("--warmup_iters", type=int, default=0, help="Number of warmup iterations")
-    parser.add_argument("--log_interval", type=int, default=100, help="Logging interval")
-    parser.add_argument("--save_interval", type=int, default=1000, help="Model saving interval")
-    # 添加多卡参数
-    parser.add_argument("--gpus", type=str, default='0,1', help="Comma-separated GPU IDs (e.g. '0,1,2')")
+    
+    # 基础训练参数
+    parser.add_argument("--out_dir", type=str, default="base_model_215M", help="模型输出目录")
+    parser.add_argument("--epochs", type=int, default=1, help="训练轮数")
+    parser.add_argument("--batch_size", type=int, default=64, help="批次大小")
+    parser.add_argument("--learning_rate", type=float, default=2e-4, help="学习率")
+    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="训练设备")
+    parser.add_argument("--dtype", type=str, default="bfloat16", help="数据类型")
+    
+    # 实验跟踪和数据加载参数
+    parser.add_argument("--use_swanlab", action="store_true", help="是否使用SwanLab进行实验跟踪")
+    parser.add_argument("--num_workers", type=int, default=8, help="数据加载的工作进程数")
+    parser.add_argument("--data_path", type=str, default="./seq_monkey_datawhale.jsonl", help="训练数据路径")
+    
+    # 训练优化参数
+    parser.add_argument("--accumulation_steps", type=int, default=8, help="梯度累积步数")
+    parser.add_argument("--grad_clip", type=float, default=1.0, help="梯度裁剪阈值")
+    parser.add_argument("--warmup_iters", type=int, default=0, help="学习率预热迭代次数")
+    
+    # 日志和保存参数
+    parser.add_argument("--log_interval", type=int, default=100, help="日志记录间隔")
+    parser.add_argument("--save_interval", type=int, default=1000, help="模型保存间隔")
+    
+    # 多GPU训练参数
+    parser.add_argument("--gpus", type=str, default='0,1,2,3,4,5,6,7', help="使用的GPU ID，用逗号分隔 (例如: '0,1,2')")
 
     args = parser.parse_args()
 
-    # 设置可见GPU
+    # ==================== GPU环境设置 ====================
+    # 设置可见的GPU设备
     if args.gpus is not None:
         os.environ["CUDA_VISIBLE_DEVICES"] = args.gpus
-        # 自动设置主设备为第一个GPU
+        # 自动设置主设备为第一个可用GPU
         if torch.cuda.is_available():
             args.device = "cuda:0"
         else:
             args.device = "cpu"
 
+    # ==================== 实验跟踪初始化 ====================
     if args.use_swanlab:
-        swanlab.login(api_key='your key')
+        # 注意：使用前需要先登录 swanlab.login(api_key='your key')
         run = swanlab.init(
-            project="Tiny-LLM",
-            experiment_name="Pretrain-215M",
-            config=args,
+            project="Happy-LLM",  # 项目名称
+            experiment_name="Pretrain-215M",  # 实验名称
+            config=args,  # 保存所有超参数
         )
 
+    # ==================== 模型配置 ====================
+    # 定义语言模型的配置参数
     lm_config = ModelConfig(
-        dim=1024,
-        n_layers=18,
+        dim=1024,      # 模型维度
+        n_layers=18,   # Transformer层数
     )
-    max_seq_len = lm_config.max_seq_len
-    args.save_dir = os.path.join(args.out_dir)
-    os.makedirs(args.save_dir, exist_ok=True)
+
+    # ==================== 训练环境设置 ====================
+    max_seq_len = lm_config.max_seq_len  # 最大序列长度
+    args.save_dir = os.path.join(args.out_dir)  # 模型保存目录
+    
+    # 创建必要的目录
     os.makedirs(args.out_dir, exist_ok=True)
+    
+    # 设置随机种子以确保结果可复现
     torch.manual_seed(42)
+    
+    # 确定设备类型（用于选择合适的上下文管理器）
     device_type = "cuda" if "cuda" in args.device else "cpu"
 
+    # 设置混合精度训练的上下文管理器
+    # CPU训练时使用nullcontext，GPU训练时使用autocast
     ctx = nullcontext() if device_type == "cpu" else torch.cuda.amp.autocast()
 
+    # ==================== 模型和数据初始化 ====================
+    # 初始化模型和分词器
     model, tokenizer = init_model()
     
+    # 创建训练数据集
     train_ds = PretrainDataset(args.data_path, tokenizer, max_length=max_seq_len)
+    
+    # 创建数据加载器
     train_loader = DataLoader(
         train_ds,
-        batch_size=args.batch_size,
-        pin_memory=True,
-        drop_last=False,
-        shuffle=True,
-        num_workers=args.num_workers
+        batch_size=args.batch_size,  # 批次大小
+        pin_memory=True,             # 将数据加载到固定内存中，加速GPU传输
+        drop_last=False,             # 不丢弃最后一个不完整的批次
+        shuffle=True,                # 随机打乱数据
+        num_workers=args.num_workers # 数据加载的并行工作进程数
     )
 
+    # ==================== 优化器和训练组件初始化 ====================
+    # 初始化混合精度训练的梯度缩放器
+    # 只有在使用float16或bfloat16时才启用
     scaler = torch.cuda.amp.GradScaler(enabled=(args.dtype in ['float16', 'bfloat16']))
+    
+    # 初始化Adam优化器
     optimizer = optim.Adam(model.parameters(), lr=args.learning_rate)
 
+    # ==================== 开始训练 ====================
+    # 计算每个epoch的迭代次数
     iter_per_epoch = len(train_loader)
+    
+    # 开始训练循环
     for epoch in range(args.epochs):
         train_epoch(epoch)

docs/chapter5/code/ddp_sft_full.py

@@ -17,13 +17,18 @@ from dataset import SFTDataset
 
 import swanlab
 
+# 忽略警告
 warnings.filterwarnings('ignore')
 
 
 def Logger(content):
+    """日志记录器"""
     print(content)
 
 def get_lr(it, all):
+    """获取学习率"""
+    # 1) linear warmup for warmup_iters steps
+    # 1) 预热迭代的线性预热
     warmup_iters = args.warmup_iters
     lr_decay_iters = all
     min_lr = args.learning_rate / 10
@@ -31,33 +36,42 @@ def get_lr(it, all):
     if it < warmup_iters:
         return args.learning_rate * it / warmup_iters
     
+    # 2) if it > lr_decay_iters, return min learning rate
+    # 2) 如果迭代次数超过学习率衰减迭代次数，则返回最小学习率
     if it > lr_decay_iters:
         return min_lr
     
+    # 3) in between, use cosine decay down to min learning rate
+    # 3) 在两者之间，使用余弦衰减至最小学习率
     decay_ratio = (it - warmup_iters) / (lr_decay_iters - warmup_iters)
     assert 0 <= decay_ratio <= 1
     coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))
     return min_lr + coeff * (args.learning_rate - min_lr)
 
 def train_epoch(epoch):
+    """训练一个epoch"""
     start_time = time.time()
     for step, (X, Y, loss_mask) in enumerate(train_loader):
         X = X.to(args.device)
         Y = Y.to(args.device)
         loss_mask = loss_mask.to(args.device)
 
+        # 获取学习率并更新优化器
         lr = get_lr(epoch * iter_per_epoch + step, args.epochs * iter_per_epoch)
         for param_group in optimizer.param_groups:
             param_group['lr'] = lr
 
+        # 前向传播
         with ctx:
             out = model(X, Y)
             loss = out.last_loss / args.accumulation_steps
             loss_mask = loss_mask.view(-1)
             loss = torch.sum(loss * loss_mask) / loss_mask.sum()
 
+        # 反向传播
         scaler.scale(loss).backward()
 
+        # 更新权重
         if (step + 1) % args.accumulation_steps == 0:
             scaler.unscale_(optimizer)
             torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
@@ -67,6 +81,7 @@ def train_epoch(epoch):
 
             optimizer.zero_grad(set_to_none=True)
 
+        # 打印日志
         if step % args.log_interval == 0:
             spend_time = time.time() - start_time
             Logger(
@@ -84,6 +99,7 @@ def train_epoch(epoch):
                     "lr": optimizer.param_groups[-1]['lr']
                 })
 
+        # 保存模型
         if (step + 1) % args.save_interval == 0:
             model.eval()
             ckp = f'{args.save_dir}/sft_dim{lm_config.dim}_layers{lm_config.n_layers}_vocab_size{lm_config.vocab_size}.pth'
@@ -93,6 +109,7 @@ def train_epoch(epoch):
             torch.save(state_dict, ckp)
             model.train()
         
+        # 定期保存模型
         if (step + 1) % 20000 == 0:
             model.eval()
             ckp = f'{args.save_dir}/sft_dim{lm_config.dim}_layers{lm_config.n_layers}_vocab_size{lm_config.vocab_size}_step{step+1}.pth'
@@ -103,14 +120,19 @@ def train_epoch(epoch):
 
 
 def init_model():
+    """初始化模型"""
     def count_parameters(model):
+        """计算模型参数量"""
         return sum(p.numel() for p in model.parameters() if p.requires_grad)
 
+    # 加载分词器
     tokenizer = AutoTokenizer.from_pretrained('./tokenizer_k/')
 
+    # 初始化模型
     model = Transformer(lm_config)
 
-    ckp = './base_monkey_215M/pretrain_1024_18_6144.pth'
+    # 加载预训练权重
+    ckp = './base_model_215M/pretrain_1024_18_6144.pth'
     state_dict = torch.load(ckp, map_location=args.device)
     unwanted_prefix = '_orig_mod.'
     for k, v in list(state_dict.items()):
@@ -131,22 +153,22 @@ def init_model():
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Tiny-LLM Pretraining")
-    parser.add_argument("--out_dir", type=str, default="BeelGroup_sft_model_215M", help="Output directory")
-    parser.add_argument("--epochs", type=int, default=1, help="Number of epochs")
-    parser.add_argument("--batch_size", type=int, default=64, help="Batch size")
-    parser.add_argument("--learning_rate", type=float, default=2e-4, help="Learning rate")
-    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="Device to use")
-    parser.add_argument("--dtype", type=str, default="bfloat16", help="Data type")
-    parser.add_argument("--use_swanlab", type=bool, default=True, help="Use Weights & Biases")
-    parser.add_argument("--num_workers", type=int, default=4, help="Number of workers for data loading")
-    parser.add_argument("--data_path", type=str, default="", help="Path to training data")
-    parser.add_argument("--accumulation_steps", type=int, default=4, help="Gradient accumulation steps")
-    parser.add_argument("--grad_clip", type=float, default=1.0, help="Gradient clipping threshold")
-    parser.add_argument("--warmup_iters", type=int, default=0, help="Number of warmup iterations")
-    parser.add_argument("--log_interval", type=int, default=100, help="Logging interval")
-    parser.add_argument("--save_interval", type=int, default=1000, help="Model saving interval")
+    parser.add_argument("--out_dir", type=str, default="sft_model_215M", help="输出目录")
+    parser.add_argument("--epochs", type=int, default=1, help="训练轮数")
+    parser.add_argument("--batch_size", type=int, default=64, help="批处理大小")
+    parser.add_argument("--learning_rate", type=float, default=2e-4, help="学习率")
+    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="使用的设备")
+    parser.add_argument("--dtype", type=str, default="bfloat16", help="数据类型")
+    parser.add_argument("--use_swanlab", action="store_true", help="是否使用SwanLab进行实验跟踪")
+    parser.add_argument("--num_workers", type=int, default=8, help="数据加载的工作进程数")
+    parser.add_argument("--data_path", type=str, default="./BelleGroup_sft.jsonl", help="训练数据路径")
+    parser.add_argument("--accumulation_steps", type=int, default=8, help="梯度累积步数")
+    parser.add_argument("--grad_clip", type=float, default=1.0, help="梯度裁剪阈值")
+    parser.add_argument("--warmup_iters", type=int, default=0, help="预热迭代次数")
+    parser.add_argument("--log_interval", type=int, default=100, help="日志记录间隔")
+    parser.add_argument("--save_interval", type=int, default=1000, help="模型保存间隔")
     # 添加多卡参数
-    parser.add_argument("--gpus", type=str, default='0,1', help="Comma-separated GPU IDs (e.g. '0,1,2')")
+    parser.add_argument("--gpus", type=str, default='0,1,2,3,4,5,6,7', help="逗号分隔的GPU ID (例如 '0,1,2')")
 
     args = parser.parse_args()
 
@@ -159,29 +181,32 @@ if __name__ == "__main__":
         else:
             args.device = "cpu"
 
+    # 初始化swanlab
     if args.use_swanlab:
-        swanlab.login(api_key='your key')
         run = swanlab.init(
-            project="Tiny-LLM",
-            experiment_name="BelleGropu-sft-215M",
+            project="Happy-LLM",
+            experiment_name="SFT-215M",
             config=args,
         )
 
+    # 模型配置
     lm_config = ModelConfig(
         dim=1024,
         n_layers=18,
     )
     max_seq_len = lm_config.max_seq_len
     args.save_dir = os.path.join(args.out_dir)
-    os.makedirs(args.save_dir, exist_ok=True)
     os.makedirs(args.out_dir, exist_ok=True)
     torch.manual_seed(42)
     device_type = "cuda" if "cuda" in args.device else "cpu"
 
+    # 上下文管理器
     ctx = nullcontext() if device_type == "cpu" else torch.cuda.amp.autocast()
 
+    # 初始化模型和分词器
     model, tokenizer = init_model()
     
+    # 创建数据集和数据加载器
     train_ds = SFTDataset(args.data_path, tokenizer, max_length=max_seq_len)
     train_loader = DataLoader(
         train_ds,
@@ -192,9 +217,11 @@ if __name__ == "__main__":
         num_workers=args.num_workers
     )
 
+    # 缩放器和优化器
     scaler = torch.cuda.amp.GradScaler(enabled=(args.dtype in ['float16', 'bfloat16']))
-    optimizer = optim.Adam(model.parameters(), lr=args.learning_rate)
+    optimizer = optim.AdamW(model.parameters(), lr=args.learning_rate)
 
+    # 开始训练
     iter_per_epoch = len(train_loader)
     for epoch in range(args.epochs):
         train_epoch(epoch)

docs/chapter5/code/deal_dataset.py

@@ -1,32 +1,24 @@
-import os 
-from tqdm import tqdm
+import os
 import json
+from tqdm import tqdm
 
-# 设置环境变量
-os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
-
-
-# 下载预训练数据集
-os.system("modelscope download --dataset ddzhu123/seq-monkey mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2 --local_dir your_local_dir")
-# 解压预训练数据集
-os.system("tar -xvf your_local_dir/mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2")
-
-# 下载SFT数据集
-os.system(f'huggingface-cli download --repo-type dataset --resume-download BelleGroup/train_3.5M_CN --local-dir BelleGroup')
-
+# pretrain_data 为运行download_dataset.sh时，下载的pretrain_data本地路径
+pretrain_data = 'your local pretrain_data'
+output_pretrain_data = 'seq_monkey_datawhale.jsonl'
 
+# sft_data 为运行download_dataset.sh时，下载的sft_data本地路径
+sft_data = 'your local sft_data'
+output_sft_data = 'BelleGroup_sft.jsonl'
 
 # 1 处理预训练数据
 def split_text(text, chunk_size=512):
     """将文本按指定长度切分成块"""
     return [text[i:i+chunk_size] for i in range(0, len(text), chunk_size)]
 
-input_file = 'mobvoi_seq_monkey_general_open_corpus.jsonl'
-
-with open('seq_monkey_datawhale.jsonl', 'a', encoding='utf-8') as pretrain:
-    with open(input_file, 'r', encoding='utf-8') as f:
+with open(output_pretrain_data, 'a', encoding='utf-8') as pretrain:
+    with open(pretrain_data, 'r', encoding='utf-8') as f:
         data = f.readlines()
-        for line in tqdm(data, desc=f"Processing lines in {input_file}", leave=False):  # 添加行级别的进度条
+        for line in tqdm(data, desc=f"Processing lines in {pretrain_data}", leave=False):  # 添加行级别的进度条
             line = json.loads(line)
             text = line['text']
             chunks = split_text(text)
@@ -34,7 +26,6 @@ with open('seq_monkey_datawhale.jsonl', 'a', encoding='utf-8') as pretrain:
                 pretrain.write(json.dumps({'text': chunk}, ensure_ascii=False) + '\n')
 
 # 2 处理SFT数据
-
 def convert_message(data):
     """
     将原始数据转换为标准格式
@@ -49,10 +40,10 @@ def convert_message(data):
             message.append({'role': 'assistant', 'content': item['value']})
     return message
 
-with open('BelleGroup_sft.jsonl', 'a', encoding='utf-8') as sft:
-    with open('BelleGroup/train_3.5M_CN.json', 'r') as f:
+with open(output_sft_data, 'a', encoding='utf-8') as sft:
+    with open(sft_data, 'r', encoding='utf-8') as f:
         data = f.readlines()
         for item in tqdm(data, desc="Processing", unit="lines"):
             item = json.loads(item)
             message = convert_message(item['conversations'])
-            sft.write(json.dumps(message, ensure_ascii=False) + '\n')
+            sft.write(json.dumps(message, ensure_ascii=False) + '\n')

docs/chapter5/code/download_dataset.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# 设置环境变量
+export HF_ENDPOINT=https://hf-mirror.com
+
+# dataset dir 下载到本地目录
+dataset_dir="your local dataset dir"
+
+# 下载预训练数据集， 需要预先安装modelscope，使用pip3 install modelscope安装
+modelscope download --dataset ddzhu123/seq-monkey mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2 --local_dir ${dataset_dir}
+
+# 解压预训练数据集
+tar -xvf "${dataset_dir}/mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2" -C "${dataset_dir}"
+
+# 下载SFT数据集
+huggingface-cli download \
+  --repo-type dataset \
+  --resume-download \
+  BelleGroup/train_3.5M_CN \
+  --local-dir "${dataset_dir}/BelleGroup"

docs/chapter5/code/model_sample.py

@@ -8,7 +8,7 @@ import argparse
 
 class TextGenerator:
     def __init__(self, 
-                 checkpoint='out/SkyWork_pretrain_768_12_6144.pth',  # 模型检查点路径
+                 checkpoint='./base_model_215M/pretrain_1024_18_6144.pth',  # 模型检查点路径
                  tokenizer_model_path='./tokenizer_k/',  # 分词器模型路径
                  seed=42,  # 随机种子，确保可重复性
                  device=None,  # 设备，优先使用 CUDA，如果没有可用的 CUDA，则使用 CPU
@@ -55,7 +55,7 @@ class TextGenerator:
 
     def chat_template(self, prompt):
         message = [
-            {"role": "system", "content": "你是一个AI助手。"},
+            {"role": "system", "content": "你是一个AI助手，你的名字叫小明。"},
             {"role": "user", "content": prompt}
         ]
         return self.tokenizer.apply_chat_template(message, tokenize=False, add_generation_prompt=True)
@@ -126,18 +126,6 @@ class TextGenerator:
         return generated_texts  # 返回生成的文本样本
     
 if __name__ == "__main__":
-    print("\n ------------------- SFT Sample ------------------- \n")
-    sft_prompt_datas = [
-        '你好呀',
-        "中国的首都是哪里？",
-        "1+1等于多少？",
-    ]
-    generator = TextGenerator(checkpoint='./BeelGroup_sft_model_215M/sft_dim1024_layers18_vocab_size6144.pth')  # 初始化生成器
-    for i in range(len(sft_prompt_datas)):
-        samples = generator.sft_sample(start=sft_prompt_datas[i], num_samples=1, max_new_tokens=512, temperature=0.75)
-        print(f"\nSample {i+1}:\nQuestion: {sft_prompt_datas[i]} \nAI answer: {samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
-
-    
     print("------------------- Pretrain Sample ------------------- \n")
 
     pretrain_prompt_datas = [
@@ -145,7 +133,22 @@ if __name__ == "__main__":
         '<|im_start|>中国矿业大学（北京）地球科学与测绘工程学院',
     ]
 
-    generator = TextGenerator(checkpoint='./base_monkey_215M/pretrain_1024_18_6144.pth')  # 初始化生成器
+    generator = TextGenerator(checkpoint='./base_model_215M/pretrain_1024_18_6144.pth')  # 初始化生成器
     for i in range(len(pretrain_prompt_datas)):
-        samples = generator.pretrain_sample(start=pretrain_prompt_datas[i], num_samples=1, max_new_tokens=120, temperature=1.0)
-        print(f"\nSample {i+1}:\n{pretrain_prompt_datas[i]}{samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
+        samples = generator.pretrain_sample(start=pretrain_prompt_datas[i], num_samples=1, max_new_tokens=120, temperature=0.75)
+        print(f"\nSample {i+1}:\n{pretrain_prompt_datas[i]}{samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
+
+    print("\n ------------------- SFT Sample ------------------- \n")
+
+    sft_prompt_datas = [
+        '你好呀',
+        "中国的首都是哪里？",
+        "1+12等于多少？",
+        "你是谁？"
+    ]
+    generator = TextGenerator(checkpoint='./sft_model_215M/sft_dim1024_layers18_vocab_size6144.pth')  # 初始化生成器
+    for i in range(len(sft_prompt_datas)):
+        samples = generator.sft_sample(start=sft_prompt_datas[i], num_samples=1, max_new_tokens=128, temperature=0.6)
+        print(f"\nSample {i+1}:\nQuestion: {sft_prompt_datas[i]} \nAI answer: {samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
+
+    

docs/chapter5/code/windows_download_dataset.sh

@@ -0,0 +1,35 @@
+# Windows下载方式
+# 使用PowerShell下载
+# 暂时为当前PowerShell界面设置环境，关闭Powershell环境自动消失
+$env:HF_ENDPOINT = "https://hf-mirror.com"
+
+# 将\path\to\your\dataset替换成想要下载dataset目录地址
+$dataset_dir = "\path\to\your\dataset"
+
+# 需要预先安装modelscope，使用pip install modelscope安装
+modelscope download --dataset ddzhu123/seq-monkey mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2 --local_dir "$dataset_dir"
+
+tar -xvf "$dataset_dir\mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2" -C "$dataset_dir"
+
+huggingface-cli download `
+  --repo-type dataset `
+  --resume-download `
+  BelleGroup/train_3.5M_CN `
+  --local-dir "$dataset_dir\BelleGroup"
+
+# 使用CMD下载
+# 暂时为当前CMD界面设置环境，关闭CMD环境自动消失
+set HF_ENDPOINT=https://hf-mirror.com
+
+# 将\path\to\your\dataset替换成想要下载dataset目录地址
+set dataset_dir=\path\to\your\dataset
+
+modelscope download --dataset ddzhu123/seq-monkey mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2 --local_dir %dataset_dir%
+
+tar -xvf "%dataset_dir%\mobvoi_seq_monkey_general_open_corpus.jsonl.tar.bz2" -C "%dataset_dir%"
+
+huggingface-cli download ^
+  --repo-type dataset ^
+  --resume-download ^
+  BelleGroup/train_3.5M_CN ^
+  --local-dir "%dataset_dir%\BelleGroup"

docs/chapter5/第五章 动手搭建大模型.md

@@ -2,13 +2,13 @@
 
 ## 5.1 动手实现一个 LLaMA2 大模型
 
-Meta（原Facebook）于2023年2月发布第一款基于Transformer结构的大型语言模型LLaMA，并于同年7月发布同系列模型LLaMA2。我们在第四章已经学习了解的了LLM，记忆如何训练LLM等等。那本小节我们就来学习，如何动手写一个LLaMA2模型。
+Meta（原Facebook）于2023年2月发布第一款基于Transformer结构的大型语言模型LLaMA，并于同年7月发布同系列模型LLaMA2。我们在第四章已经学习和了解了LLM，以及如何训练LLM等内容。本小节我们就来学习如何动手实现一个LLaMA2模型。
 
-LLaMA2 模型结构如下图5.0所示：
+LLaMA2 模型结构如下图5.1所示：
 
 <div align='center'>
-    <img src="../images/5-images/LLama2.png" alt="alt text" width="100%">
-    <p>图 5.0 LLaMA2结构</p>
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/5-images/LLama2.png" alt="alt text" width="100%">
+    <p>图 5.1 LLaMA2结构</p>
 </div>
 
 ### 5.1.1 定义超参数
@@ -51,6 +51,8 @@ class ModelConfig(PretrainedConfig):
         super().__init__(**kwargs)
 ```
 
+> 在以下代码中出现 `args` 时，即默认为以上 `ModelConfig` 参数配置。
+
 我们来看一下其中的一些超参数的含义，比如`dim`是模型维度，`n_layers`是Transformer的层数，`n_heads`是注意力机制的头数，`vocab_size`是词汇表大小，`max_seq_len`是输入的最大序列长度等等。上面的代码中也对每一个参数做了详细的注释，在后面的代码中我们会根据这些超参数来构建我们的模型。
 
 ### 5.1.2 构建 RMSNorm
@@ -104,13 +106,18 @@ output = norm(x)
 print(output.shape)
 
 out:
-orch.Size([1, 50, 288])
+torch.Size([1, 50, 768])
 ```
 
 ### 5.1.3 构建 LLaMA2 Attention
 
 在 LLaMA2 模型中，虽然只有 LLaMA2-70B模型使用了分组查询注意力机制（Grouped-Query Attention，GQA），但我们依然选择使用 GQA 来构建我们的 LLaMA Attention 模块，它可以提高模型的效率，并节省一些显存占用。
 
+<div align='center'>
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/5-images/llama2-attention.png" alt="alt text" width="50%">
+    <p>图 5.2 LLaMA2 Attention 结构</p>
+</div>
+
 #### 5.1.3.1 repeat_kv
 
 在 LLaMA2 模型中，我们需要将键和值的维度扩展到和查询的维度一样，这样才能进行注意力计算。我们可以通过如下代码实现`repeat_kv`：
@@ -654,7 +661,7 @@ torch.Size([1, 1, 6144])
 
 在自然语言处理 (NLP) 中，Tokenizer 是一种将文本分解为较小单位（称为 token）的工具。这些 token 可以是词、子词、字符，甚至是特定的符号。Tokenization 是 NLP 中的第一步，直接影响后续处理和分析的效果。不同类型的 tokenizer 适用于不同的应用场景，以下是几种常见的 tokenizer 及其特点。
 
-### 5.3.1 Word-based Tokenizer
+### 5.2.1 Word-based Tokenizer
 
 **Word-based Tokenizer** 是最简单和直观的一种分词方法。它将文本按空格和标点符号分割成单词。这种方法的优点在于其简单和直接，易于实现，且与人类对语言的直觉相符。然而，它也存在一些明显的缺点，如无法处理未登录词（OOV，out-of-vocabulary）和罕见词，对复合词（如“New York”）或缩略词（如“don't”）的处理也不够精细。此外，Word-based Tokenizer 在处理不同语言时也会遇到挑战，因为一些语言（如中文、日文）没有显式的单词分隔符。
 
@@ -759,34 +766,26 @@ from typing import Generator
 
 #### Step 2: 加载训练数据
 
-我们使用 `datasets.load_dataset()` 库加载一个英文文本数据集，用于训练 BPE Tokenizer。这里我们使用 `wikitext` 数据集，包含了维基百科的文章文本。
+这里我们使用与预训练相同的数据集（出门问问序列猴子开源数据集）训练tokenizer，可使用`code/download_dataset.sh` 和 `code/deal_dataset.py` 下载和预处理数据集。
+
+> 注：由于数据集过大，可能会导致在训练过程中内存不足。因为本项目为学习目的，建议学习者手动分割小部分数据集用于训练验证，笔者也在 Github 仓库中存放了训练好的 tokenizer，可以直接使用。
 
 ```python
-dataset = load_dataset("wikitext", "wikitext-103-v1", split="train")
-
-# 准备训练数据
-def batch_iterator(batch_size=1000):
-    for i in range(0, len(dataset), batch_size):
-        yield dataset[i:i + batch_size]["text"]
-```
-
-如果你使用本地的文本数据集，可以将数据加载到一个列表中，然后传入 `batch_iterator()` 函数中。如下所示：
-
-```python
-def load_text_from_files(path_list):
-    text_data = []
-    for file_path in path_list:
-        with open(file_path, 'r', encoding='utf-8') as file:
-            text_data.extend(file.readlines())
-    return text_data
-
-def batch_iterator(text_data, batch_size=1000):
-    for i in range(0, len(text_data), batch_size):
-        yield text_data[i:i + batch_size]
-
-# 假设你的文件路径列表是
-path_list = ['text_data1.txt', 'text_data2.txt', 'text_data3.txt']
-text_data = load_text_from_files(path_list)
+def read_texts_from_jsonl(file_path: str) -> Generator[str, None, None]:
+    """读取JSONL文件并安全提取文本数据"""
+    with open(file_path, 'r', encoding='utf-8') as f:
+        for line_num, line in enumerate(f, 1):
+            try:
+                data = json.loads(line)
+                if 'text' not in data:
+                    raise KeyError(f"Missing 'text' field in line {line_num}")
+                yield data['text']
+            except json.JSONDecodeError:
+                print(f"Error decoding JSON in line {line_num}")
+                continue
+            except KeyError as e:
+                print(e)
+                continue
 ```
 
 #### Step 3: 创建配置文件
@@ -991,7 +990,7 @@ Special tokens preserved: False
 
 在前面的章节中，我们熟悉了各种大模型的模型结构，以及如如何训练Tokenizer。在本节中，我们将动手训练一个八千万参数的LLM。
 
-### 5.3.0 数据下载
+### 5.3.1 数据下载
 
 首先，我们需要下载预训练数据集。在这里，我们使用两个开源的数据集，包含了大量的中文对话数据，可以用于训练对话生成模型。
 
@@ -1045,7 +1044,7 @@ def convert_message(data):
     return message
 
 with open('BelleGroup_sft.jsonl', 'a', encoding='utf-8') as sft:
-    with open('BelleGroup/train_3.5M_CN.json', 'r') as f:
+    with open('BelleGroup/train_3.5M_CN.json', 'r', encoding='utf-8') as f:
         data = f.readlines()
         for item in tqdm(data, desc="Processing", unit="lines"):
             item = json.loads(item)
@@ -1053,7 +1052,7 @@ with open('BelleGroup_sft.jsonl', 'a', encoding='utf-8') as sft:
             sft.write(json.dumps(message, ensure_ascii=False) + '\n')
 ```
 
-### 5.3.1 训练Tokenize
+### 5.3.2 训练 Tokenizer
 
 首先，我们需要为文本处理训练一个Tokenizer。Tokenizer的作用是将文本转换为数字序列，以便模型能够理解和处理。我们使用的数据集是 [出门问问序列猴子开源数据集](https://www.modelscope.cn/datasets/ddzhu123/seq-monkey/files) ，这个数据集包含了大量的中文文本数据，可以用于训练Tokenizer。
 
@@ -1290,7 +1289,7 @@ Hello<|im_end|>
 Special tokens preserved: False
 ```
 
-### 5.3.2 Dataset
+### 5.3.3 Dataset
 
 #### PretrainDataset
 
@@ -1330,11 +1329,11 @@ class PretrainDataset(Dataset):
         return torch.from_numpy(X), torch.from_numpy(Y), torch.from_numpy(loss_mask)
 ```
 
-在以上代码和图5.1可以看出，`Pretrain Dataset` 主要是将 `text` 通过 `tokenizer` 转换成 `input_id`，然后将 `input_id` 拆分成 `X` 和 `Y`，其中 `X` 为 `input_id` 的前 n-1 个元素，`Y` 为 `input_id` 的后 n-1 `个元素。loss_mask` 主要是用来标记哪些位置需要计算损失，哪些位置不需要计算损失。
+在以上代码和图5.3可以看出，`Pretrain Dataset` 主要是将 `text` 通过 `tokenizer` 转换成 `input_id`，然后将 `input_id` 拆分成 `X` 和 `Y`，其中 `X` 为 `input_id` 的前 n-1 个元素，`Y` 为 `input_id` 的后 n-1 `个元素。loss_mask` 主要是用来标记哪些位置需要计算损失，哪些位置不需要计算损失。
 
 <div align='center'>
-    <img src="../images/5-images/pretrain_dataset.png" alt="alt text" width="100%">
-    <p>图5.1 预训练损失函数计算</p>
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/5-images/pretrain_dataset.png" alt="alt text" width="100%">
+    <p>图5.3 预训练损失函数计算</p>
 </div>
 
 图中示例展示了当`max_length=9`时的处理过程：
@@ -1417,17 +1416,17 @@ class SFTDataset(Dataset):
         return torch.from_numpy(X), torch.from_numpy(Y), torch.from_numpy(loss_mask)
 ```
 
-在 SFT 阶段，这里使用的是多轮对话数据集，所以就需要区分哪些位置需要计算损失，哪些位置不需要计算损失。在上面的代码中，我使用了一个 `generate_loss_mask` 函数来生成 `loss_mask`。这个函数主要是用来生成 `loss_mask`，其中 `loss_mask` 的生成规则是：当遇到 `|<im_start|>assistant\n` 时，就开始计算损失，直到遇到 `|<im_end|>` 为止。这样就可以保证我们的模型在 SFT 阶段只计算当前轮的对话内容，如图5.2所示。
+在 SFT 阶段，这里使用的是多轮对话数据集，所以就需要区分哪些位置需要计算损失，哪些位置不需要计算损失。在上面的代码中，我使用了一个 `generate_loss_mask` 函数来生成 `loss_mask`。这个函数主要是用来生成 `loss_mask`，其中 `loss_mask` 的生成规则是：当遇到 `|<im_start|>assistant\n` 时，就开始计算损失，直到遇到 `|<im_end|>` 为止。这样就可以保证我们的模型在 SFT 阶段只计算当前轮的对话内容，如图5.4所示。
 
 <div align='center'>
-    <img src="../images/5-images/sftdataset.png" alt="alt text" width="90%">
-    <p>图5.2 SFT 损失函数计算</p>
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/5-images/sftdataset.png" alt="alt text" width="90%">
+    <p>图5.4 SFT 损失函数计算</p>
 </div>
 
 可以看到，其实 SFT Dataset 和 Pretrain Dataset 的 `X` 和 `Y` 是一样的，只是在 SFT Dataset 中我们需要生成一个 `loss_mask` 来标记哪些位置需要计算损失，哪些位置不需要计算损失。 图中 `Input ids` 中的蓝色小方格就是AI的回答，所以是需要模型学习的地方。所以在 `loss_mask` 中，蓝色小方格对应的位置是黄色，其他位置是灰色。在代码 `loss_mask` 中的 1 对应的位置计算损失，0 对应的位置不计算损失。
 
 
-### 5.3.3 预训练
+### 5.3.4 预训练
 
 在数据预处理完成后，我们就可以开始训练模型了。我们使用的模型是一个和LLama2结构一样的 Decoder only Transformer模型，使用Pytorch实现。相关代码在`code/k_model.py`文件中。此处不再赘述，源码中有详细的中文注释，且我们在之前的文章中也有详细的介绍。
 
@@ -1480,174 +1479,298 @@ class SFTDataset(Dataset):
 
 ```python
 def get_lr(it, all):
-    warmup_iters = args.warmup_iters
-    lr_decay_iters = all
-    min_lr = args.learning_rate / 10
+    """
+    计算当前迭代的学习率，使用余弦退火调度策略
+    
+    学习率调度策略：
+    1. Warmup阶段：学习率从0线性增长到目标学习率
+    2. 余弦退火阶段：学习率按余弦函数衰减到最小学习率
+    3. 超出训练步数后：保持最小学习率
+    
+    Args:
+        it (int): 当前迭代步数
+        all (int): 总迭代步数
+        
+    Returns:
+        float: 当前步数对应的学习率
+    """
+    warmup_iters = args.warmup_iters  # 预热迭代次数
+    lr_decay_iters = all  # 学习率衰减的总迭代次数
+    min_lr = args.learning_rate / 10  # 最小学习率，为初始学习率的1/10
 
+    # Warmup阶段：线性增长
     if it < warmup_iters:
         return args.learning_rate * it / warmup_iters
     
+    # 超出训练步数：保持最小学习率
     if it > lr_decay_iters:
         return min_lr
     
+    # 余弦退火阶段
     decay_ratio = (it - warmup_iters) / (lr_decay_iters - warmup_iters)
     assert 0 <= decay_ratio <= 1
-    coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))
+    coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))  # 余弦系数
     return min_lr + coeff * (args.learning_rate - min_lr)
 
 def train_epoch(epoch):
-    start_time = time.time()
+    """
+    训练一个epoch的函数
+    
+    实现了完整的训练循环，包括：
+    1. 数据加载和设备转移
+    2. 动态学习率调整
+    3. 前向传播和损失计算
+    4. 梯度累积和反向传播
+    5. 梯度裁剪和优化器更新
+    6. 日志记录和模型保存
+    
+    Args:
+        epoch (int): 当前epoch编号
+    """
+    start_time = time.time()  # 记录开始时间
+    
+    # 遍历数据加载器中的每个batch
     for step, (X, Y, loss_mask) in enumerate(train_loader):
-        X = X.to(args.device)
-        Y = Y.to(args.device)
-        loss_mask = loss_mask.to(args.device)
+        # 将数据转移到指定设备（GPU/CPU）
+        X = X.to(args.device)  # 输入序列
+        Y = Y.to(args.device)  # 目标序列
+        loss_mask = loss_mask.to(args.device)  # 损失掩码，用于忽略padding token
 
+        # 计算当前步骤的学习率
         lr = get_lr(epoch * iter_per_epoch + step, args.epochs * iter_per_epoch)
+        # 更新优化器中所有参数组的学习率
         for param_group in optimizer.param_groups:
             param_group['lr'] = lr
 
+        # 使用混合精度训练上下文
         with ctx:
+            # 前向传播
             out = model(X, Y)
+            # 计算损失并除以累积步数（用于梯度累积）
             loss = out.last_loss / args.accumulation_steps
+            # 将loss_mask展平为一维
             loss_mask = loss_mask.view(-1)
+            # 应用掩码计算有效损失（忽略padding位置）
             loss = torch.sum(loss * loss_mask) / loss_mask.sum()
 
+        # 使用scaler进行混合精度的反向传播
         scaler.scale(loss).backward()
 
+        # 每accumulation_steps步执行一次优化器更新
         if (step + 1) % args.accumulation_steps == 0:
+            # 取消梯度缩放，准备梯度裁剪
             scaler.unscale_(optimizer)
+            # 梯度裁剪，防止梯度爆炸
             torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
 
+            # 执行优化器步骤
             scaler.step(optimizer)
+            # 更新scaler的缩放因子
             scaler.update()
 
+            # 清零梯度，set_to_none=True可以节省内存
             optimizer.zero_grad(set_to_none=True)
 
+        # 每log_interval步记录一次日志
         if step % args.log_interval == 0:
             spend_time = time.time() - start_time
+            # 打印训练进度信息
             Logger(
-                'Epoch:[{}/{}]({}/{}) loss:{:.3f} lr:{:.7f} epoch_Time:{}min:'.format(
+                'Epoch:[{}/{}]({}/{}) loss:{:.3f} lr:{:.7f} epoch_Time:{}min;'.format(
                     epoch + 1,
                     args.epochs,
                     step,
                     iter_per_epoch,
-                    loss.item() * args.accumulation_steps,
+                    loss.item() * args.accumulation_steps,  # 恢复真实的loss值
                     optimizer.param_groups[-1]['lr'],
                     spend_time / (step + 1) * iter_per_epoch // 60 - spend_time // 60))
+            
+            # 如果启用SwanLab，记录训练指标
             if args.use_swanlab:
                 swanlab.log({
                     "loss": loss.item() * args.accumulation_steps,
                     "lr": optimizer.param_groups[-1]['lr']
                 })
 
+        # 每save_interval步保存一次模型
         if (step + 1) % args.save_interval == 0:
-            model.eval()
+            model.eval()  # 切换到评估模式
+            # 构建检查点文件名
             ckp = f'{args.save_dir}/pretrain_{lm_config.dim}_{lm_config.n_layers}_{lm_config.vocab_size}.pth'
 
-            # 处理多卡保存
+            # 处理多卡保存：如果是DataParallel模型，需要访问.module属性
             state_dict = model.module.state_dict() if isinstance(model, torch.nn.DataParallel) else model.state_dict()
             torch.save(state_dict, ckp)
-            model.train()
+            model.train()  # 切换回训练模式
         
+        # 每20000步保存一个带步数标记的检查点
         if (step + 1) % 20000 == 0:
             model.eval()
+            # 构建带步数的检查点文件名
             ckp = f'{args.save_dir}/pretrain_{lm_config.dim}_{lm_config.n_layers}_{lm_config.vocab_size}_step{step+1}.pth'
 
+            # 保存模型状态字典
             state_dict = model.module.state_dict() if isinstance(model, torch.nn.DataParallel) else model.state_dict()
             torch.save(state_dict, ckp)
             model.train()
 
 
 def init_model():
+    """
+    初始化模型和分词器
+    
+    功能包括：
+    1. 加载预训练的分词器
+    2. 创建Transformer模型
+    3. 设置多GPU并行训练（如果可用）
+    4. 将模型移动到指定设备
+    5. 统计并打印模型参数量
+    
+    Returns:
+        tuple: (model, tokenizer) 初始化后的模型和分词器
+    """
     def count_parameters(model):
+        """
+        统计模型中可训练参数的数量
+        
+        Args:
+            model: PyTorch模型
+            
+        Returns:
+            int: 可训练参数总数
+        """
         return sum(p.numel() for p in model.parameters() if p.requires_grad)
 
+    # 从本地路径加载预训练的分词器
     tokenizer = AutoTokenizer.from_pretrained('./tokenizer_k/')
 
+    # 根据配置创建Transformer模型
     model = Transformer(lm_config)
     
-    # 多卡初始化
+    # 多卡初始化：检查可用GPU数量并设置DataParallel
     num_gpus = torch.cuda.device_count()
     if num_gpus > 1:
         Logger(f"Using {num_gpus} GPUs with DataParallel!")
+        # 使用DataParallel包装模型以支持多GPU训练
         model = torch.nn.DataParallel(model)
     
+    # 将模型移动到指定设备（GPU或CPU）
     model = model.to(args.device)
+    
+    # 计算并打印模型参数量（以百万为单位）
     Logger(f'LLM总参数量：{count_parameters(model) / 1e6:.3f} 百万')
     return model, tokenizer
 
+
 if __name__ == "__main__":
+    # ==================== 命令行参数解析 ====================
     parser = argparse.ArgumentParser(description="Tiny-LLM Pretraining")
-    parser.add_argument("--out_dir", type=str, default="output", help="Output directory")
-    parser.add_argument("--epochs", type=int, default=1, help="Number of epochs")
-    parser.add_argument("--batch_size", type=int, default=64, help="Batch size")
-    parser.add_argument("--learning_rate", type=float, default=2e-4, help="Learning rate")
-    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="Device to use")
-    parser.add_argument("--dtype", type=str, default="bfloat16", help="Data type")
-    parser.add_argument("--use_swanlab", type=bool, default=True, help="Use Weights & Biases")
-    parser.add_argument("--num_workers", type=int, default=8, help="Number of workers for data loading")
-    parser.add_argument("--data_path", type=str, default="", help="Path to training data")
-    parser.add_argument("--accumulation_steps", type=int, default=8, help="Gradient accumulation steps")
-    parser.add_argument("--grad_clip", type=float, default=1.0, help="Gradient clipping threshold")
-    parser.add_argument("--warmup_iters", type=int, default=0, help="Number of warmup iterations")
-    parser.add_argument("--log_interval", type=int, default=100, help="Logging interval")
-    parser.add_argument("--save_interval", type=int, default=1000, help="Model saving interval")
-    # 添加多卡参数
-    parser.add_argument("--gpus", type=str, default='0,1', help="Comma-separated GPU IDs (e.g. '0,1,2')")
+    
+    # 基础训练参数
+    parser.add_argument("--out_dir", type=str, default="base_model_215M", help="模型输出目录")
+    parser.add_argument("--epochs", type=int, default=1, help="训练轮数")
+    parser.add_argument("--batch_size", type=int, default=64, help="批次大小")
+    parser.add_argument("--learning_rate", type=float, default=2e-4, help="学习率")
+    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="训练设备")
+    parser.add_argument("--dtype", type=str, default="bfloat16", help="数据类型")
+    
+    # 实验跟踪和数据加载参数
+    parser.add_argument("--use_swanlab", action="store_true", help="是否使用SwanLab进行实验跟踪")
+    parser.add_argument("--num_workers", type=int, default=8, help="数据加载的工作进程数")
+    parser.add_argument("--data_path", type=str, default="./seq_monkey_datawhale.jsonl", help="训练数据路径")
+    
+    # 训练优化参数
+    parser.add_argument("--accumulation_steps", type=int, default=8, help="梯度累积步数")
+    parser.add_argument("--grad_clip", type=float, default=1.0, help="梯度裁剪阈值")
+    parser.add_argument("--warmup_iters", type=int, default=0, help="学习率预热迭代次数")
+    
+    # 日志和保存参数
+    parser.add_argument("--log_interval", type=int, default=100, help="日志记录间隔")
+    parser.add_argument("--save_interval", type=int, default=1000, help="模型保存间隔")
+    
+    # 多GPU训练参数
+    parser.add_argument("--gpus", type=str, default='0,1,2,3,4,5,6,7', help="使用的GPU ID，用逗号分隔 (例如: '0,1,2')")
 
     args = parser.parse_args()
 
-    # 设置可见GPU
+    # ==================== GPU环境设置 ====================
+    # 设置可见的GPU设备
     if args.gpus is not None:
         os.environ["CUDA_VISIBLE_DEVICES"] = args.gpus
-        # 自动设置主设备为第一个GPU
+        # 自动设置主设备为第一个可用GPU
         if torch.cuda.is_available():
             args.device = "cuda:0"
         else:
             args.device = "cpu"
 
+    # ==================== 实验跟踪初始化 ====================
     if args.use_swanlab:
-        swanlab.login(api_key='your key')
+        # 注意：使用前需要先登录 swanlab.login(api_key='your key')
         run = swanlab.init(
-            project="Tiny-LLM",
-            experiment_name="Pretrain-215M",
-            config=args,
+            project="Happy-LLM",  # 项目名称
+            experiment_name="Pretrain-215M",  # 实验名称
+            config=args,  # 保存所有超参数
         )
 
+    # ==================== 模型配置 ====================
+    # 定义语言模型的配置参数
     lm_config = ModelConfig(
-        dim=1024,
-        n_layers=18,
+        dim=1024,      # 模型维度
+        n_layers=18,   # Transformer层数
     )
-    max_seq_len = lm_config.max_seq_len
-    args.save_dir = os.path.join(args.out_dir)
-    os.makedirs(args.save_dir, exist_ok=True)
+
+    # ==================== 训练环境设置 ====================
+    max_seq_len = lm_config.max_seq_len  # 最大序列长度
+    args.save_dir = os.path.join(args.out_dir)  # 模型保存目录
+    
+    # 创建必要的目录
     os.makedirs(args.out_dir, exist_ok=True)
+    
+    # 设置随机种子以确保结果可复现
     torch.manual_seed(42)
+    
+    # 确定设备类型（用于选择合适的上下文管理器）
     device_type = "cuda" if "cuda" in args.device else "cpu"
 
+    # 设置混合精度训练的上下文管理器
+    # CPU训练时使用nullcontext，GPU训练时使用autocast
     ctx = nullcontext() if device_type == "cpu" else torch.cuda.amp.autocast()
 
+    # ==================== 模型和数据初始化 ====================
+    # 初始化模型和分词器
     model, tokenizer = init_model()
     
+    # 创建训练数据集
     train_ds = PretrainDataset(args.data_path, tokenizer, max_length=max_seq_len)
+    
+    # 创建数据加载器
     train_loader = DataLoader(
         train_ds,
-        batch_size=args.batch_size,
-        pin_memory=True,
-        drop_last=False,
-        shuffle=True,
-        num_workers=args.num_workers
+        batch_size=args.batch_size,  # 批次大小
+        pin_memory=True,             # 将数据加载到固定内存中，加速GPU传输
+        drop_last=False,             # 不丢弃最后一个不完整的批次
+        shuffle=True,                # 随机打乱数据
+        num_workers=args.num_workers # 数据加载的并行工作进程数
     )
 
+    # ==================== 优化器和训练组件初始化 ====================
+    # 初始化混合精度训练的梯度缩放器
+    # 只有在使用float16或bfloat16时才启用
     scaler = torch.cuda.amp.GradScaler(enabled=(args.dtype in ['float16', 'bfloat16']))
+    
+    # 初始化Adam优化器
     optimizer = optim.Adam(model.parameters(), lr=args.learning_rate)
 
+    # ==================== 开始训练 ====================
+    # 计算每个epoch的迭代次数
     iter_per_epoch = len(train_loader)
+    
+    # 开始训练循环
     for epoch in range(args.epochs):
         train_epoch(epoch)
 ```
 
-### 5.3.4 SFT 训练
+### 5.3.5 SFT 训练
 
 SFT 训练和预训练的代码基本一样，只是导入的 Dataset 不一样。在这里我们使用的是 SFTDataset，用于多轮对话的训练。
 
@@ -1671,13 +1794,18 @@ from dataset import SFTDataset
 
 import swanlab
 
+# 忽略警告
 warnings.filterwarnings('ignore')
 
 
 def Logger(content):
+    """日志记录器"""
     print(content)
 
 def get_lr(it, all):
+    """获取学习率"""
+    # 1) linear warmup for warmup_iters steps
+    # 1) 预热迭代的线性预热
     warmup_iters = args.warmup_iters
     lr_decay_iters = all
     min_lr = args.learning_rate / 10
@@ -1685,33 +1813,42 @@ def get_lr(it, all):
     if it < warmup_iters:
         return args.learning_rate * it / warmup_iters
     
+    # 2) if it > lr_decay_iters, return min learning rate
+    # 2) 如果迭代次数超过学习率衰减迭代次数，则返回最小学习率
     if it > lr_decay_iters:
         return min_lr
     
+    # 3) in between, use cosine decay down to min learning rate
+    # 3) 在两者之间，使用余弦衰减至最小学习率
     decay_ratio = (it - warmup_iters) / (lr_decay_iters - warmup_iters)
     assert 0 <= decay_ratio <= 1
     coeff = 0.5 * (1.0 + math.cos(math.pi * decay_ratio))
     return min_lr + coeff * (args.learning_rate - min_lr)
 
 def train_epoch(epoch):
+    """训练一个epoch"""
     start_time = time.time()
     for step, (X, Y, loss_mask) in enumerate(train_loader):
         X = X.to(args.device)
         Y = Y.to(args.device)
         loss_mask = loss_mask.to(args.device)
 
+        # 获取学习率并更新优化器
         lr = get_lr(epoch * iter_per_epoch + step, args.epochs * iter_per_epoch)
         for param_group in optimizer.param_groups:
             param_group['lr'] = lr
 
+        # 前向传播
         with ctx:
             out = model(X, Y)
             loss = out.last_loss / args.accumulation_steps
             loss_mask = loss_mask.view(-1)
             loss = torch.sum(loss * loss_mask) / loss_mask.sum()
 
+        # 反向传播
         scaler.scale(loss).backward()
 
+        # 更新权重
         if (step + 1) % args.accumulation_steps == 0:
             scaler.unscale_(optimizer)
             torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
@@ -1721,6 +1858,7 @@ def train_epoch(epoch):
 
             optimizer.zero_grad(set_to_none=True)
 
+        # 打印日志
         if step % args.log_interval == 0:
             spend_time = time.time() - start_time
             Logger(
@@ -1738,6 +1876,7 @@ def train_epoch(epoch):
                     "lr": optimizer.param_groups[-1]['lr']
                 })
 
+        # 保存模型
         if (step + 1) % args.save_interval == 0:
             model.eval()
             ckp = f'{args.save_dir}/sft_dim{lm_config.dim}_layers{lm_config.n_layers}_vocab_size{lm_config.vocab_size}.pth'
@@ -1747,6 +1886,7 @@ def train_epoch(epoch):
             torch.save(state_dict, ckp)
             model.train()
         
+        # 定期保存模型
         if (step + 1) % 20000 == 0:
             model.eval()
             ckp = f'{args.save_dir}/sft_dim{lm_config.dim}_layers{lm_config.n_layers}_vocab_size{lm_config.vocab_size}_step{step+1}.pth'
@@ -1757,14 +1897,19 @@ def train_epoch(epoch):
 
 
 def init_model():
+    """初始化模型"""
     def count_parameters(model):
+        """计算模型参数量"""
         return sum(p.numel() for p in model.parameters() if p.requires_grad)
 
+    # 加载分词器
     tokenizer = AutoTokenizer.from_pretrained('./tokenizer_k/')
 
+    # 初始化模型
     model = Transformer(lm_config)
 
-    ckp = './base_monkey_215M/pretrain_1024_18_6144.pth'
+    # 加载预训练权重
+    ckp = './base_model_215M/pretrain_1024_18_6144.pth'
     state_dict = torch.load(ckp, map_location=args.device)
     unwanted_prefix = '_orig_mod.'
     for k, v in list(state_dict.items()):
@@ -1785,22 +1930,22 @@ def init_model():
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Tiny-LLM Pretraining")
-    parser.add_argument("--out_dir", type=str, default="output", help="Output directory")
-    parser.add_argument("--epochs", type=int, default=1, help="Number of epochs")
-    parser.add_argument("--batch_size", type=int, default=64, help="Batch size")
-    parser.add_argument("--learning_rate", type=float, default=2e-4, help="Learning rate")
-    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="Device to use")
-    parser.add_argument("--dtype", type=str, default="bfloat16", help="Data type")
-    parser.add_argument("--use_swanlab", type=bool, default=True, help="Use Weights & Biases")
-    parser.add_argument("--num_workers", type=int, default=4, help="Number of workers for data loading")
-    parser.add_argument("--data_path", type=str, default="", help="Path to training data")
-    parser.add_argument("--accumulation_steps", type=int, default=4, help="Gradient accumulation steps")
-    parser.add_argument("--grad_clip", type=float, default=1.0, help="Gradient clipping threshold")
-    parser.add_argument("--warmup_iters", type=int, default=0, help="Number of warmup iterations")
-    parser.add_argument("--log_interval", type=int, default=100, help="Logging interval")
-    parser.add_argument("--save_interval", type=int, default=1000, help="Model saving interval")
+    parser.add_argument("--out_dir", type=str, default="sft_model_215M", help="输出目录")
+    parser.add_argument("--epochs", type=int, default=1, help="训练轮数")
+    parser.add_argument("--batch_size", type=int, default=64, help="批处理大小")
+    parser.add_argument("--learning_rate", type=float, default=2e-4, help="学习率")
+    parser.add_argument("--device", type=str, default="cuda:0" if torch.cuda.is_available() else "cpu", help="使用的设备")
+    parser.add_argument("--dtype", type=str, default="bfloat16", help="数据类型")
+    parser.add_argument("--use_swanlab", action="store_true", help="是否使用SwanLab进行实验跟踪")
+    parser.add_argument("--num_workers", type=int, default=8, help="数据加载的工作进程数")
+    parser.add_argument("--data_path", type=str, default="./BelleGroup_sft.jsonl", help="训练数据路径")
+    parser.add_argument("--accumulation_steps", type=int, default=8, help="梯度累积步数")
+    parser.add_argument("--grad_clip", type=float, default=1.0, help="梯度裁剪阈值")
+    parser.add_argument("--warmup_iters", type=int, default=0, help="预热迭代次数")
+    parser.add_argument("--log_interval", type=int, default=100, help="日志记录间隔")
+    parser.add_argument("--save_interval", type=int, default=1000, help="模型保存间隔")
     # 添加多卡参数
-    parser.add_argument("--gpus", type=str, default='0,1', help="Comma-separated GPU IDs (e.g. '0,1,2')")
+    parser.add_argument("--gpus", type=str, default='0,1,2,3,4,5,6,7', help="逗号分隔的GPU ID (例如 '0,1,2')")
 
     args = parser.parse_args()
 
@@ -1813,29 +1958,32 @@ if __name__ == "__main__":
         else:
             args.device = "cpu"
 
+    # 初始化swanlab
     if args.use_swanlab:
-        swanlab.login(api_key='your key')
         run = swanlab.init(
-            project="Tiny-LLM",
-            experiment_name="BelleGropu-sft-215M",
+            project="Happy-LLM",
+            experiment_name="SFT-215M",
             config=args,
         )
 
+    # 模型配置
     lm_config = ModelConfig(
         dim=1024,
         n_layers=18,
     )
     max_seq_len = lm_config.max_seq_len
     args.save_dir = os.path.join(args.out_dir)
-    os.makedirs(args.save_dir, exist_ok=True)
     os.makedirs(args.out_dir, exist_ok=True)
     torch.manual_seed(42)
     device_type = "cuda" if "cuda" in args.device else "cpu"
 
+    # 上下文管理器
     ctx = nullcontext() if device_type == "cpu" else torch.cuda.amp.autocast()
 
+    # 初始化模型和分词器
     model, tokenizer = init_model()
     
+    # 创建数据集和数据加载器
     train_ds = SFTDataset(args.data_path, tokenizer, max_length=max_seq_len)
     train_loader = DataLoader(
         train_ds,
@@ -1846,16 +1994,18 @@ if __name__ == "__main__":
         num_workers=args.num_workers
     )
 
+    # 缩放器和优化器
     scaler = torch.cuda.amp.GradScaler(enabled=(args.dtype in ['float16', 'bfloat16']))
-    optimizer = optim.Adam(model.parameters(), lr=args.learning_rate)
+    optimizer = optim.AdamW(model.parameters(), lr=args.learning_rate)
 
+    # 开始训练
     iter_per_epoch = len(train_loader)
     for epoch in range(args.epochs):
         train_epoch(epoch)
 ```
 
 
-### 5.3.4 使用模型生成文本
+### 5.3.6 使用模型生成文本
 
 在模型训练完成后，会在`output`目录下生成模型文件，这个文件就是我们训练好的模型。我们可以使用以下命令生成文本。
 
@@ -1866,9 +2016,17 @@ python model_sample.py
 我们来看下`model_sample.py`文件中的代码，这个文件中定义了一个`TextGenerator`类，用于生成文本。
 
 ```python
+import os
+import pickle
+from contextlib import nullcontext
+import torch
+from k_model import ModelConfig, Transformer
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import argparse
+
 class TextGenerator:
     def __init__(self, 
-                 checkpoint='out/SkyWork_pretrain_768_12_6144.pth',  # 模型检查点路径
+                 checkpoint='./base_model_215M/pretrain_1024_18_6144.pth',  # 模型检查点路径
                  tokenizer_model_path='./tokenizer_k/',  # 分词器模型路径
                  seed=42,  # 随机种子，确保可重复性
                  device=None,  # 设备，优先使用 CUDA，如果没有可用的 CUDA，则使用 CPU
@@ -1915,7 +2073,7 @@ class TextGenerator:
 
     def chat_template(self, prompt):
         message = [
-            {"role": "system", "content": "你是一个AI助手。"},
+            {"role": "system", "content": "你是一个AI助手，你的名字叫小明。"},
             {"role": "user", "content": prompt}
         ]
         return self.tokenizer.apply_chat_template(message, tokenize=False, add_generation_prompt=True)
@@ -1984,6 +2142,33 @@ class TextGenerator:
                     generated_texts.append(self.tokenizer.decode(y[0].tolist()))  # 解码生成的 token 序列为可读文本
         
         return generated_texts  # 返回生成的文本样本
+    
+if __name__ == "__main__":
+    print("------------------- Pretrain Sample ------------------- \n")
+
+    pretrain_prompt_datas = [
+        '<|im_start|>北京大学是',
+        '<|im_start|>中国矿业大学（北京）地球科学与测绘工程学院',
+    ]
+
+    generator = TextGenerator(checkpoint='./base_model_215M/pretrain_1024_18_6144.pth')  # 初始化生成器
+    for i in range(len(pretrain_prompt_datas)):
+        samples = generator.pretrain_sample(start=pretrain_prompt_datas[i], num_samples=1, max_new_tokens=120, temperature=0.75)
+        print(f"\nSample {i+1}:\n{pretrain_prompt_datas[i]}{samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
+
+    print("\n ------------------- SFT Sample ------------------- \n")
+
+    sft_prompt_datas = [
+        '你好呀',
+        "中国的首都是哪里？",
+        "1+12等于多少？",
+        "你是谁？"
+    ]
+    generator = TextGenerator(checkpoint='./sft_model_215M/sft_dim1024_layers18_vocab_size6144.pth')  # 初始化生成器
+    for i in range(len(sft_prompt_datas)):
+        samples = generator.sft_sample(start=sft_prompt_datas[i], num_samples=1, max_new_tokens=128, temperature=0.6)
+        print(f"\nSample {i+1}:\nQuestion: {sft_prompt_datas[i]} \nAI answer: {samples[0]}\n{'-'*20}")  # 打印生成的样本并用分隔线分割
+
 ```
 
 最后我们来看一下模型输出的结果：
@@ -2023,9 +2208,15 @@ Sample 2:
 --------------------
 ```
 
-到这里，我们的模型就训绽完成了，恭喜你训练了一个属于你自己的大模型。
+到这里，我们的模型就训练完成了，恭喜你训练了一个属于你自己的大模型。
+
+> 大家在训练的时候可以将 batch 调的低一些，这样可以减少显存的占用，避免显存不足的问题。当然这样会增加训练时间，可以根据自己的显卡显存大小来调整 batch 的大小。实测 Pretrain batch 为 4 的情况下只需要 7G 显存，训练时长预计 533 小时。作者是在 8卡4090 上进行训练的，预训练一共耗时 46 小时，SFT 阶段在 BelleGroup 350万条中文指令训练 24 小时。
+
+作者也在魔搭平台上传了本章节训来的模型，如果大家的设备不足以训练大模型，大家也可以在魔搭平台下载模型进行调试和模型体验。模型下载地址如下：
+
+> *ModelScope 模型下载地址：[🤖 ModelScope](https://www.modelscope.cn/collections/Happy-LLM-e98b91b10b684a)*    
+> *ModelScope 创空间体验地址：[🤖 创空间](https://www.modelscope.cn/studios/kmno4zx/happy_llm_215M_sft)*
 
-> 大家在训练的时候可以将 batch 调的低一些，这样可以减少显存的占用，避免显存不足的问题。当然这样会增加训练时间，可以根据自己的显卡显存大小来调整 batch 的大小。实测 Pretrain batch 为 4 的情况下只需要 7G 显存，训练时长预计 533 小时。作者是在 4卡A100上进行训练的，预训练一共耗时26小时，SFT 阶段在 BelleGroup 350万条中文指令训练 4 小时。
 
 **参考资料**
 

docs/chapter6/code/finetune.py

@@ -33,7 +33,7 @@ from transformers import (
 import datetime
 from transformers.testing_utils import CaptureLogger
 from transformers.trainer_utils import get_last_checkpoint
-import wandb
+import swanlab
 from tqdm import tqdm
 
 
@@ -183,8 +183,8 @@ def main():
     parser = HfArgumentParser((ModelArguments, DataTrainingArguments, TrainingArguments))
     model_args, data_args, training_args = parser.parse_args_into_dataclasses()
 
-    # 初始化 WandB
-    wandb.init(project="sft", name="qwen-1.5b")
+    # 初始化 SwanLab
+    swanlab.init(project="sft", experiment_name="qwen-1.5b")
     
     # 设置日志
     logging.basicConfig(

docs/chapter6/code/finetune.sh

@@ -22,6 +22,6 @@ deepspeed finetune.py \
     --bf16 \
     --gradient_checkpointing \
     --deepspeed ./ds_config_zero2.json \
-    --report_to wandb
+    --report_to swanlab
     
     # --resume_from_checkpoint ${output_model}/checkpoint-20400 \

docs/chapter6/code/pretrain.py

@@ -30,7 +30,7 @@ from transformers import (
 import datetime
 from transformers.testing_utils import CaptureLogger
 from transformers.trainer_utils import get_last_checkpoint
-import wandb
+import swanlab
 
 
 logger = logging.getLogger(__name__)
@@ -95,8 +95,8 @@ def main():
     parser = HfArgumentParser((ModelArguments, DataTrainingArguments, TrainingArguments))
     model_args, data_args, training_args = parser.parse_args_into_dataclasses()
 
-    # 初始化 WandB
-    wandb.init(project="pretrain", name="from_scrach")
+    # 初始化 SwanLab
+    swanlab.init(project="pretrain", experiment_name="from_scrach")
     
     # 设置日志
     logging.basicConfig(

docs/chapter6/code/pretrain.sh

@@ -24,6 +24,6 @@ deepspeed pretrain.py \
     --bf16 \
     --gradient_checkpointing \
     --deepspeed ./ds_config_zero2.json \
-    --report_to wandb
+    --report_to swanlab
     
     # --resume_from_checkpoint ${output_model}/checkpoint-20400 \

docs/chapter6/code/requirements.txt

@@ -0,0 +1,7 @@
+transformers
+datasets
+torch
+torchdata
+deepspeed
+pandas
+swanlab

docs/chapter6/第六章 大模型训练流程实践.md

@@ -15,7 +15,7 @@
 Transformers 是由 Hugging Face 开发的 NLP 框架，通过模块化设计实现了对 BERT、GPT、LLaMA、T5、ViT 等上百种主流模型架构的统一支持。通过使用 Transformers，开发者无需重复实现基础网络结构，通过 AutoModel 类即可一键加载任意预训练，图6.1 为 Hugging Face Transformers 课程首页：
 
 <div align='center'>
-    <img src="../images/6-images/1-1.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-1.png" alt="alt text" width="90%">
     <p>图6.1 Hugging Face Transformers</p>
 </div>
 
@@ -24,7 +24,7 @@ Transformers 是由 Hugging Face 开发的 NLP 框架，通过模块化设计实
 对 LLM 时代的 NLP 研究者更为重要的是，HuggingFace 基于 Transformers 框架搭建了其庞大的 AI 社区，开放了数亿个预训练模型参数、25万+不同类型数据集，通过 Transformers、Dataset、Evaluate 等多个框架实现对预训练模型、数据集及评估函数的集成，从而帮助开发者可以便捷地使用任一预训练模型，在开源模型及数据集的基础上便捷地实现个人模型的开发与应用。
 
 <div align='center'>
-    <img src="../images/6-images/1-2.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-2.png" alt="alt text" width="90%">
     <p>图6.2 Hugging Face Transformers 模型社区</p>
 </div>
 
@@ -35,14 +35,14 @@ Transformers 是由 Hugging Face 开发的 NLP 框架，通过模块化设计实
 我们可以使用 transformers 的 AutoModel 类来直接初始化已经实现好的模型。对于任意预训练模型，其参数中都包含有模型的配置信息。如果是想要从头训练一个 LLM，可以使用一个已有的模型架构来直接初始化。这里，我们以 [Qwen-2.5-1.5B](https://huggingface.co/Qwen/Qwen2.5-1.5B/tree/main)的模型架构为例：
 
 <div align='center'>
-    <img src="../images/6-images/1-3.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-3.png" alt="alt text" width="90%">
     <p>图6.3 Qwen-2.5-1.5B</p>
 </div>
 
 该界面即为 HuggingFace 社区中的 Qwen-2.5-1.5B 模型参数，其中的 `config.json` 文件即是模型的配置信息，包括了模型的架构、隐藏层大小、模型层数等，如图6.4所示：
 
 <div align='center'>
-    <img src="../images/6-images/1-4.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-4.png" alt="alt text" width="90%">
     <p>图6.4 Qwen-2.5-1.5B config.json 文件</p>
 </div>
 
@@ -59,7 +59,7 @@ os.system('huggingface-cli download --resume-download Qwen/Qwen2.5-1.5B --local-
 如图6.5，此处的 “Qwen/Qwen2.5-1.5B”即为要下载模型的标识符，对于其他模型，可以直接复制 HuggingFace 上的模型名即可：
 
 <div align='center'>
-    <img src="../images/6-images/1-5.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-5.png" alt="alt text" width="90%">
     <p>图6.5 模型下载标识</p>
 </div>
 
@@ -87,7 +87,7 @@ model = AutoModelForCausalLM.from_config(config,trust_remote_code=True)
 由于 LLM 一般都是 CausalLM 架构，此处使用了 AutoModelForCausalLM 类进行加载。如果是用于分类任务训练，可使用 AutoModelForSequenceClassification 类来加载。查看该 model，图6.6可以看到其架构和定义的配置文件相同：
 
 <div align='center'>
-    <img src="../images/6-images/1-6.png" alt="alt text" width="70%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-6.png" alt="alt text" width="70%">
     <p>图6.6 模型结构输出结果</p>
 </div>
 
@@ -101,7 +101,7 @@ model = AutoModelForCausalLM.from_pretrained(model_name_or_path,trust_remote_cod
 
 类似的，直接使用 from_pretrained 方法加载即可，此处的 model_name_or_path 即为下载好的参数的本地路径。
 
-我们还需要初始化一个 tokenizer。此处，我们直接使用 Qwen-2.5-1.5B 对应的 tokenzier 参数即可：
+我们还需要初始化一个 tokenizer。此处，我们直接使用 Qwen-2.5-1.5B 对应的 tokenizer 参数即可：
 
 ```python
 # 加载一个预训练好的 tokenizer
@@ -130,7 +130,7 @@ ds["train"][0]
 ```
 
 <div align='center'>
-    <img src="../images/6-images/1-7.png" alt="alt text" width="100%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/1-7.png" alt="alt text" width="100%">
     <p>图6.7 数据集展示</p>
 </div>
 
@@ -250,7 +250,7 @@ trainer = Trainer(
 trainer.train()
 ```
 
-> 注：上述代码存放于 `./code/pretrian.ipynb` 文件中。
+> 注：上述代码存放于 `./code/pretrain.ipynb` 文件中。
 
 ### 6.1.5 使用 DeepSpeed 实现分布式训练
 
@@ -289,7 +289,7 @@ from transformers import (
 import datetime
 from transformers.testing_utils import CaptureLogger
 from transformers.trainer_utils import get_last_checkpoint
-import wandb
+import swanlab
 ```
 
 首先需要定义几个超参的类型，用于处理 sh 脚本中设定的超参值。由于 transformers 本身有 TraingingArguments 类，其中包括了训练的一些必备超参数。我们这里只需定义 TrainingArguments 中未包含的超参即可，主要包括模型相关的超参（定义在 ModelArguments）和数据相关的超参（定义在 DataTrainingArguments）：
@@ -456,14 +456,14 @@ trainer.save_model()
 ```
 注意，由于上文检测了是否存在 checkpoint，此处使用 resume_from_checkpoint 来实现从 checkpoint 恢复训练的功能。
 
-由于在大规模训练中监测训练进度、loss 下降趋势尤为重要，在脚本中，我们使用了 wandb 作为训练检测的工具。在脚本开始进行了 wandb 的初始化：
+由于在大规模训练中监测训练进度、loss 下降趋势尤为重要，在脚本中，我们使用了 swanlab 作为训练检测的工具。在脚本开始进行了 swanlab 的初始化：
 
 ```python
-# 初始化 WandB
-wandb.init(project="pretrain", name="from_scrach")
+# 初始化 SwanLab
+swanlab.init(project="pretrain", experiment_name="from_scrach")
 ```
 
-在启动训练后，终端会输出 wandb 监测的 url，点击即可观察训练进度。此处不再赘述 wandb 的使用细节，欢迎读者查阅相关的资料说明。
+在启动训练后，终端会输出 swanlab 监测的 url，点击即可观察训练进度。此处不再赘述 swanlab 的使用细节，欢迎读者查阅相关的资料说明。
 
 完成上述代码后，我们使用一个 sh 脚本（`./code/pretrain.sh`）定义超参数的值，并通过 Deepspeed 启动训练，从而实现高效的多卡分布式训练：
 
@@ -495,7 +495,7 @@ deepspeed pretrain.py \
     --bf16 \
     --gradient_checkpointing \
     --deepspeed ./ds_config_zero2.json \
-    --report_to wandb
+    --report_to swanlab
     # --resume_from_checkpoint ${output_model}/checkpoint-20400 \
 ```
 在安装了 Deepspeed 第三方库后，可以直接通过 Deepspeed 命令来启动多卡训练。上述脚本命令主要是定义了各种超参数的值，可参考使用。在第四章中，我们介绍了 DeepSpeed 分布式训练的原理和 ZeRO 阶段设置，在这里，我们使用 ZeRO-2 进行训练。此处加载了 `ds_config_zero.json` 作为 DeepSpeed 的配置参数：
@@ -690,8 +690,8 @@ class SupervisedDataset(Dataset):
 parser = HfArgumentParser((ModelArguments, DataTrainingArguments, TrainingArguments))
 model_args, data_args, training_args = parser.parse_args_into_dataclasses()
 
-# 初始化 WandB
-wandb.init(project="sft", name="qwen-1.5b")
+# 初始化 SwanLab
+swanlab.init(project="sft", experiment_name="qwen-1.5b")
 
 # 设置日志
 logging.basicConfig(
@@ -741,7 +741,7 @@ logger.info(f"继承一个预训练模型 - Total size={n_params/2**20:.2f}M par
 
 # 初始化 Tokenizer
 tokenizer = AutoTokenizer.from_pretrained(model_args.model_name_or_path)
-logger.info("完成 tokenzier 加载")
+logger.info("完成 tokenizer 加载")
 
 # 加载微调数据
 with open(data_args.train_files) as f:
@@ -788,7 +788,7 @@ trainer.save_model()
 具体而言，其在预训练模型每层中插入用于下游任务的参数，即 Adapter 模块，在微调时冻结模型主体，仅训练特定于任务的参数，如图6.8所示。
 
 <div align='center'>
-    <img src="../images/6-images/3-1.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/3-1.png" alt="alt text" width="90%">
     <p>图6.8 Adapt Tuning</p>
 </div>
 
@@ -840,7 +840,7 @@ $$h = W_0 x + \Delta W x = W_0 x + B A x$$
 训练思路如图6.9所示：
 
 <div align='center'>
-    <img src="../images/6-images/3-2.jpg" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/6-images/3-2.jpg" alt="alt text" width="90%">
     <p>图6.9 LoRA</p>
 </div>
 

docs/chapter7/Agent/demo.py

@@ -1,5 +1,5 @@
 from src.core import Agent
-from src.tools import add, count_letter_in_string, compare, get_current_datetime
+from src.tools import add, count_letter_in_string, compare, get_current_datetime, search_wikipedia, get_current_temperature
 
 from openai import OpenAI
 
@@ -13,7 +13,7 @@ if __name__ == "__main__":
     agent = Agent(
         client=client,
         model="Qwen/Qwen2.5-32B-Instruct",
-        tools=[get_current_datetime, add, compare, count_letter_in_string],
+        tools=[get_current_datetime, search_wikipedia, get_current_temperature],
     )
 
     while True:

docs/chapter7/Agent/requirements.txt

@@ -1,4 +1,55 @@
-json
-openai
-datetime
-pprint
+altair==5.5.0
+annotated-types==0.7.0
+anyio==4.9.0
+attrs==25.3.0
+beautifulsoup4==4.13.4
+blinker==1.9.0
+cachetools==6.1.0
+certifi==2025.6.15
+charset-normalizer==3.4.2
+click==8.2.1
+datetime==5.5
+distro==1.9.0
+gitdb==4.0.12
+gitpython==3.1.44
+h11==0.16.0
+httpcore==1.0.9
+httpx==0.28.1
+idna==3.10
+jinja2==3.1.6
+jiter==0.10.0
+jsonschema==4.24.0
+jsonschema-specifications==2025.4.1
+markupsafe==3.0.2
+narwhals==1.43.1
+numpy==2.3.0
+openai==1.88.0
+packaging==25.0
+pandas==2.3.0
+pillow==11.2.1
+protobuf==6.31.1
+pyarrow==20.0.0
+pydantic==2.11.7
+pydantic-core==2.33.2
+pydeck==0.9.1
+python-dateutil==2.9.0.post0
+pytz==2025.2
+referencing==0.36.2
+requests==2.32.4
+rpds-py==0.25.1
+setuptools==80.9.0
+six==1.17.0
+smmap==5.0.2
+sniffio==1.3.1
+soupsieve==2.7
+streamlit==1.46.0
+tenacity==9.1.2
+toml==0.10.2
+tornado==6.5.1
+tqdm==4.67.1
+typing-extensions==4.14.0
+typing-inspection==0.4.1
+tzdata==2025.2
+urllib3==2.5.0
+wikipedia==1.4.0
+zope-interface==7.2

docs/chapter7/Agent/src/core.py

@@ -2,11 +2,11 @@ from openai import OpenAI
 import json
 from typing import List, Dict, Any
 from src.utils import function_to_json
-from src.tools import get_current_datetime, add, compare, count_letter_in_string
+from src.tools import get_current_datetime, add, compare, count_letter_in_string, search_wikipedia, get_current_temperature
 
 import pprint
 
-SYSREM_PROMPT = """
+SYSTEM_PROMPT = """
 你是一个叫不要葱姜蒜的人工智能助手。你的输出应该与用户的语言保持一致。
 当用户的问题需要调用工具时，你可以从提供的工具列表中调用适当的工具函数。
 """
@@ -17,7 +17,7 @@ class Agent:
         self.tools = tools
         self.model = model
         self.messages = [
-            {"role": "system", "content": SYSREM_PROMPT},
+            {"role": "system", "content": SYSTEM_PROMPT},
         ]
         self.verbose = verbose
 

docs/chapter7/Agent/src/tools.py

@@ -1,12 +1,14 @@
-from datetime import datetime
+import datetime
+import wikipedia
+import requests
 
 # 获取当前日期和时间
 def get_current_datetime() -> str:
     """
-    获取当前日期和时间。
+    获取真实的当前日期和时间。
     :return: 当前日期和时间的字符串表示。
     """
-    current_datetime = datetime.now()
+    current_datetime = datetime.datetime.now()
     formatted_datetime = current_datetime.strftime("%Y-%m-%d %H:%M:%S")
     return formatted_datetime
 
@@ -54,3 +56,76 @@ def count_letter_in_string(a: str, b: str):
     
     count = string.count(letter)
     return(f"The letter '{letter}' appears {count} times in the string.")
+
+def search_wikipedia(query: str) -> str:
+    """
+    在维基百科中搜索指定查询的前三个页面摘要。
+    :param query: 要搜索的查询字符串。
+    :return: 包含前三个页面摘要的字符串。
+    """
+    page_titles = wikipedia.search(query)
+    summaries = []
+    for page_title in page_titles[: 3]:  # 取前三个页面标题
+        try:
+            # 使用 wikipedia 模块的 page 函数，获取指定标题的维基百科页面对象。
+            wiki_page = wikipedia.page(title=page_title, auto_suggest=False)
+            # 获取页面摘要
+            summaries.append(f"页面: {page_title}\n摘要: {wiki_page.summary}")
+        except (
+                wikipedia.exceptions.PageError,
+                wikipedia.exceptions.DisambiguationError,
+        ):
+            pass
+    if not summaries:
+        return "维基百科没有搜索到合适的结果"
+    return "\n\n".join(summaries)
+
+
+def get_current_temperature(latitude: float, longitude: float) -> str:
+    """
+    获取指定经纬度位置的当前温度。
+    :param latitude: 纬度坐标。
+    :param longitude: 经度坐标。
+    :return: 当前温度的字符串表示。
+    """
+
+    # Open Meteo API 的URL
+    open_meteo_url = "https://api.open-meteo.com/v1/forecast"
+
+    # 请求参数
+    params = {
+        'latitude': latitude,
+        'longitude': longitude,
+        'hourly': 'temperature_2m',
+        'forecast_days': 1,
+    }
+
+    # 发送 API 请求
+    response = requests.get(open_meteo_url, params=params)
+
+    # 检查响应状态码
+    if response.status_code == 200:
+        # 解析 JSON 响应
+        results = response.json()
+    else:
+        # 处理请求失败的情况
+        raise Exception(f"API Request failed with status code: {response.status_code}")
+
+    # 获取当前 UTC 时间
+    current_utc_time = datetime.datetime.now(datetime.UTC)
+
+    # 将时间字符串转换为 datetime 对象
+    time_list = [datetime.datetime.fromisoformat(time_str).replace(tzinfo=datetime.timezone.utc) for time_str in
+                 results['hourly']['time']]
+
+    # 获取温度列表
+    temperature_list = results['hourly']['temperature_2m']
+
+    # 找到最接近当前时间的索引
+    closest_time_index = min(range(len(time_list)), key=lambda i: abs(time_list[i] - current_utc_time))
+
+    # 获取当前温度
+    current_temperature = temperature_list[closest_time_index]
+
+    # 返回当前温度的字符串形式
+    return f'现在温度是 {current_temperature}°C'

docs/chapter7/Agent/web_demo.py

@@ -0,0 +1,62 @@
+import streamlit as st
+from src.core import Agent
+from src.tools import add, count_letter_in_string, compare, get_current_datetime, search_wikipedia, get_current_temperature
+from openai import OpenAI
+
+# --- 页面配置 ---
+st.set_page_config(
+    page_title="Tiny Agent Demo",  # 页面标题
+    page_icon="🤖",  # 页面图标
+    layout="centered",  # 页面布局
+    initial_sidebar_state="auto",  # 侧边栏初始状态
+)
+
+# --- OpenAI客户端初始化 ---
+client = OpenAI(
+    api_key="sk-quovvfgjdmmrvwiljusggiwvxfiekzicwjgtdvpfqhpmbpqu",
+    base_url="https://api.siliconflow.cn/v1",  
+)
+
+# --- Agent初始化 ---
+@st.cache_resource
+def load_agent():
+    """创建并缓存Agent实例。"""
+    return Agent(
+        client=client,
+        model="Qwen/Qwen2.5-32B-Instruct",  # 使用的模型
+        tools=[get_current_datetime, search_wikipedia, get_current_temperature],  # Agent可以使用的工具
+    )
+
+agent = load_agent()  # 加载Agent
+
+# --- UI组件 ---
+st.title("🤖 Happy-LLM Tiny Agent")  # 设置页面标题
+st.markdown("""欢迎来到 Tiny Agent web 界面！
+
+在下方输入您的提示，查看 Agent 的实际操作。
+""")  # 显示Markdown格式的欢迎信息
+
+# 初始化聊天记录
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+# 在应用重新运行时显示历史聊天记录
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.markdown(message["content"])
+
+# 响应用户输入
+if prompt := st.chat_input("我能为您做些什么？"):
+    # 在聊天消息容器中显示用户消息
+    st.chat_message("user").markdown(prompt)
+    # 将用户消息添加到聊天记录中
+    st.session_state.messages.append({"role": "user", "content": prompt})
+
+    with st.spinner('思考中...'):
+        response = agent.get_completion(prompt)  # 获取Agent的响应
+        
+    # 在聊天消息容器中显示助手响应
+    with st.chat_message("assistant"):
+        st.markdown(response)
+    # 将助手响应添加到聊天记录中
+    st.session_state.messages.append({"role": "assistant", "content": response})

docs/chapter7/RAG/.env_example

@@ -0,0 +1,4 @@
+# 此处默认使用国内可访问的轨迹流动平台 https://cloud.siliconflow.cn/
+
+OPENAI_API_KEY='your api key'
+OPENAI_BASE_URL='https://api.siliconflow.cn/v1' 

docs/chapter7/RAG/Embeddings.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 '''
-@File    :   Embeddings.py
-@Time    :   2024/02/10 21:55:39
+@File    :   Embedding.py
+@Time    :   2025/06/20 13:50:47
 @Author  :   不要葱姜蒜
-@Version :   1.0
+@Version :   1.1
 @Desc    :   None
 '''
 
@@ -12,8 +12,8 @@ import os
 from copy import copy
 from typing import Dict, List, Optional, Tuple, Union
 import numpy as np
+from openai import OpenAI
 
-os.environ['CURL_CA_BUNDLE'] = ''
 from dotenv import load_dotenv, find_dotenv
 _ = load_dotenv(find_dotenv())
 
@@ -23,21 +23,59 @@ class BaseEmbeddings:
     Base class for embeddings
     """
     def __init__(self, path: str, is_api: bool) -> None:
+        """
+        初始化嵌入基类
+        Args:
+            path (str): 模型或数据的路径
+            is_api (bool): 是否使用API方式。True表示使用在线API服务，False表示使用本地模型
+        """
         self.path = path
         self.is_api = is_api
     
     def get_embedding(self, text: str, model: str) -> List[float]:
+        """
+        获取文本的嵌入向量表示
+        Args:
+            text (str): 输入文本
+            model (str): 使用的模型名称
+        Returns:
+            List[float]: 文本的嵌入向量
+        Raises:
+            NotImplementedError: 该方法需要在子类中实现
+        """
         raise NotImplementedError
     
     @classmethod
     def cosine_similarity(cls, vector1: List[float], vector2: List[float]) -> float:
         """
-        calculate cosine similarity between two vectors
+        计算两个向量之间的余弦相似度
+        Args:
+            vector1 (List[float]): 第一个向量
+            vector2 (List[float]): 第二个向量
+        Returns:
+            float: 两个向量的余弦相似度，范围在[-1,1]之间
         """
-        dot_product = np.dot(vector1, vector2)
-        magnitude = np.linalg.norm(vector1) * np.linalg.norm(vector2)
-        if not magnitude:
-            return 0
+        # 将输入列表转换为numpy数组，并指定数据类型为float32
+        v1 = np.array(vector1, dtype=np.float32)
+        v2 = np.array(vector2, dtype=np.float32)
+
+        # 检查向量中是否包含无穷大或NaN值
+        if not np.all(np.isfinite(v1)) or not np.all(np.isfinite(v2)):
+            return 0.0
+
+        # 计算向量的点积
+        dot_product = np.dot(v1, v2)
+        # 计算向量的范数（长度）
+        norm_v1 = np.linalg.norm(v1)
+        norm_v2 = np.linalg.norm(v2)
+        
+        # 计算分母（两个向量范数的乘积）
+        magnitude = norm_v1 * norm_v2
+        # 处理分母为0的特殊情况
+        if magnitude == 0:
+            return 0.0
+            
+        # 返回余弦相似度
         return dot_product / magnitude
     
 
@@ -48,70 +86,18 @@ class OpenAIEmbedding(BaseEmbeddings):
     def __init__(self, path: str = '', is_api: bool = True) -> None:
         super().__init__(path, is_api)
         if self.is_api:
-            from openai import OpenAI
             self.client = OpenAI()
+            # 从环境变量中获取 硅基流动 密钥
             self.client.api_key = os.getenv("OPENAI_API_KEY")
+            # 从环境变量中获取 硅基流动 的基础URL
             self.client.base_url = os.getenv("OPENAI_BASE_URL")
     
-    def get_embedding(self, text: str, model: str = "text-embedding-3-large") -> List[float]:
+    def get_embedding(self, text: str, model: str = "BAAI/bge-m3") -> List[float]:
+        """
+        此处默认使用轨迹流动的免费嵌入模型 BAAI/bge-m3
+        """
         if self.is_api:
             text = text.replace("\n", " ")
             return self.client.embeddings.create(input=[text], model=model).data[0].embedding
         else:
             raise NotImplementedError
-
-class JinaEmbedding(BaseEmbeddings):
-    """
-    class for Jina embeddings
-    """
-    def __init__(self, path: str = 'jinaai/jina-embeddings-v2-base-zh', is_api: bool = False) -> None:
-        super().__init__(path, is_api)
-        self._model = self.load_model()
-        
-    def get_embedding(self, text: str) -> List[float]:
-        return self._model.encode([text])[0].tolist()
-    
-    def load_model(self):
-        import torch
-        from transformers import AutoModel
-        if torch.cuda.is_available():
-            device = torch.device("cuda")
-        else:
-            device = torch.device("cpu")
-        model = AutoModel.from_pretrained(self.path, trust_remote_code=True).to(device)
-        return model
-
-class ZhipuEmbedding(BaseEmbeddings):
-    """
-    class for Zhipu embeddings
-    """
-    def __init__(self, path: str = '', is_api: bool = True) -> None:
-        super().__init__(path, is_api)
-        if self.is_api:
-            from zhipuai import ZhipuAI
-            self.client = ZhipuAI(api_key=os.getenv("ZHIPUAI_API_KEY")) 
-    
-    def get_embedding(self, text: str) -> List[float]:
-        response = self.client.embeddings.create(
-        model="embedding-2",
-        input=text,
-        )
-        return response.data[0].embedding
-
-class DashscopeEmbedding(BaseEmbeddings):
-    """
-    class for Dashscope embeddings
-    """
-    def __init__(self, path: str = '', is_api: bool = True) -> None:
-        super().__init__(path, is_api)
-        if self.is_api:
-            import dashscope
-            dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
-            self.client = dashscope.TextEmbedding
-
-    def get_embedding(self, text: str, model: str='text-embedding-v1') -> List[float]:
-        response = self.client.call(
-            model=model,
-            input=text
-        )
-        return response.output['embeddings'][0]['embedding']

docs/chapter7/RAG/LLM.py

@@ -2,37 +2,33 @@
 # -*- coding: utf-8 -*-
 '''
 @File    :   LLM.py
-@Time    :   2024/02/12 13:50:47
+@Time    :   2025/06/20 13:50:47
 @Author  :   不要葱姜蒜
-@Version :   1.0
+@Version :   1.1
 @Desc    :   None
 '''
 import os
 from typing import Dict, List, Optional, Tuple, Union
+from openai import OpenAI
 
-PROMPT_TEMPLATE = dict(
-    RAG_PROMPT_TEMPALTE="""使用以上下文来回答用户的问题。如果你不知道答案，就说你不知道。总是使用中文回答。
-        问题: {question}
-        可参考的上下文：
-        ···
-        {context}
-        ···
-        如果给定的上下文无法让你做出回答，请回答数据库中没有这个内容，你不知道。
-        有用的回答:""",
-    InternLM_PROMPT_TEMPALTE="""先对上下文进行内容总结,再使用上下文来回答用户的问题。如果你不知道答案，就说你不知道。总是使用中文回答。
-        问题: {question}
-        可参考的上下文：
-        ···
-        {context}
-        ···
-        如果给定的上下文无法让你做出回答，请回答数据库中没有这个内容，你不知道。
-        有用的回答:"""
-)
+from dotenv import load_dotenv, find_dotenv
+_ = load_dotenv(find_dotenv())
+
+RAG_PROMPT_TEMPLATE="""
+使用以上下文来回答用户的问题。如果你不知道答案，就说你不知道。总是使用中文回答。
+问题: {question}
+可参考的上下文：
+···
+{context}
+···
+如果给定的上下文无法让你做出回答，请回答数据库中没有这个内容，你不知道。
+有用的回答:
+"""
 
 
 class BaseModel:
-    def __init__(self, path: str = '') -> None:
-        self.path = path
+    def __init__(self, model) -> None:
+        self.model = model
 
     def chat(self, prompt: str, history: List[dict], content: str) -> str:
         pass
@@ -41,73 +37,18 @@ class BaseModel:
         pass
 
 class OpenAIChat(BaseModel):
-    def __init__(self, path: str = '', model: str = "gpt-3.5-turbo-1106") -> None:
-        super().__init__(path)
+    def __init__(self, model: str = "Qwen/Qwen2.5-32B-Instruct") -> None:
         self.model = model
 
     def chat(self, prompt: str, history: List[dict], content: str) -> str:
-        from openai import OpenAI
         client = OpenAI()
         client.api_key = os.getenv("OPENAI_API_KEY")   
         client.base_url = os.getenv("OPENAI_BASE_URL")
-        history.append({'role': 'user', 'content': PROMPT_TEMPLATE['RAG_PROMPT_TEMPALTE'].format(question=prompt, context=content)})
+        history.append({'role': 'user', 'content': RAG_PROMPT_TEMPLATE.format(question=prompt, context=content)})
         response = client.chat.completions.create(
             model=self.model,
             messages=history,
-            max_tokens=150,
+            max_tokens=2048,
             temperature=0.1
         )
         return response.choices[0].message.content
-
-class InternLMChat(BaseModel):
-    def __init__(self, path: str = '') -> None:
-        super().__init__(path)
-        self.load_model()
-
-    def chat(self, prompt: str, history: List = [], content: str='') -> str:
-        prompt = PROMPT_TEMPLATE['InternLM_PROMPT_TEMPALTE'].format(question=prompt, context=content)
-        response, history = self.model.chat(self.tokenizer, prompt, history)
-        return response
-
-
-    def load_model(self):
-        import torch
-        from transformers import AutoTokenizer, AutoModelForCausalLM
-        self.tokenizer = AutoTokenizer.from_pretrained(self.path, trust_remote_code=True)
-        self.model = AutoModelForCausalLM.from_pretrained(self.path, torch_dtype=torch.float16, trust_remote_code=True).cuda()
-
-class DashscopeChat(BaseModel):
-    def __init__(self, path: str = '', model: str = "qwen-turbo") -> None:
-        super().__init__(path)
-        self.model = model
-
-    def chat(self, prompt: str, history: List[Dict], content: str) -> str:
-        import dashscope
-        dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
-        history.append({'role': 'user', 'content': PROMPT_TEMPLATE['RAG_PROMPT_TEMPALTE'].format(question=prompt, context=content)})
-        response = dashscope.Generation.call(
-            model=self.model,
-            messages=history,
-            result_format='message',
-            max_tokens=150,
-            temperature=0.1
-        )
-        return response.output.choices[0].message.content
-    
-
-class ZhipuChat(BaseModel):
-    def __init__(self, path: str = '', model: str = "glm-4") -> None:
-        super().__init__(path)
-        from zhipuai import ZhipuAI
-        self.client = ZhipuAI(api_key=os.getenv("ZHIPUAI_API_KEY"))
-        self.model = model
-
-    def chat(self, prompt: str, history: List[Dict], content: str) -> str:
-        history.append({'role': 'user', 'content': PROMPT_TEMPLATE['RAG_PROMPT_TEMPALTE'].format(question=prompt, context=content)})
-        response = self.client.chat.completions.create(
-            model=self.model,
-            messages=history,
-            max_tokens=150,
-            temperature=0.1
-        )
-        return response.choices[0].message

docs/chapter7/RAG/VectorBase.py

@@ -2,16 +2,16 @@
 # -*- coding: utf-8 -*-
 '''
 @File    :   VectorBase.py
-@Time    :   2024/02/12 10:11:13
+@Time    :   2025/06/20 10:11:13
 @Author  :   不要葱姜蒜
-@Version :   1.0
+@Version :   1.1
 @Desc    :   None
 '''
 
 import os
 from typing import Dict, List, Optional, Tuple, Union
 import json
-from RAG.Embeddings import BaseEmbeddings, OpenAIEmbedding, JinaEmbedding, ZhipuEmbedding
+from Embeddings import BaseEmbeddings, OpenAIEmbedding
 import numpy as np
 from tqdm import tqdm
 

docs/chapter7/RAG/demo.py

@@ -0,0 +1,19 @@
+from VectorBase import VectorStore
+from utils import ReadFiles
+from LLM import OpenAIChat
+from Embeddings import OpenAIEmbedding
+
+# 没有保存数据库
+docs = ReadFiles('./data').get_content(max_token_len=600, cover_content=150) # 获得data目录下的所有文件内容并分割
+vector = VectorStore(docs)
+embedding = OpenAIEmbedding() # 创建EmbeddingModel
+vector.get_vector(EmbeddingModel=embedding)
+vector.persist(path='storage') # 将向量和文档内容保存到storage目录下，下次再用就可以直接加载本地的数据库
+
+# vector.load_vector('./storage') # 加载本地的数据库
+
+question = 'RAG的原理是什么？'
+
+content = vector.query(question, EmbeddingModel=embedding, k=1)[0]
+chat = OpenAIChat(model='Qwen/Qwen2.5-32B-Instruct')
+print(chat.chat(question, [], content))

docs/chapter7/RAG/requirements.txt

@@ -0,0 +1,28 @@
+annotated-types==0.7.0
+anyio==4.9.0
+beautifulsoup4==4.13.4
+bs4==0.0.2
+certifi==2025.6.15
+charset-normalizer==3.4.2
+distro==1.9.0
+h11==0.16.0
+httpcore==1.0.9
+httpx==0.28.1
+idna==3.10
+jiter==0.10.0
+markdown==3.8.2
+numpy==2.3.0
+openai==1.88.0
+pydantic==2.11.7
+pydantic-core==2.33.2
+pypdf2==3.0.1
+python-dotenv==1.1.0
+regex==2024.11.6
+requests==2.32.4
+sniffio==1.3.1
+soupsieve==2.7
+tiktoken==0.9.0
+tqdm==4.67.1
+typing-extensions==4.14.0
+typing-inspection==0.4.1
+urllib3==2.5.0

docs/chapter7/RAG/utils.py

@@ -2,9 +2,9 @@
 # -*- coding: utf-8 -*-
 '''
 @File    :   utils.py
-@Time    :   2024/02/11 09:52:26
+@Time    :   2025/06/20 13:50:47
 @Author  :   不要葱姜蒜
-@Version :   1.0
+@Version :   1.1
 @Desc    :   None
 '''
 
@@ -13,7 +13,6 @@ from typing import Dict, List, Optional, Tuple, Union
 
 import PyPDF2
 import markdown
-import html2text
 import json
 from tqdm import tqdm
 import tiktoken
@@ -69,37 +68,65 @@ class ReadFiles:
         lines = text.splitlines()  # 假设以换行符分割文本为行
 
         for line in lines:
-            line = line.replace(' ', '')
+            # 保留空格，只移除行首行尾空格
+            line = line.strip()
             line_len = len(enc.encode(line))
+            
             if line_len > max_token_len:
                 # 如果单行长度就超过限制，则将其分割成多个块
-                num_chunks = (line_len + token_len - 1) // token_len
-                for i in range(num_chunks):
-                    start = i * token_len
-                    end = start + token_len
-                    # 避免跨单词分割
-                    while not line[start:end].rstrip().isspace():
-                        start += 1
-                        end += 1
-                        if start >= line_len:
-                            break
-                    curr_chunk = curr_chunk[-cover_content:] + line[start:end]
+                # 先保存当前块（如果有内容）
+                if curr_chunk:
                     chunk_text.append(curr_chunk)
-                # 处理最后一个块
-                start = (num_chunks - 1) * token_len
-                curr_chunk = curr_chunk[-cover_content:] + line[start:end]
-                chunk_text.append(curr_chunk)
+                    curr_chunk = ''
+                    curr_len = 0
                 
-            if curr_len + line_len <= token_len:
+                # 将长行按token长度分割
+                line_tokens = enc.encode(line)
+                num_chunks = (len(line_tokens) + token_len - 1) // token_len
+                
+                for i in range(num_chunks):
+                    start_token = i * token_len
+                    end_token = min(start_token + token_len, len(line_tokens))
+                    
+                    # 解码token片段回文本
+                    chunk_tokens = line_tokens[start_token:end_token]
+                    chunk_part = enc.decode(chunk_tokens)
+                    
+                    # 添加覆盖内容（除了第一个块）
+                    if i > 0 and chunk_text:
+                        prev_chunk = chunk_text[-1]
+                        cover_part = prev_chunk[-cover_content:] if len(prev_chunk) > cover_content else prev_chunk
+                        chunk_part = cover_part + chunk_part
+                    
+                    chunk_text.append(chunk_part)
+                
+                # 重置当前块状态
+                curr_chunk = ''
+                curr_len = 0
+                
+            elif curr_len + line_len + 1 <= token_len:  # +1 for newline
+                # 当前行可以加入当前块
+                if curr_chunk:
+                    curr_chunk += '\n'
+                    curr_len += 1
                 curr_chunk += line
-                curr_chunk += '\n'
                 curr_len += line_len
-                curr_len += 1
             else:
-                chunk_text.append(curr_chunk)
-                curr_chunk = curr_chunk[-cover_content:]+line
-                curr_len = line_len + cover_content
+                # 当前行无法加入当前块，开始新块
+                if curr_chunk:
+                    chunk_text.append(curr_chunk)
+                
+                # 开始新块，添加覆盖内容
+                if chunk_text:
+                    prev_chunk = chunk_text[-1]
+                    cover_part = prev_chunk[-cover_content:] if len(prev_chunk) > cover_content else prev_chunk
+                    curr_chunk = cover_part + '\n' + line
+                    curr_len = len(enc.encode(cover_part)) + 1 + line_len
+                else:
+                    curr_chunk = line
+                    curr_len = line_len
 
+        # 添加最后一个块（如果有内容）
         if curr_chunk:
             chunk_text.append(curr_chunk)
 

docs/chapter7/第七章 大模型应用.md

@@ -17,7 +17,6 @@
 
 2. **工具使用评测集**：
    - **BFCL V2**：用于评测模型在复杂工具使用任务中的表现，特别是在执行多步骤操作时的正确性和效率。这些任务通常涉及与数据库交互或执行特定指令，以模拟实际工具使用场景。
-   - **Nexus**：用于测试模型在多步骤操作中的工具使用能力，主要评估其在多任务操作中的协调性和任务管理能力，如进行文件操作、数据整合等复杂流程。
 
 3. **数学评测集**：
    - **GSM8K**：GSM8K是一个包含小学数学问题的数据集，用于测试模型的数学推理和逻辑分析能力。具体任务包括算术运算、简单方程求解、数字推理等。GSM8K中的问题虽然看似简单，但模型需要理解问题语义并进行正确的数学运算，体现了逻辑推理和语言理解的双重挑战。
@@ -47,7 +46,7 @@
 Open LLM Leaderboard 为由 Hugging Face 提供的开放式榜单，汇集了多个开源大模型的评测结果，帮助用户了解不同模型在各种任务上的表现。该榜单通过多个标准化测试集来评估模型的性能，并通过持续更新的方式反映最新的技术进展，为研究者和开发者提供了高价值的对比参考，如图7.1所示。
 
 <div align='center'>
-    <img src="../images/7-images/7-1-Open%20LLM%20Leaderboard.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-1-Open%20LLM%20Leaderboard.png" alt="alt text" width="90%">
     <p>图 7.1 Open LLM Leaderboard</p>
 </div>
 
@@ -56,7 +55,7 @@ Open LLM Leaderboard 为由 Hugging Face 提供的开放式榜单，汇集了多
 由lmsys提供的聊天机器人评测榜单，通过多维度的评估，展示各类大模型在对话任务中的能力。该榜单采用真实用户与模型交互的方式来评测对话质量，重点考察模型的自然语言生成能力、上下文理解能力以及用户满意度，是当前评估聊天机器人性能的重要工具，如图7.2所示。
 
 <div align='center'>
-    <img src="../images/7-images/7-1-lmsys%20Chatbot%20Arena%20Leaderboard.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-1-lmsys%20Chatbot%20Arena%20Leaderboard.png" alt="alt text" width="90%">
     <p>图7.2 Lmsys Chatbot Arena Leaderboard</p>
 </div>
 
@@ -65,7 +64,7 @@ Open LLM Leaderboard 为由 Hugging Face 提供的开放式榜单，汇集了多
 OpenCompass 是国内的评测榜单，针对大模型在多种语言和任务上的表现进行评估，提供了中国市场特定应用的参考。该榜单结合了中文语言理解和多语言能力的测试，以适应本地化需求，并特别关注大模型在中文语境下的准确性、鲁棒性和适应性，为国内企业和研究者选择合适的模型提供了重要参考。
 
 <div align='center'>
-    <img src="../images/7-images/7-1-opencompass.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-1-opencompass.png" alt="alt text" width="90%">
     <p>图7.3 OpenCompass</p>
 </div>
 
@@ -84,7 +83,7 @@ OpenCompass 是国内的评测榜单，针对大模型在多种语言和任务
 - 医疗榜：基于MedBench评测集，评估大语言模型在医学知识问答、安全伦理理解等方面的表现。由上海人工智能实验室提供。
 
 <div align='center'>
-    <img src="../images/7-images/7-1-垂直领域榜单.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-1-垂直领域榜单.png" alt="alt text" width="90%">
     <p>图7.4 垂直领域榜单</p>
 </div>
 
@@ -118,7 +117,7 @@ RAG的基本结构有哪些呢？
 上述也就是 TinyRAG 的所有模块内容，如图7.5所示。
 
 <div align='center'>
-    <img src="../images/7-images/7-2-tinyrag.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-2-tinyrag.png" alt="alt text" width="90%">
     <p>图7.5 TinyRAG 项目结构</p>
 </div>
 
@@ -131,66 +130,11 @@ RAG的基本结构有哪些呢？
 如下图7.6所示的流程图，图片出处 ***[Retrieval-Augmented Generation for Large Language Models: A Survey](https://arxiv.org/pdf/2312.10997.pdf)***
 
 <div align='center'>
-    <img src="../images/7-images/7-2-rag.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-2-rag.png" alt="alt text" width="90%">
     <p>图7.6 RAG 流程图</p>
 </div>
 
-#### Step 2: 向量化
-
-首先我们来动手实现一个向量化的类，这是RAG架构的基础。向量化类主要用来将文档片段向量化，将一段文本映射为一个向量。
-
-首先我们要设置一个 `BaseEmbeddings` 基类，这样我们在使用其他模型时，只需要继承这个基类，然后在此基础上进行修改即可，方便代码扩展。
-
-```python
-class BaseEmbeddings:
-    """
-    Base class for embeddings
-    """
-    def __init__(self, path: str, is_api: bool) -> None:
-        self.path = path
-        self.is_api = is_api
-    
-    def get_embedding(self, text: str, model: str) -> List[float]:
-        raise NotImplementedError
-    
-    @classmethod
-    def cosine_similarity(cls, vector1: List[float], vector2: List[float]) -> float:
-        """
-        calculate cosine similarity between two vectors
-        """
-        dot_product = np.dot(vector1, vector2)
-        magnitude = np.linalg.norm(vector1) * np.linalg.norm(vector2)
-        if not magnitude:
-            return 0
-        return dot_product / magnitude
-```
-
-`BaseEmbeddings`基类有两个主要方法：`get_embedding`和`cosine_similarity`。`get_embedding`用于获取文本的向量表示，`cosine_similarity`用于计算两个向量之间的余弦相似度。在初始化类时设置了模型的路径和是否是API模型，例如使用OpenAI的Embedding API需要设置`self.is_api=True`。
-
-继承`BaseEmbeddings`类只需要实现`get_embedding`方法，`cosine_similarity`方法会被继承下来。这就是编写基类的好处。
-
-```python
-class OpenAIEmbedding(BaseEmbeddings):
-    """
-    class for OpenAI embeddings
-    """
-    def __init__(self, path: str = '', is_api: bool = True) -> None:
-        super().__init__(path, is_api)
-        if self.is_api:
-            from openai import OpenAI
-            self.client = OpenAI()
-            self.client.api_key = os.getenv("OPENAI_API_KEY")
-            self.client.base_url = os.getenv("OPENAI_BASE_URL")
-    
-    def get_embedding(self, text: str, model: str = "text-embedding-3-large") -> List[float]:
-        if self.is_api:
-            text = text.replace("\n", " ")
-            return self.client.embeddings.create(input=[text], model=model).data[0].embedding
-        else:
-            raise NotImplementedError
-```
-
-#### Step 3: 文档加载和切分
+#### Step 2: 文档加载和切分
 
 接下来我们来实现一个文档加载和切分的类，这个类主要用于加载文档并将其切分成文档片段。
 
@@ -218,29 +162,176 @@ def get_chunk(cls, text: str, max_token_len: int = 600, cover_content: int = 150
     curr_len = 0
     curr_chunk = ''
 
-    lines = text.split('\n')
+    token_len = max_token_len - cover_content
+    lines = text.splitlines()  # 假设以换行符分割文本为行
 
     for line in lines:
-        line = line.replace(' ', '')
+        # 保留空格，只移除行首行尾空格
+        line = line.strip()
         line_len = len(enc.encode(line))
+        
         if line_len > max_token_len:
-            print('warning line_len = ', line_len)
-        if curr_len + line_len <= max_token_len:
+            # 如果单行长度就超过限制，则将其分割成多个块
+            # 先保存当前块（如果有内容）
+            if curr_chunk:
+                chunk_text.append(curr_chunk)
+                curr_chunk = ''
+                curr_len = 0
+            
+            # 将长行按token长度分割
+            line_tokens = enc.encode(line)
+            num_chunks = (len(line_tokens) + token_len - 1) // token_len
+            
+            for i in range(num_chunks):
+                start_token = i * token_len
+                end_token = min(start_token + token_len, len(line_tokens))
+                
+                # 解码token片段回文本
+                chunk_tokens = line_tokens[start_token:end_token]
+                chunk_part = enc.decode(chunk_tokens)
+                
+                # 添加覆盖内容（除了第一个块）
+                if i > 0 and chunk_text:
+                    prev_chunk = chunk_text[-1]
+                    cover_part = prev_chunk[-cover_content:] if len(prev_chunk) > cover_content else prev_chunk
+                    chunk_part = cover_part + chunk_part
+                
+                chunk_text.append(chunk_part)
+            
+            # 重置当前块状态
+            curr_chunk = ''
+            curr_len = 0
+            
+        elif curr_len + line_len + 1 <= token_len:  # +1 for newline
+            # 当前行可以加入当前块
+            if curr_chunk:
+                curr_chunk += '\n'
+                curr_len += 1
             curr_chunk += line
-            curr_chunk += '\n'
             curr_len += line_len
-            curr_len += 1
         else:
-            chunk_text.append(curr_chunk)
-            curr_chunk = curr_chunk[-cover_content:] + line
-            curr_len = line_len + cover_content
+            # 当前行无法加入当前块，开始新块
+            if curr_chunk:
+                chunk_text.append(curr_chunk)
+            
+            # 开始新块，添加覆盖内容
+            if chunk_text:
+                prev_chunk = chunk_text[-1]
+                cover_part = prev_chunk[-cover_content:] if len(prev_chunk) > cover_content else prev_chunk
+                curr_chunk = cover_part + '\n' + line
+                curr_len = len(enc.encode(cover_part)) + 1 + line_len
+            else:
+                curr_chunk = line
+                curr_len = line_len
 
+    # 添加最后一个块（如果有内容）
     if curr_chunk:
         chunk_text.append(curr_chunk)
 
     return chunk_text
+
 ```
 
+#### Step 3: 向量化
+
+首先我们来动手实现一个向量化的类，这是RAG架构的基础。向量化类主要用来将文档片段向量化，将一段文本映射为一个向量。
+
+首先我们要设置一个 `BaseEmbeddings` 基类，这样我们在使用其他模型时，只需要继承这个基类，然后在此基础上进行修改即可，方便代码扩展。
+
+```python
+class BaseEmbeddings:
+    """
+    Base class for embeddings
+    """
+    def __init__(self, path: str, is_api: bool) -> None:
+        """
+        初始化嵌入基类
+        Args:
+            path (str): 模型或数据的路径
+            is_api (bool): 是否使用API方式。True表示使用在线API服务，False表示使用本地模型
+        """
+        self.path = path
+        self.is_api = is_api
+    
+    def get_embedding(self, text: str, model: str) -> List[float]:
+        """
+        获取文本的嵌入向量表示
+        Args:
+            text (str): 输入文本
+            model (str): 使用的模型名称
+        Returns:
+            List[float]: 文本的嵌入向量
+        Raises:
+            NotImplementedError: 该方法需要在子类中实现
+        """
+        raise NotImplementedError
+    
+    @classmethod
+    def cosine_similarity(cls, vector1: List[float], vector2: List[float]) -> float:
+        """
+        计算两个向量之间的余弦相似度
+        Args:
+            vector1 (List[float]): 第一个向量
+            vector2 (List[float]): 第二个向量
+        Returns:
+            float: 两个向量的余弦相似度，范围在[-1,1]之间
+        """
+        # 将输入列表转换为numpy数组，并指定数据类型为float32
+        v1 = np.array(vector1, dtype=np.float32)
+        v2 = np.array(vector2, dtype=np.float32)
+
+        # 检查向量中是否包含无穷大或NaN值
+        if not np.all(np.isfinite(v1)) or not np.all(np.isfinite(v2)):
+            return 0.0
+
+        # 计算向量的点积
+        dot_product = np.dot(v1, v2)
+        # 计算向量的范数（长度）
+        norm_v1 = np.linalg.norm(v1)
+        norm_v2 = np.linalg.norm(v2)
+        
+        # 计算分母（两个向量范数的乘积）
+        magnitude = norm_v1 * norm_v2
+        # 处理分母为0的特殊情况
+        if magnitude == 0:
+            return 0.0
+            
+        # 返回余弦相似度
+        return dot_product / magnitude
+```
+
+`BaseEmbeddings`基类有两个主要方法：`get_embedding`和`cosine_similarity`。`get_embedding`用于获取文本的向量表示，`cosine_similarity`用于计算两个向量之间的余弦相似度。在初始化类时设置了模型的路径和是否是API模型，例如使用OpenAI的Embedding API需要设置`self.is_api=True`。
+
+继承`BaseEmbeddings`类只需要实现`get_embedding`方法，`cosine_similarity`方法会被继承下来。这就是编写基类的好处。
+
+```python
+class OpenAIEmbedding(BaseEmbeddings):
+    """
+    class for OpenAI embeddings
+    """
+    def __init__(self, path: str = '', is_api: bool = True) -> None:
+        super().__init__(path, is_api)
+        if self.is_api:
+            self.client = OpenAI()
+            # 从环境变量中获取 硅基流动 密钥
+            self.client.api_key = os.getenv("OPENAI_API_KEY")
+            # 从环境变量中获取 硅基流动 的基础URL
+            self.client.base_url = os.getenv("OPENAI_BASE_URL")
+    
+    def get_embedding(self, text: str, model: str = "BAAI/bge-m3") -> List[float]:
+        """
+        此处默认使用轨迹流动的免费嵌入模型 BAAI/bge-m3
+        """
+        if self.is_api:
+            text = text.replace("\n", " ")
+            return self.client.embeddings.create(input=[text], model=model).data[0].embedding
+        else:
+            raise NotImplementedError
+```
+
+> 注：此处我们默认使用国内用户可访问的[硅基流动大模型API服务平台](https://cloud.siliconflow.cn/i/ybUFvmqK)。
+
+
 #### Step 4: 数据库与向量检索
 
 完成文档切分和Embedding模型加载后，需要设计一个向量数据库来存放文档片段和对应的向量表示，以及设计一个检索模块用于根据Query检索相关文档片段。
@@ -252,7 +343,7 @@ def get_chunk(cls, text: str, max_token_len: int = 600, cover_content: int = 150
 - `get_vector`：获取文档的向量表示。
 - `query`：根据问题检索相关文档片段。
 
-完整代码可以在 ***[RAG/VectorBase.py](RAG/VectorBase.py)*** 文件中找到。
+完整代码可以在 ***[/VectorBase.py](./RAG/VectorBase.py)*** 文件中找到。
 
 ```python
 class VectorStore:
@@ -303,41 +394,43 @@ class BaseModel:
         pass
 ```
 
-`BaseModel` 包含两个方法：`chat`和`load_model`。对于本地化运行的开源模型需要实现`load_model`，而API模型则不需要。
-
-下面以 ***[InternLM2-chat-7B](https://huggingface.co/internlm/internlm2-chat-7b)*** 模型为例：
+`BaseModel` 包含两个方法：`chat`和`load_model`。对于本地化运行的开源模型需要实现`load_model`，而API模型则不需要。在此处我们还是使用国内用户可访问的硅基流动大模型API服务平台，使用API服务的好处就是用户不需要本地的计算资源，可以大大降低学习者的学习门槛。
 
 ```python
-class InternLMChat(BaseModel):
-    def __init__(self, path: str = '') -> None:
-        super().__init__(path)
-        self.load_model()
+from openai import OpenAI
 
-    def chat(self, prompt: str, history: List = [], content: str='') -> str:
-        prompt = PROMPT_TEMPLATE['InternLM_PROMPT_TEMPLATE'].format(question=prompt, context=content)
-        response, history = self.model.chat(self.tokenizer, prompt, history)
-        return response
+class OpenAIChat(BaseModel):
+    def __init__(self, model: str = "Qwen/Qwen2.5-32B-Instruct") -> None:
+        self.model = model
+
+    def chat(self, prompt: str, history: List[dict], content: str) -> str:
+        client = OpenAI()
+        client.api_key = os.getenv("OPENAI_API_KEY")   
+        client.base_url = os.getenv("OPENAI_BASE_URL")
+        history.append({'role': 'user', 'content': RAG_PROMPT_TEMPLATE.format(question=prompt, context=content)})
+        response = client.chat.completions.create(
+                model=self.model,
+                messages=history,
+                max_tokens=2048,
+                temperature=0.1
+            )
+        return response.choices[0].message.content
 
-    def load_model(self):
-        import torch
-        from transformers import AutoTokenizer, AutoModelForCausalLM
-        self.tokenizer = AutoTokenizer.from_pretrained(self.path, trust_remote_code=True)
-        self.model = AutoModelForCausalLM.from_pretrained(self.path, torch_dtype=torch.float16, trust_remote_code=True).cuda()
 ```
 
-可以用一个字典来保存所有的prompt，方便维护：
+设计一个专用于RAG的大模型提示词，如下：
 
 ```python
-PROMPT_TEMPLATE = dict(
-    InternLM_PROMPT_TEMPLATE="""先对上下文进行内容总结,再使用上下文来回答用户的问题。如果你不知道答案，就说你不知道。总是使用中文回答。
-        问题: {question}
-        可参考的上下文：
-        ···
-        {context}
-        ···
-        如果给定的上下文无法让你做出回答，请回答数据库中没有这个内容，你不知道。
-        有用的回答:"""
-)
+RAG_PROMPT_TEMPLATE="""
+使用以上下文来回答用户的问题。如果你不知道答案，就说你不知道。总是使用中文回答。
+问题: {question}
+可参考的上下文：
+···
+{context}
+···
+如果给定的上下文无法让你做出回答，请回答数据库中没有这个内容，你不知道。
+有用的回答:
+"""
 ```
 
 这样我们就可以利用InternLM2模型来做RAG啦！
@@ -347,47 +440,51 @@ PROMPT_TEMPLATE = dict(
 接下来，我们来看看Tiny-RAG的Demo吧！
 
 ```python
-from RAG.VectorBase import VectorStore
-from RAG.utils import ReadFiles
-from RAG.LLM import OpenAIChat, InternLMChat
-from RAG.Embeddings import JinaEmbedding, ZhipuEmbedding
+from VectorBase import VectorStore
+from utils import ReadFiles
+from LLM import OpenAIChat
+from Embeddings import OpenAIEmbedding
 
 # 没有保存数据库
-docs = ReadFiles('./data').get_content(max_token_len=600, cover_content=150) # 获取data目录下的所有文件内容并分割
+docs = ReadFiles('./data').get_content(max_token_len=600, cover_content=150) # 获得data目录下的所有文件内容并分割
 vector = VectorStore(docs)
-embedding = ZhipuEmbedding() # 创建EmbeddingModel
+embedding = OpenAIEmbedding() # 创建EmbeddingModel
 vector.get_vector(EmbeddingModel=embedding)
-vector.persist(path='storage') # 将向量和文档内容保存到storage目录，下次再用可以直接加载本地数据库
+vector.persist(path='storage') # 将向量和文档内容保存到storage目录下，下次再用就可以直接加载本地的数据库
 
-question = 'git的原理是什么？'
+# vector.load_vector('./storage') # 加载本地的数据库
 
-content = vector.query(question, model='zhipu', k=1)[0]
-chat = InternLMChat(path='model_path')
+question = 'RAG的原理是什么？'
+
+content = vector.query(question, EmbeddingModel=embedding, k=1)[0]
+chat = OpenAIChat(model='Qwen/Qwen2.5-32B-Instruct')
 print(chat.chat(question, [], content))
 ```
 
 也可以从本地加载已处理好的数据库：
 
 ```python
-from RAG.VectorBase import VectorStore
-from RAG.utils import ReadFiles
-from RAG.LLM import OpenAIChat, InternLMChat
-from RAG.Embeddings import JinaEmbedding, ZhipuEmbedding
+from VectorBase import VectorStore
+from utils import ReadFiles
+from LLM import OpenAIChat
+from Embeddings import OpenAIEmbedding
 
 # 保存数据库之后
 vector = VectorStore()
 
-vector.load_vector('./storage') # 加载本地数据库
+vector.load_vector('./storage') # 加载本地的数据库
 
-question = 'git的原理是什么？'
+question = 'RAG的原理是什么？'
 
 embedding = ZhipuEmbedding() # 创建EmbeddingModel
 
 content = vector.query(question, EmbeddingModel=embedding, k=1)[0]
-chat = InternLMChat(path='model_path')
+chat = OpenAIChat(model='Qwen/Qwen2.5-32B-Instruct')
 print(chat.chat(question, [], content))
 ```
 
+> 注：7.2 章节的所有代码均可在 [Happy-LLM Chapter7 RAG](https://github.com/datawhalechina/happy-llm/tree/main/docs/chapter7/RAG) 中找到。
+
 ## 7.3 Agent
 
 ### 7.3.1 什么是 LLM Agent？
@@ -403,7 +500,7 @@ print(chat.chat(question, [], content))
 传统的LLM像一个知识渊博但只能纸上谈兵的图书馆员，而 LLM Agent 则更像一个全能的私人助理，不仅懂得多，还能跑腿办事，甚至能主动思考最优方案。
 
 <div align='center'>
-    <img src="../images/7-images/7-3-Agent工作原理.png" alt="alt text" width="90%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-3-Agent工作原理.png" alt="alt text" width="90%">
     <p>图7.7 Agent 工作原理</p>
 </div>
 
@@ -440,7 +537,7 @@ LLM Agent 通过将大型语言模型的强大语言理解和生成能力与规
 最终的实现效果如图7.8所示：
 
 <div align='center'>
-    <img src="../images/7-images/7-3-tinyagent-example.png" style="width: 100%;">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-3-tinyagent-example.png" style="width: 100%;">
     <p>图7.8 效果示意图</p>
 </div>
 
@@ -481,29 +578,6 @@ def get_current_datetime() -> str:
     formatted_datetime = current_datetime.strftime("%Y-%m-%d %H:%M:%S")
     return formatted_datetime
 
-def add(a: float, b: float):
-    """
-    计算两个浮点数的和。
-    :param a: 第一个浮点数。
-    :param b: 第二个浮点数。
-    :return: 两个浮点数的和。
-    """
-    return str(a + b)
-
-def compare(a: float, b: float):
-    """
-    比较两个浮点数的大小。
-    :param a: 第一个浮点数。
-    :param b: 第二个浮点数。
-    :return: 比较结果的字符串表示。
-    """
-    if a > b:
-        return f'{a} is greater than {b}'
-    elif a < b:
-        return f'{b} is greater than {a}'
-    else:
-        return f'{a} is equal to {b}'
-
 def count_letter_in_string(a: str, b: str):
     """
     统计字符串中某个字母的出现次数。
@@ -513,6 +587,28 @@ def count_letter_in_string(a: str, b: str):
     """
     return str(a.count(b))
 
+def search_wikipedia(query: str) -> str:
+    """
+    在维基百科中搜索指定查询的前三个页面摘要。
+    :param query: 要搜索的查询字符串。
+    :return: 包含前三个页面摘要的字符串。
+    """
+    page_titles = wikipedia.search(query)
+    summaries = []
+    for page_title in page_titles[: 3]:  # 取前三个页面标题
+        try:
+            # 使用 wikipedia 模块的 page 函数，获取指定标题的维基百科页面对象。
+            wiki_page = wikipedia.page(title=page_title, auto_suggest=False)
+            # 获取页面摘要
+            summaries.append(f"页面: {page_title}\n摘要: {wiki_page.summary}")
+        except (
+                wikipedia.exceptions.PageError,
+                wikipedia.exceptions.DisambiguationError,
+        ):
+            pass
+    if not summaries:
+        return "维基百科没有搜索到合适的结果"
+    return "\n\n".join(summaries)
 # ... (可能还有其他工具函数)
 ```
 
@@ -552,7 +648,7 @@ from utils import function_to_json
 # 导入定义好的工具函数
 from tools import get_current_datetime, add, compare, count_letter_in_string
 
-SYSREM_PROMPT = """
+SYSTEM_PROMPT = """
 你是一个叫不要葱姜蒜的人工智能助手。你的输出应该与用户的语言保持一致。
 当用户的问题需要调用工具时，你可以从提供的工具列表中调用适当的工具函数。
 """
@@ -633,7 +729,7 @@ Agent 的工作流程如下：
 如图7.9所示，Agent 调用工具流程：
 
 <div align='center'>
-    <img src="../images/7-images/7-3-Tiny_Agent.jpg" alt="alt text" width="80%">
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-3-Tiny_Agent.jpg" alt="alt text" width="80%">
     <p>图7.9 Agent 工作流程</p>
 </div>
 
@@ -667,8 +763,6 @@ if __name__ == "__main__":
         print("\033[92mAssistant: \033[0m", response)  # 绿色显示AI助手回答
 ```
 
-运行 `python demo.py` 后，你可以开始提问。如果问题需要调用工具，Agent 会自动处理。
-
 **示例交互:**
 
 ```bash
@@ -691,6 +785,14 @@ Assistant:  当前的时间是2025年4月26日17:01:33。不过，我注意到
 User: exit
 ```
 
+另外，我们也准备了一份可以展示的 Streamlit 应用，可以运行在本地，展示 Agent 的功能。`streamlit run web_demo.py` 来运行，以下为 Agent 运行效果。
+
+<div align='center'>
+    <img src="https://raw.githubusercontent.com/datawhalechina/happy-llm/main/docs/images/7-images/7-3-streamlit-demo.png" alt="alt text" width="80%">
+    <p>图 7.10 Streamlit Demo</p>
+</div>
+
+
 **参考文献**
 
 [1] Hugging Face. (2023). *Open LLM Leaderboard: 开源大语言模型基准测试平台*. https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard  

docs/前言.md

@@ -2,7 +2,7 @@
 
 2022年底，ChatGPT 的横空出世改变了人们对人工智能的认知，也给自然语言处理（Natural Language Process，NLP）领域带来了阶段性的变革，以 GPT 系列模型为代表的大语言模型（Large Language Model，LLM）成为 NLP 乃至人工智能领域的研究主流。自 2023年至今，LLM 始终是人工智能领域的核心话题，引发了一轮又一轮的科技浪潮。
 
-LLM 其实是 NLP 领域经典研究方法预训练语言模型（Pretrain Langguage Model，PLM）的一种衍生成果。NLP 领域聚焦于人类书写的自然语言文本的处理、理解和生成，从诞生至今经历了符号主义阶段、统计学习阶段、深度学习阶段、预训练模型阶段到而今大模型阶段的多次变革。以 GPT、BERT 为代表的 PLM 是上一阶段 NLP 领域的核心研究成果，以注意力机制为模型架构，通过预训练-微调的阶段思想通过在海量无监督文本上进行自监督预训练，实现了强大的自然语言理解能力。但是，传统的 PLM 仍然依赖于一定量有监督数据进行下游任务微调，且在自然语言生成任务上性能还不尽如人意，NLP 系统的性能距离人们所期待的通用人工智能还有不小的差距。
+LLM 其实是 NLP 领域经典研究方法预训练语言模型（Pretrain Language Model，PLM）的一种衍生成果。NLP 领域聚焦于人类书写的自然语言文本的处理、理解和生成，从诞生至今经历了符号主义阶段、统计学习阶段、深度学习阶段、预训练模型阶段到而今大模型阶段的多次变革。以 GPT、BERT 为代表的 PLM 是上一阶段 NLP 领域的核心研究成果，以注意力机制为模型架构，通过预训练-微调的阶段思想通过在海量无监督文本上进行自监督预训练，实现了强大的自然语言理解能力。但是，传统的 PLM 仍然依赖于一定量有监督数据进行下游任务微调，且在自然语言生成任务上性能还不尽如人意，NLP 系统的性能距离人们所期待的通用人工智能还有不小的差距。
 
 LLM 是在 PLM 的基础上，通过大量扩大模型参数、预训练数据规模，并引入指令微调、人类反馈强化学习等手段实现的突破性成果。相较于传统 PLM，LLM 具备涌现能力，具有强大的上下文学习能力、指令理解能力和文本生成能力。在大模型阶段，NLP 研究者可以一定程度抛弃大量的监督数据标注工作，通过提供少量监督示例，LLM 即能在指定下游任务上达到媲美大规模微调 PLM 的性能。同时，强大的指令理解能力与文本生成能力使 LLM 能够直接、高效、准确地响应用户指令，从而真正向通用人工智能的目标逼近。