Deep Research API 入门

背景

Deep Research API 使您能够自动化需要推理、规划和跨越真实世界信息进行综合的复杂研究工作流。它旨在接受一个高级查询，并通过利用能够分解任务、执行网络搜索和综合结果的代理模型来返回一个结构化的、富含引用的报告。

与 ChatGPT 中抽象化此过程不同，API 提供直接的编程访问。当您发送请求时，模型会自主规划子问题，使用网络搜索和代码执行等工具，并生成最终的结构化响应。本指南将简要介绍 Deep Research API 及其用法。

您可以通过 responses 端点访问 Deep Research，使用以下模型：

o3-deep-research-2025-06-26：针对深入综合和更高质量的输出进行了优化
o4-mini-deep-research-2025-06-26：轻量级且速度更快，非常适合对延迟敏感的用例

设置

安装要求

安装最新版本的 OpenAI Python SDK。

!pip install --upgrade openai

认证

导入 OpenAI 客户端并使用您的 API 密钥进行初始化。

from openai import OpenAI
OPENAI_API_KEY="" # YOUR OPENAI_API_KEY
#OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
client = OpenAI(api_key=OPENAI_API_KEY)

入门

让我们通过一个 Deep Research API 调用的示例。假设我们是一家医疗保健金融服务公司的员工，负责撰写一份关于用于治疗 2 型糖尿病和肥胖症的最新药物（特别是司美格鲁肽）的经济影响的深入报告。我们的目标是将临床结果、成本效益和区域定价数据综合成一份结构化的、有引文支持的分析，为投资、支付方策略或政策建议提供信息。

为了开始，让我们：

在系统消息中放入我们的角色，概述我们想生成的报告类型
目前将 summary 参数设置为“auto”，以获得最佳可用摘要。（如果您希望您的报告更详细，您可以将 summary 设置为 detailed）
包括必需的工具 web_search_preview，并可选地添加 code_interpreter。
将 background 参数设置为 True。由于 Deep Research 任务可能需要几分钟才能执行，启用后台模式将允许您异步运行请求，而不必担心超时或其他连接问题。

system_message = """
您是一位专业的 غادي研究员，代表全球卫生经济学团队准备一份结构化、数据驱动的报告。您的任务是分析用户提出的健康问题。

做：

- 关注数据丰富的见解：包括具体的数字、趋势、统计数据和可衡量的结果（例如，住院费用降低、市场规模、定价趋势、支付方采用情况）。
- 在适当的时候，以可转化为图表或表格的方式总结数据，并在响应中注明（例如，“这可以很好地用条形图比较各地区的每位患者成本”）。
- 优先使用可靠、最新的来源：同行评审的研究、卫生组织（例如，世界卫生组织、疾病控制与预防中心）、监管机构或制药公司收益报告。
- 包括内联引用并返回所有来源元数据。

保持分析性，避免笼统性，并确保每个部分都支持可为医疗政策或财务建模提供信息的基于数据的推理。
"""

user_query = "研究司美格鲁肽对全球医疗保健系统的经济影响。"

response = client.responses.create(
  model="o3-deep-research",
  input=[
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": system_message,
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": user_query,
        }
      ]
    }
  ],
  reasoning={
    "summary": "auto"
  },
  tools=[
    {
      "type": "web_search_preview"
    },
    {
      "type": "code_interpreter",
      "container": {
        "type": "auto",
        "file_ids": []
      }
    }
  ]
)

解析响应

Deep Research API 响应包括结构化的最终答案以及内联引用、推理步骤摘要和来源元数据。

提取最终报告输出

这是此报告的主要文本输出。

# 从响应对象访问最终报告
print(response.output[-1].content[0].text)

访问内联引用和元数据

响应文本中的内联引用已进行注释，并链接到其相应的来源元数据。每个注释包含：

start_index 和 end_index：引用所指文本的字符跨度
title：来源的简短标题
url：完整的来源 URL

此结构将允许您构建引文列表或参考文献，在下游应用程序中添加可点击的超链接，并突出显示和追溯报告中基于数据的声明。

annotations = response.output[-1].content[0].annotations
for i, citation in enumerate(annotations):
    print(f"Citation {i+1}:")
    print(f"  Title: {citation.title}")
    print(f"  URL: {citation.url}")
    print(f"  Location: chars {citation.start_index}–{citation.end_index}")

查看中间步骤

