【通用智能体】Search Tools：Open Deep Research 项目实战指南

一、项目运行方式

（一）运行环境要求

• Node.js：需要安装 Node.js 20+ 版本，建议从Node.js 官网下载并安装。
• 包管理工具：可选择 npm、yarn、pnpm 或 bun 中的任意一种，用于安装项目依赖。

（二）运行方式

项目提供了两种运行方式，分别是传统本地运行和 Docker 容器运行，以下是详细步骤：

（三）传统本地运行

1. 克隆仓库
   • 打开终端或命令行工具，运行以下命令克隆项目仓库：

   git clone https://github.com/btahir/open-deep-research
   cd open-deep-research
   

2. 安装依赖
   • 根据你选择的包管理工具，运行以下命令之一安装项目依赖：

   npm install
   # 或
   yarn install
   # 或
   pnpm install
   # 或
   bun install
   

3. 配置环境变量
   • 在项目根目录下创建 .env.local 文件，并根据项目需求填写相应的 API 密钥等配置信息。例如：

   # Google Gemini Pro API key (required for AI report generation)
   GEMINI_API_KEY=your_gemini_api_key# OpenAI API key (optional - required only if OpenAI models are enabled)
   OPENAI_API_KEY=your_openai_api_key# Upstash Redis (required for rate limiting)
   UPSTASH_REDIS_REST_URL=your_upstash_redis_url
   UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_token# Bing Search API (Optional - if using Bing as search provider)
   AZURE_SUB_KEY="your-azure-subscription-key"# Google Custom Search API (Optional - if using Google as search provider)
   GOOGLE_SEARCH_API_KEY="your-google-search-api-key"
   GOOGLE_SEARCH_CX="your-google-search-cx"
   

   • 注意：你只需要提供计划使用的平台的 API 密钥。如果某个平台在配置中启用但未提供 API 密钥，该平台的模型将在 UI 中显示为禁用状态。
4. 启动开发服务器
   • 根据你使用的包管理工具，运行以下命令之一启动开发服务器：

   npm run dev
   # 或
   yarn dev
   # 或
   pnpm dev
   # 或
   bun dev
   

   • 启动成功后，打开浏览器访问 http://localhost:3000 即可查看项目运行效果。

（四）Docker 容器运行

1. 构建 Docker 镜像
   • 在项目根目录下运行以下命令构建 Docker 镜像：

   docker build -t open-deep-research:v1 .
   

2. 运行 Docker 容器
   • 运行以下命令启动 Docker 容器：

   docker run -p 3000:3000 open-deep-research
   

   • 同样，打开浏览器访问 http://localhost:3000 即可访问项目。

二、操作步骤

（一）使用搜索功能

1. 输入搜索关键词
   • 在项目首页的搜索框中输入你想要搜索的关键词，例如“人工智能发展趋势”。
2. 选择搜索结果
   • 点击搜索按钮后，应用会调用配置的搜索提供商（Google Custom Search 或 Bing Search API）获取搜索结果，并显示在页面上。你可以浏览搜索结果，选择你感兴趣的几个结果。
3. 生成报告
   • 选择完搜索结果后，点击“Generate Report”按钮，应用将根据你选择的 AI 模型（如 Google Gemini、OpenAI GPT 等）和搜索结果生成详细的报告。

（二）使用本地文件功能

1. 上传本地文件
   • 点击搜索界面中的上传按钮（⬆️），选择你想要分析的本地文件，支持 TXT、PDF 和 DOCX 格式。
   • 例如，你可以上传一篇关于人工智能的学术论文。
2. 生成报告
   • 上传的文件将作为自定义来源出现在搜索结果中，你可以选择它并点击“Generate Report”按钮，应用将根据文件内容和你选择的 AI 模型生成报告。

（三）使用知识库功能

1. 保存报告
   • 生成报告后，你可以点击“Save to Knowledge Base”按钮将报告保存到知识库中。报告将保存在浏览器的本地存储中，包括报告的完整内容、原始搜索查询、源 URL 和生成时间戳等信息。
2. 访问知识库
   • 通过界面中的知识库按钮打开知识库侧边栏，你可以在这里查看和加载你之前保存的所有报告，方便你随时回顾和参考。

（四）使用流程功能（Flow）

1. 创建研究流程
   • 在 Flow 界面中，输入初始研究查询，例如“人工智能在医疗领域的应用”。
2. 生成报告和后续问题
   • 根据你的查询，应用会生成相关的报告，并基于报告内容为你推荐后续的研究问题，例如“人工智能在疾病诊断中的准确性”。
3. 深入探索和整合报告
   • 你可以从这些后续问题中选择一个继续深入研究，生成新的报告。最终，你可以将多个相关的报告整合为一个综合的最终报告，全面总结你的研究成果。

三、常见问题及解决方法

（一）API 密钥相关问题

• 问题：在运行项目时，提示某些 API 密钥未配置或无效。
• 解决方法：确保你已经正确填写了 .env.local 文件中的所有必要的 API 密钥，并且密钥是有效的。如果某个平台的 API 密钥你暂时不需要使用，可以在配置文件中将该平台的 enabled 属性设置为 false，这样即使没有配置密钥，也不会影响项目的其他功能。

（二）搜索结果不准确或不相关

• 问题：搜索结果与你的搜索关键词不相关，或者结果数量较少。
• 解决方法：检查搜索提供商的配置是否正确。你可以尝试切换搜索提供商（如从 Google 切换到 Bing 或反之），看看是否能获取更准确的结果。此外，确保你的搜索关键词足够具体，避免使用过于宽泛的词汇。

（三）报告生成缓慢或失败

• 问题：报告生成过程非常缓慢，或者直接失败。
• 解决方法：首先，检查你选择的 AI 模型是否适合你的查询。有些模型可能在处理某些类型的查询时表现不佳。如果报告生成时间过长，可以尝试增加服务器无服务器函数的持续时间限制（如在 Vercel 部署时修改 vercel.json 文件或在路由文件中设置 maxDuration）。如果问题仍然存在，可能是 AI 平台的服务器负载过高或网络问题，稍后再试或联系平台的客服。

（四）知识库存储问题

• 问题：保存到知识库的报告丢失或无法加载。
• 解决方法：知识库是基于浏览器的本地存储实现的，因此报告会保存在你的浏览器中。如果你更换了浏览器或清除了浏览器缓存，可能会导致报告丢失。为了避免这种情况，建议定期将重要的报告导出为 PDF、Word 或文本格式进行备份。

（五）Docker 运行问题

• 问题：在使用 Docker 运行项目时，容器无法正常启动或访问。
• 解决方法：确保你的 Docker 环境正常运行，并且你已经正确构建了 Docker 镜像。检查 Docker 容器的日志，查看是否有错误信息。如果端口冲突，可以尝试更改映射的端口，例如将 -p 3000:3000 改为 -p 3001:3000，然后访问 http://localhost:3001。

（六）本地开发问题

• 问题：在本地开发过程中，修改代码后无法立即看到效果，或者开发服务器报错。
• 解决方法：确保你已经正确安装了所有依赖，并且按照项目的开发文档进行了配置。如果开发服务器报错，可以根据错误信息进行排查。常见的问题包括语法错误、依赖版本不兼容等。对于语法错误，仔细检查你的代码；对于依赖版本问题，可以尝试更新或降级相关依赖。

四、总结

Open Deep Research 是一个功能强大的开源研究工具，通过简单的配置和操作，你可以快速上手并利用它进行高效的研究和报告生成。无论是通过网络搜索还是本地文件分析，它都能为你提供丰富的功能支持。在使用