プロンプトキャッシュ（プレフィックスキャッシュとも呼びます）は、共通の入力を持つプロンプトへの応答を速くするパフォーマンス最適化です。以前計算した入力テンソルを再利用し、最初から再処理しないことで、Time to First Token（TTFT）を短縮し、Tokens Per Second（TPS）のスループットを上げます。
キャッシュされた入力トークンは、通常の入力トークンより割引された料金で課金されます。Workers AI は、対象モデルでプレフィックスキャッシュをデフォルトで有効にします。対応状況と料金の詳細は、各 モデルページ にあります。
LLM がリクエストを処理するときは、次の 2 段階を通ります。
- プリフィル段階 — 入力トークン（システムプロンプト、ツール定義、会話履歴）を処理します。
- 出力段階 — 出力トークンを生成します。
プレフィックスキャッシュでは、Workers AI はプリフィル段階で計算した入力テンソルを保存します。同じプレフィックスを共有する後続リクエストでは、キャッシュ済みの部分のプリフィルをスキップし、新しい入力トークンだけを処理します。連続するリクエストが大量のコンテキストを共有するエージェントワークロードでは、計算時間を大きく節約できます。
たとえば、コーディングエージェントが新しいプロンプトを送るときは、通常、以前のプロンプト、ツール定義、会話履歴をすべて再送します。連続リクエストの差分は、新しい数行だけであることが多いです。プレフィックスキャッシュは、共有コンテキスト全体の冗長なプリフィルを避けます。
プレフィックスキャッシュは、キャッシュされたテンソルを持つ同じモデルインスタンスへリクエストがルーティングされたときだけ機能します。キャッシュヒット率を最大化するには、セッションまたはエージェントを一意に識別する x-session-affinity ヘッダーを送ります。同じ識別子のリクエストが同じモデルインスタンスへルーティングされ、プレフィックスキャッシュにヒットしやすくなります。
curl -X POST \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/moonshotai/kimi-k2.5" \
-H "Authorization: Bearer {api_token}" \
-H "Content-Type: application/json" \
-H "x-session-affinity: ses_12345678" \
-d '{
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "What is prefix caching and why does it matter?"
}
],
"max_tokens": 2400,
"stream": true
}'const response = await env.AI.run(
"@cf/moonshotai/kimi-k2.5",
{
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain prefix caching." },
],
},
{
extraHeaders: {
"x-session-affinity": "ses_12345678",
},
},
);プレフィックスキャッシュは、プロンプト先頭からのトークン列を完全一致で照合します。トークンが 1 つ違うと、その地点以降のキャッシュは無効になります。
キャッシュヒットを最大化するには、次を行います。
- 静的な内容を先に置きます。 システムプロンプト、ツール定義、共有の指示はプロンプトの先頭に置きます。ユーザー固有または動的な内容（タイムスタンプ、ユーザークエリ）は末尾に置きます。
- システムプロンプトにタイムスタンプを入れないでください。 システムプロンプトの先頭にタイムスタンプがあると、リクエストごとにプレフィックスが変わり、キャッシュがまったく効きません。時刻の文脈が必要な場合は、ユーザーメッセージに追加します。
- リクエスト間でツール定義を再利用します。 関数呼び出しエージェントでは、ツールはプロンプトプレフィックスの一部です。同じセッションのリクエストでツール定義を揃えると、キャッシュの再利用が増えます。
Workers AI は、レスポンスの usage オブジェクトにキャッシュ済みトークン数を出します。プレフィックスキャッシュが動作していることの確認と、コスト削減の追跡に使います。最初のリクエストは通常コールドなので、初回ヒットではキャッシュ済みトークンは返りません。ブロックサイズの都合で、キャッシュ対象にするには入力が十分大きい必要があります。
キャッシュ済みトークンは通常の入力トークンより低い料金で課金され、neuron 数に合算されます。