如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

网页搜索

让模型在生成回复前通过网页搜索获取最新信息。

网页搜索让模型可以从互联网上获取最新信息,并在回答中注明来源。您可以在 Responses API 中使用网页搜索工具来启用这项功能。在某些情况下,也可以通过 Chat Completions 使用网页搜索。

请根据要回答的问题选择搜索方式。

  • 如果只需快速查询,可以让模型查找某项具体事实,并注明来源。
  • 如果回答问题需要查阅多个来源,请使用 gpt-6.2-astra 等推理模型。模型可以根据已读到的结果调整后续搜索。如果请求可能需要几分钟才能完成,请使用后台模式。

选择集成方式

使用场景 推荐方式 说明
新建网页搜索集成 在 Responses API 中使用 web_search 和 gpt-6.2-astra 托管的网页搜索工具支持筛选域名、查看来源、控制实时访问,以及运行耗时较长的研究任务
已通过 Chat Completions 集成搜索 在 Chat Completions 中使用 gpt-5-search-api 仅在需要保留现有 Chat Completions 集成时使用
多步骤研究或生成耗时较长的报告 使用 gpt-6.2-astra,并将推理强度设为 high 或 xhigh 如果生成报告可能需要几分钟,请使用后台模式

使用 Responses API 时,您可以在内容生成请求的 tools 数组中配置网页搜索工具,以启用网页搜索。与使用其他工具时一样,模型可以根据输入提示词的内容决定是否搜索网页。

对于新的 Responses API 集成,请使用 { "type": "web_search" }。旧版集成仍可使用早期的 web_search_preview 工具,但该工具不支持 filters、external_web_access 和 return_token_budget 等较新的控制参数。

网页搜索工具示例
import OpenAI from "openai";
const client = new OpenAI();

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

console.log(response.output_text);

输出和引用

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

  • 一个 web_search_call 输出项,包含此次搜索调用的 ID,执行的操作记录在 web_search_call.action 中。操作类型有以下几种:
    • search 表示执行网页搜索。此操作通常会在 queries 中列出实际使用的查询,但有时会省略该字段。搜索操作会产生工具调用费用(请参阅定价)。
    • open_page 表示打开网页。推理模型支持此操作。
    • find_in_page 表示在网页内搜索。推理模型支持此操作。
  • 一个 message 输出项,包含:
    • 文本结果,位于 message.content[0].text 中。
    • 所引用 URL 的注解,位于 message.content[0].annotations 中。

默认情况下,模型会在回复正文中引用网页搜索结果中的 URL。此外,url_citation 注解对象还包含所引用来源的 URL、标题和引用位置。

在界面中展示网页搜索结果或其中的信息时,必须将正文中的引用显示为醒目且可点击的链接。

[
  {
    "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..."
          }
        ]
      }
    ]
  }
]

从旧版网页搜索迁移

当前使用的方式 推荐方式 说明
Responses 中的 web_search_preview 迁移到 web_search web_search 支持 filters、external_web_access 和 return_token_budget 等较新的控制参数
gpt-4o-search-preview 或 gpt-4o-mini-search-preview 迁移到 Responses 的 web_search 工具。如果必须继续使用 Chat Completions,请使用 gpt-5-search-api 这些预览版搜索模型已弃用,并已于 2026 年 7 月 23 日停用
Chat Completions 搜索集成 使用 gpt-5-search-api,或迁移到 Responses 的 web_search 工具,以便使用更多控制参数,并让模型按需搜索 Chat Completions 搜索模型每次都会先搜索再回复。在 Responses 中,搜索是一项可调用的工具
Responses 中的 o4-mini 改用支持 web_search 的推理模型,并配合该工具进行搜索 该模型已于 2026 年 10 月 23 日停用

如果您的集成仍使用 gpt-5,则必须将推理强度设为高于 minimal 的级别才能使用网页搜索。

搜索上下文大小

search_context_size 控制模型在生成回复前可以从网页搜索结果中获取多少上下文。如果只需查找少量细节,请使用 low。medium 适合作为兼顾不同需求的默认选项。如果回答可能需要搜索结果中的更多细节,请使用 high。此设置不会指定确切的 Token 数量,也不保证来源或引用的数量。

设置搜索上下文大小
import OpenAI from "openai";
const openai = new OpenAI();

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

运行耗时较长的网页研究任务

如果研究还需要查阅私有记录,请分开提交请求:用一个请求搜索公开网页,用另一个请求通过 MCP 查询私有记录。

在 Responses API 中使用 GPT-5 及更高版本的推理模型执行搜索时,return_token_budget 控制工具在一次运行中可以返回多少网页搜索结果内容。对于大多数请求,请保留默认值。仅当研究或评估任务需要深入查阅大量网页,且可能因达到标准返回 Token 上限而提前停止时,才将其设为 unlimited。

请按需使用 unlimited,因为它可能会增加延迟和费用。对于耗时较长、需要多次搜索的任务,请使用后台模式(background: true),让请求继续异步运行。您可以稍后获取最终响应。

值 行为
default 网页搜索结果使用标准的返回 Token 预算。效果与省略 return_token_budget 相同。
unlimited 取消此次网页搜索默认的返回 Token 预算限制。

