跳到主要内容
AI教程

从零搭建 Adaptive-RAG 电商客服：自适应检索、意图识别与订单工具实战

本教程将带你在本地运行 Adaptive-RAG 电商客服，理解动态检索、多轮证据补充、忠实度校验、Jev 与 DeepSeek 意图识别，并体验政策问答、订单查询、人工确认、测试评测及 Docker 部署。

AI我搜编辑部阅读约 15 分钟
从零搭建 Adaptive-RAG 电商客服：自适应检索、意图识别与订单工具实战

项目简介

Adaptive-RAG 电商客服是一个面向多条件政策咨询的智能客服项目，重点解决证据不足、回答缺少依据以及复杂问题无法一次检索完整等问题。后端由 FastAPI 和 LangGraph 驱动，前端使用 React，系统可以根据用户意图与问题复杂度，在直接回答、知识检索、补充检索、工具执行、人工确认和拒答之间动态选择路径。

项目适合本地演示、学习 Adaptive RAG 工作流以及进行工程验证。它支持政策来源引用、演示订单查询、待确认操作、会话记忆和 SSE 响应，但订单与物流数据并非真实业务数据。

当前 API 直接接受客户端传入的 user_id，尚未验证其真实身份。不要在未接入可信身份认证、TLS 和访问控制的情况下将项目直接部署到公网。

系统如何处理一次请求

用户通过 Web 页面或 HTTP API 提交问题后，请求会依次经过输入护栏、意图识别和复杂度路由。系统随后选择合适的处理分支，最后完成回答生成、忠实度检查、会话记忆更新以及引用返回。

用户 → Web / HTTP API → 输入护栏
     → 意图识别 → 复杂度路由
       ├─ 直接回答
       ├─ 检索 → 精排 → 必要时补充检索
       ├─ 规划 → 工具执行 / 人工确认
       └─ 拒答
     → 生成与忠实度检查 → 会话记忆 → 回答与引用

意图识别可以使用默认的 DeepSeek，也可以切换到 TypeSafe Jev。需要注意，Jev 只替换意图分类节点；复杂度判断、查询改写、任务规划、回答生成、忠实度检查和记忆摘要等其他 LLM 节点仍由 DeepSeek 负责。

核心能力

  • 自适应路由：结合业务意图和问题复杂度，选择直接回答、单轮检索、多轮检索、工具执行或拒答。
  • 混合检索：结合 BM25 与稠密向量召回，使用 RRF 融合结果，并可启用 Cross-Encoder 精排。
  • 证据增强：支持查询改写、证据不足时的补充检索、回答忠实度检查与自纠错。
  • 双意图后端：默认使用 DeepSeek，也可通过 Jev 的结构化 choice 接口识别预定义的 14 类业务意图。
  • 文档处理：直接支持 Markdown；安装可选依赖和系统工具后，可以解析 PDF、Office 与 OCR 文档。
  • 结构化切块：普通文本默认采用 500 字符窗口和 60 字符重叠；识别出的表格会单独成块，并保留标题、章节和来源等元数据。
  • 业务工具：提供订单类演示工具，并包含权限检查、降级、人工确认和幂等机制，也可以接入 MCP 工具。
  • 工程能力：包括会话记忆压缩、结构化日志、Prometheus 指标、健康检查和自动化测试。

准备运行环境

基础要求

  • Python 3.11 或更高版本。
  • 如需运行 Web 前端，使用 Node.js 20.19+ 或 22.12+，并准备 npm。
  • 默认本地模式使用 SQLite 和内存检索组件，不要求预先启动 Docker。

Windows PowerShell 安装步骤

克隆仓库并进入项目根目录后，创建虚拟环境、安装开发依赖、复制配置文件并生成演示数据：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demo

如果项目根目录已经存在 .env，请保留原文件并跳过复制命令。随后启动 FastAPI：

.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

macOS 与 Linux

在 macOS 或 Linux 上，可以创建并激活虚拟环境，再执行对应安装命令：

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

配置模型与本地服务

