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+ 原生协议）

curl "https://api.openai-hub.com/v1beta/models/gemini-2.5-pro:generateContent?key=$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "2026 年五一档电影票房排行" }]
      }
    ],
    "tools": [
      { "google_search": {} }
    ]
  }'

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：

curl https://api.openai-hub.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{ "role": "user", "content": "..." }],
    "tools": [{ "type": "google_search" }]
  }'

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

字段说明

google_search (2.0+)

googleSearchRetrieval (1.5)

响应

{
  "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 字段速览

与函数调用并行

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

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

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

请求头

响应