Gemini 3.8 FlashからHydrogenへのアップグレード：必ず調整すべき5つのAPI設定と互換性の変更

著者注：Gemini 3.8 Flash から Hydrogen への移行では、SDK とコンテキスト、思考パラメータ、サンプリング設定、キャッシュ、そしてマルチターンのツール呼び出しにおける署名管理を同時に調整する必要があります。

Google は 2026年11月12日に Gemini 4 Hydrogen を正式リリースしました。API モデル ID は gemini-4-hydrogen で、日常的なプログラミングと AIエージェントの実行を想定したモデルです。多くのチームはまずコード内のモデル名を置き換えるだけで本番投入しようとしますが、その結果として HTTP 400、パラメータが効かない、マルチターンのツール呼び出しエラー、長い出力の切り捨てに遭遇します。本記事では、Gemini 3.8 Flash から Hydrogen へアップグレードする際に必ず調整すべき 5 つの API 設定を整理し、各項目を「旧動作 → 新動作 → 修正方法 → 典型的な影響」の順で解説します。

これは発表会の再掲ではありません。本文中のパラメータ名、有効値、SDK バージョン、エラー種別は、Google Cloud の公式移行ガイドとモデル仕様書に基づいています。サードパーティの評価やコミュニティのフィードバックは、出典を別途明記します。

本記事の価値：読み終えれば、チェックリストに沿って既存の Gemini 3.8 Flash 呼び出しコードを項目ごとに修正し、AIエージェントとバッチ処理を Hydrogen へスムーズに移行できます。

Hydrogen移行で必ず押さえたい5つの用語

作業を始める前に、移行ガイドで繰り返し登場する概念を整理しておきましょう。

• thinking_level：モデルの推論の深さを制御する思考レベルのパラメータです。Hydrogen では旧来の thinking_budget に代わるもので、有効な段階は Low、Medium、High、XHigh です。
• thought_signature：モデルがレスポンスで返す思考関連の署名です。マルチターンの会話やツール呼び出しでは、必ずそのまま保持して返送する必要があります。そうしないと、モデルは以前の推論状態を引き継げません。
• continuation_token：長い出力の次のセグメント生成をつなぐための続き書き用トークンです。1セグメントの出力が上限に達した後、これを使って生成を続けられます。
• 暗黙的キャッシュ：条件を満たす入力プレフィックスをプラットフォームが自動的に再利用する仕組みです。ヒットした部分はキャッシュ価格で課金され、開発者が手動でキャッシュオブジェクトを作成する必要はありません。
• コンテキストウィンドウ：1回のモデル処理で扱える情報の範囲です。Hydrogen では入力・出力・思考・ツール呼び出しが合計 1,048,576 tokens の統一枠を共有します。

1. HydrogenのアップグレードがモデルIDの差し替えだけでは済まない理由

Gemini 3.8 Flash と Hydrogen は同じ Gemini ファミリーに属していますが、API の挙動には互換性のない点が少なくありません。公式の移行ガイドによると、thinking_budget と MINIMAL の思考レベルは Hydrogen ではサポートされず、リクエストはそのまま HTTP 400 を返します。一方、temperature、top_p、top_k といったサンプリングパラメータはエラーにならず、黙って無視されるだけです。前者はテスト段階で気づけますが、後者は「パラメータがまだ効いている」と誤解させる可能性があります。

さらに見落としやすいリスクが2つあります。1つはマルチターンのツール呼び出しで署名の管理がより厳格になったことです。過去の会話が圧縮やトリミングを受けると、署名とプレフィックスが一致せず HTTP 400 が発生することがあります。もう1つは、デフォルトの思考レベルが Medium から High に引き上げられたことです。明示的に設定しない場合、同じリクエストでも思考トークンをより多く消費し、レイテンシも長くなります。以下の表が5つの調整項目の概要です。

二、調整1：Hydrogen のモデルID、SDKバージョン、コンテキスト制限

従来の動作 → 新しい動作：3.8 Flash の時代には、ほとんどのプロジェクトが SDK のバージョンにさほど敏感ではありませんでした。Hydrogen へ移行すると、モデルIDを gemini-4-hydrogen に変更する必要があり、超長い出力が必要な場合は SDK のバージョンが必須条件になります。Google 公式の移行ガイドで示されている最低バージョンは次のとおりです。

Hydrogen のコンテキストと長い出力を変更する方法

