# DeepResearch

**Repository Path**: dirty_up/deep-research

## Basic Information

- **Project Name**: DeepResearch
- **Description**: 基于 Zilliz 开源项目改进的智能深度检索系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSearcher - 智能深度检索系统

![DeepSearcher](./assets/pic/logo.png)

<div align="center">
  
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/zilliz_universe.svg?style=social&label=Follow%20%40Zilliz)](https://twitter.com/zilliz_universe)
<a href="https://discord.gg/mKc3R95yE5"><img height="20" src="https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge&logo=discord&logoColor=white" alt="discord"/></a>

</div>

---

## 项目概述

DeepSearcher 是一个基于 Zilliz 开源项目改进的智能深度检索系统，主要提升了生成报告的质量并增加了在线搜索能力。系统采用混合检索架构，结合传统向量检索和 Agentic 深度分析，支持基于模糊位置信息的智能检索。

## 核心特性

### 🔍 混合检索架构
- **传统向量检索**: 快速筛选相关候选文档
- **Agentic深度分析**: 对候选文档进行智能深度分析
- **位置感知检索**: 支持基于模糊位置信息的精确检索
- **智能重排序**: 结合相似度和位置匹配度进行结果重排序

### 🎯 智能路由系统
- **自动分析查询特征**: 使用LLM分析查询的复杂度、类型和需求
- **智能选择RAG方法**: 根据分析结果自动选择最合适的RAG代理
- **多种RAG方法支持**: NaiveRAG、ChainOfRAG、DeepSearch、HybridRAG、OnlineDeepSearch
- **查询类型识别**: search、question、report、compare

### 📍 位置信息支持
- **多种位置格式**: 支持页码、章节、段落、字符位置等多种位置信息
- **模糊匹配**: 支持±2页的模糊位置匹配
- **位置统计**: 提供详细的位置覆盖统计信息
- **智能解析**: 自动从查询中提取和分离位置信息

### 🚀 性能优化
- **分层处理**: 根据内容量自动选择最优处理策略
- **Token管理**: 智能的Token使用和批处理
- **缓存机制**: 避免重复计算
- **异步处理**: 支持高并发查询

## 系统架构

### 核心技术框架

```mermaid
graph TD
    %% 1. 基础服务层 (最底层)
    subgraph "基础服务层 (Basic Services Layer)"
        J1[算力服务 - LLM API]
        J2[模型服务 - 嵌入模型]
        J3[数据服务 - 向量数据库]
        J4[网络服务 - 搜索引擎]
    end

    %% 2. 平台业务功能层
    subgraph "平台业务功能层 (Platform Business Functions Layer)"
        G1[智能体管理]
        G2[用户管理]
        G3[配置管理]
        G4[日志管理]
        G5[监控管理]
    end

    %% 3. 用户接口层
    subgraph "用户接口层 (User Interface Layer)"
        A1[WebSocket API]
        A2[REST API]
        A3[FastAPI 服务器]
        A4[WebSocket 流式响应]
    end

    %% 4. 智能体应用编排层
    subgraph "智能体应用编排层 (Agent Orchestration Layer)"
        B1[查询类型分析]
        B2[子查询分解]
        B3[智能体路由选择]
        B4[多模式处理]
        B5[结果整合]
    end

    %% 5. 核心处理引擎层
    subgraph "核心处理引擎层 (Core Processing Engine Layer)"
        H1[DeepSearch 智能体]
        H2[OnlineDeepSearch 智能体]
        H3[NaiveRAG 智能体]
        H4[RAGRouter 路由器]
        H5[CollectionRouter 集合路由]
    end

    %% 6. 数据处理流程层 (最顶层)
    subgraph "数据处理流程层 (Data Processing Pipeline Layer)"
        I1[文档加载]
        I2[内容解析]
        I3[智能分块]
        I4[向量化嵌入]
        I5[向量存储]
        I6[相似度检索]
        I7[结果重排序]
        I8[内容生成]
    end

    %% 智能体构建引擎 (横向支撑)
    subgraph "智能体构建引擎 (Agent Construction Engine)"
        %% 提示词库
        subgraph "提示词库 (Prompt Library)"
            C1[查询分析提示词]
            C2[内容架构规划提示词]
            C3[分层处理提示词]
            C4[质量评估提示词]
            C5[多模式专用提示词]
        end

        %% 专家知识库
        subgraph "专家知识库 (Expert Knowledge Base)"
            D1[文档解析引擎]
            D2[多模态内容提取]
            D3[智能分块切分]
            D4[位置信息保留]
            D5[元数据管理]
            D6[知识去重]
        end

        %% 算法仓
        subgraph "算法仓 (Algorithm Warehouse)"
            E1[分层处理算法]
            E2[Token管理算法]
            E3[信息增益计算]
            E4[相似度计算]
            E5[重排序算法]
        end

        %% 插件库
        subgraph "插件库 (Plugin Library)"
            F1[文件加载器插件]
            F2[网络爬虫插件]
            F3[嵌入模型插件]
            F4[向量数据库插件]
            F5[LLM模型插件]
        end
    end

    %% 外部服务集成
    subgraph "外部服务集成 (External Services)"
        K1[Kimi LLM API]
        K2[SiliconFlow 嵌入API]
        K3[Milvus 向量数据库]
        K4[SearxNG 搜索引擎]
        K5[DeepSeek API]
    end

    %% 纵向连接关系 (从下到上)
    J1 --> G1
    J2 --> G2
    J3 --> G3
    J4 --> G4

    G1 --> A1
    G2 --> A2
    G3 --> A3
    G4 --> A4

    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B1

    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> B5

    B3 --> H4
    H4 --> H1
    H4 --> H2
    H4 --> H3

    H1 --> I1
    H2 --> I1
    H3 --> I1

    %% 数据处理流程连接
    I1 --> I2
    I2 --> I3
    I3 --> I4
    I4 --> I5
    I5 --> I6
    I6 --> I7
    I7 --> I8

    %% 智能体构建引擎支撑连接
    H1 --> C1
    H1 --> C2
    H1 --> C3
    H1 --> C4
    H1 --> C5

    H1 --> D1
    H1 --> D2
    H1 --> D3
    H1 --> D4
    H1 --> D5
    H1 --> D6

    H1 --> E1
    H1 --> E2
    H1 --> E3
    H1 --> E4
    H1 --> E5

    H1 --> F1
    H1 --> F2
    H1 --> F3
    H1 --> F4
    H1 --> F5

    %% 插件到数据处理流程的连接
    F1 --> I1
    F2 --> I1
    F3 --> I4
    F4 --> I5
    F4 --> I6
    F5 --> I8

    %% 外部服务连接
    J1 --> K1
    J1 --> K5
    J2 --> K2
    J3 --> K3
    J4 --> K4

    %% 样式定义
    classDef basicServiceLayer fill:#e8f5e8
    classDef platformLayer fill:#fff3e0
    classDef userLayer fill:#e1f5fe
    classDef orchestrationLayer fill:#f3e5f5
    classDef processingLayer fill:#e8f5e8
    classDef dataLayer fill:#fce4ec
    classDef engineLayer fill:#fff3e0
    classDef externalLayer fill:#f1f8e9

    class J1,J2,J3,J4 basicServiceLayer
    class G1,G2,G3,G4,G5 platformLayer
    class A1,A2,A3,A4 userLayer
    class B1,B2,B3,B4,B5 orchestrationLayer
    class H1,H2,H3,H4,H5 processingLayer
    class I1,I2,I3,I4,I5,I6,I7,I8 dataLayer
    class C1,C2,C3,C4,C5,D1,D2,D3,D4,D5,D6,E1,E2,E3,E4,E5,F1,F2,F3,F4,F5 engineLayer
    class K1,K2,K3,K4,K5 externalLayer
```

## 快速开始

### 1. 安装依赖

```bash
# 使用 uv 包管理器（推荐）
uv sync

# 或使用传统方式
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python main.py
```

### 3. 使用混合检索API

#### REST API

```python
import requests

# 基础混合检索
response = requests.post("http://localhost:8000/hybrid-search/", json={
    "query": "什么是深度学习？",
    "collection_name": "knowledge_1"
})

# 位置感知检索
response = requests.post("http://localhost:8000/location-search/", json={
    "query": "深度学习的应用",
    "location_hint": "第5页",
    "collection_name": "knowledge_1"
})
```

#### WebSocket API

```javascript
const ws = new WebSocket('ws://localhost:8000/ws/query');

ws.send(JSON.stringify({
    "query": "神经网络的结构",
    "type": "hybrid",
    "collection_name": "knowledge_1"
}));
```

## 功能模块

### 1. 智能路由系统

智能RAG路由系统是一个自动化的检索增强生成（RAG）路由解决方案，能够根据用户查询的特征自动选择最合适的RAG方法。

#### 核心功能
- **自动分析查询特征**：使用LLM分析查询的复杂度、类型和需求
- **智能选择RAG方法**：根据分析结果自动选择最合适的RAG代理
- **支持强制指定**：允许用户强制指定特定的RAG方法
- **多种RAG方法支持**：NaiveRAG、ChainOfRAG、DeepSearch、HybridRAG、OnlineDeepSearch

#### API接口

```http
POST /smart-search/
Content-Type: application/json

{
    "query": "用户查询",
    "collection_name": "知识库名称",
    "force_rag_method": "可选：强制指定RAG方法",
    "enable_web_search": true,
    "enable_location_search": true
}
```

### 2. 混合检索架构

混合检索架构结合了传统向量检索和Agentic深度分析，同时支持基于模糊位置信息的智能检索。

#### 核心特性
- **传统向量检索**: 快速筛选相关候选文档
- **Agentic深度分析**: 对候选文档进行智能深度分析
- **位置感知检索**: 支持基于模糊位置信息的精确检索
- **智能重排序**: 结合相似度和位置匹配度进行结果重排序

#### 位置信息格式

| 格式 | 示例 | 说明 |
|------|------|------|
| 页码 | `第5页`, `5页`, `page 5` | 指定页码 |
| 章节 | `第3章`, `3章`, `chapter 3` | 指定章节 |
| 段落 | `第2段`, `2段`, `paragraph 2` | 指定段落 |
| 字符位置 | `字符[1000-2000]`, `pos 1000-2000` | 指定字符范围 |
| 行号 | `第10行`, `10行`, `line 10` | 指定行号 |

### 3. 任务控制中心

系统实现了任务控制中心RAG选择功能，用户发送消息后思考内容默认为展开状态，在右侧任务控制中心中可以选择返回的RAG方法。

#### 功能特性
- **任务控制中心RAG选择器**: 在右侧任务控制中心显示RAG方法选择器
- **思考内容默认展开**: 发送消息后思考内容默认为展开状态
- **智能RAG选择流程**: 完整的用户交互流程

### 4. WebSocket连接保持

系统已修复WebSocket连接断开问题，现在在返回推荐RAG后，WebSocket连接会继续保存，不会重新建立新连接。

#### 修复内容
- **WebSocket连接保持**: 移除了重新建立WebSocket连接的逻辑
- **RAG选择后继续处理**: 选择RAG后使用现有连接继续处理
- **思考内容默认展开**: 思考内容默认为展开状态

## 配置选项

### 后端配置

```python
# 智能RAG路由系统配置
smart_rag_router = SmartRAGRouter(
    llm=llm,
    embedding_model=embedding_model,
    vector_db=vector_db,
    enable_web_search=True,
    enable_location_search=True
)
```

### 前端配置

```javascript
// 智能路由启用状态
const smartRoutingEnabled = ref(true)

// 知识库模式
const currentKnowledgeMode = ref({
  value: 'smart',
  label: '智能路由'
})
```

## 性能指标

### 检索性能
- **向量检索速度**: < 100ms (10个候选)
- **Agentic分析时间**: 2-5秒 (取决于内容复杂度)
- **位置匹配精度**: > 85% (模糊匹配)
- **整体响应时间**: 3-8秒 (端到端)

### 质量指标
- **答案相关性**: > 90% (基于人工评估)
- **位置准确性**: > 80% (位置匹配准确率)
- **信息完整性**: > 85% (覆盖查询要点)

## 测试和验证

### 运行测试

```bash
# 运行混合检索测试
python test_hybrid_rag.py

# 运行智能路由测试
python test_smart_rag_router.py

# 运行集成测试
python test_smart_routing_integration.py
```

### 测试内容
1. **基础混合检索**: 测试基本的语义检索功能
2. **位置感知检索**: 测试基于位置信息的检索
3. **智能路由分析**: 验证查询特征分析
4. **WebSocket查询**: 测试实时流式查询

## 评估系统

系统提供了完整的评估框架，支持多种评估指标和数据集。

### 评估指标
- **Recall@K**: 检索到的相关文档占所有相关文档的百分比
- **Token消耗**: 不同迭代次数下的Token使用情况
- **性能对比**: DeepSearcher vs 传统RAG方法

### 支持的数据集
- **2WikiMultiHopQA**: 多跳问答数据集
- 更多数据集将在未来添加

### 运行评估

```bash
python evaluate.py \
--dataset 2wikimultihopqa \
--config_yaml ./eval_config.yaml \
--pre_num 5 \
--output_dir ./eval_output
```

## 开发环境设置

### 使用 uv 包管理器

```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone https://github.com/zilliztech/deep-searcher.git && cd deep-searcher

# 同步依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate
```

### 添加依赖

```bash
# 添加新依赖
uv add <package_name>

# 添加可选依赖
uv add <package_name> --optional <extra>
```

## 贡献指南

### 开发流程

1. Fork 仓库并创建分支
2. 进行代码修改
3. 运行测试和代码检查
4. 提交 Pull Request

### 代码规范

```bash
# 检查代码风格
make lint

# 修复代码风格
make format
```

### 开发证书

所有贡献需要签署开发证书，在提交信息中添加：

```text
Signed-off-by: Your Name <your.email@example.com>
```

## 故障排除

### 常见问题

1. **服务器连接失败**
   ```bash
   # 检查Milvus服务
   docker ps | grep milvus
   
   # 检查端口占用
   netstat -tlnp | grep 8000
   ```

2. **位置信息不匹配**
   ```python
   # 检查位置模式
   from deepsearcher.agent.location_enhanced_search import LocationMatcher
   matcher = LocationMatcher()
   print(matcher.location_patterns)
   ```

3. **Token限制错误**
   ```python
   # 调整批处理大小
   hybrid_rag = HybridRAG(
       vector_search_top_k=5,  # 减少候选数
       agentic_analysis_top_k=3
   )
   ```

### 调试方法

```python
import logging
logging.basicConfig(level=logging.DEBUG)

# 启用详细日志
logger = logging.getLogger('deepsearcher.agent.hybrid_rag')
logger.setLevel(logging.DEBUG)
```

## 技术栈

- **后端框架**: FastAPI + WebSocket
- **向量数据库**: Milvus
- **嵌入模型**: SiliconFlow (BAAI/bge-m3)
- **大语言模型**: Kimi (Moonshot) + DeepSeek
- **文档处理**: pdfplumber, python-docx, pandas
- **网络搜索**: SearxNG
- **配置管理**: YAML + 环境变量

## 许可证

本项目采用 Apache 2.0 许可证。详见 [LICENSE](LICENSE) 文件。

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue: [GitHub Issues](https://github.com/zilliztech/deep-searcher/issues)
- Discord: [Zilliz Discord](https://discord.gg/mKc3R95yE5)
- Twitter: [@Zilliz](https://twitter.com/zilliz_universe)

---

**注意**: 本混合检索架构专为中文文档优化，支持多种位置信息格式，特别适合学术论文、技术文档等需要精确定位的检索场景。