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

大規模モデルの推論リクエストには、マルチターン対話や同じ書籍に関する一連の質問など、重複する入力が含まれることがよくあります。コンテキストキャッシュは、これらのリクエストの共通プレフィックスをキャッシュすることで、冗長な計算を削減します。これにより、応答品質に影響を与えることなく、応答速度の向上と利用コストの削減を実現します。

さまざまなシナリオをサポートするために、コンテキストキャッシュには 2 つのモードが用意されています。利便性、確実性、コストの要件に基づいてモードを選択してください：

• 明示的キャッシュ：手動で有効にするモードです。特定のコンテンツに対してキャッシュを作成し、5 分間の有効期間内に確定的なヒットを保証します。キャッシュの作成に使用されるトークンは、標準入力トークン価格の 125% で課金されますが、その後のキャッシュヒットは、その価格のわずか 10% で課金されます。
• 暗黙的キャッシュ：この自動モードは追加の構成を必要とせず、無効にすることもできません。利便性を優先するシナリオに最適です。システムはリクエストの共通プレフィックスを自動的に識別してキャッシュしますが、ヒット確率は保証されません。キャッシュから提供された入力部分は、標準入力トークン価格の 20% で課金されます。

明示的キャッシュ

暗黙的キャッシュとは異なり、明示的キャッシュは明示的な作成が必要でオーバーヘッドが発生しますが、より高いキャッシュヒット率と低いアクセスレイテンシを提供します。

仕組み

"cache_control": {"type": "ephemeral"} マーカーを messages 配列に追加します。その後、システムは各 cache_control マーカーから後方に検索し、最大 20 個の先行する content ブロックを調べてキャッシュヒットを探します。

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

• キャッシュミス

  キャッシュミスが発生した場合、システムは messages 配列の先頭と cache_control マーカーの間のコンテンツから新しいキャッシュブロックを作成します。新しいキャッシュブロックの有効期間は 5 分です。

  システムは、モデルが応答を生成した後にキャッシュを作成します。そのキャッシュにヒットさせるには、作成リクエストが完了するまで待ってください。

  キャッシュブロックには、少なくとも 1,024 トークンが含まれます。

• キャッシュヒット

  キャッシュヒットが発生した場合、システムは最長一致プレフィックスを選択し、対応するキャッシュブロックの有効期間を 5 分にリセットします。

次の例は、この仕組みを示しています：

1. 最初のリクエストを送信：テキスト A (1,024 トークン以上) を含むシステムメッセージを送信し、キャッシュマーカーを追加します：

[{"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"}}]}
]

• 「その他のメッセージ」が 20 以下の場合、リクエストはキャッシュブロック A にヒットし、その有効期間が 5 分にリセットされます。システムはまた、A、その他のメッセージ、および B に基づいて新しいキャッシュブロックを作成します。
• 「その他のメッセージ」が 20 を超える場合、リクエストはキャッシュブロック A をミスします。システムは引き続き、完全なコンテキスト (A、その他のメッセージ、および B) に基づいて新しいキャッシュブロックを作成します。

サポート対象モデル

クイックスタート

以下の例は、OpenAI 互換、DashScope、および Anthropic 互換プロトコルにおけるキャッシュブロックの作成とキャッシュヒットのメカニズムを示しています。

from openai import OpenAI
import os

