Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。
搜尋結果內容區塊可實現具有適當來源歸屬的自然引用，為您的自訂應用程式帶來網頁搜尋品質的引用功能。此功能對於「RAG」（Retrieval-Augmented Generation，檢索增強生成）應用程式特別強大，因為您需要 Claude 準確地引用來源。
搜尋結果功能可在以下模型上使用：
claude-opus-4-7）claude-opus-4-6）claude-sonnet-4-6）claude-sonnet-4-5-20250929）claude-opus-4-5-20251101）claude-opus-4-1-20250805）claude-opus-4-20250514）claude-sonnet-4-20250514）claude-haiku-4-5-20251001）claude-3-5-haiku-20241022）搜尋結果可透過兩種方式提供：
在這兩種情況下，Claude 都可以自動引用搜尋結果中的資訊，並提供適當的來源歸屬。
搜尋結果使用以下結構：
{
"type": "search_result",
"source": "https://example.com/article", // Required: Source URL or identifier
"title": "Article Title", // Required: Title of the result
"content": [
// Required: Array of text blocks
{
"type": "text",
"text": "The actual content of the search result..."
}
],
"citations": {
// Optional: Citation configuration
"enabled": true // Enable/disable citations for this result
}
}| 欄位 | 類型 | 說明 |
|---|---|---|
type | string | 必須為 "search_result" |
source | string | 內容的來源 URL 或識別碼 |
title | string | 搜尋結果的描述性標題 |
content | array | 包含實際內容的文字區塊陣列 |
| 欄位 | 類型 | 說明 |
|---|---|---|
citations | object | 包含 enabled 布林欄位的引用設定 |
cache_control | object | 快取控制設定（例如 {"type": "ephemeral"}） |
content 陣列中的每個項目必須是具有以下內容的文字區塊：
type：必須為 "text"text：實際的文字內容（非空字串）最強大的使用案例是從您的自訂工具回傳搜尋結果。這可實現動態 RAG 應用程式，其中工具擷取並回傳相關內容，並自動產生引用。
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-opus-4-8", # Works with all supported models
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-opus-4-8", # Works with all supported models
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, # Search results go here
)
],
),
],
)您也可以直接在使用者訊息中提供搜尋結果。這適用於：
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# 直接在使用者訊息中提供搜尋結果
response = client.messages.create(
model="claude-opus-4-8",
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)無論搜尋結果如何提供，Claude 在使用其中的資訊時都會自動包含引用：
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.",
"citations": [
{
"type": "search_result_location",
"cited_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.",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 1
}
]
},
{
"type": "text",
"text": "\n\nTo set this up from scratch, you'll need to "
},
{
"type": "text",
"text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.",
"citations": [
{
"type": "search_result_location",
"cited_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.",
"source": "https://docs.company.com/quickstart",
"title": "Getting Started Guide",
"search_result_index": 1,
"start_block_index": 0,
"end_block_index": 1
}
]
}
]
}每個引用包含：
| 欄位 | 類型 | 說明 |
|---|---|---|
type | string | 對於搜尋結果引用，始終為 "search_result_location" |
source | string | 來自原始搜尋結果的來源 |
title | string 或 null | 來自原始搜尋結果的標題 |
cited_text | string | 被引用區塊的完整文字，串接而成。等於 content[start_block_index:end_block_index] 的內容連接在一起。不計入輸出 token。 |
search_result_index | integer | 在請求中所有 search_result 區塊中，被引用搜尋結果的 0 起始索引，依其出現順序排列（跨所有訊息和工具結果）。 |
start_block_index | integer | 搜尋結果 content 陣列中第一個被引用區塊的 0 起始索引。 |
end_block_index | integer | 搜尋結果 content 陣列中被引用區塊範圍的排他性結束索引。始終大於 start_block_index。 |
區塊索引識別搜尋結果 content 陣列的一個切片，而 cited_text 是該切片的完整文字。文字區塊是最小的可引用單位：Claude 引用整個區塊，而非區塊內的子字串。若要獲得更細粒度的引用，請將您的搜尋結果內容拆分為更小的區塊（請參閱多個內容區塊）。
搜尋結果可以在 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."
}
]
}參照速率限制區塊的引用如下所示：
{
"type": "search_result_location",
"cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"search_result_index": 0,
"start_block_index": 1,
"end_block_index": 2
}當此搜尋結果被引用時，start_block_index 和 end_block_index 識別引用涵蓋哪些區塊，而 cited_text 正好包含這些區塊的文字。將內容拆分為更小、更聚焦的區塊可讓 Claude 獲得更精細的引用邊界；將內容合併為一個區塊則意味著每個引用都會回傳完整文字。這與引用功能中自訂內容文件所使用的模型相同。
您可以在同一對話中同時使用基於工具和頂層的搜尋結果：
from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam
# 第一則訊息，包含頂層搜尋結果
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 可能會回應並呼叫工具來搜尋定價資訊
# 接著您提供包含更多搜尋結果的工具結果兩種方法都支援將搜尋結果與其他內容混合使用：
from anthropic.types import SearchResultBlockParam, TextBlockParam
# 在工具結果中
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 // Enable citations for this result
}
}當 citations.enabled 設定為 true 時，Claude 在使用搜尋結果中的資訊時會包含引用參照。這可實現：
引用是全有或全無的：請求中的所有搜尋結果必須全部啟用引用，或全部停用引用。混合使用不同引用設定的搜尋結果會導致錯誤。
有效地建構結果：
保持一致性：
優雅地處理錯誤：
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)}"}content 陣列必須包含至少一個文字區塊Was this page helpful?