Hydrogen の 1,048,576 トークンは共通の割り当てであり、入力と履歴コンテキスト、思考トークン、ツール呼び出しに関連するトークン、最終出力のすべてがこの1つの枠から差し引かれます。つまり、100万トークンを入力したうえで、さらに100万トークンを追加出力することはできません。長文ドキュメント分析系の Agent では、入力側で思考とツール呼び出しのための余裕をあらかじめ確保しておく必要があります。

1回のフォアグラウンド生成の上限は通常 65,536 トークンです。この長さを超える場合、3つの方法から選択できます。対応 SDK の自動継続を使う、Interactions API で background=true を設定してバックグラウンドで長い生成を行う、あるいは自前で continuation_token を管理して逐次的に連結する、という方法です。特に注意すべき点として、公式の入門ドキュメントでは、長い出力の継続には現在 v1beta1 API が必要であり、Agent Platform の v1 ではこの機能がサポートされていないと説明されています。

典型的な影響：長いレポートや長いコードファイルをバッチ生成する業務が最もつまずきやすいポイントです。まず SDK をアップグレードし、次に API バージョンを v1beta1 に切り替え、最後に 65,536 トークンを超えるリクエストで回帰テストを行うことをおすすめします。

pip install -U "google-genai>=2.34.0"
npm install @google/genai@^2.32.0

三、調整2：Hydrogen の thinking_budget を thinking_level に変更

従来の動作：3.8 Flash では thinking_budget を使ってトークン数で思考の長さを制御していました。さらに MINIMAL というレベルも選択でき、デフォルトは Medium でした。

新しい動作：Hydrogen は thinking_level のみを受け付け、有効な値は Low、Medium、High、XHigh の4段階で、デフォルトは High です。引き続き thinking_budget や MINIMAL を渡すと HTTP 400 が返されます。公式が推奨する用途はそれぞれ、Low は分類、Medium は通常のコーディング、High は多段階エージェント、XHigh は複雑な深い推論です。

第三者機関の Artificial Analysis は11月12日に4段階の独立評価（Intelligence Index v5.0.1）を完了しており、この結果から各段階の違いを理解できます。下表の所要時間とコストは標準化された評価タスクの平均値であり、一般ユーザーの1回の会話における実際のコストを表すものではありません：

データを見ると、High は Medium より10ポイント高い一方、XHigh は High よりわずか3ポイント高いだけで、評価コストは1.87ドルから3.16ドルへと上昇しています。つまり最高レベルが必ずしも最もコスト効率が良いとは限らず、同じモデル名でもレベルによって能力差が大きいということです。

Hydrogen thinking_level の変更例

以下の例は公式の Google Gen AI SDK の構文を使用しています。列挙値の大文字・小文字の書き方は、インストールされている SDK バージョンの型定義に従ってください：

from google import genai
from google.genai import types

client = genai.Client()

# 旧記法（3.8 Flash）：Hydrogen では HTTP 400 を返します
# thinking_config=types.ThinkingConfig(thinking_budget=2048)

# 新記法：通常のコーディングタスクでは Medium を選択
coding_config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="medium"),
)

# 多段階エージェントでは High を選択（デフォルト値でもあり、明示的に書くことを推奨）
agent_config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="high"),
)

resp = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="この関数のヌルポインタ問題を修正してください：...",
    config=coding_config,
)
print(resp.text)

典型的な影響：思考トークンは出力価格で課金されるため、レベルを明示的に設定していないプロジェクトは移行後に自動的に High にフォールバックし、請求額とレイテンシがどちらも増加します。古い thinking_budget の範囲をレベルにマッピングすることをおすすめします。小さな予算は Low または Medium、大きな予算は High に対応させます。

4. 調整3：Hydrogen で無効になった生成パラメータを整理する

従来の動作：3.8 Flash では temperature、top_p、top_k を使って出力のランダム性を調整でき、ペナルティパラメータや複数候補の出力にも対応していました。

新しい動作：Hydrogen のデフォルト温度は 1.0 でカスタム値は反映されず、top_p は 0.95、top_k は 64 に固定されています。これら 3 つのパラメータを渡しても無視されます。公式の移行チェックリストでは、次のフィールドへの対応も求められています。

公式ドキュメントでは特に、一部の旧パラメータは無視されるだけだが、別のパラメータはリクエスト検証エラーを引き起こすと注意を促しています。そのためトラブルシューティングのロジックを一律に扱うことはできません。400 が発生した場合は thinking_budget、MINIMAL、そして削除が必要なフィールドを優先的に確認しましょう。出力スタイルが期待と異なる場合は、温度パラメータにまだ依存していないかを確認します。

