Gemini 工具调用与搜索检索
本文档详细说明通过 UniGateway 调用 Gemini API 时的函数声明(functionDeclarations)、JSON Schema 参数清洗、Google Search 联网检索增强、代码执行环境(codeExecution)及工具调用策略配置(toolConfig)。
章节导引
本篇为 Gemini API 参考文档的第 5 章节:
- Gemini 概览与接入
- generateContent 概述与快速开始
- 请求参数与多模态内容格式
- 扩展思考与思维链签名
- 工具调用与搜索检索(当前章节)
- 结构化输出与生成配置
- 响应、流式与错误处理
工具定义结构与 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": [...]
}
下一步
- 了解结构化输出与生成参数:结构化输出与生成配置
- 查看流式 SSE 与错误重试:响应、流式与错误处理
- 回顾扩展思考配置:扩展思考与思维链签名