LLM 工程化全流程手册

0.1 这份文档针对什么问题

如果你已经用了两三年 LLM，日常在做训练和推理加速，那么真正缺的通常不是某个单点技术，而是把单点放到整条链路上的位置感。这种缺失会在两种时刻暴露出来：

• 遇到新概念时无法归类：比如看到某个新项目"工作在 logits 这一层"，你要先知道 logits 在整个前向计算里处于哪一步、它的形状和数值特性是什么、谁在消费它，才能判断这个项目到底新在哪。
• 做技术选型时缺少约束意识：知道 KV Cache 能省显存，但不知道它和并发数、上下文长度、batch size 之间是乘法关系，于是容量规划全靠线上试错。

所以这份文档的组织原则是沿流程走，而不是按技术名词罗列。每个环节都回答同样的问题：

0.2 全流程地图：一张图看完

注意这条链是回环而不是直线：线上评测结果会反向决定后训练的数据配比，推理约束（比如必须支持 128K 上下文）会在预训练阶段就改变位置编码与注意力实现的选择。

0.3 三种读法，对应三种真实场景

另外，每一章末尾都有自查清单（第 10 章汇总）。如果你能不看文档答出来，说明这一章可以打勾了；答不出来，说明只是"眼熟"而不是"掌握"。

0.4 四周刷新计划

0.5 版本与更新日志

这一章的目标只有一个：让你能在脑子里把「一段文本」变成「下一个 token 的概率分布」的完整过程走一遍，并且知道每一步的张量形状。后面所有章节（Logits、量化、KV Cache、投机解码、Jev）都是在这条链上做文章——不知道链在哪，就不知道别人改的是哪一环。

1.1 全景：五个阶段

其中 ① 由 tokenizer 在 CPU 上完成，②③④ 是模型的张量计算（GPU），⑤ 是一段很小的确定性/随机性数学运算加控制逻辑。工程上绝大部分优化发生在 ③④ 与"如何重复 ①–⑤ 而不重复计算"。

1.2 Tokenizer：文本到 id

关键认识：tokenizer 是模型的一部分，不是预处理工具。词表一旦确定，模型的输入输出空间就固定了，换 tokenizer 等于换模型，必须从头训练。

1.3 Embedding 与位置编码

token id 通过一个查表矩阵 E ∈ R^{V×d} 变成 d 维向量，得到 [B, S, d] 的初始表示。位置信息不能靠这个查表获得（查表与顺序无关），必须显式注入。

1.4 Transformer block 内部

现代 LLM 基本都是 Pre-Norm 的 decoder-only 结构，一个 block 两步：

# Pre-Norm 残差结构（伪代码，L 层重复）
h = x + Attention(RMSNorm(x))     # 注意力：让 token 之间交换信息
y = h + FFN(RMSNorm(h))           # 前馈：逐 token 做非线性变换（承载大部分参数）
# 全部 L 层结束后：
h_final = RMSNorm(y)              # 最后的 norm 不能省
logits  = h_final @ E_out.T       # E_out ∈ R^{V×d}，即 lm_head

注意力的形状（以 Llama-3-8B 量级为例：d=4096, n_heads=32, n_kv_heads=8, head_dim=128）：

输入     x        : [B, S, 4096]
Q 投影            : [B, S, 32, 128]     # n_heads    × head_dim
K, V 投影         : [B, S,  8, 128]     # n_kv_heads × head_dim  ← GQA
注意力分数        : [B, 32, S, S]       # 因果掩码后上三角为 -inf
注意力输出        : [B, S, 4096]        # concat 所有头后过 W_o

1.5 从 hidden state 到 logits

最后一层输出经过最终 RMSNorm，再乘输出投影矩阵（lm_head），得到整个词表上每个 token 的分数，这就是 logits：

hidden : [B, S, d]
lm_head: [V, d]
logits : [B, S, V]        # 例如 [1, 8192, 128256]

1.6 从 logits 到下一个 token

这一步在工程上被实现成一条固定的流水线，顺序很重要（HuggingFace 系框架的命名可以一一对应）：

