Gemini 2.5 Flash Thinking API 实战指南 — thinking_budget亲测结论

我原本以为开启 Thinking 功能必然让模型更聪明。亲测之后，发现这只说对了一半。

我将 Gemini 2.5 Flash 的 thinking_budget 参数分别设为 0、1024、8000，在简单任务、数学推理、代码审查三个场景逐一测试，同时测量响应时间、输出 token 数和 thinking token 数。数字讲的故事比我预期的更微妙。

Thinking API 究竟做了什么

thinking_budget 限制模型在给出回答前能花多少 token 进行”内部推理”。Budget=0 完全禁用 thinking。Budget=-1 让模型自行决定推理深度。正整数设置上限（最大 24576）。

有一点很重要：thinking token 不会出现在响应中，但收费标准与输出 token 完全相同。正如LLM API 定价比较文章所示，Gemini 2.5 Flash 输出 token 为 $0.0035/1K。使用 1024 个 thinking token，就要额外付这部分费用。

另一个实用提示：旧版 google.generativeai 包已弃用，必须使用新版 google-genai 包。

# ❌ 已弃用（不再更新）
import google.generativeai as genai

# ✅ 当前标准
from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="你的问题",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_budget=1024,
            include_thoughts=True,  # 在响应中展示推理过程
        ),
    ),
)

# 从响应中分离思考过程和实际答案
for part in response.candidates[0].content.parts:
    if part.thought:
        print(f"[Thinking] {part.text[:100]}...")
    else:
        print(f"[Answer] {part.text}")

设置 include_thoughts=True 可以将模型的内部推理过程作为独立的响应部分查看，便于调试。生产环境中保持 False 即可。

实验方法与测量指标

我创建了一个全新的沙盒目录，只安装 google-genai，然后对三类提示词分别应用 Budget=0/1024/8000。

测量指标：

• 响应时间（秒）：wall clock time
• 输出 token：实际回答的 token 数
• thinking token：内部推理消耗的 token 数（usage_metadata.thoughts_token_count）

三类提示词：

1. 简单任务：“用一句话说明 Python 中如何对列表排序”
2. 数学推理：找出满足三个条件的所有两位正整数
3. 代码审查：在简单 Python 函数中找出 bug 和改进点

实验结果：数字说明一切

以下是实际测量值，原样呈现，未作修饰。

任务类型	Budget=0	Budget=1024	Budget=8000
简单任务	1.4秒 / 输出54tok	6.8秒 / 输出61tok / thinking 751tok	9.0秒 / 输出45tok / thinking 1282tok
数学推理	8.8秒 / 输出2143tok	15.1秒 / 输出1915tok / thinking 918tok	26.2秒 / 输出1671tok / thinking 4036tok
代码审查	6.7秒 / 输出1367tok	13.1秒 / 输出1126tok / thinking 734tok	22.6秒 / 输出2055tok / thinking 1824tok

简单任务：Budget=0 时 1.4 秒，Budget=1024 时 6.8 秒，慢了近 5 倍。回答质量几乎没有差别。Budget=8000 消耗 1282 个 thinking token，输出反而只剩 45 token。纯属浪费。

数学推理：这里出现了意外结果。Budget=0 时输出高达 2143 token。模型在”大声思考”，把所有解题步骤全部写在输出里。Budget=1024 时，内部推理用了 918 token，输出降至 1915 token，总 token 消耗相近，但答案结构更清晰。Budget=8000 把推理加深到 4036 token，输出缩减至 1671 token。

代码审查：Budget=1024 让输出从 1367 降至 1126 token，答案更有针对性。Budget=8000 扩展到 2055 token，分析更全面，但速度慢 3 倍。哪种更好取决于具体需求。

按任务类型选择最优 Budget

基于实验，我整理了实用决策框架。不是万能公式，但作为起点有效。

**Budget=0（禁用 thinking）**适用于：

• 分类、打标签、标注任务
• 摘要、翻译、格式转换
• 简单问答、事实查询
• 高频批处理（成本敏感）

简单任务在 Budget=0 下只需 1.4 秒。给它 1024 budget 意味着等待 6.8 秒并支付额外费用。没有任何收益，纯粹是浪费。

**Budget=1024〜2048（中等 thinking）**适用于：

• 需要集中分析的代码审查、bug 定位
• 中等复杂度推理
• 需要多步判断但对延迟敏感的场景