打开项目根目录中的 .env。以下配置最值得优先检查：

  • DEEPSEEK_API_KEY：启用 DeepSeek 工作流及默认意图分类。真实 API 调用可能产生费用。
  • INTENT_BACKEND：可设为默认的 deepseek 或可选的 jev。
  • JEV_API_KEY：启用 Jev 意图分类时需要。
  • JEV_MODEL：项目当前默认值为 jev-1.13.0。
  • DATABASE_URL：默认使用 sqlite+aiosqlite:///./data/local/app.db。
  • KNOWLEDGE_DIR：默认值为 knowledge，其中的知识文档会在启动时入库。
  • LOCAL_EMBEDDING_ENABLED：控制本地语义向量功能。
  • CROSS_ENCODER_ENABLED：控制本地精排功能。
  • REDIS_URL 与 QDRANT_URL：配置可选的外部缓存和向量服务。

如果不配置 DeepSeek 密钥，系统仍可使用离线演示逻辑，但其回答质量与真实模型模式不同。完整变量可以查看 配置参考 和 示例环境文件。

启动 React 聊天界面

保持后端进程运行，在另一个终端进入前端目录：

cd frontend
npm ci
npm run dev

访问 http://127.0.0.1:5173 即可打开聊天页面。开发服务器会把 /api 请求代理到本机的 8000 端口。

前端支持来源引用、本地会话列表和操作确认卡片。后端会在答案完成校验后，通过 SSE 分段发送内容。如果执行 npm run build 生成 frontend/dist，FastAPI 检测到该目录后会从根路径提供前端页面。

基本使用：咨询退换货政策

首先确认服务状态：

下面使用 PowerShell 向聊天接口提交一个包含多个政策条件的问题：

$payload = @{
    message = "定制马克杯过了七天，但是有质量问题，可以退吗？"
    user_id = "u_demo"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8000/api/v1/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($payload))

系统会先识别退换货相关意图，再根据问题复杂度决定是否检索政策文档。如果初次证据不足，工作流可以改写查询并补充检索；生成答案后还会检查回答是否忠于检索证据，并返回可用的来源引用。

除了 HTTP API，也可以在后端运行期间执行以下命令，使用终端客户端：

python -m app.cli

基本使用：查询和操作演示订单

scripts.seed_demo 会显式创建演示订单。API 启动本身不会自动写入这些数据，因此首次运行时不要跳过数据初始化。演示用户为 u_demo，可用订单包括：

  • ORD10001：已发货，商品为降噪耳机。
  • ORD10002：已签收，商品为定制马克杯。
  • ORD10003：已支付未发货，商品为 T 恤。

例如，在聊天页面输入 取消订单 ORD10003。系统在执行需要确认的操作时，可能返回 pending_action。确认请求必须带回响应中的 session_id，并将 pending_action.action_id 放入 confirm_action_id。Web 页面会使用确认卡片帮助完成该流程。

待确认操作默认保存在服务端进程内 15 分钟。服务重启或请求切换到另一个进程后，可能需要重新发起操作。具体字段与接口格式请参考 API 参考。

进阶配置：启用 Jev 意图识别

要把意图分类节点切换到 TypeSafe Jev，请在本地 .env 中加入或修改以下配置：

INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true

DEEPSEEK_API_KEY=your_deepseek_api_key

保存后重启后端。Jev 通过 HTTP 接口接入，不需要安装专用 SDK。返回结果会经过 Pydantic 校验，再转换成统一的分类结果。

当 Jev 密钥缺失、请求失败或响应不合法时，系统会回退到原有的 IntentClassifier。回退链路优先使用配置的 DeepSeek；离线或模型调用失败时，则继续使用规则分类。可重试错误采用指数退避，且 JEV_MAX_RETRIES 在当前实现中表示最大尝试次数。

JEV_INTENT_APPLY_OVERLAY 控制 Jev 成功分类后的规则纠偏，默认开启。该选项不会控制回退分类器自身的覆盖层。若要恢复默认意图分类，只需把 INTENT_BACKEND 改回 deepseek。

进阶配置：增强检索与文档解析

安装本地向量与精排依赖

.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"

rerank 依赖用于本地稠密向量模型和 Cross-Encoder。默认向量模型为 BAAI/bge-small-zh-v1.5，默认精排模型为 BAAI/bge-reranker-base。首次加载时可能下载模型权重；模型不可用时系统会降级，因此效果不能等同于完整模型配置。

安装扩展文档解析依赖

.\.venv\Scripts\python.exe -m pip install -e ".[docs]"