client = OpenAI(
    # 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えます
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 中国 (北京) のモデルを使用する場合は、base_url を https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 に置き換えます
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

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

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

# 最初のリクエスト
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"First request cached tokens: {first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# 2 番目のリクエスト。コードの内容は同じですが、質問が異なります。
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Second request cached tokens: {second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import MultiModalConversation
# 次の URL はシンガポールリージョン用です。{WorkspaceId} をご利用のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

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

# リクエストを行う関数
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # ここに cache_control マーカーを配置します。これにより、messages 配列の先頭からこの時点までのすべてのコンテンツを含むキャッシュブロックが作成されます。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # ユーザーの質問はリクエストごとに異なります。
        {
            "role": "user",
            "content": [{"text": user_input}],
        },
    ]
    response = MultiModalConversation.call(
        # 環境変数が設定されていない場合は、Model Studio API キーを直接使用します： api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        model="qwen3.8-max",
        messages=messages,
    )
    return response

# 最初のリクエスト
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"First request cached tokens: {first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# 2 番目のリクエスト。コードの内容は同じですが、質問が異なります。
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"Second request cached tokens: {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";
    // モックコードリポジトリのコンテンツ (1,024 トークンを超えるように 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 {
        // 次の URL はシンガポールリージョン用です。{WorkspaceId} をご利用のワークスペース ID に置き換えてください。URL はリージョンによって異なります。
        Generation gen = new Generation("http", "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1");

        // キャッシュコントロール付きのシステムメッセージを構築します。
        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 cache creation tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s cached tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // 最初のリクエスト
            GenerationResult firstResult = getCompletion("What is the content of this code?");
            printCacheInfo(firstResult, "First request");
            System.out.println(new String(new char[20]).replace('\0', '='));            // 2 番目のリクエスト
            GenerationResult secondResult = getCompletion("How can this code be optimized?");
            printCacheInfo(secondResult, "Second request");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("API call failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import anthropic
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
client = anthropic.Anthropic(
    # 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えます
    api_key=api_key,
    # 中国 (北京) のモデルを使用する場合は、base_url を https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic に置き換えます
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
    default_headers={"Authorization": f"Bearer {api_key}"},
)

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

# リクエストを行う関数
def get_completion(user_input):
    response = client.messages.create(
        # 明示的キャッシュをサポートするモデルを選択します。
        model="qwen3.8-max",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": long_text_content,
                # ここに cache_control マーカーを配置して、システムテキストコンテンツからキャッシュブロックを作成します。このマーカーは `messages` にも配置できます。
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[
            # ユーザーの質問はリクエストごとに異なります。
            {"role": "user", "content": user_input},
        ],
    )
    return response

# 最初のリクエスト
first_completion = get_completion("What is the content of this code?")
print(f"First request cache creation tokens: {first_completion.usage.cache_creation_input_tokens}")
print(f"First request cached tokens: {first_completion.usage.cache_read_input_tokens}")
print("=" * 20)
# 2 番目のリクエスト。コードの内容は同じですが、質問が異なります。
second_completion = get_completion("How can this code be optimized?")
print(f"Second request cache creation tokens: {second_completion.usage.cache_creation_input_tokens}")
print(f"Second request cached tokens: {second_completion.usage.cache_read_input_tokens}")

cache_control マーカーを追加すると、モックコードリポジトリのコンテンツに対して明示的キャッシュが有効になります。このコンテンツを照会する後続のリクエストでは、システムはキャッシュブロックを再利用し、再計算を排除します。これにより、キャッシュにヒットしたリクエストは、最初のキャッシュ作成リクエストよりも高速かつ安価になります。

First request cache creation tokens: 1605
First request cached tokens: 0
====================
Second request cache creation tokens: 0
Second request cached tokens: 1605

複数のキャッシュマーカーによる詳細な制御

複雑なシナリオでは、プロンプトはしばしば再利用頻度が異なる複数の部分で構成されます。複数のキャッシュマーカーを使用して、詳細な制御を実現できます。

例えば、インテリジェントなカスタマーサービスエージェントのプロンプトには、通常、以下が含まれます：

• システムペルソナ：非常に安定しており、めったに変わりません。
• 外部ナレッジ：これはナレッジベースから、またはツールクエリを通じて取得され、1 回の対話中に変更されない場合があります。
• 対話履歴：動的に増加します。
• 現在の質問：リクエストごとに異なります。

プロンプト全体を単一のユニットとしてキャッシュすると、外部ナレッジの更新などのわずかな変更でもキャッシュミスが発生する可能性があります。

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

課金

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

• キャッシュ作成：新しいキャッシュの作成に使用されるコンテンツは、標準入力トークン価格の 125% で課金されます。新しいキャッシュのコンテンツに既存のキャッシュがプレフィックスとして含まれている場合、増分部分のみがキャッシュ作成として課金されます (つまり、新しいキャッシュトークンの数から既存のキャッシュトークンの数を引いたもの)。

  例えば、既存の 1,200 トークンのキャッシュ (キャッシュ A) があり、新しいリクエストで 1,500 トークンのコンテンツ (コンテンツ AB) をキャッシュする場合、最初の 1,200 トークンはキャッシュヒットとして標準価格の 10% で課金されます。新しい 300 トークンは、キャッシュ作成として標準価格の 125% で課金されます。

  cache_creation_input_tokens パラメーターは、キャッシュ作成に使用されるトークンの数を指定します。

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

  cached_tokens パラメーターは、キャッシュされたトークンの数を指定します。

• その他のトークン：キャッシュヒットでもキャッシュ作成に使用されたものでもないトークンは、標準入力トークン価格で課金されます。

• 例外：qwen3.8-max、qwen3.8-flash、および qwen3.8-2.4t-a95b の明示的キャッシュヒット価格は、標準入力トークン価格の 10% ではありません。具体的な価格については、Model Studio コンソールをご参照ください。(キャッシュ作成価格は標準価格の 125% のままです。)

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

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

• システムメッセージ

  注記関数呼び出しの場合、リクエストに tools パラメーターが含まれていると、ツール定義はキャッシュ計算のためにシステムメッセージに含まれます。ツール定義は独立してキャッシュすることはできません。キャッシュマーカーはメッセージのコンテンツにのみ追加できるため、ツール定義に追加されたキャッシュマーカーは無視されます。

• ユーザーメッセージ

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

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

• ツールメッセージ (ツール実行の結果)

例えば、システムメッセージの場合、content フィールドを配列に変更し、cache_control フィールドを追加する必要があります：

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<your specified prompt>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

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

キャッシュの制限事項

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

• キャッシュは後方プレフィックスマッチング戦略を使用します。一致するコンテンツと cache_control マーカーを持つメッセージが 20 個以上の content ブロックで区切られている場合、キャッシュミスが発生します。

• type は ephemeral にのみ設定でき、これにより 5 分間の有効期間を持つキャッシュが作成されます。

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

  4 つ以上のキャッシュマーカーが提供された場合、最後の 4 つのみが有効になります。

関数呼び出しのキャッシュ最適化

ツール定義は、キャッシュのために JSON 文字列にシリアル化されます。キャッシュの無効化を防ぐため、この定義はすべてのリクエストで同一でなければなりません。以下に注意してください：

• 一貫したツール順序：tools 配列内のツールの順序は、すべてのリクエストで一貫している必要があります。
• 一貫したフィールド順序：同じツール内の JSON フィールドの順序は、すべてのリクエストで一貫している必要があります。
• 一貫したフィールド構造：フィールドが空またはオプションであっても、フィールドを省略したり追加したりしないでください。

並列ツール呼び出しのためのメッセージ構造の最適化

並列ツール呼び出しを使用すると、モデルは 1 回の応答で複数の tool_calls を返します。各ツール結果を個別の tool メッセージとして送信すると、messages 配列内の content ブロックの数が急速に増加します。cache_control マーカーと以前のコンテンツの間に 20 を超える content ブロックがあると、後方ルックバックウィンドウがそれらの以前のブロックに到達できず、キャッシュミスが発生します。

これを解決するには、次のリクエストを送信する前に、連続する同じロールのツールメッセージを複数の content ブロックを持つ単一の tool メッセージにマージします。これにより、総 content ブロック数が減り、キャッシュしたいコンテンツが 20 ブロックのルックバックウィンドウ内に収まります。

最適化前 (個別のツールメッセージ — キャッシュヒット率が低い)：

# モデルが並列 tool_calls を返した後、各結果を個別のメッセージとして送信します
messages.append(assistant_message)  # 並列 tool_calls を含むアシスタントメッセージ
# 各ツール結果は独自のメッセージです — content ブロック数を N 個増やします
messages.append({"role": "tool", "tool_call_id": "call_1", "content": "result_1"})
messages.append({"role": "tool", "tool_call_id": "call_2", "content": "result_2"})

最適化後 (マージされたツールメッセージ — キャッシュヒット率が高い)：

# モデルが並列 tool_calls を返した後、すべての結果を 1 つのメッセージにマージします
messages.append(assistant_message)  # 並列 tool_calls を含むアシスタントメッセージ
# すべてのツール結果を複数の content ブロックを持つ単一のメッセージにマージします
messages.append({
    "role": "tool",
    "tool_call_id": "call_1",
    "content": [
        {"type": "text", "text": "result_1"},
        {"type": "text", "text": "result_2", "tool_call_id": "call_2"},
    ],
})

キャッシュヒット率をさらに向上させるには、cache_control マーカーを messages 配列の安定した位置 (例えば、システムメッセージや他の頻繁に変更されないコンテンツ) に配置します。1 つのリクエストで最大 4 つのキャッシュマーカーをサポートします。

使用例

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # これはシンガポールリージョンの base_url です。呼び出しを行う際は、{WorkspaceId} を実際の WorkspaceId に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.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 マーカーを配置して、プロンプトの先頭からこの content オブジェクトの末尾 (モックコードリポジトリのコンテンツ) までをキャッシュします。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 明示的キャッシュをサポートするモデルを選択します
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

# 最初のリクエスト
first_completion = get_completion("What is the content of this code?")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"First request - Cache creation tokens: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"First request - Cache hit tokens: {hit_cached_tokens}")
print(f"First request - Uncached tokens: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# 同じコードコンテンツで質問が異なる 2 番目のリクエスト
second_completion = get_completion("What are some possible optimizations for this code?")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Second request - Cache creation tokens: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"Second request - Cache hit tokens: {hit_cached_tokens}")
print(f"Second request - Uncached tokens: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

First request - Cache creation tokens: 1605
First request - Cache hit tokens: 0
First request - Uncached tokens: 13
====================
Second request - Cache creation tokens: 0
Second request - Cache hit tokens: 1605
Second request - Uncached tokens: 15

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# モックコードリポジトリのコンテンツ。明示的キャッシュの最小しきい値である 1,024 トークンを超えるようにします。
long_text_content = "<Your Code Here>" * 400

# ツール定義：すべてのリクエストで同一であることを確認します (ツールの順序、フィールドの順序、フィールドの構造)。
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "指定された都市の現在の天気情報を取得します。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "都市名。例：北京、上海、ニューヨーク。"
                    },
                    "unit": {
                        "type": "string",
                        "description": "温度の単位。「celsius」または「fahrenheit」。デフォルトは「celsius」。",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "指定されたタイムゾーンの現在の日時を取得します。",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "IANA タイムゾーン名。例：「Asia/Shanghai」または「America/New_York」。デフォルトは「Asia/Shanghai」。"
                    }
                },
                "required": [],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "リアルタイムの為替レートに基づいて通貨額を換算します。",
            "parameters": {
                "type": "object",
                "properties": {
                    "from_currency": {
                        "type": "string",
                        "description": "換算元通貨の ISO 4217 コード。例：CNY、USD、EUR。"
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "換算先通貨の ISO 4217 コード。"
                    },
                    "amount": {
                        "type": "number",
                        "description": "換算する金額。"
                    }
                },
                "required": ["from_currency", "to_currency", "amount"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
]

def get_completion(user_input, messages=None):
    if messages is None:
        messages = [
            {
                "role": "system",
                "content": [
                    {
                        "type": "text",
                        "text": long_text_content,
                        # ここに cache_control マーカーを配置します。これにより、messages 配列の先頭から現在の content オブジェクトまでのすべてのコンテンツを含むキャッシュブロックが作成されます。
                        # cache_control マーカーはメッセージの 'content' に配置する必要があり、'tools' には配置できません。
                        "cache_control": {"type": "ephemeral"},
                    }
                ],
            }
        ]

    messages.append({"role": "user", "content": user_input})

    completion = client.chat.completions.create(
        # 明示的キャッシュをサポートするモデルを選択します
        model="qwen3.7-plus",
        messages=messages,
        tools=tools,
        # 思考モードを無効にします
        extra_body={"enable_thinking": False},
    )
    return completion

# 最初のリクエスト：キャッシュを作成
print("=== First request (Create cache) ===")
first_completion = get_completion("What's the weather like in Beijing now?")
usage = first_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"Cache creation tokens: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit tokens: {usage.prompt_tokens_details.cached_tokens}")
print(f"Model selected tool(s): {[t.function.name for t in first_completion.choices[0].message.tool_calls or []]}")
print()

# 2 番目のリクエスト：同じシステムメッセージで質問が異なるため、キャッシュにヒットします
print("=== Second request (Cache hit) ===")
messages = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": long_text_content,
                "cache_control": {"type": "ephemeral"},
            }
        ],
    }
]
second_completion = get_completion("What's the weather like in Shanghai now?", messages=messages)
usage = second_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"Cache creation tokens: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit tokens: {usage.prompt_tokens_details.cached_tokens}")
print(f"Model selected tool(s): {[t.function.name for t in second_completion.choices[0].message.tool_calls or []]}")