Hydrogen で簡略化したリクエスト設定

config = types.GenerateContentConfig(
    system_instruction=STABLE_SYSTEM_PROMPT,   # 安定した内容を先頭に置くと暗黙的キャッシュに有利
    thinking_config=types.ThinkingConfig(thinking_level="medium"),
    response_mime_type="application/json",      # 構造化出力は引き続きサポートされる
    max_output_tokens=8192,
)

典型的な影響：これまで低い温度に頼って JSON の安定した出力を保証していたプロジェクトは、構造化出力の機能に切り替えるべきです。また、プリフィルされた model のターンでフォーマットを制御していたプロジェクトは、フォーマット要件をシステムプロンプトに記述する必要があります。

五、調整4：Hydrogen の明示的キャッシュを暗黙的キャッシュへ変更

以前の動作：3.8 Flash では、開発者はまずキャッシュオブジェクトを作成し、その後リクエスト内で cached_content="cachedContents/xxx" を参照できました。

新しい動作：Hydrogen は明示的なコンテキストキャッシュをサポートせず、暗黙的キャッシュのみをサポートします。さらに、永続的な暗黙的キャッシュの仕組みがデフォルトで有効になります。キャッシュの最小プレフィックス長は 3.8 Flash の 6,144トークンから 4,096トークンに下がり、比較的短い共通システムプロンプトや固定の知識素材でもヒットしやすくなりました。

変更方法：caches.create の呼び出しと cached_content の参照をすべて削除し、代わりにプロンプトの組み立て順序を最適化します。Google は、安定した共通コンテンツを入力の前半に置き、毎回変化するユーザーの質問を末尾に置くことを推奨しています：

1. システムプロンプトと役割設定（ほぼ不変）
2. 共通ナレッジベース、API ドキュメント、コード規約（低頻度で変化）
3. 会話履歴（ターンごとに追加）
4. 現在のユーザーの質問（毎回変化）

典型的な影響：価格面では、Google AI Studio の公式価格ページ（確認日：2026年11月13日、単位は100万トークンあたりの米ドル）によると、Hydrogen の標準呼び出しでは、暗黙的キャッシュがヒットした入力は $0.075、Batch および Flex モードでは $0.0375 で、標準入力の $1.50 を大きく下回ります。タイムスタンプやユーザー ID などの動的変数をプロンプトの先頭に挿入すると、プレフィックスが毎回異なるため、キャッシュにヒットしません。

六、調整5：Hydrogen で thought_signature を正しく維持する

従来の動作：3.8 Flash では、多くの Agent フレームワークが会話履歴を独自に再構築し、テキストとツール呼び出しの結果だけを保持していました。そのため、署名が失われても目立った影響が出ることはほとんどありませんでした。

新しい動作：Hydrogen のマルチターン会話では、関連するすべてのパーツに付随する署名を保持する必要があります。これには最終テキストパーツが持つ署名も含まれます。公式の移行ガイドでは、並列ツール呼び出しについて次のように規定されています。

• 複数の並列 functionCall は同一のモデルメッセージ内に置かなければならない
• thought_signature は最初の並列 functionCall パーツにのみ配置する
• 後続の functionResponse は、対応する呼び出し ID、名前、そして順序に従って返す必要がある
• 同じモデルで署名を再利用する際、履歴のプレフィックスが変わると、デフォルトでは HTTP 400 が返されることがある

Hydrogen の署名維持における変更方法

最も確実なのは、parts を手動で再構築しないことです。モデルが返した content オブジェクトをそのまま履歴に追加します。

history = [types.Content(role="user", parts=[types.Part(text=question)])]
resp = client.models.generate_content(
    model="gemini-4-hydrogen", contents=history, config=agent_config
)
model_content = resp.candidates[0].content
history.append(model_content)          # そのまま保持し、署名も一緒に残る

calls = [p.function_call for p in model_content.parts if p.function_call]
responses = [
    types.Part.from_function_response(name=c.name, response=run_tool(c))
    for c in calls                      # functionCall と同じ順序を保つ
]
history.append(types.Content(role="user", parts=responses))

履歴を圧縮したりトリミングしたりする Agent（スライディングウィンドウや要約による置き換えなど）では、履歴のプレフィックスが必ず変化します。そのような場合は、移行ガイドに従って prefix_mismatch_behavior="DROP" を設定すると、プレフィックスが一致しないときに古い署名を破棄するようになり、エラーを返さずに済みます。このフィールドがリクエスト内のどこに置かれるかは、公式の移行ガイドで確認してください。

