搜索结果内容块目前处于测试阶段。使用 search-results-2025-06-09
测试版标头 来启用此功能。
搜索结果内容块通过适当的来源归属启用自然引用,为您的自定义应用程序带来网络搜索质量的引用。此功能对于需要Claude准确引用来源的RAG(检索增强生成)应用程序特别强大。
搜索结果功能在以下模型上可用:
- Claude 3.5 Haiku (
claude-3-5-haiku-20241022
)
- Claude 3.5 Sonnet (
claude-3-5-sonnet-20241022
)
- Claude 3.7 Sonnet (
claude-3-7-sonnet-20250219
)
- Claude Opus 4 (
claude-opus-4-20250514
)
- Claude Sonnet 4 (
claude-sonnet-4-20250514
)
主要优势
- 自然引用 - 为任何内容实现与网络搜索相同的引用质量
- 灵活集成 - 在工具返回中用于动态RAG或作为预获取数据的顶级内容
- 适当的来源归属 - 每个结果都包含来源和标题信息以进行清晰归属
- 无需文档变通方法 - 消除了对基于文档的变通方法的需求
- 一致的引用格式 - 匹配Claude网络搜索功能的引用质量和格式
工作原理
搜索结果可以通过两种方式提供:
- 来自工具调用 - 您的自定义工具返回搜索结果,启用动态RAG应用程序
- 作为顶级内容 - 您直接在用户消息中提供搜索结果,用于预获取或缓存的内容
在这两种情况下,Claude都可以自动引用搜索结果中的信息并进行适当的来源归属。
搜索结果架构
搜索结果使用以下结构:
必需字段
字段 | 类型 | 描述 |
---|
type | string | 必须是 "search_result" |
source | string | 内容的来源URL或标识符 |
title | string | 搜索结果的描述性标题 |
content | array | 包含实际内容的文本块数组 |
可选字段
字段 | 类型 | 描述 |
---|
citations | object | 带有 enabled 布尔字段的引用配置 |
cache_control | object | 缓存控制设置(例如,{"type": "ephemeral"} ) |
content
数组中的每个项目必须是具有以下内容的文本块:
type
:必须是 "text"
text
:实际文本内容(非空字符串)
方法1:来自工具调用的搜索结果
最强大的用例是从您的自定义工具返回搜索结果。这启用了动态RAG应用程序,其中工具获取并返回具有自动引用的相关内容。
示例:知识库工具
from anthropic import Anthropic
from anthropic.types.beta import (
BetaMessageParam,
BetaTextBlockParam,
BetaSearchResultBlockParam,
BetaToolResultBlockParam
)
client = Anthropic()
knowledge_base_tool = {
"name": "search_knowledge_base",
"description": "搜索公司知识库以获取信息",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索查询"
}
},
"required": ["query"]
}
}
def search_knowledge_base(query):
return [
BetaSearchResultBlockParam(
type="search_result",
source="https://docs.company.com/product-guide",
title="产品配置指南",
content=[
BetaTextBlockParam(
type="text",
text="要配置产品,请导航到设置 > 配置。默认超时时间为30秒,但可以根据您的需要在10-120秒之间调整。"
)
],
citations={"enabled": True}
),
BetaSearchResultBlockParam(
type="search_result",
source="https://docs.company.com/troubleshooting",
title="故障排除指南",
content=[
BetaTextBlockParam(
type="text",
text="如果遇到超时错误,请首先检查配置设置。常见原因包括网络延迟和不正确的超时值。"
)
],
citations={"enabled": True}
)
]
response = client.beta.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
betas=["search-results-2025-06-09"],
tools=[knowledge_base_tool],
messages=[
BetaMessageParam(
role="user",
content="如何配置超时设置?"
)
]
)
if response.content[0].type == "tool_use":
tool_result = search_knowledge_base(response.content[0].input["query"])
final_response = client.beta.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
betas=["search-results-2025-06-09"],
messages=[
BetaMessageParam(role="user", content="如何配置超时设置?"),
BetaMessageParam(role="assistant", content=response.content),
BetaMessageParam(
role="user",
content=[
BetaToolResultBlockParam(
type="tool_result",
tool_use_id=response.content[0].id,
content=tool_result
)
]
)
]
)
方法2:搜索结果作为顶级内容
您也可以直接在用户消息中提供搜索结果。这对以下情况很有用:
- 来自您的搜索基础设施的预获取内容
- 来自先前查询的缓存搜索结果
- 来自外部搜索服务的内容
- 测试和开发
示例:直接搜索结果
from anthropic import Anthropic
from anthropic.types.beta import (
BetaMessageParam,
BetaTextBlockParam,
BetaSearchResultBlockParam
)
client = Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-20250514",
max_tokens=1024,
betas=["search-results-2025-06-09"],
messages=[
BetaMessageParam(
role="user",
content=[
BetaSearchResultBlockParam(
type="search_result",
source="https://docs.company.com/api-reference",
title="API参考 - 身份验证",
content=[
BetaTextBlockParam(
type="text",
text="所有API请求都必须在Authorization标头中包含API密钥。密钥可以从仪表板生成。速率限制:标准层每小时1000个请求,高级层10000个。"
)
],
citations={"enabled": True}
),
BetaSearchResultBlockParam(
type="search_result",
source="https://docs.company.com/quickstart",
title="入门指南",
content=[
BetaTextBlockParam(
type="text",
text="开始使用:1)注册账户,2)从仪表板生成API密钥,3)使用pip install company-sdk安装我们的SDK,4)使用您的API密钥初始化客户端。"
)
],
citations={"enabled": True}
),
BetaTextBlockParam(
type="text",
text="基于这些搜索结果,我如何验证API请求以及速率限制是什么?"
)
]
)
]
)
print(response.model_dump_json(indent=2))
Claude的引用响应
无论搜索结果如何提供,Claude在使用其中的信息时都会自动包含引用:
引用字段
每个引用包括:
字段 | 类型 | 描述 |
---|
type | string | 搜索结果引用始终为 "search_result_location" |
source | string | 来自原始搜索结果的来源 |
title | string或null | 来自原始搜索结果的标题 |
cited_text | string | 被引用的确切文本 |
search_result_index | integer | 搜索结果的索引(从0开始) |
start_block_index | integer | 内容数组中的起始位置 |
end_block_index | integer | 内容数组中的结束位置 |
注意:search_result_index
指的是搜索结果内容块的索引(从0开始),无论搜索结果是如何提供的(工具调用或顶级内容)。
多个内容块
搜索结果可以在 content
数组中包含多个文本块:
Claude可以使用 start_block_index
和 end_block_index
字段引用特定块。
高级用法
结合两种方法
您可以在同一对话中同时使用基于工具的和顶级搜索结果:
与其他内容类型结合
两种方法都支持将搜索结果与其他内容混合:
缓存控制
添加缓存控制以获得更好的性能:
引用控制
默认情况下,搜索结果的引用是禁用的。您可以通过显式设置 citations
配置来启用引用:
当 citations.enabled
设置为 true
时,Claude在使用搜索结果中的信息时将包含引用参考。这启用了:
- 为您的自定义RAG应用程序提供自然引用
- 与专有知识库接口时的来源归属
- 为任何返回搜索结果的自定义工具提供网络搜索质量的引用
如果省略 citations
字段,默认情况下引用是禁用的。
引用是全有或全无的:请求中的所有搜索结果都必须启用引用,或者所有搜索结果都必须禁用引用。混合使用不同引用设置的搜索结果将导致错误。如果您需要为某些来源禁用引用,则必须为该请求中的所有搜索结果禁用引用。
最佳实践
对于基于工具的搜索(方法1)
- 动态内容:用于实时搜索和动态RAG应用程序
- 错误处理:在搜索失败时返回适当的消息
- 结果限制:仅返回最相关的结果以避免上下文溢出
对于顶级搜索(方法2)
- 预获取内容:当您已经有搜索结果时使用
- 批处理:非常适合一次处理多个搜索结果
- 测试:非常适合使用已知内容测试引用行为
一般最佳实践
-
有效构建结果
- 使用清晰、永久的来源URL
- 提供描述性标题
- 将长内容分解为逻辑文本块
-
保持一致性
- 在您的应用程序中使用一致的来源格式
- 确保标题准确反映内容
- 保持格式一致
-
优雅地处理错误
- 搜索结果内容块仅在使用测试版标头时可用
- 搜索结果中仅支持文本内容(不支持图像或其他媒体)
content
数组必须包含至少一个文本块