网络搜索工具
网络搜索工具使Claude能够直接访问实时网络内容,允许它回答超出其知识截止日期的问题,提供最新信息。Claude会自动在回答中引用搜索结果中的来源。
请通过我们的反馈表单分享您使用网络搜索工具的体验。
支持的模型
网络搜索可用于:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (新版) (
claude-3-5-sonnet-latest
) - Claude Haiku 3.5 (
claude-3-5-haiku-latest
)
网络搜索的工作原理
当您在API请求中添加网络搜索工具时:
- Claude根据提示决定何时搜索。
- API执行搜索并向Claude提供结果。在单个请求中,这个过程可能会重复多次。
- 在其回合结束时,Claude会提供带有引用来源的最终回答。
如何使用网络搜索
您组织的管理员必须在控制台中启用网络搜索。
在您的API请求中提供网络搜索工具:
工具定义
网络搜索工具支持以下参数:
最大使用次数
max_uses
参数限制执行的搜索次数。如果Claude尝试的搜索次数超过允许的次数,web_search_tool_result
将返回一个带有max_uses_exceeded
错误代码的错误。
域名过滤
使用域名过滤器时:
- 域名不应包含HTTP/HTTPS协议(使用
example.com
而不是https://example.com
) - 子域名会自动包含(
example.com
涵盖docs.example.com
) - 支持子路径(
example.com/blog
) - 您可以使用
allowed_domains
或blocked_domains
,但不能在同一请求中同时使用两者。
本地化
user_location
参数允许您根据用户的位置本地化搜索结果。
type
:位置类型(必须是approximate
)city
:城市名称region
:地区或州country
:国家timezone
:IANA时区ID。
响应
以下是响应结构示例:
搜索结果
搜索结果包括:
url
:源页面的URLtitle
:源页面的标题page_age
:网站最后更新的时间encrypted_content
:加密内容,必须在多轮对话中传回以进行引用
引用
网络搜索始终启用引用,每个web_search_result_location
包括:
url
:被引用来源的URLtitle
:被引用来源的标题encrypted_index
:必须在多轮对话中传回的引用。cited_text
:最多150个字符的被引用内容
网络搜索引用字段cited_text
、title
和url
不计入输入或输出令牌使用量。
向最终用户显示网络结果或网络结果中包含的信息时,必须在您的用户界面中清晰显示内联引用并使其可点击。
错误
如果在网络搜索期间发生错误,您将收到以下形式的响应:
以下是可能的错误代码:
too_many_requests
:超出速率限制invalid_input
:无效的搜索查询参数max_uses_exceeded
:超出最大网络搜索工具使用次数query_too_long
:查询超出最大长度unavailable
:发生内部错误
pause_turn
停止原因
响应可能包含pause_turn
停止原因,这表示API暂停了一个长时间运行的回合。您可以在后续请求中按原样提供响应,让Claude继续其回合,或者如果您希望中断对话,可以修改内容。
提示缓存
网络搜索与提示缓存兼容。要启用提示缓存,请在您的请求中添加至少一个cache_control
断点。系统将自动缓存直到执行工具时的最后一个web_search_tool_result
块。
对于多轮对话,请在最后一个web_search_tool_result
块上或之后设置cache_control
断点,以重用缓存的内容。
例如,要在多轮对话中将提示缓存与网络搜索一起使用:
流式传输
启用流式传输后,您将收到作为流的一部分的搜索事件。在搜索执行期间会有暂停:
批量请求
您可以在Messages Batches API中包含网络搜索工具。通过Messages Batches API进行的网络搜索工具调用的定价与常规Messages API请求中的相同。
使用和定价
网络搜索使用量除了令牌使用量外还会收费:
网络搜索在Anthropic API上可用,每1,000次搜索收费10美元,外加搜索生成内容的标准令牌费用。在整个对话中检索的网络搜索结果计为输入令牌,包括在单个回合中执行的搜索迭代和后续对话回合中的搜索。
每次网络搜索计为一次使用,无论返回的结果数量如何。如果在网络搜索期间发生错误,则不会对该网络搜索收费。