Google Cloud や Vertex AI で Gemini API を使ったエージェント実装をしている方に向けた内容です。Gemini 4 Carbon(Google が2025年に投入したコーディング・検証特化モデル)を既存のAI Studio連携やCI連携に組み込もうとすると、ドキュメントの読み方次第で思わぬ設定ミスにつながる箇所があります。順を追って確認していきます。
何が起きるか:仕様の「読み違え」で動かなくなる
Gemini 4 Carbonは、既存のGemini 4 Argon(同じGemini 4世代の標準コーディングモデル)の後継ではありません。
Argonが苦手とする「数時間〜数日かかる長時間タスク」を引き受ける、上位ティアのモデルという位置づけです。
この位置づけを誤解したまま、Argon向けに作った呼び出しコードをそのままCarbonのモデルIDに差し替えると、いくつかの箇所でつまずきます。
代表的なのは次の3点です。
- 出力トークンの上限設定を誤り、長時間実行のはずが途中で打ち切られる
- 明示的キャッシュ(explicit caching)を前提にしたコスト設計が通用しない
- 画像・動画・音声を「出力」できると誤認し、マルチモーダル生成の呼び出しでエラーになる
これらはいずれも、モデルを切り替えた直後の動作確認で発覚しやすい不具合です。
CIでのスモークテストが薄いプロジェクトほど、本番投入後に気づく可能性があります。
なぜ起きるか:ドキュメントの数字が2系統ある
原因を段階的に分解します。
1. 出力上限の記載がドキュメントごとに異なる
Google CloudのモデルページとAI Studioのモデルページで、最大出力トークンの表記が揃っていません。
Google Cloud側は「1,048,576トークン」という大きな数字を最大出力として掲載しています。
一方でAI Studio側は「デフォルトの同期実行では65,536トークン、long decode(長時間デコード、推論を長く続けてから出力する機能)を有効にした場合のみ1,048,576トークンまで拡張可能」という、条件付きの説明になっています。
この2つはおそらく同じ仕様を異なる粒度で説明しているだけですが、設定ファイルやSDKの初期値をどちらか一方だけ見て決めてしまうと、想定より早く出力が打ち切られる原因になります。
2. コンテキストウィンドウの「統合」という仕様を見落とす
Carbonのコンテキストウィンドウは1,048,576トークンですが、これは入力・思考(reasoning)・出力をすべて合算した「統合ウィンドウ」です。
入力プロンプトが長いエージェントタスクほど、出力に回せる残りトークンが圧迫されます。
Argon時代の感覚で「入力は別枠」と思い込んでいると、長時間タスクの途中で出力が尽きる挙動に遭遇します。
3. 明示的キャッシュが使えないという制約
Carbonは暗黙のキャッシュ(implicit caching、同一プレフィックスを自動検出して課金を抑える仕組み)のみ対応で、明示的キャッシュ(explicit caching、キャッシュIDを指定して確実に再利用する仕組み)は未対応です。
既存のArgonやGemini 1.5系のコスト最適化コードで明示的キャッシュAPIを呼んでいる場合、Carbonに切り替えた瞬間にそのリクエストは無視されるか失敗します。
4. 対応ツール・非対応機能の線引きが細かい
Carbonはファンクションコール、コード実行、コンピュータ操作(computer use)、ファイル検索、URLコンテキスト取得、Google検索・マップのグラウンディング、構造化出力には対応しています。
その一方で、画像生成・音声生成・Live API(リアルタイム双方向対話API)は非対応です。
テキスト・画像・動画・音声・PDFは入力として受け付けますが、出力はテキストのみという非対称な仕様です。
マルチモーダル生成を期待してAPIを叩くと、エラーまたは意図しない空応答になります。
自分のプロジェクトが該当するか確認する方法
実際に影響を受けるかどうかは、次の手順で確認できます。
使用中のモデルIDを洗い出す
まず、リポジトリ内でGeminiのモデルIDをハードコードまたは環境変数経由で指定している箇所を検索します。
grep -rn "gemini-4" --include="*.{py,ts,js,yaml,env}" .gemini-4-carbon や gemini-4-carbon-cyber-permissive(Fairwindという承認プロセスを経たプロジェクト向けの派生モデル)が含まれていれば、以下のチェックが必要です。
出力トークン上限の設定値を確認する
max_output_tokens やそれに相当するSDKのパラメータが、65,536固定で書かれていないか確認します。
long decodeを使う意図があるなら、その指定が別パラメータとして必要かどうかをAI StudioとGoogle Cloudの両方のモデルページで突き合わせてください。
キャッシュ関連の呼び出しを確認する
cached_content やキャッシュID(cachedContents.create 相当のAPI)を使っているコードがあれば、Carbonでは暗黙キャッシュのみという前提で設計し直す必要があります。
マルチモーダル出力を期待していないか確認する
レスポンスから画像・音声データを取り出す処理が残っていないか、呼び出し側のパース処理を確認します。
出力がテキストのみである前提でレスポンスハンドラを書き直す必要があります。
対策の手順
確認の結果、該当箇所が見つかった場合の対処手順です。
1. モデルの使い分けを明文化する: Argonは通常の開発・知識作業向け、Carbonは数時間〜数日かかる検証ループやセキュリティ診断(脆弱性の検出・悪用可能性の優先順位付け・根本原因の修正まで一貫して担える点が特徴)向けと役割を分け、呼び出し元で条件分岐させます。
2. 出力上限を明示的に指定する: デフォルト値に頼らず、long decodeを使う場合はその設定を明示し、使わない場合は65,536を上限として組み込み処理側でタイムアウトやリトライを設計します。
3. キャッシュ戦略をCarbon用に分離する: 明示的キャッシュに依存するコスト計算ロジックをCarbon呼び出しから切り離し、暗黙キャッシュが効くようにプロンプトの先頭部分(システムプロンプトなど)を固定・再利用可能な形に整えます。
4. マルチモーダル出力のテストケースを追加する: CIのスモークテストに「画像生成を要求した場合に正しくエラーまたはテキストのみ応答になるか」を確認するケースを1つ加えます。
5. 利用規約の該当条項を確認する: CarbonはGoogleのサービス固有条項内で「Frontier Model」として扱われ、濫用監視の対象になっています。規制対象データを扱う場合は、この条項を運用担当者と確認しておく必要があります。
まとめ
Gemini 4 Carbonは、Argonの「上位互換」ではなく「別の予算配分で動く別モデル」という理解が出発点になります。
- 出力トークン上限はGoogle CloudとAI Studioの記載が条件付きで異なるため、両方のモデルページを突き合わせて確認する
- 明示的キャッシュは使えず、暗黙キャッシュのみという前提でコスト設計を見直す
- 出力はテキストのみという非対称な入出力仕様を、CIのテストケースとして固定化する
まずは grep でモデルIDの使用箇所を洗い出すところから始めて、上記のチェックリストを1つずつ当ててみるのが確実な進め方です。