LangChain 智能客服机器人 -- RAG、订单查询、对话记忆与人工转接

经过前面的学习，我们已经掌握了 LangChain 的 Agent、Tools、Middleware、RAG、Checkpointer 和 Human-in-the-Loop 等功能。

但这些功能单独使用还不够。真正的 AI 应用，通常需要将它们组合起来，解决一个完整的业务问题。

本章节将构建一个 LangChain AI 智能客服机器人，实现知识库问答、订单查询、多轮对话、输入检查以及人工转接。

整个项目基于 LangChain 1.x，使用 DeepSeek 作为聊天模型、阿里百炼作为 Embedding 模型、Chroma 保存知识库、SQLite 保存对话状态。

说明：本项目使用模拟的课程、订单和人工客服数据，重点演示 LangChain 的开发流程，不会连接真实订单、会员、退款或人工客服系统。

一、项目功能与需求分析

我们的客服机器人需要支持以下功能：

系统的整体流程如下：

用户发送消息
       ↓
    智能客服
       ↓
  Middleware 检查
       ↓
     大语言模型
       ↓
   判断任务类型
       |
       ├── 课程问题 → RAG 检索知识库
       |
       ├── 订单问题 → 订单查询工具
       |
       ├── 人工转接 → interrupt() 暂停
       |                  ↓
       |               人工处理
       |                  ↓
       |           Command(resume)
       |
       └── 普通问题 → 模型回答
       ↓
   最终回复格式化
       ↓
    Checkpointer
       ↓
     返回用户

这是一个典型的工具型 Agent：模型负责理解用户意图并选择工具，工具负责实际的数据查询或业务动作。

二、项目目录结构

我们先创建一个独立的 Python 项目。

langchain-customer-service/
│
├── .env
├── .gitignore
├── check_install.py
├── customer_service_bot.py
│
├── runoob_kb/
│   └── Chroma 向量数据
│
└── customer_service.db
    SQLite 对话状态数据库

其中：

• .env：保存模型 API Key。
• check_install.py：检查运行环境。
• customer_service_bot.py：客服机器人主程序。
• runoob_kb/：Chroma 知识库持久化目录，运行后生成。
• customer_service.db：SQLite 检查点文件，运行后生成。

本教程将核心功能放在一个 Python 文件里，方便学习和测试。

正式项目可以进一步拆分为 Agent、Tools、Knowledge Base、Database 和 API 模块。

三、环境准备

第一步：检查 Python 版本

建议使用 Python 3.11 或更新的兼容版本。

python --version

如果 Python 版本太旧，需要先升级，再安装 LangChain 相关依赖。

第二步：创建虚拟环境

python -m venv venv

Windows 激活：

venv\Scripts\activate

macOS / Linux 激活：

source venv/bin/activate

第三步：安装依赖

执行：

python -m pip install -U langchain langgraph langchain-deepseek langchain-openai langchain-chroma langchain-text-splitters langgraph-checkpoint-sqlite python-dotenv

主要依赖：

第四步：配置 API Key

在项目根目录创建 .env 文件：

DEEPSEEK_API_KEY=your_deepseek_api_key
DASHSCOPE_API_KEY=your_dashscope_api_key

本教程默认使用：

• DeepSeek：负责用户对话和工具调用。
• 阿里百炼 text-embedding-v4：负责知识库向量化。

如果使用 OpenAI Embedding，可以参考前面的 RAG 教程替换 Embedding 初始化代码。

创建 .gitignore：

.env
venv/
__pycache__/
*.pyc
customer_service.db
runoob_kb/

注意：API Key 和包含聊天记录的数据库文件都不应该提交到公开的 Git 仓库。

四、验证安装环境

创建 check_install.py，检查依赖及环境变量。

运行：

python check_install.py

如果依赖和环境变量正常，会打印当前安装版本和成功提示。

