「プロンプトは10行ほどしかないのに、response.text が空で返ってくる。しかも finish_reason を見たら MAX_TOKENS — いやいや、そんなに長い出力なんて頼んでいないのに」。Gemini 2.5 や 3 系の思考モデルを使い始めて、こう首をかしげた経験はないでしょうか。
私自身、2014年から続けているアプリ事業で、App Store / Google Play のレビューを gemini-2.5-flash で分類するバッチを書いていたとき、まさにこの症状にぶつかりました。コスト最適化のつもりで maxOutputTokens を 256 まで絞ったところ、本文だけが空っぽで返り、原因の特定に半日溶かしてしまったのです。結論を先にお伝えすると、空に見える応答を作っている真犯人は「思考トークン（thinking tokens）」です。
症状 — 短い出力を頼んだのに MAX_TOKENS で止まる
まず再現条件です。思考モデル（gemini-2.5-flash、gemini-2.5-pro、gemini-3-* 系）に対して maxOutputTokens を小さめ（数十〜数百）に設定すると、答えが短いはずの依頼でも次のような応答が返ります。
from google import genai
from google.genai import types
client = genai.Client(api_key="YOUR_API_KEY")
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents="このレビューの感情を positive / negative の一語で答えてください。「動作が軽くて満足」",
config=types.GenerateContentConfig(max_output_tokens=256),
)
print(repr(resp.text)) # '' もしくは None
print(resp.candidates[0].finish_reason) # FinishReason.MAX_TOKENSたった一語を返すだけの依頼で MAX_TOKENS。直感に反しますが、ここに思考モデル特有の落とし穴が潜んでいます。
なぜ起きるのか — 思考トークンが出力予算を先に食い尽くす
Gemini 2.5 以降の思考モデルは、最終的な答えを出す前に内部で「思考」を行います。この思考も立派なトークン消費であり、maxOutputTokens は「思考トークン＋可視の回答トークン」の合計に対する上限として働きます。
つまり maxOutputTokens=256 のとき、モデルが思考に 256 トークンを使い切ってしまうと、可視の回答に回す予算がゼロになります。その結果、parts にテキストが一つも入らないまま MAX_TOKENS で打ち切られ、response.text は空になるわけです。応答自体は壊れていません。予算配分の問題です。
これは usage_metadata を見ると一目で分かります。
um = resp.usage_metadata
print("prompt:", um.prompt_token_count)
print("thoughts:", um.thoughts_token_count) # ここが maxOutputTokens 近くまで膨らんでいる
print("candidates:", um.candidates_token_count) # 0 もしくは極端に小さいthoughts_token_count が maxOutputTokens に張り付いていて、candidates_token_count が 0 — これが「思考に全予算を吸われた」決定的な証拠です。旧来の非思考モデル（gemini-1.5-* 等）では起きなかった挙動なので、移行時に面食らう方が多いところだと思います。
対処1 — maxOutputTokens を思考分込みで確保する
最も素直な対処は、出力上限を思考トークンの分まで含めて広めに取ることです。思考モデルでは maxOutputTokens を「回答に必要な長さ」だけで見積もってはいけません。
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents="このレビューの感情を positive / negative の一語で答えてください。「動作が軽くて満足」",
config=types.GenerateContentConfig(max_output_tokens=2048), # 思考分を含めて広めに
)
print(resp.text) # 'positive'私の感覚では、短い分類・抽出タスクでも思考モデルを使うなら maxOutputTokens は最低 1024、安全側なら 2048 以上を確保しておくと、MAX_TOKENS による空応答はほぼ消えます。出力上限はあくまで「暴走を止める安全弁」と捉え、回答の実長で攻めすぎないのがコツです。
対処2 — thinkingBudget で思考量そのものを制御する
回答が確実に短いタスクなら、思考の量を直接抑えるほうがコストにも効きます。thinking_config の thinking_budget で思考トークンの上限を指定できます。
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents="このレビューの感情を positive / negative の一語で答えてください。「動作が軽くて満足」",
config=types.GenerateContentConfig(
max_output_tokens=256,
thinking_config=types.ThinkingConfig(thinking_budget=0), # 思考を無効化
),
)
print(resp.text) # 'positive'ここで一点、機種差に注意してください。gemini-2.5-flash や flash-lite は thinking_budget=0 で思考を完全に切れますが、gemini-2.5-pro は思考を完全には無効化できず、最小予算が残ります（おおむね 128 以上を指定する必要があります）。Pro でゼロを渡すと INVALID_ARGUMENT になりますので、Pro の場合は「0 で切る」ではなく「対処1で出力上限を広げる」方針を採るのが安全です。thinking_budget=-1 を渡せばモデルがタスクに応じて思考量を自動調整する動的モードになります。
本番で空応答を検知して自動リカバリする
バッチや常駐サービスでは、空応答を握りつぶさずに検知してリトライする層を一枚挟んでおくと、夜間バッチが静かに欠損する事故を防げます。私のレビュー分類パイプラインでは、累計5,000万DL分のアプリにまたがって毎晩これが回っているため、ここの堅牢性は収益の安定に直結しています。
def generate_with_guard(client, model, contents, max_tokens=2048):
resp = client.models.generate_content(
model=model,
contents=contents,
config=types.GenerateContentConfig(max_output_tokens=max_tokens),
)
fr = resp.candidates[0].finish_reason
text = resp.text or ""
if not text and str(fr) == "FinishReason.MAX_TOKENS":
# 思考が予算を食い切ったとみなし、上限を倍にして一度だけ再試行
resp = client.models.generate_content(
model=model,
contents=contents,
config=types.GenerateContentConfig(max_output_tokens=max_tokens * 2),
)
text = resp.text or ""
if not text:
raise RuntimeError(f"空応答が継続: finish_reason={fr}")
return textfinish_reason を見てから本文に触る、という順序を徹底するだけで、空応答まわりのトラブルは大半が予防できます。Node SDK（@google/genai）でも考え方は同じで、response.candidates?.[0]?.finishReason を確認し、response.usageMetadata?.thoughtsTokenCount で思考消費を観測できます。
思考モデルへ移行したあと最初に maxOutputTokens を見直すこと — まずはそこから試してみてください。同じところで時間を溶かしている方の助けになれば嬉しいです。