第 2 课

按官方建议选型号,设置思考档并阅读 usage

在 Neon、Carbon 和 Hydrogen 之间选型,设置思考档并对照官方 usage

图文22 分钟Gemini 官方文档 ↗

课程目录第 2 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

图文教材

本课对照官方文档「Choosing a model」「What's new in Gemini 4 Neon」「Gemini thinking」「Long decode」编写。思考档示例、usage 对照数字来自官方文档;成功回复采用官方示例,本环境未用真实密钥跑出成功回复。2026-11-20 核对。

本课目标

  • 按官方建议,在 Neon、Carbon 和 Hydrogen 之间选择型号
  • 设置 thinking_level,避免传入会被拒绝的 minimal
  • 跑通官方思考档示例,并对照 usage 里的 total_thought_tokens
  • 给输出留出足够空间,必要时再按官方方式开启 long decode

前置条件

  • 已完成第 1 课,当前终端里仍有有效的 GEMINI_API_KEY,并且项目已开通付费层
  • 已安装 google-genai 包(2.3.0 或更高版本)

第 1 步:按官方建议选 Neon、Carbon 或 Hydrogen

官方「Choosing a model」把选型写得很直接:

  • 日常写代码、交互应用、带工具的智能体和多模态文档,默认先用 gemini-4-hydrogen,它更快、也更省
  • 复杂、高频的任务用 gemini-4-neon:推理比 Hydrogen 更深,完成任务又比 Carbon 更快,适合多文件编程、知识工作和科学流程;只在付费层提供
  • 最难的问题用 gemini-4-carbon:会花更多思考 tokens 去验证边界情况,面向系统架构、调试、科学和安全类难题
  • 大量文本生成、抽取、翻译、摘要,或要亚秒级延迟时,再用 gemini-3.5-flash-lite

把代码里的 model 换成对应 ID 即可,不必改请求结构。本课的练习对象是 Neon。

官方发布页还放了一张 Gemini 4 家族对比图。图中 Neon 的刊例价是 $3 / $15,思考档写的是 Low、medium、high、xhigh,订阅写的是 Google AI Pro 与 Ultra,可用性写的是 AI Studio 付费层。请同时看图注:Carbon 一行标的是 $4 / $20,脚注写明 11 月 30 日前的推出价是 $2 / $10。本课对照价格时,以定价页当次打开的数字为准,不以示意图里的目录价代替推出期价格。

官方发布页中的 Gemini 4 家族对比图

官方原图,来源为 2026-11-18 发布说明中的对比图,已缩到宽 1280 供课内阅读。原图地址:

https://storage.googleapis.com/gweb-uniblog-publish-prod/images/gemini-4-neon__comparison-graphi.width-2000.format-webp.webp

发布说明:

https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-neon/

官方「Choosing a model」在 2026-11-20 给出的 Standard 刊例价对照如下,单位是每 100 万 tokens。Carbon 的推出价有效期到 2026 年 11 月 30 日,12 月 1 日起改为 $4.00 / $20.00。Neon 没有推出价。

模型思考档刊例价(输入 / 输出)
gemini-4-carbonlow、medium(默认)、high$2.00 / $10.00(至 11-30)
gemini-4-neonlow、medium、high(默认)、xhigh$3.00 / $15.00
gemini-4-hydrogenlow、medium、high(默认)、xhigh$1.50 / $7.50
gemini-3.5-flash-liteminimal(默认)、low、medium、high$0.30 / $2.50

Hydrogen 和 Flash-Lite 可在免费层使用;Carbon 和 Neon 不可以。

官方「Choosing a model」页首屏

2026-11-20 实拍。

https://aistudio.google.com/docs/choosing-a-model

第 2 步:设置思考档,不要传 minimal

思考模型会先在内部推理,再写出可见回答。在 Interactions API 里,思考档写在 generation_config.thinking_level。官方「Gemini thinking」为 Neon 列出的取值是 low、medium、high(默认)和 xhigh。

官方对这四档的概括如下:

思考档用量适用场景
low最少、最快对成本和延迟敏感的负载,如快速对话和高吞吐;官方仍称它能做智能体任务
medium更少、更快交互式编程、实时界面原型、响应式对话,以及对延迟敏感的工具调用
high默认、平衡大多数复杂编程、智能体执行、工具调用和多模态知识工作的推荐默认值
xhigh最多、最深留给 high 不够的多步工程或科学问题,且愿用更高延迟和更多 tokens 换质量

官方建议:大多数复杂任务先从 high 开始;只有当 high 不够时再试 xhigh。请在四个档位上做自己的评估,并把 max_output_tokens 设得足够高,避免答案被截断,然后选能达到质量要求的最低档。

不要给 Neon 传入 minimal。官方写明:Gemini 4 型号和 gemini-3.8-flash 不支持 minimal,传入会被拒绝并返回错误。也不要把 temperature、top_p、top_k 再写进请求:官方迁移说明写明,服务器会忽略范围内的自定义值;超出范围则返回 400 校验错误。

