内容
# 🤖 AI 研究助理：RAG + 多智能体系统
<div align="center">
**一款基于检索增强生成（RAG）和多智能体架构的智能文档分析系统**
</div>
---
## 📋 描述
**AI 研究助理**是一款复杂的全栈应用，利用先进的AI技术实现智能文档分析和问答。用户可以上传文档（PDF/TXT），系统通过多智能体管道处理，提供上下文准确的答案，使用检索增强生成（RAG）。
本项目演示了结合RAG、MCP和多智能体架构的实际应用。
系统展示了企业级架构模式，包括：
- **RAG管道**：使用FAISS矢量数据库的高效文档检索
- **多智能体架构**：用于规划、检索和处理任务的专用智能体
- **MCP样式工具集成**：模块化工具的智能体设计模式
- **生产就绪的防护措施**：输入验证和安全过滤
- **全面的可观察性**：整个管道的结构化日志记录
---
## ✨ 功能
### 核心能力
- 📄 **文档上传与处理** - 支持PDF和TXT文件，自动解析
- 🔍 **语义搜索** - 基于FAISS的矢量相似性，用于准确的块检索
- 🧠 **RAG驱动的问答** - 使用Groq API通过LLaMA 3提供上下文感知答案
- 💬 **对话历史** - 持久的聊天会话，保留上下文
### 多智能体系统
- **规划智能体** - 分析查询并协调任务执行
- **检索智能体** - 通过语义搜索获取最相关的文档块
- **处理智能体** - 执行特定领域的任务（总结、关键提取、主题分析）
### 高级功能
- 🛡️ **防护措施** - 空输入检测，不安全内容过滤
- 📊 **可观察性** - 结构化日志记录，查询跟踪，错误诊断
- ✅ **单元测试** - 全面的pytest测试套件
- ⚡ **实时处理** - 异步任务处理
## 🔗 MCP（模型上下文协议）
该项目遵循MCP样式架构，其中：
- 智能体通过结构化上下文进行通信
- 工具（摘要、关键点、主题）作为模块化能力
- 规划器根据用户意图动态选择工具
这使得灵活和可扩展的AI工作流成为可能。
---
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────────────┐
│ 前端（React） │
│ 文档上传与聊天界面 │
└──────────────────────┬──────────────────────────────────────┘
│ HTTP/REST API
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI后端 │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ API层（FastAPI路由） │ │
│ │ • 聊天端点 │ │
│ │ • 文档上传与管理 │ │
│ │ • 用户会话与历史 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ 多智能体编排层 │ │
│ │ │ │
│ │ ┌────────────────┐ ┌─────────────────┐ │ │
│ │ │ 规划智能体 │──▶ 处理智能体 │ │ │
│ │ └────────────────┘ └─────────────────┘ │ │
│ │ │ ▲ │ │
│ │ └────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ 检索智能体 │ │ │
│ │ │ （语义搜索 + 块检索） │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ RAG与数据处理管道 │ │
│ │ │ │
│ │ • 文本分块（句子转换器） │ │
│ │ • 嵌入生成 │ │
│ │ • FAISS矢量数据库（相似性搜索） │ │
│ │ • 上下文组装与提示工程 │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ LLM集成（Groq API - LLaMA 3） │ │
│ │ 响应生成 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 基础设施与存储 │ │
│ │ • MongoDB（聊天历史，元数据） │ │
│ │ • FAISS索引（矢量存储） │ │
│ │ • 文件系统（文档存储） │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 数据流
```
用户查询
▼
防护措施（输入验证）
▼
规划智能体（任务分析）
▼
检索智能体（FAISS搜索） ◀──┐
▼ │
上下文组装 ──────────────────┘
▼
LLM处理（Groq API）
▼
处理智能体（后处理）
▼
用户响应 + 历史存储
```
---
## 🛠️ 技术栈
### 后端
| 组件 | 技术 | 目的 |
|-----------|-----------|---------|
| **框架** | FastAPI | 高性能REST API |
| **LLM** | LLaMA 3（通过Groq API） | 响应生成 |
| **矢量数据库** | FAISS | 语义相似性搜索 |
| **嵌入** | 句子转换器 | 文本嵌入生成 |
| **数据库** | MongoDB | 持久存储（历史，元数据） |
| **任务队列** | Python asyncio | 异步处理 |
| **测试** | pytest | 单元测试与集成测试 |
| **日志记录** | Python日志记录 | 结构化可观察性 |
### 前端
| 组件 | 技术 | 目的 |
|-----------|-----------|---------|
| **框架** | React 18 | 交互式UI |
| **样式** | CSS/Tailwind（可选） | UI/UX设计 |
| **HTTP客户端** | Fetch API/axios | 后端通信 |
### DevOps与基础设施
- **包管理**：pip/poetry（Python），npm（Node.js）
- **环境管理**：Python venv
- **数据管道**：自定义分块与嵌入服务
---
## 📁 项目结构
```
ai-research-assistant/
├── README.md # 项目文档
├── pytest.ini # Pytest配置
├── requirements.txt # Python依赖
│
├── app/ # 主应用包
│ ├── __init__.py
│ ├── config.py # 配置管理
│ ├── main.py # FastAPI应用初始化
│ │
│ ├── agents/ # 多智能体系统
│ │ ├── __init__.py
│ │ ├── agent.py # 基础智能体类
│ │ ├── multi_agent.py # 多智能体编排
│ │ └── tools.py # MCP样式智能体工具（摘要，关键点，主题）
│ │
│ ├── api/ # REST API端点
│ │ ├── __init__.py
│ │ ├── chat.py # 聊天端点
│ │ ├── history.py # 历史管理
│ │ ├── upload.py # 文档上传
│ │ └── user.py # 用户管理
│ │
│ ├── database/ # 数据库层
│ │ ├── __init__.py
│ │ ├── models.py # Pydantic/MongoDB模型
│ │ └── mongodb.py # MongoDB连接与查询
│ │
│ ├── services/ # 核心业务逻辑
│ │ ├── __init__.py
│ │ ├── chunking.py # 文本分块服务
│ │ ├── embedding.py # 嵌入生成（句子转换器）
│ │ ├── retrieval.py # 基于FAISS的检索
│ │ ├── guardrails.py # 输入验证与安全
│ │ ├── observability.py # 日志记录与监控
│ │ └── ... # 其他服务
│ │
│ └── utils/ # 实用函数
│
├── rag-frontend/ # React前端
│ ├── package.json
│ ├── public/
│ ├── src/
│ │ ├── components/ # React组件
│ │ ├── pages/ # 页面
│ │ └── App.js
│ └── README.md
│
├── data/ # 数据存储
│ ├── uploads/ # 用户上传文件
│ ├── vector_store/ # FAISS索引
│ ├── string/ # 字符串嵌入缓存
│ └── test/ # 测试数据
│
├── mongodb_data/ # MongoDB本地存储
│
└── tests/ # 测试套件
├── __init__.py
├── test_chat.py
└── ... # 其他测试
```
---
## 🚀 安装与设置
### 先决条件
- Python 3.10+
- Node.js 16+
- MongoDB（本地或云）
- Groq API密钥
### 后端设置
#### 1. 克隆仓库并创建虚拟环境
```bash
cd ai-research-assistant
python -m venv venv
# 激活虚拟环境
# 在Windows上：
venv\Scripts\activate
# 在macOS/Linux上：
source venv/bin/activate
```
#### 2. 安装Python依赖
```bash
pip install -r requirements.txt
```
#### 3. 配置环境变量
在项目根目录创建`.env`文件：
```env
GROQ_API_KEY=your_groq_api_key
MONGODB_URI=mongodb://localhost:27017/ai_research_assistant
FAISS_INDEX_PATH=data/vector_store/
CHUNK_SIZE=512
CHUNK_OVERLAP=50
MODEL_NAME=llama-3.1-8b-instant
```
#### 4. 启动MongoDB（如果使用本地实例）
```bash
# 确保MongoDB正在运行
mongod
```
#### 5. 初始化FAISS索引与嵌入
```bash
python app/services/embedding.py --initialize
```
#### 6. 运行FastAPI后端
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### 前端设置
#### 1. 导航到前端目录
```bash
cd rag-frontend
```
#### 2. 安装依赖
```bash
npm install
```
#### 3. 配置API端点
更新`.env`或`src/config.js`：
```javascript
REACT_APP_API_URL=http://localhost:8000/api
```
#### 4. 启动开发服务器
```bash
npm start
```
应用程序将在`http://localhost:3000`可用。
---
## 💡 工作原理
### 逐步查询处理流程
```
1. 用户上传文档
│
├─ PDF/TXT解析
├─ 文本提取
└─ 元数据存储在MongoDB中
2. 文本预处理
│
├─ 分块（512个令牌，50个重叠）
├─ 句子转换器嵌入
└─ FAISS索引存储
3. 用户提问
│
├─ 输入验证（防护措施）
├─ 安全检查（内容过滤）
└─ 发出到多智能体系统
4. 规划智能体
│
└─ 分析查询意图
└─ 路由到检索智能体
5. 检索智能体
│
├─ 嵌入用户查询
├─ FAISS相似性搜索（top-k块）
└─ 返回上下文
6. 处理智能体
│
├─ 组装提示与上下文
├─ 应用总结/提取（如有需要）
└─ 准备LLM
7. LLM推理
│
├─ Groq API调用（LLaMA 3）
├─ RAG增强生成
└─ 响应流式传输
8. 响应与历史
│
├─ 返回答案给用户
├─ 存储对话在MongoDB中
└─ 记录可观察性指标
```
---
## 📊 示例查询与输出
### 示例1：文档总结
**文档**：关于“机器学习在医疗保健中的应用”的研究论文
**用户查询**：`总结论文中的关键发现`
**智能体流程**：
- 规划器 → 检测总结任务
- 检索器 → 获取所有相关部分
- 处理器 → 应用总结工具
- LLM → 生成简洁的总结
**输出**：
```
论文确定了机器学习在医疗保健中的5个关键突破：
1. 提高了诊断准确率（95.3% vs 87% 基线）
2. 降低了计算需求
3. 增强了临床使用的可解释性
...
```
### 示例2：主题提取
**用户查询**：`这些文档涵盖了哪些主要主题？`
**输出**：
```
已识别文档中的主题：
- 机器学习算法（23%）
- 临床应用（18%）
- 数据隐私与伦理（15%）
- 性能基准（12%）
- 未来方向（32%）
```
### 示例3：复杂推理
**用户查询**：`如果更改隐私法规，文档会有什么影响？`
**智能体流程**：
- 规划器 → 复杂推理任务
- 检索器 → 多块检索
- 处理器 → 上下文组装
- LLM → 生成分析
---
## 🛡️ 防护措施与安全
### 输入验证
```python
✓ 空输入检测
✓ 最大输入长度强制执行
✓ 特殊字符过滤
✓ SQL注入预防
✓ 跨站脚本（XSS）预防
```
### 内容安全
- 使用启发式过滤器检测不安全内容
- 查询意图验证
- 响应适当性检查
### 实现
参见`app/services/guardrails.py`以获取实现细节。
---
## 📊 可观察性与日志记录
### 结构化日志记录
系统在所有管道阶段实施了全面的日志记录：
```python
# 查询日志记录
logger.info("收到查询", extra={
"user_id": user_id,
"query_length": len(query),
"timestamp": datetime.utcnow()
})
# 检索日志记录
logger.info("FAISS检索完成", extra={
"chunks_retrieved": k,
"similarity_scores": scores,
"retrieval_time_ms": elapsed_time})
# LLM日志记录
logger.info("LLM推理完成", extra={
"model": "llama-3.1-8b-instant",
"tokens_generated": output_tokens,
"latency_ms": inference_time
})
```
### 跟踪指标
- 查询量与分布
- 检索延迟与准确率
- LLM响应质量
- 错误率与类型
- 用户参与模式
参见`app/services/observability.py`以获取完整实现。
---
## 🎯 实现的关键概念
- ✔ 检索增强生成（RAG）
- ✔ 多智能体系统
- ✔ MCP（模型上下文协议）
- ✔ 智能体AI框架
- ✔ 防护措施（输入验证与安全）
- ✔ 可观察性（日志记录与监控）
- ✔ 单元测试（pytest）
## 🎥 演示流程
### 1️⃣ 首页
- 用户登录首页
- 导航：登录、注册、仪表盘
### 2️⃣ 登录与注册
- 新用户注册
- 现有用户登录
- 存储用户ID以进行个性化
### 3️⃣ 文档上传
- 上传PDF/TXT
- 文本提取 → 分块 → 嵌入 → FAISS存储
### 4️⃣ 提问
- 用户输入查询
- 示例：
- "总结文档"
- "给出关键点"
- "主题是什么？"
### 5️⃣ 响应生成（RAG + 智能体 + MCP）
用户查询
↓
规划器
↓
检索器（RAG）
↓
处理器
↓
LLM（Groq - LLaMA 3）
- 上下文感知响应生成
### 6️⃣ 聊天历史
- 存储在数据库中
- 用户可以查看过去的聊天记录
## ✅ 测试
### 运行测试
```bash
# 运行所有测试
pytest
# 运行覆盖率
pytest --cov=app tests/
# 运行特定测试文件
pytest tests/test_chat.py -v
```
### 测试覆盖率
- 单元测试智能体、服务和实用程序
- 集成测试RAG管道
- API端点测试
- 数据库操作测试
### 配置
参见`pytest.ini`以获取pytest配置。
---
## 🚀 Live Capabilities
- 实时文档问答
- 智能总结
- 上下文推理
- 多智能体决策
---
## 🚀 Future Improvements
- [ ] **多语言支持** - 支持多语言文档
- [ ] **高级缓存** - 常见查询的LLM响应缓存
- [ ] **微调管道** - 自定义领域数据模型微调
- [ ] **实时协作** - WebSocket支持的协作文档分析
- [ ] **移动应用** - 原生移动应用
---
## 👤 作者
**Hafzafarzana**
人工智能与数据科学学生
如有问题或贡献，请开启问题或提交拉取请求。
---
## 📄 许可证
本项目使用 **MIT 许可证** 授权 - 详见 LICENSE 文件。
---
<div align="center">
**使用FastAPI、React和先进的AI技术构建 ❤️**
[⭐ 如果您觉得这个仓库有用，请给它点个星！](https://github.com)
</div>
---
## 📸 截图 / 实现
### 首页
<p align="center">
<img src="implementation_img/home_page.png" width="800"/>
</p>
### 登录页面
<p align="center">
<img src="implementation_img/login_page.png" width="800"/>
</p>
### 注册页面
<p align="center">
<img src="implementation_img/signup_page.png" width="800"/>
</p>
### 仪表盘页面
<p align="center">
<img src="implementation_img/dashboard_page.png" width="800"/>
</p>
### 聊天界面
<p align="center">
<img src="implementation_img/chat_page.png" width="800"/>
</p>
### 历史页面
<p align="center">
<img src="implementation_img/history_page.png" width="800"/>
</p>
### 系统架构
<p align="center">
<img src="implementation_img/architecture_diagram.png" width="800"/>
</p>
### 实现视图
<p align="center">
<img src="implementation_img/implementation.png" width="800"/>
</p>
连接信息
猜你喜欢
暂无推荐服务器