logits
  → ① LogitsProcessor 链   重复惩罚 / 频率惩罚 / 存在惩罚 / logit bias /
                           禁止词 / 最小长度 / 约束解码（语法、正则、JSON schema）
  → ② LogitsWarper 链      温度缩放 → top-k → top-p → min-p → typical
  → ③ Sampler             greedy(argmax) / multinomial(按概率采样) / beam search
  → 下一个 token id

1.7 训练目标与 loss

预训练目标就是下一 token 预测：把输入右移一位当标签，对每个位置计算交叉熵。工程上有三个必须知道的细节：

• shift by one。logits[:, :-1] 与 labels[:, 1:] 对齐。差一位的 off-by-one 是自研训练脚本最经典的 bug，表现为 loss 能降但模型很笨。
• loss mask。SFT 时只在"助手该说的话"上计算 loss，用户输入与 padding 位置的标签置为忽略值（通常 −100）。掩码错了，模型会学会模仿用户口吻。
• 与困惑度的关系。PPL = exp(平均交叉熵)。loss=2.0 对应 PPL≈7.4；loss=1.0 对应 PPL≈2.7。PPL 只在同一 tokenizer下可比——换词表后 PPL 数字直接失去意义。

1.8 形状与数字总表

以下以 Llama-3-8B 量级的配置为参照（L=32, d=4096, n_heads=32, n_kv_heads=8, head_dim=128, d_ff=14336, V=128256）：

这一章回答一个具体问题：当有人说"我的工作发生在 logits 这一层"时，他到底站在流水线的哪个位置，改的是什么，为什么这件事有价值。同时把 logits 相关的一堆容易混淆的名词（logprobs、logit bias、约束解码、分类头、logit lens、softmax 校准）摆到同一张图里区分清楚。

2.1 严格定义：logit 为什么叫 logit

p_i = exp(z_i) / Σ_j exp(z_j)

三个必须内化的性质，它们解释了后面 90% 的工程细节：

2.2 形状、内存与"到底要算几个 logit"

logits = hidden_final @ lm_head.T
hidden_final : [B, S, d]
lm_head      : [V, d]
logits       : [B, S, V]     ← 三维张量，V 通常在 32k ~ 256k

关键在于 V 很大而 B×S 也不小，两者相乘会爆掉。于是有了"到底需要哪些位置的 logit"这个问题，而回答它正是很多优化的切入点：

2.3 消费方一：训练时的 logits

训练时 logits 只有一个消费方：交叉熵损失。但围绕它有一串工程细节。

2.4 消费方二：推理时的 logits

推理时 logits 的消费方比训练多得多，而且每一个都对应一个你可能用过的开关：

2.5 消费方三：把 logits 当接口（六种用法）

把"生成一段文本"变成"读一个分布"，是近年来很活跃的一条工程路线。下面六种用法常被混为一谈，请注意区分改的是什么、需不需要训练、有没有重新归一化。

2.6 数值工程：精度、稳定性、稀疏投影

2.7 语义陷阱：什么时候 logprob 不再等于概率

下面这些操作都会让"logprob"失去"模型原始概率"的含义。把它们记成一张清单，比记住任何公式都有用。

2.8 校准：为什么"置信度"不能当"正确率"

现代 LLM 的原始概率通常不是校准的：经过 RLHF/偏好对齐后往往过度自信（RLHF 会系统性推高被选答案的 logprob），而经过蒸馏或强标签平滑的模型可能偏保守。因此：

• 置信度 ≠ 正确率，除非你在自己的留出集上验证过。
• 阈值必须在自己的数据上定。不要用别人博客里的 0.9。
• 温度缩放是成本最低的校准手段：在验证集上拟合一个标量 T（不重训模型），再用于概率输出。它不改变 top-1 排序，只让数值更接近真实正确率。
• 若要做"拒绝/升级"（reject option、模型级联），校准质量直接决定系统收益——这是第 9 章 Jev 类接口最关键的工程前提。

2.9 常见坑与索引

在预训练里，数据配方是比架构更重要的变量。同一个架构、同样的算力，数据质量与配比不同，最终能力可以差出一个代际。这一章按"从原始网页到可训练样本"的处理链路走。

3.1 数据来源与它们的特性

3.2 抽取与清洗

