Gemini API/Gemini 工具调用与搜索检索

Gemini 自定义函数定义、JSON Schema 参数兼容性清洗、Google Search 联网检索、代码执行与 toolConfig 调用策略。

Gemini 工具调用与搜索检索

本文档详细说明通过 UniGateway 调用 Gemini API 时的函数声明(functionDeclarations)、JSON Schema 参数清洗、Google Search 联网检索增强、代码执行环境(codeExecution)及工具调用策略配置(toolConfig)。


章节导引

本篇为 Gemini API 参考文档的第 5 章节:

  1. Gemini 概览与接入
  2. generateContent 概述与快速开始
  3. 请求参数与多模态内容格式
  4. 扩展思考与思维链签名
  5. 工具调用与搜索检索(当前章节)
  6. 结构化输出与生成配置
  7. 响应、流式与错误处理

工具定义结构与 tools 参数

Gemini 通过顶层 tools 数组声明模型可用的外部能力。主要工具类型包括自定义函数(functionDeclarations)、Google Search 联网检索以及代码执行环境。

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "北京今天天气怎么样?"}]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_current_weather",
          "description": "获取指定城市的实时天气数据",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市或地区名称"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ]
}

工具与搜索三维对照表

参数 / 场景Google Gemini 官方规范UniGateway 处理规则
functionDeclarations 与 parametersJsonSchema工具函数声明放置在 functionDeclarations 数组下,支持 parameters(Google v1beta Protobuf Schema 子集)与 parametersJsonSchema(标准 JSON Schema 扩展字段)。部分内部通道(如 v1internal)仅识别 parameters。双层 Schema 保留与降级兼容:<br>1. 在标准 v1beta 通道上,网关出站时原样保留 parametersJsonSchema 及其标准 JSON Schema 约束(如 minimum、maximum、minItems、maxItems、minLength、maxLength、pattern、format、anyOf、title),仅对 parameters 执行 Protobuf Schema 清洗;<br>2. 在 v1internal 通道或当上游因 Schema 字段返回 400 错误时,网关自动将 parametersJsonSchema / parameters_json_schema 降级归一化为 parameters,执行深度递归清洗后在同账号自动重试。
Protobuf Schema 兼容清洗Google v1beta Protobuf Schema 仅支持标准属性子集,不识别 $schema、$id、$ref、definitions、additionalProperties、patternProperties、propertyNames、strict、uniqueItems、multipleOf、dependencies、examples、default、const 等关键字。非法关键字净化与边界转义:<br>1. 自动剥离上述上游 Proto 不支持的关键字,同时保留 title、pattern、format、anyOf 及标准数组/字符串长度约束;<br>2. 将 min、max、exclusiveMinimum、exclusiveMaximum 自动提取并转义为 description 中的自然语言约束提示(如 (min: 1)),确保模型获取数值边界约束且不触发 Proto 校验拒绝;<br>3. 将联合类型(如 type: ["string", "null"])自动平滑转换为原生支持的 type: "string", nullable: true;<br>4. 自动将非字符串类型的枚举值转换为字符串并确保 type: "string"。
内置 Google Search 检索允许在 tools 中声明 {"googleSearch": {}} 或 {"google_search": {}} 以开启模型实时联网搜索能力。原生透传与规范化:标准化空对象 {} 结构,在出站前确保键名符合上游端点规范;若 tools 为空数组,网关自动剥离 tools 字段。
内置代码执行 codeExecution支持在 tools 中声明 {"codeExecution": {}},由模型在安全沙箱内执行 Python 代码计算并返回分析结果。原生支持与多块返回:完整支持模型输出的 executableCode 与 codeExecutionResult 内容块,并可在流式 SSE 中精确汇聚。
toolConfig 调用策略控制通过 toolConfig.functionCallingConfig.mode 控制工具调用策略,可选模式:AUTO(模型自主决定)、ANY(强制调用指定或任一函数)、NONE(仅生成文本,不调用函数)。空配置剥离与模式规范化:自动剔除空的 toolConfig 与 tool_config 顶层对象;规范化 mode 取值,防止大小写微差导致报错。

函数调用交互生命周期

1. 第一轮请求:声明工具

客户端发送包含 tools 声明的用户查询。

2. 模型响应:触发 functionCall

模型返回带参数的函数调用块及对应的 thoughtSignature:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_current_weather",
              "args": {
                "location": "北京",
                "unit": "celsius"
              }
            },
            "thoughtSignature": "sig_gemini_weather_001"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

3. 第二轮请求:回传 functionResponse

客户端本地执行工具并返回结果,必须原样保留上一轮模型的 functionCall 及 thoughtSignature:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "北京今天天气怎么样?"}]
    },
    {
      "role": "model",
      "parts": [
        {
          "functionCall": {
            "name": "get_current_weather",
            "args": {"location": "北京", "unit": "celsius"}
          },
          "thoughtSignature": "sig_gemini_weather_001"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "get_current_weather",
            "response": {
              "temperature": 22,
              "condition": "晴朗"
            }
          }
        }
      ]
    }
  ],
  "tools": [...]
}

下一步