網頁搜尋工具
網頁搜尋工具讓 Claude 能夠直接存取即時網頁內容,使其能夠使用超出其知識截止日期的最新資訊來回答問題。Claude 會在回答中自動引用搜尋結果中的來源。
請透過我們的意見回饋表單分享您使用網頁搜尋工具的體驗。
支援的模型
網頁搜尋可用於:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (新版) (
claude-3-5-sonnet-latest
) - Claude Haiku 3.5 (
claude-3-5-haiku-latest
)
網頁搜尋的運作方式
當您在 API 請求中添加網頁搜尋工具時:
- Claude 根據提示決定何時進行搜尋。
- API 執行搜尋並向 Claude 提供結果。在單一請求中,此過程可能重複多次。
- 在其回合結束時,Claude 會提供帶有引用來源的最終回應。
如何使用網頁搜尋
您組織的管理員必須在 Console 中啟用網頁搜尋。
在您的 API 請求中提供網頁搜尋工具:
工具定義
網頁搜尋工具支援以下參數:
最大使用次數
max_uses
參數限制執行的搜尋次數。如果 Claude 嘗試進行的搜尋超過允許的次數,web_search_tool_result
將返回一個帶有 max_uses_exceeded
錯誤代碼的錯誤。
網域過濾
使用網域過濾器時:
- 網域不應包含 HTTP/HTTPS 協議(使用
example.com
而非https://example.com
) - 子網域會自動包含(
example.com
涵蓋docs.example.com
) - 支援子路徑(
example.com/blog
) - 您可以使用
allowed_domains
或blocked_domains
,但不能在同一請求中同時使用兩者。
本地化
user_location
參數允許您根據用戶的位置本地化搜尋結果。
type
:位置類型(必須為approximate
)city
:城市名稱region
:地區或州country
:國家timezone
:IANA 時區 ID。
回應
以下是回應結構的範例:
搜尋結果
搜尋結果包括:
url
:來源頁面的 URLtitle
:來源頁面的標題page_age
:網站最後更新的時間encrypted_content
:加密內容,必須在多回合對話中傳回以供引用
引用
網頁搜尋始終啟用引用功能,每個 web_search_result_location
包括:
url
:被引用來源的 URLtitle
:被引用來源的標題encrypted_index
:必須在多回合對話中傳回的參考。cited_text
:最多 150 個字符的引用內容
網頁搜尋引用字段 cited_text
、title
和 url
不計入輸入或輸出令牌使用量。
向最終用戶顯示網頁結果或網頁結果中包含的信息時,必須在您的用戶界面中清晰顯示並使內嵌引用可點擊。
錯誤
如果在網頁搜尋期間發生錯誤,您將收到以下形式的回應:
以下是可能的錯誤代碼:
too_many_requests
:超出速率限制invalid_input
:無效的搜尋查詢參數max_uses_exceeded
:超出最大網頁搜尋工具使用次數query_too_long
:查詢超出最大長度unavailable
:發生內部錯誤
pause_turn
停止原因
回應可能包含 pause_turn
停止原因,這表示 API 暫停了一個長時間運行的回合。您可以在後續請求中按原樣提供回應,讓 Claude 繼續其回合,或者如果您希望中斷對話,可以修改內容。
提示快取
網頁搜尋與提示快取兼容。要啟用提示快取,請在您的請求中添加至少一個 cache_control
斷點。系統將自動快取直到執行工具時的最後一個 web_search_tool_result
區塊。
對於多回合對話,請在最後一個 web_search_tool_result
區塊上或之後設置 cache_control
斷點,以重用快取內容。
例如,要在多回合對話中將提示快取與網頁搜尋一起使用:
串流
啟用串流後,您將收到作為串流一部分的搜尋事件。在搜尋執行期間會有一個暫停:
批次請求
您可以在 Messages Batches API 中包含網頁搜尋工具。通過 Messages Batches API 進行的網頁搜尋工具調用的價格與常規 Messages API 請求中的相同。
使用量和定價
網頁搜尋使用量除了令牌使用量外還需額外收費:
網頁搜尋在 Anthropic API 上的價格為每 1,000 次搜尋 $10,外加搜尋生成內容的標準令牌費用。在對話過程中檢索的網頁搜尋結果計為輸入令牌,包括在單次回合中執行的搜尋迭代和後續對話回合中的搜尋。
每次網頁搜尋計為一次使用,無論返回的結果數量如何。如果在網頁搜尋期間發生錯誤,則不會對該網頁搜尋收費。