English
主导航

旧版 API

网络搜索

允许模型在生成回复之前搜索网络以获取最新信息。

网页搜索允许模型访问互联网上的最新信息,并在回答时提供带有来源的引用。要启用此功能,请在 Responses API 中使用网页搜索工具,或者在部分场景下使用 Chat Completions。

OpenAI 模型提供三种主要类型的网页搜索:

  1. 非推理网页搜索:非推理模型将用户查询发送至网页搜索工具,该工具根据最相关的结果返回响应。模型没有内部规划,仅直接传递搜索工具的响应。此方法速度快,非常适合快速查询。
  2. 使用推理模型的智能体搜索是一种由模型主动管理搜索过程的方法。它可以在其思维链中执行网页搜索,分析结果,并决定是否继续搜索。这种灵活性使智能体搜索非常适合复杂的工作流,但也意味着搜索耗时比快速查询更长。例如,你可以在以下模型上调整推理级别: gpt-5.5 以同时改变搜索的深度和延迟。
  3. 深度研究是一种由推理模型执行的专门的、由智能体驱动的深入、长时间调查方法。模型在其思维链中进行网页搜索,通常会查阅数百个信息源。深度研究可能需要运行几分钟,建议在后台模式下使用。使用 gpt-5.5 with reasoning set to high or xhigh.

选择一种集成方式

用例推荐路径备注
新的网页搜索集成Responses API 搭配 web_search and gpt-5.5支持托管的网页搜索控制,例如过滤器、来源、实时访问控制以及更长的研究任务
现有的 Chat Completions 搜索集成Chat Completions 搭配 gpt-5-search-api仅在需要保留现有 Chat Completions 集成时使用
多步骤研究或长时间运行的报告gpt-5.5 with high or xhigh 推理对可能耗时数分钟的报告使用后台模式

使用 API 请求中的 Responses API,您可以通过在 tools 数组来生成内容。与任何其他工具一样,模型可以根据输入提示的内容自主选择是否搜索网页。

对于新的 Responses API 集成,请使用 { "type": "web_search" }中进行配置来启用网络搜索。早期的 web_search_preview 工具仍可用于遗留集成,但它不支持较新的控制功能,例如 filters, external_web_access,且 return_token_budget.

网页搜索工具示例
1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-5.5",
    tools: [
        { type: "web_search" },
    ],
    input: "What was a positive news story from today?",
});

console.log(response.output_text);

输出与引用

使用网页搜索工具的模型响应将包含两部分:

  • A web_search_call 输出项,包含搜索调用的 ID 以及在 web_search_call.action。该操作为以下之一:
    • search,表示网络搜索。它通常(但不总是)包含搜索 queries 中所执行的操作。搜索操作会产生工具调用费用(参见 定价).
    • open_page,表示正在打开一个网页。推理模型支持此操作。
    • find_in_page,表示在网页内进行搜索。推理模型支持此操作。
  • A message 输出项,包含:
    • The text result in message.content[0].text
    • 注释 message.content[0].annotations for the cited URLs

默认情况下,模型的回复将包含网络搜索结果中 URL 的内联引用。除此之外, url_citation annotation 对象将包含所引用来源的 URL、标题和位置。

在向最终用户展示网络搜索结果或其中包含的信息时,必须在您的用户界面中清晰展示内联引用,并确保其可点击。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "latest news about AI"
    }
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]
如果您使用推荐路径备注
web_search_preview in Responses迁移至 web_searchweb_search 支持更新的控件,例如 filters, external_web_access,且 return_token_budget
gpt-4o-search-preview or gpt-4o-mini-search-preview迁移到 Responses web_search使用的微调模型和工具,或使用 gpt-5-search-api 如果你必须继续使用 Chat Completions预览版搜索模型将于 2026-07-23 弃用并关闭
Chat Completions 搜索集成使用 gpt-5-search-api,或迁移至 Responses web_search 以获取更多工具控制和可选搜索Chat Completions 搜索模型在响应前始终进行搜索;Responses 搜索是一个工具

搜索上下文大小

search_context_size 控制模型在生成响应之前,有多少来自网页搜索结果的上下文可供其使用。使用 low for simple lookups, medium 以获得均衡的默认设置,而在 high 当答案可能需要搜索结果中的更多细节时使用。此设置不会设定确切的 token 数量,也不保证特定数量的来源或引用。

设置搜索上下文大小
1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "gpt-5.5",
    tools: [{
        type: "web_search",
        search_context_size: "low",
    }],
    input: "What movie won best picture in 2025?",
});
console.log(response.output_text);

运行更长的网络研究

return_token_budget 控制在 Responses API 搜索运行期间,配合 GPT-5+ 推理模型时该工具可以返回多少网页搜索结果内容。对于大多数请求,请保持默认值。仅当 unlimited 仅适用于需要检查大量页面且可能会在达到标准返回 token 上限时停止的高投入研究或评估运行时,才将其设置为

使用 unlimited 请谨慎选择,因为这会增加延迟和成本。对于运行时间较长的多搜索任务,请使用后台模式(background: true),这样请求可以继续异步运行,你可以在稍后获取最终响应。

行为
default对 Web 搜索结果使用标准的返回 token 预算。这与省略该参数时的行为相同 return_token_budget.
unlimited移除 Web 搜索运行的默认返回 token 预算。

