• AI 应用
• AI Agent
• RAG
• 前端
• 后端

Open Deep Research 是 OpenAI Deep Research 实验的开源克隆项目，其核心思路是用 Firecrawl 为主线，结合 lib/ai/index.ts、app/(chat)/api/chat/route.ts/api/chat/route.ts) 等源码，完整讲解项目架构、模型提供商切换、一键部署、本地运行、DeepSeek/TogetherAI 依赖安装以及REASONING_MODEL推理模型配置，并深入剖析深度研究工具的执行流程与数据流实现，帮助你快速掌握部署与二次开发的关键环节。

一、项目定位与技术原理

Open Deep Research 是一个"研究型 AI Agent"：它接收一个研究主题，自主完成搜索（search）→ 提取（extract）→ 分析规划（analyze & plan）→ 综合成文（synthesis）的迭代循环，最终产出一份包含引用来源的深度分析报告。

与 OpenAI 官方方案不同，本项目不对模型做微调，而是采用两条关键路径的组合：

• Firecrawl Search + Extract：通过 Firecrawl 的搜索引擎把实时网页数据喂给 AI，并通过 extract 从多个网站提取结构化数据；
• 推理模型：负责研究分析、文档建议、数据抽取与结构化输出等需要"深思熟虑"的任务，默认使用o1-mini，可替换为o1、o3-mini、gpt-4o、DeepSeek-R1、deepseek-reasoner 等。

从 app/(chat)/api/chat/route.ts/api/chat/route.ts#L44-L55) 可以看到，聊天接口把工具分为三类：blocksTools（requestSuggestions）、firecrawlTools（search、extract、scrape）以及allTools（firecrawl 三件套 +deepResearch），其中deepResearch是真正驱动深度研究循环的编排工具。

二、核心特性与技术栈全景

README 将项目能力划分为六个方面，以下逐一结合源码展开说明。

2.1 Firecrawl Search + Extract

• Feed realtime data to the AI via search：通过搜索把实时数据输入 AI，避免模型知识陈旧；
• Extract structured data from multiple websites：通过 extract 从多个网站抽取结构化数据，供分析阶段使用。

Firecrawl 客户端在路由文件中以单例形式初始化（app/(chat)/api/chat/route.ts/api/chat/route.ts#L57-L59)）：

const app = new FirecrawlApp({ apiKey: process.env.FIRECRAWL_API_KEY || '', });

仓库还额外提供了scrape工具：当模型已经拿到具体 URL 时，直接抓取该页面的 Markdown 内容，命中率高、成本更低。三个工具的定位可以这样区分：

2.2 Next.js App Router

• 先进路由带来无缝导航与性能提升；
• React Server Components（RSCs）与 Server Actions 用于服务端渲染、提升性能。

仓库使用next15.0.3-canary 版本，采用app目录结构：app/(auth)) 存放认证相关页面与 NextAuth 配置，app/(chat)) 存放聊天主界面与全部 API 路由（chat、document、files/upload、history、suggestions、vote）。

2.3 AI SDK（Vercel AI SDK）

• 统一 API 生成文本、结构化对象与工具调用；
• 提供构建动态聊天与生成式 UI 的 Hooks；
• 支持 OpenAI（默认）、Anthropic、Cohere 及其他模型提供商。

源码中大量使用了 AI SDK 的核心能力，例如 app/(chat)/api/chat/route.ts/api/chat/route.ts) 中的streamText、streamObject、generateObject、generateText、createDataStreamResponse，前端 components/data-stream-handler.tsx 则通过useChat的 data stream 消费服务端推送的增量事件。

2.4 shadcn/ui

• 使用 Tailwind CSS 进行样式设计；
• 组件原语来自 Radix UI，兼顾无障碍与灵活性。

仓库 components/ui 目录内置了 button、card、input、select、tabs、tooltip 等全套 shadcn/ui 组件，components.json 记录了样式配置（默认使用 Tailwind + CSS 变量主题）。

2.5 数据持久化

• Vercel Postgres（Neon 驱动）：保存聊天历史与用户数据；
• Vercel Blob：高效的文件存储。

数据库层由 Drizzle ORM 管理（drizzle.config.ts），表结构定义在 lib/db/schema.ts：User、Chat、Message、Vote、Document、Suggestion六张表，聊天与文档均关联用户 ID。查询封装在 lib/db/queries.ts，通过postgres客户端直连POSTGRES_URL。

2.6 NextAuth.js 认证

