火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟调用工具调用联网搜索工具
复制全文
下载 pdf联网搜索工具
文档反馈
问问助手联网搜索工具可以为大模型获取实时的公开网络信息，适用于新闻、商品、天气、行业动态和事实核验等场景。您可以根据接口协议、搜索来源和搜索控制需求选择合适的工具。
支持的工具
联网搜索场景支持以下工具：
开通组件
- 登录方舟控制台，打开应用组件库 > 豆包搜索标签页。
- 在豆包搜索 Custom 版的操作列中点击开通服务。
- 登录方舟控制台，打开应用组件库 > 应用组件标签页。
- 在联网内容插件的操作列中点击开通服务。
示例代码
说明
豆包搜索 Custom 版
请求示例：
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seed-2-1-pro-260628",
"stream": true,
"tools": [
{
"type": "web_search",
"sources": ["doubao"]
}
],
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "今天有什么 AI 领域的热点新闻？"
}
]
}
]
}'
curl https://ark.cn-beijing.volces.com/api/compatible/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ARK_API_KEY" \
-d '{
"model": "doubao-seed-2-1-pro-260628",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
"messages": [
{
"role": "user",
"content": "今天有什么 AI 领域的热点新闻？"
}
]
}'
返回示例：
{
"id": "resp_02178849073345588e74****",
"object": "response",
"model": "doubao-seed-2-1-pro-260628",
"status": "completed",
"output": [
{
"id": "rs_02178849073770400000****",
"type": "reasoning",
"status": "completed",
"summary": [
{
"type": "summary_text",
"text": "用户需要获取 2026 年 9 月 4 日的 AI 领域热点新闻，我将使用网页搜索工具，通过时间限定关键词检索相关信息。"
}
],
"encrypted_content": "djFlkf4Bo9PjH2A5r+39.../9yJWTg="
},
{
"id": "ws_02178849074154500000****",
"type": "web_search_call",
"status": "completed",
"action": {
"type": "search",
"query": "2026年9月4日 AI领域热点新闻",
"queries": [
"2026年9月4日 AI领域热点新闻"
]
}
},
{
"id": "msg_02178849076046900000****",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "2026年9月4日 AI 领域的核心热点是 OpenAI 正式发布新一代旗舰大模型 GPT-6 Astra。",
"annotations": [
{
"type": "url_citation",
"title": "OpenAI，发布“地球最强大模型”GPT-6：欢迎进入 AGI 时代！",
"url": "https://news.sina.cn/2026-09-04/detail-iniqrpra63******.d.html",
"site_name": "新浪新闻",
"publish_time": "2026-09-04T10:24:00+08:00",
"summary": "当地时间 9 月 3 日，OpenAI 正式发布新一代旗舰模型 GPT-6 Astra，并称其实现“代际跃迁”。"
}
]
}
]
}
],
"usage": {
"input_tokens": 3666,
"output_tokens": 1610,
"total_tokens": 5276,
"tool_usage": {
"web_search": 1
},
"tool_usage_details": {
"web_search": {
"doubao": 1
}
}
}
}
{
"id": "021788491735391ee3582c20fb7529745750c3f00520e5c262****",
"type": "message",
"role": "assistant",
"model": "doubao-seed-2-1-pro-260628",
"content": [
{
"type": "thinking",
"thinking": "我将调用搜索工具获取 2026 年 9 月 4 日的 AI 热点新闻，再基于搜索结果整理回答。",
"signature": "djE09ahKIu8KsvSLLVrg...Nf/EYMTk3hjlMg=="
},
{
"type": "server_tool_use",
"id": "srvtoolu_2ccc8b83a8d345f8be35d32b457e****",
"name": "web_search",
"input": {
"query": "2026年9月4日 AI领域热点新闻"
}
},
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_2ccc8b83a8d345f8be35d32b457e****",
"content": [
{
"type": "web_search_result",
"title": "OpenAI，发布“地球最强大模型”GPT-6：欢迎进入AGI时代！山姆·奥特曼首次明确表示：一定会做人形机器人",
"url": "https://news.sina.cn/2026-09-04/detail-iniqrpra63****.d.html",
"page_age": "2026-09-04T10:24:00+08:00",
"encrypted_content": "djGk3VaymgA8eiuLkR7w...0QazEoRxp46hi3n/Zd5L2aG3kN7cexLZzcoSdoA6f34iEEJBw=="
},
{
"type": "web_search_result",
"title": "OpenAI最强模型GPT-6 Astra发布，公司总裁称AGI时代到来",
"url": "http://finance.sina.cn/stock/jdts/2026-09-04/detail-iniqrpqy08****.html",
"page_age": "2026-09-04T10:25:00+08:00",
"encrypted_content": "djEz4PKCbjpmdizu9giy...p4I8TYtvYardgTA9CgOtejh6rWWpAFvj29xL+I/mK1vAOPs0tm+4NU=="
}
]
},
{
"type": "text",
"text": "根据 2026 年 9 月 4 日的 AI 领域最新热点，最重磅的事件是 OpenAI 正式发布新一代旗舰大模型 GPT-6 Astra。"
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 3770,
"output_tokens": 1859,
"cache_read_input_tokens": 0,
"server_tool_use": {
"web_search_requests": 1,
"web_fetch_requests": 0
}
}
}
联网内容插件
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seed-2-1-pro-260628",
"stream": true,
"tools": [
{
"type": "web_search",
"max_keyword": 2
}
],
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "今天有什么热点新闻？"
}
]
}
]
}'
import os
from volcenginesdkarkruntime import Ark
# To obtain the api key from your environment variables, see: https://ark.volcengine.com/region:cn-beijing/docs/82379/1820161
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
tools = [{
"type": "web_search",
"max_keyword": 2,
}]
# Create a conversation request
response = client.responses.create(
model="doubao-seed-2-1-pro-260628",
input=[{"role": "user", "content": "今天有什么热点新闻？"}],
tools=tools,
)
print(response)
package com.ark.example;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.volcengine.ark.runtime.models.responses.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.Arrays;
import java.util.List;
public class demo {
public static ObjectMapper om = new ObjectMapper();
public demo() throws JsonProcessingException {
}
public static List<Tool> buildTools() {
WebSearchTool t = WebSearchTool.builder()
.build();
System.out.println(Arrays.asList(t));
return Arrays.asList(t);
}
public static void main(String[] args) throws JsonProcessingException {
String apiKey = System.getenv("ARK_API_KEY");
// Create an ArkService instance
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
ResponsesRequest req = ResponsesRequest.builder()
.model("doubao-seed-2-1-pro-260628")
.input(ResponsesInput.ofList(java.util.Arrays.asList(ItemEasyMessage.builder().role(MessageRole.USER).content(
MessageContent.ofList(java.util.Arrays.asList(ContentItemText.builder().text("今天有什么热点新闻？").build()))
).build())))
.tools(buildTools())
.build();
Response resp = arkService.createResponse(req);
System.out.println(resp);
arkService.shutdownExecutor();
}
}
package main
import (
"context"
"fmt"
"io"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
request := &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260628",
Input: responses.NewStringResponsesInput(
"请查询今天的重要 AI 产品发布，并给出来源。",
),
Tools: []responses.Tool{
{
OneOf: responses.NewWebSearchToolToolSum(
responses.WebSearchTool{
Type: responses.WebSearchToolTypeWebSearch,
},
),
},
},
MaxToolCalls: responses.NewOptInt64(1),
}
stream, err := client.CreateResponsesStream(context.Background(), request)
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
for {
event, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
switch event.OneOf.Type {
case responses.ResponseTextDeltaEventResponseStreamEventSum:
print(event.OneOf.ResponseTextDeltaEvent.Delta.Or(""))
case responses.ResponseWebSearchCallInProgressEventResponseStreamEventSum:
fmt.Println("web search started")
case responses.ResponseWebSearchCallCompletedEventResponseStreamEventSum:
fmt.Println("web search completed")
}
}
fmt.Println()
}
参数说明
Responses API（兼容 OpenAI Responses 接口协议）
通过 Responses API 调用豆包搜索 Custom 版时，工具类型仍为 web_search，并需要将 sources 显式设置为 ["doubao"]。doubao 不能与其他搜索来源同时配置。
- tools.type：固定为 web_search。
- tools.sources：固定传入 ["doubao"]。
- tools.limit：参数不生效，传入的值将被忽略。
- tools.max_keyword：参数不生效，传入的值将被忽略。
- tools.user_location：参数不生效，传入的值将被忽略。
- max_tool_calls：限制一次模型响应中可执行工具调用的最大轮次。
Messages API（兼容 Anthropic Messages 接口协议）
通过 Messages API 调用豆包搜索 Custom 版时，使用兼容 Anthropic Messages 接口协议的服务端工具配置：
- tools.name：工具名称。本文示例固定为 web_search。
- tools.type：工具类型或版本标识。本文示例使用 web_search_20250305。
- tools.max_uses：单个服务端工具在一次请求中的最大调用次数。
- tools.user_location：参数不生效，传入的值将被忽略。
- tools.allowed_domains：限制搜索结果仅来自允许访问的域名列表。
- tools.blocked_domains：限制搜索结果不包含禁止访问的域名列表。
Agent 场景下的用法
您可以在 Claude Code 或 Codex 中调用豆包搜索 Custom 版工具，该工具兼容 Anthropic Messages 接口协议和 OpenAI Responses API 接口协议。
Claude Code 通过兼容 Anthropic Messages 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Claude Code 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见在 Claude Code 中使用 Web Search 工具。
注意
调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Codex 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见在 Codex 中使用 Web Search 工具。
注意
调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
API 调用场景下的用法与配置
本节介绍联网搜索场景中的工具用法与常用配置。不同工具的差异以相关说明为准。
注意
本节内容仅适用于 Responses API，不适用于 Messages API。
开启流式调用
在 response 中设置 stream=True，即可开启流式调用，使响应以流式方式返回，从而更快地获取部分结果，同时可实时查看模型判断是否调用搜索的思考过程。
示例：
response = client.responses.create(
model="doubao-seed-2-1-pro-260628",
input=[ # 输入内容，包含系统提示和用户问题
...
],
tools=[ # 使用工具及参数
...
],
stream=True, # 启用流式响应（实时返回结果，而非等待全部完成）
)
设置搜索来源
豆包搜索 Custom 版和联网内容插件的搜索来源配置方式不同：
- 豆包搜索 Custom 版：
- 通过 Responses API 调用时，工具类型仍为 web_search，并需要将 sources 显式设置为 ["doubao"]。doubao 不能与其他搜索来源同时配置。
- 通过 Messages API 调用时，使用的是兼容 Anthropic Messages 接口协议的服务端工具配置。本文示例中 tools.type 使用 web_search_20250305。
- 联网内容插件：默认通过 search_engine 搜索全网内容。您可以通过 tools.sources 添加以下内容源：
- "douyin"：抖音百科。
- "moji"：墨迹天气。
- "toutiao"：头条图文。
示例：
tools=[
{
"type": "web_search", # 配置工具类型为联网内容插件
"sources": ["douyin", "moji", "toutiao"], # 附加搜索来源（抖音百科、墨迹天气、头条图文等平台）
}
],
指定用户地理位置
您可以在 tools 中设置 user_location 字段，并提供用户的国家、地区和城市信息，以优化与地理位置相关的搜索结果。
示例：
tools=[
{
"type": "web_search", # 配置工具类型为联网内容插件
"user_location": { # 指定用户地理位置（用于优化搜索结果）
"type": "approximate", # 大致位置
"country": "中国",
"region": "浙江",
"city": "杭州"
}
}
],
设置搜索限制
说明
以下搜索限制参数仅联网内容插件支持，豆包搜索 Custom 版不支持。即当 sources 的值为 ["doubao"] 时，tools.limit、tools.max_keyword、tools.user_location 均不生效，向它们传入的值将被忽略。
- tools.max_keyword
- 作用：限制单轮搜索中可使用的最大关键词数量。
- 取值范围：1～50。
- 示例：如果模型原本计划搜索三个关键词（例如“大模型最新进展”、“2025 年科技创新”），但将 max_keyword 设置为 1，模型将仅使用第一个关键词进行搜索。关于 max_keyword 参数的具体使用方法和示例，请参见 创建模型响应。
- tools.limit
- 作用：限制单轮搜索操作返回的最大结果条数。
- 取值范围：1～50。
- 默认值：10。
- 说明：此参数会影响返回内容的规模和请求性能。单次搜索最多可返回 20 条结果，但单轮可能有多次搜索，默认召回 10 条。
- max_tool_calls
- 作用：限制在一次完整的模型响应中可以执行工具调用的最大轮次。
- 取值范围：1～10。
- 默认值：3。
示例：
tools = [{
"type": "web_search",
"max_keyword": 2,
"limit": 10,
}]
max_tool_calls = 3
查询搜索用量
您可以在 API 返回的参数中查看工具使用情况：
- usage.tool_usage：显示 Responses API 中工具的总调用次数。
- usage.tool_usage_details：显示 Responses API 中每个搜索源的详细调用次数，例如 search_engine、toutiao 或 doubao。
- Messages API：通过 usage.server_tool_use.web_search_requests 查看服务端工具发起的联网搜索请求次数。
设置系统提示词
系统提示词的设置对搜索请求的影响较大，建议进行优化以提升搜索的准确性与效率。以下两种系统提示词模板供您参考。
模板 1：
# 定义系统提示词
system_prompt = """
你是AI个人助手，负责解答用户的各种问题。你的主要职责是：
1. **信息准确性守护者**：确保提供的信息准确无误。
2. **搜索成本优化师**：在信息准确性和搜索成本之间找到最佳平衡。
# 任务说明
## 1. 联网意图判断
当用户提出的问题涉及以下情况时，需使用 `web_search` 进行联网搜索：
- **时效性**：问题需要最新或实时的信息。
- **知识盲区**：问题超出当前知识范围，无法准确解答。
- **信息不足**：现有知识库无法提供完整或详细的解答。
## 2. 联网后回答
- 在回答中，优先使用已搜索到的资料。
- 回复结构应清晰，使用序号、分段等方式帮助用户理解。
## 3. 引用已搜索资料
- 当使用联网搜索的资料时，在正文中明确引用来源，引用格式为：
`[1] (URL地址)`。
## 4. 总结与参考资料
- 在回复的最后，列出所有已参考的资料。格式为：
1. [资料标题](URL地址1)
2. [资料标题](URL地址2)
"""
模板 2：
# 定义系统提示词
system_prompt = """
# 角色
你是AI个人助手，负责解答用户的各种问题。你的主要职责是：
1. **信息准确性守护者**：确保提供的信息准确无误。
2. **回答更生动活泼**：请在模型的回复中多使用适当的 emoji 标签 🌟😊🎉
# 任务说明
## 1. 联网意图判断
当用户提出的问题涉及以下情况时，需使用 `web_search` 进行联网搜索：
- **时效性**：问题需要最新或实时的信息。
- **知识盲区**：问题超出当前知识范围，无法准确解答。
- **信息不足**：现有知识库无法提供完整或详细的解答。
## 2. 联网后回答
- 在回答中，优先使用已搜索到的资料。
- 回复结构应清晰，使用序号、分段等方式帮助用户理解。
## 3. 引用已搜索资料
- 当使用联网搜索的资料时，在正文中明确引用来源，引用格式为：
`[1] (URL地址)`。
## 4. 总结与参考资料
- 在回复的最后，列出所有已参考的资料。格式为：
1. [资料标题](URL地址1)
2. [资料标题](URL地址2)
"""
注意事项
- 自定义函数名称应避免使用 web_search，否则模型可能按内置工具优先级判断调用逻辑。
- doubao 只能单独配置，不能与 toutiao、douyin、moji 或 search_engine 等其他搜索来源同时使用。
- 豆包搜索 Custom 版支持 Responses API 和 Messages API；联网内容插件仅支持 Responses API。
- 联网内容插件是否触发搜索由模型判断。一轮搜索可能发起多个关键词搜索，可以通过 max_keyword 参数限制一轮搜索的关键词数量，以控制调用频次和成本。
- 豆包搜索 Custom 版和联网内容插件均不支持 caching 参数，该参数不可与 tools 参数一起使用，否则会返回 400 错误。
相关文档
- 计费
- 豆包搜索 Custom 版
- 普通 API 调用场景：豆包搜索产品计费
- Agent Plan 场景：套餐内 AFP 抵扣规则、超额后付费规则
- Coding Plan 场景：套餐概览
- 联网内容插件：按联网内容插件实际使用次数计费。具体收费标准详见联网内容插件产品计费。
- Agent 场景使用方法
- API 参考
- 错误码说明：错误码
最近更新时间：2026.09.13 21:16:06
这个页面对您有帮助吗？
有用
有用
无用
无用