• 正文抽取：从 HTML 里剥掉导航、广告、页脚。工具如 trafilatura、Readability 系算法。抽取质量差会直接引入"模板噪声"，让模型学会输出网页残渣。
• 规则清洗：去 control 字符、统一 Unicode（NFKC）、修 HTML 实体、剔除超短/超长/符号占比异常的行。
• 模板与样板去除：同一模板在大量页面重复出现（如"点击这里订阅"），会污染语言模型分布。按行/按段落跨文档计数是常用的做法。
• PII 与合规：邮箱、电话、身份证等敏感串的识别与脱敏；robots 与许可证合规记录。

3.3 去重：三档强度

3.4 质量过滤：从启发式到分类器

3.5 去污染：这一步没做，后面所有评测都不可信

3.6 Tokenizer 训练：数据阶段的最后一个决定

• 训练语料的采样：词表要用与预训练配比一致的样本训练，否则会偏向某个领域（例如用纯英文训词表，中文就被切得很碎）。
• 压缩率指标：常用"字节/token"或"token/词"衡量。压缩率高 → 同样的上下文窗口装更多信息 → 推理成本更低。这是中文/多语言模型必须重点优化的一项。
• 词表大小与 embedding 成本：V×d 参数（可能双份，如果输出不共享）。
• 稳定性：词表一旦上线，改动成本极高（要重训或做 embedding 对齐手术），所以宁可在早期多试几版。

3.7 三种数据 schema（后面章节都会用到）

# ① 预训练：纯文本流
{"text": "……"}

# ② SFT：对话 + 只在助手回答上算 loss
{"messages": [
  {"role": "user",      "content": "……"},
  {"role": "assistant", "content": "……"}          # ← 只有这里参与 loss
]}

# ③ 偏好数据：同一 prompt 的两个回答 + 人类/模型偏好
{"prompt": "……", "chosen": "……", "rejected": "……"}
# 可验证奖励（RLVR）则不需要 rejected，只要有标准答案/可执行校验：
{"prompt": "……", "answer": "42", "verifier": "math_exact_match"}

预训练是整条链上最贵、最难调试、也最"工程"的一环。它的核心问题只有三个：做多大（Scaling law）、怎么切到几千张卡上跑（并行）、怎么让它别崩（稳定性）。

4.1 规模直觉：算力、参数、数据三者的关系

训练总 FLOPs ≈ 6 × N × D
    N = 参数量（不含 embedding 时可近似）
    D = 训练 token 数
系数 6 = 前向 2（乘加）+ 反向 4

MFU（Model FLOPs Utilization，实际算力/峰值算力）是预训练最重要的效率指标。大模型训练里 MFU 40%+ 已经很好，50%+ 属于调优很到位。它受通信、气泡、重计算、算子实现共同影响——这也解释了为什么并行策略的选择直接等于钱。

4.2 Scaling law：定规模的依据

4.3 架构选择：dense 还是 MoE

4.4 并行策略：切什么、通信多少

这是预训练工程的核心表格。判断一个并行方案是否可行，只要看通信量与可用带宽是否匹配。

节点内（NVLink，带宽最高）→ TP + EP + SP/CP
节点间（IB/RoCE）        → PP（通信量小）
最外层                   → DP / ZeRO（可与计算重叠）

4.5 显存账单：全参训练到底要多少

激活显存与 B × S × L × d 成正比，长序列下会成为主要项。控制手段：梯度检查点（重计算，用算力换显存，通常多花约 30% 时间）、序列并行、分块注意力、以及把中间量以低精度存储。

4.6 混合精度与低精度训练

4.7 训练稳定性：loss spike 的因果与处置

4.8 长上下文扩展

4.9 MoE 训练细节

• 路由：每 token 选 top-k 专家（k 常为 1–8）。细粒度专家 + 共享专家是当前主流设计：把专家切得更小更多，并留若干"永远激活"的共享专家承载通用能力。
• 负载均衡：若无约束，路由会塌缩到少数专家。用辅助损失（aux loss，鼓励各专家被均匀使用）或专家选择路由（expert-choice）来均衡；过强的 aux loss 会损害质量，权重需要调。
• 容量因子与丢 token：每个专家有容量上限，超出部分的 token 会被丢弃（或走残差）。丢弃比例是重要监控指标。
• 通信：all-to-all 是主要瓶颈，需与计算重叠；专家放置要考虑拓扑。

4.10 基础设施与容错

