概述

DeepSeek API 的 Context Caching on Disk（磁盘上下文缓存） 技术对所有用户默认开启，无需修改代码即可受益。其核心思想是：每次用户请求都会触发硬盘缓存的构建；如果后续请求与之前请求存在重叠前缀（overlapping prefix），重叠部分将从缓存中读取，计为一次 cache hit。

注意： 硬盘缓存仅匹配用户输入的前缀部分。输出仍然通过计算推理生成，受 temperature 等参数影响，具备随机性。

缓存持久化与命中规则

由于 Sliding Window Attention（滑动窗口注意力） 机制，缓存前缀的存储和匹配方式与传统的 KV Cache 有所不同：

每个被缓存的 prefix 是一个独立、完整的单元（cache prefix unit）。后续请求必须完全匹配某个 cache prefix unit 才能命中缓存——部分匹配不会命中。三种缓存持久化触发时机

触发类型

说明

1. 请求边界持久化

每个请求会在

用户输入的末尾位置

和

模型输出的末尾位置

各产生两个 cache prefix unit。后续请求若能完全匹配这些 unit，即可命中缓存。

2. 公共前缀检测持久化

当系统检测到多个请求之间存在公共前缀时，会将该公共前缀作为独立的 cache prefix unit 持久化。后续请求若能完全复用该 unit，即可命中缓存。

3. 固定 token 间隔持久化

对于长输入或长输出，系统会按固定 token 间隔切分出 cache prefix unit，避免长前缀因从未到达末端位置而完全无法被缓存。

缓存命中判定流程

请求到达 │ ├─ 请求前缀是否完全匹配某个已持久化的 cache prefix unit？ │ │ │ ├─ 是 → Cache Hit（匹配部分从硬盘缓存读取） │ │ │ └─ 否 → Cache Miss（全部重新计算） │ └─ 请求结果参与后续缓存持久化（边界 / 公共前缀 / 间隔）示例示例 1：多轮对话

第一轮请求：

{ "messages": [ { "role": "system", "content": "You are a helpful assistant" }, { "role": "user", "content": "What is the capital of China?" } ]}

第二轮请求：

{ "messages": [ { "role": "system", "content": "You are a helpful assistant" }, { "role": "user", "content": "What is the capital of China?" }, { "role": "assistant", "content": "The capital of China is Beijing." }, { "role": "user", "content": "What is the capital of the United States?" } ]}

命中分析：

第一轮请求的 user input 末尾（即 system user 两个消息的末尾）生成 cache prefix unit ①第二轮请求的前缀完全复用了第一轮的 messages → 完全匹配 unit ① ↓ Cache Hit ✅

第二轮请求可以完全复用第一轮请求产生的 cache prefix unit，前缀部分计为 cache hit。

示例 2：长文本问答

场景： 用户对同一份财报进行多轮不同角度的提问。

第一轮请求：

{ "messages": [ { "role": "system", "content": "You are an experienced financial report analyst..." }, { "role": "user", "content": "nnPlease summarize the key information of this financial report." } ]}

第二轮请求：

{ "messages": [ { "role": "system", "content": "You are an experienced financial report analyst..." }, { "role": "user", "content": "nnPlease analyze the profitability of this financial report." } ]}

第三轮请求：

{ "messages": [ { "role": "system", "content": "You are an experienced financial report analyst..." }, { "role": "user", "content": "nnPlease analyze the ratio of the company's revenue to expenses." } ]}

命中分析：

第一轮：Cache Miss — 无已持久化 prefix 可匹配 系统记录 prefix: system_message 第二轮：Cache Miss — 第一轮的 cache prefix unit 是完整的第一轮 user input， 包含了 "summarize..."，第二轮的前缀只匹配到 ， 后续不匹配 → 不命中 但系统检测到两轮请求的公共前缀： system_message → 将此外公共前缀持久化为独立 cache prefix unit ②第三轮：Cache Hit ✅ — 第三轮前缀完全匹配 unit ② system_message

时序总结：

轮次

Cache Hit?

原因

第 1 轮

❌ Miss

无已有缓存

第 2 轮

❌ Miss

前缀与第 1 轮 unit 不完全匹配；触发公共前缀检测

第 3 轮

✅ Hit

完全匹配第 2 轮后持久化的公共前缀 unit

缓存命中状态检查

DeepSeek API 在响应的 usage 字段中新增了两个字段来反映缓存的命中情况：

字段

含义

prompt_cache_hit_tokens

本次请求输入中命中缓存的 token 数量

prompt_cache_miss_tokens

本次请求输入中未命中缓存的 token 数量

示例响应片段：

{ "usage": { "prompt_tokens": 1500, "completion_tokens": 300, "total_tokens": 1800, "prompt_cache_hit_tokens": 1200, "prompt_cache_miss_tokens": 300 }}

上例中，1500 个 prompt token 中有 1200 个命中缓存（仅需从磁盘读取），300 个未命中（需要完整计算）。

定价

缓存命中可大幅降低成本。以每百万 token 为单位：

模型

Input (Cache Miss)

Input (Cache Hit)

Output

deepseek-v4-flash

$0.14

$0.0028

$0.28

deepseek-v4-pro

$0.435

$0.003625

$0.87

Cache Hit 的价格约为 Cache Miss 的 1/50 ~ 1/120，显著节省长上下文场景的成本。

设计要点总结1. 为什么采用"完全匹配前缀单元"而非部分匹配？

这是由 Sliding Window Attention 机制决定的。在滑动窗口注意力下，KV Cache 的计算依赖于完整的上下文窗口边界。部分匹配的 KV 状态无法直接复用——因此每个 cache prefix unit 被设计为独立完整的原子单元，要求完全匹配以保证 KV 状态的正确性与一致性。

2. 三层渐进式持久化策略的设计意图

层次

设计意图

请求边界

覆盖最常见的多轮对话场景——下一轮天然复用上一轮的 messages 前缀

公共前缀检测

覆盖"同一模板 不同问题"场景（如示例 2）——系统自动学习热点前缀

固定间隔切分

覆盖长文档场景——避免超长前缀因从未"抵达末端"而完全不可缓存

3. Best-Effort 机制缓存系统以 best-effort（尽力而为） 方式运行，不保证 100% 命中率。缓存构建需要数秒时间。不再使用的缓存将在数小时到数天内自动清理。4. 对应用开发者的影响无需显式管理缓存生命周期——系统自动构建与淘汰。多轮对话天然受益——只要延续同一会话的 messages 前缀即可命中。长文档 多问题场景——前两次请求作为"预热"，第三次起可命中公共前缀缓存。通过 prompt_cache_hit_tokens 监控收益——可据此评估应用架构是否充分利用了缓存。DeepSeek Anthropic API 兼容层不支持 cache_control 字段（该字段会被忽略），缓存行为完全由系统自动管理，与原生 DeepSeek API 一致。