前缀缓存
更新时间：2025-12-11
上下文缓存可以存储和重复使用之前处理过的上下文信息，以降低使用成本和时延。
什么是前缀缓存
- 一次性缓存，主要用于缓存固定的背景信息等。初始信息存储后，在后续的每次对话中无需更新。
- 适用于单次请求prompt模板固定的场景，比如人设信息、对话开场白、规则化模板、超长文本深度分析等。
缓存开启方式
此模式需要主动开启，您可以通过缓存创建API将指定内容写入缓存，在有效期内使用缓存信息即可实现命中。
支持模型
- deepseek-v3.1-250821
- deepseek-v3.1-think-250821
- deepseek-v3
使用限制
此为邀测能力，如需使用，请提交工单开通。
计费说明
| 模型名称 | 输入 元/千tokens |
缓存命中 元/千tokens |
缓存存储 元/千 tokens /小时 |
输出 元/千tokens |
|---|---|---|---|---|
| deepseek-v3.1-250821 | 0.004 | 0.0008 | 0.000017 | 0.012 |
| deepseek-v3.1-think-250821 | 0.004 | 0.0008 | 0.000017 | 0.012 |
| deepseek-v3 | 0.002 | 0.0005 | 0.000017 | 0.008 |
使用上下文缓存调用模型时，费用分为以下4个部分：
- 输入（元/千tokens)：请求未被命中的输入token按标准输入单价进行计费。
- 缓存命中（元/千tokens)：请求命中缓存部分的输入token按标准输入单价的20%或25%计费。
- 缓存存储（元/千 token/小时）：缓存存储的费用，按照自然小时缓存的最大量乘以单价进行累加。在缓存有效期内，如果该小时缓存未变更，则取上个小时的缓存最大值进行计算，以此类推。
- 输出（元/千tokens)：模型生成token按标准输出单价进行计费。
注：
- 缓存创建后开始收取存储费用，直到缓存被删除（一直未被使用，达TTL被删除或使用删除API自行删除）停止计费。
- 存储费用在每个自然小时整点出账，不足 1 小时按照 1 小时计算。
每次调用模型，可以在返回的usage中查看token消耗情况。
Plain Text
1 "usage": {
2 "prompt_tokens": 24,
3 "completion_tokens": 87,
4 "total_tokens": 111,
5 "prompt_tokens_details": {
6 "cached_tokens": 23
7 },
8 "completion_tokens_details": {
9 "reasoning_tokens": 73
10 }
11 }各字段含义如下：
- prompt_tokens：本次请求输入给模型的token数。
- completion_tokens：模型回复的token数，即输出token数量，用于计算输出费用。
- total_tokens：本次请求总共消耗的token，为输入、输出token总和。
- prompt_tokens_details.cached_tokens：本次请求缓存命中的token数量，用于计算缓存命中的费用。
可以通过以上字段计算：
- 输入费用：（prompt_tokens-cached_tokens）* 输入单价
- 缓存存储费用：每个自然小时计算 cached_tokens最大值，乘以单价
快速开始
1. 创建前缀缓存
在使用前缀缓存进行对话前，需要调用创建缓存的API，将初始信息写入。
Plain Text
1curl --location 'https://qianfan.baidubce.com/v2/caching' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \
4--data '{
5 "model": "deepseek-v3.1-250821",
6 "messages":[
7 {
8 "role": "system",
9 "content": "你是一个专业的百度千帆技术客服，回答问题必须严谨、简短、并且使用中文。"
10 }
11 ],
12 "ttl":3600
13}'可以通过ttl指定缓存的过期时长，单位为秒。缓存信息在创建后开始计时，超过ttl后缓存信息会被删除。每次调用缓存发起对话都会根据ttl更新过期时间。
模型回复如下：
Plain Text
1{
2 "id": "cache-20251107212205-xxxxxx",
3 "model": "deepseek-v3.1-250821",
4 "mode": "common_prefix",
5 "ttl": 3600,
6 "usage": {
7 "prompt_tokens": 23,
8 "completion_tokens": 0,
9 "total_tokens": 23
10 }
11}返回已创建的前缀缓存基本信息，其中cache-20251107212205-xxxxxx是创建的前缀缓存的 ID，需要记录并在后续请求模型推理服务时使用。usage.total_tokens是本次写入缓存的token数。
2. 使用前缀缓存进行对话
整体使用方法与普通的对话chat API(v2/chat/completions)一致，增加了cache_id字段，用于引入已经写入缓存的信息，详情请查看缓存对话API。
Plain Text
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
4--data '{
5 "cache_id": "cache-20251107212205-xxxxxx",
6 "model": "deepseek-v3.1-250821",
7 "messages": [
8
9 {
10 "role": "user",
11 "content": "你是谁"
12 }
13 ]
14}
15'3. 查询前缀缓存
如需查询已经写入的缓存信息，可以通过查询接口。
Plain Text
1curl --location 'https://qianfan.baidubce.com/v2/caching/{cache_id}' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \接口返回：
Plain Text
1{
2 "id": "cache-20251107212205-xxxxx",
3 "model": "deepseek-v3.1-250821",
4 "mode": "common_prefix",
5 "ttl": 3600,
6 "usage": {
7 "prompt_tokens": 23,
8 "completion_tokens": 0,
9 "total_tokens": 23
10 },
11 "expire_at": 1762528155
12}返回信息与创建缓存时返回的信息基本一致，可以通过expire_at获取该缓存的最新过期时间。
4. 删除前缀缓存
前缀缓存将会根据缓存的token数量以及时长收取存储费用，如果不再需要缓存信息可以及时进行删除，接口详情请查看删除缓存API。
Plain Text
1curl -X DELETE 'https://qianfan.baidubce.com/v2/caching/{cache_id}' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \接口返回：
Plain Text
1{
2 "id": "cache-20251107212205-xxxxx",
3 "deleted": true
4}deleted": true表示该缓存已成功删除。
注：缓存删除后无法恢复，如需再次使用请通过创建接口重新写入。