用 Responses API 的 Web Search 做联网问答

官方把 Web search 分成三类：非推理快速查找、带推理的 agentic search，以及可跑数分钟的 deep research。新项目默认走 Responses API 的 web_search。

• 新集成：Responses API + web_search（可配合当前文档推荐模型）
• 必须留在 Chat Completions：再用官方仍支持的 search API 路径
• 长报告 / 多步研究：提高 reasoning，并考虑 background mode

旧的 web_search_preview 仍可用，但不支持 filters、external_web_access、return_token_budget 等新控制项。新代码直接写 {"type": "web_search"}。

和别的工具一样，把 web_search 放进 tools。模型会根据输入决定是否搜索。下面是官方 Python 示例。

pip install -U openai
export OPENAI_API_KEY=sk-...

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?",
)

print(response.output_text)

若模型名在账号侧不可用，换成文档当前推荐且支持 web_search 的模型。先看 output_text 是否像“读过今天的网页”，再检查结构化输出。

使用 web_search 的响应通常包含两类 output item：web_search_call（检索动作）与 message（文本 + annotations）。

web_search_call.action 常见为 search（通常含 query）；推理模型还可能出现 open_page、find_in_page。message.content[0].annotations 里的 url_citation 带 url、title 与文本位置。

for item in response.output:
    print(item.type)
    if item.type == "web_search_call":
        print(item.action)
    if item.type == "message":
        for content in item.content:
            if getattr(content, "annotations", None):
                for ann in content.annotations:
                    if ann.type == "url_citation":
                        print(ann.title, ann.url)

官方要求：向终端用户展示来自网页的信息时，必须让 inline citation 清晰可见且可点击。产品里不要只吞掉 annotations。

search_context_size 控制检索结果进入模型前的上下文量：low 适合简单查询，medium 是更均衡的默认，high 适合需要更多细节的问题。它不保证固定来源数或精确 token 数。

response = client.responses.create(
    model="gpt-5.6",
    tools=[
        {
            "type": "web_search",
            "search_context_size": "low",
        }
    ],
    input="What movie won best picture in 2025?",
)

print(response.output_text)

web_search 是工具，不是“每次必搜”。问题若明显需要当前事实，模型更可能调用；纯定义或与网络无关的推理，可能不搜。

这和旧版 Chat Completions search 模型不同：那些路径常常是搜索后再答。Responses 上你可以观察有没有 web_search_call，再决定产品层要不要提示“已联网”。

• responses.create 成功返回
• 对时效性问题出现 web_search_call
• output_text 可读
• 需要展示来源时能拿到 url_citation

若代码仍在用 web_search_preview，迁到 web_search 以获得新控制项。依赖 gpt-4o-search-preview / gpt-4o-mini-search-preview 的路径应按官方迁移说明切换，这些 preview 搜索模型已进入弃用与关停时间表。

只有必须留在 Chat Completions 时，才使用官方仍维护的 search API 路径；新功能优先 Responses + web_search。