文档中心

上下文缓存

原理及选型

在多轮对话、工具调用及角色扮演等存在大量重复上下文输入的场景中，利用上下文缓存机制复用计算结果，避免模型对相同内容的重复处理。这将有效消除重复加载带来的开销，显著降低 Token 成本。

说明

方舟平台的新用户？获取 API Key 及开通模型等准备工作，请参见快速入门。

缓存模式

上下文缓存支持两种工作模式，可根据便捷性、确定性及成本需求进行选择。

隐式缓存：自动模式，用户无需做额外配置，且无法关闭，适合追求便捷的通用场景。系统会自动识别请求中的公共前缀并进行缓存，但不保证缓存命中。

显式缓存：需要主动开启的缓存模式。需要主动配置创建缓存，且支持缓存确定性命中。

注意

隐式缓存无需配置，系统自动开启。当请求使用显式缓存时，隐式缓存不生效。

对比项	隐式缓存	显式缓存
配置方式	无需配置，不可关闭	需要显式配置
是否影响回复效果	不影响	不影响
支持 API	Responses API Chat API Batch API	Responses API Context Chat API
缓存命中	不保证命中，具体命中概率由系统判定	确定性命中（缓存命中率更高）
缓存有效期	不确定，系统不承诺缓存可用时长	支持配置缓存过期时间
缓存最少 Token 数	1024	Responses API 前缀缓存：256 其他缓存类型：没有限制
命中缓存的输入 Token 计费	根据模型输入长度分段计费	根据模型输入长度分段计费
缓存存储计费	不计费	计费

隐式缓存

支持模型

隐式缓存支持的模型如下，具体可参见上下文缓存能力。

在线推理场景下，doubao-seed-code模型、doubao-seed-2.0及之后系列模型支持隐式缓存，且不可关闭。

批量推理场景下，支持的模型会开启隐式缓存，且不可关闭。

工作原理

向支持隐式缓存的模型发送请求时，该功能会自动开启，工作原理如下：

缓存创建：系统会基于请求输入的公共前缀进行缓存。当某次请求在完成推理后，系统可能将其输入中可复用的前缀片段写入缓存，以便后续请求在相同前缀出现时复用。

缓存命中：当后续请求的输入在开头部分与已有缓存条目存在相同的前缀时，系统会尝试复用这段前缀对应的缓存结果，从而减少重复计算。

不保证命中：缓存容量有限，旧缓存可能被淘汰；分布式路由也会影响命中概率。

不保证最长前缀命中：系统会综合考虑可用资源与命中收益，命中长度可能不是全局最长命中的那一段。

缓存命中条件：缓存块最少为 1024 tokens 才可能会被系统识别并参与命中匹配。即请求输入最少为 1024 tokens 才有可能触发缓存命中。

说明

通过 API 响应字段usage.prompt_tokens_details判断是否命中隐式缓存：

命中：cached_tokens > 0

未命中：cached_tokens = 0

计费说明

当请求命中隐式缓存时，计费信息如下：

命中的输入 tokens （cached_tokens）：按缓存命中输入单价计费。

未命中的输入 tokens ：按正常输入单价计费。

输出 tokens：按正常输出单价计费。

缓存存储：不计费。

注意

与显式缓存相比，隐式缓存存储不计费。

缓存命中输入单价可能会随上下文输入长度区间变化。如 Seed 2.0 系列模型在输入长度为 [0, 32k]、[32k, 128k]、[128k, 256k] 时，缓存命中输入单价不同。

使用限制

隐式缓存仅对支持该功能的模型，且通过Responses API、 Chat API 、Batch API 调用时生效。

最佳实践

提示词组织方式：把静态或重复内容放在提示词开头，把动态或差异内容放在末尾。

让具有相同提示词前缀的请求持续、稳定发送，减少缓存被淘汰的概率并最大限度提高缓存收益。

通过记录 API 响应字段usage.prompt_tokens_details监控缓存命中的 token 数，分析并优化缓存策略。

显式缓存

与隐式缓存相比，显式缓存需要显式创建，但能实现更高的缓存命中率（确定性命中）。

支持模型

显式缓存支持的模型及 API，请参见上下文缓存能力。

工作原理

显式缓存支持两种类型，分别为 Session 缓存和前缀缓存。

Session 缓存

存储初始信息，同时随每一轮对话动态更新缓存。在新一轮请求，将缓存信息与输入信息一起输入给模型进行推理。适合在多轮对话、多轮工具调用等场景使用。