docs 依赖用于 Unstructured 文档解析。处理 PDF、OCR 和 Office 文件时，还可能需要安装 Poppler、Tesseract 及中文语言包、LibreOffice。详细要求见 解析与检索说明。

知识切片 ID 根据文档路径和切片序号生成。当路径与切分结果不变时，重复入库可以保持 ID 一致；文件迁移、内容编辑或切块策略变化后，历史引用不保证继续指向相同内容。

使用 Docker 启动完整服务

如果希望同时运行 API、PostgreSQL、Redis、Qdrant 和构建后的 Web 前端，请先准备本地 .env，再运行：

docker compose up --build

启动后访问 http://127.0.0.1:8000。Compose 中的数据库口令和端口映射仅面向本地演示。公网部署前必须替换演示口令、限制数据库和缓存端口、启用可信身份认证与 TLS，并设计可靠的持久化和运维方案。

测试、静态检查与评测

在项目根目录运行后端测试和质量检查：

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrieval

前端测试与构建命令需要在 frontend 目录中执行：

npm test
npm run build

测试配置会隔离本地模型密钥并使用测试数据库。单独执行真实模型评测前，应检查模型和网络配置，因为调用外部模型可能产生费用。

比较 Jev 与 DeepSeek 意图分类

配置两种模型的本地密钥后，可以在相同样本和相同覆盖层条件下运行对比：

.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.json

报告包含准确率、P50 与 P95 延迟、回退次数和规则覆盖次数。--no-overlay 会关闭两种分类器的规则纠偏，便于观察模型本身的分类结果；移除该参数则可以比较加入覆盖层后的效果。

当前意图数据集属于开发集，准确率会包含回退样本，不能直接视为 Jev 独立模型的泛化能力。历史评测也不代表当前版本已经重新验证，更不构成真实业务效果保证。

实用工程建议

  1. 先以默认本地模式验证流程：SQLite 和内存检索组件足以完成基础演示，不必一开始就部署外部数据库与向量服务。
  2. 区分意图模型和工作流模型：切换到 Jev 不会替换其他 DeepSeek 节点。若希望运行完整在线工作流，仍需配置 DeepSeek。
  3. 用健康接口排查问题：/api/v1/health 用于进程检查，/api/v1/ready 更适合确认依赖是否就绪。
  4. 谨慎变更切块策略：路径、文本内容或切块参数变化都可能影响切片 ID 和历史引用。
  5. 不要依赖进程内确认状态：默认待确认操作只有 15 分钟有效期，并且可能因重启或多进程切换而丢失。
  6. 保护敏感数据：不要把 .env、真实密钥、本地数据库、日志、用户上传文档或私人资料提交到 GitHub。
  7. 审查外部数据传输：使用外部模型或远程 MCP 前，应确认请求内容不包含不应外传的用户信息。
  8. 规划知识库更新：当前系统启动时会全量入库，尚未提供完整的增量删除流程。

项目目录速览

  • app/api：HTTP API 与 SSE。
  • app/agents：LangGraph 执行图和工作流节点。
  • app/retrieval：解析、切块、召回、融合与精排。
  • app/providers：模型和向量服务适配。
  • app/tools：业务工具、工具注册和权限控制。
  • app/mcp：MCP 工具接入。
  • app/memory：会话记忆与压缩。
  • app/guardrails：输入与回答检查。
  • app/observability：日志和指标。
  • frontend：React 与 TypeScript 聊天界面。
  • knowledge：政策知识文档。
  • tests 与 eval：自动化测试、评测数据和执行器。

总结

Adaptive-RAG 电商客服展示了一个较完整的智能客服工程链路：先进行意图识别和复杂度判断，再按需组合混合检索、多轮证据补充、工具调用、人工确认和忠实度校验。你可以先使用 SQLite、演示订单和离线逻辑快速体验，再逐步启用 DeepSeek、Jev、本地向量模型、Cross-Encoder、扩展文档解析以及 Docker 服务。

在进入真实业务前，还需要重点补齐身份认证、真实订单系统集成、持久化确认状态、知识库增量维护、密钥管理和生产级网络安全。项目采用 MIT License，进一步的架构和限制说明可查看 架构与运行流程、检索设计及 限制与路线图。