酒中仙

RAG 中的数据准备

Tue, 31 Mar 2026 20:40:25 -0800

RAG 中的数据准备

第一节数据加载

虽然本节内容在实际应用中非常重要，但是由于各种文档加载器的迭代更新，以及各类 AI 应用的不同需求，具体选择需要根据实际情况。本节仅作简单引入，但请务必重视数据加载环节，“垃圾进，垃圾出 (Garbage In, Garbage Out)” ——高质量输入是高质量输出的前提。

一、文档加载器

1.1 主要功能

RAG 系统中，数据加载是整个流水线的第一步，也是不可或缺的一步。文档加载器负责将各种格式的非结构化文档（如PDF、Word、Markdown、HTML等）转换为程序可以处理的结构化数据。数据加载的质量会直接影响后续的索引构建、检索效果和最终的生成质量。

文档加载器在 RAG 的数据管道中一般需要完成三个核心任务，一是解析不同格式的原始文档，将 PDF、Word、Markdown 等内容提取为可处理的纯文本，二是在解析过程中同时抽取文档来源、页码、作者等关键信息作为元数据，三是把文本和元数据整理成统一的数据结构，方便后续进行切分、向量化和入库，其整体流程与传统数据工程中的抽取、转换、加载相似，目标都是把杂乱的原始文档清洗并对齐为适合检索和建模的标准化语料。

1.2 当前主流RAG文档加载器

表 2-1 当前主流 RAG 文档加载器

工具名称	特点	适用场景	性能表现
PyMuPDF4LLM	PDF→Markdown转换，OCR+表格识别	科研文献、技术手册	开源免费，GPU加速
TextLoader	基础文本文件加载	纯文本处理	轻量高效
DirectoryLoader	批量目录文件处理	混合格式文档库	支持多格式扩展
Unstructured	多格式文档解析	PDF、Word、HTML等	统一接口，智能解析
FireCrawlLoader	网页内容抓取	在线文档、新闻	实时内容获取
LlamaParse	深度PDF结构解析	法律合同、学术论文	解析精度高，商业API
Docling	模块化企业级解析	企业合同、报告	IBM生态兼容
Marker	PDF→Markdown，GPU加速	科研文献、书籍	专注PDF转换
MinerU	多模态集成解析	学术文献、财务报表	集成LayoutLMv3+YOLOv8

第二节文本分块

一、理解文本分块

文本分块（Text Chunking）是构建 RAG 流程的关键步骤。它的原理是将加载后的长篇文档，切分成更小、更易于处理的单元。这些被切分出的文本块，是后续向量检索和模型处理的基本单位。

二、文本分块重要性

2.1 满足模型上下文限制

将文本分块的首要原因，是为了适应 RAG 系统中两个核心组件的硬性限制：

嵌入模型 (Embedding Model): 负责将文本块转换为向量。这类模型有严格的输入长度上限。例如，许多常用的嵌入模型（如 bge-base-zh-v1.5）的上下文窗口为512个token。任何超出此限制的文本块在输入时都会被截断，导致信息丢失，生成的向量也无法完整代表原文的语义。因此，文本块的大小必须小于等于嵌入模型的上下文窗口。
大语言模型 (LLM): 负责根据检索到的上下文生成答案。LLM同样有上下文窗口限制（尽管通常比嵌入模型大得多，从几千到上百万token不等）。检索到的所有文本块，连同用户问题和提示词，都必须能被放入这个窗口中。如果单个块过大，可能会导致只能容纳少数几个相关的块，限制了LLM回答问题时可参考的信息广度。

因此，分块是确保文本能够被两个模型完整、有效处理的基础。

2.2 为何“块”不是越大越好

假设嵌入模型最多能处理 8192 个 token，是否应该把块切得尽可能大（比如8000个token）呢？答案是否定的。块的大小并非越大越好，过大的块会严重影响RAG系统的性能。

2.2.1 嵌入过程中的信息损失

大多数嵌入模型都基于 Transformer 编码器。其工作流程大致如下：

分词 (Tokenization): 将输入的文本块分解成一个个 token。
向量化 (Vectorization): Transformer 为每个 token 生成一个高维向量表示。
池化 (Pooling): 通过某种方法（如取 [CLS] 位的向量、对所有token向量求平均 mean pooling 等），将所有 token 的向量压缩成一个单一的向量，这个向量代表了整个文本块的语义。

[CLS] 是BERT等Transformer模型在输入文本开头添加的特殊标记，它通过自注意力机制动态聚合整个序列的上下文信息，其最终向量被训练用作代表全局语义的嵌入。

在这个压缩过程中，信息损失是不可避免的。一个768维的向量需要概括整个文本块的所有信息。文本块越长，包含的语义点越多，这个单一向量所承载的信息就越稀释，导致其表示变得笼统，关键细节被模糊化，从而降低了检索的精度。

2.2.2 生成过程的“大海捞针” (Lost in the Middle)

即使将检索到的多个大块文本都塞进LLM的长上下文窗口中，也会出现关键信息被“淹没”在大量无关内容里的问题。有研究表明 ¹，当LLM处理非常长的、充满大量信息的上下文时，它倾向于更好地记住开头和结尾的信息，而忽略中间部分的内容。

如果提供给LLM的上下文块又大又杂，充满了与问题无关的噪音，模型就很难从中提取出最关键的信息来形成答案，从而导致回答质量下降或产生幻觉。

2.2.3 主题稀释导致检索失败

一个好的文本块应该聚焦于一个明确、单一的主题。如果一个块包含太多不相关的主题，它的语义就会被稀释，导致在检索时无法被精确匹配。

举个栗子🌰：

假设有一个关于《王者荣耀》英雄鲁班七号的攻略文档。

糟糕的分块策略：将“技能介绍”、“推荐出装”和“背景故事”这三个完全不同主题的内容，全部放在一个巨大的文本块里。
- 当玩家查询“鲁班七号怎么出装？”时，这个大块虽然包含了出装信息，但由于被技能说明和英雄故事等无关主题严重稀释，其整体的检索相关性得分可能会很低，导致无法被召回。
优秀的分块策略：将“技能”、“出装”和“故事”分别切分为三个独立的、主题聚焦的块。
- 当玩家再次查询时，“推荐出装”这个块会因为与查询高度相关而获得极高的分数，从而被精准地检索出来。

通过合理分块，可以有效提升检索的信噪比，确保了后续生成环节能得到最优质、最相关的上下文。

三、基础分块策略

LangChain 提供了丰富且易于使用的文本分割器（Text Splitters），下面将介绍几种最核心的策略。

3.1 固定大小分块

这是最简单直接的分块方法。根据LangChain源码，这种方法的工作原理分为两个主要阶段：

（1）按段落分割：CharacterTextSplitter 采用默认分隔符 "\n\n"，使用正则表达式将文本按段落进行分割，通过 _split_text_with_regex 函数处理。

（2）智能合并：调用继承自父类的 _merge_splits 方法，将分割后的段落依次合并。该方法会监控累积长度，当超过 chunk_size 时形成新块，并通过重叠机制（chunk_overlap）保持上下文连续性，同时在必要时发出超长块的警告。

需要注意，CharacterTextSplitter 实际实现的并非严格的固定大小分块。根据 _merge_splits 源码逻辑，这种方法会：

优先保持段落完整性：只有当添加新段落会导致总长度超过 chunk_size 时，才会结束当前块
处理超长段落：如果单个段落超过 chunk_size，系统会发出警告但仍将其作为完整块保留
应用重叠机制：通过 chunk_overlap 参数在块之间保持内容重叠，确保上下文连续性

所以，LangChain 的实现更准确地应该称为"段落感知的自适应分块"，块大小会根据段落边界动态调整。

下面的代码展示了如何配置一个固定大小分块器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


from langchain_text_splitters import CharacterTextSplitter
from langchain_community.document_loaders import TextLoader

# 1. 文档加载
loader = TextLoader("./txt/蜂医.txt", encoding="utf-8")
docs = loader.load()

# 2. 初始化固定大小分块器
text_splitter = CharacterTextSplitter(
 chunk_size=200, # 每个块的大小
 chunk_overlap=10 # 块之间的重叠大小
)

# 3. 执行分块
chunks = text_splitter.split_documents(docs)

# 4. 打印结果
print(f"文本被切分为 {len(chunks)} 个块。\n")
print("--- 前5个块内容示例 ---")
for i, chunk in enumerate(chunks[:5]):
 print("=" * 60)
 # chunk 是一个 Document 对象，需要访问它的 .page_content 属性来获取文本
 print(f'块 {i+1} (长度: {len(chunk.page_content)}): "{chunk.page_content}"')

这种方法的主要优势在于实现简单、处理速度快且计算开销小。劣势在于可能会在语义边界处切断文本，影响内容的完整性和连贯性。实际的固定大小分块实现（如LangChain的 CharacterTextSplitter）通常会结合分隔符来减少这种问题，在段落边界处优先切分，只有在必要时才会强制按大小切断。因此，这种方法在日志分析、数据预处理等场景中仍有其应用价值。

3.2 递归字符分块

在前面的章节中，已经尝试了使用 RecursiveCharacterTextSplitter 的默认配置来处理文档分块。现在让我们深入了解 RecursiveCharacterTextSplitter 的实现。这种分块器通过分隔符层级递归处理，相对与固定大小分块，改善了超长文本的处理效果。

算法流程：（1）寻找有效分隔符: 从分隔符列表中从前到后遍历，找到第一个在当前文本中存在的分隔符。如果都不存在，使用最后一个分隔符（通常是空字符串 ""）。

（2）切分与分类处理: 使用选定的分隔符切分文本，然后遍历所有片段：

如果片段不超过块大小: 暂存到 _good_splits 中，准备合并
如果片段超过块大小:
- 首先，将暂存的合格片段通过 _merge_splits 合并成块
- 然后，检查是否还有剩余分隔符：
  - 有剩余分隔符: 递归调用 _split_text 继续分割
  - 无剩余分隔符: 直接保留为超长块

（3）最终处理: 将剩余的暂存片段合并成最后的块

实现细节：

批处理机制: 先收集所有合格片段（_good_splits），遇到超长片段时才触发合并操作。
递归终止条件: 关键在于 if not new_separators 判断。当分隔符用尽时（new_separators 为空），停止递归，直接保留超长片段。确保算法不会无限递归。

与固定大小分块的关键差异：

固定大小分块遇到超长段落时只能发出警告并保留。
递归分块会继续使用更细粒度的分隔符（句子→单词→字符）直到满足大小要求。

具体示例如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

loader = TextLoader("../../data/C2/txt/蜂医.txt")
docs = loader.load()

text_splitter = RecursiveCharacterTextSplitter(
 separators=["\n\n", "\n", "。", "，", " ", ""], # 分隔符优先级
 chunk_size=200,
 chunk_overlap=10,
)

chunks = text_splitter.split_text(docs)

分隔符配置：

默认分隔符：["\n\n", "\n", " ", ""]

多语言支持：对于无词边界语言（中文、日文、泰文），可添加：

1
2
3
4
5
6
7


separators=[
 "\n\n", "\n", " ",
 ".", ",", "\u200b", # 零宽空格(泰文、日文)
 "\uff0c", "\u3001", # 全角逗号、表意逗号
 "\uff0e", "\u3002", # 全角句号、表意句号
 ""
]

编程语言特化支持：

RecursiveCharacterTextSplitter 能够针对特定的编程语言（如Python, Java等）使用预设的、更符合代码结构的分隔符。它们通常包含语言的顶级语法结构（如类、函数定义）和次级结构（如控制流语句），以实现更符合代码逻辑的分割。

1
2
3
4
5
6


# 针对代码文档的优化分隔符
splitter = RecursiveCharacterTextSplitter.from_language(
 language=Language.PYTHON, # 支持Python、Java、C++等
 chunk_size=500,
 chunk_overlap=50
)

递归字符分块的原理是采用一组有层次结构的分隔符（如段落、句子、单词）进行递归分割，旨在有效平衡语义完整性与块大小控制。在 RecursiveCharacterTextSplitter 的实现中，该分块器首先尝试使用最高优先级的分隔符（如段落标记）来切分文本。如果切分后的块仍然过大，会继续对这个大块应用下一优先级分隔符（如句号），如此循环往复，直到块满足大小限制。这种分层处理的机制，能够在尽可能保持高级语义结构完整性的同时，有效控制块大小。

完整代码如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

loader = TextLoader("./txt/蜂医.txt", encoding="utf-8")
docs = loader.load()

old_separators=["\n\n", "\n", "。", "，", " ", ""], # 按顺序尝试分割

new_separators=[
 "\n\n", "\n", " ",
 ".", ",", "\u200b", # 零宽空格(泰文、日文)
 "\uff0c", "\u3001", # 全角逗号、表意逗号
 "\uff0e", "\u3002", # 全角句号、表意句号
 ""
]


text_splitter = RecursiveCharacterTextSplitter(
 # 针对中英文混合文本，定义一个更全面的分隔符列表
 separators=new_separators,
 chunk_size=200,
 chunk_overlap=10
)

chunks = text_splitter.split_documents(docs)

print(f"文本被切分为 {len(chunks)} 个块。\n")
print("--- 前5个块内容示例 ---")
for i, chunk in enumerate(chunks[:5]):
 print("=" * 60)
 print(f'块 {i+1} (长度: {len(chunk.page_content)}): "{chunk.page_content}"')

3.3 语义分块

语义分块（Semantic Chunking）是一种更智能的方法，这种方法不依赖于固定的字符数或预设的分隔符，而是尝试根据文本的语义内涵来切分。其核心是：在语义主题发生显著变化的地方进行切分。这使得每个分块都具有高度的内部语义一致性。LangChain 提供了 langchain_experimental.text_splitter.SemanticChunker 来实现这一功能。

实现原理

SemanticChunker 的工作流程可以概括为以下几个步骤：

（1）句子分割 (Sentence Splitting)：首先，使用标准的句子分割规则（例如，基于句号、问号、感叹号）将输入文本拆分成一个句子列表。

（2）上下文感知嵌入 (Context-Aware Embedding)：这是 SemanticChunker 的一个关键设计。该分块器不是对每个句子独立进行嵌入，而是通过 buffer_size 参数（默认为1）来捕捉上下文信息。对于列表中的每一个句子，这种方法会将其与前后各 buffer_size 个句子组合起来，然后对这个临时的、更长的组合文本进行嵌入。这样，每个句子最终得到的嵌入向量就融入了其上下文的语义。

（3）计算语义距离 (Distance Calculation)：计算每对相邻句子的嵌入向量之间的余弦距离。这个距离值量化了两个句子之间的语义差异——距离越大，表示语义关联越弱，跳跃越明显。

（4）识别断点 (Breakpoint Identification)：SemanticChunker 会分析所有计算出的距离值，并根据一个统计方法（默认为 percentile）来确定一个动态阈值。例如，它可能会将所有距离中第95百分位的值作为切分阈值。所有距离大于此阈值的点，都被识别为语义上的“断点”。

（5）合并成块 (Merging into Chunks)：最后，根据识别出的所有断点位置，将原始的句子序列进行切分，并将每个切分后的部分内的所有句子合并起来，形成一个最终的、语义连贯的文本块。

断点识别方法 (breakpoint_threshold_type)

如何定义“显著的语义跳跃”是语义分块的关键。SemanticChunker 提供了几种基于统计的方法来识别断点：

percentile (百分位法 - 默认方法):
- 逻辑: 计算所有相邻句子的语义差异值，并将这些差异值进行排序。当一个差异值超过某个百分位阈值时，就认为该差异值是一个断点。
- 参数: breakpoint_threshold_amount (默认为 95)，表示使用第95个百分位作为阈值。这意味着，只有最显著的5%的语义差异点会被选为切分点。
standard_deviation (标准差法):
- 逻辑: 计算所有差异值的平均值和标准差。当一个差异值超过“平均值 + N * 标准差”时，被视为异常高的跳跃，即断点。
- 参数: breakpoint_threshold_amount (默认为 3)，表示使用3倍标准差作为阈值。
interquartile (四分位距法):
- 逻辑: 使用统计学中的四分位距（IQR）来识别异常值。当一个差异值超过 Q3 + N * IQR 时，被视为断点。
- 参数: breakpoint_threshold_amount (默认为 1.5)，表示使用1.5倍的IQR。
gradient (梯度法):
- 逻辑: 这是一种更复杂的方法。它首先计算差异值的变化率（梯度），然后对梯度应用百分位法。对于那些句子间语义联系紧密、差异值普遍较低的文本（如法律、医疗文档）特别有效，因为这种方法能更好地捕捉到语义变化的“拐点”。
- 参数: breakpoint_threshold_amount (默认为 95)。

具体示例如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


from langchain_experimental.text_splitter import SemanticChunker
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.document_loaders import TextLoader

embeddings = HuggingFaceEmbeddings(
 model_name="BAAI/bge-small-zh-v1.5",
 model_kwargs={'device': 'cpu'},
 encode_kwargs={'normalize_embeddings': True}
)

# 初始化 SemanticChunker
text_splitter = SemanticChunker(
 embeddings,
 breakpoint_threshold_type="percentile" # 也可以是 "standard_deviation", "interquartile", "gradient"
)

loader = TextLoader("./txt/蜂医.txt", encoding="utf-8")
documents = loader.load()

docs = text_splitter.split_documents(documents)

print(f"文本被切分为 {len(docs)} 个块。\n")
print("--- 前2个块内容示例 ---")
for i, chunk in enumerate(docs[:2]):
 print("=" * 60)
 print(f'块 {i+1} (长度: {len(chunk.page_content)}):\n"{chunk.page_content}"')

3.4 基于文档结构的分块

对于具有明确结构标记的文档格式（如Markdown、HTML、LaTex），可以利用这些标记来实现更智能、更符合逻辑的分割。

以 Markdown 结构分块为例

针对结构清晰的 Markdown 文档，利用其标题层级进行分块是一种高效且保留了丰富语义的方法。LangChain 提供了 MarkdownHeaderTextSplitter 来处理。

实现原理: 该分块器的主要逻辑是“先按标题分组，再按需细分”。
1. 定义分割规则: 用户首先需要提供一个标题层级的映射关系，例如 [ ("#", "Header 1"), ("##", "Header 2") ]，告诉分块器 # 是一级标题，## 是二级标题。
2. 内容聚合: 分块器会遍历整个文档，将每个标题下的所有内容（直到下一个同级或更高级别的标题出现前）聚合在一起。每个聚合后的内容块都会被赋予一个包含其完整标题路径的元数据。
元数据注入的优势: 这是此方法的主要特点。例如，对于一篇关于机器学习的文章，某个段落可能位于“第三章：模型评估”下的“3.2节：评估指标”中。经过分割后，这个段落形成的文本块，其元数据就会是 {"Header 1": "第三章：模型评估", "Header 2": "3.2节：评估指标"}。这种元数据为每个块提供了精确的“地址”，极大地增强了上下文的准确性，让大模型能更好地理解信息片段的来源和背景。
局限性与组合使用: 单纯按标题分割可能会导致一个问题：某个章节下的内容可能非常长，远超模型能处理的上下文窗口。为了解决这个问题，MarkdownHeaderTextSplitter 可以与其它分块器（如 RecursiveCharacterTextSplitter）组合使用。具体流程是：
- 第一步，使用 MarkdownHeaderTextSplitter 将文档按标题分割成若干个大的、带有元数据的逻辑块。
- 第二步，对这些逻辑块再应用 RecursiveCharacterTextSplitter，将其进一步切分为符合 chunk_size 要求的小块。由于这个过程是在第一步之后进行的，所有最终生成的小块都会继承来自第一步的标题元数据。
RAG应用优势: 这种两阶段的分块方法，既保留了文档的宏观逻辑结构（通过元数据），又确保了每个块的大小适中，是处理结构化文档进行RAG的理想方案。

四、其他开源框架中的分块策略

4.1 Unstructured：基于文档元素的智能分块

Unstructured是一个强大的文档处理工具，同样提供了实用的分块功能。

（1）分区 (Partitioning): 这是一个重要功能，负责将原始文档（如PDF、HTML）解析成一系列结构化的“元素”（Elements）。每个元素都带有语义标签，如 Title (标题)、NarrativeText (叙述文本)、ListItem (列表项) 等。这个过程本身就完成了对文档的深度理解和结构化。

（2）分块 (Chunking): 该功能建立在分区的结果之上。分块功能不是对纯文本进行操作，而是将分区产生的“元素”列表作为输入，进行智能组合。Unstructured 提供了两种主要的分块方法：

basic: 这是默认方法。这种方法会连续地组合文档元素（如段落、列表项），直到达到 max_characters 上限，尽可能地填满每个块。如果单个元素超过上限，则会对其进行文本分割。
by_title: 该方法在 basic 方法的基础上，增加了对“章节”的感知。该方法将 Title 元素视为一个新章节的开始，并强制在此处开始一个新的块，确保同一个块内不会包含来自不同章节的内容。这在处理报告、书籍等结构化文档时非常有用，效果类似于 LangChain 的 MarkdownHeaderTextSplitter，但适用范围更广。

Unstructured 允许将分块作为分区的一个参数在单次调用中完成，也支持在分区之后作为一个独立的步骤来执行分块。这种“先理解、后分割”的策略，使得 Unstructured 能在最大程度上保留文档的原始语义结构，特别是在处理版式复杂的文档时，优势尤为明显。

4.2 LlamaIndex：面向节点的解析与转换

LlamaIndex 将数据处理流程抽象为对“节点（Node）”的操作。文档被加载后，首先会被解析成一系列的“节点”，分块只是节点转换（Transformation）中的一环。

LlamaIndex 的分块体系有以下特点：

（1）丰富的节点解析器 (Node Parser): LlamaIndex 提供了大量针对特定数据格式和方法的节点解析器，可以大致分为几类：

结构感知型: 如 MarkdownNodeParser, JSONNodeParser, CodeSplitter 等，能理解并根据源文件的结构（如Markdown标题、代码函数）进行切分。
语义感知型:
- SemanticSplitterNodeParser: 与 LangChain 的 SemanticChunker 类似，这种解析器使用嵌入模型来检测句子之间的语义“断点”，在语义连续性明显减弱的地方切开，从而让每个 chunk 内部尽量连贯。
- SentenceWindowNodeParser: 这是一种巧妙的方法。该方法将文档切分成单个的句子，但在每个句子节点（Node）的元数据中，会存储其前后相邻的N个句子（即“窗口”）。这使得在检索时，可以先用单个句子的嵌入进行精确匹配，然后将包含上下文“窗口”的完整文本送给LLM，极大地提升了上下文的质量。
常规型: 如 TokenTextSplitter, SentenceSplitter 等，提供基于Token数量或句子边界的常规切分方法。

（2）灵活的转换流水线: 用户可以构建一个灵活的流水线，例如先用 MarkdownNodeParser 按章节切分文档，再对每个章节节点应用 SentenceSplitter 进行更细粒度的句子级切分。每个节点都携带丰富的元数据，记录着其来源和上下文关系。

（3）良好的互操作性: LlamaIndex 提供了 LangchainNodeParser，可以方便地将任何 LangChain 的 TextSplitter 封装成 LlamaIndex 的节点解析器，无缝集成到其处理流程中。

4.3 ChunkViz：简易的可视化分块工具

在本文开头部分展示的分块图就是通过 ChunkViz 生成的。可以将你的文档、分块配置作为输入，用不同的颜色块展示每个 chunk 的边界和重叠部分，方便快速理解分块逻辑。

参考文献

Nelson F. Liu, et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. ↩︎

生活片段分享平台

Mon, 30 Mar 2026 18:40:25 -0800

生活片段分享平台

前言

去年夏天，我搭建了一个 Life-Moments 的平台用于分享自己的生活，但是因为数据存储的问题，这个工具没能成为我日常工具的一部分。

类似微信朋友圈的工具有很多，比如Moments、Memos 和 Ech0。

特性	Memos	Moments	Ech0
PWA 适配	✅ 支持	❌ 不支持	✅ 支持
标签系统	✅ 完善	✅ 完善	✅ 支持
S3 图床	✅ 支持	✅ 支持	✅ 支持
Meting 音乐	❌ 不支持	✅ 支持	✅ 支持
视频分享	✅ 支持	✅ 支持	✅ 支持
设计风格	功能导向，略显臃肿	功能全面，类似后台	简约美观，轻量
开发活跃度	非常活跃，API 易变	相对稳定	活跃，快速迭代
个人评价	功能强大，但更新太折腾，生态不稳定。	功能完美，但没 PWA 对我是减分项	界面戳我，功能追上来了，PWA 是加分项，目前的最爱

Ech0：自托管个人微博客

自托管个人微博客：你的时间线可以被分享、讨论，同时数据完全由你掌控。

GitHub——Ech0 – An open-source, self-hosted lightweight publishing platform for personal idea sharing.

Ech0 helps individuals publish thoughts, notes, and links with full data ownership, ultra-light footprint, and a focused writing experience.

Ech0 示例可以参考： https://mm.liushen.fun/

像 Memos 这样的工具非常适合快速记录想法。Ech0 更关注“记录之后”的阶段：把内容发布到个人时间线，让更多人可以持续关注和互动。你可以在自己的服务器上托管内容，保留完整控制权，同时通过可选评论与分享保持轻连接，而不是变成复杂社交平台。它保持轻量、易部署、完全开源。

适合你，如果你想：

搭建一个自己的公开或半公开动态站
用统一界面发布短文、链接与媒体卡片
兼顾数据主权，同时保留 RSS 与评论等能力
让个人内容具备轻社交连接能力，而不需要重型社交产品

不太适合你，如果你需要：

双链知识库式的笔记工作流（例如 Obsidian 风格）
团队优先的协作文档平台（例如 Notion 风格）
纯私密备忘且不关注发布/时间线场景

Memos：私有、轻量、开源、自托管的备忘录

Memos 是一种隐私优先的轻量级笔记解决方案，可让您轻松捕捉和分享您的想法。它开源且免费支持自部署。生态上支持第三方的手机端APP、浏览器插件等方式记录笔记，优势是生态够强，缺点是开发者每次更新大版本后之前的API可能就直接废弃了。

这是一个采用 React+Tailwind+TypeScript+Go 开发的备忘录中心，相当于极简的微博。支持私有/公开备忘录、标签、互动式日历等功能，以及 Docker 部署。

Memos 的官方文档： https://www.usememos.com/docs

开源地址： https://github.com/usememos/memos

特色介绍

隐私优先🏠：掌控你的数据。所有运行时数据都安全地存储在本地数据库中。
快速创建✍️：将内容保存为纯文本以便快速访问，并支持 Markdown 以实现快速格式化和轻松共享。
轻量但强大🤲：使用 Go、React.js 和紧凑的架构构建，我们的应用程序在轻量级的包中提供强大的性能。
可定制🧩：轻松自定义服务器名称、图标、描述、系统风格和执行脚本，使其独一无二。
开源🦦：Memos 拥抱开源的未来，所有代码在 GitHub 上可用，以实现透明度和协作。
免费使用💸：完全免费享受所有功能，任何内容都不会收取任何费用。

功能

支持Markdown语法
支持S3存储
支持多用户
支持评论
支持MYsql或者SQLite作为数据库
支持API

Memos 相关工具

Moe Memos - 适用于 iOS 和 Android 的第三方客户端
lmm214/memos-bber - Chrome 扩展
Rabithua/memos_wmp - 微信小程序
qazxcdswe123/telegramMemoBot - 电报机器人
eallion/memos.top - 使用 Memos API 呈现的静态页面
eindex/logseq-memos-sync - Logseq 插件
JakeLaoyu/memos-import-from-flomo - 导入数据。来自flomo、微信读书的支持
发送到备忘录- iOS 的快捷方式
备忘录 Raycast Extension - Raycast 扩展
Memos Desktop - 适用于 MacOS 和 Windows 的第三方客户端
MemosGallery - 使用 Memos API 呈现的静态图库

Moments - 极简朋友圈

moments 是一个极简设计的朋友圈社交平台，旨在为用户提供一个简洁而高效的分享空间。它允许用户轻松记录和分享生活中的点滴时刻、创意作品以及其他任何想要记录的内容。通过其直观的界面和一系列实用功能，moments 促进了用户之间的交流与互动。

GitHub——极简朋友圈

作者的 Demo：https://m.mblog.club/

功能说明

用户系统：

默认管理员：admin/a123456，登录后可在后台修改密码
多用户模式：可以在后台设置是否允许用户注册

Memo：

支持使用 Markdown 语法编写
支持修改发布时间，若发布时间晚于当前时间，则对游客不可见
支持添加标签，方便分类查找
支持上传图片、视频
支持引用外部音乐、外部视频、外部链接
支持引用豆瓣读书、豆瓣电影
支持点赞、评论，可在后台开启/关闭评论功能

文件上传：

上传到服务器时：

支持上传到服务器的 $UPLOAD_DIR 目录下
上传文件时，会先通过 SHA256 检查文件是否被上传过，若上传过则可以“秒传”
上传图片时，会自动创建图片的缩略图，在浏览 Memo 时默认加载缩略图
上传文件时，会和 Memo 产生关联，可以在设置中清理无用的文件，无用的文件将会被整理到 $UPLOAD_DIR/removed 目录下

上传到 S3 时：

支持上传到兼容 S3 的存储服务
开启 S3 时，可以设置图片压缩后缀，在浏览 Memo 时，会默认请求带后缀的图片加载缩略图

以下功能没有详细介绍，请自行探索：

友情链接
邮件通知
RSS 订阅
暗黑模式
数据库自动备份，当检测到启动的版本发生变化时，自动备份数据库文件到 $DB 目录下

项目部署

部署平台推荐 ClawCloud 和 Render 。

Render 是一家来自旧金山的云平台公司，目标是打造开发者友好的全托管部署平台，支持 Web 服务、静态站点、后端 API、数据库、Cron Job 等。用户可以使用 Dockerfile 部署自定义服务，或直接部署 Git 仓库。

官网：https://render.com
免费层：有免费 Web 服务（自动休眠）、PostgreSQL 数据库等

Clawcloud 是一个新兴的云平台，主打“简洁”、“极致性价比”、“对个人开发者友好”。在 2024 年底至 2025 年间快速崛起，因其不强制休眠的免费容器服务和极低的延迟部署时间受到好评。

官网：https://run.claw.cloud/
免费层：每日最多运行 12 小时的容器服务，月流量限制更宽松

两者对比：

对比项	Render 免费版	Clawcloud 免费版
运行时间限制	自动休眠（15 分钟无请求休眠，冷启动 30s 左右）	每天最多运行 12 小时（可配置时段），不强制休眠
支持 Docker	✅ 完全支持，需上传 Dockerfile	✅ 原生支持，直接上传镜像或 Dockerfile
自定义域名与 HTTPS	✅ 支持自动 HTTPS	✅ 支持自动 HTTPS，支持裸域
免费数据库	✅ PostgreSQL（256MB）	❌ 目前不提供数据库服务
月流量限制	~750 小时/月 + 100GB 出站流量	12 小时 * 30 天 + 100GB 出站流量（约等同）
并发容器数量	单服务 + 限资源（512MB RAM）	单实例 + 限资源（512MB RAM）

小结：

Clawcloud 更适合“轻量、全天候运行”的项目，例如个人博客、Webhook 服务、定时任务
Render 更适合“对数据库有需求”的项目，例如全栈应用、API 后端等
两者都限制资源，但对于轻量应用已足够使用

部署教程可以参考如下链接：

使用ClawCloud免费部署memos服务

参考资料

从Moments迁移到Ech0

使用ClawCloud免费部署memos服务

自建 Memos 服务：碎片化笔记 + 博客说说栏，一栈双用

利用 Claw Cloud Run 免费应用部署前端网页

Render vs Clawcloud：免费的 Docker 应用部署平台推荐（2025）

RAG 简介及其简单实现

Sat, 28 Mar 2026 20:40:25 -0800

RAG 简介及其简单实现

一、什么是 RAG？

1.1 核心定义

从本质上讲，RAG（Retrieval-Augmented Generation）是一种旨在解决大语言模型（LLM）“知其然不知其所以然”问题的技术范式。它的核心是将模型内部学到的“参数化知识”（模型权重中固化的、模糊的“记忆”），与来自外部知识库的“非参数化知识”（精准、可随时更新的外部数据）相结合。其运作逻辑就是在 LLM 生成文本前，先通过检索机制从外部知识库中动态获取相关信息，并将这些“参考资料”融入生成过程，从而提升输出的准确性和时效性 ¹ ² ³。

💡 一句话总结：RAG 就是让 LLM 学会了“开卷考试”，它既能利用自己学到的知识，也能随时查阅外部资料。

1.2 技术原理

那么，RAG 系统是如何实现“参数化知识”与“非参数化知识”的结合呢？如图 1-1 所示，其架构主要通过两个阶段来完成这一过程：

（1）检索阶段：寻找“非参数化知识”

知识向量化：嵌入模型（Embedding Model） 充当了“连接器”的角色。它将外部知识库编码为向量索引（Index），存入向量数据库。
语义召回：当用户发起查询时，检索模块利用同样的嵌入模型将问题向量化，并通过相似度搜索（Similarity Search），从海量数据中精准锁定与问题最相关的文档片段。

（2）生成阶段：融合两种知识

上下文整合：生成模块接收检索阶段送来的相关文档片段以及用户的原始问题。
指令引导生成：该模块会遵循预设的 Prompt 指令，将上下文与问题有效整合，并引导 LLM（如 DeepSeek）进行可控的、有理有据的文本生成。

图 1-1 RAG 双阶段架构示意图

1.3 技术演进分类

RAG 的技术架构经历了从简单到复杂的演进，如图 1-2 大致可分为三个阶段 ⁴。

图 1-2 RAG 技术演进分类

这三个阶段的具体对比如表 1-1 所示。

	初级 RAG（Naive RAG）	高级 RAG（Advanced RAG）	模块化 RAG（Modular RAG）
流程	离线: `索引` 在线: `检索 → 生成`	离线: `索引` 在线: `...→ 检索前 → ... → 检索后 → ...`	积木式可编排流程
特点	基础线性流程	增加检索前后的优化步骤	模块化、可组合、可动态调整
关键技术	基础向量检索	查询重写（Query Rewrite）结果重排（Rerank）	动态路由（Routing）查询转换（Query Transformation）多路融合（Fusion）
局限性	效果不稳定，难以优化	流程相对固定，优化点有限	系统复杂性高

表 1-1 RAG 技术演进分类对比

“离线”指提前完成的数据预处理工作（如索引构建）；“在线”指用户发起请求后的实时处理流程。

二、为什么要使用 RAG？

2.1 技术选型：RAG vs. 微调

在选择具体的技术路径时，一个重要的考量是成本与效益的平衡。通常，我们应优先选择对模型改动最小、成本最低的方案，所以技术选型路径往往遵循的顺序是提示词工程（Prompt Engineering） -> 检索增强生成 -> 微调（Fine-tuning）。

我们可以从两个维度来理解这些技术的区别。如图 1-3 所示，横轴代表“LLM 优化”，即对模型本身进行多大程度的修改。从左到右，优化的程度越来越深，其中提示工程和 RAG 完全不改变模型权重，而微调则直接修改模型参数。纵轴代表“上下文优化”，是对输入给模型的信息进行多大程度的增强。从下到上，增强的程度越来越高，其中提示工程只是优化提问方式，而 RAG 则通过引入外部知识库，极大地丰富了上下文信息。

图 1-3 选型路径图

基于此，我们的选择路径就清晰了：

先尝试提示工程：通过精心设计提示词来引导模型，适用于任务简单、模型已有相关知识的场景。
再选择 RAG：如果模型缺乏特定或实时知识而无法回答，则使用 RAG，通过外挂知识库为其提供上下文信息。
最后考虑微调：当目标是改变模型“如何做”（行为/风格/格式）而不是“知道什么”（知识）时，微调是最终且最合适的选择。例如，让模型学会严格遵循某种独特的输出格式、模仿特定人物的对话风格，或者将极其复杂的指令“蒸馏”进模型权重中。

RAG 的出现填补了通用模型与专业领域之间的鸿沟，它在解决如表 1-2 所示 LLM 局限时尤其有效：

问题	RAG的解决方案
静态知识局限	实时检索外部知识库，支持动态更新
幻觉（Hallucination）	基于检索内容生成，错误率降低
领域专业性不足	引入领域特定知识库（如医疗/法律）
数据隐私风险	本地化部署知识库，避免敏感数据泄露

表 1-2 RAG 对 LLM 局限的解决方案

2.2 关键优势

（1）准确性与可信度的双重提升

RAG 最核心的价值在于突破了模型预训练知识的限制。它不仅能补充专业领域的知识盲区，还能通过提供具体的参考材料，有效抑制“一本正经胡说八道”的幻觉现象。论文研究还表明，RAG 生成的内容在具体性和多样性上也显著优于纯 LLM。更重要的是，RAG 具备可溯源性——每一条回答都能找到对应的原始文档出处，这种“有据可查”的特性极大提高了内容在法律、医疗等严肃场景下的可信度。

（2）时效性保障

在知识更新方面，RAG 解决了 LLM 固有的知识时滞问题（即模型不知道训练截止日期之后发生的事）。RAG 允许知识库独立于模型进行动态更新——新政策或新数据一旦入库，立刻就能被检索到。这种能力在论文中被称为**“索引热拔插”（Index Hot-swapping）**——就像给机器人换一张存储卡一样，瞬间切换其世界知识库，而无需重新训练模型，实现了知识的实时在线。

（3）显著的综合成本效益

从经济角度看，RAG 是一种高性价比的方案。首先，它避免了高频微调带来的巨额算力成本；其次，由于有了外部知识的强力辅助，我们在处理特定领域问题时，往往可以使用参数量更小的基础模型来达到类似的效果，从而直接降低了推理成本。这种架构也减少了试图将海量知识强行“塞入”模型权重中所需的计算资源消耗。

（4）灵活的模块化可扩展性

RAG 的架构具备极强的包容性，支持多源集成，无论是 PDF、Word 还是网页数据，都能统一构建进知识库中。同时，其模块化设计实现了检索与生成的解耦，这意味着我们可以独立优化检索组件（比如更换更好的 Embedding 模型），而不会影响到生成组件的稳定性，便于系统的长期迭代。

2.3 适用场景风险分级

表 1-3 展示了 RAG 技术在不同风险等级场景中的适用性。

风险等级	案例	RAG适用性
低风险	翻译/语法检查	高可靠性
中风险	合同起草/法律咨询	需结合人工审核
高风险	证据分析/签证决策	需严格质量控制机制

表 1-3 RAG 适用场景风险分级

三、如何上手 RAG？

3.1 基础工具链选择

构建 RAG 系统通常涉及几个关键环节的选型。在开发模式上，我们可以利用 LangChain 或 LlamaIndex 等成熟框架快速集成，也可以选择不依赖框架的原生开发，以获得对系统流程更精细的控制力（在 AI 编程辅助下这并非难事）。而在记忆载体（向量数据库）方面，既有 Milvus、Pinecone 等适合大规模数据的方案，也有 FAISS、Chroma 等轻量级或本地化的选择，需根据具体业务规模灵活决定。后期为了量化效果，还可以引入 RAGAS 或 TruLens 等自动化评估工具。

3.2 四步构建最小可行系统（MVP）

（1）数据准备与清洗：这是系统的地基。我们需要将 PDF、Word 等多源异构数据标准化，并采用合理的分块策略（如按语义段落切分而非固定字符数），避免信息在切割中支离破碎。

（2）索引构建：将切分好的文本通过嵌入模型转化为向量，并存入数据库。可以在此阶段关联元数据（如来源、页码），这对后续的精确引用很有帮助。

（3）检索策略优化：不要依赖单一的向量搜索。可以采用混合检索（向量+关键词）等方式来提升召回率，并引入重排序模型对检索结果进行二次精选，确保 LLM 看到的都是精华。

（4）生成与提示工程：最后，设计一套清晰的 Prompt 模板，引导 LLM 基于检索到的上下文回答用户问题，并明确要求模型“不知道就说不知道”，防止幻觉。

3.3 新手友好方案

如果希望快速验证想法而非深耕代码，可以尝试 FastGPT 或 Dify 这样的可视化知识库平台，它们封装了复杂的 RAG 流程，仅需上传文档即可使用。对于开发者，利用 LangChain4j Easy RAG 或 GitHub 上的 TinyRAG ⁵等开源模板，也是高效的起手方式。

3.4 进阶与挑战

当基础的 RAG 系统搭建完成后，下一步的进阶之路便聚焦于如何评估、诊断并突破其固有的瓶颈。

（1）评估维度与挑战

一套 RAG 系统的好坏，并不能仅凭感觉。业界通常会从几个维度进行量化评估，首先是检索相关性（找到的内容是否包含答案），其次是生成质量，这又可以细分为语义准确性（回答的意思是否正确）和词汇匹配度（专业术语是否使用得当）。

这些评估维度也直接对应了 RAG 当前面临的主要挑战。比如，检索依赖性问题——如果检索系统召回了错误信息，再强的 LLM 也会“一本正经地胡说八道”。此外，对于需要跨多个文档进行综合分析的多跳推理问题，常见的 RAG 架构也普遍感到吃力。

（2）优化方向与架构演进

针对上述挑战，社区探索出了多种优化路径。在性能层面，可以通过索引分层（对高频数据启用缓存）和多模态扩展（支持图像/表格检索）来提升效率和能力边界。而在架构层面，简单的线性流程正在被更复杂的设计模式所取代。例如，系统可以通过分支模式并行处理多路检索，或通过循环模式进行自我修正，这些灵活的架构是通往更智能 RAG 的必由之路。

四、RAG 已死？

随着大模型长上下文窗口能力的提升，社区中开始出现“RAG 已死”的声音。这一论调主要来自两个方面，一是认为长上下文已经能暴力“消化”海量文本，不再需要复杂的检索系统；二是批评 RAG 这个术语本身就过于宽泛，模糊了太多技术细节，反而阻碍了理解与优化。

这些观点忽略了一个技术概念在演进过程中的普遍规律。正如我们可以轻易地为现代复杂的 RAG 系统起一个更精确、更唬人的名字，比如 “大模型知识管理专家系统”（Large Language Model Knowledge Management Expert System，LKE）。因为它早已超出了最初“检索-增强-生成”的简单范畴。但这种“换名游戏”，恰恰说明了“RAG 已死”论的表面化——这无异于在用一个新瓶子去装 RAG 这个不断陈化的老酒。

笔者在此并非要创造一个新词，不过为什么要起 LKE 这个名字？它代表了三个核心要素：

L（Large Language Model）：强调系统的驱动力是大语言模型。

K（Knowledge Management）：寓意着系统就像一个知识管理员，精准地为我们找到（检索）所需要的知识，辅助我们后续利用大模型进行更高阶应用。

E（Expert）：说明系统能像专家一样，通过路由、分析、融合、修正等一系列步骤，最终给出答案（生成）、解决问题。

可以类比 Transformer。今天无论是以 GPT 为代表的 Decoder-only 还是以 BERT 为代表的 Encoder-only，我们都习惯称之为“基于 Transformer 架构”，尽管它们与最初论文中的完整形态差异巨大。但是 Transformer 这个标签抓住了一次技术范式的核心飞跃，并成为了一个技术时代的象征。同理，RAG 的核心在于“将 LLM 的内在参数化知识与外部非参数化知识相结合”。只要这个思想或需求不变，无论我们为其增加多少模块——查询转换、多路召回或者自我修正等等，它本质上依然是在这个框架下的演进。

所以，“RAG 已死”是一个伪命题。相反，RAG 作为一个概念活得很好，它正在像 Transformer 一样，成为一个不断吸收新技术、不断进化的基础架构范式。它的生命力，正在于它的“面目全非”和“包罗万象”。而本教程的目标，就是绘制出这张描绘 RAG 全貌的清晰地图，当我们可以解构它的每一个模块、理解它的每一种可能性时，RAG 也好，LKE 也罢，这些都无关紧要。我们要做的就是通过 RAG 这道经典例题来学习和拓展（将 LLM 的内在参数化知识与外部非参数化知识相结合）这类题型的解题思路。

RAG 技术仍在快速发展中，可以持续关注学术和工业界的最新进展！

五、基于 LangChain 框架的 RAG 实现

在第一节中，我们提到四步构建最小可行系统分别是数据准备、索引构建、检索优化和生成集成。下面将围绕这四个方面来实现一个基于 LangChain 框架的 RAG 应用。

本节完整代码（改造后）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


import os
# hugging face镜像设置，如果国内环境无法使用启用该设置
# os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from dotenv import load_dotenv
from langchain_community.document_loaders import UnstructuredMarkdownLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

load_dotenv()

markdown_path = "./markdown/easy-rl-chapter1.md"

# 加载本地markdown文件
loader = UnstructuredMarkdownLoader(markdown_path)
docs = loader.load()

# 文本分块
text_splitter = RecursiveCharacterTextSplitter()
chunks = text_splitter.split_documents(docs)

# 中文嵌入模型
embeddings = HuggingFaceEmbeddings(
 model_name="BAAI/bge-small-zh-v1.5",
 model_kwargs={'device': 'cpu'},
 encode_kwargs={'normalize_embeddings': True}
)

# 构建向量存储
vectorstore = InMemoryVectorStore(embeddings)
vectorstore.add_documents(chunks)

# 提示词模板
prompt = ChatPromptTemplate.from_template("""请根据下面提供的上下文信息来回答问题。
请确保你的回答完全基于这些上下文。
如果上下文中没有足够的信息来回答问题，请直接告知：“抱歉，我无法根据提供的上下文找到相关信息来回答此问题。”

上下文:
{context}

问题: {question}

回答:"""
 )

# 配置大语言模型
llm = ChatOpenAI(
 model="gpt-4o",
 temperature=0.7,
 max_tokens=4096,
 api_key=os.getenv("LLM_API_KEY"),
 base_url=os.getenv("LLM_BASE_URL"),
)

# 用户查询
question = "文中举了哪些例子？"

# 在向量存储中查询相关文档
retrieved_docs = vectorstore.similarity_search(question, k=3)
docs_content = "\n\n".join(doc.page_content for doc in retrieved_docs)

answer = llm.invoke(prompt.format(question=question, context=docs_content))
print(answer)

3.1 初始化设置

首先进行基础配置，包括导入必要的库、加载环境变量以及下载嵌入模型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import os
# os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from dotenv import load_dotenv
from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_core.prompts import ChatPromptTemplate
from langchain_deepseek import ChatDeepSeek

# 加载环境变量
load_dotenv()

3.2 数据准备

加载原始文档: 先定义Markdown文件的路径，然后使用TextLoader加载该文件作为知识源。

1
2
3


markdown_path = "../../data/C1/markdown/easy-rl-chapter1.md"
loader = TextLoader(markdown_path)
docs = loader.load()

文本分块 (Chunking): 为了便于后续的嵌入和检索，长文档被分割成较小的、可管理的文本块（chunks）。这里采用了递归字符分割策略，使用其默认参数进行分块。当不指定参数初始化 RecursiveCharacterTextSplitter() 时，其默认行为旨在最大程度保留文本的语义结构：
- 默认分隔符与语义保留: 按顺序尝试使用一系列预设的分隔符 ["\n\n" (段落), "\n" (行), " " (空格), "" (字符)] 来递归分割文本。这种策略的目的是尽可能保持段落、句子和单词的完整性，因为它们通常是语义上最相关的文本单元，直到文本块达到目标大小。
- 保留分隔符: 默认情况下 (keep_separator=True)，分隔符本身会被保留在分割后的文本块中。
- 默认块大小与重叠: 使用其基类 TextSplitter 中定义的默认参数 chunk_size=4000（块大小）和 chunk_overlap=200（块重叠）。这些参数确保文本块符合预定的大小限制，并通过重叠来减少上下文信息的丢失。
1 2

text_splitter = RecursiveCharacterTextSplitter() texts = text_splitter.split_documents(docs)

3.3 索引构建

数据准备完成后，接下来构建向量索引：

初始化中文嵌入模型: 使用HuggingFaceEmbeddings加载之前在初始化设置中下载的中文嵌入模型。配置模型在CPU上运行，并启用嵌入归一化 (normalize_embeddings: True)。
1 2 3 4 5

embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-small-zh-v1.5", model_kwargs={'device': 'cpu'}, encode_kwargs={'normalize_embeddings': True} )
构建向量存储: 将分割后的文本块 (texts) 通过初始化好的嵌入模型转换为向量表示，然后使用InMemoryVectorStore将这些向量及其对应的原始文本内容添加进去，从而在内存中构建出一个向量索引。
1 2

vectorstore = InMemoryVectorStore(embeddings) vectorstore.add_documents(texts)
这个过程完成后，便构建了一个可供查询的知识索引。

3.4 查询与检索

索引构建完毕后，便可以针对用户问题进行查询与检索：

定义用户查询: 设置一个具体的用户问题字符串。
1

question = "文中举了哪些例子？"
在向量存储中查询相关文档: 使用向量存储的similarity_search方法，根据用户问题在索引中查找最相关的 k (此处示例中 k=3) 个文本块。
1

retrieved_docs = vectorstore.similarity_search(question, k=3)
准备上下文: 将检索到的多个文本块的页面内容 (doc.page_content) 合并成一个单一的字符串，并使用双换行符 ("\n\n") 分隔各个块，形成最终的上下文信息 (docs_content) 供大语言模型参考。
1

docs_content = "\n\n".join(doc.page_content for doc in retrieved_docs)
使用 "\n\n" (双换行符) 而不是 "\n" (单换行符) 来连接不同的检索文档块，主要是为了在传递给大型语言模型（LLM）时，能够更清晰地在语义上区分这些独立的文本片段。双换行符通常代表段落的结束和新段落的开始，这种格式有助于LLM将每个块视为一个独立的上下文来源，从而更好地理解和利用这些信息来生成回答。

3.5 生成集成

最后一步是将检索到的上下文与用户问题结合，利用大语言模型（LLM）生成答案：

构建提示词模板: 使用ChatPromptTemplate.from_template创建一个结构化的提示模板。此模板指导LLM根据提供的上下文 (context) 回答用户的问题 (question)，并明确指出在信息不足时应如何回应。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


prompt = ChatPromptTemplate.from_template("""请根据下面提供的上下文信息来回答问题。
请确保你的回答完全基于这些上下文。
如果上下文中没有足够的信息来回答问题，请直接告知：“抱歉，我无法根据提供的上下文找到相关信息来回答此问题。”

上下文:
{context}

问题: {question}

回答:"""
 )

配置大语言模型: 初始化ChatDeepSeek客户端，配置所用模型 (deepseek-chat)、生成答案的温度参数 (temperature=0.7)、最大Token数 (max_tokens=2048) 以及API密钥 (从环境变量加载)。
1 2 3 4 5 6

llm = ChatDeepSeek( model="deepseek-chat", temperature=0.7, max_tokens=2048, api_key=os.getenv("DEEPSEEK_API_KEY") )
调用LLM生成答案并输出: 将用户问题 (question) 和先前准备好的上下文 (docs_content) 格式化到提示模板中，然后调用ChatDeepSeek的invoke方法获取生成的答案。
1 2

answer = llm.invoke(prompt.format(question=question, context=docs_content)) print(answer)

老湿老湿，Langchain 很强大但还是太吃操作了，有没有更加简单又好用的框架推荐呢？

有的兄弟，有的！像这样好用的框架还有LlamaIndex😉

六、低代码（基于LlamaIndex）

在 RAG 方面，LlamaIndex 提供了更多封装好的 API 接口，这无疑降低了上手门槛，下面是一个简单实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import os
# os.environ['HF_ENDPOINT']='https://hf-mirror.com'
from dotenv import load_dotenv
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

load_dotenv()

Settings.llm = Ollama(model="deepseek-chat", request_timeout=60.0)
Settings.embed_model = HuggingFaceEmbedding("BAAI/bge-small-zh-v1.5")

docs = SimpleDirectoryReader(input_files=["./markdown/easy-rl-chapter1.md"]).load_data()

index = VectorStoreIndex.from_documents(docs)

query_engine = index.as_query_engine()

print(query_engine.get_prompts())

print(query_engine.query("文中举了哪些例子?"))

参考文献

多模态——从头训练简化版 Omni 模型

Fri, 27 Mar 2026 23:40:25 -0800

多模态——从 0 训练简化版 Omni 模型

经过了这么多章节的漫长学习，想必大家已经对大模型技术的完整演进脉络有了相对全面的认知。本节我们来把此前所学的知识进行融会贯通，在单张消费级显卡上从 0 开始，使用 PyTorch 实现一个简版的 Omni 模型。我们的目标是构建一个能够同时接收文本和图像两路输入的多模态基座。在这个模型中，我们将通过投影与注入机制，将提取好的视觉特征与文本序列相结合，构建一个端到端联合计算与生成的多模态大模型。

一、数据准备与预处理

1.1 获取训练数据

由于资源所限，我们可以参考上一节介绍的 Qwen3-Omni 等模型的落地方案，采取“先炼纯文本基座，再做多模态对齐”的分阶段训练策略。为了能够在单卡上完成训练，我们需要抛开动辄数 TB 的海量语料，转而寻找“小而精”的高质量数据集作为切入点。在纯文本数据准备阶段，我们可以借用开源项目 MiniMind 提供的数据。这是一个致力于在普通个人显卡上从 0 训练超轻量级大模型的开源项目，其中自带了作者经过过滤乱码、去重除噪与启发式质量打分后沉淀出的高质量精简数据集。我们主要选择其中的 pretrain_hq.jsonl 作为语言预训练语料，以及 sft_mini_512.jsonl 作为微调语料。当纯文本基座有了优质的数据后，要想让它进一步具备视觉感知，还需要引入跨模态对齐数据。出于同样的算力及训练时长考量，图像数据方面，我们可以选择 Flickr8k 这个经典的测试数据集。由于我们的目标是在中文语境下进行交互，所以就需要配套引入 Flickr8k-CN 的中文描述文本（flickr8kzhc.caption.txt）。

有了现成的高质量开源数据之后，就可以开始实现项目代码了。我们先创建一个名为 seeker-omni 的项目文件夹，并且作为现代化的 Python 工程，可以在该目录下使用 uv init 快速初始化一个带有 pyproject.toml 的虚拟环境，并把运行所需的依赖（如 torch、tokenizers、tqdm 等）都一并在环境中打通。随后在其中分别创建一个 dataprep/download 和一个 dataprep/prepare 文件夹，用于存放数据的下载脚本以及前期的清洗、Tokenizer（分词器）训练等处理代码。由于不同数据集的下载接口和清洗逻辑大同小异，且往往伴随繁琐的工程细节，为了不偏离本节的主要目标，就不再赘述这部分“脏活累活”的代码实现了，我们可以直接利用 AI 编程工具辅助生成相应的处理脚本。笔者运行脚本拉取数据并处理后的目录结构大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


seeker-omni/
└─ data/
 ├─ raw/
 │ ├─ minimind/
 │ │ ├─ pretrain_hq.jsonl
 │ │ └─ sft_mini_512.jsonl
 │ └─ flickr8k/
 │ ├─ flickr8kzhc.caption.txt
 │ ├─ Flickr8k_Dataset/
 │ │ ├─ *.jpg
 │ │ └─ ...
 │ └─ text/
 │ ├─ Flickr_8k.trainImages.txt
 │ └─ ...
 └─ interim/
 ├─ tokenizer_corpus/
 │ └─ minimind_pretrain_text.txt
 ├─ sft_converted/
 │ └─ minimind_sft_chatml.jsonl
 └─ packs/
 └─ mm/
 └─ train_imgonly.jsonl

可以看到 data/interim（中间产物）目录下，存放着经过脚本“清洗过滤与格式转换”后的数据。tokenizer_corpus/minimind_pretrain_text.txt 是在去除乱码并剔除低含中量、多符号以及长度不合格等低质样本后提取出的预训练文本，专门用于后续训练我们自己的分词器。为了让大家对这些数据有一个直观的体感，我们可以看一下截取自 minimind_pretrain_text.txt 的纯文本语料片段（各对话之间用 <|im_end|> 粗略隔开）：

1

我知道底边长度和高，分别是5cm和8cm，请告诉我计算出来的面积是多少。三角形的面积为20平方厘米。<|im_end|> 为什么理智告诉我们不要跟陌生人接触？因为陌生人可能会对我们的个人安全造成威胁、危害或诱骗等恶劣行为。<|im_end|> 上一次科比在NBA总决赛中获得总冠军是哪一年？科比在NBA总决赛中最后一次获得总冠军是在2010年。<|im_end|> 写一首五言诗，以“秋天”为主题。秋叶飘飘降，秋风肆虐长街，落叶纷纷掉下，百鸟南飞不归，唯有寒蝉孤嘶。<|im_end|> 好的。那你可以跟我聊一下最近的天气吗？当然可以。最近的天气因地区而异，你想知道哪个城市的天气情况呢？<|im_end|> 好的，那么请你接着把这个句子进一步改写，加入一个介绍该书的短语。这本畅销书是由名著名文学家所著写的。<|im_end|> 从以下描述中归纳出这是哪种动物：该动物四肢行走，有毛发，是哺乳动物。这是哺乳动物，具体种类无法确定。<|im_end|> 请问这周末的天气怎么样？我需要您告诉我您所在的城市地区，我可以通过查询天气API来提供相关天气信息。<|im_end|>

还有 sft_converted/minimind_sft_chatml.jsonl 除了经过同样的清洗，还被统一赋予了包含 System、User、Assistant 角色绑定的标准 ChatML 对话指令格式，它的一行 JSONL 数据结构大致如下：

1

{"id": "line-676605", "conversations": [{"role": "system", "content": "你是一个知识丰富的AI，尽力为用户提供准确的信息。"}, {"role": "user", "content": "请向我解释在 GitHub 的公共代码库中使用的 MIT 许可证。"}, {"role": "assistant", "content": "MIT 许可证是一种广泛使用的开源软件许可证，允许用户自由地使用、修改和分发软件。它通常用于 GitHub 上的公共存储库，因为它提供了一个简单和宽松的许可证，允许其他人在不需要担心严格要求或复杂的法律条款的情况下使用和建立在该软件之上。该许可证还要求用户保留软件中的版权和许可证通知，这有助于确保该软件的原始创建者获得信誉，并且其他人知道可以使用该软件的条款。总的来说，MIT 许可证为他人提供开源软件的简单有效方式，同时保护原始创建者的权利。"}, {"role": "user", "content": "你觉得 MIT 许可证好吗？"}, {"role": "assistant", "content": "MIT许可证的好处最终取决于使用它的个人或组织的具体情况和目标。一般而言，MIT许可证被认为是一种非常宽松和简单的开源许可证，允许用户自由使用、修改和分发软件，而不需要其他开源许可证中存在的严格要求和法律复杂性。这使它成为许多开源项目的好选择，特别是那些专注于协作和社区参与的项目。"}]}

至于图文侧最终产出的 packs/mm/train_imgonly.jsonl，同样以类似风格的结构化格式将 Flickr8k 的图片路径与经过基础规范的中文描述整齐地绑定在了一起：

1

{"id": "flickr8k-2208631481_3e4a5675e1-zhc-0", "system": "你是一个只用中文回答的助手。", "prompt": "请描述这张图片。", "answer": "在草地上赛跑的两只黑狗。", "image": "data/raw/flickr8k/Flickr8k_Dataset/2208631481_3e4a5675e1.jpg"}

1.2 分词器的构建与训练

数据处理好后我们是不是就可以开始编写大模型的训练代码了呢？当然不是，在此之前我们需要先完成分词器的训练。来到 dataprep/prepare 文件夹下，开始创建分词器的核心执行脚本 tokenizer.py。为了让代码结构更清晰，我们“自顶向下”的来逐步完成各个模块。首先在 tokenizer.py 文件顶部，引入必要的系统包，并提前规划好本库多模态架构与对话微调高度依赖的特殊控制符。这些标记包括通用占位符 <|endoftext|>，切分 ChatML 角色发言边界的 <|im_start|> 和 <|im_end|>，以及界定视觉特征插入位置的 <img_bos>、<img> 与 <img_eos>。只有在构建字典时硬性绑定这批特殊的控制标记，后续端到端训练时的切片逻辑才能正常运作。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# dataprep/prepare/tokenizer.py
import json
import random
import shutil
import time
from pathlib import Path

from tokenizers import Tokenizer

from .text_bpe import train_text_bpe
from ..data_paths import DATA_INTERIM, MINIMIND_TEXT_CORPUS, TOKENIZER_DIR, TOKENIZER_VOCAB_SIZE

MINIMIND2_CHATML_TOKENS = [
 "<|endoftext|>",
 "<|im_start|>",
 "<|im_end|>",
 "<img_bos>",
 "<img>",
 "<img_eos>",
]

可以看到上面的代码中，我们引入了两个当前还未详细讲解的模块分别是 data_paths 和 text_bpe。先来看相对简单的路径管理模块。其实在之前的 dataprep/download 数据清洗阶段，为了避免整个项目中随处可见散落的硬编码路径，我们就已经建立了一个集中的路径注册表。在 dataprep 目录下新建的这个 data_paths.py 中，已经把诸如中间存放语料的目录、分词器保存的目录，以及词表大小上限等统一定义在了这里并暴露出去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# dataprep/data_paths.py
from pathlib import Path

DATA_RAW = Path("data/raw")
DATA_INTERIM = Path("data/interim")
DATA_PROCESSED = Path("data/processed")
ARTIFACTS = Path("artifacts")

# 默认设置常量
SEED = 42
OVERWRITE = False

# (此处省略中间各种有关 Flickr8k 图文和 minimind 基础语料的大量源地址定义和图文的交接文件配置)
...

# 分词器语料与默认导出目录
MINIMIND_TEXT_CORPUS = DATA_INTERIM / "tokenizer_corpus" / "minimind_pretrain_text.txt"
TOKENIZER_VOCAB_SIZE = 6400
TOKENIZER_DIR = ARTIFACTS / "tokenizers" / "bpe_m2chatml_6400"

def default_dataprep_cfg():
 """返回 dataprep 默认配置 dict"""
 return {
 "seed": int(SEED),
 "overwrite": bool(OVERWRITE),
 "tokenizer": {
 "sample_ratio": 0.6,
 "sample_seed": int(SEED),
 },
 # 其他限流参数与占位配置省略...
 }

除了上面统一管理的大量路径常量外，data_paths.py 底部还提供了一份 default_dataprep_cfg() 默认配置字典。它将所有的下载源链接、文件覆盖策略以及分词器的采样种子参数等统统打包在了一起，为整个数据处理管道提供了一套完整的开箱即用蓝本。

在实际的工程开发中，data_paths.py 里专门针对 tokenizer 的这部分配置往往是和下游的分词器训练脚本同步编排、逐渐补充完善的。但出于教学脉络连贯的考量，我们在文中予以了提前展示。

搞定了路径与全局变量的集中管控后，接下来就要解决分词器训练的底层算法 train_text_bpe 了。我们在 dataprep/prepare/ 目录下创建一个脚本 text_bpe.py。由于这个脚本兼具了推断配置参数和核心算法调用的双重职责，我们把它拆解为两部分进行实现。第一部分是辅助函数，负责智能推断模型的对话体系标准并自动写入对应的配置文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


# dataprep/prepare/text_bpe.py
import json
from pathlib import Path

from tokenizers import Tokenizer
from tokenizers.decoders import ByteLevel as ByteLevelDecoder
from tokenizers.models import BPE
from tokenizers.pre_tokenizers import ByteLevel
from tokenizers.trainers import BpeTrainer

# 此处省略 ChatML Jinja 模板字符串，完整内容参考配套代码
_MINIMIND_CHAT_TEMPLATE = """{%- if tools %}..."""

def _infer_core_tokens(special_tokens):
 """从 special_tokens 推断 scheme 名称与 pad/bos/eos/unk 的字符串形式。

 当前 dataprep 只支持 minimind2_chatml。
 """
 s = set(map(str, special_tokens))
 required = {"<|endoftext|>", "<|im_start|>", "<|im_end|>"}
 if not required.issubset(s):
 raise ValueError(
 "special_tokens must include minimind2_chatml core tokens: "
 "<|endoftext|>, <|im_start|>, <|im_end|>"
 )
 return "minimind2_chatml", "<|endoftext|>", "<|im_start|>", "<|im_end|>", "<|endoftext|>"

def _write_tokenizer_config(
 *, out_dir, tok, special_tokens,
 scheme_name, pad_token, bos_token, eos_token, unk_token,
):
 added_tokens_decoder = {
 str(i): {
 "content": t, "lstrip": False, "normalized": False,
 "rstrip": False, "single_word": False, "special": True
 } for i, t in enumerate(special_tokens)
 }

 cfg = {
 "legacy": True, "model_max_length": 32768,
 "tokenizer_class": "PreTrainedTokenizerFast",
 "added_tokens_decoder": added_tokens_decoder,
 "bos_token": str(bos_token), "eos_token": str(eos_token),
 "pad_token": str(pad_token), "unk_token": str(unk_token),
 "vocab_size": int(tok.get_vocab_size()),
 }
 if str(scheme_name) == "minimind2_chatml":
 cfg["chat_template"] = _MINIMIND_CHAT_TEMPLATE

 (out_dir / "tokenizer_config.json").write_text(json.dumps(cfg, ensure_ascii=False, indent=2), encoding="utf-8")

上面的 _infer_core_tokens 函数通过严格提取并校验我们预先指定的控制符子集，专门针对 ChatML 对话方案进行了映射绑定。只要它检查到外部传来的控制符列表里包含了完整的 ChatML 核心边界符，就会直接提取这套专为多轮交互设计的词表配置映射，进而在 _write_tokenizer_config 时自动将大模型体系专用的那段对话提示词模板（_MINIMIND_CHAT_TEMPLATE）写入最终的 tokenizer_config.json 配置文件中，实现参数装配的自动化与解耦。在准备好这些后勤辅助逻辑后，第二部分就是真正负责读取清洗数据并调用 Hugging Face 库训练构建字典的核心函数了。为了解决生僻字或特殊符号导致的 OOV 问题，我们在这一步采用跟 GPT 实现相同的字节级 BPE（BBPE）。

分词器是怎么“训练”的？

在这个 BBPE 算法中，训练不涉及神经网络的梯度反向叠加，而是纯粹的词频统计与合并分析。算法首先会把海量的预训练纯文本语料彻底打碎成最基础的 256 种单字节。然后遍历整套语料，统计拼在一起出现频率最高的“字节对”，并把这两个字节“粘合”成一个新的专属词条加入词典。接着它会在剩下的语料中继续寻找新的高频组合不断粘合。这个过程一直循环周而复始，直到词典里的“积木块”数量达到了我们设定的上限（本例中设定了 vocab_size=6400）为止，训练就会停止。也正对应我们在 GPT 应用中发现的，常见词语会被切成完整的一块，生僻字可能会被拆解为两三个散碎的底层字节。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


# dataprep/prepare/text_bpe.py
def train_text_bpe(
 *, input_path, out_dir, vocab_size=6400, special_tokens,
):
 inp = Path(input_path)
 out = Path(out_dir)
 out.mkdir(parents=True, exist_ok=True)

 special_tokens = list(special_tokens)
 scheme_name, pad_token, bos_token, eos_token, unk_token = _infer_core_tokens(special_tokens)

 tok = Tokenizer(BPE(unk_token=str(unk_token), byte_fallback=True))
 tok.pre_tokenizer = ByteLevel(add_prefix_space=False)

 trainer = BpeTrainer(
 vocab_size=int(vocab_size), special_tokens=special_tokens,
 show_progress=True, initial_alphabet=ByteLevel.alphabet(),
 )
 tok.train([str(inp)], trainer=trainer)

 # 保证特殊 token 的 ID 稳定
 for i, t in enumerate(special_tokens):
 tid = tok.token_to_id(t)
 if tid is None or int(tid) != int(i):
 raise ValueError(f"special token id mismatch: {t} -> {tid} (expected {i})")

 tok.decoder = ByteLevelDecoder()
 tok.save(str(out / "tokenizer.json"))
 _write_tokenizer_config(
 out_dir=out, tok=tok, special_tokens=special_tokens,
 scheme_name=str(scheme_name), pad_token=str(pad_token),
 bos_token=str(bos_token), eos_token=str(eos_token), unk_token=str(unk_token),
 )

 meta = {
 "special_tokens_scheme": str(scheme_name), "vocab_size": tok.get_vocab_size(),
 "special_tokens": special_tokens, "special_ids": {t: tok.token_to_id(t) for t in special_tokens},
 }
 (out / "meta.json").write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")

train_text_bpe 函数会首先实例化一个开启了底层字节回退（byte_fallback=True）机制的 BPE 模型，并利用 BpeTrainer 对输入语料集进行高频片段的归并与词典训练。但在训练出底层映射后，它还执行了一步关键的断言校验，主要用于强制检查字典里那批系统级特殊控制符所分配的 ID 是否与我们预期硬塞入的列表索引完全一致（验证它们是否强制占用了词表最靠前的 0, 1, 2… 等位置）。这步“锁死”特殊 Token ID 的操作对于多模态架构很重要，只有它们的系统 ID 永远固定，后续大模型在做视觉特征切片与对应的词嵌入检索时才不会发生错位。一切校验无误后，它才会将分词器本体、模型配置及自定义的元数据分别落盘保存。实现了底层算法后，我们再回到刚才未完成的 tokenizer.py 文件中，补全余下负责整体统筹的流程控制代码。剩余的逻辑主要负责读取 MINIMIND_TEXT_CORPUS 语料，为避免语料过大导致内存溢出，它还会根据配置支持对预训练文本进行按比例采样以加快训练速度。随后，代码会调用刚才写好的 train_text_bpe 正式挂载训练构建。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


# dataprep/prepare/tokenizer.py
def _count_nonempty_lines(path):
 n = 0
 with path.open("r", encoding="utf-8-sig") as f:
 for line in f:
 if line.strip():
 n += 1
 return n

def _sample_text_corpus(*, src, dst, ratio, seed, overwrite):
 # 随机采样逻辑，详见配套源码
 pass

def _ensure_tokenizer(*, text_corpus, out_dir, vocab_size, overwrite):
 meta_path = out_dir / "meta.json"
 if overwrite and out_dir.exists():
 shutil.rmtree(out_dir)

 if meta_path.exists():
 meta = json.loads(meta_path.read_text(encoding="utf-8"))
 if meta.get("special_tokens_scheme") == "minimind2_chatml" and int(meta.get("vocab_size", -1)) == int(vocab_size):
 return

 out_dir.parent.mkdir(parents=True, exist_ok=True)
 t0 = time.time()
 train_text_bpe(
 input_path=text_corpus,
 out_dir=out_dir,
 vocab_size=int(vocab_size),
 special_tokens=list(MINIMIND2_CHATML_TOKENS),
 )
 dt = int(time.time() - t0)
 print(f"ok: tokenizer -> {out_dir} (sec={dt})")

def ensure_tokenizer_and_load(cfg):
 seed = int(cfg.get("seed", 42))
 overwrite = bool(cfg.get("overwrite", False))
 tok_cfg = cfg.get("tokenizer", {})

 vocab_size = int(TOKENIZER_VOCAB_SIZE)
 tokenizer_out = Path(TOKENIZER_DIR)
 text_corpus = Path(MINIMIND_TEXT_CORPUS)
 if not text_corpus.exists():
 raise FileNotFoundError(text_corpus)

 tmp_root = Path(DATA_INTERIM) / "tmp"
 sample_ratio = float(tok_cfg.get("sample_ratio", 1.0))
 sample_seed = int(tok_cfg.get("sample_seed", seed))

 tokenizer_corpus_for_train = text_corpus
 if sample_ratio < 1.0:
 safe_name = text_corpus.name.replace(".", "_")
 ratio_str = f"{sample_ratio:.6f}".rstrip("0").rstrip(".")
 sampled = tmp_root / f"{safe_name}.sample_p{ratio_str}_seed{sample_seed}.txt"
 tokenizer_corpus_for_train = _sample_text_corpus(
 src=text_corpus, dst=sampled, ratio=sample_ratio, seed=sample_seed, overwrite=overwrite
 )

 print(f"using tokenizer corpus: {tokenizer_corpus_for_train} (lines={_count_nonempty_lines(tokenizer_corpus_for_train)})")
 print("== prepare: tokenizer ==")

 _ensure_tokenizer(
 text_corpus=tokenizer_corpus_for_train,
 out_dir=tokenizer_out,
 vocab_size=vocab_size,
 overwrite=overwrite,
 )

 if tokenizer_corpus_for_train != text_corpus and tokenizer_corpus_for_train.exists():
 tokenizer_corpus_for_train.unlink(missing_ok=True)

 tok = Tokenizer.from_file(str(tokenizer_out / "tokenizer.json"))
 if int(tok.get_vocab_size()) != int(vocab_size):
 raise RuntimeError(f"tokenizer vocab mismatch: tok={tok.get_vocab_size()} expected={vocab_size}")
 return tok

当我们把分词器的训练和加载逻辑收拢完毕后，为了便于外部作为工程模块统一调用，我们在 dataprep/prepare 目录下顺手把包结构搭建起来。新建一个 __init__.py 对外暴露出一个全局的 run 执行入口：

1
2
3
4
5


# dataprep/prepare/__init__.py
from .tokenizer import ensure_tokenizer_and_load

def run(cfg):
 tok = ensure_tokenizer_and_load(cfg)

1.3 训练语料特征序列化

有了分词器和对应数据，按理说大模型就可以直接拿它们去训练了，但如果我们直接在 PyTorch 的 DataLoader 里挂载前面我们处理好的那些 .jsonl 或是 .txt 文本，在进行多卡甚至是单卡的大批量吞吐时，由于涉及到海量变长字符串的实时分词与内存分配，CPU 或磁盘 I/O 很容易成为阻碍 GPU 计算的性能瓶颈。为了解决这个问题我们可以在预处理阶段，提前把文本与图像都转换为可训练的数值表示。文本用分词器转换为等长的数字 ID，再使用 Numpy 的 memmap（内存映射）技术，将这些张量紧凑地当成二维连续矩阵序列化到磁盘特定的二进制（.bin）文件中。我们在 dataprep/prepare 目录下创建一个执行脚本 memmap.py。这个脚本的作用就是把前面清洗好的语料和训练好的分词器组合起来，分别去生成预训练和微调所需的二进制数据块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# dataprep/prepare/memmap.py
import shutil
import time
from pathlib import Path
from tokenizers import Tokenizer
from .memmap_io import MemmapMeta

def _ensure_packed_text(*, text_path, out_dir, tokenizer, vocab_size, max_seq_len, max_samples, seed, overwrite):
 # 1. 校验是否已存在符合要求的历史特征，避免重复生成
 meta_path = out_dir / "meta.json"
 if meta_path.exists() and not overwrite:
 meta = MemmapMeta.load(meta_path)
 if int(meta.seq_len) == int(max_seq_len) and int(meta.vocab_size) == int(vocab_size):
 return

 # 2. 调用底层的构造器正式生成二进制特征阵列
 # (具体封装逻辑 `build_packed_text_memmap_dataset` 省略，功能是读取文本逐行Token化并写入硬盘)
 ...

在上述的调度流程中可以看到，真正将海量文本转化为连续硬盘矩阵的逻辑都交由底层的 memmap_io 模块来实现。让我们在同级目录下继续建设这个基础读写模块 memmap_io.py：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


# dataprep/prepare/memmap_io.py
import json
from dataclasses import dataclass
from pathlib import Path
import numpy as np

@dataclass(frozen=True)
class MemmapMeta:
 """memmap 数据集的元信息（用于数据准备阶段写入/校验）。"""
 # ...省略字段定义（num_samples, seq_len 等）...

 @staticmethod
 def load(path):
 # ...从 JSON 加载元数据逻辑...
 pass

 def save(self, path):
 # ...保存至 meta.json 逻辑...
 pass

class MemmapWriter:
 """将 token/labels/attention 写入到 memmap 目录。"""
 def __init__(self, out_dir, *, num_samples, seq_len, vocab_size, pad_id, image_tokens=None, image_feat_dim=None, mode="w+"):
 self.out_dir = Path(out_dir)
 self.out_dir.mkdir(parents=True, exist_ok=True)

 # 初始化与校验元数据
 self.meta = MemmapMeta(num_samples, seq_len, vocab_size, pad_id, image_tokens=image_tokens, image_feat_dim=image_feat_dim)
 if mode == "w+":
 self.meta.save(self.out_dir / "meta.json")

 n = int(self.meta.num_samples)
 s = int(self.meta.seq_len)

 # 基于元信息开辟 Numpy 内存映射空间
 self.input_ids = np.memmap(self.out_dir / "input_ids.bin", dtype=np.dtype(self.meta.input_dtype), mode=mode, shape=(n, s))
 self.labels = np.memmap(self.out_dir / "labels.bin", dtype=np.dtype(self.meta.label_dtype), mode=mode, shape=(n, s))
 self.attention_mask = np.memmap(self.out_dir / "attention_mask.bin", dtype=np.dtype(self.meta.attention_dtype), mode=mode, shape=(n, s))

 self.image_feats = None
 if self.meta.image_tokens is not None and self.meta.image_feat_dim is not None:
 self.image_feats = np.memmap(
 self.out_dir / "image_feats.bin", dtype=np.float16, mode=mode,
 shape=(n, int(self.meta.image_tokens), int(self.meta.image_feat_dim)),
 )

 def write(self, idx, *, input_ids, labels, attention_mask, image_feats=None):
 self.input_ids[idx] = input_ids.astype(self.input_ids.dtype, copy=False)
 self.labels[idx] = labels.astype(self.labels.dtype, copy=False)
 self.attention_mask[idx] = attention_mask.astype(self.attention_mask.dtype, copy=False)

 if self.image_feats is not None and image_feats is not None:
 self.image_feats[idx] = image_feats.astype(np.float16, copy=False)

 def flush(self):
 self.input_ids.flush()
 self.labels.flush()
 self.attention_mask.flush()
 if self.image_feats is not None:
 self.image_feats.flush()

这里的 memmap_io 模块展示了数据管道走向落地的最后一步。首先，我们用不可变的数据类 MemmapMeta 将包括序列长度、词表大小在内的这套张量规格严格固化了下来，并保存为同级目录下的 meta.json 索引卡。这么做是为了在后续训练读取甚或是增量生成数据时，防止维度定义错乱造成内存越界。在建立好规范后，MemmapWriter 的 __init__ 函数直接利用 np.memmap ，一次性为全部将要输入模型的核心张量（输入 ID、标签 Label、注意力掩码 Attention Mask）预分配好结构严密且连续的二进制磁盘空间。而且为了原生支撑整个多模态架构的运行，一旦检测到外部配置了图片特征的相关维度约束（image_tokens 与 image_feat_dim），它还会专门开辟出一整块用于存储大体积视觉向量矩阵的 image_feats.bin 区域，并精细地将其底层数据格式卡在 np.float16 以节省空间。当 MemmapWriter 初始化并分配好内存映射空间后，memmap.py 调度脚本只需源源不断地抽取处理好的文本 Token ID 或图像特征矩阵，通过 writer.write(idx, ...) 方法按索引写入对应的预定位置，最后调用 flush 将数据落盘保存即可。

完成了无监督预训练数据的落盘操作后，我们知道大模型要想掌握对话的能力，还必须用到 SFT 指令语料。接下来我们继续在 memmap.py 中实现负责调度微调数据的 _ensure_sft_text 函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# dataprep/prepare/memmap.py
from .sft_builder import build_sft_text_memmap_dataset

def _ensure_sft_text(*, in_jsonl, out_dir, tokenizer, vocab_size, max_seq_len, overwrite):
 # 第一步同理，先通过 meta.json 校验是否可复用缓存跳过...

 # 主要差异：由专属的 SFT 构造器来处理带角色限定的对话语料
 build_sft_text_memmap_dataset(
 jsonl_path=str(in_jsonl),
 out_dir=str(out_dir),
 text_tokenizer=tokenizer,
 vocab_size=int(vocab_size),
 max_seq_len=int(max_seq_len),
 resume=False,
 flush_every=200,
 )

与预训练阶段直接顺次拼接文本并分块切片的简单流水线不同，微调语料有着严格的结构划分（System、User、Assistant），所以必然得有一套专门用于提示模板包裹与交叉熵损失屏蔽的逻辑。为了实现 build_sft_text_memmap_dataset 接口，我们继续在同级目录下新建一个 sft_builder.py 脚本来处理这份更加精细的构造任务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


# dataprep/prepare/sft_builder.py
import json
import numpy as np
from .memmap_io import MemmapWriter

def build_sft_text_memmap_dataset(*, jsonl_path, out_dir, text_tokenizer, max_seq_len, vocab_size, ...):
 # 1. 挂载词表中的特殊控制 Token（如 pad 占位，以及 ChatML 体系的体系化标记）
 pad_id = text_tokenizer.token_to_id("<|endoftext|>")
 bos_id = text_tokenizer.token_to_id("<|im_start|>")
 eos_id = text_tokenizer.token_to_id("<|im_end|>")
 # ...省略繁琐的 Token ID 校验与断言...

 # 2. 初始化底层流式存储类
 writer = MemmapWriter(out_dir, num_samples=n, seq_len=max_seq_len, vocab_size=vocab_size, pad_id=pad_id, mode='w+')

 # 3. 逐行读取 jsonl 格式的微调语料，通过 ChatML 角色控制符硬编码包裹拼接
 for idx, obj in enumerate(_iter_json_objects(jsonl_path)):
 conversations = obj.get("conversations")

 tokens = [] # 喂给大模型的所有字符索引
 labels_list = [] # 训练掩码对齐数组

 for m in conversations:
 role = m["role"]
 content = m["content"]

 # 使用 ChatML 特有的边界符包裹具体的发言内容，帮助基座快速建立角色认知
 header = [bos_id] + text_tokenizer.encode(f"{role}\n").ids
 body = text_tokenizer.encode(content).ids
 footer = [eos_id] + text_tokenizer.encode("\n").ids

 msg_tokens = header + body + footer

 # 只让大模型对 Assistant（它自己的答案）去计算 Loss
 # 对于 System、User 的上下文前提，统统打上 -100 (PyTorch CrossEntropyLoss 默认的 ignores_index)
 msg_labels = [-100] * len(msg_tokens)
 if role == "assistant":
 for j in range(len(header), len(msg_tokens)):
 msg_labels[j] = msg_tokens[j]

 tokens.extend(msg_tokens)
 labels_list.extend(msg_labels)

 # 4. 根据设定的最大序列长度进行截断与 Padding（以 pad_id 填补余位），最后交由 MemmapWriter 写盘
 # ...省略截断补齐的矩阵赋值...
 writer.write(idx, input_ids=input_ids, labels=labels, attention_mask=attention_mask)

 writer.flush()

sft_builder 的代码实现有两个亮点。其一是针对大模型专属的对话提示进行了系统性的 ChatML 组装，使基座模型可以通过识别专门的边界占位符快速建立对应的角色认知。第二个是在构造训练标签时，我们设计了一套巧妙的交叉熵掩码屏蔽机制。这里我们利用了 PyTorch 原生计算交叉熵去忽略无效索引的默认掩码值 -100。基于这种遮蔽策略我们将先验指令和人类的问题都打上了专门的占位符，只让基座模型对应该作答的内容去收敛预测参数。不管人类怎么提问这些前序语句都只作为上下文条件存在而不单独耗费梯度的算力，这也为模型带来了最高效的针对性复习体验。接下来回到 memmap.py 中，我们分别通过 _ensure_packed_text 和 _ensure_sft_text 铺设好了预训练与微调的解析方案后，只需在 memmap.py 的最下方提供一个统一的对外调度入口 ensure_memmaps：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# dataprep/prepare/memmap.py
from pathlib import Path
from ..data_paths import MINIMIND_TEXT_CORPUS, MINIMIND_SFT_SEEKER, TEXT_PRETRAIN_340, TEXT_SFT_340

def ensure_memmaps(cfg: dict, tokenizer):
 overwrite = bool(cfg.get("overwrite", False))
 vocab_size = int(tokenizer.get_vocab_size())

 print("== prepare: packed text (340) ==")
 _ensure_packed_text(
 text_path=Path(MINIMIND_TEXT_CORPUS),
 out_dir=Path(TEXT_PRETRAIN_340),
 tokenizer=tokenizer,
 vocab_size=vocab_size,
 max_seq_len=340,
 overwrite=overwrite,
 )

 print("== prepare: sft text (340) ==")
 _ensure_sft_text(
 in_jsonl=Path(MINIMIND_SFT_SEEKER),
 out_dir=Path(TEXT_SFT_340),
 tokenizer=tokenizer,
 vocab_size=vocab_size,
 max_seq_len=340,
 overwrite=overwrite,
 )

回到 dataprep/prepare/__init__.py 的 run 函数中，把刚刚写完的二进制分配逻辑加上，成为数据准备管线的“最后一块拼图”：

1
2
3
4
5
6
7


# dataprep/prepare/__init__.py
from .tokenizer import ensure_tokenizer_and_load
from .memmap import ensure_memmaps # 引入新增的内存映射逻辑

def run(cfg):
 tok = ensure_tokenizer_and_load(cfg)
 ensure_memmaps(cfg, tok) # 词表构建完毕，正式执行所有数据的二进制分配

最后，我们还可以在这层包下再补上一个 __main__.py 入口，支持从命令行一键独立拉起这整个预处理管线：

1
2
3
4
5
6
7


# dataprep/prepare/__main__.py
from . import run
from ..data_paths import default_dataprep_cfg

if __name__ == "__main__":
 cfg = default_dataprep_cfg()
 run(cfg)

有了这套外壳，我们在系统终端只要敲下 uv run python -m dataprep.prepare 的指令，基于 uv 隔离环境的整个数据准备构建流程就能一顺到底彻底跑通了。运行结束后，我们将会得到以下两大类核心产物。

分词器配置：

tokenizer.json：BPE 分词器的权重与词缀拼装合并规则集合。

tokenizer_config.json：包含控制符配置以及供后续推理框架适配使用的 ChatML 对话模板（Jinja 格式）。

meta.json：我们在预处理流程中专门固化的元数据（包含词表大小、特殊 Token 的映射关系等）。

可以直接供模型吞吐的训练张量：

预训练 Packed Memmap：位于 data/processed/text_pretrain_packed_340_u16_offline/（TEXT_PRETRAIN_340），包含 meta.json、input_ids.bin、labels.bin 与 attention_mask.bin 四份张量。

微调 SFT Memmap：位于 data/processed/text_sft_340/（TEXT_SFT_340），包含 meta.json、input_ids.bin、labels.bin 与 attention_mask.bin 四份张量。

二、模型训练流水线与核心架构设计

数据准备就绪后，接下来我们在项目根目录下创建一个 seeker_omni 模块文件夹，开始具体设计模型架构与训练组装流程。与一上来就搭建庞大复杂的网络不同，在有限的算力下，我们要想让大模型具备出色的多模态能力，稳妥的做法是让模型先掌握语言规律，再学习遵循人类指令，最后注入视觉感知。那么我们可以将整个训练流水线明确划分为纯文本无监督预训练、纯文本指令微调以及端到端多模态对齐三个阶段。在第一阶段，也就是纯文本无监督预训练中，我们将此前清洗得到的二进制连续分布语料库送入模型，通过海量的无标注文本和因果语言建模进行自监督学习，让模型首先“学会说话”并掌握语言文字规律。但是，单纯的预训练基座只懂得顺着上文续写，所以在第二阶段的纯文本指令微调中，我们会使用 ChatML 格式包裹好、且带有 -100 交叉熵掩码屏蔽用户问题的精选问答数据对其进行精进，使模型蜕变为能听懂指令的助手。当纯文本基座具备了成熟的对话能力后，我们再进入第三阶段的端到端多模态对齐训练来赋予其视觉感知。不同于早期梯度断裂的拼接模型，这里我们引入图文描述记录，在训练中同时更新视觉特征投影层甚至解冻部分语言模型的骨干权重。这种端到端的联合反向传播，正是上一节中我们学习过的 Qwen3-Omni 等工业级模型时所强调的“紧耦合”架构的精髓所在。通过这种联合优化，拉近离散文本空间与连续视觉编码特征的距离，使大模型能够自然吞吐外界视觉特征，实现看图作答。如果想要进一步打磨模型的回答质量，让它的风格、安全性和有用性更符合人类的期望，就还需要进行基于人类反馈的强化学习偏好对齐，这部分技术我们在前面的章节中已经进行过学习和实战。由于本节我们的主要目标是跑通大模型多模态化的流程与核心回路，而不是实现一款可用的产品，所以这部分就略去了。笔者在后续的额外章节中，会基于当前这套项目框架，专门探讨如何引入 RLHF 对齐以及 MoE 等进阶优化技术，进一步释放模型潜力。

基于上述的阶段性训练策略，我们简化的多模态框架应该包含三个核心组件，第一个是负责文本处理的模块，它主要由常规的词嵌入与多模态特殊占位符构成。其次是视觉特征投影，负责接收由外部冻结的视觉编码器提取出的视觉特征，通过线性层和门控机制将视觉特征投影对齐到大模型的特征维度并注入到特征序列中。最后是统一大语言模型，也就是一个标准的 Transformer Decoder 模型，用来接收多模态融合后的特征序列并进行端到端自回归推理。具体架构如图 20-16 所示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


graph LR
 subgraph 输入["输入"]
 TXT["Token IDs"]
 IMG["Image Features"]
 end

 subgraph 嵌入["嵌入层"]
 EMB["词嵌入<br/><i>special + base</i>"]
 PROJ["Linear Projection<br/>× tanh(门控)"]
 ADD_E(("Add"))
 end

 TXT --> EMB --> ADD_E
 IMG -.-> PROJ -.-> ADD_E
 ADD_E --> DROP["Dropout"]

 subgraph BLOCK["Transformer Block × N"]

 subgraph 自注意力["Grouped-Query Attention"]
 QKV["Q / K / V 投影"] --> ROPE["RoPE"]
 ROPE --> SDPA["Scaled Dot-Product<br/>Attention<br/><i>+ Causal Mask</i>"]
 SDPA --> O_PROJ["Output Projection"]
 end

 subgraph 前馈网络["SwiGLU Feed-Forward"]
 GU["W_gate / W_up"] --> SW["SiLU(gate) × up"]
 SW --> WD["W_down"]
 end

 DROP --> NORM1["RMSNorm"]
 NORM1 --> QKV
 O_PROJ --> ADD1(("Add"))
 DROP -. "残差" .-> ADD1

 ADD1 --> NORM2["RMSNorm"]
 NORM2 --> GU
 WD --> ADD2(("Add"))
 ADD1 -. "残差" .-> ADD2
 end

 subgraph 输出["输出层"]
 FNORM["RMSNorm"]
 HEAD["LM Head<br/><i>与嵌入权重共享</i>"]
 LOGITS["Output Logits"]
 end

 ADD2 --> FNORM --> HEAD --> LOGITS

 style BLOCK fill:#fef9e7,stroke:#f39c12,stroke-width:2px
 style 自注意力 fill:#eaf2f8,stroke:#2980b9
 style 前馈网络 fill:#f5eef8,stroke:#8e44ad
 style 嵌入 fill:#fdf2e9,stroke:#e67e22
 style 输出 fill:#e8f8f5,stroke:#1abc9c
 style ADD1 fill:#d5f5e3,stroke:#27ae60
 style ADD2 fill:#d5f5e3,stroke:#27ae60
 style ADD_E fill:#d5f5e3,stroke:#27ae60

图 20-16 Seeker-Omni 统一多模态大模型架构

三、模型架构的实现

了解了整体架构与流水线之后，我们就开始动手，用 PyTorch 将这套多模态网络“搭”出来。我们先在刚刚创建好的 seeker_omni 模块下，新建一个专门存放模型核心代码的 model 文件夹，后续所有的网络组件实现都将归档于这个目录下。

3.1 前置配置模块

在工程开发中，各种常量路径、特殊字符和模型超参数的定义，往往是我们在搭建各个核心模块的过程中逐渐沉淀、抽离出来的。不过，为了让大家在后续组装主干网络时能在脑海里有个大致的结构概念，我们不妨先提前预览一下 seeker_omni 模块根目录下的这三个基础依赖文件的核心骨架。首先是整个项目输入输出常量的 paths.py，以及专门存放模型超参数数据类的 config.py：

1
2
3
4
5


# seeker_omni/paths.py
from pathlib import Path
DATA_PROCESSED = Path("data/processed")
TEXT_PRETRAIN_340 = DATA_PROCESSED / "text_pretrain_packed_340_u16_offline"
# ... 其他训练相关的数据集与分词器默认常量路径定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# seeker_omni/config.py
from dataclasses import dataclass
from .special_tokens import DEFAULT_SPECIAL_TOKENS_SCHEME

@dataclass(frozen=True)
class ModelConfig:
 name: str
 vocab_size: int
 max_seq_len: int
 hidden_size: int
 num_layers: int
 num_heads: int
 # ... 其他架构参数
 special_tokens_scheme: str = DEFAULT_SPECIAL_TOKENS_SCHEME

在 config.py 中，我们为超参数设定了默认的词表方案，所以我们需要在 special_tokens.py 中将整个模型用到的特殊占位符（如 <|im_start|>、<|im_end|> 与 <img>）以及对应的方案列表进行统一定义：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75


# seeker_omni/special_tokens.py
from dataclasses import dataclass

@dataclass(frozen=True)
class TokenSchemeSpec:
 name: str
 special_tokens: list[str]
 pad_token: str
 bos_token: str
 eos_token: str
 unk_token: str


MINIMIND2_CHATML = TokenSchemeSpec(
 name="minimind2_chatml",
 special_tokens=[
 "<|endoftext|>",
 "<|im_start|>",
 "<|im_end|>",
 "<img_bos>",
 "<img>",
 "<img_eos>",
 ],
 pad_token="<|endoftext|>",
 bos_token="<|im_start|>",
 eos_token="<|im_end|>",
 unk_token="<|endoftext|>",
)


_SPECS: dict[str, TokenSchemeSpec] = {
 MINIMIND2_CHATML.name: MINIMIND2_CHATML,
}


def get_token_scheme_spec(scheme: str | None) -> TokenSchemeSpec:
 scheme = (scheme or MINIMIND2_CHATML.name).strip()
 spec = _SPECS.get(scheme)
 if spec is None:
 opts = ", ".join(sorted(_SPECS.keys()))
 raise ValueError(f"unknown special_tokens_scheme={scheme!r} (expected one of: {opts})")
 return spec


@dataclass(frozen=True)
class SpecialTokenIds:
 pad: int
 unk: int
 bos: int
 eos: int
 img_bos: int
 img: int
 img_eos: int


def build_special_token_ids(spec: TokenSchemeSpec) -> SpecialTokenIds:
 tok2id = {t: i for i, t in enumerate(spec.special_tokens)}

 def _id(t: str) -> int:
 if t not in tok2id:
 raise ValueError(f"required special token missing from scheme={spec.name!r}: {t}")
 return int(tok2id[t])

 return SpecialTokenIds(
 pad=_id(spec.pad_token),
 unk=_id(spec.unk_token),
 bos=_id(spec.bos_token),
 eos=_id(spec.eos_token),
 img_bos=_id("<img_bos>"),
 img=_id("<img>"),
 img_eos=_id("<img_eos>"),
 )


DEFAULT_SPECIAL_TOKENS_SCHEME = MINIMIND2_CHATML.name

3.2 文本嵌入

接下来我们就可以在 model 目录下新建 lm.py 文件，开始编写模型的主干类 SeekerOmniLM。多模态大模型的底座依然是语言模型，所以文本处理始终是最基础的起点。为了保持系统的高内聚与低耦合，并为后续多模态控制标记的演进（如增减模态占位符）预留空间，我们不会简单地使用单一的 nn.Embedding 把所有标记揉在一起，而是将特殊控制标记与普通文本词表的嵌入层在物理结构上直接拆分开来。有了前面的配置支撑，我们就能毫无阻碍地切分出特殊词表和普通词表，并完成真正的文本查表组装映射：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# seeker_omni/model/lm.py
import torch
import torch.nn as nn
from ..config import ModelConfig
from ..special_tokens import get_token_scheme_spec, build_special_token_ids

class SeekerOmniLM(nn.Module):
 def __init__(self, cfg: ModelConfig):
 super().__init__()
 self.cfg = cfg
 self.special_spec = get_token_scheme_spec(cfg.special_tokens_scheme)
 self.special = build_special_token_ids(self.special_spec)
 self.n_special = int(len(self.special_spec.special_tokens))

 # 将特殊 token（如 bos, eos, img 占位符等）与普通文本 token 分离
 self.special_embed = nn.Embedding(self.n_special, cfg.hidden_size)
 self.base_embed = nn.Embedding(cfg.vocab_size - self.n_special, cfg.hidden_size)

 def _embed_tokens(self, input_ids):
 # 分别根据 ID 范围查特殊词表和普通词表，最后拼合成统一的隐藏层张量
 n_special = int(self.n_special)
 is_special = input_ids < n_special

 x = torch.empty(
 (*input_ids.shape, self.cfg.hidden_size),
 device=input_ids.device,
 dtype=self.special_embed.weight.dtype,
 )

 if is_special.any():
 x[is_special] = self.special_embed(input_ids[is_special])
 if (~is_special).any():
 base_ids = (input_ids[~is_special] - n_special).clamp(min=0)
 x[~is_special] = self.base_embed(base_ids)
 return x

 def reset_parameters(self):
 # 初始化常规嵌入以及线性层
 nn.init.normal_(self.special_embed.weight, mean=0.0, std=0.02)
 nn.init.normal_(self.base_embed.weight, mean=0.0, std=0.02)
 for module in self.modules():
 if isinstance(module, nn.Linear):
 nn.init.normal_(module.weight, mean=0.0, std=0.02)

 # 关键：将模态占位符的词嵌入强行初始化为 0，确保模型初期不会因占位符引入额外噪声
 with torch.no_grad():
 for tid in (
 self.special.img_bos,
 self.special.img,
 self.special.img_eos,
 ):
 self.special_embed.weight[tid].zero_()

 def _lm_head_weight(self):
 # 语言模型头的权重与底层的文本嵌入权重共享（Weight Tying）以节约显存
 return torch.cat([self.special_embed.weight, self.base_embed.weight], dim=0)

通过这一步处理，混合了图片标记和文本标记的序列被成功映射为了连续向量。但是如果在输入序列中出现了图像占位符，我们就需要将外部的视觉特征对应注入进来。所以，我们先去实现一下它所依赖的视觉对齐模块。

3.3 视觉特征压缩与注入

由于资源所限，我们不再把 ViT 写在 LLM 的前向传播里进行重头训练，转而选择接收训练好的 SigLIP 提取出来的视觉特征。但预训练的 Vision Encoder 提取出的特征序列通常非常长（例如 729 个 Token），如果直接送入语言模型会极大拖慢推理速度并消耗过多显存。所以，我们需要引入一个感知重采样器对这一长串特征序列进行压缩。我们在 model 目录下新建 resampler.py，通过少量的可学习潜在查询向量，利用交叉注意力机制将冗长的图像特征平滑过渡并压缩到固定的较短长度（例如 64 个 Token）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# seeker_omni/model/resampler.py
import torch
from torch import nn

class PerceiverResampler(nn.Module):
 def __init__(self, *, dim, num_latents, num_layers=2, num_heads=8, ff_mult=4):
 super().__init__()
 self.dim = int(dim)

 # 初始化固定数量的可学习潜在特征 (Latents)
 lat = torch.empty((num_latents, dim), dtype=torch.float32)
 nn.init.trunc_normal_(lat, std=0.02)
 self.latents = nn.Parameter(lat)

 # 构建交叉注意力层与前馈网络
 # ... (具体层的构建代码省略)
 self.layers = nn.ModuleList([...])

 def forward(self, x):
 # x 为 SigLIP 提取的原始长序列视觉特征: [B, T_img, D]
 b = int(x.shape[0])
 # 扩展潜在特征以匹配批次大小: [B, num_latents, D]
 latents = self.latents.unsqueeze(0).expand(b, -1, -1)

 for layer in self.layers:
 q = layer["ln_q"](latents)
 kv = layer["ln_kv"](x)
 # 通过交叉注意力，用少量的 Latents 去 Query 密集的视觉特征 KV
 attn_out, _ = layer["attn"](q, kv, kv, need_weights=False)
 latents = latents + attn_out
 latents = latents + layer["ff"](layer["ln_ff"](latents))

 # 返回定长的压缩视觉特征: [B, num_latents, D]
 return latents

视觉特征被成功压缩后，我们还需要最后一步的对齐。也就是在 model 目录下新建 projector.py 文件，通过可学习的线性映射与零初始化门控策略，将这些特征的维度对齐到大模型的隐藏层维度，并注入到对应的“图像占位 Token”位置中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# seeker_omni/model/projector.py
import torch

def inject_feature_tokens(
 x,
 *,
 input_ids,
 image_feats,
 img_token_id,
 img_proj,
 img_gate,
):
 # x: [B, S, hidden_size]
 if image_feats is not None:
 img_mask = input_ids == int(img_token_id)
 if img_mask.any():
 # 将视觉特征投影至 LLM 维度
 img_tokens = img_proj(image_feats.to(dtype=x.dtype))
 # 门控机制：初始阶段 tanh(0)=0，使得模型初期等同于纯文本模型，有助于更稳定的联合训练
 img_tokens = img_tokens * torch.tanh(img_gate)[None, None, :]

 # 使用 nonzero 获取展平索引，进行快路径累加注入
 pos = img_mask.nonzero(as_tuple=False) # [N,2] row-major
 flat = img_tokens.reshape(-1, img_tokens.shape[-1])
 if pos.shape[0] == flat.shape[0]:
 x[pos[:, 0], pos[:, 1]] = x[pos[:, 0], pos[:, 1]] + flat
 else:
 for b in range(int(x.shape[0])):
 idx = torch.where(img_mask[b])[0]
 if idx.numel() == 0:
 continue
 take = min(idx.numel(), img_tokens.shape[1])
 x[b, idx[:take]] = x[b, idx[:take]] + img_tokens[b, :take]
 return x

可以注意到，这里的 projector.py 内部并没有直接去调用 resampler.py。这是一种非常经典的解耦设计：我们在上游的系统调度代码（例如专门的预处理脚本或多模态 Pipeline 本身）中，先运用 resampler.py 把极长的图像特征压缩成了短小精悍的连续张量。最后，这批被压缩过的张量会以 image_feats 参数的形式，干干净净地传递到文本底座的 projector 里进行投影和注入。这样一来，大模型主干代码的阅读体验就仿佛是在处理纯文本一样。为了在 lm.py 的主干网络中顺利调用 inject_feature_tokens 函数，我们只需在 SeekerOmniLM 类里补充一个轻便的内部方法 _inject_modality_tokens 来进行中转映射：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# seeker_omni/model/lm.py

 def _inject_modality_tokens(self, x, *, input_ids, image_feats):
 # 将传入的投影参数绑定好，方便 forward 调用
 from .projector import inject_feature_tokens
 return inject_feature_tokens(
 x,
 input_ids=input_ids,
 image_feats=image_feats,
 img_token_id=int(self.special.img),
 img_proj=self.img_proj,
 img_gate=self.img_gate,
 )

现在我们特征的提取和对齐注入工作就已经备齐了。但如果现在就开始写前向传播，会发现还缺了一个“计算大脑”，所以还得先把解码块写完。

3.4 构建 Transformer 解码块

我们继续在 model 目录下新建 block.py 分别实现前馈神经网络块。在 block.py 中，我们的 SeekerBlock 需要组合注意力层、全连接层与均方根归一化，并且支持流式推理必须的 KV Cache。为了理清脉络，我们先写出 block.py 的主干骨架：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# seeker_omni/model/block.py
import torch
from torch import nn

from .attention import PastKeyValue, SeekerSelfAttention
from .mlp import SeekerMLP
from .norm import RMSNorm

class SeekerBlock(nn.Module):
 def __init__(self, hidden_size, num_heads, num_kv_heads, **kwargs): # 用 **kwargs 代替其他传入的初始化超参数
 super().__init__()
 self.attn_norm = RMSNorm(hidden_size)
 self.attn = SeekerSelfAttention(hidden_size, num_heads, num_kv_heads, **kwargs)
 self.mlp_norm = RMSNorm(hidden_size)
 self.mlp = SeekerMLP(hidden_size, **kwargs)

 def forward(self, x, cos, sin, attention_mask=None, past_kv=None, use_cache=False):
 # 如果开启流式缓存，则调用注意力机制时抽取并封装 KV 缓存
 if use_cache:
 attn_out, present_kv = self.attn(
 self.attn_norm(x),
 cos=cos, sin=sin, attention_mask=attention_mask,
 past_kv=past_kv, use_cache=True,
 )
 x = x + attn_out
 x = x + self.mlp(self.mlp_norm(x))
 return x, present_kv

 # 否则普通的残差堆叠计算
 x = x + self.attn(self.attn_norm(x), cos=cos, sin=sin, attention_mask=attention_mask)
 x = x + self.mlp(self.mlp_norm(x))
 return x

有了蓝图，我们再逐个将引入的三个基础底座组件实现出来。首先在 model 目录下新建 norm.py 代入对应公式实现 RMSNorm。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# seeker_omni/model/norm.py
import torch
from torch import nn

class RMSNorm(nn.Module):
 def __init__(self, dim, eps=1e-5):
 super().__init__()
 self.eps = eps
 self.weight = nn.Parameter(torch.ones(dim))

 def forward(self, x):
 scale = torch.rsqrt(x.pow(2).mean(dim=-1, keepdim=True) + self.eps)
 return (x * scale) * self.weight

在编写自注意力层之前，我们还需要先实现它的一个旋转位置编码。由于我们使用了早融合机制将图像作为特征序列插入文本，为了让整个序列的长距离注意力衰减保持绝对一致，我们在 model 目录下新建 rope.py 来专门处理位置编码的生成与应用。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# seeker_omni/model/rope.py
import torch
from torch import nn

def _build_rope_cache(seq_len, dim, theta):
 # 构建复数域的旋转角度缓存矩阵
 inv_freq = 1.0 / (theta ** (torch.arange(0, dim, 2).float() / dim))
 positions = torch.arange(seq_len, dtype=torch.float32)
 freqs = torch.einsum("i,j->ij", positions, inv_freq)
 return torch.cos(freqs), torch.sin(freqs)

def apply_rope(x, cos, sin):
 # 将预计算好的 cos 和 sin 旋转矩阵作用到张量的奇偶维度上
 x_even = x[..., 0::2]
 x_odd = x[..., 1::2]

 cos = cos[None, None, :, :]
 sin = sin[None, None, :, :]

 out_even = x_even * cos - x_odd * sin
 out_odd = x_even * sin + x_odd * cos
 return torch.stack((out_even, out_odd), dim=-1).flatten(-2)

然后，我们需要新建 attention.py，来编写自注意力机制 SeekerSelfAttention。为了兼顾训练与推理的性能，我们在此类中引入分组查询注意力以成倍缩减显存开销，并直接内嵌对流式长文本生成的底层支持，即在每层实时计算并拼接 KV Cache。对于输入特征的位置标识，我们还需应用旋转位置编码技术，使模型即使在处理变长上下文时也能准确捕捉词汇相对距离。同时，注意力缩放点积计算，我们可以直接调用 PyTorch 原生集成在后端的 Flash Attention 算子（F.scaled_dot_product_attention），以缓解大矩阵内存读写的瓶颈。下面是这一核心流程的代码构建：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


# seeker_omni/model/attention.py
import torch.nn.functional as F
from .rope import apply_rope

class SeekerSelfAttention(nn.Module):
 def __init__(self, hidden_size, num_heads, num_kv_heads, dropout=0.0):
 super().__init__()
 # ... 维度整除校验等省略 ...
 self.hidden_size = hidden_size
 self.num_heads = num_heads
 self.num_kv_heads = num_kv_heads
 self.head_dim = hidden_size // num_heads

 # 分组查询注意力（GQA）投影层
 q_out = num_heads * self.head_dim
 kv_out = num_kv_heads * self.head_dim
 self.q_proj = nn.Linear(hidden_size, q_out, bias=False)
 self.k_proj = nn.Linear(hidden_size, kv_out, bias=False)
 self.v_proj = nn.Linear(hidden_size, kv_out, bias=False)
 self.o_proj = nn.Linear(q_out, hidden_size, bias=False)

 def forward(self, x, *, cos, sin, attention_mask=None, past_kv=None, use_cache=False):
 bsz, seq_len, _ = x.shape

 # 1. 投影并重塑维度: [B, H, S, D]
 q = self.q_proj(x).view(bsz, seq_len, self.num_heads, self.head_dim).transpose(1, 2)
 k = self.k_proj(x).view(bsz, seq_len, self.num_kv_heads, self.head_dim).transpose(1, 2)
 v = self.v_proj(x).view(bsz, seq_len, self.num_kv_heads, self.head_dim).transpose(1, 2)

 # 2. 对 Q 和 K 注入 RoPE 旋转位置编码
 q = apply_rope(q, cos, sin)
 k = apply_rope(k, cos, sin)

 # 3. 如果使用 KV Cache，则与历史缓存进行维度拼接
 if past_kv is not None:
 past_k, past_v = past_kv
 k_all = torch.cat([past_k.to(k.dtype), k], dim=2)
 v_all = torch.cat([past_v.to(v.dtype), v], dim=2)
 else:
 k_all, v_all = k, v

 # 4. GQA：将 K, V 的头数广播扩展至与 Q 一致
 if self.num_kv_heads != self.num_heads:
 repeat = self.num_heads // self.num_kv_heads
 k_rep = k_all.repeat_interleave(repeat, dim=1)
 v_rep = v_all.repeat_interleave(repeat, dim=1)
 else:
 k_rep, v_rep = k_all, v_all

 # 5. 求解自回归掩码与 Padding 掩码偏差（attn_bias）的逻辑省略 ...
 attn_bias = None

 # 6. 调用 PyTorch 原生的 Flash Attention / 缩放点积注意力加速计算
 out = F.scaled_dot_product_attention(
 q, k_rep, v_rep,
 attn_mask=attn_bias,
 dropout_p=self.dropout if self.training else 0.0,
 is_causal=False, # 手动传入掩码时需关闭原生 causal 标志
 )

 # 6. 维度还原与输出投影
 out = out.transpose(1, 2).contiguous().view(bsz, seq_len, -1)
 out = self.o_proj(out)

 if use_cache:
 return out, (k_all, v_all)
 return out

然后我们需要新建 mlp.py 来实现带门控结构的前馈神经网络 SeekerMLP。这里我们选择使用表现更优的 SwiGLU（SiLU + Gate）激活机制。为了配合门控机制的矩阵乘法，网络中需要设置平行的 w_gate 和 w_up 两个上采样投影层，以及一个下采样投影层 w_down。同时为了保持参数量水平，中间隐藏层维度（intermediate_size）默认会按照隐藏层的 $\frac{8}{3}$ 比例进行缩放并向上取整到 64 的倍数，以获得硬件计算上的最佳内存对齐效率。下面是包含这一完整结构的代码实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# seeker_omni/model/mlp.py
import torch
import torch.nn.functional as F
from torch import nn

def _round_up(x, multiple):
 # 向上取整到 multiple 的倍数，用于硬件显存对齐
 return ((x + multiple - 1) // multiple) * multiple

class SeekerMLP(nn.Module):
 def __init__(self, hidden_size, intermediate_size=None, dropout=0.0):
 super().__init__()
 # 如果未指定中间层维度，则默认缩放为 8/3 并对齐 64
 if intermediate_size is None:
 intermediate_size = int(hidden_size * 8 / 3)
 intermediate_size = _round_up(intermediate_size, 64)

 # SwiGLU 需要平行的 Gate 和 Up 两个上采样矩阵
 self.w_gate = nn.Linear(hidden_size, intermediate_size, bias=False)
 self.w_up = nn.Linear(hidden_size, intermediate_size, bias=False)
 self.w_down = nn.Linear(intermediate_size, hidden_size, bias=False)
 self.dropout = dropout

 def forward(self, x):
 # 将门控输出经过 SiLU 后与 Up 输出逐元素相乘
 x = F.silu(self.w_gate(x)) * self.w_up(x)
 x = self.w_down(x)
 return F.dropout(x, p=self.dropout, training=self.training)

3.5 组装统一的主干网络

文本词表嵌入机制、视觉投影机制以及 Transformer 解码块都准备就绪后，我们回到刚才创建的 lm.py 文件中，看看真正的早融合（Early Fusion）是如何在自回归主干流中发生的。在 SeekerOmniLM 类中继续补全前向传播方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# seeker_omni/model/lm.py

class SeekerOmniLM(nn.Module):
 def __init__(self, cfg):
 super().__init__()
 self.cfg = cfg
 # ... 前文已初始化的特殊文本嵌入层等代码 (此处略)

 # 初始化模态投影层与门控
 self.img_proj = nn.Linear(cfg.image_feat_dim, cfg.hidden_size, bias=False)
 self.img_gate = nn.Parameter(torch.zeros(cfg.hidden_size))

 # 初始化旋转位置编码与自注意力解码块序列
 head_dim = cfg.hidden_size // cfg.num_heads
 self.rope = RotaryEmbedding(dim=head_dim, max_seq_len=cfg.max_seq_len, theta=cfg.rope_theta)
 self.blocks = nn.ModuleList([
 SeekerBlock(
 cfg.hidden_size,
 cfg.num_heads,
 cfg.num_kv_heads,
 dropout=cfg.dropout,
 intermediate_size=cfg.mlp_intermediate_size,
 ) for _ in range(cfg.num_layers)
 ])

 self.norm = RMSNorm(cfg.hidden_size)

 def forward(self, input_ids, image_feats=None, **kwargs):
 # 1. 文本 Token 化为词汇嵌入矩阵
 x = self._embed_tokens(input_ids)

 # 2. 模态特征注入: 使用 Projector 将视觉特征注入到指定的图像占位符位置
 x = self._inject_modality_tokens(x, input_ids=input_ids, image_feats=image_feats)
 x = self.drop(x)

 # 3. 准备 RoPE 旋转位置编码
 seq_len = int(input_ids.shape[1])
 cos, sin = self.rope.get_cos_sin(seq_len) # 省略对具体最大序列长度和精度的适配

 # 4. 逐层通过标准的 Transformer Decoder Blocks 进行自注意力推理
 present_kv = [] if use_cache else None

 for i, block in enumerate(self.blocks):
 if use_cache:
 pkv = past_kv[i] if past_kv is not None else None
 x, kv = block(x, cos=cos, sin=sin, attention_mask=attention_mask, past_kv=pkv, use_cache=True)
 present_kv.append(kv)
 else:
 x = block(x, cos=cos, sin=sin, attention_mask=attention_mask)

 # 5. 计算最后的输出与 LM Loss
 x = self.norm(x)
 logits = F.linear(x, self._lm_head_weight())

 # 返回带分布概率的 Logits 和更新后的 KV 缓存
 return SeekerOmniOutput(logits=logits, loss=loss, kv_cache=present_kv) # 封装为 dataclass，省略损失计算部分

现在一套完整的前向传播链路就初步搭建出来了。但对于一个大语言模型来说，光有 forward 计算特征和损失还不够，我们还必须为它编写一套能够自回归生成回答的推理循环机制。因为大模型生成文本是一个“逐字往外蹦”的过程，如果没有 KV Cache，模型每次生成一个新词都需要把前面成百上千个历史词元重新计算一遍注意力，这在计算量上很不划算。所以，我们在 lm.py 的最后，补全用于文本生成的 generate_text 方法。需要利用我们在前向传播中预留的 use_cache 开关与 past_kv 管道，实现 Prefill（预填充） + Decode（解码） 两阶段加速生成流。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


# seeker_omni/model/lm.py

class SeekerOmniLM(nn.Module):
 # ...

 @torch.no_grad()
 def generate_text(self, input_ids, image_feats=None, max_new_tokens=64, eos_id=None, **kwargs):
 self.eval()
 out = input_ids
 prompt_len = out.shape[1]

 # ==========================================
 # 阶段一：Prefill (预填充阶段)
 # 一次性将完整的 Prompt 送入模型，提取并保存其 KV Cache
 # ==========================================
 # ... 省略 prefill_chunk_size 分块处理超长 Prompt 的支持逻辑
 out_prefill = self.forward(
 out,
 image_feats=image_feats,
 past_kv=None, # 第一步没有历史缓存
 use_cache=True,
 position_offset=0
 )

 # 提取出 Prompt 最后一个 Token 的预测 Logits，以及这一长串的 KV 缓存
 logits_prev = out_prefill.logits[:, -1, :]
 past_kv = out_prefill.kv_cache

 # ==========================================
 # 阶段二：Decode (解码阶段)
 # 拿着 Prefill 吐出来的最后一个 Token，逐字自回归生成
 # ==========================================
 # ... 省略针对控制占位符的禁止生成列表 (forbid_ids) 的构建逻辑

 for _ in range(max_new_tokens):
 # ... 省略 Repetition Penalty (重复惩罚) 与 No-Repeat N-Gram 过滤逻辑

 # 1. 采样：本例采用最简单的贪心解码 (Greedy Decoding) 取概率最大的词
 # ... 省略 Temperature, Top-P, Top-K 分布采样逻辑
 next_id = torch.argmax(logits_prev, dim=-1, keepdim=True)

 # 将新生成的词拼接到最终输出序列中
 out = torch.cat([out, next_id], dim=1)

 # 如果碰到了终止符 EOS，立刻提前退出生成循环
 if eos_id is not None and torch.all(next_id.squeeze(-1) == int(eos_id)):
 break

 # 2. 状态更新：带着上一步吐出的*单个新词*和*庞大的历史缓存*再次进入模型
 out_step = self.forward(
 next_id, # 注意！这里输入的长度只有 1
 image_feats=image_feats,
 past_kv=past_kv, # 将上一轮积累的缓存喂给当前层
 use_cache=True,
 position_offset=past_kv[0][0].shape[2] # 偏移量即为当前缓存的长度
 )

 # 更新缓存，为下一次循环做准备
 past_kv = out_step.kv_cache
 logits_prev = out_step.logits[:, -1, :]

 return out

至此，我们多模态的底层架构 lm.py 就实现闭环了。它不仅能接收图文混合排列的标记序列进行并行训练（forward），还能在推理阶段利用增量缓存成倍加速对话生成的响应速度（generate_text）。

3.6 封装训练循环

完成了所有的架构拼装之后，我们下一步要做的就是实现整体训练流程。不过，在开始写训练循环之前，还需要先在 seeker_omni 下新建一个 dataset 目录，来进行数据方面的一些处理。在预训练和普通指令微调阶段，为了最大化显卡的计算吞吐率，我们这套框架采用了全离线的数据处理策略。要求所有的文本都提前被切成 Token，还有图片也提前被视觉模型抽成特征，一起固化成底层的二进制文件（.bin）。所以，我们得编写一个 MemmapDataset，通过内存映射技术，让 GPU 在训练时能极其高效地将文本的 Token 序列和预先提取好的图像特征直接吸入显存。具体实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# seeker_omni/dataset/memmap.py
import numpy as np

class MemmapDataset:
 def __init__(self, data_dir):
 # ... 读取元数据
 self._input_ids = np.memmap(data_dir / "input_ids.bin", dtype=np.int32, mode="c", shape=(n, s))
 self._labels = np.memmap(data_dir / "labels.bin", dtype=np.int32, mode="c", shape=(n, s))
 self._attn = np.memmap(data_dir / "attention_mask.bin", dtype=np.uint8, mode="c", shape=(n, s))
 self._image_feats = np.memmap(data_dir / "image_feats.bin", dtype=np.float16, mode="c", shape=...)

 def __getitem__(self, idx: int):
 import torch
 # 将磁盘映射数据零拷贝搬往 Tensor
 out = {
 "input_ids": torch.from_numpy(self._input_ids[idx]),
 "labels": torch.from_numpy(self._labels[idx]),
 "attention_mask": torch.from_numpy(self._attn[idx]),
 "image_feats": torch.from_numpy(self._image_feats[idx])
 }
 return out

打通了数据加载后，我们就可以继续在 seeker_omni 中新建一个专门用于存放训练模块的 train 文件夹。首先，我们先在该文件夹中创建 loop.py，它将包含驱动模型参数更新的 train() 大循环。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


# seeker_omni/train/loop.py

# ... 前置的导包与辅助函数（代码细节已省略）：
# 1. _prepare_batch：负责将纯文本和图文 Batch 动态推入显存；若无填充词，机智抛弃注意力掩码以触发底层 Flash Attention 加速。
# 2. _corrupt_answer_tokens_for_mm：多模态强力去依赖机制；在监督对的答案开头强制注入 UNK 掩码，断刷语言模型的续写本能，逼迫其观察视觉特征。
# 3. _adamw_param_groups：精细化权重衰减控制器；不对视觉门控矩阵、词表和归一化层施加脆弱的 L2 正则约束。
# --------------------------------------------------------------------------

def train(cfg: ExperimentConfig) -> None:
 device = torch.device(cfg.train.device)
 dtype = torch.float16 if cfg.train.dtype == 'fp16' else torch.bfloat16

 # ... 环境变量与混合数据集对象读取逻辑省略 ...

 # 1. 实例化自回归语言模型，并强制应用多阶段冻结策略
 # 此步骤极为关键：例如在 s1 阶段它只会解冻 Projector 投影层，冻结其它一切参数
 model = SeekerOmniLM(cfg.model).to(device)
 apply_stage_freeze(model, cfg.train)

 # 2. 构造优化器与半精度损失梯度缩放器
 opt = torch.optim.AdamW(_adamw_param_groups(model, weight_decay=cfg.train.weight_decay), lr=cfg.train.lr)
 scaler = torch.amp.GradScaler(device.type, enabled=(device.type == 'cuda' and dtype == torch.float16))

 # 3. 正式开启工业级训练单步大循环
 while step < int(total_steps):
 step += 1

 # 4. 动态学习率调度
 lr = cosine_lr(step, base_lr=cfg.train.lr, total_steps=int(total_steps), warmup_steps=cfg.train.warmup_steps)
 for g in opt.param_groups:
 g['lr'] = lr

 # 2. 从多个数据集中按权重混采数据
 batch, src = next_mixed_batch()
 input_ids, labels, attention_mask, image_feats = _prepare_batch(batch, device=device)

 # 3. 多模态教师强制扰动：降低对“标准答案前缀”的依赖，逼迫模型看图
 if image_feats is not None:
 input_ids = _corrupt_answer_tokens_for_mm(
 input_ids, labels,
 unk_id=int(model.special.unk), n_special=int(model.n_special),
 )

 # 4. 混合精度（FP16/BF16）前向传播，狂省显存
 with torch.autocast(device_type=device.type, dtype=dtype):
 out = model(
 input_ids,
 attention_mask=attention_mask,
 labels=labels,
 image_feats=image_feats,
 )

 # 开启梯度累加（Gradient Accumulation），单次 Loss 除以累加步数
 loss = out.loss / cfg.train.grad_accum

 # 5. 反向传播与梯度缩放（防止半精度下溢）
 if scaler.is_enabled():
 scaler.scale(loss).backward()
 else:
 loss.backward()

 # 6. 当累加步数凑齐了 batch_size 倍数时，执行真更新
 if step % cfg.train.grad_accum == 0:
 if scaler.is_enabled():
 scaler.unscale_(opt)

 # 梯度裁剪：防止突发的坏数据导致梯度爆炸毁掉整个模型
 torch.nn.utils.clip_grad_norm_(params, cfg.train.grad_clip)

 # 更新权重并清零梯度
 if scaler.is_enabled():
 scaler.step(opt)
 scaler.update()
 else:
 opt.step()
 opt.zero_grad(set_to_none=True)

 # ... 后续的 TensorBoard 记录与保存断点逻辑省略 ...

可以看到，在 train() 里面我们调用了一个叫 apply_stage_freeze 的函数。多模态大模型的训练中，“什么时候该冻结什么参数” 甚至比“怎么写 Loss”还要重要。如果不加选择地将一个好不容易预训练聪明的 LLM 底座与一个随机初始化的视觉投影层一起放开训练，激烈的梯度更新会在第一个 Epoch 就摧毁大语言模型原有的文本能力（灾难性遗忘）。所以，我们需要在 seeker_omni/train/freezing.py 中编写一套实用的参数冰冻术。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


# seeker_omni/train/freezing.py
from ..config import TrainConfig
from ..model.lm import SeekerOmniLM

def apply_stage_freeze(model: SeekerOmniLM, train_cfg: TrainConfig) -> None:
 # 默认放开所有参数的梯度
 for p in model.parameters():
 p.requires_grad = True

 # 1. 冻结语言模型底座（对齐阶段的常规操作，只练 Projector）
 if train_cfg.freeze_backbone:
 for p in model.blocks.parameters():
 p.requires_grad = False
 for p in model.norm.parameters():
 p.requires_grad = False
 for p in model.base_embed.parameters():
 p.requires_grad = False

 # 即使冻结底座，也可以选择性地放开最后 N 层 Transformer 
 # 用于承担更深度的多模态特征融合
 unfreeze_last_n = int(train_cfg.unfreeze_last_n_layers or 0)
 if unfreeze_last_n > 0:
 n = min(unfreeze_last_n, len(model.blocks))
 for blk in model.blocks[-n:]:
 for p in blk.parameters():
 p.requires_grad = True
 for p in model.norm.parameters():
 p.requires_grad = True

 # 2. 独立冻结词表与特殊占位符
 if train_cfg.freeze_base_embed:
 for p in model.base_embed.parameters():
 p.requires_grad = False
 if train_cfg.freeze_special_embed:
 for p in model.special_embed.parameters():
 p.requires_grad = False

除了 freezing.py 和 loop.py，我们其实还需要 lr.py（学习率调度）、checkpoint.py（断点保存与加载）以及 seed.py（随机种子设置）。这些都是标准的深度学习工程化模板代码，这里就不再赘述。

拥有了这套单步训练引擎后，我们可以回过头来对“纯文本预训练 -> 指令微调 -> 多模态对齐”这三个训练阶段进行统一管理。为了将这些零散的阶段无缝串联起来，我们在 seeker_omni 中再新建一个用于总体编排的 steps 目录，并在其中编写最外层入口脚本 train.py。这个脚本将作为多阶段总控调度器，它的作用是读取一系列连贯的阶段配置文件，并将上一个阶段引擎跑出来的最终 Checkpoint 权重，自动喂给下一个阶段作为初始权重：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# seeker_omni/steps/train.py
def run(cfg):
 cfg_paths = [str(x) for x in cfg["configs"]]
 prev_cfg = None

 # 循环遍历每一个训练阶段的配置文件
 for i, cfg_path in enumerate(cfg_paths):
 exp = ExperimentConfig.load(cfg_path)

 # ... （省略部分容错检查、第一阶段 init_from 处理以及日志打印代码）

 # 核心逻辑：自动去上一个阶段的输出目录里找最新的权重，作为本阶段起点
 if i > 0 and auto_init and prev_cfg is not None:
 prev_ckpt = latest_checkpoint(prev_cfg.train.out_dir)

 # 若本阶段未显式指定起点，则接力加载上一阶段的存档
 cur_init = exp.train.init_from
 if cur_init is None or not Path(cur_init).exists():
 exp = replace(exp, train=replace(exp.train, init_from=prev_ckpt))

 # 将最新的配置送入底层 loop.py 训练引擎开始单步训练
 # ... （省略 set_seed 等细节操作）
 train(exp)
 prev_cfg = exp

通过上述的 steps/train.py 调度器，我们已经顺利串联起了文本预训练和指令微调。到目前为止，整个工程里还缺少的最后一个阶段就是多模态对齐。但在正式开始编写这部分代码之前，我们不妨先把现有的基础工程跑通。为了实现一键启动，我们需要在核心包目录下创建一个总管线脚本：seeker_omni/pipeline.py，把前面写好的纯文本阶段都打包统筹起来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# seeker_omni/pipeline.py
import os
from pathlib import Path

from .config import load_yaml

def _project_root():
 return Path(__file__).resolve().parents[1]

def _read_yaml(path):
 p = Path(path)
 return load_yaml(p)

def train():
 from .steps.train import run as train_run

 os.chdir(_project_root())
 print("== pipeline: train ==")
 cfg = _read_yaml("configs/train.yaml")
 train_run(cfg)
 return 0

回到 seeker_omni/steps 文件夹下，我们新建一个 e2e 文件夹，继续实现最后的对齐流程。在实现这部分内容之前，我们同样还需要来到 seeker_omni/dataset 文件夹下，新建一个 schema.py 文件，用来处理在线的动态图文数据流解析。端到端联合对齐的第一大挑战就是数据加载方式的转变。在先前的 train 循环中，由于不用加载视觉模型，我们为了速度读取 memmap.py 喂的离线 .bin 数组。但在真正的端到端联合对齐阶段，模型需要自由调配图文混采比例，此时就必须抛弃固化的离线特征，转为从原始的 .jsonl 语料文件中逐行流式解析指令文本，并实时提取真实图片的本地路径：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# seeker_omni/dataset/schema.py
import json
from pathlib import Path

class RawSample:
 def __init__(self, id, system, prompt, answer, image):
 self.id = id
 self.system = system
 self.prompt = prompt
 self.answer = answer
 self.image = image

def iter_jsonl(path):
 p = Path(path)
 with p.open("r", encoding="utf-8-sig") as f:
 for line_no, line in enumerate(f, start=1):
 line = line.strip()
 if not line:
 continue
 try:
 obj = json.loads(line)
 except json.JSONDecodeError as e:
 raise ValueError(f"invalid json at line {line_no}: {p}") from e

 yield RawSample(
 id=str(obj.get("id", f"line-{line_no}")),
 system=obj.get("system"),
 prompt=str(obj.get("prompt", "")),
 answer=str(obj.get("answer", "")),
 image=obj.get("image"),
 )

补齐数据处理后，我们就可以将目光切回刚才新建的 steps/e2e 文件夹，来实现最终的对齐脚本 runner.py。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# seeker_omni/steps/e2e/runner.py
import torch
# ... (省略引包和 Dataset 初始化的逻辑) ...

def run_from_yaml_config(cfg):
 # 1. 恢复我们在上一阶段微调好的 LLM 主模型
 model = SeekerOmniLM(cfg.model).to(device)
 # ... 

 # 2. 加载 SigLIP 视觉模型
 from transformers import SiglipVisionModel
 vision = SiglipVisionModel.from_pretrained(args.vision_model).to(device)

接下来我们就要处理端到端的对齐，为了在不毁灭视觉模型原有认知的情况下解锁深层能力，不能靠无脑的全局梯度更新。我们需要依赖两项精细的手术，分别是局部解冻（只放开最后几层）和特征蒸馏（用原版模型约束行为）。我们 runner.py 的同级目录下新建两个扩展组件 vision.py 用于负责从本地加载原始 RGB 图片，并提供一个函数用来冻结视觉模型绝大多数的层，仅放开最后 $N$ 层：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# seeker_omni/steps/e2e/vision.py
import torch
import torch.nn.functional as F
from PIL import Image

def load_rgb(path):
 img = Image.open(path)
 if img.mode in ("RGBA", "LA"):
 img = img.convert("RGB")
 return img

def pool_tokens_torch(x, *, target_tokens):
 # [B, T, D] -> [B, target, D] 池化压缩视觉 Token
 if int(x.shape[1]) == int(target_tokens):
 return x
 t = x.transpose(1, 2)
 return F.adaptive_avg_pool1d(t, int(target_tokens)).transpose(1, 2)

def freeze_vision_all_but_last_n(vision, *, last_n):
 for p in vision.parameters():
 p.requires_grad = False

 n = int(last_n)
 if n <= 0:
 return

 # 仅解冻最后 n 层 Transformer 块的参数
 vm = getattr(vision, "vision_model", vision)
 layers = getattr(vm.encoder, "layers", None)
 for layer in list(layers)[-n:]:
 for p in layer.parameters():
 p.requires_grad = True

 # 别忘了还有最后的 LayerNorm 层
 pln = getattr(vm, "post_layernorm", None)
 if pln is not None:
 for p in pln.parameters():
 p.requires_grad = True

紧接着，为了防止这刚解冻就被卷入剧烈更新的最后 $N$ 层彻底“放飞自我”、遗忘掉原本优秀的特征提取能力，我们再新建一个 distill.py 脚本文件。它利用最简单的 MSE 均方误差，计算正在训练的学生视觉特征与一个被完全冻死在原始状态的老师视觉特征之间的差距，作为正则化惩罚项：

1
2
3
4
5
6


# seeker_omni/steps/e2e/distill.py
import torch
import torch.nn.functional as F

def mse_distill(student_hidden, teacher_hidden):
 return F.mse_loss(student_hidden.float(), teacher_hidden.float())

完成这两个组件的编写之后，我们切回 runner.py 接着往下写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# seeker_omni/steps/e2e/runner.py
from transformers import SiglipVisionModel

def run_from_yaml_config(cfg):
 # ... (省略 LLM 与主视觉模型加载代码) ...

 # 实例化主视觉编码器，并动态解冻最后 N 层
 vision = SiglipVisionModel.from_pretrained(args.vision_model).to(device)
 if int(args.vision_train_last_n) > 0:
 freeze_vision_all_but_last_n(vision, last_n=int(args.vision_train_last_n))

 # 引入处于完全冻结状态的教师视觉模型
 teacher_vision = None
 if float(args.vision_distill_weight) > 0.0 and (not bool(args.freeze_vision)):
 teacher_vision = SiglipVisionModel.from_pretrained(args.vision_model).to(device)
 teacher_vision.eval()
 for p in teacher_vision.parameters():
 p.requires_grad = False

 # ... (省略进入核心的大循环逻辑) ...
 # ... 以下为在训练大循环 (Train Loop) 中计算蒸馏损失的部分：

 if has_image:
 vout = vision(pixel_values=px)
 hs = vout.last_hidden_state

 # 与教师模型的输出特征进行 MSE 蒸馏，防止视觉特征遗忘
 if teacher_vision is not None:
 with torch.no_grad():
 tout = teacher_vision(pixel_values=px)
 ths = tout.last_hidden_state
 distill_loss = mse_distill(hs, ths)

在上述端到端的实现中，通过 freeze_vision_all_but_last_n 解冻视觉网络最后的数层计算图，使得视觉编码器能够直接接收来自大语言模型的梯度回传。同时，为了防止解冻后的视觉网络在语言梯度的更新中“遗忘”原本优秀的识图能力，代码中引入了一个完全冻结的同构 teacher_vision 模型。在每步的前向传播中，都会计算当前解冻视觉层与教师模型输出特征之间的均方误差，将其作为蒸馏损失加入到总 Loss 中，以此在联合演化的同时保住视觉模型的性能底线。 runner.py 完成后，我们回到 seeker_omni/pipeline.py，把最后对齐阶段的调用给组装上，并写一个 run_all() 把整个流程串起来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# seeker_omni/pipeline.py

import os
from pathlib import Path

# ... (省略 _read_yaml, _project_root 等帮助函数) ...

def train():
 # ... (省略上文已实现的纯文本阶段管线)
 pass

def e2e():
 from .steps.e2e.runner import run_from_yaml_config

 os.chdir(_project_root())
 print("== pipeline: e2e ==")
 cfg = _read_yaml("configs/e2e.yaml")
 run_from_yaml_config(cfg)
 return 0

def run_all():
 train()
 e2e()
 return 0

那么现在全部的核心内容我们就写完了。接下来，只需要在相关模块里补齐工程化的封装收口（例如通过 __init__.py 暴露对外 API、在 __main__.py 中提供 python -m ... 的启动入口，并将训练阶段的参数收拢到 config.py / YAML 等配置文件中统一管理），就可以使用 uv run python -m seeker_omni 命令将整套训练跑起来了。

图文多模态之原生统一架构

Fri, 27 Mar 2026 22:40:25 -0800

图文多模态之原生统一架构

上节我们介绍了以 BLIP-2 和 LLaVA 为代表的“连接”方法。这类方法通过轻量级适配模块连接冻结的视觉编码器与 大语言模型，虽极大降低了训练成本，但底层模态的分离和输入端的生硬拼接限制了其在实时音频/视频交互等场景下的表现。为了突破这些局限，学术界与工业界正加速向原生统一的架构演进。

一、迈向统一的探索

1.1 Flamingo 架构设计

DeepMind 在 2022 年提出的 Flamingo ¹ 虽然在时间上早于 BLIP-2，但在多模态的大一统进程中占据了独特的生态位。不同于 BLIP-2 和 LLaVA 追求的“利用现有组件高效连接”，Flamingo 探索的是大规模图文交错序列（Interleaved Image-Text）的学习极限。在架构演进的视角下，它事实上构成了从“简单连接”向“原生统一”进化的关键过渡形态。其核心架构目标是桥接强大的预训练视觉模型和大型语言模型（LLM），在保留它们各自预训练知识的同时，成功实现了在极少样本情况下对**任意交错（Interleaved）**图像和文本序列的处理能力。为了实现这一目标，Flamingo 采用了如图 20-7 所示的架构。

图 20-7 Flamingo 架构

可以看到图中的图像数据会先通过左侧的视觉路径进行视觉编码（Vision Encoder）和重采样（Perceiver Resampler），生成固定长度的视觉特征。接着，这些特征被注入到右侧的语言路径中，通过插入在 LLM 层间的门控交叉注意力接口（Gated XATTN-DENSE）参与文本生成。为了支撑这一跨模态流转过程，Flamingo 设计了以下三个关键组件：

（1）视觉感知与特征重采样

Flamingo 使用 NFNet-F6 作为冻结的视觉编码器，提取图像或视频的特征。由于视觉输入的分辨率和视频帧数可能不同，导致特征图的大小和数量也是变化的。为了将这些变长的视觉特征统一为固定长度的输入，Flamingo 引入了 Perceiver Resampler 模块。该模块预定义了一组固定数量的可学习的潜在查询向量（Latent Queries），通过 Cross-Attention 机制与视觉特征交互，最终输出固定数量的视觉 Token（论文中为 64 个）。这种设计不仅显著降低了视觉-文本 Cross-Attention 的计算开销，也通过“压缩视觉 token 数量”的方式在实践中缓解了 Transformer 随序列长度增长带来的 $O(N^2)$ 计算/显存压力（严格来说并非“消除” $O(N^2)$，而是让 $N$ 不至于被视觉 token 拉得过大）。结合图 20-8 所示，Perceiver Resampler 会先将 Vision Encoder 输出的变长视觉特征（$X_f$）展平。对于视频输入，Flamingo 会在展平前为每一帧特征加入可学习的时间嵌入；同时作者也明确指出未显式加入空间网格位置编码（空间信息更多由 CNN 特征隐式携带）。这里的 Key 和 Value 在论文的示意与伪代码中可以由时空视觉特征 $X_f$ 与 learned latent vectors 拼接而成。也就意味着 Latent Queries 在通过 Attention 机制“查询”视觉信息时，不仅关注图像特征，也在“参考”自身的当前状态，继而保持了特征提取的连贯性。随后，这些 Latent Queries 主动去“查询”视觉特征中包含的关键信息，无论输入视觉特征序列有多长（单图或多帧视频），最终都只输出与 Latent Queries 数量一致的定长视觉 Token。通过这种机制，海量的视觉数据被高效地压缩成了少量的定长 Token 序列，供后续 LLM 使用。

图 20-8 Perceiver Resampler 机制

（2）视觉信息注入与门控机制

为了将视觉信息有效注入预训练且冻结的语言模型（Chinchilla）中，Flamingo 在其层间插入了 GATED XATTN-DENSE 模块。如图 20-9 所示，该模块以语言特征（Language input）作为 Query，以 Perceiver Resampler 输出的视觉特征（Vision input）作为 Key 和 Value，通过交叉注意力机制让语言模型主动从视觉序列中提取相关信息。为了维持冻结 LLM 原有的语言能力，Cross-Attention 和随后的 FFW 层均配置了 tanh 门控机制（tanh gating），这些门控参数在初始化时设为 0，确保模型在训练初期表现为纯语言模型，避免了视觉噪声冲击导致的训练不稳定。随着训练的进行，门控值逐渐增大，视觉信息以残差连接的方式“平滑”地融入语言特征流中。这种设计不仅防止了灾难性遗忘，还让模型能够通过交错的 Self-Attention 和 Cross-Attention 层，在保持语言逻辑的同时实现深度的多模态对齐。

图 20-9 Gated Cross-Attention

（3）多图支持与掩码策略

为了支持任意数量的图像/视频输入，Flamingo 在 Masked Cross-Attention 层采用了特殊的分段掩码策略。如图 20-10 所示，这种策略实施了严格的局部关注，即每个文本 Token 仅被允许关注其直接前导的那一张图像（由指示函数 $\phi$ 决定），而不是所有历史图像。例如，图中标记为 1 的文本段只能看到 Image 1，而无法看到 Image 2 或其他图像。具体而言，图中亮蓝色区域代表允许文本 Token 关注的视觉特征，而深色区域则代表被屏蔽的部分。这种设计限制了单次交叉注意力的计算复杂度，防止模型被无关图像干扰。虽然 Cross-Attention 层只关注局部，但跨图像的长程依赖被交给底层的 LM Self-Attention，通过文本 Token 作为中介，间接实现了多图信息的融合。基于这一机制，Flamingo 能够高效处理包含多达 32 对图文的 Few-Shot Prompt，展示了强大的上下文学习能力。

图 20-10 多模态掩码注意力

1.2 局限性与思考

Flamingo 强大的少样本能力很大程度上归功于它的训练数据。DeepMind 构建了 M3W (Multi-Modal Massive Web) 数据集，包含从 4300 万个网页中提取的图文交错序列（如：文本-图像-文本）。这种结构模拟了人类浏览网页的真实体验，使模型学会了根据上下文预测下一个 Token。而且，为了兼顾通用的视觉识别能力，Flamingo 还混合使用了传统的强对齐图文对数据集（ALIGN, LTIP）和视频文本对数据集（VTP），并通过加权损失函数进行联合训练。然而，Flamingo 仍然存在一些局限性。例如，相较于直接优化图文检索任务的 Contrastive 模型（如 CLIP），Flamingo 在单纯的图像分类任务表现稍逊，这可能源于其生成式目标的特性。同时，作为建立在 LLM 基础上的模型，Flamingo 继承了 LLM 的缺点，偶尔会产生幻觉或做出无根据的猜测。最关键的是，受限于当时的技术背景，Flamingo 依然保留了“冻结视觉编码器”这一连接范式的特征。虽然这种依赖冻结编码器的设计有助于保留预训练模型的通用能力，但也导致视觉和语言在底层特征空间上无法真正融合，细腻的视觉感知能力（如 OCR、细粒度识别）容易在层层传递中丢失。

二、Token 级统一与单一网络

为了彻底打破上述局限，Chameleon ² 和 GPT-4o ³ 等模型开启了纯粹的原生时代。严格意义上的“纯粹原生”指模型不再是“拼凑”出来的，它从一开始就将所有模态视为地位平等的“语言”，在同一个大模型中进行混合模态的端到端预训练。就像人类婴儿并非先学会“看”再学会“说”，而是在成长的过程中同时通过视觉、听觉和语言来感知世界一样，原生多模态模型试图模拟这种过程。在架构方面，模型彻底摒弃了独立的模态编码器，并将像素、波形和文本一视同仁地映射为 Token 或底层特征，直接送入同一个“大脑”（单一大模型网络）进行处理。

2.1 Chameleon 与统一词表

Meta AI 推出的 Chameleon 是“早期融合（Early-Fusion）”架构的典型代表。虽然在架构上进行了彻底的重构（不再依赖外挂的视觉编码器），但从数据层面来看，Chameleon 完美继承并发展了 Flamingo 最宝贵的遗产，也就是基于大规模“图文交错”数据的训练范式。它的理念非常激进，主张把一切都视为 Token。为了实践这一目标，Chameleon 在架构设计上进行了以下三个层面的创新：

（1）统一词表与离散化

Chameleon 使用一个名为 Gafni 的图像分词器将 $512 \times 512$ 的图像量化为 1024 个离散的 Image Tokens。这些视觉 Token 与文本 Token 并没有本质区别，它们共同组成了一个大小为 65,536 的统一词表（包含了 8192 个图像 Codebook Token）。这意味着在模型眼中，像素和文字都是来自同一个字典的“单词”。

（2）混合序列与端到端架构

在处理输入时，Chameleon 将图像 Token 和文本 Token 按照逻辑顺序拼接成一个混合模态序列（Mixed-Modal Sequence）。整个序列直接输入到一个统一的 Transformer 架构中。无论是理解还是生成，本质上都转化为了自回归的下一 Token 预测任务。这种架构极大地简化了流程，不再依赖外挂的视觉编码器或复杂的跨模态对齐模块。如图 20-11 所示，通过图像分词器（Image Tokenizer），图像被转化为与文本（绿色）地位平等的蓝色 Token，并在**边界符（Start/End Image）**的辅助下混合编排，真正实现了端到端的全原生多模态理解与生成。

图 20-11 Chameleon 混合模态序列

（3）攻克训练稳定性挑战

“从头开始”训练这样一个混合模态大模型面临着巨大的优化稳定性挑战（如模态间的竞争导致的 Logit 漂移）。为此，Chameleon 引入了一系列架构创新，包括 QK-Norm (Query-Key Normalization) 和特殊的层归一化布局。这些改进确保了模型能够在没有预训练视觉编码器“保底”的情况下，稳定地学习到跨模态的复杂依赖关系。图 20-12 通过三组实验揭示了稳定性问题的本质与解决方案。图 (a) 展示了在应用优化策略后，7B 和 34B 模型均能在混合模态数据上稳定收敛。图 (b) 则通过对比实验指出，图像生成任务（Image Generation）是导致不稳定的根源——当禁用图像生成时，Loss 曲线非常平滑，未出现发散。图 (c) 进一步验证了架构调整的有效性，单纯引入 Dropout 并不能解决发散问题（橙色曲线依然发散），而层归一化重排（Norm Reordering） 才是实现稳定训练的关键（蓝色曲线）。

图 20-12 Chameleon 训练稳定性实验

通过表 20-1 可以清楚地看到，Chameleon 7B 和 34B 在架构参数上与 LLaMa-2 总体保持一致（如 Context Length 和 GQA），但为了适应混合模态训练，其在优化策略上做出了明显调整，重点包括引入 Z-loss 和 QK-Norm，并将训练数据量提升到了 4.4T Token（约为 LLaMa-2 的两倍）。这种原生统一架构实现了真正的全模态理解与生成。模型可以在任意层级、任意位置进行模态间的推理，展现出惊人的上下文学习能力。然而，这种“原生”也是昂贵的。Chameleon 需要在包含约 10 万亿（10T） token 的混合数据上进行大规模预训练，且训练过程对超参数极度敏感。

Model	Params	Context	GQA	Tokens	LR	Epochs	Dropout	Z-loss	QK-Norm
LLaMA-1	7B	2k	x	1.0T	3.0e-4	1.0	0.0	0.0	x
LLaMA-1	33B	2k	x	1.4T	1.5e-4	1.0	0.0	0.0	x
LLaMA-2	7B	4k	x	2.0T	3.0e-4	1.0	0.0	0.0	x
LLaMA-2	34B	4k	✓	2.0T	1.5e-4	1.0	0.0	0.0	x
Chameleon	7B	4k	x	4.4T	1.0e-4	2.1	0.1	1e-5	✓
Chameleon	34B	4k	✓	4.4T	1.0e-4	2.1	0.0	1e-5	✓

表 20-1 Chameleon 架构参数与优化配置对比

2.2 GPT-4o 与全模态原生

在图文统一的基础上，GPT-4o (“o” 代表 Omni) 进一步打破了音频的边界，成为了纯粹原生全模态模型的标杆。根据 OpenAI 的公开介绍，在 GPT-4o 之前，语音模式是由三个独立模型组成的级联系统（ASR 转文本 -> LLM 处理文本 -> TTS 转语音）。对于 GPT-4o，OpenAI 跨文本、视觉和音频端到端地训练了一个单一的新模型，也就意味着所有的输入和输出都由同一个神经网络处理。这种纯粹的原生架构使 GPT-4o 能够直接感知语气、多个说话者、背景噪音，并输出带有情感的语音，在语音对话中甚至能达到最短约 232ms的响应延迟。

三、走向全能：端到端 Omni 系统的工业实践

虽然 Chameleon 和 GPT-4o 定义了“纯粹原生”的最终形态（单一网络、彻底的 Token 统一），但从头训练的成本极为高昂。在真实的工业界和开源社区中，更常见也更容易规模化落地的一条路线，是走向端到端紧耦合（End-to-End Tightly-Coupled）的 Omni 系统。这类系统（如 Qwen3-Omni ⁴ 和 MiniCPM-o 4.5 ⁵）严格来说不属于单一网络的原生架构，因为它们依然保留了专门的音频或视觉编码器。但它们打破了早期“冻结外挂”的连接范式，通过全参数解冻的端到端联合训练、深度的隐藏态耦合以及高速的流式架构，在体验上无限逼近了 GPT-4o 的实时语音交互。

3.1 解耦架构与流式生成

虽然 GPT-4o 的闭源策略让我们难以窥探其单一网络的内部细节，但 Qwen3-Omni 为这种“全能体验”的工业落地给出了可复现的系统级拆解。它不仅在文本和视觉任务上保持了与同系列单模态模型相当的性能，也在实时音频交互上展现了很高的工程水准。

（1）通用的听觉底座

不同于以往多模态模型常依赖 Whisper 等现成且冻结的 ASR 模型，Qwen3-Omni 采用了一个拥有约 6 亿参数的从头训练的 AuT（Audio Transformer） 音频编码器。如图 20-13 所示，AuT 采用了 Transformer 架构，包含 32 层 Encoder 和 8 层 Decoder。并在 2000 万小时的监督音频数据上进行了预训练，使它不仅能处理语音，还能理解环境音和音乐。在特征提取阶段，AuT 通过 3 层下采样卷积 将输入音频（10ms 帧移的 FBank 特征）在时间维度上压缩 8 倍，将特征采样率大幅降低至 12.5Hz（即每 80ms 一个 Token），实现了高效表征。同时，AuT 在 32 层 Encoder 中还引入了 分块窗口注意力 (Block-wise Window Attention) 机制，支持动态窗口大小，使得模型在实时流式输入时能高效地进行 Prefill（预填充），而无需等待整个音频片段。

图 20-13 Audio Transformer (AuT) 架构概览

（2）Thinker-Talker 混合专家架构与极致流式

Qwen3-Omni 采用了独特的 Thinker-Talker 双模型协作架构，并均升级为 MoE 以应对高并发需求。为了达成 234ms 的端到端延迟，这套架构结合了深度解耦与极速流式设计。主要分成 Thinker（思考者）和 Talker（表达者）两部分。其中，Thinker 是一个强大的多模态 MoE 模型，它主要负责“脑力”工作，也就是理解来自 AuT 的音频流、视觉编码器的视频流以及文本输入，进行深度推理，并生成文本回复或推理结果；Talker 则是一个专门的流式语音生成 MoE 模型，它不再直接消费 Thinker 的高层文本表征/文本 Token，而是接收 Thinker 输出的多模态高维表征，并共享对话历史。这种解耦设计赋予了 Talker 更高的灵活性，使它能专注于对齐语音的韵律、情感和语速，不必受制于语言模型的逐词生成节奏，各模块的具体参数配置如表 20-2 所示。

Module	Architecture	Params	Streaming
Audio Encoder	AuT	650M	✓
Vision Encoder	SigLIP2-So400M	540M	-
Thinker	MoE Transformer	30B-A3B	✓
Talker	MoE Transformer	3B-A0.3B	✓
MTP	Dense Transformer	80M	✓
Code2wav	ConvNet	200M	✓
First-Packet Latency	End-to-End	234/547ms (Audio/Video, cold start theoretical)	-

表 20-2 Qwen3-Omni 30B-A3B 架构参数与延迟概览

各组件的协同工作，实现了极其高效的端到端生成。如图 20-14 所示，为了实现极致流式，Thinker 模型首先处理多模态输入，生成高层语义表征；而后 Talker 接收这些表征并自回归地预测第 0 层（主）Codebook；紧接着，轻量级的 MTP 模块会快速预测同一帧中其余残差 Codebook。最后，所有层级的 Codebook 被送入 流式 Codec 解码器 (Streaming Codec Decoder)，逐帧流式地合成出波形。这一流程确保了模型不需要等待完整的句子甚至完整的词生成完毕，只要第一个 codec token 产生，声音就能立即被“流”出来。

图 20-14 Qwen3-Omni 架构概览

（3）三阶段训练策略

为了实现上述能力，Qwen3-Omni 还经历了三个关键的预训练阶段。在编码器对齐（Encoder Alignment）阶段，模型冻结 LLM，专注于训练 AuT 和视觉编码器的适配器，使其对齐到语言空间。进入通用预训练阶段后，全参数解冻，在包含 2 万亿 Token 的大规模多模态数据（文本、图像、音频、视频）上进行混合训练。而在**长上下文扩展（Long Context Stage）**阶段，序列长度被扩展至 32k，重点增强模型对长视频和长音频的理解能力。这一系列复杂的联合优化与流式调度证明，通过精巧的系统设计，模型完全可以在复用现成模块的同时，打破延迟瓶颈，兼顾强大的推理能力与毫秒级的交互响应。

3.2 全双工与端侧延伸

在 Omni 系统领域，除了追求模型体量和极致的理解能力，系统级的实时流式交互（全双工，Full-Duplex）和端侧部署成为了另一个重要的演进方向，开源社区的 MiniCPM-o 4.5 正是这一趋势的代表。以往的语音助手多采用“半双工”（你听我说，我说你听）或简单的打断机制，而 MiniCPM-o 4.5 实现了真正的“边听边想边说”。它能够在接收实时视频和音频输入流的同时，不阻塞地并行输出文本和语音流。得益于它底层将多模态数据流（并行输入/输出）在毫秒级时间轴上进行了精密的对齐与同步处理，使模型能在任意时刻主动决定是否发声，实现自然的“主动插话”和“响应打断”。如图 20-15 所示，模型会在 LLM 输出序列中插入 [silent] 占位 Token 以维持流式节拍，并将生成的 Token 与隐藏态 $h$ 一并送入语音 Token 解码器，产生 25Hz 的 speech tokens，由此在统一时间轴上对齐输入与输出，完成复杂的全双工调度。

图 20-15 MiniCPM-o 4.5 全双工流式对齐机制

尽管 MiniCPM-o 4.5 整合了视觉（SigLIP2）、听觉（Whisper-medium）、语音合成（CosyVoice2）以及大语言模型（Qwen3-8B），但这套架构被端到端地深度融合在了一起，整体参数量控制在 9B 左右。配合高效的模型量化（如 Int4 仅需 11GB 显存）和专属推理框架，它甚至能够在普通的个人电脑乃至手机上流畅运行全双工的音视频对话。这种在有限算力下逼近 GPT-4o 级别实时体验的设计，展现了端到端紧耦合架构在工程落地上的巨大潜力。

参考文献

图文多模态之BLIP-2 与 LLaVA

Fri, 27 Mar 2026 21:40:25 -0800

图文多模态之BLIP-2 与 LLaVA

一、从对齐到生成

1.1 如何高效构建多模态生成能力？

CLIP 通过对比学习让图像和文本在特征空间实现了对齐，但这仅仅完成了“理解”的第一步。作为典型的双塔判别式模型，CLIP 更擅长做“给定候选文本算相似度”的检索/分类式判断，而不是自由形式的文本生成；所以它不能像语言模型那样，直接对“画里有什么？”这类开放式问题给出自然语言答案。为了突破这一局限，我们需要赋予模型“开口说话”的能力，在强大的语义基础之上构建生成能力。为此，DeepMind 的 Flamingo ¹ 等先驱尝试了在冻结的视觉编码器与语言模型之间插入跨注意力等新模块，并在海量交错图文数据上训练这些新增模块以实现强大的生成与对话能力。虽然效果惊艳，但数据与训练成本并非普通实验室所能承受。

那不妨换个思路，既然我们手头已经有了“视觉地基”（ViT）和“语言大脑”（LLM），能不能只训练一个轻量级的“适配器”把它们连起来呢？Salesforce 提出的 BLIP-2 ² 正是这一思路的杰出代表。它采用 Bootstrapping（引导）策略，利用冻结的预训练图像编码器和 LLM，以极低的计算成本实现了强大的多模态能力（例如，论文报告其在 VQAv2 零样本 test-dev 上相对 Flamingo-80B 高出 8.7 个百分点，同时使用 54× 更少的可训练参数）。这个“四两拨千斤”效果的关键在于它设计了轻量级的 Q-Former，作为一个信息瓶颈，从视觉特征中“萃取”出最关键的信息并“翻译”给 LLM。如图 20-1 所示，整个模型的训练如同在搭建积木，左侧是冻结的图像编码器负责“看”，右侧是冻结的 LLM 负责“说”，我们主要训练中间这个轻量级的 Q-Former（以及后续对接 LLM 的小映射层）来进行高效的“传译”。

图 20-1 BLIP-2 总体架构

1.2 Q-Former 与两阶段预训练

在原论文中，Q-Former（Querying Transformer）是一个初始化自 BERT-base 的轻量级 Transformer 模块（仅 188M 参数），核心目标是连接冻结的视觉与语言模型。如图 20-2，Q-Former 内部包含两个共享 Self-Attention 层的子模块。左侧路径（论文中称为 Image Transformer）接收一组固定数量的可学习查询向量 (Learnable Queries)（文中设定为 32 个）作为输入，通过每一层的 Cross-Attention 机制与冻结的图像编码器输出交互，从海量的视觉特征中“萃取”出最精华的视觉信息；右侧路径（论文中称为 Text Transformer）则作为文本编码器或解码器处理文本输入。这种双塔共享权重的设计，让 Queries 既能通过 Cross-Attention 学习视觉特征，又能通过共享的 Self-Attention 与文本特征进行交互。由于 32 个 Query 的数量远小于原始图像特征的空间尺寸，这种设计强制模型进行高强度的信息压缩，构成了所谓的“信息瓶颈”，确保传递给 LLM 的都是经过筛选的、与文本最相关的有效信息。

图 20-2 Q-Former 详细架构

为了确保 Q-Former 既能理解图像，又能对接到 LLM，BLIP-2 采用了两阶段预训练策略。

（1）视觉-语言表征学习

在此阶段，图像编码器被冻结。为了让那一组可学习查询向量能够提取出既包含视觉信息又与文本对齐的特征，Q-Former 设计了三种预训练目标，并利用特定的 Attention Mask 策略在同一个架构中同时优化它们。如图 20-3 所示，首先是图文匹配 (ITM)，利用 Bi-directional Mask，允许 Query 和 Text 互相完全可见，学习细粒度的图文对齐；中间是图文生成 (ITG)，使用 Multimodal Causal Mask，这里 Query 可以相互注意但看不见 Text，而 Text 可以看见所有的 Query 和之前的 Text，用于引导基于图像的文本生成；最后是图文对比学习 (ITC)，使用 Uni-modal Mask，让 Query 和 Text 互不可见，专注于对齐整体的视觉和语言表征。这三种策略的结合，确保了 Q-Former 输出的 Query Embeddings 包含了最精华的视觉语义信息。

图 20-3 第一阶段预训练目标 (a) ITM, (b) ITG, (c) ITC

Mask 图解说明：每个方形矩阵代表 Transformer 的注意力掩码（Attention Mask），横纵坐标分别对应 Query 和 Text 的 Token。矩阵被分为四个象限，左上是 Query 对自身的注意力（Q-Q），右下是 Text 对自身的注意力（T-T），右上和左下则是 Query 与 Text 之间的交叉注意力（Q-T 和 T-Q）。空白区域表示“可见”（unmasked），深色区域表示“不可见”（Masked）。例如在 ITC 任务中，我们希望 Query 和 Text 互不可见，对应的右上和左下象限就是深色的。

（2）视觉-语言生成学习

这一阶段，LLM 也被冻结。为了将 Q-Former 提取的视觉特征注入到 LLM 中，BLIP-2 引入了一个全连接层（Fully Connected）将 Query Embeddings（$Z$）线性映射到 LLM 的文本 Embedding 维度。这些映射后的向量充当了“软视觉提示”，直接拼接在文本 Embedding 之前。如图 20-4 所示，具体对接策略取决于 LLM 的架构。若对接 Decoder-based LLM（图 20-4 上半部分，如 OPT），Q-Former 的输出作为前缀，由于 Decoder 是单向注意力的，它能看见视觉 Prompt 并据此生成后续文本；若对接 Encoder-Decoder-based LLM（图 20-4 下半部分，如 Flan-T5），Q-Former 的输出与文本前缀拼接后输入到 Encoder 中，Decoder 则负责根据 Encoder 的跨模态表示生成后缀文本。这种设计通过“软提示”机制，巧妙地复用了 LLM 强大的语言生成能力。

图 20-4 BLIP-2 第二阶段预训练：对接 Decoder-based 或 Encoder-Decoder-based LLM

通过这种方式，BLIP-2 成功地用极小的代价（主要训练 Q-Former，以及将其输出映射到 LLM 词向量空间的全连接映射层）就将视觉感知能力“嫁接”到了大语言模型上。

二、LLaVA 与视觉指令微调

2.1 视觉指令微调的必要性

虽然 BLIP-2 成功地将视觉编码器和 LLM 连接了起来，并且在论文中已经展示了通过提示词进行零样本的指令式图像到文本生成，但它的预训练目标核心仍围绕“模态对齐”与“图像条件生成”。在实际“助手式”交互场景中，这通常表现为模型可以生成，但对复杂指令的稳定遵循、多轮对话格式、以及更贴近人类偏好的回答风格，并没有被系统性地对齐与强化（尤其缺少专门的视觉指令对话数据来做端到端的指令微调）。所以，BLIP-2 更像是“能看懂、也能说”的通用接口原型，而距离像 ChatGPT 一样可对话、可推理、强指令遵循的视觉助手仍有差距。

LLaVA (Large Language and Vision Assistant) ³ 的出现正是为了解决这一问题。它引入了 视觉指令微调，目标是将多模态模型从“看图说话”的工具升级为通用的“智能视觉助手”。正如 NLP 领域从 GPT-3 到 ChatGPT 的进化离不开指令微调，多模态模型也需要通过高质量的视觉指令数据来学习如何遵循人类意图。LLaVA 不仅提出了一个简单的架构，更重要的是提出了一种低成本构建这些数据的方法。

2.2 数据构建

LLaVA 团队（2023年4月）发现，当时虽然缺乏图像-指令对数据，但有丰富的图像-文本对数据（如 COCO），于是他们利用 GPT-4 作为“老师”，采用上下文学习的方式，将图像的符号化表示（多视角图像描述与 COCO 等数据集中现成的目标边界框/类别标注）以及少量人工设计的种子样例喂给 GPT-4，从而生成了总计 158K 条高质量的指令数据。这批数据包含 58K 条模拟人与助手日常交互的对话数据；包含 23K 条要求对图片各个方面进行详尽刻画的详细描述数据；此外还有 77K 条复杂推理数据，这类数据会提出需要基于图片内容进行更深层逻辑推理的问题，并要求给出相对清晰的推理过程。

图 20-5 就是一个具体的生成实例。注意 GPT-4 并没有通过视觉编码器“看”到原始图片，而是根据输入的“Context type 1: Captions”提供的语义描述（如“一群人站在黑色车旁”、“SUV 在地下车库”）以及“Context type 2: Boxes”提供的精确定位信息（如“person: [坐标]”、“suitcase: [坐标]”），在脑海中“脑补”出了完整的场景。基于这些符号化信息，GPT-4 生成了下方的“Response type 1: Conversation”关于车型和地点的问答，“Response type 2: Detailed Description”对场景和人物动作的细致刻画，甚至在“Response type 3: Complex Reasoning”中推理出了人们正面临“如何把大量行李装进车里”的挑战。这种利用大语言模型强大的常识推理能力来生成视觉指令数据的方法，就是 LLaVA 的核心创新之一。

图 20-5 LLaVA 数据构建示例

2.3 LLaVA 架构与训练

LLaVA 的架构非常简洁（如图 20-6 所示）。输入图片 $X_v$ 首先经过 Vision Encoder（使用预训练的 CLIP ViT-L/14），提取出视觉特征 $Z_v$。在其实验中，作者比较了使用 CLIP ViT 的最后一层与最后一层之前的 patch/grid tokens 作为视觉特征。在 ScienceQA 设置下，使用倒数一层特征带来约 0.96 个百分点的提升。随后，Projection Layer（一个简单的线性层 $W$）起到了“翻译官”的作用，将视觉特征线性映射为 LLM 能理解的 Embedding $H_v$。最后，开源 LLM Vicuna（基于 LLaMA 微调）同时处理这些视觉 Embedding 和文本指令 Embedding $H_q$，最终生成回复 $X_a$。

图 20-6 LLaVA 模型架构

为了让这些组件协同工作并获得多模态能力，LLaVA 同样采用了两阶段的训练策略：

（1）特征对齐预训练

为了平衡概念覆盖率和训练效率，LLaVA 将 CC3M 数据集过滤至 595K 个图像-文本对。在此阶段，冻结 Vision Encoder 和 LLM，仅训练投影层。这一步的目标是训练一个与 LLM 兼容的“视觉 Tokenizer”，让图像特征能够对齐到 LLM 的语义空间。

（2）视觉指令微调

使用前述 GPT-4 生成的 158K 条高质量指令数据（对话、描述、推理），冻结 Vision Encoder，同时更新投影层和 LLM 的权重。这一阶段让模型真正学会了如何作为多模态助手与人类交互。

实验结果显示，LLaVA 不仅在日常聊天中展现了出色的多模态能力，在 ScienceQA（多模态科学问答）数据集上也取得了令人瞩目的成绩。论文报告的 92.53% 来自一种“集成”设置，当 LLaVA 与文本版 GPT-4 结合，并由 GPT-4 充当“裁判”在两者答案不一致时做最终仲裁时，可达到该准确率。

参考文献

图文多模态及其实现

Fri, 27 Mar 2026 20:40:25 -0800

图文多模态及其实现

虽然多模态领域涵盖了音频、视频、3D 点云、热成像等多种数据形式，且“多模态”的边界正在不断拓展，但**图文（Image-Text）**始终是目前研究最深入、应用最广泛，也是最能体现跨模态交互逻辑的基础组合。本节我们将深入探讨两个具有代表性的模型架构，分别是将 Transformer 引入视觉领域的 ViT，以及连接文本与图像语义的 CLIP。

一、视觉的 Transformer 化

在过去十年里，计算机视觉领域长期以 CNN（卷积神经网络，如 ResNet）为主流，而 NLP 领域自 2017 年后则由 Transformer 主导。虽然两者都能通过网络设计获得全局信息，但在基础算子的特性上仍有明显区别。2020年，Google 提出了 ViT (Vision Transformer) ¹，既然 Transformer 擅长处理 Token 序列，能不能把图像切成 Patch（图像块），把每个 Patch 当作一个 Token，直接用 Transformer 来做图像识别？

1.1 序列化图像

Transformer 的标准输入是 1D 向量序列，而图像是 2D 网格。ViT 的处理方式非常直接且“暴力”，具体步骤如下：

（1）Patch Embedding（把图像变成 Token，见图 19-5 左下）：将图像 $\mathbf{x}\in\mathbb{R}^{H\times W\times C}$ 切分为 $N$ 个固定大小的 Patch（如 $P\times P \times C$），展平后得到 $\mathbf{x}_p\in\mathbb{R}^{N\times(P^2\cdot C)}$，其中

$$ N=\frac{H\cdot W}{P^2} \tag{19.1} $$

然后用一个可学习的线性投影 $\mathbf{E}\in\mathbb{R}^{(P^2\cdot C)\times D}$ 把每个 Patch 映射为 $D$ 维向量（图 19-5 中的粉色长条 “Linear Projection…”）。这一步在实现上等价于一个 kernel=$P$、stride=$P$ 的卷积（把每个 patch “一次性”投到 $D$ 维）。

（2）特殊的 [CLS] Token（全局聚合器，见图 19-5 左下角标 * 的紫色胶囊）：借鉴 BERT，在序列开头拼接一个可学习的分类令牌 $\mathbf{x}_{class}$。它更像一个“读写全局信息的槽位”，通过自注意力在层间不断从各个 patch 聚合信息。最终，我们只用该位置对应的输出向量（图 19-5 左上角的 “Class” 黄色框）来代表整张图像进行分类。

假设图像尺寸为 $224\times224$，Patch 大小 $P=16$，则会切分出 $14\times14=196$ 个 Patch。加上这个额外的 [CLS] Token 后，输入 Transformer 的序列总长度变为 $196+1=197$。

（3）位置编码（保留空间信息，见图 19-5 紫色标号圆圈）：给序列加上可学习的 1D 位置编码 $\mathbf{E}_{pos}\in\mathbb{R}^{(N+1)\times D}$。

图 19-5 ViT 架构概览（左侧为 Patch Embedding 流程，右侧为 Transformer Encoder 内部结构）

最终，输入 Transformer 的向量序列 $\mathbf{z}_0$ 如下：

$$ \mathbf{z}_0=[\mathbf{x}_{class};\mathbf{x}_p^1\mathbf{E};\mathbf{x}_p^2\mathbf{E};\dots;\mathbf{x}_p^N\mathbf{E}] + \mathbf{E}_{pos} \tag{19.2} $$

其中：

$\mathbf{x}_{class}$：特殊的分类 Token 向量。
$\mathbf{x}_p^k\mathbf{E}$：第 $k$ 个图像 Patch 经过线性投影后的嵌入向量。
$\mathbf{E}_{pos}$：与序列长度对应的位置编码，用于补充 Transformer 缺失的位置信息。

1.2 ViT 模型架构细节

ViT 尽可能保持了 Transformer 的原貌，这种“无修饰”的设计反而使其具有极强的扩展性。我们可以对照图 19-5 中右侧的 Transformer Encoder 部分。

（1）Encoder-only + Pre-Norm：ViT 沿用了标准的 Transformer Encoder 架构（即 MSA 和 MLP 的堆叠），不过它将 Layer Norm 移到了每个子层的输入位置（Pre-Norm）。这种设计与之前学习过的 GPT-2/3 一致。

（2）分类读出：用分类 token 的输出做表征：

$$ \mathbf{y}=\mathrm{LN}(\mathbf{z}_L^{0}) \tag{19.3} $$

其中 $\mathbf{z}_L^{0}$ 表示 Transformer Encoder 最后一层（第 $L$ 层） 输出序列中的第 0 个 token（即 [CLS] 位置）的向量。实践中， $\mathbf{y}$ 会接一个 MLP 分类头来输出最终类别。论文指出，在预训练阶段这个 Head 是含有一个隐藏层的 MLP，而在微调阶段通常简化为单层线性映射。

（3）位置编码与“高分辨率微调”的 2D 插值：ViT 的位置编码本身是 1D 可学习向量，但当微调分辨率变化导致 $N$ 变化时，需要把预训练的 $\mathbf{E}_{pos}$ 视作 $h\times w$ 的 patch 网格再做 2D 插值，以适配新的 patch 网格尺寸。这也是 ViT 少数显式注入“2D 结构”的地方。也就是说假设 Patch 大小为 $16 \times 16$，预训练时图像为 $224\times224$，Patch 数量为 $14\times14=196$（即 $224/16=14$）。微调时若图像放大到 $384\times384$，Patch 数量变为 $24\times24=576$（即 $384/16=24$）。此时，我们不仅要处理序列变长的问题，还要保持空间位置的相对关系。所以，需要将原本 $14\times14$ 的位置编码矩阵“拉伸”（双线性插值）到 $24\times24$，以初始化新的位置编码。

为什么微调时要放大图像？

这是一个在计算机视觉中常见的策略（效率 vs 精度权衡）。预训练阶段由于数据量巨大，为了节省计算成本，通常使用标准分辨率。而微调阶段面向下游特定任务，数据量相对较小，此时使用更高分辨率（如 $384 \times 384$）可以让模型“看清”更多细节，以追求更高的精度。

（4）全局交互：这其实就是 BERT 中“深度双向注意力”在图像领域的直接体现。在 BERT 中，每个 Token 在第一层就能“看见”句子中所有的其他 Token。同样地，在 ViT 中，每个 Patch 就相当于一个 Token。CNN 需要堆叠多层卷积才能扩大感受野看到全图，而 ViT 的自注意力机制在第一层就能让任意两个 Patch 进行交互。左上角的 Patch 可以直接“关注”到右下角的 Patch，无需经过层层传递，通过 Attention 矩阵实现了一步到位的全局视角。但这种能力的代价是计算量，标准 Self-Attention 的复杂度是序列长度 $N$ 的平方（$O(N^2)$）。Patch 越小（$P$ 越小），序列长度 $N$ 就越大（$N \propto 1/P^2$），计算量就会呈平方级爆炸（$O(1/P^4)$）。这也是为什么 ViT 通常不把 Patch 设置得太小的原因。

1.3 关键特性

ViT 的设计哲学与 CNN 截然不同，首先体现在弱归纳偏置 (Inductive Bias) 上。所谓归纳偏置，就是模型在处理数据时预先带有的“偏见”或“假设”。CNN 天然假设图像具有局部性（相邻像素有关联）和平移等变性（猫在左上角和右下角都是猫）等结构先验，就像是带着“有色眼镜”看图，所以 CNN 在小数据上也能快速抓住重点，更容易泛化。而 ViT 的自注意力是全局的，它把图像看作一串长长的序列，显式的 2D 结构只在切 patch与位置编码插值这两处出现。这就好比 ViT 是一张白纸，模型无法预先“知道”像素的空间规则，需要更多数据去“学会”稳定的空间与语义模式。

空间与语义模式

空间模式指像素点如何在空间上组成有意义的几何结构（如“圆形”通常由连续的弧线像素组成，“眼睛”通常位于“鼻子”上方），CNN 通过卷积核的局部连接天然假设了这种相邻关系，而 ViT 最初是一张白纸，必须靠大量数据自己发现“相邻的 Patch 往往属于同一个物体”这一规律。语义模式则指图像内容的高层含义及其组合规则，例如“蓝色的上方区域”通常是“天空”，“两个尖耳朵 + 胡须”通常代表“猫”。ViT 不仅要学会识别这些物体，还要学会跨越长距离关注它们的关联（如鸟的头和尾巴虽然相距很远，但共同定义了“鸟”这个概念）。

这种弱归纳偏置的设计虽然增加了学习难度，但也带来了架构的统一性 (Unified Architecture)。ViT 的最大贡献在于证明了 Transformer 是一个通用的计算原语。在 ViT 之前，CV 领域由 CNN 统治，NLP 领域由 Transformer 统治，两者的模型设计思路完全不同。ViT 出现后，CV 和 NLP 终于可以在底层架构上实现统一（都用 Transformer 处理 Token 序列）。这种统一性不仅简化了模型设计，更为后续的多模态大模型提供了实现路径。图像和文本都能被变成 Token 喂给 Transformer，那么在一个模型里同时处理它们就有了可能性。归纳偏置的减弱同时也导致了 ViT 的数据饥渴 (Data Hungry) 特性。在中小数据集（如 ImageNet-1k）从头训练时，ViT 往往不如同规模的 CNN。但当在超大规模数据（如 ImageNet-21k、JFT-300M）上预训练后，再迁移到下游任务，ViT 会呈现更强的扩展性（scale 越大越吃香）。总结起来就是因为 ViT 的归纳偏置更弱、需要从数据里学到“空间结构 + 语义组合”这套规则，所以更依赖大规模预训练数据来把泛化能力堆起来。

二、连接图文的 CLIP 架构

2021年，OpenAI 紧随其后发布了 CLIP (Contrastive Language-Image Pre-training) ²。如果说 ViT 统一了视觉的模型架构，那么 CLIP 就统一了图文的语义空间。

2.1 CLIP 的架构与原理

ViT 虽然实现了图像与文本在底层架构上的统一，但这仅仅是第一步。尽管模型能“吃”进去图像和文本，但它并不理解“一张猫图”和“单词 Cat”之间有什么联系。要打破这层隔阂，我们需要让这两个模态在语义空间上实现对话。而实现这一对话的关键就是 Embedding，它能够将高维、非结构化的数据（图片、文字）映射到一个低维的、稠密的数学空间中。在多模态任务中，仅仅分别得到图像向量和文本向量是不够的。我们还需要让这两个向量在同一个空间中具有几何意义上的关联，这就是语义对齐（Alignment）。多模态学习的理想状态下，一张“猫”的图片生成的向量 $V_{img}$ 应该与单词“Cat”生成的向量 $V_{text}$ 在空间中距离非常近，即夹角小且相似度高。面对图像和文本原本处于两个完全不同异构特征空间的挑战，CLIP 的目标就是解决如何让模型学会将它们对齐。

（1）双塔结构

为了实现上述目标，CLIP 采用了经典的双塔结构，但在具体设计上不仅追求特征的表达能力，更注重大规模训练的效率。对于负责将图像编码为特征向量的图像编码器（Image Encoder），OpenAI 探索了经过改进的 ResNet 和 ViT 两种架构。ResNet 版本在 ResNet-50 的基础上引入了 ResNet-D 的改进，并采用抗混叠下采样（anti-aliased downsampling）来减少下采样带来的信息折叠；同时将末端的全局平均池化替换为注意力池化，以更好地聚合全局特征。ViT 版本则基本遵循原始 ViT 的实现，只做了很小的改动。仅在 patch embedding 和 position embedding 相加后、进入 Transformer 之前增加一个额外的 LayerNorm，并使用了稍微不同的初始化方案以提升训练稳定性。如图 19-6 所示，实验表明在同样的计算预算下，ViT 架构在相近计算预算下整体表现更优。论文也指出 CLIP 的 ViT 系列在计算效率上大约比 CLIP ResNet 系列高 3 倍。而对于负责将文本编码为特征向量的文本编码器（Text Encoder），CLIP 选用了类似 GPT-2 的 Decoder-only Transformer 架构而非 BERT，通过自注意力掩码确保模型在编码当前词时仅能关注之前的词。文本序列以 [SOS] 标记开始，以 [EOS] 标记结束。经过 Transformer 编码后，每个词位置都会产生对应的特征向量，但 CLIP 只取最后一层 Transformer 在 [EOS] 标记位置的特征向量作为整句话的语义表示。这是因为 [EOS] 位置的特征通过自注意力机制已经聚合了整个句子的信息，能够代表整句话的语义。

图 19-6 CLIP 图像编码器计算效率对比：ViT vs ResNet

这两个模态塔（图像模态塔和文本模态塔）在特征提取阶段互不干扰，分别输出图像和文本的特征向量。随后，两个向量会分别经过一个线性的投影层映射到维度相同的联合嵌入空间 (Joint Embedding Space) 中，并进行 L2 归一化。通过这一系列操作就可以直接计算两个向量的点积（即余弦相似度），来衡量"图"与"文"在语义上的匹配程度。

（2）对比学习

如图 19-7 所示，对比学习（Contrastive Learning）是 CLIP 的核心训练策略，它为双塔结构注入了“灵魂”，真正实现了让图像和文本在同一个 Embedding 空间中实现语义对齐。

图 19-7 CLIP 的对比预训练过程

我们可以结合图 19-7 来完整梳理一下这个跨模态对齐的过程。第一步是输入一个包含 $N$ 个图文对的 Batch（图中通过叠放的输入和下标 $1 \dots N$ 来示意），图像和文本会分别通过各自的 Encoder 变成特征向量。接下来，这些原始特征会被投影到同一个联合嵌入空间，分别形成图像 Embedding ($I_1, I_2, \dots, I_N$) 和文本 Embedding ($T_1, T_2, \dots, T_N$)。此时，它们已经变成了“同一种语言”（都是 $D$ 维向量）。接下来进行相似度矩阵的构建，模型会计算这两个序列中所有向量的两两点积，生成一个 $N \times N$ 的相似度矩阵（图中右侧的网格）。其中，对角线（蓝色块）代表 $I_k$ 和 $T_k$ 的匹配程度，这是原始数据中真实的“图文对”，即正样本；而非对角线（白色块）代表 $I_k$ 和 $T_j (j \neq k)$ 的匹配程度（比如“猫的图”配了“描述狗的字”），这是错误的组合，即负样本。最后的训练目标是最大化对角线上的数值，同时最小化非对角线上的数值。也就是说，当模型努力让 $I_{dog} \cdot T_{dog}$ 变大时，它实际上是在高维空间中推着“狗的图片向量”和“Dog 单词向量”相互靠近；反之，当模型努力让 $I_{cat} \cdot T_{dog}$ 变小时，它是在让它们相互远离。通过在 4 亿对数据上重复这个过程，CLIP 最终“学会”了将视觉概念和语言概念紧密地绑定在一起。这就实现了我们最初的构想，Embedding 不再是孤立的模态特征，而是成为了连接视觉与语言的通用货币。

2.2 零样本推理与提示工程

虽然 CLIP 在预训练阶段仅仅是学习了图文对齐，但它最具革命性的特性其实是它的零样本推理能力。传统的计算机视觉模型通常只能识别训练时定义好的类别，一旦遇到新类别就必须重新收集数据微调模型。而 CLIP 将“分类任务”彻底重构为“图文匹配任务”，打破了固定类别的限制。

为了让模型更好地理解类别名称，CLIP 还引入了提示工程的概念。当我们需要识别一张图像是否属于某个类别（例如“狗”）时，不再是让模型输出一个类别 ID，而是让模型去判断这张图与句子“一张狗的照片”之间的相似度（如图 19-8 所示）。由于训练数据多为句子而非单词，直接输入单词往往会造成歧义（例如论文中提到的 “boxer”，既可能是“拳师犬”，也可能是“拳击手”），且与预训练数据的分布存在差异。所以，我们可以将类别标签填入一个模板句子，如 “A photo of a {label}.”。在推理时，模型会将所有候选类别（如猫、狗、飞机）都填入模板，生成一组文本向量，然后找出与当前图像向量相似度最高的那句话，从而确定图像的类别。这种范式使得 CLIP 无需任何微调，就能直接迁移到任意的视觉分类任务中，成为一个真正的“开放词汇”分类器。

图 19-8 CLIP 的 Zero-Shot 推理过程

2.3 CLIP 的局限

作为多模态领域的里程碑，CLIP 的出现打通了视觉与语言的壁垒。它生成的 Embedding 具有很强的语义线性与鲁棒性，例如在 Stable Diffusion 等扩散模型中，通常会使用 CLIP/OpenCLIP 的文本编码器将提示词变成条件向量，达到在生成过程中提供语义约束的目的。它也启发并影响了后续大量视觉语言模型，为“图文对齐 + 下游任务适配”提供了关键范式。除此之外，由于在海量且多样化的互联网数据上训练，CLIP 对图像风格、光照变化、草图甚至卡通画的鲁棒性往往强于传统仅在 ImageNet 上训练的模型。

然而，CLIP 并非完美无缺。由于它是基于“图像整体”与“文本整体”的统计相关性进行训练的，它在处理细粒度分类（如区分波音747与波音777，或不同品种的特定花卉）时往往表现不佳，因为这些细微差别在海量图文对中可能被淹没。同时，CLIP 在逻辑计数（如“数一数图中有几个红色的气球”）或空间关系判断（如“车在房子的左边还是右边”）方面也存在短板，这通常被归因于对比学习损失函数难以捕捉复杂的组合性语义。最后，在医学影像或遥感图像等与其预训练数据分布差异巨大的专业领域，CLIP 的 Zero-Shot 性能也会显著下降，通常需要进行针对性的微调。

三、CLIP 代码实现

本节完整代码

（1）图像与文本编码器

理解了 CLIP 的原理后，我们尝试用 PyTorch 实现一个简化版的 CLIP 模型。原始 CLIP 的两个编码器都是从零训练，并且会进行 L2 归一化 + 可学习温度（logit scale）缩放，这里为了跑通流程与降低门槛，我们直接加载预训练的模型。第一步可以先构建双塔结构的两个编码器。首先是 Image Encoder，利用 timm 库可以非常方便地加载预训练的 ViT 模型。这里我们选择 vit_small_patch16_224 这个型号，其中 patch16 表示将图像切分为 $16 \times 16$ 的块，224 表示输入分辨率。同时开启 pretrained=True 让模型加载在 ImageNet 上预训练好的权重，让模型拥有基础的“看图”能力。由于 timm 的 ViT 默认带有用于分类的 head，为了得到我们需要的图像 embedding，会显式加一个投影层把视觉特征映射到目标 embedding 维度（这样不会误把随机初始化的分类 head 当作 embedding）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class ImageEncoder(nn.Module):
 """图像编码器"""
 def __init__(self, output_dim):
 super(ImageEncoder, self).__init__()
 # num_classes=0 会移除分类 head，输出 backbone 特征（维度为 vit.num_features）
 self.vit = timm.create_model('vit_small_patch16_224', pretrained=True, num_classes=0)
 self.proj = nn.Linear(self.vit.num_features, output_dim, bias=False)

 def forward(self, x):
 feat = self.vit(x) # (Batch, vit.num_features)
 return self.proj(feat) # (Batch, output_dim)

对于 Text Encoder，为了贴近原始 CLIP 使用 Decoder-only 架构的设计，我们选择 GPT-2 作为近似替代。不过，GPT-2 是为文本生成设计的，默认没有 Padding Token，而在处理 Batch 数据时我们要对齐长度，所以需要将它的 pad_token 临时设置为 eos_token。在获取特征时，我们取序列最后一个非 padding token的隐藏状态作为整句话表征。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


class TextEncoder(nn.Module):
 """文本编码器"""
 def __init__(self, output_dim):
 super(TextEncoder, self).__init__()
 self.tokenizer = GPT2Tokenizer.from_pretrained('gpt2')
 # 解决 GPT-2 无 pad_token 的问题，将其设为 eos_token
 self.tokenizer.pad_token = self.tokenizer.eos_token
 self.model = GPT2Model.from_pretrained('gpt2')
 self.proj = nn.Linear(self.model.config.hidden_size, output_dim, bias=False)

 def forward(self, texts):
 inputs = self.tokenizer(texts, return_tensors='pt', padding=True, truncation=True).to(self.model.device)
 output = self.model(**inputs)

 # 获取最后一个非 padding token 的输出作为句子表征
 # 利用 attention_mask 找到每个样本的真实长度
 last_hidden_state = output.last_hidden_state
 attention_mask = inputs.attention_mask
 last_token_idx = attention_mask.sum(dim=1) - 1

 # 从 batch 中取出对应索引的向量
 batch_idx = torch.arange(last_hidden_state.size(0)).to(last_token_idx.device)
 sent = last_hidden_state[batch_idx, last_token_idx] # (Batch, hidden)
 return self.proj(sent) # (Batch, output_dim)

（2）投影与双塔对齐

接下来我们将刚才实现的两个编码器组合起来实现一个完整的 CLIP 模型。图像编码器和文本编码器输出的特征通常是不同维度的。为了计算相似度，我们需要通过可学习的投影层 将它们映射到相同的维度（联合嵌入空间），并计算点积。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class CLIP(nn.Module):
 """CLIP：双塔 + 线性投影 + 归一化 + 温度缩放"""
 def __init__(self, embed_dim):
 super(CLIP, self).__init__()
 self.image_encoder = ImageEncoder(embed_dim)
 self.text_encoder = TextEncoder(embed_dim)
 # 可学习温度（论文中用 log 参数化的 logit_scale）
 self.logit_scale = nn.Parameter(torch.log(torch.tensor(1 / 0.07)))

 def forward(self, images, texts):
 # 1) 提取 embedding
 img = self.image_encoder(images)
 txt = self.text_encoder(texts)

 # 2) L2 归一化（点积 -> 余弦相似度）
 img = torch.nn.functional.normalize(img, dim=-1)
 txt = torch.nn.functional.normalize(txt, dim=-1)

 # 3) 温度缩放后的相似度矩阵 (Batch, Batch)
 scale = self.logit_scale.exp()
 logits = scale * (img @ txt.T)
 return logits

（3）数据准备

为了演示，我们使用 CIFAR-10 数据集。由于 ViT 模型默认的输入分辨率是 224x224，而 CIFAR-10 的图片大小是 32x32，所以我们需要在预处理阶段将图片 Resize 到 224。同时，为了匹配预训练模型的输入分布，我们还需要使用模型特定的均值和方差（通过 vit.default_cfg 获取）对图像进行归一化处理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def load_cifar10_dataset(batch_size, image_size=224, root='./cifar10', mean=None, std=None):
 """加载CIFAR10数据集"""
 transform = transforms.Compose([
 transforms.Resize((image_size, image_size)),
 transforms.ToTensor(),
 transforms.Normalize(mean=mean, std=std),
 ])

 train_dataset = CIFAR10(root=root, train=True, download=True, transform=transform)
 loader = DataLoader(train_dataset, batch_size=batch_size, shuffle=True)
 classes = train_dataset.classes
 return loader, classes

（4）对比训练过程

最后的训练循环需要遍历数据集以构造 Batch 数据，获取一批图像及其对应的类别名称作为文本。随后将这些图像和文本同时输入模型，生成 $N \times N$ 的相似度矩阵 logits。由于第 $i$ 张图对应的正是第 $i$ 个文本，所以监督信号就是对角线的“匹配位置索引”，即 targets=[0, 1, ..., N-1]。接下来，我们分别计算“图像找文本”（行方向）和“文本找图像”（列方向）的损失，并将两者取平均值作为最终的优化目标。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


if __name__ == "__main__":
 device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 print(f"Using device: {device}")

 # 初始化模型
 clip_model = CLIP(embed_dim=512).to(device)
 clip_model.text_encoder.model.to(device)

 cfg = clip_model.image_encoder.vit.default_cfg
 mean = cfg['mean']
 std = cfg['std']
 data_root = os.path.join(os.path.dirname(__file__), "cifar10")
 dataset, classes = load_cifar10_dataset(batch_size=4, root=data_root, mean=mean, std=std)

 # 模拟训练循环
 for i, (images, labels) in enumerate(dataset):
 images = images.to(device)
 # 将标签转换为对应的文本描述 (例如 label 0 -> "airplane")
 texts = [classes[label.item()] for label in labels]

 # 前向计算得到相似度矩阵
 logits = clip_model(images, texts)

 # 构造目标标签
 targets = torch.arange(logits.shape[0]).to(device)

 # 计算损失
 loss_i = nn.CrossEntropyLoss()(logits, targets)
 loss_t = nn.CrossEntropyLoss()(logits.T, targets)
 loss = (loss_i + loss_t) / 2

 print(f"Batch {i}: Loss = {loss.item():.4f}")

 # 仅演示前几个batch
 if i >= 2: break

输出如下：

1
2
3


Batch 0: Loss = ...
Batch 1: Loss = ...
Batch 2: Loss = ...

CLIP 实现完整代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126


import os
import torch
import torch.nn as nn
from torch.utils.data import DataLoader
import torchvision.transforms as transforms
from torchvision.datasets import CIFAR10
from transformers import GPT2Model, GPT2Tokenizer
import timm

# 1. 模型定义

class ImageEncoder(nn.Module):
 """图像编码器"""
 def __init__(self, output_dim):
 super(ImageEncoder, self).__init__()
 # 使用来自timm的ViT模型
 # num_classes=0 会移除分类 head，输出 backbone 特征（维度为 vit.num_features）
 self.vit = timm.create_model('vit_small_patch16_224', pretrained=True, num_classes=0)
 self.proj = nn.Linear(self.vit.num_features, output_dim, bias=False)

 def forward(self, x):
 feat = self.vit(x)
 return self.proj(feat)


class TextEncoder(nn.Module):
 """文本编码器"""
 def __init__(self, output_dim):
 super(TextEncoder, self).__init__()
 model_name = 'gpt2'
 self.tokenizer = GPT2Tokenizer.from_pretrained(model_name)
 # GPT-2默认没有pad_token，将其设为eos_token
 self.tokenizer.pad_token = self.tokenizer.eos_token
 self.model = GPT2Model.from_pretrained(model_name)
 self.proj = nn.Linear(self.model.config.hidden_size, output_dim, bias=False)

 def forward(self, texts):
 # 文本通过GPT-2
 inputs = self.tokenizer(texts, return_tensors='pt', padding=True, truncation=True).to(self.model.device)
 output = self.model(**inputs)

 # 获取最后一个非 padding token 的输出
 # 根据 attention_mask 计算每个样本的最后一个有效 token 索引
 last_hidden_state = output.last_hidden_state
 attention_mask = inputs.attention_mask
 last_token_idx = attention_mask.sum(dim=1) - 1 # (B)

 # 从batch中取出对应索引的向量
 batch_idx = torch.arange(last_hidden_state.size(0)).to(last_token_idx.device)
 sent = last_hidden_state[batch_idx, last_token_idx] # (B, 768)
 return self.proj(sent) # (B, output_dim)


class CLIP(nn.Module):
 """CLIP模型：结合图像和文本编码器"""
 def __init__(self, embed_dim):
 super(CLIP, self).__init__()
 self.image_encoder = ImageEncoder(embed_dim)
 self.text_encoder = TextEncoder(embed_dim)

 # 可学习温度系数（论文中用 log 参数化的 logit_scale）
 self.logit_scale = nn.Parameter(torch.log(torch.tensor(1 / 0.07)))

 def forward(self, images, texts):
 img = self.image_encoder(images) # (B, embed_dim)
 txt = self.text_encoder(texts) # (B, embed_dim)

 # 归一化后点积即余弦相似度
 img = torch.nn.functional.normalize(img, dim=-1)
 txt = torch.nn.functional.normalize(txt, dim=-1)

 # 温度缩放
 scale = self.logit_scale.exp()
 logits = scale * (img @ txt.T) # (B, B)
 return logits


# 2. 数据处理

def load_cifar10_dataset(batch_size, image_size=224, root='./cifar10', mean=None, std=None):
 """加载CIFAR10数据集"""
 transform = transforms.Compose([
 transforms.Resize((image_size, image_size)),
 transforms.ToTensor(),
 transforms.Normalize(mean=mean, std=std),
 ])
 # download=True 会自动下载
 train_dataset = CIFAR10(root=root, train=True, download=True, transform=transform)
 loader = DataLoader(train_dataset, batch_size=batch_size, shuffle=True)
 classes = train_dataset.classes
 return loader, classes


if __name__ == "__main__":
 device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 print(f"Using device: {device}")

 # 初始化模型
 clip_model = CLIP(embed_dim=512).to(device)
 clip_model.text_encoder.model.to(device)

 # 加载数据
 cfg = clip_model.image_encoder.vit.default_cfg
 mean = cfg['mean']
 std = cfg['std']
 data_root = os.path.join(os.path.dirname(__file__), "cifar10")
 dataset, classes = load_cifar10_dataset(batch_size=4, root=data_root, mean=mean, std=std)

 # 3. 训练循环
 for i, (images, labels) in enumerate(dataset):
 images = images.to(device)
 texts = [classes[label.item()] for label in labels]

 # 前向计算
 logits = clip_model(images, texts) # (B, B)

 # 计算损失
 targets = torch.arange(logits.shape[0]).to(device)
 loss_i = nn.CrossEntropyLoss()(logits, targets)
 loss_t = nn.CrossEntropyLoss()(logits.T, targets)
 loss = (loss_i + loss_t) / 2

 print(f"Batch {i}: Loss = {loss.item():.4f}")

 # 仅演示前几个batch
 if i >= 2: break

小结

回顾第一节提到的多模态机器学习五大挑战（表征、转换、对齐、融合、协同学习），本节介绍的 ViT 解决了“表征”的统一性，它打破了 CNN 对视觉的统治，证明 Transformer 能作为通用的计算原语，通过 Patch Embedding 将图像“序列化”为 Token，从而在底层架构上与语言达成一致。而 CLIP 则解决了“对齐”的普适性，利用对比学习将异构的图文映射到同一联合嵌入空间，让 Embedding 真正成为连接不同模态的“桥梁”，无需微调即可实现零样本迁移。通过本节的代码实践，我们也亲手实现了这种“双塔+对比损失”的简洁架构。尽管 CLIP 在细粒度理解和复杂逻辑上仍有短板，但它为后续的多模态生成与复杂推理提供了关键的语义地基。

参考文献

多模态概述

Fri, 27 Mar 2026 16:40:25 -0800

多模态概述

在前面的章节中，我们主要围绕文本（Text）这一单一模态系统性学习了 NLP 与 LLM 的主线能力。但真实世界的信息并不只以文字存在，图片、视频、语音、音乐、传感器、布局与结构化信号……共同构成了人类认知的“输入流”。多模态学习关注的就是如何让模型在这些异构信息之间建立联系，完成理解、生成与决策。

图 19-1 多模态模型 Nano Banana 生成的多模态交互示意图

一、多模态的定义与内涵

1.1 从模态到多模态

在工程语境里，模态（Modality）通常指信息的感知/表达通道（可理解为模型的输入或输出形式），也就是同一类“语义”在不同载体上的呈现形式（信息来源/形式）。正因为载体不同，各模态在数据层面天然存在差异。文本通常表现为离散的 token 序列；图像是 $H \times W \times C$（高度 $\times$ 宽度 $\times$ 通道数）的像素网格；语音/音频常以连续时间波形或谱图表示；传感器往往是多路同步的时间序列，并伴随漂移、缺失与噪声等工程问题。结构不同会带来统计特性差异（例如局部性与全局性、时序依赖、尺度变化与噪声分布），进而决定了预处理、采样与建模方式也不应“一把梭”。因此，多模态（Multimodal）系统通常会为不同模态配置各自的编码器（Text / Image / Audio / Sensor Encoder），先把异构信号映射为可计算的表征，再进入后续的对齐、融合与推理。

微观多模态

除了跨越物理媒介的模态（如声、光、电），在文本模态内部，也存在“结构形态”发生显著变化的转换。例如：

Text-to-Code（文本转代码）：代码具有更严密的逻辑和语法约束。

Text-to-Table（文本转表格）：表格是结构化的二维信息。这些转换虽然输入输出都是字符流，但在信息组织形式上发生了质变，也可视为广义的多模态转换。

基于上述对模态差异的理解，一个具备可操作性的定义是当系统需要同时处理两种及以上“本质异构”的模态，并且需要显式建模它们之间的语义关系（对应、互补、约束）时，就可以称为多模态。不过，“多模态”并不等同于把多路数据简单拼在一起，也不应只用“输入/输出的个数”来粗暴划分；关键是模型是否真的利用了模态之间的互补信息，并在表征、对齐与推理层面建立起跨模态的联系。站在工程落地的视角，多模态任务最常见的形态包括以图像与文本共同输入并输出文本答案的图文问答（VQA）；以文本为条件生成图像、音频或视频的内容生成；以及在更复杂系统中同时接收多模态输入并输出多模态结果（例如看图对话的同时用语音回答，甚至驱动动作执行），本质都是围绕“异构信息的协同建模”展开。

1.2 多模态的交互与表征对齐

多模态研究并非近年才出现，但它在多模态机器学习语境下的快速发展，更多发生在大规模数据、可扩展模型与训练范式逐步成熟之后。纵向回顾相关工作，可以将其脉络概括为两条相互关联但侧重点不同的路线。分别是以用户输入通道互补为核心的多模态交互，以及以共享潜在空间为核心的多模态表征对齐。

第一条路线主要源于人机交互（HCI）与多通道界面的研究传统，强调不同输入通道在语义表达上的互补性与消歧能力。Richard A. Bolt 在 SIGGRAPH 1980 发表并演示的 “Put-That-There” 系统，是早期语音与指点/手势协同交互的经典案例 ¹。系统将语音命令与同步指向结合，使语言中的指示词（如 that/there）能够借助空间指点获得更明确的指代，完成图形对象在界面中的定位与操作。需要指出的是，此类工作通常以规则、语法或时序约束实现跨通道整合，其研究重点在于交互机制与解析策略，而非通过大规模数据学习统一表示。

第二条路线聚焦在表征空间的对齐，即学习一个（或一组）潜在空间，使不同视角变量或不同模态的表示在该空间中具有可比性，并对语义对应关系保持一致性。这个思想在统计学习中具有更早的数学基础，Hotelling 提出的**典型相关分析（CCA）**可被理解为通过线性投影最大化两组变量相关性的对齐方法，为后续“共享子空间”的建模思路提供了重要工具 ²。在信息检索领域，**LSA/LSI（Latent Semantic Analysis / Latent Semantic Indexing）**虽然主要处理单一文本模态，但它通过降维构造低维语义空间、并以空间邻近关系刻画语义相似性的范式，为之后以“向量空间”承载语义并进行相似度计算的做法奠定了方法论基础 ³。

随着跨模态任务（如图文检索、视觉—语言建模）的发展，研究重心逐步转向“如何学习可迁移的联合嵌入空间”。在这一过程中，CCA 及其核化形式（Kernel CCA, KCCA）被系统化总结并作为“学习共同子空间/共同表征”的重要工具 ⁴，为后续跨模态匹配与检索提供了可复用的对齐范式。深度学习范式下，对比式目标进一步推动了“对齐”从相关性最大化走向可扩展的表示学习：Hadsell、Chopra、LeCun 的**对比损失（Contrastive Loss）**为“拉近正样本、推远负样本”的度量学习目标提供了早期形式化表达 ⁵。随后，ConVIRT 等工作在配对图文数据上采用双向对比目标进行预训练，为跨模态对比学习在实际任务中的有效性提供了直接证据 ⁶。CLIP 则将该训练范式扩展到更大规模的图文配对数据，并在零样本迁移等设置中展示了共享嵌入空间对齐对下游泛化能力的重要作用 ⁷，推动该路线进入快速发展阶段。

误区辨析

把“多源/多路数据”当成多模态，把“概念混用”当成定义：多模态的关键不在于“数据路数多”，而是模态是否异构、信息是否互补、系统是否真的做了对齐/融合/协同推理。比如多篇文本、多视角图像、多张图片拼接，很多时候仍属于同一模态的扩展，并不天然等于多模态；相反，一张图片加一句描述这种最简单的图文对，只要目标是学习跨模态语义关系，就已经是多模态。工程上还有个常见混淆点，“多模态”和“多任务学习”不是一回事——前者讨论的是信息来源（模态）的异构与融合，后者讨论的是目标函数/任务的并行优化，两者可以组合但不能互相替代。

二、多模态认知图谱

为了打破“多模态”作为抽象概念的疏离感，我们可以从任务复杂度和技术挑战两个维度来构建认知图谱。这不仅是对应场景的简单罗列，也是为了理清模型架构演进的内在逻辑，理解随着任务从“判断匹配”升级到“生成内容”乃至“复杂推理”，模型的能力边界是如何一步步拓展的。

2.1 多模态任务图谱

根据输入输出的依赖关系与任务复杂度，现有的多模态任务大致可以被归纳为四个递进的层级。虽然我们常以图文为例，但这些层级的逻辑天然适用于视频、音频、传感器等任意模态组合。

（1）基础理解与检索

这是多模态能力的基础，主要逻辑是判断跨模态信息的匹配度或从库中寻找对应项。最典型的场景是图文检索（以文搜图/以图搜文），正是 CLIP 这类双塔结构最擅长的领域。同样的逻辑也适用于“以音搜文/以文搜音”（音频-文本检索），以及“多传感器片段检索”（例如用 IMU/振动序列检索对应故障描述）。一些前沿工作甚至尝试将图像、文本、音频、深度、热成像、IMU 等绑定到同一嵌入空间（如 ImageBind），使“检索/匹配”天然跨越多种模态组合。在这个层级，模型主要完成的是“特征对齐”工作，以及跨模态一致性/支持性判断（例如图文是否一致、文本描述是否被图像证据支持。也可被更严格地形式化为“跨模态蕴含”类任务）。

（2）定位与结构化理解

在基础理解之上，模型需要把语言或符号“落到可定位的证据”上，具备更精细的定位与解析能力。视觉指代/定位 (Visual Grounding) 解决了“指到哪/是哪一个”的问题，是细粒度 VQA 和具身智能的前置能力。这一能力可扩展为“音频/视频 Grounding”（定位视频时间片段或音频事件区间），以及“传感器时序对齐”（把语言指令落到某段传感器时间窗）。除此之外，文档与图表理解 (Document & Diagram Understanding)（OCR、表格布局、坐标轴等）也是一类高频结构化输入，在多模态理解与推理基准中占有重要位置。这一层级决定了后续推理是否建立在准确的证据之上。

（3）生成与转换

当模型具备了理解能力后，下一步就是跨越模态创造新信息。这一层级的核心是跨模态生成与条件生成。图生文 (Image Captioning) 要求模型“看图说话”，将视觉信息翻译为自然语言；而 文生图 (Text-to-Image) 则如 Stable Diffusion，通过文本提示控制像素生成。近年来的视觉语言模型（如 LLaVA）往往不以“纯 Caption 数据集训练”作为唯一目标，而是通过视觉-语言对齐与指令数据进一步增强“可对话、可解释、可执行指令”的生成能力。推广到其他模态，还包括“文生音频/音频生文”（语音识别、音频描述/摘要）、“视频→文本总结”，以及“传感器→文本报告/告警解释”（把多路时序生成结构化告警或自然语言报告）。统一来看，这一层解决的是跨模态 Mapping 与条件生成。

（4）复杂推理与控制

这部分是目前多模态大模型的前沿高地，核心是结合外部知识与上下文进行多步思考或行动。在更具挑战性的视觉问答/视觉对话/多模态推理基准中，模型不仅要“看懂并描述”，还要围绕问题组织证据、进行多步推理并给出可追溯结论。更进一步则是 具身智能 (Embodied AI)，例如指令机器人“去厨房拿那个红色的苹果”，要求模型不仅能理解视觉场景，还要规划动作序列并执行。在其他模态中，这对应了“视听多步推理”（基于视频+音频回答事件因果/流程问题），以及“多传感器决策控制”（融合摄像头、雷达、IMU 等信号做规划/控制）。这一层级的能力往往受限于对齐精度、证据可追溯性与长序列建模成本，它的目标不仅是让模型“能回答”，更要实现“基于证据的推理与行动”。

2.2 多模态机器学习五大挑战

在明确了任务图谱后，我们自然会想到实现这些任务的难点在哪里？Baltrušaitis、Ahuja、Morency 在其多模态机器学习综述与分类中提出的“五大挑战”（表征、转换、对齐、融合、协同学习），即便在 LLM 时代，依然是审视多模态架构设计的高频框架 ⁸。结合 Mercari Tech Blog 的工程视角解读 ⁹，我们可以通过表 19-1 更具体地理解这五个维度的核心难题：

挑战维度	核心关注	主要难点	演进与策略
表征	异构数据映射到统一空间	数据形式差异巨大（如离散符号 vs 连续像素），且含不同程度噪声与冗余。	常见策略是“各模态专用编码器 + 共享 token 空间/Transformer 交互”，或先做统一 token 化再用 Transformer 建模，在保留模态特性的同时挖掘互补信息。
转换	模态之间的映射与生成	克服“一对多”映射歧义性（Ambiguity），保证“翻译”的语义一致性与真实性。	涵盖从图生文（Captioning）到文生图（Diffusion）的多向生成，重点解决逻辑性与质量难题。
对齐	跨模态元素的对应关系	识别不同模态中指代同一实体或事件的子结构（从 Patch/Token 到全局 Instance）。	通过 CLIP 对比学习，在大规模数据上显式拉近配对数据距离，建立语义匹配。
融合	信息的整合与推理	决策时有效结合多模态信息，消除歧义并抑制冲突带来的幻觉。	引入 Cross-Attention 等深度交互机制（如 LLaVA），替代简单拼接以实现协同增益。
协同学习	知识的跨模态迁移	如何利用高资源模态（如文本）辅助低资源模态的学习。	典型手段包括跨模态迁移/蒸馏、伪标注、联合预训练与缺失模态鲁棒训练；目标是在模态可用性不一致时仍能可靠泛化（包括 zero-shot / few-shot）。

表 19-1 多模态机器学习五大挑战（基于综述与工程解读）

三、应用场景

截止 2026 年，多模态模型已经不再是停留在实验室的理论模型，而是深入渗透到了各类业务场景中。基于行业实践（如电商、自动驾驶、娱乐等），我们可以将纷繁复杂的多模态应用版图整合为四大核心领域：

（1）商业与消费体验：商业与消费领域直接面向消费者（ToC），核心价值是通过增强体验来促进交易与娱乐，是目前多模态技术变现最成熟的赛道。在全链路电商体验方面，涵盖从“搜”到“买”的全流程，其中多模态推荐融合商品图片、描述与评论实现深度个性化，视觉搜索支持“拍立淘”式的以图搜图或跨模态检索，虚拟试穿则通过 3D 渲染结合 CV 关键点技术或利用生成式模型提供逼真的在线试穿体验。内容创作与娱乐则通过虚拟人在直播带货与短视频中结合 TTS 与 CV 技术实现实时互动，游戏 NPC 也正从脚本驱动转向多模态驱动，能根据玩家的语音语调、动作甚至表情做出动态反应。例如在一些公开演示/宣传案例中（如图 19-2），游戏 NPC 被展示为可根据玩家语言进行情境化行动，从而带来更强的沉浸式互动。

图 19-2 逆水寒智能 NPC

（2）企业级认知与服务：企业级服务主要面向企业（ToB）与专业机构，目标是降本增效，处理高密度的复杂信息流。比如智能客服与交互超越纯文本问答，多模态客服能理解用户发送的截图（如报错页面）或语音（带情绪的投诉）并精准回复，公共场所的流媒体智能屏则可在合规授权的前提下基于视觉感知进行定向信息交互。在文档与知识处理领域，智能文档处理 (IDP) 作为 OCR、文档解析与信息提取的系统工程，不仅识别文字，还能精准还原发票、标书以及笔记中的版面布局与表格结构，如图 19-3 就是 PaddleOCR-VL 对笔记的识别效果。除此之外，多模态翻译在视频会议中可同步处理语音翻译、语气调整甚至画面中的文字替换。金融风控则是结合声纹特征、设备指纹、用户行为序列及多源一致性校验构建更立体的反欺诈体系，部分场景也在探索微表情等辅助信号。

图 19-3 PaddleOCR-VL 识别效果

（3）实体智能与出行：实体智能代表了 AI 从“数字世界”走向“物理世界”的关键一步，要求模型具备感知环境并执行动作的能力。自动驾驶以特斯拉（尽量减少对雷达依赖的视觉主导路线）和“蔚小理”（多传感器融合路线）为代表，行业虽然长期目标是 L5（完全自动驾驶，无需人类干预），但当前主流仍聚焦于 L2+/L3 的工程化落地，其中 L2+ 需要驾驶员持续监督，L3 在其 ODD（运行设计域）内可由系统监控环境但需要驾驶员在系统请求时接管。在感知层面，车辆需实时处理异构数据，视觉主导路线侧重于摄像头的深度挖掘，融合路线则进一步结合激光雷达和毫米波雷达以提升冗余度，完成路径规划与避障。机器人则涵盖了从商场导购机器人到家用扫地机等多种形态，不仅要“看”（视觉 SLAM 建图），还要“听”（语音指令识别），并结合触觉传感器与物理世界交互。更前沿的还有特斯拉 Optimus、宇树 G1等正在快速发展的具身智能（Embodied AI），趋势是用端到端（或弱分层）的策略模型把多模态感知（视觉/深度/力觉等）与动作决策连接起来，输出动作序列或关节控制指令，并在真实环境中通过数据驱动学习实现泛化与闭环控制。

图 19-4 Unitree H1

（4）科学与医疗探索：在对数据精度与隐私要求极高的专业领域，多模态技术也在辅助专家突破人类认知的边界。智慧医疗整合医学影像（CT/MRI）、电子病历（文本）与生化指标（结构化数据）辅助癌症筛查或病情预判，该领域的难点在于极低的容错率，必须严格抑制幻觉并引入人类专家复核（HITL）与可追溯证据机制。还有跨学科科研中，多模态模型可以被用于遥感/卫星图像与文本报告的联合分析（如灾害评估、土地覆盖变化），以及在生命科学中融合成像数据、组学表格、序列/结构信息与文献文本进行证据汇总、假设生成与实验设计，加速从研究到应用的闭环。

参考文献

分布式训练框架 DeepSpeed

Fri, 27 Mar 2026 15:40:25 -0800

分布式训练框架 DeepSpeed

一、DeepSpeed 全家桶一览

1.1 DeepSpeed 概述

我们在前面已经通过 QLoRA、PEFT、RLHF 等技术，体验了在单机单卡甚至消费级显卡上完成大模型微调的可能性。但如果目标从“微调一个 7B 模型”升级为从零预训练、全量微调甚至训练万亿参数模型，仅靠量化与 LoRA 显然还不够，此时就需要引入微软开源的 PyTorch 分布式训练与推理优化库 DeepSpeed。它的目标是让开发者在相同硬件条件下用更少的显存训练更大的模型、训练更快、扩展更稳，并提供从训练到推理的一整套工程化组件。它与 Hugging Face 的关系可以简单理解为 Hugging Face 更偏向“模型与数据”的生态（transformers、datasets 等），而 DeepSpeed 更偏向“系统与算力”的生态（显存优化、并行策略、通信调度等）。

图 13-7 DeepSpeed 官方文档 Getting Started 页面

在微软的官方介绍中，DeepSpeed 的主要子模块包括本节的主角 DeepSpeed Training（包含 ZeRO、Offload、Infinity、3D 并行等训练技术），针对推理和压缩（量化、剪枝、KV Cache 优化等）的加速库 DeepSpeed Inference / Compression，面向 MoE 大模型的高效路由与通信实现 DeepSpeed-MoE，支持大规模 RLHF、DeepSpeed-Chat 等对话模型训练的 DeepSpeed-Chat / RLHF，以及将这些系统能力扩展到科学计算场景的 DeepSpeed for Science。日常工作中，最常见的两个使用场景是当我们想在单机多卡或多机多卡环境下进行预训练或全量微调大模型时，通常会重点使用 DeepSpeed Training + ZeRO。而当我们需要在服务器上部署一个高吞吐的推理服务时，则会更多地结合 DeepSpeed Inference 与各类量化/压缩技术一起使用。

1.2 DeepSpeed Training 要解决的三大挑战

DeepSpeed Training 希望解决的是这样一个组合问题。一是显存不够，单张 GPU 就算有 80GB 显存，也远远放不下万亿参数的模型训练所需状态（权重、梯度、优化器状态、激活值）；二是加速比不理想，单纯堆 GPU 数量，在数据并行下很快就会遇到通信瓶颈，难以获得接近线性的加速；三是硬件异构，现实集群中同时存在 GPU 显存、CPU 内存、NVMe SSD 甚至远程存储，如何让这些异构资源一起“干活”，而不是让昂贵的 GPU 无限空等。围绕这三个问题，DeepSpeed 提出了以 ZeRO（Zero Redundancy Optimizer） 为核心的一系列技术（ZeRO、ZeRO-Offload、ZeRO-Infinity），再叠加数据并行、模型并行、流水线并行构成完整的 3D 并行框架。

二、显存开销与 ZeRO 系列内存优化

前面我们已经学会了如何估算推理阶段的显存开销，知道“只加载权重并做前向传播”大概需要多少显存。这里我们换一个视角，聚焦在训练相对于推理多出来的那一部分显存。相比只做推理或只训练极少量 LoRA 参数的 QLoRA 微调，全量预训练或全量微调需要为每一个参数额外维护梯度和优化器状态，而这正是 ZeRO 要重点优化的部分。为了更直观地理解这一点，我们先以一个 7B 模型为例，看看在不做任何内存优化时，全量训练大致需要多少显存。

2.1 Qwen2.5-7B 全量训练需要多少显存？

假设我们想要对一个 7B 模型（约 70 亿参数）进行全量预训练或微调，并采用常见的 Adam 优化器和混合精度训练策略。

（1）模型权重

存储精度：通常采用 FP16/BF16（2 Bytes）；
显存占用：

$$ \text{Param} \approx 7 \times 10^{9} \times 2\ \text{Bytes} \approx 14\ \text{GB} \tag{13.11} $$

（2）梯度

反向传播中同样以 16-bit 精度存储；
显存占用与参数同量级：

$$ \text{Grad} \approx 14\ \text{GB} \tag{13.12} $$

（3）优化器状态——以 Adam 为例

在优化器内部，一般会将参数提升为 FP32（4 Bytes） 精度来计算更新；
对每个参数，Adam 至少需要存储：
- 一个 FP32 精度的参数拷贝（Master Weights）；
- 一阶动量 $m$；
- 二阶动量 $v$。
每个状态都是 4 Bytes，因此单参数的优化器状态一共约 12 Bytes：

$$ K_{\text{Adam}} = 4\ (\text{master}) + 4\ (m) + 4\ (v) = 12\ \text{Bytes} \tag{13.13} $$

对于 7B 参数模型：

$$ \text{OptStates} \approx 7 \times 10^{9} \times 12\ \text{Bytes} \approx 84\ \text{GB} \tag{13.14} $$

（4）总显存开销（不含激活与碎片）

把上述三部分加起来：

$$ \text{Mem}_{\text{states}} \approx (14 + 14 + 84)\ \text{GB} = 112\ \text{GB} \tag{13.15} $$

再考虑到中间激活、临时张量、显存碎片等，实际训练中的峰值显存往往会来到 120GB 甚至更高。很多资料中常见的结论，一个 7B 模型如果想全量训练，大概需要 120GB 显存，就是由这一组估算推导出来的。

为了便于后续讨论，可以把“每个参数对应的字节数”抽象写成：

$$ \underbrace{2}_{\text{参数}} + \underbrace{2}_{\text{梯度}} + \underbrace{12}_{\text{优化器}} = 16\ \text{Bytes/Param} \tag{13.16} $$

也就是说，在经典数据并行 + Adam 的设定下，每个可训练参数平均需要约 16 Bytes 显存（不含激活）。这就是 DeepSpeed 想要“动刀”的地方。如果我们能把这 16 Bytes 中的冗余复制部分打散分摊到多张卡上，每张卡就不需要承担完整的 16 Bytes 开销，从而在固定总 GPU 数量下训练更大的模型。

2.2 Zero Redundancy Optimizer 的分治思路

回到刚才的结论，在经典数据并行 + Adam 的设定下，每个参数都会对应一整套模型状态。在 Data Parallel（数据并行） 中，会用 $N$ 张 GPU，每张 GPU 上都存一份完整的模型状态副本，每次训练时由不同 GPU 处理不同的数据子集（batch 切分），计算结束后再通过 all-reduce 汇总梯度并统一更新参数。这样一来，那一整套模型状态会在每张卡上各复制一份，总共变成 $N$ 份，这部分跨设备的重复存储就是所谓的“冗余”。ZeRO 的名字 “Zero Redundancy Optimizer” 正是针对这一痛点而来 ¹，它的核心思路是将这些冗余的模型状态在不同 GPU 之间分片（Shard），从“人人持有一整份”变成“大家一起拼一份”，从而降低单卡显存压力。

All-Reduce（全归约）的内部拆解

标准的 All-Reduce 操作（让每张卡都得到梯度的总和/平均）通常由两步完成：

Reduce-Scatter（分散归约）：大家手里都有一部分数据（如梯度），先将不同部分归约（求和/平均）到不同的 GPU 上。结果是每张 GPU 只握有一部分归约后的完整结果。

All-Gather（全局收集）：大家手里都有一部分数据（如参数分片），通过广播互换，最终每张 GPU 都收集到了所有人的数据，拼成了一份完整的数据副本。

2.2.1 ZeRO 的三个 Stage 在分谁？

ZeRO 将显存优化分为三个递进的阶段，关键是逐步把优化器状态（Optimizer States）、梯度（Gradients） 和 模型参数（Parameters） 从“每卡完整复制”变为“多卡分片存储”。

在经典数据并行下，每张 GPU 需要维护：

$$ \text{Mem}_{\text{DP}} \propto OS + G + P \tag{13.17} $$

其中，$\text{Mem}_{\text{DP}}$ 表示在经典数据并行（Data Parallel, DP）设定下单张 GPU 上用于存储模型状态的显存开销，而 $OS$、$G$、$P$ 分别代表优化器状态、梯度和参数，这里只关注它们的相对规模，所以用“$\propto$”表示与这三部分之和成正比。

这个过程中 ZeRO 分别在三个 Stage 中逐步把这三类状态打散到多张 GPU 上：

（1）ZeRO-1（Optimizer States Sharding）

在这一阶段，ZeRO 仅对优化器状态（OS）进行分片，而参数（P）与梯度（G）仍然在每张 GPU 上完整保存。此时，单卡显存开销近似变为：

$$ \text{Mem}_{\text{ZeRO-1}} \propto P + G + \frac{OS}{DP} \tag{13.18} $$

相当于大家依然各自持有完整的模型和梯度，但优化器状态（如 Adam 的动量）被切分了，每张卡只负责维护其中一小块。由于优化器状态在总显存中占比往往最大（约 75%），仅这一步就能带来显著的显存节省。这也是为什么在当前的大模型训练实践中，ZeRO-1 往往被视为“最低配置”或默认开启的基线功能。

（2）ZeRO-2（OS + G 分片）

在 ZeRO-1 的基础上，ZeRO-2 进一步对梯度进行了分片，此时只有参数仍完整复制在每张卡上。单卡显存进一步降低为：

$$ \text{Mem}_{\text{ZeRO-2}} \propto P + \frac{G}{DP} + \frac{OS}{DP} \tag{13.19} $$

这通常能带来约 8～16 倍的显存节省（视 DP 并行度而定），使得单卡能训练更大的模型。

（3）ZeRO-3（OS + G + P 全分片）

这是“火力全开”的终极形态，对模型参数本身也进行了分片。此时每张 GPU 只保存整个模型参数的一部分，单卡显存变为：

$$ \text{Mem}_{\text{ZeRO-3}} \propto \frac{P}{DP} + \frac{G}{DP} + \frac{OS}{DP} \tag{13.20} $$

理论上，随着 GPU 数量的增加，单卡显存占用可以被压缩到原来的 $1/DP$ 量级，这就是训练万亿参数模型的关键所在。

如图 13-8 展示了 Baseline 与 ZeRO 三个阶段在显存占用上的对比。随着 ZeRO 阶段的深入，单卡显存占用（绿色代表优化器状态，橙色代表梯度，蓝色代表参数）被逐步“削减”和分摊。

图 13-8 ZeRO 各阶段显存占用对比图

如果把之前说的 “16 Bytes/Param” 的分解代入（其中 OS = 12 Bytes，G = 2 Bytes，P = 2 Bytes），可以用一个更直观的形式表示：

$$ \text{Bytes/Param} \approx \begin{cases} 2 + 2 + 12, & \text{Baseline 数据并行}\\ 2 + 2 + \dfrac{12}{DP}, & \text{ZeRO-1}\\[4pt] 2 + \dfrac{2}{DP} + \dfrac{12}{DP}, & \text{ZeRO-2}\\[4pt] \dfrac{2}{DP} + \dfrac{2}{DP} + \dfrac{12}{DP}, & \text{ZeRO-3} \end{cases} \tag{13.21} $$

当 DP=64 时，ZeRO-3 能将每参数平均显存从 16 Bytes 压缩到约 $16/64 \approx 0.25$ Bytes 量级（不含激活与碎片），这就是论文中在 64 张 V100 上用 16GB 单卡显存训练万亿参数模型的底层逻辑。

为了更直观地感受这三个阶段的威力，我们可以参考 ZeRO 论文中的实测数据（表 13-2）。表中展示了不同参数规模的模型，在不同 GPU 数量下，开启 ZeRO 各阶段后的单卡显存占用（单位：GB）：

DP (GPUs)	7.5B 模型 (ZeRO-1 / 2 / 3)	128B 模型 (ZeRO-1 / 2 / 3)	1T 模型 (ZeRO-1 / 2 / 3)
1	120 / 120 / 120	2048 / 2048 / 2048	16TB / 16TB / 16TB
64	31.4 / 16.6 / 1.9	536 / 284 / 32	4.2TB / 2.2TB / 250
1024	30.1 / 15.1 / 0.1	513 / 257 / 2	4TB / 2TB / 15.6

表 13-2 不同模型规模与并行度下的 ZeRO 单卡显存占用对比 (单位: GB)

能够看到如果不使用 ZeRO（相当于第一行 DP=1 的情况），训练一个 1T 参数模型需要单卡 16TB 显存，这在现有硬件上是不可能的。但如果开启 ZeRO-3 并在 1024 张 GPU 上并行（最后一行最右侧），单卡显存仅需 15.6 GB！这意味着用现有的 16GB/32GB 显卡集群就可以训练万亿参数模型。

2.2.2 通信开销与“线性加速比”的平衡

在分片带来显存红利的同时，也会引入额外的通信开销。ZeRO 论文中对通信量（Communication Volume）进行了详细分析（假设模型参数量为 $\Psi$）：

ZeRO-1 / ZeRO-2：通信量为 $2\Psi$，与标准数据并行同阶。直观理解是把标准 DP 的 all-reduce 用 reduce-scatter + all-gather 这类等价组合来实现后，总通信量量级不变，但通信“形态”发生了变化（例如 ZeRO-2 需要配合分片优化器在 step 内做参数分片的聚合/同步）。
ZeRO-3：通信量为 $3\Psi$，约为标准数据并行的 1.5 倍。这是因为在前向/反向传播中需要为计算临时聚合当前层所需参数分片（可理解为额外的参数 all-gather），再叠加梯度的 reduce-scatter 与更新后参数的同步通信。虽然通信量上升，但换来的是参数级别的全分片，使得单卡显存占用能随 GPU 数量近似按 $1/DP$ 下降。

总的来说，ZeRO 系列论文和 DeepSpeed 的工程实现，核心就是在显存开销、通信带宽与计算时间三者之间找到一个工程上可接受、又足够通用的平衡点。由于 ZeRO 节省了大量显存，往往允许使用更大的 Batch Size，可以显著提升计算的算术强度，在部分场景下甚至能观察到**超线性加速（Super-linear Speedup）**的效果。

2.3 ZeRO-R

在实践中，即使把参数、梯度和优化器状态都进行了分片优化，训练过程中的显存峰值仍然可能被其他因素“偷走”。例如，中间激活值的缓存、反向传播中临时张量的创建与释放、显存碎片（Fragmentation）导致的不可用空间，以及不均匀的 layer 配置导致的部分 GPU 负载不均，都可能成为新的显存瓶颈。

为此，论文中提出了一个补充模块 ZeRO-R，主要从三个维度进一步优化显存使用：

分区激活检查点（Partitioned Activation Checkpointing, $P_a$）
- 结合 Activation Checkpointing，但在模型并行（MP）中，ZeRO 进一步删除了激活值的复制冗余；
- 仅保留分片的激活检查点，需要时通过 all-gather 重建。这使得激活显存随 MP 并行度线性降低。
恒定大小缓冲区（Constant Size Buffers）
- 将很多临时张量的分配重定向到一个或少数几个可复用的大型 buffer 中；
- 避免频繁的小块分配与释放造成的显存碎片。
显存碎片整理（Memory Defragmentation）
- 对显存中的可用区域做更加智能的分配策略；
- 在长时间训练过程中保持可用显存的有效比例。

这些优化看起来只是“工程小技巧”，却往往决定了：你是刚好能跑起来，还是训练到一半 OOM 崩溃。

2.4 ZeRO-Offload

2.4.1 为什么需要 Offload？

前面的 ZeRO 假设所有模型状态（无论是否分片）都存放在 GPU 显存中。但在许多现实环境下，GPU 显存资源往往非常有限（比如每卡仅 16GB～24GB），而 CPU 内存则相对“富裕”（几十 GB 甚至上百 GB）。如果能把一部分状态“搬”到 CPU 内存上，哪怕训练速度稍慢一点，也能让普通用户“有机会”训练参数量大得多的模型。

ZeRO-Offload 的思路是把一部分原本需要占用 GPU 显存的模型状态（最典型的是 FP32 master weights 与优化器状态，以及在某些配置下的梯度缓冲区），卸载（Offload）到 CPU 内存上，由 CPU 负责更新；GPU 侧则尽可能聚焦前向/反向的计算 ²。论文从训练数据流与通信量角度分析了这种“GPU 计算前向/反向 + CPU 计算参数更新”划分在多种约束下的合理性。图 13-9 展示了其核心架构：GPU 负责计算密集型的前向与反向传播（FWD-BWD Super Node），CPU 负责显存密集型的参数更新（Update Super Node）。图中 M 表示模型参数量，对应箭头上的 2M/4M 可理解为一次 step 内在 CPU 与 GPU 之间需要交换的数据量级（常见的拆解是：梯度约 2M（FP16），参数回传约 2M（FP16），合计约 4M；而 FP32 master 与优化器状态主要驻留在 CPU 内存中）。

图 13-9 ZeRO-Offload 数据流与计算划分示意图

2.4.2 单机单卡下的典型数据流与优化

在单卡 + ZeRO-Offload 的设定下，一次训练 step 的简化流程大致如下：

（1）GPU 上前反向传播，必要时将梯度/分片梯度 Offload 到 CPU：

GPU 上保留用于计算的 FP16/BF16 参数副本，完成前向计算得到激活与 loss，并进行反向传播得到梯度。随后根据配置（例如是否做梯度分片、是否将梯度缓冲转移到 CPU），通过 PCIe/NVLink 将梯度（或梯度分片）拷贝到 CPU 内存，以释放 GPU 显存压力并为 CPU 侧更新做准备。

（2）CPU 上执行优化器更新（更新 FP32 master 与优化器状态）：

CPU 内存中保存着 FP32 精度的 master weights 以及 Adam 的 $m$、$v$ 等状态。CPU 利用刚刚拷贝来的梯度更新这些状态，得到新的参数值（此时仍在 CPU 端）。为了降低 CPU 侧优化器成为瓶颈的风险，ZeRO-Offload 会采用高度优化的 CPU Adam 实现（例如利用 SIMD 指令与多线程并行）。同时，为了进一步掩盖 CPU 计算与 CPU↔GPU 交换的延迟，论文还提出了单步延迟更新（One-Step Delayed Parameter Update, DPU）机制，允许 CPU 的参数更新与 GPU 下一步的前向/反向计算在一定程度上重叠执行。图 13-10 用“计算流（Computation stream）”与“交换流（Swapping stream）”展示了这种 overlap 的直觉：Step i 的梯度产生后，CPU 开始更新参数；GPU 则可以更早进入 Step i+1 的计算阶段，从而减少等待。这种重叠执行有效地掩盖了 CPU 计算和 CPU↔GPU 通信带来的延迟，保证了训练的高吞吐量。虽然 GPU 可能会使用旧一步的参数进行计算，但实验证明这几乎不影响收敛性。

图 13-10 单步延迟更新机制（One-Step Delayed Parameter Update）

（3）将更新后的参数（FP16 计算副本）回传到 GPU：CPU 完成更新后，将用于计算的 FP16/BF16 参数副本同步回 GPU，进入下一个训练 step 的循环（实际系统里通常会分层/分 bucket 同步，并尽量与计算重叠）。

通过这种设计，ZeRO-Offload 在单卡 V100 (32GB) 的设置下可将可训练模型规模提升到 10B 量级（论文示例中最高约 13B），并在一定条件下保持较高吞吐（数量级可达数十 TFLOPS）。不过在多卡训练场景下，ZeRO-Offload 通常不会简单地让每张卡各自与 CPU 做大规模同步（这会更容易触及 PCIe/主机内存带宽瓶颈），而是结合 ZeRO-2 的梯度分片机制来控制交换量，先在 GPU 端对梯度做 Reduce-Scatter，将 $N$ 张卡上的梯度切分成 $N$ 份；随后，每张 GPU 只需将自己负责的那 $1/N$ 份梯度 Offload 到 CPU；接着，CPU 并行更新对应的参数分片；最后更新后的参数分片回传到各自 GPU，并通过 All-Gather 同步到需要完整参数副本的设备上。得益于这种“先分片、再 offload”的设计，CPU↔GPU 的交换开销通常不会随卡数线性膨胀，更有利于扩展到更大规模集群。

2.5 ZeRO-Infinity

2.5.1 突破显存与带宽墙

如果说 ZeRO-Offload 把 CPU 内存也纳入了训练资源，那么 Ren 等人提出的 ZeRO-Infinity ³ 则更进一步，把 NVMe SSD 甚至远程存储 也纳入了统一的“内存池”视角。它的思路是构建一个多层次的异构内存体系，GPU HBM 显存作为 Fast 层，容量最小但带宽最高（几百 GB/s），仅用于存放当前正在参与计算的参数 shard 与激活；CPU DRAM 作为 Medium 层，容量较大但带宽较低，存放近期会被访问的参数、优化器状态与激活片段；NVMe / SSD 则作为 Slow 层，容量最大但带宽延迟最差，用于存放远期才会被访问或备用的模型状态。Infinity Offload Engine 能够自动管理这三层存储之间的数据流动，实现全量 Offload。所以，只要 NVMe 硬盘够大，理论上就可以存放任意规模的模型状态，而不仅仅局限于 CPU 内存大小。

NVMe (Non-Volatile Memory Express) 是一种专为 SSD 设计的高速通信协议。它直接利用 PCIe 通道与 CPU 通信，相比传统的 SATA 协议（最初为机械硬盘设计）具有极高的吞吐量和极低的延迟。

不过，将数据放在 NVMe 上最大的挑战是带宽（PCIe 3.0/4.0 远慢于 HBM）。ZeRO-Infinity 提出了 Bandwidth-Centric Partitioning（以带宽为中心的切分） 策略。传统的 Offload（如 ZeRO-Offload）通常受限于单张卡的 PCIe 带宽，而 ZeRO-Infinity 利用 All-Gather 通信模式，让所有 GPU 同时从 CPU/NVMe 拉取不同的数据分片。其效果是有效加载带宽随 GPU 数量 线性增加。例如在 64 张 GPU 的集群上，它能利用 64 条 PCIe 通道的聚合带宽，从而掩盖 NVMe 读写慢的问题。如图 13-11 展示的带宽为中心的分区策略，模型状态被切分并存放在慢速存储（CPU + NVMe）中。与传统的让单个 GPU 负责所有数据传输不同，ZeRO-Infinity 让每张 GPU （$GPU^{(0)}$ 到 $GPU^{(3)}$）并行地通过 All-Gather 操作仅拉取自己负责的那一小部分数据（如 $P_0^{(0)}$）。这样一来，整个系统的有效带宽就变成了所有 GPU PCIe 带宽的总和，极大地提升了从慢速存储加载数据的效率。

图 13-11 ZeRO-Infinity 带宽为中心的切分 (Bandwidth-Centric Partitioning) 示意图

2.5.2 突破单层限制

即使模型总状态能存下，超大模型（如万亿参数）的单个层也可能大到无法放入单张 GPU 的显存中。ZeRO-Infinity 引入了 Memory-Centric Tiling（以内存为中心的切片），把一个巨大的 Operator（例如超大矩阵乘法）拆解为一系列更小的 Tiles，每次只加载一个 Tile 到 GPU 参与计算，算完释放，再加载下一个。需要注意的是，这类 tiling 能在一些场景下降低对张量并行（TP）的刚性依赖，但并不意味着“完全替代模型并行”。工程上仍需结合算子形态、通信带宽与吞吐目标综合选择并行策略。

得益于这些技术，ZeRO-Infinity 实现了自动化模型切分，即在模型初始化阶段（__init__）就自动进行切分和 Offload，防止初始化时就 OOM。同时，它还展现了惊人的扩展性，论文展示了在**单台 DGX-2 节点（16 张 V100）**上即可微调 1 万亿参数的模型；在 512 张 GPU 上可训练 32 万亿参数的模型。从设计目标来看，ZeRO-Infinity 甚至将视野投向了支撑百万亿参数规模的超大模型训练。如图 13-12 所示，在相同硬件条件下（如 512 张 V100 GPU），ZeRO-Infinity 能支持的模型规模（32T）比最先进的 3D Parallelism（0.64T）高出 50 倍。

图 13-12 ZeRO-Infinity 与 3D Parallelism 在不同 GPU 规模下支持的最大参数量对比

三、DeepSpeed 中的并行策略与生态

3.1 并行策略

ZeRO 主要解决的是“模型状态如何分片”这个问题，但要在大规模集群上高效训练，还需要与其他并行策略配合使用，并理解它在更大生态中的位置。常见的四类并行是：

（1）数据并行（Data Parallelism, DP）：把同一个模型复制到多张 GPU 上，让不同 GPU 并行处理不同的数据子集。这种方式实现简单，通信模式清晰，且相对容易扩展到几十甚至上百张卡。不过，它的缺点是每张卡都需要存储一份完整的模型副本，对于大模型而言显存开销巨大。这也是 ZeRO 的作用所在——通过对 OS/G/P 的分片，打破“数据并行必须每卡存储完整模型状态”的限制 ⁴。

（2）模型并行（Model Parallelism, MP）：将同一个模型的计算与参数拆分到不同 GPU 上，以突破单卡显存限制。工程实践中更常见的是按张量维度拆分（张量并行/TP）：例如在单层内将大矩阵按列或行切分到多卡上，由多张卡协作完成同一个算子的计算。它的优点是能在不改变整体网络结构的情况下把“单层算子”做细粒度拆分；缺点是通信更频繁，对跨节点带宽更敏感（常见通信包括 all-gather / reduce-scatter 等）。需要区分的是，ZeRO-3 虽然通过参数切分大幅降低了显存占用，但它本质上仍属于数据并行的优化（计算时不拆分算子）。而 DeepSpeed 支持与 Megatron-LM 等张量并行库结合，实现的是算子内部的细粒度拆分与并行计算（即多张卡协作完成一个算子的计算）⁵。

（3）流水线并行（Pipeline Parallelism, PP）：将模型不同层段按“流水线工序”分配到不同 GPU，例如 48 层 Transformer，GPU0 负责第 1–12 层，GPU1 负责第 13–24 层，以此类推。如果只是做朴素的“按层切分”但不采用 micro-batch，那么后续 GPU 往往必须等待前一段 GPU 产出激活才能继续计算，容易出现较长的空转时间；而流水线并行通过 Micro-batch（微批次） 将一个大 Batch 切分成多个小块，使得各段 GPU 能交错处理不同 micro-batch，尽量填满计算时间片，并常与 Activation Checkpointing 配合以降低激活显存。实践中的难点是需要合理设计 micro-batch 大小与流水线深度，以减少流水线启动与结束阶段因设备空闲等待而产生的“气泡”⁶⁷。

（4）3D 并行（3D Parallelism）：在实际的超大规模训练中，往往会同时使用 数据并行（DP）、张量并行（TP） 和 流水线并行（PP）（常写作 $DP \times TP \times PP$）。DeepSpeed 与 Megatron-LM 等框架联合，在 BLOOM 等超大开源模型中成功实践了这种 3D 并行 策略。简单来说就是 DP 解决“更多数据”的问题，TP/PP 解决“更大模型”的问题，ZeRO + Offload/Infinity 解决“显存不够 & 内存层次异构”的问题 ⁸⁹。

3.2 DeepSpeed 生态中的其他模块

在理解了 ZeRO 系列之后，再回头看 DeepSpeed 的其他模块就容易多了。

模块名称	核心功能与技术特性	应用价值与互补性
DeepSpeed-Inference / Compression	推理 Kernel 优化：如 attention/MLP 等算子融合、kernel injection 等。 KV Cache 优化：减少长上下文推理的显存与带宽开销。量化/剪枝集成：配合 GPTQ、AWQ、LLM.int8 等技术降低成本。	与量化互补：量化负责“把模型变小”，而它负责“让小/中等模型在多卡/多节点上跑得更快”。推理加速：显著提升推理吞吐量。
DeepSpeed-Chat 与 RLHF	全流程封装：提供 SFT / RM / RLHF（如 PPO 等）训练流水线，并与 ZeRO/并行策略结合以支撑更大规模对齐训练。高效并行实现：内置 ZeRO 与 3D 并行策略，解决千亿参数模型的显存与调度难题。	降低门槛：解决显存不足、并行策略复杂、混合调度困难等问题。大规模对齐：使大规模指令对齐训练在合理资源下成为可能。
DeepSpeed for Science	非 Transformer 支持：优化稀疏算子、复杂网格结构等科学计算常用结构。系统经验迁移：将 LLM 的大规模训练优化经验应用于科学模型。	解决同类难题：本质上解决的仍是“用有限 GPU 训练超大规模模型（如分子模拟、气候建模）”的系统工程问题。

表 13-3 DeepSpeed 生态模块功能一览

参考文献

模型量化实战

Fri, 27 Mar 2026 14:40:25 -0800

模型量化实战

在前面的实战章节中，为了在消费级显卡上加载大模型，我们已经初步体验了量化技术的魔力——只需几行代码配置 BitsAndBytesConfig，庞大的模型就能“塞”进显存。但你是否好奇，这背后的 int8 或 nf4 到底发生了什么？除了微调时用到的 BitsAndBytes，还有哪些量化技术更适合推理部署？

一、小资源干大活

1.1 冗余与压缩

量化，听起来是一个复杂的数学概念，但实际非常简单，就是用较少的信息来表示数据，在尽量不损失模型性能的前提下，降低资源开销。深度学习模型（无论是 CV 还是 NLP 领域）普遍表现出显著的参数冗余性。早在 1989 年，Yann LeCun 等人就在论文《Optimal Brain Damage》 ¹中指出神经网络中存在大量参数可以被删除而不影响准确率；而后续著名的“彩票假设”（The Lottery Ticket Hypothesis） ²更是进一步证明，密集网络中包含一个极小的子网络（“中奖彩票”），它的性能可与原始网络媲美。量化技术正是利用这一特性，通过降低非关键参数的数值精度（例如从 FP16 降至 INT4），在大幅减少显存占用和计算量的同时，尽可能保持模型的原始性能。

比如一张原本几十 MB 的高清无损照片（如 RAW 格式），在压缩为几百 KB 的 JPG 格式后，虽然丢失了大量人眼难以察觉的色彩细节（精度降低），但我们依然能清晰地识别出照片中的人物和风景。这种现象说明原始数据中包含大量对于“视觉理解”来说非必须的冗余信息。量化的过程也是类似，我们试图找出模型参数中那些对最终输出影响不大的微小精度，将其削减，在大幅降低显存占用的同时，保留模型的核心能力，实现**“瘦身不降智”**。

1.2 量化的价值

量化技术主要带来两方面的巨大收益：

（1）降低显存开销：通常模型以 FP16（16位浮点数）格式存储，若量化为 INT8（8位整数），显存占用直接减半；若进一步量化为 INT4（4位整数），显存占用仅为原来的 1/4。原本需要多张 A100 才能加载的千亿模型，量化后可能只需一张消费级显卡即可运行。

（2）提升推理速度：数据量的减少意味着内存带宽（Memory Bandwidth）压力的降低。在 LLM 推理这种典型的“内存受限（Memory-bound）”场景下，更快的权重加载速度直接转化为更快的 Token 生成速度。

二、从“装不下”到“跑得动”

2.1 精度与显存的关系

模型权重通常以浮点数形式存储，不同的精度决定了每个参数占用的字节数：

FP32（Full Precision）：单精度浮点数，占用 4 Bytes。这是深度学习训练的默认精度，但在推理时通常不需要这么高。
FP16 / BF16（Half Precision）：半精度浮点数，占用 2 Bytes。
- FP16：传统的半精度，数值范围较小，容易溢出。
- BF16（BFloat16）：Google 提出的格式，牺牲了小数位精度以换取与 FP32 相同的数值范围（指数位），训练更稳定，是目前大模型训练的主流选择。
INT8：8 位整数，占用 1 Byte。
INT4：4 位整数，占用 0.5 Byte（即 4 bit）。

2.2 显存估算公式

在动手实践之前，我们需要学会如何估算一个模型到底需要多少显存。在计算机存储单位中，1 GB = 1024 MB，1 MB = 1024 KB。但在估算模型参数量（如 7B = 7 Billion）和显存（GB）时，为了方便，通常近似认为 $1 \text{ GB} \approx 10^9 \text{ Bytes}$。如果追求精确计算，记得除以 $1024^3$。模型所需显存大小的通用估算公式如下：

$$ \text{权重显存占用} \approx \text{模型参数量} \times \text{每参数占用字节数} \tag{13.1} $$

以我们之前学习过的 Qwen2.5 为例，这里选择 Qwen2.5-7B（约 70 亿参数，即 $7 \times 10^9$）：

（1）FP16 / BF16 精度（2 Bytes/参数）：

$$ 7 \times 10^9 \times 2 \text{ Bytes} \approx 14 \text{ GB} \tag{13.2} $$

（2）INT8 量化（1 Byte/参数）：

$$ 7 \times 10^9 \times 1 \text{ Byte} \approx 7 \text{ GB} \tag{13.3} $$

（3）INT4 量化（0.5 Byte/参数）：

$$ 7 \times 10^9 \times 0.5 \text{ Byte} \approx 3.5 \text{ GB} \tag{13.4} $$

这只是模型权重的静态占用。实际运行时，还需要预留显存给：

KV Cache：上下文缓存，与序列长度（Context Length）成正比，上下文越长，占用越大。

激活值：中间层计算结果，与 Batch Size 和序列长度相关。

框架开销：PyTorch / CUDA context 本身会占用一定开销。

所以，实际显存需求通常比估算值高 20%~30%。例如加载 7B 的 INT4 模型（3.5GB 权重），推荐显存至少 6GB 起步。

三、Transformers 中的主流集成方案

虽然量化方法层出不穷，但在 Hugging Face Transformers 的官方文档与实践中，最常用的三类集成方式是加载 GPTQ、AWQ 以及 bitsandbytes（bnb）。在代码层面，它们通常通过 AutoModel*.from_pretrained(..., quantization_config=...) 搭配相应的配置类（如 GPTQConfig、AwqConfig、BitsAndBytesConfig）实现相对统一的调用体验。

如果从使用场景来区分，GPTQ 和 AWQ 主要面向推理部署与加速，它们属于 PTQ（Post-Training Quantization）算法，生成的模型通常以量化后的检查点形式保存，加载后显存占用低且推理速度快。bitsandbytes 则既常用于 8bit/4bit 推理，也是诸如 QLoRA 在内的一系列低显存微调方案的核心依赖，尤其擅长让大模型在单卡上完成 4-bit 训练。

3.1 面向生成式模型的高效量化

GPTQ (Generative Pre-trained Transformer Quantization) ³是一种面向大规模生成式 Transformer 的训练后量化（Post-Training Quantization, PTQ）技术。它是经典的 OBQ (Optimal Brain Quantization) 算法在超大模型上的高效进化版，基于近似二阶信息实现了一次性权重量化（one-shot weight quantization）。GPTQ 解决了以往简单的“四舍五入”（Round-to-Nearest, RTN）量化在模型参数超过百亿级时会导致严重精度崩塌的问题，成功将 1750 亿参数的超大模型压缩至 3-bit 或 4-bit，且几乎不损失精度。

GPTQ 的量化目标是最小化量化前后激活值的平方误差：

$$ \min_{\widehat{\mathbf{W}}} \| \mathbf{WX} - \widehat{\mathbf{W}}\mathbf{X} \|_2^2 \tag{13.5} $$

其中，$\mathbf{W}$ 为原始权重矩阵，$\mathbf{X}$ 为输入激活值矩阵，$\widehat{\mathbf{W}}$ 为量化后的权重矩阵。

GPTQ 的成功依赖于三个关键机制：

（1）二阶信息补偿：它利用海森矩阵（Hessian Matrix，$\mathbf{H} = 2\mathbf{X}\mathbf{X}^\top$）的二阶信息来判断权重的重要性。这就是识别“冗余参数”的重要数学工具。海森矩阵描述了损失函数曲面的曲率，如果某个权重方向上的曲率很小（平坦），说明该权重的微小变化对总误差影响不大，它是相对“冗余”的；反之则是“关键”参数。GPTQ 利用其逆矩阵 $\mathbf{H}^{-1}$ 来更新剩余权重，以补偿当前权重量化带来的误差 $\delta$：

$$ \boldsymbol{\delta}_F = - \frac{w_q - Q(w_q)}{[\mathbf{H}_F^{-1}]_{qq}} \cdot (\mathbf{H}_F^{-1})_{:, q} \tag{13.6} $$

其中，$w_q$ 是当前被量化的权重，$Q(w_q)$ 是其量化值，$\boldsymbol{\delta}_F$ 是对剩余未量化权重集合 $F$ 的更新向量，$\mathbf{H}_F^{-1}$ 是对应当前未量化权重的海森矩阵逆矩阵。

这里给出的只是 GPTQ 在分块/局部参数子集上的近似更新形式，省略了部分实现细节，主要是理解它利用二阶信息做误差补偿的思想。

（2）任意顺序与延迟批量更新：GPTQ 发现大模型不需要像 OBQ 那样进行昂贵的“贪心排序”，只需按顺序量化即可。同时，它引入了 Lazy Batch-Updates（延迟批量更新） 策略，将计算密集型的更新操作分块执行（如 128 列为一组），大大提升了 GPU 利用率。

（3）Cholesky 分解：为了解决大模型下海森矩阵逆计算的数值不稳定性问题，GPTQ 引入了 Cholesky 分解，确保了算法在千亿参数规模下的稳健运行。

GPTQ 的量化过程是分块进行的。如图 13-1，加粗的列块（Block）表示当前正在处理的列。左侧灰色部分是利用 Cholesky 分解预先计算好的逆 Hessian 信息。在处理当前块（橙色部分）时，算法会递归地逐列量化（中间白色列），并将量化误差利用预计算的 Hessian 信息“推”给后续未量化的权重（右侧蓝色部分）进行更新补偿，从而最大程度保留模型精度。

图 13-1 GPTQ 量化过程示意图

得益于上述优化，GPTQ 能以极快的速度（如 1750 亿参数仅需 4 小时）完成量化。实验表明，模型规模越大，GPTQ 带来的相对精度损失反而越小。如图 13-2，在 OPT 模型家族中，随着参数量增加（横轴向右），传统 RTN 方法（蓝线）的困惑度（PPL）急剧上升，意味着模型“崩了”；而 GPTQ（红线）则紧贴全精度基线（黑虚线），展现了极强的鲁棒性。生成的 INT4 模型配合 ExLlama 等专用内核，推理速度可达 FP16 的 3~4 倍。

图 13-2 GPTQ 与 RTN 在不同规模模型上的 PPL 对比

3.2 激活感知权重量化

AWQ (Activation-aware Weight Quantization) ⁴ 提出了一种更符合直觉且高效的量化思路，特别适合端侧部署。与 GPTQ 依赖复杂的二阶信息进行误差补偿不同，AWQ 另辟蹊径，发现权重的“重要性”并不取决于权重本身的大小，而取决于它所处理的激活值的大小。实验表明，仅保留 1% 的“显著权重”（即对应激活值较大的通道）为 FP16 精度，就能极大恢复模型性能。有趣的是，如果按权重本身的 L2 范数来选这 1%，效果和随机选差不多；但如果按激活值幅值来选，效果立竿见影。

为了工程落地，AWQ 并没有真正把这 1% 的权重存成 FP16（混合精度会拖累推理速度），而是采用了一种精妙的数学等价变换。如图 13-3 所示，(a) 中简单的 RTN 量化导致 PPL 高达 43.2，模型基本“报废”；(b) 展示了如果保留 1% 显著权重为 FP16，PPL 能降回 13.0，但混合精度效率低。AWQ 的做法是 (c)：找出那些对应较大激活值的权重通道，给它们乘上一个放大系数 $s$（Scale up），同时在输入 $x$ 上除以 $s$。

原理：在不改变线性层输出（例如 $y = \mathbf{w}\mathbf{x}$）的前提下，将“重要通道”的权重按系数 $s$ 放大、并将对应输入按 $1/s$ 缩小，使得整体计算在数学上保持等价，但被放大的权重在量化时的相对误差更小。
效果：当权重被放大后，其数值范围变大，相对量化误差（Relative Quantization Error）就会变小。AWQ 的优化目标是找到一组最优的缩放因子 $\mathbf{s}$，使得量化误差最小：
$$ \mathbf{s}^* = \arg \min_{\mathbf{s}} \mathcal{L}(\mathbf{s}) \tag{13.7} $$$$ \mathcal{L}(\mathbf{s}) = \| Q(\mathbf{W} \cdot \text{diag}(\mathbf{s})) (\text{diag}(\mathbf{s})^{-1} \cdot \mathbf{X}) - \mathbf{WX} \| \tag{13.8} $$
其中，$Q(\cdot)$ 表示量化函数，$\mathbf{W}$ 为原始权重，$\mathbf{X}$ 为输入特征，$\mathbf{s}$ 为我们需要寻找的最佳缩放因子向量，$\text{diag}(\mathbf{s})$ 是由 $\mathbf{s}$ 构成的对角矩阵。这就好比用一把尺子去量物体，把物体放大后再量，读数的相对精度自然就高了。最终 AWQ 在全 INT 量化下也能达到与混合精度相当的性能（PPL 13.0）。

图 13-3 AWQ 量化原理示意图：(a) RTN 导致精度崩塌；(b) 混合精度效果好但效率低；(c) AWQ 通过等价缩放实现全 INT 量化下的高性能

通过表 13-1 的实验结果可以看到，在 Llama-2-7B/13B/70B 等不同规模的模型上，AWQ（W4-g128）的困惑度始终低于 RTN 和 GPTQ。特别是在 70B 模型上，AWQ 的 INT4 量化效果（PPL 3.41）几乎与 FP16 全精度基线（PPL 3.32）持平，证明了其在保护模型性能方面的优越性。

PPL ↓		Llama-2			LLaMA
PPL ↓		7B	13B	70B	7B	13B	30B	65B
FP16	-	5.47	4.88	3.32	5.68	5.09	4.10	3.53
INT3	RTN	6.66	5.52	3.98	7.01	5.88	4.88	4.24
INT3	GPTQ	6.43	5.48	3.88	8.81	5.66	4.88	4.17
g128	GPTQ-R	6.42	5.41	3.86	6.53	5.64	4.74	4.21
g128	AWQ	6.24	5.32	3.74	6.35	5.52	4.61	3.95
INT4	RTN	5.73	4.98	3.46	5.96	5.25	4.23	3.67
INT4	GPTQ	5.69	4.98	3.42	6.22	5.23	4.24	3.66
g128	GPTQ-R	5.63	4.99	3.43	5.83	5.20	4.22	3.66
g128	AWQ	5.60	4.97	3.41	5.78	5.19	4.21	3.62

表 13-1 不同量化方法在 LLaMA/Llama-2 上的 PPL 对比

在 LLaMA、Mistral 等模型上，AWQ 的 INT4 量化几乎能达到 FP16 的无损性能水平。而且它具有端侧友好性，配合论文提出的 TinyChat 推理框架，作者展示了在高配 Jetson Orin 上以小 batch 形式运行 Llama-2-70B 的可能性；在树莓派等资源更受限的设备上，理论上也可以以 INT4 形式跑 7B 模型，但整体更偏 Demo/实验性质，速度和体验都会受到一定限制。

3.3 BitsAndBytes (BNB)

在前面的实战中，我们其实已经尝试使用了 BNB，通过配置 BitsAndBytesConfig 轻松实现了 4-bit 量化加载。如果说 GPTQ 和 AWQ 是侧重于“精打细算”的量化算法，那么 BNB 则是承载了 LLM.int8() ⁵和 QLoRA 等前沿研究的工程基石。它不仅是一个底层的 CUDA 库，更包含了一整套处理大模型量化难题的解决方案。BNB 的主要贡献是解决了大模型量化中一个棘手的**“离群值”问题。研究发现，当模型参数规模超过 67 亿（6.7B）时，Transformer 层中会系统性地涌现出少量数值巨大的离群特征（Emergent Outliers）**。虽然这些特征只占所有参数的约 0.1%，但它们对模型性能非常重要。传统的 8-bit 量化会将这些巨大的数值强制截断或粗糙量化，导致模型精度瞬间崩塌（如困惑度暴增）。如图 13-4，在 6.7B 参数规模处，普通 8-bit 量化（橙线）的准确率急剧下降，而 LLM.int8()（蓝线）则保持了与 16-bit 基线一致的性能。

图 13-4 模型规模与量化性能的关系

LLM.int8() 解决这一问题的主要原理是混合精度分解（Mixed-precision Decomposition）。它就像一个智能筛子，在推理过程中动态探测特征值的大小。对于 99.9% 的常规数值，使用**向量级量化（Vector-wise Quantization）**把它们压缩为 8-bit 进行矩阵乘法，以节省显存：

$$ \mathbf{C}_{f16} \approx \frac{1}{\mathbf{c}_{x} \otimes \mathbf{c}_{w}} \mathbf{C}_{i32} \tag{13.9} $$

其中，$\mathbf{C}{f16}$ 是近似的 FP16 输出结果，$\mathbf{C}{i32}$ 是 INT8 矩阵乘法得到的 INT32 结果，$\mathbf{c}{x}$ 和 $\mathbf{c}{w}$ 分别是输入 $\mathbf{X}$ 和权重 $\mathbf{W}$ 的量化缩放因子（Scaling Factors）。

而对于那 0.1% 超过阈值（如 6.0）的“离群”维度 $O$，则自动拆分出来，保持 FP16 高精度计算。最后将两部分结果合并（见图 13-5）：

$$ \mathbf{C}_{f16} \approx \underbrace{\sum_{h \in O} \mathbf{X}_{f16}^h \mathbf{W}_{f16}^h}_{\text{离群值 (FP16)}} + \underbrace{S \cdot \sum_{h \notin O} \mathbf{X}_{i8}^h \mathbf{W}_{i8}^h}_{\text{常规值 (INT8)}} \tag{13.10} $$

其中，$h$ 代表特征维度，$O$ 是离群特征维度的集合，$S$ 是去归一化项（对应上面的缩放因子乘积）。为了便于理解，这里对缩放因子 $\mathbf{c}{x}$、$\mathbf{c}{w}$ 和 $S$ 的张量维度及广播方式做了简化，实际工程实现中会针对 batch/head/channel 等维度分别维护缩放因子。

这种“抓大放小”的策略，让我们可以在几乎不损失任何精度的情况下，用 INT8 的显存开销运行超大模型。

图 13-5 LLM.int8() 混合精度分解示意图

在此基础上，BNB 进一步演进，成为了微调技术 QLoRA 的主要依赖。它引入了 NormalFloat4 (NF4) 数据类型，这是一种专门为正态分布权重量身定制的 4-bit 类型，比标准的 INT4 具有更高的信噪比。如今，通过 BitsAndBytesConfig，我们可以轻松调用这些技术，在单张消费级显卡上不仅能加载大模型，还能进行高效的微调。

四、Qwen2.5 模型推理量化实战

了解了量化的基本原理后，让我们进入实战环节使用 llmcompressor 库对 Qwen/Qwen2.5-1.5B-Instruct 模型分别进行 GPTQ 和 AWQ 的量化测试。

本节完整代码

4.1 环境准备

4.1.1 `llmcompressor` 简介

LLM Compressor ⁶ 是一个易于使用的库，目标是优化大语言模型以便使用 vLLM 进行部署。它能够实现高达 5 倍的推理速度提升，并显著降低成本。作为一个综合性的工具包，提供了以下核心功能：

算法支持丰富：支持包括 GPTQ、AWQ、SmoothQuant、SparseGPT 等在内的多种权重量化、激活量化和剪枝算法。
无缝集成：与 Hugging Face 的 Transformers、Models 和 Datasets 深度集成，使用体验流畅。
vLLM 友好：支持基于 safetensors 的压缩模型存储格式，可直接被 vLLM 加载。
高效处理：借助 accelerate 库，支持对超大模型进行高性能压缩。

如图 13-6 所示，LLM Compressor 的工作流程首先输入准备好的 Hugging Face 模型和（可选的）校准数据集；接着在压缩阶段，使用 llmcompressor 库应用量化算法（如 GPTQ、AWQ 等）；随后输出压缩后的模型检查点（Compressed Model Checkpoint）；最后在部署阶段，将压缩模型直接加载到 vLLM 中进行高效推理，最终服务于上层应用。

图 13-6 LLM Compressor 工作流程图

4.1.2 环境安装

接下来先安装 llmcompressor 库，它提供了一套统一的 API 来执行各种量化算法，简化了 auto-gptq 或 autoawq 等底层库的调用。

1

pip install llmcompressor

验证安装是否成功：

1

pip show llmcompressor

如果得到类似这样的输出就说明安装成功了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Name: llmcompressor
Version: 0.9.0
Summary: A library for compressing large language models utilizing the latest techniques and research in the field for both training aware and post training techniques. The library is designed to be flexible and easy to use on top of PyTorch and HuggingFace Transformers, allowing for quick experimentation.
Home-page: https://github.com/vllm-project/llm-compressor
Author: Neuralmagic, Inc.
Author-email: support@neuralmagic.com
License: Apache
Location: c:\users\dalvqw\.conda\envs\peft\lib\site-packages
Requires: accelerate, auto-round, compressed-tensors, datasets, loguru, numpy, nvidia-ml-py, pillow, pyyaml, requests, torch, tqdm, transformers
Required-by:

4.2 GPTQ 量化实战

4.2.1 初始化环境

这里我们不仅需要 transformers 来加载模型，还需要从 llmcompressor 中导入量化修饰器 GPTQModifier 和一键量化函数 oneshot。

1
2
3
4
5
6
7
8


import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from llmcompressor.modifiers.quantization import GPTQModifier
from llmcompressor import oneshot

# 基础配置
base_model_id = "Qwen/Qwen2.5-1.5B-Instruct"
device = "cuda" if torch.cuda.is_available() else "cpu"

4.2.2 定义量化策略

接下来是量化的核心步骤。需要通过 GPTQModifier 来定义量化的具体策略。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 量化后模型输出目录
gptq_out_dir = "models/qwen2.5-1.5b-instruct-gptq-llmc"

# 定义 GPTQ 量化策略
gptq_recipe = [
 GPTQModifier(
 scheme="W4A16", # 权重 4bit，激活保持 16bit
 targets="Linear", # 只量化线性层
 ignore=["lm_head"], # 保持输出头的高精度，避免性能损失
 ),
]

scheme="W4A16"：W4 代表权重（Weights）被量化为 4-bit 整数，将模型体积压缩为原来的 1/4；A16 代表激活值（Activations）在计算时保持 16-bit 浮点精度（FP16/BF16）。这种组合既降低了显存占用，又利用了 GPU 的 INT4 Tensor Core 进行加速，同时保持了较高的计算精度。
targets="Linear"：指定量化仅应用于线性层（Linear Layers）。Transformer 模型的大部分参数都集中在这些全连接层中。
ignore=["lm_head"]：这是一个必须注意的细节。模型的输出头（LM Head）负责将高维特征映射回词表空间，对数值精度极其敏感。对其进行 4-bit 量化往往会导致输出乱码或逻辑崩坏，所以通常将其排除在量化范围之外。

4.2.3 执行 One-Shot 量化

定义好策略后，就可以开始执行量化了。llmcompressor 提供的 oneshot 函数将加载模型、应用算法并保存结果，全流程一气呵成。

1
2
3
4
5
6
7
8


oneshot(
 model=base_model_id,
 dataset="open_platypus", # 使用公开数据集进行校准
 recipe=gptq_recipe, # 传入定义好的量化策略
 output_dir=gptq_out_dir,
 max_seq_length=2048,
 num_calibration_samples=128, # 128个样本通常足够计算准确的统计信息
)

执行该函数后，终端会打印出详细的量化进度日志。我们可以看到 llmcompressor 正在逐层（model.layers.0, model.layers.1…）对模型的线性模块（q_proj, k_proj…）进行压缩：

1
2
3
4
5


2025-12-19T03:57:34.951606+0800 | compress_modules | INFO - Quantizing model.layers.0.self_attn.q_proj using 128 samples
2025-12-19T03:57:36.204668+0800 | compress | METRIC - time 1.25s
2025-12-19T03:57:36.206047+0800 | compress | METRIC - error 1758.54
...
2025-12-19T03:57:36.264447+0800 | compress_modules | INFO - Quantizing model.layers.0.self_attn.k_proj using 128 samples

在这个过程中，校准（Calibration） 是不可或缺的一环。与微调不同，GPTQ 是一种 Post-Training Quantization (PTQ) 方法，它不需要全量训练，但需要少量的真实数据来“观察”模型的激活值分布。

dataset="open_platypus"：GPTQ 依赖于计算海森矩阵来判断权重的重要性。我们需要输入一些具有代表性的文本数据。当前选用的 open_platypus 是一个高质量的指令微调数据集，涵盖了逻辑推理、代码生成等多种任务，能够很好地代表真实场景的输入分布，防止量化后的模型在特定领域能力退化。
num_calibration_samples=128：通常情况下，128 到 512 个样本就足以计算出准确的统计信息。过多的样本不仅增加耗时，边际收益也递减。

4.2.4 加载与效果验证

量化完成后，生成的模型本质上还是一个 Transformer 模型，但其内部的权重层结构发生了变化。我们可以像加载普通模型一样加载它，并检查其结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 加载 GPTQ 量化后的检查点做推理

gptq_tokenizer = AutoTokenizer.from_pretrained(gptq_out_dir, trust_remote_code=True)
if gptq_tokenizer.pad_token_id is None:
 gptq_tokenizer.pad_token = gptq_tokenizer.eos_token

gptq_model = AutoModelForCausalLM.from_pretrained(
 gptq_out_dir,
 device_map="auto",
 torch_dtype=torch.float16,
 trust_remote_code=True,
)
gptq_model.eval()

# 打印 tokenizer 的特殊 token 信息，确保 pad_token 设置正确
gptq_tokenizer.pad_token, gptq_tokenizer.eos_token, gptq_tokenizer.pad_token_id, gptq_tokenizer.eos_token_id

输出如下：

1

('<|endoftext|>', '<|im_end|>', 151643, 151645)

加载完成后，我们检查一下模型结构。

1
2
3


# 检查第 0 层的 q_proj，确认量化是否生效
layer = gptq_model.model.layers[0].self_attn.q_proj
print(f"GPTQ Layer Type: {type(layer)}")

输出如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


GPTQ q_proj layer type: <class 'compressed_tensors.linear.compressed_linear.CompressedLinear'>
GPTQ quantization_config: CompressedTensorsConfig {
 "config_groups": {
 "group_0": {
 "format": "pack-quantized",
 "input_activations": null,
 "output_activations": null,
 "targets": [
 "Linear"
 ],
 "weights": {
 "actorder": "static",
 "block_structure": null,
 "dynamic": false,
 "group_size": 128,
 "num_bits": 4,
 "observer": "minmax",
 "observer_kwargs": {},
 "scale_dtype": null,
 "strategy": "group",
 "symmetric": true,
 "type": "int",
 "zp_dtype": null
 }
 }
...
 "kv_cache_scheme": null,
 "quantization_status": "compressed"
}

可以看到输出的层类型变成了 CompressedLinear，说明原本庞大的 FP16 线性层已经被成功替换为支持压缩张量计算的专用层。同时，quantization_config 中清晰地记录了量化策略：weights 部分显示 num_bits: 4 和 group_size: 128，确认模型已按照 W4A16 的分组量化策略进行了压缩。为了验证量化后的模型没有“变傻”，我们可以进行一次简单的推理测试。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


gptq_tokenizer = AutoTokenizer.from_pretrained(gptq_out_dir)

@torch.no_grad()
def gptq_chat(question: str) -> str:
 msgs = [
 {"role": "system", "content": "你是一名 AI 助手，回答准确、简洁。"},
 {"role": "user", "content": question},
 ]
 input_ids = gptq_tokenizer.apply_chat_template(
 msgs,
 tokenize=True,
 add_generation_prompt=True,
 return_tensors="pt",
 ).to(gptq_model.device)

 gen_ids = gptq_model.generate(
 input_ids=input_ids,
 max_new_tokens=256,
 do_sample=True,
 temperature=0.7,
 top_p=0.9,
 repetition_penalty=1.1,
 eos_token_id=gptq_tokenizer.eos_token_id,
 pad_token_id=gptq_tokenizer.pad_token_id,
 )
 out_ids = gen_ids[0, input_ids.shape[-1]:]
 return gptq_tokenizer.decode(out_ids, skip_special_tokens=True).strip()

gptq_chat("用两三句话解释一下什么是量子计算？")

输出如下：

1

量子计算是利用量子位（qubits）代替经典比特进行信息处理的一种计算方式。它利用量子叠加、纠缠等特性来实现超越传统计算机的并行处理能力，可以高效地解决某些特定问题。通过使用量子比特...

可以看到模型依然能够生成逻辑清晰、内容准确的回答，证明 4-bit 量化在大幅压缩模型体积的同时，依然很好地保留了模型的核心能力。

4.3 AWQ 量化实战

4.3.1 定义 AWQ 策略

AWQ 的配置流程与 GPTQ 非常相似，主要区别在于使用 AWQModifier。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from llmcompressor.modifiers.awq import AWQModifier

awq_out_dir = "models/qwen2.5-1.5b-instruct-awq-llmc"

awq_recipe = [
 AWQModifier(
 scheme="W4A16",
 targets="Linear",
 ignore=["lm_head"],
 ),
]

虽然参数看起来一样，但就像前文所介绍的那样，它们背后的算法逻辑是截然不同的。AWQ 不像 GPTQ 那样依赖海森矩阵的逆，而是依据激活值的幅度来搜索最优的缩放因子（Scaling Factor），将那些对应较大激活值（即更重要）的权重通道进行“放大”保护。这种机制使得 AWQ 在某些特定场景（如代码生成或逻辑推理）下能保留更多的细节能力。

4.3.2 执行量化与对比

1
2
3
4
5
6
7
8


oneshot(
 model=base_model_id,
 dataset="open_platypus",
 recipe=awq_recipe,
 output_dir=awq_out_dir,
 max_seq_length=2048,
 num_calibration_samples=128,
)

整个过程同样依赖校准数据集来统计激活值的幅度。执行后，会看到类似如下的日志输出，特别是在每一层（model.layers.*）的注意力机制中，系统会进行“平滑”操作（SmoothQuant）并应用量化：

1
2
3
4


2025-12-19T04:08:32.146092+0800 | _set_resolved_mappings | WARNING - skipping AWQ for model.layers.0.self_attn.v_proj ...
...
2025-12-19T04:08:32.160737+0800 | compress_modules | INFO - Running SmoothQuant for model.layers.0.self_attn.q_proj
2025-12-19T04:08:32.161737 | compress_modules | INFO - Running SmoothQuant for model.layers.0.self_attn.k_proj

在 AWQ 量化时，日志中出现的 SmoothQuant 或 Smoothing 阶段，是 llmcompressor 在实现 AWQ 时对平滑/缩放步骤采用的内部命名，算法本身依然是 AWQ（与 SmoothQuant 论文中的方法不同）。这个过程本质上是在执行一次网格搜索（Grid Search），所以我们会发现 AWQ 的量化过程比 GPTQ 要慢很多。因为 GPTQ 的核心计算（海森矩阵求逆）是确定性的数学解析过程，计算量相对固定；而 AWQ 需要针对每一层，在校准数据上反复尝试不同的缩放因子 $s$，来找到让量化误差最小的最优解。这个迭代搜索的过程自然比单次矩阵运算更耗时。不过，这种额外的时间投入换来的是对离群点的鲁棒性。大模型中常存在极少数数值巨大的激活值（尖峰），如果不加处理直接量化，会带来巨大的精度损失。AWQ 的 Smoothing 过程相当于将这些“尖峰”的压力平滑地分摊到了权重上，从而在不增加推理计算量的前提下，显著降低了量化噪声。而且，AWQ 的这种设计使其生成的模型在 vLLM 等推理引擎中往往能获得更好的原生加速支持。量化完成后，可以使用与 GPTQ 相同的方式加载和测试模型。

参考文献

基于 LLaMA-Factory 的RLHF（DPO）实战

Fri, 27 Mar 2026 13:40:25 -0800

基于 LLaMA-Factory 的RLHF（DPO）实战

我们在上一节详细介绍了 RLHF 的原理以及目前主流的 DPO（Direct Preference Optimization） 算法。相比于传统的 PPO，DPO 省去了训练独立的奖励模型（Reward Model）和复杂的强化学习采样过程，直接在偏好数据上优化策略，更加稳定且高效。

本节我们将使用开源社区流行的微调框架 LLaMA-Factory，配合阿里发布的轻量级指令模型 Qwen2.5-0.5B-Instruct，在单张消费级显卡（甚至 CPU）上跑通 DPO 对齐流程。

一、LLaMA-Factory 简介

LLaMA-Factory 是一个简洁高效的大型语言模型（Large Language Model）训练与微调平台，旨在让开发者能够“零代码”地完成大模型的定制化训练。它具有以下特点：

广泛的模型支持：支持业界主流的开源模型，如 LLaMA、Qwen（通义千问）、Baichuan（百川）、ChatGLM、Mistral、Yi 等。
全流程覆盖：涵盖了从 预训练（Pre-Training）、指令监督微调（SFT） 到 RLHF（包含奖励模型建模、PPO、DPO、KTO、ORPO 等）的完整训练阶段。
高效的微调技术：内置了 LoRA、QLoRA、DoRA、GaLore 等多种参数高效微调（PEFT）方法，大幅降低了显存需求。
易用的交互界面：提供名为 LLaMA-Board 的 Web UI 界面，通过可视化操作即可配置训练参数、监控训练进度以及进行模型对话测试。
硬件友好：支持 DeepSpeed、FlashAttention 等加速技术，并支持 4-bit/8-bit 量化训练，使得普通消费级显卡也能运行大模型训练。

二、环境搭建

2.1 拉取代码并安装依赖

克隆 LLaMA-Factory 仓库

1
2


git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

激活 Conda 环境
1

conda activate peft
安装依赖
1

pip install -e .[metrics]

验证安装

1

llamafactory-cli version

如果安装成功后，能够看到类似下面的输出：

1
2
3
4
5


----------------------------------------------------------
| Welcome to LLaMA Factory, version 0.9.4.dev0 |
| |
| Project page: https://github.com/hiyouga/LLaMA-Factory |
----------------------------------------------------------

2.2 启动 Web UI 界面

LLaMA-Factory 提供了一个简单易用的 Web UI 界面，可以用于训练、评估和聊天。

1

llamafactory-cli webui

启动后，将看到如下输出：

1
2
3


Visit http://ip:port for Web UI, e.g., http://127.0.0.1:7860
* Running on local URL: http://0.0.0.0:7860
* To create a public link, set `share=True` in `launch()`.

访问 http://localhost:7860，就能看到如图 12-9 所示界面：

图 12-9 LLaMA-Factory Web UI 界面

三、DPO 训练准备

RLHF（DPO）通常是在模型已经具备一定指令遵循能力的基础上进行的。由于我们直接使用已经经过指令微调的 Qwen2.5-0.5B-Instruct 版本，因此可以直接进入 DPO 阶段。

3.1 配置模型

进入 WebUI 后，可以根据自己熟悉的语言切换界面语言（目前支持 en、ru、zh、ko、ja 等）。然后在下拉框中选择 Qwen2.5-0.5B-Instruct（聊天 / 指令版本）并设置下载源。默认为 Hugging Face，如果遇到网络问题，可以切换为 ModelScope 或 OpenMind 进行下载。

图 12-10 模型选择与配置

3.2 配置微调参数

微调方法：保持默认的 lora。
量化配置：对于显存较小的设备，可以选择将 Quantization bit 设置为 8 或 4，启用量化训练（QLoRA）。如果显存充足或希望获得更好的效果，可以保持默认（不量化）。
其他参数：
- Quantization method: 量化方法，默认为 bnb（bitsandbytes）。
- Chat template: 对话模板。
  - 对于 Base 模型，可选择 default, alpaca, vicuna 等。
  - 对于 Instruct/Chat 模型，务必选择对应的模板（例如 Qwen 系列选择 qwen）。
  - 训练和推理时必须使用相同的模板。
- RoPE scaling: 旋转位置编码缩放，用于扩展上下文长度。
- Booster: 加速库，默认 auto 即可，它会自动选择最适合的加速后端（如 FlashAttention）。

如图 12-11 ，我们设置了 LoRA 微调，并手动指定了对话模板为 qwen，其余选项保持默认。

图 12-11 微调方法与量化配置

3.3 配置数据集

如图 12-12 需要先在左上角的 Stage 下拉菜单中选择 DPO。接着，在“数据集”一栏中，选择需要的训练数据。我们将使用 LLaMA-Factory 自带的 DPO 演示数据集 dpo_zh_demo。这个数据集包含了偏好对比（chosen vs rejected）的数据对。选中数据集后，可以点击右上角的 Preview dataset 按钮预览数据格式，确认数据无误。

图 12-12 数据集选择与预览

四、启动 DPO 训练

4.1 设置训练参数

笔者根据自己的机器情况设置了如图 12-13 所示的配置。

图 12-13 训练参数配置

关键参数说明：
- Learning rate: 1e-4 （学习率）
- Epochs: 3.0 （训练轮数）
- Compute type: fp16 （兼容性好，若显卡适配可选 bf16）
- Cutoff length: 2048
- Batch size: 1 （取决于显存）
- Gradient accumulation: 16 （建议 Batch size × Gradient accumulation ≈ 16 或 32）
- LoRA rank: 8 （LoRA 的秩，决定微调参数量，8 是默认配置）
- LoRA alpha: 16 （缩放系数，默认设置为 Rank 的 2 倍）

4.2 启动训练

如图 12-14 设置好输出目录后，可以点击 Preview command 预览训练命令，确认无误后直接点击 Start 开始训练。

图 12-14 预览命令并启动训练

训练完成后，适配器（Adapter）权重将保存在 saves/Qwen2.5-0.5B-Instruct/lora/Qwen2.5-0.5B-dpo-demo 目录下。我们也可以在 Train 面板中看到如图 12-15 的训练过程 Loss 曲线，观察模型收敛情况。

图 12-15 训练 Loss 曲线

五、效果测试与对比

在训练完成后，本来还应进行评估的步骤（这步也可以直接通过可视化界面的 Evaluate & Predict 面板进行），但是由于没有准备测试数据集，所以这一步就省略了。我们将直接使用 LLaMA-Board 的 Chat 功能来测试模型的对话效果。

5.1 加载模型进行对话

如图 12-16 所示，切换到 Chat 栏。在训练开始前，我们可以先不选择任何 Adapter，直接点击 Load model 加载原始的 Qwen2.5-0.5B-Instruct 模型，测试一下未训练时的模型表现。

图 12-16 加载模型进行对话测试

加载成功后，在页面下方的对话框中输入测试问题，查看原始模型的回答情况（如图 12-14）。

测试配置：

System prompt: 您是一名AI助手。用户会给您一个任务。您的目标是尽量忠实地完成任务。在执行任务时，要逐步思考并合理地解释您的步骤。

Input:

1

体重增加是一个复杂的问题。但毫无疑问，西方国家当前的食物环境——大量含有高度加工的咸、甜和油脂食品——起着重要作用。我们饮食中摄入的大部分盐都是在制造过程中添加的。这与大多数食物中天然存在的少量盐或在餐桌上或在家里烹饪时添加的盐形成对比。盐可以增加食物的可口性，帮助保鲜；这就是为什么它通常被添加到加工食品中。盐和脂肪的结合被认为是促进食物被 passively 过量消费的强大组合。想想看，咸薯片有多令人回味。对咸和油脂食物更喜欢与整体摄入更多千焦耳、不受控制的饮食和儿童超重有关。食物过量摄入与其盐度程度之间的联系被认为比对甜和油脂食物的喜好更强。从进一步揭示盐可能如何影响对油脂食物的过量摄入，Deakin 大学的感官研究人员招募了 48 名健康成年人参加品尝小组。在四个午餐时间段（在那天早上进行了标准早餐后），每个人都吃了一顿经过脂肪和盐含量调整的通心粉奶酪餐。四种餐食组合分别是低脂/低盐、低脂/高盐、高脂/低盐和高脂/高盐。鼓励参与者吃到饱为止。还记录了进食速度、餐食的可口性以及主观评价的饥饿感和饱腹感。盐促进过量进食当食用含盐量高的餐食时，摄入的千焦耳增加了 11%。而这与脂肪含量高低无关。餐食的脂肪含量并没有导致人们按重量摄入更多食物，但由于其更高的能量密度，这意味着摄入了更多千焦耳。问题：那些习惯于喜欢高热量密度饮食的人可能经常食用高盐食品吗？=== 上述问题的答案是 可选项： (1). 一周以上。 (2). 大多数时候通心粉奶酪被提供时。 (3). 没有足够的信息 (4). 通常在午餐时间。 答案：

图 12-17 原始模型对话测试

在图 12-17 中，原始模型给出的答案简短且武断。虽然我们在 System Prompt 中要求它“逐步思考并合理地解释步骤”，但它忽略了这一指令，直接给出了一个基于表面关联（文中提到午餐）的猜测性结论。这种倾向于“快速给出答案”而非“深思熟虑”的风格，在未经过偏好对齐的模型中很常见。

5.2 验证 DPO 效果

当 DPO 训练完成后，如图 12-18 需要选择 Checkpoint path 为我们刚刚训练好的 Adapter（位于 saves/Qwen2.5-0.5B-Instruct/lora/Qwen2.5-0.5B-dpo-demo），然后再次点击 Load model 加载混合了 DPO 权重的模型。

图 12-18 加载 DPO 训练后的 Adapter

对比图 12-17 和图 12-19，我们可以看到 DPO 训练带来的行为风格变化：

原始模型：回答简短、直接，但缺乏解释，倾向于“猜测”答案，表现出一种“急于完成任务”但缺乏严谨性的风格。
DPO 模型：回答更加严谨。它不仅给出了选项，还忠实地执行了 System Prompt 中“解释步骤”的要求，明确指出了原文信息的局限性（“缺乏关于这些人群饮食习惯的直接证据”）。相比于原始模型的一句话猜测，DPO 模型的回答展示了推理过程，这更符合我们对角色的期待。

图 12-19 DPO 模型对话测试

这就是 RLHF 的价值——不仅仅是让模型“做对题”，更是让模型学会人类偏好的交互风格。通过 dpo_zh_demo 数据集的训练，模型初步对齐了数据集中这种“诚实且严谨”的偏好风格。

本章小结

本章我们探讨了让大语言模型“更懂人类”技术——RLHF。在理论层面，我们不仅剖析了模型对齐的必要性，对比了 SFT 与 RLHF 的核心差异，还详细解析了从经典的 PPO 到高效的 DPO，再到驱动 DeepSeek-R1 等推理模型涌现的 GRPO 算法。特别是 GRPO 与 RLVR 的结合，展示了通过强化学习激发模型长链推理能力的巨大潜力。

在实战环节，借助 LLaMA-Factory 这一高效框架，成功在消费级硬件上完成了 Qwen2.5 模型的 DPO 训练。通过对比训练前后的对话效果，我们直观地看到了模型在行为风格上的转变，即从简单武断的回答，进化为能够遵循复杂指令、展示推理过程的严谨回复。这不仅验证了 DPO 算法的有效性，也展示了如何通过偏好数据低成本地定制模型的“性格”。此外，虽然可视化界面便于上手，但在实际使用中，开发者往往更倾向于使用命令行方式，以获取对训练过程更细致的控制。

基于人类反馈的强化学习（RLHF）技术详解

Fri, 27 Mar 2026 12:40:25 -0800

基于人类反馈的强化学习（RLHF）技术详解

通过前面的学习，我们已经知道如何通过 PEFT，用较低的成本让大语言模型适应下游任务。无论是 PEFT 还是全量微调，主要方法大多是有监督微调（Supervised Fine-tuning, SFT），即用成对的“(指令, 回答)”数据来训练模型。但是，SFT 存在一个重要的局限。它教会模型模仿高质量的范例，但无法让模型理解人类的偏好。一个 SFT 模型或许能很好地回答“中国的首都是哪里？”，但当面对更开放、更复杂的指令，如“为我的项目写一个既专业又有创意的介绍”时，SFT 的局限性就暴露无遗：

缺乏泛化能力：模型只能很好地响应数据集中出现过的指令模式，无法覆盖用户千奇百怪的真实意图。
“对齐”不足：模型的回答可能在事实上正确，但在风格、语气、安全性或有用性上，并不符合人类的期望。它只知道“正确答案”，却不知道“更好的答案”。

一、模型对齐的必要性

为了跨越从“遵循指令”到“理解偏好”的鸿沟，我们需要一种新的训练范式。基于人类反馈的强化学习（Reinforcement Learning from Human Feedback, RLHF） 正是解决这一问题的关键技术。它的核心目标就是让模型超越简单的模仿学习，真正理解并内化人类复杂的价值观，使其输出更符合我们的期望。

表 12-1 总结了 SFT 与 RLHF 在核心理念与实现方式上的关键差异：

对比维度	监督微调 (SFT)	人类反馈强化学习 (RLHF)
核心目标	模仿正确答案（指令遵循）	对齐人类偏好（有用/无害/诚实）
数据需求	高质量的 `(指令, 回答)` 对	提示词 `(Prompt)` + 偏好排序/评分
学习方式	填鸭式教学（拟合分布）	探索式学习（试错与反馈）
优化信号	Token 级预测概率（交叉熵）	整句生成质量评分（标量奖励）
泛化能力	局限于训练数据分布	可泛化到未见过的复杂指令

表 12-1 SFT 与 RLHF 核心差异对比

如图 12-1 所示，RLHF 的有效性在实践中得到了强有力的验证。在 InstructGPT 的研究中 ¹，经过 RLHF 对齐后，仅有 13 亿参数的模型，在人类评估中的表现甚至超过了 1750 亿参数的原始 GPT-3 模型。这说明，让模型“懂”人类偏好，比单纯增加参数规模更能提升其实用性。

图 12-1 InstructGPT 与 GPT-3 人类偏好对比

二、通往对齐模型的三大阶段

在实践中，对齐训练通常划分为三个阶段，分别面向通用语言能力、指令遵循与偏好对齐：

（1）基础模型预训练

在大规模（万亿级 Token）无标注文本数据（网页、书籍、代码等）上进行自回归预训练。通过预测下一个词的任务，模型能够习得广泛的语料知识并具备基础的生成能力，从而得到一个基础语言模型。虽然此时模型尚未进行指令或偏好对齐，但这一阶段的训练门槛极高，不仅算力成本巨大，还需在超大规模数据与模型上解决复杂的收敛稳定性问题。

（2）有监督指令微调

使用少量（千到几万条）高质量“指令-回答”对，对基础模型进行有监督微调，使其学会理解并执行人类指令。这一阶段通常使用 (prompt, response) 格式的数据，并可结合 QLoRA 等参数高效微调技术进行训练。它的目标是在指令上下文中实现条件生成，以此显著提升模型的指令遵循与任务完成能力，最终获得一个在指定任务与约束条件下更为可控的“指令模型”（Instruction-tuned LM）。高质量的 SFT 数据集是模型能力养成的关键。根据目标的不同，数据集可以分为两类：

任务型指令数据集：如 WizardLM Evol‑Instruct 70k (AI 生成) 和 Dolly-15k (专家编写)，它们主要由单轮的“指令-回答”构成，核心目标是教会模型如何“做事”，准确地遵循指令完成特定任务。
对话型数据集：这类数据集的代表作就是 OpenAssistant (OASST)。它专注于教会模型如何“聊天”，其独特性和重要性体现在：
- 来源真实且多样：数据由超过 1.3 万名真实志愿者众包贡献，覆盖了广泛的话题和真实的语言风格，而非 AI 生成或专家编写的固定模式。
- 专注于多轮对话：OASST 的核心是多轮对话树，完整记录上下文、分支和用户的追问。这对于训练模型理解上下文、进行连贯的长对话至关重要。
- 丰富的反馈信号：数据不仅包含对话文本，还有人工标注的质量评分和多种标签（可作为偏好学习/奖励建模的有益信号）。这使其不仅是优秀的 SFT 数据，也是训练奖励模型（Reward Model）、进行 RLHF 的宝贵材料。

简单来说就是任务型数据集教会模型“智商”，而以 OASST 为代表的对话型数据集则赋予模型“情商”，使模型更接近一个真正能与人交流的智能助手。

（3）基于人类反馈的强化学习

这一阶段是模型从“及格”走向“卓越”的关键跨越。虽然经过 SFT 微调的模型已经能流畅地遵循指令，但它本质上仍是在进行“模仿学习”，受限于标注数据的质量，会存在“只知其一不知其二”的问题，且容易产生幻觉或不安全的输出。RLHF 引入了人类价值观作为指导信号，通过构建奖励模型来模拟人类的判别标准，并利用强化学习算法让模型在生成过程中不断“试错”并学习如何获得更高的奖励。这一过程不再要求模型死记硬背固定的标准答案，而是鼓励它探索出更符合有用性（Helpful）、诚实性（Honest）和无害性（Harmless）（简称 3H 原则）的回复路径。

三、RLHF 的形式化定义

在深入具体步骤之前，我们需要理解为什么文本生成任务可以被建模为强化学习问题。在 RLHF 框架中，将 Token 生成过程建模为 “片段的（Episodic）马尔可夫决策过程（MDP）” 是连接 NLP 与 RL 的核心桥梁。这个“片段”特指“从接收用户提示到生成完整输出”的单次生成任务。

状态 (State, $s_t$)：当前已生成的上下文，包括用户提示 $x$ 和已生成的 Token 序列 $y_{<t}$。即 $s_t = (x, y_1, …, y_{t-1})$。
动作 (Action, $a_t$)：模型在当前时间步生成的下一个 Token $y_t$。
策略 (Policy, $\pi_\theta$)：即我们的大语言模型。$\pi(a_t|s_t)$ 对应模型在当前上下文下预测下一个 Token 的概率分布。
奖励 (Reward, $R$)：通常在整个回答生成完毕（Episode 结束）后，由奖励模型给予一个标量反馈 $R(x, y)$。中间步骤的奖励通常为 0。

在这个定义下，RLHF 的目标就是寻找一个最优策略 $\pi_\theta$，使得生成的完整序列期望奖励最大化：

$$ \max_\pi \mathbb{E}_{x \sim \mathcal{D}, y \sim \pi(\cdot|x)} [R(x, y)] $$

理解了这一形式化定义，我们就能明白为什么 PPO 等算法可以通过试错（Sampling）和反馈（Reward）来调整模型参数，从而让模型生成的“轨迹”（文本）更符合人类偏好。

四、RLHF 的核心步骤

如图 12-2 所示，RLHF 的流程主要包含三个核心步骤。首先通过有监督微调得到初始策略模型；然后，收集人类偏好数据训练一个奖励模型；最后，使用奖励模型作为信号，通过强化学习算法（如 PPO）进一步优化策略模型。

图 12-2 RLHF 经典三步法示意图

4.1 训练奖励模型

在 RLHF 中，我们需要一个“裁判”，用来评判模型的哪个回答更好；这个“裁判”就是奖励模型（RM）。RM 的目标是学习一个函数 $r(x, y)$，输入提示 $x$ 和回答 $y$，输出一个标量分数，代表人类对该回答的偏好程度。在 InstructGPT 的实践中，RM 数据集约含 33k 个训练提示（由此衍生出数量级更大的成对比较样本）。接下来，分别介绍一下如何收集人类偏好数据，以及训练奖励模型。

（1）收集人类偏好数据

第一步需要准备一个指令（prompt），可从真实用户请求中选取，也可由标注员设计；让 SFT 模型针对该指令生成多个（InstructGPT 中为 4-9 个）不同的回答；由人工标注员对这些回答进行排序（Ranking），从最好到最差。相比于给每个回答打一个绝对分数，排序是一种对人类更友好、也更一致的标注方式。这些排序数据构成了偏好数据集 $\mathcal{D} = {(x, y_w, y_l)}_{i=1}^N$，其中 $y_w$ 是比 $y_l$ 更受偏好的回答 (winner)，$y_l$ 是较差的回答 (loser)。

（2）训练奖励模型

训练奖励模型的常见做法包括以下几点。

将一个包含 K 个回答的排序数据，转换成 $\binom{K}{2}$ 个成对的比较数据。例如，(回答A > 回答B)、(回答A > 回答C)、(回答B > 回答C)…
奖励模型（RM）通常和我们正在优化的语言模型结构类似（但可以小得多），它的任务不是生成文本，而是输入 (prompt, response)，输出一个标量分数 reward。
训练 RM 的目标是，让它给人类偏好的回答打出更高的分数。这通常基于 Bradley-Terry 模型，该模型假设人类对两个回答的偏好概率可以用它們的潜在奖励分数通过 Sigmoid 函数来建模：
$$ P(y_w \succ y_l | x) = \sigma(r(x, y_w) - r(x, y_l)) $$
其损失函数（负对数似然）如下：
$$ \text{loss}(\theta) = - \mathbb{E}_{(x, y_w, y_l) \sim \mathcal{D}} \left[ \log(\sigma(r_\theta(x, y_w) - r_\theta(x, y_l))) \right] $$
其中 $r_\theta$ 是奖励模型，$y_w$ 是比 $y_l$ 更受偏好的回答，$\sigma$ 是 Sigmoid 函数。这个损失函数旨在最大化偏好回答与非偏好回答之间的分数差距。

经过训练，RM 能够逼近人类偏好函数，作为自动化的偏好评估器，为后续策略优化提供稳定的标量奖励信号。

4.2 使用策略优化算法微调模型

有了“裁判”（或者隐式的偏好信号），就可以开始真正的“强化学习”训练了。这个阶段的目标是更新语言模型的策略，让它生成的回答能够获得更高的奖励。传统的强化学习算法存在高方差、训练不稳定的问题。因此，学术界和工业界发展出了一系列更先进的策略优化算法，其中 PPO、DPO 和 GRPO 是目前的主流。

如图 12-3 所示，不同的对齐范式在流程设计上有所侧重。经典的 RLHF 范式依赖奖励模型和 PPO 进行在线优化；DPO 直接基于偏好数据进行离线优化；而 RLVR 则利用确定性的验证器（如代码执行器）结合 GRPO 进行训练。

图 12-3 不同强化学习对齐范式的对比（RLHF / DPO / RLVR）

4.2.1 PPO 与“对齐税”

近端策略优化（Proximal Policy Optimization, PPO） 是 RLHF 中最经典的算法 ²。PPO 的主要思路是，在尝试最大化奖励的同时，通过一个约束项来限制新旧策略的差异范围，继而避免单步更新过大导致训练崩溃。它通过优化一个“替代目标函数”（Surrogate Objective）来实现这一点。PPO 最常用的替代目标是 Clipped Surrogate Objective:

$$ L^{CLIP}(\theta) = \hat{\mathbb{E}}_t \left[ \min\left(r_t(\theta)\hat{A}_t, \text{clip}(r_t(\theta), 1-\epsilon, 1+\epsilon)\hat{A}_t\right) \right] $$

其中，$r_t(\theta) = \frac{\pi_\theta(a_t|s_t)}{\pi_{\theta_{\text{old}}}(a_t|s_t)}$ 是新旧策略的概率比，$\hat{A}_t$ 是优势函数估计，$\epsilon$ 是一个限制更新范围的超参数（通常为 0.2）。这个裁剪操作有效地构建了一个悲观的下界，防止策略更新过于激进。

如图 12-4 是 PPO 裁剪代理目标函数 $L^{CLIP}$ 的单步示意图。当优势 $\hat{A}_t>0$ 时（左），目标函数随概率比 $r_t(\theta)$ 的增加而增加，但增长被限制在 $1+\epsilon$ 处；当 $\hat{A}_t<0$ 时（右），目标函数随 $r_t(\theta)$ 的增加而减小，但减小幅度被限制在 $1-\epsilon$ 处，从而约束了策略更新的步长。

图 12-4 PPO 的裁剪代理目标函数

但研究者发现，单纯用 PPO 优化奖励模型，可能会导致模型在某些传统 NLP 任务（如 SQuAD）上的性能下降，这种现象被称为 “对齐税”（Alignment Tax）。为了解决这个问题，InstructGPT 提出了一种名为 PPO-ptx 的变体，它在优化奖励的同时，混合了一部分预训练数据的梯度，其优化目标为：

$$ \text{objective}(\phi) = \mathbb{E}_{(x, y) \sim D_{\pi_\phi^{RL}}} [r_\theta(x, y) - \beta \log(\pi_\phi^{RL}(y|x) / \pi^{SFT}(y|x))] + \gamma \mathbb{E}_{x \sim D_{pretrain}}[\sum_t \log(\pi_\phi^{RL}(x_t|x_{其中：

PPO 主目标项（奖励 + KL 约束）：在当前策略生成的数据分布 $D_{\pi_\phi^{RL}}$ 上，最大化奖励模型分数 $r_\theta(x,y)$，并用每 token KL 约束惩罚新策略 $\pi_\phi^{RL}$ 偏离参考模型 $\pi^{SFT}$，以抑制灾难性漂移。
预训练保留项（ptx）：在预训练语料 $D_{pretrain}$ 上进行最大似然学习 $\sum_t \log \pi_\phi^{RL}(x_t|x_{<t})$，用于保留通用语言能力与知识面，缓解“对齐税”。
符号说明：$\beta$ 控制 KL 约束强度；$\gamma$ 控制 ptx 项权重；$D_{\pi_\phi^{RL}}$ 为在线由当前策略采样的数据分布；$D_{pretrain}$ 为静态预训练语料；KL 为每 token KL 散度。

通过图 12-5 可以看到 PPO-ptx 缓解了 RLHF 在部分公开 NLP 数据集上的性能下降（对齐税）问题。图中 PPO-ptx 模型（红色）代表混合了预训练梯度，而 PPO 模型（橙色）则没有。在 SQuADv2、DROP 等多个任务上，PPO-ptx 的性能显著优于单纯的 PPO。

图 12-5 PPO-ptx 缓解对齐税

4.2.2 直接偏好优化

尽管 PPO 效果很好，但它流程复杂（需要训练奖励模型、价值模型，并进行在线采样），训练成本高且不稳定。直接偏好优化（Direct Preference Optimization, DPO） 是一项创新的技术 ³，它巧妙地绕过了显式的奖励模型训练和复杂的强化学习过程。

主要思路：DPO 证明了，我们可以从人类偏好数据 $\mathcal{D} = {(x, y_w, y_l)}$ 中，直接推导出最优策略，而无需先拟合一个奖励模型。它将问题转化为一个简单的分类任务，不需要显式训练奖励模型，也无需在线采样，所以更稳定、高效。
优化目标： DPO 的损失函数直接最大化模型对“更好”回答的偏好概率，同时用 KL 散度进行约束：
$$ \mathcal{L}_{\text{DPO}}(\pi_\theta; \pi_{\text{ref}}) = - \mathbb{E}_{(x, y_w, y_l) \sim \mathcal{D}} \left[ \log \sigma \left( \beta \log \frac{\pi_\theta(y_w|x)}{\pi_{\text{ref}}(y_w|x)} - \beta \log \frac{\pi_\theta(y_l|x)}{\pi_{\text{ref}}(y_l|x)} \right) \right] $$
其中 $\pi_{\text{ref}}$ 是参考模型（通常是 SFT 模型），$\sigma$ 是 Sigmoid 函数。这个损失函数简洁地鼓励模型提高 $y_w$ 的概率，降低 $y_l$ 的概率。
训练动力学：DPO 的梯度更新有一个直观的解释。它会给那些被隐式奖励模型错误排序的样本（即认为 $y_l$ 比 $y_w$ 更好）更大的权重，从而集中火力修正模型的“判断失误”。这个隐式奖励由下式定义：
$$ \hat r_\theta(x,y)=\beta \log \frac{\pi_\theta(y|x)}{\pi_{\mathrm{ref}}(y|x)} $$
优势：由于其简单、稳定且高效，DPO 及其变种正在迅速成为 RLHF 的新范式。

如图 12-6，该图展示了在 IMDb 情感生成任务中，不同偏好学习算法的 Reward-KL 效率前沿。DPO（黄色散点）在所有 KL 散度值上都获得了最高的期望奖励，表明 DPO 能够更有效地在最大化奖励和与参考模型的 KL 散度约束之间进行权衡，其优化效果优于 PPO 等基线方法。

图 12-6 DPO 与 PPO 的 Reward-KL 效率前沿对比

4.2.3 群体相对策略优化

群体相对策略优化（Group Relative Policy Optimization, GRPO） 是 DeepSeek 在 2024 年发布的 DeepSeekMath 中提出的一种高效算法 ⁴。此时 DPO (2023) 虽已流行，但主要用于偏好对齐；而在数学、代码等**带可验证奖励（Reinforcement Learning with Verifiable Rewards, RLVR）**的场景中，模型更需要通过在线探索（Online Exploration）来寻找正确路径，而非仅仅拟合静态数据。

RLVR 的核心逻辑是用确定性的验证器（Validator）取代主观的奖励模型（如通过代码测试用例 $v(x, y) \in {0, 1}$ 直接判断正误）。这种强反馈消除了 Reward Hacking 中“欺骗人类”的可能性，并驱动模型通过自我博弈（Self-Play）涌现出思维链（CoT）等高级推理能力。然而，传统的 PPO 算法需要维护一个与策略模型规模相当的价值网络（Critic），在训练千亿参数模型时显存开销巨大。GRPO 的关键创新是“去 Critic 化”，它通过组内统计量来替代 Critic 的基线估计功能：

组采样 (Group Sampling)：对于同一个提示词 $x$，利用旧策略 $\pi_{\theta_{old}}$ 采样生成一组输出 ${y_1, y_2, …, y_G}$。
组内优势估计 (Group Relative Advantage)：利用奖励模型或验证器对这组输出打分。关键在于，GRPO 不使用额外的 Critic 来预测基线，而是直接使用组内奖励的均值作为动态基线。这种方法不仅显著降低了显存占用（无需维护与策略模型同等规模的 Critic），还有效利用了组内对比来降低方差。对于每个输出，其优势 $A_i$ 通常通过标准化计算得出：
$$ A_i = \frac{r_i - \text{mean}(\{r_1, ..., r_G\})}{\text{std}(\{r_1, ..., r_G\})} $$
KL 散度正则化：与 PPO 通常在奖励函数中直接扣除 KL 惩罚不同，GRPO 将 KL 散度 $D_{KL}(\pi_\theta || \pi_{ref})$ 直接加入损失函数中作为正则项。这样做的好处是保持了优势估计的纯粹性，使其仅反映组内输出的相对好坏，而不会被 KL 惩罚项混淆。

通过这种设计，GRPO 既保留了 PPO 在线探索的能力（适合推理任务），又享受了类似 DPO 的低资源消耗，成为 DeepSeek-R1 等推理模型背后的关键技术。如图 12-7 所示的时间线展现了使用强化学习训练的代表性推理模型的发展。这一过程囊括了各类开源与闭源的语言模型、多模态模型以及智能体模型。其中，OpenAI o1 与 DeepSeek-R1 作为推理模型领域的关键里程碑，有力证明了可验证奖励训练的重要性。通过这种训练，模型得以掌握包括规划、反思及自我纠错在内的长链推理能力。

图 12-7 基于强化学习训练的推理模型

4.2.4 算法选择指南

PPO（稳定性与通用性）: PPO 适用于各类需与环境交互的通用任务（如游戏 AI、机器人控制）。在 LLM 领域，当系统已经有了成熟的 RL 框架，或者需要对模型行为进行极细粒度的控制（如复杂的指令遵循、多轮对话策略）时，PPO 仍然是首选。它通过显式的 Critic 模型进行价值估计，能够处理更复杂的奖励信号，但计算成本较高。
DPO（效率与数据利用）: DPO 是样本数据稀缺或追求高训练效率场景下的利器。由于它绕过了显式的奖励建模和在线采样，直接利用离线偏好数据进行优化，因此非常适合快速迭代或计算资源有限的项目（如对话风格微调、摘要生成）。它能高效利用有限的标注数据，但在缺乏大规模探索的情况下，上限可能不如 RL 方法。
GRPO（推理与长序列奖励）: 针对奖励常在序列末尾给出（如数学最终答案、代码运行结果）的场景，GRPO 是最佳选择。它解决了 PPO 难以给每个 Token 精确分配价值的难题，通过组采样（Group Sampling）和组内优势估计来优化策略。GRPO 去除了 Critic 模型，显著降低了显存占用，非常适合需要在线探索以涌现思维链（CoT）能力的复杂推理任务（如 DeepSeek-R1）。

4.3 RLHF 的实际效果

以 InstructGPT 为例，RLHF 带来了显著且复杂的影响。如图 12-8 展示了模型在 TruthfulQA 基准上的真实性表现。其中，灰色柱表示“真实性（truthfulness）”，彩色柱表示“真实性与信息量（truthfulness and informativeness）”。整体来看，经过 RLHF 的 InstructGPT 模型（PPO-ptx/PPO）在 TruthfulQA 上相较 GPT-3 基线更真实且更具信息量。但需注意，原论文报告 1.3B 的 PPO-ptx 模型在 TruthfulQA 上略低于同尺寸 GPT-3。

图 12-8 InstructGPT 在 TruthfulQA 上的真实性表现

更具体地说，这些效果体现在以下几个方面：

提升真实性：在 TruthfulQA 等基准上，模型生成真实、信息丰富答案的频率提升了约一倍，且在封闭问答中“捏造事实”的比例减半。
降低有害性：当被明确指示要“尊重地”回答时，模型产生有毒输出的比例比原始 GPT-3 减少了约 25%。
偏见问题依然存在：在衡量社会偏见的数据集（如 Winogender）上，RLHF 并没有带来明显改善。
仍会犯错：模型有时仍会盲目遵循错误的指令前提（例如，回答“为什么要饭后吃袜子”），或者在简单问题上过度“耍滑头”、含糊其辞。

4.4 RLHF 的实践挑战与前沿方向

尽管 RLHF 效果显著，但它也面临着巨大的挑战，许多问题仍在探索之中。一篇近期的综述论文 ⁵ 系统性地梳理了这些挑战。首先是奖励过拟合 (Reward Hacking)，这是核心挑战之一，模型可能会学会利用奖励模型的漏洞，通过生成过分追求详细而导致啰嗦、避而不答、或“听起来不错”的无意义内容来获取高分，这要求在数据收集和模型训练中进行仔细的权衡和约束；其次是评估困境，如何准确评估一个模型是否真的与人类价值观“对-齐”是一个开放性问题，现有的基准测试可能无法完全覆盖人类偏好的广度和深度，而 LLM-as-a-Judge 的方法也存在自身的偏见和提示敏感性问题；再者是多模态对齐，当前 RLHF 主要集中在文本，如何将其有效扩展到视频、音频等多模态场景，解决视觉幻觉（Visual Hallucination）、时序理解等新问题，是一个重要方向；同时，文化与价值观对齐也面临困难，主流的偏好数据大多来自单一文化背景，这使得模型可能无法理解和尊重多样化的文化、价值观和人口特征，甚至会放大偏见；还有就是效率与成本（低延迟对齐）问题，RLHF 流程（特别是基于 PPO 的方法）计算成本高昂，探索更轻量级的对齐方法（例如在推理时进行对齐）和更高效的算法，是降低成本、实现低延迟响应的关键。

针对上述挑战，学术界和工业界正探索更先进的对齐路径。其中具有代表性的方向包括：

（1）RLAIF (Reinforcement Learning from AI Feedback)：使用更强大的 AI 模型产生偏好信号，作为人类标注的补充或替代，以降低收集成本并缓解主观偏见。

（2）迭代式后训练 (Iterative Post-training)：如 LLaMA 3 的做法，不再是一次性的 RLHF，而是将“采样 -> 偏好标注 -> DPO/PPO 训练”作为一个循环不断迭代。前一轮的最优模型成为下一轮的数据生成器，实现模型的持续自我进化。

（3）从对话到推理 (Reasoning Models)：以 OpenAI o1 和 DeepSeek-R1 为代表，通过引入 RLVR 和长思维链（CoT），让模型在后训练阶段不仅仅是对齐偏好，更是通过强化学习探索复杂的逻辑推理路径，实现“慢思考”能力的涌现。这标志着 RLHF 正从单纯的“对齐”工具，演变为激发模型深层智能的关键手段。

参考文献

学术论文批量翻译

Thu, 26 Mar 2026 12:40:25 -0800

学术论文批量翻译

使用 pdf2zh_next 翻译学术论文

告别 API 报错！Python 批量翻译 PDF 论文：遍历文件夹 + 调用 pdf2zh_next 终端命令（100% 可用）

在使用 PDFMathTranslate-next (pdf2zh_next) 翻译学术论文时，很多朋友都会遇到 Python API 调用的各种坑：导入错误、配置校验失败、类缺失、版本冲突…… 折腾半天根本跑不起来。

其实最简单、最稳定的方案：用 Python 遍历 PDF 文件夹，自动调用终端命令pdf2zh_next逐份翻译，完全避开复杂的 API 适配，手动能跑的命令，代码就一定能跑！

本文就给大家带来零报错、开箱即用的批量 PDF 翻译脚本，适配 ollama 本地模型，保留原文格式，批量处理论文超方便。

PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/Docker

pdf2zh-next.com

一、适用场景

不想适配复杂的 Python API，只想快速批量翻译 PDF
旧版 / 新版pdf2zh_nextAPI 报错、导入失败、配置校验不通过
需要遍历文件夹自动翻译所有论文 PDF
使用 ollama 本地模型翻译，保留排版格式
默认使用 SiliconFlow 的翻译 API

二、环境准备

1. 安装依赖

确保你已经安装好pdf2zh_next：

1

pip install pdf2zh-next

2. 验证终端命令可用

先手动测试命令是否能正常运行（这一步很重要）：

1

pdf2zh_next .\papers_compression\测试论文.pdf --output .\paper_translated\

只要手动能翻译成功，本文代码就 100% 可用。

开启 GUI 格式：

1

pdf2zh_next --gui

三、完整批量翻译代码

这个脚本实现：遍历指定文件夹所有 PDF → 自动逐份翻译 → 实时输出日志 → 异常不中断任务。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


import os
import subprocess
from pathlib import Path

# ===================== 配置区域 =====================
PDF_FOLDER = r".\papers_compression" # 你的PDF文件夹
OUTPUT_FOLDER = r".\paper_translated" # 输出文件夹
LANG_IN = "en"
LANG_OUT = "zh"
# SERVICE = "ollama:translategemma"
# ====================================================

# 自动创建输出目录
os.makedirs(OUTPUT_FOLDER, exist_ok=True)

# 遍历所有PDF文件
pdf_dir = Path(PDF_FOLDER)
if not pdf_dir.exists():
 print(f"错误：文件夹不存在 {PDF_FOLDER}")
 exit()

pdf_files = list(pdf_dir.glob("*.pdf"))
if not pdf_files:
 print("未找到任何PDF文件")
 exit()

print(f"找到 {len(pdf_files)} 个PDF，开始批量翻译...\n")

# 逐个翻译
for i, pdf_path in enumerate(pdf_files, 1):
 pdf_str = str(pdf_path)
 print(f"[{i}/{len(pdf_files)}] 正在翻译: {pdf_path.name}")

 # 终端命令（完全和你手动输入的一致）
 cmd = [
 "pdf2zh_next",
 pdf_str,
 "--output", OUTPUT_FOLDER,
 "--lang-in", LANG_IN,
 "--lang-out", LANG_OUT,
 # "--service", SERVICE,
 # "--thread", "4"
 ]

 try:
 # 执行子进程（会实时打印翻译日志）
 subprocess.run(cmd, check=True)
 print(f"✅ 翻译完成: {pdf_path.name}\n")
 except subprocess.CalledProcessError as e:
 print(f"❌ 翻译失败: {pdf_path.name}\n")
 except KeyboardInterrupt:
 print("\n⏹️ 用户终止任务")
 break

print("🎉 批量翻译任务全部结束！")

四、代码使用说明

1. 修改配置

只需要修改脚本开头的配置区域，适配你的文件路径：

1
2
3


PDF_FOLDER = r".\papers_compression" # 你的论文文件夹
OUTPUT_FOLDER = r".\paper_translated" # 翻译输出文件夹
SERVICE = "ollama:translategemma" # 你的ollama模型名

2. 运行脚本

直接执行 Python 文件即可自动批量翻译：

1

python pdf_translator.py

3. 功能特性

✅ 自动遍历文件夹，识别所有.pdf文件
✅ 逐份翻译，单个文件失败不影响整体任务
✅ 实时打印翻译日志，和终端操作完全一致
✅ 支持Ctrl+C手动终止任务
✅ 自动创建输出文件夹，无需手动新建
✅ 保留 PDF 原版格式，完美适配学术论文

五、为什么这个方案最稳定？

不依赖任何 Python API

完全不调用pdf2zh_next的库代码，彻底解决：
- 导入错误ModuleNotFoundError
- 配置校验错误ValidationError
- 版本冲突、类缺失等问题
和手动执行命令完全一致

你在终端能跑通的命令，Python 子进程就一定能执行，无兼容性问题。
极简稳定

代码逻辑简单，没有复杂的异步、配置初始化，新手也能轻松使用。

相比于折腾复杂的 Python API，Python 遍历 + 终端命令是pdf2zh_next批量翻译最稳妥的方案。

这个脚本零报错、易修改、可直接投入使用，非常适合需要批量翻译英文论文的朋友，彻底告别 API 适配烦恼，专注于论文阅读！

其他工具

pdf2zh 工具

可能会报错：‘PDFPageInterpreterEx’ object has no attribute ’ncs’

当遇到 AttributeError: ‘PDFPageInterpreterEx’ object has no attribute ’ncs’ 错误时，通常是由于 pdfminer.six 库的版本更新或自定义类未正确继承所需属性导致的。

此问题可能是由于 pdfminer.six 的版本不兼容引起的。可以通过安装特定版本来解决，例如：

1

pip install pdfminer-six==20250416

此版本与许多项目的自定义实现兼容，避免了 ncs 属性缺失的问题。

📖 pdf2zh 桌面版 · 开箱即用的 PDF 学术翻译神器 🚀

开箱即用的免费桌面 PDF 论文翻译神器｜保留排版 + 公式无损 + 批量任务+ 历史追踪 + 长文本与扫描版增强｜基于 PDFMathTranslate 的 GUI 版

🎉 无需安装 Python · 无需配置环境 · 下载解压双击就能用！

基于 PDFMathTranslate（EMNLP 2025）打造，在原项目基础上大幅增强桌面体验。

让学术 PDF 翻译变得像复制粘贴一样简单——公式、图表、排版全部完美保留 ✨

🤔 为什么选择桌面版？

还在为翻译一篇论文折腾 Python 环境？还在对着黑窗口敲命令行？

桌面版帮你把这些烦恼统统打包带走 👋

-	原版（Web/CLI）🖥️	✨ 桌面版
安装方式	需要 Python + pip 😵	解压即用 🎁
操作界面	浏览器 / 终端	原生 Windows GUI 🪟
翻译预览	浏览器内查看	内置 PDF 预览器 👁️
批量处理	命令行参数	界面一键操作 🖱️
离线能力	不支持	程序本体完全离线 📴

✨ 桌面版增强亮点

🎯 真正的「零门槛」

📦 完全独立打包：Python 3.12 运行时 + 所有依赖全部内置，不污染你的系统
🖱️ 告别命令行：全图形化操作，拖拽文件就能翻译
🔧 智能错误诊断：出问题？程序自动弹窗告诉你怎么修
💼 真·便携版：拷贝到 U 盘带着走，换台电脑照样用

🚀 超长文档？不在话下！

📄 1000+ 页的大部头轻松拿下
🧩 分块翻译：自定义每块页数（5~200 页），自动分块逐段翻译，内置限流延迟，翻完自动拼接完整文档
🧠 智能内存管理：逐页释放布局数组，即使上千页也不会内存溢出
⏯️ 断点续传——中途退出也不怕，下次自动接着翻，不浪费一分 API 额度
📜 扫描版 PDF 支持：自动为译文区域生成白色背景，覆盖底图原文，扫描版书籍也能获得清晰的翻译结果

📚 历史记录 & 实时预览

🗂️ 完整翻译历史，键盘上下键快速切换，随时回看
👀 内置 PDF 预览器，翻译效果所见即所得
🔍 翻译前后对比，一目了然
📝 同一文件多次翻译自动编号（文件(1)、文件(2)），不覆盖历史结果

📁 批量翻译

📂 一次丢进来一堆 PDF，挨个翻译，每个文件独立跟踪进度
🎯 智能文件识别，只翻 PDF，不怕误操作

基于 peft 库的 LoRA 实战

Wed, 25 Mar 2026 22:40:25 -0800

基于 peft 库的 LoRA 实战

在前两个小节中，探讨了参数高效微调（PEFT）的理论背景和主流方法，特别是 LoRA 的核心原理。这些知识为我们提供了理论支撑，但要真正驾驭这些技术，还需要一个强大而易用的工具。本节将进入实战环节，学习使用当前社区常用的 PEFT 工具库——Hugging Face 的 peft ¹。 peft 库的设计理念与 Hugging Face 生态系统一脉相承，它希望将复杂的 PEFT 技术（如 LoRA, Prefix Tuning, Adapter 等）抽象成统一、简洁的接口，让开发者能够以最小的代码改动，将这些高效微调方法无缝地应用到 Hugging Face Hub 上的大模型上。如图 11-11，peft 库的官方文档将其内容划分为快速入门、方法指南、概念指南和参考手册，便于开发者上手。

图 11-11 Hugging Face PEFT 库官方文档首页

一、`peft` 库的设计理念

要理解 peft 库，首先要明白它并非要取代基础的模型库（例如 transformers），而是作为其插件或 增强模块 而存在。

我们可以类比游戏《黑神话：悟空》：

基础预训练模型：如同主角“天命人”（悟空），他本身已拥有强大的基础能力和标志性的金箍棒。但面对不同的 Boss（下游任务），只靠基础能力会很吃力。让他“重新修炼”以获得全新能力（即全量微调）显然不现实。
peft 库：则相当于悟空掌握的“七十二变”法术神通库。这个库里包含了各种强大的法术（如 LoRA）、变身能力（如 Prefix Tuning）和法宝（如 Prompt Tuning）。
PeftConfig：相当于一份为特定 Boss 战准备的“法术搭配方案”。这份方案详细规划了要启用哪一种核心神通（例如 peft_type='LORA'），以及该神通的具体参数（例如 LoRA 的 r、lora_alpha，可以理解为法术的威力和范围）。
get_peft_model 函数：扮演着“临阵变身”的角色。它接收基础的“悟空”（base_model）和选定的“法术搭配方案”（peft_config），然后依据方案，将对应的神通（例如 LoRA 的低秩矩阵）“加持”在悟空身上，从而打造出一个针对特定 Boss 特化的、能力更强的 PeftModel。

通过这种方式，无需改动庞大的基础模型本身（冻结其大部分权重），只需定义、训练和切换不同的轻量级插件（Adapter），就能让模型高效地适应各种下游任务。这不仅节省了大量的计算和存储资源，也使得模型的管理和部署变得更加灵活。

二、`peft` 库的核心组件

peft 库通过几个核心的类和函数，实现了对各种 PEFT 方法的统一封装，使其遵循一致的调用逻辑。接下来，简单介绍一下。

2.1 声明式配置 PeftConfig

PeftConfig 是所有 PEFT 方法配置的基类，它采用声明式的方式定义了微调的策略。其中最重要的两个通用参数是：

peft_type：一个枚举类型，用于 指定要使用的 PEFT 插件类型。例如，PeftType.LORA 明确表示使用 LoRA 方法。这是 peft 库能够自动检索和应用不同微调算法的关键。
task_type：同样是枚举类型，用于 指定模型的下游任务类型。例如，TaskType.CAUSAL_LM 用于自回归语言模型（如 GPT），TaskType.SEQ_2_SEQ_LM 用于序列到序列模型（如 T5）。这个参数能够帮助 peft 库为特定任务对模型的头部（Head）或其他结构进行正确的适配。

针对每一种具体的 PEFT 方法，peft 库都提供了一个继承自 PeftConfig 的子类，例如 LoraConfig、PromptTuningConfig 等。以 LoraConfig 为例，它包含了 LoRA 方法专属的超参数，这些参数直接源于 LoRA 论文中的定义：

r：LoRA 的秩（rank），决定了低秩矩阵 A 和 B 的中间维度 (d, r) 和 (r, k)。它是控制新增参数量和模型适应能力的核心超参数。
lora_alpha：LoRA 的缩放因子。在 LoRA 的计算中，低秩矩阵的输出 BAx 会乘以一个缩放系数 alpha/r。lora_alpha 就是这个公式中的 alpha，它用于调整低秩适应矩阵与原始权重矩阵合并时的尺度。
target_modules：一个字符串或正则表达式列表，用于 精确指定要将 LoRA 应用于基础模型中的哪些模块。如，["q_proj", "v_proj"] 表示仅在 Transformer 层的 query 和 value 投影矩阵上应用 LoRA。
lora_dropout：在 LoRA 层上应用的 Dropout 比例，用于防止过拟合。
bias：偏置参数的训练方式，可选值为 'none'（冻结所有 bias）、'all'（训练所有 bias）或 'lora_only'（仅训练 LoRA 模块自身的 bias）。

2.2 动态注入生成 PeftModel

get_peft_model 是 peft 库中的核心工厂函数。它接收一个原始的预训练模型和一个 PeftConfig 对象，然后执行以下操作：

解析 PeftConfig，确定要使用的 PEFT 方法和相关参数。
遍历基础模型的网络结构，根据 target_modules 找到需要注入 LoRA 模块的目标层。
将原始的目标层（如 nn.Linear）替换/封装为注入了 LoRA 的线性模块（如 LoraLinear 或其 k-bit 量化变体）。该模块内部保留冻结的原始权重，并引入可训练的低秩分支 A 和 B。
返回一个 PeftModel 实例。

返回的 peft_model 对象是一个高度封装的模型。它内部保留了对原始基础模型的引用，并通过动态修改其 forward 传递路径，实现了 LoRA 逻辑的注入。这个 peft_model 实例拥有与基础模型完全兼容的接口，可以直接用于 Trainer 或自定义的训练循环中。

peft_model 还提供了一个有用的调试方法是 print_trainable_parameters()，它可以计算并打印出模型中可训练参数的数量及其占总参数量的比例，能够直观地感受到 PEFT 在节约资源上的巨大优势。

三、LoRA 微调实战流程

结合 peft 库，可以形成一个标准的 LoRA 微调流程。下面以 EleutherAI/pythia-2.8b-deduped 模型为例，进行微调实战。

本节完整代码

3.1 加载依赖、基础模型与分词器

为了在消费级硬件上运行数十亿参数的大模型，需要采用量化技术。这里，我们使用 bitsandbytes 库，在加载模型时直接对其进行 8-bit 量化，并指定 dtype=torch.float16 以进一步优化显存。

根据 transformers 库的最新实践，现已不再推荐使用已被弃用的 load_in_8bit=True 参数，而是通过定义一个 BitsAndBytesConfig 对象，并将其传递给 quantization_config 参数来精确地控制量化行为。同时，通过设置 device_map="auto"，可以让 accelerate 库自动地、智能地将模型层分配到可用的硬件上（例如，将所有层都放到唯一的 GPU 上）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

model_id = "EleutherAI/pythia-2.8b-deduped"

# --- 使用 BitsAndBytesConfig 定义 8-bit 量化配置 ---
bnb_config = BitsAndBytesConfig(
 load_in_8bit=True,
)

# 加载模型，并将量化配置传给 `quantization_config` 参数
model = AutoModelForCausalLM.from_pretrained(
 model_id,
 quantization_config=bnb_config,
 dtype=torch.float16,
 device_map="auto",
)

执行完这段代码后，如果打印 model 对象，你会看到模型架构的详细信息。其中，类似 (query_key_value): Linear8bitLt(in_features=2560, out_features=7680, bias=True) 的层表明，原始的 nn.Linear 已经被成功替换为 8-bit 量化版本 Linear8bitLt，说明模型加载和量化已成功完成。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


GPTNeoXForCausalLM(
 (gpt_neox): GPTNeoXModel(
 (embed_in): Embedding(50304, 2560)
 (emb_dropout): Dropout(p=0.0, inplace=False)
 (layers): ModuleList(
 (0-31): 32 x GPTNeoXLayer(
 (input_layernorm): LayerNorm((2560,), eps=1e-05, elementwise_affine=True)
 (post_attention_layernorm): LayerNorm((2560,), eps=1e-05, elementwise_affine=True)
 (post_attention_dropout): Dropout(p=0.0, inplace=False)
 (post_mlp_dropout): Dropout(p=0.0, inplace=False)
 (attention): GPTNeoXAttention(
 (query_key_value): Linear8bitLt(in_features=2560, out_features=7680, bias=True)
 (dense): Linear8bitLt(in_features=2560, out_features=2560, bias=True)
 )
 (mlp): GPTNeoXMLP(
 (dense_h_to_4h): Linear8bitLt(in_features=2560, out_features=10240, bias=True)
 (dense_4h_to_h): Linear8bitLt(in_features=10240, out_features=2560, bias=True)
 (act): GELUActivation()
 )
 )
 )
 (final_layer_norm): LayerNorm((2560,), eps=1e-05, elementwise_affine=True)
 (rotary_emb): GPTNeoXRotaryEmbedding()
 )
 (embed_out): Linear(in_features=2560, out_features=50304, bias=False)
)

模型加载完成后，加载其对应的分词器。对于 Pythia 这类模型，其分词器默认可能没有 pad_token。在进行批量训练时，数据整理器（Data Collator）要用 pad_token 将序列填充至相同长度，我们需要手动将其设置为 eos_token。

1
2
3


tokenizer = AutoTokenizer.from_pretrained(model_id)
# Pythia模型的tokenizer默认没有pad_token，我们将其设置为eos_token
tokenizer.pad_token = tokenizer.eos_token

3.2 模型预处理

在使用 peft 对 8-bit 量化模型进行微调之前，需要进行一些必要的预处理。peft 库提供了一个非常方便的函数 prepare_model_for_kbit_training 来完成这项工作。

在 PEFT 0.10.0 及更高版本中，原来的 prepare_model_for_int8_training 已被 prepare_model_for_kbit_training 替代，新函数同时支持 4-bit 和 8-bit 量化。

这个函数主要执行几个关键操作：

（1）类型转换：将模型中一些需要以更高精度（如 FP32）计算的层（例如 LayerNorm）进行类型转换，以保证训练的数值稳定性。

（2）启用梯度检查点：调用 model.gradient_checkpointing_enable()，这是一种用计算时间换取显存的技术。它在反向传播时会重新计算中间层的激活值，而不是将它们全部存储在显存中，从而显著降低了训练过程中的显存峰值。

（3）输出嵌入层预处理：对模型的输出嵌入层进行一些必要的处理，以使其与 LoRA 兼容。

（4）输入梯度处理：为需要的输入启用梯度，保证在冻结大部分权重且使用 k-bit 训练时的反向传播兼容性。

1
2
3
4


from peft import prepare_model_for_kbit_training

# 对量化后的模型进行预处理
model = prepare_model_for_kbit_training(model)

3.3 定义 LoRA 配置并创建 `PeftModel`

这是整个 PEFT 流程中最核心的一步。我们将应用刚才介绍的核心组件，实例化一个 LoraConfig 对象来声明 LoRA 微调的具体策略，然后使用 get_peft_model 函数将其应用到预处理过的基础模型上。

在 LoraConfig 中，会详细设置 LoRA 的各个超参数，这些参数的选择直接关系到微调的效果和效率，与在上节 LoRA 方法详解 中讨论的理论紧密相关：

r：LoRA 的秩。这是最关键的超参数之一。r 越大，意味着低秩矩阵的表达能力越强，可训练的参数也越多。但正如前文的实验所示，r 并非越大越好，过大的 r 可能会增加噪声，且会线性增加可训练参数量。通常建议从 8 或 16 开始尝试。
lora_alpha：LoRA 的缩放因子。在前文提到过，最终的权重更新量会以 alpha/r 的比例进行缩放。这意味着，lora_alpha 的值可以理解为对学习到的低秩矩阵的“增强系数”。一个常见的做法是将其设置为 r 的两倍。
target_modules：指定要将 LoRA 应用于模型中的哪些模块。这是一个非常关键的参数，因为不同模型的模块命名方式不同。

如何确定 target_modules？ 可以先打印出基础模型 model 的结构，并以其显示的层命名为准。对于大多数 Transformer 模型，注意力机制中的“查询（Query）”、“键（Key）”和“值（Value）”层（如 q_proj, k_proj, v_proj）是首选。而对于 Pythia 或 GPT-NeoX 系列模型，其注意力权重常被合并在一个 query_key_value 层中，前馈网络（FFN）中的线性层则常见 dense、dense_h_to_4h 和 dense_4h_to_h。将 LoRA 应用于这些层通常都能带来收益。
bias：偏置参数的训练方式。'none' 是最常用的设置，意味着不训练任何偏置参数，这与 LoRA 的原始思想保持一致，以最大化参数效率。在数据量充足的情况下，可以尝试 'lora_only'，仅训练 LoRA 模块自身的偏置。

LoraConfig 的其他参数（如 lora_dropout、task_type）也都提供了对微调过程的精细控制，具体代码如下。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from peft import LoraConfig, get_peft_model

# 定义 LoRA 配置
config = LoraConfig(
 r=16,
 lora_alpha=32,
 target_modules=["query_key_value", "dense"],
 lora_dropout=0.05,
 bias="none",
 task_type="CAUSAL_LM",
)

# 应用配置，获得 PEFT 模型
peft_model = get_peft_model(model, config)
peft_model.print_trainable_parameters()

输出如下：

1

trainable params: 7,864,320 || all params: 2,783,073,280 || trainable%: 0.2826

通过前面提到的 print_trainable_parameters() 可以看到，可训练参数仅占总参数量的 0.28%。

3.4 数据处理

现在模型已经准备就绪，需要为它准备“教材”——也就是训练数据。本次微调的目标是让模型学会生成名人名言。这里将使用 Abirate/english_quotes 这个数据集，它包含了大量的英文名言。

数据处理流程如下：

加载数据集：使用 datasets 库从 Hugging Face Hub 下载数据集。
数据预处理：定义一个 tokenize 函数，该函数会接收一批数据，提取出所关心的 quote 字段，然后使用之前加载的分词器 tokenizer 对其进行编码，将其转换为模型可以理解的 input_ids。
应用处理：使用 dataset.map() 方法，将 tokenize 函数批量应用到整个数据集上。这是 datasets 库一个非常高效的特性。

首先，加载数据集并查看一条样本。

1
2
3
4
5
6
7


from datasets import load_dataset

# 加载数据集
quotes_dataset = load_dataset("Abirate/english_quotes")

# 查看数据集示例
quotes_dataset['train'][0]

输出显示了数据集的结构，包含 quote、author 和 tags 字段。

1
2
3
4
5
6
7
8


{'quote': '“Be yourself; everyone else is already taken.”',
 'author': 'Oscar Wilde',
 'tags': ['be-yourself',
 'gilbert-perreira',
 'honesty',
 'inspirational',
 'misattributed-oscar-wilde',
 'quote-investigator']}

接下来，定义分词函数并将其应用到整个数据集上。

1
2
3
4
5
6
7
8
9


# 定义分词函数
def tokenize_quotes(batch):
 # 只对 "quote" 列进行分词
 return tokenizer(batch["quote"], truncation=True)

# 对整个数据集进行分词处理
tokenized_quotes = quotes_dataset.map(tokenize_quotes, batched=True)

tokenized_quotes['train'][0]

处理后的数据集新增了模型所需的 input_ids 和 attention_mask 列。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{'quote': '“Be yourself; everyone else is already taken.”',
 'author': 'Oscar Wilde',
 'tags': ['be-yourself',
 'gilbert-perreira',
 'honesty',
 'inspirational',
 'misattributed-oscar-wilde',
 'quote-investigator'],
 'input_ids': [1628, 4678, 4834, 28, 4130, 2010, 310, 2168, 2668, 1425],
 'attention_mask': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}

3.5 定义 Trainer 并开始训练

Trainer 是 transformers 库提供的一个高度抽象化的训练器，它封装了标准的 PyTorch 训练循环。只需通过 TrainingArguments 定义训练的“策略”，而无需手动编写繁琐的训练代码（如梯度更新、学习率调度、日志记录等）。

在 TrainingArguments 中，会设置一些关键的训练参数：

per_device_train_batch_size & gradient_accumulation_steps：这两个参数共同决定了有效批量大小（effective batch size）。per_device_train_batch_size 是指每个 GPU 单次前向传播处理的样本数，而 gradient_accumulation_steps 则指定了梯度累积的步数。有效批量大小 = per_device_train_batch_size * gradient_accumulation_steps * num_gpus。通过梯度累积，可以在显存有限的情况下，模拟出更大的批量大小，这通常有助于稳定训练过程。
warmup_steps: 学习率预热的步数。在训练初期，学习率会从一个很小的值线性增加到设定的 learning_rate，这能让模型在开始阶段更好地适应数据。
max_steps: 训练的总步数。为了快速演示，这里只训练 200 步。
learning_rate: 学习率，控制模型参数更新的幅度。
fp16: 启用 16-bit 混合精度训练。可以在不牺牲太多性能的情况下，进一步减少显存占用并加速训练。

最关键的是，将之前创建的 PeftModel 实例直接传递给 Trainer。Trainer 会足够智能，自动识别出只有 LoRA 相关的参数是可训练的，并在训练时冻结所有其他参数。

除了上述基础参数外，还有两个关于训练策略的要点值得注意：

max_steps vs num_train_epochs：TrainingArguments 允许通过设置 max_steps（总训练步数）或 num_train_epochs（总训练轮数）来控制训练的总长度。在快速原型验证或演示时，使用 max_steps 可以精确控制训练量，便于快速看到结果。在正式的项目中，使用 num_train_epochs 更为常见，它能确保模型完整地学习过所有训练数据指定的轮数。
验证集的缺失：在专业的训练流程中，通常会从数据集中划分出一部分作为验证集，并在 TrainingArguments 中通过 evaluation_strategy 参数设置评估时机（例如，每 N 步或每个 epoch 结束后），以便监控模型是否过拟合，并据此进行早停等操作。为了简化演示流程，本教程省略了这一环节。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


from transformers import Trainer, TrainingArguments, DataCollatorForLanguageModeling

# 推荐操作：关闭缓存可提高训练效率
peft_model.config.use_cache = False

# 定义训练参数
train_args = TrainingArguments(
 per_device_train_batch_size=4,
 gradient_accumulation_steps=4,
 warmup_steps=100,
 max_steps=200,
 learning_rate=2e-4,
 fp16=True, # 启用混合精度训练
 logging_steps=1,
 output_dir="outputs",
)

# 数据整理器，用于处理批量数据
quote_collator = DataCollatorForLanguageModeling(tokenizer, mlm=False)

# 实例化 Trainer
trainer = Trainer(
 model=peft_model,
 train_dataset=tokenized_quotes["train"],
 args=train_args,
 data_collator=quote_collator,
)

# 开始训练
trainer.train()

执行 trainer.train() 后，控制台会实时打印训练日志。训练完成后，train 方法会返回一个包含所有训练指标的 TrainOutput 对象，方便进行分析和记录。

3.6 模型保存与推理

训练完成后，可以将学到的知识——也就是轻量的 LoRA 适配器保存下来，以备后续使用。

对 PeftModel（即 peft_model）调用 save_pretrained() 时，peft 会只保存增量的、可训练的适配器权重，而不是整个庞大的基础模型。通常，保存下来的文件（adapter_model.safetensors 和 adapter_config.json）只有几十 MB。

合并权重

正如上节中所讨论的，LoRA 的一个核心优势是它不会在推理时引入额外的延迟。这是因为它训练出的旁路矩阵 $A$ 和 $B$ 可以被 合并（merge） 回原始的权重矩阵中。训练完成后，可以调用 merged_model = peft_model.merge_and_unload() 方法，它会返回一个标准的 transformers 模型，其权重已经包含了 LoRA 的更新。这个 merged_model 的结构与原始模型完全一致，所以可以像任何普通模型一样进行部署，而没有任何额外的计算开销。若基础模型以 8/4-bit 量化加载，合并后返回的标准模型通常会转为 FP16/FP32；若需继续以 k-bit 部署，可在合并后按需重新量化。

为了验证微调的效果，可以进行一次推理测试，观察模型在续写名言开头的表现。为了获得最佳的推理效果并避免警告，需要注意以下几点：

传递 attention_mask：显式传递 attention_mask，确保模型能够正确识别有效的 token。
启用采样：设置 do_sample=True 以启用温度采样和核采样参数。
启用 use_cache：推理前将 use_cache=True 可提升生成效率；训练阶段通常配合梯度检查点将其关闭。

生成参数说明：

max_length: 生成文本的最大长度（包括输入）。
do_sample: 是否使用采样策略。设置为 True 时，temperature、top_p、top_k 才会生效。
temperature: 控制生成的随机性。较低的值（如 0.6）会使生成更具确定性，而较高的值则会增加多样性。
top_p: 核采样的概率阈值。只考虑累积概率达到 top_p 的最小 token 集合。
top_k: 每步只从概率最高的 k 个 token 中采样。
repetition_penalty: 重复惩罚因子，大于 1.0 会降低重复内容的概率。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# 将模型设置为评估模式
peft_model.eval()

# 设置 pad_token_id 到模型配置中
peft_model.config.pad_token_id = tokenizer.pad_token_id

prompt = "Be yourself; everyone"

# 对输入进行分词，并获取 attention_mask
inputs = tokenizer(prompt, return_tensors="pt")
input_ids = inputs["input_ids"].to(peft_model.device)
attention_mask = inputs["attention_mask"].to(peft_model.device)

# 生成文本
with torch.no_grad():
 # 使用 autocast 提高混合精度推理的效率
 with torch.amp.autocast('cuda'):
 outputs = peft_model.generate(
 input_ids=input_ids,
 attention_mask=attention_mask,
 max_length=50,
 do_sample=True,
 temperature=0.6,
 top_p=0.95,
 top_k=40,
 repetition_penalty=1.2,
 pad_token_id=tokenizer.pad_token_id
 )

# 解码并打印结果
decoded_output = tokenizer.decode(outputs[0], skip_special_tokens=True)
decoded_output

输出如下：

1

'Be yourself; everyone else is taken.” - Oscar Wilde"I have found that people will forget what you said, people will forget what you did, but people will never forget how you made them feel” Maya Angelou“The worst thing we'

从输出可以看到，模型成功地补全了这句来自奥斯卡·王尔德的名言，并且还继续生成了另一句风格相似的名言。这表明，仅仅通过200步的微调，模型就已经从数据集中大致学习到了名言的风格和内容，证明了 PEFT 方法的高效性。

模型输出的非确定性

大语言模型输出的非确定性主要来源于解码阶段的采样策略。当 do_sample=True 时，模型会根据计算出的词汇表概率分布进行随机抽样，而不是像确定性的贪心搜索那样总是选择概率最高的词。temperature、top_p 等参数正是用来调节这种抽样过程的随机程度的。

所以，这些采样参数是引入输出多样性的主要和意图性 的来源。除此之外，底层的CUDA算子、浮点数计算精度等因素也可能导致即使在固定随机种子的情况下，两次运行结果仍存在微小差异，但这并非主要原因。在本地运行时得到与文档不完全相同的结果，属于正常现象。

参考文献

Hugging Face PEFT Documentation. (2024). ↩︎

使用 Qwen2.5 微调私有数据

Wed, 25 Mar 2026 22:39:25 -0800

使用Qwen2.5 微调私有数据

在前几节的学习中，我们已经构建起一套完整的参数高效微调知识体系。手握“道”（PEFT 理论）与“器”（peft 库）之后，本节将以 Qwen2.5 模型为例，应用 QLoRA 技术进行微调实战。

在开始之前，需要先对模型有一定的了解。模型的架构范式、关键组件（如注意力机制的实现、激活函数的选择）以及预训练时采用的技巧——从根本上决定了微调的正确“姿势”。例如，在上一节对 Pythia 模型的微调中，我们在 LoraConfig 里指定了 target_modules=["query_key_value", "dense"]。这个参数并非随意设置，而是由 Pythia 模型的具体结构决定的。如果将这套配置原封不动地用于 Qwen2.5，结果很可能是失败的。基于以上讨论，下面我们先了解一下 Qwen2.5 的架构特点。

一、Qwen2.5 模型要点解析

Qwen2.5 是阿里巴巴开源的高性能大语言模型家族，涵盖了从 0.5B 到 72B 的多种参数规模，以满足不同场景的需求。它不仅是一个单独的模型，更是一个强大的基础平台，在其之上衍生出了 Qwen2.5-Math、Qwen2.5-Coder 等专业模型 ¹。

在图 11-12 中展示了 Qwen 系列模型（从 Qwen1.5-72B 到 Qwen2.5-72B）的性能与其预训练数据量之间的正相关关系。随着数据规模从 3 万亿 Token 增长至 18 万亿 Token，模型在 MMLU、BBH、MBPP 和 Math 等多个关键基准测试上的得分均稳步提升。这证明，海量、高质量的预训练让 Qwen2.5 拥有了强大的通用能力。

图 11-12 Qwen系列模型性能随预训练数据量增长

1.1 预训练奠定能力

Qwen2.5 强大的基础能力源于在高达 18 万亿 Token 的高质量、多样化数据上的预训练。这不仅是一个量的堆砌，更是在关键领域上的策略性强化：

通用知识：涵盖了广泛的常识、百科知识，为模型的通用对话和理解能力奠定基础。
专业领域：重点加强了代码和数学相关数据的训练，使得 Qwen2.5 在这两个领域具有天然的优势。

了解模型的“学前教育”背景，能帮助我们更好地判断它是否适合我们的微调目标。

1.2 Decoder-only 架构

Qwen2.5 的核心是一个标准的、仅包含解码器的 Transformer 架构。它的工作方式就是给定一段文本，模型从左到右依次读取，并在每一步都尽力预测下一个最可能的 Token。

其关键架构组件与 Llama 类似，这些技术我们在 “手搓一个大模型” 中基本已经有过介绍，可以回顾一下：

分组查询注意力：在保证模型性能的同时，有效降低 KV 缓存的占用，提升长序列推理效率。
SwiGLU 激活函数：作为 FFN 的非线性激活（实现上常体现为 SiLU 激活的门控前馈，模型打印时显示为 SiLUActivation），已被证明可以提升性能。
旋转位置编码：用于对序列中的位置信息进行编码，在处理长序列时很重要。
RMSNorm：在每个 Transformer 子层之前进行预归一化，以确保训练过程的稳定性。
QKV 偏置（Bias）：在注意力机制的查询（Query）、键（Key）、值（Value）投影中加入了偏置项，以增强模型表达能力。

1.3 分词器与对话模板

如果说模型架构是“大脑”，那么分词器和对话模板就是它与世界沟通的“语言和语法规则”。用错了规则，模型就会“误解”我们的意图。

分词器（Tokenizer）：Qwen2.5 采用 字节级 BPE (Byte-level Byte-Pair Encoding, BBPE) 分词器，其词表大小为 151,643。BBPE 能够有效处理多语言和未登录词。
对话模板（Chat Template）：这是指导模型理解多轮对话结构的关键。Qwen2.5 的 tokenizer 内置了官方推荐的模板，我们可以通过 apply_chat_template 方法来自动应用它。

一个典型的多轮对话，在 Qwen2.5 的模板下，会被格式化成类似下面的字符串（其中 <|im_start|> 和 <|im_end|> 是特殊 token，用于界定角色和内容的边界）：

1
2
3
4
5
6


<|im_start|>system
You are a helpful assistant.<|im_end|>
<|im_start|>user
你好，请介绍一下你自己。<|im_end|>
<|im_start|>assistant
你好，我是通义千问...<|im_end|>

这可以确保模型能正确理解“谁在说话”、“指令是什么”、“应该从哪里开始回答”。

二、制定 Qwen2.5 微调策略

在投入 GPU 资源开始训练之前，必须基于对模型的理解来制定微调策略。这能帮助我们明确配置、正确处理数据，并最大化微调效果。整个策略的制定，可以围绕以下四个问题展开。

（1）首先需要明确最基础的模型架构。Qwen2.5 是一个标准的 Decoder-only 架构，唯一的预训练任务就是 从左到右预测下一个词 (Causal Language Modeling)。这一“天性”决定了我们的微调必须遵循它的规则。在配置 LoraConfig 时，task_type 参数必须设为 "CAUSAL_LM"；同时，所有微调数据都必须被构造成 [输入/提示] -> [期望的输出] 的因果序列格式，让模型学习在给定“因”之后，生成我们期望的“果”。

（2）要确保我们与模型之间的“沟通语言”是正确无误的。模型通过**分词器（Tokenizer）和对话模板（Chat Template）**来理解输入。任何偏差都会导致灾难性的误解。因此，数据预处理的核心，就是将我们的原始数据，如问答对，严格地转换 为 Qwen2.5 的官方对话模板格式。这不仅是简单的字符串拼接，而是要使用 <|im_start|> 和 <|im_end|> 等特殊 Token，精确地构建出模型能够理解的结构化内容。最可靠的方法是调用 transformers 库提供的 apply_chat_template 函数，它能保证格式的绝对正确。

（3）我们需要决定将 LoRA 适配器“注入”到模型的哪些部位。为了最高效地影响模型的行为，我们应将目标对准计算最密集的“核心组件”，也就是自注意力和前馈网络模块。这要求我们在 LoraConfig 中，将 target_modules 参数优先指向这些模块中的线性层，例如注意力模块中的查询、键、值、输出投影层（q_proj, k_proj, v_proj, o_proj），以及前馈网络中的门控、上行和下行投影层（gate_proj, up_proj, down_proj）。

（4）微调策略的选择应充分利用模型的“先天优势”。微调并非从零开始，而是对一位博学的“通才”进行专业“深造”。Qwen2.5 在海量数据上进行了预训练，并在知识、代码和数学等领域得到了特别强化。这意味着模型已具备了强大的先验知识。如果我们的微调目标恰好与这些领域相关，例如构建一个特定领域的代码助手或知识问答机器人，那么 Qwen2.5 便是一个绝佳的起点。此时，微调过程将事半功倍，因为我们是在模型已有的强大能力之上，引导它去适应我们特定的任务需求。

通过以上四个方面的考量，我们对 Qwen2.5 的微调有了一个初步的规划。

三、构建私有微调数据集

虽然已经大致确定了微调流程，但是好像还缺点什么🤔。我们还没有数据！为了更清晰的了解整个过程，我们将不再使用已有的数据集，这次选择构建自己的私有数据集来完成整个微调过程。

3.1 微调前的能力评估

在投入资源微调前，必须先摸清基础模型的底细，确认微调的必要性。这里选择游戏《黑神话：悟空》进行效果测试。

评估完整代码

3.1.1 加载量化模型与分词器

为了在消费级硬件上运行模型，我们选择 Qwen2.5-7B-Instruct 作为基础模型并以 4-bit 量化的方式加载模型和对应的分词器。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

# 定义模型 ID
model_id = "Qwen/Qwen2.5-7B-Instruct"

# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 定义4-bit量化配置
bnb_config = BitsAndBytesConfig(load_in_4bit=True)

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
 model_id,
 quantization_config=bnb_config,
 device_map="cuda:0",
)

接下来可以打印一下模型实例，看看具体的网络结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


Qwen2ForCausalLM(
 (model): Qwen2Model(
 (embed_tokens): Embedding(152064, 3584)
 (layers): ModuleList(
 (0-27): 28 x Qwen2DecoderLayer(
 (self_attn): Qwen2Attention(
 (q_proj): Linear4bit(in_features=3584, out_features=3584, bias=True)
 (k_proj): Linear4bit(in_features=3584, out_features=512, bias=True)
 (v_proj): Linear4bit(in_features=3584, out_features=512, bias=True)
 (o_proj): Linear4bit(in_features=3584, out_features=3584, bias=False)
 )
 (mlp): Qwen2MLP(
 (gate_proj): Linear4bit(in_features=3584, out_features=18944, bias=False)
 (up_proj): Linear4bit(in_features=3584, out_features=18944, bias=False)
 (down_proj): Linear4bit(in_features=18944, out_features=3584, bias=False)
 (act_fn): SiLUActivation()
 )
 (input_layernorm): Qwen2RMSNorm((3584,), eps=1e-06)
 (post_attention_layernorm): Qwen2RMSNorm((3584,), eps=1e-06)
 )
 )
 (norm): Qwen2RMSNorm((3584,), eps=1e-06)
 (rotary_emb): Qwen2RotaryEmbedding()
 )
 (lm_head): Linear(in_features=3584, out_features=152064, bias=False)
)

通过结构可以看到，注意力模块（self_attn）和前馈网络（mlp）中的所有线性层（如 q_proj, v_proj, gate_proj 等）都已被替换为 Linear4bit，这说明 4-bit 量化已成功应用。这些层的名称也是后续进行 LoRA 微调时需要关注的目标模块。

3.1.2 定义推理函数

接着，定义一个 chat 函数，该函数负责将我们的提问，通过 Qwen2.5 的对话模板（Chat Template）格式化后，再送入模型进行推理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


def chat(user_message, system_message="你是《黑神话：悟空》领域助手，回答准确、简明。"):
 messages = [
 {"role": "system", "content": system_message},
 {"role": "user", "content": user_message}
 ]

 # 应用对话模板
 text = tokenizer.apply_chat_template(
 messages,
 tokenize=False,
 add_generation_prompt=True
 )

 model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

 # 模型生成
 generated_ids = model.generate(
 input_ids=model_inputs.input_ids,
 attention_mask=model_inputs.attention_mask,
 max_new_tokens=256
 )

 # 解码时跳过 prompt 部分
 generated_ids = [
 output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
 ]

 response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]

 return response

你可能已经注意到，我们使用的模型 Qwen/Qwen2.5-7B-Instruct 带有一个 -Instruct 后缀。这个后缀是区分“基础模型”和“指令微调模型”的标识。

基础模型 (Base Model)，如 Qwen/Qwen2.5-7B，是经过海量文本预训练的，擅长文本续写，但通常不直接用于对话或问答。

指令/对话模型 (Instruct/Chat Model)，如我们使用的 -Instruct 版本，是在基础模型之上，用高质量的“指令-回答”数据对进行额外微调的产物。这个过程会教会模型如何遵循指令、扮演特定角色并以对话形式进行交流。

像 Qwen2.5-Instruct 这样的指令微调模型，它们在训练时接收的不是纯粹的文本，而是一种带有 特殊格式的对话结构。这就像一种“语法”，模型通过它来理解不同角色（如系统 system、用户 user、助手 assistant）之间的对话流程。

Qwen2.5 的“语法”就包含像 <|im_start|> 和 <|im_end|> 这样的特殊标记。如果模型在推理时收到的输入不符合这个格式，它就无法很好地理解指令，也就不能产生预期的、高质量的回答。

tokenizer.apply_chat_template 函数的作用，就是 自动、准确地将我们输入的对话列表转换成模型训练时所使用的这种标准格式。

3.1.3 执行评估

我们向模型提出两个关于《黑神话：悟空》的问题，来检验它的知识储备。

（1）“我该怎么成为天命人？”

1
2
3


question_1 = "我该怎么成为天命人？"
answer_1 = chat(question_1)
print(f"问题: {question_1}\n回答:\n{answer_1}")

输出如下：

1
2
3
4
5
6
7
8


问题: 我该怎么成为天命人？
回答:
在《黑神话：悟空》的设定中，成为天命人需要满足特定条件和经历一系列考验。具体步骤包括：

1. **选对道路**：游戏中选择正确的道路至关重要，不同道路会影响角色的发展方向。
2. **完成任务**：跟随游戏主线和支线任务，完成各种挑战和任务。
...
最终是否能成为天命人取决于玩家的选择和表现。请注意，《黑神话：悟空》尚未正式发布，上述内容基于已知的游戏设定进行推测。实际游戏中可能有所不同。

（2）“如何获得并合成出云棍？”

1
2
3


question_2 = "如何获得并合成出云棍？"
answer_2 = chat(question_2)
print(f"问题: {question_2}\n回答:\n{answer_2}")

输出如下：

1
2
3
4
5
6
7
8


问题: 如何获得并合成出云棍？
回答:
在《黑神话：悟空》中，云棍可以通过完成特定任务和击败特定 boss 获得材料，然后在炼器炉中合成。

具体步骤如下：
1. **获取材料**：首先需要通过游戏中的特定任务或击败特定 boss 来获得制作云棍所需的材料。
...
请注意，《黑神话：悟空》目前尚未正式发布，上述信息基于游戏设定和预告片内容，具体细节可能会有所调整。

可以看出 Qwen2.5-7B-Instruct 对于《黑神话：悟空》的具体知识存在明显的 细节缺失和偏差，无法正确的回答关于黑猴的问题。

3.2 通过 LLM 构建数据集

评估完成后，我们正式进入数据集构建阶段。我们将利用一个更强大的“教师”模型，将非结构化的游戏介绍文档，自动化地加工成结构化的指令微调数据集。

数据构建完整代码

3.2.1 初始化与配置

首先，我们进行环境配置，初始化 API 客户端，并定义输入输出路径。笔者选用的是 Qwen/Qwen3-235B-A22B-Instruct-2507 作为“教师模型”来生成数据，如果本地算力支持也可以在本地进行推理。

什么是“教师模型”？

“教师模型”指的是一个能力强大、知识渊博的大语言模型。利用它的高级推理和语言生成能力，来为我们 自动化地生产高质量的训练数据。

这个过程类似于聘请一位领域专家（教师），让他阅读原始材料（blackwukong.md），然后根据这些材料编写一本高质量的练习册（我们的 (instruction, output) 数据集）。这本练习册随后将被用来训练一个更专注、更小型的“学生模型”（我们微调的 Qwen2.5-7B）。通过这种方式，可以将“教师模型”的通用知识和强大能力，“蒸馏”或迁移到特定任务中，从而提升数据构建的效率和质量。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


import os, re, json, datetime, time, random, glob
from openai import OpenAI

# 路径与配置
DATA_DIR = "./data"
SRC_MD = f"{DATA_DIR}/blackwukong.md"
TS = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
OUT_BASE_JSONL = f"{DATA_DIR}/wukong_base_{TS}.jsonl"
OUT_JSONL = f"{DATA_DIR}/wukong_dataset_{TS}.jsonl"

# 注意：此处为演示方便，不推荐在生产环境硬编码敏感信息
BASE_URL = "https://api.siliconflow.cn/v1"
MODEL_ID = "Qwen/Qwen3-235B-A22B-Instruct-2507"
API_KEY = "sk-..."

client = OpenAI(api_key=API_KEY, base_url=BASE_URL)

这里选用的是一个性能强大的 235B 模型作为“教师”，主要是为了最大化单次生成数据的质量，避免因模型能力不足导致需要反复调整 Prompt 或修正数据，从而节省宝贵的时间和精力。也就是“金钱换时间”。在实际应用中，可以根据自己的预算和需求，选用一个更小、更经济的模型来完成这项任务。虽然可能需要进行 Prompt 进行打磨，但同样能够生成高质量的数据集。

3.2.2 读取与切分源数据

本次选取的文档 blackwukong.md 处理自百度百科中的“黑神话：悟空”词条。下面读取这个 Markdown 作为知识来源，并按二级或三级标题切分成不同的知识片段。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


with open(SRC_MD, "r", encoding="utf-8") as f:
 raw_markdown = f.read()

# 按标题切分
matches = list(re.finditer(r"(?m)^(#{2,3})\\s+(.+)$", raw_markdown))
sections = []
# ... (此处省略切分与去重逻辑) ...
for i, m in enumerate(matches):
 s = m.start()
 e = matches[i + 1].start() if i + 1 < len(matches) else len(raw_markdown)
 block = raw_markdown[s:e].strip()
 if len(block) >= 100:
 sections.append(block)
# ...
print(f"sections={len(sections)}")

输出如下：

1

sections=14

3.2.3 生成初始问答对

简单设计一个 System Prompt，它会指导“教师”模型如何将知识片段转化为 (instruction, output) 问答对。

1
2
3
4
5
6
7
8
9


SYS_PROMPT = (
 "你是《黑神话：悟空》的资深资料整理者。"
 "将给定原文片段转写为一条训练样本，严格输出JSON："
 '{"instruction":"用户问题","output":"权威完整答案"}。'
 "要求："
 "1. instruction 是自然语言问题；"
 "2. output 仅依据原文，不要臆测；"
 "3. 禁止任何额外说明或代码块。"
)

然后，遍历所有知识片段，调用教师模型 API 生成基础问答对，并存入 wukong_base_{TS}.jsonl 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


os.makedirs(os.path.dirname(OUT_BASE_JSONL), exist_ok=True)
base_written = 0
with open(OUT_BASE_JSONL, "w", encoding="utf-8") as fbase:
 for seg in sections:
 # ... (此处省略 API 调用与重试逻辑) ...
 try:
 resp = client.chat.completions.create(
 model=MODEL_ID,
 messages=[
 {"role": "system", "content": SYS_PROMPT},
 {"role": "user", "content": seg},
 ],
 temperature=0.2,
 max_tokens=600,
 response_format={"type": "json_object"},
 )
 # ... (解析与写入逻辑) ...
 obj = json.loads(resp.choices[0].message.content)
 ins = (obj.get("instruction") or "").strip()
 out = (obj.get("output") or "").strip()
 if ins and out:
 fbase.write(json.dumps({"instruction": ins, "output": out}, ensure_ascii=False) + "\n")
 base_written += 1
 except Exception:
 continue

print(f"base saved: {base_written} -> {OUT_BASE_JSONL}")

输出如下：

1

base saved: 14 -> ./data/wukong_base_20251109_201117.jsonl

这段代码的逻辑是遍历每一个切分后的 Markdown 文本片段（sections），并让“教师”模型为每一个片段生成一个核心的 (instruction, output) 对。最后生成的 14 条基础问答对，与前面切分出的 14 个文本片段对应。

3.2.4 通过数据增强生成多样化提问

为了让模型能应对各种不同的提问方式，我们对每个基础问题进行“数据增强”，让教师模型生成 14 种不同的问法（此处以 14 为例，可根据需求调整），并写入最终的数据集文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


NUM_VARIANTS = 14
written = 0
# ...
with open(IN_BASE_JSONL, "r", encoding="utf-8") as fr, open(OUT_JSONL, "w", encoding="utf-8") as fw:
 for line in fr:
 # ...
 base_q = (json.loads(line).get("instruction") or "").strip()
 answer = (json.loads(line).get("output") or "").strip()

 # 设计用于数据增强的 Prompt
 paraphrase_prompt = (
 "严格输出 JSON 对象：{\\\"paraphrases\\\": [\\\"...\\\"]}；"
 "禁止任何额外文本/代码块/前后缀。"
 "每项必须是可直接回答的等价问法..."
 )

 # ... (API 调用与重试逻辑) ...
 r2 = client.chat.completions.create(...)

 # ... (解析与写入逻辑) ...
 arr = json.loads(r2.choices[0].message.content).get("paraphrases", [])
 for s in arr:
 # ... (去重与格式化) ...
 fw.write(json.dumps({"instruction": s, "output": answer}, ensure_ascii=False) + "\n")
 written += 1

print(f"saved: {written} -> {OUT_JSONL}")

现在，我们高效地将一篇文档，加工成了一百多条指令微调数据。可能数据质量不高，不过已经能够满足使用需要。

四、模型微调与评估

拥有数据集后，就进入了最后的模型微调与评估阶段。我们将使用上一节生成的 wukong_dataset_*.jsonl 文件，对 Qwen/Qwen2.5-7B-Instruct 模型进行 QLoRA 微调。

QLoRA 微调完整代码

4.1 QLoRA 微调

4.1.1 加载数据集、分词器与模型

首先，加载所有必需的库并加载之前准备好的数据集，接着初始化 Qwen2.5 的分词器。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


import os, glob, json, torch
from datasets import load_dataset
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import prepare_model_for_kbit_training

# ... (路径与配置) ...

# 加载数据集
train_set = load_dataset("json", data_files=train_jsonl, split="train")

# 加载分词器，并处理 pad_token
tokenizer = AutoTokenizer.from_pretrained(checkpoint_id, trust_remote_code=True)

tokenizer.pad_token, tokenizer.eos_token, tokenizer.pad_token_id, tokenizer.eos_token_id

输出如下：

1

('<|endoftext|>', '<|im_end|>', 151643, 151645)

在批量训练时，需要用一个 pad_token 将序列填充到相同长度。所以，在加载分词器后，打印出它的关键 token 可以帮助我们确认其默认配置。通过输出可以看到，Qwen2.5 分词器自带了 padding 功能所需的所有设置：pad_token 被设为 <|endoftext|> (ID 151643)，与 eos_token <|im_end|> (ID 151645) 相区分。说明我们可以直接在后续数据处理中使用 tokenizer.pad_token_id。

接下来，我们着手加载模型。这部分是 QLoRA 实现的核心，分为两个步骤：

（1）定义量化配置：通过 BitsAndBytesConfig，精确地告诉 transformers 库如何对模型进行量化。load_in_4bit=True 激活 4-bit 量化；bnb_4bit_quant_type="nf4" 指定使用正态浮点（NormalFloat）4-bit 类型，这是一种专为正态分布权重优化的数据类型；bnb_4bit_use_double_quant=True 启用双重量化，进一步节省显存；bnb_4bit_compute_dtype=torch.bfloat16 设置计算时使用的数据类型为 bfloat16，以在保持精度的同时加速计算。

（2）加载量化模型并进行预处理：使用 bnb_cfg 以 4-bit 加载；随后调用 prepare_model_for_kbit_training 做 k-bit 训练准备（启用输入梯度/可选梯度检查点、将部分归一化层上调为 float32 提升稳定性），不改变基础权重的可训练性。

为帮助读者区分 LoRA 与 QLoRA 的实现差异，这里进行总结：

LoRA：方法本体是冻结基础权重，仅训练注入的低秩适配器。上一节示例将其与 8-bit 量化加载结合，并以 FP16 训练。LoRA 本身不限定基础模型精度，也可以在 4-bit 量化的基础模型上使用；但当采用 NF4/双重量化等特定 4-bit 配置，并仅以 16-bit 训练适配器时，通常称为 QLoRA。

QLoRA：是在 LoRA 框架下的一套具体工程方案。标准做法是将冻结的基础权重量化为 4-bit（常用 NF4），启用 双重量化 与 分页优化器（PagedAdamW），同时仅以 16-bit（推荐 BF16） 训练 LoRA 适配器，以在极低显存下保持较高性能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 4-bit 量化配置
bnb_cfg = BitsAndBytesConfig(
 load_in_4bit=True,
 bnb_4bit_quant_type="nf4",
 bnb_4bit_use_double_quant=True,
 bnb_4bit_compute_dtype=torch.bfloat16,
)
base_model = AutoModelForCausalLM.from_pretrained(
 checkpoint_id,
 trust_remote_code=True,
 quantization_config=bnb_cfg,
 device_map="cuda:0",
)

# k-bit 训练预处理
base_model = prepare_model_for_kbit_training(base_model)

4.1.2 定义 LoRA 配置

在上一节中，我们通过手动指定模块名列表（如 ['query_key_value']）的方式来设置 target_modules。这种方法精确但需要人工检查。peft 库为了简化这一过程，提供了一种便捷的方式。它内置了一个映射表，包含了对多种主流模型推荐的 target_modules 配置。可以直接从这个映射中获取针对 qwen2 模型的推荐值，以确保 LoRA 被应用到最关键的层上。这个映射表的源码可以在 peft/utils/constants.py 中找到。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


from peft import LoraConfig, get_peft_model
from peft.utils import TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING

# LoRA 配置
lora_cfg = LoraConfig(
 r=16,
 lora_alpha=32,
 lora_dropout=0.05,
 bias="none",
 task_type="CAUSAL_LM",
 target_modules=TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING["qwen2"],
)
peft_model = get_peft_model(base_model, lora_cfg)
peft_model.print_trainable_parameters()

4.1.3 格式化数据集

在训练前，需要将问答对数据严格按照 Qwen2.5 的对话模板进行格式化，并生成用于计算损失的 labels。我们只对“回答”部分计算损失，而将“问题”部分的 labels 设置为 -100 以忽略。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


def format_sample_for_qwen(record):
 # ... 
 # 构造不包含答案的 prompt
 msgs_no_assist = [
 {"role": "system", "content": "..."},
 {"role": "user", "content": instr},
 ]
 prompt_ids = tokenizer.apply_chat_template(msgs_no_assist, ...)

 # 构造包含答案的完整对话
 msgs_full = msgs_no_assist + [{"role": "assistant", "content": ans}]
 full_ids = tokenizer.apply_chat_template(msgs_full, ...)

 # 生成 labels，仅保留答案部分的 token
 cut = len(prompt_ids)
 labels = [-100] * cut + full_ids[cut:]

 return {"input_ids": full_ids, "labels": labels}

# 对整个数据集应用格式化函数
proc_train = train_set.map(format_sample_for_qwen, ...)

4.1.4 定义训练器并开始训练

最后一步配置 TrainingArguments，实例化 Trainer 并开始训练。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


from transformers import TrainingArguments, Trainer

args = TrainingArguments(
 output_dir=run_dir, # run_dir 为动态生成的检查点目录
 per_device_train_batch_size=1,
 gradient_accumulation_steps=8,
 learning_rate=1e-3,
 num_train_epochs=4,
 lr_scheduler_type="linear",
 warmup_ratio=0.03,
 logging_steps=1,
 optim="adamw_torch",
 bf16=True, # 如果支持，优先使用 bf16
)

trainer = Trainer(
 model=peft_model,
 args=args,
 train_dataset=proc_train,
 data_collator=collator, # collator 为自定义的数据整理器
)

# 开始训练并保存 LoRA 适配器
train_output = trainer.train()
peft_model.save_pretrained(run_dir)

可以看到这里使用了 bf16=True 这个参数。它用于启用 BFloat16 混合精度训练。与常规的 FP16 相比，BF16 拥有与 FP32 几乎相同的动态范围，但在精度显存节省和计算加速，又能有效上有所牺牲。这一特性使得 BF16 在现代 GPU（如 NVIDIA Ampere 架构及更新版本）上进行深度学习训练时，既能享受到混合精度带来的避免 FP16 中常见的梯度下溢（vanishing gradients）问题，从而让训练过程更加稳定。因此，如果硬件支持，bf16 是比 fp16 更优先的选择。

4.2 效果评估与迭代

微调完成后，用同样的问题再次进行测试，检验微调的成果。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


peft_model.eval()
TEST_QUERIES = [ "我该怎么成为天命人？", "如何获得并合成出云棍？" ]

@torch.no_grad()
def infer_one(question: str) -> str:
 # ...（推理逻辑，构造prompt并调用 peft_model.generate）
 return tokenizer.decode(out_ids, skip_special_tokens=True).strip()

for q in TEST_QUERIES:
 ans = infer_one(q)
 print(f"Q: {q}\nA: {ans}\n" + "-" * 60)

输出如下：

1
2
3
4
5
6


Q: 我该怎么成为天命人？
A: 想要成为天命之人，首先你需要收集“部分灵根”，然后在特定地点（如石卵处）激活它们，之后才能解锁通往黄风岭、狼烟堡等地点的通行权，并进行后续剧情。
------------------------------------------------------------
Q: 如何获得并合成出云棍？
A: 在“黄风岭-挟魂崖”找到6个佛目珠后，前往“挟魂崖-枕石坪”BOSS石先锋所在区域，使用佛目珠召唤并击败BOSS石敢当，获得材料“铁石心”，之后即可解锁铸造出云棍。
------------------------------------------------------------

通过这个结果可以看出微调效果显著。模型成功地“吸收”了投喂的游戏知识，能够准确回答游戏相关问题。需要提醒的是，本例侧重演示流程，未系统控制过拟合风险。若数据量较小、训练步数/学习率设置不当，模型可能对训练样例“背题记忆”。

五、何时选择微调

我们已经完成了微调的初步学习，但何时需要进行微调呢？整个技术选型路径应遵循成本效益原则，从低到高依次为提示词工程 (Prompt Engineering) -> 检索增强生成 (RAG) -> 微调 (Fine-tuning)。

我们可以从两个维度来理解这些技术的区别。如图 11-13 所示，横轴代表“LLM 优化”，即对模型本身进行多大程度的修改。从左到右，优化的程度越来越深，其中提示工程和 RAG 完全不改变模型权重，而微调则直接修改模型参数。纵轴代表“上下文优化”，是对输入给模型的信息进行多大程度的增强。从下到上，增强的程度越来越高，其中提示工程只是优化提问方式，而 RAG 则通过引入外部知识库，极大地丰富了上下文信息。

图 11-13 技术选型路径图

基于这个框架，选择路径就很清晰了。我们应先尝试成本最低的“上下文优化”策略，通过精心设计提示词来引导模型，适用于任务简单、模型已有相关知识的场景。如果模型缺乏特定或实时知识而无法回答，下一步尝试使用 RAG，通过外挂知识库为大模型提供上下文信息。这两种方法的核心是“引导”和“提供知识”，能解决大部分问题，但无法从根本上改变模型的“行为”或“技能”。

当上述方法都无法满足需求时，就需要成本较高也是效果最好的微调登场。微调通过在高质量示例上继续训练，直接修改模型权重，从根本上重塑其能力。它并非用于灌输新知识（这是 RAG 的强项），而是用于传授特定的“技能”或“行为模式”。例如，让模型学会严格遵循某种独特的输出格式（如特定的 JSON 结构）、模仿特定人物的对话风格、深度适配某个专业领域的“行话”，或者将极其复杂的指令“蒸馏”进模型权重中以优化 API 调用。总结而言，当我们的目标是改变模型“如何做”而不是“知道什么”时，微调就是最终且最合适的选择。

本章小结

本章系统性地探讨了参数高效微调（PEFT）技术，从理论基础到实战应用，构建了一幅完整的知识图景。我们从大模型时代全量微调所面临的成本、存储与稳定性三大困境出发，引出了 PEFT 这一核心解决方案。

我们的探索遵循着 PEFT 技术的发展脉络：

作用于激活值的“加法”思路：我们首先学习了以 Adapter Tuning 为代表的早期方法，它通过在模型内部插入小型“适配器”模块来适应新任务。随后，我们转向了更为非侵入式的 Prompt Tuning 及其演进，包括 Prefix-Tuning 和 P-Tuning v2。这些方法的核心思想是在不触碰原始模型权重的前提下，通过添加可学习的“软提示”来引导模型的行为，影响其激活值。
重参数化权重的“手术刀”思路：接着，我们深入研究了当前社区最主流的 LoRA 技术。它另辟蹊径，不再“绕道”激活值，而是基于“权重更新低秩”的假设，直接通过低秩分解来模拟权重更新矩阵，实现了性能与效率的平衡，并解决了 Adapter 的推理延迟问题。我们还进一步学习了其两大重要变体，引入SVD思想和重要性评分机制、实现参数预算动态分配的 AdaLoRA；以及通过4-bit量化、双重量化和分页优化器等技术，将显存效率推向极致的 QLoRA。

在掌握了理论之后，我们将目光投向实践。学习了如何利用 Hugging Face 的 peft 库，它通过 PeftConfig 和 get_peft_model 等简洁的接口，将复杂的 PEFT 技术标准化，大大降低了应用门槛。通过对 pythia-2.8b 模型的 LoRA 微调实战，我们完整地走过了从加载量化模型、配置 LoRA 参数，到数据处理和使用 Trainer 进行训练的全过程。

最后，在 Qwen2.5 的 QLoRA 微调案例中，我们将所有知识融会贯通。这个案例不仅是一个综合性的实战，更强调了模型理解在微调策略制定中的地位——只有深入了解模型架构（如注意力模块构成）、分词器和对话模板，才能正确地设置 target_modules 和处理数据。同时，我们还实践了如何利用“教师模型”高效构建私有数据集，并最终通过微调，让模型掌握了特定领域的专业知识，验证了 PEFT 技术的强大威力。

在结束本章时，我们还建立了一个技术选型的决策框架，提示词工程 -> RAG -> 微调。应优先尝试成本最低的提示工程；当模型缺乏知识时，采用 RAG 为其“开卷考试”；只有当目标是改变模型的“行为模式”、传授“技能”（如遵循特定格式、模仿特定风格）时，才是微调登场的最佳时机。PEFT 不仅仅是一系列节约资源的技术，更是一种全新的、与大模型高效协作的范式，它让每一位开发者都有机会驾驭大模型的强大力量。

参考文献

Qwen Team. (2024). Qwen2.5 Technical Report. ↩︎

低秩近似（LoRA）方法详解

Wed, 25 Mar 2026 22:38:25 -0800

低秩近似（LoRA）方法详解

在上一节中，我们探讨了以 Adapter 和各类 Prompt Tuning 为代表的 PEFT 技术。它们通过在模型中插入新的模块或在输入端添加可学习的提示，巧妙地实现了高效微调。这些方法的核心，都是在尽量不“打扰”原始模型权重的前提下，通过影响模型的激活值来适应新任务。

本节，我们将介绍一种另辟蹊径，也是当前社区应用最广泛的 PEFT 方法——LoRA（Low-Rank Adaptation of Large Language Models）。它不再“绕道而行”，而是直击模型的权重矩阵，并提出一个观点。那就是大模型的参数更新，或许并不需要那么“兴师动众”。

一、低秩近似的核心思想

全量微调之所以成本高昂，是因为它需要为模型中每一个权重矩阵 $W$（维度可能高达数万）计算并存储一个同样大小的更新矩阵 $ΔW$。为了解决这个问题，研究者们提出了像 Adapter Tuning 和 Prompt Tuning 这样的参数高效微调方法。但是，它们也存在一些未解决的痛点。Adapter 虽好，却会引入额外的推理延迟；Prompt Tuning 则会占用输入序列长度，且优化难度较高。

有没有一种方法，既能大幅减少参数，又不引入推理延迟，还能直接作用于模型权重呢？这就是 LoRA 试图回答的问题。它的提出，源于一个假设 ¹：

大语言模型是过参数化的（Over-parametrized），它们在针对特定任务进行微调时，权重更新矩阵 $ΔW$ 具有一个很低的“内在秩”（Intrinsic Rank）。

这意味着，尽管 $ΔW$ 的维度很高，但它所包含的“有效信息”实际上可以被一个远小于其规模的低秩矩阵来表示。对此，LoRA 的核心思想就是用两个更小的“低秩”矩阵 $A$ 和 $B$ 的乘积，来模拟（近似）这个庞大的更新矩阵 $ΔW$。

$$ \Delta W = B \cdot A $$

其中， $W_0 \in \mathbb{R}^{d \times k}$，低秩分解后的 $B \in \mathbb{R}^{d \times r}$， $A \in \mathbb{R}^{r \times k}$，而秩 $r \ll \min(d, k)$。

LoRA 的工作方式可以理解为在原始的预训练权重 $W_0$ 旁边，增加了一个并行的“旁路”结构，如图 11-7 计算分为两条路径：

主路：输入 $x$ 经过原始的、被冻结的预训练权重 $W_0$。
旁路：输入 $x$ 依次通过两个低秩矩阵 $A$ 和 $B$。矩阵 $A$ 先将输入维度从 $k$ “压缩”到一个很小的秩 $r$，然后再由矩阵 $B$ “解压”回输出维度 $d$。

图 11-7 LoRA 结构示意图

最终的输出 $h$ 是这两条路径结果的加和：

$$ h = W_0 \cdot x + \Delta W \cdot x = W_0 \cdot x + (B \cdot A) \cdot x $$

在训练时，只有旁路的矩阵 $A$ 和 $B$ 会被更新。通过这种方式，需要优化的参数量就从 $d \times k$ 下降到了 $d \times r + r \times k$。通常，秩 $r$ 会选择一个非常小的值（如 8, 16, 64），使得可训练参数量仅为全量微调的千分之一甚至万分之一。

初始化与缩放技巧

初始化：如图 11-7 所示，旁路矩阵有特殊的初始化方式。矩阵 A 通常使用高斯分布进行随机初始化（ $A = \mathcal{N}(0, \sigma^2)$ ），而矩阵 B 则初始化为全零（ $B=0$ ）。这样做可以确保在训练开始时，旁路输出为零，微调是从原始的预训练模型状态开始的，保证了训练初期的稳定性。

缩放：LoRA 的前向计算公式会包含一个缩放因子 $s$: $h = W_0 \cdot x + s \cdot (B \cdot A) \cdot x$。这个 $s$ 通常设为 $\alpha/r$，其中 $\alpha$ 是一个可调超参。这个缩放操作有助于在调整秩 $r$ 时，减少对学习率等其他超参数的重新调整需求，让训练过程更稳定。

二、LoRA 的优势与实践

相比于之前介绍的 PEFT 方法，LoRA 以其独特的结构带来了显著的优势，下面来具体看一下。

2.1 核心优势

LoRA 凭借其独特的并行结构和直接作用于权重的特性，展现出几大核心优势：

更高的参数与存储效率：对于每一个下游任务，不再需要存储一个完整的模型副本，而只需保存极小的矩阵 A 和 B。论文指出，这可以将模型 checkpoints 的体积缩小高达 10,000 倍（例如从 350GB 减小到 35MB）。在训练时，由于无需为冻结的参数计算梯度和存储优化器状态，可以节省高达 2/3 的 GPU 显存，并提升约 25% 的训练速度。
零额外推理延迟：这是 LoRA 相比 Adapter Tuning 最具吸引力的优点。Adapter 在模型中串行地引入了新的计算层，不可避免地会增加推理延迟。而 LoRA 的旁路结构在训练完成后，可以通过矩阵加法 $(W’ = W_0 + s \cdot B \cdot A)$ 直接“合并”回原始权重中。这样，模型的网络结构与原始模型完全一致，不会引入任何额外的计算步骤。

这种“合并”策略的代价是，如果你需要为 不同的任务（拥有不同的 LoRA 权重）同时提供服务，在单个 batch 中混合处理这些任务会变得不那么直接。
效果媲美全量微调，且不占用输入长度：与 Prompt-Tuning 等作用于输入激活值的方法不同，LoRA 直接修改权重矩阵，能更深入、更直接地影响模型的行为，效果也更接近于全量微调。同时，它不添加任何 virtual token，不会占用上下文长度，在处理长文本任务时更有优势。
良好的可组合性：LoRA 的设计是 正交的，它可以与 Prefix-Tuning 等其他 PEFT 方法结合使用，取长补短，进一步提升模型性能。

2.2 关键实践

LoRA 虽然强大，但也带来了新的超参数选择问题：应该对哪些权重矩阵应用 LoRA？秩 $r$ 又该如何选择？幸运的是，原始论文通过大量实验为我们提供了指导。

第一个问题是：应该对哪些权重矩阵应用 LoRA？

LoRA 的作者们为了简化问题和提高参数效率，将研究范围 限定在了自注意力模块（Self-Attention）的权重矩阵 上，并冻结了前馈网络等其他模块。在自注意力模块中，主要有四个权重矩阵：查询（Query）的 $W_q$、键（Key）的 $W_k$、值（Value）的 $W_v$ 和输出（Output）的 $W_o$。通过原文的实验数据（如表 11-1 所示）可以发现一个规律。在固定的可训练参数预算下，将 LoRA 应用于 多种类型的注意力权重（特别是 $W_q$ 和 $W_v$ 的组合）通常比把所有预算用于增大单一类型权重的秩（rank）效果更好。所以，原论文提出并验证了一个高效的策略：仅在注意力模块中应用 LoRA，并冻结模型的其余部分。

	# of Trainable Parameters = 18M
Weight Type	W_q	W_k	W_v	W_o	W_q, W_k	W_q, W_v	W_q, W_k, W_v, W_o
Rank r	8	8	8	8	4	4	2
WikiSQL (±0.5%)	70.4	70.0	73.0	73.2	71.4	73.7	73.7
MultiNLI (±0.1%)	91.0	90.8	91.0	91.3	91.3	91.3	91.7

表 11-1 不同注意力权重上的 LoRA 微调效果

第二个问题是：秩 r 的选择是不是越大越好？

通过表 11-2 的实验结果可以看到，一个非常小的秩 $r$（例如 4, 8 甚至 1）就已经足够强大。盲目增大 $r$ 不仅会增加参数量，有时甚至会导致性能下降。例如，对于 $W_q$ 和 $W_v$ 的组合，即使秩 $r$ 仅为 1 或 2，模型在各项任务上的表现也已具竞争力，甚至超过了 $r=64$ 的情况。这说明权重更新确实是低秩的。

	Weight Type	r=1	r=2	r=4	r=8	r=64
WikiSQL(±0.5%)	W_q	68.8	69.6	70.5	70.4	70.0
	W_q, W_v	73.4	73.3	73.7	73.8	73.5
	W_q, W_k, W_v, W_o	74.1	73.7	74.0	74.0	73.9
MultiNLI (±0.1%)	W_q	90.7	90.9	91.1	90.7	90.7
	W_q, W_v	91.3	91.4	91.3	91.6	91.4
	W_q, W_k, W_v, W_o	91.2	91.7	91.7	91.5	91.4

表 11-2 不同秩 r 对 LoRA 微调效果的影响

最后一个问题是，LoRA 究竟是如何生效的？ 论文通过分析发现，它学习到的更新矩阵 $\Delta W$ 并不是对原始权重 $W_0$ 中最重要特征的简单复制，恰恰相反，它学习到的是那些在预训练中学习到但未被充分强调、却对下游任务至关重要的“隐藏特征”，并对其进行大幅放大。它不是在重复模型已经很擅长的事情，而是在“查缺补漏”，精准地增强了模型在特定任务上所欠缺的能力。

三、AdaLoRA 自适应微调

尽管我们根据上述实验知道了应该优先微调注意力权重、并选择一个较小的秩 r，但 LoRA 这种固定的设置方式仍然引入了新的问题：

秩 $r$ 的选择： $r$ 应该设为多大？这是一个固定的超参数，无法在训练中自适应调整。
微调目标的选择：应该对哪些权重矩阵（ $W_q, W_k, W_v, W_o$ 还是前馈网络的矩阵）应用 LoRA？原始 LoRA 论文的实验主要集中在注意力模块，忽略了 FFN 模块，但后续研究发现 FFN 的微调同样重要。

实验表明，为所有矩阵和所有层级设置一个统一的、固定的秩 $r$，远非最优解。不同任务、不同模型层、不同权重矩阵，其“可塑性”和对任务的重要性是不同的，它们理应被区别对待。手动为每个矩阵和层级寻找最优秩的组合，其超参数空间巨大，几乎不可能完成。不过，如图 11-8 所示的实验，已经揭示了这种重要性的差异：

图左侧显示，在固定的参数预算下，微调前馈网络（FFN）模块的权重（$W_{f1}, W_{f2}$）带来的性能收益，显著高于微调注意力模块的权重（$W_q, W_k, W_v, W_o$）。
图右侧则表明，微调模型更高层级（如 10-12 层）的权重，也比微调底层（如 1-3 层）能带来更大的性能提升。

图 11-8 不同模块与层级的微调性能对比

为了解决固定秩分配的次优性与手动调参的困难，AdaLoRA (Adaptive LoRA) ² 提出了一种更智能的、自适应的 LoRA 方案——根据权重的重要性，动态地、有选择地为不同模块分配参数预算。AdaLoRA 不再使用固定的秩 $r$，而是让模型在训练过程中自己“决定”哪些部分更需要被微调，以及需要多大的“力度”（秩）去微调。这一过程主要包含三个关键创新。

3.1 基于 SVD 的参数化

AdaLoRA 的第一步，是对 LoRA 的低秩分解形式进行了改进。它不再是使用两个简单的矩阵 $B \cdot A$，而是引入了经典的奇异值分解 (SVD) 思想来参数化更新矩阵 $\Delta W$：

$$ \Delta W = P \Lambda Q $$

在机器学习和信号处理中，SVD 是一种强大的矩阵分解技术，能将任意矩阵分解为三个矩阵的乘积：一个左奇异向量矩阵 $P$、一个对角矩阵 $\Lambda$ 和一个右奇异向量矩阵 $Q$。其中，对角线上的奇异值代表了数据中最重要的主成分。AdaLoRA 正是借鉴了这一思想。

这种参数化方式有两大好处：

避免了高昂的计算成本：它只是在形式上模拟了 SVD，在训练时 $P, \Lambda, Q$ 都是可训练的参数，并不需要对 $\Delta W$ 进行真正的、计算开销极大的 SVD 分解。
结构化的重要性：这种分解将 $\Delta W$ 的更新信息解耦为三个部分： $P$ 和 $Q$ 决定了更新的“方向”，而 $\Lambda$ 中的奇异值 $\lambda_i$ 则决定了在对应方向上的更新“幅度”。这使得我们可以通过调整奇异值的大小来直接控制每个“更新分量”的重要性，也即调整矩阵的秩。

为确保 $P$ 和 $Q$ 在训练中保持正交性（这是奇异向量的性质），AdaLoRA 还在训练损失中加入了一个正交正则化项，以保证分解的稳定性和有效性。

3.2 重要性评分与动态预算分配

有了 SVD 这种分解结构，AdaLoRA 接下来要解决的问题就是如何衡量每个“更新分量”的重要性？

它将每个奇异值和其对应的左右奇异向量组合成一个“三元组” $\mathcal{G}{k,i} = {P{k,\ast i}, \lambda_{k,i}, Q_{k,i \ast}}$。在训练过程中，AdaLoRA 会为每个三元组计算一个重要性分数 $S_{k,i}$。这个分数是基于对三元组中每个参数 $w$ 的重要性 $s(w)$ 进行聚合得到的。

参数 $w$ 的重要性 $s(w)$ 由两部分相乘得到，分别是平滑后的参数敏感度 (Sensitivity) $\bar{I}(w)$ 和不确定性 (Uncertainty) $\bar{U}(w)$。

参数敏感度 I：它被定义为参数自身大小与其梯度的乘积的绝对值，即 $I(w) = |w \cdot \nabla_w \mathcal{L}|$。其直观含义是：如果将这个参数 $w$ 置零，模型损失会发生多大的变化。敏感度越高，说明该参数对当前任务的性能影响越大。
平滑与不确定性 U：由于训练是分批次（mini-batch）进行的，单个批次计算出的梯度具有随机性，导致敏感度 I 的值会剧烈波动。为了得到更稳定的评估，AdaLoRA 引入了指数移动平均 (EMA) 来对敏感度和不确定性进行平滑处理：
$$ \bar{I}^{(t)}(w) = \beta_1 \bar{I}^{(t-1)}(w) + (1-\beta_1)I^{(t)}(w) $$$$ \bar{U}^{(t)}(w) = \beta_2 \bar{U}^{(t-1)}(w) + (1-\beta_2)|I^{(t)}(w) - \bar{I}^{(t)}(w)| $$
其中， $\bar{I}^{(t)}$ 是平滑后的敏感度，而 $\bar{U}^{(t)}$ 则量化了瞬时敏感度与平滑后值的偏差，即“不确定性”。一个参数如果不仅敏感度高，而且这种敏感性在训练中持续稳定出现（即不确定性低），那么它就更重要。

最终，单个三元组的重要性分数 $S_{k,i}$ 由其内部所有参数的重要性聚合而成：

$$ S_{k,i} = s(\lambda_{k,i}) + \frac{1}{d_1}\sum_{j=1}^{d_1}s(P_{k,ji}) + \frac{1}{d_2}\sum_{j=1}^{d_2}s(Q_{k,ij}) $$

其中 $d_1 = d,\ d_2 = k$（对应 $\Delta W\in\mathbb{R}^{d\times k}$）。

在计算出所有三元组的重要性分数后，AdaLoRA 会进行排序，并根据一个预设的参数预算（总秩），裁剪掉那些得分最低的三元组（即将它们对应的奇异值 $\lambda_i$ 置为 0），从而实现了参数的动态分配。

3.3 全局预算调度器与目标函数

为了让训练过程更加稳定和高效，AdaLoRA 的整体目标函数 L 包含了原始的损失函数 C 和我们前面提到的正交正则项 R：

$$ \mathcal{L}(\mathcal{P},\mathcal{E},\mathcal{Q}) = \mathcal{C}(\mathcal{P},\mathcal{E},\mathcal{Q}) + \gamma \sum_{k=1}^n R(P_k,Q_k) $$

同时，它还引入了全局预算调度器 (Global Budget Scheduler) 的策略。这里的“预算” $b(t)$，指的就是在训练的第 $t$ 步，模型总共保留的奇异值的数量。它由一个分段函数精确控制：

$$ b^{(t)} = \begin{cases} b^{(0)} & 0 \le t < t_i \\ b^{(T)} + (b^{(0)} - b^{(T)})\left(1 - \frac{t - t_i}{T - t_i - t_f}\right)^3 & t_i \le t < T-t_f \\ b^{(T)} & \text{otherwise} \end{cases} $$

这个调度策略包含三个阶段：

热身阶段 ($0 \le t < t_i$)：从一个比目标预算 $b^{(T)}$ 略高的初始预算 $b^{(0)}$ 开始训练，让模型有更充分的机会去“探索”所有参数的潜在重要性。
裁剪阶段 ($t_i \le t < T-t_f$)：按照一个三次方的调度曲线，逐步地裁剪掉重要性分数较低的奇异值，将预算平滑地降低到最终的目标值。
微调阶段：在预算分配基本稳定后，固定预算为 $b^{(T)}$（即锁定了最重要的参数），继续对模型进行微调直至收敛。

这种“先探索、后收敛”的策略，让模型有更充分的机会去发现哪些权重真正重要，从而做出更优的预算分配决策。最终，AdaLoRA 实现了在训练过程中对秩的动态调整和在不同模块间的智能分配。

在图 11-9 中可以看到，模型自动为 FFN 模块（ $W_{f1}, W_{f2}$ ）以及模型的高层（层级 6-12）分配了更高的秩（颜色更深），这与图 11-8 的实验观察完全吻合，证明了其自适应机制的有效性。

图 11-9 AdaLoRA 最终秩分配结果示意图

与 Adapter、SVD 主题模型的联系

与 Adapter Tuning：两者都采用了“高维 → 低维 → 高维”的瓶颈结构。但 Adapter 是作用于 激活值 的串行模块（增加推理延迟），而 LoRA/AdaLoRA 是作用于权重的并行支路（可合并，无额外延迟）。AdaLoRA 在结构上更高效。

与 SVD 主题模型：在第二章第三节的中学习中，我们提到过 SVD 在主题模型中被用于分解“词-文档”矩阵，以发现最重要的“语义主题”（数据层面的低秩近似）。而 AdaLoRA 则创造性地将 SVD 的思想用于分解“权重更新矩阵”，以找到最关键的“参数变化方向”（模型层面的低秩近似）。

论文的实验结果也表明，AdaLoRA 的自适应机制是有效的。它能自动发现前馈网络和模型顶层的权重矩阵更为重要，并为其分配更高的秩。此外，消融实验证明，即使不使用动态预算分配，仅仅将参数化形式从 $B \cdot A$ 替换为 $P \Lambda Q$，就已经能带来性能提升，说明 SVD 结构本身的优越性。这种自适应的机制，让 AdaLoRA 在相同的参数预算下，往往能达到比原始 LoRA 更好的性能，进一步提升了参数高效微调的水平。

四、QLoRA 参数压缩

LoRA 和 AdaLoRA 分别从“低秩近似”和“自适应秩分配”两个角度优化了微调过程，但它们都还有一个共同的前提，原始的、被冻结的大模型权重仍然是以较高的精度（如 FP16 或 BF16）加载到显存中的。对于动辄几百上千亿参数的模型来说，这部分权重本身就是一笔巨大的显存开销。

华盛顿大学的研究者们提出了 QLoRA (Quantized LoRA)，一种更高阶的参数高效微调方法 ³。它通过一系列压缩技术，实现了很不错的效果。在保持与 16-bit 全量微调相当性能的同时，成功将一个 65B（650 亿）参数模型的微调任务，压缩到了一块 48GB 显存的 GPU 上。如图 11-10 所示，与冻结 16-bit 模型的标准 LoRA 相比，QLoRA 更进一步，将基座模型量化为 4-bit。训练时，梯度会穿过被冻结的 4-bit 模型，反向传播到 16-bit 的适配器中，并只更新适配器参数。此外，它还引入了 分页优化器，在显存不足时，可以将优化器状态临时卸载到 CPU 内存，从而有效管理内存峰值。

图 11-10 全量微调、LoRA 与 QLoRA 的机制对比

基于这些创新，QLoRA 训练出的 Guanaco 模型系列，在 Vicuna 基准测试中甚至达到了 ChatGPT 99.3% 的性能水平，而这仅仅需要单张 GPU 训练 24 小时。QLoRA 的成功，主要归功于三方面的创新：4-bit NormalFloat (NF4)、双量化 (Double Quantization) 和分页优化器 (Paged Optimizers)。

4.1 4-bit NormalFloat 数据类型

量化是模型压缩领域的常用技术，通过用更少的信息位数（bit）来表示数值，从而减小模型体积和显存占用。然而，传统的量化方法（如均匀量化）在面对神经网络权重时会遇到一个难题：权重值的分布通常是零中心的正态分布，其中大部分值集中在 0 附近，而少量“离群值”的绝对值又非常大。均匀的量化策略无法很好地适应这种非均匀分布，导致较大的精度损失。

以一个典型的 8-bit 均匀量化为例，其量化过程由以下公式定义：

$$ \mathbf{X}^{\text{Int8}} = \text{round}\left(\frac{127}{\text{absmax}(\mathbf{X}^{\text{FP32}})} \mathbf{X}^{\text{FP32}}\right) = \text{round}(c^{\text{FP32}} \cdot \mathbf{X}^{\text{FP32}}) $$

这个过程依赖于 absmax 缩放，即找到张量中的绝对值最大值来计算缩放系数，也就是 量化常数 $c^{\text{FP32}}$。这种方法对离群值非常敏感，也是它的主要局限性。反量化则是其逆过程：

$$ \text{dequant}(c^{\text{FP32}}, \mathbf{X}^{\text{Int8}}) = \frac{\mathbf{X}^{\text{Int8}}}{c^{\text{FP32}}} \approx \mathbf{X}^{\text{FP32}} $$

理解这个基础过程，特别是“量化常数”的概念，对于我们后续理解 QLoRA 的双量化会有所帮助。

那么，为了解决传统量化方法的问题，QLoRA 提出了一种专门为正态分布权重设计的 4-bit 数据类型——NormalFloat (NF4)。它被证明是一种 信息论上最优 的数据类型，其设计哲学基于“分位数量化（Quantile Quantization）”。

分位数量化旨在让每个量化“桶”中，都包含相同数量的来自目标分布的值。这意味着，在数据密集的区域（如正态分布的中心），量化点会更密集；在数据稀疏的区域（如分布的两尾），量化点会更稀疏。NF4 的具体构建步骤如下：

确定理论分布：首先，构建一个理论上的标准正态分布 $N(0, 1)$。
计算分位数：为这个标准正态分布精确计算出 $2^4 = 16$ 个值，这些值能将该分布的累积密度函数（CDF）划分为 16 个等概率的区间。这些计算出的分位数点，就构成了 NF4 数据类型能够表示的所有数值。
归一化与量化：在对实际的模型权重（通常以 block 为单位处理）进行量化时，首先通过“绝对值最大缩放”（absmax rescaling）进行归一化。具体来说，就是找到当前权重块中的绝对值最大值，并计算出其缩放因子，这个因子就是该块的 量化常数，它通常是一个 32-bit 浮点数。将块内所有权重都乘以这个缩放因子，就可以将它们的数值范围归一化到 $[-1, 1]$ 区间。最后，将每一个归一化后的权重值，映射到离它最近的 NF4 分位数点上。

更精确地说，一个 k-bit 的 NormalFloat 数据类型（NFk）包含 $2^k$ 个量化点（$q_i$），其数值是通过以下公式估算的：

$$ q_i = \frac{1}{2} \left( Q_X\left(\frac{i}{2^k+1}\right) + Q_X\left(\frac{i+1}{2^k+1}\right) \right) $$

这里的 $Q_X(\cdot)$ 是标准正态分布 $N(0, 1)$ 的分位数函数（Quantile Function）。该函数的作用是，给定一个概率值 $p$（在 0 到 1 之间），它能返回在该概率点上的具体数值。公式中的 $\frac{i}{2^k+1}$ 和 $\frac{i+1}{2^k+1}$ 就是将累积概率分布划分为 $2^k+1$ 个等份的点。整个公式的含义是，第 $i$ 个量化点 $q_i$ 的值，被定义为标准正态分布中第 $i$ 个和第 $i+1$ 个等概率区间隔断点的中点。

通过这种方式，NF4 用极其有限的 4 个 bit，实现了对正态分布数据的高精度近似，最大程度地保留了原始权重中的信息，远优于传统的 4-bit 整数或浮点数量化。

4.2 双量化与分页优化器

除了开创性的 NF4 数据类型，QLoRA 还引入了另外两项技术来进一步压缩显存。

双量化 (Double Quantization, DQ)：上述量化过程需要为每一组（block）权重存储一个对应的“量化常数”（通常是 32-bit 的浮点数）。对于一个巨大的模型，这些量化常数累加起来也会占用相当大的显存。例如，对于一个 block size 为 64 的权重块，这些常数平均会给每个参数带来 $32 / 64 = 0.5$ bit 的额外开销。双量化的思想是，对这些量化常数本身，再进行一次量化。通过用 8-bit 浮点数对第一级量化常数进行第二级量化，可以将这部分额外开销从每参数 0.5 bit 大幅降低到约 0.127 bit。
分页优化器 (Paged Optimizers)：在微调过程中，梯度和优化器状态（如 Adam 算法中的动量和方差）会产生瞬时的显存峰值，尤其是在处理长序列时，很容易导致显存溢出（Out-of-Memory, OOM）。分页优化器借鉴了操作系统中“虚拟内存”的思想，它利用 NVIDIA 统一内存（Unified Memory） 的特性，在 GPU 显存不足时，能自动地、按需地将一部分优化器状态“分页”暂存到 CPU 内存中，待需要时再加载回 GPU。这极大地提高了训练过程的稳定性，避免了因偶然的显存峰值而导致的训练失败。

4.3 QLoRA 的工作流程

结合上述技术，QLoRA 的完整微调流程可以概括为一种“存算分离”的巧妙设计：它使用一种低精度的数据类型进行存储，但在计算时又恢复为高精度。整个流程可以分为以下几个步骤：

加载与量化 (存)：加载 16-bit 的预训练模型，然后将其权重量化为 4-bit 的 NF4 格式，并应用 双量化 进一步压缩量化常数。此时，巨大的基座模型以极低的显存占用被冻结在 GPU 中。
前向传播 (算)：在模型中插入 LoRA 适配器，其权重保持为 16-bit 精度（BF16）。当进行前向计算时，需要使用的基座模型权重会被 动态地反量化回 16-bit 的 BF16 格式。计算完成后，这些临时的 16-bit 权重立即被丢弃，显存得以释放。
反向传播与更新：在反向传播过程中，梯度只会通过冻结的 4-bit 模型反向传播到 16-bit 的 LoRA 适配器中，并只更新适配器的权重。如果出现显存峰值，分页优化器 会介入，防止 OOM 发生。

这个“存算分离”的前向传播过程，可以用以下公式进行精确地数学描述：

$$ \mathbf{Y}^{\text{BF16}} = \mathbf{X}^{\text{BF16}}\text{doubleDequant}(c_1^{\text{FP32}}, c_2^{\text{k-bit}}, \mathbf{W}^{\text{NF4}}) + \mathbf{X}^{\text{BF16}}\mathbf{L}_1^{\text{BF16}}\mathbf{L}_2^{\text{BF16}} $$

第一部分（主路）：doubleDequant 函数对应了步骤 2 中的核心操作，它将 4-bit 的权重 $\mathbf{W}^{\text{NF4}}$ 动态恢复为 16-bit，再与 16-bit 的输入 $\mathbf{X}^{\text{BF16}}$ 相乘。
第二部分（旁路）： $\mathbf{X}^{\text{BF16}}\mathbf{L}_1^{\text{BF16}}\mathbf{L}_2^{\text{BF16}}$ 则是标准的 LoRA 模块，其计算全程保持 16-bit 精度。

参考文献

参数高效微调（PEFT）技术综述

Wed, 25 Mar 2026 22:36:25 -0800

参数高效微调（PEFT）技术综述

从本章开始，我们将步入对大模型微调的学习。之所以将 PEFT 作为学习的起点，是因为它不仅是当前应对大模型训练高昂成本的主流解决方案，更代表了我们与超大模型互动和应用范式上的一次重要变革。理解 PEFT，是掌握如何在资源有限的条件下，高效、灵活地驾驭大模型强大能力的关键第一步。

一、大模型时代的“微调”困境

自 BERT 模型发布以来，“预训练-微调”（Pre-train and Fine-tune）的范式在自然语言处理领域取得了巨大成功。不过，当模型参数规模从 BERT 的数亿级别跃升至 GPT-3 的千亿级别时，传统的全量微调（Full Fine-Tuning）遇到了挑战：

高昂的训练成本：微调一个千亿参数的大模型需要巨大的计算资源（数百 GB 的显存）和时间成本，这对于绝大多数开发者和企业来说是遥不可及的。
巨大的存储压力：如果为每一个下游任务都保存一份完整的、千亿级别的模型副本，将导致难以承受的存储开销。
灾难性遗忘：在针对特定任务进行微调时，模型很可能会“忘记”在预训练阶段学到的海量通用知识，损害其泛化能力。
训练不稳定性：大模型的网络结构“又宽又深”，其训练过程对学习率等超参数极为敏感，很容易出现梯度消失/爆炸等问题，导致训练失败。

面对这些困境，研究者们迫切需要一种新的范式，既能有效利用大模型的强大能力，又能避免全量微调带来的高昂成本。

1.1 “提示”范式的兴起与局限

2020 年 GPT-3 论文带来了一种全新的、无需训练的范式——In-Context Learning ¹。研究者们惊喜地发现，在不调整任何模型参数的情况下，仅通过在输入中提供一些任务示例（即 提示 Prompt），就能引导大模型完成特定任务。这一发现迅速催生了“提示工程”（Prompt Engineering）的繁荣。用户通过组合各种关键词、权重和特殊符号，像“炼金术士”一样探索和“召唤”AI 的强大能力。这种人工设计的、离散的文本指令，我们称之为“硬提示”（Hard Prompt）。

但是，“硬提示”这种“刀耕火种”式的方法存在三个明显的局限。找到最优的提示词往往需要大量的试错和经验，过程繁琐且不稳定，充满了“玄学”；离散的文本提示在表达能力上存在上限，难以充分激发和精确控制大模型的潜力；而且在一个模型上精心设计的提示，换到另一个模型或另一种语言上，效果可能大打折扣。

1.2 参数高效微调的诞生

如何找到一种既能有效利用大模型能力，又不必承受全量微调高昂成本的方法？学术界和工业界开始探索一种全新的方法——参数高效微调（Parameter-Efficient Fine-Tuning, PEFT）。

核心思想：冻结（freeze） 预训练模型 99% 以上的参数，仅调整其中极小一部分（通常<1%）的参数，或者增加一些额外的“小参数”，从而以极低的成本让模型适应下游任务。

PEFT 的思想借鉴了计算机视觉领域的迁移学习（Transfer Learning）。在 CV 任务中，我们通常会冻结预训练模型（如 ResNet）负责提取通用特征的卷积层，仅微调后面的全连接层来适应新的分类任务。PEFT 将这一思想应用于 Transformer 架构，并发展出多条技术路线。

二、PEFT 技术发展脉络

2.1 Adapter Tuning

Adapter Tuning 是 PEFT 领域的开创性工作之一，由 Google 在 2019 年为 BERT 模型设计 ²。其思路是在 Transformer 的每个块中插入小型的“适配器”（Adapter）模块。如图 11-1 所示，左侧的 Transformer 层展示了 Adapter 模块是如何被集成进去的。Adapter 被插入到每个子层（注意力层和前馈网络）的内部，并与主干网络形成残差连接。在训练时，只有 Adapter 模块的参数会被更新。

图 11-1 Adapter Tuning 结构

图 11-1 的右侧展示了 Adapter 模块自身的结构，主要包括一个“降维”的全连接层（Feedforward down-project）将高维特征映射到低维空间，一个非线性激活函数（Nonlinearity），一个“升维”的全连接层（Feedforward up-project）再将特征映射回原始维度，以及一个贯穿该模块的残差连接将模块的输出与原始输入相加，保证信息流的稳定。通过这种“瓶颈式”的结构，Adapter 模块可以用极少的参数量来模拟特定任务的知识。这种方法不仅参数效率高、训练稳定，而且性能上能接近全量微调。相比全量微调，能够明显降低可训练参数与优化器状态占用。但由于各层插入了额外模块，训练时仍会带来一定的激活内存与算力开销，在千亿级规模且资源受限的条件下，工程实现更具挑战。

2.2 Prefix Tuning

2021 年，斯坦福大学的研究者提出了 Prefix Tuning，为 PEFT 开辟了一条全新的思路 ³。与 Adapter 在模型内部“动手术”不同，Prefix Tuning 选择在模型外部做文章，就像是给模型带上了一张“小抄”。图 11-2 是一个注解示例，揭示了 Prefix Tuning 的工作细节。该图分别展示了 Prefix Tuning 在自回归语言模型（上）和编码器-解码器模型（下）中的应用。它的核心机制在于：

前缀激活值（Prefix Activations）：图中 PREFIX 部分对应的激活值 $h_i$（其中 $i ∈ P_idx$）是从一个专门的可训练矩阵 $P_{\theta}$ 中提取的，这部分参数就是微调的对象。
模型计算的激活值: 而原始输入 $x$ 和输出 $y$ 对应的激活值，则是由冻结的 Transformer 模型正常计算得出的。

图 11-2 Prefix Tuning 注解示例

通过这种方式，模型在不改变原有参数的情况下，学会利用这些可控的“前缀”来引导后续内容的生成，从而适应新的任务。同时，为了达到更好的效果，Prefix Tuning 不仅在输入层添加前缀，还在 Transformer 的每一层都添加了对应的可学习 Prefix，并通过一个小型的前馈网络（MLP）来生成这些参数。这种方法的优点是具有较高的参数效率，仅需优化极少数 Prefix 参数而无需改动原模型；它对显存较为友好，因不更新原模型权重，训练时无需维护优化器状态，能显著降低显存与存储开销（尽管需为各层前缀的 K/V 额外预留显存）；而且，它的通用性强，在自回归模型（如 GPT-2）和编解码模型（如 T5/BART）上均取得了不错的效果。不过，Prefix Tuning 也存在一些缺点，直接优化 Prefix 向量比微调 Adapter 更困难，训练相对不稳定，对超参数和初始化较为敏感；同时，多数实现将前缀作为各层注意力的额外 K/V 记忆，其长度通常计入注意力配额，可能会减少可用的有效上下文窗口。

2.3 Prompt Tuning

Prefix Tuning 虽然强大，但其复杂的训练过程和在每一层都添加参数的设计，在实践中不够便捷。同年，Google 提出了 Prompt Tuning，可以看作是 Prefix Tuning 的一个简化版 ⁴。这种方法也被称为一种“软提示”。它的做法就是只在输入的 Embedding 层添加可学习的虚拟 Token（称为 Soft Prompt），不再干预 Transformer 的任何中间层。图 11-3 直观地展示了 Prompt Tuning 这种简化思路在实践中所带来的巨大差异，它不仅是参数效率的提升，更在使用范式上迈出了新的一步。

（1）左侧：全量微调：作为性能基准，这种方法遵循“一个任务，一个模型”的模式。针对每一个下游任务（Task A, B, C），都需要用其专属的数据集，对庞大的预训练模型（图中为 110 亿参数）进行完整的微调。最终会得到 N 个与原模型同样大小的任务专属模型副本，导致巨大的存储和部署开销。

（2）右侧：提示微调：它将 PEFT 的效率思想发挥得更加充分，将任务知识完全“外置”到一个轻量级的提示（Prompt）中。实践中可便利地实现混合任务批处理（Mixed-task Batch），便于共享同一冻结模型并提升训练吞吐；多任务训练并非 Prompt Tuning 所独有，但其实现较为简洁。我们可以通过一个具体的例子来理解这个过程：

定义任务：假设我们有三个不同的任务类型。任务 A 是情感分析，任务 B 是问答，任务 C 是 文章摘要。
准备数据：任务 A 的一条数据 a1 可能是一句影评：“这部电影拍得真不错！”。任务 B 的数据 b1 可能是一个问答对：“上下文：‘Datawhale是一个专注于AI与数据科学的开源组织。’ 问题：‘Datawhale是什么？’”。
拼接提示进行训练：在训练时，我们会为 a1 这条数据前，拼接上专门为“情感分析”任务学习的、可训练的 Soft Prompt A。这个 Soft Prompt A 并非一段人类可读的文本指令（如“请分析情感”），而是一组可通过反向传播优化的、连续的向量（Embeddings）。可以把它理解为一把能解锁大模型特定能力的“钥匙”：在训练时，它可能由“情感”、“正面”、“负面”等词的向量来初始化，并最终被模型自动微调成最优的、能够高效引导模型执行情感分析任务的“虚拟指令”。同理，为 b1 数据拼接上为“问答”任务学习的 Soft Prompt B。如图所示，这些来自不同任务、但都已拼接好各自 Soft Prompt 的数据，可以被组合成一个混合批次，然后一起送入同一个、完全冻结的大语言模型进行训练。模型通过反向传播，只会更新 Soft Prompt A 和 Soft Prompt B 的参数，而自身权重保持不变。

结果就是训练对象只是微型的任务提示（参数规模通常为万级，取决于提示长度与嵌入维度），而大模型（11B 参数）始终冻结并被所有任务共享。最终产出的是几个极小的提示文件，而非庞大的模型副本。这种非侵入式的方法实现起来极为简单，达到了很高的参数与存储效率，为实现单一模型服务多种下游任务提供了可能。

图 11-3 Model Tuning 与 Prompt Tuning 对比

此外，这篇论文最重要的发现是模型规模的缩放效应（The Power of Scale）。如图 11-4 所示，实验表明当模型规模较小（如 1 亿参数）时，Prompt Tuning 的效果（绿线）远不如传统的模型微调（红线和橙线）。但当模型规模超过 100 亿时，Prompt Tuning 的性能开始追平甚至超越全量微调。

图 11-4 Prompt Tuning 性能与模型规模的关系

这个发现说明只要模型“足够大”，我们就不再需要复杂的、侵入式的微调技术，仅通过学习一个微型的 Soft Prompt，就能让大模型涌现出强大的任务适应能力。然而，这也揭示了 Prompt Tuning 的局限，它的成功强依赖于模型的规模，在中小型模型上效果并不好。

三、P-Tuning v2

Prompt Tuning 虽然足够高效，但它的稳定性较差，且严重依赖超大模型的规模，这限制了其在更广泛场景中的应用。为了解决这些问题，由清华大学团队主导的 P-Tuning 系列工作，对软提示进行了深入优化，最终发展出了效果更强、更通用的 P-Tuning v2。

3.1 P-Tuning 的主要逻辑

为了理解 P-Tuning v2 的精髓，我们首先需要了解其前身 P-Tuning v1。v1 的主要目标是解决离散提示（Discrete Prompts） 的“不稳定性”问题 ⁵。

如图 11-5 所示，P-Tuning v1 将自己与传统的离散提示搜索方法进行了对比：

（a）离散提示搜索：这类方法试图在离散的文本空间中找到最优的提示词组合。这种搜索过程通常只能依赖离散的奖励信号，优化非常困难且不稳定，找到的解往往是次优的。
（b）P-Tuning：它提出，不应该在离散空间搜索，而应该在连续空间中进行优化。为此，P-Tuning v1 引入了一个关键组件——Prompt Encoder。它的逻辑是先定义一组可学习的、连续的伪提示（Pseudo Prompts），例如 $[P_0], …, [P_m]$，然后将这些伪提示作为输入，送入一个小型神经网络（如 LSTM）构成的 Prompt Encoder。Prompt Encoder 会将这些伪提示编码，捕捉它们之间的依赖关系，并生成最终作为大模型输入的任务相关向量 $h_0, …, h_m$。

图 11-5 离散提示搜索与 P-Tuning 对比

通过这种方式，Prompt Encoder 及其输入的伪提示，都可以通过反向传播进行端到端的优化。这从根本上改变了寻找最优提示的方式：从“人工试错”变成了可以通过“梯度下降”来自动化求解的数学问题，大幅提升了优化的稳定性和最终效果。我们可以结合上图的具体案例来理解一下。图中展示了一个首都预测任务，输入实体是 “Britain”（英国），目标输出是 “London”（伦敦）。

（1）传统离散提示：我们需要精心设计一个自然语言模板，例如 "The capital of Britain is [MASK]"。在这个模板中，"The", "capital", "of", "is" 这些词是固定的、离散的 Token。如果我们将模板换成 "Britain's capital city is [MASK]"，模型的输出效果可能会发生剧烈变化。这种对提示词的敏感性使得找到“最佳模板”变得很困难。

（2）P-Tuning：P-Tuning 放弃了寻找具体的离散单词，而是引入了一组连续的伪 Token（Pseudo Tokens），我们将其标记为 $[h_0, h_1, …, h_i]$。这时，输入给模型的序列可能变成了这样：

$$[h_0, h_1, ..., h_i], \text{"capital"}, \text{"Britain"}, [h_{i+1}, ..., h_m], \text{[MASK]}$$

这里的 $h$ 并不是词表里的某个具体单词，而是可训练的向量参数。在训练开始时，这些向量可能只是随机初始化的，或者用 “The capital of” 对应词向量进行初始化。随后在训练过程中，通过反向传播算法，这些 $h$ 向量会在连续的向量空间中不断调整数值。最终，它们会收敛为一组人类无法直接阅读（因为它们不对应具体的词），但对模型来说最优的提示特征。这组特征能比任何人工设计的离散句子更准确地激发模型输出 “London”。就好比我们不再试图用字典里有限的词汇去拼凑一句“咒语”，而是直接把钥匙（提示向量）打磨成最契合锁孔（模型参数）的形状，以此打开模型知识库的大门。

但是，P-Tuning v1 仍然存在两个问题。它对模型规模较为敏感（在较小模型上收益有限，而在更大模型上更稳定、更具优势），并且在一些复杂的自然语言理解（NLU）任务（特别是序列标注）上表现不佳。

3.2 P-Tuning v2 的演进

2021 年底问世的 P-Tuning v2，就是为了解决 v1 的局限性而设计的 ⁶。它博采众长，吸收了 Prefix Tuning 的思想，最终成为一种在不同模型规模、不同任务上都表现出色的通用 PEFT 方案。

我们可以对照图 11-6，来详细拆解这一演进过程。这张图对比了 P-Tuning v1（图 a）和 P-Tuning v2（图 b）在架构上的本质区别。

图 11-6 P-Tuning v1 与 P-Tuning v2 的结构对比

（1）P-Tuning v1 的瓶颈：注意图（a）中橙色的提示向量 $h_0, \dots, h_i$ 的位置。

浅层提示（Shallow Prompting）：提示向量仅被插入到输入层。这意味着提示信息必须经过 Transformer 所有层的层层传递，对模型深层行为的影响力非常有限。也就解释了为什么 P-Tuning v1 和 Prompt Tuning 这类技术在中小规模模型上效果远不如全量微调，往往只有在模型参数规模足够大（具备极强的内在通用能力）时，才能仅靠输入层的微调获得不错的效果。
任务局限（Verbalizer）：观察输出端的 Verbalizer。第一代技术为了利用预训练目标，强行将所有任务都包装成“完形填空”问题（Masked Language Modeling）。比如做情感分类，必须让模型预测 “good” 或 “bad” 这样的词，再映射回标签。这在处理分类任务时还能应付，但面对序列标注或抽取式阅读理解这种需要对每个 Token 进行细粒度分类的复杂任务时，设计 Verbalizer 就变得极其困难甚至不可能。

（2）P-Tuning v2 的演进：P-Tuning v2 针对上述两个痛点进行了改进，其结构如图（b）所示。

深层提示（Deep Prompting）：可以看到图（b）左侧的橙色箭头。提示向量不再只停留在输入层，而是被复制并独立注入到 Transformer 的每一层（Layer 1 Prompts, Layer 2 Prompts…）。这借鉴了 Prefix Tuning 的多层设计。现在，每一层的 Transformer 块都能直接接收到可学习的提示信息。相当于给模型开了“后门”，在每一层都进行直接引导。这种设计大幅增强了提示对模型的控制力。即使是小模型，深层提示也能发挥显著作用。
回归传统分类头（No Verbalizer）：我们来看看图（b）下方的输出端，它抛弃了复杂的 Verbalizer，直接换回了传统的 Class Label (with linear head)。既然我们已经通过 Deep Prompting 获得了足够的控制力，就不再需要强行迎合预训练任务了。对于分类或序列标注任务，我们可以直接在最后一层接一个简单的线性层（Linear Head），像传统微调（Fine-tuning）一样直接输出标签。通过这种机制，P-Tuning v2 瞬间拥有了处理复杂任务的能力。它不再受限于“填空题”的格式，可以轻松应用于各类复杂任务。

所以 P-Tuning v2 其实就是做了一个巧妙的融合，包含了 Prefix Tuning 的多层结构 + 传统微调的输出头 + Prompt Tuning 的轻量化。它既保留了 PEFT 参数高效的优势（仅需微调 0.1%~3% 的参数），又找回了全量微调在复杂任务上的通用性和在小模型上的稳定性。

参考文献

命名实体识别全流程

Wed, 25 Mar 2026 22:34:25 -0800

命名实体识别全流程

第一节命名实体识别概要

一、命名实体识别简介

在上一章节中，我们学习了如何对整个文本进行分类，这是一种对文本的宏观理解。现在，我们将从宏观走向微观，深入文本内部，学习如何精准识别出句子中的人名、地名等具有特定意义的词语或短语，这就是理论部分多次提到的 命名实体识别 (Named Entity Recognition, NER)。作为信息抽取、知识图谱构建、智能问答等众多高级应用的 关键环节，NER的目标是从非结构化文本中，精准地定位并分类出业务所关心的实体对象。

1.1 什么是命名实体？

简单来说，命名实体就是现实世界中事物的名称，是文本中那些指向特定对象、具有可识别性和唯一性的词语或短语。NER 的任务就是将这些“名字”找出来，并贴上预先定义好的标签。常见的实体类型包括：

人名 (PER): 姚明, 雷军
地名 (LOC): 北京, 故宫
组织机构名 (ORG): 阿里巴巴, 英伟达
产品名 (PROD): 黑神话：悟空, Blackwell 芯片
作品名 (WORK): 三体, 流浪地球
其他/杂项 (MISC): 含义依数据集而异（如民族、语言、事件等）
时间 (TIME): 昨天, 2025年

一个词是否被视为实体，以及它属于哪种实体，完全由业务场景的需求来决定。例如，在通用的场景下，“苹果”可能只是一个水果；但在数码产品的讨论中，它很可能需要被识别为一个“组织机构名”或“品牌名”。

不同数据集的实体类型定义差异较大（如 CoNLL 2003 仅含 PER/ORG/LOC/MISC；OntoNotes 5 则包含 PERSON、GPE、ORG、FAC、PRODUCT、EVENT、WORK_OF_ART 等更细类别）。实际项目应先明确标签集合。

1.2 NER 的应用价值

如果说 文本分类 是让计算机理解一段话的 主旨大意（比如判断情感是积极还是消极），那么 NER 就是让它更进一步，学会从文本中**“抓住重点”**，精准地找出谁（Who）、在哪（Where）、做了什么（What）等关键信息。这一能力使机器能够“抓住”文本中的关键信息，由此衍生出了更多 NLP 应用：

知识图谱构建: 从海量文本中抽取实体及其关系，是构建知识图谱的第一步。
信息抽取: 帮助机器从无结构的文本中，整理出结构化的信息。
搜索引擎优化: 通过识别查询中的实体，提供更精准、更结构化的搜索结果。
智能问答/对话系统: 理解用户意图，从用户的提问中抽取出关键实体，给出准确回答。

以医疗领域为例，NER可以从电子病历、医学文献等海量文本中，像专业医生一样抽取出关键信息，例如“II型糖尿病”等疾病诊断、“多饮”和“多食”等症状描述、“血糖检测”等检查方式，以及“二甲双胍口服”等治疗方案。通过这些抽取出的实体，可以高效地构建医疗知识图谱，为辅助诊断系统、临床研究等提供强大的数据支持。

二、命名实体识别的应用场景

2.1 智能搜索

每当你在搜索引擎中输入问题并立即得到结构化的“知识卡片”时，背后就有 NER 技术在默默工作。一个典型的流程如下：

（1）用户输入 Query：例如，“姚明的身高是多少？”。

（2）Query 理解：后台对 Query 进行分词、词性标注、纠错等基础处理，尝试“读懂”用户的真实意图。这种深度理解通常包括以下两步：

意图识别：判断 Query 属于哪种意图，例如“属性查询”、“汇率转换”、“单位换算”等。
命名实体识别

：根据识别出的意图，有针对性地抽取相应的实体。
- 属性查询 (“姚明的身高是多少？")：抽取“主体”（姚明）和“属性类型”（身高）。
- 汇率转换 (“50欧元等于多少日元”)：抽取“源汇率金额”(50)、“源汇率类型”(欧元)、“目标汇率类型”(日元)。
- 单位换算 (“5英尺等于多少厘米”)：抽取“源度量值”(5)、“源单位”(英尺)、“目标单位”(厘米)。

（3）信息检索：根据理解结果，从庞大的知识图谱或索引库中精准匹配答案。

（4）结果排序与呈现：将最相关的结果排序后，以结构化的方式优先呈现给用户。

2.2 聊天机器人与智能辅助诊断

在金融、医疗等特定领域的对话系统中，NER 同样扮演着重要角色。

（1）智能客服：在电商场景下，用户可能会用多种方式咨询同一个问题，例如：

“我的快递到哪了？”
“查一下我的订单”
“我买的东西发货了吗？”

系统无需理解每句话的细微差别，只要通过NER准确识别出用户的核心意图实体“物流信息”，结合用户信息，即可调用订单查询服务，返回最新的物流状态。

（2）智能辅助诊断系统：这是一个多技术融合场景。

计算机视觉: 负责处理CT、B超等影像图片，进行病灶识别。
自然语言处理

医生输入病人的文本描述（查体信息），NLP 模块会先通过

NER

从文本中抽取

症状

、

既往病史

等实体，然后进行

关系抽取/查询

，结合知识库构建类似以下的推理链路来辅助医生决策：
- [症状 A, 症状 B] => 建议检查 [项目 X]
- [项目 X 的结果] => 得出 [结论 Y]
- [症状 A, 症状 B, 结论 Y] => 高概率诊断 [疾病 Z]
- [疾病 Z, 既往病史 P] => 推荐 [疗法 Q]

三、NER的数据标注

与大多数深度学习任务一样，NER 模型也需要“吃”大量的数据才能学到知识。数据质量在很大程度上决定了模型性能的上限。标注的过程，本质上就是人类在手把手地“教”模型：在给定的文本中，哪些词或短语是什么类型的实体。一份高质量的标注数据集是训练出优秀模型的前提。为了获得高质量的标注数据，业界在实践中探索出了多种不同的标注方法，通常需要在质量成本与效率之间进行权衡：

人工标注: 这种方法质量高且可靠，但由于成本高、耗时长，是典型的人力密集型工作。在工具选择上，可以使用简单的 Excel，也可以开发专门的前端标注平台来提高效率。
大语言模型辅助标注: 先使用 LLM 对数据进行预标注，然后再由人工进行校对和修正。优点是可以显著提高标注效率，将人的角色从“从零创造”变为“审核修正”。不过，由于 LLM 的输出质量不稳定，所以仍需人工审核以保证数据最终的质量。
半监督/迭代式标注: 这是一种不断迭代优化的流程，首先人工标注一小部分数据来训练一个“学生”模型；接着用这个模型去预测大量未标注的数据，然后由人工检查和修正这些预测结果（这通常比从零标注快得多）；最后将修正后的数据加入训练集，训练出更强的“学生”模型，并重复以上过程。

四、命名实体识别的实现方法

实现命名实体识别的技术路径多种多样，从简单高效的规则匹配到复杂强大的深度学习模型。选择哪种方法，往往需要在项目初期的效果、成本和开发周期之间做出权衡。下面我们来探讨几种主流的实现方案。

4.1 基于字典和规则匹配

这是最传统和简单的方法。通过维护一个包含各种实体词汇的字典（例如，一个巨大的地名词典），然后在文本中进行字符串匹配。该方法优点是实现简单、速度快，对于特定、封闭领域的实体，准确率可能很高。缺点则是泛化能力差，无法识别字典外的新词（新出现的人名、公司名等），并且规则的维护成本极高。

4.2 序列标注模型

目前常见的 NER 实现方式[1]。它将 NER 任务转化为了一个 序列标注 问题——即为文本序列中的每一个 token（通常是字或词）打上一个预定义的标签。

4.2.1 方案一：Token 级别标签预测 (BMES/BIO)

这种方法为每个 Token 预测其在实体中扮演的角色，是序列标注最经典的思想。

标注体系:
- BMES: B(Begin), M(Middle), E(End), S(Single)
- BIO: B(Begin), I(Inside), O(Outside)
示例:
- 文本 (x): 西安的大雁塔门票多少钱
- BMES 体系 (y): B-LOC E-LOC O B-LOC M-LOC E-LOC B-ATTR E-ATTR O O O
- BIO 体系 (y): B-LOC I-LOC O B-LOC I-LOC I-LOC B-ATTR I-ATTR O O O
上例中，LOC 代表“地点”（Location），如“西安”和“大雁塔”；ATTR 代表“属性”（Attribute），此处指“门票”。
模型结构: Token Embedding层 -> 序列模型层 -> Token分类层
- Token Embedding/Encoder 表示: 可以是静态的 nn.Embedding；更常见的是直接使用预训练 Encoder（如 BERT/RoBERTa/DeBERTa 等）的上下文表示。
- Token Classify
  
  :
  - Softmax: 对每个Token独立分类，类别总数为 1 (非实体) + 实体类别数 * 4 (以BMES为例)。
  - CRF: 在 Softmax 基础上，额外学习标签之间的转移概率（如 B-LOC 后更可能是 M-LOC），对整个序列进行全局最优解码。对 RNN/CNN 等编码器通常有效；但在强大的预训练 Encoder（如 BERT）上收益在不少数据集上已变小，是否采用以实验为准。
缺点: 无法解决实体嵌套问题。例如，对于文本“他就读于北京大学”，这种方法很难同时识别出“北京”（地名）和“北京大学”（组织机构名）这两个存在包含关系的实体。一个更理想的嵌套实体示例如下：
1 2 3 4 5 6 7

{ "token": ["他", "就", "读", "于", "北", "京", "大", "学"], "span": [ {"type": "LOC", "start": 4, "end": 5}, {"type": "ORG", "start": 4, "end": 7} ] }

4.2.2 方案二：指针网络与片段网络

这类方法主要是为了解决实体嵌套问题，是当前处理复杂 NER 场景的主流方案之一。

片段网络[2][3]:
- 思路: “暴力美学”——枚举出文本中所有可能的连续片段，然后用一个分类器去判断每一个片段属于哪个实体类型（或是“非实体”）。
- 示例
  
  对于文本 “美式咖啡”，片段网络会进行如下操作：
  1. 枚举所有候选片段
    
    :
    - 长度为 1: 美, 式, 咖, 啡
    - 长度为 2: 美式, 式咖, 咖啡
    - 长度为 3: 美式咖, 式咖啡
    - 长度为 4: 美式咖啡
  2. 对每个片段进行分类
    
    :
    - 美式 -> PROD
    - 咖啡 -> PROD
    - 美式咖啡 -> PROD
    - (所有其他片段) -> O (非实体)
- 优点: 理论上可以解决实体嵌套问题。
- 缺点
  
  :
  1. 计算量大: 候选片段数量随文本长度平方级增长（如上例，4个字的文本就产生了10个候选片段）。
  2. 样本不均衡: 绝大多数片段都是非实体，导致正负样本严重失衡，训练困难。

指针网络[4]:

思路: 与其为每个 token 打一个固定的 BMES 标签，指针网络的思想是为每个 token 训练多个独立的二分类器，分别判断它是否是“某类实体的开头”以及“某类实体的结尾”。这种方式非常适合作为生成候选片段的第一步。

示例: 对于句子 “来一杯星巴克的美式咖啡”，如果我们想同时识别出“星巴克”（机构名）以及嵌套的“美式”、“咖啡”、“美式咖啡”（产品名），指针网络的输出会是这样：

Token	is_ORG_start	is_ORG_end	is_PROD_start	is_PROD_end	…
来	0	0	0	0	…
一	0	0	0	0	…
杯	0	0	0	0	…
星	1	0	0	0	…
巴	0	0	0	0	…
克	0	1	0	0	…
的	0	0	0	0	…
美	0	0	1	0	…
式	0	0	0	1	…
咖	0	0	1	0	…
啡	0	0	0	1	…

候选生成: 得到预测后，后处理程序会按实体类型分别进行“开头-结尾”配对：
- ORG 类型: 星 (start) + 克 (end) => 星巴克
- PROD 类型
  
  :
  - 美 (start) + 式 (end) => 美式
  - 咖 (start) + 啡 (end) => 咖啡
  - 美 (start) + 啡 (end) => 美式咖啡

通过这种“判断边界，再组合配对”的方式，指针网络巧妙地生成了所有可能的实体片段（包括嵌套的），为后续的分类环节提供了高质量的候选。

指针网络 + 片段网络[5]:
- 思路: 结合两者的长处，形成一个高效的两阶段流程。
1. 候选生成 (指针网络): 先使用指针网络高效地预测出所有可能的实体“开头”和“结尾”。
2. 候选组合: 将所有合法的“开头-结尾”配对，组合成候选实体片段。这个过程极大地减少了候选片段的数量，过滤掉了绝大多数无意义的组合。
3. 候选分类 (片段网络): 再使用片段网络对这些数量大大减少的 候选片段 进行分类。
- 优点: 既能解决嵌套问题，又有效降低了计算量，是解决复杂 NER 问题的有效方案。

4.2.3 方案三：基于分词的分类

思路: 将 NER 任务分解为两步：先调用一个现成的分词模型将文本切分成词语，然后对每个词语进行分类。
示例

:
- 原始文本: 西安的大雁塔门票多少钱
- 分词结果: 西安, 的, 大雁塔, 门票, 多少, 钱
- 分类结果: LOC, O, LOC, ATTR, O, O
缺点: 效果高度依赖上游分词模型的质量。如果分词出错（例如，将“大雁塔”错分成“大雁”和“塔”），实体识别基本不可能正确，可谓“一步错，步步错”。

4.3 生成式模型

随着大语言模型的发展，也可以将 NER 任务统一到生成框架下，通过精心设计的 Prompt 来“指令”模型完成任务。

思路: 将原始文本作为输入的一部分，让模型直接生成包含实体信息的结构化文本。
实现方式

核心思路是通过设计不同的输入输出格式（Prompt 工程），将 NER 任务转化为一个序列到序列（Seq2Seq）的生成任务。
- 方式一：标准 Encoder-Decoder 模式
  - 思路: 将原始文本喂给 Encoder，然后训练 Decoder 生成格式化的实体字符串。
  - 训练细节
    
    :
    - Encoder 输入 (x): 西安的大雁塔门票多少钱
    - Decoder 输入 (y_in): [START] 地点实体:西安[SEP]大雁塔[SEP];属性实体:门票
    - Decoder 目标 (y_out): 地点实体:西安[SEP]大雁塔[SEP];属性实体:门票 [END]
- 方式二：带“实体清单”提示的 Encoder-Decoder
  - 思路: 在原始文本后附加上下文提示（Context Prompting），明确告知模型需要关注哪些实体类型，以约束模型的输出空间，提高准确性。
  - Encoder 输入 (x): 西安的大雁塔门票多少钱 | 可选实体列表为:[地点实体, 属性实体, ...]
  - Decoder 目标 (y_out): 地点实体:西安[SEP]大雁塔[SEP];属性实体:门票 [END]
- 方式三：续写式生成 (Decoder-Only)
  - 思路: 将输入和输出拼接成一个完整的字符串，训练一个 GPT 风格的自回归模型来“续写”出实体部分。
  - 统一输入输出: 西安的大雁塔门票多少钱 | 可选实体列表为:[地点实体, 属性实体, ...] | 地点实体:西安[SEP]大雁塔[SEP];属性实体:门票 [END]
  - 训练: 将整段文本作为模型的输入进行训练，但 只计算 模型在预测“|”符号之后内容时的损失。前面的部分作为已知上下文，不计入损失。
  - 推理: 只提供前半部分（... | 之前的内容），让模型续写出后面的实体。
优缺点

:
- 优点
  
  :
  - 统一的生成框架: 将实体抽取任务完全转化为一个“文本到文本”的任务，单个模型就能直接生成包含复杂结构（如实体嵌套）的结果，输出形式非常灵活。
  - Few-shot/Zero-shot: 强大的LLMs能极大减少数据标注成本，在很多场景下无需训练就能获得不错的效果。
- 缺点
  
  :
  - 输出不稳定: 结果格式可能不统一，需要额外的后处理逻辑来解析。
  - 幻觉问题: 可能生成文本中不存在的实体。

五、项目实现思路

在第七章中，我们已经学习并实践了文本分类任务，并了解了 NLP 项目的通用流程。命名实体识别作为另一项 NLP 任务，其项目实现思路在宏观上遵循着相同的流程。在深入探讨具体代码实现之前，本章将再次遵循 数据处理 -> 模型构建 -> 训练、评估与持久化 这套标准流程，勾勒出一个标准 NER 项目的实现思路。

5.1 数据处理与增强

作为模型训练的起点，数据质量在很大程度上决定了模型性能的上限。

主要流程:
1. 分词/分Token: 将原始文本切分为Token序列。
2. Token与ID映射: 构建词表，将每个Token映射为一个唯一的数字ID。
3. 标签与ID映射: 构建标签表，将B-LOC, I-LOC等标签也映射为唯一的数字ID。
数据增强: 在标注数据有限的情况下，可以通过代码“创造”一些新的、合理的数据，以提升模型的泛化能力和鲁棒性。
- 实体替换
  
  准备同类型实体的词典（如地名词典、时间词典、天气现象词典），随机替换原始文本中的实体。
  - 示例: “查一下北京明天会下雨吗” -> “查一下深圳明天会下雨吗”。
  - 说明: 这种方式能教会模型学习 上下文语境，而不是死记硬背具体的实体词。
- 引入噪声
  
  模拟真实输入数据中的错误，随机地对文本进行微小改动。
  - 示例: “查一下北京明天会下雨吗” -> “查一下北京明天汇下雨吗” (同音字替换)。
- 随机遮盖
  
  :
  - 方法: 在训练时，随机地将文本中的一小部分（非实体）词元替换为<UNK>（未知）标记。
  - 示例: “查一下北京明天会下雨吗” -> “查一下北京<UNK>天会下雨吗”。
  - 目的: 这种方式会强制模型在部分信息缺失的情况下，更多地依赖上下文来做出判断，从而有效降低过拟合风险，提升模型的泛化能力。
- 拼音替换
  
  将少量中文词替换为拼音，模拟弱规范输入。
  - 示例: “查一下北京明天会下雨吗” -> “cha yi xia bei jing ming tian hui xia yu ma”。

在医疗等强约束领域做“实体替换”时，应确保替换后的样本不破坏实体间的真实语义关系（如疾病-症状-药物的搭配约束），否则可能引入反效果。

5.2 模型构建与迁移学习

NER 模型的经典组合一般是 Embedding层 + 动态词向量编码器 (如BERT, Bi-LSTM等) + Token分类层 (如全连接层+Softmax/CRF)。在输入与输出方面，模型输入形状通常为 [N, T] 的 Tensor（其中 N 是批次大小 Batch Size，T 是序列长度 Sequence Length），内容是 Token ID；模型输出形状则为 [N, T, num_classes] 的 Tensor，代表每个 Token 在所有 num_classes 个类别上的置信度得分。

在迁移学习与微调的实践中，通常使用在通用领域预训练好的模型作为初始化参数。常见的微调策略有四种：一是冻结参数，即将预训练模型参数冻结（requires_grad = False），只训练自己新增的分类层，速度快但效果可能受限；二是同等处理，将迁移过来的参数和新增的参数视为一体，使用相同的学习率和更新逻辑进行训练；三是差分学习率微调，为迁移过来的参数设置一个非常小的学习率进行“微调”，使其在保留通用知识的基础上向新任务靠近，同时为新增的参数设置一个正常的学习率使其能快速收敛；四是分层冻结/部分冻结，例如仅冻结 BERT 的前若干层，让后几层与分类头共同更新，这在算力有限或数据较少时常是较好的折中。

5.3 训练、评估与持久化

这是连接数据和模型，产出最终模型的重要循环。

训练循环: 迭代train_dataloader，在每个批次上执行模型前向传播、计算损失、反向传播和参数更新。
评估循环与指标

:
- 迭代eval_dataloader，计算模型在验证集上的性能。
- Token级别指标: 计算Token分类的准确率、F1值等，用于监控训练过程。
- 实体级别指标 (核心): 计算实体片段的精确率 (Precision)、召回率 (Recall) 和 F1值。这是衡量模型最终效果的核心标准。
标签序列 -> 实体片段解码要点

（以 BMES/BIO 为例）:
1. 从左到右扫描标签序列，遇到 B-T 开始一个新片段（类型 T）。
2. 在 BMES 中，M-T 继续片段，E-T 结束片段；S-T 表示单字实体；O 表示非实体。
3. 在 BIO 中，I-T 继续片段，遇到类型不一致或 O 时关闭当前片段。
4. 记录每个片段的 (start, end, type) 边界与类型，用于与标注集对齐计算 P/R/F1。
持久化: 在评估过程中，根据 实体级别 的评估指标结果（如验证集F1值达到新高），决定是否将当前模型的参数保存到磁盘。

第二节 NER 项目的数据处理

在上一节，我们简单了解了命名实体识别的任务定义、应用场景及主流实现方法。本节将正式进入编码阶段，从数据处理开始，逐步构建一个完整的 NER 项目。为了清晰地构建 NER 的处理流程，我们采用流程化的代码组织思路，将整个流程拆分为多个独立的脚本。

本章全部代码

一、数据处理流程总览

在 NLP 中，原始的文本和标注数据是无法直接被神经网络模型利用的。需要将这些原始数据转换成模型能够理解的、标准化的数字张量。那么，具体要转换成什么样？又该如何转换？这就是本节数据处理流程要解决的问题。

1.1 明确数据处理的目标

在设计之前，我们需要先明确最终的目标。对于一个命名实体识别任务，数据处理需要产出什么？

模型的输入 (X) 是什么？
- 它应该是一个整数张量，形状为 [batch_size, seq_len]。
- 其中 batch_size 是批次大小，seq_len 是序列长度（通常是批次内最长句子的长度）。
- 张量中的每一个数字，都代表原始句子中一个字符（Token）在词汇表里对应的唯一 ID。
模型的标签 (Y) 是什么？
- 它也应该是一个整数张量，形状与输入 X 完全相同，即 [batch_size, seq_len]。
- 其中的每一个数字，代表着对应位置字符的实体标签 ID（例如，B-bod 对应的 ID）。
如何实现从“文本”到“ID”的转换？
- 文本 -> Token ID：需要构建一个 “字符-ID” 的映射表，也就是词汇表 (Vocabulary)。
- 实体 -> 标签 ID：需要构建一个 “标签-ID” 的映射表。

1.2 数据格式解析

我们使用的是 CMeEE-V2（中文医学实体抽取）数据集。经过分析，该数据集采用的是标准的 JSON 数组 格式。

1.2.1 原始数据示例

打开 CMeEE-V2_train.json，可以看到文件内容是一个完整的 JSON 数组：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[
 ...,
 {
 "text": "（2）室上性心动过速可用常规抗心律失常药物控制，年龄小于5岁。",
 "entities": [
 {
 "start_idx": 3,
 "end_idx": 9,
 "type": "dis",
 "entity": "室上性心动过速"
 },
 {
 "start_idx": 14,
 "end_idx": 20,
 "type": "dru",
 "entity": "抗心律失常药物"
 }
 ]
 },
 ...
]

1.2.2 字段说明

text：原始文本字符串
entities

：实体标注列表，每个实体包含：
- start_idx：实体起始位置（包含）
- end_idx：实体结束位置（包含）
- type：实体类型（如 dis 疾病、dru 药物）
- entity：实体文本（用于验证）

索引的包含性

对于当前 data/ 目录下的数据，经实测：start_idx 与 end_idx 均为包含（闭区间）。实体应由 text[start_idx : end_idx + 1] 取得。例如：

文本："（2）室上性心动过速可用常规抗心律失常药物控制，年龄小于5岁。”

实体 “室上性心动过速”：start_idx=3, end_idx=9

实际字符：text[3:10] = “室上性心动过速”

所以，实体长度 = end_idx - start_idx + 1。

二、构建标签映射

目标：从原始数据中提取所有实体类型，然后基于 BMES 标注方案构建一个全局统一的“标签-ID”映射表。

2.1 加载数据

在处理任何数据之前，首要需要把它加载到内存里。

2.1.1 调试观察数据结构

开始的代码很简单，我们需要先读取文件并加载其内容。

1
2
3
4
5
6
7
8
9


import json

def collect_entity_types_from_file(file_path):
 with open(file_path, 'r', encoding='utf-8') as f:
 all_data = json.load(f) # 下断点

if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 collect_entity_types_from_file(train_file)

操作指引：

如 图 2.1 所示，本次调试过程分为三步：

设置断点：在代码行 all_data = json.load(f) 左侧的行号旁边单击，设置一个断点。
启动调试：点击 PyCharm 右上角的“Debug”按钮（绿色甲虫图标），以调试模式运行当前脚本。程序会自动执行到断点所在行并暂停，此时 all_data 变量还未被赋值。
单步执行 (Step Over)：点击调试控制台中的“Step Over”按钮。此操作会执行当前行代码。执行后，all_data 变量才会被成功赋值。

图 2.1: PyCharm 调试器观察数据结构

完成以上步骤后，可以在下方的“Debug”工具窗口中展开 all_data 变量，从而审查其内部结构。通过观察 图 2.1，可以得出结论：

all_data 是一个 list（列表）。
列表中的每一个元素都是一个 dict（字典），代表一条标注数据。
每个字典都包含 text 和 entities 两个键。

以上步骤以 PyCharm 为例，但其调试逻辑（设置断点、启动调试、单步执行）在 VS Code 等其他主流 IDE 中是完全通用的。

刚刚我们通过断点调试，清楚地看到了 all_data 的内部结构，这为编写后续的遍历代码提供了依据。请记住这种方法，后续学习中如果遇到任何不理解的代码或不清楚的变量，都可以使用同样的方式：“哪里不会 D 哪里😉”。

2.1.2 提取实体类型

既然已经清楚了数据结构，现在要做的就是遍历这个列表，从每个字典中提取出我们真正关心的信息——实体类型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


import json

def collect_entity_types_from_file(file_path):
 types = set()
 with open(file_path, 'r', encoding='utf-8') as f:
 all_data = json.load(f)
 for data in all_data:
 # 遍历实体列表，提取 'type' 字段
 for entity in data['entities']:
 types.add(entity['type'])
 return types

if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 entity_types = collect_entity_types_from_file(train_file)
 print(f"从 {train_file} 中提取的实体类型: {entity_types}")

运行结果：

1

从 ./data/CMeEE-V2_train.json 中提取的实体类型: {'dru', 'dep', 'dis', 'bod', 'mic', 'equ', 'sym', 'pro', 'ite'}

2.2 处理多个文件并保证顺序

下一步需要完成两件事：

处理所有的数据文件（训练集、验证集），以确保包含了全部的实体类型。
对提取出的实体类型进行排序，以保证每次生成的标签 ID 映射都是完全一致的。

基于此，对代码进行扩展：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# (collect_entity_types_from_file 函数保持不变，此处省略)
# ...

def generate_tag_map(data_files):
 all_entity_types = set()
 for file_path in data_files:
 types_in_file = collect_entity_types_from_file(file_path)
 all_entity_types.update(types_in_file)

 # 排序，保证每次运行结果一致
 sorted_types = sorted(list(all_entity_types))

 # 后续将在这里构建 BMES 映射
 # ...

if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 dev_file = './data/CMeEE-V2_dev.json'

 generate_tag_map(data_files=[train_file, dev_file])

2.3 构建 BMES 标签映射

有了排序后的实体类型列表，就可以构建最终的 tag_to_id 映射字典了。规则如下：

非实体标签 'O' 的 ID 为 0。
对于每一种实体类型（如 dis），都生成 B-dis, M-dis, E-dis, S-dis 四种标签，并按顺序赋予递增的 ID。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# ... (在 generate_tag_map 函数内部) ...

# ... (汇总和排序逻辑) ...
sorted_types = sorted(list(all_entity_types))

# 构建 BMES 标签映射
tag_to_id = {'O': 0} # 'O' 代表非实体
for entity_type in sorted_types:
 for prefix in ['B', 'M', 'E', 'S']:
 tag_name = f"{prefix}-{entity_type}"
 tag_to_id[tag_name] = len(tag_to_id)

print(f"\n已生成 {len(tag_to_id)} 个标签映射。")

2.4 封装与保存

为了让这个映射表能够被其他脚本方便地使用，需要将它保存成一个 JSON 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


def save_json(data, file_path):
 os.makedirs(os.path.dirname(file_path), exist_ok=True)
 with open(file_path, 'w', encoding='utf-8') as f:
 json.dump(data, f, ensure_ascii=False, indent=4)

def collect_entity_types_from_file(file_path):
 # ... (函数已在前面定义，此处省略)

def generate_tag_map(data_files, output_file): # 添加 output_file 参数
 # 1. 汇总所有实体类型 ...

 # 2. 排序以保证映射一致性 ...

 # 3. 构建 BMES 标签映射 ...

 # 4. 保存映射文件
 save_json(tag_to_id, output_file)
 print(f"标签映射已保存至: {output_file}")

if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 dev_file = './data/CMeEE-V2_dev.json'
 output_path = './data/categories.json'
 generate_tag_map(data_files=[train_file, dev_file], output_file=output_path)

通过这样一步步的迭代和完善，我们从一个基础的思路，最终构建出了一个可复用的预处理脚本。

2.5 运行结果

执行最终的 01_build_category.py 脚本，会生成 categories.json 文件，内容如下（部分展示）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 "O": 0,
 "B-bod": 1,
 "M-bod": 2,
 "E-bod": 3,
 "S-bod": 4,
 "B-dep": 5,
 "M-dep": 6,
 "E-dep": 7,
 "S-dep": 8,
 "B-dis": 9,
 "M-dis": 10,
 "E-dis": 11,
 "S-dis": 12,
 ...
}

三、构建词汇表

有了标签映射，我们还需要创建一个“字符-ID”的映射表（即词汇表），为后续将文本转换为数字序列做准备。

3.1 统计所有字符

目前的首要任务是获取数据中出现的所有字符。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from collections import Counter
import json

def create_char_vocab(data_files):
 char_counts = Counter()
 with open(data_files, 'r', encoding='utf-8') as f:
 all_data = json.load(f)
 for data in all_data:
 char_counts.update(list(data['text']))

 print(f"初步统计的字符种类数: {len(char_counts)}")

if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 create_char_vocab(train_file)

3.2 文本规范化

在检查初步统计的字符时，会发现一个问题。数据中可能同时包含 全角字符（如 ，，（）和 半角字符（如 ,，(）。它们在语义上相同，但会被视为两个不同的 token（如图 2.2 所示）。

图 2.2: 全角/半角字符混用

为了减小词汇表规模并提升模型泛化能力，可以将它们统一。这里我们直接将所有全角字符转换为半角字符。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def normalize_text(text):
 """
 规范化文本
 """
 full_width = "０１２３４５６７８９ＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＱＲＳＴＵＶＷＸＹＺａｂｃｄｅｆｇｈｉｊｋｌｍｎｏｐｑｒｓｔｕｖｗｘｙｚ！＃＄％＆’（）＊＋，－．／：；＜＝＞？＠［＼］＾＿｀｛｜｝～＂"
 half_width = r"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!#$%&'" + r'()*+,-./:;<=>?@[\]^_`{|}~".'
 mapping = str.maketrans(full_width, half_width)
 return text.translate(mapping)

def create_char_vocab(data_files):
 char_counts = Counter()
 with open(data_files, 'r', encoding='utf-8') as f:
 all_data = json.load(f)
 for data in all_data:
 # 在统计前先进行规范化
 normalized_text = normalize_text(data['text'])
 char_counts.update(list(normalized_text))

 print(f"初步统计的字符种类数: {len(char_counts)}")

3.3 过滤、排序与添加特殊符

接下来，进行收尾工作：

过滤低频词：可以设定一个阈值 min_freq，移除出现次数过少的罕见字，以进一步精简词汇表。
排序：与标签映射一样，对最终的字符列表进行排序，确保每次生成的词汇表文件内容完全一致。
添加特殊 Token：在列表的最前面，加入两个特殊的标记：<PAD>（用于后续对齐序列）和 <UNK>（用于表示词汇表中不存在的未知字符）。

3.4 封装与保存

将以上所有逻辑整合，并加入保存文件的功能，便得到了最终的脚本。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


 # ... 

def save_json(data, file_path):
 # ... (函数与上个脚本中相同，此处省略)

def normalize_text(text):
 # ... (函数已在前面定义，此处省略)

def create_char_vocab(data_files, output_file, min_freq=1):
 # 1. 统计规范化后的字符频率
 char_counts = Counter()
 for file_path in data_files:
 with open(file_path, 'r', encoding='utf-8') as f:
 all_data = json.load(f)
 for data in all_data:
 text = normalize_text(data['text'])
 char_counts.update(list(text))

 # 2. 过滤低频词
 frequent_chars = [char for char, count in char_counts.items() if count >= min_freq]

 # 3. 排序
 frequent_chars.sort()

 # 4. 添加特殊标记
 special_tokens = ["<PAD>", "<UNK>"]
 final_vocab_list = special_tokens + frequent_chars

 print(f"词汇表大小 (min_freq={min_freq}): {len(final_vocab_list)}")

 # 5. 保存词汇表
 save_json(final_vocab_list, output_file)
 print(f"词汇表已保存至: {output_file}")


if __name__ == '__main__':
 train_file = './data/CMeEE-V2_train.json'
 dev_file = './data/CMeEE-V2_dev.json'
 output_path = './data/vocabulary.json'
 create_char_vocab(data_files=[train_file, dev_file], output_file=output_path, min_freq=1)

四、封装数据加载器

现在有了标签映射和词汇表，最后一步就是构建一个可复用的 DataLoader，将文本数据高效地转换成 PyTorch 模型能够理解的格式。直接用循环读取数据并手动转换是低效且不灵活的。一个合格的数据加载器需要解决自动批量化、序列填充、数据转换和随机化这几个问题。

所以我们将整个流程拆分为以下几个步骤来逐步实现：

步骤一：封装 Vocabulary 类，专门负责 Token 和 ID 之间的转换。
步骤二：创建 NerDataset，继承自 PyTorch 的 Dataset，负责处理单个数据样本的转换。
步骤三：定义 collate_fn 函数，负责将多个样本打包、填充成一个 batch。
步骤四：整合所有组件，创建一个 DataLoader 实例并进行测试。

4.1 封装 Vocabulary 类

第一步，创建一个 Vocabulary 类来加载之前生成的 vocabulary.json，并提供方便的查询接口。这个类主要负责 Token 和 ID 之间的转换。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import json

class Vocabulary:
 """
 负责管理词汇表和 token 到 id 的映射
 """
 def __init__(self, vocab_path):
 with open(vocab_path, 'r', encoding='utf-8') as f:
 self.tokens = json.load(f)
 self.token_to_id = {token: i for i, token in enumerate(self.tokens)}
 self.pad_id = self.token_to_id['<PAD>']
 self.unk_id = self.token_to_id['<UNK>']

 def __len__(self):
 return len(self.tokens)

 def convert_tokens_to_ids(self, tokens):
 return [self.token_to_id.get(token, self.unk_id) for token in tokens]

if __name__ == '__main__':
 vocab_file = './data/vocabulary.json'
 vocabulary = Vocabulary(vocab_path=vocab_file)
 print(f"词汇表大小: {len(vocabulary)}")

4.2 创建 NerDataset

现在要创建的是核心的数据集类，它继承了 torch.utils.data.Dataset。负责将单条原始数据转换为模型所需的 token_ids 和 label_ids。可以把它想象成一个数据处理的“单件工厂”，DataLoader 每次需要数据时，都会向这个工厂索要一件（__getitem__）加工好的产品。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


# ... 
from torch.utils.data import Dataset
# ... (需要 normalize_text 函数) ...

class Vocabulary:
 # ... (类已在前面定义，此处省略)

class NerDataset(Dataset):
 def __init__(self, data_path, vocab: Vocabulary, tag_map: dict):
 # 一次性将整个 JSON 文件（一个大列表）读入内存
 self.vocab = vocab
 self.tag_to_id = tag_map
 with open(data_path, 'r', encoding='utf-8') as f:
 self.records = json.load(f)

 def __len__(self):
 return len(self.records)

 def __getitem__(self, idx):
 # 1. 根据索引获取原始记录
 record = self.records[idx]
 text = normalize_text(record['text'])
 tokens = list(text)

 # 2. 将文本字符转换为 token_ids
 token_ids = self.vocab.convert_tokens_to_ids(tokens)

 # 3. 生成与文本等长的 tag 序列，默认为 'O'
 tags = ['O'] * len(tokens)

 # 4. 遍历实体列表，用 BMES 标签覆盖默认的 'O'
 for entity in record.get('entities', []):
 entity_type = entity['type']
 start = entity['start_idx']
 end = entity['end_idx'] # 闭区间结束索引

 if end >= len(tokens): continue

 if start == end:
 tags[start] = f'S-{entity_type}' # 单字实体
 else:
 tags[start] = f'B-{entity_type}' # 实体开始
 tags[end] = f'E-{entity_type}' # 实体结束
 for i in range(start + 1, end):
 tags[i] = f'M-{entity_type}' # 实体中间

 # 5. 将 BMES 标签字符串序列转换为 label_ids
 label_ids = [self.tag_to_id[tag] for tag in tags]

 # 6. 返回包含两个 Tensor 的字典
 return {
 "token_ids": torch.tensor(token_ids, dtype=torch.long),
 "label_ids": torch.tensor(label_ids, dtype=torch.long)
 }

if __name__ == '__main__':
 # 为测试 NerDataProcessor 准备所需的 vocab 和 tag_map
 vocab_file = './data/vocabulary.json'
 categories_file = './data/categories.json'
 train_file = './data/CMeEE-V2_train.json'

 vocabulary = Vocabulary(vocab_path=vocab_file)
 with open(categories_file, 'r', encoding='utf-8') as f:
 tag_map = json.load(f)

 # 创建数据集实例
 train_dataset = NerDataset(train_file, vocabulary, tag_map)
 print(f"数据集大小: {len(train_dataset)}")

4.3 整合为 DataLoader

最后，定义 create_ner_dataloader 函数。它接收 Dataset 实例，并将其封装成一个 DataLoader。在 NLP 任务中，由于每个样本（句子）的长度都不同，所以不能直接让 DataLoader 使用默认的方式打包数据，否则会因序列长度不一而报错。因此，我们需要提供一个自定义的 collate_fn (校对函数) 来解决这个问题。

collate_fn 的主要任务，就是将从 Dataset 中取出的、由多条数据组成的列表（batch），“聚合”成一个统一的、规整的批次。在当前任务中，它主要负责两件事：

动态填充 (Padding)：找到当前批次中最长的序列，并将这个批次内的所有样本都填充到这个最大长度。
生成 Attention Mask：创建一个 mask 矩阵，用来标记哪些是真实的 Token (值为 1)，哪些是填充的 Token (值为 0)。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# ... 
from torch.utils.data import Dataset, DataLoader
from torch.nn.utils.rnn import pad_sequence
# ... (省略前面所有的类和函数定义) ...

def create_ner_dataloader(data_path, vocab, tag_map, batch_size, shuffle=False):
 dataset = NerDataset(data_path, vocab, tag_map)

 def collate_batch(batch):
 token_ids_list = [item['token_ids'] for item in batch]
 label_ids_list = [item['label_ids'] for item in batch]

 padded_token_ids = pad_sequence(token_ids_list, batch_first=True, padding_value=vocab.pad_id)
 padded_label_ids = pad_sequence(label_ids_list, batch_first=True, padding_value=-100)
 attention_mask = (padded_token_ids != vocab.pad_id).long()

 return {
 "token_ids": padded_token_ids,
 "label_ids": padded_label_ids,
 "attention_mask": attention_mask
 }

 return DataLoader(
 dataset,
 batch_size=batch_size,
 shuffle=shuffle,
 collate_fn=collate_batch
 )

if __name__ == '__main__':
 # 文件路径
 train_file = './data/CMeEE-V2_train.json'
 vocab_file = './data/vocabulary.json'
 categories_file = './data/categories.json'

 # 1. 加载资源
 vocabulary = Vocabulary(vocab_path=vocab_file)
 with open(categories_file, 'r', encoding='utf-8') as f:
 tag_map = json.load(f)

 # 2. 创建 DataLoader
 train_loader = create_ner_dataloader(
 data_path=train_file,
 vocab=vocabulary,
 tag_map=tag_map,
 batch_size=4,
 shuffle=True
 )

 # 3. 验证一个批次的数据
 batch = next(iter(train_loader))

 print("\n--- DataLoader 输出验证 ---")
 print(f" Token IDs shape: {batch['token_ids'].shape}")
 print(f" Label IDs shape: {batch['label_ids'].shape}")
 print(f" Attention Mask shape: {batch['attention_mask'].shape}")

torch.utils.data.DataLoader 是 PyTorch 的核心数据加载工具，它像一个高度自动化的“数据供应管道”。将 NerDataProcessor 实例（dataset）作为数据源传入，并配置了几个关键参数：

batch_size：定义了每个批次包含多少样本。
shuffle=True：使得加载器在每个 epoch 开始时都随机打乱数据顺序，能有效提升泛化能力。
collate_fn：这是最关键的参数，它指定了如何将 batch_size 个单独的样本“校对”和“打包”成一个规整的批次。传入的 collate_batch 函数在这里完成了动态填充和 attention_mask 的创建工作。

为什么 tag_ids 的填充值是 -100？

这是一个 PyTorch 中的惯例。在计算损失时，我们不希望填充位置的标签对最终的损失值和梯度产生影响。PyTorch 的交叉熵损失函数 torch.nn.CrossEntropyLoss 中有一个参数 ignore_index，它的默认值恰好是 -100。

当损失函数看到标签值为 -100 时，会自动“忽略”这个位置，不计算它的损失。

第三节模型构建、训练与推理

书接上回，我们已经完成了 NER 项目的数据处理工作，包括构建标签映射、词汇表以及一个功能完备的 DataLoader。本节将聚焦于如何利用 PyTorch 构建一个序列标注模型，并进一步封装一个可复用的训练流程，最终实现模型的训练、评估与推理。

一、模型结构设计

正如第一节所介绍，NER 任务本质上是一个 序列标注 问题——为输入序列中的每一个 Token 预测一个对应的标签。基于此，可以设计一个有效的模型结构，它主要由三个核心部分组成：

Token Embedding 层
- 作用：将输入的 token_ids（一串数字）转换为初始的词向量。
- 实现：通常使用 torch.nn.Embedding 层。它就像一个可学习的、巨大的查询表，每个 token_id 对应表中的一行（一个向量）。这些向量在训练开始时随机初始化，并随着模型训练过程不断优化。这个阶段产出的其实就是 静态词向量，因为它不考虑上下文，同一个字在任何句子中都对应同一个向量。
动态特征提取层
- 作用：让模型理解上下文，生成包含上下文特征信息的 动态词向量。由于静态词向量无法区分同一个词在不同上下文中的含义，所以需要一个 Encoder 来融合上下文信息，从而生成更能体现语义的动态词向量。
- 实现：循环神经网络 (RNN) 及其变体（如 LSTM, GRU）是处理序列数据的经典选择。我们可以使用 双向 GRU (Bi-GRU)，它能够同时从左到右和从右到左两个方向捕捉序列信息，从而更全面地理解每个 Token 的上下文。当然，也可以使用其他更强大的模型，如 BERT，来作为特征提取器。
分类决策层
- 作用：基于包含上下文信息的动态词向量，为每个 Token 预测其最终的实体标签（如 B-dis, O 等）。
- 实现：通常使用一个简单的全连接层 (torch.nn.Linear)。它将 Encoder 输出的动态词向量从 hidden_size 维度映射到 num_classes（标签总数）维度，得到的输出即为每个 Token 在所有标签上的置信度得分。

整个模型本质上是一个 Token 分类模型：接收 Token 序列，并为其中的每一个 Token 输出一个分类结果。

二、构建 PyTorch 模型

编写模型代码之前，先来回顾一下 DataLoader 输出的数据。如下图所示，经过 collate_fn 处理后，每个批次（Batch）的数据都包含了三个 torch.Tensor：token_ids、label_ids 和 attention_mask。

其中，token_ids 是模型最直接的输入，它是一个 torch.int64 类型的张量，代表了文本序列转换后的 Token 索引。

图 3.1: 数据加载器输出示例

2.1 输入与输出

为了在代码层面更清晰地展示这些张量，我们直接复制如图 3.1 所示的真实数据片段。这有助于在正式实现模型前，先通过这组数据核对输入/输出的维度与取值约定（例如 -100 表示忽略位置）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import torch

if __name__ == '__main__':

 token_ids = torch.tensor([
 [210, 18, 871, 147, 0, 0, 0, 0],
 [922, 2962, 842, 210, 18, 871, 147, 0]
 ], dtype=torch.int64)

 # attention_mask 标记哪些是真实 token (1) 哪些是填充 (0)
 attention_mask = torch.tensor([
 [1, 1, 1, 1, 0, 0, 0, 0],
 [1, 1, 1, 1, 1, 1, 1, 0]
 ], dtype=torch.int64)

 label_ids = torch.tensor([
 [0, 0, 0, 0, -100, -100, -100, -100],
 [0, 0, 0, 0, 0, 0, 0, -100]
 ], dtype=torch.int64)

从上面的示例中可以知道：

输入：模型需要接收两个参数，token_ids 和 attention_mask。
输出：模型的输出 logits 是一个三维张量，形状为 [batch_size, seq_len, num_tags]。

2.2 基础模型框架

目标明确后，就可以开始搭建模型了。先从一个最基础的单向 GRU 模型 GRUNerNetWork 开始。它包含 __init__ 构造函数和 forward 前向传播方法。为了构建一个更强大、更灵活的深度模型，这里采用 nn.ModuleList 来显式地堆叠多个 GRU 层。这种做法不仅让网络结构更清晰，还允许我们在层与层之间轻松地加入残差连接，这对于训练深度网络很重要。

nn.ModuleList vs nn.Sequential

在 PyTorch 中，nn.ModuleList 和 nn.Sequential 都是用来容纳多个子模块的容器，但它们的设计思想和使用场景不同：

nn.Sequential：像一个自动化的流水线，数据会自动按顺序流过每一层。适用于简单的线性堆叠，但无法实现层间的复杂交互。

nn.ModuleList：更像一个普通的 Python 列表，只负责存储模块，而不会自动执行它们。你需要在 forward 方法中手动编写循环来调用每一层，所以可以在层与层之间加入自定义逻辑（如残差连接）。

对于这种情况，我们还需要做一个小的设计：将词向量的维度与 GRU 的隐状态维度 hidden_size 设置为相同的值，这样残差连接（即两个张量相加）才能顺利进行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


import torch.nn as nn
import torch.nn.utils.rnn as rnn

class GRUNerNetWork(nn.Module):
 def __init__(self, vocab_size, hidden_size, num_tags, num_gru_layers=1):
 super().__init__()
 # 1. Token Embedding 层
 # 为了方便进行残差连接，embedding_dim 直接等于 hidden_size
 self.embedding = nn.Embedding(vocab_size, hidden_size)

 # 2. 使用 ModuleList 构建多层单向 GRU
 self.gru_layers = nn.ModuleList()
 for _ in range(num_gru_layers):
 self.gru_layers.append(
 nn.GRU(
 input_size=hidden_size, # 输入维度统一为 hidden_size
 hidden_size=hidden_size,
 num_layers=1,
 batch_first=True,
 bidirectional=False
 )
 )

 # 3. 分类决策层
 self.classifier = nn.Linear(hidden_size, num_tags)

 def forward(self, token_ids, attention_mask=None):
 # [batch_size, seq_len] -> [batch_size, seq_len, hidden_size]
 embedded_text = self.embedding(token_ids)

 current_input = embedded_text
 for gru_layer in self.gru_layers:
 gru_output, _ = gru_layer(current_input)
 # 添加残差连接
 current_input = gru_output + current_input

 logits = self.classifier(current_input)

 return logits

if __name__ == '__main__':
 # ... (数据构建) ...

 # 实例化模型
 model = GRUNerNetWork(
 vocab_size=10000,
 hidden_size=128,
 num_tags=37,
 num_gru_layers=2
 )

 # 3. 执行前向传播
 logits = model(token_ids=token_ids)

 # 4. 构造损失函数
 loss_fn = nn.CrossEntropyLoss(ignore_index=-100, reduction='none')

 # 5. 计算损失
 # CrossEntropyLoss 要求类别维度在前，所以需要交换最后两个维度
 # [batch, seq_len, num_tags] -> [batch, num_tags, seq_len]
 permuted_logits = torch.permute(logits, dims=(0, 2, 1))
 loss = loss_fn(permuted_logits, label_ids)

 # 6. 打印结果
 print(f"Logits shape: {logits.shape}")
 print(f"Loss shape: {loss.shape}")
 print("\n每个 Token 的损失:")
 print(loss)

运行结果：

1
2
3
4
5
6
7


Logits shape: torch.Size([2, 8, 10])
Loss shape: torch.Size([2, 8])

每个 Token 的损失:
tensor([[2.3364, 2.2961, 2.3879, 2.3275, 0.0000, 0.0000, 0.0000, 0.0000],
 [2.2855, 2.3020, 2.2478, 2.3787, 2.2882, 2.3392, 2.3553, 0.0000]],
 grad_fn=<ViewBackward0>)

这段输出说明：

维度正确：模型的输出 logits 维度为 [2, 8, 10]，与 [batch_size, seq_len, num_tags] 对应。
损失形状正确：由于设置了 reduction='none'，损失张量的形状 [2, 8] 与 label_ids 一致，返回了每个 Token 各自的损失。
ignore_index 生效：可以看到 label_ids 中值为 -100 的填充位置，其对应的损失值为 0。这证明损失函数成功忽略了这些填充位，避免了无效信息对模型训练的干扰。

你可能会注意到，在 GRUNerNetWork 的 forward 方法中，并没有使用 attention_mask 来处理填充。那为什么模型还能正常工作？

这是 单向 GRU 的计算特性 和 损失函数的 ignore_index 机制 共同作用的结果：

单向计算：GRU 从左到右处理序列，在计算一个真实 Token（如 w_i）的特征时，它只依赖于其左侧的上下文（w_1, ..., w_{i-1}）。序列末尾的 Padding Token 不会影响 到它前面真实 Token 的特征计算。

损失忽略：Padding Token 虽然也会经过模型产生 logits，但由于在 label_ids 中已将这些位置标记为 -100，损失函数会自动忽略这些位置的损失。

所以，对于单向 RNN，Padding 虽然参与了计算，但其产生的影响最终被损失函数“屏蔽”了。不过，这种“侥幸”在双向模型中将不复存在。

2.3 双向模型改进

单向 GRU 的局限性导致其无法看到未来的上下文。在当前的任务中为了让模型在预测每一个 Token 时都能同时“左顾右盼”，最简单的改进就是引入 双向 GRU。不过，我们 不能通过简单地设置 bidirectional=True 来实现双向 GRU。

因为，双向 GRU 包含一个从右到左的反向传播路径。它会从序列的末尾开始计算，如果末尾都是无意义的 <PAD> 标记，那么这些“垃圾信息”就会作为初始状态，一路污染到序列中真实的 Token 表示中去。所以，需要一种方法来“告知”GRU 每个序列的真实长度，让它在计算时能够忽略掉这些填充位。

2.3.1 变长序列处理

既然问题的源于 RNN 无法区分真实 Token 和填充位，那么解决方案的重点就是：在将数据送入 RNN 之前，以某种方式明确地告诉它每个序列的真实长度。

PyTorch 提供了一套工具——torch.nn.utils.rnn.pack_padded_sequence。可以先来看看它的源码定义，重点关注输入参数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# torch/nn/utils/rnn.py

def pack_padded_sequence(
 input: Tensor,
 lengths: Union[Tensor, list[int]],
 batch_first: bool = False,
 enforce_sorted: bool = True,
) -> PackedSequence:
 r"""Packs a Tensor containing padded sequences of variable length.

 # ... (省略大部分文档) ...

 Args:
 input (Tensor): 经过填充的、变长的序列批次。
 lengths (Tensor or list(int)): 一个列表或张量，包含了批次中每个序列的真实长度。
 batch_first (bool, optional): 如果为 True，则输入张量的形状为 (B, T, *)。
 enforce_sorted (bool, optional): 如果为 True (默认)，则要求输入序列已按长度降序排列。
 如果为 False，函数会在内部自动进行排序。

 Returns:
 一个 PackedSequence 对象
 """
 # ... (省略内部实现逻辑) ...

从源码中可以看到，这个函数的主要作用是接收一个 填充后 的 input 张量，以及一个记录了 真实长度 的 lengths 列表。它会返回一个 PackedSequence 对象，可以把它想象成一个“压缩”后的数据包，其中所有的填充位都被暂时移除了。RNN 模块在接收到这个特殊对象后，其内部就能正确、高效地处理变长序列。

当然，有“打包”就有“解包”。与之对应的 pad_packed_sequence 函数会负责将 RNN 计算完成后的 PackedSequence 对象再“解压”还原成带有填充的、规整的 Tensor。

2.3.2 BiGRUNerNetWork 代码实现

理解了“打包-解包”机制后，就可以动手改造 GRUNerNetWork 了。代码的主要改动如下：

开启双向：在 nn.GRU 的参数中设置 bidirectional=True。
增加特征融合层：由于双向 GRU 的输出维度会变为 hidden_size * 2，需要增加一个全连接层，将拼接后的特征重新映射回 hidden_size，以便与输入进行残差连接。
集成 Pack/Pad：在 forward 方法中，实现完整的“计算长度 -> 打包 -> GRU 计算 -> 解包 -> 残差连接”流程。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


class BiGRUNerNetWork(nn.Module):
 def __init__(self, vocab_size, hidden_size, num_tags, num_gru_layers=1):
 super().__init__()
 # 1. Token Embedding 层
 self.embedding = nn.Embedding(vocab_size, hidden_size)

 # 2. 使用 ModuleList 构建多层双向 GRU
 self.gru_layers = nn.ModuleList()
 for _ in range(num_gru_layers):
 self.gru_layers.append(
 nn.GRU(
 input_size=hidden_size,
 hidden_size=hidden_size,
 num_layers=1,
 batch_first=True,
 bidirectional=True # 开启双向
 )
 )

 # 3. 特征融合层
 self.fc = nn.Linear(hidden_size * 2, hidden_size)

 # 4. 分类决策层 (Classifier)
 self.classifier = nn.Linear(hidden_size, num_tags)

 def forward(self, token_ids, attention_mask):
 # 1. 计算真实长度
 lengths = attention_mask.sum(dim=1).cpu()

 # 2. 获取词向量
 embedded_text = self.embedding(token_ids)

 # 3. 打包序列
 current_packed_input = rnn.pack_padded_sequence(
 embedded_text, lengths, batch_first=True, enforce_sorted=False
 )

 # 4. 循环通过 GRU 层
 for gru_layer in self.gru_layers:
 # GRU 输出 (packed)
 packed_output, _ = gru_layer(current_packed_input)

 # 解包以进行后续操作，并指定 total_length
 output, _ = rnn.pad_packed_sequence(
 packed_output, batch_first=True, total_length=token_ids.shape[1]
 )

 # 特征融合
 features = self.fc(output)

 # 残差连接
 # 同样需要解包上一层的输入
 input_padded, _ = rnn.pad_packed_sequence(
 current_packed_input, batch_first=True, total_length=token_ids.shape[1]
 )
 current_input = features + input_padded

 # 重新打包作为下一层的输入
 current_packed_input = rnn.pack_padded_sequence(
 current_input, lengths, batch_first=True, enforce_sorted=False
 )

 # 5. 解包最终输出用于分类
 final_output, _ = rnn.pad_packed_sequence(
 current_packed_input, batch_first=True, total_length=token_ids.shape[1]
 )

 # 6. 分类
 logits = self.classifier(final_output)

 return logits

通过这番改造，BiGRUNerNetWork 才算是一个能够正确处理变长序列的、健壮的双向模型。

三、组件构建与训练封装

一个成熟的项目，其训练代码不应是零散的脚本，而应是结构化、可复用的框架。本节将从封装 Trainer 的训练与评估流程开始，逐步实现并接入模型、数据加载器、分词器、评估指标等组件，最后完成主程序的整体组装。

为了实现这一目标，我们采用的设计思路是 组件式组装 与 部门化分工：

Trainer 只负责“训练”: Trainer 类的核心职责是执行标准的训练和评估循环。它不关心模型是怎么构建的，也不关心数据是怎么加载的。
组件由外部创建并“注入”: 模型、优化器、数据加载器等所有必要的组件都在外部被创建好，然后像零件一样被“注入”到 Trainer 的构造函数中。

3.1 搭建 Trainer 骨架

在开始编写 Trainer 类之前，先在 src/ 目录下创建一个 trainer 文件夹，并在其中新建一个 trainer.py 文件，用于存放 Trainer 类的定义。然后，定义 Trainer 类的基本结构。它通过构造函数接收所有必要的组件，并提供一个 fit 方法作为训练的统一入口。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


# src/trainer/trainer.py
import torch
import os

class Trainer:
 def __init__(self, model, optimizer, loss_fn, train_loader, dev_loader=None,
 eval_metric_fn=None, output_dir=None, device='cpu'):
 """
 初始化训练器。

 Args:
 model: PyTorch 模型。
 optimizer: 优化器。
 loss_fn: 损失函数。
 train_loader: 训练数据加载器。
 dev_loader: 验证数据加载器。
 eval_metric_fn: 评估函数。
 output_dir: 模型输出目录。
 device: 训练设备。
 """
 self.model = model.to(device)
 self.optimizer = optimizer
 self.loss_fn = loss_fn
 self.train_loader = train_loader
 self.dev_loader = dev_loader
 self.eval_metric_fn = eval_metric_fn
 self.output_dir = output_dir
 self.device = torch.device(device)

 if self.output_dir:
 os.makedirs(self.output_dir, exist_ok=True)

 def fit(self, epochs):
 """
 训练的主入口，负责整个训练流程的调度。
 """
 pass

 def _train_one_epoch(self):
 """封装一个 epoch 的训练逻辑。"""
 pass

 def _train_step(self, batch):
 """封装一个训练步骤的逻辑（前向、损失、反向）。"""
 pass

 def _evaluate(self):
 """封装评估逻辑。"""
 pass

 def _evaluation_step(self, batch):
 """封装一个评估步骤的逻辑（前向、损失）。"""
 pass

 def _save_checkpoint(self, is_best=False):
 """封装模型保存逻辑。"""
 pass

3.2 引入配置类管理参数

在搭建骨架时，会发现整个流程依赖于大量的参数，包括文件路径、模型超参数和训练设置。如果将这些参数零散地分布在代码中，会显得非常混乱且难以管理。

我们可以创建一个专门的 配置类 来统一管理所有这些参数。从最核心的几个参数开始定义：

路径参数：训练/验证集在哪，词汇表在哪，模型要输出到哪。
训练参数：batch_size, epochs, learning_rate 等。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# src/configs/configs.py
import torch
from dataclasses import dataclass, field

@dataclass
class NerConfig:
 # --- 路径参数 ---
 data_dir: str = "data"
 train_file: str = "CMeEE-V2_train.json"
 dev_file: str = "CMeEE-V2_dev.json"
 vocab_file: str = "vocabulary.json"
 tags_file: str = "categories.json"
 output_dir: str = "output"

 # --- 训练参数 ---
 batch_size: int = 32
 epochs: int = 20
 learning_rate: float = 1e-3
 device: str = field(default_factory=lambda: 'cuda' if torch.cuda.is_available() else 'cpu')

 # --- 模型参数 ---
 hidden_size: int = 256
 num_gru_layers: int = 2

@dataclass 是 Python 3.7 引入的装饰器，可以简化类的编写。对于 TrainerConfig 这样的配置类，它会自动生成构造函数 (__init__)，无需再手动编写冗长的参数赋值代码。同时，它还会生成一个友好的打印格式 (__repr__)，这意味着 print(config) 会清晰地展示所有参数和值，便于调试。

3.3 完善 Trainer 类

有了 NerConfig，就可以回过头来完善 Trainer 的代码。在我们当前的“组件式组装”设计中，虽然 Trainer 不直接接收整个 config 对象（以保持解耦），但 config 依然是所有“零件”的参数来源。

接下来，填充 Trainer 类的完整实现，使其能够执行完整的训练和评估流程。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127


import torch
from tqdm import tqdm
import os
from dataclasses import asdict

class Trainer:
 def __init__(self, model, optimizer, loss_fn, train_loader, dev_loader=None,
 eval_metric_fn=None, output_dir=None, device='cpu'):
 self.model = model.to(device)
 self.optimizer = optimizer
 self.loss_fn = loss_fn
 self.train_loader = train_loader
 self.dev_loader = dev_loader
 self.eval_metric_fn = eval_metric_fn
 self.output_dir = output_dir
 self.device = torch.device(device)

 if self.output_dir:
 os.makedirs(self.output_dir, exist_ok=True)

 def fit(self, epochs):
 best_metric = float('inf') # 初始化一个无穷大的 best_metric，用于后续比较

 for epoch in range(1, epochs + 1):
 # 1. 执行一个周期的训练
 train_loss = self._train_one_epoch()
 print(f"Epoch {epoch} - Training Loss: {train_loss:.4f}")

 # 2. 执行评估
 metrics = self._evaluate()
 if metrics:
 print(f"Epoch {epoch} - Validation Metrics: {metrics}")
 current_metric = metrics.get('loss') # 默认监控验证集 loss

 # 3. 如果当前 metric 优于历史最优，则保存最佳模型
 if current_metric < best_metric:
 best_metric = current_metric
 if self.output_dir:
 self._save_checkpoint(is_best=True)
 print(f"New best model saved with validation loss: {best_metric:.4f}")

 # 4. 每个 epoch 结束后，保存最新的模型状态
 if self.output_dir:
 self._save_checkpoint(is_best=False)

 def _train_one_epoch(self):
 """执行一个完整的训练周期。"""
 self.model.train() # 设置为训练模式
 total_loss = 0

 # 使用 tqdm 显示进度条
 for batch in tqdm(self.train_loader, desc=f"Training Epoch"):
 outputs = self._train_step(batch)
 total_loss += outputs['loss'].item() # 累加 loss

 return total_loss / len(self.train_loader) # 返回平均 loss

 def _train_step(self, batch):
 """执行单个训练步骤（前向、损失、反向）。"""
 # 1. 将数据移动到指定设备
 batch = {k: v.to(self.device) for k, v in batch.items() if isinstance(v, torch.Tensor)}

 # 2. 模型前向传播
 logits = self.model(token_ids=batch['token_ids'], attention_mask=batch['attention_mask'])

 # 3. 计算损失
 # CrossEntropyLoss 要求 logits 的形状为 [B, C, L]，label_ids 的形状为 [B, L]
 loss = self.loss_fn(logits.permute(0, 2, 1), batch['label_ids'])

 # 4. 反向传播与参数更新
 self.optimizer.zero_grad()
 loss.backward()
 self.optimizer.step()

 return {'loss': loss, 'logits': logits}

 def _evaluate(self):
 """在验证集上执行评估。"""
 if self.dev_loader is None:
 return None

 self.model.eval() # 设置为评估模式
 total_loss = 0
 all_logits = []
 all_labels = []
 all_attention_mask = []

 with torch.no_grad(): # 禁用梯度计算
 for batch in tqdm(self.dev_loader, desc="Evaluating"):
 outputs = self._evaluation_step(batch)

 total_loss += outputs['loss'].item()
 # 收集所有批次的 logits 和 labels，用于后续评估
 all_logits.append(outputs['logits'].cpu())
 all_labels.append(batch['label_ids'].cpu())
 all_attention_mask.append(batch['attention_mask'].cpu())

 metrics = {}
 # 如果提供了评估函数，则调用它来计算指标
 if self.eval_metric_fn:
 metrics = self.eval_metric_fn(all_logits, all_labels, all_attention_mask)

 # 计算并记录平均 loss
 metrics['loss'] = total_loss / len(self.dev_loader)
 return metrics

 def _evaluation_step(self, batch):
 """执行单个评估步骤（前向、损失）。"""
 # 1. 将数据移动到指定设备
 batch = {k: v.to(self.device) for k, v in batch.items() if isinstance(v, torch.Tensor)}

 # 2. 模型前向传播
 logits = self.model(token_ids=batch['token_ids'], attention_mask=batch['attention_mask'])

 # 3. 计算损失
 loss = self.loss_fn(logits.permute(0, 2, 1), batch['label_ids'])

 return {'loss': loss, 'logits': logits}

 def _save_checkpoint(self, is_best):
 """保存模型检查点。"""
 state = {'model_state_dict': self.model.state_dict()}
 if is_best:
 # 保存最佳模型
 torch.save(state, os.path.join(self.output_dir, 'best_model.pth'))
 # 保存最新模型
 torch.save(state, os.path.join(self.output_dir, 'last_model.pth'))

3.4 实现模型组件

完成通用的 Trainer 类之后，接下来就是一步步地去构建传入 __init__ 方法的各个组件。这里先来处理一下模型组件。

第一步：创建模型目录

在 src/ 目录下创建一个新的文件夹 models。

第二步：定义模型基类

在构建具体的模型之前，可以先在 src/models/ 目录下创建一个 base.py 文件来定义一个 模型基类。这个基类使用 Python 的 abc 模块（Abstract Base Classes）来规定所有 NER 模型都必须遵循的一个统一接口。

这样做的好处是：

强制接口统一：所有模型都必须实现一个 forward 方法，且接收相同的参数（token_ids, attention_mask）。这保证了 Trainer 可以与任何我们未来创建的新模型（如 BERT-NER, LSTM-NER）无缝协作，无需修改 Trainer 的代码。
提高可读性与可维护性：代码的结构更清晰，别人接手项目时，只需查看基类就能明白模型部分的接口规范。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# src/models/base.py
import torch.nn as nn
from abc import ABC, abstractmethod

class BaseNerNetwork(nn.Module, ABC):
 @abstractmethod
 def forward(self, token_ids, attention_mask):
 """
 定义所有 NER 模型都必须遵循的前向传播接口。

 Args:
 token_ids (torch.Tensor): [batch_size, seq_len]
 attention_mask (torch.Tensor): [batch_size, seq_len]

 Returns:
 torch.Tensor: Logits, [batch_size, seq_len, num_tags]
 """
 raise NotImplementedError

第三步：实现具体的 NER 模型

接下来，在 src/models 文件夹中创建一个新的 Python 文件，命名为 ner_model.py。可以将之前实现的 BiGRUNerNetWork 模型的代码直接复制到 ner_model.py 文件中，并让它继承我们刚刚定义的 BaseNerNetwork。

1
2
3
4
5
6
7


# src/models/ner_model.py
import torch.nn as nn
import torch.nn.utils.rnn as rnn
from .base import BaseNerNetwork # 导入基类

class BiGRUNerNetWork(BaseNerNetwork): # 继承自 BaseNerNetwork
 # ... (省略具体实现，与前文一致) ...

3.5 实现数据加载组件

在模型结构确定之后，需要为 Trainer 准备数据加载器（DataLoader）这个组件。通常分为两步：

创建 Dataset：负责读取单条数据，并将其转换为模型所需的张量（Tensor）。
创建 DataLoader：从 Dataset 中批量、随机地抓取数据，并通过 collate_fn 函数将它们整理成一个规整的批次（Batch）。

第一步：创建 NerDataset

在 src/data/ 目录下创建一个 dataset.py 文件，用于定义 NerDataset 类。同样的我们只需要复制之前在 03_data_loader.py 中实现过的 NerDataset 类就行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


# src/data/dataset.py
import torch
from torch.utils.data import Dataset
import json

class NerDataset(Dataset):
 def __init__(self, data_path, tokenizer, tag_map):
 self.tokenizer = tokenizer
 self.tag_to_id = tag_map

 # 直接加载和解析 JSON 文件
 with open(data_path, 'r', encoding='utf-8') as f:
 self.records = json.load(f)

 def __len__(self):
 return len(self.records)

 def __getitem__(self, idx):
 record = self.records[idx]
 text = record['text']
 tokens = self.tokenizer.text_to_tokens(text)
 token_ids = self.tokenizer.tokens_to_ids(tokens)

 tags = ['O'] * len(tokens)
 for entity in record.get('entities', []):
 entity_type = entity['type']
 start = entity['start_idx']
 end = entity['end_idx'] # 闭区间结束索引

 if end >= len(tokens): continue

 if start == end:
 tags[start] = f'S-{entity_type}'
 else:
 tags[start] = f'B-{entity_type}'
 tags[end] = f'E-{entity_type}'
 for i in range(start + 1, end):
 tags[i] = f'M-{entity_type}'

 label_ids = [self.tag_to_id.get(tag, self.tag_to_id['O']) for tag in tags]

 return {
 "token_ids": torch.tensor(token_ids, dtype=torch.long),
 "label_ids": torch.tensor(label_ids, dtype=torch.long)
 }

第二步：重构代码，封装通用函数

在 NerDataset 中，使用 json.load 来读取数据。但是，在项目中，可能会在多个地方都需要读取 JSON 文件（比如加载词汇表、加载配置文件等）。为了避免代码重复，并让代码更具可维护性，可以将这个文件读取的逻辑封装成一个通用的函数。

在 src/ 目录下创建一个 utils 文件夹，并在其中新建一个 file_io.py 文件。我们将在这里存放所有与文件读写相关的工具函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# src/utils/file_io.py
import json

def load_json(file_path):
 """从 JSON 文件加载数据。"""
 with open(file_path, 'r', encoding='utf-8') as f:
 return json.load(f)

def save_json(data, file_path):
 """将数据保存为 JSON 文件。"""
 with open(file_path, 'w', encoding='utf-8') as f:
 json.dump(data, f, ensure_ascii=False, indent=4)

然后回头优化 dataset.py 的代码，让它使用新创建的 load_json 函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# src/data/dataset.py
import torch
from torch.utils.data import Dataset
from ..utils.file_io import load_json # 导入封装好的函数

class NerDataset(Dataset):
 def __init__(self, data_path, tokenizer, tag_map):
 self.tokenizer = tokenizer
 self.tag_to_id = tag_map
 self.records = load_json(data_path) # 调用通用函数，代码更简洁

 # ... (省略 __len__ 和 __getitem__)

第三步：创建 DataLoader

在 src/data/ 目录下创建 data_loader.py 文件。复制 create_ner_dataloader 函数稍作调整来封装创建 DataLoader 的逻辑。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# src/data/data_loader.py
from torch.utils.data import DataLoader
from torch.nn.utils.rnn import pad_sequence
from .dataset import NerDataset

def create_ner_dataloader(data_path, tokenizer, tag_map, batch_size, shuffle=False, device='cpu'):
 dataset = NerDataset(data_path, tokenizer, tag_map)

 def collate_batch(batch):
 token_ids_list = [item['token_ids'] for item in batch]
 label_ids_list = [item['label_ids'] for item in batch]

 padded_token_ids = pad_sequence(token_ids_list, batch_first=True, padding_value=tokenizer.get_pad_id())
 padded_label_ids = pad_sequence(label_ids_list, batch_first=True, padding_value=-100)

 attention_mask = (padded_token_ids != tokenizer.get_pad_id()).long()

 return {
 "token_ids": padded_token_ids.to(device),
 "label_ids": padded_label_ids.to(device),
 "attention_mask": attention_mask.to(device)
 }

 return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle, collate_fn=collate_batch)

3.6 实现分词器组件

至此，模型和数据加载器的结构都已就绪。但在 NerDataset 内部，还需要一个核心组件来处理原始文本：分词器。它的任务是将文本字符串，转换成模型能够理解的、由数字 ID 组成的序列。

第一步：定义分词器基类

与模型的设计类似，为分词器定义一个基类同样是一种推荐的做法，这能确保不同分词器实现之间接口的统一。在 src/tokenizer/ 目录下创建 base.py 文件。这保证了我们未来可能创建的任何新分词器（例如基于 Jieba 的分词器）都会遵循相同的接口规范，从而可以与 NerDataset 无缝对接。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# src/tokenizer/base.py
from abc import ABC, abstractmethod

class BaseTokenizer(ABC):
 @abstractmethod
 def text_to_tokens(self, text: str) -> list[str]:
 """将文本分割成 token 列表。"""
 raise NotImplementedError

 @abstractmethod
 def tokens_to_ids(self, tokens: list[str]) -> list[int]:
 """将 token 列表转换为 ID 列表。"""
 raise NotImplementedError

 def encode(self, text: str) -> list[int]:
 """将文本直接编码为 ID 列表的便捷方法。"""
 tokens = self.text_to_tokens(text)
 return self.tokens_to_ids(tokens)

 @abstractmethod
 def get_pad_id(self) -> int:
 """获取填充 token 的 ID。"""
 raise NotImplementedError

第二步：实现字符级分词器

接下来，在 src/tokenizer/ 目录下创建 char_tokenizer.py。将分词和词汇表管理的所有逻辑都放在这一个类里。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# src/tokenizer/char_tokenizer.py
from .base import BaseTokenizer
from ..utils.file_io import load_json

def normalize_text(text):
 # ... (省略 normalize_text 函数实现) ...

class CharTokenizer(BaseTokenizer):
 def __init__(self, vocab_path: str):
 # 词汇表管理
 self.tokens = load_json(vocab_path)
 self.token_to_id = {token: i for i, token in enumerate(self.tokens)}
 self.id_to_token = {i: token for i, token in enumerate(self.tokens)}
 self.pad_id = self.token_to_id['<PAD>']
 self.unk_id = self.token_to_id['<UNK>']

 def __len__(self):
 return len(self.tokens)

 def text_to_tokens(self, text: str):
 normalized_text = normalize_text(text)
 return list(normalized_text)

 def tokens_to_ids(self, tokens: list[str]):
 return [self.token_to_id.get(token, self.unk_id) for token in tokens]

 def get_pad_id(self) -> int:
 return self.pad_id

第三步：创建词汇表管理器

为了让代码结构更清晰，可以将词汇表管理的功能抽离出来，封装成一个独立的 Vocabulary 类。在 src/tokenizer/ 目录下创建 vocabulary.py 文件，将之前 CharTokenizer 中 __init__ 方法里的词汇表逻辑迁移过来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# src/tokenizer/vocabulary.py
from ..utils.file_io import load_json

class Vocabulary:
 """
 管理词汇表和 token 到 id 的映射。
 """
 def __init__(self, vocab_path):
 self.tokens = load_json(vocab_path)
 self.token_to_id = {token: i for i, token in enumerate(self.tokens)}
 self.id_to_token = {i: token for i, token in enumerate(self.tokens)}
 self.pad_id = self.token_to_id['<PAD>']
 self.unk_id = self.token_to_id['<UNK>']

 def __len__(self):
 return len(self.tokens)

 def convert_tokens_to_ids(self, tokens):
 return [self.token_to_id.get(token, self.unk_id) for token in tokens]

 @classmethod
 def load_from_file(cls, vocab_path):
 return cls(vocab_path)

第四步：优化分词器

最后，我们回到 char_tokenizer.py，用新创建的 Vocabulary 类来重构它。可以看到，重构后的 CharTokenizer 将只负责分词。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# src/tokenizer/char_tokenizer.py
from .vocabulary import Vocabulary
from .base import BaseTokenizer

def normalize_text(text):
 # ... (省略 normalize_text 函数实现) ...

class CharTokenizer(BaseTokenizer):
 def __init__(self, vocab: Vocabulary):
 self.vocab = vocab

 def text_to_tokens(self, text: str):
 normalized_text = normalize_text(text)
 return list(normalized_text)

 def tokens_to_ids(self, tokens: list[str]):
 return self.vocab.convert_tokens_to_ids(tokens)

 def get_pad_id(self) -> int:
 return self.vocab.pad_id

3.7 实现评估指标组件

对于 NER 任务，简单地计算每个 Token 的分类准确率是不够的。我们更关心的是模型作为一个整体，能否准确地、完整地抽取出命名实体。所以，需要计算实体级别（Entity-level）的指标：精确率（Precision）、召回率（Recall）和 F1 值。

计算这些指标的流程如下：

解码：将模型预测出的标签 ID 序列（如 [12, 13, 14, 0]）转换回实体片段的列表（如 [('dis', 0, 3)]）。
对比：将预测出的实体列表与真实的实体列表进行比较。
计算

：
- TP (True Positives)：预测正确且与真实实体完全匹配（类型、起始和结束位置都相同）的实体数量。
- FP (False Positives)：预测出的、但实际上不存在的实体数量。
- FN (False Negatives)：真实存在、但模型未能预测出的实体数量。
- Precision = TP / (TP + FP)
- Recall = TP / (TP + FN)
- F1 = 2 (Precision Recall) / (Precision + Recall)

新建 src/metrics/ 目录并创建一个 entity_metrics.py 文件来实现这个逻辑。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70


# src/metrics/entity_metrics.py
import torch

def _trans_entity2tuple(label_ids, id2tag):
 """
 将标签ID序列转换为实体元组列表（严格 BMES 解码）。
 仅在遇到 E- 或 S- 时落盘；遇到新的 B- 或 O 不闭合未完成片段。
 """
 entities = []
 current_entity = None

 for i, label_id in enumerate(label_ids):
 # 将标签ID映射为字符串标签，未知则视作 'O'
 tag = id2tag.get(label_id.item(), 'O')

 if tag.startswith('B-'):
 # 开启新片段：记录类型与起始位置；end 暂定为 i+1
 current_entity = (tag[2:], i, i + 1)
 elif tag.startswith('M-'):
 # 仅当已存在片段，且类型一致时续接（扩展 end）
 if current_entity and current_entity[0] == tag[2:]:
 current_entity = (current_entity[0], current_entity[1], i + 1)
 else:
 # 类型不一致或不存在片段：丢弃未完成片段
 current_entity = None
 elif tag.startswith('E-'):
 # 仅当已存在片段且类型一致时闭合并落盘
 if current_entity and current_entity[0] == tag[2:]:
 current_entity = (current_entity[0], current_entity[1], i + 1)
 entities.append(current_entity)
 # 无论是否匹配，E- 都视为一次片段结束
 current_entity = None
 elif tag.startswith('S-'):
 # 单字实体：直接落盘（start=i, end=i+1）
 entities.append((tag[2:], i, i + 1))
 current_entity = None
 else: # 'O'
 # 非实体位置：严格模式不闭合未完成片段，直接丢弃
 current_entity = None

 # 返回集合去重
 return set(entities)

def calculate_entity_level_metrics(all_pred_ids, all_label_ids, id2tag):
 """
 逐样本评估（未使用 mask），解码采用严格 BMES。
 """
 true_entities = set()
 pred_entities = set()

 # 遍历批次中的每一个样本
 for i in range(len(all_label_ids)):
 # 将标签ID序列解码为实体集合（严格 BMES）
 sample_true_entities = _trans_entity2tuple(all_label_ids[i], id2tag)
 sample_pred_entities = _trans_entity2tuple(all_pred_ids[i], id2tag)

 true_entities.update(sample_true_entities)
 pred_entities.update(sample_pred_entities)

 # 计算 TP / FP / FN
 num_correct = len(true_entities.intersection(pred_entities)) # TP
 num_true = len(true_entities) # TP + FN
 num_pred = len(pred_entities) # TP + FP

 # 计算 P / R / F1（含零保护）
 precision = num_correct / num_pred if num_pred > 0 else 0.0
 recall = num_correct / num_true if num_true > 0 else 0.0
 f1 = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0.0

 return {"precision": precision, "recall": recall, "f1": f1}

批量评估中的挑战与解决方案：

当前 calculate_entity_level_metrics 的实现，在面对 Trainer 的批量评估场景时，会遇到两个问题：

处理填充：在一个批次中，不同长度的句子会被填充到相同长度。这些填充位（Padding）不应参与评估。我们需要利用 attention_mask 机制，来过滤掉所有因填充而产生的无效 Token，确保评估只在有效的序列片段上进行。

追踪样本来源：当处理一个批次的多个样本时，必须能区分每个实体到底来自哪个样本。例如，批次中的第一个样本和第二个样本可能在相同的位置 (0, 2) 都有一个 'dis' 类型的实体。如果在解码时不加以区分，这两个独立的实体在存入 set 时会被误判为同一个。为了准确区分来自同一批次中不同样本的实体，设计了一种方案：为每个解码出的实体附加其所在样本的唯一ID（即批次内索引 i）。确保每个实体都由一个唯一的 (样本ID, 实体类型, 起始位置, 结束位置) 四元组来标识，从根本上解决实体归属混淆的问题。

改进后的 calculate_entity_level_metrics 函数实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# src/metrics/entity_metrics.py

# _trans_entity2tuple 函数同上，此处省略...

def calculate_entity_level_metrics(all_pred_ids, all_label_ids, all_masks, id2tag):
 """
 计算实体级别的精确率、召回率和 F1 分数。
 """
 true_entities = set()
 pred_entities = set()
 sample_idx = 0

 # 按批次遍历，同时保持 preds/labels/masks 对齐
 for preds_batch, labels_batch, masks_batch in zip(all_pred_ids, all_label_ids, all_masks):
 B = labels_batch.shape[0] # 当前批次样本数
 for b in range(B):
 # 对单个样本应用布尔掩码，去除 padding 位置
 row_mask = masks_batch[b].bool()
 row_labels = labels_batch[b][row_mask]
 row_preds = preds_batch[b][row_mask]

 # 严格 BMES 解码为实体集合
 te = _trans_entity2tuple(row_labels, id2tag)
 pe = _trans_entity2tuple(row_preds, id2tag)

 # 为每个实体附加 (sample_idx,) 前缀，确保不同样本的相同实体不冲突
 true_entities.update({(sample_idx,) + e for e in te})
 pred_entities.update({(sample_idx,) + e for e in pe})
 sample_idx += 1

 num_correct = len(true_entities.intersection(pred_entities))
 num_true = len(true_entities)
 num_pred = len(pred_entities)

 precision = num_correct / num_pred if num_pred > 0 else 0.0
 recall = num_correct / num_true if num_true > 0 else 0.0
 f1 = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0.0
 return {"precision": precision, "recall": recall, "f1": f1}

3.8 组装所有组件

最后让我们组装刚才实现的各个组件。在根目录创建一个 05_train.py 文件，它将导入并组装在 src/ 目录下构建的所有模块。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105


# 05_train.py
import os
import torch
import torch.nn as nn
# 导入定义的所有组件
from src.configs.configs import config
from src.data.data_loader import create_ner_dataloader
from src.tokenizer.vocabulary import Vocabulary
from src.tokenizer.char_tokenizer import CharTokenizer
from src.models.ner_model import BiGRUNerNetWork
from src.trainer.trainer import Trainer
from src.utils.file_io import load_json
from src.metrics.entity_metrics import calculate_entity_level_metrics

def main():
 """
 主函数，负责组装所有组件并启动NER训练任务。
 """
 # --- 1. 加载词汇表和标签映射, 并创建分词器 ---
 vocab_path = os.path.join(config.data_dir, config.vocab_file)
 tags_path = os.path.join(config.data_dir, config.tags_file)
 train_path = os.path.join(config.data_dir, config.train_file)
 dev_path = os.path.join(config.data_dir, config.dev_file)

 vocab = Vocabulary.load_from_file(vocab_path)
 tokenizer = CharTokenizer(vocab)
 tag_map = load_json(tags_path)
 id2tag = {v: k for k, v in tag_map.items()}

 # --- 2. 创建数据加载器 ---
 train_loader = create_ner_dataloader(
 data_path=train_path,
 tokenizer=tokenizer,
 tag_map=tag_map,
 batch_size=config.batch_size,
 shuffle=True,
 device=config.device
 )
 dev_loader = create_ner_dataloader(
 data_path=dev_path,
 tokenizer=tokenizer,
 tag_map=tag_map,
 batch_size=config.batch_size,
 shuffle=False,
 device=config.device
 )

 # --- 3. 初始化模型、优化器、损失函数 ---
 model = BiGRUNerNetWork(
 vocab_size=len(vocab),
 hidden_size=config.hidden_size,
 num_tags=len(tag_map),
 num_gru_layers=config.num_gru_layers
 )
 optimizer = torch.optim.AdamW(model.parameters(), lr=config.learning_rate)
 loss_fn = nn.CrossEntropyLoss(ignore_index=-100)

 # --- 4. 定义评估函数 ---
 def eval_metric_fn(all_logits, all_labels, all_attention_mask):
 # 将模型输出的 logits 转换为预测的 tag id
 all_preds_ids = [torch.argmax(logits, dim=-1) for logits in all_logits]

 # 将所有数据移动到 CPU 以便进行后续计算
 all_labels_cpu = [labels.cpu() for labels in all_labels]
 all_preds_ids_cpu = [preds.cpu() for preds in all_preds_ids]
 all_attention_mask_cpu = [mask.cpu() for mask in all_attention_mask]

 # 将 attention_mask 转换为布尔类型，用于过滤 padding
 active_masks = [mask.bool() for mask in all_attention_mask_cpu]

 # 基于 mask 的 token 级准确率
 total_equal_tokens, total_effective_tokens = 0, 0
 for preds, labels, mask in zip(all_preds_ids_cpu, all_labels_cpu, active_masks):
 eq = (preds == labels) & mask
 total_equal_tokens += int(eq.sum().item())
 total_effective_tokens += int(mask.sum().item())
 token_acc = (total_equal_tokens / total_effective_tokens) if total_effective_tokens > 0 else 0.0

 # 调用之前定义的实体级评估函数
 metrics = calculate_entity_level_metrics(
 all_preds_ids_cpu,
 all_labels_cpu,
 active_masks,
 id2tag
 )
 metrics['token_acc'] = token_acc
 return metrics

 # --- 5. 初始化并启动训练器 ---
 trainer = Trainer(
 model=model,
 optimizer=optimizer,
 loss_fn=loss_fn,
 train_loader=train_loader,
 dev_loader=dev_loader,
 eval_metric_fn=eval_metric_fn,
 output_dir=config.output_dir,
 device=config.device
 )

 # 启动训练
 trainer.fit(epochs=config.epochs)

if __name__ == "__main__":
 main()

最终，我们完整地构建了从数据处理、模型构建、训练封装到评估的整个 NER 项目流程。在 code/C8/ 目录下，通过 python 05_train.py 命令，就可以启动整个训练过程。

第四节模型的推理与优化

经过前面章节的数据处理、模型构建与训练，我们已经得到了一个可用的 NER 模型。本章将探讨如何实现模型的推理过程，并深入研究如何通过自定义损失函数来应对数据不均衡问题，通过集成可视化日志、提前停止和断点续训等功能，进一步提升训练框架的健壮性和实用性。

一、理解模型输出

在上一节构建 Trainer 时，已经明确了实体级别的 F1 值是衡量模型性能的核心标准，而非简单的 Token 分类准确率。这里探讨一下 为什么 需要这样做，以及这对设计推理流程有何启发。

1.1 Token 级准确率的陷阱

最直接的评估方式是计算 Token 级别的分类准确率，即模型预测正确的标签数占总标签数的比例。不过，正如在上一节中讨论过的，这个指标具有误导性，尤其是在实体词占比较低的场景中。主要问题在于 数据不均衡。在大部分文本中，绝大多数的 Token 标签都是 'O'（非实体）。一个“聪明”但完全没用的模型，如果它将所有 Token 都预测为 'O'，也能轻松达到一个非常高的 Token 准确率。但是，这样的模型没有识别出任何一个实体，对于当前的任务来说毫无价值。

当模型训练到一定阶段后，其预测结果可能会出现大量甚至全部为 'O'（ID 为 0）的情况。尽管此时的 Token 准确率看上去很高，但模型实际上已经陷入了通过预测多数类来最小化损失的“捷径”中，这是一种典型的过拟合现象，说明模型并没有真正学会识别实体。

1.2 对推理流程的启发

模型的原始输出（Token 标签序列）本身不是最终交付物。我们需要一个“后处理”或“解码”步骤，将这个标签序列转换成用户真正关心的结构化的实体列表。这不仅是正确评估模型的需要，也是模型能否在实际应用中创造价值的关键。

所以，当前的主要任务就是实现这个从标签序列到实体列表的解码过程。

二、从标签到实体：解码预测序列

模型的前向传播最终输出的是一个 logits 张量，形状为 [batch_size, seq_len, num_tags]。经过 argmax 操作后，会得到一个标签 ID 序列，例如 [0, 9, 10, 11, 0, ...]。

这个序列本身并不直观。为了进行实体级评估，或者将预测结果呈现给用户，必须实现一个 解码 (Decode) 函数，将这个数字序列转换成一个包含具体实体信息的列表，例如：[{"text": "高血压", "type": "dis", "start": 3, "end": 6}]。这个解码过程的核心，就是根据 BMES 标注体系的规则，从标签序列中解析出实体的边界和类型。

2.1 解码逻辑详解

解码函数需要遍历标签序列，并像一个“状态机”一样，根据当前遇到的标签（B, M, E, S, O）来维护一个 current_entity 对象。其解码逻辑如下：

遇到 B- (实体开始):
- 如果此时还有一个未结束的 current_entity（说明上一个实体没有被 E- 正常闭合），则将其视为一个无效片段并放弃。
- 创建一个新的 current_entity 对象，记录下它的类型、起始位置和起始字符。
遇到 M- (实体中间):
- 检查当前是否存在一个 current_entity，并且其类型与 M- 标签的类型是否一致。
- 如果一致，将当前字符追加到 current_entity 的 text 中。
- 如果不一致（例如 B-dis 后面跟了一个 M-sym），则说明这是一个非法的标签序列。我们将 current_entity 重置为 None，放弃这个不完整的片段。
遇到 E- (实体结束):
- 与 M- 标签的检查逻辑类似，首先确保存在一个类型匹配的 current_entity。
- 如果匹配，将当前字符追加进去，并记录下结束位置 end = i + 1。
- 此时，一个完整的实体已经被识别出来，将其添加到最终的 entities 列表中。
- 最后，必须将 current_entity 重置为 None，表示当前实体已处理完毕。
遇到 S- (单字实体):
- 同样地，先放弃任何未闭合的 current_entity。
- 直接创建一个包含类型、文本、起始和结束位置的完整实体，并将其添加到 entities 列表中。
遇到 O (非实体):
- O 标签的出现意味着当前位置没有实体，或者一个实体刚刚结束。
- 如果此时还有一个未闭合的 current_entity，放弃它，并将 current_entity 重置为 None。

这个过程确保了只有符合 BMES 规范、被正确“闭合”的实体才会被最终提取出来，继而保证了解码结果的健壮性。

解码策略：

当前采用的是一种 “严格”模式。任何不符合规范的序列（例如只有 B- 没有 E- 的实体）都会被直接放弃。这是最常见的做法，因为它能保证输出实体的规范性。

在某些特定的业务场景下，也可以采用更 “宽松”的策略。例如，如果模型预测出一个 B-M-O 的序列，可以选择将 B-M 这部分作为一个实体输出，而不是完全丢弃它。这种策略的选择，取决于具体应用对“召回率”和“精确率”的不同侧重，需要根据实际需求来决定。

2.2 代码实现

这个解码逻辑在 06_predict.py 中实现为一个名为 _extract_entities 的方法。它接收分词后的 tokens 列表和模型预测的 tags 列表作为输入，输出结构化的实体字典列表。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# code/C8/06_predict.py

def _extract_entities(self, tokens, tags):
 entities = []
 current_entity = None
 for i, tag in enumerate(tags):
 if tag.startswith('B-'):
 # 如果前一个实体未正确结束，则放弃
 if current_entity:
 pass # 或者可以根据业务逻辑决定是否保存不完整的实体
 current_entity = {"text": tokens[i], "type": tag[2:], "start": i}
 elif tag.startswith('M-'):
 # M 标签必须跟在 B- 或 M- 之后
 if current_entity and current_entity["type"] == tag[2:]:
 current_entity["text"] += tokens[i]
 else:
 # 非法 M 标签，重置当前实体
 current_entity = None
 elif tag.startswith('E-'):
 # E 标签必须跟在 B- 或 M- 之后
 if current_entity and current_entity["type"] == tag[2:]:
 current_entity["text"] += tokens[i]
 current_entity["end"] = i + 1
 entities.append(current_entity)
 # 实体已结束，重置
 current_entity = None
 elif tag.startswith('S-'):
 # S 标签表示单个字符的实体
 # 如果有未结束的实体，则放弃
 current_entity = None
 entities.append({"text": tokens[i], "type": tag[2:], "start": i, "end": i + 1})
 else: # 'O' 标签
 # O 标签意味着没有实体，或者实体已经结束
 # 如果有未结束的实体，则放弃
 current_entity = None

 # 循环结束后，不再处理任何未闭合的实体
 return entities

三、封装推理器

最后将所有推理相关的逻辑（加载模型、文本预处理、模型预测、结果解码）封装到一个 NerPredictor 类中，使其成为一个开箱即用的独立组件。

3.1 推理器的设计

一个好的推理器应该具备以下特点：

易于初始化: 只需提供训练好的模型目录，就能自动加载所有必要的资源（模型权重、配置文件、词汇表等）。
接口简洁: 提供一个简单的 predict(text) 方法，接收原始文本字符串，返回结构化的实体列表。
与训练解耦: 推理过程不应依赖任何训练时的代码或对象。

3.2 `NerPredictor` 核心流程

3.2.1 初始化 `init`

__init__ 方法的目标是加载并准备好所有推理所需的组件。

加载配置: 从模型目录加载 config.json，获取模型超参数和相关文件路径。

[开发插曲] 确保训练与推理的配置同步

在编写 NerPredictor 时，可能会遇到了一个问题：推理脚本需要知道训练时使用的模型配置（如 hidden_size 等）才能正确地重建模型，但之前的训练脚本 05_train.py 并没有将这些配置信息保存下来。

这会导致在运行 06_predict.py 时出现 FileNotFoundError: [Errno 2] No such file or directory: 'output/config.json' 的错误。

为了解决这个问题，回到 05_train.py，增加一步：在训练开始前，将当前的配置对象保存到输出目录中。这样，训练和推理阶段就能共享同一份配置，确保信息同步。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# code/C8/05_train.py

from dataclasses import asdict
from src.utils.file_io import save_json

def main():
 # ... (组件初始化)

 trainer = Trainer(...)

 # 在训练开始前，保存配置文件
 os.makedirs(config.output_dir, exist_ok=True)
 save_json(asdict(config), os.path.join(config.output_dir, "config.json"))
 print(f"Configuration saved to {os.path.join(config.output_dir, 'config.json')}")

 trainer.fit(epochs=config.epochs)

加载词汇表和标签映射: 根据配置文件中的路径，加载 vocabulary.json 和 tags.json，并构建 id2tag 映射。
加载分词器: 初始化 CharTokenizer。
初始化模型并加载权重:
- 根据配置实例化 BiGRUNerNetWork 模型。
- 从模型目录加载 best_model.pth 模型权重。这里需要使用 map_location=self.device 来确保模型可以被加载到指定的设备上（无论是 CPU 还是 GPU）。
- 调用 model.to(self.device) 将模型移至指定设备。
- 调用 model.eval() 将模型切换到评估模式，关闭 Dropout 和 BatchNorm 等只在训练时使用的层，确保预测结果的确定性。

3.2.2 预测 `predict`

predict 方法负责执行从原始文本到实体列表的完整端到端流程。

预处理

:
- 调用 tokenizer 将输入文本转换为 token_ids。
- 将 token_ids 转换为 torch.Tensor，并添加一个 batch 维度（因为模型期望的输入是 [batch_size, seq_len]）。
- 创建 attention_mask。
- 将所有张量移动到 self.device。
模型预测

:
- 使用 with torch.no_grad(): 临时禁用梯度计算，减少内存消耗并加速推理过程。
- 将 token_ids 和 attention_mask 送入模型，得到 logits。
后处理

:
- 对 logits 在最后一个维度上执行 argmax，得到预测的 label_ids 序列。
- 使用 id2tag 映射，将 label_ids 转换为 tags 字符串列表。
- 调用 _extract_entities 方法，完成最终的解码，返回实体列表。

3.3 完整代码实现

在清晰地理解了设计思路和流程后，下面是 06_predict.py 的完整代码。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


# code/C8/06_predict.py
import torch
import json
import os
import argparse
from src.models.ner_model import BiGRUNerNetWork
from src.tokenizer.vocabulary import Vocabulary
from src.tokenizer.char_tokenizer import CharTokenizer
from src.utils.file_io import load_json

class NerPredictor:
 def __init__(self, model_dir, device='cpu'):
 self.device = torch.device(device)

 # --- 1. 加载配置文件以获取模型参数 ---
 config_path = os.path.join(model_dir, 'config.json')
 self.config = load_json(config_path)

 # --- 2. 加载词汇表和标签映射 ---
 vocab_path = os.path.join(self.config["data_dir"], self.config["vocab_file"])
 tags_path = os.path.join(self.config["data_dir"], self.config["tags_file"])

 self.vocab = Vocabulary.load_from_file(vocab_path)
 self.tokenizer = CharTokenizer(self.vocab)
 tag_map = load_json(tags_path)
 self.id2tag = {v: k for k, v in tag_map.items()}

 # --- 3. 初始化模型并加载权重 ---
 self.model = BiGRUNerNetWork(
 vocab_size=len(self.vocab),
 hidden_size=self.config["hidden_size"],
 num_tags=len(tag_map),
 num_gru_layers=self.config["num_gru_layers"]
 )
 model_path = os.path.join(model_dir, 'best_model.pth')
 self.model.load_state_dict(torch.load(model_path, map_location=self.device)['model_state_dict'])
 self.model.to(self.device)
 self.model.eval()

 def predict(self, text):
 tokens = self.tokenizer.text_to_tokens(text)
 token_ids = self.tokenizer.tokens_to_ids(tokens)

 # --- 预处理 ---
 token_ids_tensor = torch.tensor([token_ids], dtype=torch.long).to(self.device)
 attention_mask = torch.ones_like(token_ids_tensor)

 # --- 模型预测 ---
 with torch.no_grad():
 logits = self.model(token_ids_tensor, attention_mask)

 # --- 后处理 ---
 predictions = torch.argmax(logits, dim=-1).squeeze(0)
 tags = [self.id2tag[id_.item()] for id_ in predictions]

 return self._extract_entities(tokens, tags)

 def _extract_entities(self, tokens, tags):
 entities = []
 current_entity = None
 for i, tag in enumerate(tags):
 if tag.startswith('B-'):
 if current_entity:
 pass
 current_entity = {"text": tokens[i], "type": tag[2:], "start": i}
 elif tag.startswith('M-'):
 if current_entity and current_entity["type"] == tag[2:]:
 current_entity["text"] += tokens[i]
 else:
 current_entity = None
 elif tag.startswith('E-'):
 if current_entity and current_entity["type"] == tag[2:]:
 current_entity["text"] += tokens[i]
 current_entity["end"] = i + 1
 entities.append(current_entity)
 current_entity = None
 elif tag.startswith('S-'):
 current_entity = None
 entities.append({"text": tokens[i], "type": tag[2:], "start": i, "end": i + 1})
 else: # 'O' 标签
 current_entity = None

 return entities

def main():
 parser = argparse.ArgumentParser(description="NER Prediction")
 parser.add_argument("--model_dir", type=str, required=True, help="Directory of the saved model and config.")
 parser.add_argument("--text", type=str, required=True, help="Text to predict.")
 args = parser.parse_args()

 predictor = NerPredictor(model_dir=args.model_dir)
 entities = predictor.predict(args.text)
 print(f"Text: {args.text}")
 print(f"Entities: {json.dumps(entities, ensure_ascii=False, indent=2)}")

if __name__ == "__main__":
 main()

3.4 使用示例

06_predict.py 的 main 函数提供了一个标准的命令行使用接口。在训练完成后，可以通过以下命令来调用训练好的模型进行预测：

1

python 06_predict.py --model_dir "output" --text "患者自述发热、咳嗽，伴有轻微头痛。"

--model_dir: 指向我们第三节中训练结果的输出目录（包含了 best_model.pth 和 config.json）。
--text: 需要进行实体识别的文本。

预期输出:

由于我们仅进行了简单的训练，并未进行调优，所以当前模型的预测结果可能并不完美（例如可能只识别出部分实体或单字实体）。这里展示的输出主要是为了说明整个推理流程的格式和工作方式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Text: 患者自述发热、咳嗽，伴有轻微头痛。
Entities: [
 {
 "text": "发",
 "type": "sym",
 "start": 4,
 "end": 5
 },
 {
 "text": "咳",
 "type": "sym",
 "start": 7,
 "end": 8
 }
]

四、自定义损失函数

在当前使用的 CMeEE 数据集中，数据不均衡是一个显著的特点：大部分 Token 都是非实体的 ‘O’ 标签。虽然导致模型性能不佳的原因可能多种多样，但这种数据不均衡无疑是影响模型学习效果的关键因素之一。仅仅依赖实体级评估指标是在“下游”进行补救，我们也可以尝试从“上游”——即损失函数的设计入手，主动引导模型去关注实体样本。

标准的交叉熵损失函数对所有 Token 一视同仁，当 'O' 标签占据绝大多数时，损失值自然会被这些“多数派”主导。下面介绍两种策略，来尝试缓解这个问题。

4.1 核心策略

4.1.1 加权交叉熵损失

最简单的方法就是“加权”。给数量稀少的实体标签（B, M, E, S）一个更高的权重，给数量庞大的非实体标签（O）一个较低的权重。例如，我们可以设置实体损失的权重为 10，非实体损失的权重为 1。这样，模型在反向传播时，如果弄错了一个实体 Token，会受到比弄错一个非实体 Token 大 10 倍的“惩罚”，从而迫使模型更加关注对实体的识别。

4.1.2 硬负样本挖掘

另一种思路是“采样”。在大量的非实体样本中，大部分是模型可以轻易正确预测的“简单样本”，它们对损失的贡献很小，反复学习意义不大。真正有价值的是那些模型容易搞错的“硬负样本”，例如一个模型倾向于预测为实体的非实体 Token。

硬负样本挖掘的做法是：在计算非实体部分的损失时，不计算所有非实体 Token 的平均损失，而是只选择其中损失值最大（Top-K）的一部分进行计算和反向传播。这样就相当于从海量的“多数派”中，筛选出了最有价值的“疑难样本”进行学习，提升了训练的效率和效果。

4.2 代码实现

为了将上述策略集成到训练框架中，来创建一个新的 NerLoss 类，并修改项目的相关部分来调用它。

4.2.1 创建 `NerLoss`

首先，在 src 目录下创建一个新的 loss 文件夹，并在其中新建 ner_loss.py 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86


# code/C8/src/loss/ner_loss.py

import torch
import torch.nn as nn

class NerLoss(nn.Module):
 """
 自定义 NER 损失函数，集成两种策略来对抗数据不均衡问题：
 1. 加权交叉熵
 2. 硬负样本挖掘
 """
 def __init__(self, loss_type='cross_entropy', entity_weight=10.0, hard_negative_ratio=0.5, ignore_index=-100):
 super().__init__()
 # --- 参数定义 ---
 self.loss_type = loss_type # 损失类型: 'cross_entropy', 'weighted_ce', 'hard_negative_mining'
 self.entity_weight = entity_weight # 实体损失的权重
 self.hard_negative_ratio = hard_negative_ratio # 硬负样本与正样本的比例

 # 基础损失函数，设置为 'none' 模式以获取每个 token 的单独损失
 self.base_loss_fn = nn.CrossEntropyLoss(reduction='none', ignore_index=ignore_index)

 def forward(self, logits, labels):
 """
 根据初始化时选择的 loss_type 计算损失。
 """
 if self.loss_type == 'weighted_ce':
 return self._weighted_cross_entropy(logits, labels)
 elif self.loss_type == 'hard_negative_mining':
 return self._hard_negative_mining(logits, labels)
 else:
 # 默认使用 PyTorch 原生的交叉熵损失
 return self.base_loss_fn(logits, labels).mean()

 def _weighted_cross_entropy(self, logits, labels):
 """
 加权交叉熵损失的实现。
 """
 # 计算每个 token 的基础损失, shape: [batch_size, seq_len]
 loss_per_token = self.base_loss_fn(logits, labels)

 # 创建掩码来区分实体和非实体 token
 entity_mask = (labels > 0).float() # 实体 (B, M, E, S)
 non_entity_mask = (labels == 0).float() # 非实体 (O)

 # 分别计算实体和非实体部分的平均损失
 entity_loss = torch.sum(loss_per_token * entity_mask) / (torch.sum(entity_mask) + 1e-8)
 non_entity_loss = torch.sum(loss_per_token * non_entity_mask) / (torch.sum(non_entity_mask) + 1e-8)

 # 根据预设权重，组合两部分损失
 total_loss = self.entity_weight * entity_loss + 1.0 * non_entity_loss
 return total_loss, entity_loss.detach(), non_entity_loss.detach()

 def _hard_negative_mining(self, logits, labels):
 """
 硬负样本挖掘损失的实现。
 """
 # 计算每个 token 的基础损失
 loss_per_token = self.base_loss_fn(logits, labels)

 # 实体部分的损失计算与加权交叉熵方法相同
 entity_mask = (labels > 0).float()
 entity_loss = torch.sum(loss_per_token * entity_mask) / (torch.sum(entity_mask) + 1e-8)

 # 筛选出所有非实体 token 的损失
 non_entity_mask = (labels == 0).float()
 non_entity_loss = loss_per_token * non_entity_mask

 # 确定要挖掘的硬负样本数量
 num_entities = torch.sum(entity_mask).item()
 num_hard_negatives = int(num_entities * self.hard_negative_ratio)

 # 如果当前批次没有实体，则按固定比例选择负样本，避免数量为0
 if num_hard_negatives == 0:
 num_non_entities = torch.sum(non_entity_mask).item()
 num_hard_negatives = int(num_non_entities * 0.1)

 # 从非实体损失中选出最大的 top-k 个作为硬负样本
 topk_losses, _ = torch.topk(non_entity_loss.view(-1), k=num_hard_negatives)

 # 计算硬负样本的平均损失
 hard_negative_loss = torch.mean(topk_losses)

 # 结合实体损失和硬负样本损失
 total_loss = self.entity_weight * entity_loss + 1.0 * hard_negative_loss

 return total_loss, entity_loss.detach(), hard_negative_loss.detach()

这个类封装了所有与损失计算相关的逻辑。它会返回一个元组 (总损失, 实体损失, 非实体损失)，便于我们在训练日志中观察不同部分损失的变化情况。

4.2.2 硬负样本挖掘实现细节

在 _hard_negative_mining 的实现中，有一个需要特别注意的细节：torch.topk 函数要求 k 的值不能超过输入张量的维度大小。在此场景中，如果计算出的 num_hard_negatives 超过了当前批次中非实体 O 的总数，就会引发运行时错误。

同时，需要将二维的 non_entity_loss 展平（view(-1)）成一维，以确保 topk 是在所有非实体样本中寻找损失最大的 k 个。下面是修正后的关键代码片段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# code/C8/src/loss/ner_loss.py

def _hard_negative_mining(self, logits, labels):
 # ... (省略实体损失计算)

 non_entity_mask = (labels == 0).float()
 non_entity_loss = loss_per_token * non_entity_mask

 num_hard_negatives = int(torch.sum(entity_mask).item() * self.hard_negative_ratio)
 if num_hard_negatives == 0:
 num_hard_negatives = int(torch.sum(non_entity_mask).item() * 0.1)

 # 关键修改：将损失展平为一维
 non_entity_loss_flat = non_entity_loss.view(-1)

 # 关键修改：确保 k 不超过非实体 token 的总数
 num_non_entities = torch.sum(non_entity_mask).item()
 k = min(num_hard_negatives, num_non_entities)

 if k == 0: # 如果没有负样本可选，则损失为 0
 non_ner_loss_mean = torch.tensor(0.0, device=logits.device)
 else:
 topk_losses, _ = torch.topk(non_entity_loss_flat, k=k)
 non_ner_loss_mean = torch.mean(topk_losses)

 total_loss = self.entity_weight * ner_loss_mean + 1.0 * non_ner_loss_mean
 return total_loss, ner_loss_mean.detach(), non_ner_loss_mean.detach()

4.2.3 更新配置文件

接着，需要在 src/configs/configs.py 中添加几个参数，以便能够灵活地选择和配置损失函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# code/C8/src/configs/configs.py

# ...
 learning_rate: float = 1e-3
 device: str = field(default_factory=lambda: 'cuda' if torch.cuda.is_available() else 'cpu')

 # --- 损失函数参数 ---
 loss_type: str = "weighted_ce" # 可选: "cross_entropy", "weighted_ce", "hard_negative_mining"
 entity_loss_weight: float = 10.0 # 在 weighted_ce 和 hard_negative_mining 中, 给实体部分损失的权重
 hard_negative_ratio: float = 0.5 # 在 hard_negative_mining 中, 负样本数量与正样本数量的比例

 # --- 模型参数 ---
# ...

4.2.4 修改训练器

为了处理 NerLoss 返回的多个损失值，并优化训练日志，需要对 src/trainer/trainer.py 进行升级。

主要的修改点包括：

仅用“主损”反向传播（若为元组损失，取 loss[0]）。
训练阶段累计并返回三元组（总损/实体/非实体）。
评估阶段用“主损”统计验证集 loss。
保存最优模型以 {'model_state_dict': ...} 方式，便于 06_predict.py 直接加载。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112


# code/C8/src/trainer/trainer.py

# ... (省略未修改部分)
from tqdm import tqdm
import os
import torch

class Trainer:
 # ... (省略 __init__ 等)

 def fit(self, epochs):
 os.makedirs(self.output_dir, exist_ok=True)
 best_metric = float('-inf') # 优先最大化 F1
 for epoch in range(1, epochs + 1):
 print(f"--- Epoch {epoch}/{epochs} ---")
 train_losses = self._train_one_epoch()
 # 支持元组损失的日志打印（总损/实体/非实体）
 if isinstance(train_losses, tuple):
 train_loss_str = (
 f"Train Total Loss: {train_losses[0]:.4f}, "
 f"NER Loss: {train_losses[1]:.4f}, "
 f"Non-NER Loss: {train_losses[2]:.4f}"
 )
 else:
 train_loss_str = f"Train Total Loss: {train_losses:.4f}"
 print(train_loss_str)

 eval_metrics = self._evaluate()
 eval_metrics_str = ", ".join([f"{k}: {v:.4f}" for k, v in eval_metrics.items()])
 print(f"Validation Metrics: {eval_metrics_str}")

 # 以验证集 F1 作为保存准则；无 F1 时回退用 loss
 is_best = False
 if 'f1' in eval_metrics:
 if eval_metrics['f1'] > best_metric:
 best_metric = eval_metrics['f1']
 is_best = True
 else:
 if best_metric == float('-inf'):
 best_metric = float('inf')
 if eval_metrics['loss'] < best_metric:
 best_metric = eval_metrics['loss']
 is_best = True

 if is_best:
 print(f"New best model found! Saving to {self.output_dir}")
 # 以字典方式保存，键为 'model_state_dict'，便于 06_predict.py 加载
 torch.save({'model_state_dict': self.model.state_dict()},
 os.path.join(self.output_dir, "best_model.pth"))

 def _train_one_epoch(self):
 self.model.train()
 total_loss_sum = 0
 total_ner_loss = 0
 total_non_ner_loss = 0
 custom_loss_used = False

 for batch in tqdm(self.train_loader, desc=f"Training Epoch"):
 outputs = self._train_step(batch)
 loss = outputs['loss']
 if isinstance(loss, tuple):
 # 支持元组损失（总损/实体/非实体）并分别累计
 custom_loss_used = True
 total_loss_sum += loss[0].item()
 total_ner_loss += loss[1].item()
 total_non_ner_loss += loss[2].item()
 else:
 total_loss_sum += loss.item()

 if custom_loss_used:
 # 返回三元组 (avg_total, avg_ner, avg_non_ner)
 avg_loss = total_loss_sum / len(self.train_loader)
 avg_ner_loss = total_ner_loss / len(self.train_loader)
 avg_non_ner_loss = total_non_ner_loss / len(self.train_loader)
 return avg_loss, avg_ner_loss, avg_non_ner_loss
 else:
 return total_loss_sum / len(self.train_loader)

 def _train_step(self, batch):
 # ... (省略前向部分)
 logits = self.model(token_ids=batch['token_ids'], attention_mask=batch['attention_mask'])
 loss = self.loss_fn(logits.permute(0, 2, 1), batch['label_ids'])
 # 仅用主损进行反向传播（元组时取 loss[0]）
 main_loss = loss[0] if isinstance(loss, tuple) else loss
 self.optimizer.zero_grad()
 main_loss.backward()
 self.optimizer.step()
 return {'loss': loss, 'logits': logits}

 def _evaluate(self):
 if self.dev_loader is None:
 return None
 self.model.eval()
 total_loss = 0
 all_logits, all_labels, all_attention_mask = [], [], []
 with torch.no_grad():
 for batch in tqdm(self.dev_loader, desc="Evaluating"):
 outputs = self._evaluation_step(batch)
 loss = outputs['loss']
 # 验证 loss 也使用主损统计
 main_loss = loss[0] if isinstance(loss, tuple) else loss
 total_loss += main_loss.item()
 all_logits.append(outputs['logits'].cpu())
 all_labels.append(batch['label_ids'].cpu())
 all_attention_mask.append(batch['attention_mask'].cpu())
 metrics = {}
 if self.eval_metric_fn:
 metrics = self.eval_metric_fn(all_logits, all_labels, all_attention_mask)
 metrics['loss'] = total_loss / len(self.dev_loader)
 return metrics

 # ... (其余方法保持不变)

4.2.5 集成到主函数

最后一步，在 05_train.py 中根据配置来实例化对应的损失函数。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# code/C8/05_train.py

# ...
from src.loss.ner_loss import NerLoss # 导入新模块

# ... (在main函数中)
 # --- 3. 初始化模型、优化器、损失函数 ---
 model = BiGRUNerNetWork(...)
 optimizer = torch.optim.AdamW(...)

 # 根据配置选择损失函数
 if config.loss_type == "cross_entropy":
 loss_fn = nn.CrossEntropyLoss(ignore_index=-100)
 else:
 loss_fn = NerLoss(
 loss_type=config.loss_type,
 entity_weight=config.entity_loss_weight,
 hard_negative_ratio=config.hard_negative_ratio
 )
# ...

完成以上步骤后，就可以通过简单地修改 configs.py 中的 loss_type 参数，来切换不同的损失函数策略，并观察它们对模型训练效果的影响。例如，将 loss_type 设置为 "weighted_ce"，然后重新运行 05_train.py，会看到训练日志中包含了实体和非实体各自的损失值。

4.2.6 解读验证集损失

在使用自定义损失函数（尤其是 weighted_ce 和 hard_negative_mining）时，你可能会观察到一个现象：验证集上的 F1 分数在稳步提升，但 loss 值却停滞不前甚至上升。这是一个正常且符合预期的现象。

这是因为 Trainer 在评估阶段同样使用了这个自定义的、加权的损失函数来计算验证集 loss。这个 loss 主要反映的是训练目标的优化情况，而不是一个标准的评估指标。

权重影响: 由于实体部分的损失被赋予了很高的权重（例如 entity_loss_weight=10.0），少数几个实体相关的错误就会导致 loss 值大幅波动或居高不下。
硬负样本挖掘影响: hard_negative_mining 策略会动态地聚焦于模型最容易搞错的那些非实体 O 标签。随着训练的进行，简单的负样本损失会降低，但模型会转而面对更“棘手”的硬样本，导致计算出的 non_ner_loss 可能不会持续下降。

因此，当使用这些高级损失策略时，验证集 loss 不再是衡量模型好坏的主要标准。应将注意力更多地放在能够直接反映任务最终目标的指标上，对于 NER 任务而言，这个指标就是实体级别的 F1 分数。这也是 Trainer 将 F1 作为保存最佳模型依据的原因。

五、优化训练工作流

在我们实现了核心的训练、评估与推理流程之后，一个健robustness的训练框架还需要更多辅助功能来应对真实场景中的各种挑战。本节将介绍如何为 Trainer 集成三项关键的实用功能：可视化日志、提前停止和断点续训，让训练过程更加可控、高效和可靠。

5.1 训练过程可视化

纯文本的训练日志虽然直接，但难以洞察模型训练的全局动态。为了更直观地监控训练过程，例如观察损失是否平稳下降、验证集 F1 是否持续提升，以及模型是否出现过拟合迹象，可以集成 TensorBoard 来实现可视化；同时，为提高结果的可复现性，建议在训练开始前固定随机数种子。

为了将日志记录功能模块化，可以创建一个专门的 TensorBoardLogger 类来封装所有与 SummaryWriter 相关的操作。

创建 TensorBoardLogger 类:

在 src/utils/ 目录下创建 logger.py 文件。这个类将负责 SummaryWriter 的初始化、指标记录和关闭。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# code/C8/src/utils/logger.py
from torch.utils.tensorboard import SummaryWriter

class TensorBoardLogger:
 def __init__(self, log_dir):
 # 如果提供了日志目录，则初始化 SummaryWriter
 self.writer = SummaryWriter(log_dir) if log_dir else None

 def log_metrics(self, metrics, step, prefix):
 # 如果 writer 未初始化，则不执行任何操作
 if self.writer is None: return

 # 根据 metrics 类型（元组或字典）以不同方式记录
 if isinstance(metrics, tuple):
 self.writer.add_scalar(f"{prefix}/Total_Loss", metrics[0], step)
 if len(metrics) > 1:
 self.writer.add_scalar(f"{prefix}/NER_Loss", metrics[1], step)
 self.writer.add_scalar(f"{prefix}/Non-NER_Loss", metrics[2], step)
 elif isinstance(metrics, dict):
 for k, v in metrics.items():
 self.writer.add_scalar(f"{prefix}/{k.capitalize()}", v, step)

 def close(self):
 # 确保在训练结束时关闭 writer，将所有挂起的事件写入磁盘
 if self.writer:
 self.writer.close()

在 configs.py 中添加配置:

1
2
3
4
5
6
7
8
9


# code/C8/src/configs/configs.py

# ... (省略)
class NerConfig:
 # ... (省略)
 # --- 增强功能参数 ---
 output_summary_dir: str = "output/logs" # TensorBoard 日志输出路径
 seed: int = 42 # 随机数种子（用于可复现性）
# ... (省略)

在 Trainer 中使用 TensorBoardLogger:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# code/C8/src/trainer/trainer.py
from src.utils.logger import TensorBoardLogger

class Trainer:
 def __init__(self, ..., summary_writer_dir=None, ...):
 # ... (省略其他初始化)
 # 初始化日志记录器
 self.logger = TensorBoardLogger(summary_writer_dir)

 def fit(self, epochs):
 for epoch in range(self.start_epoch, epochs + 1):
 # ... (训练与评估)

 # 在每个 epoch 结束后调用 logger 记录训练和验证指标
 self.logger.log_metrics(train_losses, epoch, "Train")
 self.logger.log_metrics(eval_metrics, epoch, "Validation")

 # 训练结束后关闭 logger
 self.logger.close()

添加随机数种子

为了使可视化对比与调参更稳定可复现，建议在训练启动时固定随机数种子，读取 configs.py 中新增的 seed 配置。

在 05_train.py 中添加工具函数并调用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# code/C8/05_train.py
# ... 省略导入

def seed_everything(seed: int = 42):
 torch.manual_seed(seed)
 if torch.cuda.is_available():
 torch.cuda.manual_seed_all(seed)
 torch.backends.cudnn.deterministic = True
 torch.backends.cudnn.benchmark = False

def main():
 # 训练前设置随机种子（读取 configs.py 的 seed）
 seed_everything(getattr(config, 'seed', 42))
 # ... 后续组件初始化与训练

5.2 早停实现

为了让这个逻辑更清晰且可复用，可将其封装到一个独立的 EarlyStopping 类中，这个类就像一个“回调”一样，在每个 epoch 结束时被 Trainer 调用来检查是否需要停止。

创建 EarlyStopping 工具类:

在 src/utils/ 目录下创建一个新文件 early_stop.py。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# code/C8/src/utils/early_stop.py
import numpy as np

class EarlyStopping:
 def __init__(self, patience=5, verbose=False, delta=0, monitor='f1', mode='max'):
 self.patience = patience # 耐心值：连续多少轮性能没有提升则停止
 self.verbose = verbose # 是否打印日志
 self.counter = 0 # 计数器
 self.best_score = None # 历史最佳分数
 self.early_stop = False # 提前停止标志
 self.val_metric_best = np.inf if mode == 'min' else -np.inf # 根据模式初始化最佳指标
 self.delta = delta # 容忍的性能下降范围
 self.monitor = monitor # 监控的指标
 self.mode = mode # 'max' 或 'min'

 def __call__(self, val_metric):
 # 根据 'mode' 调整分数计算方式
 score = -val_metric if self.mode == 'min' else val_metric

 if self.best_score is None:
 self.best_score = score
 # 如果当前分数没有超过（最佳分数 + delta），则增加计数器
 elif score < self.best_score + self.delta:
 self.counter += 1
 if self.verbose:
 print(f'EarlyStopping counter: {self.counter} out of {self.patience}')
 if self.counter >= self.patience:
 self.early_stop = True
 # 如果分数有提升，则更新最佳分数并重置计数器
 else:
 self.best_score = score
 self.counter = 0
 return self.early_stop

在 configs.py 中添加配置:

1
2
3
4


# code/C8/src/configs/configs.py

# ... (省略)
early_stopping_patience: int = 5 # 提前停止的耐心轮数

在 Trainer 中集成 EarlyStopping 实例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# code/C8/src/trainer/trainer.py
from src.utils.early_stop import EarlyStopping

class Trainer:
 def __init__(self, ..., early_stopping_patience=5, ...):
 # ... (省略其他初始化)
 # 初始化 EarlyStopping 回调
 self.early_stopping = EarlyStopping(
 patience=early_stopping_patience,
 verbose=True,
 monitor='f1'
 )

 def fit(self, epochs):
 for epoch in range(self.start_epoch, epochs + 1):
 # ... (训练与评估)

 current_metric = eval_metrics.get('f1', -eval_metrics.get('loss', float('inf')))

 # ... (保存最佳模型逻辑)

 # 调用 early_stopping 实例判断是否需要停止
 if self.early_stopping(current_metric):
 print("Early stopping triggered.")
 break # 跳出训练循环

5.3 实现断点续训

对于需要数小时甚至数天的长时间训练任务，意外中断（如断电、程序崩溃）是常见风险。从头开始训练会造成巨大的时间浪费。断点续训 (Checkpointing & Resuming) 机制允许我们保存训练过程中的完整状态（包括模型权重、优化器状态和当前轮数），并在需要时从中恢复，继续训练。

实现此功能主要分为三步：首先添加配置项，然后在 Trainer 中构建核心的保存与恢复逻辑，最后在主训练脚本中启用它。

在 configs.py 中添加配置:

首先，在 NerConfig 中增加一个 resume_checkpoint 字段，用于指定需要恢复的检查点文件路径。如果它为 None，则从头开始训练。
1 2 3 4

# code/C8/src/configs/configs.py # ... (其他配置) # 用于恢复训练的检查点路径, e.g., "output/last_model.pth" resume_checkpoint: str = None

为 Trainer 新增保存与恢复能力:

接下来，为 Trainer 类赋予保存和恢复检查点的能力。这包括新增两个核心方法 _save_checkpoint 和 _resume_checkpoint，并修改 __init__ 和 fit 方法来调用它们。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# code/C8/src/trainer/trainer.py

class Trainer:
 def __init__(self, ..., resume_checkpoint=None, ...):
 # ...
 self.start_epoch = 1 # 默认从第一轮开始
 # ...
 # 如果指定了检查点路径，则调用恢复方法
 if resume_checkpoint:
 self._resume_checkpoint(resume_checkpoint)

 def fit(self, epochs):
 # 使用 self.start_epoch 替换固定的 `1`，以支持从指定轮数开始
 for epoch in range(self.start_epoch, epochs + 1):
 # ... (训练和评估)

 # --- 保存逻辑 ---
 is_best = False
 current_metric = eval_metrics.get('f1', -eval_metrics.get('loss', float('inf')))
 if current_metric > self.best_metric:
 self.best_metric = current_metric
 is_best = True

 # 在每轮结束后都保存检查点
 self._save_checkpoint(epoch, is_best)

 # ... (早停逻辑)

 # 调用 early_stopping 实例判断是否需要停止
 if self.early_stopping(current_metric):
 print("Early stopping triggered.")
 break # 跳出训练循环

这里有几个关键点：

__init__ 中会检查 resume_checkpoint，如果提供了路径，就调用恢复方法。
fit 方法的循环 for epoch in range(1, epochs + 1) 需要修改为 for epoch in range(self.start_epoch, epochs + 1)，以便从恢复的轮数继续训练。
fit 方法在每轮结束时调用 _save_checkpoint 来保存当前状态。

在 05_train.py 中启用并校验:

最后，在主训练脚本中，我们需要在初始化 Trainer 之前，先检查配置文件中 resume_checkpoint 指定的路径是否有效。如果路径无效，就将其置为 None，以确保 Trainer 能够安全地从头开始训练，而不是因找不到文件而报错。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# code/C8/05_train.py

# ... (省略前半部分)

# 在初始化 Trainer 前，检查检查点文件是否存在
if config.resume_checkpoint and not os.path.exists(config.resume_checkpoint):
 print(f"Checkpoint file not found: {config.resume_checkpoint}. Starting training from scratch.")
 config.resume_checkpoint = None # 设为 None, 避免 Trainer 报错

trainer = Trainer(
 # ...
 resume_checkpoint=config.resume_checkpoint
)

5.4 更新主训练脚本

完成了对 Trainer 的升级并将日志、早停等功能模块化后，最后一步是在主训练脚本 05_train.py 中，将相应的配置参数传递给 Trainer 实例，从而正式启用这些新功能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# code/C8/05_train.py

# ... (省略前半部分代码)

# --- 5. 初始化并启动训练器 ---
trainer = Trainer(
 model=model,
 optimizer=optimizer,
 loss_fn=loss_fn,
 train_loader=train_loader,
 dev_loader=dev_loader,
 eval_metric_fn=eval_metric_fn,
 output_dir=config.output_dir,
 device=config.device,
 # 传入新增的配置参数，以启用对应的功能
 summary_writer_dir=config.output_summary_dir, # TensorBoard 日志目录
 early_stopping_patience=config.early_stopping_patience, # 早停耐心轮数
 resume_checkpoint=config.resume_checkpoint # 断点续训的检查点路径
)

# ... (省略后半部分代码)

本章小结

回顾整个流程，一个完整的命名实体识别项目已经从零开始被系统性地构建出来。整个过程贯穿了从数据处理、模型构建到训练优化与最后推理的全流程：

数据处理与准备：首先解析原始的 CMeEE 数据集，构建了全局统一的 BMES 标签映射 (categories.json) 和字符级词汇表 (vocabulary.json)，并最终封装成一个高效、可复用的 DataLoader，为模型训练提供了标准化的数据输入。
模型构建与训练框架：设计并实现了一个基于 Bi-GRU 的序列标注模型，并围绕它打造了一个结构清晰、组件化的训练框架。通过将模型、数据加载器、分词器、评估指标等核心功能解耦，构建了一个易于维护和扩展的 Trainer 类。
推理与工作流优化：实现从模型输出到结构化实体的解码逻辑，并将其封装成一个开箱即用的 NerPredictor 推理器。同时，为了提升训练框架的健壮性和实用性，还集成了自定义损失函数来应对数据不均衡问题，并引入了 TensorBoard 可视化日志、提前停止（Early Stopping）和断点续训（Checkpointing）等高级功能。

通过以上步骤，不仅实现了一个能跑通的 NER 模型，更重要的是搭建起了一套模块化、功能完备的 NER 项目脚手架。尽管当前基线模型的性能可能还有提升空间，但这个框架为后续探索更先进的模型（如 BERT）、尝试更复杂的策略提供了不错的起点。

参考文献

微调 BERT 模型进行文本分类

Wed, 25 Mar 2026 18:34:25 -0800

微调 BERT 模型进行文本分类

回顾前两节的内容，我们依次实现了一个基于全连接网络的“词袋”模型和一个基于 LSTM 的序列模型。这两次的运行结果揭示了一个有趣的现象，对于当前的新闻分类任务，结构更复杂的 LSTM 模型在性能上并未超越更简单的全连接模型。这说明，对于这个特定任务，捕捉“关键词”比分析“词序”更关键。不过，这两种模型都是从零开始训练的，它们对语言的理解完全依赖于我们提供的小规模 20 Newsgroups 数据集。那么我们能否利用在更大、更通用语料库上预先学到的知识，来帮助模型更好地理解文本，从而提升分类性能呢？

这就是预训练语言模型，特别是 BERT，所要解决的问题。在第五章第一节中，我们已经学习了 BERT 的原理。它通过在海量原始文本上以自监督的方式构造“掩码语言模型”和“下一句预测”等训练任务（无需人工标注标签），学习到了丰富的语言学知识和世界知识。本节是文本分类系列实战的最后一站。我们将把模型架构迁移为 BERT，探索从“从零训练”到“微调”这一范式转变所带来的性能提升。

一、从“序列建模”到“预训练微调”

回顾前两个模型，它们的核心都是在特定任务数据上从随机初始化的词向量开始学习如何进行分类。而基于 BERT 的微调则采用了一种完全不同的范式，通常包含以下三个步骤：

（1）加载预训练权重：我们不再随机初始化模型，而是加载一个已经在海量数据（如维基百科、书籍）上训练好的 BERT 模型。这个模型已经是一个通用的“语言理解专家”。

（2）附加任务相关的“头”：在 BERT 模型的主体结构之上，我们添加一个简单的、未经训练的分类层（通常就是一个全连接层）。

（3）在下游任务上“微调”：使用我们的新闻分类数据，对整个模型（或者仅仅是顶部的分类层）进行训练。由于 BERT 部分已经具备了强大的语言理解能力，整个模型可以很快地适应新的分类任务，并且通常只需要很少的训练轮次和较小的学习率。

这个“预训练-微调”的范式是现代 NLP 领域最主流、最有效的方法之一。它大大降低了对特定任务标注数据的依赖，并显著提升了模型性能的上限。

二、代码修改实践

将 LSTM 模型改造为 BERT 模型，同样遵循之前的思路，主要修改涉及数据处理和模型结构，同时也要相应地调整训练超参数。

本节完整代码

2.1 替换为 `BertTokenizer`

现在我们不需要手动构建词典。transformers 库为每个预训练模型都提供了配套的 Tokenizer。对于英文 20 Newsgroups 数据集，选择 bert-base-uncased 模型及其对应的分词器。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from transformers import BertTokenizer

bert_model_name = 'bert-base-uncased'
tokenizer = BertTokenizer.from_pretrained(bert_model_name)

# 查看特殊token
print(f"UNK token: '{tokenizer.unk_token}', ID: {tokenizer.unk_token_id}")
print(f"PAD token: '{tokenizer.pad_token}', ID: {tokenizer.pad_token_id}")
print(f"CLS token: '{tokenizer.cls_token}', ID: {tokenizer.cls_token_id}")
print(f"SEP token: '{tokenizer.sep_token}', ID: {tokenizer.sep_token_id}")
print(f"Vocab size: {tokenizer.vocab_size}")

输出：

1
2
3
4
5


UNK token: '[UNK]', ID: 100
PAD token: '[PAD]', ID: 0
CLS token: '[CLS]', ID: 101
SEP token: '[SEP]', ID: 102
Vocab size: 30522

BertTokenizer 会自动处理文本的预处理（如小写转换、标点分割），并为文本添加特殊的 [CLS] 和 [SEP] 标记。其中，[CLS] 位于序列开头，它在 BERT 输出中对应的向量通常被用作整个序列的聚合表示，非常适合用于分类任务；[SEP] 用于分隔两个句子，在单句分类任务中标志着句子的结束。

2.2 改造 `Dataset` 与 `collate_fn`

为了适配 BERT，数据处理流程需要进行如下调整：

（1）Dataset: BertTextClassificationDataset 现在直接调用 BertTokenizer 来进行分词和ID转换。处理长文本的滑窗分割逻辑保持不变。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class BertTextClassificationDataset(Dataset):
 def __init__(self, texts, labels, tokenizer, max_len=128):
 self.tokenizer = tokenizer
 self.max_len = max_len
 self.processed_data = []

 for text, label in tqdm(zip(texts, labels), total=len(labels), desc="Processing Dataset"):
 # 直接使用BertTokenizer进行编码
 encoding = self.tokenizer(text, add_special_tokens=True, truncation=False)
 input_ids = encoding['input_ids']

 # 滑窗分割逻辑保持不变
 if len(input_ids) <= self.max_len:
 self.processed_data.append({"input_ids": input_ids, "label": label})
 else:
 stride = max(1, int(self.max_len * 0.8))
 for i in range(0, len(input_ids) - self.max_len + 1, stride):
 chunk = input_ids[i:i + self.max_len]
 self.processed_data.append({"input_ids": chunk, "label": label})
 ...

（2）collate_fn: BERT 的一个重要输入是 attention_mask（注意力掩码）。它是一个与 input_ids 形状相同的张量，用 1 标记真实 Token，用 0 标记填充（Padding）的 Token。模型会根据这个掩码，在计算注意力时忽略填充部分。所以，我们需要修改 collate_fn 以生成并返回 attention_mask。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


def bert_collate_fn(batch):
 max_batch_len = max(len(item["input_ids"]) for item in batch)

 batch_input_ids, batch_attention_masks, batch_labels = [], [], []

 for item in batch:
 input_ids = item["input_ids"]
 padding_len = max_batch_len - len(input_ids)

 padded_ids = input_ids + [tokenizer.pad_token_id] * padding_len
 # 新增：生成 attention_mask
 attention_mask = [1] * len(input_ids) + [0] * padding_len

 batch_input_ids.append(padded_ids)
 batch_attention_masks.append(attention_mask)
 batch_labels.append(item["label"])

 return {
 "input_ids": torch.tensor(batch_input_ids, dtype=torch.long),
 # 新增：返回 attention_mask
 "attention_mask": torch.tensor(batch_attention_masks, dtype=torch.long),
 "labels": torch.tensor(batch_labels, dtype=torch.long),
 }

2.3 构建 `TextClassifierBERT` 模型

得益于 transformers 库的高度封装，从代码实现的角度来看，新的模型结构非常简洁，一个预训练的 BERT 主干网络 + 一个线性分类头。尽管 BERT 模型内部结构极其复杂，但我们只需几行代码便可调用。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


from transformers import BertModel

class TextClassifierBERT(nn.Module):
 def __init__(self, model_name, num_classes, freeze_bert=False):
 super(TextClassifierBERT, self).__init__()
 # 1. 加载预训练的BERT模型
 self.bert = BertModel.from_pretrained(model_name)
 # 2. 定义分类头
 self.classifier = nn.Linear(self.bert.config.hidden_size, num_classes)

 # 3. (可选) 冻结BERT参数
 if freeze_bert:
 for param in self.bert.parameters():
 param.requires_grad = False

 def forward(self, input_ids, attention_mask):
 # 将输入传入BERT
 outputs = self.bert(input_ids=input_ids, attention_mask=attention_mask)

 # 使用[CLS] token的输出(pooler_output)进行分类
 pooled_output = outputs.pooler_output

 # 传入分类头得到logits
 logits = self.classifier(pooled_output)
 return logits

在 __init__ 方法中，BertModel.from_pretrained(model_name) 会自动下载并加载指定名称的预训练模型权重。分类头的输入维度直接从 self.bert.config.hidden_size 获取，这是一个非常好的实践，避免了硬编码。此外提供了 freeze_bert 选项，如果为 True，则 BERT 部分的参数不会在训练中更新。这被称为“特征提取”模式，训练速度更快，但效果通常不如全量微调。实战中还可以更细粒度地“冻结”部分层（例如仅冻结 Embedding 和前几层 Transformer Block，或按层号前缀选择参数，将其 requires_grad=False），在训练速度 / 显存占用与微调效果之间做折中，这里为了示例清晰，仅展示了“全部冻结 BERT 主干”这一简单形式。而在 forward 函数中，现在接收 input_ids 和 attention_mask。BERT 模型的输出 outputs 中，outputs.pooler_output 是 [CLS] Token 对应的隐藏状态经过进一步处理后得到的向量，专门用于句子级别的任务，我们直接取用这个向量送入分类层即可。

2.4 调整 `Trainer` 与 `Predictor`

Trainer 的 _run_epoch 和 _evaluate 方法需要修改，以将 attention_mask 传递给模型。同时，保存模型的逻辑也应更新为 transformers 推荐的方式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 在 Trainer._run_epoch 方法中
...
input_ids = batch["input_ids"].to(self.device)
attention_mask = batch["attention_mask"].to(self.device) # 新增
labels = batch["labels"].to(self.device)

outputs = self.model(input_ids=input_ids, attention_mask=attention_mask) # 修改
...

# 在 Trainer._save_checkpoint 方法中
...
# 对于transformers模型，推荐使用save_pretrained来保存
self.model.bert.save_pretrained(self.output_dir)
# 单独保存分类头
classifier_path = os.path.join(self.output_dir, "classifier.pth")
torch.save(self.model.classifier.state_dict(), classifier_path)
...

另外，别忘了在训练脚本中将 tokenizer 一并保存到同一个目录，方便推理阶段直接从该目录恢复分词器配置与词表，例如：

1
2


# 训练脚本中
tokenizer.save_pretrained(hparams["output_dir"])

Predictor 的逻辑与 LSTM 版本非常相似，同样采用分块+投票的策略。主要区别在于，现在需要为每个 chunk 创建对应的 attention_mask。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 在 Predictor.predict 方法中
...
# (分块逻辑不变)...
padded_chunks, attention_masks = [], []
for chunk in chunks:
 padding_len = max_chunk_len - len(chunk)
 padded_chunks.append(chunk + [self.tokenizer.pad_token_id] * padding_len)
 attention_masks.append([1] * len(chunk) + [0] * padding_len) # 新增

input_ids_tensor = torch.tensor(padded_chunks, dtype=torch.long).to(self.device)
attention_mask_tensor = torch.tensor(attention_masks, dtype=torch.long).to(self.device) # 新增

with torch.no_grad():
 # 将input_ids和attention_mask都传入
 outputs = self.model(input_ids=input_ids_tensor, attention_mask=attention_mask_tensor)
 preds = torch.argmax(outputs, dim=1)
...
# (投票逻辑不变)

2.5 更新训练超参数

微调 BERT 时，超参数的选择与从零训练有很大不同。学习率通常设置得非常小，例如 2e-5 到 5e-5 之间，这是因为我们希望在预训练学到的知识基础上做“微小”的调整，过大的学习率会破坏这些知识。至于训练轮次通常只需要 3-5 个轮次就足以收敛。

1
2
3
4
5
6
7
8
9


hparams = {
 "model_name": 'bert-base-uncased',
 "num_classes": len(train_dataset_raw.target_names),
 "freeze_bert": False,
 "epochs": 5, # 减少轮次
 "learning_rate": 2e-5, # 降低学习率
 "device": "cuda" if torch.cuda.is_available() else "cpu",
 "output_dir": "output_bert"
}

2.6 推理阶段资源加载

推理阶段的整体流程与 LSTM 版本保持一致，但在加载推理所需资源时有几个容易忽略的细节。训练时我们使用 save_pretrained 将 BERT 主干和 tokenizer 一并保存到 output_bert 目录，所以推理阶段不需要手动构建或加载词表，可以应该直接从该目录恢复。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


labels_path = os.path.join(hparams["output_dir"], "label_map.json")
with open(labels_path, "r", encoding="utf-8") as f:
 label_map_loaded = json.load(f)

inference_tokenizer = BertTokenizer.from_pretrained(hparams["output_dir"])

inference_model = TextClassifierBERT(
 model_name=hparams["output_dir"],
 num_classes=len(label_map_loaded),
).to(hparams["device"])

classifier_path = os.path.join(hparams["output_dir"], "classifier.pth")
inference_model.classifier.load_state_dict(
 torch.load(classifier_path, map_location=hparams["device"])
)

这里有两个关键点：

通过 BertTokenizer.from_pretrained 从输出目录一次性恢复完整的分词器配置与词表，无需手动加载独立的 vocab 文件；
TextClassifierBERT 的 model_name 也改为输出目录，从而加载微调后的 BERT 权重。

三、实验结果与分析

完成所有改造后，我们启动训练。由于 BERT 模型参数量远大于之前的模型（bert-base-uncased 约有1.1亿参数），每个 epoch 的训练时间会更长，对计算资源（特别是 GPU 显存）的要求也更高。下面是本次实验的训练日志：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


Epoch 1 [训练中]: 100%|██████████| 625/625 [01:53<00:00, 5.53it/s]
Epoch 1 [评估中]: 100%|██████████| 467/467 [00:29<00:00, 16.02it/s]
Epoch 1/5 | 训练损失: 0.4214 | 验证集准确率: 0.8738
新最佳模型已保存! Epoch: 1, 验证集准确率: 0.8738
Epoch 2 [训练中]: 100%|██████████| 625/625 [02:14<00:00, 4.64it/s]
Epoch 2 [评估中]: 100%|██████████| 467/467 [00:31<00:00, 14.84it/s]
Epoch 2/5 | 训练损失: 0.1495 | 验证集准确率: 0.8827
新最佳模型已保存! Epoch: 2, 验证集准确率: 0.8827
Epoch 3 [训练中]: 100%|██████████| 625/625 [02:18<00:00, 4.51it/s]
Epoch 3 [评估中]: 100%|██████████| 467/467 [00:31<00:00, 14.66it/s]
Epoch 3/5 | 训练损失: 0.0698 | 验证集准确率: 0.8915
新最佳模型已保存! Epoch: 3, 验证集准确率: 0.8915
Epoch 4 [训练中]: 100%|██████████| 625/625 [02:20<00:00, 4.46it/s]
Epoch 4 [评估中]: 100%|██████████| 467/467 [00:32<00:00, 14.44it/s]
Epoch 4/5 | 训练损失: 0.0404 | 验证集准确率: 0.8946
新最佳模型已保存! Epoch: 4, 验证集准确率: 0.8946
Epoch 5 [训练中]: 100%|██████████| 625/625 [02:22<00:00, 4.37it/s]
Epoch 5 [评估中]: 100%|██████████| 467/467 [00:32<00:00, 14.48it/s]
Epoch 5/5 | 训练损失: 0.0251 | 验证集准确率: 0.9032
新最佳模型已保存! Epoch: 5, 验证集准确率: 0.9032
训练完成！
Tokenizer 和标签映射 (output_bert\label_map.json) 已保存。

图 7-6 BERT 模型训练损失与验证集准确率变化曲线

我们将三个模型的最佳性能进行对比：

全连接模型 (基线)：最佳验证集准确率 ~0.8469。
LSTM 模型 (正则化后)：最佳验证集准确率 ~0.8415。
BERT 微调模型：最佳验证集准确率 ~0.9032。

结果分析:

通过日志可以看出，BERT 模型的性能远超前两个从零开始训练的模型。具体来看，BERT的优势体现在以下几点：

（1）性能上限更高：BERT 微调模型最终达到了约 90.32% 的准确率，比之前两个模型高出超过 5 个百分点，这是一个显著的提升。

（2）收敛速度快：仅仅在第一个 epoch 结束后，BERT 模型的准确率（87.38%）就已经超过了前两个模型经过 20 个 epoch 充分训练后的最佳水平。

（3）强大的上下文理解能力：BERT 的核心是 Transformer 的自注意力机制，它能够捕捉句子中任意两个词之间的依赖关系，无论它们相隔多远。使得 BERT 能够生成真正“上下文相关”的词向量，深刻理解词语在不同语境下的含义。

（4）海量预训练知识的迁移：BERT 在预训练阶段已经学习了丰富的语法、语义和世界知识。在微调时，这些知识被有效地迁移到了下游的新闻分类任务中。模型不再是一个“新生儿”，而是一个知识渊博的“专家”，只需要少量数据就能学会如何应用已有知识来完成新任务。

（5）成熟的范式：相比于需要精心设计网络结构、调整正则化策略的从零训练，BERT 的“预训练-微调”范式更加成熟和标准化。它为各种 NLP 任务提供了一个更高的起点，通过这种方式我们能够用相对少的代码和调试，就达到了出色的效果。

这个结果初看似乎与上一节“如无必要，勿增实体”的结论有所矛盾。但这并不意味着奥卡姆剃刀原理失效了，而是提醒我们要在正确的维度上应用它。当然，这并不绝对否定简单模型（如全连接或 LSTM）通过更精细的特征工程、算法优化和超参数调优，有可能在特定任务上接近甚至超越 BERT 的效果。但是，那通常需要耗费巨大的精力。相比之下，BERT 的成功揭示了“预训练-微调”范式的巨大优势。一方面它具备强大的预训练知识，BERT 不是从零学习，而是将从海量文本中学到的通用语言知识迁移到了我们的任务中，所以它对词汇和语境的理解深度远超任何从头训练的模型。另一方面它是一条更便捷的路径，我们不再需要为特定任务从头设计复杂的网络或特征，而是可以方便地在一个强大的通用模型基础上进行微调，用更少的努力达到更高的性能上限。

所以，这里的结论并非“模型越复杂越好”，而是“利用高质量的预训练模型进行微调，往往是一种在下游任务中以更少的开发精力和数据量达成更好性能的推荐方式”。与此同时，我们也必须认识到，微调所带来的便捷和高效，是建立在 BERT 等大模型在预训练阶段已经消耗了巨大计算资源和时间的基础之上的。

本章小结

综合三节的实践，我们完成了一次 NLP 文本分类任务的探索之旅。整个过程为我们提供了宝贵的实践经验，并最终指向一个现代 NLP 项目中进行模型选择与迭代的常用流程：

（1）从一个简单、快速的基线模型开始（如第一节的全连接模型）。建立基线有助于我们评估任务的难度，并为后续的优化提供一个比较标准。

（2）审慎地增加模型的复杂性。第二节的实验证明，对于特定任务，更复杂的结构（从零训练的LSTM）未必能带来性能提升，其结果恰好印证了“奥卡姆剃刀原理”。

（3）优先考虑利用高质量的预训练模型进行微调。当基线模型无法满足需求时，与其从零开始构建更复杂的模型，不如优先采用“预训练-微调”的范式。第三节的实验清晰地展示了，采用此范式通常是通往较优性能的高效路径。

整个探索过程也侧面反映了 NLP 技术的发展脉络，也提供了一个更全面、辩证的实践准则，帮助我们在未来的项目中做出更明智的技术选型。

附录——使用BERT实现中文文本情感分类

参考资料：

微调BERT模型实现文本分类

BERT文本处理——Tokenizer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


from transformers import BertTokenizer

token = BertTokenizer.from_pretrained('bert-base-chinese')

out = token.batch_encode_plus(
 batch_text_or_text_pairs=['今天我要努力学习自然语言处理', '明天我要认真学习金融学'],
 truncation=True,
 padding='max_length',
 max_length=15,
 return_tensors='pt',
 )

for i in out:
 print(i,out[i].shape)

print(token.decode(out['input_ids'][0]))
print(token.decode(out['input_ids'][1]))

输出结果如下所示：

1
2
3
4
5


input_ids torch.Size([2, 15])
token_type_ids torch.Size([2, 15])
attention_mask torch.Size([2, 15])
[CLS] 今 天 我 要 努 力 学 习 自 然 语 言 处 [SEP]
[CLS] 明 天 我 要 认 真 学 习 金 融 学 [SEP] [PAD] [PAD]

未微调时使用 text-classification pipeline

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from transformers import BertTokenizer, BertForSequenceClassification, pipeline

model = BertForSequenceClassification.from_pretrained('bert-base-chinese', num_labels=3)
tokenizer = BertTokenizer.from_pretrained('bert-base-chinese')

classifier = pipeline('text-classification', model=model, tokenizer=tokenizer)

output = classifier('我今天心情很好')
print(output)

output = classifier('你好，我是AI助手')
print(output)

output = classifier('我今天很生气')
print(output)

输出结果如下所示：

1
2
3
4
5
6


Some weights of BertForSequenceClassification were not initialized from the model checkpoint at bert-base-chinese and are newly initialized: ['classifier.bias', 'classifier.weight']
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
Device set to use cuda:0
[{'label': 'LABEL_2', 'score': 0.5192456841468811}]
[{'label': 'LABEL_2', 'score': 0.502333402633667}]
[{'label': 'LABEL_2', 'score': 0.47641533613204956}]

微调后使用 text-classification pipeline

首先我们需要通过同样的方法来构建基础模型。然后通过语料样本来进行微调。这里我们使用lansinuote/ChnSentiCorp数据集。

lansinuote/ChnSentiCorp数据集是一个用于中文情感分析的数据集。该数据集汇集了来自网络平台的多样化评论数据，主要覆盖三大领域：酒店住宿体验、笔记本电脑使用评价以及书籍阅读感受。数据集分为训练集、验证集和测试集。其中，训练集包含约 9600 条数据，验证集和测试集各包含约 1200 条数据。每条数据包含一段评论文本和对应的情感标签，情感标签通常为二分类（如好评、差评），部分版本可能包含中性标签。

将lansinuote/ChnSentiCorp数据集下载之后，使用模型的分词器对其进行处理，将处理之后的数据放入模型进行训练，我们仅训练1轮看看效果。训练完之后再测试集上进行预测查看训练效果。并将模型保存。实现代码如下。

模型预训练过程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


from transformers import BertTokenizer, BertForSequenceClassification, Trainer, TrainingArguments
from datasets import load_dataset
import re

tokenizer = BertTokenizer.from_pretrained('bert-base-chinese')
mode = BertForSequenceClassification.from_pretrained('bert-base-chinese', num_labels=3)
dataset = load_dataset('lansinuote/ChnSentiCorp')


def clean_text(text):
 text = re.sub(r'[^\w\s]+', ' ', text)
 text = text.strip()
 return text

dataset = dataset.map(lambda x: {'text': clean_text(x['text']), 'label': x['label']})

def tokenize_function(examples):
 return tokenizer(examples['text'], padding='max_length', truncation=True, max_length=128)

encoded_dataset = dataset.map(tokenize_function, batched=True)

training_args = TrainingArguments(
 output_dir='./results',
 num_train_epochs=1,
 per_device_train_batch_size=32,
 per_device_eval_batch_size=32,
 eval_strategy='epoch',
 logging_dir='./logs'
)

trainer = Trainer(
 model=mode,
 args=training_args,
 train_dataset=encoded_dataset['train'],
 eval_dataset=encoded_dataset['validation'],
)
trainer.train()

trainer.evaluate(encoded_dataset['test'], metric_key_prefix='eval')
mode.save_pretrained('./sentiment_model')
tokenizer.save_pretrained('./sentiment_model')

保存模型后进行情感分类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


from transformers import BertTokenizer, BertForSequenceClassification, pipeline

mode_dir = './sentiment_model'

model = BertForSequenceClassification.from_pretrained(mode_dir)
tokenizer = BertTokenizer.from_pretrained(mode_dir)

classifier = pipeline('text-classification', model=model, tokenizer=tokenizer)

output = classifier('我今天心情很好')
print(output)

output = classifier('你好，我是AI助手')
print(output)

output = classifier('我今天很生气')
print(output)

输出结果如下所示：

1
2
3
4


Device set to use cuda:0
[{'label': 'LABEL_1', 'score': 0.7787742614746094}]
[{'label': 'LABEL_0', 'score': 0.5039134621620178}]
[{'label': 'LABEL_0', 'score': 0.9373114109039307}]

效果明显好了很多。

基于 LSTM 的文本分类

Wed, 25 Mar 2026 17:34:25 -0800

基于 LSTM 的文本分类

在上一节，我们实现了一个基于全连接层的文本分类模型。该模型虽然简单有效，但它的核心是将所有词元的特征向量进行平均池化，这本质上是一种“词袋”模型。这种方法的一个显著局限是它忽略了文本中词语的顺序，而语序在多数 NLP 任务中是很重要的。那么，对于文本分类任务，捕捉序列信息是否总能带来性能提升呢？为了验证这一点，我们自然会想到循环神经网络（RNN）及其变体，如LSTM。在第三章第二节中我们已经学习了 LSTM 的原理。理论上，它能够通过处理序列信息来捕捉更丰富的语义。本节将进行一次实验，我们将上一节的全连接模型改造为基于LSTM的模型，来探索在本新闻分类任务上，序列建模是否会比简单的词袋模型更有效。

一、从“词袋”到序列建模

先回顾一下基线模型的主要操作：

（1）词嵌入：将输入的 token_ids ([batch_size, seq_len]) 转换为词向量 embedded ([batch_size, seq_len, embed_dim])。

（2）特征提取：通过几层全连接网络，将每个词向量独立地映射到更高维的特征空间，得到 token_features ([batch_size, seq_len, hidden_dim])。

（3）掩码平均池化：为了处理变长序列，将所有 token_features 沿 seq_len 维度进行求和，再除以真实长度，得到一个代表整句话的向量 pooled_features ([batch_size, hidden_dim])。

（4）分类：将 pooled_features 输入最后的分类层，得到最终预测。

这个流程的瓶颈在第三步。平均池化操作将序列信息压缩成一个向量，这可能导致词序信息的丢失。

与之相对，LSTM 网络通过其内部的循环结构和门控机制，能够逐个处理序列中的词元，并持续更新一个内部状态（记忆）。这个状态在每个时间步都会编码从序列开始到当前位置的所有信息。因此，当 LSTM 处理完整个序列后，它最终的隐藏状态理论上包含了对整个句子序列更丰富的语义表示，这有可能比简单的词向量平均更能捕捉句子的深层含义。

二、代码修改实践

将基线模型改造为 LSTM 模型，主要涉及这三个部分的修改：数据处理、模型结构和推理逻辑。

本节完整代码

2.1 改造 `collate_fn` 以提供序列长度

为了让 LSTM 能够高效地处理被填充（Padding）过的变长序列，需要使用 torch.nn.utils.rnn.pack_padded_sequence 函数。该函数要求在输入批次中明确提供每个样本在填充前的真实长度。所以，我们应该修改 collate_fn 函数，让它在返回 token_ids 和 labels 的同时，也返回一个包含该批次中每个序列真实长度的张量 lengths。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


def collate_fn(batch):
 max_batch_len = max(len(item["token_ids"]) for item in batch)

 batch_token_ids, batch_labels, batch_lengths = [], [], []

 for item in batch:
 token_ids = item["token_ids"]
 # 新增：记录真实长度
 lengths = len(token_ids)
 padding_len = max_batch_len - lengths

 padded_ids = token_ids + [0] * padding_len
 batch_token_ids.append(padded_ids)
 batch_labels.append(item["label"])
 # 新增：将长度加入列表
 batch_lengths.append(lengths)

 return {
 "token_ids": torch.tensor(batch_token_ids, dtype=torch.long),
 "labels": torch.tensor(batch_labels, dtype=torch.long),
 # 新增：返回长度张量
 "lengths": torch.tensor(batch_lengths, dtype=torch.long),
 }

2.2 构建 `TextClassifierLSTM` 模型

这是本次优化的主要内容。我们将原来的 TextClassifier 替换为一个新的 TextClassifierLSTM 模型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


class TextClassifierLSTM(nn.Module):
 def __init__(self, vocab_size, embed_dim, hidden_dim, num_classes,
 n_layers=1, dropout=0.3, bidirectional=False):
 super(TextClassifierLSTM, self).__init__()
 self.embedding = nn.Embedding(vocab_size, embed_dim, padding_idx=0)

 self.lstm = nn.LSTM(
 input_size=embed_dim,
 hidden_size=hidden_dim,
 num_layers=n_layers,
 dropout=dropout,
 bidirectional=bidirectional,
 batch_first=True # 关键参数：输入和输出张量的维度为 (batch, seq, feature)
 )

 num_directions = 2 if bidirectional else 1
 self.classifier = nn.Linear(hidden_dim * num_directions, num_classes)

 def forward(self, token_ids, lengths):
 embedded = self.embedding(token_ids)

 # 1. 打包序列
 packed_embedded = nn.utils.rnn.pack_padded_sequence(
 embedded,
 lengths.cpu(), # 长度必须在CPU上
 batch_first=True,
 enforce_sorted=False
 )

 # 2. LSTM 前向传播
 # hidden 和 cell 的形状: [n_layers * num_directions, batch_size, hidden_dim]
 packed_output, (hidden, cell) = self.lstm(packed_embedded)

 # 3. 提取最终隐藏状态用于分类
 if self.lstm.bidirectional:
 # 拼接最后一个时间步的前向和后向的隐藏状态
 # hidden[-2,:,:] 是前向的最后一个隐藏状态
 # hidden[-1,:,:] 是后向的最后一个隐藏状态
 hidden = torch.cat((hidden[-2,:,:], hidden[-1,:,:]), dim=1)
 else:
 # 只取最后一层的最后一个隐藏状态
 hidden = hidden[-1,:,:]

 # 4. 分类
 logits = self.classifier(hidden)
 return logits

模型解析:

（1）__init__：

除了词嵌入层 nn.Embedding 和分类层 nn.Linear，核心是一个 nn.LSTM 层。
增加几个 LSTM 相关的超参数：n_layers (LSTM层数), dropout (层间丢弃率), bidirectional (是否使用双向LSTM)。
batch_first=True 是一个重要的设置，它让 LSTM 接受 [batch_size, seq_len, feature_dim] 形状的输入，与 DataLoader 的输出保持一致，简化了代码。
分类层的输入维度需要根据 bidirectional 的值来动态确定。如果是双向的，隐藏层维度会加倍。
在 PyTorch 的 nn.LSTM 中，dropout 只在 n_layers > 1 时于层间生效；当仅 1 层时该参数不会起作用。若使用单层 LSTM，可将 dropout 设为 0.0（或保留任意值，效果一致），避免造成误解。

（2）forward：

forward 函数现在额外接收 lengths 参数。
打包 (Packing)：pack_padded_sequence 是处理填充序列的关键。它会将一个填充过的批次数据（例如，多个句子被填充到相同长度）压缩成一个更紧凑的表示，LSTM 只需对真实的、非填充部分进行计算，大大提高了效率和准确性。
最终状态提取：LSTM 的输出 hidden 张量包含了所有层在最后一个时间步的隐藏状态。我们通常取最后一层（对于单向 LSTM 是 hidden[-1,:,:]）作为整个序列的语义表示。如果是双向 LSTM，则需要拼接前向和后向的最终隐藏状态。
最后，将这个代表序列的 hidden 向量送入分类器。

2.3 调整 `Trainer` 和 `Predictor`

由于模型 forward 函数的输入签名发生了变化，我们需要对 Trainer 和 Predictor 进行微调，以确保 lengths 张量被正确传递。

1. Trainer 修改: 在 _run_epoch 和 _evaluate 方法中，从 batch 字典中取出 lengths，并将其传递给 self.model。

1
2
3
4
5
6
7
8


# 在 Trainer._run_epoch 方法中
...
token_ids = batch["token_ids"].to(self.device)
labels = batch["labels"].to(self.device)
lengths = batch["lengths"]

outputs = self.model(token_ids, lengths)
...

（_evaluate 方法同理）

2. Predictor 修改: Predictor 在处理单个文本时，也需要模拟批处理的逻辑：对文本分块后，手动计算每个块的长度，并进行填充，然后将 chunk_tensors 和 length_tensors 一同传入模型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# 在 Predictor.predict 方法中
...
# (文本分块逻辑不变) ...
chunks = [...]

# 手动计算长度并进行填充
chunk_lengths = [len(c) for c in chunks]
max_chunk_len = max(chunk_lengths) if chunk_lengths else 0

padded_chunks = []
for chunk in chunks:
 padding_len = max_chunk_len - len(chunk)
 padded_chunks.append(chunk + [0] * padding_len)

if not padded_chunks:
 return "无法预测（文本过短）"

chunk_tensors = torch.tensor(padded_chunks, dtype=torch.long).to(self.device)
length_tensors = torch.tensor(chunk_lengths, dtype=torch.long) # 长度在CPU上

with torch.no_grad():
 outputs = self.model(chunk_tensors, length_tensors)
 preds = torch.argmax(outputs, dim=1)
...

2.4 更新训练入口代码

最后一步，更新用于启动训练的单元格。我们需要：

（1）为 LSTM 添加新的超参数（n_layers, dropout, bidirectional）。

（2）实例化新的 TextClassifierLSTM 模型。

（3）（可选）为新的模型实验设置一个独立的输出目录，如 "output_lstm"。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import torch

hparams = {
 "vocab_size": len(tokenizer),
 "embed_dim": 128,
 "hidden_dim": 256,
 "num_classes": len(train_dataset_raw.target_names),
 "n_layers": 2, # 新增
 "dropout": 0, # 新增：此处显式设为 0，当前不启用 Dropout
 "bidirectional": True, # 新增
 "epochs": 20,
 "learning_rate": 0.001,
 "device": "cuda" if torch.cuda.is_available() else "cpu",
 "output_dir": "output_lstm" # 修改输出目录
}

# 实例化新模型
model = TextClassifierLSTM(
 vocab_size=hparams["vocab_size"],
 embed_dim=hparams["embed_dim"],
 hidden_dim=hparams["hidden_dim"],
 num_classes=hparams["num_classes"],
 n_layers=hparams["n_layers"],
 dropout=hparams["dropout"],
 bidirectional=hparams["bidirectional"]
).to(hparams["device"])

# (后续代码不变)

完成以上修改后，重新运行整个 Notebook，即可训练一个能够处理序列信息的 LSTM 模型。接下来，我们来对比它与基线模型的性能，并分析序列建模在本次任务中的实际效果。

2.5 实验结果与分析

在分别运行了基线的全连接模型和我们新构建的LSTM模型后（均未加正则化策略），我们得到了如下的性能数据：

全连接模型 (基线)：最终验证集最佳准确率约为 0.8469。
LSTM 模型：最终验证集最佳准确率约为 0.8143。

图 7-4 LSTM 模型训练损失与验证集准确率变化曲线

结果分析:

显然结果并不符合我们的预期，理论上更能捕捉序列信息的 LSTM 模型，在本次新闻分类任务上的表现反而劣于简单的全连接模型。这个发现说明模型的复杂性与任务的实际需求应该匹配。值得一提的是，本次对比实验并未严格控制固定随机数种子，所以每次运行的结果会存在细微的差别。然而，一个稳定的现象是，引入序列建模的 LSTM 并未带来性能提升，其结果反而总是比简单的全连接模型低 ~2% 左右，足以让我们得出以下结论。

出现这种结果的可能原因有两点：

（1）任务对语序相对不敏感：在目前的数据规模、从零开始训练模型的前提下，这个新闻分类任务在很大程度上依赖于关键词。例如，看到 “Jesus”、“God” 很可能属于宗教类；看到 “Graphics”、“Monitor” 很可能属于计算机图形类。全连接模型本质上是一个高效的“词袋”模型，非常擅长捕捉这类强特征词的存在与否。对于这个特定实验设置来说，“有哪些词”远比“这些词的顺序”更重要。LSTM 为学习语序付出的额外努力，在这里并没有转化为实际的性能优势。

（2）模型复杂性与过拟合：LSTM 模型比简单的全连接网络复杂得多，拥有更多的参数。虽然它理论上能学习到更复杂的模式，但也更容易在数据量不够大的情况下陷入过拟合。从训练日志中可以看到，普通 LSTM 的训练损失已经非常低，但验证集准确率却不高，这是过拟合症状。模型过于“记住”了训练集中的特定句子结构，而没有学到普适的规律。

三、过拟合解决方案与效果对比

基础 LSTM 模型效果不佳的一个可能原因是 过拟合。在第一节的末尾，我们介绍了三种简单有效的正则化方法分别是提前停止、随机Token遮盖和Dropout。

现在，我们将这三种方法组合应用到新的 LSTM 模型上，观察它们的综合效果。

3.1 随机Token遮盖

这是一种数据增强技术。我们在 TextClassificationDataset 的基础上创建一个子类，在 __getitem__ 方法中，对训练样本的 token_ids 进行随机替换。具体来说，以一定概率（例如10%）将部分词元替换为 <UNK> 对应的 ID。使得模型不能过度依赖个别特征词，而是要从更广的上下文中学习语义，从而增强泛化能力。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import random

class TextClassificationDatasetWithMasking(TextClassificationDataset):
 def __init__(self, texts, labels, tokenizer, max_len=128, is_train=False, mask_prob=0.1):
 super().__init__(texts, labels, tokenizer, max_len)
 self.is_train = is_train
 self.mask_prob = mask_prob
 self.unk_token_id = tokenizer.token_to_id.get("<UNK>", 1)

 def __getitem__(self, idx):
 # 关键：创建副本，避免修改原始数据
 item = super().__getitem__(idx).copy()

 if self.is_train:
 token_ids = item['token_ids']
 masked_token_ids = []
 for token_id in token_ids:
 # 不遮盖PAD (ID=0)
 if token_id != 0 and random.random() < self.mask_prob:
 masked_token_ids.append(self.unk_token_id)
 else:
 masked_token_ids.append(token_id)
 item['token_ids'] = masked_token_ids

 return item

在 TextClassificationDatasetWithMasking 的 __getitem__ 方法中，有一个非常关键的细节，item = super().__getitem__(idx).copy()。必须使用 .copy() 方法来创建数据的副本。

如果没有 .copy()，__getitem__ 中的修改将会永久地改变原始数据集。这会导致在第二个训练周期（Epoch）时，模型看到的是已经被第一次随机遮盖过的数据，并在此基础上进行二次遮盖，如此循环往复，最终导致有效信息完全丢失。数据增强必须保证每一轮都是在干净的原始数据上进行的独立操作。

3.2 提前停止 (Early Stopping)

提前停止是一种简单而高效的正则化策略。其核心思想是在训练过程中持续监控模型在验证集上的性能。如果验证集准确率（或损失）连续 N 个轮次（N 称为“耐心值” patience）没有超过历史最佳水平，就认为模型已经达到了最佳点或开始过拟合，此时应提前终止训练。我们在 Trainer 类的基础上创建一个子类，重写 train 方法以实现该逻辑。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


import os
import json

class TrainerWithEarlyStopping(Trainer):
 def __init__(self, model, optimizer, criterion, train_loader, valid_loader, device, output_dir=".", patience=3):
 super().__init__(model, optimizer, criterion, train_loader, valid_loader, device, output_dir)
 self.patience = patience
 self.epochs_no_improve = 0

 def train(self, epochs, tokenizer, label_map):
 for epoch in range(epochs):
 avg_loss = self._run_epoch(epoch)
 val_accuracy = self._evaluate(epoch)

 print(f"Epoch {epoch+1}/{epochs} | 训练损失: {avg_loss:.4f} | 验证集准确率: {val_accuracy:.4f}")

 current_best = self.best_accuracy
 self._save_checkpoint(epoch, val_accuracy)

 if self.best_accuracy > current_best:
 self.epochs_no_improve = 0
 else:
 self.epochs_no_improve += 1

 if self.epochs_no_improve >= self.patience:
 print(f"\n提前停止于 Epoch {epoch+1}，因为验证集准确率连续 {self.patience} 轮未提升。")
 break

 print("\n训练完成！")
 # ... (保存词典和标签映射)

3.3 实验与对比

最后，我们将所有正则化策略整合起来，实例化相应的数据集、模型和训练器，并启动训练。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 1. 创建应用了随机遮盖的数据集
train_dataset_reg = TextClassificationDatasetWithMasking(
 ..., is_train=True, mask_prob=0.1
)
train_loader_reg = DataLoader(train_dataset_reg, ..., collate_fn=collate_fn) # 继续使用前面改造过的 collate_fn，以便返回 lengths

# 2. 实例化模型，并启用 Dropout
model_reg = TextClassifierLSTM(
 ...,
 dropout=0.3, # 启用 Dropout
 ...
).to(device)

# 3. 使用带提前停止功能的训练器
trainer_reg = TrainerWithEarlyStopping(
 model_reg,
 ...,
 output_dir="output_lstm_regularized",
 patience=3
)

# 启动训练
trainer_reg.train(...)

完成训练后，可以通过比较两个实验的输出日志，来分析正则化带来的效果：

训练是否提前停止？ 如果是，说明模型可能在更早的阶段就已收敛。
最终验证集准确率：对比 output_lstm 和 output_lstm_regularized 中 best_model.pth 对应的验证集准确率，正则化版本是否取得了更好的泛化性能？
训练损失与验证准确率曲线：观察两个实验的日志，正则化版本的验证集准确率曲线是否更平滑，或者与训练损失的差距是否更小？这些都是过拟合得到缓解的迹象。

3.4 最终效果分析

在应用了这三种策略后，我们的 LSTM 模型取得了约 0.8415 的最佳验证集准确率。从下面的训练日志中可以看到，模型在第16轮达到了最佳性能，并在第19轮成功触发了“提前停止”策略，避免了不必要的训练和潜在的过拟合。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


Epoch 16 [训练中]: 100%|██████████| 224/224 [00:06<00:00, 33.60it/s]
Epoch 16 [评估中]: 100%|██████████| 169/169 [00:01<00:00, 97.13it/s]
Epoch 16/20 | 训练损失: 0.0206 | 验证集准确率: 0.8415
新最佳模型已保存! Epoch: 16, 验证集准确率: 0.8415
Epoch 17 [训练中]: 100%|██████████| 224/224 [00:06<00:00, 32.80it/s]
Epoch 17 [评估中]: 100%|██████████| 169/169 [00:01<00:00, 94.98it/s]
Epoch 17/20 | 训练损失: 0.0176 | 验证集准确率: 0.8243
Epoch 18 [训练中]: 100%|██████████| 224/224 [00:07<00:00, 31.27it/s]
Epoch 18 [评估中]: 100%|██████████| 169/169 [00:01<00:00, 96.61it/s]
Epoch 18/20 | 训练损失: 0.0172 | 验证集准确率: 0.8175
Epoch 19 [训练中]: 100%|██████████| 224/224 [00:06<00:00, 33.10it/s]
Epoch 19 [评估中]: 100%|██████████| 169/169 [00:01<00:00, 95.57it/s]
Epoch 19/20 | 训练损失: 0.0136 | 验证集准确率: 0.8066

提前停止于 Epoch 19，因为验证集准确率连续 3 轮未提升。

训练完成！
词典 (output_lstm_regularized\vocab.json) 和标签映射 (output_lstm_regularized\label_map.json) 已保存。

图 7-5 正则化 LSTM 模型训练损失与验证集准确率变化曲线

这个结果展示了正则化策略的价值：

相比于无正则化的LSTM（~0.8143）：性能得到了明显提升。这证明我们之前的判断是正确的——基础 LSTM 模型的一个主要问题就是过拟合。通过数据增强、提前停止和层间Dropout的组合，有效地抑制了模型对训练数据的“死记硬背”，使它学习到了更具泛化能力的模式。
- 随机 Token 遮盖强迫模型不能过度依赖训练集中少数几个“明星”关键词（例如特定作者），而是要学会识别更广泛、更多样化的关键词组合来做出判断，从而提升模型的健壮性和泛化能力。
- 提前停止则像一个“安全阀”，在模型性能达到巅峰并即将开始下滑（过拟合）的时刻及时终止了训练，锁定了最佳的模型状态。
- Dropout在多层 LSTM 中，会对除最后一层外各层的输出施加随机丢弃（dropout），相当于在层与层之间随机“关闭”部分神经元连接，破坏可能形成的“共适应”关系，从而增强模型的独立特征学习能力。
相比于全连接模型（~0.8469）：经过正则化后，LSTM模型的性能已经非常接近，但仍然略逊于更简单的基线模型。再次证明了对于这个特定的、以关键词为驱动的新闻分类任务，一个高效的“词袋”模型已经足够强大。试图用更复杂的序列模型来捕捉此处并不关键的语序信息，即使在组合了多种正则化策略后，也难以带来超越性的优势。

这个系列的实验也印证了著名的“奥卡姆剃刀原理”——如无必要，勿增实体。在模型选择上，我们应该从一个基线开始，逐步增加复杂性，并通过实验去验证每一步改动是否真的带来了收益。

文本分类简单实现

Wed, 25 Mar 2026 16:34:25 -0800

文本分类简单实现

一、文本分类任务概述

文本分类是 NLP 中常见的任务之一，它的目标是将给定的文本自动分配到一个或多个预定义的类别中。这项技术的实际应用广泛，例如情感分析可以判断商品评价或电影评论的情感倾向是正面、负面还是中性；新闻分类能够将新闻报道自动归入体育、财经、科技或娱乐等不同频道；在智能客服或语音助手中，意图识别技术用于判断用户输入的指令属于查询天气还是播放音乐等特定意图；而垃圾邮件过滤则能自动识别并拦截收件箱中的垃圾邮件，净化沟通环境。

在理论篇的第二章中，我们已经学习了如何将文本进行分词，并通过词向量技术将其转换为模型可以理解的数值形式。本节将在此基础上，以一个经典的新闻分类任务为例，详细讲解如何从零开始，一步步构建、训练和评估一个用于文本分类的深度学习模型。这个过程将涵盖数据处理、模型设计、训练循环、推理预测等所有核心环节。

二、NLP 项目通用流程

无论是文本分类，还是其他更复杂的 NLP 任务，深度学习的解决方案通常遵循一个标准化的项目流程。可以概括为以下几个核心模块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


graph LR
 A[1. 数据准备] --> B[2. 模型构建]
 B --> C[3. 定义损失与优化器]

 subgraph "训练循环 (Training Loop)"
 D[4. 迭代训练] --> E[5. 模型评估]
 E --> F{6. 是否更优?}
 F -- 是/Yes --> G[7. 保存模型]
 F -- 否/No --> D
 G --> D
 end

 C --> D

这个流程是搭建深度学习应用的通用范式，是一套标准化、可复用的模板。理解并掌握这套流程，比单纯实现某个模型更为重要。在接下来的内容中，我们将按照这个流程，将各个模块封装成独立的类，构建一个更规范、更易于维护和扩展的项目。

三、新闻文本分类代码实践

本节完整代码

本节将使用 scikit-learn 库中的 20 Newsgroups 数据集，这是一个包含约20000篇新闻文档、近似均衡分布在20个不同新闻组（类别）的集合。

3.1 模块化设计思路

在开始编写具体代码之前，更重要的步骤是“设计”。一个原则是，要先想清楚每个模块的输入和输出是什么。

数据模块的输出是什么？ -> 模型需要的“词元ID序列” (token_ids) 张量和“标签ID” (label_ids) 张量。
模型的输入是什么？ -> 数据模块的输出。
模型的输出是什么？ -> 每个类别的置信度。

如果对数据处理感到困惑，不妨先从模型定义开始。一旦我们清晰地定义了模型 forward 函数需要的输入（例如，ID序列），数据处理阶段的目标就变得很明确了，只需要把原始文本处理成模型所需的格式。

3.2 步骤一：数据解析与加载

3.2.1 数据加载

首先，加载scikit-learn提供的原始数据集。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from sklearn.datasets import fetch_20newsgroups

# 为了方便演示，只选择4个类别
categories = ['alt.atheism', 'soc.religion.christian', 'comp.graphics', 'sci.med']
train_dataset_raw = fetch_20newsgroups(subset='train', categories=categories, shuffle=True, random_state=42)
test_dataset_raw = fetch_20newsgroups(subset='test', categories=categories, shuffle=True, random_state=42)

sample = {
 "text_preview": train_dataset_raw.data[0][:200],
 "label": train_dataset_raw.target_names[train_dataset_raw.target[0]],
}
sample

输出如下：

1
2


{'text_preview': 'From: sd345@city.ac.uk (Michael Collier)\nSubject: Converting images to HP LaserJet III?\nNntp-Posting-Host: hampton\nOrganization: The City University\nLines: 14\n\nDoes anyone know of a good way (standard',
 'label': 'comp.graphics'}

3.2.2 数据探索与可视化

在进行任何复杂的预处理之前，对数据进行探索性分析是很重要且必要的。这有助于我们理解数据特性，从而做出更合理的设计决策。

（1）文本长度分布：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import matplotlib.pyplot as plt
import re

# 为了进行探索，先定义一个简单的分词函数
def basic_tokenize(text):
 text = text.lower()
 text = re.sub(r"[^a-z0-9(),.!?\'`]", " ", text)
 text = re.sub(r"([,.!?\'`])", r" \1 ", text)
 tokens = text.strip().split()
 return tokens

# 计算每篇文档的词元数量
train_text_lengths = [len(basic_tokenize(text)) for text in train_dataset_raw.data]

plt.figure(figsize=(10, 6))
plt.hist(train_text_lengths, bins=50, alpha=0.7, color='blue')
plt.title('Distribution of Text Lengths in Training Data')
plt.xlabel('Number of Tokens')
plt.ylabel('Frequency')
plt.grid(True)
plt.show()

图 7-1 训练集文本长度分布

（2）词频分布：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


from collections import Counter
import numpy as np

# 计算所有词元的频率
word_counts = Counter()
for text in train_dataset_raw.data:
 word_counts.update(basic_tokenize(text))

# 获取频率并按降序排序
frequencies = sorted(word_counts.values(), reverse=True)
# 生成排名
ranks = np.arange(1, len(frequencies) + 1)

# 绘制对数坐标图
plt.figure(figsize=(10, 6))
plt.loglog(ranks, frequencies)
plt.title('Rank vs. Frequency (Log-Log Scale)')
plt.xlabel('Rank (Log)')
plt.ylabel('Frequency (Log)')
plt.grid(True)
plt.show()

图 7-2 词频-排名对数图

通过数据分析可以发现，图 7-1 的文本长度分布直方图显示大部分文本的长度集中在较短的区间，但仍存在少量长度非常长的“异常值”，说明简单的直接截断策略可能会丢失过多信息。除此之外，如图 7-2 的对数坐标图所示，词频分布呈现出自然语言中典型的齐夫定律（Zipf’s Law）现象，即少数高频词占据了绝大多数的出现次数，而大量词汇构成了长长的“尾巴”，其出现频率极低。

3.2.3 Tokenizer 封装

接下来，我们创建一个 Tokenizer（分词器）类来负责所有与分词、词典构建和 ID 转换相关的任务，它封装了与数据探索时相同的分词逻辑并增加了 ID 转换等功能。其中 _tokenize_text 方法实现了一套基于正则表达式的分词策略，先将文本转为小写，通过 re.sub 移除非字母、数字和基本标点之外的字符，为了确保标点符号能被作为独立的词元，在它们周围添加空格，最后按空格切分文本得到词元列表。在词典构建方面，通过遍历所有训练文本统计词频，并过滤掉出现次数过少的低频词以减少词典规模和噪声，同时词典初始化时会预设两个特殊的 Token，即用于填充的 <PAD>（ID 为 0）和用于表示未登录词的 <UNK>（ID 为 1）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


class Tokenizer:
 def __init__(self, vocab):
 self.vocab = vocab
 self.token_to_id = {token: idx for token, idx in self.vocab.items()}

 @staticmethod
 def _tokenize_text(text):
 text = text.lower()
 text = re.sub(r"[^a-z0-9(),.!?\\'`]", " ", text)
 text = re.sub(r"([,.!?\\'`])", r" \\1 ", text)
 tokens = text.strip().split()
 return tokens

 def convert_tokens_to_ids(self, tokens):
 return [self.token_to_id.get(token, self.vocab["<UNK>"]) for token in tokens]

 def tokenize(self, text):
 return self._tokenize_text(text)

 def __len__(self):
 return len(self.vocab)

3.2.4 Tokenizer 与词典构建

基于前面对数据的分析，现在可以正式构建词典和 Tokenizer。词典将只包含在训练集中出现超过 min_freq 次的词元。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def build_vocab_from_counts(word_counts, min_freq=5):
 vocab = {"<PAD>": 0, "<UNK>": 1}
 for word, count in word_counts.items():
 if count >= min_freq:
 vocab[word] = len(vocab)
 return vocab

# 使用上一步计算出的word_counts来构建词典
vocab = build_vocab_from_counts(word_counts, min_freq=5)
tokenizer = Tokenizer(vocab)

{"vocab_size": len(tokenizer)}

输出如下：

1

{'vocab_size': 10983}

3.2.5 如何处理长文本？

在数据探索中能够发现，20 Newsgroups 数据集中存在大量超长文本，有的甚至超过1万个词元。而大部分深度学习模型（尤其是非 Transformer 模型）都难以处理过长的序列，直接输入会导致内存溢出和计算效率低下。而简单的截断会丢失大量文本末尾的信息，可能会导致关键信息丢失。

一个更好的方法是将一篇长文档切分成多个固定长度、且有部分重叠的“文本块”（Chunks）。例如，一篇 1000 词的文档若按 max_len=128、overlap=26 的方式进行切分，此时第一个块会包含 words[0:128]，第二个块则顺延为 words[102:230]（128-26=102），并以此类推完成整个文档的切分。这样做有两大好处，一方面通过信息保全完整地利用了整篇文章的信息；另一方面则带来了数据增强的效果，将一篇长文档变成了多条训练样本，增加了训练数据量。

3.2.6 封装 `Dataset` 和 `DataLoader`

TextClassificationDataset 负责的核心逻辑是接收原始文本，调用 tokenizer 进行 ID 化，并应用 滑窗分割 策略处理长文本。如果文本超过 max_len，则会进行切分。代码中的 stride 被设置为 max_len 的 80%，意味着每个文本块之间有20%的重叠，这有助于保持上下文信息的连续性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import torch
import torch.nn as nn
from torch.utils.data import Dataset
from tqdm import tqdm

class TextClassificationDataset(Dataset):
 def __init__(self, texts, labels, tokenizer, max_len=128):
 self.tokenizer = tokenizer
 self.max_len = max_len
 self.processed_data = []

 for text, label in tqdm(zip(texts, labels), total=len(labels)):
 token_ids = self.tokenizer.convert_tokens_to_ids(self.tokenizer.tokenize(text))

 # 滑窗分割逻辑
 if len(token_ids) <= self.max_len:
 self.processed_data.append({"token_ids": token_ids, "label": label})
 else:
 stride = max(1, int(self.max_len * 0.8))
 for i in range(0, len(token_ids) - self.max_len + 1, stride):
 chunk = token_ids[i:i+self.max_len]
 self.processed_data.append({"token_ids": chunk, "label": label})

 def __len__(self):
 return len(self.processed_data)

 def __getitem__(self, idx):
 return self.processed_data[idx]

接着，定义 collate_fn 函数，它负责将一个批次内长短不一的样本，通过填充操作（使用 <PAD> 对应的ID 0），打包成形状规整的张量，以便模型进行批处理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def collate_fn(batch):
 max_batch_len = max(len(item["token_ids"]) for item in batch)

 batch_token_ids, batch_labels = [], []

 for item in batch:
 token_ids = item["token_ids"]
 padding_len = max_batch_len - len(token_ids)

 padded_ids = token_ids + [0] * padding_len
 batch_token_ids.append(padded_ids)
 batch_labels.append(item["label"])

 return {
 "token_ids": torch.tensor(batch_token_ids, dtype=torch.long),
 "labels": torch.tensor(batch_labels, dtype=torch.long),
 }

使用我们创建的 Dataset 和 collate_fn 来实例化训练和验证数据加载器 DataLoader：

1
2
3
4
5
6
7
8
9


from torch.utils.data import DataLoader

train_dataset = TextClassificationDataset(train_dataset_raw.data, train_dataset_raw.target, tokenizer)
train_loader = DataLoader(train_dataset, batch_size=32, shuffle=True, collate_fn=collate_fn)

valid_dataset = TextClassificationDataset(test_dataset_raw.data, test_dataset_raw.target, tokenizer)
valid_loader = DataLoader(valid_dataset, batch_size=32, collate_fn=collate_fn)

{"train_samples": len(train_dataset), "valid_samples": len(valid_dataset), "batch_size": 32}

输出如下：

1

{'train_samples': 7142, 'valid_samples': 5408, 'batch_size': 32}

3.3 步骤二：模型构建

3.3.1 模型结构设计

在编写模型代码前，先梳理清楚数据的“变形记”，也就是张量形状在网络中如何变化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


Input:
 token_ids (词元ID序列): [batch_size, seq_len]
 |
 V
nn.Embedding(padding_idx=0)
 |
 V
 embedded: [batch_size, seq_len, embed_dim]
 |
 V
nn.Linear(embed_dim, hidden_dim*2) -> nn.ReLU -> nn.Linear(hidden_dim*2, hidden_dim*4) -> nn.ReLU
 |
 V
 token_features: [batch_size, seq_len, hidden_dim*4]
 |
 V
Masked Average Pooling (关键操作)
 |
 V
 pooled_features: [batch_size, hidden_dim*4] <-- seq_len维度被聚合掉了
 |
 V
nn.Linear (分类层)
 |
 V
Output:
 logits: [batch_size, num_classes]

3.3.2 掩码平均池化

池化（Pooling）的目的是将一个序列的特征（[seq_len, hidden_dim]）聚合成一个代表整条序列的向量（[hidden_dim]），但简单的平均池化会受到填充 <PAD> 的影响从而导致语义偏差。举例来说，假设一个批次有 2 个句子且最大长度为 4，其中句子 A 的真实长度为 4（表示为 [v_I, v_love, v_NLP, v_too]），而句子 B 的真实长度为 2（表示为 [v_NLP, v_rocks, v_PAD, v_PAD]）。掩码池化的计算过程如下：

（1）创建掩码：mask = [[1, 1, 1, 1], [1, 1, 0, 0]]

（2）向量置零：将句子 B 中 <PAD> 对应的向量 v_PAD 乘以 0，使其变为零向量。

（3）向量求和：句子 A 求和得到 sum_A = v_I + v_love + v_NLP + v_too；句子 B 求和得到 sum_B = v_NLP + v_rocks + 0 + 0。

（4）除以真实长度：句子 A 除以 4 得到 pool_A = sum_A / 4；句子 B 除以 2 得到 pool_B = sum_B / 2。

通过这种方式就得到了不受填充影响的、精确的句子平均向量。而在 forward 方法中，这个过程大致包含四个步骤。首先是创建掩码，即根据输入的词元 ID 序列（token_ids）中不等于 padding_idx 的位置，生成一个值为 0 或 1 的掩码张量；紧接着进行向量置零，利用广播机制将特征向量与掩码相乘，使所有填充位置的特征向量都会变为零向量；随后向量求和，沿序列长度维度对特征向量进行求和；最后除以真实长度，将求和结果除以每个样本的真实长度（即掩码中 1 的数量），得到最终的池化向量。

3.3.3 模型代码

根据上述分析，下面是 TextClassifier 模型的完整实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


class TextClassifier(nn.Module):
 def __init__(self, vocab_size, embed_dim, hidden_dim, num_classes):
 super(TextClassifier, self).__init__()
 self.embedding = nn.Embedding(vocab_size, embed_dim, padding_idx=0)

 self.feature_extractor = nn.Sequential(
 nn.Linear(embed_dim, hidden_dim * 2),
 nn.ReLU(),
 nn.Linear(hidden_dim * 2, hidden_dim * 4),
 nn.ReLU()
 )

 self.classifier = nn.Linear(hidden_dim * 4, num_classes)

 def forward(self, token_ids):
 embedded = self.embedding(token_ids)
 token_features = self.feature_extractor(embedded)

 # shapes:
 # token_ids: [batch_size, seq_len]
 # embedded: [batch_size, seq_len, embed_dim]
 # token_features: [batch_size, seq_len, hidden_dim * 4]
 # padding_mask: [batch_size, seq_len]
 # masked_features: [batch_size, seq_len, hidden_dim * 4]
 # summed_features: [batch_size, hidden_dim * 4]
 # pooled_features: [batch_size, hidden_dim * 4]
 # logits: [batch_size, num_classes]

 # --- 掩码平均池化 ---
 padding_mask = (token_ids != self.embedding.padding_idx).float()
 masked_features = token_features * padding_mask.unsqueeze(-1)
 summed_features = torch.sum(masked_features, 1)
 real_lengths = padding_mask.sum(1, keepdim=True)
 pooled_features = summed_features / torch.clamp(real_lengths, min=1e-9)

 logits = self.classifier(pooled_features)

 return logits

3.4 步骤三：训练与评估

将所有与训练、评估、优化和模型保存相关的逻辑都封装到一个Trainer类中。这个类负责协调模型、数据和优化器，完成整个训练流程。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85


import os
import json

class Trainer:
 def __init__(self, model, optimizer, criterion, train_loader, valid_loader, device, output_dir="."):
 self.model = model
 self.optimizer = optimizer
 self.criterion = criterion
 self.train_loader = train_loader
 self.valid_loader = valid_loader
 self.device = device
 self.best_accuracy = 0.0
 self.output_dir = output_dir
 os.makedirs(self.output_dir, exist_ok=True)
 # 用于记录历史数据
 self.train_losses = []
 self.val_accuracies = []

 def _run_epoch(self, epoch):
 self.model.train()
 total_loss = 0
 for batch in tqdm(self.train_loader, desc=f"Epoch {epoch+1} [训练中]"):
 self.optimizer.zero_grad()

 token_ids = batch["token_ids"].to(self.device)
 labels = batch["labels"].to(self.device)

 outputs = self.model(token_ids)
 loss = self.criterion(outputs, labels)
 total_loss += loss.item()

 loss.backward()
 self.optimizer.step()

 return total_loss / len(self.train_loader)

 def _evaluate(self, epoch):
 self.model.eval()
 correct_preds = 0
 total_samples = 0
 with torch.no_grad():
 for batch in tqdm(self.valid_loader, desc=f"Epoch {epoch+1} [评估中]"):
 token_ids = batch["token_ids"].to(self.device)
 labels = batch["labels"].to(self.device)

 outputs = self.model(token_ids)
 _, predicted = torch.max(outputs, 1)

 total_samples += labels.size(0)
 correct_preds += (predicted == labels).sum().item()

 return correct_preds / total_samples

 def _save_checkpoint(self, epoch, val_accuracy):
 if val_accuracy > self.best_accuracy:
 self.best_accuracy = val_accuracy
 save_path = os.path.join(self.output_dir, "best_model.pth")
 torch.save(self.model.state_dict(), save_path)
 print(f"新最佳模型已保存! Epoch: {epoch+1}, 验证集准确率: {val_accuracy:.4f}")

 def train(self, epochs, tokenizer, label_map):
 self.train_losses = []
 self.val_accuracies = []
 for epoch in range(epochs):
 avg_loss = self._run_epoch(epoch)
 val_accuracy = self._evaluate(epoch)

 self.train_losses.append(avg_loss)
 self.val_accuracies.append(val_accuracy)

 print(f"Epoch {epoch+1}/{epochs} | 训练损失: {avg_loss:.4f} | 验证集准确率: {val_accuracy:.4f}")

 self._save_checkpoint(epoch, val_accuracy)

 print("训练完成！")
 # 训练结束后，保存最终的词典和标签映射
 vocab_path = os.path.join(self.output_dir, 'vocab.json')
 with open(vocab_path, 'w', encoding='utf-8') as f:
 json.dump(tokenizer.vocab, f, ensure_ascii=False, indent=4)

 labels_path = os.path.join(self.output_dir, 'label_map.json')
 with open(labels_path, 'w', encoding='utf-8') as f:
 json.dump(label_map, f, ensure_ascii=False, indent=4)
 print(f"词典 ({vocab_path}) 和标签映射 ({labels_path}) 已保存。")
 return self.train_losses, self.val_accuracies

3.5 步骤四：执行训练

通过前面的精心封装，现在执行训练的入口代码变得非常直观和简洁。我们先定义一个超参数字典 hparams 来集中管理所有配置，这是一种良好的工程实践。然后，只需实例化所有需要的“零件”，并将它们交给“训练总管” Trainer 即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# 超参数
hparams = {
 "vocab_size": len(tokenizer),
 "embed_dim": 128,
 "hidden_dim": 256,
 "num_classes": len(train_dataset_raw.target_names),
 "epochs": 20,
 "learning_rate": 0.001,
 "device": "cuda" if torch.cuda.is_available() else "cpu",
 "output_dir": "output"
}

# 实例化
model = TextClassifier(
 hparams["vocab_size"],
 hparams["embed_dim"],
 hparams["hidden_dim"],
 hparams["num_classes"]
).to(hparams["device"])

criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=hparams["learning_rate"])

hparams

然后，我们使用这些超参数来实例化模型、损失函数、优化器，并将它们全部交给 Trainer 类进行管理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


trainer = Trainer(
 model,
 optimizer,
 criterion,
 train_loader,
 valid_loader,
 hparams["device"],
 output_dir=hparams["output_dir"]
)

# 创建 标签名 -> ID 的映射，并传入 trainer 以便保存
label_map = {name: i for i, name in enumerate(train_dataset_raw.target_names)}

# 开始训练，并接收返回的历史数据
train_losses, val_accuracies = trainer.train(epochs=hparams["epochs"], tokenizer=tokenizer, label_map=label_map)

输出如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


...
Epoch 14 [训练中]: 100%|██████████| 224/224 [00:00<00:00, 314.05it/s]
Epoch 14 [评估中]: 100%|██████████| 169/169 [00:00<00:00, 788.40it/s]
Epoch 14/20 | 训练损失: 0.0003 | 验证集准确率: 0.8469
...
Epoch 19 [训练中]: 100%|██████████| 224/224 [00:00<00:00, 326.07it/s]
Epoch 19 [评估中]: 100%|██████████| 169/169 [00:00<00:00, 786.61it/s]
Epoch 19/20 | 训练损失: 0.0001 | 验证集准确率: 0.8450
Epoch 20 [训练中]: 100%|██████████| 224/224 [00:00<00:00, 324.01it/s]
Epoch 20 [评估中]: 100%|██████████| 169/169 [00:00<00:00, 792.40it/s]
Epoch 20/20 | 训练损失: 0.0001 | 验证集准确率: 0.8443
训练完成！
词典 (output\vocab.json) 和标签映射 (output\label_map.json) 已保存。

在本次训练中，模型于第14个轮次（Epoch）达到了最佳性能，验证集准确率最高为 84.69%。由于代码并未固定随机数种子，模型初始权重和数据加载顺序在每次运行时都会有所不同，所以每次运行时得到的结果可能会有细微差异。

3.5.1 训练过程可视化

为了更直观地分析模型的训练过程，例如判断是否收敛、是否存在过拟合等，可以将每个周期的训练损失和验证集准确率绘制成图表。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


def plot_history(train_losses, val_accuracies, title_prefix=""):
 epochs = range(1, len(train_losses) + 1)

 fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 5))

 # 绘制训练损失曲线
 ax1.plot(epochs, train_losses, 'bo-', label='Training Loss')
 ax1.set_title(f'{title_prefix} Training Loss')
 ax1.set_xlabel('Epochs')
 ax1.set_ylabel('Loss')
 ax1.grid(True)
 ax1.legend()

 # 绘制验证集准确率曲线
 ax2.plot(epochs, val_accuracies, 'ro-', label='Validation Accuracy')
 ax2.set_title(f'{title_prefix} Validation Accuracy')
 ax2.set_xlabel('Epochs')
 ax2.set_ylabel('Accuracy')
 ax2.grid(True)
 ax2.legend()

 plt.suptitle(f'{title_prefix} Training and Validation Metrics', fontsize=16)
 plt.show()

# 调用绘图函数
plot_history(train_losses, val_accuracies, title_prefix="Feed-Forward Network")

图 7-3 训练损失与验证集准确率变化曲线

从图 7-3 中能够看出：

训练损失：随着训练的进行，损失稳步下降并趋于平缓，说明模型在训练数据上得到了有效的学习。
验证集准确率：准确率在前几个轮次（Epochs）中迅速提升，随后在达到一个较高水平后出现小幅波动并趋于饱和。这表明模型在训练早期就快速收敛，并在后续训练中将性能稳定在最佳水平附近。

3.6 步骤五：模型推理

训练完成后，最终的目的是使用模型对全新的、未见过的数据进行预测。一个健壮的推理流程必须确保使用与训练时完全相同的预处理配置（特别是词典）和模型权重。

3.6.1 长文本推理的聚合策略

由于我们对长文本进行了滑窗分割，一篇原始文档在推理时会得到多个文本块的预测结果。那么如何将这些结果聚合成一个最终预测呢？常见的策略主要有两种，第一个是多数投票法，也是最直观的方法，具体做法是分别查看每个文本块被预测成的类别，然后选择得票最多的那个类别作为最终结果，若出现平票则可选择置信度总和最高的类别。第二个是概率累乘/平均法，该方法会计算每个类别在所有文本块上的平均置信度或概率，然后选择平均置信度最高的类别。虽然累乘也是一种选择，但在实践中容易因小概率值导致数值下溢，因此取对数后再求和（等价于累乘）或直接平均更为常用。

下面的 Predictor 类将封装完整的推理流程，并实现了“多数投票法”作为聚合策略。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


class Predictor:
 def __init__(self, model, tokenizer, label_map, device, max_len=128):
 self.model = model.to(device)
 self.model.eval()
 self.tokenizer = tokenizer
 self.label_map = label_map
 self.id_to_label = {idx: label for label, idx in self.label_map.items()}
 self.device = device
 self.max_len = max_len

 def predict(self, text):
 token_ids = self.tokenizer.convert_tokens_to_ids(self.tokenizer.tokenize(text))
 chunks = []
 if len(token_ids) <= self.max_len:
 chunks.append(token_ids)
 else:
 stride = max(1, int(self.max_len * 0.8))
 for i in range(0, len(token_ids) - self.max_len + 1, stride):
 chunks.append(token_ids[i:i + self.max_len])

 chunk_tensors = torch.tensor(chunks, dtype=torch.long).to(self.device)
 with torch.no_grad():
 outputs = self.model(chunk_tensors)
 preds = torch.argmax(outputs, dim=1)

 final_pred_id = torch.bincount(preds).argmax().item()

 final_pred_label = self.id_to_label[final_pred_id]
 return final_pred_label

# 加载资源
vocab_path = os.path.join(hparams["output_dir"], 'vocab.json')
with open(vocab_path, 'r', encoding='utf-8') as f:
 loaded_vocab = json.load(f)

labels_path = os.path.join(hparams["output_dir"], 'label_map.json')
with open(labels_path, 'r', encoding='utf-8') as f:
 label_map_loaded = json.load(f)

# 实例化推理组件
inference_tokenizer = Tokenizer(vocab=loaded_vocab)
inference_model = TextClassifier(
 len(inference_tokenizer),
 hparams["embed_dim"],
 hparams["hidden_dim"],
 len(label_map_loaded)
).to(hparams["device"])

model_path = os.path.join(hparams["output_dir"], "best_model.pth")
inference_model.load_state_dict(torch.load(model_path, map_location=hparams["device"]))

predictor = Predictor(
 inference_model,
 inference_tokenizer,
 label_map_loaded,
 hparams["device"]
)

# 预测
new_text = "The doctor prescribed a new medicine for the patient's illness, focusing on its gpu accelerated healing properties."
predicted_class = predictor.predict(new_text)

{"text": new_text, "pred": predicted_class}

输出如下：

1
2


{'text': "The doctor prescribed a new medicine for the patient's illness, focusing on its gpu accelerated healing properties.",
 'pred': 'sci.med'}

四、过拟合问题

刚刚构建的模型并没有考虑过拟合（Overfitting） 的问题，即模型在训练集上表现优异，但在未见过的验证集或测试集上表现不佳。下面简单介绍三个常用的方案：

（1）提前停止（早停）

这种方法是在Trainer的train方法中，持续监控验证集的准确率（或损失）。如果发现验证集准确率连续N个轮次（N被称为“耐心值”，Patience）都没有超过历史最佳值，就提前终止训练。这可以在Trainer中增加一个patience参数和一个计数器来实现此逻辑。

（2）随机 Token 遮盖

这是一种数据增强方法，具体操作是在训练过程中，随机地将文本中的一部分词元（例如15%）替换为<UNK>。使得模型不能过度依赖个别“明星词汇”，而是要学习更全面的上下文语义来进行判断，继而提升模型的泛化能力。这个修改可以在TextClassificationDataset类的__getitem__方法中，在返回数据前增加一个随机替换的步骤。不过要注意，这个操作只应在训练时进行。

（3）Dropout

它的核心是在训练过程中，以一定的概率p随机地将神经网络中某些神经元的输出置为零。可以防止神经元之间形成过于复杂的共适应关系，迫使网络学习到更鲁棒、更泛化的特征。可以在 TextClassifier 模型的 feature_extractor 模块中，于 nn.Linear 层和 nn.ReLU 激活函数之后加入 nn.Dropout(p) 层。

大模型上下文学习与提示词技术

Tue, 24 Mar 2026 14:34:25 -0800

大模型上下文学习与提示词技术

在学习 GPT 结构的过程中，我们提到过上下文学习以及它所包含的各种提示模式（Zero-shot、One-shot、Few-shot）。可以了解到，这是一种只需提供不同数量的参考示例，在推理阶段不发生任何梯度反向传播或权重更新，主要依靠提示词就能让大模型在许多任务上获得可观效果的交互范式。既然没有实际的学习更新过程，模型是如何做到这一点的？本节我们就深入探究它的工作机制，以及当遇到难度瓶颈时，如何利用提示词技术进一步激发模型的推理潜能。

一、零样本与少样本机制

1.1 零样本学习

**零样本学习（Zero-Shot Learning）**是指在提示词中仅提供任务指令和待处理的输入内容，而不提供任何预期输出的参考示例。大语言模型凭借预训练阶段积累的广博知识，直接对未见过的任务进行处理。以常见的情感分析任务为例，下面是在没有任何示例的情况下让模型判断文本情感倾向的典型设定：

1
2
3
4


阅读以下评论，并判断一下评论表达的情感：

评论：这部电影的剧情有些拖沓。
情感：

如图 6-34 所示，我们在 DeepSeek 的网页端测试一下这个输入。可以看到在这个场景下，模型不只是机械地弹出一个分类标签，而是输出了一句完整的自然语言“评论表达的情感：负面。”，并且精准地给出了 负面 这个情感判断。之所以能够做到这一点，得益于模型在海量语料上预训练所建立的共享语义空间，预训练阶段模型不仅学习到了“电影”、“剧情”、“拖沓”等词汇的表征，还有这些词汇与“负面”情感概念在潜空间中的深层关联。当我们下达自然语言指令时，零样本学习在实践中往往还依赖于模型经过对齐微调后形成的指令遵循能力 ¹。通过解析指令的意向，自回归生成机制会将当前的新任务映射到其已构建的底层语义概念上。这种基于先验知识的语义映射会直接影响模型预测下一个 token 时的概率分布。模型不仅能依次采样输出结构完整的句子，而且当生成到表达核心态度的那一步时，代表“负面”的 token 往往会因上下文的语义引导而获得更高的生成概率，进而在不更新任何权重的条件下完成任务。

图 6-34 零样本学习示例

1.2 少样本学习

尽管零样本学习展现出了强大的泛化能力，但这种能力高度依赖于数据中固有的常见模式。如果我们需要模型严格遵循某种特定的输出格式，或者处理一些边界模糊、容易混淆的复杂情况，仅仅依靠指令说明可能无法得到稳定可靠的结果，模型很多时候还会像零样本例子中那样，输出多余的解释性自然语言或产生判断偏差。这就必须引入具备“观摩”作用的少样本学习（Few-Shot Learning），在上下文中补充几个规范的输入输出示例，向大模型清晰地演示预期效果。其中，**单样本学习（One-Shot Learning）**就是只给模型提供一个参考示例，相当于是少样本学习的特例。例如，为了让模型明白我们只需要单纯的极性词，可以给模型输入如下内容：

1
2
3
4
5
6
7


阅读以下评论，并判断一下评论表达的情感：

评论：画面非常唯美，配乐也很震撼！
情感：正面

评论：这部电影的剧情有些拖沓。
情感：

如图 6-35，有了这个单样本的约束，模型的输出就变得非常干净。

图 6-35 单样本学习示例

单样本学习在大多数常规规范任务中表现良好，但是如果面临的任务比较复杂、反直觉或高度定制化时，它的效果就捉襟见肘了。比如，我们加上一条极其违背常规语言习惯的规则，将情感词倒序输出（“正面”输出“面正”，“负面”输出“面负”）：

1
2
3
4
5
6
7


阅读以下评论，并判断一下评论表达的情感：

评论：画面非常唯美，配乐也很震撼！
情感：面正

评论：这部电影的剧情有些拖沓。
情感：

在这种非标准逻辑的冲击下，由于只看了一个反直觉的例子，模型往往无法确信这究竟是一次偶然的拼写错误，还是一条必须遵循的硬性规定。它可能会干脆放弃顺应你的规则。如图 6-36 所示，它不仅没有按照规则逆序输出，反而还补充了多余的对话文本。

图 6-36 单样本反差约束失效示例

要克服模型预训练阶段积累的语言先验，以及对齐微调阶段形成的固有对话范式对新规则的强烈干扰，让上下文构建的任务模式能够主导最终的输出概率，我们就需要增加示例的数量，用少样本学习来强化这种非标准的映射关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


阅读以下评论，并判断一下评论表达的情感：

评论：画面非常唯美，配乐也很震撼！
情感：面正

评论：演技太令人尴尬了，中途就想离场。
情感：面负

评论：一般般，没有预期的那么好看，但也不至于太差。
情感：性中

评论：这部电影的剧情有些拖沓。
情感：

有了这几个示例作为铺垫，如图 6-37 所示，模型捕捉到了隐藏的规则，判断出这不是单词拼错，而是要将情感分类词汇逆序输出。

图 6-37 少样本反差约束成功示例

少样本学习之所以有效，是因为它在上下文窗口中构建了一个临时的任务概率分布。受上下文连续多个一致性示例的驱动，模型的注意力机制能够较为敏锐地提炼并模仿这种有悖常理的映射关系，并将其更稳健地泛化到当前的目标输入上。这证明大语言模型不仅能回忆静态知识，还能实时地在复杂上下文中进行动态的全新模式匹配与学习。

1.3 上下文学习的内在机制

为了解释为什么在不更新任何权重的情况下，大语言模型依然能在提示词上下文中“学会”新任务，学术界近年来提出了几种主流的假设与验证机制：

（1）感应头机制 ²：这是从模型内部注意力层面的机械可解释性角度提出的。研究发现，Transformer 模型在预训练的特定阶段会激发出一种特殊的注意力头——“感应头”。它的核心行为模式是“匹配并复制”，当模型在上下文中发现当前输入 A 此前出现过，它会将注意力回溯到前一个 A，并倾向于直接预测其后跟随的 Token B 作为当前的输出。这种底层的复制机制是少样本学习中模式匹配的重要微观基础之一。

（2）隐式学习动力学（隐式权重更新） ³：有研究从“前向计算本身就是一种学习过程”的角度解释上下文学习。在 Transformer block 内，自注意力会把上下文中的示例信息写入激活，再与后续的 MLP 组合，可近似理解为产生一种对后续计算起作用的低秩“权重更新/适配”效应。这个过程无需显式反向传播或持久化的权重改动，但会以瞬时激活的形式影响后续 token 的 logits，从而动态改变输出分布。

（3）（近似）贝叶斯视角与其检验 ⁴⁵：有一类工作把上下文学习理解为“在上下文中对潜在任务/潜变量做（近似）推断”的过程，用先验—后验来解释零样本与少样本的差异；也有研究提出可操作的统计检验，并在其实验设置下观察到 LLM 的上下文学习会偏离严格的贝叶斯性质。总体而言，贝叶斯更像是一类有启发性的解释框架，而非已被普遍证明的严格等价。

这三大理论从微观执行（注意力单元复制）、中观适配（隐式权重更新）到宏观统计（概率推断），共同揭示了现代大语言模型强大泛化能力的底层本质。

二、进阶提示词技术

随着对大语言模型潜力挖掘的深入，如图 6-38 研究人员发现仅靠简单的示例有时仍然无法解决需要多步复杂逻辑推理的数学或算法规划问题。为此，提示词工程领域发展出了更高级的引导策略。

图 6-38 标准提示词与思维链（CoT）的效果对比

2.1 思维链

思维链（Chain-of-Thought, CoT） 技术 ⁶ 鼓励模型在给出最终答案之前，先显式地输出中间的推理步骤。这种方法不仅客观上增加了生成过程的计算步数，让模型获得了更多的“思考时间”，而且将一个复杂的大问题拆解成了多个简单连贯的小逻辑节点。在应用层面上，这项技术经历了一条清晰且快速的演进路线。最初的研究提出了需要手动编写详尽推理示例的多样本思维链（Few-Shot CoT）。随后，研究人员观察到在一些模型与任务上，在提示词末尾添加一句“Let’s think step by step”也可能显著提升推理过程的显式展开，也就是常说的零样本思维链（Zero-Shot CoT）。后续，学术界又提出了尝试让大模型自动化构建推理示例的自动思维链（Auto-CoT） ⁷。对于基础大模型，我们可以用一个非常直观的零样本测试样例去感受思维链被激活的过程。例如向模型抛出一道暗含生活常识与逻辑陷阱的问题：

1

我想洗车，洗车店离我家 50 米。我应该开车去还是走路去？

如图 6-39 所示，未经过深层推理特化的大模型往往会被表面的“距离近应该走路”逻辑误导，给出一个“抽象”的建议。

图 6-39 缺乏深层推理时的逻辑错误示例

如果我们尝试在提示词末尾加上要求逐步思考的“魔法咒语”，会发现一个有意思的情况。

1

我想洗车，洗车店离我家 50 米。我应该开车去还是走路去？让我们一步一步地思考

如图 6-40 所示，模型虽然列出了“一步步”的分析框架，但在关键逻辑上依然出现了严重的幻觉（在第 3 点中假设人走过去车就在那里），最后给出“走路去”的错误结论。

图 6-40 中文 CoT 引导失败示例

但如果我们换用英文最经典的 CoT 触发词：

1

我想洗车，洗车店离我家 50 米。我应该开车去还是走路去？Let's think step by step

这一次模型如图 6-41 成功发现了盲点。它准确推理出“如果走路去，车还在家里，所以没法洗车”，得出“you should drive”的正解。

图 6-41 英文 CoT 引导成功示例

仅仅是中英文提示词的差异，为什么会导致截然不同的逻辑推理结果？

这在一定程度上反映出基础大语言模型的多语言推理能力可能存在分布不均衡。在模型的预训练阶段，包含严密逻辑推导的高质量数据（如数学解答、编程逻辑、学术论文等）在英文语料中往往更常见、积累时间更长，也更容易在早期训练中形成相对稳健的推理模式。同时，诸如“Let’s think step by step”这类高频的经典触发短语，可能在部分微调和评测数据集中反复出现，更容易在一些模型上引导出“显式分步推导”的生成模式。而且，如图 6-41 所示，在使用英文触发词后，模型不仅算对了答案，后续的整个推导过程也全都变为了英文。对这种现象，比较合理的猜测是在该模型的训练数据与对齐策略下，英文触发短语更容易让模型调动到其较强的推理习惯与表达模板。相比之下，中文直译版本在某些模型上可能只强化了“分点作答”的外观格式，而未必稳定触发有效的自我校验。本质上，通过显式要求生成中间推导步骤，并提供更容易引导分步推导的提示方式，模型会把前文生成的中间结果当作延伸的“草稿纸”，继续引导下一步的文本生成，在一定程度上缓解“直觉短路”带来的局部逻辑盲区。

思维链技术的生效归根结底仍然高度依赖于底层训练数据。常规模型只有在预训练阶段见过海量的推理论证逻辑，才更可能在推理阶段被某些提示方式稳定引导出分步推导。随着业界对大模型复杂推理能力的追求，最新一代的专用推理模型（如 OpenAI o1、DeepSeek-R1 等）在产品形态上也更强调“先推导、后作答”。这类模型在预训练之后，通常还会结合强化学习等后训练方法，并配合高质量样本对输出行为进行规范化，从而让模型在面对复杂或充满陷阱的问题时，更倾向于在内部展开更充分的自我检查与多步推演。

2.2 思维树

在线性、单向的思维链基础上，研究人员进一步提出了思维树（Tree of Thoughts, ToT） 框架 ⁸。对于更具挑战性、需要全局规划或容易陷入逻辑死胡同的任务（如算 24 点、填字游戏或规划调度），单向单线的 CoT 很可能有去无回——中间某一步哪怕只犯了微小的评估错误，就会使得推理陷入局部最优，导致最终结果全盘皆输。如图 6-42 所示，思维树将线性的推理链条扩展成了具有多个分支的树状拓扑结构。它的核心理念可以总结为“系统性多路径探索 + 智能评估 + 回溯机制”。它允许模型在推理过程中像树枝一样展开多个可能的探索分支，并交替执行以下环节：

生成候选：在当前步骤生成多种可能的下一步解法方向。
状态评估：由模型自身作为“智能裁判”，对各个候选路径的后续成功潜力进行打分排查。
选择与回溯：借助经典的搜索算法（如广度优先搜索 BFS 或深度优先搜索 DFS），根据评分选择最优路径继续深入。一旦发现某条路径走进了“死胡同”，立刻向后回溯到上一个安全节点并尝试其他选项。

图 6-42 从 IO、CoT 到思维树（ToT）的提示词范式演进

我们可以继续用前文探讨的“洗车问题”来做一个极简的推演。面对“应该开车去还是走路去洗车”的决策，ToT 会首先要求模型生成第一步所有可能的行动候选分支（如 分支 A：开车去 或 分支 B：走路去）。接着，它触发状态评估机制，判断这些分支能否真正达成“洗车”的目的。例如，走入 分支 B：走路去 时，评估模型会判断出“如果人走过去了，车却留在了家里，没有车可以洗”。于是，系统会抛弃这条无效路径，向后回溯并选择另外一个候选分支（分支 A：开车去）。当然，洗车只是一个用于演示的简单示例。如图 6-43 所示，在应对“算 24 点”这类搜索空间庞大的复杂任务时，ToT 基于状态评分与剪枝回溯的探索机制才能体现出实际的工程价值。

图 6-43 思维树（ToT）在“算 24 点”游戏中的执行过程

这种将经典启发式搜索算法与大模型实时评估能力融合的框架具有创新性。但是在工程落地时，开发者也必须清醒认识到实际应用中的弊端。首先是算力成本的急剧膨胀，每一次分支探索和智能审查都需要密集消耗推理资源和等待时间。其次是自我评估偏差，完全依赖模型自身进行裁判很容易产生认知盲点。最后则是随时可能因为迭代轮次过多而导致的搜索空间爆炸。ToT 只是一种算法思想，它并不强制要求绑定复杂的智能体（AI Agent）框架才能运行。开发者完全可以通过编写原生的 Python 脚本（利用数组维护树节点、使用 while 循环进行 BFS/DFS 搜索、通过 API 调用大模型进行打分）来实现一套轻量级的 ToT 推理链路。只因为这种多步规划与自省的机制与自主智能体的诉求高度契合，ToT 目前才更多地被提炼为一种宏观规划模块，融入到了现代复杂 Agent 的底层架构之中，而不是作为一种日常单次对话中最常用的提示词技巧。

2.3 专用推理模型

前文提到的诸如 OpenAI o1 或 DeepSeek-R1 等专用推理模型，标志着大模型底层能力维度的范式进化。为了实现“将探索、试错与自省的推导能力更充分地内化于基座权重”，这些新型模型在训练阶段经历了范式的转变。以 DeepSeek-R1 为例，实现这一跨越的核心机制通常涉及多个阶段的后训练组合。其中往往包含强化学习主导的阶段：在基础预训练之后，模型不再单纯依赖传统的人类偏好对齐，还会通过大规模的强化学习提升逻辑推导能力。在数学求解或代码生成等具有明确结果反馈的场景中，系统基于规则的奖励机制引导模型自我探索，促使模型更愿意延长推导链条以换取更高奖励，形成更强的自我校验与纠错倾向。同时，也常会配合监督微调的阶段，通过整理、过滤与构建高质量样本，进一步稳定模型长序列推理的输出风格与可读性，如图 6-44 展示了这类用于微调的数据集示例。

图 6-44 推理数据集示例

结合上述机制，专用推理模型在接收到复杂用户请求时，往往会在输出答案前自动展开更长的推导过程（耗时会持续数秒到数分钟不等）。从外部可观察到的效果是模型更倾向于进行自我检查、反思与多步推演。至于内部是否采用显式的树状展开、剪枝与回溯等实现形式，则可能因模型与系统实现而异。如图 6-45，我们使用 DeepSeek 的推理模型对“洗车问题”进行测试，可以看到它的思考内核经历了“评估走路（距离近）、发现盲点（车没带过去）、尝试发散解决（让人把车开过去但麻烦）、最终收敛（必须开车去）”的自省链条。

图 6-45 推理模型应对“洗车问题”时的后台推导轨迹

不过，在带来更好推理效果的同时，这类模型也伴随显著的代价，首当其冲的便是推理期算力开销的成倍增加以及首字响应延迟的延长。所以，对于日常问答、常规翻译或直接的信息检索等无需长逻辑链条干预的基础级任务，调用满血的推理模型会造成高强度的资源浪费。在实际的系统工程架构设计中，通常需要引入路由网关模块来实现不同复杂度的任务级动态分发，比如将常规类任务调度给基础生成模型，而将复杂多步规划任务路由给推理模型，以平衡生成质量与计算成本。

参考文献

手撕大模型文本生成策略

Tue, 24 Mar 2026 13:34:25 -0800

手撕大模型文本生成策略

前两节我们通过 Llama2 和 MoE，深入理解了大模型的网络架构（即“大脑”是如何构造的）。但仅有架构还不够，模型前向传播输出的仅仅是概率分布（Logits），如何将这些概率一步步转化为流畅的文本，就是本节要探讨的核心——解码策略。我们将回到成熟的 Transformers 库，以 GPT 模型为例，避开繁琐的数学公式，直接通过代码调试的方式，探究 model.generate() 的底层工作原理，看看从“输入 Prompt”到“输出文本”的完整数据流是如何在代码中流转的。

一、“逐 token 生成”在做什么

1.1 从 Pipeline 入手调试准备

重新打开在第五章中实现的 GPT 实战代码，如图 6-16 注释掉其他内容，只保留文件最后的 # pipeline 应用 的部分以及相关初始化变量。具体调试方法可以参考第八章 NER 项目的数据处理中的简单说明。

图 6-16 Pipeline 调试代码准备

接下来按下面步骤进行调试：

（1）在 pipeline_outputs = generator(...) 这一行打断点。Debug 运行脚本，程序停住后，点击步入（Step Into），如图 6-17 我们就进入 Transformers 包内部代码。

图 6-17 Pipeline 源码

可以看到图中源码的猫咪 emoji（🐈 🐈 🐈）。Hugging Face 的三位创始人都是法国人，而在法语中 “chat” 就是猫的意思，所以工程师用它暗示这里有“一堆 chats（猫）”。哈哈，极客幽默。

（2）言归正传，接下来我们需要在 text_generation.py 文件中的四个位置下断点。分别在 preprocess() 最后找到 return inputs 这一行；在 _forward() 中找到 output = self.model.generate(；在 postprocess() 的循环里找到 text = self.tokenizer.decode( 和 if return_type == ReturnType.FULL_TEXT:，然后把断点打在这四行。

调试器命中断点时通常会停在该行“执行之前”，所以如果某个变量是“在这一行才刚被赋值/更新”的，需要单步执行一次或把断点下在下一行，才能看到它的最终值。

（3）断点下好后，点击 恢复程序（Continue / Resume），程序会依次停在这四个位置。

1.2 Pipeline 接口的输入与输出结构

（1）停在 preprocess()：看模型“吃进去”的是什么

在前处理阶段，展开 inputs 我们看看模型“吃进去”的到底是什么。如图 6-18 所示，会发现文本被 tokenizer 变成了 token ids 以及 mask（见 input_ids 和 attention_mask），同时 pipeline 还会保留原始输入 prompt_text，这是为了后处理时能拼回 FULL_TEXT。在图中可以看到 input_ids 和 attention_mask 形状是 Tensor: (1, 4)，对应我们的输入 I like eating fried，第 1 维 = batch size = 1（本次只输入 1 条 prompt），第 2 维 = 序列长度 = 4（这条 prompt 被 tokenizer 切成了 4 个 token）。

图 6-18 前处理阶段的 inputs 结构

（2）停在 _forward()：确认真正的解码发生在 model.generate()

这里我们可以看到 Pipeline 只是把参数整理好，真正的解码策略发生在 model.generate() 里。如图 6-19 这里就是“最终生效”的生成参数，这里传入了我们在前处理阶段得到的 input_ids 和 attention_mask，同时还有我们在 generator() 中传入的 max_new_tokens=5、num_return_sequences=1 两个参数。

图 6-19 推理生成阶段传递生成参数

（3）停在 postprocess()：把 token ids 还原成文本，并决定返回 FULL/NEW

后处理阶段的任务就是把生成出来的 token ids 用 tokenizer.decode(...) 还原成文本，并决定返回 FULL_TEXT/NEW_TEXT。

如图 6-20，程序首先停在 text = self.tokenizer.decode( 的位置。这里有个关键参数 sequence：通过 Ctrl + B（转到定义）回溯可以发现，这个值来自 model_outputs["generated_sequence"][0]。所以实际上在 Transformers 的实现里，模型推理结束后会得到一个字典，包含 'generated_sequence'、'input_ids' 以及 'prompt_text'。接下来 generated_sequence 会被转换成 Python 列表，并在 for idx, sequence in enumerate(generated_sequence): 里逐条取出，因此此处的 sequence 本质上就是“一条生成序列”的 token id 列表。观察 sequence 的值能够发现，前面的四个 40, 588, 6600, 23018 是我们的输入 token，而后面五个 9015, 553, 531, 262, 582 则是模型新生成的内容，并且与 max_new_tokens=5 的设置对应。

图 6-20 后处理阶段的 sequence
再次恢复程序会停到 if return_type == ReturnType.FULL_TEXT:。此时重点看 prompt_length 和 all_text：prompt_length 表示“prompt 在 decode 后的长度”，Pipeline 用它把 text 的前半段（prompt 部分）裁掉，得到“新增内容” all_text（也就是 NEW_TEXT）。如图 6-21 所示，本次推理的结果被 decode 成字符串后的结果是 ' chicken, but I like'，而 prompt_length=19 也刚好对应 ““I”(1) + 空格(1) + “like”(4) + 空格(1) + “eating”(6) + 空格(1) + “fried”(5) = 19”。如果设置的是 FULL_TEXT（默认值），Pipeline 会在后面把 prompt_text 再拼回去，所以最终输出会包含原始 prompt。如果想看到最后输出的结果，也可以在当前代码文件尾部 return records 的位置继续下断点，这里就不再赘述。

图 6-21 后处理阶段的 prompt_length 与 all_text

1.3 分析解码流程

刚才提到了真正的解码策略发生在 model.generate() 里，那么接下来我们取消掉除了 output = self.model.generate( 这行之外的其他三处断点，然后重新调试。

（1）步入进去 text_generation.py 后恢复程序会停到 output = self.model.generate( 这行，然后我们对 generate() 方法 Ctrl + B 转到定义，这时一般会跳到 generation/utils.py（或同类路径）里定义 generate() 方法的地方。接着在下面找到 generation_config, model_kwargs = self._prepare_generation_config( 下完断点后恢复程序。

（2）如图 6-22，我们可以看到 GenerationConfig 的配置如下，这些配置在本地下载的模型 config.json 文件中也有体现。同时我们还可以看一下 kwargs 中的内容，这就是我们传入 generate() 的参数。

1
2
3
4
5
6
7
8


GenerationConfig {
 "bos_token_id": 50256,
 "do_sample": true,
 "eos_token_id": 50256,
 "max_length": 50,
 "max_new_tokens": 256,
 "temperature": 0.7
}

其中，bos_token_id 是生成起始 token（当 inputs=None 时会用它来“起一个头”）；eos_token_id 是结束 token（生成到它或满足停止条件就停止）；do_sample 表示是否采样（False 更确定，True 更有随机性/多样性）；temperature 是采样温度（越大越随机，越小越保守）；max_length 是总长度上限（prompt+新生成）；max_new_tokens 是新增 token 上限（如果同时设置了 max_length，以最终合并后的配置为准）。

图 6-22 默认的 GenerationConfig

（3）接着在 generation_mode = generation_config.get_generation_mode(assistant_model) 这行也下个断点。恢复程序后，我们可以看到多了个变量 model_kwargs，其中包括了 input_ids 和 attention_mask。同时 GenerationConfig 中的默认值（如 max_new_tokens）也被传参覆盖。

（4）我们下一步看看本次推理会走哪种解码策略，可以选择在 decoding_method = getattr(type(self), GENERATION_MODES_MAPPING[generation_mode]) 这行下个断点，也可以直接步过（Step Over）。如图 6-23 可以看到 generation_mode 的值是 <GenerationMode.SAMPLE: 'sample'>，说明本次会走**采样（Sampling）**分支，通常对应 do_sample=True 且 num_beams=1（区别于 do_sample=False,num_beams=1 的贪心，以及 num_beams>1 的 beam 系列策略；如果 do_sample=True 且 num_beams>1，则会走 BEAM_SAMPLE）。采样的含义是每一步不是“永远选概率最大的 token”，而是在（可能经过 temperature/top_k/top_p 等处理后的）概率分布上随机采样一个 token，所以输出通常会更有多样性。这部分具体判定代码可以使用 Ctrl + B 转到 generation_config.get_generation_mode(...) 的代码定义进行查看。

图 6-23 解码策略分支选择

（5）继续往下走，我们看一下输入张量 inputs_tensor 怎么变成 input_ids。我们首先把断点下在 if "inputs_tensor" in inspect.signature(decoding_method).parameters.keys(): 这行。此时 _prepare_model_inputs() 执行完成后，如图 6-24 我们可以看到 model_kwargs 中的 input_ids 被拆成了 inputs_tensor，而且有一个新变量 model_input_name。model_input_name 相当于一个标签，代表 inputs_tensor 对应的是哪一种输入类型。

图 6-24 model_input_name 标记输入类型

（6）如果 num_return_sequences>1（一次要返回多条候选）或 num_beams>1（beam search 需要多条 beam 路径），那么同一条 prompt 的 input_ids（以及 attention_mask）会在 batch 维度被复制 expand_size=max(num_beams, num_return_sequences) 份，用来并行生成；如果这两个值都是 1，就会看到这里“几乎没变化”。另外我们还可以在 if generation_config.token_healing: 这行下断点，此时能看到“扩展后”的 input_ids（以及 model_kwargs 里的 attention_mask）形状，同时也能确认 generation_config.token_healing 是否开启（开启时下一行会对 input_ids 做一次 heal_tokens 处理）。

（7）当前代码文件的最后一处断点我们可以下在 result = decoding_method(，这里是真正的逐 token 生成循环入口。当恢复程序代码停在这里后，如图 6-25 我们可以看一下传入 decoding_method(...) 的几个参数。这里主要说明一下 prepared_logits_processor 跟 prepared_stopping_criteria 的作用，其他几个参数可能具体值有些变化不过作用没什么变化就不再赘述。当前的 prepared_logits_processor 可以理解为“每一步选 token 之前对 logits 做规则化修正”的一串处理器（例如最小长度、坏词过滤、重复惩罚等都会在这里把某些 token 的概率压低/置为 -inf），而 prepared_stopping_criteria 则是一组“什么时候该停止生成”的判定条件（例如达到最大长度、遇到 eos_token_id 或满足自定义停止条件时就结束循环）。

图 6-25 decoding_method(...) 入参

（8）最后在这行多次点击步入后，我们就进入了本次推理阶段实际执行的解码循环 _sample() 方法，这部分我们暂时先简单总结一下代码逻辑。_sample() 方法的内部是一个 while 循环，每一轮先用 prepare_inputs_for_generation(...) 基于当前 input_ids 准备本轮模型输入，然后做一次 forward 得到 outputs.logits[:, -1, :]（只取“最后一个位置”的 logits），再把 logits 交给 logits_processor(...) 做规则化修正，随后根据 do_sample 选择采样（torch.multinomial）或贪心（argmax）得到 next_tokens，把新 token 拼回 input_ids（torch.cat）作为下一轮输入；最后用 stopping_criteria(input_ids, scores) 判断是否满足停止条件（例如到达最大长度或遇到 eos_token_id），满足则跳出循环并返回生成的序列。如图 6-26，最终我们得到的这个 (1, 9) 的 input_ids 跟我们之前在后处理阶段看到的 model_outputs["generated_sequence"][0] 是一样的。

图 6-26 _sample() 返回值

1.4 从 Pipeline 到底层循环的完整调用链

经过上述对 Pipeline 和 model.generate() 的深度调试，我们可以将一次完整的文本生成任务归纳为以下 5 个核心步骤的接力跑：

（1）预处理（Preprocess）：Pipeline 的 preprocess() 方法调用 tokenizer，将原始字符串 prompt_text 转换为模型可识别的 Token ID 张量 (input_ids) 和 Attention Mask。

（2）入口分发：Pipeline 的 _forward() 方法携带处理好的张量调用 model.generate()；在 generate() 内部，会先合并用户参数与 GenerationConfig 默认配置，确定最终的生成参数（如 max_new_tokens、do_sample 等）。

（3）策略选择：generate() 根据配置自动判断解码模式（Greedy / Sampling / Beam Search 等），并动态分发给对应的具体实现方法（如 _sample(), _greedy_search(), _beam_search()）。

（4）解码循环：进入具体方法（如 _sample()）后，开启 while 循环。

准备输入：prepare_inputs_for_generation() 处理缓存 (past_key_values) 和当前输入。
模型前向：执行 model() 得到最新的 logits。
规则修正：LogitsProcessor 修改概率分布（如惩罚重复、限制词表）。
采样选择：根据概率分布采样（multinomial）或贪心选择（argmax）得到 Next Token。
拼接更新：将新 Token 拼接到 input_ids 末尾。
停止判定：检查 StoppingCriteria（如是否遇到 EOS 或达到最大长度），决定是否跳出循环。

（5）后处理（Postprocess）：生成结束后得到的完整 sequence 会被送回 Pipeline 的 postprocess()，再调用 tokenizer.decode() 将 Token ID 序列还原为人类可读的字符串，并根据配置处理 FULL_TEXT / NEW_TEXT 的截取逻辑，最终返回给用户。

二、logits 规则链与常用解码策略

我们刚才已经能顺着断点走到 result = decoding_method(，并进一步步入到本次实际执行的策略方法（例如 _sample()）。接下来还有两个问题需要解决。第一，get_logits_processor（源码里常见的是 _get_logits_processor）到底往生成流程里“塞了哪些规则”，以及这些规则是在每一步如何修改 logits 的；第二，在这些规则生效之后，Greedy/Sampling/Beam 这几类策略分别是“怎么选下一 token”的。

2.1 logits 规则链是怎么构造出来的

（1）第一步“基操”，我们在 prepared_logits_processor = self._get_logits_processor( 下个断点，其他不需要的断点都可以取消，然后重新以调试方式运行代码。

（2）程序停下后先看看 _get_logits_processor 内传入了哪些参数。如图 6-27，我们可以看到 input_ids_length 的值为 4，那很显然“值如其名”这就是 input_ids 的长度。然后关注一下 model_kwargs，这里面多了两个不认识的值：

logits_to_keep 是“本次 forward 只保留/只计算最后多少个位置的 logits”的提示参数（很多模型支持它来节省显存与计算量，当前取值是 1，表示只需要最后一个 token 位置的 logits 就够做 next-token 选择了）；
past_key_values 是自回归解码的 KV Cache（缓存每一层注意力的 key/value），用于在下一步生成时复用历史计算结果，避免每一步都把整个序列从头算一遍，从而显著加速逐 token 生成。当前的这个 DynamicCache(layers=[DynamicLayer, ...]) 就说明用的是 DynamicCache 这种缓存结构，而 layers=[DynamicLayer, ...] 有 12 个则表示模型有 12 层 Transformer block，每一层都有一份对应的缓存（每层一个 DynamicLayer）。缓存会随着生成过程逐步增长（每生成一个 token，每层的 K/V 都会多一列），用于下一步注意力计算直接复用历史 K/V，从而加速逐 token 生成。

图 6-27 _get_logits_processor 调用

（3）接着点几次步入就进入了 _get_logits_processor() 的具体实现中，这时会看到 processors 还是一个空的 LogitsProcessorList()（因为规则链是“边判断边 append”的）。然后我们直接把断点下到最后 return processors 的位置。恢复程序停在这行之后，如图 6-28 我们观察一下 processors 的值具体包含了什么。我们会发现它已经变成一个“规则链”，里面依次追加了采样相关的 Warper，例如 TemperatureLogitsWarper(temperature=0.7)（温度缩放，控制随机性强弱）和 TopKLogitsWarper(top_k=50, filter_value=-inf)（只保留 top-k 候选，其余置为 -inf，避免在全词表里乱抽）。如果我们同时设置了 top_p/typical_p/epsilon_cutoff/eta_cutoff，这里也会出现对应的 Warper。所以实际上 _get_logits_processor() 的作用就是把我们在 generation_config/kwargs 里写的“生成控制参数”，翻译成一个“每一步生成都会执行的 logits 处理规则链”（LogitsProcessorList）并按顺序组装好返回。

图 6-28 processors（logits 规则链）示例

（4）回到 _sample() 的循环，在 next_token_scores = logits_processor(input_ids, next_token_logits) 这一行下个断点。恢复程序后，我们可以看几个变量。首先找到 outputs，这个就是模型推理的输出，里面有个 logits 属性。当前 logits 的形状是 (batch_size, seq_len, vocab_size)，这里会看到 (1, 1, 50257)：其中第一个 1 表示本次只推理 1 条输入（batch size = 1），第二个 1 表示本次 forward 只保留了 1 个位置的 logits（因为 logits_to_keep=1，只需要最后一个位置来做 next-token 选择），而 50257 就是词表大小（vocab_size），表示对词表里的每个 token 都给了一个分数。再看 next_token_logits 这个值来自 outputs.logits[:, -1, :]，形状会变成 (batch_size, vocab_size)（只取最后一个位置）。

（5）点击步入，我们会来到 logits_process.py 文件中 LogitsProcessorList 类的魔法方法。可以看到程序停在了 for processor in self:，这里的 self 是 LogitsProcessorList（本质是一个 list 容器），所以这个循环是在依次遍历列表里的每一个 warper 对象（本次推理的 warper 对象是 TemperatureLogitsWarper 和 TopKLogitsWarper）。接着点击几次步过条件判断语句会把我们带到 scores 赋值。然后点击步入，对于本次推理我们就跳转到了 TemperatureLogitsWarper 类的魔术方法，这里可以看到 scores_processed = scores / self.temperature 对 logits 做缩放（等价于把 logits 除以温度 $T$，$T<1$ 分布更尖更“确定”，$T>1$ 分布更平更“随机”）；

在 TemperatureLogitsWarper 里，形参名叫 scores，但它传进来的就是 softmax 之前的分数，所以也可以称其为 logits。这次缩放后面代入 softmax 后，就会让分布在 $T<1$ 时更尖锐、$T>1$ 时更平坦。假设模型输出为 $z=[2,1,0]$，温度缩放后用的是 $\mathrm{softmax}(z/T)$。

当 $T=1$：就是原始 softmax，$e^2=7.389,e^1=2.718,e^0=1$，总和 $11.107$，所以概率约为 $[0.665,0.245,0.090]$。

当 $T=0.5$（更小）：先除以 $0.5$ 得到 $[4,2,0]$，$e^4=54.598,e^2=7.389,e^0=1$，总和 $62.987$，概率约为 $[0.867,0.117,0.016]$，最大项更接近 1——分布更“尖”。

当 $T=2$（更大）：先除以 $2$ 得到 $[1,0.5,0]$，$e^1=2.718,e^{0.5}=1.649,e^0=1$，总和 $5.367$，概率约为 $[0.506,0.307,0.186]$，更平均——分布更“平”。

（6）接着步过这次调用，我们就又回到了 LogitsProcessorList 类。然后重复刚才的步骤我们就来到了 TopKLogitsWarper 类的魔术方法。它会先用 torch.topk(scores, top_k)[0][..., -1, None] 取出“第 $k$ 大”的分数作为阈值，然后计算 indices_to_remove = scores < threshold 得到一个布尔 mask；步过后看到 indices_to_remove 里 True 表示“需要被过滤掉”的 token（不在 top-k 里），False 表示保留；最后用 scores.masked_fill(indices_to_remove, -inf) 把这些 True 的位置统一置为 -inf，这样进入 softmax 后它们的概率就是 0，采样时永远不会被选到。类似地：

top_p（nucleus sampling）会按概率从高到低排序，只保留累计概率达到 $p$ 的最小 token 集合，其余置为 -inf；
typical_p（typical sampling）会按“局部典型性（local typicality）”来筛选 token，保留满足阈值的 token 集合（官方文档的表述是：local typicality 衡量“预测某个 token 的条件概率”与“从该分布随机抽一个 token 的期望条件概率”有多相似）；
epsilon_cutoff 会在 softmax 概率空间做阈值过滤：当 epsilon_cutoff 设为 $0 < \epsilon < 1$ 时，只允许条件概率大于 epsilon_cutoff 的 token 参与采样，其余过滤；
eta_cutoff 属于 eta sampling：它是 “locally typical sampling + epsilon sampling” 的混合形式。按官方文档描述，当 eta_cutoff 设为 $0 < \eta < 1$ 时，一个 token 只有在满足以下条件之一时才会被考虑。其概率 $p$ 大于 eta_cutoff，或 $p > \sqrt{\text{eta_cutoff}} \cdot e^{-\text{entropy}}$ （其中 entropy 指当前分布的熵）。

不管是 top_k 还是 top_p 以及其他的这些，本质上都是“裁剪规则”。

top_k：每一步只保留分数最高的 K 个 token，其余置为 -inf（候选数量固定）。

top_p：每一步按概率从高到低累加，保留“累计概率 ≥ p 的最小 token 集合”，其余置为 -inf（候选数量动态，取决于分布“尖不尖”）。

因此 top_k 越小，越容易反复选到高分 token，输出更稳定，但也更容易变得模板化/重复；top_p 越小，也会更早截断到一小撮高概率 token，候选更少。实际应用中 temperature 和 top_p 是“分工明确”的一对。temperature 把分布变尖/变平（决定“随机性强弱”），top_p 就是把低概率尾巴裁掉（决定“从哪些 token 里抽”）。top_p 和 top_k 没什么联动，如果同时开启，相当于是双重过滤，最后能被采样的 token 会落在“满足 top_k 的集合”和“满足 top_p 的集合”的交集里。

（7）继续步过，我们就跳出了 logits_processor(...)，而这个时候的 next_token_scores 就是被规则链修正后的 logits。接着步过，如图 6-29，经过 softmax 和按 probs 的概率分布随机抽样后我们就得到了第一个预测 token “2057”。打开模型的 vocab.json 文件，检索一下可以看到这个词是 “\u0120food”，“\u0120”其实就是我们在学习 GPT 的过程中学习过的“Ġ”，这个前缀表示一个词的开始。那么本次推理的第一个单词显然就是 “food”。继续步过，下面这行 if has_eos_stopping_criteria: 就是判断某条序列是否已经“结束了”，如果结束了就把它后续每一步的 next_token 设成 pad_token_id，避免它继续生成乱七八糟的 token，同时保持 batch 里所有序列长度一致。

图 6-29 第一个预测 token

（8）最后继续步过，执行完 input_ids = torch.cat([input_ids, next_tokens[:, None]], dim=-1) 我们就能看到新的 token 已经追加到了 input_ids 后面。后面的 unfinished_sequences = unfinished_sequences & ~stopping_criteria(input_ids, scores) 就是判断本次 while 循环是否结束的，如图 6-30 所示，如果判断不停止就继续循环推理并生成下一个词。调试结束后就得到了本次的生成结果 “I like eating fried food. I’m in”。

图 6-30 继续循环推理

2.2 常用解码策略

（1）Greedy Search（默认策略之一）：确定性地选最大值

当 num_beams=1 且 do_sample=False 时，generate() 通常会选择 Greedy Search（我们前面看到的 GenerationMode.GREEDY_SEARCH）。底层循环的核心非常简单：每一步 forward 得到 outputs.logits[:, -1, :]，先过一遍 logits_processor(...)，然后直接 argmax 选出分数最大的 token 作为 next_tokens，再把它拼回 input_ids 进入下一轮，直到 stopping_criteria 判定停止。Greedy 的好处是速度快、结果稳定，适合做 baseline 或需要强确定性的场景；缺点是容易陷入局部最优，开放式续写时更容易产生重复或“套路化”的输出。

（2）Sampling（抽样，LLM 开放式生成中最常用的家族）

在对话/开放式文本生成里，更常见的做法是开启采样（do_sample=True），并配合 temperature/top_p/top_k 来控制多样性与稳定性。以你已经步入过的 _sample() 为例：每一步拿到 next_token_scores 后先做 softmax 得到概率分布，再用 torch.multinomial 从该分布中抽一个 token；而 temperature/top_p/top_k 这些“看起来是策略参数”的东西，通常就是在 logits_processor（或同类 warper）里提前把分布处理好，保证采样只在合理候选集里进行。也就是说：Sampling 的“随机性”不是乱抽，而是“先按规则改分布，再从改过的分布里抽”。（Transformers 官方也把这类方法归为 generation strategies 的核心内容，可参考 Hugging Face 的 generation strategies 文档。）

（3）Beam Sample（束采样）：beam 框架 + 采样

当 num_beams>1 且 do_sample=True（并且 num_beam_groups==1）时，generate() 通常会选择 GenerationMode.BEAM_SAMPLE。你可以把它理解成“beam search 的框架不变，但每一步的扩展不再是纯 top-k 硬选，而是引入采样带来的随机性/多样性”。它的适用场景通常是既希望保留多条候选路径的搜索能力，又希望输出不要过于死板；但在大模型开放式对话里，工程上更常见的仍是直接 Sampling（num_beams=1）+ top-p/temperature，Beam Sample 相对少见一些，你可以把它当作“可选的折中策略”。

（4）Beam Search（束搜索）：更“序列级”的搜索，但更慢也更保守

当 num_beams>1 且 do_sample=False 时，generate() 通常会进入 GenerationMode.BEAM_SEARCH。beam 框架的核心是：每一步同时维护 num_beams 条候选序列（beams），对每条序列扩展出若干候选 token，并根据“累计分数”（常见做法是对 log 概率求和，并可能加上 length_penalty）进行排序剪枝，只保留最好的 num_beams 条继续滚动；这能更接近“序列级最优”，因此在翻译/摘要等任务里经常很稳。但在开放式生成中，beam search 往往更保守，也更容易出现某些重复/模板化模式，同时计算开销更大，所以在大语言模型的聊天式生成里并不是首选策略之一（这也是为什么很多推理默认更偏向 sampling 家族）。

（5）其他策略

如果我们在 generation_mode 里遇到下面这些分支，一般知道“它们解决什么问题”就够了：

Group Beam Search：把 beam 分组来增加多样性，缓解 beam search 的同质化；
Contrastive Search：用 penalty_alpha 等机制在“高概率/低重复”之间折中；
Constrained Beam Search：在 beam search 上加硬约束（例如必须包含某些词/短语），用于强控制生成。

三、调试技巧

老东西，终于把焚决交出来了！

通过这整个调试过程，可以发现为了教学方便这里的步骤是一个线性的过程。不过实际上在面对不熟悉的代码时，真实的调试过程并不是这样的。还是以这个 GPT 的代码为例，假设我们是第一次拿到这段 pipeline 的代码。如图 6-31，除了我们认识的导库、环境配置的一些操作，唯一不认识的就是这两行代码：

1
2


generator = pipeline("text-generation", model=model_name, device=device)
pipeline_outputs = generator(prompt_en, max_new_tokens=5, num_return_sequences=1)

图 6-31 化繁为简

那么首先我们就在 pipeline_outputs = generator(...) 下个断点，看看 generator 是什么类型。发现这是个对象后，那我们唯二不认识的代码行就只剩一行了，第一行无非就是创建了一个对象。接着步入这段代码会来到有三只小猫注释的“魔法方法”。这里主要是一些输入格式判断和改写，我们可以直接跳到最后的 return super().__call__(...) 并继续步入。再次来到了一大段看起来像“框架胶水”的代码，也还是先定位到最后的 return 并步入。通过 return self.run_single(...) 步入之后我们就来到了图 6-32 所示的 run_single() 方法。

图 6-32 run_single() 主流程

虽然这里我们不知道 run_single() 里面这几段是干什么的，不过通过变量名还是多少能猜出来这里就是我们要找的主要流程，从模型输入（model_inputs）到模型输出（outputs），还有眼熟的 forward。猜不到也没关系，从 model_inputs = self.preprocess(...) 开始继续步入，就来到了 preprocess() 方法，依然是一堆看起来没什么大用的代码；继续往下走回到 run_single()。但是在这步结束后我们是能够看到输出，也就是 model_inputs 的值，如果觉得这个输出包含有用的东西，那说明 preprocess() 中有我们需要的代码逻辑，可以在 model_inputs = self.preprocess(...) 下个断点，然后重新开始调试。现在先不管这部分，步入 forward() 方法。如图 6-33，我们又看到了两处眼熟的 forward，那就步过，看程序会走哪处判断，接着继续步入 model_outputs = self._forward(...)。

图 6-33 forward() 方法

到了 _forward() 方法后，继续步过。需要注意在步过的同时我们还需要关注变量窗口，看看有没有什么可能有用的变量。当我们步过 output = self.model.generate(...)，明显会得到一个大概率有用的 output 变量，那就在 output = self.model.generate(...) 这行下个断点，然后中止调试后重启调试。回到 output = self.model.generate(...) 后，两次步入就来到了 generate() 方法。在 generate() 中可以看到清晰的 1~9 的步骤注释，这有助于我们定位到需要分析的代码行。当然不是所有代码中都有这么清晰的注释，所以当前我们已知 output 的值是最后 return 来的，那就直接定位到最后的 return result。然后开始通过 Ctrl + B 转到定义回溯这个 result 是哪来的，这样就定位到了 result = decoding_method(，在这里下个断点。接着看 decoding_method() 中传入的参数，比如我想了解 stopping_criteria=prepared_stopping_criteria 这个参数是干嘛的，继续通过 Ctrl + B 转到定义回溯这个 prepared_stopping_criteria 是哪来的，然后下断点。以此类推，最后我们就回到了 generate() 开头的地方，这个时候需要的断点也已经都下好了。恢复程序后，顺着所下断点进行步过步入等操作后，我们就能完整分析出整个过程的数据流。

参考资料

MoE 架构解析

Tue, 24 Mar 2026 12:34:25 -0800

MoE 架构解析

我们在上一节详细解析了 Llama2 的架构。像 Llama2、GPT-3 这样的模型，通常被称为稠密模型（Dense Model）。这意味着，对于每一个输入的 Token，模型中所有的参数（从第一层到最后一层）都会参与计算。

但是，随着模型规模向万亿级别迈进，全量参数计算带来的算力成本变得不可承受。这就引出了本节的主角——混合专家模型（Mixture of Experts, MoE）。MoE 技术通过一种 “稀疏激活” 的机制，兼具了大规模参数的知识容量与极低的推理成本。Mistral 8x7B 等模型的出现，更是证明了 MoE 在开源大模型领域的巨大潜力，使其成为当前最受关注的技术方向之一。

一、MoE 的来龙去脉

1.1 自适应局部专家混合

最早的 MoE 思想可以追溯到 1991 年 Michael Jordan 和 Geoffrey Hinton 发表的经典论文《Adaptive Mixture of Local Experts》 ¹。这篇论文不仅提出了分治的架构，更重要的是从理论层面解决了神经网络在多任务学习中的根本性难题。

1.1.1 干扰效应与分治思想

在传统的单体神经网络中，如果我们尝试让一个网络同时学习多个截然不同的子任务（例如既学做菜又学修车），往往会出现**“强干扰效应（Strong Interference Effects）”**。这是因为网络的所有权重都参与了所有任务的计算，当网络调整参数以适应任务 A 时，可能会破坏它在任务 B 上已经学到的特征表示。从而导致学习速度变慢，泛化能力变差。

为了解决这个问题，论文提出了一种基于**“分治（Divide and Conquer）”**策略的系统架构：

专家网络：系统包含多个独立的神经网络（可以是简单的前馈网络）。每个专家不再需要处理全局任务，只需专注于输入空间中的一个局部区域或一类特定的子任务。
门控网络：充当协调者的角色。它接收与专家相同的输入 $x$，并输出一组混合比例（Mixing Proportions）$p_i$，即选择每个专家的概率。它就像一个软性的随机开关，决定当前的输入案例应该由哪位专家来主导处理。

1.1.2 损失函数设计

该论文最重要的贡献在于设计了特定的机制来鼓励专家之间的竞争（Competition），而非合作。如果仅仅将所有专家的输出简单线性相加来逼近目标 $\mathbf{y}$，即预测值 $\hat{\mathbf{y}} = \sum p_i \mathbf{E}_i$，并在最终输出上计算误差，专家们会倾向于“合作”。

$$ Loss_{coop} = || \mathbf{y} - \sum_{i} p_i \mathbf{E}_i ||^2 \tag{6.2} $$

在这种合作模式下，为了减小总误差，每个专家都会试图去弥补其他专家的残差。继而导致每个案例都牵动所有专家的权重，依然无法解决“干扰效应”。为了实现解耦，作者提出将系统视为一个随机生成器，并采用负对数似然作为目标函数：

$$ Loss_{comp} = - \log \sum_{i} p_i e^{-\frac{1}{2} || \mathbf{y} - \mathbf{E}_i ||^2} \tag{6.3} $$

其中：

$\mathbf{y}$ 是我们希望模型输出的真实目标。
$\mathbf{E}_i$ 是第 $i$ 个专家的输出。
$p_i$ 是门控网络分配给第 $i$ 个专家的权重（概率）。

在这个目标函数中，系统倾向于**“赢家通吃”。当某个专家 $\mathbf{E}_i$ 的输出非常接近目标 $\mathbf{y}$ 时（即误差项 $|| \mathbf{y} - \mathbf{E}_i ||^2$ 很小），指数项 $e^{-\dots}$ 会变得很大。为了最小化总 Loss，门控网络会倾向于显著增加这个“表现好”的专家的权重 $p_i$，而忽略其他专家。这一机制实现了权重的解耦**。误差反向传播时，只有被选中的“胜出者”和门控网络的权重会被更新，其他专家几乎不受影响。有效缓解了任务间的干扰，实现了“让专业的人干专业的事”。

MoE vs. 集成学习

虽然结构看似相似，但两者有本质区别。集成学习（如随机森林）通常假设基模型是独立或互补的，预测时所有模型都参与，通过投票或加权平均得出结果。而 MoE 强调动态的条件计算，它根据输入数据本身（Data-driven）动态地划分任务空间，不同的输入激活不同的子网络路径。

1.2 深度神经网络中的 MoE

2013 年，Ilya Sutskever 等人发表了论文《Learning Factored Representations in a Deep Mixture of Experts》 ²，将 MoE 与深度学习进行了开创性的结合。

1.2.1 从浅层到深层的变革

在此之前，MoE 通常作为一种独立的浅层模型存在。Ilya 等人的工作打破了这一局限，他们提出 Deep Mixture of Experts（DMoE），将 MoE 结构“模块化”并嵌入到深度神经网络的多个层级中。

意味着 MoE 不再是一个孤立的架构，而成为了一种可插拔的层。我们可以在一个深层网络的不同位置（例如第 1 层和第 2 层）分别插入 MoE 模块，每一层都有自己独立的门控网络和专家集合。

层级化的门控（Hierarchical Gating）：输入 $x$ 首先经过第一层的门控 $g^1$，被路由到第一层的专家 $f^1_i$。第一层的输出 $z^1$ 接着作为第二层门控 $g^2$ 的输入，再次被路由到第二层的专家 $f^2_j$。
指数级增长的组合路径：通过这种堆叠，网络能够表达的有效“专家组合”数量呈指数级增长。如果第一层有 $N$ 个专家，第二层有 $M$ 个专家，那么网络潜在的组合路径就高达 $N \times M$ 种。每个输入样本都会根据其特性，动态地选择一条最适合的处理路径。

1.2.2 学习分解的特征表示

论文的标题强调了“Factored Representations”。通过在不同层级引入混合专家，模型能够自发地在不同层级学习到数据的不同维度的特征。论文在“Jittered MNIST”（带随机平移的手写数字）数据集上观察到了有趣的现象：

第一层专家倾向于根据数字的**位置（Location）**进行分工，成为了“Where Experts”。
第二层专家倾向于根据数字的**类别（Class）**进行分工，成为了“What Experts”。

这种自动的特征解耦证明了深度 MoE 能够有效地利用其深层结构，将复杂任务分解为多个正交的子问题进行处理，为后来 MoE 在 Transformer 中的广泛应用奠定了重要的理论基础。

1.3 稀疏门控 MoE

Google Brain 团队（包括 Geoffrey Hinton 和 Jeff Dean 等）于 2017 年发表了论文《Outrageously Large Neural Networks: The Sparsely-Gated Mixture-of-Experts Layer》 ³，正式将 MoE 带入了超大规模模型（百亿参数级）的时代。

1.3.1 条件计算

当时，深度学习面临一个两难困境。模型容量（参数量）越大，预测准确率通常越高，但计算成本和训练时间也会呈平方级增长。传统的 LSTM 等网络受限于梯度消失和计算资源，很难无限制地加深或加宽。这就引出了条件计算（Conditional Computation）的概念，我们能否在不增加计算量的前提下，大幅增加模型的参数量？

这篇论文给出了肯定的答案。他们设计了一种稀疏门控混合专家层（Sparsely-Gated MoE Layer），可以在每个样本处理过程中只激活网络的一小部分。

1000 倍的模型容量：通过引入多达 1370 亿个参数的 MoE 层（包含数千个专家），该模型在语言建模和机器翻译任务上取得了显著优于 SOTA 的结果，而其计算效率仅有微小的损失。
LSTM + MoE 架构：如图 6-3 所示，研究者将 MoE 层嵌入到堆叠的 LSTM 层之间。左侧展示了该层被卷积式地应用于每个时间步；右侧细节显示，MoE 层接收前一层的输入，通过门控网络（绿色框）计算稀疏权重，仅激活少数专家（灰色框）参与计算，其余专家（白色框）保持闲置。各专家的输出经加权求和后，传递给下一层。对于输入序列中的每一个位置（Token），MoE 都会动态选择不同的专家组合进行处理。

图 6-3：稀疏门控 MoE 层的架构示意图

1.3.2 稀疏性与负载均衡

为了让这一构想落地，论文重点解决了**“如何稀疏选择”以及“如何防止专家崩塌”**这两个关键挑战。

引入噪声的稀疏门控：传统的 Softmax 门控通常会给所有专家分配非零的权重，意味着所有专家都要参与计算，无法节省算力。为此，论文引入了一种带噪声的门控机制：在门控输入中加入可训练的高斯噪声，计算后仅保留权重最大的 $k$ 个专家（例如 $k=4$），将其余所有专家的权重强制置为 $-\infty$（即概率为 0）。如图 6-4 所示，这种稀疏性带来了巨大的收益。在保持计算预算（每步约 800 万次运算）基本不变的情况下，随着专家数量从 4 个增加到 4096 个（横轴），模型参数量剧增，但测试集困惑度（纵轴）显著下降。说明条件计算可以在不增加推理成本的前提下，利用海量参数大幅提升性能。

图 6-4 模型容量与测试集困惑度的关系
避免“赢家通吃”的负载均衡：稀疏选择机制很容易引发**“马太效应”（Rich get richer）**。在训练初期，某些专家可能仅仅因为初始化权重的随机差异而“运气好”被选中。被选中意味着得到了梯度更新，它们变得“更聪明”，从而更有可能在下一次被再次选中。反之，其他落选的专家因得不到训练而持续“愚钝”，最终导致大部分专家“饿死”，模型退化为只有少数活跃专家的稠密模型。

为了解决这个问题，作者在总损失函数中加入了额外的辅助损失（Auxiliary Loss），包含 Importance Loss 和 Load Loss。这些损失函数并不直接服务于预测准确率，而是专门用来惩罚“分配不均”的现象，强制门控网络“雨露均沾”，确保所有专家都能接收到大致相等的样本量，从而得到充分的训练。

二、大模型时代的 MoE

进入 Transformer 时代后，MoE 技术成为了突破模型规模瓶颈的关键。Google 在这一领域进行了密集的探索，通过 GShard、Switch Transformer 和 GLaM 等一系列工作，确立了现代大规模 MoE 的技术范式。

2.1 GShard 迈向六千亿参数

2020 年，Google 提出了 GShard ⁴，旨在将 Transformer 模型扩展到 6000 亿（600B） 参数级别。GShard 不仅仅是一个模型，更是一套支持超大规模稀疏模型并行的训练框架。它通过**数据并行（Data Parallelism）与模型并行（Model Parallelism）**的优雅结合，解决了超大模型无法装入单卡显存、通信开销过大等训练难题。

2.1.1 MoE 层的构建与门控机制

在 GShard 中，MoE 层的应用变得更加标准化。它并没有将所有的层都转换为 MoE 层，而是采用了**“隔层替换”**的策略：

保留 Attention：Transformer 的 Self-Attention 层保持不变，因为其参数量相对较小且计算关键。
替换 FFN：将 Transformer Block 中的前馈神经网络替换为 MoE 层。
隔层设置：通常采用“隔层替换”的策略（例如第 1、3、5 层使用 MoE，第 2、4、6 层保留标准 FFN），在增加容量和保持稳定性之间取得平衡。

对于 MoE 层的计算，GShard 明确了输入 Token $\mathbf{x}$ 的输出 $\mathbf{y}$ 是由门控网络 $\mathcal{G}$ 选择的专家输出的加权和：

$$ \mathbf{y} = \sum_{i=1}^{N} p_i(\mathbf{x}) \cdot \mathbf{E}_i(\mathbf{x}) \tag{6.4} $$

其中：

$p_i(\mathbf{x})$ 是门控网络（Router）计算出的第 $i$ 个专家的权重（通常是 Softmax 后的 Top-k 概率，其余为 0）。
$\mathbf{E}_i(\mathbf{x})$ 是第 $i$ 个专家网络（Expert FFN）对输入 $\mathbf{x}$ 的处理结果。

每个专家 $\mathbf{E}_i$ 内部通常就是一个标准的双层全连接网络：

$$ \mathbf{E}_i(\mathbf{x}) = \mathbf{W}_{out} \cdot \text{ReLU}(\mathbf{W}_{in} \cdot \mathbf{x}) \tag{6.5} $$

在此基础上，GShard 提出了 Top-2 Gating（Top-2 门控） 策略。此前的研究通常使用 Top-k（如 k=4）或更复杂的门控，但 GShard 发现，每个 Token 只路由给 2 个专家（Top-2）就足够了：

第一专家：选择权重最高的专家，保证主要任务的处理。
第二专家：根据权重概率随机选择或直接选择第二高权重的专家，引入辅助处理和一定的随机性，有助于负载均衡。

这种 Top-2 策略成为了后来（包括 Mistral）的标准配置。

2.1.2 分布式并行策略

单张 GPU/TPU 显然无法装下 6000 亿参数。GShard 创造性地结合了数据并行（Data Parallelism）与模型并行（Model Parallelism），解决了超大模型的存储与通信难题。

非 MoE 层（如 Attention）：采用**复制（Replicated）**策略。所有设备持有相同的副本，进行标准的数据并行训练。
MoE 层：采用**分片（Sharded）**策略。专家网络被切分并分布在不同设备上（例如 2048 个专家分布在 2048 个 TPU 核上）。

当一个 Token 需要被路由到不在当前设备的专家时，系统会通过高效的 All-to-All 通信原语，将该 Token 发送到目标设备。计算完成后，再将结果传回。

如图 6-5 展示了从标准 Transformer 到分布式 MoE 的演进。(a) 标准 Transformer 编码器堆叠了 Self-Attention 和 FFN 层；(b) MoE Transformer 将每隔一个 FFN 层替换为 MoE 层；(c) 在跨设备扩展时，Attention 层（黄色）在所有设备间复制，而 MoE 层（红色）则被分片存储。这种“复制与分片”结合的策略，既保证了非 MoE 层的高效计算，又通过分片突破了单设备的显存限制。

图 6-5 GShard MoE Transformer Encoder 架构与并行策略

通过这种设计，GShard 实现了亚线性（Sub-linear） 的计算成本增长。模型参数量增加 16 倍（从 37.5B 到 600B），训练算力成本仅增加了不到 4 倍。

2.2 Switch Transformer

虽然 GShard 验证了规模化路径，但大规模 MoE 的训练仍面临复杂性高、通信成本大和训练不稳定等挑战。2021 年 Google 推出的 Switch Transformer ⁵ 通过简化路由算法和改进训练技术，成功将参数量推向了 1.6 万亿（Trillion）级别，同时实现了 4 倍于 T5-XXL 的训练速度提升。通过表 6-1 可以看出，在相同的算力预算下，Switch Transformer 无论是在质量（负对数困惑度）还是在速度上，都全面超越了传统的 T5 模型以及早期的 MoE 模型。

Model	Capacity Factor	Quality after 100k steps (↑) (Neg. Log Perp.)	Time to Quality Threshold (↓) (hours)	Speed (↑) (examples/sec)
T5-Base	—	-1.731	Not achieved†	1600
T5-Large	—	-1.550	131.1	470
MoE-Base	2.0	-1.547	68.7	840
Switch-Base	2.0	-1.554	72.8	860
MoE-Base	1.25	-1.559	80.7	790
Switch-Base	1.25	-1.553	65.0	910
MoE-Base	1.0	-1.572	80.1	860
Switch-Base	1.0	-1.561	62.8	1000
Switch-Base+	1.0	-1.534	67.6	780

表 6-1 Switch Transformer 与 MoE 及 T5 的性能对比

2.2.1 简化稀疏路由

Switch Transformer 的主要创新在于提出了 Switch Layer。如图 6-6 所示，它用稀疏的 Switch FFN 层（浅蓝色区域）替换了标准 Transformer 中的稠密 FFN 层。在该层中，对于输入序列中的每个 Token（例如图中的 “More” 和 “Parameters”），路由器（Router）会计算其路由概率，并将其分发给唯一的一个专家（实线箭头）进行处理。

这种 **Top-1 Routing（单专家路由）**机制是 Switch Transformer 与传统 MoE（通常路由给 Top-k 个专家，k > 1）最大的区别。尽管看似激进，但它带来了显著的优势：

减少路由计算：路由决策更简单。
降低通信成本：每个 Token 只需发送到一个目的地。
减小专家批量：每个专家需要处理的 Token 数量（Expert Capacity）至少减半。

虽然直觉上 $k=1$ 可能限制了专家的协作，但实验证明这种简化不仅保持了模型质量，还显著提高了计算效率。

图 6-6 Switch Transformer Encoder 架构图

2.2.2 高效稀疏路由与负载均衡

为了在硬件（如 TPU）上高效运行，Switch Transformer 必须解决动态路由带来的负载不均问题。由于硬件通常要求静态的 Tensor 形状，模型必须预设每个专家能处理的最大 Token 数量，即专家容量（Expert Capacity）：

$$ \text{Capacity} = \left( \frac{\text{TotalTokens}}{\text{NumExperts}} \right) \times \text{CapacityFactor} \tag{6.6} $$

Capacity Factor（容量因子）：通常设置为大于 1.0（如 1.0 或 1.25），这一机制的作用如图 6-7 所示。图中每个方块代表专家的处理槽位，Capacity Factor > 1.0 为专家提供了额外的缓冲空间（图中白色空槽位），以应对 Token 分配不均的情况。
Token Dropping（丢弃机制）：当路由到某个专家的 Token 数量超过其容量上限（即公式计算出的 $Capacity$）时（图中红色虚线所示的溢出部分），就会触发丢弃机制。这些多余的 Token 将不会被该专家处理，而是直接通过残差连接传递到下一层。这虽然保证了并行计算的静态形状要求，但也可能导致信息损失，所以合理的容量设置至关重要。

图 6-7 Token 路由动态与专家容量示意图

同时，Switch Transformer 还引入了一个辅助损失函数来尽量减少 Token 的丢弃，鼓励 Token 均匀分布到所有专家：

$$ Loss_{aux} = \alpha \cdot N \cdot \sum_{i=1}^{N} f_i \cdot P_i \tag{6.7} $$

其中：

$f_i$ 是实际分发给专家 $i$ 的 Token 比例（实际上有多少人去了专家 $i$ 那里）。
$P_i$ 是预期路由给专家 $i$ 的概率总和（门控网络觉得专家 $i$ 应该接收多少人）。

这个公式希望“实际去的”和“计划去的”向量的点积最小。只有当两者都均匀分布（即所有专家的负载都相等）时，这个 Loss 才会达到最小值。这迫使 Router 不偏科，雨露均沾。

2.2.3 改进的训练与微调技术

大规模稀疏模型训练极易不稳定，Switch Transformer 提出了一系列改进方案：

Router z-loss：为了提高训练稳定性，Switch Transformer 引入了 z-loss 来惩罚门控网络中过大的 logit 值。这有助于减少数值溢出问题，使训练过程更加平稳。
选择性精度（Selective Precision）：在混合精度训练（通常用 bfloat16）中，路由器的 Softmax 计算容易导致数值不稳定。Switch Transformer 创新地在局部路由计算部分使用 float32，而在其他部分保持 bfloat16。这既保证了稳定性，又没有增加昂贵的 float32 通信成本。
更小的初始化方差：将权重初始化的高斯分布标准差缩减为原来的 $1/10$（例如 $s=0.1$ 而非 $1.0$），显著提升了训练初期的稳定性。
专家正则化（Expert Regularization）：在微调阶段，为了防止过拟合（特别是专家层参数量巨大），模型对专家层内部采用了更高的 Dropout 比率（如 0.4），而非专家层保持较低比率（如 0.1）。

2.3 GLaM 高能效通用语言模型

GLaM （Generalist Language Model） ⁶ 是 Google 在 2021 年推出的通用大语言模型。与 Switch Transformer 采用的 Encoder-Decoder 架构不同，GLaM 采用了与 GPT-3 相同的 Decoder-only 架构，这使其更适合于 Few-shot 和 Zero-shot 生成任务。

GLaM 将参数规模推向了 1.2 万亿，是 GPT-3（175B）的 7 倍。不过，得益于稀疏 MoE 架构，它在保证超大规模参数容量的同时，实现了比 GPT-3 更高的训练和推理效率。

2.3.1 架构特点

GLaM 展示了如何将 MoE 层有效地应用于 Decoder-only 的语言模型中。如图 6-8 它采用了隔层替换策略，即在标准的 Transformer 堆叠中，每隔一个层（upper block）将其中的 FFN 替换为 MoE 层（bottom block）。

在 MoE 层中，Gating 模块会根据输入 Token（例如 “roses”）的特性，从 64 个专家中动态选择出最相关的 2 个专家（蓝色网格所示）。随后，这两个专家的输出经过加权平均后，传递给下一层的 Transformer 模块。这种机制确保了模型在拥有巨大参数量的同时，每次推理仅需激活极少部分的参数。

图 6-8 GLaM 模型架构图

隔层稀疏：类似于 GShard，GLaM 采用隔层替换策略，将每隔一个 Transformer 层中的前馈网络（FFN）替换为 MoE 层。
Top-2 路由：每个 MoE 层包含 64 个专家，对于每个输入 Token，门控网络会选择权重最高的 2 个专家进行处理。
活跃参数：尽管总参数量高达 1.2T，但对于每个 Token，仅激活 966 亿（96.6B） 参数（约占总量的 8%）。这意味着在推理时，GLaM 的计算量（FLOPs）仅为 GPT-3（175B 全激活）的约一半。

此外，GLaM 的研究团队发现，高质量的数据对于大模型的性能很重要。他们开发了一套高质量的文本质量分类器，对原始网页数据进行了严格的过滤。实验表明，使用过滤后的高质量数据训练的模型，在各项任务上的表现均优于使用未过滤海量数据的模型。

2.3.2 性能与能效对比

GLaM 的主要贡献在于证明了稀疏模型可以在减少计算资源消耗的同时，超越同等规模甚至更大规模的稠密模型。

如图 6-9，GLaM（绿色）在 Zero-shot (a)、One-shot (b) 和 Few-shot (c) 设置下，绝大多数任务上都全面优于 GPT-3（橙色）。特别是在图 (d) 的成本对比中，GLaM 的推理计算量仅为 GPT-3 的一半，训练总能耗更是大幅下降至 1/3。

图 6-9 GLaM 与 GPT-3 在各任务性能及训练/推理成本上的详细对比

表 6-2 进一步列出了具体的数值对比，直观地证明了 MoE 架构在实现高性能的同时，显著降低了算力成本。

对比维度	指标	GPT-3 (175B)	GLaM (1.2T)	变化幅度
成本 (Cost)	推理计算量 (FLOPs/token)	350 G	180 G	-48.6%
成本 (Cost)	训练能耗 (Energy)	1287 MWh	456 MWh	-64.6%
平均准确率 (Accuracy)	Zero-shot	56.9	62.7	+10.2%
	One-shot	61.6	65.5	+6.3%
	Few-shot	65.2	68.1	+4.4%

表 6-2：GLaM 与 GPT-3 在成本与性能上的对比

MoE 架构为实现“更大、更强、更环保”的模型提供了一条极具潜力的技术路径。这打破了以往“性能提升必须依靠堆砌更多算力”的固有认知。

三、MoE 架构的创新与实践

随着开源社区的活跃，MoE 技术不再是科技巨头的专属。Mistral 8x7B 和 DeepSeek-R1 的出现，分别在中等规模和超大规模上证明了开源 MoE 模型的强大实力，标志着 MoE 技术进入了全面普及和深度创新的新阶段。

3.1 Mistral 8x7B 如何以小博大

3.1.1 架构与性能概览

Mistral 8x7B (Mixtral) ⁷ 在开源大语言模型中成功实践了 MoE 架构，有力地证明了合理设计的稀疏模型即使不需要万亿参数，也能超越同量级的稠密模型。

架构参数：它拥有约 470 亿（47B） 的总参数量（Sparse Parameters），但对于每个 Token，仅激活 130 亿（13B） 参数（Active Parameters）。这使得它在推理时拥有 13B 模型的计算速度，却能发挥出 47B 模型的知识容量。需要注意的是，虽然计算量较小，但由于所有专家参数都需要加载到内存中，其显存占用（VRAM Usage）依然是 47B 模型级别的。
路由机制：每一层包含 8 个专家（Experts），采用标准的 Top-2 Routing 策略。如图 6-10 所示，每个输入 Token 会被 Router 网络分配给 8 个专家中的 2 个，这两个专家的输出经过加权求和后作为该层的最终输出。这种机制巧妙地在增加模型容量（更多专家）的同时，保持了极低的推理成本（只激活 2 个）。

图 6-10 Mistral 8x7B 的 Top-2 路由机制示意图
性能表现：在 GSM8K（数学）、MMLU（综合知识）、HumanEval（代码）等基准测试上，Mistral 8x7B 以 13B 的活跃参数量超越了稠密的 Llama 2 70B 以及 GPT-3.5。如图 6-11，Mistral 8x7B（黄色柱状图）在几乎所有任务上都包围或持平了 Llama 2 70B（绿色柱状图），特别是在数学和代码生成任务上，其优势尤为显著。
长上下文能力：Mistral 8x7B 支持 32k 的上下文长度，并且在长文本信息检索（Passkey Retrieval）任务中表现出了 100% 的召回率，证明了 MoE 架构在处理长序列时依然稳健。

图 6-11 Mistral 8x7B 与 Llama 2 系列在各基准测试上的性能对比

3.1.2 路由机制分析

Mistral 团队对 Router 选择专家的行为进行了深入分析，得到了一个令人惊讶的结论。专家并没有按预想的那样根据“学科领域”（如生物、数学、哲学）进行分工。

他们统计了不同领域数据（如 arXiv, PubMed, Wikipedia 等）在不同层（Layer 0, 15, 31）的专家分配比例。如图 6-12 可以看出，同一行（即同一个专家）在不同列（不同数据集）上的颜色深浅非常接近。这说明，无论输入文本属于哪个领域，Router 选择各专家的概率分布几乎是一样的。专家似乎更多地是根据语法和Token 结构（如缩进、介词）来分工，而非人类定义的知识领域。

图 6-12 不同领域数据在 Mistral 8x7B 各层中的专家路由分布（显示出无领域偏差的特性）

3.2 DeepSeekMoE 与 DeepSeek-R1

如果说 Mistral 开启了开源 MoE 模型的大门，那么 DeepSeek-R1 ⁸（及其基座 DeepSeek-V3 ⁹）则将开源 MoE 模型的性能推向了与当时顶尖闭源模型（如 OpenAI o1）比肩的高度。DeepSeek 在 MoE 架构上进行了更深度的创新，提出了 DeepSeekMoE ¹⁰ 架构，目标是解决传统 Top-k 路由中的“知识冗余”和“专业化不足”问题。

3.2.1 细粒度专家与共享专家

与 Mistral 采用的“粗粒度”专家不同，如图 6-13 所示，DeepSeekMoE 引入了两个关键策略。

图 6-13 DeepSeekMoE 架构演进：(a) 传统 Top-2 路由; (b) 细粒度专家分割; (c) 细粒度 + 共享专家隔离（最终架构）

细粒度专家分割（Fine-Grained Expert Segmentation）： DeepSeek 将一个标准的大专家拆分为多个更小的专家。对比图 6-13 的 (a) 和 (b) 可以看到，原本的专家 1 被进一步拆分为更小的专家 1 和 2。为了保持总计算量不变，激活的专家数量 $K$ 也相应倍增（从 $K=2$ 变为 $K=4$）。这种变化使得组合的可能性呈指数级增加，让模型能更灵活地组合不同的“知识碎片”来应对复杂输入，从而实现了更高的专家专业化。
共享专家隔离（Shared Expert Isolation）：这是 DeepSeekMoE 的核心创新。如图 6-13(c) 所示，专家 1 被指定为绿色的共享专家（Shared Expert）。它不再经过 Router 选择，而是通过一条独立的通路直接接收输入（Input Hidden），对所有 Token 总是被激活。Router 仅负责从剩余的路由专家中选择 $K=3$ 个进行补充。

这种设计让共享专家负责捕获通用的、跨任务的知识（如语法），而路由专家则专注于特定的领域知识。通过这种“通用+专用”的分离，有效减少了路由专家中重复学习通用知识的冗余，显著提升了参数效率。

可以用公式统一表示为：
$$ \mathbf{y} = \underbrace{\sum_{i \in \mathcal{S}} \mathbf{E}_i(\mathbf{x})}_{\text{Shared Experts}} + \underbrace{\sum_{j \in \text{TopK}(\mathcal{R})} p_j(\mathbf{x}) \cdot \mathbf{E}_j(\mathbf{x})}_{\text{Routed Experts}} \tag{6.8} $$
其中 $\mathcal{S}$ 代表共享专家集合（总是被激活），$\mathcal{R}$ 代表路由专家集合（仅选择性激活）。这种双路径结构是其区别于传统 MoE（公式 6.4）的关键。

3.2.2 性能里程碑

DeepSeek-R1 不仅在常规任务上表现出色，更通过大规模强化学习具备了强大的逻辑推理能力。DeepSeek-R1 在 AIME 2024（数学竞赛）上 Pass@1 准确率达到 79.8%，稍高于 OpenAI-o1-1217；在 MATH-500 上达到 97.3%，与 o1 持平。在 Codeforces 编程竞赛中，其 Elo 等级分达到 2029，超过了 96.3% 的人类参赛者。如图 6-14 所示，DeepSeek-R1（深蓝色柱状图）在多个推理密集型基准测试中均展现出了与顶尖闭源模型（如 OpenAI-o1-1217，灰色柱状图）分庭抗礼的实力。

图 6-14 DeepSeek-R1 在数学、代码及知识类基准测试上的性能表现

四、MoE 代码实战

接下来，让我们基于上节实现的 Llama2 的代码，将标准的稠密 FFN 层替换为 MoE 层，从而实现一个简单的 MoE 模型。只需要对原有代码进行两处修改。首先在 src/ffn.py 中新增一个包含门控网络和多专家的 MoE 类，随后在 src/transformer.py 中用这个新类替换掉原有的 FeedForward 层。而模型的其他核心组件（如 Attention, RoPE, Norm 等）保持不变。下面来逐一实现。

如图 6-15 在 Transformer Block 中（紫色区域）引入了 Router 和 Experts，这就组成了我们的 Llama2 + MoE 架构。输入经过 RMS Norm 后，进入 MoE 层。Router 根据输入计算每个 Expert 的权重，并选择 Top-k 个 Expert。选中的 Expert 并行处理输入，最后将各 Expert 的输出加权求和，作为 MoE 层的最终输出。

图 6-15 Llama2 + MoE 架构图

本节完整代码

4.1 实现 MoE 层

我们在 src/ffn.py 中原有的 FeedForward 类下方，新增一个 MoE 类。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


# code/C6/MoE/src/ffn.py
# ... (保留原有的 FeedForward 类)

class MoE(nn.Module):
 def __init__(self, dim: int, hidden_dim: int, multiple_of: int, ffn_dim_multiplier: Optional[float], num_experts: int = 8, top_k: int = 2):
 super().__init__()
 self.num_experts = num_experts
 self.top_k = top_k
 # 门控网络：决定每个 Token 去往哪个专家
 self.gate = nn.Linear(dim, num_experts, bias=False)
 # 专家列表：创建 num_experts 个独立的 FeedForward 网络
 self.experts = nn.ModuleList([
 FeedForward(dim, hidden_dim, multiple_of, ffn_dim_multiplier)
 for _ in range(num_experts)
 ])

 def forward(self, x: torch.Tensor) -> torch.Tensor:
 # x: (batch_size, seq_len, dim)
 B, T, D = x.shape
 x_flat = x.view(-1, D)

 # 1. 门控网络
 gate_logits = self.gate(x_flat) # (B*T, num_experts)
 # 2. Top-k 路由
 weights, indices = torch.topk(gate_logits, self.top_k, dim=-1)
 weights = F.softmax(weights, dim=-1) # 归一化权重

 output = torch.zeros_like(x_flat)

 for i, expert in enumerate(self.experts):
 # 3. 找出所有选中当前专家 i 的 token 索引
 batch_idx, k_idx = torch.where(indices == i)

 if len(batch_idx) == 0:
 continue

 # 4. 取出对应的输入进行计算
 expert_input = x_flat[batch_idx]
 expert_out = expert(expert_input)

 # 5. 获取对应的权重
 expert_weights = weights[batch_idx, k_idx].unsqueeze(-1) # (num_selected, 1)

 # 6. 将结果加权累加回输出张量
 output.index_add_(0, batch_idx, expert_out * expert_weights)

 return output.view(B, T, D)

这个实现虽然是循环处理，不如 CUDA Kernel 高效，但逻辑非常清晰：

Gate（门控）: 通过 self.gate(x_flat) 计算每个 Token 对所有 8 个专家的打分（Logits）。
Top-k（路由）: 使用 torch.topk 选出每个 Token 分数最高的 k=2 个专家及其索引。并通过 Softmax 对这 k 个权重进行归一化，确保它们的和为 1。
Dispatch（分发与计算）: 这是 MoE 的核心。我们遍历每一个专家：
- 通过 torch.where 找出所有被分配给当前专家的 Token 索引。
- 将这些 Token 挑选出来（Index Select），送入对应的 expert 网络（即一个 SwiGLU FFN）进行计算。
Combine（加权聚合）: 专家的输出并不是直接作为最终结果。我们需要将专家的输出乘以对应的门控权重（Weight），然后通过 index_add_ 累加回输出张量 output 的对应位置。

这样，每个 Token 最终的输出就是它所激活的 2 个专家输出的加权和。

4.2 替换 TransformerBlock

接下来修改 src/transformer.py，引入我们刚写的 MoE 类，并替换掉原来的 FeedForward。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# code/C6/MoE/src/transformer.py
# ...
from .ffn import FeedForward, MoE # 导入 MoE

class TransformerBlock(nn.Module):
 def __init__(
 # ... args ...
 ):
 super().__init__()
 # ...

 # 修改：使用 MoE 替换标准的 FeedForward
 self.feed_forward = MoE(
 dim=dim,
 hidden_dim=4 * dim,
 multiple_of=multiple_of,
 ffn_dim_multiplier=ffn_dim_multiplier,
 num_experts=8, # 定义8个专家
 top_k=2, # 每个Token激活2个专家
 )
 # ...

这里我们将专家数设为 8，Top-k 设为 2，刚好是 Mistral 8x7B 的经典配置。

4.3 运行验证

最后，我们不需要修改 main.py 中的任何逻辑，直接运行即可。因为对于外部调用者来说，LlamaTransformer 的接口（输入输出形状）没有任何变化，MoE 的复杂性被完全封装在了层内部。运行后，如果看到下面的输出，说明我们的 MoE 模型已经成功跑通了。

输出：

1

logits shape: (2, 16, 1000)

通过这不到 50 行代码的修改，我们就把一个标准的 Llama2 改进成了一个具备稀疏激活能力的 MoE 模型。这种能够作为通用、可插拔组件无缝集成到现有 Transformer 架构中的特性，也正是 MoE 架构优雅之处的体现。

参考文献

手搓Llama2大模型

Tue, 24 Mar 2026 11:34:25 -0800

手搓Llama2大模型

前面我们已经深入学习了 注意力机制、Transformer 架构，以及基于其 Encoder 衍生的 BERT 和基于 Decoder 衍生的 GPT。接下来尝试亲手实现一个（曾经的）前沿大语言模型，看看它的模型结构究竟有什么不同。本节将聚焦于 Llama2，一个由 Meta AI 推出的开源大模型。我们不再依赖 transformers 库的高度封装，而是从零开始，先梳理关键思想与设计取舍，再逐步落地到代码实现。这一过程将有助于学习原理，深化对大模型内部工作的理解。

一、Llama2 架构总览

Llama2 遵循了 GPT 系列开创的 Decoder-Only 架构，也就意味着它完全由 Transformer 解码器层堆叠而成，天然适用于自回归的文本生成任务。如图 6-1 所示，Llama2 的核心是 N 个相同的 Transformer Block 堆叠，其内部数据流展示了多项关键设计。与经典 Transformer 的后归一化不同，输入在进入注意力层和前馈网络之前，都会先经过一次 RMS Norm 进行预归一化（Pre-Normalization），正如当初 GPT-2/3 转向 Pre-Norm 解决了深层网络的训练难题一样，这种预归一化被认为是提升大模型训练稳定性的关键。其次在组件升级上，模型支持了 Grouped-Query Attention（GQA）（如 Llama2-70B 采用 ¹，小模型可视为 n_kv_heads == n_heads 的 MHA 特例），前馈网络采用了 SwiGLU，并且归一化统一使用 RMSNorm。除此之外，位置信息并不是在输入端与词嵌入相加，而是通过 RoPE（旋转位置编码）操作在注意力层内部动态地施加于查询（Q）和键（K）向量之上。最后，每个诸如注意力层和前馈网络等子层的输出都通过残差连接（+号）与子层的输入相加，从而完整且无损地保留了原始信息流。整个模型的数据流自下而上贯穿所有 Transformer Block，最后经过一次最终的 RMS Norm 和一个线性输出层，得到 Logits。

图 6-1：Llama2 架构示意图

与原始 Transformer 解码器相比，Llama2 及其同类模型进行了一系列改进，以提升性能和训练稳定性。它的数据流可以概括为：

（1）输入嵌入：将 token_ids 转换为词向量。

（2）N x Transformer 层堆叠：数据依次通过 N 个相同的 Transformer Block。

预归一化：在进入子层之前，先进行一次 RMSNorm。
注意力子系统：包含旋转位置编码、分组查询注意力（GQA） 和 KV 缓存机制。
前馈网络子系统：采用 SwiGLU 激活函数。

（3）最终归一化与输出：在所有层之后，进行最后一次 RMSNorm，并通过一个线性层将特征映射到词汇表 logits。

下面，我们将根据图 6-1 中 Llama2 的结构顺序，从输入端开始，逐一实现其核心组件。

二、关键组件详解

本节完整代码

2.1 预归一化

标准的 Layer Normalization 在 Transformer 中用于稳定训练，但它的计算（减去均值、除以标准差）相对复杂。为了在保证性能的同时提升计算效率，Llama2 采用了它的变体 RMSNorm（Root Mean Square Layer Normalization） ²。目的为了简化归一化过程，一方面移除均值中心化，只通过输入的均方根（Root Mean Square）对它进行缩放；另一方面保留可学习增益，依然保留一个可学习的 weight 参数 ($\gamma$)，用于在归一化后恢复模型的表达能力。公式如下，其中 $x$ 是输入向量， $\gamma$ 是可学习的缩放参数：

$$ y = \frac{x}{\sqrt{\frac{1}{n}\sum_{i=1}^{n}x_i^2 + \epsilon}} \cdot \gamma $$

在接口定义方面，输入是一个形状为 [batch_size, seq_len, dim] 的张量 x，输出是与输入形状相同的张量，其中每个词元（dim 维度）都会被独立归一化。

之前的学习中我们已经知道，原始的文本数据首先会被分词器（Tokenizer）转换成一个由整数ID组成的序列。为了进行批处理，我们会将多个这样的序列打包在一起，形成一个形状为 [batch_size, seq_len] 的二维张量。随后，这个张量会经过一个词嵌入层（Embedding Layer），将每个整数ID映射成一个高维向量。这个向量的维度就是 dim。这样，我们就得到了一个 [batch_size, seq_len, dim] 形状的三维张量，这就是 Transformer Block 的标准输入。

具体代码实现（src/norm.py）如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# code/C6/llama2/src/norm.py
class RMSNorm(nn.Module):
 def __init__(self, dim: int, eps: float = 1e-6):
 super().__init__()
 self.eps = eps
 self.weight = nn.Parameter(torch.ones(dim)) # 对应公式中的 gamma

 def _norm(self, x: torch.Tensor) -> torch.Tensor:
 # 核心计算：x * (x^2的均值 + eps)的平方根的倒数
 return x * torch.rsqrt(x.pow(2).mean(dim=-1, keepdim=True) + self.eps)

 def forward(self, x: torch.Tensor) -> torch.Tensor:
 out = self._norm(x.float()).type_as(x)
 return out * self.weight

在这里，_norm 方法精确地实现了 RMSNorm 的核心公式，self.eps 则是一个为了防止除以零而添加的小常数，保证了数值稳定性。为了确保代码的独立可用性和正确性，我们还可以进行简单的单元测试。为此添加一个 if __name__ == "__main__" 测试块，这是一种良好的工程实践，可以单独运行此文件来快速验证功能：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# code/C6/llama2/src/norm.py
if __name__ == "__main__":
 # 准备参数和输入
 batch_size, seq_len, dim = 4, 16, 64
 x = torch.randn(batch_size, seq_len, dim)

 # 初始化并应用 RMSNorm
 norm = RMSNorm(dim)
 output = norm(x)

 # 验证输出形状
 print("--- RMSNorm Test ---")
 print("Input shape:", x.shape)
 print("Output shape:", output.shape)

2.2 旋转位置编码

我们在 Transformer 章节中已经知道，模型需要位置信息来理解词元的顺序。传统的位置编码（无论是固定的还是可学习的）是一种绝对位置编码，它为每个位置分配一个独立的向量。Llama2 采用了更先进的 旋转位置编码（Rotary Positional Embedding, RoPE） ³，它是一种相对位置编码。与传统位置编码通过加法直接注入词嵌入的方式不同，RoPE 的策略是让位置信息不再是"加"到词嵌入上，而是在计算注意力时，通过复数"乘法"的方式"旋转"Query 和 Key 向量。

图 6-2：RoPE 旋转位置编码的工作原理

如图 6-2 所示，RoPE 通过复数乘法实现向量旋转。在数学原理上，将向量的每对维度 $(x_1, x_2)$ 视为复数 $x_1 + ix_2$，复数可表示为 $r e^{i\theta}$（$r$ 为模，$\theta$ 为幅角），两复数相乘时模相乘、幅角相加，即 $(r_1 e^{i\theta_1}) \cdot (r_2 e^{i\theta_2}) = r_1 r_2 e^{i(\theta_1 + \theta_2)}$，RoPE 的 freqs_cis 是模为 1 的复数 $e^{im\theta}$（$m$ 为位置），与 Q/K 向量相乘后得到旋转后的 $(x’_1, x’_2)$，只改变方向而不改变长度。在位置编码方面，序列中每个位置（1-6）的 Query/Key 向量被旋转不同的角度，位置越靠后旋转越大，颜色变化体现了这一点，以此将位置信息编码到向量的方向上。

RoPE 的优势主要体现在三个方面。第一个是相对位置编码，两个词元（位置 $m$ 和 $n$）旋转后的 Q/K 点积仅与相对距离 $m-n$ 相关，与绝对位置无关，这让注意力模式具备平移不变性，也就是说相距 2 个位置的词元关系，无论出现在序列何处计算方式都一致。其次是长度外推能力，由于依赖相对位置，模型对超出训练长度的序列仍能较好地处理位置关系。最后是计算高效，它通过复数乘法实现，不改变向量模长，避免了额外的归一化操作。在接口上，RoPE 的实现分为两部分：

（1）precompute_freqs_cis: 预计算一个包含旋转角度信息的复数张量 freqs_cis，这个张量在模型初始化时计算一次即可。它的输入包括 head 的维度 dim、序列最大长度 end 以及一个用于控制频率范围的超参数 theta，最终输出一个形状为 [end, dim / 2] 的复数张量。

（2）apply_rotary_emb: 将预计算的 freqs_cis 应用于输入的 Query 和 Key 向量。输入端需要传入形状为 [batch_size, seq_len, n_heads, head_dim] 的 Query 向量 xq、形状为 [batch_size, seq_len, n_kv_heads, head_dim] 的 Key 向量 xk，以及预计算的旋转矩阵切片 freqs_cis，它会输出旋转后的 xq 和 xk，且两者的形状保持不变。

我们知道，进入注意力模块的张量 x 的形状是 [batch_size, seq_len, dim]。为了实现多头注意力，首先要将这个张量通过一个线性层（例如 wq），它将输入从 dim 维投影到 n_heads * head_dim 维。在 Llama2 的设计中，输入维度 dim 恰好等于 n_heads * head_dim，所以这个线性层实际上是一个 dim 到 dim 的投影，其输出张量形状依然是 [batch_size, seq_len, dim]。关键的一步发生在之后：我们利用 dim = n_heads * head_dim 这一关系，通过一次 view 或 reshape 操作，将最后一个维度 dim 逻辑上拆分为 n_heads 和 head_dim 两个维度，从而得到 [batch_size, seq_len, n_heads, head_dim] 这样的四维张量。这个形状的含义是：对于每个词元，我们都计算出了 n_heads 个独立的、维度为 head_dim 的 Query 向量表示。对 Key 向量 xk 的处理也是完全类似的。

对应的代码实现（src/rope.py）如下：

（1）precompute_freqs_cis:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def precompute_freqs_cis(dim: int, end: int, theta: float = 10000.0) -> torch.Tensor:
 # 1. 计算频率：1 / (theta^(2i/dim))
 freqs = 1.0 / (theta ** (torch.arange(0, dim, 2)[: (dim // 2)].float() / dim))
 # 2. 生成位置序列 t = [0, 1, ..., end-1]
 t = torch.arange(end, device=freqs.device)
 # 3. 计算相位：t 和 freqs 的外积
 freqs = torch.outer(t, freqs).float()
 # 4. 转换为复数形式 (cos(theta) + i*sin(theta))
 freqs_cis = torch.polar(torch.ones_like(freqs), freqs)
 return freqs_cis

其中 torch.arange(0, dim, 2) / dim 对应公式中的 2i/dim：i 实际遍历的是偶数维索引（长度为 dim/2）。

（2）reshape_for_broadcast: 辅助函数，用于将 freqs_cis 的形状调整为可以与 Q/K 向量进行广播乘法。

1
2
3
4


def reshape_for_broadcast(freqs_cis: torch.Tensor, x: torch.Tensor) -> torch.Tensor:
 ndim = x.ndim
 shape = [d if i == 1 or i == ndim - 1 else 1 for i, d in enumerate(x.shape)]
 return freqs_cis.view(*shape)

（3）apply_rotary_emb:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def apply_rotary_emb(
 xq: torch.Tensor,
 xk: torch.Tensor,
 freqs_cis: torch.Tensor,
) -> tuple[torch.Tensor, torch.Tensor]:
 # 将 Q/K 向量视为复数
 xq_ = torch.view_as_complex(xq.float().reshape(*xq.shape[:-1], -1, 2))
 xk_ = torch.view_as_complex(xk.float().reshape(*xk.shape[:-1], -1, 2))

 # 准备广播
 freqs_q = reshape_for_broadcast(freqs_cis, xq_) # 针对 Q 的广播视图

 # 复数乘法即为旋转
 xq_out = torch.view_as_real(xq_ * freqs_q).flatten(3)

 # K 向量可能与 Q 向量有不同的头数（GQA），所以需单独生成广播视图
 freqs_k = reshape_for_broadcast(freqs_cis, xk_)
 xk_out = torch.view_as_real(xk_ * freqs_k).flatten(3)
 return xq_out.type_as(xq), xk_out.type_as(xq)

在这部分代码中，torch.view_as_complex 将 head_dim 维的实数向量巧妙地看作 head_dim/2 维的复数向量。而核心操作 xq_ * freqs_cis 正是旋转的实现，因为在复数域中，两个复数相乘即表示幅角相加、模相乘，由于 freqs_cis 的模为 1，这个操作就等价于将 xq_ 向量旋转 freqs_cis 所代表的角度。此外代码还通过分别为 Q 和 K 生成广播视图（freqs_q 与 freqs_k）来兼容 GQA 带来的形状差异。关于参数 theta，它是 RoPE 的“基底”，控制位置编码的频率范围，10000.0 是一个标准值。在工程考量上，LlamaTransformer 初始化时，预计算的长度通常会大于 max_seq_len（例如 max_seq_len * 2），这是为了给推理时处理更长序列提供“缓冲”，避免重新计算。我们接着对 rope.py 文件包含的三个核心函数进行测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# code/C6/llama2/src/rope.py
if __name__ == "__main__":
 # 准备参数和输入
 batch_size, seq_len, n_heads, n_kv_heads, head_dim = 4, 16, 8, 2, 16
 dim = n_heads * head_dim
 n_rep = n_heads // n_kv_heads

 # --- Test precompute_freqs_cis ---
 print("--- Test precompute_freqs_cis ---")
 freqs_cis = precompute_freqs_cis(dim=head_dim, end=seq_len * 2)
 print("freqs_cis shape:", freqs_cis.shape)

 # --- Test apply_rotary_emb ---
 print("\n--- Test apply_rotary_emb ---")
 xq = torch.randn(batch_size, seq_len, n_heads, head_dim)
 xk = torch.randn(batch_size, seq_len, n_kv_heads, head_dim)
 freqs_cis_slice = freqs_cis[:seq_len]
 xq_out, xk_out = apply_rotary_emb(xq, xk, freqs_cis_slice)
 print("xq shape (in/out):", xq.shape, xq_out.shape)
 print("xk shape (in/out):", xk.shape, xk_out.shape)

2.3 分组查询注意力

标准的多头注意力（Multi-Head Attention, MHA） 为每个 Query 头都配备了一组独立的 Key 和 Value 头。这意味着 K 和 V 投影矩阵的尺寸以及推理时 KV 缓存的大小都与总头数 n_heads 成正比，当模型规模增大时，这部分开销变得非常显著。而分组查询注意力（Grouped-Query Attention, GQA） ⁴ 就是对此的核心优化，它的思路是允许多个 Query 头共享同一组 Key 和 Value 头。具体来说，MHA 中每个 Q 头都有自己的 K/V 头（即 n_heads 与 n_kv_heads 相等），而 GQA 则是让每组 Q 头共享一组 K/V 头（此时 n_heads 大于 n_kv_heads）。还有一种特殊情况是多查询注意力（MQA），所有 Q 头共享唯一的一组 K/V 头（n_kv_heads 等于 1），可以被视为 GQA 的特例。

通过分组，GQA 在保持 MHA 大部分性能的同时，显著减少了 K/V 相关的计算量和显存占用，这对于加速模型推理很重要。它带来了显存节省和计算加速两方面的收益，其中显存节省体现在 KV 缓存的大小从与 n_heads 成正比降低为与 n_kv_heads 成正比，约为原来的 n_kv_heads / n_heads，对于 70B 模型可以节省数十 GB 的显存，而计算加速则来源于注意力计算中 K/V 投影和后续矩阵乘法的计算量同步下降。例如，当一个模型有 n_heads = 32 个查询头并采用 GQA，将 n_kv_heads 设为 8 时，Key 和 Value 相关的参数量、计算量以及 KV 缓存大小都会减少到原来的四分之一。

具体到该模块的设计，输入需要一个形状为 [batch_size, seq_len, dim] 的张量 x，以及与标准 Attention 类似的 start_pos、freqs_cis 和 mask（分别用于 KV 缓存、位置编码和因果遮蔽）。最终输出一个形状仍为 [batch_size, seq_len, dim] 的张量。这里的关键实现是在计算注意力分数前，需要将 K 和 V 的头“复制” n_rep 次（n_rep = n_heads / n_kv_heads），使其数量与 Q 头匹配，以便进行进一步的矩阵乘法。为实现 GQA 的头数对齐，需要辅助函数 repeat_kv（定义在 src/rope.py 中）。之所以放在该文件，是因为我们将与注意力计算相关的“无状态张量算子”（如 RoPE 的 apply_rotary_emb、precompute_freqs_cis 以及头复制 repeat_kv）集中到同一处，便于复用、解耦 attention.py 的类实现，并避免引入更重的依赖。该函数通过 expand 和 reshape 将 [batch_size, seq_len, n_kv_heads, head_dim] 的 K/V 张量按 n_rep 复制为 [batch_size, seq_len, n_kv_heads * n_rep, head_dim]，以与 Q 头数对齐。代码实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# code/C6/llama2/src/rope.py
def repeat_kv(x: torch.Tensor, n_rep: int) -> torch.Tensor:
 batch_size, seq_len, n_kv_heads, head_dim = x.shape
 if n_rep == 1:
 return x
 return (
 x[:, :, :, None, :]
 .expand(batch_size, seq_len, n_kv_heads, n_rep, head_dim)
 .reshape(batch_size, seq_len, n_kv_heads * n_rep, head_dim)
 )

接下来，实现 GroupedQueryAttention 类。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# code/C6/llama2/src/attention.py
class GroupedQueryAttention(nn.Module):
 def __init__(self, dim: int, n_heads: int, n_kv_heads: int | None = None, ...):
 ...
 self.n_local_heads = n_heads
 self.n_local_kv_heads = n_kv_heads
 self.n_rep = self.n_local_heads // self.n_local_kv_heads # Q头与KV头的重复比
 ...
 self.wq = nn.Linear(dim, n_heads * self.head_dim, bias=False)
 self.wk = nn.Linear(dim, n_kv_heads * self.head_dim, bias=False)
 self.wv = nn.Linear(dim, n_kv_heads * self.head_dim, bias=False)
 ...

 def forward(self, x, start_pos, freqs_cis, mask):
 xq = self.wq(x).view(batch_size, seq_len, self.n_local_heads, self.head_dim)
 xk = self.wk(x).view(batch_size, seq_len, self.n_local_kv_heads, self.head_dim)
 xv = self.wv(x).view(batch_size, seq_len, self.n_local_kv_heads, self.head_dim)

 xq, xk = apply_rotary_emb(xq, xk, freqs_cis=freqs_cis)

 # ... KV Cache 逻辑 ...

 keys = repeat_kv(keys, self.n_rep) # <-- 关键步骤
 values = repeat_kv(values, self.n_rep) # <-- 关键步骤

 scores = torch.matmul(xq.transpose(1, 2), keys.transpose(1, 2).transpose(2, 3)) / ...
 ...

可以看到 wq、wk、wv 的输出维度不同，分别对应 n_heads 和 n_kv_heads，这直接体现了 GQA 的设计。而且在计算注意力分数之前，通过 repeat_kv 函数将 K 和 V 的头进行扩展，使其数量与 Q 头匹配，从而能够进行标准的注意力计算。为了测试 GQA 模块的正确性，我们需要完整初始化 GroupedQueryAttention 类，并为 forward 方法准备好所有必需的输入（其中包括模拟的 freqs_cis 行测试用例）。测试的核心是验证经过整个注意力计算流程后，输出张量的形状是否与输入一致：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# code/C6/llama2/src/attention.py
if __name__ == "__main__":
 # 准备参数和输入
 batch_size, seq_len, dim = 4, 16, 128
 n_heads, n_kv_heads = 8, 2
 head_dim = dim // n_heads

 # 初始化注意力模块
 attention = GroupedQueryAttention(
 dim=dim,
 n_heads=n_heads,
 n_kv_heads=n_kv_heads,
 max_batch_size=batch_size,
 max_seq_len=seq_len,
 )

 # 准备输入
 x = torch.randn(batch_size, seq_len, dim)
 freqs_cis = precompute_freqs_cis(dim=head_dim, end=seq_len * 2)
 freqs_cis_slice = freqs_cis[:seq_len]

 # 执行前向传播
 output = attention(x, start_pos=0, freqs_cis=freqs_cis_slice)

 # 验证输出形状
 print("--- GroupedQueryAttention Test ---")
 print("Input shape:", x.shape)
 print("Output shape:", output.shape)

2.4 SwiGLU 前馈网络

Transformer 中的前馈网络为模型提供了非线性计算能力，通常由两个线性层和一个 ReLU 激活函数构成。Llama2 采用了一种变体 SwiGLU⁵，被证明能带来更好的性能。其核心是引入门控机制，使用三个线性变换（W、V、W2）而不是两个。第一个变换 xW 会先经过 Swish 激活函数（swish(x) = x * sigmoid(x)），接着第二个变换 xV 作为“门”，与前一步的结果进行逐元素相乘，最后通过第三个变换 W2 输出。公式表示如下，其中 $\otimes$ 是逐元素乘法：

$$ \text{SwiGLU}(x, W, V, W_2) = (\text{swish}(xW) \otimes xV)W_2 $$

这种门控结构允许网络动态地控制信息流，被认为是它性能优于标准 ReLU FFN 的主要原因。从输入输出上看，网络接收形状为 [batch_size, seq_len, dim] 的张量 x 作为输入，并输出形状与输入完全相同的张量。另外，中间隐藏层的维度 hidden_dim 通常会大于 dim，Llama2 中通过特定公式计算并对其进行对齐，以提高硬件计算效率。对应的代码实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# code/C6/llama2/src/ffn.py
class FeedForward(nn.Module):
 def __init__(self, dim: int, hidden_dim: int, multiple_of: int, ...):
 super().__init__()
 # hidden_dim 计算，并用 multiple_of 对齐以提高硬件效率
 hidden_dim = int(2 * hidden_dim / 3)
 ...
 hidden_dim = multiple_of * ((hidden_dim + multiple_of - 1) // multiple_of)

 self.w1 = nn.Linear(dim, hidden_dim, bias=False) # 对应 W
 self.w2 = nn.Linear(hidden_dim, dim, bias=False) # 对应 W2
 self.w3 = nn.Linear(dim, hidden_dim, bias=False) # 对应 V

 def forward(self, x: torch.Tensor) -> torch.Tensor:
 # F.silu(self.w1(x)) 实现了 swish(xW)
 # * self.w3(x) 实现了门控机制
 return self.w2(torch.nn.functional.silu(self.w1(x)) * self.w3(x))

在这段代码中，torch.nn.functional.silu 指的就是 PyTorch 内置的 Swish 激活函数，整个 forward 函数准确地实现了 SwiGLU 的公式。最后，我们为 FeedForward 模块添加了一段测试代码，验证它能否正确处理输入张量并返回相同形状的输出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# code/C6/llama2/src/ffn.py
if __name__ == "__main__":
 # 准备参数和输入
 batch_size, seq_len, dim = 4, 16, 128

 # 初始化 FFN 模块
 ffn = FeedForward(
 dim=dim,
 hidden_dim=4 * dim,
 multiple_of=256,
 ffn_dim_multiplier=None
 )

 # 准备输入
 x = torch.randn(batch_size, seq_len, dim)

 # 执行前向传播
 output = ffn(x)

 # 验证输出形状
 print("--- FeedForward (SwiGLU) Test ---")
 print("Input shape:", x.shape)
 print("Output shape:", output.shape)

三、模型组装与前向传播

有了所有核心组件，我们就可以将它们组装成一个完整的 LlamaTransformer 了。代码实现如下：

（1）TransformerBlock: 这是构成 Llama2 的基本单元。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# code/C6/llama2/src/transformer.py
class TransformerBlock(nn.Module):
 def __init__(self, layer_id: int, ...):
 ...
 self.attention = GroupedQueryAttention(...)
 self.feed_forward = FeedForward(...)
 self.attention_norm = RMSNorm(...)
 self.ffn_norm = RMSNorm(...)

 def forward(self, x, start_pos, freqs_cis, mask):
 # 预归一化 + 残差连接
 h = x + self.attention(self.attention_norm(x), start_pos, freqs_cis, mask)
 out = h + self.feed_forward(self.ffn_norm(h))
 return out

代码清晰地展示了 预归一化 结构。先 RMSNorm，再送入 attention 或 feed_forward，最后进行残差连接。

（2）LlamaTransformer: 顶层模型，负责堆叠 TransformerBlock 并处理输入输出。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# code/C6/llama2/src/transformer.py
class LlamaTransformer(nn.Module):
 def __init__(self, vocab_size: int, ...):
 ...
 self.tok_embeddings = nn.Embedding(vocab_size, dim)
 self.layers = nn.ModuleList([TransformerBlock(...) for i in range(n_layers)])
 self.norm = RMSNorm(dim, eps=norm_eps)
 self.output = nn.Linear(dim, vocab_size, bias=False)
 self.register_buffer("freqs_cis", precompute_freqs_cis(...))

 def forward(self, tokens: torch.Tensor, start_pos: int) -> torch.Tensor:
 h = self.tok_embeddings(tokens)

 # 1. 准备 RoPE 旋转矩阵
 freqs_cis = self.freqs_cis[start_pos : start_pos + seq_len]

 # 2. 准备因果掩码 (Causal Mask)
 mask = None
 if seq_len > 1:
 mask = torch.full((seq_len, seq_len), float("-inf"), device=tokens.device)
 mask = torch.triu(mask, diagonal=1)
 # 考虑 KV Cache 的偏移
 mask = torch.hstack([torch.zeros((seq_len, start_pos), ...), mask]).type_as(h)

 # 3. 循环通过所有 TransformerBlock
 for layer in self.layers:
 h = layer(h, start_pos, freqs_cis, mask)

 h = self.norm(h)
 logits = self.output(h).float()
 return logits

在上述 LlamaTransformer 的实现中，tok_embeddings 负责将 token ID 转换为向量，layers 使用 nn.ModuleList 堆叠了 N 个 TransformerBlock，而 norm 和 output 构成了最终的归一化和线性输出层。至于 freqs_cis 则是用于预先计算并缓存 RoPE 旋转矩阵。整个 forward 流程，首先会进行 freqs_cis 切片，即根据当前输入的 start_pos 和 seq_len，从预计算的旋转矩阵中取出需要的部分。接着进行 mask 构造，这也是实现因果语言模型的关键环节，通过 torch.triu 创建一个上三角矩阵，确保每个位置只能关注到它自己和它之前的位置。torch.hstack 则进一步考虑了 start_pos，配合 KV 缓存（在推理时 start_pos > 0），确保当前 Query 可以关注到缓存中所有的历史 Key。完成构建后，特征便会循环调用 TransformerBlock 逐层处理，并最终通过 norm 和 output 层得到对应的 logits。

四、整体验证

4.1 快速验证

在所有组件实现并组装后，我们可以通过一个简单脚本来验证整个 LlamaTransformer 模型的输入输出是否符合预期。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# code/C6/llama2/main.py
import torch
from src.transformer import LlamaTransformer

def main() -> None:
 # 使用小尺寸参数，便于 CPU/GPU 都能快速跑通
 model = LlamaTransformer(
 vocab_size=1000,
 dim=256,
 n_layers=2,
 n_heads=8,
 n_kv_heads=2,
 multiple_of=64,
 ffn_dim_multiplier=None,
 norm_eps=1e-6,
 max_batch_size=4,
 max_seq_len=64,
 )

 # 构造随机 token 序列并执行前向
 batch_size, seq_len = 2, 16
 tokens = torch.randint(0, 1000, (batch_size, seq_len))
 logits = model(tokens, start_pos=0)

 # 期望: [batch_size, seq_len, vocab_size]
 print("logits shape:", tuple(logits.shape))

if __name__ == "__main__":
 main()

我们会看到如下输出，这证明模型已经能够正确处理输入并返回符合预期的 logits 张量：

1

logits shape: (2, 16, 1000)

这个脚本实例化了一个小型的 LlamaTransformer，并用一个随机的 tokens 张量（代表一个批次、长度为16的两个句子）作为输入，执行了模型的前向传播，最终验证了输出 logits 的形状与 [batch_size, seq_len, vocab_size] 匹配。

Token	is_ORG_start	is_ORG_end	is_PROD_start	is_PROD_end	…
来	0	0	0	0	…
一	0	0	0	0	…
杯	0	0	0	0	…
星	1	0	0	0	…
巴	0	0	0	0	…
克	0	1	0	0	…
的	0	0	0	0	…
美	0	0	1	0	…
式	0	0	0	1	…
咖	0	0	1	0	…
啡	0	0	0	1	…

Token	is_ORG_start	is_ORG_end	is_PROD_start	is_PROD_end	…
来	0	0	0	0	…
一	0	0	0	0	…
杯	0	0	0	0	…
星	1	0	0	0	…
巴	0	0	0	0	…
克	0	1	0	0	…
的	0	0	0	0	…
美	0	0	1	0	…
式	0	0	0	1	…
咖	0	0	1	0	…
啡	0	0	0	1	…

酒中仙

RAG 中的数据准备

RAG 中的数据准备

第一节 数据加载

一、文档加载器

1.1 主要功能

1.2 当前主流RAG文档加载器

第二节 文本分块

一、理解文本分块

二、文本分块重要性

2.1 满足模型上下文限制

2.2 为何“块”不是越大越好

2.2.1 嵌入过程中的信息损失

2.2.2 生成过程的“大海捞针” (Lost in the Middle)

2.2.3 主题稀释导致检索失败

三、基础分块策略

3.1 固定大小分块

3.2 递归字符分块

3.3 语义分块

3.4 基于文档结构的分块

以 Markdown 结构分块为例

四、其他开源框架中的分块策略

4.1 Unstructured：基于文档元素的智能分块

4.2 LlamaIndex：面向节点的解析与转换

4.3 ChunkViz：简易的可视化分块工具

参考文献

生活片段分享平台

生活片段分享平台

前言

Ech0：自托管个人微博客

Memos：私有、轻量、开源、自托管的备忘录

特色介绍

功能

Memos 相关工具

Moments - 极简朋友圈

功能说明

项目部署

参考资料

RAG 简介及其简单实现

RAG 简介及其简单实现

一、什么是 RAG？

1.1 核心定义

1.2 技术原理

1.3 技术演进分类

二、为什么要使用 RAG？

2.1 技术选型：RAG vs. 微调

2.2 关键优势

2.3 适用场景风险分级

三、如何上手 RAG？

3.1 基础工具链选择

3.2 四步构建最小可行系统（MVP）

3.3 新手友好方案

3.4 进阶与挑战

四、RAG 已死？

五、基于 LangChain 框架的 RAG 实现

本节完整代码（改造后）

3.1 初始化设置

3.2 数据准备

3.3 索引构建

3.4 查询与检索

3.5 生成集成

六、低代码（基于LlamaIndex）

参考文献

多模态——从头训练简化版 Omni 模型

多模态——从 0 训练简化版 Omni 模型

一、数据准备与预处理

1.1 获取训练数据

1.2 分词器的构建与训练

1.3 训练语料特征序列化

二、模型训练流水线与核心架构设计

三、模型架构的实现

3.1 前置配置模块

3.2 文本嵌入

3.3 视觉特征压缩与注入

3.4 构建 Transformer 解码块

3.5 组装统一的主干网络

3.6 封装训练循环

图文多模态之原生统一架构

图文多模态之原生统一架构

一、迈向统一的探索

第一节数据加载

第二节文本分块

Token	is_ORG_start	is_ORG_end	is_PROD_start	is_PROD_end	…
来	0	0	0	0	…
一	0	0	0	0	…
杯	0	0	0	0	…
星	1	0	0	0	…
巴	0	0	0	0	…
克	0	1	0	0	…
的	0	0	0	0	…
美	0	0	1	0	…
式	0	0	0	1	…
咖	0	0	1	0	…
啡	0	0	0	1	…