Skip to main content

明示的キャッシュ(Qwen4)

Qwen4 シリーズモデル専用の明示的キャッシュです。自動キャッシュまたはキャッシュブレークポイントで再利用する入力プレフィックスを指定し、キャッシュの有効期間を 5 分または 1 時間に設定することで、重複計算を減らし、遅延と入力コストを削減します。

マルチターン対話、長文ドキュメントの Q&A、Agent などのシナリオでは、連続するリクエストに同じ冒頭コンテンツが大量に含まれることがよくあります。たとえば、システムプロンプト、ツールの説明、参照ドキュメントなどです。明示的キャッシュ(Qwen4)を使用すると、有効期間内の後続リクエストはこの部分をキャッシュから直接読み取れるため、再計算が不要になり、応答遅延と入力コストが削減されます。 明示的キャッシュはキャッシュブレークポイントで再利用するコンテンツプレフィックスを指定し、ヒットは確定的です。プレフィックスが完全に同じで有効期間内であれば、後続リクエストはキャッシュを読み取れます。共通プレフィックスを自動的に識別する暗黙的キャッシュは、ヒットを保証しません。 Qwen4 は基本の使い方に加えて、自動キャッシュとキャッシュ TTL を提供します。詳細は高度な使い方を参照してください。
このページでは、既存の明示的キャッシュの Qwen4 版について説明します。コンテンツブロックのブレークポイントの使い方は変わらず、自動キャッシュとキャッシュ TTL が追加されています。コンテキストキャッシュの 2 つのキャッシュモードとの関係は次のとおりです。
  • 明示的キャッシュ:キャッシュブレークポイントで入力プレフィックスを指定し、ヒットが確定的です。このページで説明する内容です。
  • 暗黙的キャッシュ:キャッシュパラメーターを設定しない場合に共通プレフィックスを自動的に識別しますが、ヒットは保証されません。詳細は暗黙的キャッシュを参照してください。
  • OpenAI 互換 Chat Completions API の従来の cache_control コンテンツブロックマーカーは引き続き互換性があり、prompt_cache_breakpoint と同じように使用できます。詳細は基本の使い方を参照してください。

仕組み

キャッシュはブレークポイント単位で作成および読み取られます。自動キャッシュでは、システムが入力の末尾にブレークポイントを設定します。キャッシュブレークポイントでは、コンテンツブロックにブレークポイントを設定します。各ブレークポイントのキャッシュプレフィックスは、リクエストの先頭からブレークポイントを含むコンテンツブロックの末尾までのすべての入力です。 リクエストを受信すると、システムは各ブレークポイントを終点として最大 20 個のコンテンツブロックを前方に検索し、キャッシュ済みの最長の同一プレフィックスを選択します。
  • キャッシュヒット:キャッシュ済みのプレフィックスを読み取り、今回のリクエストの TTL で更新します。
  • キャッシュミス:リクエストの先頭からブレークポイントまでのコンテンツを新しいキャッシュとして作成します。プレフィックスの一部がすでにキャッシュにヒットしている場合は、新しく追加された部分のみをキャッシュします。
キャッシュヒットにはプレフィックスが完全に一致している必要があり、キャッシュは同一ユーザーのリクエスト間でのみ再利用されます。ヒット率を高めるには、変わらないコンテンツを先頭に置き、リクエストごとに変わるコンテンツをブレークポイントの後に置きます。 キャッシュパラメーターを設定しない場合、システムは暗黙的キャッシュを使用してリクエスト間の共通プレフィックスを自動的に識別しますが、ヒットは保証されません。特定のコンテンツを確実に再利用するには、自動キャッシュを有効にするか、キャッシュブレークポイントを設定します。

基本の使い方

再利用するコンテンツブロックにキャッシュブレークポイントを設定します。システムはそのコンテンツブロックの末尾をブレークポイントとし、リクエストの先頭からその位置までのすべての入力をキャッシュプレフィックスとして扱います。最初のリクエストでキャッシュが作成され、有効期間内に同じプレフィックスを持つ後続リクエストがキャッシュを読み取ります。キャッシュプレフィックスは 1,024 トークン以上必要です。
  • OpenAI 互換 Chat Completions
  • OpenAI 互換 Responses
  • Anthropic 互換
