01 · LangGraph / FastAPI / Function Calling

Agentic RAG 智能客服

LangGraph 对话引擎 + 混合检索 + Agent 工具链 + 声明门控流式输出与转人工兜底，企业级智能客服系统

查看源码互动演示

1572

测试用例

对话节点

5 工具 + Agent 循环

工具链

OTel + Prometheus 告警

可观测

概述

基于 FastAPI + LangGraph 的企业级智能客服系统：12 节点 StateGraph 编排对话（安全检查 → 意图识别 → 路由 → 槽位收集 / 工具执行 / FAQ 快速路径 / RAG 检索 / Agent 循环 → 生成 → 转人工），支持多轮槽位收集、Function Calling、意图切换与恢复。检索侧为向量 + BM25 混合检索与知识图谱；可靠性侧包括声明门控流式输出、跨会话用户记忆、人工工单兜底与知识缺口闭环；性能侧为 L0/L1/L2 三层缓存金字塔（KB 变更时整体失效，无逐键驱逐）；KPI 侧以一次解决率为北极星指标（转人工与差评双信号排除口径）。可观测侧覆盖 OpenTelemetry 全链路追踪与 Prometheus 指标/告警。1572 项测试。本页演示区右侧的「执行链路」面板实时展示每轮对话各阶段的执行与耗时（事件随 SSE 流内联推送）。

互动演示

RAG 智能对话

检查中...

你好！我是智能客服助手，基于 LangGraph 对话引擎。支持退款/退货/订单查询/物流追踪/投诉等业务，也能回答常见问题。试试："我要退款" → 多轮槽位收集 "退货政策是什么" → RAG 知识检索

点击麦克风开始/停止录音

执行链路

第 0 轮

发送一条消息，观察每一阶段的实时执行

本轮指标

TTFT 首字: —
总时长: —
内容块: 0
管线事件: 0
完成阶段: 0

技术概览

LangGraph 对话状态图

12 节点 StateGraph 编排完整对话流程，Postgres Checkpointer 按会话自动持久化状态。

安全检查 (Guardrail)

Prompt Injection 检测（11 条正则）、PII 脱敏、毒性关键词拦截。未通过直接返回安全提示

意图识别 (Intent Detection)

混合策略（规则 + LLM）。5 种任务型（退款/退货/订单/物流/投诉）+ 知识型（FAQ/Policy）+ 对话型 + 元意图（确认/否认/取消）

意图切换处理 (Intent Switch)

检测意图变更 → 挂起当前任务推入 State Stack → 新意图开始。用户返回时弹栈恢复槽位状态，无缝继续

三路路由 (Route)

Task → 多轮槽位收集 → Function Calling 工具执行；RAG → 向量/图谱检索；Direct → LLM 直出（闲聊/问候）

槽位收集 + 工具执行

正则提取槽位值 + 短消息回退赋值。缺槽追问，槽位完整后执行 Function Calling（退款/退货/订单查询/物流/投诉 5 个工具）

回复生成 + 恢复提示

LLM 生成最终回复。如有挂起任务，自动追加恢复提示。流式响应支持（SSE）

业务意图分类

替代传统的知识型意图（QUESTION/HOW_TO），直接映射业务动作，驱动 Function Calling。

💰

退款

槽位: order_id, reason, amount

📦

退货

槽位: order_id, reason

🔍

订单查询

槽位: order_id

🚚

物流追踪

槽位: order_id

📢

投诉

槽位: category, description

FAQ

RAG 检索

Policy

RAG 检索

Chitchat

LLM 直出

Cancel/Confirm

状态动作

意图切换与恢复

用户中途切换意图时，当前任务状态自动推栈保存。返回时弹栈恢复，无缝继续。

用户: "我要退款"
→ detect_intent: refund
→ collect_slots: filled={}, pending=[order_id, reason]
→ generate: "请提供您的订单号"

用户: "订单号12345"
→ collect_slots: filled={order_id:"12345"}, pending=[reason]
→ generate: "请问退款原因是什么？"

用户: "退货政策是什么"         ← 中途切换！
→ handle_switch: push({intent:refund, filled:{order_id:12345}})
→ detect_intent: policy
→ rag_lookup: 检索退货政策
→ generate: "退货政策是7天无理由..."
   + "您之前的退款申请需要继续吗？"

用户: "继续，原因是质量问题"
→ handle_switch: pop → 恢复 refund + filled={order_id:"12345"}
→ collect_slots: filled={order_id:"12345", reason:"质量问题"}, pending=[]
→ execute_tool: mock_refund → {status:success, refund_id:"RF123456"}
→ generate: "退款已受理，退款单号RF123456，预计3-5个工作日到账。"

AI 安全门禁

三层防御体系：输入校验、Prompt 加固、输出净化。全部本地执行，不依赖外部 API。

输入防护

11 条 Prompt Injection 正则（中英双语）
PII 正则：手机号、身份证、邮箱、银行卡、IPv4
毒性关键词黑名单
消息长度校验

Prompt 加固

7 条安全规则注入系统 Prompt
反角色扮演指令
拒绝有害内容指令
领域边界强制执行

输出防护

LLM 响应 PII 脱敏
话题合规性校验
flagged 内容安全兜底
环境变量可配置

