DeepSeek API 缓存机制：不用改代码，自动生效

DeepSeek API 的磁盘缓存技术对所有用户默认开启，不需要改任何代码，自动生效。发多轮对话时只要把历史消息完整带上，重叠前缀会直接从缓存读取，成本最高可节省 90%。

工作机制

每次请求都会触发磁盘缓存的构建。后续请求如果与之前的请求存在重叠前缀，重叠部分直接从缓存读取，计为"缓存命中"。

命中的关键条件：后续请求必须完全匹配一个已持久化的缓存前缀单元，从第 0 个 token 开始，前缀不一致则不命中。

缓存何时被持久化

三种情况触发缓存持久化：

• 请求边界持久化：每次请求结束时，在用户输入末尾和模型输出末尾各生成一个缓存前缀单元
• 公共前缀检测持久化：系统检测到多个请求存在公共前缀时，将该公共前缀作为独立缓存单元持久化
• 固定间隔持久化：超长输入或输出按固定 token 间隔切分缓存单元，避免长前缀因永远无法到达结束位置而完全无法缓存

curl 请求示例

发多轮对话时，只要把历史消息完整带上，缓存就会自动命中，不需要任何额外字段。

第一轮：

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个资深的财报分析师"},
      {"role": "user", "content": "<财报内容>\n请总结这份财报的关键信息"}
    ]
  }'

第二轮（追加历史，前缀命中缓存）：

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个资深的财报分析师"},
      {"role": "user", "content": "<财报内容>\n请总结这份财报的关键信息"},
      {"role": "assistant", "content": "...（上轮回答）..."},
      {"role": "user", "content": "分析一下这家公司的盈利能力"}
    ]
  }'

system prompt + <财报内容> 这段公共前缀会被系统检测并持久化，后续请求直接命中。

如何确认缓存命中

响应的 usage 字段中有两个新字段：

• prompt_cache_hit_tokens：本次命中缓存的 token 数
• prompt_cache_miss_tokens：本次未命中缓存的 token 数

用 jq 直接解析验证：

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}' | jq '.usage'

# 输出示例：
# {
#   "prompt_tokens": 1500,
#   "completion_tokens": 200,
#   "prompt_cache_hit_tokens": 1200,
#   "prompt_cache_miss_tokens": 300
# }

性能收益

128K prompt 的场景下，首 token 延迟从 13 秒降至约 500ms，成本最高可节省 90%。

几个注意事项

• 缓存系统以 64 个 token 为存储单位，少于 64 个 token 的内容不会被缓存
• 缓存系统基于"尽力而为"原则，不保证 100% 命中率
• 缓存构建需要数秒时间，缓存停止使用后通常在数小时到数天内自动清除
• 把 system prompt 和长文档放到消息最前面，保持前缀稳定
• 不要在 system prompt 里嵌入时间戳或随机 ID，否则每次前缀都变了，永远命中不了

第三方平台的缓存支持

需要注意的是，DeepSeek 的磁盘缓存是官方平台独有的工程实现，依赖他们自己的分布式磁盘阵列和调度系统。第三方推理平台无法透传这个能力。

以 SiliconFlow 为例，对 deepseek-ai/DeepSeek-V4-Flash 未启用 Prompt Cache，cached_tokens 和 prompt_cache_hit_tokens 始终为 0。

类似情况也存在于阿里云百炼、腾讯云等平台——这些平台有自己的 KV cache 实现，但接口字段未必对齐 DeepSeek 官方的 prompt_cache_hit_tokens。

如果你的场景对缓存敏感，直接用 DeepSeek 官方 API（api.deepseek.com）是最省成本的选择。