网页搜索允许模型访问互联网上的最新信息,并在回答时提供带有来源的引用。要启用此功能,请在 Responses API 中使用网页搜索工具,或者在部分场景下使用 Chat Completions。
OpenAI 模型提供三种主要类型的网页搜索:
- 非推理网页搜索:非推理模型将用户查询发送至网页搜索工具,该工具根据最相关的结果返回响应。模型没有内部规划,仅直接传递搜索工具的响应。此方法速度快,非常适合快速查询。
- 使用推理模型的智能体搜索是一种由模型主动管理搜索过程的方法。它可以在其思维链中执行网页搜索,分析结果,并决定是否继续搜索。这种灵活性使智能体搜索非常适合复杂的工作流,但也意味着搜索耗时比快速查询更长。例如,你可以在以下模型上调整推理级别:
gpt-5.5以同时改变搜索的深度和延迟。 - 深度研究是一种由推理模型执行的专门的、由智能体驱动的深入、长时间调查方法。模型在其思维链中进行网页搜索,通常会查阅数百个信息源。深度研究可能需要运行几分钟,建议在后台模式下使用。使用
gpt-5.5with reasoning set tohighorxhigh.
选择一种集成方式
| 用例 | 推荐路径 | 备注 |
|---|---|---|
| 新的网页搜索集成 | Responses API 搭配 web_search and gpt-5.5 | 支持托管的网页搜索控制,例如过滤器、来源、实时访问控制以及更长的研究任务 |
| 现有的 Chat Completions 搜索集成 | Chat Completions 搭配 gpt-5-search-api | 仅在需要保留现有 Chat Completions 集成时使用 |
| 多步骤研究或长时间运行的报告 | gpt-5.5 with high or xhigh 推理 | 对可能耗时数分钟的报告使用后台模式 |
使用 API 请求中的 Responses API,您可以通过在 tools 数组来生成内容。与任何其他工具一样,模型可以根据输入提示的内容自主选择是否搜索网页。
对于新的 Responses API 集成,请使用 { "type": "web_search" }中进行配置来启用网络搜索。早期的 web_search_preview 工具仍可用于遗留集成,但它不支持较新的控制功能,例如 filters, external_web_access,且 return_token_budget.
1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-5.5",
tools: [
{ type: "web_search" },
],
input: "What was a positive news story from today?",
});
console.log(response.output_text);输出与引用
使用网页搜索工具的模型响应将包含两部分:
- A
web_search_call输出项,包含搜索调用的 ID 以及在web_search_call.action。该操作为以下之一:search,表示网络搜索。它通常(但不总是)包含搜索queries中所执行的操作。搜索操作会产生工具调用费用(参见 定价).open_page,表示正在打开一个网页。推理模型支持此操作。find_in_page,表示在网页内进行搜索。推理模型支持此操作。
- A
message输出项,包含:- The text result in
message.content[0].text - 注释
message.content[0].annotationsfor the cited URLs
- The text result in
默认情况下,模型的回复将包含网络搜索结果中 URL 的内联引用。除此之外, url_citation annotation 对象将包含所引用来源的 URL、标题和位置。
在向最终用户展示网络搜索结果或其中包含的信息时,必须在您的用户界面中清晰展示内联引用,并确保其可点击。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
{
"type": "web_search_call",
"id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
"status": "completed",
"action": {
"type": "search",
"query": "latest news about AI"
}
},
{
"id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "On March 6, 2025, several news...",
"annotations": [
{
"type": "url_citation",
"start_index": 2606,
"end_index": 2758,
"url": "https://...",
"title": "Title..."
}
]
}
]
}
]使用 API 请求中的 Chat Completions API,您可以直接访问由 ChatGPT 中的搜索.
使用 Chat Completions 时,模型在响应您的查询之前,始终会先从网络检索信息。若要让模型自行决定是否进行搜索,请切换至 Responses API with the web_search tool.
目前,请使用此模型在 Chat Completions 中进行网络搜索:
gpt-5-search-api
1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const client = new OpenAI();
const completion = await client.chat.completions.create({
model: "gpt-5-search-api",
web_search_options: {},
messages: [{
"role": "user",
"content": "What was a positive news story from today?"
}],
});
console.log(completion.choices[0].message.content);输出与引用
位于 choices 数组中的 API 响应项将包含:
message.content以及来自模型的文本结果(包含所有内联引用)annotations以及引用的 URL 列表
默认情况下,模型的回复将包含网络搜索结果中 URL 的内联引用。除此之外, url_citation annotation 对象将包含所引用来源的 URL 和标题,以及在模型响应中使用这些来源的起始和结束索引字符。
在向最终用户展示网络搜索结果或其中包含的信息时,必须在您的用户界面中清晰展示内联引用,并确保其可点击。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
{
"index": 0,
"message": {
"role": "assistant",
"content": "the model response is here...",
"refusal": null,
"annotations": [
{
"type": "url_citation",
"url_citation": {
"end_index": 985,
"start_index": 764,
"title": "Page title...",
"url": "https://..."
}
}
]
},
"finish_reason": "stop"
}
]从旧版网络搜索迁移
| 如果您使用 | 推荐路径 | 备注 |
|---|---|---|
web_search_preview in Responses | 迁移至 web_search | web_search 支持更新的控件,例如 filters, external_web_access,且 return_token_budget |
gpt-4o-search-preview or gpt-4o-mini-search-preview | 迁移到 Responses web_search使用的微调模型和工具,或使用 gpt-5-search-api 如果你必须继续使用 Chat Completions | 预览版搜索模型将于 2026-07-23 弃用并关闭 |
| Chat Completions 搜索集成 | 使用 gpt-5-search-api,或迁移至 Responses web_search 以获取更多工具控制和可选搜索 | Chat Completions 搜索模型在响应前始终进行搜索;Responses 搜索是一个工具 |
搜索上下文大小
search_context_size 控制模型在生成响应之前,有多少来自网页搜索结果的上下文可供其使用。使用 low for simple lookups, medium 以获得均衡的默认设置,而在 high 当答案可能需要搜索结果中的更多细节时使用。此设置不会设定确切的 token 数量,也不保证特定数量的来源或引用。
1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();
const response = await openai.responses.create({
model: "gpt-5.5",
tools: [{
type: "web_search",
search_context_size: "low",
}],
input: "What movie won best picture in 2025?",
});
console.log(response.output_text);运行更长的网络研究
return_token_budget 控制在 Responses API 搜索运行期间,配合 GPT-5+ 推理模型时该工具可以返回多少网页搜索结果内容。对于大多数请求,请保持默认值。仅当 unlimited 仅适用于需要检查大量页面且可能会在达到标准返回 token 上限时停止的高投入研究或评估运行时,才将其设置为
使用 unlimited 请谨慎选择,因为这会增加延迟和成本。对于运行时间较长的多搜索任务,请使用后台模式(background: true),这样请求可以继续异步运行,你可以在稍后获取最终响应。
| 值 | 行为 |
|---|---|
default | 对 Web 搜索结果使用标准的返回 token 预算。这与省略该参数时的行为相同 return_token_budget. |
unlimited | 移除 Web 搜索运行的默认返回 token 预算。 |
此参数仅适用于托管 Responses API web_search 搭配 GPT-5+ 推理网页搜索工具。它不会更改搜索上下文窗口,也不适用于非推理网页搜索、旧版 Search API 路径、容器网页搜索、Chat Completions 搜索模型或 web_search_preview。仅 default and unlimited 是支持的值; null,数字和其他字符串会被拒绝。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5.5",
"reasoning": { "effort": "xhigh" },
"tools": [
{
"type": "web_search",
"return_token_budget": "unlimited"
}
],
"input": "Research the economic impact of semaglutide on global healthcare systems.\n\nDo:\n- Include specific figures, trends, statistics, and measurable outcomes.\n- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.\n- Include inline citations and return all source metadata.\n\nBe analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
}'域名过滤
网页搜索中的域名过滤允许你将结果限定在一组特定的域名内。使用 filters 参数,你最多可以配置 100 个 allowed_domains or up to 100 blocked_domains。格式化域名时,请省略 HTTP 或 HTTPS 前缀。例如,使用 openai.com 而不是 https://openai.com/。此方法还会将子域名包含在搜索中。请注意,域名过滤仅在 Responses API 中通过 web_search tool.
来源
要查看网页搜索期间检索到的所有 URL,请使用 sources 字段。与仅显示最相关引用的行内引用不同,来源会返回模型在生成响应时参考过的完整 URL 列表。来源的数量通常多于引用的数量。实时第三方数据源也会在此处显示,并标记为 oai-sports, oai-weather, or oai-finance可用。sources 字段在使用 web_search and web_search_preview tools.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5.5",
"reasoning": { "effort": "low" },
"tools": [
{
"type": "web_search",
"filters": {
"allowed_domains": [
"pubmed.ncbi.nlm.nih.gov",
"clinicaltrials.gov",
"www.who.int",
"www.cdc.gov",
"www.fda.gov"
],
"blocked_domains": [
"reddit.com",
"quora.com",
"wikipedia.org"
]
}
}
],
"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."
}'用户位置
为了根据地理位置优化搜索结果,您可以使用国家、城市、地区和/或时区指定大致的用户位置。
- The
cityandregion字段是自由文本字符串,例如MinneapolisandMinnesotarespectively. - The
country字段是双字母 ISO 国家代码时均可用,例如US. - The
timezone字段是 IANA 时区 则America/Chicago.
请注意,使用网页搜索的深度研究模型不支持用户位置。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import OpenAI from "openai";
const openai = new OpenAI();
const response = await openai.responses.create({
model: "gpt-5.5",
tools: [{
type: "web_search",
user_location: {
type: "approximate",
country: "GB",
city: "London",
region: "London"
}
}],
input: "What are the best restaurants near me?",
});
console.log(response.output_text);1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import OpenAI from "openai";
const client = new OpenAI();
const completion = await client.chat.completions.create({
model: "gpt-5-search-api",
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?",
}],
});
console.log(completion.choices[0].message.content);实时互联网访问
控制在 Responses API 中,网页搜索工具是获取实时内容还是仅使用缓存/已索引的结果。
- 设置
external_web_access: false将web_search工具设置为以离线/仅缓存模式运行。 - 默认为
true(实时访问)如果您未进行设置。 - 预览变体(
web_search_preview) 忽略此参数,其行为类似于external_web_accessistrue.
1
2
3
4
5
6
7
8
curl "https://api.openai.com/v1/responses" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_API_KEY" -d '{
"model": "gpt-5.5",
"tools": [
{ "type": "web_search", "external_web_access": false }
],
"tool_choice": "auto",
"input": "Find when the Eiffel Tower opened to the public and cite the source."
}'限制
Chat Completions API
Chat Completions API 仅支持使用专门的搜索模型进行网页搜索。这些模型不支持 Responses API 的 web_search 功能,例如域名过滤、完整来源列表、实时访问控制以及返回 token 预算控制。
| 模型 | 上下文窗口 | 限制 |
|---|---|---|
gpt-5-search-api | 200k | 使用 Chat Completions 搜索模型路径 |
gpt-4o-search-preview | 128k | 使用 Chat Completions 搜索模型路径; 已弃用,将于 2026-07-23 关闭 |
gpt-4o-mini-search-preview | 128k | 使用 Chat Completions 搜索模型路径; 已弃用,将于 2026-07-23 关闭 |
Responses API
使用托管的 web_search 工具。Responses API 仍接受 web_search_preview 用于旧版集成,但请使用 web_search for new integrations.
如需更大的模型上下文窗口,请使用 gpt-5.5。网络搜索上下文窗口仍为 128k。
| 模型 | 模型上下文窗口 | 限制 |
|---|---|---|
gpt-4.1 | 1M | 搜索上下文限制为 128k |
gpt-4.1-mini | 1M | 搜索上下文限制为 128k |
o4-mini | 200k | 搜索上下文限制为 128k; 已弃用,将于 2026-10-23 关闭 |
对于 Responses API 网页搜索,搜索上下文窗口限制为 128k,即使模型上下文窗口更大也是如此。
- 网页搜索不支持
gpt-5withminimalreasoning. gpt-5.4当推理努力设置为none可能会产生质量较低的结果。- Responses API 网页搜索使用底层模型的分级速率限制。
web_search_preview不支持filtersorreturn_token_budget,并忽略external_web_access.- With
tool_choice: "auto",搜索是可选的。使用tool_choice: "required"或在必须运行搜索时选择特定的网页搜索工具。
使用说明
| API 可用性 | 速率限制 | 备注 |
|---|---|---|
与配合工具使用的底层 模型 的分级速率限制相同。 |