注意：此脚本只检查本地导入和环境变量是否存在，并不会实际验证 API Key 是否有效。真实接口是否可用，需要在后续请求中确认。

五、准备客服知识库

客服机器人的第一项能力，是根据知识库回答问题。

这里使用一组模拟数据，涉及编程课程、学习方式和客服规则。

为了避免把教学资料误当作真实商业政策，课程数量、会员价格和退款规则均不使用未经核实的数据。

实例：模拟知识库

每条文档包含：

• page_content：知识正文。
• source：来源标识。
• title：文档标题。

真实项目应该从经过审核的文档、数据库或网站内容中加载知识，并保留来源 URL 和更新时间。

六、创建 Chroma 向量知识库

使用阿里百炼 Embedding 将知识文档转换成向量，再保存到 Chroma。

为了避免重复初始化，每个文档使用稳定的 ID。

实例：向量化和检索

这里的每个模拟文档都比较短，通常只产生一个 Chunk，因此可以直接使用 source 作为演示 ID。

但实际长文档可能会拆分成多个 Chunk，这时必须为每个 Chunk 创建独立 ID，例如文档 ID 加上片段序号或内容哈希。

注意：真实项目应将知识库构建与客服问答分开运行。文档更新时还要处理旧索引，而不只是不断调用 add_documents()。

七、定义知识库检索工具

通过 @tool 将 Retriever 包装为 Agent 可调用的搜索工具。

实例：search_kb

例如用户询问：

Python 入门应该学习哪些知识？

Agent 可以调用：

search_kb("Python 入门需要学习的知识点")

并根据返回资料生成回答。

需要注意，向量检索不保证返回的所有内容都正确相关。如果知识库没有答案，模型应该明确说明资料不足。

八、定义订单查询工具

客服系统另一个常见需求是订单查询。

例如：

我的订单 ORD-DEMO-001 是什么状态？

但订单数据属于用户私人信息，必须处理权限问题。

不能仅凭知道订单号就允许查询订单详情。

这里通过 ToolRuntime.context 获取经过应用后端认证的用户 ID，然后检查订单归属。

准备模拟订单数据

这里的数据仅用于演示，不对应真实交易。

实例：query_order

注意，这里的 user_id 不是由模型生成的工具参数，而是由应用通过 Runtime Context 提供。

如果当前用户是：

user_xiaoming

他可以查询：

ORD-DEMO-001

但无法读取归属于 user_other 的订单。

重要：实际 Web 应用需要由后端登录系统提供可信 user_id，不能允许浏览器直接指定任意身份。

九、人工转接：interrupt()

当用户需要投诉、人工协助或进一步处理时，可以通过 HITL 机制暂停当前 Agent。

LangGraph 的 interrupt() 会让执行在当前节点暂停，等待外部系统提供恢复数据。

例如：

用户：我要投诉，请转接人工
          ↓
Agent 调用 transfer_to_human
          ↓
       interrupt()
          ↓
      等待人工处理
          ↓
   Command(resume=...)
          ↓
      Agent 继续执行

实例：人工转接工具

这里不会真的创建工单或将用户接入客服队列。

如果接入真实客服系统，需要在审批后调用工单 API，并根据 API 实际返回的成功状态、工单 ID 等信息回复用户。

注意：恢复被 interrupt() 暂停的节点时，节点代码会重新执行。因此，在 interrupt() 之前不应该创建真实工单或执行其他不可重复的副作用。

十、Middleware：用户输入检查

前面介绍过 @before_model，它可以在模型调用之前检查当前状态。

本例实现一个简单的演示拦截器。

为了避免使用不可靠的关键词屏蔽规则，这里只拦截一个明确的测试指令：

BLOCK_DEMO

实例：content_guard

这里有两个关键点：

• can_jump_to=["end"] 声明允许提前结束。
• 拦截回复使用 AIMessage，而不是 HumanMessage。

