Alibaba Cloud Model Studio:コンテキストキャッシュ

使用方法

「"cache_control": {"type": "ephemeral"}」マーカーを `messages` 配列に追加できます。その後、システムは各 cache_control マーカーの位置から最大20個の content ブロックを遡って検索し、キャッシュヒットを試行します。

1 回のリクエストでは、最大 4 個のキャッシュマーカーをサポートします。

• キャッシュミス

  システムは、メッセージ配列の開始と cache_control マーカーの間のコンテンツから、新しいキャッシュブロックを作成します。キャッシュブロックは 5 分間有効です。

  キャッシュ作成はモデル応答後に実行されます。キャッシュ作成リクエストが完了した後で、キャッシュヒットを試行してください。

  キャッシュブロックには、最低でも 1024 トークンを含める必要があります。

• キャッシュヒット

  システムは、最も長い一致するプレフィックスをヒットしたキャッシュブロックとして選択し、その有効期間を 5 分間にリセットします。

以下の例は、この機能の使用方法を示しています。

1. 最初のリクエストを送信：1024 トークンを超えるテキスト A を含むシステムメッセージを送信し、キャッシュマーカーを追加できます。

   [{"role": "system", "content": [{"type": "text", "text": A, "cache_control": {"type": "ephemeral"}}]}] 

   システムは最初のキャッシュブロック（キャッシュブロック A）を作成します。

2. 2 回目のリクエストを送信：以下の構造を持つリクエストを送信できます。

   [
       {"role": "system", "content": A},
       <other messages>
       {"role": "user","content": [{"type": "text", "text": B, "cache_control": {"type": "ephemeral"}}]}
   ]

   • other messages の数が 20 を超えない場合、キャッシュブロック A がヒットし、その有効期間が 5 分間にリセットされます。また、A、other messages、B に基づいて新しいキャッシュブロックも作成されます。

   • other messages の数が 20 を超える場合、キャッシュブロック A はヒットしません。システムは、完全なコンテキスト（A + other messages + B）に基づいて新しいキャッシュブロックを作成します。

対応モデル

はじめに

以下の例では、OpenAI 互換インターフェイスおよび DashScope プロトコルにおけるキャッシュブロックの作成およびヒットの方法を示します。

from openai import OpenAI
import os

