从一颗 Token
到一支智能体团队

大多数人想象中的 AI，是一个坐在屏幕里什么都会的「大脑」。这个想象会让你在所有技术选型上判断失误。 真实的 AI 系统更接近一家公司：有人负责把话听清，有人负责查资料，有人负责动手，有人负责兜底。 你叫它「AI」的时候，其实是在叫整家公司。

下面这 11 位，就是这套教材的全部主角。后面每一章，都是在讲其中某一位具体在干什么活、被谁管、以及他做不了什么。

这一章只讲一件事：AI 产品是一条加法链，不是一个选择题。
你看到的每个产品——知识库问答、客服机器人、编码 Agent、内容生产线——都是同一条链上某个位置的产物。 位置决定了它能干什么，也决定了它会怎么坏。
所以读完这一章，你应该能对任何一个需求说出一句话：「这个要加到第几步，多加的那几步是浪费。」

1.1 十二步配方表：每一步加什么、变成什么

先说结论：底下的模型不变，上面每加一个部件，产品的形态就跳一档。 下面这张表是全章的骨架，后面四节只拆解其中四个转折点。

图上每层正面的 ▸ 那一行，就是这一层的技术重点。下面把它们摊开，并标出每个点在本书哪一章展开—— 看图知道位置，查表知道去哪一章看细节。

1.2 四个转折点：产品形态在这里跳档

转折一：LLM + RAG = 开卷考试

它变成了什么：一个能引用原文的知识问答系统——企业知识库、客服机器人、合同审阅、政策查询，全是这一个配方。

为什么会走到这一步：因为裸模型的知识有三个硬缺陷——有截止时间、不含你的私有资料、说不清依据。 前两个可以靠微调缓解，第三个微调解决不了：参数里没有"出处"这个东西。 而 RAG 把答案的来源摆在明面上，用户能点开看第几页第几段。

它欠下的债：只解决「知道」，不解决「做到」。所以下一步很自然——让它能动手。

转折二：+ 工具 + 循环 = Agent

它变成了什么：一个能自己决定下一步做什么的执行体。编码 Agent、研究 Agent、运维 Agent，都是这个形态。

关键差别只有一处：Function Calling 是「问一次，调一次」；Agent 是「调完看一眼结果，再决定下一次」。 多出来的这个循环，就是「助手」和「执行者」的分界线。

它欠下的债：不可控。同一个任务跑两次，路径可能完全不同，成本差三倍。 于是几乎所有做过 Agent 的团队，最后都会走到下一步。

转折三：Agent → Workflow = 把决策权收回来

怎么选：步骤稳定、出错代价高、要给外人用 → Workflow；输入五花八门、要探索 → Agent。 现实里最常见的是混合：外层 Workflow 管骨架，某个节点内部放一个小 Agent 处理不确定性。

转折四：+ Harness = 从「能跑」到「敢交付」

它变成了什么：一个能给别人用的产品。同样的模型，有无 Harness，体验和可靠性差一个量级。

前面所有的加法，其实都在做同一件事——一层一层往里包。 把这三层拆开看，它们是包裹关系，不是并列关系：

怎么读这张图：LLM 在最里面，只会做一件事——把上下文变成下一个 token 的概率分布。 它不会循环、没有手脚、不记得上一次。Agent 包在它外面，用「想 → 调工具 → 看结果 → 再决定」这个圈， 把一次推理变成一串动作。Harness 再包在 Agent 外面，管住它能不能跑、跑多久、能碰什么、出了事怎么查。

再往后（+MCP 协议、+Skills 插件包）属于「扩大接入面」和「固化质量」， 它们不改变产品形态，只改变你能接多少工具、能复制多少份。这两步的细节在后面的 MCP 章与一人公司章。

1.3 能力阶梯：一句话版本

把上面十二步压成六级，就是这张图。每一级都在回答同一个问题：它还缺什么？

1.4 每加一层的代价

加法链不是免费的。每加一层，你都在这五个维度上做交易——看清楚代价，才知道哪一层现在不该加。

1.5 反向读法：从产品倒推「要加到第几步」

实际做项目时，顺序是反的：先有产品，再倒推需要哪几层。 下表左边是常见产品，右边是「必须有」和「可以没有」——「可以没有」那一列，就是省钱和少踩坑的地方。

1.6 三句话建立坐标系

大部分 AI 教材的问题是：它把知识全给你了，但没告诉你先学哪个、学到什么程度算够、学完能干什么。 结果读完一遍，脑子里是一堆并列的名词；真让你做一个东西，还是不知道从哪下手。 这一章不教技术，它教你怎么用这本书。

2.1 先回答一个问题：你要的是「懂」还是「能做」

这不是修辞。这三件事的知识量差三倍，时间差十倍，而很多人是从中间那个开始、假装自己在做第三个。

2.2 五个阶段：每个阶段只回答一个问题

全书的四十章不是线性排列的知识点，而是六个阶段。每个阶段有一个核心问题——所有内容都是为了回答它。 判断你是否过关，不看「读完了没有」，看那个问题你能不能用自己的话答上来，并且有产物。

2.3 五条岗位路线：五个岗位的知识重叠不到四成

你说要按岗位视角学，那得先承认一件事：Prompt 工程师和 Agent 开发工程师需要的知识，重叠不到 40%。 全读一遍是浪费，跳读也必须知道跳什么。下面五张表就是「跳什么」的许可。

2.4 三个阶段最容易卡住的地方

下面这三处，是我见过的转岗者最常停下的位置。它们的共同点是：看起来是技术问题，实际是方法问题。

2.5 三种读法，以及各自的入口

还有一条不算读法、但更有效的用法：把这本书当检查清单。 你手上如果已经有一个 AI 项目，直接翻各章末尾的「易错点」——全书四十多处，每一条都是别人踩过的坑。 对照自己的项目看一遍，比从头读一遍的收益高得多。