• 简单且安全的认证方案。

app/(auth)/auth.ts/auth.ts) 使用 Credentials Provider 支持邮箱密码登录，并且支持匿名会话：无会话用户访问时自动创建anon_*@anonymous.user账号（lib/db/schema.ts 中密码使用 bcrypt 加盐哈希），因此无需注册即可体验深度研究。认证配置与中间件见 app/(auth)/auth.config.ts/auth.config.ts) 与 middleware.ts。

三、模型提供商配置

3.1 默认模型与切换机制

模板默认使用 OpenAI 的gpt-4o。在 lib/ai/models.ts 中定义了两个可选模型：

DEFAULT_MODEL_NAME固定为'gpt-4o'，页面通过 cookiemodel-id记忆用户选择（见 app/(chat)/page.tsx/page.tsx)）。

由于底层使用 AI SDK，切换到 Anthropic、Cohere 等提供商只需要几行代码。README 特别说明仓库兼容 OpenRouter 与 OpenAI：设置OPENROUTER_API_KEY后即可通过 OpenRouter 路由到更多模型。

3.2 提供商分发逻辑（源码级）

lib/ai/index.ts 的customModel函数体现了完整的路由决策：

export const customModel = (apiIdentifier: string, forReasoning: boolean = false) => { const hasOpenRouterKey = process.env.OPENROUTER_API_KEY && process.env.OPENROUTER_API_KEY !== "****"; const modelId = forReasoning ? getReasoningModel(apiIdentifier) : apiIdentifier; if (hasOpenRouterKey) { return wrapLanguageModel({ model: openrouter(modelId), middleware: customMiddleware }); } const model = modelId === 'deepseek-ai/DeepSeek-R1' ? togetherai(modelId) : modelId === 'deepseek-reasoner' ? deepseek(modelId) : openai(modelId); return wrapLanguageModel({ model, middleware: customMiddleware }); };

决策顺序为：

1. 若配置了有效的OPENROUTER_API_KEY（非"****"占位值），所有模型都统一走 OpenRouter；
2. 否则按模型 ID 分发：deepseek-ai/DeepSeek-R1→ TogetherAI，deepseek-reasoner→ DeepSeek，其余 → OpenAI；
3. 所有模型统一经过wrapLanguageModel包裹（中间件当前为空实现，见 lib/ai/custom-middleware.ts，属于可扩展点）。

3.3 环境变量全景

本地运行时需要 .env.example 中定义的环境变量，完整清单如下：

注意：切勿把.env文件提交到版本库，否则会泄露密钥，导致他人控制你的 OpenAI 与认证提供商账号。

四、部署与本地运行

4.1 一键部署到 Vercel

README 提供 Vercel 一键部署入口，部署时需配置四个环境变量：

• AUTH_SECRET
• OPENAI_API_KEY
• OPENROUTER_API_KEY
• FIRECRAWL_API_KEY

同时关联 Postgres 与 Blob 两个存储服务（Vercel 会自动为部署项目注入POSTGRES_URL与BLOB_READ_WRITE_TOKEN）。Upstash Redis 变量（限流用）也建议一并配置，否则 lib/rate-limit.ts 中的限流器将因缺少连接信息而无法工作。

4.2 本地运行步骤

README 给出了标准的三步流程，配合 Vercel CLI 拉取环境变量：

# 1. 安装 Vercel CLI 并链接本地实例到 Vercel/GitHub 账号（生成 .vercel 目录） npm i -g vercel vercel link # 2. 拉取环境变量（或手动复制 .env.example 为 .env 并填充） vercel env pull # 3. 安装依赖 pnpm install # 4. 执行数据库迁移 pnpm db:migrate # 5. 启动开发服务 pnpm dev

启动后访问 localhost:3000 即可使用。

数据库迁移脚本db:migrate实际执行npx tsx lib/db/migrate.ts（见 package.json 的 scripts 字段），迁移 SQL 存放在 lib/db/migrations，当前共 6 个迁移文件（0000–0005），覆盖用户、聊天、消息、投票、文档、建议等全部表结构。项目还提供db:generate、db:push、db:studio、db:check等 Drizzle 工具链命令。

4.3 模型依赖安装（DeepSeek / TogetherAI）

默认模板只内置 OpenAI 依赖，若要使用其他推理模型，需按 README 安装对应依赖：

# DeepSeek pnpm add @ai-sdk/deepseek # TogetherAI 的 DeepSeek pnpm add @ai-sdk/togetherai