此参数仅适用于托管 Responses API web_search 搭配 GPT-5+ 推理网页搜索工具。它不会更改搜索上下文窗口,也不适用于非推理网页搜索、旧版 Search API 路径、容器网页搜索、Chat Completions 搜索模型或 web_search_preview。仅 default and unlimited 是支持的值; null,数字和其他字符串会被拒绝。

运行更长的网页搜索
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "reasoning": { "effort": "xhigh" },
    "tools": [
      {
        "type": "web_search",
        "return_token_budget": "unlimited"
      }
    ],
    "input": "Research the economic impact of semaglutide on global healthcare systems.\n\nDo:\n- Include specific figures, trends, statistics, and measurable outcomes.\n- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.\n- Include inline citations and return all source metadata.\n\nBe analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
  }'

域名过滤

网页搜索中的域名过滤允许你将结果限定在一组特定的域名内。使用 filters 参数,你最多可以配置 100 个 allowed_domains or up to 100 blocked_domains。格式化域名时,请省略 HTTP 或 HTTPS 前缀。例如,使用 openai.com 而不是 https://openai.com/。此方法还会将子域名包含在搜索中。请注意,域名过滤仅在 Responses API 中通过 web_search tool.

来源

要查看网页搜索期间检索到的所有 URL,请使用 sources 字段。与仅显示最相关引用的行内引用不同,来源会返回模型在生成响应时参考过的完整 URL 列表。来源的数量通常多于引用的数量。实时第三方数据源也会在此处显示,并标记为 oai-sports, oai-weather, or oai-finance可用。sources 字段在使用 web_search and web_search_preview tools.

列出来源
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "allowed_domains": [
            "pubmed.ncbi.nlm.nih.gov",
            "clinicaltrials.gov",
            "www.who.int",
            "www.cdc.gov",
            "www.fda.gov"
          ],
          "blocked_domains": [
            "reddit.com",
            "quora.com",
            "wikipedia.org"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "include": ["web_search_call.action.sources"],
    "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
  }'

用户位置

为了根据地理位置优化搜索结果,您可以使用国家、城市、地区和/或时区指定大致的用户位置。

  • The city and region 字段是自由文本字符串,例如 Minneapolis and Minnesota respectively.
  • The country 字段是双字母 ISO 国家代码时均可用,例如 US.
  • The timezone 字段是 IANA 时区America/Chicago.

请注意,使用网页搜索的深度研究模型不支持用户位置。

自定义用户位置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "gpt-5.5",
    tools: [{
        type: "web_search",
        user_location: {
            type: "approximate",
            country: "GB",
            city: "London",
            region: "London"
        }
    }],
    input: "What are the best restaurants near me?",
});
console.log(response.output_text);

实时互联网访问

控制在 Responses API 中,网页搜索工具是获取实时内容还是仅使用缓存/已索引的结果。

  • 设置 external_web_access: falseweb_search 工具设置为以离线/仅缓存模式运行。
  • 默认为 true (实时访问)如果您未进行设置。
  • 预览变体(web_search_preview) 忽略此参数,其行为类似于 external_web_access is true.
控制实时互联网访问
1
2
3
4
5
6
7
8
curl "https://api.openai.com/v1/responses" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_API_KEY" -d '{
  "model": "gpt-5.5",
  "tools": [
    { "type": "web_search", "external_web_access": false }
  ],
  "tool_choice": "auto",
  "input": "Find when the Eiffel Tower opened to the public and cite the source."
}'

限制

Chat Completions API

Chat Completions API 仅支持使用专门的搜索模型进行网页搜索。这些模型不支持 Responses API 的 web_search 功能,例如域名过滤、完整来源列表、实时访问控制以及返回 token 预算控制。

模型上下文窗口限制
gpt-5-search-api200k使用 Chat Completions 搜索模型路径
gpt-4o-search-preview128k使用 Chat Completions 搜索模型路径; 已弃用,将于 2026-07-23 关闭
gpt-4o-mini-search-preview128k使用 Chat Completions 搜索模型路径; 已弃用,将于 2026-07-23 关闭

Responses API

使用托管的 web_search 工具。Responses API 仍接受 web_search_preview 用于旧版集成,但请使用 web_search for new integrations.

如需更大的模型上下文窗口,请使用 gpt-5.5。网络搜索上下文窗口仍为 128k。

模型模型上下文窗口限制
gpt-4.11M搜索上下文限制为 128k
gpt-4.1-mini1M搜索上下文限制为 128k
o4-mini200k搜索上下文限制为 128k; 已弃用,将于 2026-10-23 关闭

对于 Responses API 网页搜索,搜索上下文窗口限制为 128k,即使模型上下文窗口更大也是如此。

  • 网页搜索不支持 gpt-5 with minimal reasoning.
  • gpt-5.4 当推理努力设置为 none 可能会产生质量较低的结果。
  • Responses API 网页搜索使用底层模型的分级速率限制。
  • web_search_preview 不支持 filters or return_token_budget,并忽略 external_web_access.
  • With tool_choice: "auto",搜索是可选的。使用 tool_choice: "required" 或在必须运行搜索时选择特定的网页搜索工具。

使用说明

API 可用性速率限制备注

与配合工具使用的底层 模型 的分级速率限制相同。

定价
ZDR 和数据驻留