LangChain 构建 RAG Agent

前两篇我们已经介绍了 LangChain 的 RAG 基础，包括文档加载、文本切分、Embedding 向量化以及 Chroma 向量数据库。

本章节将这些组件组合起来，构建一个完整的 RAG Agent（检索增强智能体）。

与普通 RAG 不同，RAG Agent 可以将知识库检索封装为 Tool，由大语言模型判断什么时候需要搜索，再根据检索结果生成回答。

例如，用户询问菜鸟教程 RUNOOB 的课程信息时，Agent 可以先搜索知识库，再根据找到的资料回答。

本教程基于 LangChain 1.x，使用 DeepSeek 作为聊天模型，OpenAI 或阿里百炼作为 Embedding 模型，Chroma 作为向量数据库。

一、RAG Agent 是什么？

RAG Agent 是将 RAG 检索能力集成到 Agent 工具系统中的一种实现方式。

普通 RAG 的执行过程通常是固定的：

用户问题
    ↓
知识库检索
    ↓
检索到的文档
    ↓
大模型生成回答

而 RAG Agent 的执行过程是：

用户问题
    ↓
Agent 判断是否需要检索
    ↓
是否调用知识库工具？
    ├── 是 → Retriever → 返回相关文档
    │                       ↓
    │                 Agent 读取资料
    │                       ↓
    │                 生成最终回答
    │
    └── 否 → 直接生成回答

因此，RAG Agent 的关键在于：把 Retriever 包装成 Agent 可以调用的 Tool。

普通 RAG 与 RAG Agent 对比

注意：RAG Agent 不一定比普通 RAG 更准确。如果业务要求每个回答都必须先查阅知识库，2-step RAG 通常更容易保证这一流程。

二、环境准备

先安装本教程所需的 Python 包：

pip install -U langchain langchain-deepseek langchain-openai langchain-chroma langchain-text-splitters python-dotenv

主要组件：

配置 API Key

在项目目录下创建 .env：

DEEPSEEK_API_KEY=your_deepseek_api_key

# 使用阿里百炼 Embedding
DASHSCOPE_API_KEY=your_dashscope_api_key

# 使用 OpenAI Embedding 时配置
OPENAI_API_KEY=your_openai_api_key

聊天模型和 Embedding 模型可以来自不同服务商。

本教程的完整示例默认使用阿里百炼 Embedding，便于不使用 OpenAI API Key 的读者运行。

三、初始化 Embedding 模型

Embedding 用于把知识文档和用户查询转换成向量。

这里提供两种方案，选择其中一种即可。

方式一：OpenAI Embedding

text-embedding-3-small 默认输出 1536 维向量。

方式二：阿里百炼 Embedding

如果没有 OpenAI API Key，可以使用阿里百炼的 text-embedding-v4。

百炼提供 OpenAI 兼容接口，可以通过 OpenAIEmbeddings 调用。

使用默认设置时，text-embedding-v4 通常输出 1024 维向量。

这里的两个参数需要注意：

• check_embedding_ctx_length=False：避免 OpenAI 专用的 Token ID 预处理与百炼兼容接口发生冲突。
• chunk_size=10：限制 Embedding 批量请求的文本条数。

也可以参考：LangChain 阿里百炼配置教程。

重要：创建索引和执行检索时必须使用兼容的同一 Embedding 模型。不能把 OpenAI 和阿里百炼生成的向量混合到同一个已有集合中。

四、准备知识库文档

下面使用几条教学模拟资料，构建一个小型编程课程知识库。

这些资料是为了演示 RAG 流程而编写的测试数据，不代表真实课程数量、网站历史或会员服务信息。

实例：创建 Document

这里使用 Document 而不是普通字符串，是因为 Document 可以保存来源元数据。

后续检索时，可以通过 metadata 获取资料标题和来源标识。

五、切分文档

对于长篇教程、PDF 或 Markdown，通常需要先切分成较小的 Chunk。

可以使用 RecursiveCharacterTextSplitter。

实例：切分中文资料

由于当前演示文档很短，每个 Document 通常仍然只有一个 Chunk。