2.6 一条反常识的建议：先做，再懂

很多人卡在「我要先把原理搞懂再动手」，然后卡三个月。

真相是：AI 系统的失败，大多不在原理层，在数据层和工程层。 你花两周搞懂注意力矩阵怎么算，不会让你少踩一个「PDF 双栏解析错位」的坑；也不会让你提前想到「用户问的问题，答案分散在三份文件里」。 这些坑只能在做的时候遇到。

所以建议的节奏是交替，不是串联：每读两章，必须写一次代码或做一次实验。 读的时候带着「这东西能解决我上次遇到的哪个问题」，做的时候带着「它为什么会这样，书上哪一章讲过」。

如果你完全没接触过 AI，这一章是为你写的。它一个问题一个问题往下问，不预设你懂任何术语。
如果你已经用过 ChatGPT 几个月，也建议扫一遍——因为「用过」和「知道它是什么」，中间隔着一层很关键的东西： 你能不能预判它什么时候会出错。

3.1 一个完全外行，最该先问的三个问题

这三问三答，基本就是这一章的全部内容。下面逐条拆开。

3.2 它是什么：一句话，和三种说法

这句话不好懂。要拆开它，得先看清它到底是个什么物件——而且要用三种不同的说法去看， 因为对着不同的人，说法不能一样；说错了对象，会出问题。

同一个东西，在三种场合要说三种话。搞混了会出问题：跟老板用技术定义，他听不懂；跟工程师用功能定义，他会低估复杂度。

3.3 它能干什么：四类任务，可靠性完全不同

所以「AI 能干什么」这个问题问得太粗。更有用的问法是：它做哪一类事比较可靠，做哪一类必须有人复核。

3.4 它不能干什么：五条边界，都是架构决定的

这一节比上一节重要。因为「能干什么」决定你能用它做什么，「不能干什么」决定你会在哪里翻车。 下面五条不是「现在还不够强」，是这个架构天然做不到——指望下一代模型解决，通常等不到。

3.5 它的成长史：六代演进，每一代都留下一个没解决的问题

了解历史不是为了考试，是为了理解为什么现在的设计长这样。 AI 的每一次转向，都是被上一代的天花板逼出来的——而这些天花板，现在仍然以「它的某种怪毛病」的形式留在你面前。

3.6 它和那些「插件」是什么关系：发动机与汽车

这是零基础的人最困惑的一块。市面上有一堆名词——Prompt、RAG、Function Calling、Agent、Workflow、Harness、MCP——它们听起来像并列的几样东西，其实根本不在同一个层级。

一个类比自己就能说清：LLM 是发动机，不是汽车。

3.7 第一周：三个实验，亲手看到它的三副面孔

光读没用。这三个实验加起来不到两小时，但能让你对它的判断从「听说」变成「见过」。

3.8 零基础最容易带上的八个误解

3.9 接下来往哪走

这一章给你的是一张「它是什么」的地图。但地图不等于地形——你还需要知道它内部到底怎么运转， 不然你永远只能靠试错来调它。

接下来四章是由外向内拆：

• 第 4 章：文字怎么变成数字（Token、上下文窗口、Embedding）——这一层决定了成本、容量和「它为什么数不清字数」
• 第 5 章：Transformer 与参数——它凭什么能理解上下文，参数量的「大」到底大在哪
• 第 7 章：Prompt 工程——从这一章开始，你就在动手了
• 第 9 章起：往外装部件（RAG、Agent、Workflow、Harness）

计算机不认识字，只认识数。所以任何 AI 的第一步，都是把人类语言拆成整数序列。 这一步看起来最枯燥，但它决定了很多你后来会踩的坑：为什么模型数不清字数、为什么中文比英文贵、为什么长文档中间的内容会被忽略。

4.1 Token：AI 眼里的「字」不是字

小 Tok 的工作很简单：拿一段文本，按训练时学好的词表切块，每块给一个编号。切法叫 BPE（Byte Pair Encoding）—— 从单个字符开始，反复把「最常一起出现的两段」合并成一个新单位。所以高频词会被合并成一整块，生僻词会被拆成碎片。

4.2 上下文窗口：模型的「工作台」有多大

上下文窗口（context window）是模型一次能同时看到的 token 上限。它不是硬盘，是工作台—— 桌子上摊开的纸越多，你能同时对照的东西越多，但每张纸能分到的注意力会变少。

4.3 Embedding：把「意思」变成坐标

阿嵌不读句子，他给每段文本算一个高维坐标（常见 768 / 1024 / 1536 / 3072 维）。 神奇的地方在于：语义相近的文本，坐标也相近。于是「意思像不像」这个模糊问题，变成了「距离近不近」这个可计算问题。

相似度怎么算？最常用 余弦相似度：把两个向量都归一化后求点积，值域 −1 到 1，越接近 1 越像。 实际工程里更常用 内积（dot product），因为归一化后两者等价，而内积算得更快。

上一步我们只把字变成了数字。要让它「懂」，需要解决一个核心问题：每个词该看哪些别的词。 「苹果发布了新手机，它很贵」——「它」指什么？人一眼就知道，机器必须靠机制算出来。这个机制叫注意力。

5.1 什么是 Transformer：一句话、一个结构、一条数据流

上一章我们把文字变成了向量。但向量之间是互相孤立的——「苹果」的向量不知道旁边有「发布」「新手机」。 要让模型理解一句话，必须解决一个问题：怎么让这些向量互相交流。

整体结构：三层，一条直线

不管多大的模型，骨架都是这三段：输入层 → N 个 Block 堆叠 → 输出层。 「7B」「70B」说的就是这些 Block 里的参数总量，「32 层」「80 层」说的就是 N。

上面那张是压缩版——它只说清「输入进、输出出，中间叠 N 层」。 把它展开，就是 Transformer 论文里那张著名的双栏结构图。这张图值得逐块看一遍，因为后面所有术语都在这里面。