Deep Research API 还公开了代理执行的所有中间步骤，包括推理步骤、网络搜索调用和代码执行。您可以使用这些来调试、分析或可视化最终答案的构建方式。每个中间步骤都存储在 response.output 中，type 字段指示其类型。

推理步骤

这些代表模型在推理子问题时生成的内部摘要或计划。

# 查找第一个推理步骤
reasoning = next(item for item in response.output if item.type == "reasoning")
for s in reasoning.summary:
    print(s.text)

网络搜索调用

这些显示了执行了哪些搜索查询，并有助于您跟踪模型检索到的信息。

# 查找第一个网络搜索步骤
search = next(item for item in response.output if item.type == "web_search_call")
print("Query:", search.action["query"])
print("Status:", search.status)

代码执行

如果模型使用了代码解释器（例如，用于解析数据或生成图表），这些步骤将显示为“code_interpreter_call”或类似类型。

# 查找代码执行步骤（如果有）
code_step = next((item for item in response.output if item.type == "code_interpreter_call"), None)
if code_step:
    print(code_step.input)
    print(code_step.output)
else:
    print("未找到代码执行步骤。")

模型上下文协议 (MCP)

假设您想在 Deep Research 任务中引入您自己的内部文档。Deep Research 模型和 Responses API 都支持 MCP 工具，因此您可以扩展它们来查询您组织的私有知识库或其他第三方服务。

在下面的示例中，我们配置了一个 MCP 工具，该工具允许 Deep Research 按需获取您组织内部的司美格鲁肽研究。MCP 服务器是 OpenAI 文件存储服务的代理，可自动矢量化您上传的文件以实现高效检索。

如果您想了解我们如何构建这个简单的 MCP 服务器，请参阅这个相关的指南。

# system_message 包括对 MCP 内部文件查找的引用。
system_message = """
您是一位专业的 غادي研究员，代表全球卫生经济学团队准备一份结构化、数据驱动的报告。您的任务是分析用户提出的健康问题。

做：

- 关注数据丰富的见解：包括具体的数字、趋势、统计数据和可衡量的结果（例如，住院费用降低、市场规模、定价趋势、支付方采用情况）。
- 在适当的时候，以可转化为图表或表格的方式总结数据，并在响应中注明（例如，“这可以很好地用条形图比较各地区的每位患者成本”）。
- 优先使用可靠、最新的来源：同行评审的研究、卫生组织（例如，世界卫生组织、疾病控制与预防中心）、监管机构或制药公司收益报告。
- 包括一个内部文件查找工具，用于从我们自己的内部数据源检索信息。如果您已经检索了某个文件，请不要再次调用 fetch 来获取相同的文件。优先包含该数据。
- 包括内联引用并返回所有来源元数据。

保持分析性，避免笼统性，并确保每个部分都支持可为医疗政策或财务建模提供信息的基于数据的推理。
"""

user_query = "研究司美格鲁肽对全球医疗保健系统的经济影响。"

response = client.responses.create(
  model="o3-deep-research-2025-06-26",
  input=[
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": system_message,
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": user_query,
        }
      ]
    }
  ],
  reasoning={
    "summary": "auto"
  },
  tools=[
    {
      "type": "web_search_preview"
    },
    { # 添加 MCP 工具支持
      "type": "mcp",
      "server_label": "internal_file_lookup",
      "server_url": "https://<your_mcp_server>/sse/", # 更新为您 MCP 服务器的位置
      "require_approval": "never"
    }
  ]
)

查看您的响应

您的研究报告的前 100 个字符，以及引文和 MCP 工具调用。

# 一旦获取完整的报告文本
report_text = response.output[-1].content[0].text

print("报告节选：")
print(report_text[:100])   # 前 100 个字符
print("--------")

annotations = response.output[-1].content[0].annotations
target_url = "https://platform.openai.com/storage/files"

for citation in annotations:
    if citation.url.startswith(target_url):
        start, end = citation.start_index, citation.end_index

        # 提取引用的确切跨度
        excerpt       = report_text[start:end]

        # 提取引文之前的最多 100 个字符
        pre_start     = max(0, start - 100)
        preceding_txt = report_text[pre_start:start]

        print("MCP 引文样本：")
        print(f"  标题：       {citation.title}")
        print(f"  URL：         {citation.url}")
        print(f"  位置：    字符 {start}–{end}")
        print(f"  前面的文本：   {preceding_txt!r}")
        print(f"  节选：     {excerpt!r}")
        break

print("--------")


# 示例 MCP 引文

