内容
# 多智能体 RAG 系统与 FastMCP 集成
一个使用 **FastAPI** 构建的 **多智能体 AI 系统**，通过 **检索增强生成（RAG）** 回答常见问题，提供 **天气信息**，并通过 **FastMCP 待办事项服务器** 管理 **任务**。该系统使用 **LangGraph** 进行智能体编排，使用 **ChromaDB** 进行向量存储，并完全容器化，具有解耦的 **Streamlit** 前端。
---
## 目录
- [系统架构](#系统架构)
- [系统设计](#系统设计)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [设置说明](#设置说明)
- [Docker 设置](#docker-设置)
- [API 文档](#api-文档)
- [测试](#测试)
- [智能体深入探讨](#智能体深入探讨)
---
## 系统架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ Streamlit 前端 │
│ （解耦微服务） │
│ 聊天 UI │ 天气 UI │ 待办事项管理器 UI │
└───────────────────────────────┬─────────────────────────────────────┘
│ HTTP/REST（JSON）
▼
┌─────────────────────────────────────────────────────────────────────┐
│ FastAPI 后端 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │
│ │ 认证 API │ │ 聊天 API │ │天气 API│ │ 待办事项 API │ │
│ │ /auth/* │ │ /chat │ │ /weather │ │ /todos/* │ │
│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────────┬─────────┘ │
│ │ │ │ │ │
│ │ ┌────▼──────────────┴──────────────────┘ │
│ │ │ │
│ JWT 认证 ┌───▼────────────────────────────────────┐ │
│ 中间件 │ 父智能体（LangGraph 编排器） │ │
│ │ │ │
│ │ ┌──────────┐ ┌─────────────────────┐│ │
│ │ │意图检测 │ │ 条件路由器 ││ │
│ │ │（LLM） │ │ 常见问题 → RAG 智能体 ││ │
│ │ │ │ │ 天气 → 工具智能体 ││ │
│ │ │ │ │ 待办事项 → 工具智能体 ││ │
│ │ └──────────┘ │ 待办事项 → 工具智能体 ││ │
│ │ └─────────────────────┘│ │
│ └─────┬────────────────────┬─────────────┘ │
│ │ │ │
│ ┌────────▼──────┐ ┌────────▼───────────┐ │
│ │ RAG 智能体 │ │ 工具智能体 │ │
│ │ │ │ │ │
│ │ 1. 语义搜索 │ │ ┌──────────────┐ │ │
│ │ 语义构建 │ │ │ 天气工具 │ │ │
│ │ 3. LLM 答案 │ │ │ （Open-Meteo） │ │ │
│ │ 生成 │ │ ┌──────────────┐ │ │
│ │ │ │ │ 待办事项工具 │ │ │
│ │ │ │ │ （FastMCP） │ │ │
│ └───────┬───────┘ └─────────┼──────────┘ │
│ │ │ └──────┬───────┘ │ │
│ ┌───────▼───────┐ └─────────┼──────────┘ │
│ │ ChromaDB │ │ │
│ │ 向量存储 │ ┌─────────▼──────────┐ │
│ │ （常见问题数据） │ │ FastMCP 待办事项 │ │
│ └───────────────┘ │ 服务器（PostgreSQL）│ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ PostgreSQL 数据库 │ │
│ │ （用户 + 待办事项） │ │
│ └────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 系统设计
### 微服务架构
应用程序遵循 **微服务架构**，具有两个独立部署的服务：
| 服务 | 技术 | 端口 | 责任 |
|----------------|-----------|------|----------------------------------------|
| **后端** | FastAPI | 8000 | API 服务器，智能体编排，RAG，MCP |
| **前端** | Streamlit | 8501 | 用户界面，仅通过 REST API 通信 |
| **数据库** | PostgreSQL| 5432 | 用户和待办事项的持久存储 |
前端 **松散耦合** - 它只知道后端的 URL，并仅通过 HTTP REST 调用进行通信。没有共享代码，没有共享状态。
### 多智能体系统（LangGraph）
智能体系统使用 **LangGraph** 构建，实现有向状态图：
```
┌─────────────────┐
│ 检测意图 │ （入口点）
│ （LLM 基础） │
└────────┬────────┘
│
┌────────▼────────┐
│ 条件路由器 │
└──┬──────┬───┬───┘
│ │ │
"常见问题" │ │ │ "未知"
│ │ │
┌────────▼┐ ┌──▼───▼─────┐ ┌───────────┐
│ RAG 节点 │ │ 工具节点 │ │ 未知节点 │
│ │ │ │ │ │
└────┬────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
└─────────────┴───────────────┘
│
[结束]
```
1. **父智能体（编排器）**：接收查询，使用 LLM 分类意图（`常见问题`，`天气`，`待办事项`，`未知`），然后路由到适当的专家。
2. **RAG 智能体**：对 ChromaDB 进行语义搜索，从 top-k 结果中构建上下文，并使用 LLM 生成基础答案。
3. **工具智能体**：根据分类意图调度到天气 API 或 FastMCP 待办事项工具。
### RAG 管道
```
CSV 数据 → LangChain 文档 → OpenAI 嵌入 → ChromaDB 向量存储
│
用户查询 → 嵌入 → 相似性搜索（top-4）→ 上下文构建 → LLM → 答案
```
- **数据来源**：常见问题 CSV 文件（386 个问答对，来自 BigRock）
- **嵌入**：OpenAI `text-embedding-3-small`
- **向量存储**：ChromaDB（内存 + 可选持久化）
- **LLM**：GPT-4.1 Mini（可配置）
- **回退**：如果不存在相关上下文，则返回"我无法找到答案"
### FastMCP 集成
待办事项服务作为 **FastMCP 3.x 服务器** 实现，工具通过 MCP 协议暴露。待办事项存储在 **PostgreSQL** 中，通过 SQLAlchemy：
- `create_task` — 创建新的待办事项
- `list_tasks` — 列出所有任务（带过滤器）
- `get_task` — 通过 ID 检索任务
- `update_task` — 修改任务标题/描述/状态
- `delete_task` — 删除任务
后端使用 **FastMCP 客户端** 进行内存传输（同一进程内的 MCP 调用无需网络跳转），同时还暴露 REST API 端点供直接访问。智能体还支持 **基于关键字的任务解析** - 用户可以通过名称引用任务。
### JWT 认证
所有 API 端点（`/auth/*` 和健康检查除外）都受 **JWT Bearer 令牌认证** 保护。
流程：
1. `POST /auth/register` 或 `POST /auth/login` → 返回 JWT
2. 在后续请求中包含 `Authorization: Bearer <token>`
3. 在每个受保护的端点上验证令牌
### 数据流
```
用户输入 → Streamlit → POST /chat → JWT 验证 → 编排器
→ 意图检测（LLM）→ 路由到智能体 → 执行 → 返回响应
→ Streamlit 渲染答案
```
---
## 技术栈
| 组件 | 技术 |
|-----------------|-------------------------------|
| 后端 API | FastAPI，Uvicorn |
| 智能体框架 | LangGraph，LangChain |
| LLM | OpenAI GPT-4.1 Mini |
| 嵌入 | OpenAI text-embedding-3-small |
| 向量数据库 | ChromaDB |
| 数据库 | PostgreSQL，SQLAlchemy，Alembic|
| MCP 服务器 | FastMCP 3.x |
| 天气 API | Open-Meteo（免费，无密钥） |
| 认证 | JWT（python-jose） |
| 前端 | Streamlit |
| HTTP 客户端 | httpx（异步），requests |
| 测试 | Pytest |
| 容器化 | Docker，Docker Compose |
---
## 项目结构
```
Multi_Agent_RAG_With_FastMCP/
├── docker-compose.yml # 编排后端 + 前端容器
├── README.md
├── data/
│ ├── faqs.csv # 常见问题数据集（问答对）
│ └── faqs 3.xlsx # 原始 Excel 源
│
├── backend/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── requirements.txt
│ ├── pytest.ini
│ ├── alembic.ini # Alembic 配置（URL 被 env.py 覆盖）
│ ├── .env # 秘密变量（gitignored）
│ ├── .env.example # 环境变量模板
│ ├── alembic/ # Alembic 配置
│ │ ├── env.py # 迁移环境（读取 DATABASE_URL）
│ │ └── versions/ # 迁移脚本
│ ├── app/
│ │ ├── main.py # FastAPI 入口点，CORS，生命周期
│ │ ├── config.py # 环境变量设置
│ │ ├── database.py # SQLAlchemy 引擎，会话，Base
│ │ │
│ │ ├── models/ # ORM 模型
│ │ │ ├── __init__.py # 导出 User，Todo
│ │ │ ├── user.py # 用户模型
│ │ │ └── todo.py # 待办事项模型
│ │ │
│ │ ├── auth/ # 认证模块
│ │ │ ├── routes.py # POST /auth/login，/auth/register
│ │ │ ├── controllers.py # 登录/注册逻辑
│ │ │ └── jwt_handler.py # JWT 创建/验证，FastAPI 依赖
│ │ │
│ │ ├── chat/ # 聊天模块
│ │ │ ├── routes.py # POST /chat
│ │ │ └── controllers.py # 委托给编排器
│ │ │
│ │ ├── weather/ # 天气模块
│ │ │ ├── routes.py # GET /weather
│ │ │ └── controllers.py # 委托给工具智能体
│ │ │
│ │ ├── todo/ # 待办事项模块
│ │ │ ├── routes.py # CRUD /todos/*
│ │ │ └── controllers.py # 代理到 FastMCP 客户端
│ │ │
│ │ ├── agents/ # 多智能体系统
│ │ │ ├── orchestrator.py # 父智能体（LangGraph 状态图）
│ │ │ ├── rag_agent.py # RAG 管道智能体
│ │ │ └── tool_agent.py # 天气 + 待办事项智能体
│ │ │
│ │ ├── rag/ # RAG 基础设施
│ │ │ ├── loader.py # CSV → LangChain 文档
│ │ │ └── vectorstore.py # ChromaDB 构建/查询
│ │ │
│ │ └── mcp/ # FastMCP 集成
│ │ ├── todo_server.py # FastMCP 服务器与 CRUD 工具（PostgreSQL）
│ │ └── client.py # FastMCP 客户端（内存传输）
│ │
│ └── tests/
│ ├── conftest.py # 共享夹具
│ ├── test_auth.py # 认证 API 测试
│ ├── test_weather.py # 天气 API 测试
│ ├── test_todos.py # 待办事项 API 测试
│ └── test_chat.py # 聊天 API 测试
│
└── frontend/
├── Dockerfile
├── .dockerignore
├── requirements.txt
├── .env
├── .env.example
├── config.py # 前端配置
├── api_client.py # 后端 API 的 HTTP 客户端
├── app.py # Streamlit 应用程序
└── .streamlit/
└── config.toml # Streamlit 服务器配置
```
---
## 设置说明
### 先决条件
- Python 3.12+
- OpenAI API 密钥
- PostgreSQL 16+（或使用 Docker，它包含）
- （可选）Docker & Docker Compose
### 本地开发（无 Docker）
#### 1. 后端设置
```bash
cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或：venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 编辑 .env 并添加您的 OPENAI_API_KEY 和 DATABASE_URL
# 运行数据库迁移
alembic upgrade head
# 运行后端
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000```
API 文档可在 **http://localhost:8000/docs**（Swagger UI）访问。
#### 2. 前端设置
```bash
cd frontend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 运行前端
streamlit run app.py --server.port 8501```
前端可在 **http://localhost:8501** 访问。
#### 3. 默认凭证
| 用户名 | 密码 |
|----------|-----------|
| admin | admin123 |
您也可以通过 UI 或 API 注册新帐户。
---
## Docker 设置
### 快速入门
```bash
# 从项目根目录
cp backend/.env.example backend/.env
# 编辑 backend/.env 并添加您的 OPENAI_API_KEY
docker-compose up --build
```
这启动三个服务：
- **PostgreSQL** 在 localhost:5432（通过 Docker 卷持久化）
- **后端** 在 http://localhost:8000 (API + Swagger UI)
- **前端** 在 http://localhost:8501
后端容器自动在启动时运行 Alembic 迁移。
### Docker 网络
`docker-compose.yml` 覆盖了某些 `.env` 值以进行容器联网：
- `DATABASE_URL` → 指向 `db:5432` 而不是 `localhost:5432`
- `BACKEND_URL` → 前端内部使用 `http://backend:8000`
- `FAQ_CSV_PATH` → `/data/faqs.csv`（从 `./data` 挂载）
您的 `.env` 保留 `localhost` 值，因此本地开发（无需 Docker）仍然有效。
### 停止服务
```bash
docker-compose down
# 要同时删除卷（清除数据库和 ChromaDB 数据）：
docker-compose down -v
```
---
## API 文档
一旦后端运行，交互式 API 文档位于：
- **Swagger UI**：http://localhost:8000/docs
- **ReDoc**：http://localhost:8000/redoc
### 端点摘要
| 方法 | 端点 | 认证 | 标签 | 描述 |
|--------|-----------------------|------|----------------|------------------------------------|
| POST | `/auth/login` | 否 | 认证 | 登录并获取 JWT 令牌 |
| POST | `/auth/register` | 否 | 认证 | 注册新用户并获取 JWT |
| POST | `/chat` | 是 | 聊天 | 发送查询到编排器智能体 |
| GET | `/weather` | 是 | 天气 | 获取指定城市的当前天气 |
| POST | `/todos` | 是 | 待办事项 | 创建新任务 |
| GET | `/todos` | 是 | 待办事项 | 列出所有任务 |
| GET | `/todos/{task_id}` | 是 | 待办事项 | 获取特定任务 |
| PUT | `/todos/{task_id}` | 是 | 待办事项 | 更新任务 |
| DELETE | `/todos/{task_id}` | 是 | 待办事项 | 删除任务 |
| GET | `/` | 否 | 健康检查 | 健康检查 |
| GET | `/health` | 否 | 健康检查 | 详细健康检查 |
### 示例用法
```bash
# 1. 登录（使用表单编码数据以兼容 OAuth2）
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
-d 'username=admin&password=admin123' \
| jq -r '.access_token')
# 2. 聊天（常见问题查询）
curl -X POST http://localhost:8000/chat \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "BigRock 提供哪些域名？"}'
# 3. 天气
curl -X GET "http://localhost:8000/weather?city=London" \
-H "Authorization: Bearer $TOKEN"
# 4. 创建待办事项
curl -X POST http://localhost:8000/todos \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "购买杂货", "description": "牛奶，鸡蛋，面包"}'
```
---
## 测试
在快乐路径测试套件中运行：
```bash
cd backend
pytest tests/ -v
```
测试套件涵盖：
- **认证 API**：注册，登录，重复处理，JWT 验证
- **天气 API**：默认城市，自定义城市，认证强制执行
- **待办事项 API**：创建，列出，更新，删除任务，认证强制执行
- **聊天 API**：常见问题/天气/待办事项查询（隔离的模拟编排器）
---
## 智能体深入探讨
### 父智能体（编排器）
**文件**：`backend/app/agents/orchestrator.py`
使用 LangGraph `StateGraph` 带有类型状态 (`AgentState`)。LLM 将用户的意图分类为以下之一：`常见问题`，`天气`，`待办事项` 或 `未知`。条件边根据分类路由到相应的专家节点。
### RAG 智能体
**文件**：`backend/app/agents/rag_agent.py`
1. 接收原始查询
2. 对 ChromaDB 进行相似性搜索（前 4 个结果）
3. 将检索的文档格式化为上下文块
4. 将上下文 + 查询发送到 GPT-4.1 Mini，并带有严格的基础指令
5. 返回生成的答案（或回退消息）
### 工具智能体
**文件**：`backend/app/agents/tool_agent.py`
调度到：
- **天气工具**：调用 **Open-Meteo API**（免费，无需 API 密钥）。使用 2 步流程：地理编码城市名称 → 获取当前天气。
- **待办事项工具**：通过内存 MCP 客户端调用 **FastMCP 待办事项服务器**。支持基于关键字的任务解析 - 用户可以通过名称/描述而不是 ID 引用任务。
---
## 配置参考
所有机密和配置存储在 `backend/.env` 中：
| 变量 | 描述 | 默认值 |
|----------------------------------|----------------------------------|------------------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | （必填） |
| `OPENAI_MODEL` | LLM 模型名称 | `gpt-4.1-mini` |
| `JWT_SECRET_KEY` | JWT 签名密钥 | （必填） |
| `JWT_ALGORITHM` | JWT 算法 | `HS256` |
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES`| Token 过期分钟数 | `30` |
| `DATABASE_URL` | PostgreSQL 连接字符串 | （必填） |
| `WEATHER_DEFAULT_CITY` | 默认城市用于天气查询 | `伦敦` |
| `CHROMA_PERSIST_DIR` | ChromaDB 数据目录 | `./chroma_db` |
| `CHROMA_COLLECTION_NAME` | ChromaDB 集合名称 | `faq_collection` |
| `FAQ_CSV_PATH` | 常见问题 CSV 文件路径 | `../data/faqs.csv`|
---
## 许可证
请参阅 [LICENSE](LICENSE) 获取详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器