这张图里有三处注意力，它们是初学者最常混的地方：

5.2 一个 Block 里到底有什么：两个子层，两次残差

这是理解 Transformer 的关键。一个 Block 只做两件事，交替进行：

5.3 三种形态：同一套零件，三种装法

Transformer 不是一个固定结构，而是一套零件。按「注意力能不能回头看」和「有没有解码器」，分成三种形态。 这个区分很重要——你调用不同模型时，行为差异的根源就在这里。

5.4 自注意力：Block 里的那场圆桌会议

给每个 token 配三个向量：Query（我在找什么）、Key（我是什么）、Value（我能提供什么）。 用我的 Q 去和所有人的 K 做点积，得到一组相关性分数，softmax 归一化后，对所有 V 加权求和——这就是我这个位置的「新理解」。

一个 Transformer Block = 多头注意力 + 残差连接 + LayerNorm + 前馈网络（FFN）。 把几十到上百个这样的 Block 堆起来，就是「层数」。FFN 承担了大部分参数，也一般认为承载了模型的「知识记忆」。

5.5 单头与多头：为什么要把一组 QKV 拆成 32 组

第 5.4 节讲了自注意力的三个步骤，但有个前提没说：那一节默认你只有一组 Q、K、V。 真实模型不是这样——它是「多头」。这一节把单头和多头的差别说清，以及一个反直觉的事实： 多头几乎不增加成本。

单头的问题：一张表装不下所有关系

先把「单头」说清楚。自注意力的计算是三步：Q 和 K 点积算相关性 → softmax 归一化成权重 → 用权重加权求和 V。 如果只有一组 Q、K、V，那么对每个位置来说，它最终只得到一张权重分布。

问题就出在「一张」上。一句话里同时存在多种关系：

单头必须用同一张权重表同时兼顾这四件事，结果是每种都做得不够专。 这就是多头的出发点：不是让它看得更多，是让它能同时用几种不同的「看的角度」。

多头怎么做：切维度，不是复制模型

很多人以为多头是「跑 32 个 Transformer」，这是错的。多头是把同一个 d_model 切成 h 份，每份独立做一次注意力，再拼回去。

最反直觉的一点：计算量几乎没变

直觉上「32 个头」应该贵 32 倍。实际不是，因为每个头的维度也缩小了 32 倍。

所以多头是一笔「几乎免费的表达力提升」——参数总量没涨，计算量没涨，但模型能同时保留多种关注模式。 这也是为什么它从 2017 年至今没被替换掉。

头到底在学什么：别把它想得太整齐

论文和科普常画「这个头管语法、那个头管指代」，读起来很舒服。但要说实话：没有哪一层是被人工指定分工的， 这些观察是事后分析出来的，而且不同模型、不同层差异很大。

工程变体：MQA 与 GQA，省的是显存不是表达力

标准多头（MHA）在推理时有个麻烦：KV Cache 会随头数线性增长。于是出现了两个变体， 它们不改「多头提升表达力」这件事，只改推理时缓存多少 K 和 V。

5.6 同类架构：Transformer 的对手们，以及它们为什么没赢

这一节回答一个被大多数教材跳过的问题：Transformer 是唯一的选择吗？ 不是。过去三十年，处理序列数据至少有六种主流架构，每一种都在解决「怎么让模型记住前文」这个问题， 只是取舍不同。理解这些取舍，你才能看懂今天为什么是现在这个样子，也才能判断未来的变化。

七种架构横向对比

逐个说清楚：每种架构的取舍

一张表说清「谁在解决什么问题」

5.7 参数：7B、70B 到底指什么

参数就是模型里那些可被训练的数字（权重矩阵里的元素）。7B = 70 亿个浮点数。 它决定了模型「脑子里能装多少东西」，但参数量 ≠ 能力——数据质量、训练策略、后训练对齐，对最终表现的影响往往比参数量更大。

5.8 训练 vs 推理：两个完全不同的过程

温度与采样：为什么同一个问题答案不一样

• Temperature：调低（0～0.3）→ 输出更确定、更收敛，适合抽取、代码、分类；调高（0.8～1.2）→ 更发散，适合创意。
• Top-p（核采样）：只在累计概率达到 p 的候选里采样，砍掉长尾胡话。
• Top-k：只保留概率最高的 k 个候选。
• Greedy / Beam Search：取最高概率或保留多条候选路径，用于翻译、结构化输出等确定性任务。

如果你只记住这一章的一句话，请记住这句：大模型不是「知识库 + 检索」，而是「概率续写器」。 它的每一个字都是「最可能接下去的那个字」。理解了这一点，幻觉、上下文遗忘、不能算数、不会用工具，全都变得可解释。

6.1 下一 Token 预测：一个被低估的机制

训练目标只有一个：给定前文，最大化下一个 token 的似然。看起来简单到不像能产生智能，但要在整个互联网上把这个任务做好， 模型被迫学会了语法、事实关联、逻辑推理、代码结构、翻译对齐——因为这些都是「预测下一个词」的必要条件。

6.2 涌现能力与 Scaling Law

6.3 知识截止与「不知道」的缺失

模型的全部世界知识来自训练语料，语料有截止日期。截止之后发生的事，它一律不知道——但它不会告诉你「我不知道」， 因为它没有被训练成「先判断可知性再回答」，而是「接着往下写」。

很多人对 Prompt 工程师的理解停在「会写咒语」。真实情况正相反：这个岗位的核心不是措辞，是实验设计。
一个人能不能胜任，看他被问「你怎么证明改完更好」时的反应——答不出评测方法的，都还停在「玩」的阶段。

7.1 这个岗位到底在解决什么问题

7.2 能力模型：六个维度，缺一个就会卡在某个环节

7.3 一条工业级提示词的六段结构

