OpenAI Web Search
透過 Responses 或 Chat 入口搜尋網路並處理來源引用。
OpenAI Web Search 讓支援該能力的模型在回答前搜尋網路，並在回應中回傳文字、搜尋呼叫和來源引用。它適合新聞、天氣、產品更新和其他具有明顯時效性的查詢。
如果資料來自你自己的資料庫或業務服務，應改用 Tool Calling 定義受控工具，而不是把內部資料交給公共網路搜尋。
先確認模型和入口
Web Search 欄位存在於協議中，不代表目前帳戶的每個模型都支援搜尋。請先在模型廣場確認模型和協議，再檢視對應 API Reference。
選擇 Responses 或 Chat
| 入口 | 啟用方式 | 結果位置 |
|---|---|---|
| Responses | 在 tools 中加入 Web Search Tool | web_search_call 與 Message Output Item |
| Chat Completions | 使用 web_search_options | Assistant Message 和 annotations |
Responses 更適合需要區分搜尋呼叫、回答和來源的應用；Chat 適合已經使用訊息結構的專案。
使用 Responses 搜尋網路
curl 'https://api.agtcloud.cn/v1/responses' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
--data '{
"model": "MODEL_ID",
"tools": [
{
"type": "web_search_preview",
"search_context_size": "medium"
}
],
"input": "今天有哪些值得關注的技術新聞？"
}'模型可能根據問題決定是否執行搜尋。搜尋發生時，回應的 output 通常同時包含搜尋呼叫項和文字訊息項；完整 Tool 類型見 Responses Reference。
使用 Chat Completions
curl 'https://api.agtcloud.cn/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
--data '{
"model": "MODEL_ID",
"messages": [
{
"role": "user",
"content": "今天有哪些值得關注的技術新聞？"
}
],
"web_search_options": {
"search_context_size": "medium"
}
}'Chat 回應本文位於 choices[].message.content，結構化引用在回應提供時位於 choices[].message.annotations。完整欄位見 Chat Completions Reference。
讀取回答和引用
{
"output": [
{
"type": "web_search_call",
"id": "ws_example",
"status": "completed"
},
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "根據搜尋結果……",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "來源標題"
}
]
}
]
}
]
}不要只儲存回答文字。應用應保留 URL、標題以及引用與文字位置的關聯，在介面中提供可點擊來源，並對外部連結使用安全的新標籤頁屬性。
限制搜尋範圍
在模型和入口支援時，可以設定以下搜尋條件：
- 網域範圍：只從允許的站點檢索，適合醫學、法規或企業知識來源。
- 使用者位置：提供國家、城市、地區或時區，幫助回傳本地化結果。
- 搜尋上下文規模：在回應品質、延遲和用量之間選擇合適範圍。
- 來源清單：Responses 可在支援時回傳搜尋過程中查閱的來源，不僅是回答本文中最終引用的來源。
這些欄位在 Responses 與 Chat 中的位置不同，具體名稱和限制以對應 Reference 為準。
失敗與降級
| 現象 | 處理方式 |
|---|---|
| 沒有執行搜尋 | 判斷問題是否需要即時資訊，並確認模型支援搜尋 |
| 有回答但沒有引用 | 不偽造來源；提示目前回應沒有回傳可顯示引用 |
| 搜尋失敗 | 根據回應錯誤決定重試、改用非搜尋回答或提示使用者稍後再試 |
| 來源衝突 | 顯示多個來源和更新時間，不讓模型替應用隱藏重要分歧 |
| 來源不可存取 | 保留標題和原 URL，提示使用者該頁面目前無法打開 |
外部網頁內容可能包含錯誤資訊或針對模型的惡意指令。不要因為內容來自搜尋結果就自動信任，也不要讓搜尋內容繞過應用權限或觸發高風險工具。
上線前檢查
- 模型和協議明確支援 Web Search。
- 回答、搜尋呼叫、引用和來源清單分別解析。
- 沒有引用時不會生成虛假連結。
- 網域和位置資訊只在業務需要時傳送。
- 外部內容不會繞過 Tool Calling 的權限與確認流程。
- 搜尋失敗、逾時和無結果都有清晰降級。