Gemini 扩展思考与思维链签名
本文档详细说明通过 UniGateway 调用 Gemini API 时的扩展思考配置(thinkingConfig)、thinkingLevel 与 thinkingBudget 代际换算规则、includeThoughts 默认注入与零预算保护、思维链签名(thoughtSignature)跨轮次与跨协议保持,以及损坏签名的反应式自愈机制。
章节导引
本篇为 Gemini API 参考文档的第 4 章节:
- Gemini 概览与接入
- generateContent 概述与快速开始
- 请求参数与多模态内容格式
- 扩展思考与思维链签名(当前章节)
- 工具调用与搜索检索
- 结构化输出与生成配置
- 响应、流式与错误处理
思考配置 thinkingConfig 参数规范
Gemini 3 与 Gemini 2.5 系列模型原生支持扩展推理(Extended Thinking),允许模型在输出最终答案前生成隐藏或可见的思维链。
在请求体中,思考配置嵌套在 generationConfig.thinkingConfig 对象内:
{
"generationConfig": {
"thinkingConfig": {
"includeThoughts": true,
"thinkingLevel": "high"
}
}
}
1. thinkingConfig 字段说明
| 字段名 | 类型 | 支持模型 | 说明 |
|---|---|---|---|
includeThoughts | boolean | Gemini 3 / 2.5 | 控制模型是否在返回内容中输出 thought: true 的思考文本块。UniGateway 在文本生成端点默认注入 true。 |
thinkingLevel | string | Gemini 3 系列 | 抽象思考强度档位。可选值:minimal、low、medium、high、none / off。 |
thinkingBudget | integer | Gemini 3 / 2.5 / 2.0 | 显式 Token 预算下限/上限(Token 数量,如 1024、8192)。值为 0 表示显式关闭思考。 |
思考配置三维对照表
| 参数 / 场景 | Google Gemini 官方规范 | UniGateway 处理规则 |
|---|---|---|
includeThoughts 默认注入 | 控制响应是否输出思考过程。在未显式传参时,各云端平台默认行为存在差异(部分平台默认隐藏)。 | 文本端点默认可见:在 generateContent 与 streamGenerateContent 端点上,若客户端未携带 includeThoughts,网关自动注入 includeThoughts: true 以呈现完整思维链;在 Token 计数(countTokens)端点及生图/TTS 模型上不注入。 |
| 思考预算为零时的冲突保护 | 当 thinkingBudget: 0(显式禁用思考)时,Vertex AI 要求不能同时携带 includeThoughts,否则返回 400 Thinking_config.include_thoughts is only enabled when thinking is enabled。 | 零预算联动修剪:当检测到客户端传入了数值为 0 的 thinkingBudget 时,网关主动剔除 includeThoughts 字段,避免触发上游校验冲突。 |
| 生图与 TTS 模型的思考配置处理 | 非 Gemini 3 生图模型(如 gemini-2.5-flash-image)与语音合成 TTS 模型不支持思考配置;Gemini 3 生图模型(gemini-3-pro-image-preview)在支持思考的通道上可接受显式思考配置。 | 分模型精准处理:<br>1. 所有生图与 TTS 模型均抑制默认的 includeThoughts: true 自动注入;<br>2. 非 Gemini 3 生图模型与全部 TTS 模型在出站前主动剥离 thinkingConfig / thinking_config;<br>3. Gemini 3 生图模型保留客户端显式传入的 thinkingConfig,若目标通道返回 400 拒绝,则在同账号剥离 thinkingConfig 并自动重发。 |
非 Gemini 3 模型的 thinkingLevel 转换 | Gemini 3 引入了 thinkingLevel 档位。旧版 Gemini 2.5 / 2.0 模型不支持该字段,仅支持数值型 thinkingBudget;且 gemini-2.5-pro 不允许将预算设为 0。 | 跨代档位换算:在明确的 Gemini 2.5 / 2.0 模型上,网关自动将档位映射为数值预算:minimal ➔ 512,low ➔ 1024,medium ➔ 8192,high ➔ 24576;对于 none / off,在 gemini-2.5-flash 等可关闭思考的模型上映射为 0,在不可关闭思考的 gemini-2.5-pro(及 deep-think 变体)上映射为最低正预算 128,并移除出站 thinkingLevel。通用模型别名(如 gemini-pro、gemini-flash-latest)首跳保留 thinkingLevel,若上游返回 400 则动态换算重发。 |
| 上游 400 思考参数自愈重试 | 部分上游或特定模型对 thinkingLevel 或 includeThoughts 返回 400(例如 Thinking_level is not supported 或通用无效参数)。 | 动态换算与零配置重发:捕获对应错误后:<br>1. 若上游拒绝 thinkingLevel,网关自动将档位转换为数值型 thinkingBudget 或安全剥离并在同账号立即重试;<br>2. 若模型不支持思考能力(如旧版或特定第三方模型)且返回思考相关 400 错误,网关主动剥离所有层级的 thinkingConfig 并在同一账号透明重发。 |
思维链签名 thoughtSignature 保持与自愈
在多轮会话(包含 Function Calling 工具轮次及纯文本推理轮次)中,Gemini 会在生成 functionCall 或正文 text 内容块时附带不可见的加密思考签名 thoughtSignature(字符串)。
1. 签名生命周期与流转要求
- 模型输出:Gemini 在生成工具调用或推理回复时输出带有
thoughtSignature的内容块; - 客户端回传:在发起后续轮次对话或传入
functionResponse时,客户端必须在上下文历史中完整保留上一轮模型输出块及对应的thoughtSignature; - 上下文校验:推理引擎利用该签名校验多轮上下文决策链条是否合法。
2. 跨协议桥接与绑定规则
UniGateway 在跨协议转发(Gemini ⇄ OpenAI Responses ⇄ OpenAI Chat Completions ⇄ Anthropic Messages)中支持工具轮次与非工具纯文本轮次的全量无损往返:
- 精确绑定:优先依据 CallID / ItemID 配对签名,在同一轮次包含多个同名函数调用时避免发生混淆;
- OpenAI Responses 承载:工具轮次通过
function_call.signature传递,非工具文本轮次通过type: "function_call_signature"输出与输入项无损往返; - Chat Completions 承载:通过
message.thought_signature、tool_calls[].extra_content.google.thought_signature与reasoning_details载体无损往返传递; - Anthropic 承载:通过
tool_use.signature及非工具轮次text.signature内容块字段无损传递。
3. 损坏签名反应式自愈重试
| 场景 | 上游行为 | UniGateway 自愈处理规则 |
|---|---|---|
| 跨通道迁移或客户端截断 | 若签名在客户端传输中断损,或请求从其他通道迁移至严格校验签名的 Gemini 原生通道,上游会返回 400 Corrupted thought signature. 或 Invalid signature。 | 安全占位签名自愈重试:网关自动捕获该特征错误,立即将请求体中损坏的 thoughtSignature 替换为合规的跳过验证签名(skip_thought_signature_validator),并在当前账号自动重试,使复杂 Agent 调用链无需异常中断。 |
下一步
- 掌握函数调用与搜索检索:工具调用与搜索检索
- 了解结构化输出与采样参数:结构化输出与生成配置
- 查阅完整错误码与流式传输:响应、流式与错误处理