📌 项目背景
传统的电商客服机器人通常采用"一个模型处理所有问题"的架构，这在面对跨领域、多步骤的复杂请求时， 效果往往不尽人意——意图识别准确率低、回答不够专业、难以处理上下文依赖的指代消解。
"小蜜" 采用了另一种思路：将电商场景拆解为 12 个垂直领域的专业 Agent， 每个 Agent 配备专属的工具集、提示词知识和 few-shot 示例，通过 LangGraph 状态图进行编排。 用户请求经过三级意图识别路由到最合适的 Agent，辅以 RAG 知识检索和输出校验，实现专业、可控的智能服务。
🏗️ 系统架构
系统分为四层，自底向上依次是数据存储层、AI 引擎层、Agent 协作层和 API 接入层：
以下是系统的主要界面展示，从用户交互到后台监控，覆盖完整的使用场景：
1 主页界面
简洁直观的对话界面，支持多轮对话、意图识别、智能推荐等功能
📡 API 接入层
FastAPI 提供 REST + SSE 流式接口，支持普通对话、流式对话、时间旅行回放和分支对话。
🤖 Agent 协作层
LangGraph StateGraph 编排 12 个 Agent，含意图路由、输出校验、升级检测、转人工等节点。
🧠 AI 引擎层
支持 DeepSeek / OpenAI 等 LLM 后端，配合 RAG 混合检索（向量 + BM25 + Re-ranker）增强知识。
💾 数据存储层
Redis 存短期会话记忆，ChromaDB 存长期向量知识库，SQLite 存轨迹飞轮数据。
🤖 Agent 矩阵
12 个 Agent 按 4 个 Phase 分阶段上线，从核心的订单客服到高级的风控审核：
🔄 对话处理流程
一次用户请求的完整生命周期在 LangGraph StateGraph 中流转。每个节点是一个独立的处理模块， 边是条件路由函数，构成一个可观测、可调试的管道：
其中 三级意图识别（L1 → L2 → L3） 是系统的核心决策节点，采用三层递进策略：
| 层级 | 含义 | 示例 | 策略 | 耗时 |
|---|---|---|---|---|
| L1 | 领域 | shopping / order / after_service | 预设 + 关键词 | 0 ms |
| L2 | 类目 | product_recommend / order_query / return_goods | 关键词 + LLM | 0–5 s |
| L3 | 话题 | by_category / check_status / apply_return | LLM 分类 | 0–5 s |
用户在主页发起咨询后，系统会自动识别意图并路由到对应的 Agent，以下是实际的客服对话效果：
2 客服对话界面
简洁 UI 设计 · 流式输出 · 意图可视化 · Agent 状态追踪 · 结构化数据卡片
⚙️ 关键技术点
📋 LangGraph 状态图
整个对话流程建模为有限状态机。每个节点是独立模块，边是纯函数条件路由。支持检查点快照和时间旅行——可回溯到任意历史节点重新执行。
🔍 Hybrid Search RAG
ChromaDB 向量检索（语义相似度）+ BM25 关键词检索加权融合，经 Cohere / BGE Re-ranker 重排序。确保召回覆盖"意思相近"和"关键词匹配"两种场景。
🔄 查询改写与指代消解
独立的 query_rewriter 节点负责上下文补全（"怎么申请"→"怎么申请退货"）、问题拆分（"退货再买个新的"→两个子问题）和实体提取。
📊 数据飞轮（Trace）
每次请求自动记录节点级轨迹（节点耗时、意图变化路径、Agent 输出），存入 SQLite 形成可分析的飞轮数据，持续优化系统表现。
🛡️ 输出校验与自纠错
full path 的 Agent 输出经过校验检测：空回答、虚构信息、含错误标记都会触发 self_correct 重试节点，最多重试 1 次。
🔄 SSE 流式输出
支持 Server-Sent Events 流式对话，前端逐 token 渲染 LLM 输出，同时实时推送阶段事件（节点开始/完成）和 trace 事件。
除了前端对话界面，系统还提供了完整的后台日志审查能力，方便开发和运维人员追踪问题：
3 日志审查
白盒可控 · 时间旅行回放 · SQLite 持久化存储 · 便于问题定位与调试
📐 状态图结构
系统采用 LangGraph StateGraph 构建对话流程，以下为核心节点拓扑与条件路由逻辑：
主流程链路
Agent 路由分支
所有 Agent 执行后均经过 route_after_agent 决策节点
route_after_agent 决策树
| 条件 | 路由目标 | 说明 |
|---|---|---|
| fast path | update_memory → END |
直接完成，无需额外处理 |
| 有子问题待处理 | 回到对应 Agent |
链式处理多个子任务 |
| 需转人工 | human_handoff → update_memory |
升级到人工客服 |
| 校验失败 | self_correct → 重试/END |
输出校验不通过，自动纠错 |
| 其他 | update_memory → END |
默认结束流程 |
📊 技术栈
🚀 快速开始
# 1. 启动依赖（Redis + ChromaDB）
docker compose -p ecommerce_app up -d
# 2. 安装依赖
pip install -r requirements.txt
# 3. 配置环境变量（.env）
# 至少需要配置 LLM_API_KEY
LLM_PROVIDER=openai
LLM_API_KEY=sk-xxx
LLM_MODEL=deepseek-v4-pro
LLM_BASE_URL=https://api.deepseek.com/v1
# 4. 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# 5. 打开 http://localhost:8000 🎉📁 项目结构
🚀 main.py
FastAPI 入口：chat/chat_stream/fork/replay
📊 data/
知识库（BM25索引 / RAG知识 / 商品数据）
📝 prompts/few_shot/
每个 Agent 的 few-shot 示例
🌐 static/
前端页面（index.html）
🧪 tests/
测试
app/ 核心模块
🔗 graph/
LangGraph 状态图核心
graph.py 图组装 + 节点注册
edges.py 条件路由 + 升级检测 + 校验
state.py AgentState 定义
nodes/ 各节点实现（8个）
🤖 agents/
12 个 Agent（各含 system.md + tools.py）
🧠 memory/
RAG 检索：ChromaDB + Redis + BM25 + Re-ranker
🔧 tools/
Agent 工具（16 个领域工具模块）
📡 api/
API 路由 / 鉴权 / 数字人
📈 flywheel/
数据飞轮（轨迹存储 + 反馈）
🔍 trace/
请求级链路追踪
📋 registry.py
Agent 注册表 + 子图执行器
⚙️ config.py
配置管理（pydantic-settings）
🧠 llm.py
LLM 客户端工厂
📝 prompt.py
系统提示词模板
✍️ 总结与展望
"小蜜" 是一个完整的电商多 Agent 智能助手系统，通过 LangGraph 状态图驱动 12 个专业 Agent 协作， 实现了从意图识别、RAG 知识检索到输出校验的全链路覆盖。
项目目前已完成 Phase 1-2（兜底闲聊、订单、客服、导购、售后、评价）， Phase 3-4（数据分析、质检、运营策略、比价、风控、内容审核）正在开发中。
未来计划包括：多模态支持（商品图片理解）、语音对话（ASR/TTS 集成）、 更完善的数字人视频生成、以及基于飞轮数据的自动评估系统。
联系： 如有任何问题或建议，欢迎在项目中提 Issue。