prompt_cache_key 与 X-Session-ID 用法：TokenHub Cache 优化两大字段

摘要：

prompt_cache_key 和 X-Session-ID 是 TokenHub 提升 Prompt Cache 命中率的两个关键字段。前者是请求体内的逻辑标识，后者是 HTTP Header 中的路由标识。本文逐一拆解两者的语义、写法、最佳实践与组合用法，帮你写出真正能复用 KV Cache 的请求。

一、为什么是这两个字段

接入 TokenHub 时，开发者经常会问："我的 messages 长得一模一样，为什么命中率上不去？"答案往往不在 messages 本身，而在请求外侧的两个标识字段：prompt_cache_key 和 X-Session-ID。

它们解决的是两个不同维度的问题：

两者缺一不可。逻辑上声明了能复用，但物理上请求被分散到了不同实例，命中率依然上不去；物理上路由稳定了，但缓存系统没拿到统一标识，也没法判断哪些前缀可以拼到同一棵 KV 树上。

二、prompt_cache_key：请求体里的逻辑标识

2.1 字段定位

prompt_cache_key 是请求级别的缓存标识字段，TokenHub 的官方解释是"告诉缓存系统哪些请求的前缀相同，可复用 KV Cache"。

2.2 核心赋值原则

官方给出的原则只有一句：赋值为整体上下文总 ID（conversation_id），而非单一会话 ID（session_id）。

很多团队第一次接入会把 session_id 直接填进去，这样做表面没错，但当一个对话跨了多个 session（比如断网重连、跨设备同步、轮询断流重连），就会出现"同一对话被切成多个独立缓存"的尴尬。conversation_id 才是把整个对话生命周期串起来的唯一标识。

2.3 完整写法示例

{
  "model": "hy3-preview",
  "prompt_cache_key": "conv-6900xxxx",
  "messages": [
    {"role": "system", "content": "你是一个助手..."},
    {"role": "user", "content": "你好"}
  ]
}

2.4 三条最佳实践

a. 同一对话上下文的所有请求使用相同的 prompt_cache_key

b. 不同对话使用不同的 prompt_cache_key，避免缓存污染

c. 值建议使用业务侧的 conversation_id 或等价的全局唯一标识

第三条值得特别强调：业务系统里通常已经有一个 conversation_id，直接复用它就好，没必要额外发明一套缓存键。这样既能保证唯一性，又方便日志排查。

三、X-Session-ID：HTTP Header 里的路由标识

3.1 字段定位

X-Session-ID 通过 HTTP Header 传递会话标识，作用是"把同一用户的连续请求路由到同一推理实例，提高该实例上的 KV Cache 局部命中率"。

注意它不是请求体字段，是 Header 字段，写错位置会被忽略。

3.2 完整 cURL 示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'X-Session-ID: session-abc123' \
  -d '{"model": "your-model", "messages": [...]}'

3.3 两条最佳实践

a. 同一用户的多轮对话保持 X-Session-ID 不变

b. 不同用户或不同对话上下文使用不同 Session ID

3.4 值的设计建议

X-Session-ID 与 prompt_cache_key 的语义粒度可以不一样：

• prompt_cache_key 推荐用 conversation_id（对话级别）
• X-Session-ID 可以用 session_id 或 user_id（会话/用户级别）

实际工程里常见做法是：X-Session-ID 用一个能稳定标识"一次连续交互"的值，prompt_cache_key 用更上层的对话主键。两者层级不同，互不冲突。

四、两者协同：1 + 1 大于 2

官方文档明确写道："配合 prompt_cache_key 一起使用效果更佳。"原因不难理解：

a. 仅有 X-Session-ID：请求被路由到同一实例，但缓存系统不知道哪些请求该共享前缀

b. 仅有 prompt_cache_key：缓存系统知道复用关系，但请求可能落到不同实例上，本地缓存里根本没有对应 KV

c. 两者都有：路由稳定 + 缓存复用语义清晰，命中率自然爬升

下面这张表把"该填什么、填到哪、填什么值"一次性说清：

五、容易踩的坑

5.1 把 prompt_cache_key 当随机串

有团队为了"防冲突"给每个请求都生成一个 UUID 当 prompt_cache_key，结果命中率始终为 0。这恰恰违反了字段的设计本意——它的作用是"声明可复用"，不是"声明唯一"。

5.2 把 X-Session-ID 写到 Body 里

HTTP Header 与请求 Body 是两套位置，写在 Body 里会被忽略，缓存系统接收不到路由提示。

5.3 同一对话切换 prompt_cache_key

有些系统在多轮对话中会动态生成 key，比如把当前轮次拼到 key 里（conv-6900-turn-3）。这会让缓存系统认为每一轮都是新对话，前缀复用直接失效。

5.4 在 system prompt 里塞动态时间

比如把"今天是 2026 年 5 月 9 日"写在 system 里。即使 prompt_cache_key 和 X-Session-ID 都填对了，零点一过整张缓存就失效。正确做法是把时间放在 user message 里。

六、验证你写得对不对

调试期间最快的验证方式是发两组请求做对比：

a. 第一组：相同 messages，不传任何缓存字段，记录 TTFT 和 prompt_tokens

b. 第二组：相同 messages，按本文方式带上 prompt_cache_key 与 X-Session-ID，连续多发几次，记录 TTFT 与缓存命中输入 Token 数

如果第二组的 TTFT 明显下降、缓存命中输入 Token 占总输入 Token 的比例上升，说明你的接入是对的。

TokenHub 控制台的"用量统计"页面可以按模型、服务、API Key 维度查看缓存命中输入 Token 的具体数量，是验证效果的最权威入口。

七、零成本练手

新人开通 TokenHub 即可领取覆盖几乎全部主力模型的免费体验包，支持 Cache 缓存的 Hy3 preview、DeepSeek-V4-Pro、DeepSeek-V4-Flash、GLM-5.1、Kimi-K2.6、MiniMax-M2.7 等都在赠送范围内，有效期 90 天，足够把 prompt_cache_key 和 X-Session-ID 的接入跑完一个完整循环。

新人免费体验包详情：https://cloud.tencent.com/document/product/1823/130053。

结语

prompt_cache_key 管"逻辑复用"，X-Session-ID 管"物理路由"，两个字段配合到位，Prompt Cache 才能真正发挥出 1/4~1/10 价格的成本优势。完整字段说明、TTL 机制、Request 结构原则与发版预热建议，请查阅官方完整指南：https://cloud.tencent.com/document/product/1823/131410。