典型的な影響：自社開発の Agent Harness、ファイルを並列検索するコーディングアシスタント、コンテキスト圧縮を伴う長い会話のボットが最も大きな影響を受けます。署名の返送については、個別に統合テストを書くことをおすすめします。

七、Hydrogen への移行チェックリストと最小限の呼び出し例

OpenAI互換インターフェースによる迅速な検証

チームの業務コードがOpenAI SDKをベースにしている場合、まず互換インターフェース経由でHydrogenの出力品質を迅速に検証し、その後ネイティブSDKへの改修を判断できます。モデルが提供されているかどうか、および透過可能なパラメータについては、プラットフォームのモデルリストとドキュメントに準拠してください。

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI OpenAI互換インターフェース
)

resp = client.chat.completions.create(
    model="gemini-4-hydrogen",
    messages=[{"role": "user", "content": "用 Python 写一个带重试的 HTTP 请求函数"}],
)
print(resp.choices[0].message.content)

import json
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 統一インターフェースで、新旧モデルの比較が容易
)

TOOLS = [{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "读取仓库中的文件内容",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}]

STABLE_SYSTEM_PROMPT = "你是代码修复助手。只修改与问题相关的代码。"

def read_file(path: str) -> str:
    with open(path, encoding="utf-8") as f:
        return f.read()

def run_agent(question: str, model: str = "gemini-4-hydrogen", max_steps: int = 8) -> str:
    # 安定したシステムプロンプトを先頭に配置し、暗黙的キャッシュのヒットを促進
    messages = [
        {"role": "system", "content": STABLE_SYSTEM_PROMPT},
        {"role": "user", "content": question},
    ]
    for _ in range(max_steps):
        resp = client.chat.completions.create(
            model=model, messages=messages, tools=TOOLS
        )
        msg = resp.choices[0].message
        # assistantメッセージ全体をそのまま履歴に書き戻し、フィールドを削らずに保持
        messages.append(msg.model_dump(exclude_none=True))

        if not msg.tool_calls:
            return msg.content

        # tool_callsの元の順序に従って結果を順次返す
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments)
            result = read_file(**args) if call.function.name == "read_file" else ""
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    return "达到最大步数，任务未完成"

if __name__ == "__main__":
    print(run_agent("检查 utils.py 中的 parse_date 函数是否有时区问题"))

🚀 クイックスタートのヒント：移行期間中は3.8 Flashを対照群として残し、同じ実リクエスト群で新旧モデルを同時に実行することをお勧めします。APIYI apiyi.com なら1つのAPIキーで2つのモデルを同時に呼び出せます。新規ユーザーには無料テスト枠があるため、まず小流量で比較してから全量切り替えするのに適しています。

よくある質問 FAQ

Hydrogen移行の核心ポイント Key Takeaways

• 名前を変えるだけではありません：モデルIDをgemini-4-hydrogenに変更するのは第一歩に過ぎず、さらに4つの設定を同時に調整する必要があります。
• SDKが必須条件です：長い出力の継続生成にはPython >= 2.34.0、JS >= 2.32.0（Interactions API）が必要で、v1beta1を使用します。
• 思考パラメータの世代交代：thinking_budgetとMINIMALはHTTP 400を返すようになり、デフォルトの段階はHighに変わりました。
• サンプリングパラメータが無効化：temperature、top_p、top_kは無視され、penalty、複数候補、プレフィルラウンドは削除が必要です。
• キャッシュは構造次第：明示的キャッシュは廃止され、安定したプレフィックスが4,096トークンに達しないと暗黙的キャッシュにヒットしません。
• 署名は完全である必要があります：並列呼び出しの署名は最初のfunctionCallのみに付与され、応答は順序通りに返されます。履歴圧縮はDROPに設定できます。
• 比較してから切り替えを：APIYI apiyi.comを通じて同じKeyで新旧モデルを呼び出し、小規模トラフィックで検証してから全量移行してください。

まとめ

Gemini 3.8 FlashからHydrogenへのアップグレードの核心ポイント：

1. 基盤層：モデルIDとSDKを更新し、1,048,576トークンの統一クォータと、単一セグメント65,536トークンの出力上限を理解する；
2. パラメータ層：thinking_budgetの代わりにthinking_levelを使用し、無効になったサンプリングと生成フィールドを整理する；
3. 状態層：暗黙的キャッシュにヒットするようプロンプト構造を再設計し、thought_signatureをそのまま保持して返送する。