网上流传的提示词多是「一段话」。能用，但不可维护。真实项目里的提示词是分块的，每一块承担不同职责， 出问题时你能定位到是哪一块的问题——就像派活时你能说清「是目标没说清，还是格式没说清」。

把六段拼起来，一份可用的模板长这样。注意两处细节：标签用尖括号把材料包起来（避免材料里的文字被当成指令）， 以及约束写的是「替代动作」而不是「禁止」。

# 角色
你是一名企业合同审阅助手，只做风险标注，不做法律意见。

# 任务
阅读 <doc> 中的合同文本，找出对我方不利的条款，按风险等级排序。

# 材料
<doc id="1">
（这里粘贴合同全文或检索到的段落）
</doc>

# 约束
1. 只依据 <doc> 中的内容判断，不得引入外部知识。
2. 每条结论必须附「原文引用」，引用不超过 30 字。
3. 若 <doc> 中找不到相关条款，输出「未在合同中找到相关约定」。
4. 不做金额计算，如涉及比例，原文照抄。

# 示例
输入：甲方有权单方面调整服务价格。
输出：{"risk":"高","clause":"甲方有权单方面调整服务价格",
       "reason":"价格调整权单方归属，我方无异议机制","suggest":"增加提前30日书面通知"}

# 输出格式
严格输出 JSON 数组，每个元素包含 risk / clause / reason / suggest 四个字段。
risk 只能是 "高" / "中" / "低"。不要输出任何解释性文字。

7.4 基础五式：每一式都要知道什么时候失效

这五种是所有人都该会的。但网上只讲「怎么用」，不讲「什么时候没用」——后者才是你排查问题时需要的。

7.5 进阶六式：把一次性问答变成可拆解的流程

7.6 结构化输出：让下游能接住

提示词写得再好，如果输出是一段自然语言，它就只是个「玩具」。能进系统，必须机器可解析。

现在主流模型都支持结构化输出（JSON Schema 约束），这是最可靠的方式。但即使不用它，你也该按下面三层来做：

7.7 幻觉：不是 bug，是机制的必然产物

Hallucination（幻觉）指模型生成了流畅、自信、但事实错误或无依据的内容。它有三种完全不同的成因，对应三种完全不同的解法—— 用错解法是常见浪费。

7.8 怎么证明一版比上一版好：提示词评测

这是整个岗位最关键的一节。没有评测，你的每一次修改都是赌博——而且你会在「这次感觉好多了」的错觉里循环， 直到上线才发现某类输入全崩了。

具体怎么建评测集，三条规则：

7.9 版本管理：出问题时，你得知道是哪一次改动

提示词是代码，不是配置。它该有版本号、变更记录、和对应的评测结果。

最小可行的做法，一个表格就够了：

v5 这一行很值得看：换模型只带来 1 个点，成本翻倍。这就是为什么 6.8 的评测必须先做—— 没有这张表，你会在「感觉不够好」时本能地换更贵的模型，然后既没解决问题，又抬高了成本。

7.10 完整案例：把「帮我写周报」从 v1 改到 v5

这个案例小到可以今天做完，但包含了上面全部要素。

帮我根据下面的工作记录写一份周报。
（粘贴一堆流水账）

根据工作记录写周报，严格按以下结构：
1. 本周完成（3–5 条，每条不超过 40 字，格式：事项 + 结果）
2. 进行中（含当前进度百分比）
3. 风险与需要支持（没有就写「无」）
总长度不超过 400 字。

（在 v2 基础上追加）
约束：
- 只使用记录中出现的事实，不得补充、推断或美化。
- 每条必须能对应到原文的某一句，若记录过于简略，
  照原样写，不要扩写。
- 若某条记录不足以判断结果，写「进展：待确认」。

（在 v3 基础上加示例）
示例：
记录：周三跟产品对了下订单模块的改法，还差接口没定
输出：订单模块改造方案已对齐，接口定义待确认（进度 60%）

注意：示例展示的是「如何在不夸大的前提下写清楚」，
不是让你照抄这个句式。

7.11 十种失效模式：拿着这张表去排查

7.12 七天练习：从会写到会证明

模型不够用的时候，绝大多数人的第一反应是「微调一下」。但微调只解决一类问题—— 让模型改变「行为方式」，而不是「补充知识」或「获得实时信息」。选错路径，钱和时间都会白花。

8.1 微调家族

8.2 量化：用精度换显存

8.3 推理模型：把算力花在「想」上

2024 年之后出现了一类新范式：模型在给出答案前，先产生一长串内部推理（可能几千 token）， 通过「想更久」来提升正确率。这类模型被称为推理模型（reasoning model），核心思想叫 test-time compute（测试时计算）。

8.4 三条路径怎么选：一张决策表

RAG 是全篇最容易理解、也最容易做砸的技术。它的想法一句话说得完：回答之前先去查，把查到的原文一起递给模型。 但真正决定效果的，不是「查不查」，而是「怎么切、怎么找、怎么排、怎么塞」这四件事。

9.1 先讲清关系：RAG 和大模型到底是什么关系

绝大多数教材直接把 RAG 讲成「检索 + 生成」，但它和模型的关系没讲透，导致后面所有设计决策都缺少依据。 我的理解是：RAG 不是模型的插件，是模型的「外部知识供给线」。

一个绕不开的概念区分：参数化知识 vs 非参数化知识

这是理解 RAG 价值的关键。模型的知识有两种存在形式，各有利弊：

一个更直观的比喻：开卷考试

RAG 不能做什么：三条边界必须说清

9.2 两条链路：离线索引 vs 在线查询

初学者最常犯的错，是把 RAG 想成「一个函数」。它其实是两条独立的流水线： 一条在后台把文档加工成可检索的形态（离线，可以慢），一条在用户提问时实时跑（在线，必须快）。两条链路共用同一个向量库。

9.3 环节一：文档解析——最脏、最容易被跳过的一步

