概述 - 通义千问 API

您在使用文本生成模型时，不同的推理请求之间可能会有重合的输入内容（如多轮对话、针对一本书的多次提问等），Context Cache 技术可以将这些请求的公共前缀内容进行缓存，在推理时减少重复的运算量，提升响应速度，在不影响回复效果的情况下降低您的使用成本。

支持的模型

当前支持qwen-max、 qwen-plus 、qwen-turbo模型。

功能介绍

如何使用

您向支持 Context Cache 的模型发送请求时，会自动开启 Context Cache 模式。对于您的每次请求，系统会判断并查找请求的前缀部分是否存储在缓存中，并给出命中 Cache 的结果。

我们会定期清理一段时间内没有使用的缓存信息。

说明

上下文缓存的命中概率并不是100%，即使是上下文完全一致的请求，也存在无法命中的概率，命中概率依据系统判断而定。

如何计费

开启 Context Cache 模式无需额外付费。若您的请求被系统判断命中了 Cache，被命中的 Token 会按照 cached_token 来计费，cached_token的单价为input_token单价的40%；未被命中的 Token 仍按照 input_token计费。假设某一次请求的输入 Token 数为10,000，有5,000个 Token 被系统判断命中了 Cache，则 input_token 的计费为未开启 Context Cache 模式的 70%[(50% 未命中 Cache Token)*100%单价 + (50% 命中 Cache Token)*40%单价] ）。计费示意图如下：

output_token仍按原价计费。

您可以从返回结果的cached_tokens属性获取命中 Cache 的 Token 数。

如果您通过Batch方式调用，则无法享受 Cache 的折扣。

如何提升命中 Cache 的概率

由于 Cache 的命中逻辑是判断不同请求的前缀是否存在重复内容，因此如果您希望提高命中 Cache 的概率，需要将重合的内容放在提示词的开头，将不同的内容放在提示词的末尾。

假设系统已经缓存了“ABCD”，则请求“ABE”将有概率命中 Cache，而“BCD”将无法命中 Cache。

在您使用该功能时，不足 256 Token 的内容不会被缓存。

工作方式

Context Cache 系统的工作方式为：

查找

在收到您的请求后，我们的系统会查找您提示词的前缀部分是否存储在缓存中。

判断

命中

如果命中了缓存信息，系统将使用缓存的结果来进行推理。

未命中

如果没有命中缓存信息，系统将按照常规模式处理您的请求，您本次请求的提示词前缀将被缓存到系统中。

命中 Cache 的案例

OpenAI兼容

当您使用 OpenAI 兼容的方式调用模型并触发了 Context Cache后，可以得到如下的返回结果，在usage.prompt_tokens_details.cached_tokens可以查看命中 Cache 的 Token 数（该 Token 数包含在usage.prompt_tokens中）。

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "我是阿里云开发的一款超大规模语言模型，我叫通义千问。"
            },
            "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"
}

典型场景

如果您的不同请求有着相同的前缀信息，Context Cache 可以有效提升这些请求的推理速度，降低推理成本与首包延迟。以下是几个典型的应用场景：

基于长文本的问答

适用于需要针对固定的长文本（如小说、教材、法律文件等）发送多次请求的业务场景。

第一次请求的消息数组

之后请求的消息数组

虽然提问的问题不同，但都基于同一篇文章。相同的系统提示和文章内容构成了大量重复的前缀信息，有较大概率命中 Context Cache。

代码自动补全

在代码自动补全场景，大模型会结合上下文中存在的代码进行代码自动补全。随着用户的持续编码，代码的前缀部分会保持不变。Context Cache可以缓存之前的代码，提升补全速度。

多轮对话

实现多轮对话需要将每一轮的对话信息添加到 messages 数组中，因此每轮对话的请求都会存在与前轮对话前缀相同的情况，有较高概率命中 Context Cache。

第一轮对话的消息数组

第二轮对话的消息数组

随着对话轮数的增加，Context Cache 带来的推理速度优势与成本优势会更明显。

角色扮演或 Few Shot

在角色扮演或 Few-shot 学习的场景中，您通常需要在提示词中加入大量信息来指引大模型的输出格式，这样不同的请求之间会有大量重复的前缀信息。

以让大模型扮演营销专家为例，System prompt包含有大量文本信息，以下是两次请求的消息示例：

使用 Context Cache 后，即使用户频繁更换询问的产品类型（如从智能手表到笔记本电脑），系统也可以在触发 Cache 后快速响应。

概述

支持的模型#

功能介绍#

如何使用#

如何计费#

如何提升命中 Cache 的概率#

工作方式#

命中 Cache 的案例#

OpenAI兼容#

典型场景#