第14章 Context Caching（上下文缓存）

上下文缓存 DeepSeek API 的“上下文磁盘缓存”技术默认对所有用户开启，无需修改代码即可享受其便利。 每个用户请求都会触发硬盘缓存的构建。如果后续请求与前序请求存在重叠的前缀，重叠部分将直接从缓存中读取，这被称为“缓存命中”。 缓存持久化与命中规则 要发生缓存命中，相应的前缀必须已经“持久化”（即写入磁盘缓存）。受滑动窗口注意力机制影响，缓存前缀的存储和匹配方式与以往不同。每个缓存前缀都是独立且完整的单元。后续请求必须完全匹配某个缓存前缀单元，才能命中缓存。 缓存前缀何时持久化： 在请求边界处持久化：每个请求会在用户输入的末尾和模型输出的末尾各产生一个缓存前缀单元。如果后续请求完全匹配这些单元，即可命中缓存。 公共前缀检测持久化：当系统检测到多个请求之间存在公共前缀时，会将该公共前缀作为独立的缓存前缀单元进行持久化。如果后续请求完全复用了该缓存前缀单元，即可命中缓存。 在固定 Token 间隔处持久化：针对长输入或长输出，系统会在固定的 Token 间隔处切分出缓存前缀单元，以避免因始终未能到达结束位置而导致长前缀完全无法缓存的情况。 示例 1：用户的第一轮请求是 A + B，第二轮请求是 A + B + C。由于第二个请求能完全匹配 A + B 这个缓存前缀单元，因此 A + B 部分会命中缓存。详见下文示例 1。 示例 2：用户的第一轮请求是 A + B，第二轮请求是 A + C。由于 A + C 无法完全匹配第一轮请求的缓存前缀单元（A + B），因此第二个请求不会命中缓存。但此时系统会检测到两个请求共享公共前缀 A，并将 A 持久化为一个缓存前缀单元。当第三轮请求 A + D 到来时，它能完全匹配缓存前缀单元 A，从而命中 A 部分的缓存。详见下文示例 2。 示例 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?"}
]
在这个例子中，第二个请求可以完全复用第一个请求的缓存前缀单元，这将计为一次“缓存命中”。 示例 2：长文本问答​ 第一个请求 messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."}
{"role": "user", "content": "\n\nPlease summarize the key information of this financial report."}
]
第二个请求 messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."}
{"role": "user", "content": "\n\nPlease analyze the profitability of this financial report."}
]
第三个请求 messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."}
{"role": "user", "content": "\n\nPlease analyze the ratio of the company's revenue to expenses."}
]
在上述示例中，前两个请求不会命中缓存。在前两个请求完成后，系统会将用户消息中的系统消息 + 识别为缓存前缀单元并将其持久化。由于第三个请求与前一个持久化的缓存前缀单元完全匹配，因此它可以命中缓存。 查看缓存命中状态​ 在 DeepSeek API 的响应中，我们在 usage 部分增加了两个字段来反映请求的缓存命中状态： prompt_cache_hit_tokens：本次请求输入中命中缓存的 token 数量。 prompt_cache_miss_tokens：本次请求输入中未命中缓存的 token 数量。 磁盘缓存与输出随机性​ 磁盘缓存仅匹配用户输入的前缀部分。输出内容仍通过计算和推理生成，并受温度等参数影响，从而引入随机性。 补充说明​ 缓存系统按“尽力而为”的方式工作，不保证 100% 的缓存命中率。 缓存构建需要数秒时间。一旦缓存不再使用，它将被自动清除，通常在几小时到几天内完成。