搜尋結果內容區塊可啟用具有適當來源歸屬的自然引用,為您的自訂應用程式帶來網路搜尋品質的引用。此功能對於需要 Claude 準確引用來源的 RAG(檢索增強生成)應用程式特別強大。 搜尋結果功能可在以下模型上使用:
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • 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 3.5 Haiku (claude-3-5-haiku-20241022)

主要優勢

  • 自然引用 - 為任何內容實現與網路搜尋相同的引用品質
  • 靈活整合 - 在工具返回中用於動態 RAG,或作為頂層內容用於預先擷取的資料
  • 適當的來源歸屬 - 每個結果都包含來源和標題資訊,以便清楚歸屬
  • 無需文件解決方案 - 消除對基於文件的解決方案的需求
  • 一致的引用格式 - 符合 Claude 網路搜尋功能的引用品質和格式

運作方式

搜尋結果可以透過兩種方式提供:
  1. 來自工具呼叫 - 您的自訂工具返回搜尋結果,啟用動態 RAG 應用程式
  2. 作為頂層內容 - 您直接在使用者訊息中提供搜尋結果,用於預先擷取或快取的內容
在兩種情況下,Claude 都可以自動引用搜尋結果中的資訊,並提供適當的來源歸屬。

搜尋結果架構

搜尋結果使用以下結構:
{
  "type": "search_result",
  "source": "https://example.com/article",  // 必需:來源 URL 或識別碼
  "title": "Article Title",                  // 必需:結果的標題
  "content": [ // 必需:文字區塊陣列
    {
      "type": "text",
      "text": "The actual content of the search result..."
    }
  ],
  "citations": {                             // 選用:引用配置
    "enabled": true                          // 啟用/停用此結果的引用
  }
}

必需欄位

欄位類型說明
typestring必須為 "search_result"
sourcestring內容的來源 URL 或識別碼
titlestring搜尋結果的描述性標題
contentarray包含實際內容的文字區塊陣列

選用欄位

欄位類型說明
citationsobject具有 enabled 布林欄位的引用配置
cache_controlobject快取控制設定(例如 {"type": "ephemeral"})
content 陣列中的每個項目必須是具有以下內容的文字區塊:
  • type:必須為 "text"
  • text:實際文字內容(非空字串)

方法 1:來自工具呼叫的搜尋結果

最強大的使用案例是從您的自訂工具返回搜尋結果。這啟用了動態 RAG 應用程式,其中工具擷取並返回具有自動引用的相關內容。

範例:知識庫工具

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam
)

client = Anthropic()

# 定義知識庫搜尋工具
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Search the company knowledge base for information",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query"
            }
        },
        "required": ["query"]
    }
}

# 處理工具呼叫的函式
def search_knowledge_base(query):
    # 您的搜尋邏輯在此
    # 以正確格式返回搜尋結果
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Product Configuration Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
                )
            ],
            citations={"enabled": True}
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Troubleshooting Guide",
            content=[
                TextBlockParam(
                    type="text",
                    text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
                )
            ],
            citations={"enabled": True}
        )
    ]

# 使用工具建立訊息
response = client.messages.create(
    model="claude-sonnet-4-5",  # 適用於所有支援的模型
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content="How do I configure the timeout settings?"
        )
    ]
)

# 當 Claude 呼叫工具時,提供搜尋結果
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # 將工具結果傳回
    final_response = client.messages.create(
        model="claude-sonnet-4-5",  # 適用於所有支援的模型
        max_tokens=1024,
        messages=[
            MessageParam(role="user", content="How do I configure the timeout settings?"),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # 搜尋結果在此
                    )
                ]
            )
        ]
    )

方法 2:作為頂層內容的搜尋結果

您也可以直接在使用者訊息中提供搜尋結果。這適用於:
  • 從您的搜尋基礎設施預先擷取的內容
  • 來自先前查詢的快取搜尋結果
  • 來自外部搜尋服務的內容
  • 測試和開發

範例:直接搜尋結果

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)

client = Anthropic()