本記事のチェックリストに沿って項目ごとに改修することをお勧めします。さらに、ツール呼び出しと長い出力の回帰テストを作成したうえで、実際のトラフィックを新モデルに切り替えてください。APIYI apiyi.comを通じて新旧モデルの効果比較を素早く完了することをお勧めします。本プラットフォームはOpenAI互換インターフェースと、新規ユーザー向けの無料テストクォータを提供しています。

📚 参考資料

1. Gemini 4 Hydrogen 開発者移行ガイド：公式の互換性変更と移行チェックリスト
2. リンク： docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-4-hydrogen

3. 説明：SDK の最低バージョン、署名ルール、prefix_mismatch_behavior などの詳細に関する一次情報源

4. Gemini 4 入門と移行時の相違点対照：長文出力と API バージョンに関する解説

5. リンク： docs.cloud.google.com/gemini-enterprise-agent-platform/models/start/get-started-with-gemini-4

6. 説明：続き生成機能では v1beta1 API を使用する必要があることを説明

7. Google Cloud Hydrogen モデル仕様：コンテキスト、パラメータ、機能サポート一覧

8. リンク： docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-hydrogen

9. 説明：temperature、top_p、top_k の固定値とキャッシュのサポート状況

10. Google 公式ブログ：Gemini 4 Hydrogen リリース告知

11. リンク： blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/

12. 説明：製品の位置づけ、3.8 Flash との公式比較データ

13. Google AI Studio 料金ページ：公式 API 料金

14. リンク： aistudio.google.com/docs/pricing

15. 説明：標準、Batch、Flex、Priority、およびキャッシュヒット時の料金

16. Artificial Analysis による独立評価：4段階の思考レベル評価

17. リンク： artificialanalysis.ai/models/gemini-4-hydrogen

18. 説明：第三者によるインテリジェンス指数、評価所要時間、コストデータ

19. Google DeepMind モデルカード：能力、限界、安全性評価

20. リンク： deepmind.google/models/model-cards/gemini-4-hydrogen/
21. 説明：既知の制限と公式のモデル間評価

著者：APIYI 技術チーム
技術交流：移行の過程で互換性の問題に遭遇した場合は、APIYI 公式サイトからお気軽にご連絡ください。その他の接続資料は docs.apiyi.com のドキュメントセンターでご確認いただけます。

関連記事

• Gemini 4 Argonの推論強度設定ガイド：デフォルトはhighではなくmedium、Cherry Studioの設定を含む3つの方法:Gemini 4 Argonの推論強度のデフォルトはhighではなくmediumで、デフォルトが最高レベルのgemini-3.1-pro-previewとは異なります。本記事では、thinking_levelの3段階の値、reasoning_effortとの対応関係、Cherry Studioでのカスタムパラメータ設定方法、max_tokensによる切り詰めや400エラーなど、よくある落とし穴を詳しく解説します。
• Gemini 4 Hydrogenはどれほど強力？公式表で10項目中7項目に勝利:Googleは2026年11月12日にGemini 4 Hydrogenを発表し、公式モデルカードの10項目中7項目で比較に勝利、Gemini 3.8 Flashより2.5倍高速で、Terminal-Bench 4.1が18.2%から57%に向上したとし、これらの数値の基準、価格、呼び出し状況を説明した。
• Gemini 4 Hydrogen と Gemini 4 Carbon の比較：日常ではどう選ぶか:位置づけ、思考レベル、コンテキストと出力、価格、Orchestratorの使い方の5つの観点から、日常利用におけるGemini 4 HydrogenとGemini 4 Carbonの役割分担、およびAPIYIで現在呼び出し可能なモデルを説明する。
• Gemini 4 Hydrogen と Claude Sonnet 5.5 の比較：10項目でどう選ぶ:公式モデルカードの10項目集計と公式価格に基づき、Gemini 4 HydrogenとClaude Sonnet 5.5を比較すると、Hydrogenは7項目でリードし短いプロンプトではより安価で、Sonnetはターミナル、コンピュータ操作、科学ターミナルの3項目で上回り、選定アドバイスとAPIYI接続説明を付す。
• Gemini APIの呼び出し量が4倍に急増：開発者はArgon、Flash、Flash-Liteのどれを選ぶべき？3モデルの選定ガイド:Alphabetは自社モデルのAPIが毎分約320億トークンを処理していると公表しました。本記事では、公式価格、独立評価、コストシミュレーションの3つの観点からGemini 4 Argon、3.8 Flash、3.5 Flash-Liteを比較し、「合格したタスク1件あたりの総コスト」を明らかにします。