实际项目中，可以通过 Document Loader 加载大量真实资料，再使用相同的方法切分。

注意：chunk_size 是目标字符长度，不保证每个 Chunk 都恰好为 300 字符。

六、创建 Chroma 向量数据库

接下来将 Chunk 转换为向量，存入 Chroma。

这里使用本地持久化目录，避免程序重启后丢失向量数据。

实例：创建向量存储

主要参数：

添加文档：

这里使用内容相关的固定 ID，方便识别文档。

但如果原始文档发生修改，仍然需要删除旧版本的片段并重新建立索引，不能依赖固定 ID 自动完成整个文档同步过程。

七、创建 Retriever 检索器

向量数据库建立后，通过 as_retriever() 获取标准化检索接口。

k=3 表示最多返回三个相关片段。

向量检索返回的是相对相关的候选资料，不代表每个结果都能正确回答用户问题。

如果知识库很大，可以进一步使用元数据过滤、相似度阈值或重排序模型改善检索质量。

八、将 Retriever 包装成 Tool

这是构建 RAG Agent 最关键的一步。

通过 @tool 把 Retriever 封装成模型可调用的工具。

实例：search_knowledge_base

例如调用：

search_knowledge_base("Python 函数怎么定义？")

工具可能返回：

[来源1] 标题：Python 函数说明
来源ID：demo-python-functions
内容：Python 函数使用 def 定义，可以接收参数、返回结果，并封装重复逻辑。

模型可以根据返回资料进行回答。

注意：这是提供给模型的文本来源标识，并不代表模型自动完成了事实核查。

九、创建 RAG Agent

准备好检索工具后，就可以使用 create_agent() 创建 RAG Agent。

实例：使用 DeepSeek 创建 Agent

这里使用 ChatDeepSeek 显式初始化模型，避免依赖未经验证的模型别名。

需要注意，deepseek-chat 是本例的模型标识，实际可用模型应以用户账号和服务商 API 为准。

十、测试 RAG Agent

下面连续提出三个问题，测试 Agent 是否能根据知识库回答。

可能得到：

问题：Python 入门需要掌握哪些内容？
回答：根据知识库，Python 入门主要学习变量、数据类型、条件判断、循环、函数和模块。

问题：HTML 基础教程涉及哪些知识？
回答：主要涉及网页结构、标题、段落、链接、图片、列表、表格和表单。

问题：Python 函数有什么作用？
回答：Python 函数使用 def 定义，可以封装重复逻辑、接收参数并返回结果。

这里的三个问题均可在模拟知识库中找到对应内容。

不过，Agent 的具体工具调用行为和回答措辞由模型决定，实际输出不一定与示例完全相同。

十一、查看 Agent 是否真的调用了检索工具

仅仅看到模型回答正确，并不能证明它使用了知识库。

如果要检查是否实际调用了工具，可以遍历 Agent 返回的消息列表。

实例：查看工具调用记录

如果模型调用了检索工具，会出现类似：

模型请求工具： ['search_knowledge_base']
工具名称： search_knowledge_base
工具返回： [来源1] 标题：Python 函数说明...

最终回答： Python 函数可以封装重复逻辑、接收参数并返回结果。

可以通过这些信息检查：

• 模型是否发起检索。
• 检索工具是否返回资料。
• 最终回答是否使用了检索内容。

注意：提示词要求模型先搜索，并不构成严格保证。如果业务必须先检索，应该使用确定性工作流。

十二、添加文档来源引用

实际 RAG 系统应该尽量保留资料来源，方便用户核对。

可以在创建 Document 时设置：

metadata = {
    "title": "Python 函数教程",
    "source": "python-functions",
    "url": "https://www.runoob.com/python3/python3-function.html"
}

然后在检索工具中一并返回。

实例：带来源的检索工具

需要特别区分两种引用：

• 检索来源：应用程序实际检索到的 Document。
• 模型生成的引用：模型在自然语言回答中写出的 [来源1] 等标记。

模型引用有可能写错，因此生产环境还应保存 Document ID、原文地址和检索结果，并对引用关系进行校验。