# 直接在使用者訊息中提供搜尋結果
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="API Reference - Authentication",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Getting Started Guide",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
                        )
                    ],
                    citations={"enabled": True}
                ),
                TextBlockParam(
                    type="text",
                    text="Based on these search results, how do I authenticate API requests and what are the rate limits?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

Claude 的回應與引用

無論搜尋結果如何提供,Claude 在使用搜尋結果中的資訊時都會自動包含引用:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "To authenticate API requests, you need to include an API key in the Authorization header",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "All API requests must include an API key in the Authorization header",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". You can generate API keys from your dashboard",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Keys can be generated from the dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API Reference - Authentication",
          "cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

引用欄位

每個引用包括:
欄位類型說明
typestring搜尋結果引用始終為 "search_result_location"
sourcestring原始搜尋結果中的來源
titlestring or null原始搜尋結果中的標題
cited_textstring被引用的確切文字
search_result_indexinteger搜尋結果的索引(從 0 開始)
start_block_indexinteger內容陣列中的起始位置
end_block_indexinteger內容陣列中的結束位置
注意:search_result_index 指的是搜尋結果內容區塊的索引(從 0 開始),無論搜尋結果如何提供(工具呼叫或頂層內容)。

多個內容區塊

搜尋結果可以在 content 陣列中包含多個文字區塊:
{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "API Documentation",
  "content": [
    {
      "type": "text",
      "text": "Authentication: All API requests require an API key."
    },
    {
      "type": "text",
      "text": "Rate Limits: The API allows 1000 requests per hour per key."
    },
    {
      "type": "text",
      "text": "Error Handling: The API returns standard HTTP status codes."
    }
  ]
}
Claude 可以使用 start_block_indexend_block_index 欄位引用特定區塊。

進階用法

結合兩種方法

您可以在同一對話中同時使用基於工具和頂層搜尋結果:
# 第一條訊息包含頂層搜尋結果
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(type="text", text="Our product helps teams collaborate...")
                ],
                citations={"enabled": True}
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information"
            )
        ]
    )
]

# Claude 可能會回應並呼叫工具來搜尋定價
# 然後您提供包含更多搜尋結果的工具結果

與其他內容類型結合

兩種方法都支援將搜尋結果與其他內容混合:
# 在工具結果中
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True}
    ),
    TextBlockParam(
        type="text",
        text="Additional context: This applies to version 2.0 and later."
    )
]

# 在頂層內容中
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    TextBlockParam(
        type="text",
        text="How does the chart relate to the research findings?"
    )
]

快取控制

新增快取控制以獲得更好的效能:
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

引用控制

預設情況下,搜尋結果的引用已停用。您可以透過明確設定 citations 配置來啟用引用:
{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{"type": "text", "text": "Important documentation..."}],
  "citations": {
    "enabled": true  // 啟用此結果的引用
  }
}
citations.enabled 設定為 true 時,Claude 在使用搜尋結果中的資訊時會包含引用參考。這啟用了:
  • 為您的自訂 RAG 應用程式提供自然引用
  • 在與專有知識庫互動時進行來源歸屬
  • 為任何返回搜尋結果的自訂工具提供網路搜尋品質的引用
如果省略 citations 欄位,預設情況下引用已停用。
引用是全有或全無的:請求中的所有搜尋結果必須啟用引用,或全部停用。混合具有不同引用設定的搜尋結果將導致錯誤。如果您需要停用某些來源的引用,必須停用該請求中所有搜尋結果的引用。

最佳實踐

針對基於工具的搜尋(方法 1)

  • 動態內容:用於即時搜尋和動態 RAG 應用程式
  • 錯誤處理:搜尋失敗時返回適當的訊息
  • 結果限制:僅返回最相關的結果以避免內容溢出

針對頂層搜尋(方法 2)

  • 預先擷取的內容:當您已經有搜尋結果時使用
  • 批次處理:適合一次處理多個搜尋結果
  • 測試:非常適合使用已知內容測試引用行為

一般最佳實踐

  1. 有效地結構化結果
    • 使用清晰、永久的來源 URL
    • 提供描述性標題
    • 將長內容分解為邏輯文字區塊
  2. 保持一致性
    • 在整個應用程式中使用一致的來源格式
    • 確保標題準確反映內容
    • 保持格式一致
  3. 優雅地處理錯誤
    def search_with_fallback(query):
        try:
            results = perform_search(query)
            if not results:
                return {"type": "text", "text": "No results found."}
            return format_as_search_results(results)
        except Exception as e:
            return {"type": "text", "text": f"Search error: {str(e)}"}
    

限制

  • 搜尋結果內容區塊可在 Claude API 和 Google Cloud 的 Vertex AI 上使用
  • 搜尋結果中僅支援文字內容(無圖像或其他媒體)
  • content 陣列必須至少包含一個文字區塊