文档中心

火山方舟

历史文档

上下文缓存(Context API)（已下线）

本文介绍如何使用Context API 实现 Session 缓存以及前缀缓存能力。

说明

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

开通功能

访问开通管理，在推理(缓存)定价列开通缓存。

模型及API

API：

Context API：Context Create API、Context Chat API。

Responses API：推荐，支持更多模型，更灵活使用，教程见上下文缓存。

模型支持：上下文缓存能力

调用方式及对比

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

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

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

Session 缓存教程

快速跳转至前缀缓存教程

Session 缓存为会话级别的缓存，将会话的上下文（Context）进行缓存，并在对话进行中不断更新缓存内容，保障每轮对话能获取历史轮次的对话信息，维持对话内容延续，适合角色扮演、情景聊天等长轮数对话场景。开通 Session 缓存后，通过缓存输入的内容会有较大的折扣，可有效降低使用成本。

因使用缓存来存储您的上下文信息，您开通并使用了该功能后，会产生相应的存储费用。

快速开始

Curl

Python

Java

1.创建 Session 缓存

使用 Session 缓存前，您需要调用创建上下文缓存 API 创建缓存，并写入初始信息。后续只要在上下文缓存对话 API 中引入此缓存，即可让方舟为您管理历史对话以及享受使用缓存带来的费用降低。

其中：

$ARK_API_KEY替换为您的 API Key，或者配置 API Key 至环境变量。

<YOUR_ENDPOINT_ID>替换为您的推理接入点 ID。

"ttl":3600代表 Session 缓存 TTL，当前为 3600 秒。

"mode": "session"代表使用的 Session 缓存模式。

模型回复预览。

返回的创建的 Session 缓存的基本信息，其中<YOUR_CONTEXT_ID>是创建的 Session 缓存的 ID，格式类似ctx-****，需要记录并在后面请求模型推理服务时使用。

2.使用 Session 缓存进行对话

我们使用接口创建上下文缓存 API ，来进行使用 Session 缓存的对话。

其中。

$ARK_API_KEY替换为您的 API Key，或者配置 API Key 至环境变量。

<YOUR_CONTEXT_ID>替换为之前创建的 Session 缓存 ID。

<YOUR_ENDPOINT_ID>替换为您的推理接入点 ID。

模型回复预览。

典型使用

手动管理 Session 缓存

使用了支持 rolling_tokens 模式的模型，可以通过下面方法创建 Session 缓存，并可以根据需要来启用自动管理和手动管理 Session 缓存。

设置truncation_strategy.type为rolling_tokens，即可创建 Session 缓存。

当您希望自行控制触发 Session 缓存上限时的处理，可以将truncation_strategy.rolling_tokens设置为false，在历史消息长度超过上下文长度时模型会停止输出，并在返回信息中返回finish_reason为length，您获取此信息后可以根据您按需进行后续处理。

当您希望自动控制触发 Session 缓存上限时的处理，可以将truncation_strategy.rolling_tokens设置为true，这是会按照默认的方式进行处理，处理方式请参见 rolling_tokens 模式。

使用说明

了解 Session 缓存与前缀缓存，参见缓存类型。

Session 缓存 API 为有状态 API，不支持并发调用同一 Session 缓存，即不能在同一时刻发起多个带相同 Session 缓存 ID（context_id）的请求。

不支持 Partial 模式（又称 Prefill Response），调用创建上下文缓存 API 时，提交的messages数组的最后一条消息role可以是user或system，而不能为assistant。

正例：

"messages":[
{"role":"user","content":"你是谁"},
{"role":"assistant","content":"我是李雷"},
{"role":"user","content":"今天天气如何"}
],

反例：

"messages":[
{"role":"user","content":"你是谁"},
{"role":"assistant","content":"我是李雷"}
],

Session 缓存当前只支持在线推理，不支持与批量推理一起使用。

缓存上限说明

随着对话轮数增加，内容会达到 Session 缓存的上限。按照处理方式的不同，可以分为 2 种模式。

last_history_tokens 模式

触发上限则滚动信息窗口，遵循先进先出的策略。触发缓存上限时，先删除最早的缓存对话记录（初始消息不会删除，即在创建 session 缓存时写入缓存的信息不会删除），再存入新的对话信息。这个模式下，滚动数据不会产生额外的计算成本。

rolling_tokens 模式

