Gemini 内置联网搜索 (google_search)

概述

Google Gemini 通过 google_search 工具（Gemini 1.5 系列旧名 googleSearchRetrieval）提供原生联网搜索 + Grounding 引用。OpenAI-Hub 透传 Google 官方协议，并支持在 /v1/chat/completions 兼容模式下用 google_search 类型。

支持模型：gemini-2.5-flash、gemini-2.5-pro、gemini-3-pro 等。

⚠️ Gemini 1.5 系列使用旧名 googleSearchRetrieval，2.0+ 改为 google_search，请按所选模型选择对应字段。

请求示例

1. 最小用法（Gemini 2.5+ 原生协议）

2. 流式

请求路径改为 :streamGenerateContent?alt=sse&key=...，请求体相同。

3. Gemini 1.5（旧名 + 动态阈值）

{
  "contents": [{ "role": "user", "parts": [{ "text": "..." }] }],
  "tools": [
    {
      "googleSearchRetrieval": {
        "dynamicRetrievalConfig": {
          "mode": "MODE_DYNAMIC",
          "dynamicThreshold": 0.7
        }
      }
    }
  ]
}

dynamicThreshold (0.0–1.0)：模型置信度低于该阈值才会触发检索。越高越省钱、越少检索。

4. OpenAI 兼容模式

如果客户端走 /v1/chat/completions：

OpenAI-Hub 会自动转成 Gemini 原生 tools[].google_search 字段，引用以 tool_calls 形式回传。

字段说明

`google_search` (2.0+)

字段	类型	说明
`google_search`	object	占位对象，目前固定空 `{}`

`googleSearchRetrieval` (1.5)

字段	类型	说明
`dynamicRetrievalConfig.mode`	enum	`MODE_DYNAMIC` / `MODE_UNSPECIFIED`
`dynamicRetrievalConfig.dynamicThreshold`	float	0.0–1.0 自适应检索阈值

响应

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "根据猫眼数据，2026 年五一档票房冠军是..." }]
      },
      "groundingMetadata": {
        "webSearchQueries": ["2026 五一档电影票房"],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://piaofang.maoyan.com/...",
              "title": "猫眼专业版 - 五一档票房"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": { "startIndex": 0, "endIndex": 50, "text": "..." },
            "groundingChunkIndices": [0],
            "confidenceScores": [0.95]
          }
        ],
        "searchEntryPoint": {
          "renderedContent": "<style>...</style><div class=\"google-search-suggestion\">...</div>"
        }
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 320,
    "totalTokenCount": 338
  }
}

⚠️ searchEntryPoint.renderedContent 是 Google 政策强制要求展示的「搜索建议条」HTML，前端必须原样渲染（合规要求）。

Grounding 字段速览

字段	说明
`webSearchQueries`	模型自动生成的搜索词列表
`groundingChunks[].web.uri` / `.title`	检索到的网页源
`groundingSupports[].segment`	回答中哪一段引用了哪个 chunk
`groundingSupports[].confidenceScores`	每段引用的置信度
`searchEntryPoint.renderedContent`	Google 强制 UI 元素（必须展示）

与函数调用并行

Gemini 2.5+ 起支持 google_search 与自定义函数 functionDeclarations 并行（1.5 系列只能二选一）：

{
  "contents": [...],
  "tools": [
    { "google_search": {} },
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "parameters": { "type": "object", "properties": { "city": { "type": "string" } } }
        }
      ]
    }
  ]
}

模型自主决定单独调用、组合调用或都不调用。

Gemini 内置联网搜索 (google_search)

概述

请求示例

1. 最小用法（Gemini 2.5+ 原生协议）

2. 流式

3. Gemini 1.5（旧名 + 动态阈值）

4. OpenAI 兼容模式

字段说明

`google_search` (2.0+)

`googleSearchRetrieval` (1.5)

响应

Grounding 字段速览

与函数调用并行

请求参数

返回响应

Gemini 内置联网搜索 (google_search)

概述#

请求示例#

1. 最小用法（Gemini 2.5+ 原生协议）#

2. 流式#

3. Gemini 1.5（旧名 + 动态阈值）#

4. OpenAI 兼容模式#

字段说明#

google_search (2.0+)#

googleSearchRetrieval (1.5)#

响应#

Grounding 字段速览#

与函数调用并行#

请求参数

返回响应

概述

请求示例

1. 最小用法（Gemini 2.5+ 原生协议）

2. 流式

3. Gemini 1.5（旧名 + 动态阈值）

4. OpenAI 兼容模式

字段说明

`google_search` (2.0+)

`googleSearchRetrieval` (1.5)

响应

Grounding 字段速览

与函数调用并行