Update 大模型应用.md

调整高频标记;KV Cache、LoRA、量化、上下文压缩、PDF 解析、检索与重排、Agent 的记忆、Skills、评测、成本与推理服务等小节的补充与校对,附录同步更新。
This commit is contained in:
CyC2018
2026-11-07 17:10:27 +08:00
parent 71f7078105
commit 69ffd2677f
+127 -107
View File
@@ -33,8 +33,8 @@
* [多模态 RAG](#多模态-rag)
* [Text2SQL](#text2sql)
* [四、Agent](#四agent)
* [Agent 是什么](#agent-是什么) 🔥🔥
* [工具调用](#工具调用)
* [Agent 是什么](#agent-是什么)
* [工具调用](#工具调用) 🔥
* [Agent 循环](#agent-循环)
* [Agent 与工作流](#agent-与工作流)
* [意图识别与路由](#意图识别与路由)
@@ -42,7 +42,7 @@
* [记忆](#记忆) 🔥
* [多轮对话](#多轮对话)
* [MCP](#mcp) 🔥
* [Skills](#skills) 🔥
* [Skills](#skills) 🔥🔥
* [多 Agent](#多-agent)
* [AI 编程助手](#ai-编程助手) 🔥🔥
* [Harness](#harness)
@@ -205,13 +205,13 @@ softmax 把任意分数变成非负、和为 1 的权重,处处可导,指数
生成文本时,一个 Token 只能看到它自己和前面的 Token,这称为因果掩码(Causal Mask)。实现方法是把“后面的 Token”对应的分数设为负无穷,softmax 之后权重为 0,即图中分数矩阵的右上角。训练时整段文本一起输入,不遮住后文的话,预测下一个 Token 时就能直接看到答案。
注意力本身不区分 Token 的先后顺序:把“小猫很饿”打乱成“饿很小猫”,“饿”的 Q 与各个 K 的分数不变,得到的加权和也不变,所以需要额外加入位置信息,称为位置编码。最初的 Transformer 把用正余弦函数生成的位置向量加在词嵌入上,编码的是绝对位置。
注意力本身不区分 Token 的先后顺序:不加因果掩码时,把“小猫很饿”打乱成“饿很小猫”,“饿”的 Q 与各个 K 的分数不变,得到的加权和也不变,所以需要额外加入位置信息,称为位置编码。最初的 Transformer 把用正余弦函数生成的位置向量加在词嵌入上,编码的是绝对位置。
目前常用旋转位置编码(Rotary Position Embedding, RoPE):把每个头的 Q、K 向量两两分组,每组看作一个二维向量,位置为 m 的 Token 把第 i 组旋转 mθ<sub>i</sub>(θ<sub>i</sub> = base<sup>−2i/d</sup>,前面的组转得快)。位置 m 的 Q 和位置 n 的 K 旋转后,夹角变化了 (m − n)θ<sub>i</sub>,所以点积只取决于内容和相对距离。例如只有一组、每个位置转 30°,Q 和 K 旋转前都是 (1, 0):
<div align="center"> <img src="pics/llm-rope-2d.png" width="720px"/> </div><br>
前两种情况的距离都是 1,分数相同;距离为 3 时夹角为 90°,点积为 0。按 Qwen2.5-7B 的 128 维向量计算也是如此(见[进阶:附录 A4](大模型应用%20-%20进阶.md#a4-rope-的相对位置与频率))。RoPE 只旋转 Q 和 K,没有需要训练的参数。不旋转 V,是因为位置只需要影响“和谁相关”;V 是被加权汇总的内容,旋转它会把各 Token 的绝对位置带进输出。超过训练长度时怎样扩展上下文,见[进阶:旋转位置编码与长度外推](大模型应用%20-%20进阶.md#3-旋转位置编码与长度外推)。
前两种情况的距离都是 1,分数相同;距离为 3 时夹角为 90°,点积为 0。按 Qwen2.5-7B 的 128 维向量计算,相对距离相同时分数也相同(见[进阶:附录 A4](大模型应用%20-%20进阶.md#a4-rope-的相对位置与频率))。RoPE 只旋转 Q 和 K,没有需要训练的参数。不旋转 V,是因为位置只需要影响“和谁相关”;V 是被加权汇总的内容,旋转它会把各 Token 的绝对位置带进输出。超过训练长度时怎样扩展上下文,见[进阶:旋转位置编码与长度外推](大模型应用%20-%20进阶.md#3-旋转位置编码与长度外推)。
#### 1. 多头注意力
@@ -233,7 +233,7 @@ Q = x W_Q (n, 3584)
#### 2. 计算量与 FlashAttention
序列长度为 n、向量维度为 d 时,QK<sup>T</sup> 和乘以 V 各需要约 n<sup>2</sup>d 次乘加,时间复杂度为 O(n<sup>2</sup>d),分数矩阵占用 O(n<sup>2</sup>) 的显存。上下文较短时,计算量主要在线性层,上下文越长,注意力所占的比例越大,按 Qwen2.5-7B 的配置计算,两者在约 3.2 万个 Token 时相当。
序列长度为 n、向量维度为 d 时,QK<sup>T</sup> 和乘以 V 各需要约 n<sup>2</sup>d 次乘加,时间复杂度为 O(n<sup>2</sup>d),分数矩阵占用 O(n<sup>2</sup>) 的显存。上下文较短时,计算量主要在线性层,上下文越长,注意力所占的比例越大,按 Qwen2.5-7B 的配置计算,生成第 3.2 万个 Token 时两者相当。
降低这部分开销有两类做法。一类让每个 Token 只看一部分 Token,或者改写 softmax,结果与标准注意力不同:例如 Mistral 7B 的滑动窗口注意力中,每层的每个 Token 只看前 4096 个 Token;线性注意力用核函数代替 softmax,利用矩阵乘法的结合律把复杂度降为 O(n)。另一类结果不变,只减少显存的读写,即 FlashAttention。
@@ -258,14 +258,15 @@ KV Cache 是用显存换计算。每个 Token 要在每一层缓存 K 和 V 两
2 × 层数 × KV 头数 × 每个头的维度 × 每个数值的字节数
```
以 Qwen2.5-7B 为例,28 层、4 个 KV 头、每个头 128 维,使用 BF16(2 字节),每个 Token 占用 2 × 28 × 4 × 128 × 2 = 56 KB,一个 32K Token 的请求占用 1.75 GB。模型权重本身约 14 GB,几个长上下文请求的 KV Cache 就能和权重一样大,所以 KV Cache 的大小直接决定了一张显卡能同时服务多少个请求。
以 Qwen2.5-7B 为例,28 层、4 个 KV 头、每个头 128 维,使用 BF16(2 字节),每个 Token 占用 2 × 28 × 4 × 128 × 2 = 56 KB,一个 32K Token 的请求占用 1.75 GB。模型权重本身约 14 GB(本节的 KB、GB 按 2<sup>10</sup>、2<sup>30</sup> 字节计算,按 10<sup>9</sup> 字节约为 15 GB),几个长上下文请求的 KV Cache 就能和权重一样大,所以 KV Cache 的大小直接决定了一张显卡能同时服务多少个请求,估算方法见[显存:权重与 KV Cache](#3-显存权重与-kv-cache)。
减少 KV Cache 的方法:
- 分组查询注意力(Grouped-Query Attention, GQA):多个查询头共享一组 K、V。Qwen2.5-7B 有 28 个查询头、4 组 K、V,如果每个查询头都有自己的 K、V,每个 Token 要占用 392 KB。极端情况是所有查询头共享一组 K、V,称为多查询注意力(Multi-Query Attention, MQA),缓存最小,但效果下降更明显;
- 多头潜在注意力(Multi-head Latent Attention, MLA):DeepSeek-V2 提出。GQA 减少的是 K、V 的组数,MLA 则把 K、V 联合压缩成一个低维的潜在向量,只缓存这个向量,计算时再用矩阵还原出各个头的 K、V。DeepSeek-V3 每个 Token 只缓存 68.6 KB,与 Qwen2.5-7B 的 56 KB 相近,细节见[进阶:多头潜在注意力](大模型应用%20-%20进阶.md#2-多头潜在注意力);
- 多头潜在注意力(Multi-head Latent Attention, MLA):DeepSeek-V2 提出。GQA 减少的是 K、V 的组数,MLA 则把 K、V 联合压缩成一个低维的潜在向量,只缓存这个向量和一个携带位置信息的小向量,计算时再用矩阵还原出各个头的 K、V。DeepSeek-V3 每个 Token 只缓存 68.6 KB,与 Qwen2.5-7B 的 56 KB 相近,细节见[进阶:多头潜在注意力](大模型应用%20-%20进阶.md#2-多头潜在注意力);
- PagedAttention:推理框架 vLLM 把 KV Cache 切成固定大小的块按需分配,不再按最大长度预留连续的显存,相同前缀的请求还可以共享块,见[推理服务部署](#4-pagedattention);
- 量化:用 8 位甚至更少的位数存储 K、V。
- 滑动窗口注意力:每个 Token 只看前 W 个 Token 时,只需保留最近 W 个 Token 的 K、V,新的 K、V 覆盖最早的一个,缓存不再随长度增长。Mistral 7B 的 W 为 4096,32K Token 的序列缓存减为八分之一,见[计算量与 FlashAttention](#2-计算量与-flashattention);
- 量化:用 8 位甚至更少的位数存储 K、V,见 [KV Cache 量化](#4-kv-cache-量化)。
<div align="center"> <img src="pics/gqa.png" width="740px"/> </div><br>
@@ -444,7 +445,7 @@ SFT 的样本是一段完整的对话,通常每行一条 JSON:
全参数微调要更新所有参数。混合精度训练时,每个参数要保存 BF16 的参数和梯度、FP32 的参数副本和 Adam 优化器的两个状态,共 16 字节,Qwen2.5-7B 只算这部分就需要 7.6B × 16 ≈ 122 GB 显存,还不包括激活。
低秩适配(Low-Rank Adaptation, LoRA)冻结原有的参数矩阵 W,只训练两个小矩阵 B 和 A,用它们的乘积 BA 表示参数的变化量。它基于这样的观察:微调时参数的变化量通常是低秩的,用很少的参数就能表示。
低秩适配(Low-Rank Adaptation, LoRA)冻结原有的参数矩阵 W,只训练两个小矩阵 B 和 A,用它们的乘积 BA 表示参数的变化量。它基于这样的假设:微调时参数的变化量的“内在秩”很低,用很少的参数就能近似。
<div align="center"> <img src="pics/lora.png" width="640px"/> </div><br>
@@ -463,7 +464,7 @@ SFT 的样本是一段完整的对话,通常每行一条 JSON:
| 全部 7 个线性层 | 16 | 4037 万 | 0.53% |
| 全部 7 个线性层 | 64 | 1.61 亿 | 2.12% |
以 q_proj 为例,3584 × 3584 的矩阵有 1284 万个参数,r = 8 时只增加 8 × (3584 + 3584) = 57,344 个。
以 q_proj 为例,3584 × 3584 的矩阵有约 1285 万个参数,r = 8 时只增加 8 × (3584 + 3584) = 57,344 个。
r 不需要很大,是因为微调主要是调整模型已有的能力:LoRA 论文在 GPT-3 175B 的 q、v 上,r = 1 与 r = 64 的准确率只差 0.1 个百分点。r 要多大取决于训练数据中有多少信息要学:几千条格式、风格类的样本,可以从 r = 8、16 开始(PEFT 的默认值为 8),再用验证集比较;数据量很大时,r 太小会使训练损失跟不上全参数微调;在只按最终答案给奖励的数学题强化学习实验中,r = 1 也能接近全参数微调的效果。
@@ -547,15 +548,15 @@ FP8 有两种编码:E4M3(4 位指数、3 位尾数)最大 448,E5M2(5
- 每行(每个输出通道)一个系数:好一些,但这一行的最大值正好是这个离群值,同一行的其它权重仍然全部变成 0;
- 每组一个系数:离群值只影响它所在的组,另一组的权重得以保留。实际常用 128 个一组,每组多存一个 FP16 的缩放系数,平均每个权重多 0.125 位,7B 模型约多 0.12 GB。
把 Qwen2.5-7B 28 层中的全部线性层按不同的方式量化,在一段约 6600 个 Token 的中文技术文本上测量困惑度(越低越好)。困惑度(Perplexity)是模型给文本中每个 Token 的概率取负对数、求平均后再取指数,可以理解为模型平均在多少个候选之间犹豫;分词方式不同的模型之间不能直接比较:
把 Qwen2.5-7B 28 层中的全部线性层按不同的方式量化,在一段约 6700 个 Token 的中文技术文本上测量困惑度(越低越好)。困惑度(Perplexity)是模型给文本中每个 Token 的概率取负对数、求平均后再取指数,可以理解为模型平均在多少个候选之间犹豫;分词方式不同的模型之间不能直接比较:
<div align="center"> <img src="pics/quant-ppl.png" width="700px"/> </div><br>
INT8 按通道量化几乎没有损失;INT4 必须按组量化,困惑度从 6.23 升到 6.50,按通道量化则升到 11.97,整个矩阵一个系数时模型只能输出乱码(见[附录 A18](#a18-权重量化的误差与困惑度))。INT4 按组量化时也常用非对称量化:用每组的最小值和最大值确定范围,多存一个零点,0~15 的 16 个整数都能用上。
INT8 按通道量化几乎没有损失;INT4 直接取整时要按组量化,困惑度从 6.23 升到 6.50,按通道量化则升到 11.97,整个矩阵一个系数时模型只能输出乱码(见[附录 A18](#a18-权重量化的误差与困惑度))。上面按组量化的结果用的是非对称量化:用每组的最小值和最大值确定范围,多存一个零点,0~15 的 16 个整数都能用上。
#### 2. 只量化权重与连同激活一起量化
只量化权重时(例如 W4A16,权重 4 位、激活 16 位),权重以 INT4 存储,计算前还原为 FP16,再与 FP16 的激活相乘。它节省显存和带宽,适合一次生成一个 Token、受带宽限制的解码阶段,是本地部署和小批量服务最常用的方式,GPTQ、AWQ 都属于这一类。
只量化权重时(例如 W4A16,权重 4 位、激活 16 位),权重以 INT4 存储,计算前还原为 FP16,再与 FP16 的激活相乘。它节省显存和带宽,适合一次生成一个 Token、受带宽限制的解码阶段,是本地部署和小批量服务最常用的方式,GPTQ、AWQ 都属于这一类。微调时量化冻结权重的做法见 [QLoRA 与全参数微调](#4-qlora-与全参数微调)。
连同激活一起量化时(例如 W8A8),矩阵乘法直接在 INT8 上完成,能利用显卡的整数计算单元,适合计算量大的预填充和大批量推理。
@@ -595,7 +596,7 @@ KV Cache 也可以量化。Qwen2.5-7B 每个 Token 的 KV Cache 在 BF16 下占
其它原因:
- 知识缺失:训练数据有截止时间,也可能包含错误,出现次数很少的事实更容易记错。用微调灌输新知识还会加重这个问题,见上文的微调;
- 知识缺失:训练数据有截止时间,也可能包含错误,出现次数很少的事实更容易记错。用微调灌输新知识还会加重这个问题,见[什么时候微调](#1-什么时候微调);
- 解码:采样带有随机性,一旦生成了错误的 Token,后面的内容会顺着它继续生成;
- 上下文:上下文过长或者检索到的资料有噪声时,模型可能用错资料。
@@ -632,9 +633,9 @@ Agent 的幻觉除了回答错误,还会出现在工具调用的过程中。
| 工具结果 | 系统提示词 | 回答中给出了送达时间 |
| --- | --- | --- |
| 只有 location、updated_at | 只写查询流程 | 10 / 10,例如“预计 24 小时内送达” |
| 同上 | 加上“没有某项信息时如实告知,不要猜测” | 9 / 10,其中 8 次把 updated_at 当成了送达时间 |
| 改为 location_updated_at,并给出 `"eta": null` 和说明 | 以上两种 | 0 / 10,回答“承运商暂未提供预计送达时间” |
| 只有 location、updated_at | 只写查询流程 | 10 / 10,例如“预计将在24小时内送达” |
| 同上 | 加上“没有某项信息时如实告知,不要猜测” | 9 / 10,都把 updated_at 当成了送达时间 |
| 改为 location_updated_at,并给出 `"eta": null` 和说明 | 以上两种 | 0 / 10,例如回答“承运商暂未提供预计送达时间” |
只在提示词中要求“不要编造”作用有限,模型会把含义不清的字段当成它需要的信息;把工具结果写清楚之后,这组实验中就不再出现编造。所以更可靠的做法是在工具和代码上约束:
@@ -686,7 +687,7 @@ Agent 的幻觉除了回答错误,还会出现在工具调用的过程中。
- 给出几组输入和期望的输出,称为少样本(Few-shot)提示,示例比文字描述更能说明格式。示例的选择和顺序会影响结果,例如分类任务中模型会偏向示例里占多数的类别和排在最后的类别,所以分类示例先保持类别均衡,再在评测集上比较不同的示例组合、顺序和数量,并不是越多越好;
- 让模型先写出推理步骤再给出答案,称为思维链(Chain of Thought, CoT),可以提高多步推理问题的准确率。
提示词改得好不好,要在评测集上比较:准备一批带期望结果的输入,每条运行多次,能用代码判断的用代码检查,其余交给人或模型裁判,见[评测](#2-评测)。例如[工具调用](#工具调用)一节的实验中,系统提示词写明先查订单、再查物流之后,7B 模型 10 次运行中答出包裹位置的次数从 0 变为 10。修改时从失败的样例入手,补上对应的规则或示例;APE 等自动优化方法由模型生成多个候选提示词,在评测集上打分后保留得分最高的。
提示词改得好不好,要在评测集上比较:准备一批带期望结果的输入,每条运行多次,能用代码判断的用代码检查,其余交给人或模型裁判,见[评测](#2-评测)。例如[工具调用](#工具调用)一节的实验中,系统提示词写明先查订单、再查物流之后,7B 模型 10 次运行中答出包裹位置的次数从 0 变为 10。修改时从失败的样例入手,补上对应的规则或示例。规则加了仍不遵守时,可以把任务拆成几次调用(见[Agent 与工作流](#agent-与工作流)),格式交给[结构化输出](#结构化输出),事实和业务规则用代码校验(见[Agent 中的幻觉](#4-agent-中的幻觉));APE 等自动优化方法由模型生成多个候选提示词,在评测集上打分后保留得分最高的。
提示词和代码一样需要版本管理。提示词、模型版本、工具定义和采样参数共同决定了输出,最好作为一个整体编号发布,线上记录每次请求用的是哪个版本,新版本先灰度给一小部分用户,与旧版本对比线上指标,出问题时整体回滚;比较时把模型固定到具体的版本,一次只改一处,否则分不清变化来自提示词还是模型。
@@ -702,9 +703,9 @@ Agent 的幻觉除了回答错误,还会出现在工具调用的过程中。
<div align="center"> <img src="pics/constrained-decoding.png" width="660px"/> </div><br>
例如 Schema 规定 temp 是整数,已经生成了 `{"city": "杭州", "temp": ` 时,只有数字和负号是合法的,“晴”这类 Token 都会被屏蔽。vLLM 等推理框架和很多模型接口都支持这种方式,代价是 Schema 只能使用推理服务支持的子集。各家的子集不同,遇到不支持的关键字时,有的报错,有的直接忽略,例如 Gemini 不强制 minLength、maxLength,所以长度、数量这类约束仍要在本地校验。
例如 Schema 规定 temp 是整数,已经生成了 `{"city": "杭州", "temp": ` 时,只有数字、负号和空白是合法的,“晴”这类 Token 都会被屏蔽。vLLM 等推理框架和很多模型接口都支持这种方式,代价是 Schema 只能使用推理服务支持的子集。各家的子集不同,遇到不支持的关键字时,有的报错,有的直接忽略,例如 Gemini 不强制 minLength、maxLength,所以长度、数量这类约束仍要在本地校验。
需要注意的是,只保证输出是 JSON 的“JSON 模式”与约束解码不同。例如 DeepSeek 的 JSON Output(response_format 为 json_object)只保证输出合法的 JSON,有哪些字段仍要靠提示词中的样例约束;输出达到 max_tokens 时同样会被截断。
需要注意的是,只保证输出是 JSON 的“JSON 模式”与约束解码不同。例如 DeepSeek 的 JSON Output(response_format 为 json_object)只约束输出是 JSON,有哪些字段仍要靠提示词中的样例约束;输出达到 max_tokens 时同样会被截断,返回的 content 也可能只有空格,代码中要兜底。
字段的顺序也有影响:约束解码按 Schema 中的顺序逐个生成字段,需要推理的任务应把 reason 这类解释字段放在结论字段前面,否则模型要先给出结论,再为它找理由。Claude 的结构化输出会把必填字段排在可选字段之前,要固定顺序时把这几个字段都设为必填。
@@ -787,11 +788,11 @@ Agent 的幻觉除了回答错误,还会出现在工具调用的过程中。
只有闲聊这类前后轮关系不大的对话,用滑动窗口就够了。客服对话中,用户在第 6 轮说的“取件前发短信,别打电话”到第 30 轮仍然有效;Agent 执行长任务时,早期做出的决定和用户提出的约束一直有用,这些场景适合摘要加外置。实际系统常把几种方法组合起来:上下文由“系统提示词 + 摘要 + 最近几轮的原文 + 当前问题”组成,更早的消息不断并入摘要,并且先清理工具结果,不够时再做摘要;需要读大量资料、反复试错的子任务交给[子 Agent](#多-agent),在它自己的上下文中完成,只把结论带回来。
Codex 在本地压缩时把历史换成一段写给“接手的模型”的交接摘要(进展、关键决定、约束和下一步),同时从最新往前保留用户的原话,最多约 2 万个 Token,模型的回复和工具结果只保留在摘要里(Codex 源码,以最新版本为准)。
Codex 在本地压缩时把历史换成一段写给“接手的模型”的交接摘要(进展、关键决定、约束和下一步),同时从最新往前保留用户的原话,最多约 2 万个 Token,模型的回复和工具结果只保留在摘要里(Codex rust-v0.166.0 源码,以最新版本为准)。
压缩的时机按 Token 数判断,而不是按轮数。上面的对话中,每轮新增的 Token 从 33 到 611 不等,查了物流的一轮是简单问答的十几倍。上一次请求的准确 Token 数可以从接口返回的 usage 中得到,再用分词器或者按字数估算新增的消息,超过阈值就压缩。常见的做法是设两道线:历史达到预算的约 70% 时在后台生成摘要,不影响当前的回答;达到上限时必须先压缩才能继续调用。MemGPT 就采用这种方式,在 70% 时提醒模型把重要的信息保存到外部,在 100% 时移出一部分消息,并把它们和原有的摘要合并成新的摘要;Claude Code 的做法见 [AI 编程助手](#ai-编程助手)。
压缩的时机按 Token 数判断,而不是按轮数。上面的对话中,每轮新增的 Token 从 33 到 611 不等,查了物流的一轮是简单问答的十几倍。上一次请求的准确 Token 数可以从接口返回的 usage 中得到,再用分词器或者按字数估算新增的消息,超过阈值就压缩。可以设两道线:较低的一道提前处理,例如历史达到预算的约 70% 时在后台生成摘要,不影响当前的回答;达到上限时必须先压缩才能继续调用。MemGPT 也用两道线,在 70% 时提醒模型把重要的信息保存到外部,在 100% 时移出一部分消息,并把它们和原有的摘要合并成新的摘要;Claude Code 的做法见 [AI 编程助手](#ai-编程助手)。
70% 只是一种取法,各产品的默认值相差很大,例如 Codex 没有配置阈值时在窗口的 90% 压缩,Claude Code 接近窗口上限时才压缩,Claude API 的服务端压缩默认在 15 万输入 Token 时触发(以官方最新文档为准)。
70% 只是一种取法,各产品的默认值相差很大,例如 Codex 没有配置阈值时在窗口的 90% 压缩,Claude Code 接近窗口上限时才压缩,Claude API 的服务端压缩默认在 15 万输入 Token 时触发(Codex rust-v0.166.0、2026 年 11 月的 Claude 官方文档,以最新版本为准)。
保留的“最近几轮”也要按 Token 计,而不是按条数。最近几条本身就超出预算时,通常是某条工具结果或用户粘贴的文档太大:先把这条外置,上下文中只留与当前任务相关的片段和读取位置,需要时再分段读取或检索;仍然放不下就减少保留的轮数,只保证系统提示词、任务状态和当前问题完整。
@@ -809,9 +810,9 @@ Codex 在本地压缩时把历史换成一段写给“接手的模型”的交
- 让承诺通过工具留下记录:例如“取件前短信联系”应该调用备注工具写进订单,而不是只在回答中说一句;
- 摘要分项输出,要求编号、金额、时间照原文抄写;“已办理”只写有工具结果确认的操作,只是说过要做、还在等用户确认的放进“待办”,否则“准备退款”可能被压缩成“已退款”;
- 生成新摘要时在旧摘要的基础上合并,而不是只总结新移出的消息,否则早期的内容会在多次压缩后消失;
- 用框架的默认配置时,检查摘要模型实际看到了哪些消息。例如 LangChain 的摘要中间件默认把待摘要的部分裁剪到约 4000 个 Token(近似计数),保留末尾的消息和开头的系统消息,被裁掉的早期消息不参与摘要,其中往往有用户最初的要求。
- 用框架的默认配置时,检查摘要模型实际看到了哪些消息。例如 LangChain 1.4 的摘要中间件默认把待摘要的部分裁剪到约 4000 个 Token(近似计数),保留末尾的消息和开头的系统消息,被裁掉的早期消息不参与摘要,其中往往有用户最初的要求。
压缩有没有丢掉关键信息,可以用两种方法检查,上面的实验就是这样做的:
压缩有没有丢掉关键信息,可以用两种方法检查,上面的实验用了这两种方法,但只比较了两种摘要,没有测压缩前的正确率:
- 关键事实覆盖:由代码从原始对话中找出订单号、单号、金额、电话等,检查它们是否出现在压缩后的上下文中,缺少的直接补回;
- 探针问题:准备一组依赖早期对话才能回答的问题,例如“用户一开始要求的输出格式是什么”,分别用压缩前和压缩后的上下文回答,比较正确率。
@@ -852,9 +853,9 @@ RAG 能减少幻觉,是因为模型从凭记忆回答变成了根据给定的
#### 1. PDF 为什么难解析
Word、HTML、Markdown 文件本身记录了标题样式、表格和列表,按结构读取即可。PDF 则不同,它只记录“在某个坐标画某个字”,没有段落、表格的概念;扫描件更进一步,每页只是一张图片,连文字都没有,必须先用光学字符识别(Optical Character Recognition, OCR)识别出文字和位置。
Word、HTML、Markdown 文件本身记录了标题样式、表格和列表,按结构读取即可。PDF 则不同,它的页面内容只记录“在某个坐标画某个字”,没有段落、表格的概念;带标签的 PDF(Tagged PDF)会另存一份标题、段落和表格的结构,但标签是可选的,不能假定每个文件都有;扫描件更进一步,每页只是一张图片,连文字都没有,必须先用光学字符识别(Optical Character Recognition, OCR)识别出文字和位置。
用一页员工手册对比两种读取方式。页面上有页眉页脚、两级标题、一段正文和一个住宿标准表格:
用一页员工手册对比两种读取方式。页面上有页眉页脚、两级标题、两段正文和一个住宿标准表格:
<div align="center"> <img src="pics/rag-doc-parse.png" width="800px"/> </div><br>
@@ -866,7 +867,7 @@ Word、HTML、Markdown 文件本身记录了标题样式、表格和列表,按
与只输出文字和坐标的传统 OCR 相比,这类工具多了版面检测、表格结构识别和公式识别,输出的是带标题层级和表格的文档。也可以让多模态大模型直接把页面截图转为 Markdown,但长文档受上下文和输出长度限制,要逐页或分批调用,成本高、速度慢;模型还可能漏掉或改写数字,只输出 Markdown 时也丢失了坐标,难以定位回原文。因此它通常只用于专用工具处理不好的页面,效果要在自己的文档上评估。
用几条简单的规则就能看出原理:把 OCR 结果中 y 坐标相差不超过 12 像素的文字归为一行,同一行有多个文字块的就是表格行;顶部和底部 10% 的区域是页眉页脚,从中取出页码后丢弃;按“第 N 章”“N.N”的格式识别标题。对上面的扫描件,这几条规则的输出如下:
用几条简单的规则就能看出原理:把 OCR 结果中 y 坐标相差不超过 12 像素的文字归为一行,同一行有多个文字块的就是表格行;顶部和底部 10% 的区域是页眉页脚,从中取出页码后丢弃;按“第 N 章”“N.N”的格式识别标题;不以句号结尾的行与下一行合并。对上面的扫描件,这几条规则的输出如下:
```markdown
## 第 6 章 出差
@@ -933,7 +934,7 @@ Word、HTML、Markdown 文件本身记录了标题样式、表格和列表,按
#### 3. 对比实验
用一个小实验比较不同的切法。知识库是一份员工手册的 2026 版和 2023 版(除标题和施行日期外,两个版本只有 6 处数字不同)以及一份错误码说明,共约 5000 字;40 个问题都是员工的口语化提问,例如“老婆生孩子,我能休几天假?”。每个问题标注了回答所需的原句,检索出的前 K 个切片完整包含这些原句就算找到,找到的问题所占的比例记为 Recall@K(见[附录 A12](#a12-切片方式top-k-与相似度阈值)):
用一个小实验比较不同的切法。知识库是一份员工手册的 2026 版和 2023 版(除标题和施行说明外,两个版本只有 6 处数字不同)以及一份错误码说明,共约 5000 字;40 个问题都是员工的口语化提问,例如“老婆生孩子,我能休几天假?”。每个问题标注了回答所需的原句,检索出的前 K 个切片完整包含这些原句就算找到,找到的问题所占的比例记为 Recall@K(见[附录 A12](#a12-切片方式top-k-与相似度阈值)):
| 切法 | 切片数 | Recall@1 | Recall@3 | 前 3 个切片的字数 |
| --- | --- | --- | --- | --- |
@@ -950,7 +951,7 @@ Word、HTML、Markdown 文件本身记录了标题样式、表格和列表,按
按小节切的效果最好,放进提示词的字数也最少,因为固定长度的切片会把一句话切成两半,或者把两节的内容拼在一起。重叠对固定长度的切片帮助明显,200 字的 Recall@3 从 0.83 提高到 0.93,代价是切片数多了约四分之一。递归切分优先在段落和句子边界切开,不加重叠也有 0.95。语义切分的阈值不好定,改按 95 分位数切时,最长的切片有 841 字,超过了 512 Token,而 LangChain 的 SemanticChunker 默认用的就是 95 分位数。
800 字的切片召回率也高,但主要是因为放进去的字多:前 3 个切片共约 2000 字,相当于知识库的四成,而且每个切片超过 512 Token 的部分没有参与向量计算。父子切片在这里没有优势,因为每个小节本身只有一两百字,小节很长、问题只对应其中一两句时它才有用。
800 字的切片召回率也高,但主要是因为放进去的字多:前 3 个切片共约 2000 字,相当于知识库的四成,而且每个切片超过 512 Token 的部分没有参与向量计算。父子切片在这里没有优势,因为每个小节本身平均只有约 90 字,小节很长、问题只对应其中一两句时它才有用。
需要注意的是,40 个问题中一个问题就是 0.025,这组数字只说明趋势。另外,两个版本的同一节几乎一样,38 个问题的前 3 个结果里同时出现了新旧两个版本,加标题路径也区分不开(Recall@1、Recall@3 与不加时相同,见[附录 A12](#a12-切片方式top-k-与相似度阈值)),需要按版本过滤,见下文的向量数据库。
@@ -978,7 +979,7 @@ b = “休假的流程是什么” (0.6, 0.8) cos(a, b) = 0.48 + 0.48 = 0.9
c = “今天股价上涨了” (0.6, -0.8) cos(a, c) = 0.48 - 0.48 = 0
```
a 和 b 几乎没有相同的字,相似度却很高,这是向量检索相比关键词检索的优势。向量通常会归一化为长度 1,这时余弦相似度等于点积,计算更快。归一化之后,欧氏距离与余弦相似度也是等价的:|a − b|<sup>2</sup> = 2 − 2cos(a, b),按距离从小到大排序与按相似度从大到小排序的结果相同。没有归一化时三者的排序可能不同,点积还会受到向量长度的影响,应该使用模型训练时所用的度量。
a 和 b 几乎没有相同的字,相似度却很高,这是向量检索相比关键词检索的优势,它不擅长的精确匹配见[混合检索](#混合检索)。向量通常会归一化为长度 1,这时余弦相似度等于点积,计算更快。归一化之后,欧氏距离与余弦相似度也是等价的:|a − b|<sup>2</sup> = 2 − 2cos(a, b),按距离从小到大排序与按相似度从大到小排序的结果相同。没有归一化时三者的排序可能不同,点积还会受到向量长度的影响,应该使用模型训练时所用的度量。
用真实的模型计算,结论相同但数值没有这么极端:用 bge-small-zh-v1.5(512 维)编码这三句话,“怎么申请年假”与“休假的流程是什么”的余弦相似度为 0.603,与“今天股价上涨了”为 0.194(见[附录 A1](#a1-embedding-相似度与-bm25))。实际系统中不同句子的相似度大多落在一个不太宽的区间里,判断是否相关要看排名和阈值,而不是期望不相关的结果接近 0。
@@ -991,7 +992,7 @@ a 和 b 几乎没有相同的字,相似度却很高,这是向量检索相比
出差住宿标准是多少 0.380 0.339 0.627
```
训练时把每一行看成一个三选一的分类问题:相似度除以温度 τ 后做 softmax,损失是正确文档(对角线)的交叉熵,训练使对角线的值高于同一行的其它值。τ 用于放大差距,τ = 1 时第一行选中文档 1 的概率只有 0.43,τ = 0.05 时为 0.998(见[附录 A27](#a27-embedding-的池化与批内负样本))。
训练时把每一行看成一个三选一的分类问题:相似度除以温度 τ 后做 softmax,损失是正确文档(对角线)的交叉熵,训练使对角线的值高于同一行的其它值。τ 用于放大差距,τ = 1 时第一行选中文档 1 的概率只有 0.42,τ = 0.05 时为 0.998(见[附录 A27](#a27-embedding-的池化与批内负样本))。
负样本越多、越难区分,学到的向量越精细。所以 bge 训练时一个批次多达 19,200 对,后期还为每对数据挖掘一个难负样本(Hard Negative),即与问题字面相近但并不相关的文档,例如为 E1024 的问题配上 E1025 的说明。
@@ -1001,7 +1002,7 @@ a 和 b 几乎没有相同的字,相似度却很高,这是向量检索相比
检索时把问题也转为向量,找出与它最相似的 K 个切片,称为 Top-K 检索。问题和切片必须使用同一个 Embedding 模型,更换模型后所有切片都要重新计算向量。K 怎么取见下文的 Top-K 与阈值。
知识库变大后,相似度高却不能回答问题的内容可能增多,把正确切片挤出前 K 个,即使逐个精确比较也是如此。在切片实验的 52 个切片中混入 12.5 万条无关的短问题,Recall@3 从 0.975 降到 0.575:“年假可以只请半天吗?”与干扰文本“是否可以请长假?”的相似度为 0.798,正确切片只有 0.659(见[附录 A29](#a29-hnsw-的距离计算次数与知识库规模))。这是向量本身的排序问题,调向量数据库的索引参数只能使结果更接近精确检索,解决不了;要靠元数据过滤缩小范围,或者召回更多候选交给[重排](#重排),这里 K 增大到 50 时召回率回到 0.90。
知识库变大后,相似度高却不能回答问题的内容可能增多,把正确切片挤出前 K 个,即使逐个精确比较也是如此。在切片实验的 52 个切片中混入 12.5 万条无关的短问题,Recall@3 从 0.975 降到 0.575:“年假可以只请半天吗?”与干扰文本“是否可以请长假?”的相似度为 0.798,正确切片只有 0.659,从第 1 名降到第 3 名,前 3 个结果中的另外两条都是干扰文本(见[附录 A29](#a29-hnsw-的距离计算次数与知识库规模))。这是向量本身的排序问题,调向量数据库的索引参数只能使结果更接近精确检索,解决不了;要靠元数据过滤缩小范围,或者召回更多候选交给[重排](#重排),这里 K 增大到 50 时召回率回到 0.90。
#### 3. 选择模型
@@ -1009,13 +1010,13 @@ a 和 b 几乎没有相同的字,相似度却很高,这是向量检索相比
还要按模型的说明使用。问题短、切片长,两者的写法不同,所以很多模型要求只给问题加一段检索指令。例如 bge 中文模型建议在问题前加上“为这个句子生成表示以用于检索相关文章:”,切片不加;在切片实验的数据上,加前缀后 Recall@3 从 0.975 提高到 1.0,混入上述 12.5 万条短问题时从 0.575 提高到 0.700(见[附录 A12](#a12-切片方式top-k-与相似度阈值)、[A29](#a29-hnsw-的距离计算次数与知识库规模))。
其它模型的约定不同,例如 e5 要求问题以“query: ”开头、切片以“passage: ”开头,Qwen3-Embedding 把查询写成 `Instruct: {任务描述}\nQuery:{问题}` 的格式(指令建议用英文),切片不加指令。用 sentence-transformers 时,encode_query() 默认使用模型配置中的查询前缀,bge-small-zh-v1.5 的配置中这个前缀为空,encode_query() 与 encode() 的结果相同,要显式传入 prompt 参数或自己拼接(sentence-transformers 6.2 实测,见[附录 A12](#a12-切片方式top-k-与相似度阈值))。
其它模型的约定不同,例如 e5 要求问题以“query: ”开头、切片以“passage: ”开头,Qwen3-Embedding 把查询写成 `Instruct: {任务描述}\nQuery:{问题}` 的格式(多语言场景下指令建议用英文),切片不加指令。用 sentence-transformers 时,encode_query() 默认使用模型配置中的查询前缀,bge-small-zh-v1.5 没有配置查询前缀,encode_query() 使用默认的空前缀,结果与 encode() 相同,要显式传入 prompt 参数或自己拼接(sentence-transformers 6.2 实测,见[附录 A12](#a12-切片方式top-k-与相似度阈值))。
### 向量索引
#### 1. 为什么需要近似检索
最简单的检索方法是把问题向量与所有切片向量逐个比较。100 万个 1024 维的向量,每次查询需要约 10 亿次乘加运算,数据量和并发量大时太慢。向量数据库使用近似最近邻(Approximate Nearest Neighbor, ANN)索引,用少量精度换取速度,可能会漏掉个别真正最近的向量。
最简单的检索方法是把问题向量与所有切片向量逐个比较。100 万个 1024 维的向量,每次查询需要约 10 亿次乘加运算,数据量和并发量大时太慢。MySQL 这类数据库的 B+ Tree 索引也帮不上忙:它按键值排序,能加速等值、范围和前缀匹配,但不能按高维向量之间的距离取出最接近的几条(见 [B+ Tree 原理](MySQL.md#b-tree-原理))。向量数据库使用近似最近邻(Approximate Nearest Neighbor, ANN)索引,用少量精度换取速度,可能会漏掉个别真正最近的向量。
索引的召回率指的是返回的结果中有多少是逐个比较得到的真正 Top-K,衡量的是近似带来的误差;它与切片实验中“相关的资料有没有被找到”的召回率不是一回事。
@@ -1156,11 +1157,11 @@ IDF(t) = ln(1 + (N − n + 0.5) / (n + 0.5))
- Embedding 模型分别编码问题和文档,文档的向量可以提前计算并建立索引,速度快;但问题和文档在编码时互相看不到,细节的对应关系在压缩成一个向量时丢失了;
- 重排模型把问题和文档拼成一个输入一起编码,称为交叉编码器(Cross-Encoder),注意力可以在问题和文档的每个词之间计算,判断更准确;但每一对都要重新计算,只能处理少量候选。
所以先用速度快的检索从海量数据中召回几十条,再用准确的重排模型选出最终的几条,与搜索和推荐系统中先召回、后排序的分层思路一致。重排也不能作为第三路召回:它没有能提前算好的索引,按 bge-reranker-v2-m3 在 M1 Pro 上的实测速度估算,给 12.5 万条短文本全部打分约要 30 分钟(见[附录 A30](#a30-混合检索与重排的召回率))。
所以先用速度快的检索从海量数据中召回几十条,再用准确的重排模型选出最终的几条,与搜索和推荐系统中先召回、后排序的分层思路一致。重排也不能作为第三路召回:它没有能提前算好的索引,按 bge-reranker-v2-m3 在 M1 Pro 上的实测速度估算,给 12.5 万条短文本全部打分要 17~29 分钟(见[附录 A30](#a30-混合检索与重排的召回率))。
实现时,把混合检索合并后的几十个候选分别与问题组成(问题, 切片)对,交给重排模型打分,输出的相关性分数可以用 sigmoid 映射到 0~1,排序后保留前几条,再用阈值去掉分数过低的。在 [Top-K 检索](#2-top-k-检索)一节混入 12.5 万条干扰文本的实验中,对 RRF 的前 50 个候选重排后 Recall@1 从 0.275 升到 0.700,例如“结婚可以休几天假?”排第一的从“每周可以实习几天?”变为婚假一节(见[附录 A30](#a30-混合检索与重排的召回率))。
重排模型的训练与 Embedding 类似:每个问题配一个相关文档和若干难负样本,同一个问题的各个文档的分数一起做 softmax,损失是相关文档的交叉熵。常用开源的交叉编码器,例如 bge-reranker-v2-m3;也有基于大模型的重排模型,更准确但更慢。候选越多,越不容易漏掉相关的切片,延迟也越高,所以候选数量要在评测集上与延迟一起权衡。
bge-reranker 这类交叉编码器的训练与 Embedding 类似:每个问题配一个相关文档和若干难负样本,同一个问题的各个文档的分数一起做 softmax,损失是相关文档的交叉熵。常用开源的交叉编码器,例如 bge-reranker-v2-m3;也有基于大模型的重排模型,更准确但更慢。候选越多,越不容易漏掉相关的切片,延迟也越高,所以候选数量要在评测集上与延迟一起权衡。
### Top-K 与阈值
@@ -1170,7 +1171,7 @@ RAG 中有两个 K:召回的 K 是每路检索取多少个候选交给重排
#### 2. 召回的 K
召回的 K 在评测集上确定:计算不同 K 下的召回率,取召回率不再明显上升的位置。在切片一节的实验中,按小节切时 Recall@1 到 Recall@4 依次为 0.85、0.93、0.98、1.0,之后不再变化(见[附录 A12](#a12-切片方式top-k-与相似度阈值))。有重排时召回的 K 可以取大一些,排序交给重排模型。
召回的 K 在评测集上确定:计算不同 K 下的召回率,取召回率不再明显上升的位置。在切片一节的实验中,按小节切并加标题路径时 Recall@1 到 Recall@4 依次为 0.850、0.925、0.975、1.000,之后不再变化(见[附录 A12](#a12-切片方式top-k-与相似度阈值))。有重排时召回的 K 可以取大一些,排序交给重排模型。
#### 3. 放进提示词的 K
@@ -1204,7 +1205,7 @@ K 太小,需要多个切片才能回答的问题又会答不全,例如“几
改写需要多调用一次模型,会增加延迟。改写也可能变差:模型可能漏掉上下文或者偏离原意,改得差时检索效果反而不如原问题。
HyDE 这类生成扩展内容的方法,通常对原本检索效果较差的模型(例如 BM25)提升明显,对效果已经较强的 Embedding 模型和交叉编码器重排收益有限,甚至下降。作者对下降样例的人工分析中,多是扩展加入了无关或错误的词,干扰了相关性判断(Weller 等,arXiv 2309.08541,英文基准)。
HyDE 这类生成扩展内容的方法,通常对原本检索效果较差的模型(例如 BM25 和较早的稠密检索模型 DPR)提升明显,对效果已经较强的 Embedding 模型和交叉编码器重排收益有限,甚至下降。作者对下降样例的人工分析中,多是扩展加入了无关或错误的词,干扰了相关性判断(Wang 等,arXiv 2303.07678;Weller 等,arXiv 2309.08541,英文基准)。
已经用了混合检索和重排时,扩展要在评测集上确认有提升再加,也可以只用于召回差的查询;首轮和本身已经完整的问题可以不改写;评估改写时,用同一批标注了相关切片的问题,比较原问题和改写后的问题的 Recall@K、MRR,指标见[评测与优化](#评测与优化)。
@@ -1248,7 +1249,7 @@ RAG 需要分别评测检索和生成,这样才能定位问题出在哪一步
第二个回答把 3 月底写成了 6 月底,忠实度能发现,答案相关性发现不了,所以两个指标要一起看。评判模型本身也会出错:“工作两年有 5 天年假”需要从“满 1 年不满 10 年”推出来,7B 模型判为不支持,使正确的回答只得了 2 / 3。因此评判模型要选能力较强的,并抽样人工核对它的打分。
忠实度低说明回答中有资料推不出的内容,可能是编造,也可能是用了模型自己的知识,它不说明检索的好坏。ragas 库中的 Context Precision、Context Recall 要对照标准答案判断检索结果,属于检索指标,与论文中不需要标准答案的指标不同。
忠实度低说明回答中有资料推不出的内容,可能是编造,也可能是用了模型自己的知识,它不说明检索的好坏。ragas 库中的 Context Recall 要对照标准答案判断检索结果,Context Precision 默认也对照标准答案(另有用模型的回答代替标准答案的版本),它们属于检索指标,与论文中不需要标准答案的指标不同。
忠实度检查回答有没有资料支持,答案相关性检查有没有回应问题,两者都不能代替与标准答案比对对错。评测集有标准答案时,还要比较回答与标准答案:天数、日期这类短答案规范化后直接比较;长回答拆成几条陈述,与标准答案逐条比对,分别统计说错的和漏掉的,用模型比对时把标准答案交给它并要求以此为准,见[模型裁判的偏差](#3-模型裁判的偏差)。标准答案要写全要点,否则回答中正确但标准答案没写到的内容会被算成错误。
@@ -1268,10 +1269,10 @@ RAG 需要分别评测检索和生成,这样才能定位问题出在哪一步
| 步骤 | 怎么检查 | 常见问题与优化 |
| --- | --- | --- |
| 解析 | 打开相关文档的解析结果,与原文对比 | 表格错乱、页眉混入、扫描件没有 OCR:改用版面分析,表格转 Markdown |
| 切片 | 找到包含答案的切片,看答案是否完整地在一个切片中 | 答案被切断或者和无关内容混在一起:按结构切、加重叠、加标题路径 |
| Embedding 与检索 | 看相关切片在向量检索和 BM25 中分别排第几 | 措辞差异大:查询改写、换模型;专有名词、编号:混合检索;旧版本、无权限:元数据过滤;排名在 K 之外:增大 K |
| 重排 | 对比重排前后相关切片的排名 | 召回了但被排到后面:换重排模型,调整保留的数量 |
| 解析 | 打开相关文档的解析结果,与原文对比 | 表格错乱、页眉混入、扫描件没有 OCR:改用[版面分析](#2-版面分析),表格转 Markdown |
| 切片 | 找到包含答案的切片,看答案是否完整地在一个切片中 | 答案被切断或者和无关内容混在一起:按结构切、加重叠、加标题路径,见[常用做法](#2-常用做法) |
| Embedding 与检索 | 看相关切片在向量检索和 BM25 中分别排第几 | 措辞差异大:[查询改写](#查询改写)、[换模型](#3-选择模型);专有名词、编号:[混合检索](#混合检索);旧版本、无权限:[元数据过滤](#1-过滤);排名在 K 之外:[增大 K](#2-召回的-k) |
| 重排 | 对比重排前后相关切片的排名 | 召回了但被排到后面:换[重排](#重排)模型,调整[保留的数量](#3-放进提示词的-k) |
| 生成 | 把正确的资料直接交给模型,看能否答对 | 资料对但回答错:减少放入的切片,要求逐条引用,换更强的模型 |
最后一步也可以先做:把正确的资料直接交给模型,答不对说明问题在生成,答得对说明问题在前面的检索。
@@ -1291,7 +1292,7 @@ RAG 解决的是模型缺少知识的问题,固定输出风格或者学习专
### GraphRAG
按切片检索有两类问题处理不好。一类是多跳问题,例如上一节的“负责支付系统的团队的负责人是谁”,“支付系统由交易平台组维护”和“交易平台组的负责人是王磊”在两份文档里,问题与第二句的相似度很低;另一类是全局问题,例如“今年的制度主要改了哪些地方”,答案分散在整个知识库中,取几个切片覆盖不了。
按切片检索有两类问题处理不好。一类是多跳问题,例如上一节的“负责支付系统的团队的负责人是谁”,“支付系统由交易平台组维护”和“交易平台组的负责人是王磊”在两份文档里,问题中没有“交易平台组”,第二句与其它团队“负责人是某某”的句子很难区分;另一类是全局问题,例如“今年的制度主要改了哪些地方”,答案分散在整个知识库中,取几个切片覆盖不了。
GraphRAG 在建索引时让模型从每个切片中抽取实体和关系,组成知识图谱:
@@ -1302,7 +1303,7 @@ GraphRAG 在建索引时让模型从每个切片中抽取实体和关系,组
查询时先找到问题中的实体“支付系统”,沿着边走两步就得到答案,再把相关的原文交给模型生成回答,这是图检索的一般做法。微软的 GraphRAG 的局部搜索(Local Search)则用问题的向量匹配实体描述的向量,取出这些实体相邻的关系、所在社区的摘要和原文,一起放进一次上下文。
对于全局问题,微软的 GraphRAG 用社区检测算法把联系紧密的实体分组,为每组生成一段摘要;回答时先让每个摘要分别给出部分回答,再汇总成最终的回答,称为全局搜索(Global Search)。
对于全局问题,微软的 GraphRAG 用社区检测算法把联系紧密的实体分组,为每组生成一段摘要;回答时把这些摘要分成若干批,先让每批分别给出部分回答,再汇总成最终的回答,称为全局搜索(Global Search)。
代价是建索引要对每个切片调用大模型,比计算 Embedding 贵得多,抽取的错误会进入图中。
@@ -1367,7 +1368,7 @@ GROUP BY i.category;
## 四、Agent
### Agent 是什么 🔥🔥
### Agent 是什么
普通的大模型调用是一问一答:模型根据输入生成一段文本。它无法自行查询数据库、调用接口,只能依据训练中学到的知识和输入中给出的资料,更不能替用户执行操作。
@@ -1389,7 +1390,7 @@ Agent(智能体)指的是让大模型通过调用工具来完成任务的系
模型以外的部分合称 [Harness](#harness)。
### 工具调用
### 工具调用 🔥
工具调用(Function Calling)指的是模型按照约定的格式给出要调用的函数名和参数,由应用程序执行。模型能够“调用工具”,过程如下:
@@ -1454,9 +1455,9 @@ Agent(智能体)指的是让大模型通过调用工具来完成任务的系
- 返回结果要精简,只返回模型需要的字段,大段的原始数据会占用上下文;
- 出错时返回能指导模型修正的信息,例如“日期格式应为 2026-01-01”,而不是只返回“参数错误”。
描述写得是否清楚,对结果的影响很大。在上面的例子中,系统提示词只写“你是电商客服助手,回答要简短”时,7B 模型查到运单号就直接回答“已发货,运单号是 SF1234567”,没有继续查物流;采样运行 10 次,1 次也没有答出包裹的位置。在系统提示词中写明“用户问包裹到哪了时,先查订单拿到运单号,再查物流,告诉用户当前位置和预计送达时间”后,10 次全部依次调用了两个工具,回答“您的包裹目前位于杭州转运中心,预计明天送达”。同样的提示词换成 3B 模型,20 次都只调用了一个工具;模型能力不足时,提示词也弥补不了(Qwen2.5 实测,见[附录 A2](#a2-提示词对工具调用的影响))。
提示词中有没有写清调用工具的步骤,对结果的影响也很大。在上面的例子中,系统提示词只写“你是电商客服助手,回答要简短”时,7B 模型采样运行 10 次,1 次也没有答出包裹的位置:7 次查到运单号就直接回答“已发货,运单号是 SF1234567”,没有继续查物流,另外 3 次没有调用工具。在系统提示词中写明“用户问包裹到哪了时,先查订单拿到运单号,再查物流,告诉用户当前位置和预计送达时间”后,10 次全部依次调用了两个工具,回答“您的包裹目前位于杭州转运中心,预计明天送达”。同样的提示词换成 3B 模型,20 次都只调用了一个工具,这句提示词对 3B 模型没有起作用(Qwen2.5 实测,见[附录 A2](#a2-提示词对工具调用的影响))。
工具很多时,全部的工具定义会占用大量上下文,模型也更容易选错。可以只加载与当前任务相关的工具,例如先根据问题检索出最相关的十几个工具,或者把工具分组交给不同的子 Agent。
工具很多时,全部的工具定义会占用大量上下文,模型也更容易选错。可以只加载与当前任务相关的工具,例如先根据问题检索出最相关的十几个工具,或者把工具分组交给不同的子 Agent,见 [MCP](#mcp) 和[多 Agent](#多-agent)。
### Agent 循环
@@ -1573,7 +1574,7 @@ for (CompletableFuture<Message> f : results) {
- Embedding 相似度(bge-small-zh-v1.5 加每类 6 条示例)的准确率是 78.3%,示例太少时容易被字面相似误导,例如把“保修多久”分到退款;
- Qwen2.5-7B 的准确率是 95%,10 条含有其它类别关键词的消息全部分对。
需要注意的是,7B 模型把“快递员态度太差了,我要投诉”的类别输出成了“投诉”,这个类别并不存在(Qwen2.5 实测,见[附录 A6](#a6-意图路由的三种做法))。
需要注意的是,7B 模型把“快递员态度太差了,我要投诉”的类别输出成了“投诉”,这个类别并不存在。上面的准确率按第一个 Token 在 5 个类别上概率最高的一类计分,这条记为其它;按生成的文本计分,7B 的准确率是 93.3%(Qwen2.5 实测,见[附录 A6](#a6-意图路由的三种做法))。
#### 2. 怎样保证路由准确
@@ -1583,7 +1584,7 @@ for (CompletableFuture<Message> f : results) {
- 校验输出:类别名必须在列表中,用[结构化输出](#结构化输出)把输出限制为枚举值,不在列表中的按“其它”处理;
- 分层:规则只处理精确率高的情况,例如“转人工”、消息中带有订单号格式的查询,其余的交给模型。类别或工具有上百个时也可以逐级分类,先分到售后、物流这样的业务域,再在域内细分或[按问题检索工具](#工具调用);
- 低置信度兜底:置信度低于阈值时不硬分,而是反问澄清(“您是想查物流还是申请退款?”),或者交给通用的 Agent、转人工。已经进入流程后发现分错(例如用户说“我不是要退款”),流程把请求退回路由重新分类,而不是继续执行;
- 看上下文:多轮对话中的“那退了吧”单独看无法分类,要把最近几轮对话一起交给分类器,或者先把它改写成完整的问题;一句话包含多个意图时,拆成多个请求,或者交给能分派任务的主 Agent。
- 看上下文:多轮对话中的“那退了吧”单独看无法分类,要把最近几轮对话一起交给分类器,或者先把它改写成完整的问题,见[指代与省略](#1-指代与省略);一句话包含多个意图时,拆成多个请求,或者交给能分派任务的主 Agent,见[协作方式](#2-协作方式)。
阈值要在验证集上扫一遍再定:阈值越高,自动路由的比例越低,准确率一般越高。例如上面 Embedding 相似度方法的置信度阈值从 0.5 提到 0.7,自动路由从 70% 降到 48%,准确率从 90.5% 升到 96.6%,其余转入兜底流程。按兜底流程能承接的量和可以接受的错误率选一个点,分错代价高的类别(例如会进入退款流程的)可以单独设更高的阈值。
@@ -1593,7 +1594,7 @@ for (CompletableFuture<Message> f : results) {
- 按类别收集样本,每类数量接近,特别要包含容易混淆的消息和不属于任何类别的消息,后者要单独统计召回率,例如在 CLINC150 数据集上,BERT 对 150 个意图的准确率约 96%~97%,范围外的消息却只召回 40.3%(把范围外当作一类训练)或 52.3%(按概率阈值判断)(Larson 等,arXiv 1909.02027);
- 按类别看精确率(判为这一类的消息中有多少是对的)和召回率(这一类的消息找回了多少),两种错误的代价不同:误进退款流程的代价通常比漏判后转人工高。例如本例规则对退款的精确率是 100%,召回率只有 58%(7/12);
- 看混淆矩阵,即每个类别被错分到了哪里,例如本例中规则的 16 个错误有 9 个是没有命中任何关键词、落入“其它”,5 个是被“快递”“到哪”这类词误导、分到了物流;
- 看混淆矩阵,即每个类别被错分到了哪里,例如本例中规则的 16 个错误有 9 个是没有命中任何关键词、落入“其它”,6 个是被“快递”“到哪”这类词误导、分到了物流;
- 线上转人工、用户改口重说的会话说明路由可能错了,定期抽查后加入评测集;
- 修改类别定义、提示词或者模型之后,在同一个评测集上回归,确认没有让其它类别变差。
@@ -1615,7 +1616,7 @@ ReAct 把推理和行动交替进行:每一步先思考,再调用工具,
论文中的 ReAct 让模型按 Thought、Action、Observation 的文本格式输出,再由代码解析;现在的实现直接使用模型原生的工具调用,思考写在回复的文本或推理内容中。
ReAct 适合下一步取决于上一步结果、步数不多的任务,例如先查订单拿到运单号,再查物流。它的问题是每一步都要调用一次模型,步骤只能串行;长任务中容易偏离最初的目标,或者反复执行同一个步骤,上面的分析中 ReAct 的失败有 47% 是推理错误,其中包括陷入重复的步骤。
ReAct 适合下一步取决于上一步结果、步数不多的任务,例如先查订单拿到运单号,再查物流。它的问题是每一步都要调用一次模型,前后依赖的步骤只能串行(同一步中互不依赖的工具调用可以一次发出、并行执行);长任务中容易偏离最初的目标,或者反复执行同一个步骤,上面的分析中 ReAct 的失败有 47% 是推理错误,其中包括陷入重复的步骤,限制步数和预算的做法见[可靠性与评测](#可靠性与评测)。
#### 3. 先规划后执行
@@ -1635,7 +1636,7 @@ ReAct 适合下一步取决于上一步结果、步数不多的任务,例如
两种方式的比较:
- 先规划后执行:互不依赖的步骤可以并行,进度容易展示和恢复;但计划可能与实际情况不符,需要重规划。它不一定比 ReAct 省:步骤直接调用不依赖模型的工具、也不重规划时,整个任务可以只调用两次模型,分别用于规划和汇总,ReWOO 论文报告它在 HotpotQA 上的 Token 消耗约为 ReAct 的 1/5;每个步骤再用模型执行,或者每步都重规划时,调用次数可能比 ReAct 还多;
- 先规划后执行:互不依赖的步骤可以并行,进度容易展示和恢复;但计划可能与实际情况不符,需要重规划。它不一定比 ReAct 省:步骤直接调用不依赖模型的工具、也不重规划时,整个任务可以只调用两次模型,分别用于规划和汇总,ReWOO 论文报告它在 HotpotQA 上的 Token 消耗约为 ReAct 的 1/5(计划中部分步骤也调用了模型,这些 Token 已计入);每个步骤再用模型执行,或者每步都重规划时,调用次数可能比 ReAct 还多;
- ReAct:可以根据中间结果随时调整方向;但每一步都要调用一次大模型,长任务中容易偏离最初的目标。
实际系统常把两者结合:先生成一份计划,执行每个步骤时使用 ReAct,并在执行过程中更新计划。
@@ -1665,7 +1666,7 @@ ReAct 适合下一步取决于上一步结果、步数不多的任务,例如
### 记忆 🔥
模型本身不保存任何状态。模型服务的对话接口一般是无状态的,不会自动接续之前的请求,每次调用都要把需要的历史重新发过去。聊天应用看起来“记得”之前说过的话,是因为应用把这些信息保存了下来,在下一次调用时放回了上下文。也有接口可以由服务端维护对话状态,例如 OpenAI Responses API 可以用 previous_response_id 或 Conversations 接续之前的对话,由服务端把历史拼回输入,但之前的 Token 仍然按输入计费(以官方最新文档为准)。
模型本身不保存任何状态。模型服务的对话接口一般是无状态的,不会自动接续之前的请求,每次调用都要把需要的历史重新发过去。聊天应用看起来“记得”之前说过的话,是因为应用把这些信息保存了下来,在下一次调用时放回了上下文。也有接口可以由服务端维护对话状态,例如 OpenAI Responses API 可以用 previous_response_id 或 Conversations 接续之前的对话,由服务端把历史拼回输入;用 previous_response_id 接续时,之前的 Token 仍然按输入计费(以官方最新文档为准)。
所以记忆和上下文是两回事:上下文是一次调用的输入,调用结束就没有了;记忆是应用保存的数据,每次调用前从中挑出一部分放进上下文。记忆要解决的是保存什么、存在哪里,以及什么时候取出来。
@@ -1744,7 +1745,7 @@ Redis 的持久化不保证不丢数据,开启 AOF 的 everysec 时故障仍
1. 按用户 ID 过滤,这个条件由代码写进查询中,不能依靠模型,否则可能取到其他用户的记忆;
2. 按与当前问题的相似度排序,方法与 RAG 中的向量检索相同;
3. 结合时间和重要性调整顺序。例如 Generative Agents 把三项分数归一化后相加:与当前问题的相关度,按指数衰减的时间分数(每过一小时乘以 0.995),以及写入时由模型打出的重要性分数。
3. 结合时间和重要性调整顺序。例如 Generative Agents 把三项分数归一化后相加:与当前问题的相关度,按指数衰减的时间分数(从这条记忆上次被检索起,模拟环境中每过一小时乘以 0.995),以及写入时由模型打出的重要性分数。
不是每条记忆都要检索:称呼、回答风格这类每次都用得到的少量信息,可以固定放在系统提示词中;其它的按当前问题检索最相关的几条。也可以把检索做成一个 search_memory 工具,由模型判断什么时候需要,适合记忆很多、而大部分问题用不到记忆的场景。
@@ -1758,9 +1759,9 @@ Redis 的持久化不保证不丢数据,开启 AOF 的 everysec 时故障仍
<div align="center"> <img src="pics/agent-memory-update.png" width="720px"/> </div><br>
模型正确地选择了更新 m1,但在新记忆中写了一个编造的日期。所以模型只负责判断做哪种操作、新的内容是什么,用户 ID、时间这类字段由代码填写。
模型正确地选择了更新 m1,但在新记忆中写了一个编造的日期。所以模型只负责判断做哪种操作、新的内容是什么,用户 ID、时间这类字段由代码填写。选择操作同样会出错:同一次实验中,模型对手机尾号选择了 NONE,这条应该记住的事实没有写入(见[附录 A5](#a5-长期记忆的提取与更新)),所以更新这一步也要和提取一样评测。
需要注意的是,这是 Mem0 论文和早期版本的做法。Mem0 开源版后来改为自动写入只做新增:一次模型调用提取新事实,旧记忆只用来去重,搬家后新旧两条地址都保留,更正和删除由应用调用 update、delete 完成(以官方最新版本为准)。
需要注意的是,这是 Mem0 论文和早期版本的做法。Mem0 开源版从 v2.0.0(2026 年 4 月)起改为自动写入只做新增:一次模型调用提取新事实,旧记忆只用来去重,搬家后新旧两条地址都保留,更正和删除由应用调用 update、delete 完成(以官方最新版本为准)。
新旧信息冲突时,按可信程度和适用范围判断:用户本次明确说的优先于记忆中的,用户亲口说的优先于模型推断的,来源相同时以新的为准;只对这一次有效的说法不覆盖长期记忆,例如“这次说详细一点”不会改变“喜欢简短的回答”;订单、账户这类数据以业务系统为准,本来就不写进记忆。仍然无法判断时,在对话中向用户确认。
@@ -1791,7 +1792,7 @@ LangGraph 等框架用检查点(Checkpoint)在每一步之后自动保存整
多轮对话的实现方式与 Agent 循环相同:每次请求都把历史连同新消息一起发给模型,历史由应用按会话保存,见[短期记忆](#1-短期记忆)。轮数多了之后,除了上下文膨胀(见[上下文工程](#上下文工程)),还有三个常见的问题:用户的话要结合前文才能理解,信息不足时模型自行假设,话题切换后旧的内容造成干扰。
多轮对话对模型本身也更难。一项研究模拟了 20 多万次对话,把同一个任务的要求拆成几轮逐步告诉模型,15 个模型在 6 类任务上的表现比一次说完时平均下降了 39%。主要原因是模型在信息还不全的早期轮次就做出假设、给出完整的答案,之后又过度依赖这些答案,一旦走错就很难回到正轨。
多轮对话对模型本身也更难。一项研究模拟了 20 多万次对话,把同一个任务的要求拆成几轮逐步告诉模型,15 个模型在 6 类任务上的表现比一次说完时平均下降了 39%。主要原因是模型在信息还不全的早期轮次就做出假设、给出完整的答案,之后又过度依赖这些答案,一旦走错就很难回到正轨。训练时,多轮对话样本中每一轮助手的回答都计入损失,见 [SFT 数据](#2-sft-数据)。
注意力机制在长对话中有两方面的局限:
@@ -1841,7 +1842,7 @@ LangGraph 等框架用检查点(Checkpoint)在每一步之后自动保存整
处理方法:
- 把当前的目标、已确认的信息和待办作为任务状态单独维护,每次放在上下文的末尾,模型对开头和结尾的内容利用得最好;
- 把当前的目标、已确认的信息和待办作为任务状态单独维护,每次放在上下文的末尾,模型通常对开头和结尾的内容利用得最好;
- 一个话题结束后,把这部分对话压缩成一句结果,例如“订单 1025 已办理退货,单号 R2051”;
- 一个任务没完成就被新话题打断时,把原任务和已经收集到的信息挂起,新任务完成后询问用户是否继续,例如“订单 1025 的退货还要继续吗?”,而不是自动恢复原任务,Rasa 默认的中断恢复流程就是这样处理的;
- 任务结束后,清理任务状态中只属于这个任务的临时信息,收货地址这类之后还要用的信息才保留;
@@ -1853,7 +1854,7 @@ LangGraph 等框架用检查点(Checkpoint)在每一步之后自动保存整
- 对话中积累了多次失败的尝试,模型会受到前面错误回答的影响,上面的研究建议把已知的信息整理成一条完整的要求,在新会话中重新开始;
- 已经压缩了多次,摘要中丢失的细节越来越多。
开启新会话时不带上之前的完整对话,只放入长期记忆,以及上一次会话的摘要和未完成的待办,见[记忆](#记忆)中的中断与恢复。
开启新会话时不带上之前的完整对话,只放入长期记忆,以及上一次会话的摘要和未完成的待办,见[中断与恢复](#5-中断与恢复)。
### MCP 🔥
@@ -1886,7 +1887,7 @@ MCP 中有三种角色:
```json
{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "read_file", "arguments": {"path": "README.md"}}}
"params": {"name": "read_text_file", "arguments": {"path": "README.md"}}}
{"jsonrpc": "2.0", "id": 2,
"result": {"resultType": "complete",
@@ -1934,7 +1935,7 @@ Anthropic 还介绍过一种做法:把 MCP 工具生成为代码文件,Agent
另外,第三方服务端的工具描述、服务端说明(instructions,客户端可能把它放进系统提示词)和返回结果都可能包含恶意指令,应该像安装软件一样只使用可信的服务端。MCP 规范仍在快速演进,本节对照 2026-07-28 版,细节以官方最新版本为准。
### Skills 🔥
### Skills 🔥🔥
Skill(技能)是一个包含说明文档、脚本和参考资料的文件夹,用于教会 Agent 完成某一类任务,例如按团队模板写周报。文件夹中的 SKILL.md 开头用 name 和 description 描述这个 Skill 做什么、什么时候使用,正文是具体的操作步骤。
@@ -1943,12 +1944,12 @@ Skill 的核心是渐进式加载:
<div align="center"> <img src="pics/skills.png" width="690px"/> </div><br>
1. 启动时只加载每个 Skill 的名称和描述,每个约 100 Token;
2. 用户的请求与某个 Skill 的描述匹配时,才读取 SKILL.md 的正文;
2. 模型判断用户的请求与某个 Skill 的描述相符时,才读取 SKILL.md 的正文;
3. 正文中引用的其它文档和脚本在需要时才读取或执行,脚本只有运行结果进入上下文。
因此即使安装了几十个 Skill,平时占用的上下文也很少。
判断是否使用某个 Skill 的是模型本身,而不是关键词匹配或者向量检索:所有 Skill 的名称和描述放在系统提示词中,模型认为当前任务与某个描述相符时,用读取文件的工具(例如用 cat 命令读取 SKILL.md)或者 Agent 提供的专门工具把正文读进上下文,再按正文中的步骤执行。
判断是否使用某个 Skill 的通常是模型本身,而不是关键词匹配或者向量检索:所有 Skill 的名称和描述作为目录放进上下文(一般在系统提示词中,也可以写在专门加载 Skill 的工具的描述里),模型认为当前任务与某个描述相符时,用读取文件的工具(例如用 cat 命令读取 SKILL.md)或者 Agent 提供的专门工具把正文读进上下文,再按正文中的步骤执行。
读进来的正文和其它工具结果一样追加在对话历史中,此后每次请求都会带上,没有单独的卸载步骤,直到会话结束或上下文被压缩(Claude Code 压缩时会把最近用过的 Skill 重新附在摘要之后,每个最多保留 5000 Token)。效果上这与把正文粘贴进对话相同,区别在于由模型按描述自动发现、不必每次手工提供,还可以附带脚本。
@@ -1983,7 +1984,7 @@ name 只能包含小写字母、数字和连字符,最长 64 个字符;descr
需要接入外部系统、要求权限控制的能力(例如查询公司的工单系统)适合做成 MCP 服务端;告诉 Agent 怎样组合已有工具完成任务的流程和规范,适合写成 Skill。知识量大、经常更新、每次只用到其中几段的资料(例如产品手册)则适合用 RAG 检索片段,因为 Skill 的正文读入后会整段留在上下文中。
Skill 中可以包含脚本,等同于让 Agent 执行代码,只应该使用可信来源的 Skill。
Skill 中可以包含脚本,等同于让 Agent 执行代码,只应该使用可信来源的 Skill,来源不够可信的先审阅其中的说明和脚本。
Skill 与系统提示词、Agent 的区别:
@@ -2052,7 +2053,7 @@ Agent 之间传递信息的方式有三种:主管分派时通过工具调用
- 子任务之间依赖紧密、需要共享全部上下文的任务。例如两个子 Agent 分别写同一功能的前端和后端,各自假设了不同的接口字段,合并时才发现冲突;
- 对延迟和成本敏感的在线请求,例如客服的每一轮回复。
一项对 7 个多 Agent 框架、1600 多条运行记录的研究总结了 14 种失败模式,分为三类:系统设计问题(例如不遵守任务要求、重复已经完成的步骤、不知道何时该结束)、Agent 之间的不一致(例如不澄清就按错误的假设继续、忽略其它 Agent 的输入)、任务验证不足(例如提前结束、没有验证或者验证不正确)。论文也指出,在常用的基准上,多 Agent 相对单 Agent 或者简单地多次采样取最好结果,提升往往很小。
一项研究人工分析了 150 多条多 Agent 运行记录,总结出 14 种失败模式,再用模型按这套分类标注了 7 个框架的 1600 多条记录。失败模式分为三类:系统设计问题(例如不遵守任务要求、重复已经完成的步骤、不知道何时该结束)、Agent 之间的不一致(例如不澄清就按错误的假设继续、忽略其它 Agent 的输入)、任务验证不足(例如提前结束、没有验证或者验证不正确)。论文也指出,在常用的基准上,多 Agent 相对单 Agent 或者简单地多次采样取最好结果,提升往往很小。
因此多 Agent 适合可以拆成独立部分并行处理、单个上下文装不下的任务,例如同时调研多个主题;需要隔离权限时也可以拆分,例如只让一个 Agent 拥有退款工具。修改同一份代码这类任务,更适合由单个 Agent 完成。
@@ -2067,7 +2068,7 @@ Agent 之间传递信息的方式有三种:主管分派时通过工具调用
- 发现:物流 Agent 在 /.well-known/agent-card.json 发布 Agent Card,写明名称、描述、技能(例如查询轨迹、改派)、服务地址和认证方式,客服 Agent 读取后决定是否委托、怎么调用;
- 任务:客服 Agent 发送一条消息,物流 Agent 创建一个带 ID 的任务(Task)。任务有状态:已提交、处理中、需要输入(例如要收件人手机号后四位)、已完成、失败、已取消等,需要输入时客服 Agent 补充一条消息后任务继续;
- 内容:消息由若干部分(Part)组成,可以是文本、文件或结构化数据,任务的产出称为 Artifact;
- 传输:基于 HTTP,可以用 JSON-RPC 2.0、gRPC 或者 HTTP+JSON;长任务用 SSE 推送进度,或者由对方在任务状态变化时回调客户端登记的地址,回调可能重复送达,规范建议接收方做幂等处理。
- 传输:基于 HTTP,可以用 JSON-RPC 2.0、gRPC 或者 HTTP+JSON;长任务用流式响应推送进度(JSON-RPC 和 HTTP+JSON 用 SSE,gRPC 用服务端流),或者由对方在任务状态变化时回调客户端登记的地址,回调可能重复送达,规范建议接收方做幂等处理。
A2A 与 MCP 的区别:
@@ -2108,7 +2109,7 @@ Vibe Coding 这个说法由 Andrej Karpathy 在 2025 年 2 月提出,指的是
### Harness
Agent 由模型和 Harness 两部分组成。Harness 指的是模型之外的所有代码、配置和执行逻辑:Agent 循环、系统提示词、工具及其描述、上下文压缩、记忆、沙箱与权限、子 Agent 的调度,以及在固定时机执行的钩子(例如每次修改文件后自动格式化)。模型本身只接收文本、输出文本,不能保存状态、执行代码、获取实时信息,这些都要由 Harness 补上。前面不到二十行的 Agent 循环就是一个最简单的 Harness;Claude Code、Codex 是功能完整的 Harness,可以换用不同的模型。MCP 和 Skill 也是 Harness 的组成部分,前者负责接入工具,后者负责按需提供做事的方法。
Agent 由模型和 Harness 两部分组成。Harness 指的是模型之外的所有代码、配置和执行逻辑:Agent 循环、系统提示词、工具及其描述、上下文压缩、记忆、沙箱与权限、子 Agent 的调度,以及在固定时机执行的钩子(例如每次修改文件后自动格式化)。模型本身只接收文本、输出文本,不能保存状态、执行代码、获取实时信息,这些都要由 Harness 补上。前面不到二十行的 Agent 循环就是一个最简单的 Harness;Claude Code、Codex 是功能完整的 Harness,可以换用不同的模型。MCP 和 Skill 也是 Harness 的组成部分,前者负责接入工具,后者负责按需提供做事的方法,见 [MCP](#mcp) 和 [Skills](#skills)。
提示词工程关注写给模型的指令,上下文工程关注每次调用放进上下文的内容,两者都是 Harness 的一部分。关注点一层层扩大,是因为任务变了:Agent 多步执行时,每一步都要重新挑选和压缩上下文,见[上下文工程](#上下文工程);Agent 长时间自主改代码、执行命令时,权限检查、重试次数和进度保存要由程序确定地执行,写进上下文只能提醒模型,不能保证做到。
@@ -2161,11 +2162,11 @@ Harness 的每个部分都对应一个模型自己做不到或做不稳的问题
#### 4. 模型变强以后
Harness 的每个组件都隐含一个假设:模型自己做不到这件事。模型升级后,这些假设可能不再成立,需要逐个去掉组件验证效果。Anthropic 的例子中,Claude Opus 4.5 基本不再因为担心上下文用完而提前收尾,于是去掉了会话之间的上下文重置;Opus 4.6 能连续工作两个多小时,又去掉了把任务拆成多个冲刺的结构。他们的结论是,值得做的 Harness 组合不会随模型变强而减少,而是会转移到新的问题上。LangChain 的看法类似:一部分现在由 Harness 完成的事会被模型吸收,但环境、工具、持久的状态和校验循环对任何模型都有用;Claude Code、Codex 这类产品的模型在后训练时就带着 Harness 一起训练。
Harness 的每个组件都隐含一个假设:模型自己做不到这件事。模型升级后,这些假设可能不再成立,需要逐个去掉组件验证效果。Anthropic 的例子中,Claude Opus 4.5 基本不再因为担心上下文用完而提前收尾,于是去掉了会话之间的上下文重置;Opus 4.6 发布后,又去掉了把任务拆成多个冲刺的结构,生成代码的 Agent 不拆分也能连贯地工作两个多小时。他们的结论是,值得做的 Harness 组合不会随模型变强而减少,而是会转移到新的问题上。LangChain 的看法类似:一部分现在由 Harness 完成的事会被模型吸收,但环境、工具、持久的状态和校验循环对任何模型都有用;Claude Code、Codex 这类产品的模型在后训练时就带着 Harness 一起训练。
#### 5. 与开发框架的关系
开发框架(例如 LangChain)提供模型调用、工具、Agent 循环等抽象;运行时(例如 LangGraph)负责持久执行、流式输出、人工介入和状态保存;Harness 在两者之上直接给出一套可用的默认配置,包括系统提示词、工具调用的处理、规划工具和文件系统等,拿来就能工作。这个划分来自 LangChain 的文章,边界并不严格。现成的 Harness 产品变化很快,例如 Claude Code(官方文档称为 agentic harness)、DeepSeek Harness(开发者预览版,所有能力都以插件提供)、Pi(只带最小的默认功能,其余靠扩展),具体功能以官方最新文档为准。
开发框架(例如 LangChain)提供模型调用、工具、Agent 循环等抽象;运行时(例如 LangGraph)负责持久执行、流式输出、人工介入和状态保存;Harness 在两者之上直接给出一套可用的默认配置,包括系统提示词、工具调用的处理、规划工具和文件系统等,拿来就能工作。这个划分来自 LangChain 的文章,边界并不严格。现成的 Harness 产品变化很快,例如 Claude Code(官方文档称为 agentic harness)、DeepSeek Harness(开发者预览版,所有能力都以插件提供)、Pi(定位为最小、可扩展的 Harness,不内置子 Agent 和计划模式,需要时用扩展添加),具体功能以官方最新文档为准。
### 开发框架
@@ -2178,7 +2179,7 @@ Harness 的每个组件都隐含一个假设:模型自己做不到这件事。
框架减少了重复代码,但也隐藏了细节:排查问题时仍然要查看实际发送给模型的消息。Anthropic 的工程博客建议先直接调用接口,用框架时要弄清它底层做了什么。
核心的循环只有几十行,只用一个模型、少量工具时可以直接调用接口;需要持久化、人工介入或在多个模型之间切换时,框架的价值更大。框架与低代码平台的取舍见[怎样选择](#4-怎样选择)。
核心的循环不到二十行,只用一个模型、少量工具时可以直接调用接口;需要持久化、人工介入或在多个模型之间切换时,框架的价值更大。框架与低代码平台的取舍见[怎样选择](#4-怎样选择)。
#### 1. 为什么用图编排
@@ -2280,7 +2281,7 @@ String answer = ChatClient.create(chatModel)
框架根据方法签名生成参数的 JSON Schema,模型返回工具调用后,由框架执行方法、把结果发回模型,直到得到最终回答。工具抛出运行时异常时,默认把异常信息作为工具结果发回模型,让它修正或者向用户说明。但并不是所有错误都会回传:模型写了不存在的工具名时,框架直接抛出 IllegalStateException,整个请求失败;框架也不会在执行工具前按生成的 Schema 校验模型传入的参数,多余的字段被忽略,包装类型的参数缺失时传入 null(Spring AI 2.0.2 源码与测试)。已经进入工具方法的参数可以在方法内部校验并抛出异常,由框架回传给模型;不存在的工具名、基本类型的参数缺失这类框架不会自动回传的错误,要自己捕获后组织成工具的错误结果,必要时接管工具调用的循环。需要注意的是,编译时要保留参数名(javac 的 -parameters 选项,继承 spring-boot-starter-parent 时默认开启),否则 Schema 中的参数名是 arg0(Spring AI 2.0.2 实测,见[附录 A9](#a9-spring-ai-的工具调用循环))。
对话记忆由 ChatMemory 接口管理:默认的 MessageWindowChatMemory 保留最近的 20 条消息,系统消息始终保留;消息存放在 ChatMemoryRepository 中,默认在内存里,也可以换成 JDBC、Cassandra 等实现。使用时给 ChatClient 加上 MessageChatMemoryAdvisor,每次调用传入会话 ID,它在调用前按会话 ID 取出历史放进请求,调用后保存新的消息。需要注意的是,默认情况下工具调用的请求和结果不会写入记忆,下一轮对话时模型看不到上一轮查过什么(Spring AI 2.0.2 实测,见[附录 A28](#a28-spring-ai-的对话记忆与工具调用))。这是因为 MessageChatMemoryAdvisor 默认排在工具调用循环之外,只保存最终的用户消息和回答。
对话记忆由 ChatMemory 接口管理:默认的 MessageWindowChatMemory 最多保留最近的 20 条消息(按完整的轮次裁剪,实际可能更少),系统消息始终保留;消息存放在 ChatMemoryRepository 中,默认在内存里,也可以换成 JDBC、Cassandra 等实现。使用时给 ChatClient 加上 MessageChatMemoryAdvisor,每次调用传入会话 ID,它在调用前按会话 ID 取出历史放进请求,调用后保存新的消息。需要注意的是,默认情况下工具调用的请求和结果不会写入记忆,下一轮对话时模型看不到上一轮查过什么(Spring AI 2.0.2 实测,见[附录 A28](#a28-spring-ai-的对话记忆与工具调用))。这是因为 MessageChatMemoryAdvisor 默认排在工具调用循环之外,只保存最终的用户消息和回答。
需要保存工具记录时,可以把 MessageChatMemoryAdvisor 的 order 设为大于 ToolCallingAdvisor 的值;Spring AI 2.0 的内置仓库中只有内存、Redis、Neo4j 能保存工具消息,JDBC 不能(以官方最新文档为准),用 JDBC 时由应用自己保存,见[短期记忆](#1-短期记忆)。
@@ -2333,9 +2334,9 @@ Agent 的每一步都可能出错,容错的逻辑要写在控制循环(Harne
- 模型可以修正的错误,例如参数格式不对、取值不在范围内:把错误信息作为工具结果回传给模型,信息中写明错在哪、正确的格式是什么;
- 重试后仍然失败:把失败如实回传给模型,由它换一种办法,或者告诉用户哪一步失败了、返回已经拿到的部分结果、转人工,不能让模型编造结果。
不能指望模型自己处理临时性错误。在“订单 1024 到哪了”的例子中,让物流接口第一次调用返回“物流接口超时,请稍后重试”,并把错误回传给模型,7B 模型 10 次运行中没有一次重新调用,都回答物流信息暂时查不到、请稍后再试;而接口实际上第二次调用就能成功。
不能指望模型自己处理临时性错误。在“订单 1024 到哪了”的例子中,让物流接口第一次调用返回“物流接口超时,请稍后重试”,并把错误回传给模型,7B 模型 10 次运行中没有一次重新调用,都回答物流信息暂时查不到,其中 3 次还说包裹“正在运输中”;而接口实际上第二次调用就能成功。
参数错误能否被修正,取决于错误信息写得是否清楚。物流接口要求快递公司编码为 shunfeng,模型按常识填了 SF:错误信息只写“参数错误”时 10 次都没有重新调用,其中 4 次编造了位置或送达时间,例如“目前包裹在上海市,预计 2 天内送达”;写明“carrier 应为快递公司编码,顺丰为 shunfeng”时 10 次都改用 shunfeng 重新调用,全部答出了包裹在杭州转运中心(Qwen2.5-7B 实测,见[附录 A7](#a7-工具出错时-agent-的表现))。
参数错误能否被修正,取决于错误信息写得是否清楚。物流接口要求快递公司编码为 shunfeng,模型按常识填了 SF:错误信息只写“参数错误”时 10 次都没有重新调用,其中 4 次编造了位置或送达时间,例如“目前包裹在上海市,预计 2 天内送达”;写明“carrier 取值错误:应为快递公司编码,顺丰为 shunfeng,中通为 zhongtong”时 10 次都改用 shunfeng 重新调用,全部答出了包裹在杭州转运中心(Qwen2.5-7B 实测,见[附录 A7](#a7-工具出错时-agent-的表现))。
错误信息写清楚之后,模型通常能够自行修正,例如:
@@ -2404,7 +2405,7 @@ checks:
- 效率:完成任务所需的步数、耗时和 Token 消耗;
- 部分得分:多步任务中完成了几步,例如查对了订单但退款失败,比一开始就失败要好。
由于采样的随机性,同一个任务运行多次,结果可能不同,只运行一次的成功率并不可靠。τ-bench 提出用 pass^k 衡量稳定性:同一个任务连续 k 次都成功的概率。它与常见的 pass@k(k 次中至少成功一次)正好相反,假设单次成功率为 90%,pass@8 接近 100%,pass^8 只有 0.9<sup>8</sup> ≈ 43%。面向用户的 Agent 每次都要做对,更应该关注 pass^k。该论文中 GPT-4o 使用函数调用时,零售场景的单次成功率约 61%,pass^8 降到约 25%;航空场景的单次成功率只有约 35%。
由于采样的随机性,同一个任务运行多次,结果可能不同,只运行一次的成功率并不可靠。τ-bench 提出用 pass^k 衡量稳定性:同一个任务连续 k 次都成功的概率。它与常见的 pass@k(k 次中至少成功一次)正好相反,假设每个任务的单次成功率都是 90%,pass@8 接近 100%,pass^8 只有 0.9<sup>8</sup> ≈ 43%。面向用户的 Agent 每次都要做对,更应该关注 pass^k。该论文中 GPT-4o 使用函数调用时,零售场景的单次成功率约 61%,pass^8 不到 25%;航空场景的单次成功率只有约 35%。
#### 3. 模型裁判的偏差
@@ -2447,9 +2448,9 @@ checks:
选型时先按硬条件筛选:数据能否交给外部服务、许可是否允许商用(同一系列不同尺寸的许可也可能不同,例如 Qwen2.5 的 7B 用 Apache 2.0,3B 只允许研究和评估,以模型发布页的许可为准),上下文和输出长度是否够用,是否支持需要的工具调用和结构化输出;再在业务评测集上比较剩下几个模型的效果、延迟和每次任务的费用。
服务商的模型名还可能改指新的模型,旧模型也会下线,例如 DeepSeek 的 deepseek-chat 先后对应过 11 个底层模型,阿里云百炼的正式版模型在启动下线后 3 个月停止服务。服务商提供固定版本的模型名(例如带日期的快照)时,生产环境尽量用它,换模型前在同一批用例上逐条对比(以各服务商的最新文档为准)。
服务商的模型名还可能改指新的模型,旧模型也会下线,例如 DeepSeek 的 deepseek-chat 在更新日志中先后升级过 11 次,2026-07-24 起停用,阿里云百炼的正式版模型在启动下线后 3 个月停止服务。服务商提供固定版本的模型名(例如带日期的快照)时,生产环境尽量用它,换模型前在同一批用例上逐条对比(以各服务商的最新文档为准)。
上线后关注的指标:
上线后关注的指标,新版本按用户灰度时也用它们与旧版本对比,见[提示词](#提示词):
- 效果:任务完成率、转人工率、用户重复提问或者改口的比例、满意度和差评;
- 过程:工具调用的错误率、平均步数、触发最大步数和重试上限的次数;
@@ -2463,7 +2464,7 @@ checks:
### 流式输出
生成一段长回答可能需要十几秒,流式输出让用户在第一个 Token 生成后就能看到内容。大模型接口通常使用服务器发送事件(Server-Sent Events, SSE)返回结果:响应的 Content-Type 为 text/event-stream,连接保持打开,服务端每生成一段内容就写入一条事件。
生成一段长回答可能需要十几秒。模型逐个生成 Token(见[自回归生成与 KV Cache](#自回归生成与-kv-cache)),流式输出让用户在第一个 Token 生成后就能看到内容。大模型接口通常使用服务器发送事件(Server-Sent Events, SSE)返回结果:响应的 Content-Type 为 text/event-stream,连接保持打开,服务端每生成一段内容就写入一条事件。
#### 1. SSE 的格式
@@ -2547,7 +2548,7 @@ LangGraph 等框架也提供类似的机制,按节点输出状态的更新或
#### 3. 生产环境中的注意事项
- Nginx 等反向代理默认会缓冲上游的响应,流式输出变成了一次性输出,需要关闭缓冲,例如在响应首部中加上 X-Accel-Buffering: no;
- 网关和负载均衡的读超时要大于最长的生成时间;
- 网关和负载均衡的超时按它的计时方式设置:Nginx 的 proxy_read_timeout 计的是两次读之间的间隔,要大于两段输出之间最长的停顿(例如首 Token 之前的排队),或者靠心跳保持;按整个响应计时的超时(例如 Envoy 的路由超时,默认 15 秒)要对流式接口关闭,或者大于最长的生成时间;
- 不支持续传时,用户关闭页面、连接断开后要及时取消对模型的请求,否则仍在消耗 Token,但断开能否停止生成和计费取决于服务商,例如 OpenRouter 的文档写明,非流式请求或不支持取消的服务商会继续处理并按完整的回答计费,所以还要用 max_tokens 限制输出的上限;
- 网络抖动导致断线时,模型的生成无法从中途重新开始。需要续传时,让生成任务与连接解耦:生成的内容按会话和事件编号写入 Redis 等缓存,客户端带着 Last-Event-ID 重连后,先从缓存中补发之后的事件,再继续推送新的内容,超时没有重连再取消生成。这时断开连接不等于停止生成,“停止”按钮要调用单独的接口;补发缓存和开始订阅新事件之间产生的事件要一并补上,否则会漏;生成中的增量先写缓存,避免每个 Token 都写数据库,正常结束时保存完整的回答,停止时保存已经生成的部分并标记为未完成;
- Agent 任务断线后通常继续执行到当前步骤结束,已经发起的退款这类有副作用的工具调用不能中途放弃,结果写入缓存,等客户端重连后补发;
@@ -2582,11 +2583,11 @@ LangGraph 等框架也提供类似的机制,按节点输出状态的更新或
这里按关闭思考模式计算,输出只有回答本身。deepseek-flash 默认开启思考模式,思维链也按输出计费,例如每次调用思考 1000 个 Token,3 次调用仅思维链就约 2.4 分,是上面前缀全部命中时的近 30 倍;带工具调用时,之前轮次的思维链还要回传,计入后面请求的输入。
这个例子的工具和提示词都很短。实际的 Agent 往往有几千 Token 的系统提示词和工具定义,每一步还会加入大段的工具结果。假设系统提示词和工具定义共 5000 个 Token,每一步新增 2000 个 Token,第 10 步的输入是 2.3 万个 Token,但 10 步累计的输入达到 14 万个 Token:
这个例子的工具和提示词都很短。实际的 Agent 往往有几千 Token 的系统提示词和工具定义,每一步还会加入大段的工具结果。假设系统提示词和工具定义共 5000 个 Token,每一步输出 200 个 Token,连同工具结果使下一步的输入增加 2000 个 Token,第 10 步的输入是 2.3 万个 Token,但 10 步累计的输入达到 14 万个 Token:
<div align="center"> <img src="pics/agent-token-cost.png" width="760px"/> </div><br>
每一步的输入都以上一步的输入和输出为前缀,88% 的输入可以命中缓存,费用从 0.296 元降到 0.053 元。输入随步数线性增长,累计的输入随步数平方增长,所以步数多的任务更依赖缓存,也更需要压缩上下文。
每一步的输入都以上一步的输入和输出为前缀,第 1 步的系统提示词和工具定义也能命中其它请求留下的缓存,累计 88% 的输入可以命中缓存,费用从 0.296 元降到 0.053 元。输入随步数线性增长,累计的输入随步数平方增长,所以步数多的任务更依赖缓存,也更需要压缩上下文。
#### 3. 让前缀缓存命中
@@ -2607,7 +2608,7 @@ LangGraph 等框架也提供类似的机制,按节点输出状态的更新或
前缀缓存降低的是单价,减少 Token 的数量要从上下文和输出两头入手:
- 控制工具返回的内容:工具默认返回摘要或者片段和文档编号,模型判断需要细节时再调用工具读取全文。例如检索返回 5 个片段约 1500 个 Token,把 5 篇文档的全文都放进去约 3 万个 Token,后者每一次调用的输入费用是前者的 20 倍,而且后面的每一步都要带着它;
- 控制工具返回的内容:工具默认返回摘要或者片段和文档编号,模型判断需要细节时再调用工具读取全文。例如检索返回 5 个片段约 1500 个 Token,把 5 篇文档的全文都放进去约 3 万个 Token,这部分输入的费用后者是前者的 20 倍,而且后面的每一步都要带着它;
- 限制输出长度:设置 max_tokens,要求回答简洁。以上面的 deepseek-flash 为例,输出的单价是未命中缓存的输入的 4 倍;
- 按难度选择模型:先用小模型判断问题的类型,查物流、改地址这类简单问题由小模型完成,复杂的投诉交给大模型。路由会分错,需要在评测集上确认整体效果没有下降。
@@ -2635,7 +2636,7 @@ Token 消耗增长过快时,先按步骤和工具汇总每一次调用的输
#### 1. 批处理:用延迟换吞吐
解码阶段每生成一个 Token,都要把全部权重从显存中读一遍,而计算量很小,速度主要受显存带宽限制。例如 A100 80GB 的显存带宽为 2039 GB/s,Qwen2.5-7B 的 BF16 权重约 152 亿字节,每一步至少需要 7.5 毫秒,单个请求每秒最多生成约 134 个 Token。
解码阶段每生成一个 Token,都要把全部权重从显存中读一遍,而计算量很小,速度主要受显存带宽限制。例如 A100 80GB SXM 的显存带宽为 2039 GB/s,Qwen2.5-7B 的 BF16 权重约 152 亿字节,每一步至少需要 7.5 毫秒,单个请求每秒最多生成约 134 个 Token。
预填充则不同,读一遍权重就能处理全部输入,每个 Token 要做约 13 GFLOP 的矩阵乘法(各层线性权重约 65 亿个参数,每个参数一次乘加;输出层只为最后一个 Token 计算,忽略不计)。输入越长,计算越多,读权重的时间却不变,所以长输入的预填充受算力限制。
@@ -2680,13 +2681,13 @@ vLLM 的调度器维护运行和等待两个队列。每一步处理的 Token
128 56 GB 70.2 GB
```
vLLM 默认使用 92% 的显存(--gpu-memory-utilization)。在 24 GB 的显卡上,扣除权重后剩不到 7.9 GB,再扣除激活值等运行时开销,同时只能处理十几个满 8K 的请求;80 GB 的显卡上可以处理 100 多个。KV Cache 不够时,vLLM 抢占最晚加入的请求:释放它的 KV Cache,放回等待队列的最前面,之后重新做预填充,延迟明显增加,监控中的抢占次数(Prometheus 中的 vllm:num_preemptions_total)持续增长。想用同样的显卡服务更多请求,可以减小最大上下文长度、使用更多显卡,或者对权重和 KV Cache 进行[量化](#量化)。
vLLM 0.32 默认使用 92% 的显存(--gpu-memory-utilization)。在 24 GB 的显卡上,扣除权重后剩不到 7.9 GB,再扣除激活值等运行时开销,同时只能处理十几个满 8K 的请求;80 GB 的显卡上可以处理 100 多个。KV Cache 不够时,vLLM 抢占最晚加入的请求:释放它的 KV Cache,放回等待队列的最前面,之后重新做预填充,延迟明显增加,监控中的抢占次数(Prometheus 中的 vllm:num_preemptions_total)持续增长。想用同样的显卡服务更多请求,可以减小最大上下文长度、使用更多显卡,或者对权重和 KV Cache 进行[量化](#量化)。
模型一张卡放不下时用张量并行,把每层的权重矩阵切到多张卡上,每层的注意力和前馈网络算完后各要在卡间做一次 all-reduce 汇总结果,所以一般只在 NVLink 高速互联的一台机器内使用,跨机器时再按层切分(流水线并行)。
#### 4. PagedAttention
请求的实际长度事先不知道。早期的推理系统按最大长度为每个请求预留一段连续的显存,请求实际只用了其中一部分,剩下的空着也不能给别的请求使用。vLLM 的论文统计,这些系统中真正用来存放 KV Cache 的显存只有 20.4%~38.2%。
请求的实际长度事先不知道。早期的推理系统按最大长度为每个请求预留一段连续的显存,请求实际只用了其中一部分,剩下的空着也不能给别的请求使用。vLLM 的论文统计,这些系统为 KV Cache 分配的显存中,真正存放了 K、V 的只有 20.4%(按最大长度预留)~38.2%(假设事先知道输出长度)。
PagedAttention 借鉴操作系统的[分页](计算机操作系统%20-%20内存管理.md#分页系统地址映射),把 KV Cache 切成固定大小的块(vLLM 默认每块 16 个 Token),生成到需要时才分配一块,用块表记录每个请求的块在显存中的位置,浪费的只有每个请求最后一块中没写满的部分:
@@ -2793,7 +2794,9 @@ Agent 的一次请求记为一条链路(trace),以这次 Agent 调用为
```text
invoke_agent 客服 Agent 会话 ID
├─ chat deepseek-flash 输入、输出的 Token 数,结束原因为 tool_calls
├─ execute_tool get_logistics 耗时、是否出错,开启后还记录参数 order_id = 1024
├─ execute_tool get_order 耗时、是否出错,开启后还记录参数 order_id = 1024
├─ chat deepseek-flash 输入、输出的 Token 数,结束原因为 tool_calls
├─ execute_tool get_logistics 耗时、是否出错,开启后还记录参数 tracking_no = SF1234567
└─ chat deepseek-flash 输入、输出的 Token 数,结束原因为 stop
```
@@ -2819,7 +2822,7 @@ OpenTelemetry 的 GenAI 语义约定为这类 span 定义了 invoke_agent、chat
- 工具按最小权限设计,当前任务用不到的工具不提供,权限在代码中按当前用户校验,而不是依靠模型遵守提示词;
- 删除数据、转账、对外发送信息这类高风险操作需要人工确认;
- 模型的输出同样不可信,显示到页面之前要转义,防止 [跨站脚本攻击](攻击技术.md#一跨站脚本攻击),用于查询数据库时要使用参数化查询;
- 模型直接生成整条 SQL 时(例如用自然语言查询数据),不能只靠参数化查询,要在数据库一侧限制:用只能 SELECT 少数视图的账号执行,并设置执行超时和返回行数的上限,不要依赖按关键字检查 SQL 或者会话自己就能改回的只读设置(MySQL 8.0 实测,见[附录 A33](#a33-模型生成-sql-的权限限制));
- 模型直接生成整条 SQL 时(例如用自然语言查询数据),不能只靠参数化查询,要在数据库一侧限制:用只能 SELECT 少数视图的账号执行;执行超时和返回行数的上限由应用在执行时设置(例如 JDBC 的 setQueryTimeout、setMaxRows),不要依赖按关键字检查 SQL,也不要依赖只读事务、max_execution_time 这类会话自己就能改回的设置(MySQL 8.0 实测,见[附录 A33](#a33-模型生成-sql-的权限限制));
- 不要在提示词中放入密钥等敏感信息,提示词可能被诱导泄露。
以客服 Agent 为例,用户身份取自登录会话,不作为工具参数让模型填写,get_order 在代码中检查订单是否属于当前用户,模型即使被诱导传入别人的订单号,也查不到数据。退款工具只生成一条待确认的申请,前端展示金额和订单,用户点击确认后由普通的业务接口执行,模型自己无法完成退款。
@@ -2828,7 +2831,7 @@ OpenTelemetry 的 GenAI 语义约定为这类 span 定义了 invoke_agent、chat
### 设计一个客服 Agent
“设计一个智能客服 Agent”这类题要把前面的机制组合成一个能上线的系统,下面仍以前文的电商客服为例,通用的答题顺序见[系统设计题的思路](系统设计基础.md#十三系统设计题的思路)。
“设计一个智能客服 Agent”这类题要把前面的机制组合成一个能上线的系统,下面仍以前文的电商客服为例,通用的答题顺序见[系统设计题的思路](系统设计基础.md#十三系统设计题的思路);不限定场景、只问 Agent 由哪些模块组成时,见 [Agent 是什么](#agent-是什么)中的组成和 Harness 的[组成](#1-组成)。
#### 1. 需求和约束
@@ -2850,7 +2853,7 @@ OpenTelemetry 的 GenAI 语义约定为这类 span 定义了 invoke_agent、chat
- 接入层:从登录会话中取出 user_id,工具都用它鉴权,不作为参数让模型填写,见[限制模型能造成的后果](#2-限制模型能造成的后果);
- 意图路由:退款、改地址这类涉及资金、步骤固定的请求交给工作流,咨询类交给 Agent,置信度低时反问澄清,见[意图识别与路由](#意图识别与路由);
- 工作流:退款由代码按校验、生成申请、用户确认、执行的顺序处理,模型只负责从对话中提取订单号和原因,见 [Agent 与工作流](#agent-与工作流);
- Agent:一个 ReAct 循环,工具有查询订单、查询物流、检索知识库和创建工单,限制最大步数;
- Agent:一个 ReAct 循环,工具有查询订单、查询物流、检索知识库和创建工单,限制最大步数,工具超时和出错的处理见[容错](#1-容错);
- 知识库:退换货政策和商品资料切片后建立索引,用混合检索加重排,见[检索增强生成](#三检索增强生成);
- 短期记忆:摘要、最近几轮和任务状态(例如当前在处理的订单)存放在 Redis 中,见[短期记忆](#1-短期记忆)。
@@ -2918,7 +2921,7 @@ E1024:n = 1,IDF = 0.981,词频部分 = 0.977,贡献 0.958
### A2 提示词对工具调用的影响
模型用 float16 加载到 MPS,按“订单 1024 到哪了?”运行 Agent 循环,最多 5 步,采样参数 temperature = 0.7、top_p = 0.9,每次用不同的随机种子。最终回答中出现“杭州”(物流工具返回的当前位置)记为成功:
模型用 float16 加载到 MPS,按“订单 1024 到哪了?”运行 Agent 循环,最多 5 步,采样参数 temperature = 0.7、top_p = 0.9,每次用不同的随机种子。两个工具的描述分别为“按订单号查询订单状态和运单号”和“按运单号查询物流的当前位置和预计送达时间”,比正文示例中 get_order 的描述少了使用时机。最终回答中出现“杭州”(物流工具返回的当前位置)记为成功:
```python
PROMPTS = {"A": "你是电商客服助手,回答要简短。",
@@ -3016,7 +3019,7 @@ EXTRACT = {
### A6 意图路由的三种做法
评测集是自己编写的 60 条电商客服消息,物流、退款、改地址、商品咨询、其它 5 个类别各 12 条,其中 10 条含有其它类别的关键词。Embedding 相似度用 bge-small-zh-v1.5 的 [CLS] 向量,每类 6 条示例(不在评测集中)取平均作为类中心,按余弦相似度最近的类中心分类,置信度为相似度除以 0.05 后的 softmax。大模型用 float16 加载到 MPS,贪心解码,置信度取第一个 Token 在 5 个类别首 Token 上归一化后的概率(5 个类别名的首 Token 互不相同):
评测集是自己编写的 60 条电商客服消息,物流、退款、改地址、商品咨询、其它 5 个类别各 12 条,其中 10 条含有其它类别的关键词。Embedding 相似度用 bge-small-zh-v1.5 的 [CLS] 向量,每类 6 条示例(不在评测集中)取平均作为类中心,按余弦相似度最近的类中心分类,置信度为相似度除以 0.05 后的 softmax。大模型用 float16 加载到 MPS,贪心解码,预测的类别和置信度都取第一个 Token 在 5 个类别首 Token 上归一化后概率最高的一类及其概率,不解析生成的文本(5 个类别名的首 Token 互不相同):
```python
RULES = [("退款", r"退款|退货|退钱|售后|取消订单|退差价|七天无理由"),
@@ -3097,6 +3100,8 @@ msgs.append({"role": "tool", "name": c["name"], "content": json.dumps(r, ensure_
seed=0:您的包裹目前位于杭州转运中心,预计明天送达。谢谢!
```
参数错误、笼统提示的 10 次中,seed 1、2、4、6 给出了工具没有返回的位置或送达时间(seed 4 与 seed 1 的回答几乎相同),其余 6 次回答暂时查不到位置,seed 7 是其中一例。
另外做过一组参数校验更宽松的对照:carrier 取值为 SF 即可,模型 10 次都在第一次调用时主动填写了 carrier = "SF",没有触发错误。
### A8 LangGraph 的 checkpoint 与人工确认
@@ -3252,7 +3257,7 @@ y= 406 x= 507 conf=0.50 600 元
y=1155 x= 735 conf=0.50 第12页
```
版面还原的规则:y 坐标相差不超过 12 像素的文字块归为一行,一行有多个块的作为表格行;顶部和底部 10% 的区域作为页眉页脚,从中提取页码;匹配“第 N 章”和“N.N ”的行作为二级和三级标题;不以句号结尾的行与下一行合并。输出见正文,提取的元数据为 {"doc": "员工手册(2026 版)", "page": 12}。
版面还原的规则:y 坐标相差不超过 12 像素的文字块归为一行,一行有多个块的作为表格行;顶部和底部 10% 的区域作为页眉页脚,从中提取页码;匹配“第 N 章”和“N.N ”的行作为二级和三级标题,并在“第 N 章”的数字两边补上空格;不以句号结尾的行与下一行合并。输出见正文,元数据为 {"doc": "员工手册(2026 版)", "page": 12}(页码从页脚提取,文档名直接指定)。
### A12 切片方式、Top-K 与相似度阈值
@@ -3289,7 +3294,7 @@ top3 同时含 2023 版和 2026 版同一小节的问题数: 38
加前缀: Recall@1 0.850 Recall@3 1.000
```
递归切分和语义切分沿用上面的知识库、问题和命中判定。递归切分用 LangChain text-splitters 的 RecursiveCharacterTextSplitter(GitHub master 分支的源码,2026-10-30),直接切 Markdown 原文,重叠为 0;“加中文标点”的分隔符为 `["\n\n", "\n", "。", ";", ",", ""]`,keep_separator="end"。语义切分按“。”“;”和换行分句,相邻两句的余弦距离超过该文档全部相邻距离的 p 分位数时切开(与 LangChain SemanticChunker 的 percentile 方式相同,不合并前后句):
递归切分和语义切分沿用上面的知识库、问题和命中判定。递归切分用 langchain-text-splitters 1.1.3 的 RecursiveCharacterTextSplitter,直接切 Markdown 原文,重叠为 0;“加中文标点”的分隔符为 `["\n\n", "\n", "。", ";", ",", ""]`,keep_separator="end"。语义切分按“。”“;”和换行分句,相邻两句的余弦距离超过该文档全部相邻距离的 p 分位数时切开(与 LangChain SemanticChunker 的 percentile 方式相同,不合并前后句):
```python
v = emb(sents); dist = 1 - (v[:-1] * v[1:]).sum(1); th = np.percentile(dist, p)
@@ -3354,7 +3359,7 @@ IVF-PQ nprobe=16 + 重算前 100: Recall@10 0.847
### A14 忠实度与答案相关性
按 RAGAS 论文的方法实现:Qwen2.5-7B-Instruct(float16,MPS,贪心解码)先把回答拆成陈述,再逐条判断能否从资料中推出;然后根据回答反推 3 个问题,用 bge-small-zh-v1.5 计算它们与原问题的余弦相似度:
按 RAGAS 论文的思路实现(判断时只要求回答“是”或“否”,没有像论文那样先写出理由):Qwen2.5-7B-Instruct(float16,MPS,贪心解码)先把回答拆成陈述,再逐条判断能否从资料中推出;然后根据回答反推 3 个问题,用 bge-small-zh-v1.5 计算它们与原问题的余弦相似度:
```python
stmts = as_json(chat(f"把下面的回答拆成若干条独立的陈述,每条只包含一个事实。只输出 JSON 字符串数组。\n问题:{Q}\n回答:{a}"))
@@ -3489,7 +3494,7 @@ gate_proj 对称 8.25% 非对称 6.93% 非对称 + 缩放(α=0.2) 6.78%
down_proj 对称 10.99% 非对称 9.16% 非对称 + 缩放(α=0.3) 9.10%
```
困惑度:28 层中的全部线性层(q、k、v、o、gate、up、down)分别伪量化,嵌入层和输出层保持 FP16;文本为本仓库 MySQL.md 正文的前 12000 个字符(去掉图片和代码块标记,6653 个 Token),每 1024 个 Token 一段计算交叉熵;再用贪心解码回答“用一句话解释 MySQL 的回表是什么。”:
困惑度:28 层中的全部线性层(q、k、v、o、gate、up、down)分别伪量化(int4-group128 为每 128 个一组、带零点的非对称量化,其余为对称量化),嵌入层和输出层保持 FP16;文本为本仓库 MySQL.md 正文的前 12000 个字符(去掉图片和代码块标记,6653 个 Token),每 1024 个 Token 一段计算交叉熵;再用贪心解码回答“用一句话解释 MySQL 的回表是什么。”:
```text
fp16 困惑度 6.231 回答:MySQL的回表是指在执行查询时,已经通过索引找到部分条件匹配的记录,但还需要再次访问数据表(非索引页)以获取剩余列的数据。
@@ -3514,7 +3519,7 @@ explicit = lambda tracking_no: {"location": "杭州转运中心", "location_upda
```text
场景一 用户问“我的包裹到哪了?”(没有订单号)
只写“你是电商客服助手,回答要简短。”:10 次都没有调用工具,回答“请提供您的运单号,我帮您查询。”
只写“你是电商客服助手,回答要简短。”:10 次都没有调用工具,都请用户提供运单号,例如“请提供您的运单号,我帮您查询。”
加上“工具参数只能来自用户消息或工具结果,缺少订单号时先询问用户”:10 次都回答“请提供您的订单号”
(只写身份时,订单 1024 的问题中模型查到运单号就直接回答,没有调用物流工具,与附录 A2 一致,所以场景二、三改用写明流程的 FLOW)
场景二 物流接口超时,问“订单 1024 到哪了?”
@@ -3525,7 +3530,7 @@ explicit = lambda tracking_no: {"location": "杭州转运中心", "location_upda
当前您的包裹位于杭州转运中心,预计今天送达。……
您的包裹当前位于杭州转运中心,预计将在24小时内送达。谢谢!
当前包裹位于杭州转运中心,预计送达时间为2026年10月26日09点12分左右,请耐心等待。
HONEST:9 次给出了送达时间,其中 8 次为“预计送达时间为2026年10月26日09:12”;1 次回答“预计送达时间暂时无法确定”
HONEST:9 次给出了送达时间,都取自 updated_at,其中 8 次为“预计送达时间为2026年10月26日09:12”,1 次为“……09点12分左右”;1 次回答“预计送达时间暂时无法确定”
场景三' 物流结果改为 {"location": "杭州转运中心", "location_updated_at": "2026-10-26 09:12", "eta": null, "eta_note": "承运商暂未提供预计送达时间"}
FLOW:10 次都没有给出送达时间,例如“当前您的包裹位于杭州转运中心,承运商暂未提供预计送达时间。”
HONEST:10 次都没有给出送达时间
@@ -3583,6 +3588,8 @@ batch TTFT(ms) TPOT(ms) 总耗时(s) 吞吐(tok/s)
输出前 40 个 Token: '退货运费的承担通常取决于商品销售的具体条款和条件,以及买家和卖家之间的协议。在大多数情况下,退货运费是由买家承担的。这是因为买家在购买商品时,'
```
batch 为 2~8 时 TPOT 随 batch 近似成倍增加、吞吐几乎不变,到 16 时 TPOT 反而下降,原因没有查明,正文的配图只取 batch 为 1、16、32、64 的结果。
### A22 模型输出 JSON 的修复、校验与重试
Qwen2.5-3B-Instruct 以 float16 加载到 MPS,系统提示词要求从客服消息中提取 order_id、intent(4 个枚举值之一)、amount 三个字段并以 JSON 格式输出,没有要求“只输出 JSON”。20 条消息各采样 2 次(temperature = 0.7、top_p = 0.9)。修复指去掉代码块标记、截取第一个 { 到最后一个 };Schema 要求三个字段齐全、order_id 为纯数字字符串或 null、amount 为数字或 null、不允许其它字段。校验失败时把原输出和错误信息作为下一轮消息发回,重试 1 次。
@@ -3620,6 +3627,12 @@ msgs += [{"role": "assistant", "content": raw},
环境:Python 3.13.7,PyTorch 2.8.0(CPU)。冻结一个 64 × 64 的权重 W,用 r = 4 的 LoRA 拟合一个秩为 4 的变化量,Adam、学习率 0.01、300 步,比较三种初始化:B = 0、A 随机(PEFT 的默认方式);A = 0、B 随机;两者都为 0:
```python
torch.manual_seed(0)
d, r, n = 64, 4, 512
W = torch.randn(d, d) / d ** 0.5 # 冻结的原始权重
delta = (torch.randn(d, r) @ torch.randn(r, d)) * 0.1 # 目标:一个秩为 4 的变化量
X = torch.randn(n, d); Y = X @ (W + delta).T
def run(init, steps=300, lr=1e-2):
A = torch.zeros(r, d); B = torch.zeros(d, r)
if init == "B=0": torch.nn.init.kaiming_uniform_(A, a=5 ** 0.5) # 与 PEFT 默认相同
@@ -3783,7 +3796,10 @@ def enc(texts, pool="cls"):
questions = ["怎么申请年假", "错误码 E1024 是什么意思", "出差住宿标准是多少"]
docs = ["年假需提前 3 个工作日在 OA 系统提交申请", "错误码 E1024:库存不足", "北京、上海每晚住宿上限 600 元"]
sim = enc(questions) @ enc(docs).T
loss = F.cross_entropy(sim / tau, torch.arange(3), reduction="none")
for tau in (1.0, 0.05):
loss = F.cross_entropy(sim / tau, torch.arange(3), reduction="none")
p_diag = F.softmax(sim / tau, dim=1).diag() # 每个问题对应正确切片的概率
print("tau", tau, "loss per row", loss.numpy().round(3), "mean %.3f" % loss.mean().item(), "p_diag", p_diag.numpy().round(3))
```
```text
@@ -3801,7 +3817,7 @@ tau 0.05 loss per row [0.002 0. 0.01 ] mean 0.004 p_diag [0.998 1. 0.99 ]
### A28 Spring AI 的对话记忆与工具调用
Spring AI 2.0.2(spring-ai-client-chat),JDK 21。ChatClient 加上 MessageChatMemoryAdvisor,记忆使用默认参数的 MessageWindowChatMemory;桩模型第 1 次调用返回调用 getOrder 的请求,之后返回文本,并打印每次收到的消息。同一个会话先问“订单 1024 到哪了?”,再说“谢谢”:
Spring AI 2.0.2(spring-ai-client-chat),JDK 21。ChatClient 加上 MessageChatMemoryAdvisor,记忆使用默认参数的 MessageWindowChatMemory;桩模型第 1 次调用返回调用 getOrder 的请求,之后返回文本,并打印每次收到的消息(工具结果只打印占位文字 tool result)。同一个会话先问“订单 1024 到哪了?”,再说“谢谢”:
```java
ChatMemory memory = MessageWindowChatMemory.builder().build();
@@ -3865,7 +3881,7 @@ M = 32,最高层 4,各层节点数 L0:123899 L1:3959 L2:122 L3:4 L4:1
干扰 0 条: R@1 0.850 R@3 0.975 R@10 1.000 前 3 中干扰文本占 0.000
干扰 10000 条: R@1 0.500 R@3 0.850 R@10 0.975 前 3 中干扰文本占 0.333
干扰 124899 条: R@1 0.275 R@3 0.575 R@10 0.675 前 3 中干扰文本占 0.617
年假可以只请半天吗? 正确切片排第 3,相似度 0.659;前 3:
年假可以只请半天吗? 正确切片排第 3(不加干扰时排第 1),相似度 0.659;前 3:
0.798 [干扰] 是否可以请长假?
0.679 [干扰] 下学期是否也可以继续请假实习?
0.659 员工手册(2026 版) > 第 3 章 年假 > 3.2 申请 / 年假以半天为最小单位,可以分段使用……
@@ -3908,7 +3924,7 @@ for r, j in enumerate(B[i]): sc[j] += w / (61 + r)
加权 RRF(BM25 一路乘以 w)
干扰 0 条 w=1.0: R@3 0.950 w=0.5: R@3 1.000 w=0.3: R@3 1.000 w=0: R@3 0.975
干扰 10000 条 w=1.0: R@3 0.675 w=0.5: R@3 0.725 w=0.3: R@3 0.725 w=0: R@3 0.850
重排耗时:随机 2000 条干扰文本(批大小 32)28.2 s,每条 14.1 ms,外推到 124951 条约 29 分钟
重排耗时:随机 2000 条干扰文本(批大小 32)两次测量为 28.2 s 和 16.1 s,每条 14.1 ms 和 8.1 ms,外推到 124951 条约 29 分钟和 17 分钟
```
干扰文本是短问句,与口语化的问题共用很多二元词(“几天”“怎么办”),BM25 又偏向短文本,所以干扰越多 BM25 越差,等权融合把向量检索的结果也拉低了;问题中的编号、专有名词较多时结果会不同。
@@ -3945,7 +3961,7 @@ for name, scale in [("不缩放", 1), ("除以 √d", np.sqrt(d)), ("除以 d",
### A32 语义缓存的相似度
Python 3.13、sentence-transformers 6.2,模型 BAAI/bge-small-zh-v1.5(Apple M1 Pro,CPU)。向量归一化后点积即余弦相似度:
Python 3.13、sentence-transformers 6.2,模型 BAAI/bge-small-zh-v1.5(Apple M1 Pro,CPU)。向量归一化后点积即余弦相似度,输出的最后一列是人工标注的两句答案是否相同:
```python
from sentence_transformers import SentenceTransformer
@@ -3989,9 +4005,13 @@ OK SELECT COUNT(*) FROM orders -> ((1,),)
OK SET SESSION TRANSACTION READ ONLY -> []
OK SET SESSION TRANSACTION READ WRITE -> []
OK SELECT /*+ MAX_EXECUTION_TIME(100) */ SLEEP(1) FROM v_orders LIMIT 1 -> ((1,),)
OK SET SESSION max_execution_time = 100 -> []
OK SELECT SLEEP(1) FROM v_orders LIMIT 1 -> ((1,),) 耗时 0.11 s
OK SET SESSION max_execution_time = 0 -> []
OK SELECT SLEEP(1) FROM v_orders LIMIT 1 -> ((0,),) 耗时 1.01 s
```
前三条和最后三条由 bi 执行:bi 读不到原表的手机号,也不能删除;它可以把自己的会话设为只读,再改回读写。中间两条由 root 执行,说明以 WITH 开头的语句也可以删除数据,只检查语句开头的关键字拦不住。最后一条的 SLEEP 返回 1,表示执行到 100 毫秒时被中断。
第 4、5 条由 root 执行,说明以 WITH 开头的语句也可以删除数据,只检查语句开头的关键字拦不住;其余都由 bi 执行。bi 读不到原表的手机号,也不能删除;它可以把自己的会话设为只读,再改回读写。用提示 MAX_EXECUTION_TIME(100) 时 SLEEP 返回 1,表示执行到 100 毫秒时被中断;会话级的 max_execution_time 同样能被 bi 自己改回 0,之后 SLEEP(1) 跑满 1 秒。
### A34 Text2SQL 的口径与语义层
@@ -4126,7 +4146,7 @@ C 语义层:6/6
- [ArchUnit User Guide](https://www.archunit.org/userguide/html/000_Index.html)
- [Claude Docs: Tool Search Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)
- [Claude Agent SDK: Scale to many tools with tool search](https://code.claude.com/docs/en/agent-sdk/tool-search)
- [OpenTelemetry: Semantic conventions for generative AI systems](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
- [OpenTelemetry GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions-genai)
- [How We Built Our Multi-Agent Research System](https://www.anthropic.com/engineering/multi-agent-research-system)
- [DeepSeek API 文档:Tool Calls](https://api-docs.deepseek.com/zh-cn/guides/tool_calls)
- [Qwen2.5-7B-Instruct 对话模板](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct/blob/main/tokenizer_config.json)