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

仕組み

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

単一のリクエストでは最大 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"}}]}
   ]

   • 「Other messages」が 20 個以下の場合、リクエストはキャッシュブロック A にヒットし、その有効期間が 5 分にリセットされます。また、システムは A、他のメッセージ、B を基に新しいキャッシュブロックを作成します。

   • 「Other messages」が 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.7-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 Generation
# 次の 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": user_input,
        },
    ]
    response = Generation.call(
        # 環境変数が設定されていない場合は、Model Studio API キーを直接使用してください: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"), 
        model="qwen3.7-max",
        messages=messages,
        result_format="message"
    )
    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.7-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

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

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

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

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

• 外部知識: ナレッジベースまたはツールクエリから取得され、単一の会話中には変更されない可能性があります。

• 会話履歴: 動的に成長します。

• 現在の質問: 各リクエストで異なります。

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

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

課金

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

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

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

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

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

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

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

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

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 個を超えるコンテンツブロックが存在する場合、キャッシュミスが発生します。

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

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

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

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

ツール定義はキャッシュのために JSON 文字列にシリアル化されます。キャッシュの無効化を防ぐために、この定義はすべてのリクエストで同一である必要があります。次の点に注意してください。

• ツール順序の一貫性: tools 配列内のツールの順序は、すべてのリクエストで一貫している必要があります。

• フィールド順序の一貫性: 同じツール内の JSON フィールドの順序は、すべてのリクエストで一貫している必要があります。

• フィールド構造の一貫性: 空であってもオプションであっても、フィールドを省略または追加しないでください。

使用例

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 マーカーを配置して、プロンプトの先頭からこのコンテンツオブジェクトの末尾 (モックコードリポジトリコンテンツ) までのキャッシュを作成します。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 明示的キャッシュをサポートするモデルを選択します。
        model="qwen3.7-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": "Get the current weather information for a specified city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The city name, e.g., Beijing, Shanghai, or New York."
                    },
                    "unit": {
                        "type": "string",
                        "description": "The temperature unit, 'celsius' or 'fahrenheit'. Defaults to 'celsius'.",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Get the current date and time for a specified time zone.",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "IANA time zone name, e.g., 'Asia/Shanghai' or 'America/New_York'. Defaults to 'Asia/Shanghai'."
                    }
                },
                "required": [],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Convert currency amounts based on real-time exchange rates.",
            "parameters": {
                "type": "object",
                "properties": {
                    "from_currency": {
                        "type": "string",
                        "description": "The ISO 4217 code of the source currency, e.g., CNY, USD, or EUR."
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "The ISO 4217 code of the target currency."
                    },
                    "amount": {
                        "type": "number",
                        "description": "The amount to be converted."
                    }
                },
                "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 配列の先頭から現在のコンテンツオブジェクトまでのすべてのコンテンツを含むキャッシュブロックが作成されます。
                        # cache_control マーカーは 'tools' ではなく、メッセージの 'content' に配置する必要があります。
                        "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.7-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 以外のモデルの場合: cached_token の単位価格は input_token 単位価格の 20% です。

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

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

• キャッシュヒットしなかったトークン (5,000): 単位価格の 100% で課金されます。

• キャッシュヒットしたトークン (5,000): 単位価格の 20% で課金されます。

合計入力コストは、非キャッシュモード時のコストの 60% になります: (50% × 100%) + (50% × 20%) = 60%。

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

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

ユースケース

リクエストに共通のプレフィックスが含まれる場合、コンテキストキャッシュにより推論速度が大幅に向上し、推論コストが削減され、最初のパケット遅延が短縮されます。この機能は、特に次のユースケースで有用です。

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?"}]

   2 番目のターンメッセージ

   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."}
   ]

   コンテキストキャッシュにより、 lengthy なシステムプロンプトがキャッシュされるため、リクエストで頻繁にプロダクトを変更しても (たとえば、スマートウォッチからラップトップへ)、システムはより高速に応答できます。

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: input_tokens in usage は cache_creation_input_tokens と cached_tokens の合計と等しくないのはなぜですか?

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