=== First request (Create cache) ===
 Prompt Tokens: 2174
 Cache creation tokens: 2156
 Cache hit tokens: 0
 Model selected tool(s): ['get_weather']

 === Second request (Cache hit) ===
 Prompt Tokens: 2174
 Cache creation tokens: 0
 Cache hit tokens: 2156
 Model selected tool(s): ['get_weather']

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # これはシンガポールリージョンの base_url です。呼び出しを行う際は、{WorkspaceId} を実際の WorkspaceId に置き換えてください。URL はリージョンによって異なります。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "You are a witty person." * 400
messages = [{"role": "system", "content": system_prompt}]

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

while True:
    user_input = input("User: ")
    messages.append({"role": "user", "content": [{"type": "text", "text": user_input, "cache_control": {"type": "ephemeral"}}]})
    completion = get_completion(messages)
    print(f"[AI Response] {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"[Cache Info] Cache creation tokens: {created_cache_tokens}")
    print(f"[Cache Info] Cache hit tokens: {hit_cached_tokens}")
    print(f"[Cache Info] Uncached tokens: {uncached_tokens}")

暗黙的キャッシュ

サポート対象モデル

仕組み

暗黙的キャッシュ機能は、サポートされているモデルにリクエストが送信されると自動的に有効になります。システムの動作は次のとおりです：

1. 検索：リクエストを受信した後、システムはプレフィックスマッチングを使用して、リクエストの messages 配列のコンテンツの共通プレフィックスをキャッシュで確認します。

2. 決定：

   • キャッシュヒットが発生した場合、システムは残りの推論にキャッシュされた結果を使用します。
   • キャッシュミスが発生した場合、システムはリクエストを通常どおり処理し、将来のリクエストのためにプロンプトのプレフィックスをキャッシュに保存します。

システムは、長期間使用されていないキャッシュデータを定期的にクリアします。コンテキストキャッシュのヒット確率は 100% ではありません。リクエストのコンテキストが同一であっても、キャッシュミスが発生する可能性があります。システムが特定のヒット確率を決定します。

キャッシュヒット確率の向上

暗黙的キャッシュヒットは、異なるリクエストのプレフィックスに重複するコンテンツがある場合に発生します。ヒット確率を高めるには、重複するコンテンツをプロンプトの先頭に、一意のコンテンツを末尾に配置します。

• テキストモデル：例えば、システムが「ABCD」をキャッシュしたとします。「ABE」のリクエストは「AB」の部分にヒットする可能性がありますが、「BCD」のリクエストはヒットしません。

• 視覚理解モデル：
  • 同じ画像または動画について複数の質問をするには、画像または動画をテキストの前に配置します。
  • 異なる画像または動画について同じ質問をするには、テキストを画像または動画の前に配置します。

課金

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

リクエストがキャッシュにヒットすると、キャッシュヒットからの入力トークンは cached_token として課金されます。これらのトークンの割引率は、モデルによって異なります。キャッシュにヒットしなかった入力トークンは、標準の input_token として課金されます。出力トークンは元の価格で課金されます。

• deepseek-v4-pro、qwen3.8-max、qwen3.8-flash、および qwen3.8-2.4t-a95b 以外のモデルの場合：cached_token の単価は、input_token 単価の 20% です。

• deepseek-v4-pro：cached_token の単価は、input_token 単価の 20% ではありません。具体的な価格については、Model Studio コンソールをご参照ください。

• qwen3.8-max、qwen3.8-flash、および qwen3.8-2.4t-a95b：cached_token の単価は、input_token 単価の 20% ではありません。具体的な価格については、Model Studio コンソールをご参照ください。

• GLM (Alibaba Cloud Model Studio にデプロイ)：glm-5.2 および glm-5.2-fast-preview は 25%、その他のすべての GLM シリーズモデルは 20% です。

例：リクエストに 10,000 の入力トークンが含まれ、そのうち 5,000 がキャッシュヒットしたとします。コストは次のように計算されます：

• 非キャッシュヒットトークン (5,000)：単価の 100% で課金されます。
• キャッシュヒットトークン (5,000)：単価の 20% で課金されます。

総入力コストは、非キャッシュモードのコストの 60% です：(50% × 100%) + (50% × 20%) = 60%。

キャッシュヒットしたトークンの数は、応答の cached_tokens 属性から取得できます。

OpenAI 互換 - バッチ (ファイル入力) メソッドを使用して行われた呼び出しは、キャッシュ割引の対象外です。

キャッシュヒットの例

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "I am a large-scale language model developed by Alibaba Cloud. My name is Qwen."
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 3019,
        "completion_tokens": 104,
        "total_tokens": 3123,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        }
    },
    "created": 1735120033,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

