Skip to main content
Poixe 实现了一套 缓存亲和性路由（Cache Affinity Routing） 机制，用于提高上游 API 的缓存命中率，从而降低实际计费成本。

​
背景

主流模型厂商（OpenAI、Anthropic 等）均提供了 Prompt Caching 能力：当连续请求的前缀内容相同或主动标记缓存时，上游会复用已缓存的计算结果，对缓存命中部分给予折扣计费。 但缓存有一个关键约束：缓存绑定在具体的渠道（API Key / 账户）上，不能跨渠道共享。 在聚合网关场景下，Poixe 后端接入了多个上游渠道，默认由权重负载均衡模块分配请求。这意味着同一个用户的连续请求可能被分发到不同渠道，导致上游缓存频繁失效。 缓存亲和性路由正是为了解决这个问题。

​
工作原理

1

首次请求

用户请求某个模型（如 claude-opus-4-6），系统按正常权重逻辑分配到某个上游渠道，请求成功后，系统记录下这个绑定关系：用户 + 模型 → 渠道。
2

后续请求

在绑定有效期内，该用户对同一模型的后续请求会 优先路由到同一渠道，使上游缓存得以复用。
3

绑定失效

当绑定关系失效后，系统回退到默认的权重负载均衡逻辑，重新分配渠道。

​
绑定失效条件

绑定关系是短暂且脆弱的，满足以下任一条件即自动解除：
绑定失效不会导致请求失败。系统会立即回退到权重负载均衡，正常处理请求。
为什么速率不足时主动拒绝亲和？ 若对速率已告急的渠道继续建立亲和，下次请求极易触发速率限制，进入重试阶段，导致延迟显著增加甚至请求失败。系统以请求健康度优先于缓存成本为原则，在此场景下主动放弃亲和。

​
适用范围

缓存亲和性路由 不是对所有模型生效，仅对以下协议和厂商的特定模型启用：
该列表会随上游厂商的缓存策略调整而更新。不在列表中的模型走默认负载均衡，不受影响。

​
实际节省效果

以下是一个 Claude Code + claude-opus-4-6 的真实请求示例，展示缓存命中对费用的影响：
命令行终端打开 claude，多次对话输入 hi，触发对话请求。上游实际计费的 token 数如下：这是一次典型的 Claude Code 对话请求——绝大部分 prompt 内容（系统提示、项目上下文、历史对话）在前次请求中已被缓存，本次直接命中。

单次节省

86%
$0.1335 → $0.0185

缓存命中价

1/10
$5.00 → $0.50 / MTok

Claude Code 场景

~90%+
连续对话中 prompt 缓存命中率
在 Claude Code 的典型工作流中，每轮对话都会携带完整的系统提示和项目上下文（通常 20K~100K tokens），这些内容在连续请求间几乎不变。缓存亲和性路由确保这些请求尽可能命中同一渠道的缓存，将这部分 tokens 的单价从 $5/MTok 降至 $0.50/MTok。

​
设计取舍

缓存亲和性路由本质上是在 缓存命中率 和 流量均衡 之间做权衡：
  • 短 TTL + 次数上限：避免流量长期集中在单一渠道，防止负载倾斜
  • 错误即解绑：避免将后续请求持续路由到已异常的渠道
  • 尽力而为：亲和路由是优化手段而非硬性保证，任何环节失败都会静默回退到默认逻辑

​
对用户的影响

  • 无需任何配置，系统自动生效
  • 在编程助手（Claude Code、Codex 等）场景下，连续对话的缓存命中率会显著提升
  • 缓存命中时，上游按折扣价计费，Poixe 的扣费同步降低

​
对供应商的建议

建议为模型渠道部署速率足够高的账号。速率不足的账号存在以下连锁风险：
  • 某次请求完成后，系统因渠道速率告急而拒绝建立亲和，导致接下来最多 100 次连续请求的缓存机会全部浪费
  • 从数据面来看，低速率账号与高速率账号之间，最坏情况下可产生接近 100 倍的有效缓存流量差异
100 倍差异的来源：单次亲和绑定最多可承载 100 次请求。若速率不足导致亲和未建立，则这 100 次请求均回退到默认负载均衡，无法持续命中同一渠道缓存；而速率充足的账号可完整利用这 100 次窗口，两者在缓存利用率上的最大差距即为 ~100 倍。

​
上游缓存机制参考

OpenAI Prompt Caching

OpenAI 官方 Prompt Caching 文档，包含缓存规则与计费说明

Anthropic Prompt Caching

Anthropic 官方 Prompt Caching 文档，包含缓存规则与计费说明