如果你的 RAG 效果不好，先别怀疑模型，先去看解析出来的文本长什么样。 我见过太多项目：检索算法调了两周，最后发现问题出在 PDF 解析把双栏读成了串行。

判断方法很简单：随便抽 5 份文档，把解析后的纯文本打印出来读一遍。 如果你自己都读不通（句子错位、表格变乱码、页眉页脚混进正文），模型更读不通。

PDF 有三种，处理方式完全不同

一条完整的解析链路

9.4 环节二：切块——RAG 效果的第一决定因素

Chunking（切块）是把长文档切成小片段的过程。切得好，每块都是语义完整的「一页知识」；切得差，一句话被拦腰截断，检索出来也没法用。

9.5 环节三：向量化与索引——把块变成可检索的形态

切完块，每一块要变成向量并存进数据库。这一步技术上最简单，但有几个「不报错却毁效果」的细节。

元数据设计：决定后面能不能「过滤」

向量库存的不能只有向量和原文。元数据决定了你能做多精细的检索——没有它，你只能全库搜，无法做「只查这个部门」「只要今年的」这类限定。

9.6 环节四：查询改写——提升效果最快，做的人最少

这一步的性价比高得离谱：不动模型、不重建索引，只加一个改写环节，召回率常能提升 10～20 个点。 但大多数教程跳过了它。

原因很简单：用户的问题和文档的写法不匹配。用户问「报销多久到账」，文档写的是「费用核销流程的时限规定」。 向量模型再强，也难把这两种表达直接对上。

# 多查询 + HyDE 的组合（伪代码）
def rewrite(query, history):
    # ① 指代消解：把多轮里的省略补全
    standalone = llm(f"把这个问题改写成不依赖上下文、可独立理解的完整问题：\n"
                     f"对话历史：{history}\n当前问题：{query}")

    # ② 多查询：生成 3 个不同角度的表述
    variants = llm(f"从不同角度改写这个问题，输出 3 条，每行一条：\n{standalone}").split("\n")

    # ③ HyDE：生成一段「假设的答案」，用于检索（可选，对短查询特别有效）
    hypothetical = llm(f"用文档的语气写一段可能回答这个问题的文字（200 字以内）：\n{standalone}")

    return [standalone] + variants + [hypothetical]

9.7 环节五：检索——从百万条里捞出那几条

检索这一步要做四件事：算相似度、取 top-k、去重、融合多路结果。每一件都有讲究。

① 相似度与 top-k：粗筛要「多取」

粗筛阶段的目标不是「准确」，是不遗漏。所以 top-k 要取得大一些——常见 k=20～50， 然后交给重排去精挑。如果 k 只取 5，重排就没有发挥空间，而且一旦粗筛漏了，后面全错。

② 去重：MMR 算法，解决「五条结果说的是同一件事」

纯按相似度排序，很容易返回 5 条几乎重复的片段——因为它们都和问题「很像」，但信息量重复。 这时模型看到的是五种说法讲同一件事，而不是五个不同方面。

③ 融合：多路结果怎么合并

向量检索和关键词检索的分数不可比（一个是余弦相似度，一个是 BM25 分值，量纲完全不同）。 所以不能用加权求和，要用只看排名的融合方法——RRF（倒数排名融合），在第 10 章讲过，这里给具体算式：

# RRF：只看排名，不看分数
def rrf(vector_results, bm25_results, k=60):
    score = {}
    for rank, doc in enumerate(vector_results, start=1):
        score[doc.id] = score.get(doc.id, 0) + 1 / (k + rank)
    for rank, doc in enumerate(bm25_results, start=1):
        score[doc.id] = score.get(doc.id, 0) + 1 / (k + rank)
    return sorted(score.items(), key=lambda x: -x[1])

9.8 环节六：重排——把「像」变成「对」

粗筛给你 30 条候选，重排要挑出真正能回答问题的 5 条。 它用的是交叉编码器（Cross-Encoder）：把问题和候选拼在一起送进模型，逐词比对，输出一个相关性分数。

重排的价值在于它能识别一种向量检索识别不了的情况：「这段提到了关键词，但没有回答问题」。 比如问「退款多久到账」，一段讲「退款流程需要提交申请」的文档，向量相似度很高，但没回答问题——重排模型能把它压下去。

9.9 环节七：上下文拼装——最后 10% 的胜负

检索对了，拼装错了，一样白搭。这一步决定了模型「怎么理解这些材料」。

[系统]
你是一名严谨的知识库助手。规则：
1. 只依据下方【材料】回答，不得使用材料之外的知识；
2. 每句结论后标注来源编号，如 [1][2]；
3. 材料中没有的信息，回答「材料未提及」，不要推测；
4. 若多份材料矛盾，指出矛盾并分别标注来源。

【材料】
[1] 来源：《华东区经销合同 v3》第 6 章（2026-03-15）
    原文……

[2] 来源：《退款管理办法》第 2 条（2026-01-08）
    原文……

【问题】
退款一般多久到账？

[输出格式]
- 结论：一句话
- 依据：[编号] 原文摘录
- 备注：材料未覆盖的部分

9.10 环节八：生成与引用——让答案可核对

检索对了，最后一步仍可能翻车。模型看到材料，也可能「自由发挥」。所以提示模板必须给三条硬约束：

9.11 RAG 的四种形态：从「能跑」到「会自己想办法」

前面八个环节是「标准 RAG」的全部。但工程上其实有四种成熟度不同的形态，能力、成本、延迟差很多。 搞清楚自己在做哪一种，能避免「用 Naive 的方案期待 Agentic 的效果」。

9.12 一个完整的例子：500 份文档，从提问到回答

抽象讲完，看一条真实的数据流。假设你是某公司的客服知识库，有 500 份制度文件、产品手册、FAQ。