GraphRAG（知识图谱）

Neo4j 知识图谱补充向量检索，支持结构化实体关系查询。集成 LLM 实体抽取、社区发现、Text-to-Cypher 翻译。

图谱构建流水线:
  文档 → 分块 → LLM 抽取
       → 实体（产品、品牌等）
       → 关系（属于、兼容）
       → 存入 Neo4j

图谱查询流水线:
  用户查询 → 实体填充（提取提示）
           → Text-to-Cypher
           → Neo4j 查询 → 结果

多路融合

向量结果 + 图谱结果 → Reciprocal Rank Fusion → 统一排序 → Cross-Encoder 重排序

社区发现

实体关系层次聚类，支持社区级摘要和全局搜索

混合检索

语义向量 + BM25 关键词 → RRF 融合 → Top 50 → 重排序 Top 5

系统架构

客户端 (Next.js / Swagger UI)
  │
  ▼
FastAPI
  ├── 中间件
  │   ├── RequestIDMiddleware (UUID per request)
  │   ├── PrometheusMiddleware (指标采集)
  │   ├── RateLimiter (内存限流)
  │   └── OpenTelemetry (OTLP 链路追踪)
  │
  ├── LangGraph StateGraph (对话引擎)
  │   ├── guardrail_node (输入安全检查)
  │   ├── detect_intent_node (混合意图识别)
  │   │   └── cancel 优先 → 槽位值提取保持任务意图 → 元意图保持
  │   ├── handle_switch_node (意图切换推栈/弹栈恢复)
  │   ├── route_intent_node (三路路由决策)
  │   │   ├── task → collect_slots → execute_tool
  │   │   ├── rag  → rag_lookup (向量 + 图谱)
  │   │   ├── direct → direct_response
  │   │   └── meta → generate_response
  │   ├── collect_slots_node (正则 + 回退赋值)
  │   ├── execute_tool_node (Function Calling, 5 工具)
  │   ├── rag_lookup_node (Qdrant + Neo4j)
  │   ├── generate_response_node (LLM + 恢复提示)
  │   └── MemorySaver Checkpoint (按 session_id 持久化)
  │
  ├── 反馈 API (POST /feedback, 点赞/点踩)
  │
  └── 数据层
      ├── PostgreSQL (用户、会话、消息、反馈)
      ├── Redis (Embedding 缓存、限流)
      ├── Qdrant (向量库、混合检索)
      └── Neo4j (知识图谱、实体关系)

技术栈

PythonFastAPILangGraphNeo4j (Graph DB)Qdrant (Vector DB)PostgreSQLRedisOpenTelemetryPrometheusDockerOpenAI/GLM APIs

核心特性

LangGraph StateGraph 对话图：12 节点编排（安全检查 → 意图识别 → 意图切换/路由 → 槽位收集/工具执行/FAQ 快速路径/RAG 检索/Agent 循环 → 生成/直答 → 转人工）

业务意图分类：5 种任务型（退款/退货/订单查询/物流追踪/投诉）+ 知识型 + 对话型 + 元意图，规则 + LLM 混合识别

多轮槽位收集：正则提取 + 短消息回退赋值，缺槽追问直到完整

Function Calling：ToolRegistry + 5 个工具（退款/退货/订单/物流/投诉）+ Agent 工具循环

意图切换与恢复：State Stack 推栈保存/弹栈恢复，任务中断后可无缝继续；已执行任务为终态，不再挂起或复活（防止二次退款）

五路路由：task → 槽位 → 工具；faq → 策展命中直出；rag → 检索生成；agent → 工具循环；direct → LLM 直答

声明门控流式输出：句子缓冲 + 策展事实校验，越界声明拦截/改写后才放出，流式内容与持久化一致

跨会话用户记忆：user_facts 长期画像 + TTL 召回缓存，个性化上下文有界可控

转人工兜底：情绪/复杂度触发工单创建（队列位置、AHT 维度），知识缺口自动记录并闭环

GraphRAG 知识图谱：Neo4j 实体关系查询 + Text-to-Cypher + 社区发现

混合检索：Qdrant 向量 + BM25 关键词 → RRF 融合 → 重排序；本地 BGE 嵌入 + 嵌入缓存

缓存金字塔：L0 答案缓存 / L1 语义缓存 / L2 检索结果缓存，KB epoch 轮换整体失效，无逐键驱逐

一次解决率 KPI：转人工与差评双信号排除口径，DB 桥接 Prometheus gauge 周期刷新

横向扩展就绪：compose 端口段 + nginx upstream 模板 + dns_sd 多副本抓取，单机即节点模板，2→N 不重构

双层限流：Redis 全局滑动窗 + 单 IP 聊天预算，Redis 不可用时降级为进程内桶

全链路可观测：OpenTelemetry 追踪 + Prometheus 指标（TTFT/时长/结果）+ SLA/策略门控告警规则

Checkpoint 持久化：LangGraph Postgres 按会话保存/恢复对话状态

输入/输出安全防护：Prompt Injection 检测、PII 脱敏、毒性拦截、Prompt 加固

多 Provider LLM：GLM（默认）/ OpenAI / Anthropic 自动降级