# deep-research

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

## Basic Information

- **Project Name**: deep-research
- **Description**: 一款 AI 驱动的研究助手，通过搜索引擎、网页抓取和大语言模型相结合，对任意主题进行迭代式深度研究。本仓库旨在提供一个最简单的“深度研究智能体”实现——能够随时间推进不断细化研究方向，并深入挖掘主题。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Open Deep Research

一个由 AI 驱动的研究助手，通过结合搜索引擎、网页抓取和大语言模型对任何主题执行迭代式深度研究。

本仓库的目标是提供最简洁的实现方案，以展示深度研究代理的工作方式。代理可以随着时间的推移优化其研究方向并深入探索主题。我们希望仓库代码保持在 500 行以内，以便于理解和在此基础上进行开发。

如果您喜欢这个项目，请考虑给它一个 star 并在 [X/Twitter](https://x.com/dzhng) 上关注我。本项目由 [Aomni](https://aomni.com) 赞助。

## 它是如何工作的

```mermaid
flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results
```

## 特性

- **迭代研究**：通过迭代生成搜索查询、处理结果并根据发现深入探索
- **智能查询生成**：使用大语言模型 (LLM) 根据研究目标和先前发现生成有针对性的搜索查询
- **深度与广度控制**：可配置参数以控制研究的广度和深度
- **智能后续问题**：生成后续问题以更好地理解研究需求
- **全面报告**：生成包含发现和来源的详细 Markdown 报告
- **并发处理**：高效地处理多个搜索和结果并行处理

## 要求

- Node.js 环境
- API 密钥：
  - Firecrawl API (用于网络搜索和内容提取)
  - OpenAI API (用于 o3 mini 模型)

## 设置

### Node.js

1. 克隆仓库
2. 安装依赖：

```bash
npm install
```

3. 在 `.env.local` 文件中设置环境变量：

```bash
FIRECRAWL_KEY="your_firecrawl_key"
# 如果您想使用自托管的 Firecrawl，请在下方添加：
# FIRECRAWL_BASE_URL="http://localhost:3002"

OPENAI_KEY="your_openai_key"
```

要使用本地大语言模型，请注释掉 `OPENAI_KEY` 并取消注释 `OPENAI_ENDPOINT` 和 `OPENAI_MODEL`：

- 将 `OPENAI_ENDPOINT` 设置为本地服务器的地址 (例如 "http://localhost:1234/v1")
- 将 `OPENAI_MODEL` 设置为本地服务器中加载的模型名称

### Docker

1. 克隆仓库
2. 将 `.env.example` 重命名为 `.env.local` 并设置您的 API 密钥

3. 运行 `docker build -f Dockerfile`

4. 运行 Docker 镜像：

```bash
docker compose up -d
```

5. 在 docker 服务中执行 `npm run docker`：

```bash
docker exec -it deep-research npm run docker
```

## 使用方法

运行研究助手：

```bash
npm start
```

您将被提示：

1. 输入您的研究查询
2. 指定研究广度 (推荐：3-10，默认：4)
3. 指定研究深度 (推荐：1-5，默认：2)
4. 回答后续问题以优化研究方向

系统将：

1. 生成并执行搜索查询
2. 处理和分析搜索结果
3. 根据发现递归地深入探索
4. 生成全面的 Markdown 报告

最终报告将保存为工作目录中的 `report.md` 或 `answer.md`，具体取决于您选择的模式。

### 并发性

如果您拥有 Firecrawl 的付费版本或本地版本，可以通过设置 `ConcurrencyLimit` 环境变量来增加并发限制，从而使运行更快。

如果您拥有免费版本，可能会遇到速率限制错误，您可以将限制减少到 1（但这会运行得更慢）。

### DeepSeek R1

Deep research 在 R1 上表现优异！我们使用 [Fireworks](http://fireworks.ai) 作为 R1 模型的主要提供商。要使用 R1，只需设置一个 Fireworks API 密钥：

```bash
FIREWORKS_KEY="api_key"
```

当检测到密钥时，系统将自动切换到使用 R1 而不是 `o3-mini`。

### 自定义端点和模型

还有 2 个其他可选的环境变量可以让您调整端点（用于其他与 OpenAI 兼容的 API，如 OpenRouter 或 Gemini）以及模型字符串。

```bash
OPENAI_ENDPOINT="custom_endpoint"
CUSTOM_MODEL="custom_model"
```

## 它是如何工作的

1. **初始设置**

   - 接收用户查询和研究参数（广度和深度）
   - 生成后续问题以更好地了解研究需求

2. **深度研究过程**

   - 根据研究目标生成多个 SERP 查询
   - 处理搜索结果以提取关键学习点

3. **递归探索**

   - 如果深度大于 0，根据新的研究方向继续探索
   - 每次迭代都基于先前的学习成果
   - 保持研究目标和发现的上下文

4. **报告生成**
   - 将所有发现编译成全面的 Markdown 报告
   - 包括所有来源和参考文献
   - 以清晰、可读的格式组织信息

## 社区实现

**Python**: https://github.com/Finance-LLMs/deep-research-python

## 许可证

MIT License - 随意使用和修改。