DeepSeek API 的 KV Cache（上下文硬盘缓存）默认开启，无需修改代码。当请求前缀与之前完全一致时，命中缓存，价格从 3元/M 降至 0.025元/M（pro 模型）。适合有固定 system prompt 的 Agent、多轮对话、文档问答等场景。

DeepSeek API KV Cache（上下文硬盘缓存）

什么是 KV Cache

KV Cache 将最近请求的上下文前缀缓存到服务器磁盘。当后续请求的开头与缓存内容完全一致时，直接读取缓存，跳过重新计算，速度更快、价格更低。

自动开启，无需配置

// 无需任何额外参数，KV Cache 自动工作
const response = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    { role: "system", content: longSystemPrompt }, // 这部分会被缓存
    { role: "user", content: "这份文档的核心结论是什么？" },
  ],
});

查看缓存命中情况

每次响应的 usage 字段包含缓存统计：

console.log(response.usage);
// {
//   prompt_tokens: 8500,
//   completion_tokens: 200,
//   total_tokens: 8700,
//   prompt_cache_hit_tokens: 8000,    // 命中缓存的 token（低价）
//   prompt_cache_miss_tokens: 500,    // 未命中缓存的 token（正常价）
// }

成本计算（pro 模型）：

• 8000 命中 token × 0.025元/M = 0.0002元
• 500 未命中 token × 3元/M = 0.0015元
• 200 输出 token × 6元/M = 0.0012元
• 合计 ≈ 0.0029元（如果没有缓存，同样请求约 0.027元，节省约 89%）

命中条件

KV Cache 以缓存前缀单元为基本单位，只有完整匹配才能命中：

条件	说明
前缀完全一致	messages 数组开头部分内容完全相同（包括 role、content）
内容不能修改	修改任何历史消息都会破坏缓存
尽力而为	缓存不保证 100% 命中（服务器策略决定）
不影响输出	命中缓存不改变模型输出逻辑或随机性

最大化缓存命中率

实践 1：固定 system prompt，只在末尾追加新消息

// ✅ 好的做法：system prompt 固定，每轮只追加
const messages = [
  { role: "system", content: FIXED_SYSTEM_PROMPT },  // 永远不变
  ...conversationHistory,                              // 历史消息追加
  { role: "user", content: userInput },               // 最新消息
];

实践 2：文档问答将文档内容放在前缀

// ✅ 文档内容放在 system 或早期 user 消息，保持稳定
const messages = [
  {
    role: "system",
    content: `你是文档助手。以下是文档内容：\n\n${documentContent}`,
  },
  // 后续问题追加
  ...questions.map((q) => ({ role: "user" as const, content: q })),
];

实践 3：batch 处理时复用相同前缀

// ✅ 相同 system prompt 的批量请求，第一次 miss 后续全部 hit
const SHARED_SYSTEM = "你是数据分析专家...";

await Promise.all(
  items.map((item) =>
    client.chat.completions.create({
      model: "deepseek-v4-pro",
      messages: [
        { role: "system", content: SHARED_SYSTEM }, // 共享前缀
        { role: "user", content: `分析：${item}` },
      ],
    })
  )
);

适用场景

场景	预期命中率	节省效果
固定 system prompt 的 Agent	高	显著
长文档 Q&A（多个问题）	高	显著
多轮对话（对话历史稳定）	中-高	明显
每次完全不同的独立请求	低	有限

常见问题

Q: KV Cache 缓存多久过期？

A: DeepSeek 没有公开具体的缓存 TTL。缓存是"尽力而为"策略，不保证永久有效，每次请求都应以 miss 做兜底计算成本。

Q: 怎么确认缓存是否真的在生效？

A: 查看 usage.prompt_cache_hit_tokens。如果连续相同前缀的请求中，第二次开始出现 prompt_cache_hit_tokens > 0，说明缓存在生效。

Q: 流式请求也能命中缓存吗？

A: 可以，缓存机制与流式/非流式无关，命中条件相同。