# research-agent

**Repository Path**: wangshuzhang_admin/research-agent

## Basic Information

- **Project Name**: research-agent
- **Description**: 深度研究助手是一个基于大语言模型的智能研究智能体系统，能够自主规划研究任务、执行多引擎搜索、提取和精炼内容，并生成结构化的研究报告。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 深度研究助手 (Research Agent)

## 项目简介

深度研究助手是一个基于大语言模型的智能研究智能体系统，能够自主规划研究任务、执行多引擎搜索、提取和精炼内容，并生成结构化的研究报告。

### 核心功能

- **智能任务规划**：将复杂的研究主题自动分解为多个子任务
- **多引擎并行搜索**：支持百度、DuckDuckGo、Google Serper、Tavily 等多个搜索引擎
- **内容智能提取**：自动提取网页内容并使用 LLM 进行精炼和重排序
- **结构化报告生成**：基于任务摘要生成完整的研究报告
- **流式实时响应**：支持 SSE 流式输出，实时展示研究进度
- **完整数据追溯**：记录所有搜索结果和来源，方便验证和引用

## 项目效果

![主题研究](document/主题研究.png)

![报告生成](document/报告生成.png)

### 你可以直接在线观看项目演示及引导视频：

[📹 点击观看演示视频](https://gitee.com/kenneyzzz/research-agent/raw/master/research-agent.mp4)


## 为什么需要深度研究助手

在信息爆炸的时代，我们每天都需要快速了解新的技术、概念或事件。传统的研究方式有几个痛点：

- **信息过载**：搜索引擎返回成千上万的结果，你需要逐个点开链接，阅读大量内容，才能找到有用的信息
- **缺少结构**：即使找到了相关信息，这些信息往往是碎片化的，缺少系统性的组织
- **重复劳动**：每次研究新主题时，都需要重复"搜索→阅读→总结→整理"的过程

这就是深度研究助手需要解决的问题。它不仅仅是一个搜索工具，而是一个能够自主规划、执行和总结的研究助手。

### 核心价值

- **节省时间**：将 1-2 小时的研究工作压缩到 5-10 分钟
- **提高质量**：系统化的研究流程，避免遗漏重要信息
- **可追溯**：记录所有搜索结果和来源，方便验证和引用
- **可扩展**：可以轻松添加新的搜索引擎、数据源和分析工具

## 功能特性

- **任务规划**：将研究主题智能分解为多个子任务
- **并行搜索**：支持多搜索引擎并行检索（百度、DuckDuckGo、Google Serper、Tavily）
- **内容提取**：自动提取网页内容并进行 LLM 精炼
- **任务摘要**：为每个任务生成摘要
- **报告生成**：基于任务摘要生成完整研究报告
- **流式响应**：支持 SSE 流式输出，实时展示研究进度
- **数据持久化**：完整的研究流程数据存储和查询

## 技术栈

- **Web框架**：FastAPI
- **LLM框架**：LangChain
- **数据库**：MySQL + SQLAlchemy ORM
- **搜索引擎**：百度搜索、DuckDuckGo、Google Serper、Tavily
- **内容提取**：Markitdown、Crawl4AI、Firecrawl、Playwright
- **日志**：Loguru
- **依赖管理**：Poetry

## 项目结构

```
research-server/
├── src/
│   ├── agent/          # 智能体模块
│   │   ├── planner_agent.py          # 任务规划智能体
│   │   ├── task_summarizer_agent.py  # 任务摘要智能体
│   │   ├── report_writer_agent.py    # 报告生成智能体
│   │   └── research_agent.py         # 研究流程编排
│   ├── api/            # API路由
│   │   └── research.py # 研究相关接口
│   ├── config/         # 配置管理
│   │   └── config.py   # 环境变量配置
│   ├── db/             # 数据库模块
│   │   ├── database.py # 数据库连接
│   │   └── models/     # 数据模型
│   ├── model/          # 模型定义
│   │   ├── agent_model.py # Agent数据模型
│   │   ├── model.py       # LLM模型封装
│   │   └── rerank_model.py # 重排序模型
│   ├── prompt/         # 提示词模板
│   ├── tool/           # 工具模块
│   │   └── search/     # 搜索引擎实现
│   ├── util/           # 工具函数
│   └── main.py         # 应用入口
└── pyproject.toml      # 项目配置
```

## 环境要求

- Python >= 3.11, < 4.0
- Node.js >= 16.0（前端项目）
- MySQL 数据库
- Poetry（后端依赖管理）
- npm 或 yarn（前端依赖管理）

## 环境变量配置

### 必需的环境变量

- `LLM_API_KEY`：大模型 API 密钥
- `LLM_BASE_URL`：大模型服务地址
- `LLM_MODEL_ID`：模型 ID
- `LLM_RERANK_API_KEY`：重排序模型 API 密钥
- `LLM_RERANK_URL`：重排序服务 URL
- `LLM_RERANK_MODEL`：重排序模型名称
- `DATABASE_URL`：数据库连接字符串（格式：`mysql+pymysql://user:password@host:port/database?charset=utf8mb4`）

  或者分别设置以下变量：
  - `DB_HOST`：数据库主机（默认：localhost）
  - `DB_PORT`：数据库端口（默认：3306）
  - `DB_USER`：数据库用户名（默认：root）
  - `DB_PASSWORD`：数据库密码（默认：123456）
  - `DB_NAME`：数据库名称（默认：research_db）

### 可选的环境变量

- `SERPER_API_KEY`：Google Serper API 密钥
- `TAVILY_API_KEY`：Tavily API 密钥
- `SEARCH_NUM`：检索结果数量（默认：3）
- `USE_MOCK_DEBUG`：是否使用模拟调试模式（默认：false）
- `LOG_LEVEL`：日志级别（默认：INFO）
- `LOG_FILE`：日志文件路径（可选）

## 安装部署

### 1. 安装 Poetry

```bash
# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# macOS/Linux
curl -sSL https://install.python-poetry.org | python3 -
```

### 2. 克隆项目

```bash
git clone <repository-url>
cd research-agent
```

### 3. 安装后端依赖

```bash
cd research-server
poetry install
```

### 4. 安装前端依赖

```bash
cd ../research-web
npm install
```

### 5. 配置环境变量

创建 `.env` 文件并配置必要的环境变量：

```env
# LLM 配置
LLM_API_KEY=your_llm_api_key
LLM_BASE_URL=https://api.example.com/v1
LLM_MODEL_ID=your_model_id

# 重排序模型配置
LLM_RERANK_API_KEY=your_rerank_api_key
LLM_RERANK_URL=https://rerank.example.com
LLM_RERANK_MODEL=your_rerank_model

# 数据库配置（方式一：使用完整 URL）
DATABASE_URL=mysql+pymysql://user:password@localhost:3306/research_db?charset=utf8mb4

# 数据库配置（方式二：分别设置）
# DB_HOST=localhost
# DB_PORT=3306
# DB_USER=root
# DB_PASSWORD=your_password
# DB_NAME=research_db

# 可选配置
SERPER_API_KEY=your_serper_api_key
TAVILY_API_KEY=your_tavily_api_key
SEARCH_NUM=3
LOG_LEVEL=INFO
```

### 6. 初始化数据库

数据库表结构会在首次运行时自动创建，也可以手动初始化：

```bash
cd research-server
poetry run python -c "from src.db.database import init_database, create_tables; init_database(); create_tables()"
```

### 7. 启动后端服务

```bash
cd research-server
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000
```

后端服务启动后，可以访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/ping

### 8. 启动前端服务

在新的终端窗口中：

```bash
cd research-web
npm run dev
```

前端服务启动后，可以访问：
- 前端应用：http://localhost:5174

**注意**：如果后端服务不在 `http://localhost:8000`，需要在前端项目根目录创建 `.env` 文件配置后端 API 地址：

```env
VITE_API_BASE_URL=http://your-backend-host:8000
```

## API 文档

### 主要接口

#### 1. 流式执行研究任务

```http
POST /api/research/stream
Content-Type: application/json

{
  "topic": "研究主题",
  "search_engine": ["baidu", "ddg"]  // 可选，默认使用百度搜索
}
```

返回：SSE 流式响应，包含研究进度和结果

#### 2. 获取研究列表

```http
GET /api/research/list?page=1&page_size=10
```

返回：分页的研究请求列表

#### 3. 获取研究详情

```http
GET /api/research/detail/{research_request_id}
```

返回：包含任务列表、搜索结果和报告的完整研究详情

#### 4. 获取可用搜索引擎列表

```http
GET /api/research/search-engines
```

返回：所有可用的搜索引擎列表

#### 5. 删除研究请求

```http
DELETE /api/research/{research_request_id}
```

删除研究请求及其所有关联数据

#### 6. 健康检查

```http
GET /ping
```

返回：`{"status": "ok"}`

## 数据库模型

系统使用以下数据模型存储研究流程数据：

- **ResearchRequest**：研究请求表，存储研究主题、状态等信息
- **Task**：任务表，存储规划的子任务信息
- **Report**：报告表，存储最终生成的研究报告
- **SearchInfo**：搜索信息表，记录每次搜索的查询和引擎信息
- **SearchResult**：搜索结果表，存储搜索返回的 URL 和标题
- **SummarizerResult**：总结结果表，存储每个任务的摘要内容

## 工作流程

1. **接收研究请求**：用户提交研究主题和搜索引擎选择
2. **任务规划**：`PlannerAgent` 将主题分解为多个子任务，并保存到数据库
3. **并行执行任务**：`TaskSummarizerAgent` 并行处理每个任务：
   - 多引擎并行搜索
   - 提取网页内容
   - LLM 重排序和精炼
   - 生成任务摘要
4. **生成报告**：`ReportWriterAgent` 基于所有任务摘要生成最终报告
5. **流式返回**：每个阶段的进度和结果通过 SSE 流式返回给客户端

## 开发说明

### 代码结构

- **agent/**：智能体模块，包含规划、摘要、报告生成等核心逻辑
- **api/**：FastAPI 路由定义，处理 HTTP 请求
- **config/**：配置管理，从环境变量读取配置
- **db/**：数据库模型和连接管理
- **model/**：数据模型定义和 LLM 模型封装
- **prompt/**：提示词模板
- **tool/**：工具模块，包括搜索引擎实现
- **util/**：工具函数，如 URL 内容提取

### 扩展搜索引擎

要添加新的搜索引擎，需要：

1. 在 `src/tool/search/` 目录下创建新的搜索引擎类，继承 `BaseSearchEngine`
2. 实现 `perform_search` 方法
3. 在 `src/tool/search/__init__.py` 中注册新引擎
4. 在 `src/model/agent_model.py` 的 `SearchEngine` 枚举中添加新引擎

### 调试模式

设置环境变量 `USE_MOCK_DEBUG=true` 可以启用模拟调试模式，使用预设的模拟数据，避免实际调用 LLM 和搜索引擎。

## 许可证

详见 [LICENSE](LICENSE) 文件。