Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
此功能符合零数据保留（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 应用程序，其中工具获取并返回相关内容，并自动生成引用。
您也可以直接在用户消息中提供搜索结果。这适用于：
无论搜索结果以何种方式提供，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] 的内容连接在一起。不计入输出令牌。 |
search_result_index | integer | 被引用的搜索结果在请求中所有 search_result 块中的索引（从 0 开始），按其出现顺序排列（跨所有消息和工具结果）。 |
块索引标识搜索结果 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?
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)start_block_index |
| integer |
搜索结果 content 数组中第一个被引用块的索引（从 0 开始）。 |
end_block_index | integer | 搜索结果 content 数组中被引用块范围的结束索引（不含）。始终大于 start_block_index。 |