Skip to content

README.md

Latest commit

 

History

History
167 lines (121 loc) · 9.42 KB

README.md

File metadata and controls

167 lines (121 loc) · 9.42 KB

TokenRouter 技术文档

AI Token CDN 基础设施平台 -- 技术设计文档体系

最后更新：2026-04-16

项目简介

TokenRouter 是 LLM 调用层的结构整合者。通过把 N 个分散用户的请求结构收敛为少量高频前缀，最大化厂商侧 KV Cache 命中率，降低 Token 调用成本。

核心商业逻辑： 大模型厂商缓存读取价格通常为正常价格的 1/10（如 Claude: $0.30 vs $3.00/MTok）。平台通过 Chunker + Arranger + Canonicalizer 主动收敛请求结构，把跨用户的相同前缀聚合成「单一超大客户」，从中赚取结构整合差价。

快速开始

Agent 开发前必读顺序：

  1. Agent 工作流
  2. MVP 约束与红线
  3. 代码知识库 — 数据结构、接口定义、目录结构
  4. API 契约 — HTTP 端点规范
  5. 架构设计 — 核心架构与处理流水线
  6. MVP 实施计划 — 4-6 周可执行落地计划

文档索引

Agent 基础设施（必读）

文档 说明
Agent 工作流 AI Agent 标准任务执行规范
MVP 约束与红线 范围锁、变更控制、性能强制要求
代码知识库 数据结构、接口签名、包职责、扩展指南
API 契约 HTTP 接口规范、错误格式、Header 约定
测试规范 测试分层、覆盖率、验收清单

核心设计文档

文档 路径 说明
架构设计 architecture.md TokenRouter 核心架构与模块设计
MVP 实施计划 mvp-implementation-plan.md 4-6 周可执行落地计划
产品需求文档 PRD.md MVP 产品定位与需求范围
前端设计规范 DESIGN.md Apple 风格设计系统，所有前端页面标准

Phase 2 研究文档

文档 路径 说明
动态前缀缓存设计 research/dynamic-prefix-design.md 形式化模型、在线路由算法、模板生命周期（Phase 2）

模块设计文档

文档 路径 说明
系统技术实现 modules/system-implementation.md 技术栈、数据库、部署运维、监控指标
通用适配器架构 modules/adapter-architecture.md 入站/出站适配器设计、厂商接入矩阵
缓存智能管理 modules/cache-intelligence.md 静态缓存注入、前缀哈希共享、去重

决策记录 (ADR)

编号 标题 状态 路径
ADR-001 后端语言选型：Go 已批准 adr/001-go-language.md
ADR-002 Native-First 适配器架构 已批准 adr/002-native-first.md
ADR-003 缓存策略：多层缓存体系 已批准 adr/003-multi-layer-cache.md
ADR-004 数据库选型：PostgreSQL + Redis + TimescaleDB 已批准 adr/004-database-selection.md
ADR-005 MVP 单体到微服务的渐进式演进 已批准 adr/005-monolith-to-microservices.md

开发指南

文档 路径 说明
快速开始 guides/quickstart.md 环境搭建、开发、测试、部署
E2E 测试指南 guides/e2e-testing.md 真实 API 端到端测试运行指南
适配器开发指南 guides/adapter-development.md 如何开发新的 Provider 适配器插件
缓存策略开发指南 guides/cache-strategy-development.md 如何开发新的厂商缓存注入器

架构速览

处理流水线：

Inbound → Chunker → Arranger → Canonicalizer → CacheInjector → Hasher → Dedup → Outbound → Proxy

完整架构图与状态机详见 architecture.md。

技术栈

层级 选型 版本
后端语言 Go 1.24+
Web 框架 Gin -
数据库 PostgreSQL 16
时序扩展 TimescaleDB 可选
缓存 Redis 7
容器化 Docker -
监控 Prometheus + Grafana -
日志 Zap -
CI/CD GitHub Actions 规划中

关键设计指标

核心指标

指标 Phase 1 (0-3月) Phase 2 (3-9月) Phase 3 (9-18月)
KV Cache 命中率 > 40% > 50% > 65%
单请求延迟增加 (P99) < 100ms < 80ms < 50ms
首 Token 延迟增加 < 50ms < 35ms < 20ms
吞吐量 > 500 req/s > 3,000 req/s > 10,000 req/s
可用性 99.9% 99.95% 99.99%
成本节省率 > 30% > 45% > 55%

指标定义

指标 定义 度量方式
KV Cache 命中率 厂商侧缓存命中的 token 占总 prompt tokens 的比例 DeepSeek: prompt_cache_hit_tokens / prompt_tokens
Anthropic: cache_read_input_tokens / prompt_tokens
OpenAI: cached_tokens / prompt_tokens
单请求延迟增加 (P99) 从请求到达平台到发出上游请求的时间差，不含厂商响应时间 Prometheus histogram: platform_processing_duration_seconds
首 Token 延迟增加 从请求到达平台到发出第一个上游 HTTP 请求的时间差 流式场景下度量，不含网络传输和厂商 TTFT
吞吐量 单实例每秒处理的请求数（标准负载：10 条 messages，5 个 tools，~2000 tokens） 压测工具 (k6) 度量
可用性 /v1/chat/completions 端点的成功率，包含降级透传场景 成功请求数 / 总请求数，按月统计
成本节省率 与直接调用厂商 API 相比的成本节省比例 1 - (平台售价 / 厂商直接调用价格)

厂商缓存指标对照

厂商 响应字段 缓存折扣
DeepSeek prompt_cache_hit_tokens 90% off (0.1 vs 1.0 元/百万 tokens)
Anthropic cache_read_input_tokens 90% off ($0.30 vs $3.00/MTok)
OpenAI prompt_tokens_details.cached_tokens 50% off
Gemini cached_content_token_count 75% off

实施阶段

阶段 时间 目标
Phase 1: MVP 0-3 个月 验证核心假设，静态分块跑通，OpenAI 入站 + DeepSeek V3.2 出站跑通，架构预留 Anthropic 扩展位
Phase 2: 完善 3-9 个月 Observer/Clusterer 上线，动态分块生效，PMF 验证
Phase 3: 规模化 9-18 个月 1,000+ 客户，MRR > $100K，多地域部署
Phase 4: 生态 18 个月+ 插件市场，开发者社区，Series A

文档维护规范

  1. 模块独立性： 每个子文档自成体系，可独立阅读，不依赖其他子文档的上下文
  2. 单向引用： 子文档可以引用主文档和 ADR，主文档通过索引链接子文档，避免循环引用
  3. 变更同步： 修改任何设计时，同步更新对应的 ADR 记录
  4. 版本标注： 每个子文档头部标注最后更新日期和版本号
  5. 代码优先： 接口定义和数据结构以代码块形式呈现，可直接复制到项目中使用