WEB SEARCH

联网搜索能力说明

说明 GPT、Claude、Gemini 在联网搜索能力上的接口差异，以及 web_search、google_search 工具的正确用法。

联网搜索能力说明

RootFlow AI 支持多种模型协议。需要联网搜索、实时资料核验、官网依据或最新信息时，不能只在提示词里写“请联网搜索”，而要按模型家族使用对应的原生工具协议。

核心结论

/v1/chat/completions 中的“请联网搜索”只是文字指令，不代表模型真的拥有联网能力。

联网搜索应按模型类型选择接口：

模型类型	推荐接口	工具参数	是否可验证搜索
GPT / OpenAI Responses 模型	`/v1/responses`	`{ "type": "web_search" }`	看 `web_search_call` / `tool_usage`
Claude 模型	`/v1/messages`	`{ "type": "web_search_20250305", "name": "web_search" }`	看 `server_tool_use` / `web_search_tool_result`
Gemini 模型	`/v1beta/models/{model}:generateContent`	`{ "google_search": {} }`	看 `groundingMetadata`

如果响应中没有对应的工具调用或来源元数据，就不能把模型文本里的“我已联网搜索”当作真实联网结果。

Chat Completions 默认不联网

普通对话接口：

POST https://api.rootflowai.com/v1/chat/completions

示例请求：

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "user",
      "content": "请先联网搜索后回答：gemini3.5flash 是什么模型？"
    }
  ],
  "stream": false
}

这类请求只是告诉模型“希望它联网搜索”，但并没有给模型提供搜索工具。模型通常只能基于已有上下文和模型知识回答。

因此，如果问题依赖最新公开资料、官网状态、模型列表、新闻、价格、政策变化等信息，不建议只靠 /v1/chat/completions 加提示词来完成核验。

GPT / Responses API

GPT 和支持 OpenAI Responses 的模型，请使用：

POST https://api.rootflowai.com/v1/responses

并显式传入 web_search 工具：

{
  "model": "gpt-5.5",
  "tools": [
    {
      "type": "web_search"
    }
  ],
  "tool_choice": "auto",
  "input": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
}

如果搜索工具被成功调用，响应中会出现类似下面的内容：

{
  "type": "web_search_call",
  "status": "completed"
}

返回体中的 tool_usage 也可能显示搜索请求次数，例如：

{
  "tool_usage": {
    "web_search": {
      "num_requests": 2
    }
  }
}

这表示模型确实使用了联网搜索能力。

Claude Messages API

Claude 模型不要走 /v1/responses 转换链路。需要联网搜索时，请使用 Anthropic Messages 兼容接口：

POST https://api.rootflowai.com/v1/messages

请求体中传入 Claude 原生 server tool：

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
    }
  ],
  "tools": [
    {
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 3
    }
  ]
}

如果搜索被真实调用，响应内容或流式事件里会出现：

{
  "type": "server_tool_use",
  "name": "web_search"
}

以及：

{
  "type": "web_search_tool_result"
}

usage 中也可能出现：

{
  "server_tool_use": {
    "web_search_requests": 1
  }
}

看到这些字段，才表示 Claude 确实执行了 web search。

Gemini Native API

Gemini 模型不要走 /v1/responses 转换链路。需要使用 Gemini 原生接口：

POST https://api.rootflowai.com/v1beta/models/{model}:generateContent

请求体中传入 Google Search grounding 工具：

{
  "contents": [
    {
      "parts": [
        {
          "text": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
        }
      ]
    }
  ],
  "tools": [
    {
      "google_search": {}
    }
  ],
  "generationConfig": {
    "temperature": 0,
    "maxOutputTokens": 1024
  }
}

如果 Google Search grounding 被真实执行，响应的候选结果中应出现：

{
  "groundingMetadata": {
    "webSearchQueries": [],
    "groundingChunks": [],
    "groundingSupports": [],
    "searchEntryPoint": {}
  }
}

