Session 缓存（Session Cache，会话级别的缓存），是针对模型性能和成本的优化。它将Session中的上下文（Context）进行缓存（Caching），在多轮对话等场景中，可以减少计算和存储重复内容的开销。您开通 Session 缓存后，在多轮对话场景下模型的服务可以达到更低的时延，同时对于缓存中的内容使用也会给予您一定的折扣，进一步降低您使用模型推理服务的成本。

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

您可以在以下场景中使用 Session 缓存。

基本流程

Session 缓存保存Context（上下文，通常指历史的对话记录），同时在后续的对话中复用这部分信息。简要的工作流程如下图所示：

1. 创建一个会话级上下文缓存，唯一的Context ID 作为键（Key），方舟缓存会话上下文信息至关联的值（Value）。
2. 方舟收到新请求时，会根据请求的Context ID匹配缓存中的上下文信息（历史对话）。
3. 方舟只需计算和存储新输入的信息，再结合缓存中的上下文信息，交由模型推理。
4. 模型输出回复信息，并将回复信息添加到Session缓存中，供下次请求时使用。

触发缓存上限

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

last_history_tokens模式

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

rolling_tokens模式

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

1. 清除Session 缓存 B长度的陈旧消息（初始消息不会删除，即在创建session 缓存时的信息不会删除），为后续新的消息腾挪存储空间。
2. 重新计算缓存中历史信息，以确保模型回复具有一致且连贯的理解。

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

触发过期时间

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

举例：您设置了Session 缓存的TTL 为2小时，Context，其中A 2个小时没被命中，B 中途1小时时刻命中。当前，A会被从缓存中删除，B TTL还有1小时。

计费单价请参见：模型服务计费。

{
    ...
    "usage": {
        "prompt_tokens": 20,
        "completion_tokens": 8,
        "total_tokens": 28,
        "prompt_tokens_details": {
          "cached_tokens": 10
      }
  }

= 输入花费 + 命中花费 + 输出花费 + 存储花费 
= (prompt_tokens-cached_tokens) * 输入单价  
 + cached_tokens * 命中单价 
 + completion_tokens * 输出单价 
 + Max(cache_window_tokens) * 存储单价

当前支持 Session 缓存的模型如下。

last_history_tokens模式

支持last_history_tokens模式的模型

rolling_tokens模式

支持rolling_tokens模式的模型

• 您已有方舟 API Key，作为模型推理服务调用鉴权使用。如无，请参考1.获取 API Key。
• 您已创建推理接入点，其中模型请选择视语言类大模型。如无，请参考2.创建在线推理接入点（Endpoint）。
• 已开通上下文缓存功能，访问开通页面开通服务。

1.创建 Session 缓存

使用 Session 缓存前，您需要调用ContextCreate-创建上下文缓存接口创建缓存，并写入初始信息。后续只要在ContextChatCompletions-上下文缓存对话接口中引入此缓存，即可让方舟为您管理历史对话以及享受缓存命中带来的性能加速和费用折扣。

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":"你是李雷，你只会说“我是李雷”"}
     ], 
     "ttl":3600, 
     "mode": "session"
}'

其中：

• <YOUR_API_KEY>替换为您的API Key。
• <YOUR_ENDPOINT_ID>替换为您的推理接入点ID。
• "ttl":3600代表 Session 缓存 TTL，当前为 3600 秒。
• "mode": "session"代表使用的 Session 缓存模式。

模型回复预览

{
    "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
        }
    }
}

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

2.使用 Session 缓存 进行对话

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

curl --location 'https://ark.cn-beijing.volces.com/api/v3/context/chat/completions' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "context_id": "<YOUR_CONTEXT_ID>",
    "model": "<YOUR_ENDPOINT_ID>",
    "messages":[
        {
            "role":"user",
            "content": "你好"
        }
    ]
}'

其中

• <YOUR_API_KEY>替换为您的API Key。
• <YOUR_CONTEXT_ID>替换为之前创建的 Session缓存 ID。
• <YOUR_ENDPOINT_ID>替换为您的推理接入点ID。

模型回复预览

{
  "id": "****",
  "object": "chat.completion",
  "created": 167765****,
  "model": "<YOUR_ENDPOINT_ID>",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "我是李雷。",
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
 "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 5,
    "total_tokens": 33,
    "prompt_tokens_details": {
      "cached_tokens": 18
  }
}

• 上下文缓存API为有状态API，不支持并发调用。
• 不支持 Partial 模式（又称Prefill Response），即messages数组中的最后一条消息role可以是user或system，而不能为assistant。

控制 Session 缓存上限

仅last_history_token模式支持。

您可以自行控制缓存上限。根据需要选择适合的缓存上限，可以保障命中的 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":"你是李雷，你只会说“我是李雷”"}
     ], 
     "ttl":3600, 
     "mode": "session"
     {
     "truncation_strategy":{
         "type": "last_history_tokens",
         "last_history_tokens": 4096
    }
}'

其中：

• <YOUR_API_KEY>替换为您的API Key。
• <YOUR_ENDPOINT_ID>替换为您的推理接入点ID。
• "ttl":3600代表 Session 缓存 TTL，当前为 3600 秒。
• "mode": "session"代表使用的 Session 缓存模式。
• "type":"last_history_tokens"代表使用了last_history_tokens模式。
• "last_history_tokens": 4096 代表缓存最大长度为为 4096 个token，您根据自己的业务情况调整值大小。

手动管理 Session 缓存

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

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":"你是李雷，你只会说“我是李雷”"}
     ], 
     "ttl":3600, 
     "mode": "session",
     "truncation_strategy":{ 
         "type":"rolling_tokens", 
         "rolling_tokens": false 
         }
}'

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

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

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

• ContextCreate-创建上下文缓存
• ContextChatCompletions-上下文缓存对话