真实内容安全系统不应只使用简单关键词列表，应结合明确的业务规则、专门的审核机制和工具权限管理。

十一、Middleware：统一客服签名

原稿使用 @after_model 追加客服签名，但这可能导致重复。

因为 Agent 可能先调用工具，再次调用模型，而 after_model 会在每次模型响应后执行。

对于只需要修改最终回答的场景，更适合使用 @after_agent。

同时，需要保留原始 AIMessage 的 ID，避免生成重复消息。

实例：auto_signature

这样，正常情况下最终回复会变成：

Python 入门主要学习变量、循环、函数等知识。

---
RUNOOB AI 客服演示系统｜非真实订单与客服服务

这里通过 model_copy() 保留原消息 ID，避免追加第二条 AIMessage。

还会检查签名是否已经存在，避免重复追加。

注意：对于正式客服网站，更推荐将品牌签名和客服入口作为前端 UI 组件显示，而不是写入每一轮聊天消息，减少历史上下文中的重复文本。

十二、SqliteSaver：实现多轮对话记忆

为了让客服机器人记住用户前面问过什么，需要配置 Checkpointer。

这里使用 SqliteSaver，将 Agent State 保存到本地 SQLite 文件。

实例：创建 Checkpointer

所有 Agent 调用都需要放在 with 代码块内部。

同一个 thread_id 表示同一个对话线程：

config = {
    "configurable": {
        "thread_id": "chat-user-xiaoming-001"
    }
}

但需要注意：

• 一个用户可以有多个会话线程。
• thread_id 不是登录凭证。
• 不同用户不能随意访问彼此的线程。
• SQLite 更适合本地和轻量同步程序。

对于正式线上客服系统，建议使用 PostgreSQL Checkpointer，并由应用后端负责会话身份验证和数据库生命周期管理。

十三、创建智能客服 Agent

前面的组件准备好之后，就可以通过 create_agent() 将它们组合起来。

本例使用 ChatDeepSeek 初始化模型。

实例：创建客服 Agent

这里通过以下参数整合前面的功能：

十四、完整代码：智能客服机器人

下面将所有组件合并为一个完整 Python 文件。

程序实现：

• 自动检查知识库是否需要初始化。
• 使用 Chroma 保存模拟知识。
• 使用可信用户上下文查询模拟订单。
• 使用 SQLite 保存多轮对话。
• 使用 Middleware 完成输入检查和签名。
• 通过 interrupt() 模拟人工转接审批。

文件名：customer_service_bot.py

运行方式

执行：

python customer_service_bot.py

首次运行会建立模拟向量知识库，并创建 SQLite 检查点文件。

如果此前已经运行过同一个 thread_id，旧的对话历史可能仍然存在。

如果希望每次测试都是全新对话，可以更换 thread_id。

说明：这里使用 Chroma 底层集合的 count() 来判断是否为空，只是便于教学演示。正式项目应使用独立的索引构建程序和明确的文档版本管理，不应依赖"集合不为空"判断知识库是否已经更新。

十五、运行结果示例

由于模型回复和工具调用具有一定的不确定性，下面仅展示预期的主要执行效果。

场景 1：知识库问答

用户：请使用知识库介绍 Python 入门要学习什么。

客服：根据演示知识库，Python 入门包括变量、数据类型、
条件判断、循环、函数和模块等内容。

---
RUNOOB AI 客服演示｜非真实交易或人工客服服务

场景 2：查询自己的订单

用户：请查询我的模拟订单 ORD-DEMO-001。

客服：模拟订单 ORD-DEMO-001 为 Python 模拟课程，
金额 ¥99，当前状态为“已完成”。

---
RUNOOB AI 客服演示｜非真实交易或人工客服服务

场景 3：查询其他用户订单

用户：请查询模拟订单 ORD-DEMO-002。

客服：未找到您可以访问的订单，请核对订单编号。

这里即使订单在模拟数据库中存在，只要不属于当前用户，就不能返回详细数据。