{
    "status_code": 200,
    "request_id": "f3acaa33-e248-97bb-96d5-cbeed34699e1",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "I am a large language model from Alibaba Cloud. My name is Qwen. I can generate various types of text, such as articles, stories, and poems, and can adapt them based on different scenarios and requirements. Additionally, I can answer various questions and provide help and solutions. If you have any questions or need assistance, feel free to ask, and I will do my best to provide support. Please note that repeating the same content may not yield a more detailed response. We recommend providing more specific information or varying your questions so I can better understand your needs."
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 3019,
        "output_tokens": 101,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        },
        "total_tokens": 3120
    }
}

{
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "This content is repeated placeholder text."
        }
    ],
    "model": "qwen3.7-max",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 82,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 1536,
        "output_tokens": 14
    }
}

{
  "id": "chatcmpl-3f3bf7d0-b168-9637-a245-dd0f946c700f",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "This image shows a heartwarming scene of a woman and a dog interacting on a beach. The woman, wearing a plaid shirt, is sitting on the sand and smiling as she interacts with the dog. The dog is a large, light-colored breed wearing a colorful collar, with its front paw raised as if to shake hands or give a high-five to the woman. The background is a vast ocean and sky, with sunlight shining from the right side of the frame, adding a warm and serene atmosphere to the entire scene.",
        "refusal": null,
        "role": "assistant",
        "audio": null,
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1744956927,
  "model": "qwen-vl-max",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 93,
    "prompt_tokens": 1316,
    "total_tokens": 1409,
    "completion_tokens_details": null,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 1152
    }
  }
}

