搜索结果内容块目前处于测试阶段。使用 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网络搜索功能的引用质量和格式

工作原理

搜索结果可以通过两种方式提供:

  1. 来自工具调用 - 您的自定义工具返回搜索结果,启用动态RAG应用程序
  2. 作为顶级内容 - 您直接在用户消息中提供搜索结果,用于预获取或缓存的内容

在这两种情况下,Claude都可以自动引用搜索结果中的信息并进行适当的来源归属。

搜索结果架构

搜索结果使用以下结构:

{
  "type": "search_result",
  "source": "https://example.com/article",  // 必需:来源URL或标识符
  "title": "文章标题",                  // 必需:结果标题
  "content": [ // 必需:文本块数组
    {
      "type": "text",
      "text": "搜索结果的实际内容..."
    }
  ],
  "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.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="如何配置超时设置?"
        )
    ]
)

# 当Claude调用工具时,提供搜索结果
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在使用其中的信息时都会自动包含引用:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "要验证API请求,您需要在Authorization标头中包含API密钥",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API参考 - 身份验证",
          "cited_text": "所有API请求都必须在Authorization标头中包含API密钥",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": "。您可以从仪表板生成API密钥",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API参考 - 身份验证",
          "cited_text": "密钥可以从仪表板生成",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": "。速率限制为标准层每小时1,000个请求,高级层每小时10,000个请求。",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "API参考 - 身份验证",
          "cited_text": "速率限制:标准层每小时1000个请求,高级层10000个",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

引用字段

每个引用包括:

字段类型描述
typestring搜索结果引用始终为 "search_result_location"
sourcestring来自原始搜索结果的来源
titlestring或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文档",
  "content": [
    {
      "type": "text",
      "text": "身份验证:所有API请求都需要API密钥。"
    },
    {
      "type": "text",
      "text": "速率限制:API允许每个密钥每小时1000个请求。"
    },
    {
      "type": "text",
      "text": "错误处理:API返回标准HTTP状态码。"
    }
  ]
}

Claude可以使用 start_block_indexend_block_index 字段引用特定块。

高级用法

结合两种方法

您可以在同一对话中同时使用基于工具的和顶级搜索结果:

# 带有顶级搜索结果的第一条消息
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="产品概述",
                content=[
                    BetaTextBlockParam(type="text", text="我们的产品帮助团队协作...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="告诉我关于这个产品的信息并搜索定价信息"
            )
        ]
    )
]

# Claude可能会响应并调用工具来搜索定价
# 然后您提供带有更多搜索结果的工具结果

与其他内容类型结合

两种方法都支持将搜索结果与其他内容混合:

# 在工具结果中
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="用户指南",
        content=[BetaTextBlockParam(type="text", text="配置详细信息...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="附加上下文:这适用于2.0版本及更高版本。"
    )
]

# 在顶级内容中
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="研究论文",
        content=[BetaTextBlockParam(type="text", text="关键发现...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="图表与研究发现有何关系?"
    )
]

缓存控制

添加缓存控制以获得更好的性能:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "用户指南",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

引用控制

默认情况下,搜索结果的引用是禁用的。您可以通过显式设置 citations 配置来启用引用:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "用户指南",
  "content": [{"type": "text", "text": "重要文档..."}],
  "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": "未找到结果。"}
            return format_as_search_results(results)
        except Exception as e:
            return {"type": "text", "text": f"搜索错误:{str(e)}"}
    

限制

  • 搜索结果内容块仅在使用测试版标头时可用
  • 搜索结果中仅支持文本内容(不支持图像或其他媒体)
  • content 数组必须包含至少一个文本块