缓存命中概念

在大模型API的实际调用中，许多场景（如长文档问答、多轮对话、带有大量 System Prompt 的角色扮演）会反复向模型发送相同的前置内容。缓存命中是一项旨在优化此类场景的高效计算机制，系统会将您请求中的重复前置内容进行缓存，当您后续的请求携带相同的前置内容时，模型无需重新计算这些 Token。从而降低使用成本，命中缓存的输入Token将享受折扣价。

支持的模型

支持缓存命中能力的模型见各模型卡片，或前往按需计费模式-Tokens查看。

如何提升缓存命中率

在分布式集群架构下，为了提升缓存命中率，您可以在调用模型服务时传入特定的自定义参数。

1. 提升命中率的参数接入说明

在调用支持缓存命中能力的模型时，您可以在请求体Body中携带上下文会话标识参数。

• 参数名称：prompt_cache_key

• 参数限制：最大长度不超过64个字符。

• 参数要求：建议传入具有唯一性的字符串（如用户的 UserID、会话的 SessionID、文档的 DocumentID 等）。属于同一长文档阅读或同一用户连续对话的请求，建议保持该参数值一致。

2. 调用请求示例 (cURL)

curl --location --request POST 'https://wishub.ctyun.cn/v1/chat/completions' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "model": "xxx",
    "prompt_cache_key": "my-prefix-cache-key-001",
    "messages": [
        {
            "role": "user",
            "content": "请对北京与上海这两座中国顶级一线城市进行全面、深度、多角度、客观中立的对比分析。"
        }
    ],
    "max_tokens": 200,
    "temperature": 0.6,
    "top_p": 0.7,
    "repetition_penalty": 1.0,
    "stream": true,
    "enable_thinking": true,
    "stream_options": {
        "include_usage": true
    }
}'

3. 如何查看缓存命中情况

您可以通过以下两种方式查看您的缓存命中数据：

• 方式一：通过平台“调用监控”查看

在模型推理服务“调用监控服务详情”页面。在调用Token量图表筛选条件中选择“按Token用量付费”-“缓存命中”，即可直观地按时段查看缓存命中的Token量。

• 方式二：通过 API 返回的 usage 字段实时查看

在模型服务调用返回的信息中，usage字段会透出本次请求Token的消耗明细：

{
    "code": 0,
    "id": "chatcmpl-17746032558594390000da17b1bf",
    "choices": [],
    "created": 1774603256,
    "model": "DeepSeek-V3.2",
    "object": "chat.completion.chunk",
    "usage": {
        "completion_tokens": 200,
        "prompt_tokens": 414,
        "total_tokens": 614,
        "prompt_tokens_details": {
            "cached_tokens": 256
        }
    }
}

计费说明

关于支持缓存命中的模型，Input (输入) Token 的计费将被自动拆分为两部分：

• 未命中缓存：按照模型输入单价的标准价格进行计费。

• 命中缓存：按照模型“缓存命中”的输入价格进行计费。

Output (输出) Token：无论是否命中缓存，输出部分的计费标准保持不变。