预训练让模型学会语言与世界知识，后训练决定它怎么用这些能力。这一层的技术演化非常快，但骨架是清晰的：SFT 教格式与任务 → 偏好对齐教取舍 → 可验证奖励教推理。

5.1 SFT：最有效、也最容易被做坏的一步

• 数据质量 > 数量。少量高质量、多样化的样本（几千条量级）往往胜过几十万条噪声样本。混合来源时，格式一致性比单条样本的精美程度更重要。
• 轮次与长度：多轮对话要正确构造 mask（只算助手段）；样本长度分布直接决定 padding/packing 效率。
• 超参经验：全参微调 LR 常在 1e-5 ~ 2e-5，LoRA 常在 1e-4 ~ 2e-4；epochs 通常 1–3，再多就出现过拟合与"只会一种腔调"。
• 灾难性遗忘：SFT 太猛会削弱基座能力（多语言、长文、代码）。缓解：混入一定比例的预训练数据（replay）、降低 LR、用 LoRA、控制步数。

5.2 参数高效微调：LoRA 家族

5.3 偏好对齐总览

L_DPO = − log σ( β·[log(π_θ(y_w|x)/π_ref(y_w|x))
                    − log(π_θ(y_l|x)/π_ref(y_l|x))] )
y_w = 被偏好的回答, y_l = 被拒绝的回答, β 控制偏离参考模型的程度

A_i = (r_i − mean(r)) / std(r)
L = − E[ min( ρ_i·A_i , clip(ρ_i, 1−ε, 1+ε)·A_i ) − β·KL(π_θ‖π_ref) ]
ρ_i = π_θ(o_i|x) / π_θ_old(o_i|x)

5.4 蒸馏：把大模型的能力搬到小模型

5.5 模型合并与领域适配

• 模型汤 / SLERP / 任务向量：把多个同源微调模型的权重直接平均或做插值。成本极低（不需要重训），在"多个窄任务各训一个模型"时非常划算。
• TIES / DARE：先修剪小幅度参数、再解决符号冲突，最后合并。比朴素平均更稳，能减少互相干扰。
• 继续预训练（CPT）：注入领域知识（法律、医疗、内部文档）。注意：CPT 容易造成通用能力退化，应混入通用数据并做回归评测。
• 合并的评测纪律：合并出来的模型必须在所有子任务上回归，避免"平均分涨了但某个任务崩了"。

安全不是"最后一层过滤器"，而是横跨数据、训练、推理、产品四层的约束体系。把它当过滤器做，结果通常是：体验被削掉了，真正的攻击仍然能过。

6.1 有用性与无害性的张力

6.2 攻击面

6.3 防御的分层

6.4 幻觉与事实性

• 来源分类：训练数据缺口（不知道）、冲突知识（记混）、解码采样（随机性导致编造）、上下文误用（RAG 召回了错误内容）。不同来源要用完全不同的手段。
• 可行手段：检索增强（把知识外部化）、要求给出处并校验出处、自一致性/多次采样投票、工具化（计算、检索、执行代码）、拒答与不确定性表达。
• 不可靠手段：只靠"请勿幻觉"的提示词；把 logprob 当正确率（见第 2.8 节）。

6.5 可解释性工具箱（与 logits 直接相关的部分）

评测是整条链的反馈信号。信号不可信，前面所有优化都是在盲调。这一章的重点不是列举榜单，而是识别评测什么时候在骗你。

7.1 评测的三个层次

7.2 基准地图与它们的失效模式

7.3 指标与其含义

7.4 LLM-as-judge：好用，但必须防偏

7.5 线上评测

• 离线 → 在线之间必须有门禁：把关键评测做成 CI，指标退化超过阈值就阻止发布。
• A/B 的注意点：分流要按用户而非按请求（避免同一用户体验抖动）；要提前定义主指标与最小可检测效应；看尾延迟与失败率，平均值会掩盖问题。
• 影子流量：新模型只推理不影响用户，用来提前暴露崩溃与格式错误。
• 生产监控：输出长度分布、拒答率、工具调用失败率、解析失败率、用户追问率——这些比离线榜单更早发现退化。

这一章是整条链路里工程收益最直接的一环。核心认识只有一句：prefill 是算力受限，decode 是显存带宽受限。几乎所有推理优化技术，都能被归类为"针对这两者之一做了什么"。