成本感受：按 2 元/百万 token 算，这一次问答约 0.0074 元。 如果换成「把 500 份文档全塞进长上下文」，一次是 约 12 元——差 1600 倍。 这就是 RAG 在经济上的根本意义。

9.13 评测与调优：先测哪一层，后改哪一层

RAG 调优最常见的浪费，是「一上来就换模型」。正确顺序是先定位问题在哪一层，再动那一层。

9.14 十四种失败模式：一张排查表

9.15 如果这是你的岗位：RAG 应用工程师的一天

先说清这个岗位和其他岗位的分界，因为它是被误解最多的一个。

换句话说：RAG 应用工程师是那个「对最终准确率负责，但没有权力改模型」的人。 所有能提效果的手段，都在数据和流程里——这正是这份工作的难点，也是它的价值所在。

六项能力，每一项的达标标准是可验的

一条铁律：调优顺序不能反

这是这一节最想让你记住的一句话： 解析 → 切块 → 检索 → 重排 → 提示 → 换模型。越靠前越便宜、收益越大。

最后是分级。它比任何能力清单都更能回答「我现在值多少钱」。

上一节讲了 RAG 的流程，这一节拆开其中最关键的一环：「找得到」这件事是怎么在毫秒级完成的。 如果你只需要结论：向量检索负责「意思像」，关键词检索负责「字面准」，两者混合再重排，是目前最稳的组合。

10.1 为什么需要 ANN，而不是精确搜索

假设你有 100 万条文档块，每条 1024 维。要找出和查询最像的 10 条，最笨的办法是逐条算相似度——100 万次点积，单次约 1024 次乘加， 合计约 10 亿次运算，延迟到秒级，无法接受。所以工业界用 ANN（近似最近邻）：牺牲一点点召回率，换取几个数量级的加速。

10.2 混合检索：向量找不准的地方，关键词能救

纯向量检索有个天然短板：它对专有名词、型号、错误码、人名极度不敏感。 比如查「ERR_CONN_5021 这个报错怎么解决」，向量模型会把它理解成「网络连接错误」这个语义， 然后把一堆讲 404、超时、DNS 的文档都排到前面——真正讲 5021 的那篇反而因为语义「不够典型」被排后。

10.3 重排：把「像」变成「对」

10.4 当问题需要「串起来」：多跳与 GraphRAG

传统 RAG 只能回答「答案在某一两段里」的问题。但真实业务里大量问题是多跳的： 「负责华东区的销售总监，他上一份工作是哪家公司？」——需要先找到人，再查这个人的履历，两次检索。

RAG 让模型「知道得更多」，Agent 让模型「能做更多」。这是性质上的变化： RAG 的错误是说错话，Agent 的错误是做错事。所以从这一节开始，工程重点从「效果」转向「效果 + 可控」。

11.1 ReAct 循环：Agent 的心跳

ReAct = Reasoning + Acting，是目前几乎所有 Agent 的基础范式。它把「思考」和「行动」交替进行， 关键在于：每次行动的结果会回到上下文里，成为下一轮思考的依据。这就是 Agent 与「一次性问答」的本质区别。

11.2 Function Calling：模型怎么「动手」

这是一个必须讲清楚的机制细节：模型本身不能调用任何函数。它只能输出一段特定格式的文本，说「我想调用 weather 工具，参数是 city=南京」。 真正执行的是你的程序。程序执行完，把结果作为一条消息塞回对话，模型再继续。

// 第 1 步：你告诉模型「有哪些工具可用」
tools = [{
  name: "get_weather",
  description: "查询指定城市当前天气",
  parameters: { city: "string, 城市名" }
}]

// 第 2 步：模型返回的不是答案，而是一个「调用意图」
{ "tool_calls": [{ "name": "get_weather", "arguments": { "city": "南京" } }] }

// 第 3 步：你的代码真的去调气象 API
result = requests.get("https://api.weather.com/...", params={...})

// 第 4 步：把结果作为 role=tool 的消息塞回去
{ "role": "tool", "content": "{\"temp\": 21, \"weather\": \"多云\"}" }

// 第 5 步：模型基于这个结果，生成最终回答

协议层：三个角色，三段 JSON

所谓「内部运转」，本质是三段结构化数据的往返。看懂这三段，你就知道每一步该由谁负责。

// ① 请求：告诉模型「有哪些工具」
{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "当用户询问某城市当前天气时使用；缺少城市名时先追问，不要调用",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名，如「南京」" }
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"        // auto / required / 指定某个函数 / none
}

// ② 模型返回：不是答案，是「调用意图」
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,                        // 注意：这里是 null，不是文字
      "tool_calls": [{
        "id": "call_abc123",                  // 唯一标识，回传时必须带上
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"南京\"}"   // 字符串！需要 JSON.parse
        }
      }]
    },
    "finish_reason": "tool_calls"             // 见到这个值就说明该你去执行了
  }]
}

// ③ 回传：把执行结果塞回去
{
  "role": "tool",
  "tool_call_id": "call_abc123",              // 与上面的 id 对应
  "content": "{\"temp\": 21, \"weather\": \"多云\"}"   // 也只能是字符串
}

七步内部流程：一次调用到底发生了什么

并行调用：一次返回多个意图

模型可以在一次响应里返回多个 tool_calls。比如「查北京和南京的天气」，它会同时给出两个调用。 你的代码可以并发执行，再把两个结果一起回传——这样只花一轮，而不是两轮。

# 并行执行多个 tool_calls
results = await asyncio.gather(*[
    execute(tc["function"]["name"], json.loads(tc["function"]["arguments"]))
    for tc in message["tool_calls"]
])

# 每个结果都必须单独回传，且带上对应的 id
for tc, res in zip(message["tool_calls"], results):
    messages.append({
        "role": "tool",
        "tool_call_id": tc["id"],      # 关键：不能漏
        "content": json.dumps(res, ensure_ascii=False)
    })

