# 什么是上下文缓存上下文缓存（后简称缓存）是方舟提供的一个高效的缓存机制，旨在为您优化调用模型服务体验。通过缓存常用上下文数据，减少每次请求时重复处理加载开销，达到降低成本（命中缓存的输入有折扣优惠）目标。适合多轮对话、工具调用、角色扮演等需多次传入相同内容的场景。 # 支持模型支持缓存的模型请参见 [上下文缓存](/docs/82379/1330310#e6772192)。 # 工作原理如下图所示，使用缓存处理请求，会在新输入信息（问题）处理完成后，将缓存中已处理好的信息（信息 token）拼接在新输入信息（问题 token）前。相比未使用缓存的请求，可以减少信息的开销，有效降低成本。

# 缓存类型上下文缓存有两种类型，分别为 Session 缓存和前缀缓存。 ## Session 缓存 **存储初始信息**，同时**将每一轮对话动态更新至缓存**，在请求时，将缓存的信息与输入信息一起输入给模型进行处理。适合在多轮次对话场景使用，如陪聊、多工具调用等等。可见 Session 缓存的内容随着请求调用会不断更新，不适用于并发请求场景。 ### 工作原理

1. 用户创建缓存时，方舟将信息作为（Value）存到缓存中，并生成对应的缓存 ID 作为 Key。 2. 方舟收到新请求，根据请求中的缓存 ID 将缓存中的信息作为输入传入。 3. 方舟只需处理新输入的信息，再结合缓存中已处理的上下文信息，交由模型推理。 4. 模型输出回复信息，并**将回复信息添加到缓存**中，供下次请求时使用。 ## 前缀缓存存储初始信息，在每次对话时无需更新，适合标准化对话开场白、特定任务的指令、规则化模板、超长文本深度分析等静态 Prompt 模板的反复使用场景。 ### 工作原理

1. 用户创建缓存时，方舟将信息作为（Value）存到缓存中，并生成对应的缓存 ID 作为 Key。 2. 方舟收到对话请求时，会根据请求的缓存 ID 匹配缓存中的初始化信息。 3. 方舟只需处理新输入的信息，再结合缓存中已处理的上下文信息，交由模型推理。 4. 模型输出回复信息，无需更新缓存中的信息。 # 调用方式方舟提供了两套 API 来使用上下文缓存功能，具体到单个模型，最多支持一套 API 调用缓存方式，即选定模型后，缓存调用的 API 也已确定。下面是两套 API 调用方式的简要说明，供您快速了解调用方式以及两套缓存API的几个核心的区别。可以跳转至对应 API 教程中，查阅具体的调用教程。 | | | | \ |API |Response API |Context API | |---|---|---| | | | | \ |API 文档 |* [创建&使用缓存 API](https://www.volcengine.com/docs/82379/1569618) |\ | |* [删除缓存 API](https://www.volcengine.com/docs/82379/1584286) |* [创建缓存 API](https://www.volcengine.com/docs/82379/1528789) |\ | | |* [使用缓存 API](https://www.volcengine.com/docs/82379/1529329) | | | | | \ |使用流程 |1. 缓存信息：在对话时配置` "caching": {"type": "enabled" }`，存储当前对话内容到缓存中。在返回信息中获取 ID 值。 |\ | |2. 使用缓存：在对话时配置 `"previous_response_id":""`，本轮对话使用缓存信息。 |\ | | * Session 缓存：每次使用缓存同时配置`"caching": {"type": "enabled" }`，**将本轮信息也更新到缓存中，并生成新 ID。下一轮调用获取本轮调用返回的 ID。** |\ | | * 前缀缓存：无需配置`"caching": {"type": "enabled" }`，`previous_response_id`仅配置为固定缓存 ID 即可。 |1. 缓存信息：使用[创建缓存](https://www.volcengine.com/docs/82379/1528789)接口创建缓存信息，并指定创建的缓存类型（Session 缓存、前缀缓存）。在返回信息中获取缓存 ID 值。 |\ | | |2. 使用缓存：通过[使用缓存](https://www.volcengine.com/docs/82379/1529329)接口配置 `"context_id":""`，本轮对话使用缓存信息。 |\ | | | * Session 缓存：每次使用缓存时，**更新本轮信息至缓存中**。不生成新 ID。下一轮您继续使用原缓存 ID 即可。 |\ | | | * 前缀缓存：每次使用固定的缓存信息。 | | | | | \ |保留初始信息 |是 |\ | |可灵活控制，即您可删除任意一轮传入的缓存信息，来控制初始信息内容。 |是 |\ | | |不可控制，一旦写入，不可更改。 | | | | | \ |缓存收费项 |存储缓存费用以及输入命中缓存费用（折扣） |存储缓存费用以及输入命中缓存费用（折扣） | | | | | \ |可缓存的类型 |支持对多模态输入进行缓存，支持对 Functioncall 内容进行缓存。 |仅支持文本缓存。 | | | | | \ |变更缓存内容 |Session 缓存：支持更新缓存信息，缓存 ID 会新生成一个缓存 ID。 |\ | |前缀缓存：无需更新。 |Session 缓存：支持更新缓存信息，缓存 ID 保持不变。 |\ | | |前缀缓存：不支持，且无需更新。 | | | | | \ |调用往期缓存信息 |支持 |\ | |使用往期缓存 ID |Session 缓存：不支持，创建缓存后 ID 不变，往期的缓存不可调用。 |\ | | |前缀缓存：不涉及，内容不可变。 | | | | | \ |手动删除缓存信息 |支持 |\ | |可以删除任意ID的缓存信息 |不支持 |\ | | |过期自动删除 | | | | | \ |手动配置缓存保留时间 |支持 |\ | |创建时 72 小时（3天） |支持 |\ | | |创建缓存时可配置 TTL （7天） | | | | | \ |过期机制 |创建缓存 3 天后自动删除或手动删除 |创建缓存后，在 TTL 周期内未使用过。使用后激活缓存，重新计时。 | | | | | \ |最大缓存长度 |有 |\ | |最大上下文窗口-最大输出长度 |有 |\ | | |最大上下文窗口-最大输出长度 | | | | | \ |触发最大缓存长度 |创建时超出最大缓存长度，会报错。 |\ | |其中 Session 缓存在更新时超出长度限制会报错。 |创建时超出最大缓存长度，会报错。 |\ | | |其中Session 缓存在更新时超出长度限制，会自动删除历史消息。 |\ | | | | > 综上 Response API 对缓存操控非常灵活，可进行 ID 粒度的使用、变更，前缀缓存/ Session 缓存更多是使用上的区别，而非功能上的隔离，如您可在任意一轮对话中，切换至前缀缓存使用方式，只需请求不再更新缓存` "caching": {"type": "disalbed" }`，而使用固定的缓存ID。 # 相关文档 ## 教程 * [上下文缓存(Context API) ](/docs/82379/1396491)：使用 Context API 调用教程。 * [上下文缓存(Responses API)](/docs/82379/1602228)：使用 Responses API 调用模型。 ## API * [Responses API](https://www.volcengine.com/docs/82379/1585135|API) * [Context API](https://www.volcengine.com/docs/82379/1528788)

火山方舟大模型服务平台