如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

網頁搜尋

讓模型在產生回覆前,先上網搜尋最新資訊。

網頁搜尋讓模型能從網際網路取得最新資訊,並在回答中引用來源。你可以在 Responses API 中使用網頁搜尋工具,也可以在某些情況下透過 Chat Completions 使用網頁搜尋。

請根據要回答的問題選擇搜尋流程。

  • 如果只需快速查詢,請模型查找一項具體事實,並註明來源。
  • 如果需要參考多個來源才能回答問題,請使用 gpt-6-astra 等推理模型。模型可以根據已讀取的結果調整後續查詢。如果請求可能需要數分鐘,請使用背景模式。

選擇整合方式

使用情境 建議做法 備註
新增網頁搜尋整合 在 Responses API 中搭配使用 web_search 與 gpt-6-astra 支援代管網頁搜尋的篩選條件、來源清單、即時存取控制,以及執行時間較長的研究任務
現有的 Chat Completions 搜尋整合 在 Chat Completions 中使用 gpt-5-search-api 僅在需要保留現有 Chat Completions 整合時使用
多步驟研究或需要長時間撰寫的報告 使用 gpt-6-astra,並將推理程度設為 high 或 xhigh 如果產生報告可能需要數分鐘,請使用背景模式

使用 Responses API 產生內容時,你可以在 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-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
    • 引用註記,位於 message.content[0].annotations,其中列出引用的網址

根據預設,模型會在回覆的內文中標示引用的搜尋結果網址。url_citation 註記物件也會包含所引來源的網址、標題,以及引用在回覆中的位置。

介面顯示網頁搜尋結果或取自這些結果的資訊時,必須在內文中以醒目且可點選的連結標示引用來源。

[
  {
    "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-07-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-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 額度限制。

此參數僅適用於在 Responses API 中搭配 GPT-5 或更新版本的推理模型執行網頁搜尋的代管 web_search 工具。它不會改變搜尋上下文視窗,也不適用於非推理式網頁搜尋、舊版 Search API 整合方式、容器內的網頁搜尋、Chat Completions 搜尋模型或 web_search_preview。此參數僅支援 default 和 unlimited。API 會拒絕 null、數字和其他字串。

執行較長時間的網頁搜尋
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-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 工具時,才能篩選網域。

來源

若要查看網頁搜尋期間擷取的所有網址,請使用 sources 欄位。內文中的引用標示只會列出最相關的參考資料,而 sources 欄位會傳回模型產生回覆時查閱過的完整網址清單。 來源數量通常比引用數量多。這個欄位也會列出即時第三方資料來源,並標示為 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-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[]。圖片結果會與助理訊息分開傳回,因此當應用程式需要網址或中繼資料時,請直接解析 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-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:結果中圖片的標準網址。
  • source_website_url:找到該圖片的網頁網址。
  • thumbnail_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-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-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-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 與資料駐留