client = OpenAI(
    # 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えます。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えます。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# モックコードリポジトリのコンテンツ。キャッシュ可能な最小プロンプト長は 1024 トークンです。
long_text_content = "<Your Code Here>" * 400

# リクエスト送信関数
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # キャッシュブロックを作成するには、messages 配列の先頭から現在の content 位置までのすべてのコンテンツを含むように cache_control マーカーを配置します。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # 各リクエストの質問内容は異なります。
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 明示的キャッシュをサポートするモデルを選択します。
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# 最初のリクエスト
first_completion = get_completion("このコードの内容は何ですか？")
print(f"最初のリクエストのキャッシュ作成トークン数: {first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"最初のリクエストのキャッシュヒットトークン数: {first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# 2 回目のリクエスト。コードの内容は同じですが、質問のみが変更されています。
second_completion = get_completion("このコードをどのように最適化できますか？")
print(f"2 回目のリクエストのキャッシュ作成トークン数: {second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"2 回目のリクエストのキャッシュヒットトークン数: {second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import Generation
# 北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/api/v1 に置き換えます。
dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"

# モックコードリポジトリのコンテンツ。キャッシュ可能な最小プロンプト長は 1024 トークンです。
long_text_content = "<Your Code Here>" * 400

# リクエスト送信関数
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # キャッシュブロックを作成するには、messages 配列の先頭から現在の content 位置までのすべてのコンテンツを含むように cache_control マーカーを配置します。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # 各リクエストの質問内容は異なります。
        {
            "role": "user",
            "content": user_input,
        },
    ]
    response = Generation.call(
        # 環境変数が設定されていない場合は、次の行を Model Studio API キーに置き換えます：api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"), 
        model="qwen3-coder-plus",
        messages=messages,
        result_format="message"
    )
    return response

# 最初のリクエスト
first_completion = get_completion("このコードの内容は何ですか？")
print(f"最初のリクエストのキャッシュ作成トークン数: {first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"最初のリクエストのキャッシュヒットトークン数: {first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# 2 回目のリクエスト。コードの内容は同じですが、質問のみが変更されています。
second_completion = get_completion("このコードをどのように最適化できますか？")
print(f"2 回目のリクエストのキャッシュ作成トークン数: {second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"2 回目のリクエストのキャッシュヒットトークン数: {second_completion.usage.prompt_tokens_details['cached_tokens']}")

// Java SDK の最小バージョンは 2.21.6 です。
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.MessageContentText;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

import java.util.Arrays;
import java.util.Collections;

public class Main {
    private static final String MODEL = "qwen3-coder-plus";
    // モックコードリポジトリのコンテンツ（1024 トークンを超えるために 400 回繰り返します）
    private static final String LONG_TEXT_CONTENT = generateLongText(400);
    private static String generateLongText(int repeatCount) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < repeatCount; i++) {
            sb.append("<Your Code Here>");
        }
        return sb.toString();
    }
    private static GenerationResult getCompletion(String userQuestion)
            throws NoApiKeyException, ApiException, InputRequiredException {
        // 北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/api/v1 に置き換えます。
        Generation gen = new Generation("http", "https://dashscope-intl.aliyuncs.com/api/v1");

        // cache control を含むシステムメッセージを構築
        MessageContentText systemContent = MessageContentText.builder()
                .type("text")
                .text(LONG_TEXT_CONTENT)
                .cacheControl(MessageContentText.CacheControl.builder()
                        .type("ephemeral") // キャッシュタイプを設定
                        .build())
                .build();

        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .contents(Collections.singletonList(systemContent))
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content(userQuestion)
                .build();

        // リクエストパラメーターを構築
        GenerationParam param = GenerationParam.builder()
                .model(MODEL)
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }

    private static void printCacheInfo(GenerationResult result, String requestLabel) {
        System.out.printf("%s キャッシュ作成トークン数: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s キャッシュヒットトークン数: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // 最初のリクエスト
            GenerationResult firstResult = getCompletion("このコードの内容は何ですか？");
            printCacheInfo(firstResult, "最初のリクエスト");
            System.out.println(new String(new char[20]).replace('\0', '='));            // 2 回目のリクエスト
            GenerationResult secondResult = getCompletion("このコードをどのように最適化できますか？");
            printCacheInfo(secondResult, "2 回目のリクエスト");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("API 呼び出しに失敗しました: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

モックコードリポジトリのコンテンツは、cache_control マーカーを追加することで明示的キャッシュを有効化します。このリポジトリに関する後続のリクエストでは、システムがキャッシュブロックを再利用し、再計算を回避できます。これにより、キャッシュ作成前の状態と比較して、応答が高速化し、コストが削減されます。

最初のリクエストのキャッシュ作成トークン数: 1605
最初のリクエストのキャッシュヒットトークン数: 0
====================
2 回目のリクエストのキャッシュ作成トークン数: 0
2 回目のリクエストのキャッシュヒットトークン数: 1605

細かい制御のための複数キャッシュマーカーの使用

複雑なシナリオでは、プロンプトが再利用頻度の異なる複数の部分で構成されることがよくあります。このような場合、複数のキャッシュマーカーを使用することで、細かい制御が可能になります。

たとえば、スマートカスタマーサポートエージェントのプロンプトには、通常以下のような要素が含まれます。

• システムペルソナ：非常に安定しており、ほとんど変更されません。

• 外部知識：半安定です。ナレッジベースから取得されるか、ツール呼び出しによって取得され、連続した会話中は変更されないことがあります。

• 会話履歴：動的に増加します。

• 現在の質問：毎回異なります。

プロンプト全体を単一のユニットとしてキャッシュすると、外部知識の変更などのわずかな変更でもキャッシュミスが発生します。

1 回のリクエストで最大 4 個のキャッシュマーカーを設定し、プロンプトの異なる部分に対して個別のキャッシュブロックを作成できます。これにより、ヒット率が向上し、細かい制御が可能になります。

課金

明示的キャッシュは、入力トークンの課金方法にのみ影響します。ルールは以下のとおりです。

• キャッシュ作成：新しく作成されたキャッシュコンテンツは、標準入力価格の 125 % で課金されます。新しいリクエストのキャッシュコンテンツが既存のキャッシュをプレフィックスとして含む場合、追加部分のみが課金されます（新規キャッシュトークン数 − 既存キャッシュトークン数）。

  たとえば、既存のキャッシュ A（1200 トークン）があり、新しいリクエストで AB（1500 トークン）をキャッシュする必要がある場合、最初の 1200 トークンはキャッシュヒットとして課金され（標準価格の 10 %）、新しい 300 トークンはキャッシュ作成として課金されます（標準価格の 125 %）。

  cache_creation_input_tokens パラメーターで、キャッシュ作成に使用されたトークン数を確認できます。

• キャッシュヒット：標準入力価格の 10 % で課金されます。

  cached_tokens パラメーターで、ヒットしたキャッシュトークン数を確認できます。

• その他のトークン：ヒットしなかったトークンやキャッシュ作成に使用されなかったトークンは、従来の価格で課金されます。

キャッシュ可能なコンテンツ

messages 配列内の以下のメッセージタイプのみが、キャッシュマーカーの追加をサポートします。

• システムメッセージ

• ユーザー メッセージ

  qwen3-vl-plus モデルを使用してキャッシュを作成する場合、cache_control マーカーはマルチモーダルコンテンツまたはテキストの後に配置できます。その位置は、ユーザー メッセージ全体のキャッシュには影響しません。

• アシスタントメッセージ

• ツールメッセージ（ツール実行後の結果）

  リクエストに tools パラメーターが含まれる場合、messages にキャッシュマーカーを追加すると、その中に含まれるツール説明もキャッシュされます。

システムメッセージの場合、content フィールドを配列に変更し、cache_control フィールドを追加できます。

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<指定したプロンプト>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

この構造は、messages 配列内の他のメッセージタイプにも適用されます。

キャッシュ制限

• キャッシュ可能な最小プロンプト長は 1024 トークンです。

• キャッシュは後方プレフィックス一致戦略を使用します。システムは自動的に最後の 20 個のコンテンツブロックをチェックします。cache_control マーカーを含むメッセージから、一致対象のコンテンツまでが 20 個以上のコンテンツブロック離れている場合、キャッシュヒットは発生しません。

• ephemeral のみが type パラメーターでサポートされており、有効期間は 5 分間です。

• 1 回のリクエストでは、最大 4 個のキャッシュマーカーを設定できます。

  キャッシュマーカーの数が 4 個を超える場合、最後の 4 個のキャッシュマーカーのみが有効になります。

使用例

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えます。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# モックコードリポジトリのコンテンツ
long_text_content = "<Your Code Here>" * 400

# リクエスト送信関数
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # プロンプトの先頭からこのコンテンツブロック（モックコードリポジトリのコンテンツ）の末尾までキャッシュを作成します。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 明示的キャッシュをサポートするモデルを選択します。
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# 最初のリクエスト
first_completion = get_completion("このコードの内容は何ですか？")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"最初のリクエストのキャッシュ作成トークン数: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"最初のリクエストのキャッシュヒットトークン数: {hit_cached_tokens}")
print(f"最初のリクエストのキャッシュヒット・キャッシュ作成以外のトークン数: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# 2 回目のリクエスト。コードの内容は同じですが、質問のみが変更されています。
second_completion = get_completion("このコードの最適化ポイントは何ですか？")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"2 回目のリクエストのキャッシュ作成トークン数: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"2 回目のリクエストのキャッシュヒットトークン数: {hit_cached_tokens}")
print(f"2 回目のリクエストのキャッシュヒット・キャッシュ作成以外のトークン数: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

最初のリクエストのキャッシュ作成トークン数: 1605
最初のリクエストのキャッシュヒットトークン数: 0
最初のリクエストのキャッシュヒット・キャッシュ作成以外のトークン数: 13
====================
2 回目のリクエストのキャッシュ作成トークン数: 0
2 回目のリクエストのキャッシュヒットトークン数: 1605
2 回目のリクエストのキャッシュヒット・キャッシュ作成以外のトークン数: 15

from openai import OpenAI
import os
  
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えます。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "あなたは機知に富んだ人物です。" * 400
messages = [{"role": "system", "content": system_prompt}]

def get_completion(messages):
    completion = client.chat.completions.create(
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

while True:
    user_input = input("入力してください: ")
    messages.append({"role": "user", "content": [{"type": "text", "text": user_input, "cache_control": {"type": "ephemeral"}}]})
    completion = get_completion(messages)
    print(f"[AI 応答] {completion.choices[0].message.content}")
    messages.append(completion.choices[0].message)
    created_cache_tokens = completion.usage.prompt_tokens_details.cache_creation_input_tokens
    hit_cached_tokens = completion.usage.prompt_tokens_details.cached_tokens
    uncached_tokens = completion.usage.prompt_tokens - created_cache_tokens - hit_cached_tokens
    print(f"[キャッシュ情報] キャッシュ作成トークン数: {created_cache_tokens}")
    print(f"[キャッシュ情報] キャッシュヒットトークン数: {hit_cached_tokens}")
    print(f"[キャッシュ情報] キャッシュヒット・キャッシュ作成以外のトークン数: {uncached_tokens}")

対応モデル

仕組み

暗黙的キャッシュは、対応モデルに対して自動的に有効になります。

1. 検索：リクエスト受信後、システムは messages 配列内で プレフィックス一致 を使用してキャッシュを検索します。

2. 評価：

   • キャッシュヒット：システムはキャッシュされた結果を使用して推論を実行します。

   • キャッシュミス：システムはリクエストを通常どおり処理し、プロンプトのプレフィックスを将来のリクエストのために保存します。

システムは未使用のキャッシュエントリを定期的にクリアします。キャッシュヒット率は保証されません — コンテキストが同一であっても、キャッシュミスが発生する場合があります。実際のヒット率はシステムが決定します。

ヒット率の向上

暗黙的キャッシュは、リクエストをプレフィックスで一致させます。ヒット率を向上させるには、静的コンテンツを先に、可変コンテンツを後に配置 してください。

• テキストのみのモデル：システムが「ABCD」をキャッシュしている場合、「ABE」のリクエストは「AB」プレフィックスに一致しますが、「BCD」のリクエストはどのキャッシュにも一致しません。

• ビジョン理解モデル：

  • 同一の画像または動画に関する複数の質問を行う場合、ヒット率を向上させるには、テキストより前に画像または動画を配置します。

  • 異なる画像または動画について同一の質問を行う場合、ヒット率を向上させるには、画像または動画より前にテキストを配置します。

課金

暗黙的キャッシュモードを有効にしても、追加料金は発生しません。

キャッシュヒット時には、一致した入力トークンが cached_token として、input_token 単価の 20 % で課金されます。キャッシュにヒットしなかった入力トークンは、標準の input_token 価格で課金されます。出力トークンは標準価格で課金されます。

例：リクエストに 10,000 入力トークンが含まれており、そのうち 5,000 がキャッシュヒットした場合：

• 非ヒットトークン（5,000）：単価の 100 % で課金

• ヒットトークン（5,000）：単価の 20 % で課金

合計入力コスト ＝ キャッシュなしの場合のコストの 60 %：（50 % × 100 %）＋（50 % × 20 %）＝ 60 %。

キャッシュされたトークンの数は、返された結果の cached_tokens 属性から取得できます。

OpenAI 互換-Batch（ファイル入力） メソッドはキャッシュ割引の対象外です。

適用シナリオ

リクエストが同一のプレフィックスを共有する場合、コンテキストキャッシュにより推論速度が向上し、コストが削減され、最初のトークンまでの時間が短縮されます。以下は代表的な適用シナリオです。

1. 長文に基づく質問応答（Q&A）

   小説、教科書、法務文書などの固定された長文に関する複数のリクエストを送信するシナリオに該当します。

   最初のリクエストのメッセージ配列

   messages = [{"role": "system","content": "あなたは言語教師です。生徒の読解力を支援できます。"},
             {"role": "user","content": "<記事の内容> この文章に表されている著者の考えや感情は何ですか？"}]

   後続のリクエストのメッセージ配列

   messages = [{"role": "system","content": "あなたは言語教師です。生徒の読解力を支援できます。"},
             {"role": "user","content": "<記事の内容> この文章の第 3 段落を分析してください。"}]

   質問は異なりますが、いずれも同一の記事に基づいています。同一のシステムプロンプトと記事コンテンツにより、大きな反復プレフィックスが形成され、キャッシュヒット確率が高まります。

2. コード自動補完

   コード自動補完のシナリオでは、大規模言語モデル（LLM）がコンテキスト内の既存コードに基づいてコードを補完します。ユーザーがコードを継続的に記述すると、コードのプレフィックスは変更されません。コンテキストキャッシュは、以前のコードを保存することで、補完速度を向上させます。

3. マルチターン対話

   マルチターン対話を実装するには、各ターンの会話情報を messages 配列に追加します。そのため、各ターンは前のターンと同じプレフィックスを共有し、キャッシュヒット確率が高まります。

   会話の最初のターンのメッセージ配列

   messages=[{"role": "system","content": "あなたは親切なアシスタントです。"},
             {"role": "user","content": "あなたは誰ですか？"}]

   会話の 2 回目のターンのメッセージ配列

   messages=[{"role": "system","content": "あなたは親切なアシスタントです。"},
             {"role": "user","content": "あなたは誰ですか？"},
             {"role": "assistant","content": "私は Alibaba Cloud が開発した Qwen です。"},
             {"role": "user","content": "あなたは何ができますか？"}]

   会話ターン数が増えるにつれて、キャッシュによる推論速度の向上やコスト削減といったメリットがさらに顕著になります。

4. ロールプレイまたは少数ショット学習

   ロールプレイや少数ショット学習のシナリオでは、通常、LLM の出力フォーマットをガイドするために、プロンプトに大量の情報を追加します。これにより、異なるリクエスト間で大きな反復プレフィックスが作成されます。

   たとえば、LLM にマーケティング専門家として振る舞わせる場合、システムプロンプトには大量のテキストが含まれます。以下は、2 つのリクエストのメッセージ例です。

   system_prompt = """あなたは経験豊富なマーケティング専門家です。以下の形式で、さまざまな製品に対する詳細なマーケティング提案を提供してください：
   
   1. ターゲットオーディエンス：xxx
   
   2. 主な販売ポイント：xxx
   
   3. マーケティングチャネル：xxx
   ...
   12. 長期的な発展戦略：xxx
   
   提案は、製品の特徴に具体性・実行可能性・関連性を備えたものにしてください。"""
   
   # 最初のリクエストのユーザー メッセージ（スマートウォッチについて）
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "新しく発売されたスマートウォッチのマーケティング提案を提供してください。"}
   ]
   
   # 2 回目のリクエストのユーザー メッセージ（ノートパソコンについて）。システムプロンプトが同一であるため、キャッシュヒットの確率は非常に高くなります。
   messages_2=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "新しく発売されたノートパソコンのマーケティング提案を提供してください。"}
   ]

   コンテキストキャッシュを使用することで、ユーザーがスマートウォッチからノートパソコンへと質問の製品タイプを頻繁に変更したとしても、キャッシュヒット後に素早く応答できます。

5. 動画理解

   動画理解のシナリオでは、同一の動画について複数の質問を行う場合、video を text より前に配置することで、キャッシュヒット確率が高まります。異なる動画について同一の質問を行う場合、text を video より前に配置することで、キャッシュヒット確率が高まります。以下は、同一の動画に関する 2 つのリクエストの例です。

   # 最初のリクエストのユーザー メッセージ（動画の内容について）
   messages1 = [
       {"role":"system","content":[{"text": "あなたは親切なアシスタントです。"}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "この動画の内容は何ですか？"}
           ]
       }
   ]
   
   # 2 回目のリクエストのユーザー メッセージ（動画のタイムスタンプについて）。同一の動画についての質問であるため、video を text より前に配置することで、キャッシュヒットの確率が非常に高くなります。
   messages2 = [
       {"role":"system","content":[{"text": "あなたは親切なアシスタントです。"}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "動画内の出来事を時系列で説明してください。開始時刻（start_time）、終了時刻（end_time）、出来事（event）を JSON 形式で出力してください。```json``` コードセグメントは含めないでください。"}
           ]
       }
   ]

Q：暗黙的キャッシュを無効化する方法はありますか？

暗黙的キャッシュは無効化できません。対応モデルに対しては常に有効であり、出力品質への影響なく、コスト削減および応答速度の向上というメリットがあります。

Q：明示的キャッシュを作成しましたが、なぜヒットしなかったのですか？

考えられる原因は以下のとおりです。

• 5 分以内にヒットしなかったため、キャッシュが期限切れになりました。

• 最後の content ブロックと既存のキャッシュとの間に 20 個以上の content ブロックがある場合、キャッシュはヒットしません。その代わりに新しいキャッシュブロックを作成してください。

Q：明示的キャッシュのヒットは、その有効期間をリセットしますか？

はい。各ヒットごとに、キャッシュブロックの有効期間が 5 分間にリセットされます。

Q：明示的キャッシュは、異なるアカウント間で共有されますか？

いいえ。暗黙的キャッシュおよび明示的キャッシュのデータは、アカウントレベルで分離されており、アカウント間で共有されることはありません。

Q：同一アカウント内の異なるモデル間で、明示的キャッシュは共有されますか？

いいえ。キャッシュデータはモデル間で分離されており、共有されません。

Q：usage の input_tokens が cache_creation_input_tokens と cached_tokens の合計と等しくないのはなぜですか？

モデル出力品質を確保するため、バックエンドサービスはユーザー提供のプロンプトの後に、通常 10 未満の少数のトークンを追加します。cache_control マーカーの後に追加されるこれらのトークンは、キャッシュ作成およびキャッシュヒットの対象とはならず、合計 input_tokens にのみ含まれます。