流式场景：最容易踩的坑

开了 stream=true 之后，tool_calls 不是一次性到齐的，而是分片到达：

chunk 1: {"tool_calls":[{"index":0,"id":"call_abc","function":{"name":"get_weather","arguments":""}}]}
chunk 2: {"tool_calls":[{"index":0,"function":{"arguments":"{\"ci"}}]}
chunk 3: {"tool_calls":[{"index":0,"function":{"arguments":"ty\":\"南"}}]}
chunk 4: {"tool_calls":[{"index":0,"function":{"arguments":"京\"}"}}]}

# 必须按 index 累积拼接，拼完才是完整参数
buffers[index]["arguments"] += delta

如果直接把每个 chunk 的 arguments 拿去 parse，必然报错。这是接入流式 FC 时最常见的 bug， 而且因为只在流式下复现，很容易被漏掉。

错误处理：三层，三种策略

Function Calling 与 MCP：不是替代，是两层

这两个概念经常被混在一起问。一句话说清：Function Calling 是「模型怎么表达我想调工具」，MCP 是「工具怎么被接进来」。 前者是模型能力，后者是接入协议，它们在不同层，配合使用。

实际协作方式：你的应用通过 MCP 连上若干个 Server，把它们的工具能力转换成 Function Calling 的 schema 发给模型； 模型输出 tool_calls；你的代码把调用转发给对应的 MCP Server；结果再转回 role: "tool" 塞回去。
所以 MCP 是「工具的供应链」，Function Calling 是「点菜的方式」。点菜方式不变，供应链换了，菜品更多了。

11.3 记忆：Agent 为什么会「忘了刚才做过什么」

最容易忽略的是：上下文不是无限黑板。Agent 跑 20 轮之后，前面几轮的工具返回可能已被挤出窗口， 于是它开始重复劳动、或者忘记最初的约束。所以成熟的 Agent 必须做上下文压缩：把历史摘要成要点、把无用的工具返回丢弃、把关键状态写进结构化变量。

11.4 规划范式：从「走一步看一步」到「先想清楚再做」

11.5 路由：Agent 的调度中枢

前面讲的都是「一个 Agent 怎么干活」。但真实系统里，第一件事往往不是干活，而是决定谁来干、用什么干。 这个动作叫路由（Routing）。它不显眼，却决定了整个系统的成本与稳定性。

六种路由，各管一段

实现的四种手段：从「快而脆」到「慢而活」

代码：一个可运行的三级路由

ROUTES = {
    "refund":  {"kw": ["退款", "退货", "退钱"], "handler": refund_flow},
    "order":   {"kw": ["订单", "物流", "发货"], "handler": order_flow},
    "invoice": {"kw": ["发票", "开票"], "handler": invoice_flow},
}

def route(query):
    # 一级：关键词规则（快，覆盖主路径）
    for name, cfg in ROUTES.items():
        if any(k in query for k in cfg["kw"]):
            return name, 0.95

    # 二级：向量匹配（处理换说法的变体）
    sim, name = vector_match(query, ROUTES)      # 每个意图的描述向量化后比对
    if sim > 0.82:
        return name, sim

    # 三级：LLM 判断（只处理模糊请求，且给出「无法归类」选项）
    label = llm_classify(query, labels=list(ROUTES) + ["unknown"])
    return label, 0.6 if label != "unknown" else 0.3

# 关键：路由结果要带置信度，低置信度走兜底，不要硬分派

注意最后一行：路由必须输出置信度。置信度低于阈值时，正确做法不是「猜一个继续」，而是 澄清追问（「您是想查订单，还是申请退款？」）或走通用路径。硬分派是路由系统最危险的设计。

什么时候不该做路由

四个失败模式

11.6 如果这是你的岗位：Agent 开发工程师的第一周

动手之前，先定三个参数

这三个数字如果没定，后面所有代码都会返工。它们不是技术选型，是产品决策，所以要和业务方一起定。

七天，每天一个能验收的产物

注意第 4 天和第 5 天的顺序：先让它犯错（只打日志不真执行），再加闸门。 反过来做的人，永远不知道自己的闸门该拦什么——因为他从没见过它犯错的样子。

三个最常见的死法

单个 Agent 遇到瓶颈时，直觉是「多找几个人」。这个直觉在部分场景成立，但大多数情况下是负收益—— 因为多智能体引入的成本不是线性的，而是沟通成本随成员数平方增长。

12.1 四种常见拓扑

前面所有内容都建立在「文本」上。但真实世界里，大部分信息不是文字：合同是扫描件、故障是截图、需求是会议录音、操作要在界面上点。 多模态不是「加个图片上传按钮」，而是让模型能处理同一件事的不同表达形式。

13.1 什么是多模态：先看单模态长什么样

「多模态」这个词被用滥了。要讲清楚它，得先看它的反面——单模态模型。 因为没有对比，你无法判断一个模型到底「多」在哪。

四种单模态模型：各管一段，互不相通

看出问题了吗？在单模态时代，要处理一张带表格的发票，你得串起一条流水线： OCR 模型（图→文字）→ 版面分析模型（判断哪块是表格）→ 文本模型（理解内容）→ 可能还要 规则引擎（校验金额）。 每一环都会丢信息，每一环都是一个故障点。

三种技术路线：融合发生在哪一步

13.2 一张图是怎么变成 token 的

13.3 多模态在 Agent 工作流中怎么用：六种接法

很多人以为「给 Agent 加多模态」就是「让它能传图」。不是。 多模态在 Agent 里真正的价值是多了一个感知通道和一个校验通道—— 前者让它能看到界面、文档、现场；后者让它能「看见自己干得对不对」。

接法一：作为感知输入（最基础，也最常用）

把截图、扫描件、照片直接送进模型，让它输出结构化结果。这一层替代了传统的「OCR + 版面分析 + 规则引擎」流水线。