此外，只有经过验证的真实 URL 才应该作为可点击的来源链接展示。

十三、当知识库没有答案时怎么办？

向量数据库一般会返回与查询最接近的候选片段。

即使问题与知识库完全无关，也可能仍然得到几个相似度较低的结果。

例如：

用户：菜鸟教程明年的营收是多少？

如果知识库中没有营收资料，Agent 不应该根据其他教程信息推测答案。

可以在 System Prompt 中明确要求：

如果检索结果没有回答问题所需的依据，必须明确说明资料不足。
不得把无关的检索片段推断成具体事实。
不得编造数字、日期或来源。

对于准确性要求较高的业务，还可以加入相似度阈值或重排序机制。

但检索阈值需要根据所选数据库的评分定义和实际测试结果设置，不能把所有数据库的 score 统一理解为"数值越大越相关"。

十四、向量数据库持久化

在实际项目中，不应该每次启动 Agent 都重新向量化全部文档。

推荐将知识库构建与在线问答分成两个程序。

项目目录
    ├── .env
    ├── build_index.py
    ├── rag_agent.py
    └── runoob_rag_db/
          └── Chroma 数据文件

其中：

• build_index.py：读取文档、切分和生成向量。
• rag_agent.py：连接已有数据库，创建检索工具和 Agent。

首次建立数据库

后续直接连接

这里不再调用 add_documents()，因此不会在每次启动时重复为所有文档生成向量。

重要：重新连接时，需要保持相同的集合名称、数据目录和 Embedding 模型配置。

十五、完整项目：构建知识库索引

下面将前面的操作整理成两个独立 Python 文件。

第一个文件用于构建索引，第二个文件用于在线问答。

为了方便直接测试，使用阿里百炼 Embedding 和 DeepSeek 聊天模型。

文件一：build_index.py

执行：

python build_index.py

成功后，会在 runoob_rag_db 目录中保存向量数据。

本示例使用固定的测试文档。生产项目应额外维护源文档到 Chunk ID 的映射，在文档更新时清理旧版本索引。

十六、完整项目：RAG Agent 在线问答

文件二：rag_agent.py

这个程序连接已经创建的 Chroma 数据库，不会重新对全部知识文档进行向量化。

执行方式

首先建立索引：

python build_index.py

然后运行 RAG Agent：

python rag_agent.py

可能的运行结果

问题：Python 入门需要学习什么？
是否调用知识库： True
最终回答：Python 入门通常包括变量、数据类型、条件判断、循环、函数和模块。

--------------------------------------------------

问题：Python 函数有哪些作用？
是否调用知识库： True
最终回答：Python 函数可以接收参数、返回结果，并封装重复逻辑。

实际结果取决于模型是否调用了检索工具，不能保证每次运行都产生相同的输出。

如果没有调用工具，程序也会通过"是否调用知识库"输出明确显示。

十七、让 RAG Agent 支持多轮对话

前面的程序每个问题都是独立调用，没有自动保存历史消息。

如果希望 Agent 记住用户前面的提问，可以配合 Checkpointer。

实例：加入对话记忆

这里第二轮提问中的"它"，可以结合此前对话理解为 Python 函数。

但有一点需要注意：多轮 RAG 不只是保存聊天历史。

如果用户提出"它是什么""刚才那门课程有哪些知识点"等依赖上下文的问题，检索系统还需要得到包含足够信息的检索查询。

复杂项目可以增加查询改写步骤，将：

它主要有什么作用？

改写为：

Python 函数主要有什么作用？

再执行向量检索。

十八、RAG Agent 的生产环境优化

1、将索引构建与在线问答分离

文档新增或修改时才更新索引，不要在每次用户提问时重新生成全部向量。

2、限制检索数量

k 并不是越大越好。检索过多片段可能增加 Token 消耗，并引入无关内容。

3、优化 Chunk 结构

对于编程教程，尽量保持知识点标题、代码示例、说明和运行结果之间的联系。

4、保留真实来源信息