messages でキャッシュするコンテンツブロックに、値 {"mode": "explicit"} の prompt_cache_breakpoint を追加します。ブレークポイントを設定するメッセージの content は配列形式にする必要があります。
messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- キャッシュブレークポイント
      },
      {"type": "text", "text": "このドキュメントを要約してください。"},  # ブレークポイント以降のコンテンツはこのキャッシュに含まれない
    ],
  }
],
従来の "cache_control": {"type": "ephemeral"} コンテンツブロックマーカーは引き続き互換性があり、prompt_cache_breakpoint と同じように使用できます。同一ユーザーの同一プレフィックスのキャッシュは、2 つのマーカー間で再利用できます。新規の実装では prompt_cache_breakpoint を使用することを推奨します。
1 つのリクエストでは、prompt_cache_breakpoint と cache_control のいずれか一方のみを使用してください。
次の例では 2 つのリクエストを送信します。最初のリクエストでキャッシュを作成し、2 番目のリクエストではプレフィックスを変えずに質問だけを変更してキャッシュを読み取ります。
Python
import os
from openai import OpenAI

client = OpenAI(
  # 環境変数を設定していない場合は、次の行を api_key="sk-xxx" に置き換えてください
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # 以下は中国(Singapore)リージョンの URL です。呼び出す際は WorkspaceId を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 再利用する長文ドキュメント。キャッシュプレフィックスは 1024 トークン以上必要です
long_text = "<固定の長文ドキュメント>" * 400

def ask(question):
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
      {
        "role": "user",
        "content": [
          {"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}},  # <-- キャッシュブレークポイント
          {"type": "text", "text": question},  # ブレークポイント以降のコンテンツは毎回変更できます
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("このドキュメントを要約してください。")  # 1 回目のリクエスト:キャッシュを作成
details = ask("このドキュメントの要点を 3 つ挙げてください。")  # 2 回目のリクエスト:キャッシュを読み取る
print(f"キャッシュ読み取り {details.cached_tokens} トークン、キャッシュ作成 {details.cache_write_tokens} トークン")
2 回目のリクエストの cached_tokens は読み取ったキャッシュ量、cache_write_tokens は今回作成したキャッシュ量です。プレフィックスが変わらない場合、cache_write_tokens は 0 になります。数値は例示であり、実際の値はドキュメントの長さによって異なります。

複数のブレークポイントを使用する

プロンプトが異なる頻度で変化する複数の部分で構成されている場合は、部分ごとにブレークポイントを設定できます。たとえば、カスタマーサービスのプロンプトには通常、システムペルソナ(ほとんど変化しない)、ナレッジベースの検索結果(問い合わせ内容によって変化する)、会話履歴(増え続ける)が含まれます。各部分の末尾にブレークポイントを設定すると、ナレッジベースの内容が変わっても、システムペルソナの部分はキャッシュにヒットできます。 各リクエストでは最大 4 つの有効なブレークポイントが保持されます。それを超えるブレークポイントは有効になりません。自動キャッシュを有効にすると、自動ブレークポイントが 1 つを使用します。

ブレークポイントが移動した場合の更新

システムは今回のリクエスト内のブレークポイントのみを作成または更新します。ブレークポイントが移動しても、古いブレークポイントのキャッシュが読み取られた場合でも、その有効期間は延長されません。 たとえば、TTL が同じ場合、前回のリクエストのブレークポイントが 2,048 トークンの位置にあり、今回のリクエストで古いブレークポイントを残さずに 3,072 トークンの位置に移動したとします。古いブレークポイントが検索範囲内にあり、期限切れでない場合、今回のリクエストは最初の 2,048 トークンをキャッシュから読み取り、続く 1,024 トークンをキャッシュします。システムは 3,072 トークンの位置のブレークポイントのみを作成または更新します。2,048 トークンの位置のキャッシュは更新されません。

高度な使い方

Qwen4 は基本の使い方に加えて、次の 2 つの機能を提供します。これらは組み合わせて使用できます。
  • 自動キャッシュ:システムが入力の末尾に自動的にブレークポイントを設定します。マルチターン対話に適しています。
  • キャッシュ TTL:5 分または 1 時間を選択できます。

自動キャッシュ

自動キャッシュを有効にすると、システムが各リクエストの入力の末尾に自動的にブレークポイントを設定するため、会話の増加に合わせてブレークポイントを移動する必要がありません。自動ブレークポイントには、応答の生成を開始するためのテンプレートサフィックスは含まれません。自動キャッシュは、基本の使い方で説明したキャッシュブレークポイントと併用できます。入力の末尾にすでに手動ブレークポイントがある場合、重複して設定されません。
  • OpenAI 互換 Chat Completions
  • OpenAI 互換 Responses
  • Anthropic 互換
リクエストの最上位で prompt_cache_options を設定し、mode を implicit にします。OpenAI Python SDK を使用する場合は extra_body で渡します。
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "このドキュメントを要約してください:" + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- 自動キャッシュを有効にする
  },
)
prompt_cache_options.mode の値と対応する動作は次のとおりです。
設定自動ブレークポイントキャッシュ動作
mode が implicit設定される入力末尾の自動ブレークポイントと手動ブレークポイントの両方が有効
mode が explicit、手動ブレークポイントあり設定されない手動ブレークポイントでキャッシュを作成または読み取る
mode が explicit、手動ブレークポイントなし設定されない暗黙的キャッシュを使用
prompt_cache_options を省略、null または {}、または ttl のみ設定設定されない手動ブレークポイントがあればそこでキャッシュし、なければ暗黙的キャッシュを使用
mode が implicit の場合、自動ブレークポイントキャッシュが使用され、このページの TTL と課金のルールに従います。これは、キャッシュパラメーターを設定しない場合の暗黙的キャッシュとは異なります。mode を explicit にしても、自動ブレークポイントを設定しないというだけで、暗黙的キャッシュは無効になりません。mode は今回のリクエストにのみ適用されます。
次の完全な例では自動キャッシュを有効にし、同じ長文ドキュメントのリクエストを 2 回送信します。最初のリクエストでキャッシュを作成し、2 回目のリクエストで読み取ります。
  • OpenAI 互換 Chat Completions
  • OpenAI 互換 Responses
  • Anthropic 互換
import os
from openai import OpenAI

client = OpenAI(
  # 環境変数を設定していない場合は、次の行を api_key="sk-xxx" に置き換えてください
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # 以下は中国(Singapore)リージョンの URL です。呼び出す際は WorkspaceId を実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 再利用する長文ドキュメント。キャッシュプレフィックスは 1024 トークン以上必要です
long_text = "<固定の長文ドキュメント>" * 400

def ask():
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "このドキュメントを要約してください:" + long_text}],
    extra_body={
      "enable_thinking": False,
      "prompt_cache_options": {"mode": "implicit"},  # <-- 自動キャッシュを有効にする
    },
  )
  return completion.usage.prompt_tokens_details

