@haram
Gemini API コンテキストキャッシング — トークンコストを90%削減するコスパ最強の設定
AIで長いドキュメントやソースコード全体を分析していると、あっという間に増えるAPIコストが負担になることはよくあります。質問をするたびに数万トークンに及ぶ背景データを毎回最初から送信し直す必要があるためです。Gemini APIが提供する「コンテキストキャッシング」を活用すれば、この無駄な入力トークンコストを最大90%削減し、回答速度も劇的に向上させることができます。
コンテキストキャッシング、どんな仕組みで動作する？
コンテキストキャッシングは、簡単に言えば「分厚い参考書を机の上に開きっぱなしにしておく」ようなものです。本来であれば、AIに質問するたびに数百ページの説明書やソースコード全体を丸ごと渡す必要がありました。質問を少し変えるたびに同じデータを毎回最初から送信し、お金と時間を無駄にしていた構造だったのです。
Googleのコンテキストキャッシングは、この重い参考書をGoogleサーバー上に一度だけ広げておき、必要に応じてその内容を即座に参照して回答する技術です。おかげで同じデータを毎回送信する必要がなくなり、速度が劇的に速くなります。
このキャッシング技術は、大きく2つの方式に分かれます。Gemini 2.5以上のモデルで自動的に賢く動作する「暗黙的キャッシング」と、開発者がコードで明示的に生成し期間を制御する「明示的キャッシング」です。この記事では、確実なトークン割引が保証され、コスト削減を確実に実現できる明示的キャッシングを中心に解説します。
何トークンから適用される？コストを抑える新しい計算方法
かつてのGemini 1.5時代には、最低3万2,768トークン以上を入力しなければキャッシュを使えませんでした。小規模な個人開発プロジェクトにとっては、実質的に手が届かないものでした。しかし、最新モデルの登場により、このハードルは大幅に下がりました。
現在、Gemini 2.5製品群では最低2,048トークン、Gemini 3および3.5製品群では最低4,096トークンを超えれば、すぐにコンテキストキャッシングを適用できます。長めの記事やソースコードファイル1〜2個程度からでも、コスト削減の恩恵を受けられるようになったのです。
費用構造も非常に合理的です。キャッシュとして指定した領域からデータを再読み込みする場合、入力トークンコストがなんと90%割引され、元の価格の10%のみを支払えば済みます。その代わり、キャッシュデータをサーバーに保持している間、時間単位で少額の保管料を負担する仕組みです。
保管料はモデルの性能に応じて異なります。軽量で高速なFlashモデルは100万トークンあたり1時間1.00ドル、高精度のProモデルは100万トークンあたり1時間4.50ドルが課金されます。数時間稼働し続けるカスタマーサポート用チャットボットやコード分析ツールであれば、数ドルの保管料を払うだけで、数百ドル相当の重複入力コストを節約できる可能性があります。
コードで1分でキャッシングを適用する方法
明示的キャッシングを適用する方法は、意外にも非常に簡単です。Googleの最新公式SDKである @google/genai を活用すれば、数行のコードだけで大容量データをGoogleサーバーにキャッシュしておき、必要な時にいつでも再利用できます。
まず、Googleサーバーに展開しておきたい背景知識や大型ドキュメントを指定し、ai.caches.create() を呼び出します。この際、キャッシュの生存時間（TTL）を指定でき、指定しない場合はデフォルトの1時間となります。キャッシュ登録が完了すると、固有の識別子であるcache.name が発行されます。
その後質問を送る際は、取得した識別子をcachedContent の設定に含めるだけで完了です。
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI();
// 1. 대용량 문서나 배경 데이터를 캐시로 등록합니다.
const cache = await ai.caches.create({
model: 'gemini-2.5-flash',
config: {
displayName: 'large-doc-cache',
ttl: '3600s', // 캐시 생존 시간 (기본값 1시간)
},
contents: [
{
role: 'user',
parts: [{ text: '여기에 분석할 수만 글자의 대용량 소스 코드나 매뉴얼을 넣습니다.' }]
}
]
});
// 2. 등록한 캐시를 지정하여 빠르게 질문을 보냅니다.
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: '위 소스 코드에서 개선할 점을 세 가지만 찾아줘.',
config: {
// 생성된 캐시 이름을 지정해 재사용합니다.
cachedContent: cache.name,
}
});
console.log(response.text);ここで実戦でよくある注意点が1つあります。キャッシングを適用した質問を送る際は、システム指示（systemInstruction）やツール設定（tools）をリクエスト本文に重複して記述してはいけません。
これらの設定はキャッシュを初回生成する際に保存され、自動的に継承されます。質問を送る際はこれらを空欄にし、純粋な質問のみを渡すことでエラーなくスムーズに動作します。
自分のプロジェクトに導入すべき？
同じ大型ドキュメント、長文のソースコード、あるいは重いプロンプトをベースにユーザーと何度も対話を行うサービスを開発していますか？それなら、Geminiのコンテキストキャッシングはコスト削減のための心強い味方になります。ほんの数行のコードを追加するだけで、毎回発生していた入力トークンコストを最大10分の1まで抑えられるからです。
もちろん、たまに軽い質問を投げるだけのシンプルなチャットボットであれば、無理にキャッシングを設定する必要はありません。かえって保管コストの方が高くつくこともあります。しかし、サービスの性質上、基準となる2,048トークンや4,096トークンを超える処理が多いなら、今すぐGoogleのこのコスパ設定をオンにして、賢くコストを最適化してみてください！