第 2 课
按官方建议选型号,设置思考档并阅读 usage
在 Neon、Carbon 和 Hydrogen 之间选型,设置思考档并对照官方 usage
课程目录第 2 / 3 课
学习位置仅保存在当前浏览器,有效期 180 天。
图文教材
本课对照官方文档「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。本课对照价格时,以定价页当次打开的数字为准,不以示意图里的目录价代替推出期价格。

官方原图,来源为 2026-11-18 发布说明中的对比图,已缩到宽 1280 供课内阅读。原图地址:
发布说明:
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-carbon | low、medium(默认)、high | $2.00 / $10.00(至 11-30) |
gemini-4-neon | low、medium、high(默认)、xhigh | $3.00 / $15.00 |
gemini-4-hydrogen | low、medium、high(默认)、xhigh | $1.50 / $7.50 |
gemini-3.5-flash-lite | minimal(默认)、low、medium、high | $0.30 / $2.50 |
Hydrogen 和 Flash-Lite 可在免费层使用;Carbon 和 Neon 不可以。

2026-11-20 实拍。
第 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 校验错误。

2026-11-20 实拍,页面已滚动到 Controlling thinking。表中
gemini-4-neon默认是high,支持low、medium、high、xhigh。
第 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 步的同步请求跑通,再在确实需要超长输出时使用这一步。

2026-11-20 实拍。
常见坑
- 给 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 的隐式缓存。

