跳到主要内容

Gemini Thought Signatures

Gemini 3 系列独有的多轮 / 函数调用必须传递的推理状态字段。其他厂商无对应概念。

Gemini 3 在使用函数调用或多轮对话时,必须在后续轮次原样传递响应里返回的 thought_signature,用于保持模型推理状态;遗漏会返回 400。

字段位置​

  • 函数调用响应:choices[].message.tool_calls[0].provider_specific_fields.thought_signature
  • 多轮对话响应:choices[].message.provider_specific_fields.thought_signature

SDK 自动处理(推荐)​

OpenAI Python SDK 在用 response.choices[0].message 整体回传时会自动保留 thought_signature。不要解构 message 对象。

from openai import OpenAI

client = OpenAI(api_key=TURING_API_KEY, base_url=TURING_BASE_URL)

# Turn 1: 第一次调用,获取工具调用
response_1 = client.chat.completions.create(
    model="turing/gemini-3-pro-latest",
    messages=[{"role": "user", "content": "东京天气?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取当前天气",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        },
    }],
    extra_body={"reasoning_effort": "low"},
)

# Turn 2: 提供工具结果(关键: 整体复用 response_1.choices[0].message)
messages = [
    {"role": "user", "content": "东京天气?"},
    response_1.choices[0].message,  # 自动包含 thought_signature
    {
        "role": "tool",
        "content": '{"temperature": 30, "condition": "sunny"}',
        "tool_call_id": response_1.choices[0].message.tool_calls[0].id,
    },
]

response_2 = client.chat.completions.create(
    model="turing/gemini-3-pro-latest",
    messages=messages,
    tools=[...],
    extra_body={"reasoning_effort": "low"},
)

手动构造 message(cURL / 自定义流程)​

cURL 或自建流程必须手动把 thought_signature 放到 provider_specific_fields 中:

{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\": \"Tokyo\"}"
    },
    "provider_specific_fields": {
      "thought_signature": "eyJ0aGlua2luZ19zdGF0ZSI6Li4ufQ=="
    }
  }]
}

多轮对话(无 tools)​

即使不使用函数调用,多轮对话中也需要保留 thought_signature:

# Turn 1
response_1 = client.chat.completions.create(
    model="turing/gemini-3-pro-latest",
    messages=[{"role": "user", "content": "请分析量子计算的发展趋势"}],
    extra_body={"reasoning_effort": "medium"},
)

# Turn 2 同样直接复用 message 对象
messages = [
    {"role": "user", "content": "请分析量子计算的发展趋势"},
    response_1.choices[0].message,  # 自动带 thought_signature
    {"role": "user", "content": "基于你的分析,请给出具体的投资建议"},
]
client.chat.completions.create(
    model="turing/gemini-3-pro-latest",
    messages=messages,
    extra_body={"reasoning_effort": "medium"},
)

字段位置:message.provider_specific_fields.thought_signature。

关键约束​

  • 不可修改:thought_signature 必须原样传递,任何篡改都会导致 400。
  • 不可缺失:第二轮起未传会返回 400。
  • 跨模型不复用:gemini-3-pro 与 gemini-3-flash 的 signature 互不兼容,切模型会失效。

常见错误​

# ❌ 错误: 手动构建时遗漏 thought_signature
messages.append({
    "role": "assistant",
    "content": "...",  # 缺少 provider_specific_fields
})

# ✅ 正确: 整体复用 response.choices[0].message
messages.append(response.choices[0].message)

相关文档​