在当前仓库的 package.json 中，这两个依赖已经内置（@ai-sdk/deepseek: ^0.1.8、@ai-sdk/togetherai: ^0.1.9）。README 同时提醒：TogetherAI 存在最大速率限制，请参考其官方 rate limits 文档，超出会被限流。

五、推理模型配置（REASONING_MODEL）

这是 README 中技术含量最高的部分。系统为推理任务（研究分析、结构化输出等）使用一套独立的模型，与用户对话选用的通用模型互不影响。

5.1 可用选项

5.2 关键注意事项

• 只有部分 OpenAI 模型（gpt-4o、o1、o3-mini）原生支持结构化 JSON 输出；
• 其他模型（如deepseek-reasoner）可用于推理，但可能需要关闭 JSON schema 校验；
• 使用不支持 JSON schema 的模型时：
  • 在.env中设置BYPASS_JSON_VALIDATION=true；
  • 该开关允许非 OpenAI 模型参与推理任务；
  • 注意：关闭 JSON 校验后，模型响应可能结构化程度降低；
• 推理模型用于需要结构化思考与分析的任务，包括：研究分析（research analysis）、文档建议（document suggestions）、数据抽取（data extraction）、结构化响应（structured responses）；
• 未指定REASONING_MODEL时，默认使用o1-mini；
• 指定了无效模型时，回退到o1-mini。

5.3 源码级验证

lib/ai/index.ts 用白名单 + 兜底机制实现上述全部行为：

const VALID_REASONING_MODELS = ['o1', 'o1-mini', 'o3-mini', 'deepseek-ai/DeepSeek-R1', 'deepseek-reasoner', 'gpt-4o'] as const; const JSON_SUPPORTED_MODELS = ['gpt-4o', 'gpt-4o-mini', 'o1', 'o3-mini'] as const; const REASONING_MODEL = process.env.REASONING_MODEL || 'o1-mini'; const BYPASS_JSON_VALIDATION = process.env.BYPASS_JSON_VALIDATION === 'true'; function getReasoningModel(modelId: string) { // 用户当前选择的模型本身是合法推理模型，则继续使用 if (VALID_REASONING_MODELS.includes(modelId as ReasoningModel)) { return modelId; } const configuredModel = REASONING_MODEL; // 配置了无效模型 → 回退 o1-mini 并告警 if (!VALID_REASONING_MODELS.includes(configuredModel as ReasoningModel)) { console.warn(`Invalid REASONING_MODEL "${configuredModel}", falling back to ${fallback}`); return fallback; } // 未绕过 JSON 校验且模型不支持 JSON schema → 告警 if (!BYPASS_JSON_VALIDATION && !supportsJsonOutput(configuredModel)) { console.warn(`Warning: Model ${configuredModel} does not support JSON schema. Set BYPASS_JSON_VALIDATION=true to override`); } return configuredModel; }

注意一个细节：若用户在聊天中选择的模型本身就在VALID_REASONING_MODELS白名单中（如选了gpt-4o），则推理任务直接复用该模型，否则才启用REASONING_MODEL配置。

5.4 配置示例

在.env中添加：

# 可选值：deepseek-reasoner、deepseek-ai/DeepSeek-R1 REASONING_MODEL=deepseek-reasoner # 使用不支持 JSON schema 的模型时必填 BYPASS_JSON_VALIDATION=true

推理模型是自动生效的：无论用户在通用聊天中选择哪个模型，只要应用需要结构化输出或复杂分析，就会自动切换到推理模型（lib/ai/index.ts 中forReasoning参数驱动）。

5.5 推理模型的实际应用点

在深度研究工具内部，推理模型出现在两个关键环节（app/(chat)/api/chat/route.ts/api/chat/route.ts)）：

1. 分析规划（analyzeAndPlan）：通过generateObject让推理模型产出结构化analysis对象（summary、gaps、nextSteps、shouldContinue、nextSearchTopic、urlToSearch），决定是否继续搜索及下一步方向；
2. 最终综合（final synthesis）：通过generateText让推理模型基于全部 findings 与 summaries 生成长篇深度分析，maxTokens上限 16000，并要求包含关键洞察、结论、不确定点与来源引用。

六、深度研究工具的运行机制（源码剖析）

6.1 工具定义与整体流程

deepResearch工具（app/(chat)/api/chat/route.ts/api/chat/route.ts#L692-L1038)）接收一个topic参数，内部维护一个researchState状态机，核心字段包括：