{
  "status_code": 200,
  "request_id": "06a8f3bb-d871-9db4-857d-2c6eeac819bc",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "This image shows a heartwarming scene of a woman and a dog interacting on a beach. The woman, wearing a plaid shirt, is sitting on the sand and smiling as she interacts with the dog. The dog is a large breed wearing a colorful collar, with its front paw raised as if to shake hands or give a high-five to the woman. The background is a vast ocean and sky, with sunlight shining from the right side of the frame, adding a warm and serene atmosphere to the entire scene."
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 1292,
    "output_tokens": 87,
    "input_tokens_details": {
      "text_tokens": 43,
      "image_tokens": 1249
    },
    "total_tokens": 1379,
    "output_tokens_details": {
      "text_tokens": 87
    },
    "image_tokens": 1249,
    "cached_tokens": 1152
  }
}

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "このイメージは、ビーチで女性と犬が触れ合っている、心温まる光景です。"
    }
  ],
  "model": "qwen-vl-max",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 369,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 896,
    "output_tokens": 28
  }
}

ユースケース

リクエストが共通のプレフィックスを共有している場合、コンテキストキャッシュは推論速度を大幅に向上させ、推論コストを削減し、最初のパケットのレイテンシを短縮できます。この機能は、特に以下のユースケースで役立ちます：

