在隐式缓存模式下，通过在请求 Header 中设置 `X-Prompt-Cache-Id`，取值相同的请求会优先路由到缓存命中率更高的服务，从而提升缓存命中率。

说明

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

# 支持模型与 API * 支持模型：`doubao-seed-2.0` 及之后系列模型。 * 支持 API：[Chat API](https://docs.volcengine.com/docs/88760/2647396)、[Responses API](https://docs.volcengine.com/docs/88760/2647398)。 # 工作原理

说明

工作机制 ：系统将 X-Prompt-Cache-Id 作为会话级路由提示，并按 Endpoint、模型与该取值隔离路由映射。该能力采用尽力而为的亲和策略，不承诺固定实例，也不保证每次请求都能命中缓存。

1. **首次请求** ：系统按常规路由策略选择可用服务，并建立该取值对应的路由映射。 2. **后续请求** ：相同 Endpoint、模型与 `X-Prompt-Cache-Id` 组合的请求会优先路由到已映射的服务，以提高相同前缀的缓存复用概率。 3. **自动回退** ：当已映射服务不可用、请求速率超过保护阈值或其他保护条件触发时，请求会回退到常规路由。 # 使用限制 * **流量限制** ：同一 `X-Prompt-Cache-Id` 取值对应的请求总流量应控制在每分钟 15 个请求以内。速率过高时，部分请求可能回退到常规路由，从而无法复用原服务上的前缀缓存。高流量工作负载建议将流量稳定地分散到更多取值上。 * **保持稳定** ：上下文连续的请求建议使用同一取值，避免在同一会话中频繁更换。 * **隔离会话** ：不同用户或并行会话应使用不同取值，避免无关请求共享路由映射并形成热点。 * **避免敏感信息** ：建议使用不可读的内部 Session ID，不要使用手机号、邮箱、访问凭证或 Prompt 原文。 * **非强一致保证** ：服务扩缩容、发布、故障切换、映射过期或保护策略触发时，请求可能被重新路由，缓存命中率可能短暂波动。 # 使用方式在请求 Header 中设置 `X-Prompt-Cache-Id`，并确保上下文连续的请求使用同一取值（例如按内部 Session ID 设置），以提升缓存命中率。以 Chat API 为例，示例如下： Python ```Python import os from volcenginesdkarkruntime import Ark client = Ark( api_key=os.environ.get("ARK_API_KEY"), base_url="https://ark.cn-beijing.volces.com/api/v3", ) completion = client.chat.completions.create( model="doubao-seed-2-1-pro-260628", messages=[ {"role": "user", "content": "Hello"}, ], extra_headers={"X-Prompt-Cache-Id": ""}, ) print(completion.choices[0].message.content) ``` Java ```Java package com.example; import com.volcengine.ark.runtime.model.completion.chat.ChatCompletionRequest; import com.volcengine.ark.runtime.model.completion.chat.ChatMessage; import com.volcengine.ark.runtime.model.completion.chat.ChatMessageRole; import com.volcengine.ark.runtime.service.ArkService; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; public class ChatCompletionsWithPromptCacheId { public static void main(String[] args) { String apiKey = System.getenv("ARK_API_KEY"); ArkService arkService = ArkService.builder().apiKey(apiKey).baseUrl("https://ark.cn-beijing.volces.com/api/v3").build(); List messages = new ArrayList<>(); messages.add(ChatMessage.builder().role(ChatMessageRole.USER).content("Hello").build()); ChatCompletionRequest request = ChatCompletionRequest.builder() .model("doubao-seed-2-1-pro-260628") .messages(messages) .build(); Map customHeaders = new HashMap<>(); customHeaders.put("X-Prompt-Cache-Id", ""); arkService.createChatCompletion(request, customHeaders).getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); arkService.shutdownExecutor(); } } ``` Go ```Go package main import ( "context" "fmt" "os" "github.com/volcengine/volcengine-go-sdk/service/arkruntime" "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model" "github.com/volcengine/volcengine-go-sdk/volcengine" ) func main() { client := arkruntime.NewClientWithApiKey( os.Getenv("ARK_API_KEY"), arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), ) ctx := context.Background() req := model.CreateChatCompletionRequest{ Model: "doubao-seed-2-1-pro-260628", Messages: []*model.ChatCompletionMessage{ { Role: model.ChatMessageRoleUser, Content: &model.ChatCompletionMessageContent{ StringValue: volcengine.String("Hello"), }, }, }, } resp, err := client.CreateChatCompletion( ctx, req, arkruntime.WithCustomHeader("X-Prompt-Cache-Id", ""), ) if err != nil { fmt.Printf("chat completion error: %v\n", err) return } fmt.Println(*resp.Choices[0].Message.Content.StringValue) } ```

火山方舟