原理图	说明
	用户创建缓存时，方舟将信息处理为可直接用于模型推理的tokens 存入缓存，并生成 ID 作为 Key。方舟收到新请求，计算好新输入的tokens，并根据请求中的缓存 ID 取对应信息 tokens 拼接后输入给模型推理。模型返回信息，方舟将回复信息的tokens 存储入缓存中，供下次请求时使用。

前缀缓存

存储初始信息，在每次对话时无需更新，适合标准化对话开场白、特定任务的指令、规则化模板、超长文本深度分析等静态 Prompt 模板的反复使用场景。

原理图	说明
	用户创建缓存时，方舟将信息处理为可直接用于模型推理的tokens 存入缓存，并生成 ID 作为 Key。方舟收到新请求，计算好新输入的tokens，并根据请求中的缓存 ID 取对应信息 tokens 拼接后输入给模型推理。模型输出回复信息，无需更新缓存中的信息。

调用方式及对比

平台提供了两种 API 来实现显式缓存功能。由于每个模型最多只支持一种缓存 API，因此当您选定模型后，能够使用的 API 也就随之确定。

下表简要对比了这两种 API 的调用方式与核心区别。您可以查阅相应的 API 教程，获取详细的调用说明和代码示例。

API	Responses API	Context Create API
教程	上下文缓存	上下文缓存(Context API)
模型支持	上下文缓存能力	上下文缓存能力
使用流程	缓存信息：在对话时配置"caching": {"type": "enabled" }创建Session缓存，配置"caching":{"type": "enabled", "prefix": true}创建前缀缓存，存储当前对话内容到缓存中。在返回信息中获取 ID 值。使用缓存：在对话时配置 "previous_response_id":"<ID>"，本轮对话使用缓存信息。 Session 缓存：每次使用缓存同时配置"caching": {"type": "enabled" }，将本轮信息也更新到缓存中，并生成新 ID。下一轮调用获取本轮调用返回的 ID 。前缀缓存：无需配置"caching": {"type": "enabled" }，previous_response_id仅配置为固定缓存 ID 即可。	缓存信息：使用 Context Create API 创建缓存信息，并指定创建的缓存类型（Session 缓存、前缀缓存）。在返回信息中获取缓存 ID 值。使用缓存：通过 Context Chat API 配置 "context_id":"<ID>"，本轮对话使用缓存信息。 Session 缓存：每次使用缓存时，更新本轮信息至缓存中。不生成新 ID。下一轮您继续使用原缓存 ID 即可。前缀缓存：每次使用固定的缓存信息。
保留初始信息	是可灵活控制，即您可删除任意一轮传入的缓存信息，来控制初始信息内容。	是不可控制，一旦写入，不可更改。
缓存收费项	存储缓存费用以及输入命中缓存费用（折扣）。	存储缓存费用以及输入命中缓存费用（折扣）。
可缓存的类型	支持对多模态（文字、图片、视频等）输入进行缓存，支持缓存工具调用信息。	仅支持文本缓存。
变更缓存内容	Session 缓存：支持更新缓存信息，缓存 ID 会新生成一个缓存 ID。前缀缓存：不支持，且无需更新。	Session 缓存：支持更新缓存信息，缓存 ID 保持不变。前缀缓存：不支持，且无需更新。
调用往期缓存信息	支持，使用往期缓存 ID	Session 缓存：不支持，创建缓存后 ID 不变，更新内容，往期的内容会被覆盖。前缀缓存：不涉及，内容不可变。
手动删除缓存信息	支持可删除任意ID的缓存信息	不支持过期自动删除
缓存保留时间	支持配置过期时刻。 UTC Unix 时间戳（单位：秒），最大当前时间+604800（秒），即创建起保留 7 天。	支持配置TTL。创建缓存时可配置，最大168小时。
过期机制	配置的是过期时刻，即缓存到对应时间点即过期。不随着缓存/存储的使用而重置生命周期。存储及缓存过期后，需通过 Responses API 重新创建存储/缓存内容。	配置的是保存时长，计算公式：当前时刻-最近使用缓存时刻缓存在 TTL 周期内未使用过，则过期。使用后重新激活缓存，生命周期重置。
最大缓存长度	有最大上下文窗口	有最大上下文窗口-最大输出长度
触发最大缓存长度	创建时超出最大缓存长度，会报错。其中 Session 缓存在更新时超出长度限制会报错。	创建时超出最大缓存长度，会报错。其中Session 缓存在更新时超出长度限制，会自动删除历史消息。

最近更新时间：2026.08.21 11:18:08

这个页面对您有帮助吗？

有用

无用

火山方舟