8.1 两阶段模型与 roofline

8.2 该看哪些指标

8.3 KV Cache：容量、分页与复用

KV Cache 字节数 = 2 × L × n_kv_heads × head_dim × S × B × bytes_per_elem
                  ↑K和V  ↑层数              ↑缓存长度 ↑批次

8.4 注意力算子

8.5 量化

8.6 投机解码与约束解码

约束解码（结构化解码）是另一类：按 JSON Schema / 正则 / 语法在每一步把非法 token 的 logit 置 −∞。它保证可解析，不保证内容正确。实现上有编译有限状态机的，也有用推理解码器（如 xgrammar）的；复杂 schema 的每步掩码开销需要评估。第 9 章的"单 token 槽位读取"是它的最简特例：只约束一个位置且候选极少，于是可以连解码循环都省掉。

8.7 批处理与调度

8.8 分布式推理

8.9 框架选型

8.10 服务化与成本模型

这一章回应一个具体的新概念：一个项目声称"工作在 logits 等中间过程上"。我们会把它拆成(1) 它到底指什么、(2) 机制的哪一部分是真的新、(3) 与已有技术的血缘、(4) 哪些数字不能信。本章所有关键论断都标注了证据等级。

9.1 先钉死指称：这里的 "Jev" 指什么

9.2 它解决的问题：把开放式生成变成有界决策

传统做法要"让模型输出一个类别/概率"，标准套路是让它把答案写成文本或 JSON，然后解析。这条路径上有四个成本项：

9.3 机制：受限 softmax，以及它和近邻技术的精确区别

1. 把 state + 问题渲染成 prompt，让答案落在某个固定位置
2. 保证每个候选标签映射到【单个 token】（多 token 候选由编译器变换成单 token 字母等）
3. 取该位置 next-token 分布的 logits
4. 只保留候选标签对应的那些 logit，做 softmax 并【重新归一化】
5. 返回归一化后的概率（+ 置信度/熵诊断），不生成任何 token

9.4 收益：厂商宣称 vs 独立实测

9.5 边界与风险

9.6 血缘关系：它的祖先都是成熟技术

9.7 工程落地建议

9.8 待核实清单（下次刷新时优先查这些）

• 架构、参数量、训练数据与 RLCD 奖励函数是否公开，或是否出现独立复现。
• （已部分解答）机制层面已有第三方复现与实测（见 9.3：标签先验与顺序偏差、11/11 模型提升、vLLM 上 2.2× 决策吞吐）；但托管服务本身仍没有独立的公开基准对比。
• 厂商对比数字的原始测量协议与方差是否公布。
• 跨版本的行为稳定性数据。
• 注入防御是否有实质改进。当前证据是：自适应攻击可把成功率从约 1.8% 推到约 3.5%（见 9.5），需对照第 6.2 节的结构性结论一起看。
• 主流推理框架是否把"单 token 槽位读取"做成通用能力（若成为标准，这类接口会变成默认选项，而非独立产品）。

这一章是可以单独打印的部分：公式、形状、超参经验值、选型决策树，以及全文的自查清单。术语表在配套文件 llm-cheatsheet.html 中。

10.1 核心公式卡

10.2 形状速查（一次前向）

token ids        [B, S]
embedding        [B, S, d]
每层 Q           [B, S, n_heads,    head_dim]
每层 K / V       [B, S, n_kv_heads, head_dim]      # GQA: n_kv_heads < n_heads
注意力分数       [B, n_heads, S, S]                # prefill；decode 时 S→S_total
注意力输出       [B, S, d]
final norm       [B, S, d]
logits           [B, S, V]                         # 解码只需 [:, -1, :]
概率             [B, S, V]                         # softmax 在最后一维，fp32

10.3 超参经验值

10.4 选型决策树

10.5 全文自查清单

逐条用"能不能不看文档答出来"判断。答不出来的章节回去打勾前先重读。

10.6 更新日志

正文各章的「常见坑」讲的是原理上会怎么错；这份附录讲的是线上真的出问题时先查什么。按四张表组织：训练 / 后训练 / 推理服务 / 评测与质量。

A.1 训练阶段

A.2 后训练阶段

A.3 推理与服务

A.4 评测与质量结论