for i in range(1, 3):
  details = ask()
  print(f"{i} 回目のリクエスト:キャッシュ読み取り {details.cached_tokens} トークン、キャッシュ作成 {details.cache_write_tokens} トークン")
出力は次のようになります。実際のトークン数はドキュメントの長さによって異なります。
1 回目のリクエスト:キャッシュ読み取り 0 トークン、キャッシュ作成 2048 トークン
2 回目のリクエスト:キャッシュ読み取り 2048 トークン、キャッシュ作成 0 トークン
2 回目のリクエストの入力は 1 回目と同じであるため、1 回目に作成されたキャッシュを読み取ります。

キャッシュ TTL を設定する

キャッシュの有効期間(TTL)は 5m(5 分)または 1h(1 時間)を選択でき、デフォルトは 5m です。有効期間内にキャッシュがヒットすると自動的に更新されます。更新方法は更新ルールを参照してください。
  • OpenAI 互換 Chat Completions
  • OpenAI 互換 Responses
  • Anthropic 互換
リクエストの最上位の prompt_cache_options.ttl で設定します。今回のリクエストのすべてのブレークポイントに適用されます。
extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- キャッシュ TTL は 1 時間
  },
},
prompt_cache_options.ttl を設定しない場合、リクエスト内の最後の cache_control マーカーの ttl が使用されます。そのマーカーに ttl がない場合、またはリクエストに cache_control マーカーがない場合、TTL は 5m です。TTL は明示的キャッシュにのみ適用されます。ttl を設定する場合は、キャッシュブレークポイントを設定するか、自動キャッシュを有効にしてください。

更新ルール