触发上限则定量删除信息并重新计算，使用固定长度 A 来限制 Session 缓存上限，固定长度 B 来控制删除上下文的长度。当 Session 缓存达到上限时，即达到 A 长度时，会进行下面两个动作：

清除 Session 缓存 B 长度的陈旧消息（初始消息不会删除，即在创建 session 缓存时写入的信息不会删除），为后续新的消息腾挪存储空间。

重新计算缓存中历史信息，以确保模型回复与历史交互的连贯性。

具体计算逻辑供您了解：以Doubao-pro-32k模型为例，Session 缓存的 token 量达到 32k（最大上下文长度）-4k（最大输出长度）时，会删除 4k 陈旧的历史信息（除了初始消息），然后重新计算和存储保留的缓存内容。

触发 Session 缓存上限引起重新计算的轮次，会将保留的历史信息和新消息一样进行计算和存储。表现为此轮 Session 缓存的 token 比例降低为 0，该轮无缓存输入 token，后续又会趋于正常。

过期时间

Session 缓存未被使用时会开始计时，达到 TTL（Time To Live），会被删除；如果中途被使用，那么此缓存 TTL 会被重置，并继续保留。

举例：您在 8:00 创建了 Session 缓存 A、B，并设置 TTL 为 2 小时。10:00 时，缓存 A 没被使用，缓存 B 在 9:00 被使用。那么，缓存 A 会被删除，B TTL 还有 1 小时。

注意

没有触发清除的 Session 缓存，均会占用缓存，从而产生存储费用。您可以根据自己业务合理设置 TTL，保证请求的内容能享受 Session 缓存带来的低成本；又避免 Session 缓存删除前的长期空闲时间。

计费说明

计费单价请参见：模型价格。

计费项

计费逻辑

与未使用 Session 缓存相比，模型服务费用会产生在：

输入（元/千 token）：新的请求中您无需重新发送历史对话，输入 token 仅代表添加到正在进行的对话中的新文本。

在 rolling_tokens 模式下触发重新计算时，会将保存的历史对话重新计算和缓存，与新输入内容一样计费。

缓存输入（元/千 token）：缓存中使用的内容。方舟自动处理历史记录，并输入给模型，这部分内容即缓存输入内容，他们也会产生费用，但是减少了计算和存储开销，计费费率会显著低于新输入内容。

存储（元/千 token/小时）：历史对话存储在 Session 缓存中，会产生存储费用。计算方式根据每个自然小时使用缓存的最大量乘以单价进行累加。

举例说明（单价仅为举例使用）：单价为 0.000017 元/千 token/小时，第 1 小时 Session 缓存最大的缓存用量 10k token，第 2 小时 Session 缓存最大的缓存用量 15k token，那么存储费用为：

0.000017*10+0.000017*15 = 0.000425 元

注意

在 Session 缓存创建即产生，直到该 Session 缓存被删除（一直未被使用，达 TTL 被删除），停止计费。

存储费用在每个自然小时如 8:00，9:00 等整点出账，不足 1 小时按照 1 小时计算。

输出（元/千 token）：模型根据输入信息生成的内容。计费方式与未使用 Session 缓存的调用方式一致。

下面介绍对于使用特定缓存的请求（创建缓存后特定的某个 Context ID）的计费逻辑。

每次调用计费用量可在返回的usage结构体看到。

其中，各个字段含义：

prompt_tokens：此次请求输入给模型处理的总的 token 数。

completion_tokens：此次请求模型回复的 token 数，即输出的 token 量，对应的计费项为输出。

total_tokens：此次请求，总共使用的 token 数。

prompt_tokens_details.cached_tokens：此次请求，缓存输入的 token 量，对应计费项缓存输入。

其中费用计算重要数据。

输入 token 量：可以通过prompt_tokens- cached_tokens来获得。

存储费用：每个自然小时计算，该小时内cached_tokens的最大值。如果该小时未请求及变更缓存，则取上个小时cached_tokens的最大值，以此类推。

某缓存涉及的费用分为请求产生的 token 费用和存储费用，计算逻辑如下：

自然小时：以实际整点为准，举例缓存存储从 13:59开始，到14:00 时，会被计算为第 1小时。

工作原理

请参见 Session 缓存。

前缀缓存教程

快速跳转至上下文缓存(Context API)