场景 4：对话记忆

用户：我刚才问过哪些问题？

客服：您之前询问了 Python 入门知识，
以及两个模拟订单的查询问题。

同一个 thread_id 下的历史消息可以被 Checkpointer 恢复，让模型参考之前的对话。

场景 5：人工转接

用户：我要找人工客服处理问题。

状态：pending_approval
待审批：transfer_to_human

后台模拟批准

状态：completed
客服：模拟转接已获批准。
本程序未连接真实人工客服系统，也没有创建工单。

如果模型没有调用转接工具，就不会出现中断。实际项目应检查工具调用记录，而不是只根据最终回答判断是否触发了转接。

十六、为什么客服签名会重复？

原始代码中，一个问题会出现两次签名：

回答内容

---
客服签名

---
客服签名

主要原因是把最终格式化逻辑放在了 @after_model 中。

Agent 可能在同一轮任务中多次调用模型，after_model 也会运行多次。

此外，如果每次都创建新 AIMessage，而不保留原消息 ID，也可能导致对话历史出现重复消息。

本章节采用：

@after_agent
def auto_signature(state, runtime):
    ...
    updated = last.model_copy(update={"content": ...})
    return {"messages": [updated]}

这种方式保留原消息 ID，并检查是否已经包含签名，避免重复追加。

对于真实网站，最好将签名放在前端界面中统一显示，而不是写入模型历史消息。

十七、人工转接与真实客服系统对接

目前的 transfer_to_human 只是一个 HITL 演示。

如果要真正实现人工客服转接，还需要以下业务模块：

真实流程可以设计为：

用户请求转人工
       ↓
Agent 识别意图
       ↓
创建转接申请
       ↓
后端分配人工客服
       ↓
客服系统返回真实工单 ID
       ↓
用户进入人工服务状态
       ↓
人工客服接管会话

注意，是否需要人工审批，与是否已经成功建立工单，是两个不同问题。

如果业务要求所有转人工请求都进入工单系统，就不一定需要人先审批转接请求；但必须依赖真实的工单创建结果，不能由大模型自行编造工单号。

十八、如何接入 WordPress 网站？

如果希望将这个 AI 客服功能放到 WordPress 网站，可以采用前后端分离的架构。

WordPress 页面
     ↓
聊天窗口（JavaScript）
     ↓
WordPress REST API / 服务端代理
     ↓
Python FastAPI
     ↓
LangChain Agent
     |
     ├── RAG / Chroma
     ├── 订单工具
     ├── Checkpointer
     └── 人工客服转接

这里建议将 LangChain Agent 单独部署为 Python 服务，而不是直接放进 WordPress 的 PHP 执行流程中。

主要原因：

• LangChain 和相关生态以 Python 为主。
• Embedding、向量检索和 Agent 调用适合在独立服务中管理。
• 可以独立扩容和更新模型服务。
• WordPress 保留账号、会员、文章和业务数据库管理。

典型请求过程：

浏览器发送聊天消息
        ↓
WordPress 验证用户登录状态
        ↓
服务端生成可信 user_id
        ↓
调用 Python 客服服务
        ↓
Agent 执行
        ↓
返回回复或待审批状态
        ↓
WordPress 页面展示

重要：不能把 DeepSeek API Key、数据库连接凭据或用户订单读取权限放在前端 JavaScript 中。

即使客服页面允许匿名访问，也应该通过服务端代理调用模型，并限制匿名用户可使用的工具。

十九、生产环境改进建议

1、使用生产数据库保存状态

SQLite 适合本地开发。正式上线时，可以使用 PostgresSaver 保存 Agent 执行状态。

2、知识库和业务数据库分开

RAG 适合教程、帮助文档和产品说明；订单状态、会员权限和支付数据应直接从可信业务数据库查询。

3、工具必须检查权限

