Gemini 3.1 Pro 的思考级别、结构化输出与工具配置

一句话结论

对 Gemini 3.1 Pro，先固定 thinking_level 和默认 temperature，再按需组合 Search/URL context/函数调用与 JSON schema；需要 bash/custom tools 时优先测试专用 customtools endpoint。

适用场景

• 适合的任务：研究检索、代码审查、结构化抽取、需要多步工具调用的 Agent。

• 不适合的任务：把 high 用在所有高吞吐请求；也不适合把 temperature<1.0 当作默认稳定化手段。

• 适用的模型版本：gemini-3.1-pro-preview；混合 bash 与自定义工具时可测试 gemini-3.1-pro-preview-customtools。

• 适用的客户端、Agent 或 API：Interactions API（官方推荐访问最新模型/特性）、Gemini API、Google AI Studio、Vertex AI；具体 SDK 版本需与文档一致。

• 推荐的推理档位和参数：Pro 支持 low/medium/high，默认动态 high；temperature 保持 1.0，不要同时传旧 thinking_budget 和 thinking_level。

可直接使用的内容

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="""
    搜索并核对指定主题的最新资料。只使用工具返回的事实；
    每条结论附来源 URL。遇到冲突时保留双方证据并解释差异。
    最终严格输出符合 schema 的 JSON，不要添加 schema 外字段。
    主题：<topic>
    """,
    generation_config={"thinking_level": "medium"},
    tools=[
        {"type": "google_search"},
        {"type": "url_context"},
        {
            "type": "function",
            "name": "save_finding",
            "description": "Save one verified finding and return its stable ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "claim": {"type": "string"},
                    "source_url": {"type": "string"},
                    "confidence": {"type": "string"}
                },
                "required": ["claim", "source_url", "confidence"]
            }
        }
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "findings": {"type": "array"},
                "uncertainties": {"type": "array"}
            },
            "required": ["findings", "uncertainties"]
        }
    }
)

这里的工具和 schema 是可复用配置骨架；实际部署要用 google.genai 当前 SDK 校验字段，且由服务端验证 URL、权限、重复写入和 JSON。

测试/工作流步骤

1. 先用 low、medium、high 在同一任务集建立质量/延迟/费用曲线；复杂工程任务再考虑 high。

2. 固定 temperature=1.0，单独比较 thinking level，不要同时改变提示词和采样参数。

3. 先用 Search/URL context 获取证据，再允许函数写入；写入后读取并校验稳定 ID。

4. 对结构化输出执行 JSON parse、schema 校验和来源 URL 可达性检查。

5. 如果模型忽略 view_file、search_code 等 custom tool 而偏向 bash，使用 customtools endpoint 做 A/B 测试；同时记录质量波动。

原始证据与数据

• Pro 的 thinking_level 支持 low/medium/high，默认 high（动态）；minimal 对 Pro 不支持。

• 官方强烈建议 Gemini 3 的 temperature 保持默认 1.0，低于 1.0 可能出现循环或复杂数学/推理性能下降。

• 模型页列出 1,048,576 输入 token、65,536 输出 token；支持 caching、code execution、function calling、Search grounding、structured outputs、URL context。

• 模型页提供独立的 gemini-3.1-pro-preview-customtools endpoint，称其更擅长优先使用混合 bash/custom tools，但也提醒不受益于这些工具的场景可能有质量波动。

• 官方 Gemini 3 guide 给出 Search + URL context + JSON schema 的结构化输出示例。

适用边界

• Interactions API/SDK 示例会随 preview 版本变化；部署前必须以当前 API schema 和模型页为准。

• Schema 约束只约束输出格式，不能确保搜索结果真实或工具写入安全。

• customtools 的“更好优先工具”是官方定位，不是跨任务的独立成功率；必须在自己的工具集上测。

• 代码片段中的 save_finding 是示例函数，不能直接给予任意网络、文件或数据库权限。

来源摘录或观察（仅做合规短引）

官方说明 Gemini 3 的 high 是“maximum reasoning depth”的动态上限，而非严格 token 保证；这是容量和延迟配置时的关键边界。