Gemini API thought_signature 怎么处理：手动拼接 function calling 历史避免 400

接入 Gemini 3 的工具调用后，最容易在第二轮请求才暴露问题：第一轮模型正常返回了 functionCall，服务端把历史整理成更“干净”的 JSON，再把工具结果发回去，却收到 400。很多时候函数参数没有错，真正丢掉的是模型响应 part 里的 thought_signature。

如果你使用官方 Google GenAI SDK，优先把完整响应对象原样追加到历史；只有 REST 或手动拆装多轮历史时，才需要显式保留并原样回传收到的 thought_signature。

先复现：第二轮请求为什么突然变成 400

假设有一个查询天气的工具。第一轮请求里，Gemini 返回一个 functionCall，应用调用本地函数后得到温度，再把 functionResponse 放回历史。问题通常出在中间那层“消息标准化”代码：它把模型返回值转换成了只包含 name 和 args 的对象。

这段转换看起来合理，但对 Gemini 3 的思考模型并不完整。签名是加密的上下文凭据，不是给用户展示的思维原文；它必须随收到它的 part 一起回传，不能重新编码、截断或挪到下一个 part。

最小配方：保留完整响应，再追加工具结果

如果使用 Python SDK，最稳的做法不是自己提取函数名和参数，而是把 SDK 返回的完整响应对象追加回对话历史。下面的示例只演示关键边界，工具本身可以替换成订单查询、库存检查或天气服务。

from google import genai
from google.genai import types

client = genai.Client()

tools = [types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="get_weather",
        description="查询城市当前天气",
        parameters=types.Schema(
            type="OBJECT",
            properties={"city": types.Schema(type="STRING")},
            required=["city"],
        ),
    )
])]

history = [types.Content(
    role="user",
    parts=[types.Part(text="帮我查杭州天气")],
)]

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=history,
    config=types.GenerateContentConfig(tools=tools),
)

# 关键：保留完整模型响应，不要只摘出 functionCall
history.append(response.candidates[0].content)

call = response.function_calls[0]
result = {"city": call.args["city"], "temperature": 27}
history.append(types.Content(
    role="tool",
    parts=[types.Part.from_function_response(
        name=call.name,
        response=result,
    )],
))

final = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=history,
    config=types.GenerateContentConfig(tools=tools),
)
print(final.text)

这里的关键不是某个 SDK 方法名，而是历史里保留了模型返回的完整 content。SDK 知道签名所在的 part，也能按 API 要求重新组织工具结果。若你的业务层必须落库，建议把原始响应序列化保存，而不是只保存一份自定义的“简化消息”。

REST 手写历史：签名要跟着原来的 part 走

REST 客户端没有 SDK 的对象封装，通常会直接读取 JSON。处理顺序可以固定成四步：保存模型响应中的完整 parts；找到函数调用；执行本地工具；把原始函数调用 part 与新的 function response 一并放回下一轮请求。

const modelParts = response.candidates[0].content.parts;
const functionPart = modelParts.find(part => part.functionCall);

const nextContents = [
  ...contents,
  { role: "model", parts: modelParts },
  {
    role: "user",
    parts: [{
      functionResponse: {
        name: functionPart.functionCall.name,
        response: { result: { temperature: 27, city: "杭州" } }
      }
    }]
  }
];

// 下一次请求直接使用 nextContents；不要重建一个没有签名的 functionCall
const body = { contents: nextContents, tools };

这里的 modelParts 是重点。不要写成只复制 functionCall 的新对象，也不要把签名从第一个 part 移到另一个 part。官方文档还特别说明：并行函数调用时，签名可能只挂在第一个函数调用 part 上，后面的调用仍要和原响应一起保留。

三种实现方式的边界

如果系统同时支持两种 API，建议在内部定义两个明确的历史类型，不要把它们统一成只有 role、text、tool_name 的扁平结构。统一日志格式可以做，但发送给模型的 payload 必须保留各 API 的原生结构。

兼容坑：2.5、Gemini 3 与并行调用

Gemini 2.5 和 Gemini 3 的签名出现位置、函数调用触发条件并不完全一样。不要用一次测试结果推断所有模型。切换模型或调整 thinking level 后，至少验收一次“单函数调用”和一次“并行函数调用”。

还要注意签名不是可以解码、展示或拼接的普通文本。它的用途是维持后续工具调用所需的上下文，不等于把模型内部思考过程暴露给客户端。日志里可以记录字段是否存在、所在 part 和请求轮次，但不要打印签名内容。

上线前的验收清单

• 首轮模型响应的原始 parts 已保存，未只保存函数名和参数。
• 工具结果回传时，模型响应 part 的顺序与签名位置未改变。
• 单调用、并行调用、连续两轮调用都能得到最终文本。
• 400 时记录模型名、轮次和结构校验结果，不记录签名原文。
• 切换到官方 SDK 后，确认业务序列化层没有再次压扁响应。

常见问题

官方 SDK 还需要手动读取 thought_signature 吗？

通常不需要。只要把完整模型响应对象追加到历史，让 SDK 维护原生结构即可。

签名能不能保存到数据库？

可以保存用于重放，但应按原始字段原样保存并限制访问；日志和用户可见内容不要输出签名值。

只有一个 functionCall 也必须保留签名吗？

如果响应返回了签名，就应原样回传。不要因为调用数量少就删掉它。

Interactions API 和 generateContent 能共用一套历史 JSON 吗？

不建议直接共用。两者对 thought 的表达位置不同，应分别按对应 API 的请求结构转换。

把历史结构当成协议的一部分

这类 400 并不是工具函数本身失效，而是应用在中间层改写了模型协议。最小修复只有一句话：SDK 场景保留完整响应，REST 场景保留原始 part，并在每次模型切换、并行调用和多轮工具链上做结构验收。这样既能保住调用链，也不会把加密签名误当成普通回答文本。