# 报告节选：
# # 引言
# 司美格鲁肽——一种胰高血糖素样肽-1 (GLP-1) 类似物——已迅速成为一种强效的
# --------
# MCP 引文样本：
#   标题：       Document file-WqbCdYNqNzGuFfCAeWyZfp
#   URL：         https://platform.openai.com/storage/files/file-WqbCdYNqNzGuFfCAeWyZfp
#   位置：    字符 237–331
#   前面的文本：   'and obesity due to its potent clinical efficacy (often inducing ~10–15% body weight loss in trials) '
#   节选：     '([platform.openai.com](https://platform.openai.com/storage/files/file-WqbCdYNqNzGuFfCAeWyZfp))'


# 打印 MCP 工具调用
calls = [
    (item.name, item.server_label, item.arguments)
    for item in response.output
    if item.type == "mcp_call" and item.arguments
]
for name, server, args in calls:
    print(f"{name}@{server} → {args}")
print("--------")

ChatGPT 中的澄清问题与 Deep Research API

如果您在 ChatGPT 中使用过 Deep Research，您可能会注意到它在您提交查询后经常会提出后续问题。这是故意的：ChatGPT 使用中间模型（如 gpt-4.1）来帮助澄清您的意图并收集更多上下文（例如您的偏好、目标或限制），然后才开始研究过程。这个额外的步骤有助于系统定制其网络搜索并返回更相关、更有针对性的结果。

相比之下，Deep Research API 跳过了这个澄清步骤。作为开发人员，您可以配置此处理步骤来重写用户提示或提出一组澄清问题，因为模型期望接收完整的提示，并且不会要求提供额外上下文或填写缺失信息；它只会根据收到的输入开始研究。

为了获得强大、可靠的 API 输出，您可以使用两种方法。

使用另一个轻量级模型（例如 gpt-4.1）的提示重写器，在将用户查询传递给研究模型之前对其进行扩展或指定。
包括所有相关详细信息：期望的范围、比较、指标、地区、首选来源和期望的输出格式。

此设置使开发人员能够完全控制研究任务的构建方式，但也对输入提示的质量提出了更高的要求。以下是一个通用重写提示的示例，用于更好地指导后续的深度研究查询。

../../images/intro_dr.png

这是一个重写提示的示例：

suggested_rewriting_prompt = """
您将收到用户的研究任务。您的工作是提供一套说明给研究员来完成任务。请勿自行完成任务，只需提供如何完成任务的说明。

指南：

1. **最大化具体性和细节**
- 包括所有已知的用户偏好，并明确列出要考虑的关键属性或维度。
- 在说明中包含所有用户提供的细节至关重要。

2. **填充未说明但必需的维度**
- 如果某些属性对于有意义的输出至关重要，但用户未提供，请明确说明它们是开放式的或默认为无特定约束。

3. **避免不必要的假设**
- 如果用户未提供特定细节，请勿自行捏造。
- 相反，请说明规格的缺失，并指导研究员将其视为灵活的或接受所有可能的选项。

4. **使用第一人称**
- 从用户角度来表述请求（例如，“请澄清……”或“您是否有偏好……”）。

5. **表格**
- 如果您确定包含表格有助于说明、组织或增强研究输出中的信息，则必须明确要求研究员提供表格。
示例：

- 产品比较（消费者）：在比较不同的智能手机型号时，请求一个表格，并排列每个型号的功能、价格和消费者评分。
- 项目跟踪（工作）：在概述项目可交付成果时，创建一个表格，显示任务、截止日期、负责的团队成员和状态更新。
- 预算规划（消费者）：在创建个人或家庭预算时，请求一个表格，详细说明收入来源、月度支出和储蓄目标。
竞争对手分析（工作）：在评估竞争对手产品时，请求一个表格，其中包含关键指标，例如市场份额、定价和主要差异化因素。

6. **标题和格式**
- 您应在提示中包含预期的输出格式。
- 如果用户要求的内容最好以结构化格式（例如报告、计划等）返回，请要求研究员将其格式化为报告，并包含适当的标题和格式，以确保清晰和结构化。

7. **语言**
- 如果用户输入不是英语，请告知研究员用该语言回复，除非用户查询明确要求用其他语言回复。

8. **来源**
- 如果应优先考虑特定来源，请在提示中指定。
- 对于产品和旅行研究，请优先链接到官方或主要网站（例如，官方品牌网站、制造商页面或信誉良好的电子商务平台，如亚马逊以获取用户评论），而不是聚合网站或 SEO 繁重的博客。
- 对于学术或科学查询，请优先链接到原始论文或官方期刊出版物，而不是调查论文或二次摘要。
- 如果查询是特定语言的，请优先考虑以该语言发布的来源。
"""