不能将订单权限控制完全交给模型。即使模型生成了正确的订单号，工具仍要验证当前用户是否有权查询。

4、对话线程必须验证归属

thread_id 只是对话标识。后端必须确认它属于当前用户，避免通过修改 thread_id 读取别人的聊天记录。

5、知识库需要定期更新

教程、课程信息和业务规则可能发生变化，需要设置文档更新、重新索引和旧数据删除机制。

6、限制模型调用成本

建议限制单次 Agent 工具调用次数、执行时间和 Token 消耗，并对用户请求进行合理限流。

7、防范提示词注入

知识库资料可能包含用户提交的内容，不能把检索结果直接当成高权限指令。

8、处理人工转接状态

人工转接可能等待很长时间，因此需要持久化执行状态、审批记录，并处理重复请求、超时和取消。

9、不要虚构客服承诺

工单编号、预计等待时间、退款结果和会员优惠等信息，都应来自真实业务系统，而不是模型自行生成。

10、区分教学演示和真实上线

这篇示例虽然展示了完整功能组合，但正式上线仍需要 API 鉴权、日志审计、异常处理、数据库连接管理以及实际业务系统集成。

二十、常见问题

1、为什么智能客服需要 RAG？

RAG 可以让客服查询外部文档，而不是只依赖模型的训练知识。

2、DeepSeek 可以与阿里百炼 Embedding 一起使用吗？

可以。DeepSeek 负责聊天，阿里百炼负责文本向量化，两者是不同的模型任务。

3、为什么知识库使用 Chroma？

Chroma 可以在本地保存向量数据，适合教学、原型和轻量知识库应用。

4、可以直接把订单数据库内容向量化吗？

技术上可以，但涉及订单号、金额和状态等精确查询时，通常应直接使用数据库查询工具，而不是依赖向量相似度检索。

5、为什么使用 ToolRuntime？

ToolRuntime 可以将可信用户上下文等信息提供给工具，而不需要让模型自行填写身份参数。

6、SqliteSaver 能保存什么？

它可以保存 Agent 执行状态，包括消息历史和恢复执行所需的检查点信息。

7、为什么 before_model 要配置 can_jump_to？

因为如果希望通过 jump_to 提前结束执行，需要明确声明允许的跳转目标。

8、为什么签名改用 after_agent？

因为它更适合处理 Agent 正常完成后的最终回答，避免每次模型调用后都处理签名。

9、人工转接必须使用 interrupt() 吗？

不一定。简单的转接请求可以直接调用工单 API；需要暂停等待外部决策或输入时，interrupt() 比较合适。

10、Command(resume=...) 如何找到之前的执行？

通过相同 thread_id 和 Checkpointer 恢复之前保存的执行状态。

11、如何让客服支持多个用户？

使用经过认证的用户身份、独立的 thread_id、权限控制以及适合并发的状态数据库。

12、这个示例可以直接部署到线上吗？

不建议直接作为真实客服系统上线。它是一个完整的教学项目，线上还需要补充认证、访问控制、可靠持久化、工单系统和异常处理。

项目总结

通过本章节，我们已经将前面学习的 LangChain 功能组合到一个客服机器人中。

完整的执行过程可以概括为：

用户消息
    ↓
LangChain Agent
    ↓
理解需求
    ↓
选择合适工具
    ↓
检索知识库 / 查询订单 / 请求人工
    ↓
生成或恢复执行
    ↓
格式化最终回复
    ↓
保存对话状态
    ↓
返回用户

核心原则：让 Agent 负责理解和协调任务，让工具负责可靠的数据查询和业务操作，让 Checkpointer 负责对话记忆，让 HITL 负责需要人工参与的流程。

对于实际客服系统，还应让可信后端负责用户认证、订单权限、工单状态和支付等关键业务。

这样才能从一个简单的 AI 聊天机器人，逐步发展为具备知识检索、业务处理和人工协作能力的智能客服系统。