说实话，代码审查在 Budget=1024 下的答案比 Budget=0 更短，但感觉更好。不必要的冗余消失了，只留下核心内容。

**Budget=4000〜8000（深度 thinking）**适用于：

• 复杂数学、算法设计
• 全面架构审查
• 多步骤规划
• 精度远比速度重要的任务

Budget=8000 数学问题消耗了 4036 个 thinking token，耗时 26 秒。这种延迟在任何交互式应用中都无法接受。仅用于离线批处理或后台异步分析。

Gemini 2.5 Flash 成本优化指南也提到：thinking token 与输出 token 定价相同。盲目使用 Budget=8000 会让成本翻倍。

生产代码：tracking thinking 使用量

以下是我在生产环境中追踪 thinking token 消耗的模式。

from google import genai
from google.genai import types
import time

def generate_with_thinking(
    client: genai.Client,
    prompt: str,
    budget: int = 1024,
    model: str = "gemini-2.5-flash",
) -> dict:
    """在追踪 thinking 使用量的同时生成响应。"""
    start = time.perf_counter()
    
    config = types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_budget=budget,
            include_thoughts=False,  # 生产环境设为 False
        ),
    )
    
    response = client.models.generate_content(
        model=model,
        contents=prompt,
        config=config,
    )
    
    elapsed = time.perf_counter() - start
    usage = response.usage_metadata
    
    return {
        "text": response.text,
        "latency_s": round(elapsed, 2),
        "input_tokens": usage.prompt_token_count,
        "output_tokens": usage.candidates_token_count,
        "thinking_tokens": getattr(usage, "thoughts_token_count", 0) or 0,
        "total_tokens": (
            usage.prompt_token_count
            + usage.candidates_token_count
            + (getattr(usage, "thoughts_token_count", 0) or 0)
        ),
    }

# 使用示例
client = genai.Client(api_key="YOUR_API_KEY")

result = generate_with_thinking(
    client,
    "找出这段代码中的潜在内存泄漏：...",
    budget=2048,
)

print(f"延迟：{result['latency_s']}秒")
print(f"Thinking token：{result['thinking_tokens']}")
print(f"总计费 token：{result['total_tokens']}")

usage_metadata.thoughts_token_count 有时返回 0——当 budget=0 或模型判断无需 thinking 时。将此指标纳入监控，可以了解 thinking 实际触发的频率。

Thinking API 的不足之处

我想直接说说令人沮丧的部分。

**动态模式（Budget=-1）不可预测。**让模型自行决定 budget 看起来很方便，但它可能对简单任务也触发 thinking。在我的简单任务实验中，Budget=-1 耗时与 Budget=1024 相近（约 6.8 秒）。如果无法预测延迟和成本，就无法在生产中进行预算规划。

**thinking_budget 和 thinking_level 不能同时设置。**Gemini 3.x 使用 thinking_level，2.5 系列使用 thinking_budget。同一个调用中混用会得到 400 错误。这在文档中有说明，但错误信息不够直观，第一次遇到容易困惑。

**Thinking token 不受上下文缓存影响。**即使用 Context Caching 降低了长系统提示的成本，thinking token 每次仍单独计费。正如AI 智能体成本现实分析所述，在智能体循环中 thinking 成本会比预期累积得更快。

我的最终立场

Thinking API 并非被过度炒作，但”开启就好”的直觉也是错误的。

我的结论很简单：以 Budget=0 为默认，只在任务真正需要多步推理时才明确启用 Budget=1024〜2048。 Budget=8000 只用于批处理作业或精度至关重要的离线分析。

生产中跳过动态模式（Budget=-1）。可预测性比便利性更重要。

让我印象最深的反直觉发现：对于复杂数学问题，禁用 thinking 导致模型”大声思考”，输出了 2143 个 token。启用 Budget=1024 后，推理转入内部，输出降至 1915 token。总成本差异比想象中小。是否划算取决于任务本身。

小结

如果没有亲测，我可能会默认”thinking 越多越好”。测量结果说明了不同的故事。

Gemini 2.5 Flash Thinking API 用对地方是强大的工具。对复杂推理任务，它能通过内化思考减少输出 token，这个反直觉效果是真实存在的。但对简单任务盲目应用只会浪费金钱和时间。

设置 thinking_budget 前，先问自己一个问题：**这个任务真的需要深度推理吗？**大多数情况下，答案是否定的。

---

本文所有代码均可通过文中提供的代码片段重现。基于 google-genai 包 0.8.x 版本编写。