GPT 联网搜索 (Web Search)¶
允许模型在生成响应之前搜索网络以获取最新信息。这使得模型可以访问互联网上最新的信息，并提供带有来源引用的答案。
目前在我们的平台（兼容 OpenAI 原生接口）上有两种主要方式使用 Web Search 工具：Responses API 和 Chat Completions API。
基础调用¶
1. 使用 Responses API¶
在 Responses API 中，你可以在 tools 数组中配置 web_search 工具。就像其他工具一样，模型会根据输入提示的内容自行决定是否进行网络搜索。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-5",
"tools": [{"type": "web_search"}],
"input": "今天的正面新闻有哪些？"
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5",
"tools": [{"type": "web_search"}],
"input": "what was a positive news story from today?"
}'
2. 使用 Chat Completions API¶
在使用 Chat Completions 时，模型会始终先从网络检索信息再响应你的查询。若要使用该功能，你必须指定特定的搜索模型（如 gpt-4o-search-preview），并通过 web_search_options 参数启用搜索。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-type: application/json" \
-d '{
"model": "gpt-4o-search-preview",
"web_search_options": {},
"messages": [{
"role": "user",
"content": "今天的正面新闻有哪些？"
}]
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-type: application/json" \
-d '{
"model": "gpt-4o-search-preview",
"web_search_options": {},
"messages": [{
"role": "user",
"content": "What was a positive news story from today?"
}]
}'
输出与引用 (Output and citations)¶
默认情况下，模型的响应将包含在网络搜索结果中找到的 URL 的内联引用（inline citations）。
Responses API 的输出¶
Responses 的响应将包含两部分：
1. 一个 web_search_call 输出项，包含搜索调用的 ID 和执行的操作（如 search、open_page）。
2. 一个 message 输出项，包含文本结果（message.content[0].text）以及对引用 URL 的注释（message.content[0].annotations）。
在 url_citation 注解对象中，将包含被引用来源的 URL、标题和位置。
[
{
"type": "web_search_call",
"id": "ws_67c9fa05...",
"status": "completed"
},
{
"id": "msg_67c9fa07...",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "在2025年3月6日，有多条新闻报道了...",
"annotations": [
{
"type": "url_citation",
"start_index": 2606,
"end_index": 2758,
"url": "https://...",
"title": "Title..."
}
]
}
]
}
]
Chat Completions API 的输出¶
返回的 choices 数组将包含：
* message.content：包含模型的文本结果，以及任何内联引用。
* message.annotations：包含引用的 URL 列表，同样使用 url_citation 提供引用详情和在内容中的 start_index 与 end_index。
[
{
"index": 0,
"message": {
"role": "assistant",
"content": "模型的回复内容在这里...",
"refusal": null,
"annotations": [
{
"type": "url_citation",
"url_citation": {
"end_index": 985,
"start_index": 764,
"title": "Page title...",
"url": "https://..."
}
}
]
},
"finish_reason": "stop"
}
]
域名过滤 (Domain filtering)¶
域名过滤允许你将搜索结果限制在特定的域名集合中。你可以使用 filters.allowed_domains 参数设置最多 100 个 URL 的白名单。
注意：域名过滤目前**仅在 Responses API** 中的
web_search工具可用。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-5",
"tools": [
{
"type": "web_search",
"filters": {
"allowed_domains": [
"pubmed.ncbi.nlm.nih.gov",
"www.who.int",
"www.cdc.gov"
]
}
}
],
"input": "搜索关于 Semaglutide 治疗糖尿病的相关研究。"
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5",
"tools": [
{
"type": "web_search",
"filters": {
"allowed_domains": [
"pubmed.ncbi.nlm.nih.gov",
"www.who.int",
"www.cdc.gov"
]
}
}
],
"input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
}'
信源列表 (Sources)¶
要查看网络搜索期间检索到的所有 URL，你可以使用 include: ["web_search_call.action.sources"]。与仅显示最相关参考文献的内联引用（citations）不同，sources 返回模型在形成其响应时查阅的完整 URL 列表。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-5",
"tools": [{"type": "web_search"}],
"tool_choice": "auto",
"include": ["web_search_call.action.sources"],
"input": "解释一下量子计算的最新进展。"
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5",
"reasoning": { "effort": "low" },
"tools": [{"type": "web_search"}],
"tool_choice": "auto",
"include": ["web_search_call.action.sources"],
"input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
}'
用户位置 (User location)¶
为了基于地理位置优化搜索结果，你可以使用 user_location 参数指定大概的用户位置（包括国家 country、城市 city、地区 region 或时区 timezone）。
Responses API 中的使用¶
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "o4-mini",
"tools": [{
"type": "web_search",
"user_location": {
"type": "approximate",
"country": "CN",
"city": "Shanghai",
"region": "Shanghai"
}
}],
"input": "我附近有哪些推荐的景点？"
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "o4-mini",
"tools": [{
"type": "web_search",
"user_location": {
"type": "approximate",
"country": "GB",
"city": "London",
"region": "London"
}
}],
"input": "What are the best restaurants near me?"
}'
Chat Completions API 中的使用¶
在 Chat 模型中，你可以将 user_location 包含在 web_search_options 里。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-type: application/json" \
-d '{
"model": "gpt-4o-search-preview",
"web_search_options": {
"user_location": {
"type": "approximate",
"approximate": {
"country": "CN",
"city": "Beijing",
"region": "Beijing"
}
}
},
"messages": [{
"role": "user",
"content": "我附近最好的餐厅是哪家？"
}]
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-type: application/json" \
-d '{
"model": "gpt-4o-search-preview",
"web_search_options": {
"user_location": {
"type": "approximate",
"approximate": {
"country": "GB",
"city": "London",
"region": "London"
}
}
},
"messages": [{
"role": "user",
"content": "What are the best restaurants near me?"
}]
}'
控制实时互联网访问 (Live internet access)¶
你可以通过在 Responses API 中的 web_search 工具上设置 external_web_access: false，来控制工具是否抓取实时内容，还是仅使用离线/缓存（indexed）结果。默认情况为 true。
注意：预览版本（
web_search_preview）会忽略此参数并一律表现为true。
本站示例 (New API 平台)
curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-5",
"tools": [
{ "type": "web_search", "external_web_access": false }
],
"tool_choice": "auto",
"input": "请帮我查找今天巴黎的日出时间并附上来源。"
}'
OpenAI 官方示例
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5",
"tools": [
{ "type": "web_search", "external_web_access": false }
],
"tool_choice": "auto",
"input": "Find the sunrise time in Paris today and cite the source."
}'
API 兼容性 (API compatibility)¶
Web search 目前支持：
* Responses API：你可以使用通用版本 web_search 工具，或早期版本 web_search_preview 工具。
* Chat Completions API：必须使用专门的搜索模型来启用 Web Search。当前支持的模型包括：
* gpt-5-search-api
* gpt-4o-search-preview
* gpt-4o-mini-search-preview
限制说明 (Limitations)¶
- Web Search 工具当前**不支持**带有
minimalreasoning 配置的gpt-5模型，以及gpt-4.1-nano等模型。 - 在 Responses API 中作为工具使用时，它的速率限制与所选用模型的级别速率限制相同。
- Web Search 功能将受到 128,000 上下文窗口的限制（包含
gpt-4.1与gpt-4.1-mini系列）。
使用说明 (Usage notes)¶
| API 可用性 | 速率限制 (Rate limits) |
|---|---|
| Responses Chat Completions |
与作为底层工具被调用的**模型**拥有相同的速率限制。 |