本文根据 OpenAI 官方《Web search》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 OpenAI 官方网站。API 是按用量计费的独立服务，与 ChatGPT 订阅分开计算，Key 的获取见 /guides/openai-api-key。
适用于谁
- 需要让模型回答“今天发生了什么”“最新版本是多少”这类时效问题的开发者；
- 已会用 Responses API 发请求（不熟的先看 /guides/openai-responses-api），想给它加联网能力的人；
- 想在回答里显示来源链接、或限制只在某几个网站里搜的人。
结论先说
- 一行就能开：在
tools里加{"type": "web_search"}，不用自己写搜索代码。 - 新接入用
web_search，旧的web_search_preview还能用，但不支持域名过滤等新选项。 - 模型不一定搜：
tool_choice为auto时它自己决定要不要搜，想强制就设required或指定这个工具。 - 回答里的引用在
annotations，类型是url_citation；官方要求把行内引用以显眼的可点击链接展示给用户。 - 搜索要额外计费：搜索动作有工具调用费用，另外还有模型本身的 token 费用，数字以官方价格页当天为准。
图：本站根据 OpenAI 官方《Web search》 整理的示意图
一、最小示例
Python：
python
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra", # 以官方模型页当天为准
tools=[{"type": "web_search"}],
input="今天有什么积极向上的新闻？",
)
print(response.output_text)Node.js（保存为 .mjs）：
javascript
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra", // 以官方模型页当天为准
tools: [{ type: "web_search" }],
input: "今天有什么积极向上的新闻？",
});
console.log(response.output_text);没有 Key 或还没跑通基础请求的，先看 /guides/openai-api-python-quickstart 或 /guides/openai-api-nodejs-quickstart。
二、响应里有什么
一次带搜索的响应，output 里通常有两类项：
web_search_call：记录搜索动作，有id、status和action。action的类型可能是search（带查询词）、open_page（打开某个页面）或find_in_page（在页面内查找）。搜索类动作会产生工具调用费用；message：真正的回答，文字在content[0].text，引用放在content[0].annotations。
每条 url_citation 包含 type、start_index、end_index、url、title。其中 start_index 和 end_index 指出这条引用对应回答文字的哪一段，你可以据此在页面上做角标或链接。行内引用默认就带上。官方明确要求：你向用户展示联网结果时，行内引用必须以显眼的、可点击的链接形式呈现。
三、限制搜索范围
域名过滤
用 filters 指定只搜某些网站，或者排除某些网站：
python
tools=[{
"type": "web_search",
"filters": {
"allowed_domains": ["openai.com", "developers.openai.com"],
},
}]规则：allowed_domains 与 blocked_domains 各自最多 100 个域名；写域名时不要带协议，写 openai.com，不要写 https://openai.com/；子域名自动包含。这个功能只适用于 Responses API 的 web_search，旧的 web_search_preview 不支持。
用户位置
问“附近有什么”这类问题时，可以给个大致位置：
python
tools=[{
"type": "web_search",
"user_location": {
"type": "approximate",
"country": "US",
"city": "Minneapolis",
"region": "Minnesota",
"timezone": "America/Chicago",
},
}]type 固定写 approximate；country 是两位 ISO 国家代码；city、region 是自由文本；timezone 是 IANA 时区名。
四、查看全部来源
回答里的引用只是模型最终采用的几条。想看它查过的所有网址，请求里加：
python
include=["web_search_call.action.sources"]官方说这个来源列表通常比引用列表更长。实时数据类来源会带有 oai-sports、oai-weather、oai-finance 这样的标签。
五、几个参数怎么选
图：本站根据 OpenAI 官方《Web search》 整理的示意图
search_context_size：取low、medium（默认）、high，控制给模型多少搜索上下文。官方特别说明，它不是精确的 token 数，也不保证来源或引用的数量；external_web_access：布尔值，默认true，即实时联网。设为false是只用缓存、不访问外部网络的离线模式；旧的web_search_preview会忽略这个参数；tool_choice：auto时模型可能直接回答不去搜，要保证搜索就用required或指定该工具；return_token_budget：只用于托管的web_search与 GPT-5 及以上的推理模型，取值default或unlimited，官方提醒unlimited可能增加延迟和费用，要谨慎，长任务可配合background: true。
六、官方列出的限制
- 联网搜索的上下文窗口最多 128k，不管模型本身窗口多大；
- 速率限制沿用底层模型的分级限制，提高限额的办法见 /guides/openai-api-usage-tiers-rate-limits；
- 官方提醒：
gpt-5.4搭配推理强度none可能得到质量较低的搜索结果；仍在用gpt-5的，推理强度要高于minimal； - Chat Completions 里只有
gpt-5-search-api一个搜索模型，它每次回答前都会先搜，但不支持域名过滤、来源列表、实时访问控制；官方建议仅为保持旧集成才用； - 安全上，官方建议把公开网页搜索和访问私有数据的 MCP 查询放在不同请求里，以降低提示注入的风险；
- 官方页面还提到一些旧的搜索预览模型已经安排下线，如果你的代码还在用，请到官方页面核对日期。
常见问题
Q：为什么有时候明明开了工具，模型没搜？
tool_choice 默认是 auto，模型认为不需要就不会搜。要强制搜索，把它设为 required。
Q：能不能让搜索结果只来自我信任的网站？
用 filters.allowed_domains，最多 100 个域名。
Q：怎么在界面上显示来源？
读 annotations 里的 url_citation，用 url 和 title 做链接，并按官方要求让链接显眼可点击。
Q：要不要同时让回答按固定格式输出？
可以，格式化输出见 /guides/openai-api-structured-outputs；让模型自己调用你写的函数见 /guides/openai-api-function-calling。
Q：遇到 429 或其他报错？
按 /guides/openai-api-error-codes 排查。价格见 /guides/openai-api-price-official-table，以官方当天为准。
参考资料
- OpenAI 官方：Web search — https://developers.openai.com/api/docs/guides/tools-web-search
0 条评论
还没有评论，来抢沙发～