Loading...
    • 開發者指南
    • API 參考
    • MCP
    • 資源
    • 發行說明
    Search...
    ⌘K
    入門
    Claude 簡介快速開始
    模型與定價
    模型概覽選擇模型Claude 4.6 新功能遷移指南模型棄用定價
    使用 Claude 構建
    功能概覽使用 Messages API處理停止原因提示最佳實踐
    模型能力
    延伸思考自適應思考思考力度快速模式(研究預覽)結構化輸出引用串流訊息批次處理PDF 支援搜尋結果多語言支援嵌入視覺
    工具
    概覽如何實作工具使用網頁搜尋工具網頁擷取工具程式碼執行工具記憶工具Bash 工具電腦使用工具文字編輯器工具
    工具基礎設施
    工具搜尋程式化工具呼叫細粒度工具串流
    上下文管理
    上下文視窗壓縮上下文編輯提示快取Token 計數
    檔案與資源
    Files API
    Agent 技能
    概覽快速開始最佳實踐企業技能透過 API 使用技能
    Agent SDK
    概覽快速開始TypeScript SDKTypeScript V2(預覽)Python SDK遷移指南
    API 中的 MCP
    MCP 連接器遠端 MCP 伺服器
    第三方平台上的 Claude
    Amazon BedrockMicrosoft FoundryVertex AI
    提示工程
    概覽提示產生器使用提示範本提示改進器清晰直接使用範例(多範例提示)讓 Claude 思考(CoT)使用 XML 標籤賦予 Claude 角色(系統提示)串連複雜提示長上下文技巧延伸思考技巧
    測試與評估
    定義成功標準開發測試案例使用評估工具降低延遲
    強化防護機制
    減少幻覺提高輸出一致性防範越獄攻擊串流拒絕減少提示洩漏讓 Claude 保持角色
    管理與監控
    Admin API 概覽資料駐留工作區用量與成本 APIClaude Code Analytics API零資料保留
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    工具

    網路搜尋工具

    網路搜尋工具讓 Claude 能直接存取即時網路內容,使其能夠以超越知識截止日期的最新資訊來回答問題。Claude 會自動引用搜尋結果中的來源作為回答的一部分。

    最新的網路搜尋工具版本(web_search_20260209)支援 Claude Opus 4.6 和 Sonnet 4.6 的動態過濾功能。Claude 可以撰寫並執行程式碼來過濾搜尋結果,在它們進入上下文視窗之前,僅保留相關資訊並丟棄其餘內容。這能產生更準確的回應,同時減少 token 消耗。先前的工具版本(web_search_20250305)仍然可用,但不具備動態過濾功能。

    This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

    支援的模型

    網路搜尋可在以下模型上使用:

    • Claude Opus 4.6(claude-opus-4-6)
    • Claude Opus 4.5(claude-opus-4-5-20251101)
    • Claude Opus 4.1(claude-opus-4-1-20250805)
    • Claude Opus 4(claude-opus-4-20250514)
    • Claude Sonnet 4.6(claude-sonnet-4-6)
    • Claude Sonnet 4.5(claude-sonnet-4-5-20250929)
    • Claude Sonnet 4(claude-sonnet-4-20250514)
    • Claude Sonnet 3.7(已棄用)(claude-3-7-sonnet-20250219)
    • Claude Haiku 4.5(claude-haiku-4-5-20251001)
    • Claude Haiku 3.5(已棄用)(claude-3-5-haiku-latest)

    網路搜尋的運作方式

    當您在 API 請求中加入網路搜尋工具時:

    1. Claude 會根據提示詞決定何時進行搜尋。
    2. API 執行搜尋並將結果提供給 Claude。此過程在單一請求中可能重複多次。
    3. 在其回合結束時,Claude 提供附有引用來源的最終回應。

    Opus 4.6 和 Sonnet 4.6 的動態過濾

    網路搜尋是一項 token 密集型任務。使用基本網路搜尋時,Claude 需要將搜尋結果拉入上下文,從多個網站獲取完整 HTML,並對所有內容進行推理後才能得出答案。通常,這些內容中有很多是不相關的,這可能會降低回應品質。

    使用 web_search_20260209 工具版本,Claude 可以撰寫並執行程式碼來後處理查詢結果。Claude 不再對完整 HTML 檔案進行推理,而是在將搜尋結果載入上下文之前動態過濾,僅保留相關內容並丟棄其餘部分。

    動態過濾特別適用於:

    • 搜尋技術文件
    • 文獻回顧和引用驗證
    • 技術研究
    • 回應基礎驗證

    動態過濾需要啟用程式碼執行工具。改進的網路搜尋工具可在 Claude API 和 Microsoft Azure 上使用。在 Google Vertex AI 上,可使用基本網路搜尋工具(不含動態過濾)。

    要啟用動態過濾,請使用 web_search_20260209 工具版本搭配 code-execution-web-tools-2026-02-09 beta 標頭:

    curl https://api.anthropic.com/v1/messages \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01" \
        --header "anthropic-beta: code-execution-web-tools-2026-02-09" \
        --header "content-type: application/json" \
        --data '{
            "model": "claude-opus-4-6",
            "max_tokens": 4096,
            "messages": [
                {
                    "role": "user",
                    "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio."
                }
            ],
            "tools": [{
                "type": "web_search_20260209",
                "name": "web_search"
            }]
        }'

    如何使用網路搜尋

    您組織的管理員必須在 Console 中啟用網路搜尋。

    在您的 API 請求中提供網路搜尋工具:

    curl https://api.anthropic.com/v1/messages \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01" \
        --header "content-type: application/json" \
        --data '{
            "model": "claude-opus-4-6",
            "max_tokens": 1024,
            "messages": [
                {
                    "role": "user",
                    "content": "What is the weather in NYC?"
                }
            ],
            "tools": [{
                "type": "web_search_20250305",
                "name": "web_search",
                "max_uses": 5
            }]
        }'

    工具定義

    網路搜尋工具支援以下參數:

    JSON
    {
      "type": "web_search_20250305",
      "name": "web_search",
    
      // 可選:限制每個請求的搜尋次數
      "max_uses": 5,
    
      // 可選:僅包含來自這些網域的結果
      "allowed_domains": ["example.com", "trusteddomain.org"],
    
      // 可選:永不包含來自這些網域的結果
      "blocked_domains": ["untrustedsource.com"],
    
      // 可選:本地化搜尋結果
      "user_location": {
        "type": "approximate",
        "city": "San Francisco",
        "region": "California",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    }

    最大使用次數

    max_uses 參數限制執行的搜尋次數。如果 Claude 嘗試的搜尋次數超過允許的數量,web_search_tool_result 將會是一個帶有 max_uses_exceeded 錯誤代碼的錯誤。

    網域過濾

    使用網域過濾時:

    • 網域不應包含 HTTP/HTTPS 協定(使用 example.com 而非 https://example.com)
    • 子網域會自動包含(example.com 涵蓋 docs.example.com)
    • 特定子網域會將結果限制為僅該子網域(docs.example.com 僅返回該子網域的結果,而非 example.com 或 api.example.com 的結果)
    • 支援子路徑,並匹配路徑之後的所有內容(example.com/blog 匹配 example.com/blog/post-1)
    • 您可以使用 allowed_domains 或 blocked_domains,但不能在同一請求中同時使用兩者。

    萬用字元支援:

    • 每個網域條目僅允許一個萬用字元(*),且必須出現在網域部分之後(在路徑中)
    • 有效:example.com/*、example.com/*/articles
    • 無效:*.example.com、ex*.com、example.com/*/news/*

    無效的網域格式將返回 invalid_tool_input 工具錯誤。

    請求層級的網域限制必須與在 Console 中配置的組織層級網域限制相容。請求層級的網域只能進一步限制網域,不能覆蓋或擴展超出組織層級的列表。如果您的請求包含與組織設定衝突的網域,API 將返回驗證錯誤。

    本地化

    user_location 參數允許您根據使用者的位置本地化搜尋結果。

    • type:位置類型(必須為 approximate)
    • city:城市名稱
    • region:地區或州
    • country:國家
    • timezone:IANA 時區 ID。

    回應

    以下是回應結構的範例:

    {
      "role": "assistant",
      "content": [
        // 1. Claude 決定進行搜尋
        {
          "type": "text",
          "text": "I'll search for when Claude Shannon was born."
        },
        // 2. 使用的搜尋查詢
        {
          "type": "server_tool_use",
          "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
          "name": "web_search",
          "input": {
            "query": "claude shannon birth date"
          }
        },
        // 3. 搜尋結果
        {
          "type": "web_search_tool_result",
          "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
          "content": [
            {
              "type": "web_search_result",
              "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
              "title": "Claude Shannon - Wikipedia",
              "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
              "page_age": "April 30, 2025"
            }
          ]
        },
        {
          "text": "Based on the search results, ",
          "type": "text"
        },
        // 4. Claude 附帶引用的回應
        {
          "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
          "type": "text",
          "citations": [
            {
              "type": "web_search_result_location",
              "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
              "title": "Claude Shannon - Wikipedia",
              "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
              "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
            }
          ]
        }
      ],
      "id": "msg_a930390d3a",
      "usage": {
        "input_tokens": 6039,
        "output_tokens": 931,
        "server_tool_use": {
          "web_search_requests": 1
        }
      },
      "stop_reason": "end_turn"
    }

    搜尋結果

    搜尋結果包括:

    • url:來源頁面的 URL
    • title:來源頁面的標題
    • page_age:網站最後更新時間
    • encrypted_content:加密內容,必須在多輪對話中傳回以用於引用

    引用

    網路搜尋始終啟用引用功能,每個 web_search_result_location 包括:

    • url:被引用來源的 URL
    • title:被引用來源的標題
    • encrypted_index:必須在多輪對話中傳回的參考
    • cited_text:最多 150 個字元的被引用內容

    網路搜尋引用欄位 cited_text、title 和 url 不計入輸入或輸出 token 使用量。

    當直接向終端使用者顯示 API 輸出時,必須包含對原始來源的引用。如果您在向終端使用者顯示之前對 API 輸出進行修改,包括重新處理和/或將其與您自己的材料結合,請根據您法律團隊的建議適當顯示引用。

    錯誤

    當網路搜尋工具遇到錯誤時(例如達到速率限制),Claude API 仍然返回 200(成功)回應。錯誤在回應主體中以以下結構表示:

    {
      "type": "web_search_tool_result",
      "tool_use_id": "servertoolu_a93jad",
      "content": {
        "type": "web_search_tool_result_error",
        "error_code": "max_uses_exceeded"
      }
    }

    以下是可能的錯誤代碼:

    • 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 斷點以重用快取內容。

    例如,在多輪對話中使用提示詞快取搭配網路搜尋:

    import anthropic
    
    client = anthropic.Anthropic()
    
    # 第一個請求,包含網路搜尋和快取斷點
    messages = [
        {"role": "user", "content": "What's the current weather in San Francisco today?"}
    ]
    
    response1 = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        messages=messages,
        tools=[
            {
                "type": "web_search_20250305",
                "name": "web_search",
                "user_location": {
                    "type": "approximate",
                    "city": "San Francisco",
                    "region": "California",
                    "country": "US",
                    "timezone": "America/Los_Angeles",
                },
            }
        ],
    )
    
    # 將 Claude 的回應添加到對話中
    messages.append({"role": "assistant", "content": response1.content})
    
    # 第二個請求,在搜尋結果之後設置快取斷點
    messages.append(
        {
            "role": "user",
            "content": "Should I expect rain later this week?",
            "cache_control": {"type": "ephemeral"},  # 快取到此處
        }
    )
    
    response2 = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        messages=messages,
        tools=[
            {
                "type": "web_search_20250305",
                "name": "web_search",
                "user_location": {
                    "type": "approximate",
                    "city": "San Francisco",
                    "region": "California",
                    "country": "US",
                    "timezone": "America/Los_Angeles",
                },
            }
        ],
    )
    # 第二個回應將受益於快取的搜尋結果
    # 同時仍然能夠在需要時執行新的搜尋
    print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

    串流

    啟用串流後,您將在串流中接收搜尋事件。搜尋執行期間會有暫停:

    event: message_start
    data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
    
    event: content_block_start
    data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
    
    // Claude 決定進行搜尋
    
    event: content_block_start
    data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
    
    // 搜尋查詢串流
    event: content_block_delta
    data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
    
    // 搜尋執行期間暫停
    
    // 搜尋結果串流
    event: content_block_start
    data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
    
    // Claude 附帶引用的回應(本範例中省略)

    批次請求

    您可以在 Messages Batches API 中包含網路搜尋工具。透過 Messages Batches API 的網路搜尋工具呼叫與常規 Messages API 請求中的定價相同。

    使用量與定價

    Web search usage is charged in addition to token usage:

    "usage": {
      "input_tokens": 105,
      "output_tokens": 6039,
      "cache_read_input_tokens": 7123,
      "cache_creation_input_tokens": 7345,
      "server_tool_use": {
        "web_search_requests": 1
      }
    }

    Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

    Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

    Was this page helpful?

    • Opus 4.6 和 Sonnet 4.6 的動態過濾