- 状态：已批准
- 日期：2026-04-14
- 关联模块：缓存智能管理
TokenRouter 的核心商业价值在于通过结构收敛降低 AI Token 调用成本。大模型厂商的缓存读取价格通常为正常价格的 1/10（如 Claude: $0.30 vs $3.00/MTok）。v2 架构采用 Envelope + Block 中间格式，通过 Chunker + Arranger + Canonicalizer 将请求标准化，再经 CacheInjector 注入厂商缓存标记，最大化厂商侧 KV Cache 命中率。
缓存需求分析：
| 需求 | 描述 | 数据特征 |
|---|---|---|
| 厂商侧 KV Cache | 通过前缀共享最大化 Anthropic/OpenAI 等厂商的缓存命中 | 前缀匹配、确定性 JSON |
| 请求去重 | 相同完整请求的并发复用 | 精确哈希、短 TTL |
| 元数据缓存 | 模型信息、定价、用户配额等 | 键值对、低频变更 |
候选方案：
| 方案 | 说明 | 优势 | 劣势 |
|---|---|---|---|
| 单一缓存层 | 统一用 Redis 做所有缓存 | 实现简单 | 无法针对不同场景优化、缓存策略冲突 |
| 多层缓存体系 | L1-L3 分层，每层解决不同问题 | 精准优化、策略独立、可独立演进 | 架构复杂度增加 |
选择 三层缓存体系（L1-L3），各层职责明确，可渐进式实施。
- 解决的问题：通过结构收敛（Chunker + Arranger + Canonicalizer）+ 缓存标记注入，最大化厂商侧的 KV Cache 命中率
- 存储：无本地存储，命中效果直接体现在厂商响应的
cache_read_tokens中 - 策略：
- Chunker 将请求切分为 System / Tool / History / Query Block
- Arranger 合并 System、排序 Tool、截断 History
- Canonicalizer 生成字节级确定性的 JSON
- CacheInjector 按厂商要求注入
cache_control等标记 - Hasher 对 System + Tool 计算前缀哈希，用于观测与聚类
- 命中效果：节省约 90% 的缓存 Token 费用
接口定义详见 ../CODE_WIKI.md，实现示例详见 ../modules/cache-intelligence.md。
- 解决的问题：非流式相同完整请求的并发复用，减少上游调用次数
- 存储：内存 map + 短 TTL（2 分钟）
- 策略：Canonicalizer 输出后计算
FullHash，相同 hash 的并发请求挂起等待首个请求返回后复用 - 命中效果：减少重复上游调用，降低延迟和成本
接口定义详见 ../CODE_WIKI.md，实现示例详见 ../modules/cache-intelligence.md。
- 解决的问题：模型列表、定价信息、用户配额等低频变更数据的本地缓存
- 存储：进程内 sync.Map + Redis 二级缓存
- TTL：5 分钟，主动失效
- 命中效果：减少数据库查询，降低请求延迟
| 阶段 | 缓存层 | 优先级 | 预期收益 |
|---|---|---|---|
| Phase 1 | L1 厂商侧 KV Cache | P0 | 核心商业价值，直接降低 Token 成本 |
| Phase 1 | L2 请求去重 | P0 | 减少并发重复调用 |
| Phase 1 | L3 元数据缓存 | P0 | 基础设施必需，降低 DB 压力 |
- 精准优化：每层缓存针对特定场景设计，策略独立，互不干扰
- 渐进式实施：可按优先级逐步上线，MVP 阶段即可完整运行
- 可观测：每层缓存独立监控命中率，便于定位优化方向
- 灵活扩展：新增缓存层不影响已有层级，架构可扩展
- 架构复杂度：三层缓存增加了系统复杂度，需要统一的缓存管理器协调各层
- Redis 依赖加重：L2-L3 依赖 Redis，Redis 成为关键路径上的单点（需通过 Redis Cluster/Sentinel 保障高可用）
- 一致性挑战：多层缓存的一致性管理复杂，特别是在数据更新时需要级联失效
- 调试困难：缓存命中/未命中的链路较长，排查问题时需要逐层检查