POST https://ark.cn-beijing.volces.com/api/v3/context/create [运行](https://api.volcengine.com/api-explorer/?action=ContextCreate&data=%7B%7D&groupName=%E4%B8%8A%E4%B8%8B%E6%96%87%E7%BC%93%E5%AD%98&query=%7B%7D&serviceCode=ark&version=2024-01-01) 上下文缓存（Context API）是方舟提供的一个高效的缓存机制。它通过缓存上下文数据，减少重复加载或处理，提高响应速度和一致性。本文介绍上下文缓存 API 的输入输出参数，供您使用接口时查阅字段含义。 ```mixin-react return ( ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fdd3028d35cc512a10bd71b982b6eb.png =20x) [计费说明](https://www.volcengine.com/docs/82379/1099320#%E4%B8%8A%E4%B8%8B%E6%96%87%E7%BC%93%E5%AD%98%E8%AE%A1%E8%B4%B9) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_afbcf38bdec05c05089d5de5c3fd8fc8.png =20x) [API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png =20x) [支持模型（ Session 缓存）](https://www.volcengine.com/docs/82379/1396491#%E6%94%AF%E6%8C%81%E7%9A%84%E6%A8%A1%E5%9E%8B) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57d0bca8e0d122ab1191b40101b5df75.png =20x) [调用教程](https://www.volcengine.com/docs/82379/1398933) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bef4bc3de3535ee19d0c5d6c37b0ffdd.png =20x) [开通模型](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png =20x) [支持模型（前缀缓存）](https://www.volcengine.com/docs/82379/1396490#%E6%94%AF%E6%8C%81%E7%9A%84%E6%A8%A1%E5%9E%8B) `}> 如需使用 Access Key 来鉴权，推荐使用 SDK 的方式，具体请参见 [SDK概述](https://www.volcengine.com/docs/82379/1302007)。 `}>); ``` --- ## 请求参数 > 跳转 [响应参数](#Qu59cel0) ### 请求体 * **model** `string` `必选` 您需要调用的模型的 ID （Model ID），[开通模型服务](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)，并[查询 Model ID](https://www.volcengine.com/docs/82379/1330310) 。您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考[获取 Endpoint ID](https://www.volcengine.com/docs/82379/1099522#f948f953)。 * messages object[] `必选` 对话组成的消息列表。您希望缓存的信息。注意：初始化的信息如系统人设，背景信息等，请使用系统消息（System message）放在消息列表最前。这部分信息在2种缓存模式下，均会一直存储在缓存中，直到缓存到期（触达最大生命周期）释放。 ```mixin-react return ( 开发人员提供的指令，模型应遵循这些指令。如模型扮演的角色或者目标等。 * messages.**role** string \`必选\` 发送消息的角色，此处应为system。 * messages.**content** string \`必选\` 系统信息内容。 `}> 用户发送的消息，包含提示或附加上下文信息。 * messages.**role** string \`必选\` 发送消息的角色，此处应为\`user\`。 * messages.**content** string \`必选\` 用户信息内容。 * messages.**name** string 发送此消息的角色的姓名。用于区别同一个角色但是不同主体发送的消息。 `}> 模型响应用户消息而回复的消息。 :::tip 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 格式。 :::tip 模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。 ::: * messages.tool_calls**.id** string \`必选\` 调用的工具的 ID。 * messages.tool_calls**.type** string \`必选\` 工具类型，当前仅支持function。 `}>); ``` * mode `string` `必选` 本次请求创建的上下文缓存的类型，[点此](https://www.volcengine.com/docs/82379/1398933)了解类型介绍。 * session ：Session 缓存，支持的模型请参见[支持的模型](https://www.volcengine.com/docs/82379/1396491#5f0f3750)。 * common_prefix ：前缀缓存，支持的模型请参见[模型列表](https://www.volcengine.com/docs/82379/1396490#5f0f3750)。 * ttl integer / null 默认值 86400 过期时长，单位为秒，设置范围：[3600, 604800]，即1小时到7天。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。 * truncation_strategy object / null 默认值 null 缓存的上下文长度的窗口长度策略配置，只在当 mode 字段设置为session，该字段可设置。支持 Session 缓存的模型能且只能支持 1 种 Session 缓存模式。如不配置该字段，方舟会根据您调用的模型自动适配合适的 Session 缓存模式。 ```mixin-react return ( truncation_strategy.type \`string\` \`必选\` 此处应为 last_history_tokens。 * truncation_strategy.last_history_tokens integer 默认值 4096 缓存上下文窗口大小，即可缓存的上下文的最大 token 数。触发该上限将根据缓存上下文窗口大小对缓存内容进行清除。清除顺序按照信息被缓存时间长短排序，先清除缓存时间长的信息。 `}> truncation_strategy.type \`string\` \`必选\` 此处应为 last_history_tokens。 * truncation_strategy.rolling_tokens boolean 默认值 true 在context历史消息长度接近模型上下文时，是否自动对历史上下文进行裁剪。 * \`false\`：在历史消息长度超过上下文长度时模型会停止输出（返回字段**finish_reason**为\`length\`)。 * \`true\`：在历史消息长度接近上下文长度时模型按照先进先出的顺序，自动删除定量（4096 token 数）的内容，为新对话内容腾挪缓存空间；同时对缓存中的信息进行重新计算和读入，保障内容理解一致性。具体的计算逻辑，请参见 [rolling_tokens 模式](https://www.volcengine.com/docs/82379/1396491#dc052059)。 `}>); ``` ## 响应参数 > 跳转 [请求参数](#RxN8G2nH) * **id** `string` 本次请求创建的上下文缓存的ID，在后续创建带缓存的[上下文缓存对话 API](https://www.volcengine.com/docs/82379/1346560)需要使用。 * **model** `string` 本次请求使用的推理接入点的 ID 。 * **mode** `string` 本次请求创建的上下文缓存的类型。 * session ：Session 缓存，支持的模型请参见[支持的模型](https://www.volcengine.com/docs/82379/1396491#5f0f3750)。 * common_prefix ：前缀缓存，支持的模型请参见[模型列表](https://www.volcengine.com/docs/82379/1396490#5f0f3750)。 * **ttl** `integer` 本次请求创建的上下文缓存过期时长，单位为秒。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。过期时间可以设置的范围在1小时到7天，即[3600, 604800]。 * **truncation_strategy** `object` 本次请求创建的 Session 缓存使用的截断策略信息。 * **last_history_tokens 模式** * truncation_strategy.**type** `string` 本次请求创建的 Session 缓存的截断策略，此处应为 `last_history_tokens`。 * truncation_strategy.**last_history_tokens** `integer` 本次请求创建的 Session 缓存可缓存的最大 token 数。 * **rolling_tokens 模式** * 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 数。

火山方舟大模型服务平台