Agent开发完全实战指南(六)RAG检索增强
上一篇结尾留了个尾巴:关键词检索认不出"付款失败"和"支付异常"、"内存溢出"和"OOM"是一回事。因为它只会抠字面,不懂语义。
这一篇我们把检索升级成真正懂语义的版本,靠的是两个东西:embedding(把文字变成向量) 和 RAG(检索增强生成)。
RAG 的一句话概括:在让 LLM 回答之前,先从外部知识库里检索出最相关的内容,塞进上下文——让模型"开卷考试",而不是靠记忆瞎编。 而 embedding 是让检索"懂语义"的钥匙。
RAG 是记忆(第 05 篇)和知识落地的技术底座,也是目前生产 Agent 里用得最多的能力之一。
一、先搞懂 embedding:把文字变成一串数字
先说人话定义:embedding 就是把一段文字映射成一个高维向量(一串浮点数),语义越接近的文字,向量在空间里离得越近。
比如经过一个好的 embedding 模型:
- "付款失败" →
[0.12, -0.45, 0.88, ...] - "支付异常" →
[0.13, -0.43, 0.86, ...](和上面很近) - "今天天气不错" →
[-0.91, 0.22, 0.05, ...](离得很远)
关键洞察:embedding 把"语义相似"变成了"几何距离相近"这个可以计算的问题。这就是机器能"理解"两句话意思相近的底层魔法。
那怎么算两个向量"近不近"?最常用的是余弦相似度(cosine similarity)——算两个向量夹角的余弦值,范围 -1 到 1,越接近 1 越相似:
// cosineSimilarity 计算两个向量的余弦相似度
func cosineSimilarity(a, b []float64) float64 {
var dot, normA, normB float64
for i := range a {
dot += a[i] * b[i]
normA += a[i] * a[i]
normB += b[i] * b[i]
}
return dot / (math.Sqrt(normA) * math.Sqrt(normB))
}
二、RAG 的完整流程
RAG 分两个阶段:离线建库 和 在线检索。
flowchart TD
subgraph 离线["离线:建立知识库"]
Doc[原始文档] --> Chunk[切分 chunking
切成小段]
Chunk --> Embed1[逐段 embedding
转成向量]
Embed1 --> DB[(向量库
存 文本+向量)]
end
subgraph 在线["在线:回答问题"]
Q[用户问题] --> Embed2[问题 embedding]
Embed2 --> Search[在向量库里
算余弦相似度检索 Top-K]
DB --> Search
Search --> Inject[把 Top-K 相关片段
注入上下文]
Inject --> LLM[LLM 基于检索内容作答]
end对照第 05 篇的关键词检索,唯一的升级就是:把"关键词重叠度"换成了"embedding 向量的余弦相似度"。 流程框架完全一样,但检索质量天差地别。
三、影响 RAG 效果的关键变量
RAG 不是接上就完事,几个参数直接决定效果好坏:
| 变量 | 说明 | 经验建议 |
|---|---|---|
| chunk 大小 | 文档切多大一段 | 太大→检索不精准、浪费上下文;太小→丢失语境。常见 200-500 字,按语义边界切更好 |
| embedding 模型 | 用哪个模型转向量 | 中文场景要选中文效果好的模型;维度越高不一定越好 |
| Top-K | 检索返回几条 | 太少→漏关键信息;太多→引入噪声。常见 3-5 |
| rerank(重排) | 对初步检索结果用更强的模型再排序 | 对精度要求高时加,能显著提升 |
| 混合检索 | 向量检索 + 关键词检索结合 | 兼顾语义和精确匹配(如专有名词、编号) |
关键洞察:RAG 最大的误区是把它当银弹。检索质量差 = 给模型注入噪声 = 结果更烂。所以「检索准不准」本身必须单独评测(第 08 篇),而不是接上就以为万事大吉。
四、动手:用真实 embedding 做语义检索
这一篇的代码会调用 embedding 接口(OpenAI 兼容的 /v1/embeddings),因为只有真实的 embedding 模型才能演示"语义匹配"。
4.1 调用 embedding 接口
type EmbeddingRequest struct {
Model string `json:"model"`
Input []string `json:"input"` // 支持一次转多段
}
type EmbeddingResponse struct {
Data []struct {
Embedding []float64 `json:"embedding"`
Index int `json:"index"`
} `json:"data"`
}
// embed 把多段文本批量转成向量
func embed(texts []string) ([][]float64, error) {
apiKey := os.Getenv("OPENAI_API_KEY")
baseURL := os.Getenv("OPENAI_BASE_URL")
if baseURL == "" {
baseURL = "https://api.openai.com/v1"
}
model := os.Getenv("EMBEDDING_MODEL")
if model == "" {
model = "text-embedding-3-small" // 默认模型,换成你网关支持的
}
buf, _ := json.Marshal(EmbeddingRequest{Model: model, Input: texts})
req, _ := http.NewRequest("POST", baseURL+"/embeddings", bytes.NewReader(buf))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var er EmbeddingResponse
if err := json.Unmarshal(body, &er); err != nil {
return nil, fmt.Errorf("解析失败: %v, 原始响应: %s", err, string(body))
}
// 按 index 排好序返回
vecs := make([][]float64, len(er.Data))
for _, d := range er.Data {
vecs[d.Index] = d.Embedding
}
return vecs, nil
}
4.2 一个最简向量库
type Document struct {
Text string
Vector []float64
}
type VectorStore struct {
docs []Document
}
// Index 把文档批量转向量并存入(离线建库)
func (s *VectorStore) Index(texts []string) error {
vecs, err := embed(texts)
if err != nil {
return err
}
for i, t := range texts {
s.docs = append(s.docs, Document{Text: t, Vector: vecs[i]})
}
return nil
}
// Search 检索与 query 最相似的 topK 段(在线检索)
func (s *VectorStore) Search(query string, topK int) []string {
qvec, err := embed([]string{query})
if err != nil || len(qvec) == 0 {
return nil
}
type scored struct {
text string
sim float64
}
var ranked []scored
for _, d := range s.docs {
ranked = append(ranked, scored{d.Text, cosineSimilarity(qvec[0], d.Vector)})
}
sort.Slice(ranked, func(i, j int) bool { return ranked[i].sim > ranked[j].sim })
var result []string
for i := 0; i < len(ranked) && i < topK; i++ {
result = append(result, ranked[i].text)
}
return result
}
4.3 见证语义检索
现在关键的一步:知识库里存的是"支付异常",我们用"付款失败"去查——关键词检索会得 0 分,向量检索却能命中:
func main() {
store := &VectorStore{}
store.Index([]string{
"支付异常排查:先检查第三方支付渠道回调是否正常,再看订单状态机是否卡住",
"数据库死锁通常由多个事务加锁顺序不一致导致,统一加锁顺序可解决",
"服务内存持续增长最终 OOM,多半是 goroutine 泄漏或未释放的缓存",
})
query := "用户反馈付款失败,怎么排查?" // 注意:库里没有"付款失败"这个词
hits := store.Search(query, 1)
fmt.Printf("问题:%s\n最相关知识:%s\n", query, hits[0])
}
预期输出:尽管字面不含"付款失败",它依然精准命中了"支付异常"那条。这就是语义检索相对关键词检索的降维打击。
完整代码见 code/06-rag/(需要配置支持 embeddings 的接口)。
4.4 把 RAG 变成 Agent 的一个工具
RAG 怎么和前几篇的 Agent 结合?最优雅的方式是把"检索知识库"做成一个工具(第 03 篇的套路),让 Agent 自己决定何时检索:
// 一个 search_knowledge 工具,Agent 需要背景知识时自己调用
Tool{
Type: "function",
Function: FunctionDefinition{
Name: "search_knowledge",
Description: "从内部运维知识库检索相关资料。当遇到不确定的问题、需要背景知识时使用。",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"query": map[string]any{"type": "string", "description": "要检索的问题或关键词"},
},
"required": []string{"query"},
},
},
}
这样 RAG 就无缝融入了 Agent 循环——它不再是写死的流程,而是模型可以按需调用的一种能力。
五、决策指南:要不要上 RAG,怎么上
| 你的处境 | 建议 |
|---|---|
| 有大量文档/知识库,问题答案藏在里面 | 上 RAG |
| 知识量小、固定 | 直接把知识写进系统提示,别上 RAG(过度设计) |
| 需要最新/私有数据 | RAG(或工具直接查源系统) |
| 精确匹配需求强(编号、专名) | 混合检索(向量 + 关键词) |
| 检索总是不准 | 先调 chunk 大小和 Top-K,再考虑加 rerank |
| 还没做检索质量评测 | 先补评测(第 08 篇),别盲目上线 |
六、常见坑速查
| 坑 | 后果 | 正确做法 |
|---|---|---|
| 把 RAG 当银弹 | 检索噪声反而拉低效果 | 检索质量要单独评测 |
| chunk 切太大 | 检索不精准、浪费上下文 | 按语义边界切,200-500 字 |
| chunk 切太小 | 丢失语境 | 适当重叠切分,保留上下文 |
| Top-K 设太大 | 注入噪声 | 从 3-5 起步调优 |
| 用错 embedding 模型 | 中文语义检索差 | 选中文效果好的模型 |
| query 和文档 embedding 用不同模型 | 向量不可比、检索全错 | 建库和查询必须用同一个模型 |
七、小结与下一篇
- embedding 把文字变成向量,让"语义相似"变成"距离相近"的可计算问题。
- RAG = 检索相关内容注入上下文,让模型"开卷考试"。
- 流程和第 05 篇一致,只是把关键词重叠换成了余弦相似度,检索质量质变。
- 关键变量:chunk 大小、embedding 模型、Top-K、rerank、混合检索。
- RAG 不是银弹,检索质量必须单独评测。
到这里,单个 Agent 的核心能力(循环、工具、上下文、记忆、知识)就齐了。但面对复杂任务,一个 Agent 会力不从心:工具太多、上下文太杂、要并行处理。怎么办?把大任务拆给多个各司其职的 Agent。
下一篇预告——《多 Agent 协作:编排、委派与并行》:我们会讲透 Orchestrator-Worker(编排者-执行者)、Routing(路由)、Handoff(交接)三种多 Agent 模式,并动手实现一个"主 Agent 拆任务、派多个子 Agent 并行执行再汇总"的系统。这也是第 04 篇上下文工程里"Isolate(隔离)"那一板斧的落地。
参考资料
| 资料 | 来源 |
|---|---|
| OpenAI Embeddings 指南 | platform.openai.com/docs/guides/embeddings |
| Retrieval-Augmented Generation(RAG 原始论文) | arxiv.org/abs/2005.11401 |
| What is RAG?(概念综述) | aws.amazon.com/what-is/retrieval-augmented-generation |
| pgvector(给 PostgreSQL 加向量检索能力) | github.com/pgvector/pgvector |