判断 Gemini 是否真的联网，重点看 candidates[].groundingMetadata。如果只返回普通文本，或 citationMetadata 为 null，且没有 groundingMetadata，就不能视为已完成可验证联网搜索。

RootFlow Gemini 通道现状

RootFlow 当前提供的 Gemini Pro 等通道主要基于逆向 / 兼容接入，并不等同于 Google 官方 Gemini API 直连。因此，即使请求路径和请求体采用 Gemini Native 格式，也不保证完整兼容所有 Gemini Native 能力。

尤其是 Google Search grounding 相关能力：

tools: [{ "google_search": {} }] 可能被上游接受并正常返回文本；
模型可能会生成看起来像“已联网核验”的回答；
但上游不一定真实执行 Google Search grounding，也不一定返回 groundingMetadata、webSearchQueries、groundingChunks、groundingSupports 等结构化来源字段。

因此，在 RootFlow Gemini 通道里，是否真的完成可验证联网搜索，只能以响应中是否存在 candidates[].groundingMetadata 为准。没有这些字段时，请按普通模型回答处理，不要把它当作带来源的联网搜索结果。

实测边界

对同一个问题：

gemini3.5flash 是什么模型？

使用 /v1/chat/completions 时，即使提示词中要求“先联网搜索”，模型也可能表示无法实时联网核验，或只能基于已有知识回答。

OpenAI Responses 模型应使用 /v1/responses + web_search。Claude 模型应使用 /v1/messages + web_search_20250305。Gemini 模型应使用 Gemini Native generateContent + google_search，并检查返回是否包含 groundingMetadata。

如果 Gemini 返回的内容看起来像最新资料，但没有 groundingMetadata 或来源 URL 元数据，只能说明模型回答内容可能正确，不能证明接口实际执行了 Google Search grounding。

常见误区

只写“请联网搜索”是否足够？

不够。提示词只能表达任务意图，不能凭空给模型增加工具能力。

为什么模型有时会说无法联网？

如果请求没有提供搜索工具，模型无法真正访问网页。严谨的模型会说明自己不能实时联网；不严谨的模型可能会给出看似已搜索但实际未核验的回答。

为什么模型说“已联网搜索”，但没有来源？

模型文本不是工具调用证据。请检查响应结构：

OpenAI Responses：看 web_search_call 或 tool_usage.web_search
Claude：看 server_tool_use、web_search_tool_result 或 server_tool_use.web_search_requests
Gemini：看 candidates[].groundingMetadata

是否所有模型都支持 web search？

不一定。是否可用取决于当前模型、上游能力和接口参数支持情况。即使请求没有报错，也要以响应中是否出现工具调用或来源元数据为准。

联网搜索会增加用量吗？

会。联网搜索可能产生额外的工具调用和上下文用量。请仅在确实需要实时资料或公开来源核验时启用。

curl 示例

OpenAI Responses

curl https://api.rootflowai.com/v1/responses \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "tools": [
      {
        "type": "web_search"
      }
    ],
    "tool_choice": "auto",
    "input": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
  }'

Claude Messages

curl https://api.rootflowai.com/v1/messages \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
      }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3
      }
    ]
  }'

Gemini Native

curl https://api.rootflowai.com/v1beta/models/gemini-3.5-flash:generateContent \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "gemini3.5flash 是什么模型？请先联网搜索/核验公开资料，再给出结论和依据。"
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ],
    "generationConfig": {
      "temperature": 0,
      "maxOutputTokens": 1024
    }
  }'

总结

/v1/chat/completions 适合普通对话和 OpenAI 兼容接入。
/v1/chat/completions 里的“请联网搜索”只是提示词，不代表真实联网。
GPT / OpenAI Responses 模型使用 /v1/responses + web_search。
Claude 模型使用 /v1/messages + web_search_20250305。
Gemini 模型使用 /v1beta/models/{model}:generateContent + google_search，并以 groundingMetadata 判断是否真实联网。
Gemini / Claude 不建议走 /v1/responses 转换链路；如果转换层返回 not implemented 或 convert_request_failed，请改用对应原生协议。

联网搜索能力说明