官方「Gemini thinking」页,含 Neon 思考档表

2026-11-20 实拍,页面已滚动到 Controlling thinking。表中 gemini-4-neon 默认是 high,支持 low、medium、high、xhigh。

https://aistudio.google.com/docs/thinking

第 3 步:跑官方思考档示例,并看 usage

官方「What's new in Gemini 4 Neon」用下面这段 Python 把思考档设为 xhigh。官方原文的提示是一行;这里只为排版折行,拼接后与官方原句一致:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-neon",
    input=(
        "Audit this payment retry queue for race conditions "
        "and rewrite the lock acquisition logic."
    ),
    generation_config={
        "thinking_level": "xhigh"
    }
)

print(interaction.output_text)

这是可选的加深练习,不是日常默认。xhigh 会增加延迟和 tokens,费用按输出刊例价计算。若只想先用较低档位看字段,官方「Gemini thinking」还有一条 low 档示例。该页示例写的是 gemini-4-hydrogen,本课按迁移说明只把模型 ID 改成 gemini-4-neon:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-neon",
    input=(
        "Provide a list of 3 famous physicists and their "
        "key contributions"
    ),
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.output_text)
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

官方「Gemini thinking」页没有给出这两段脚本的固定样例正文,所以本课不编造运行结果。你应看到一段可见回答,并在 usage 里读到思考 tokens。真正可以对照的,是官方在同一页流式示例里给出的 usage 结构:

{
  "total_tokens": 530,
  "total_input_tokens": 62,
  "total_output_tokens": 171,
  "total_thought_tokens": 297
}

这段数字来自:

https://aistudio.google.com/docs/thinking

请对照你这次响应里的 usage。数字不会相同,但应能看到 total_thought_tokens。官方写明:模型会生成完整思考以提高最终回答质量,API 对外给出的是摘要;计费按模型实际需要的全部思考 tokens 计算,而不是只按摘要长度。思考 tokens 占用统一上下文窗口,并按输出费率计费。

采用官方文档示例,本环境未用真实密钥跑出成功回复。

第 4 步:给输出留出足够空间

max_output_tokens 限制的是一次响应里思考 tokens 与可见输出的合计。如果上限太低,答案可能被截断,甚至在可见文字出现前就结束。官方「What's new in Gemini 4 Neon」给出的起点是:

  • 常规任务:保持默认 65,536,或干脆不传 max_output_tokens
  • 已有应用若写死了较低上限(例如 8,192):删掉这段硬编码,或把上限提高到 65,536;若想少花 tokens,应降低思考档,而不是把输出上限压得很低
  • 长输出和多步任务:把 background 设为 true,并把 max_output_tokens 设为 131,072 或 262,144,最高可到 1,048,576 减去输入 tokens

官方还提醒:只把 background 设为 true、却不设 max_output_tokens 时,服务器会在 65,536 tokens 后停止。困难提示可能要运行数分钟,官方建议把 HTTP 客户端超时至少设为 15 分钟,或改走后台执行。

第 5 步:了解 long decode 的官方写法

当一次回答需要超过 64K tokens 时,官方推荐用后台执行做 long decode。下面就是官方「What's new in Gemini 4 Neon」页的 Python 示例。提示原文是一行,这里只为排版折行:

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-neon",
    input=(
        "Generate a complete multi-module migration "
        "specification and test suite for this service."
    ),
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)

官方这一页没有给出这段后台任务的固定样例回复。本环境也没有用真实密钥跑通 long decode,因此不编造输出。日常入门不必默认打开 262,144 的后台生成;先把第 3 步的同步请求跑通,再在确实需要超长输出时使用这一步。

官方「Long decode」页首屏

2026-11-20 实拍。

https://aistudio.google.com/docs/long-decode

常见坑

  • 给 Neon 传入 thinking_level: "minimal",请求会被拒绝。
  • 一上来就用 xhigh 跑简单抽取或短问答。官方提醒这会增加延迟和 tokens,还可能把 max_output_tokens 耗在思考上。
  • 把 max_output_tokens 设得太小。可能只产生思考 tokens,看不到完整回答,但费用已经发生。
  • 继续在请求里设置 temperature、top_p 或 top_k。官方迁移说明写明,范围内的值会被忽略,超出范围会返回 400。
  • 看到 Neon 定位在 Hydrogen 与 Carbon 之间,就把所有日常请求都改成 Neon。官方仍建议日常默认用 Hydrogen;Neon 留给 Hydrogen 不够、而又不必上到 Carbon 的复杂高频任务。

小结

这一课你已经能按官方建议选择型号和思考档,读懂 usage 里的思考 tokens,并知道超过 64K 输出时该用后台执行。下一课会按官方文档传入一份公开 PDF,再用 previous_interaction_id 做多轮会话,并认识 Neon 的隐式缓存。

本课资料

适用环境

  • 网页
  • iOS
  • Android
  • API

官方文档

Gemini ↗