response = client.responses.create(
    instructions=suggested_rewriting_prompt,
    model="gpt-4.1-2025-04-14",
    input="help me plan a trip to france",
)

new_query = response.output[0].content[0].text
print(new_query)

在这种情况下，用户提交了一个通用的或开放式的查询，没有指定关键细节，如旅行日期、目的地偏好、预算、兴趣或旅行同伴；重写提示重写了查询，以便 Deep Research 尝试生成广泛而包容的响应，预测常见用例。

虽然这种行为在涌现各种选项方面可能很有帮助，但它通常会导致冗长、更高的延迟和更多的 token 使用，因为模型必须考虑许多可能的场景。对于触发复杂规划或综合任务（例如多目的地旅行行程、比较研究、产品选择）的查询尤其如此。

与其立即进行广泛的研究计划，不如让我们尝试使用一个更轻量级的模型来向用户提出澄清问题，然后再生成完整的答案，然后使用重写提示为模型生成更清晰的输出。

suggested_clariying_prompt = """"
您将收到用户的研究任务。您的工作不是立即完成任务，而是提出澄清问题，这将有助于您或另一位研究员提供更具体、更有效、更相关的答案。

指南：

1. **最大化相关性**
- 提出*直接必要*以确定研究输出范围的问题。
- 考虑哪些信息会改变答案的结构、深度或方向。

2. **明确缺失但关键的维度**
- 识别用户请求中未指定的必要属性（例如，偏好、时间范围、预算、受众）。
- *明确*询问每个属性，即使它感觉很明显或典型。

3. **不要臆造偏好**
- 如果用户没有提及偏好，*不要假设它*。清楚、中性地询问。

4. **使用第一人称**
- 从助手或研究员与用户交谈的角度来提问（例如，“您能否澄清……”或“您是否有偏好……”）。

5. **如果问题多，请使用项目符号列表**
- 如果有多个开放性问题，请以项目符号格式清晰列出，以便阅读。

6. **避免过度提问**
- 优先考虑能最大程度减少歧义或范围蔓延的 3-6 个问题。您不必问*所有问题*，只需问最关键的未知项。

7. **在有帮助时包含示例**
- 如果询问偏好（例如，旅行风格、报告格式），请简要列出示例以帮助用户回答。

8. **格式化以便于对话**
- 输出应听起来乐于助人且对话化——不像表格。在保持精确的同时，力求自然语气。
"""


response = client.responses.create(
    instructions=suggested_clariying_prompt,
    model="gpt-4.1-2025-04-14",
    input="help me plan a trip to france",
)

new_query = response.output[0].content[0].text
print(new_query)

user_follow_up = """我打算八月去旅行。我想去巴黎和尼斯。我想在不含机票的情况下，将 7 天的行程控制在 1500 美元以内。
我和我的朋友一起去。我们都二十多岁。我喜欢历史、非常棒的法国美食和葡萄酒，以及徒步旅行。
"""
instructions_for_DR = client.responses.create(
    instructions=suggested_rewriting_prompt,
    model="gpt-4.1-2025-04-14",
    input=user_follow_up,
)
instructions_for_deep_research = instructions_for_DR.output[0].content[0].text
print(instructions_for_deep_research)

deep_research_call = client.responses.create(
  model="o4-mini-deep-research-2025-06-26",
  input=[
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": instructions_for_deep_research,
        }
      ]
    },
  ],
  reasoning={
    "summary": "auto"
  },
  tools=[
    {
      "type": "web_search_preview"
    },
  ]
)

# 从响应对象访问最终报告
print(deep_research_call.output[-1].content[0].text)

大功告成！一份为您即将到来的法国之旅量身定制的深度研究报告！

在本指南中，我们探讨了如何使用 Deep Research API 来自动化复杂的现实世界研究任务，从分析司美格鲁肽的经济影响到为您规划一次法国之旅。当您需要结构化的、有引文支持的、基于现实世界证据的答案时，Deep Research 就能大显身手。一些突出的用例包括：

产品比较和市场分析
竞争情报和战略报告
技术文献综述和政策综合

无论您是想构建研究代理、生成结构化报告，还是将高质量的综合信息集成到您的工作流程中，我们希望这里的示例能帮助您入门。

下一步是什么？Deep Research Agents