此参数仅适用于使用 GPT-5 及更高版本推理模型进行网页搜索的 Responses API 托管工具 web_search。它不会改变搜索上下文窗口,也不适用于非推理网页搜索、旧版 Search API 接入方式、容器网页搜索、Chat Completions 搜索模型或 web_search_preview。此参数仅支持 default 和 unlimited,不接受 null、数字或其他字符串。

运行耗时较长的网页搜索
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-astra",
    "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 参数,您可以在 allowed_domains 中指定最多 100 个允许的域名,或在 blocked_domains 中指定最多 100 个屏蔽的域名。填写域名时,请省略 HTTP 或 HTTPS 前缀。例如,请填写 openai.com,而非 https://openai.com/。筛选范围也包括所列域名的子域名。域名筛选仅适用于 Responses API 的 web_search 工具。

来源

要查看一次网页搜索检索到的所有 URL,请使用 sources 字段。正文引用只显示最相关的参考资料,而 sources 字段会返回模型在生成回复时查阅过的完整 URL 列表。 来源数量通常多于引用数量。这里也会列出第三方实时数据源,并将其标记为 oai-sports、oai-weather 或 oai-finance。web_search 和 web_search_preview 工具均支持 sources 字段。

列出来源
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-astra",
    "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."
  }'

图片搜索结果

网页搜索可以同时返回图片结果和常规文本结果。如果您的应用需要最新图片或来自网页的视觉素材,例如产品照片、地标、地点、活动图片或参考图,请使用图片搜索。

要使用图片搜索,请在 search_content_types 中加入 image。如果您还需要辅助文本结果,以便模型概括图片内容、对图片排序或解释检索到的图片,请再加入 text。

使用 image_settings 配置图片搜索的专用选项:

  • max_results:指定希望返回的图片结果数量,值必须为正数。
  • caption:请求返回简短的图片说明(如果有)。

要查看原始图片结果,请在请求中包含 web_search_call.results,然后从响应中读取 web_search_call.results[]。图片结果与助手消息分开返回,因此如果您的应用需要图片的 URL 或元数据,请直接解析 web_search_call 项。

搜索图片
import OpenAI from "openai";
const client = new OpenAI();

const tools: OpenAI.Responses.Tool[] = [
  {
    type: "web_search",
    // @ts-expect-error The published SDK omits the documented image-search options.
    search_content_types: ["image", "text"],
    image_settings: {
      max_results: 3,
      caption: true,
    },
  },
];

const response = await client.responses.create({
  model: "gpt-6.2-astra",
  reasoning: { effort: "low" },
  tools,
  include: ["web_search_call.results"],
  input:
    "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.",
});

console.log(response.output);

每个 image_result 包含以下字段:

  • image_url:该结果中图片的规范 URL。
  • source_website_url:找到该图片的网页 URL。
  • thumbnail_url:缩略图 URL(如果有)。
  • caption:简短的图片说明或描述(如果有)。
{
  "output": [
    {
      "type": "web_search_call",
      "status": "completed",
      "results": [
        {
          "type": "image_result",
          "image_url": "https://cdn.example/golden-gate-sunset.jpg",
          "thumbnail_url": "https://cdn.example/golden-gate-sunset-thumb.jpg",
          "source_website_url": "https://example.com/source-page",
          "caption": "Golden Gate Bridge at sunset"
        }
      ]
    }
  ]
}

用户位置

您可以通过国家或地区、城市、行政区、时区中的一项或多项指定用户的大致位置,以便根据地理位置优化搜索结果。

  • city 和 region 字段接受自由文本字符串,例如分别填写 Minneapolis 和 Minnesota。
  • country 字段接受由两个字母组成的 ISO 国家代码,例如 US。
  • timezone 字段接受 IANA 时区,例如 America/Chicago。
自定义用户位置
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-6.2-astra",
  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: false 后,web_search 工具会以离线模式运行,仅使用缓存结果。
  • 如果未设置此参数,默认值为 true,即允许实时访问。
  • 预览版工具(web_search_preview)会忽略此参数,其行为与将 external_web_access 设为 true 时相同。
控制实时联网访问
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-astra",
    "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-api 200k 通过 Chat Completions 调用搜索模型

Responses API

请使用托管的 web_search 工具。Responses API 仍支持旧版集成使用 web_search_preview,但对于新的集成,请使用 web_search。

即使底层模型的上下文窗口更大,网页搜索的上下文窗口也以 128k 为限。要了解 gpt-6.2-astra 或其他受支持模型的上下文上限,请查看相应的模型页面。

  • 将 gpt-5.4 的推理强度设为 none 时,搜索结果的质量可能较低。
  • Responses API 的网页搜索遵循底层模型的分级速率限制。
  • web_search_preview 不支持 filters 或 return_token_budget,并会忽略 external_web_access。
  • 设置 tool_choice: "auto" 时,模型可以自行决定是否搜索。如果必须执行搜索,请使用 tool_choice: "required" 或明确指定网页搜索工具。

使用说明

API 支持情况速率限制说明

与调用该工具的底层模型的分级速率限制相同。

定价
ZDR 和数据驻留