Multi-Agent MCP 电商客服系统

这是一个 Multi-Agent MCP 电商客服系统。

当前版本的目标是构造一个可继续扩展的电商智能客服项目骨架。

核心功能

多用户注册、登录、会话管理
电商客服聊天入口
后台知识库文档上传，支持 PDF / Markdown
Qdrant 向量库 + BM25 sparse hybrid retrieval
GraphRAG 关系图增强检索
Parent-Child Chunking
Cross-encoder / LLM / None 可选 reranker
LangGraph 多 Agent 编排
MCP 工具服务
- order_query：模拟订单 / 物流查询
- ticket_create：创建售后工单
- ticket_query：查询售后工单
- risk_check：客服风险检查
Redis 短期记忆，Redis 不可用时自动回退 JSON 文件
OpenTelemetry 链路追踪
Jaeger 可视化追踪
Docker Compose 一键启动

当前架构

User
  -> FastAPI Web UI
  -> LangGraph Supervisor / Router
     -> general_chat
     -> order_query_agent
        -> MCP client -> MCP server -> order_query
     -> ticket_agent
        -> MCP client -> MCP server -> ticket_create / ticket_query
     -> compliance_agent
        -> MCP client -> MCP server -> risk_check
     -> Knowledge RAG Agent
        -> Qdrant child chunks
        -> parent_store parent chunks
        -> graph_store entity/relation graph
        -> reranker / CRAG grading / answer synthesis

Redis
  -> short-term memory / ticket state

OpenTelemetry
  -> Jaeger

仓库结构

.
├─ docker-compose.yml              # app + MCP server + Redis + Jaeger
├─ requirements.txt
├─ README.md
└─ project/
   ├─ app.py                       # FastAPI Web UI 入口
   ├─ mcp_server_app.py            # 独立 MCP 工具服务入口
   ├─ config.py                    # 配置中心
   ├─ document_chunker.py
   ├─ core/
   │  ├─ rag_system.py
   │  ├─ chat_interface.py
   │  ├─ document_manager.py
   │  ├─ observability.py          # OpenTelemetry
   │  └─ user_store.py
   ├─ db/
   │  ├─ vector_db_manager.py      # Qdrant
   │  └─ parent_store_manager.py
   ├─ ecommerce/
   │  ├─ tools.py                  # 电商 MCP 工具实现
   │  ├─ tickets.py                # Redis / JSON fallback 工单存储
   │  └─ compliance.py
   ├─ mcp/
   │  ├─ client.py
   │  └─ registry.py
   ├─ memory/
   │  ├─ short_term.py
   │  └─ working_memory.py
   ├─ graph_rag/
   │  └─ store.py                  # JSON-backed GraphRAG 图谱存储与检索
   ├─ rag_agent/
   │  ├─ graph.py
   │  ├─ nodes.py
   │  ├─ edges.py
   │  ├─ tools.py
   │  └─ prompts.py
   └─ ui/
      └─ fastapi_ui.py

运行前准备

1. 准备 LLM 接口

项目使用 OpenAI-compatible Chat API。你需要准备：

LLM_API_KEY
LLM_BASE_URL
LLM_MODEL

默认配置偏向 DashScope/OpenAI-compatible：

LLM_MODEL=qwen-max-0919
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

2. 准备 Ollama Embedding

当前向量检索使用 Ollama embedding，默认模型是 nomic-embed-text。

ollama serve
ollama pull nomic-embed-text

Docker Compose 中默认使用：

OLLAMA_HOST=http://host.docker.internal:11434

如果 Ollama 不在宿主机运行，请在 project/.env 或 Compose 环境变量中修改。

3. 创建环境变量文件

Windows PowerShell:

Copy-Item project\.env.example project\.env

macOS / Linux:

cp project/.env.example project/.env

然后至少填写：

LLM_MODEL=qwen-max-0919
LLM_TEMPERATURE=0
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_API_KEY=your-api-key
DENSE_MODEL=nomic-embed-text
SPARSE_MODEL=Qdrant/bm25
RERANKER_TYPE=cross_encoder

如果你本机首次运行，为了降低模型下载和启动压力，可以先设置：

RERANKER_TYPE=none

推荐运行方式：Docker Compose

Docker Compose 会启动：

app：FastAPI Web UI，端口 7860
mcp-server：MCP 工具服务，端口 8765
redis：短期记忆和工单状态
jaeger：OpenTelemetry 链路追踪 UI

启动：

docker compose up --build

访问：

应用页面: http://127.0.0.1:7860
MCP 工具: http://127.0.0.1:8765/tools
Jaeger:   http://127.0.0.1:16686

停止：

docker compose down

如果也想删除 Redis / Qdrant / app 数据卷：

docker compose down -v

本地开发运行

1. 创建虚拟环境

使用 uv：

uv python install 3.12
uv venv --python 3.12 .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS / Linux:

source .venv/bin/activate

安装依赖：

uv pip install -r requirements.txt

或使用 pip：

pip install -r requirements.txt

2. 启动 Redis

Redis 是推荐项，不是强依赖。没有 Redis 时，系统会回退到 project/data/short_term_memory.json。

如果本机有 Docker，可以只启动 Redis：

docker run --rm -p 6379:6379 redis:7-alpine

3. 启动 MCP 工具服务

新开一个终端：

cd project
python mcp_server_app.py