使用前缀缓存可以降低模型调用的成本。您可以预先存储常用信息如角色、背景等信息作为初始化信息，后续调用模型时无需重复发送此信息给模型，降低开销和成本，尤其适用于具有重复提示或标准化开头文本的应用。

快速开始

Curl

Python

Java

1.创建前缀缓存

使用前缀缓存前，您需要调用创建上下文缓存 API 创建缓存，并写入初始信息。后续只要在上下文缓存对话 API 中引入此缓存，即可让方舟为您保留初始信息以及享受使用缓存带来的费用折扣。

其中：

$ARK_API_KEY替换为您的 API Key，或者配置 API Key 至环境变量。

<YOUR_ENDPOINT_ID>替换为您的推理接入点 ID。

"ttl":3600代表前缀缓存 TTL，当前为 3600 秒。

"mode": "common_prefix"代表使用的前缀缓存模式。

模型回复预览：

返回的创建的前缀缓存的基本信息，其中<YOUR_CONTEXT_ID>是创建的前缀缓存的 ID，格式类似ctx-****，需要记录并在后面请求模型推理服务时使用。

2.使用前缀缓存进行对话

我们使用接口，来进行使用前缀缓存的对话。

其中。

$ARK_API_KEY替换为您的 API Key，或者配置 API Key 至环境变量。

<YOUR_CONTEXT_ID>替换为之前创建的缓存 ID。

<YOUR_ENDPOINT_ID>替换为您的推理接入点 ID。

模型回复预览。

支持的模型

请参见文档上下文缓存。

使用限制

与 Session 缓存不同，前缀缓存支持并发调用。

不支持 Partial 模式（又称 Prefill Response），调用上下文缓存对话 API 时，messages数组的最后一条消息的role字段取值可以是user或system，而不能为assistant。

正例：

"messages":[
{"role":"user","content":"你是谁"},
{"role":"assistant","content":"我是李雷"},
{"role":"user","content":"今天天气如何"}
],

当前前缀缓存过期时长可配置范围在1小时到7天，即ttl字段设置范围（单位：秒）为 [3600, 604800]。具体字段配置说明，请参见请求体。

前缀缓存当前只支持在线推理，不支持与批量推理一起使用。

如果您需要使用Java来调用模型推理服务，您可以使用方舟的 Java SDK 来很方便使用前缀缓存。

计费说明

计费单价请参见：后付费（按tokens使用量付费）。

计费项

计费逻辑

与 Session 缓存类似，前缀缓存采用透明的计费方式，基于以下四个关键因素：

输入（元/千 token）：输入 tokens 代表发送给大语言模型的新文本，不包括缓存的前缀。

输出（元/千 token）：输出标记代表大语言模型生成的文本。输出标记的计费与标准大语言模型使用方式一致。

缓存输入（元/千 token）：每次从前缀缓存中检索标记都会产生缓存输入费用。此费用通常低于输入标记费用。

存储（元/千 token/小时）：存储费用按小时计费，基于每个自然小时内所有前缀存储的最大标记数。存储费用将持续到前缀的生存时间 (TTL) 到期。

您发起带前缀缓存的请求时，会因为下面行为产生费用：

新的输入。

缓存输入。

模型生成的输出。

初始信息存储费用（按存储信息大小以及小时计费）。

每次调用模型服务的用量，除了存储初始信息的费用，均可在返回的usage结构体看到。

其中，各个字段含义：

prompt_tokens：此次请求输入给模型处理的总的 token 数。

completion_tokens：此次请求模型回复的 token 数，即输出的 token 量，对应的计费项为输出。

total_tokens：此次请求，总共使用的 token 数。

prompt_tokens_details.cached_tokens：此次请求模型的缓存输入的 token 量，对应计费项缓存输入。

其中费用计算重要数据。

输入 token 量：可通过prompt_tokens- cached_tokens来获得。

存储费用：每个自然小时计算cached_tokens的值。

某缓存涉及的费用分为请求产生的 token 费用和存储费用，计算逻辑如下：

存储自然小时数：和存储时长可能存在差异，以实际整点为准，举例缓存存储从 13:59开始，到14:00 时，会被计算为 1 小时。

成本优化技巧：分析初始信息的使用频率，合理配置缓存生存时间（ttl），平衡缓存收益和存储支出。

工作原理

请参见文档前缀缓存。

最近更新时间：2026.09.22 16:53:08

这个页面对您有帮助吗？

有用

无用