最初のリクエスト、またはキャッシュの有効期限が切れた後は、今回のリクエストの TTL でキャッシュが作成されます。有効なキャッシュにヒットした場合、更新と課金は次のルールに従います。
  • 遅い方の有効期限が保持され、高い方のティアが維持されます。 新しい有効期限は、おおよそ「元の有効期限」と「今回のキャッシュ処理開始時刻 + 今回の TTL」の遅い方になります。たとえば、12:05 に期限切れになる 5m キャッシュに 12:03 にヒットすると、有効期限は約 12:08 に延長されます。また、5m リクエストが有効な 1h キャッシュにヒットした場合、更新は 5m に基づいて計算されますが、キャッシュは 1h ティアを維持し、有効期間内の後続の 1h リクエストは引き続きキャッシュ読み取りとして課金されます。
  • 5m から 1h にアップグレードする場合、アップグレード部分は 1h キャッシュ作成として課金されます。 1h リクエストが有効な 5m キャッシュにヒットした場合、ヒット部分は 1h の TTL で再作成され、読み取りとしては課金されません。プレフィックスの一部にすでに有効な 1h キャッシュがある場合、その部分は引き続き読み取りとして課金され、残りの部分と新しく追加されたプレフィックスのみが作成として課金されます。その他の場合(5m リクエストが 5m キャッシュにヒット、5m リクエストが 1h キャッシュにヒット、1h リクエストが 1h キャッシュにヒット)は、ヒット部分は読み取りとして課金されます。
有効期間は今回のキャッシュ処理の開始時に計算され、元の有効期限に加算されることも、応答の終了時にリセットされることもありません。応答の生成にかかる時間は有効期間に含まれ、実際の有効期限には少量の処理時間が確保されます。 次の例は、12:00 に 1h で作成され、元の有効期限が 13:00 の同じキャッシュに対する連続リクエストです。
リクエスト今回の TTLリクエスト前の有効期限リクエスト後の有効期限(約)課金とティア
12:20 に送信5m13:0013:00キャッシュ読み取り。12:25 は元の有効期限より前であるため、有効期限は変わりません。短縮も 13:20 への延長もされません。
12:58 に送信5m13:0013:03キャッシュ読み取り。有効期限は今回の開始から 5 分後に延長され、1h ティアが維持されます。
13:01 に送信1h13:0314:01キャッシュ読み取り。キャッシュはすでに 1h ティアであるため、アップグレード作成は発生しません。
上記の例は、同じプレフィックスを持つ直列リクエストに基づいています。複数のリクエストが同じキャッシュに同時に書き込むと、互いに上書きされる可能性があり、最も遅い有効期限が保持されることは保証されません。

キャッシュ使用量を確認する

応答の usage には、キャッシュから読み取ったトークン数とキャッシュに書き込んだトークン数が返されます。ストリーミング出力の場合、OpenAI 互換 Chat Completions API では stream_options を {"include_usage": true} に設定し、usage を含む最後のチャンクから読み取ります。
  • OpenAI 互換 Chat Completions
  • OpenAI 互換 Responses
  • Anthropic 互換
次は、初めてキャッシュを作成したときの usage です(テキストのみの入力、非思考モード)。
{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "text_tokens": 2304,
      "cached_tokens": 0,
      "cache_write_tokens": 2048,
      "cache_creation_input_tokens": 2048,
      "cache_type": "ephemeral",
      "cache_creation": {
        "ephemeral_5m_input_tokens": 2048,
        "ephemeral_1h_input_tokens": 0
      }
    },
    "completion_tokens_details": {}
  }
}
フィールド説明
prompt_tokensすべての入力トークン数。キャッシュ読み取り、キャッシュ作成、キャッシュを使用しない入力が含まれます。キャッシュヒットしても減算されません。
total_tokensprompt_tokens と completion_tokens の合計
prompt_tokens_details.cached_tokensキャッシュから読み取ったトークン数
prompt_tokens_details.cache_write_tokensキャッシュに書き込んだトークン数
prompt_tokens_details.cache_creation_input_tokensキャッシュに書き込んだトークン数。cache_write_tokens と同じです。合計する際は重複して加算しないでください。
prompt_tokens_details.cache_type明示的キャッシュのタイプ。常に ephemeral です。
prompt_tokens_details.cache_creationTTL 別のキャッシュ書き込みトークン数。ephemeral_5m_input_tokens と ephemeral_1h_input_tokens の合計は、キャッシュに書き込んだトークン数と同じです。
上記の例では、キャッシュを使用しない入力は 2304 − 0 − 2048 = 256 トークンです。各キャッシュフィールドは生のトークン数であり、課金倍率は含まれません。有効期間内に同じプレフィックスで再度リクエストすると、cached_tokens は 2048、cache_write_tokens、cache_creation_input_tokens、および cache_creation の 2 項目は 0、prompt_tokens は 2304 のままです。画像、音声、動画などの入力詳細は実際の入力に基づいて返されます。思考などの出力詳細はモデルと構成に基づいて返されます。該当しないフィールドは 0 として返されるのではなく、省略されます。