默认地址：

http://127.0.0.1:8765/tools

4. 启动 Web 应用

再开一个终端：

cd project
python app.py

默认地址：

http://127.0.0.1:7860

使用流程

打开 http://127.0.0.1:7860
注册并登录
进入 Documents 页面上传电商知识库文档，例如：
- 退换货政策
- 退款规则
- 物流时效说明
- 保修政策
- 商品说明书
- 活动规则 FAQ
回到聊天页面提问

上传文档时，系统会同时建立两类索引：

Qdrant 向量索引：用于语义检索具体片段。
GraphRAG 图谱索引：抽取电商领域实体和共现关系，例如“七天无理由”“退货政策”“耳机商品”“保修政策”等，用于回答政策适用关系、商品规则关联、售后条件组合类问题。

可以测试这些问题：

你好

走普通聊天。

帮我查订单 ORD-20260510-001 到哪了

走 order_query_agent，通过 MCP 工具查询模拟订单状态。

我要退款，商家一直不处理

走 ticket_agent，通过 MCP 工具创建售后工单。

查询工单 TK-20260510-ABC123

走 ticket_agent，通过 MCP 工具查询工单。

七天无理由退货规则是什么？

如果知识库中有相关文档，会走 Knowledge RAG Agent，从 Qdrant 和 GraphRAG 图谱共同检索证据后回答。

耳机商品和七天无理由退货有什么关系？

这类关系型问题会优先受益于 GraphRAG 的实体和关系证据。

关键配置

配置优先级：

进程环境变量
project/.env
project/config.py 默认值

常用配置：

| 配置 | 说明 | 默认值 | |---|---|---| | LLM_MODEL | Chat 模型名称 | qwen-max-0919 | | LLM_BASE_URL | OpenAI-compatible API 地址 | DashScope compatible endpoint | | LLM_API_KEY | LLM API Key | 空 | | DENSE_MODEL | Ollama embedding 模型 | nomic-embed-text | | SPARSE_MODEL | Sparse retrieval 模型 | Qdrant/bm25 | | RERANKER_TYPE | cross_encoder / llm / none | cross_encoder | | GRAPH_RAG_ENABLED | 是否启用 GraphRAG 图谱检索 | true | | GRAPH_RAG_MAX_RESULTS | GraphRAG 最多返回的证据数量 | 8 | | REDIS_URL | Redis 地址 | redis://localhost:6379/0 | | MCP_SERVER_URL | MCP 工具服务地址 | http://127.0.0.1:8765/mcp | | OTEL_ENABLED | 是否启用 OpenTelemetry | false | | OTEL_EXPORTER_OTLP_ENDPOINT | OTLP HTTP endpoint | 空 | | APP_HOST | Web 服务监听地址 | 127.0.0.1 | | APP_PORT | Web 服务端口 | 7860 |

数据目录

运行后会生成：

data/                       # 用户、会话、知识库文档等运行数据
qdrant_db/                  # 本地 Qdrant 数据
project/data/               # Redis 不可用时的短期记忆 fallback
data/user_data/<user>/graph_store/   # 每个用户的 GraphRAG 图谱

这些目录已在 .gitignore 中忽略。

OpenTelemetry / Jaeger

Docker Compose 默认启用 OpenTelemetry，并导出到 Jaeger：

http://127.0.0.1:16686

你可以在 Jaeger 中查看：

FastAPI 请求
聊天流式响应 span
MCP client 调用
MCP server JSON-RPC 调用

本地开发时如需启用：

OTEL_ENABLED=true
OTEL_SERVICE_NAME=multi-agent-mcp-app
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318/v1/traces

当前边界

MCP 工具服务当前是项目内 JSON-RPC 风格工具服务，已提供 tools/list 和 tools/call，后续可以继续升级为更完整的 MCP 协议实现。
订单数据是模拟数据，不连接真实电商订单系统。
工单数据使用 Redis，Redis 不可用时回退 JSON 文件。
GraphRAG 当前使用轻量 JSON 图谱存储，适合本地学习和小型知识库；生产环境可以继续替换为 Neo4j / NebulaGraph 等图数据库。
文档上传页面目前保留原 UI，定位为知识库管理入口。

License

本仓库使用 MIT License。

MCP Servers

Multi-Agent MCP 电商客服系统

核心功能

当前架构

仓库结构

运行前准备

1. 准备 LLM 接口

2. 准备 Ollama Embedding

3. 创建环境变量文件

推荐运行方式：Docker Compose

本地开发运行

1. 创建虚拟环境

2. 启动 Redis

3. 启动 MCP 工具服务

4. 启动 Web 应用

使用流程

关键配置

数据目录

OpenTelemetry / Jaeger

当前边界

License

安装包（如果需要）

Cursor 配置 (mcp.json)

Multi-Agent MCP 电商客服系统

核心功能

当前架构

仓库结构

运行前准备

1. 准备 LLM 接口

2. 准备 Ollama Embedding

3. 创建环境变量文件

推荐运行方式：Docker Compose

本地开发运行

1. 创建虚拟环境

2. 启动 Redis

3. 启动 MCP 工具服务

4. 启动 Web 应用

使用流程

关键配置

数据目录

OpenTelemetry / Jaeger

当前边界

License

安装包 （如果需要）

Cursor 配置 (mcp.json)

安装包（如果需要）