接法二：作为校验通道（最容易被忽略，价值最高）

这是多模态 Agent 与纯文本 Agent 的本质区别：它能「回头看一眼」。 比如改完一个网页布局，再截一张图，自己判断「按钮有没有被遮住」——纯文本 Agent 只能看代码，判断不了渲染结果。

# 视觉自校验循环（伪代码）
for attempt in range(3):
    action = model.decide(goal, current_screenshot)   # ① 看图决策
    execute(action)                                    # ② 执行操作
    time.sleep(0.5)                                    # ③ 等渲染
    new_shot = screenshot()                            # ④ 重新截图
    verdict = model.judge(
        before=current_screenshot,
        after=new_shot,
        expectation="弹窗应已关闭，且列表显示 3 条结果"
    )
    if verdict.ok:
        return "done"
    # ⑤ 不 OK 就把「差异」作为下一轮的输入，而不是盲目重试
    current_screenshot = new_shot

return escalate_to_human("三次尝试后仍未达成预期")

这段代码里最关键的一行是 judge(expectation=...)： 校验必须有明确的「预期」，否则模型只会说「看起来还行」。 预期要可观察——「弹窗已关闭」「列表有 3 条」「按钮变蓝」，而不是「界面更好看了」。

接法三：多模态 RAG（图文混合检索）

传统 RAG 只能检索文本。但企业知识库里大量内容是图：产品结构图、流程图、设计稿、扫描件。 多模态 RAG 要解决「用文字问题找到图」和「用图找相似图」两件事。

接法四：GUI 操作闭环（下一节详讲）

看屏 → 决策 → 点击 → 再看屏。这是多模态最「科幻」也最脆弱的用法，因为它把模型放进了真实界面， 任何布局变化、加载延迟、弹窗都会打乱节奏。详见 11.4。

接法五：内容生成管线

在第 23 章的内容创作产线里，多模态承担了从「分镜」到「成片」的全部视觉环节： 分镜文本 → 关键帧图 → 图生视频 → 配音 → 剪辑。 这里的工程难点不是「能不能生成」，是「多张图之间的一致性」——同一角色在第 3 个镜头换脸，观众立刻出戏。 解法在 21.4 讲过：文本锚点 + 参考图 + 固定 seed + 角色 LoRA。

接法六：质检与审核（生成之后的把关）

生成完不等于能用。多模态模型可以做最后一道自动质检，而且比人快得多：

• 合规检查：图里有没有水印、敏感标识、不该出现的品牌 logo。
• 一致性检查：同一角色在不同镜头的服装、发型、配饰是否一致。
• 质量检查：手指数量、文字是否乱码、透视是否错误、有没有明显的 AI 痕迹。
• 对版检查：生成的图是否符合分镜描述（「雨夜、霓虹、近景」）。

一个完整例子：商品图审核 Agent

13.4 GUI Agent：在别人的界面上干活

Computer Use / GUI Agent 是近两年最实用也最脆弱的形态：模型看屏幕截图，输出「点击坐标 (x, y)」或「在输入框打字」， 由程序执行，再截下一张图判断结果。

这是全篇最容易被低估的一节。很多人以为 Workflow 是「Agent 的低配版」，恰恰相反—— 在生产环境里，Workflow 的可靠性远高于 Agent，因为它把「下一步做什么」从模型手里拿走了。

14.1 一张典型的审批工作流

14.2 Workflow 与 Agent 的边界

这是整篇教材里最被低估、也最能区分「做过 demo」和「上过生产」的一节。 同一句「用 Claude Code 改这个文件」，在 demo 里和在真实仓库里，差别不在模型，而在 Harness。

15.1 五个必须做的工程约束

在协议出现之前，每接一个系统都要写一套适配器：接 Jira 写一套、接数据库写一套、接内部 API 再写一套。 M 个模型 × N 个工具 = M×N 份工作。协议做的事，是把它变成 M+N。

这是全篇最偏「前沿」的一节，但它解决的是一个非常具体的老问题：模型一旦在推理中途走错一步，后面会一路错到底，而且不会回头。 DoT 的思路是：让推理不再是一条直线，而是一张可以分叉、可以合并、可以退回去的图。

17.1 先看 CoT 的三个硬伤

CoT（Chain of Thought，思维链）让模型把步骤写出来，确实显著提升了多步推理的正确率。但它有一个结构性缺陷：它是线性的、单向的。

17.2 四代推理结构的演进

前面十五节讲的是「怎么做得出来」。这一节讲「怎么证明它做得对」。 我的判断很直接：没有评测集的 AI 项目，本质上是在靠感觉交付。它的每一次改动都是赌博，因为没人知道这次改动是变好还是变坏。

18.1 评测集：项目最该先建的资产

18.2 Bad case 治理：从一条差评到一次回归

16.1 讲的评测集是预防，这一节讲的是治疗。两者是一套闭环的两端： 评测集告诉你及格线在哪，bad case 告诉你离及格差在哪。

没有治理流程的团队，通常长这样：用户反馈不好用 → 团队凭印象改提示词 → 改完感觉好点了 → 下周又冒出同类问题。 问题不是不努力，是没有把「一条差评」变成「一条可复现的测试用例」。

# 每条修好的 case，必须走完这四步才算修完
1. 把这条 case 加进评测集（带标准答案）
2. 跑全量评测，确认「修好的」和「没弄坏的」
3. 整体分数不降，才允许上线
4. 上线后一周，回查这条 case 有没有复发

# 关键：第 3 步的「不降」是硬门槛，不是参考
# 只修单条不看全量，是最常见的隐性退化来源

18.3 安全：三种必须防的攻击面

下面这张图是本教材的收束。它按七层能力栈排列，每一层向下依赖、向上支撑。 看这张图只需要抓三件事：谁在谁下面、谁替代不了谁、谁离了谁就跑不起来。