ベストプラクティス

  • マルチターン対話では自動キャッシュを優先します。 自動ブレークポイントは会話の増加に合わせて後方に移動するため、ターンごとにブレークポイントを調整する必要がありません。
  • 固定コンテンツを先頭に置きます。 システムプロンプト、ツール定義、参照ドキュメントなど変化しないコンテンツを入力の先頭に置き、タイムスタンプやユーザーの質問などリクエストごとに変化するコンテンツを末尾に置きます。
  • ブレークポイントは、リクエスト間で同じ最後のコンテンツブロックに設定します。 リクエストごとに変化するコンテンツブロックにブレークポイントを設定しないでください。そうしないと、リクエストごとに新しいキャッシュが作成され、キャッシュを読み取れなくなります。
  • 履歴は書き換えずに追加します。 以前のメッセージやツール定義を変更、削除、並べ替えると、それ以降のキャッシュにヒットしなくなります。
  • 変化頻度に応じて複数のブレークポイントを使用します。 たとえば、ツール定義はほとんど変化せず、参照ドキュメントが毎日更新される場合は、それぞれの末尾にブレークポイントを設定します。
  • 1 ターンで追加されるコンテンツブロックが多い場合はブレークポイントを追加します。 各ブレークポイントは最大 20 個のコンテンツブロックを前方に検索します。1 ターンでこの範囲を超えるコンテンツが追加される場合は、中間位置にブレークポイントを追加します。
  • 再利用間隔に応じて TTL を選択します。 再利用間隔が 5 分以内の場合は 5m を使用します。ヒットするたびに更新されるためです。再利用間隔が 5 分から 1 時間の場合は 1h を使用します。
  • 使用量フィールドでヒット状況を確認します。 キャッシュヒット率は、キャッシュから読み取ったトークン数をすべての入力トークン数で割って計算できます。ヒット率が低い場合は、プレフィックスとブレークポイントの位置が安定しているか確認してください。

課金

キャッシュブレークポイントは入力トークンの課金方法にのみ影響します。出力トークンは通常価格で課金されます。
入力トークンの種類課金方法
キャッシュ作成、TTL 5m入力トークン価格の約 125%
キャッシュ作成、TTL 1h入力トークン価格の約 200%
キャッシュ読み取りQwen4-Max
キャッシュから読み取られず、書き込まれてもいない入力トークン価格
今回のリクエストのキャッシュプレフィックスに既存の有効なキャッシュが含まれる場合、既存部分はキャッシュ読み取りとして課金され、新しく追加された部分のみがキャッシュ作成として課金されます。TTL を 5m から 1h にアップグレードする場合の課金は更新ルールを参照してください。

制限事項

  • Qwen4 シリーズモデルのみをサポートします。
  • キャッシュプレフィックスは 1,024 トークン以上必要です。1,024 トークン未満ではキャッシュを作成せず、リクエストは正常に返ります。TTL 別のキャッシュ作成詳細は返されません。
  • 各リクエストでは最大 4 つの有効なブレークポイントが保持されます。自動キャッシュを有効にすると、自動ブレークポイントがそのうち 1 つを使用します。
  • システムは各ブレークポイントを終点として、最大 20 個のコンテンツブロックを前方に検索します。ヒット対象のキャッシュがブレークポイントから 20 個を超えるコンテンツブロック離れている場合、ヒットできません。
  • TTL は 5m または 1h のみ設定できます。

FAQ

Q:キャッシュパラメーターを設定しなくてもキャッシュにヒットしますか?

はい。キャッシュパラメーターを設定しない場合は暗黙的キャッシュが使用されます。システムはリクエスト間の共通プレフィックスを自動的に識別しますが、ヒットは保証されません。確実にヒットさせるには、キャッシュブレークポイントを設定するか、自動キャッシュを有効にしてください。

Q:TTL のみを設定した場合、キャッシュの有効期間が変わらないのはなぜですか?

TTL は明示的キャッシュにのみ適用されます。OpenAI 互換 Chat Completions API で prompt_cache_options.ttl のみを設定した場合、リクエストは暗黙的キャッシュを使用します。手動ブレークポイントも追加するか、prompt_cache_options.mode を implicit に設定してください。

Q:5m リクエストが 1h キャッシュにヒットすると、キャッシュの有効期間は短くなりますか?

いいえ。新しい有効期限は、元の有効期限と今回のリクエストの更新時刻の遅い方になり、キャッシュは 1h ティアを維持します。詳細は更新ルールを参照してください。