文档中心

火山方舟

上下文缓存 API

创建上下文缓存 API

POST https://ark.cn-beijing.volces.com/api/v3/context/create 运行

上下文缓存（Context API）是方舟提供的一个高效的缓存机制。它通过缓存上下文数据，减少重复加载或处理，提高响应速度和一致性。本文介绍上下文缓存 API 的输入输出参数，供您使用接口时查阅字段含义。

快速入口

鉴权说明

计费说明

API Key

支持模型

调用教程

开通模型

请求参数

跳转响应参数

请求体

model string 必选

通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考获取 Endpoint ID。

暂不支持通过 Model ID 来调用。

messages object[] 必选

对话组成的消息列表。您希望缓存的信息。

注意：初始化的信息如系统人设，背景信息等，请使用系统消息（System message）放在消息列表最前。这部分信息在2种缓存模式下，均会一直存储在缓存中，直到缓存到期（触达最大生命周期）释放。

属性

系统消息 object

系统消息，开发人员提供的指令，模型应遵循这些指令。如模型扮演的角色或者目标等。

属性

messages.role string 必选

发送消息的角色，此处应为system。

messages.content string 必选

系统信息内容。

用户消息object

用户发送的消息，包含提示或附加上下文信息。

属性

messages.role string 必选

发送消息的角色，此处应为user。

messages.content string 必选

用户信息内容。

messages.name string

发送此消息的角色的姓名。用于区别同一个角色但是不同主体发送的消息。

模型消息 object

模型响应用户消息而回复的消息。

说明

messages.content 与 messages.tool_calls 字段二者至少填写其一。

messages.role string 必选

发送消息的角色，此处应为assistant。

messages.content string

模型回复的消息。

messages.tool_calls object[]

模型回复的工具调用信息。

属性

messages.tool_calls.function object 必选

模型调用工具对应的函数信息。

属性

messages.tool_calls.function.name string 必选

模型需要调用的函数名称。

messages.tool_calls.function.arguments string 必选

模型生成的用于调用函数的参数，JSON 格式。

说明

模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。

messages.tool_calls.id string 必选

调用的工具的 ID。

messages.tool_calls.type string 必选

工具类型，当前仅支持function。

mode string 默认值 session

本次请求创建的上下文缓存的类型。点此了解类型介绍。点此了解支持的模型。

session ：Session 缓存。

common_prefix ：前缀缓存。

ttl integer / null 默认值 86400

过期时长，单位为秒，设置范围：[3600, 604800]，即1小时到7天。

信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。

truncation_strategy object / null 默认值 null

缓存的上下文长度的窗口长度策略配置，只在当 mode 字段设置为session，该字段可设置。

支持 Session 缓存的模型能且只能支持 1 种 Session 缓存模式。如不配置该字段，方舟会根据您调用的模型自动适配合适的 Session 缓存模式。

属性

last_history_tokens 模式 object

触发缓存上限不会重新计算。

属性

truncation_strategy.type string 必选

此处应为 last_history_tokens。

truncation_strategy.last_history_tokens integer 默认值 4096

取值范围：(0,32768)。

缓存上下文窗口大小，即可缓存的上下文的最大 token 数。触发该上限将根据缓存上下文窗口大小对缓存内容进行清除。清除顺序按照信息被缓存时间长短排序，先清除缓存时间长的信息。

rolling_tokens 模式 object

触发缓存上限会进行重新计算。

属性

truncation_strategy.type string 必选

此处应为 rolling_tokens。

truncation_strategy.rolling_tokens boolean 默认值 true

在缓存中历史消息长度接近 max_window_tokens 字段值时，是否自动对历史上下文进行裁剪（按照 message 元素粒度裁剪，按照 message 元素取整，即删除的信息的长度在 rolling_window_tokens 范围内，不会截断任意信息）。

false：在历史消息长度超过上下文长度时模型会停止输出（返回字段 finish_reason 为length)。

true：在历史消息长度接近上下文长度时模型按照先进先出的顺序，自动删除定量（rolling_window_tokens 字段值 token 数）的内容，为新对话内容腾挪缓存空间；同时对缓存中的信息进行重新计算和读入，保障内容理解一致性。具体的计算逻辑，请参见 rolling_tokens 模式。

truncation_strategy.max_window_tokens integer / null 默认值 32768

在缓存中可存储的历史消息长度最大值。

取值满足下面条件：0 < rolling_window_tokens < max_window_tokens < context window（模型最大上下文）。

truncation_strategy.rolling_window_tokens integer / null 默认值 4096

当缓存触发了max_window_tokens 上限，则会裁剪滚动窗口长度。

取值满足下面条件：0 < rolling_window_tokens < max_window_tokens < context window（模型最大上下文）。

响应参数

跳转请求参数

id string

本次请求创建的上下文缓存的ID，在后续创建带缓存的上下文缓存对话 API 需要使用。

model string

本次请求使用的推理接入点的 ID 。

mode string

本次请求创建的上下文缓存的类型。点此了解支持的模型。

session ：Session 缓存。

common_prefix ：前缀缓存。

ttl integer

本次请求创建的上下文缓存过期时长，单位为秒。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。

过期时间可以设置的范围在1小时到7天，即[3600, 604800]。

truncation_strategy object

本次请求创建的 Session 缓存使用的截断策略信息。

属性

last_history_tokens 模式 object

触发缓存上限，自动滚动缓存内容，无需重新计算。

属性

truncation_strategy.type string

本次请求创建的 Session 缓存的截断策略，此处应为 last_history_tokens。

truncation_strategy.last_history_tokens integer

本次请求创建的 Session 缓存可缓存的最大 token 数。

rolling_tokens 模式 object

触发缓存上限，进行重新计算。

属性

truncation_strategy.type string

本次请求创建的 Session 缓存的截断策略，此处应为 rolling_tokens。

truncation_strategy.rolling_tokens boolean

本次请求创建的 Session 缓存，当缓存的信息量达到最大缓存窗口时，是否自动处理。

usage object

本次请求的 token 用量。

属性

usage.prompt_tokens integer

输入的 prompt token 数量。

usage.completion_tokens integer

模型生成的 token 数量。

usage.total_tokens integer

本次请求消耗的总 token 数量（输入 + 输出）。

usage.prompt_tokens_details object

命中上下文缓存的 token 细节。

属性

usage.prompt_tokens_details.cached_tokens integer

命中上下文缓存的 token 数。

创建前缀缓存

创建 Session 缓存

Request

curl https://ark.cn-beijing.volces.com/api/v3/context/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d $'{
    "messages": [
        {
            "content": "你是李雷，你只会说“我是李雷”",
            "role": "system"
        }
    ],
    "mode": "common_prefix",
    "model": "ep-20250410*****-*****"
}'

Response

{
  "id": "ctx-20250410175333-lkjq2",
  "model": "ep-20250410*****-*****",
  "ttl": 86400,
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 0,
    "total_tokens": 18,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "mode": "common_prefix"
}

最近更新时间：2026.09.17 13:38:24

这个页面对您有帮助吗？

有用

无用