Gemini 工具调用（Tools）¶

Gemini 系列模型在本平台既可以通过 Google 原生 Generate Content 接口 使用工具（tools），也可以通过 OpenAI Chat Completions 兼容接口 进行函数调用等高级能力。
本文重点介绍 在新 API 平台下，如何为 Gemini 启用联网搜索（Google Search Grounding）工具。

官方参考

🌐 使用 Google 搜索建立依据（联网搜索）¶

Google 搜索工具 google_search 可以把 Gemini 模型与实时互联网内容连接起来，让回答：

更真实可靠：基于真实网页内容生成，降低幻觉
支持实时信息：回答最近事件、时效性很强的问题
带引用来源：通过 groundingMetadata 字段返回网页链接和引文片段

1. 开启 `google_search` 工具¶

在 GenerateContent 请求体中，通过 tools 字段启用 google_search 工具即可：

tools：工具列表
google_search：对于 Gemini 3 / 2.5 等新模型，推荐使用该字段（旧模型使用 google_search_retrieval）

2. 基础调用示例（REST / curl）¶

下面示例展示了在本平台网关上为 Gemini 模型开启 Google 搜索工具，并询问 2024 欧洲杯冠军：

curl "https://api-cs-al.naci-tech.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "谁赢得了 2024 年欧洲杯？请给出答案，并附上 2~3 个参考链接。"
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

与官方文档一致，当启用 google_search 后，模型会自动完成：

是否需要搜索的决策
构造查询词并调用 Google 搜索
读取搜索结果并组织自然语言回答
在响应中附带 groundingMetadata 元数据（包含网页链接、引用片段等）

3. 响应中的 `groundingMetadata` 示例¶

当 Gemini 使用了 Google 搜索建立依据后，返回中会在某个候选（candidates[i]）上带有 groundingMetadata 字段，结构大致如下（字段含义参考官方文档）：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "西班牙在 2024 年欧洲杯决赛中 2:1 战胜英格兰，获得冠军。"
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "groundingChunks": [
          { "web": { "uri": "https://www.uefa.com/...", "title": "UEFA.com" } },
          { "web": { "uri": "https://www.aljazeera.com/...", "title": "Al Jazeera" } }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 50,
              "text": "西班牙在 2024 年欧洲杯决赛中 2:1 战胜英格兰"
            },
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

你可以在服务端解析 groundingMetadata，将 groundingSupports 中的 segment 与 groundingChunks 中的 web.uri 做关联，在前端 UI 中实现 内嵌可点击引用（“[1]”、“[2]” 这种形式），提升用户对答案的信任度。
更多细节可参考 Google 官方文档示例代码（Python / JavaScript）[使用 Google 搜索建立依据] 中的 add_citations 实现。

🔧 结合其他 Gemini 工具¶

除了 google_search 以外，Gemini 还支持：

codeExecution：启用代码执行，以更可靠地完成计算或代码相关任务
functionDeclarations：定义你自己的业务函数，让模型进行函数调用
网址上下文工具：通过提供 URL 作为上下文，结合公开网页与自有内容回答问题

这些工具的通用用法（包括 tools / toolConfig / functionDeclarations 等字段）在文档中已有详细说明，可参考：

Google Gemini 对话格式 google-gemini-chat.md 中的 tools、toolConfig、Grounding 等章节
工具调用总览：工具调用（Tools）概览

在实际项目中，你可以将 Google 搜索接地 与 自建函数 / 代码执行 / URL 上下文 组合使用，让 Gemini 同时利用实时互联网、企业内数据和计算能力，为用户提供更可靠、可解释的回答。