Agent开发完全实战指南(六)RAG检索增强

上一篇结尾留了个尾巴:关键词检索认不出"付款失败"和"支付异常"、"内存溢出"和"OOM"是一回事。因为它只会抠字面,不懂语义。

这一篇我们把检索升级成真正懂语义的版本,靠的是两个东西:embedding(把文字变成向量) 和 RAG(检索增强生成)。

RAG 的一句话概括:在让 LLM 回答之前,先从外部知识库里检索出最相关的内容,塞进上下文——让模型"开卷考试",而不是靠记忆瞎编。 而 embedding 是让检索"懂语义"的钥匙。

RAG 是记忆(第 05 篇)和知识落地的技术底座,也是目前生产 Agent 里用得最多的能力之一。


一、先搞懂 embedding:把文字变成一串数字

先说人话定义:embedding 就是把一段文字映射成一个高维向量(一串浮点数),语义越接近的文字,向量在空间里离得越近。

比如经过一个好的 embedding 模型:

关键洞察: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 用不同模型 向量不可比、检索全错 建库和查询必须用同一个模型

七、小结与下一篇

到这里,单个 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