推荐为每个文档保存原始 URL、标题、章节和必要的版本信息。

模型生成的引用需要能够追溯到真实文档。

5、严格控制私有知识库权限

如果知识库包含多个用户的私人文档，必须在执行检索前由可信后端过滤用户可访问的数据。

不能仅依赖 System Prompt 来阻止泄露。

6、防范提示词注入

检索到的网页或文档可能包含恶意指令，例如要求 Agent 忽略原有规则。

工具返回的内容应被视为不可信数据，不能直接授予其系统指令权限。

7、记录真实工具调用

建议监控模型是否调用知识库、实际检索了哪些文档，以及最终回答是否有依据。

8、控制执行成本

Agent 可能多次执行检索或模型调用，应设置合理的执行限制，并监控 Token 消耗、耗时和错误率。

十九、常见问题

1、RAG Agent 和普通 RAG 有什么区别？

普通 2-step RAG 通常先检索再生成；RAG Agent 将检索作为工具，由模型决定什么时候调用。

2、RAG Agent 必须使用 Agent 吗？

不必须。如果业务要求每次都检索知识库，普通 RAG 工作流可能更简单、更可控。

3、DeepSeek 可以直接作为 Embedding 模型吗？

本教程使用 DeepSeek 聊天模型，以及 OpenAI 或阿里百炼的独立 Embedding 服务。

4、OpenAI 和百炼 Embedding 可以混用吗？

不能直接混用到同一个向量集合，应保持索引与查询时的 Embedding 配置一致。

5、为什么 Agent 没有调用检索工具？

工具调用由模型决定。System Prompt 可以引导，但不能保证每次执行。

6、怎么检查 Agent 是否调用了知识库？

可以遍历返回的 messages，检查 AIMessage 中的 tool_calls 和对应的 ToolMessage。

7、为什么检索到了无关文档？

向量数据库返回的是最相近的候选内容，不代表所有结果都足够相关。可以优化切分、检索阈值和重排序。

8、如何保存引用来源？

在 Document.metadata 中保存 title、source 和 url 等字段，并在检索结果中保留这些信息。

9、如何避免重复计算 Embedding？

使用持久化 Chroma，并将索引构建与在线问答拆分为不同程序。

10、为什么重新加载数据库后检索出错？

需要检查数据库目录、集合名称和 Embedding 模型是否与建立索引时一致。

11、RAG Agent 可以记住上一次的问题吗？

可以结合 Checkpointer 保存同一线程的对话状态，但跨轮检索查询可能还需要上下文改写。

12、RAG 能保证不出现幻觉吗？

不能。需要检查检索结果、来源引用和回答是否被资料支持。

总结

RAG Agent 是将 LangChain 知识库检索能力与 Agent 工具调用机制结合的一种实现方案。

本章节完成了：

• 准备知识库 Document。
• 通过 Text Splitter 切分文档。
• 使用 OpenAI 或阿里百炼 Embedding 生成向量。
• 通过 Chroma 持久化向量数据。
• 使用 Retriever 查询相关资料。
• 通过 @tool 封装知识库搜索。
• 使用 create_agent() 创建 RAG Agent。
• 检查 Agent 是否真正调用检索工具。
• 返回包含来源标识的检索结果。
• 结合 Checkpointer 支持多轮问答。

最核心的代码：

@tool
def search_knowledge_base(query: str) -> str:
    """搜索知识库。"""
    docs = retriever.invoke(query)
    return "\n\n".join(doc.page_content for doc in docs)

agent = create_agent(
    model=ChatDeepSeek(model="deepseek-chat"),
    tools=[search_knowledge_base]
)

最终工作流程：

用户提问
    ↓
RAG Agent
    ↓
search_knowledge_base
    ↓
Retriever
    ↓
Chroma 向量数据库
    ↓
返回 Document
    ↓
模型结合资料生成回答

核心原则：RAG Agent 的价值不只是让模型能够搜索知识库，而是能够根据任务自主使用检索工具。但当业务必须依据私有文档回答时，应采用强制检索和可靠的来源校验机制，不能只依靠提示词保证准确性。