• findings：已收集的研究发现（文本 + 来源 URL）；
• summaries：每轮分析产生的摘要；
• nextSearchTopic/urlToSearch：推理模型给出的下一轮搜索方向；
• currentDepth/maxDepth：当前深度与最大深度（默认 7）；
• failedAttempts/maxFailedAttempts：连续失败次数与上限（3 次）；
• completedSteps/totalExpectedSteps：进度统计（maxDepth * 5）。

主循环为search → extract → analyze → 决定是否继续：

1. Search 阶段：app.search(searchTopic)搜索当前主题，成功后把结果写入source-delta数据流；
2. Extract 阶段：取搜索结果前 3 条 URL，加上推理模型指定的urlToSearch，并行调用app.extract提取关键信息（重点提取事实、数据与专家观点），合并为新的 findings；
3. Analyze 阶段：调用analyzeAndPlan让推理模型总结已学内容、指出 gaps、给出下一步搜索建议；若shouldContinue=false或没有剩余 gaps 则停止；
4. Synthesis 阶段：停止后调用推理模型生成最终长篇分析报告，并通过finish数据流事件回传。

此外还有两个保护机制：单次研究总时长上限 4 分 30 秒（timeLimit = 4.5 * 60 * 1000，服务端路由maxDuration = 300秒），以及连续 3 次失败自动终止循环，避免无限消耗 API 配额。

6.2 实时进度推送（Data Stream 协议）

研究过程通过数据流实时推送给前端，定义的事件类型（见 app/(chat)/api/chat/route.ts/api/chat/route.ts) 与 components/data-stream-handler.tsx）：

前端 components/data-stream-handler.tsx 消费这些事件：activity-delta与source-delta会进入 lib/deep-research-context.tsx 维护的全局状态（addActivity、addSource），最终渲染在 components/deep-research.tsx 的右侧浮层面板中——该面板包含Activity与Sources两个标签页，活动项用黄/绿/红圆点表示 pending / complete / error 状态，来源列表直接展示域名链接。

6.3 限流保护

聊天接口对所有请求启用 Upstash 限流（lib/rate-limit.ts）：基于UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN创建 Redis 实例，使用滑动窗口Ratelimit.slidingWindow(5, '60 s')，即每个用户 60 秒内最多 5 次请求，超限返回 HTTP 429。由于深度研究单轮可能耗时数分钟，这一限流对防止 API 成本失控尤为重要。

七、二次开发建议

• 扩展推理模型：在 lib/ai/index.ts 的VALID_REASONING_MODELS白名单中加入新模型 ID，并按需补充对应 AI SDK provider 的分发分支（lib/ai/index.ts）；
• 调整研究深度与时长：修改deepResearch工具的maxDepth（默认 7）与timeLimit（默认 4.5 分钟）两个常量即可控制研究规模与成本；
• 定制研究提示词：analyzeAndPlan的 prompt（要求模型报告剩余时间、判断是否继续、指定下一步搜索主题）与最终综合的 prompt 都集中在 app/(chat)/api/chat/route.ts/api/chat/route.ts) 中，可直接改写以适配特定领域；
• 自定义中间件：lib/ai/custom-middleware.ts 目前为空实现，AI SDK 的wrapLanguageModel中间件可在此注入日志、缓存、重试等横切逻辑。

八、常见问题速查

Q：没有 OpenAI API Key，只想用 DeepSeek 做研究分析？A：设置DEEPSEEK_API_KEY与REASONING_MODEL=deepseek-reasoner，并在.env中开启BYPASS_JSON_VALIDATION=true；注意关闭 JSON 校验后输出结构化程度可能下降。

Q：配置了REASONING_MODEL但没生效？A：检查模型 ID 是否在 lib/ai/index.ts 白名单内；不在白名单会回退到o1-mini并打印告警日志。另外若配置了OPENROUTER_API_KEY，推理模型也会统一走 OpenRouter 路由。

Q：本地启动报数据库/限流错误？A：确认POSTGRES_URL已配置且已执行pnpm db:migrate；UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN缺失时限流器不可用，建议按 .env.example 补齐。

Q：部署到 Vercel 需要哪些变量？A：最低要求AUTH_SECRET、OPENAI_API_KEY（或OPENROUTER_API_KEY）、FIRECRAWL_API_KEY，存储与限流相关变量由 Vercel 与 Upstash 按需配置。

• AI 应用
• AI Agent
• RAG
• 前端
• 后端