ContextCreate-创建上下文缓存--火山方舟大模型服务平台-火山引擎

文档中心

导航

ContextCreate-创建上下文缓存

最近更新时间：2024.12.18 21:28:11首次发布时间：2024.09.24 11:09:26

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

创建上下文缓存，获得缓存 id字段后，在ContextChatCompletions-上下文缓存对话中使用。

API使用教程请参见上下文缓存（Context API）概述。

请求参数

请求体

字段	子字段	类型	是否必填	默认值	描述	示例值
model	-	string	是	-	大模型推理服务的接入点ID（Endpoint id）。通过文档创建推理接入点，您完成推理服务接入点创建，并根据业务需求配置大模型、购买方式、计费类型等信息。	`ep-xxx`
messages	-	list	是	-	由对话组成的消息列表。注意：Context Initial Messages，如系统人设，背景信息等，用户自定义的信息。这个信息用于初始化或希望服务在缓存中存储的信息，需拼接在chat前。 `[ {"role":"system","content":"you are a helpful asssistant"}, {"role":"user","content":"hello"} ]`	-
mode	-	string	是	session	上下文缓存的类型，详细见上下文缓存（Context API）概述。 `session` ：Session 缓存，支持的模型请参见支持的模型。 `common_prefix` ：前缀缓存，支持的模型请参见模型列表。	-
ttl	-	int	否	86400	过期时长，单位为秒。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。过期时间可以设置的范围在1小时到7天，即[3600, 604800]。	86400
truncation_strategy	-	object	否	-	控制历史上下文窗口。不设置会根据推理接入点调用的模型自动判断使用哪种模式的Session 缓存。当`mode`字段设置为`session`，该字段可设置。当`mode`字段设置为`common_prefix`，该字段不可设置。	-
	type	string	条件必填	-	用户截断的策略，对话会综合最近存储的历史token数、模型大小和chat时的`max_tokens`进行截断。 `last_history_tokens`：使用last_history_tokens模式，取决于使用的模型支持哪种Session 缓存。 `rolling_tokens`：使用rolling_tokens模式，取决于使用的模型支持哪种Session 缓存。	-
	last_history_tokens	int	否	4096	`type`设置为`last_history_tokens`时，进行设置。缓存存储的最大 token 数，触发该上限将根据模型上下文大小对缓存内容进行截断，截断顺序按照时间由远及近。 `{ "type": "last_history_tokens", "last_history_tokens": 12000 }`	-
	rolling_tokens	boolean	否	true	`type`设置为`rolling_tokens`时，进行设置。在context历史消息长度超过模型上下文时，是否自动对历史上下文进行裁剪。 `false`：在历史消息长度超过上下文长度时模型会停止输出（`finish_reason`为`length`时)。 `true`：在历史消息长度超过上下文长度时模型自动按照先进先出的顺序，删除定量的内容，为新对话内容腾挪缓存空间；同时对缓存中的信息进行重新计算和读入，保障内容理解一致性。 `{ "type": "rolling_tokens", "rolling_tokens": true }`	-

响应参数

请求响应

字段	子字段	类型	含义	示例值
id	-	string	您创建的上下文缓存ID，在后续创建带缓存的ContextChatCompletions-上下文缓存对话需要使用。	ctx-xxx
model	-	string	您的推理接入点ID。	ep-xxx
ttl	-	int	不活跃的时间所能达到最大时长，每次使用缓存均重置不活跃时间为0。单位为秒(second)	259200
truncation_strategy	-	object	控制历史上下文窗口策略。	-
	type	string	用户截断的策略，支持`last_history_tokens` 和`rolling_tokens`两种，取决于模型版本。	-
	last_history_tokens	int	历史存储的最大token数，默认为4096。根据模型上下文大小对历史存储截断。 `{ "type": "last_history_tokens", "last_history_tokens": 12000 }`	4096
	rolling_tokens	boolean	历史消息长度超过模型上下文时，是否自动对历史上下文进行裁剪若设置为true，在历史消息长度超过上下文长度时模型自动清除定量历史消息，并重新计算保持的消息。若设置为false，在历史消息长度超过上下文长度时模型会停止输出（finish_reason='length')。 `{ "type": "rolling_tokens", "rolling_tokens": true }`	true
usage	-	object	本次请求的 token 消耗情况。	-

请求示例

curl --location 'https://ark.cn-beijing.volces.com/api/v3/context/create' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{ 
    "model":"<YOUR_ENDPOINT_ID>", 
    "messages":[ 
        {"role":"system","content":"你是李雷，你只会说“我是李雷”"}
     ], 
     "mode":"session",
     "ttl":3600, 
     "truncation_strategy":{ 
         "type":"last_history_tokens", 
         "last_history_tokens": 4096 
         }
}'

响应示例

{
    "id": "<YOUR_CONTEXT_ID>",
    "model": "<YOUR_ENDPOINT_ID>",
    "ttl": "3600",
    "mode": "session",
    "truncation_strategy": {
            "type": "last_history_token",
            "last_history_token": 4096
            },
    "usage": {
        "prompt_tokens": 18,
        "completion_tokens": 0,
        "total_tokens": 18,
        "prompt_tokens_details": {
            "cached_tokens": 0
        }
    }
}

错误处理

错误响应

本接口调用失败的返回结构和参数释义请参见返回结构文档。

错误码

本接口错误码请参见公共错误码文档。