1. 長文テキストの質疑応答

   小説、教科書、法的文書など、同じ長文テキストについて複数のリクエストを送信する場合にこのパターンを使用します。

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

messages = [{"role": "system","content": "You are a language teacher who can help students with reading comprehension."},
          {"role": "user","content": "

messages = [{"role": "system","content": "You are a language arts teacher. You can help students with reading comprehension."},
          {"role": "user","content": "<Article content> Please analyze the third paragraph of this text."}]

質問は異なりますが、すべて同じ記事に基づいています。同じシステムプロンプトと記事の内容が大量の反復的なプレフィックス情報を構成し、キャッシュヒットの確率が高くなります。 2. コード自動補完

コード自動補完シナリオでは、モデルは周囲のコードをコンテキストとして使用して後続のコードを生成します。記述するにつれて、コードファイルの先頭は同じままです。コンテキストキャッシュはこのプレフィックスを保存して、コード補完を高速化できます。 3. マルチターン対話

マルチターン対話の場合、各ターンを messages 配列に追加します。これにより、各新しいリクエストが前のターンと共通のプレフィックスを共有し、キャッシュヒットの可能性が高まります。

messages=[{"role": "system","content": "You are a helpful assistant."},
          {"role": "user","content": "Who are you?"}]

messages=[{"role": "system","content": "You are a helpful assistant."},
          {"role": "user","content": "Who are you?"},
          {"role": "assistant","content": "I am Qwen, developed by Alibaba Cloud."},
          {"role": "user","content": "What can you do?"}]

対話が長くなるにつれて、推論速度とコストに対するキャッシュの利点がより顕著になります。 4. ロールプレイングまたはフューショット学習

ロールプレイングまたはフューショット学習シナリオでは、モデルの出力形式をガイドするために、プロンプトに広範な指示を含めることがよくあります。これにより、複数のリクエストにわたって大きな共有プレフィックスが作成されます。

例えば、モデルにマーケティングの専門家として行動するよう指示する場合、システムプロンプトには広範なテキストが含まれます。以下は 2 つのリクエスト例です：

system_prompt = """You are an experienced marketing expert. Provide detailed marketing suggestions for different products in the following format:

1. Target audience: xxx

2. Main selling points: xxx

3. Marketing channels: xxx
...
12. Long-term development strategy: xxx

Ensure your suggestions are specific, actionable, and highly relevant to the product features."""

# 最初のリクエストのユーザーメッセージはスマートウォッチについて尋ねます。
messages_1=[
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Provide marketing suggestions for a newly launched smartwatch."}
]

# 2 番目のリクエストのユーザーメッセージはラップトップについて尋ねます。system_prompt が同じであるため、キャッシュヒットの可能性が非常に高いです。
messages_2=[
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Provide marketing suggestions for a newly launched laptop."}
]

コンテキストキャッシュを使用すると、リクエストの製品を頻繁に変更しても (例えば、スマートウォッチからラップトップへ)、長いシステムプロンプトがキャッシュされるため、システムはより速く応答できます。 5. 動画理解

動画理解シナリオでは、同じ動画について複数の質問をする場合、video を text の前に配置するとキャッシュヒットの確率が高まります。異なる動画について同じ質問をする場合、text を video の前に配置するとキャッシュヒットの確率が高まります。次の例は、同じ動画に対する 2 つのリクエストを示しています：

# 最初のリクエストのユーザーメッセージは、この動画の内容について尋ねます。
messages1 = [
    {"role":"system","content":[{"text": "You are a helpful assistant."}]},
    {"role": "user",
        "content": [
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
            {"text": "What is the content of this video?"}
        ]
    }
]

# 同じ動画に関する 2 番目のリクエストでは、動画をテキストの前に配置するとキャッシュヒットの可能性が高まります。
messages2 = [
    {"role":"system","content":[{"text": "You are a helpful assistant."}]},
    {"role": "user",
        "content": [
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
            {"text": "Describe the series of events in the video. Output the start time (start_time), end time (end_time), and event (event) in JSON format. Do not include the ```json``` code block."}
        ]
    }
]

よくある質問

Q：コンテキストキャッシュはどのくらいの期間保持されますか (有効期間)？

A：コンテキストキャッシュの有効期間は、キャッシュの種類によって異なります：

• 明示的キャッシュ：有効期間は 5 分で、キャッシュヒットごとにさらに 5 分にリセットされます。キャッシュブロックが 5 分以内にヒットしない場合、システムは自動的にクリアします。
• 暗黙的キャッシュ：システムによって自動的に管理され、固定の有効期間はありません。システムは、長期間使用されていないキャッシュデータを定期的にクリアします。

Q：暗黙的キャッシュを無効にするにはどうすればよいですか？

A：無効にすることはできません。暗黙的キャッシュは、応答品質に影響を与えないため、すべての適用可能なモデルリクエストで有効になっています。キャッシュヒットが発生すると、コストが削減され、応答速度が向上します。

Q：明示的キャッシュがミスしたのはなぜですか？

A：キャッシュミスは、以下の理由で発生する可能性があります：

• システムは、5 分の有効期間内にヒットしない場合、キャッシュブロックをクリアします。
• 最後の content と既存のキャッシュブロックの間隔が 20 content ブロックを超える場合、キャッシュヒットは発生しません。新しいキャッシュブロックを作成することをお勧めします。

Q：キャッシュヒットで有効期間はリセットされますか？

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

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

A：いいえ。暗黙的キャッシュと明示的キャッシュの両方のデータは、アカウントレベルで分離されています。

Q：明示的キャッシュはモデル間で共有されますか？

A：いいえ。キャッシュデータはモデル間で分離されています。

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

A：モデルの出力品質を確保するため、バックエンドサービスはプロンプトに少数のトークン (通常は 10 以下) を追加します。これらのトークンは cache_control マーカーの後に配置されるため、キャッシュの作成や読み取りにはカウントされませんが、合計の input_tokens には含まれます。