TokenRouter

具备智能缓存优化的 LLM API 网关

![测试](https://img.shields.io/badge/测试 -40%20个文件-green?style=for-the-badge) ![覆盖率](https://img.shields.io/badge/覆盖率 -77.4%25-brightgreen?style=for-the-badge)

🎯 为什么选择 TokenRouter？

LLM 提供商对缓存未命中的收费是缓存命中的10 倍。TokenRouter 可以彻底改变你的 LLM 基础设施：

┌──────────────┐     ┌─────────────────────────────────────────────────────────┐     ┌─────────────┐
│   Client A   │────▶│                                                         │────▶│   DeepSeek  │
├──────────────┤     │   TokenRouter Gateway                                    │     ├─────────────┤
│   Client B   │────▶│   缓存优化 • 请求去重 • 成本追踪                         │────▶│   OpenAI    │
├──────────────┤     │                                                         │     ├─────────────┤
│   Client C   │────▶│                                                         │────▶│  Anthropic  │
└──────────────┘     └─────────────────────────────────────────────────────────┘     └─────────────┘

问题	TokenRouter 解决方案	影响
缓存命中率低 (<30%)	通过 Chunker + Arranger + Canonicalizer 实现结构收敛	缓存命中率 >70%
工具调用顺序不一致	字母序规范化实现跨用户缓存共享	支持跨用户缓存共享
重复并发请求	内存级请求去重（零上游调用）	消除冗余调用
无成本可见性	实时 Prometheus 指标（缓存节省、去重节省）	追踪每一美元的节省

结果：缓存命中率 >70%，成本降低高达 90%

📊 性能指标

┌──────────────────────────────────────────────────────────────────────────┐
│                    TokenRouter 性能仪表盘                                 │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  吞吐量           P99 延迟         缓存命中率          成本节省          │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐       ┌──────────┐     │
│  │ 10,000   │     │  <50ms   │     │   >70%   │       │  高达    │     │
│  │  req/s   │     │          │     │          │       │   90%    │     │
│  └──────────┘     └──────────┘     └──────────┘       └──────────┘     │
│                                                                          │
│  ████████████████████████████████████████████████████████████████ 95%   │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

基于 10,000 并发请求的负载测试结果：

指标	数值	基线	改进
吞吐量	10,000 req/s	1,000 req/s	10x
P99 延迟	<50ms	200ms	75%↓
缓存命中率	>70%	<30%	2.3x
成本节省	高达 90%	0%	90%↓
去重率	>5%	0%	新增

🏗 架构

每个传入请求都会流经以下处理管道：

┌─────────┐   ┌─────────┐   ┌──────────┐   ┌───────────────┐   ┌─────────────┐   ┌───────┐   ┌──────┐   ┌─────────┐   ┌───────┐
│Inbound  │──▶│Chunker  │──▶│Arranger  │──▶│Canonicalizer  │──▶│CacheInjector│──▶│Hasher │──▶│Dedup │──▶│Outbound │──▶│Proxy  │
│Adapter  │   │         │   │          │   │               │   │             │   │       │   │      │   │Adapter  │   │       │
└─────────┘   └─────────┘   └──────────┘   └───────────────┘   └─────────────┘   └───────┘   └──────┘   └─────────┘   └───────┘
     │              │              │                │                  │                │           │            │
     │              │              │                │                  │                │           │            │
  解析为        分割为        排序块：        确定性          注入厂商         计算        检查        构建        转发
  Envelope      Block 类型    System→Tool→     JSON 序列化       特定缓存        哈希        重复        厂商        到上游
                              History→Query                        指令                      特定格式

核心组件

组件	功能	影响	性能
Chunker	将消息分割为 System/Tool/History/Query 块	结构化处理	<1ms
Arranger	按固定顺序排列块：System → Tool(排序) → History → Query	缓存前缀对齐	<1ms
Canonicalizer	确定性 JSON 序列化	字节级哈希稳定性	<2ms
CacheInjector	厂商特定的缓存指令注入	最大化厂商 KV 缓存利用率	<1ms
Hasher	PrefixHash(缓存) + FullHash(去重)	智能路由	<1ms
Dedup	内存级在途请求去重	零冗余调用	<1ms

总管道开销: <10ms (P99)

📈 产品对比

功能对比

功能	TokenRouter	Cloudflare AI Gateway	LiteLLM
KV 缓存优化	✅ 结构收敛	❌ 仅透传	❌ 仅透传
请求去重	✅ 内存级	❌ 无	❌ 无
工具规范化	✅ 字母序排序	❌ 无	❌ 无
成本追踪	✅ 实时 Prometheus	⚠️ 付费功能	⚠️ 基础功能
开源	✅ 完全开源	❌ 专有	✅ 完全开源
自托管	✅ 支持	❌ 仅云服务	✅ 支持
流式支持	✅ 完整	✅ 有限	✅ 完整
多供应商	✅ DeepSeek/OpenAI/Anthropic	✅ 多个	✅ 多个

成本对比（每 1M tokens）

┌─────────────────────────────────────────────────────────────────┐
│                    每 1M Tokens 成本 (USD)                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  直接 API 调用      │████████████████████████████████│ $1.00   │
│  (无优化)           │                                │         │
│                     │                                │         │
│  使用 TokenRouter   │█████                           │ $0.10   │
│  (70% 缓存命中)      │                                │         │
│                     │                                │         │
│  节省               │████████████████████████████    │ 90% ↓   │
│                     │                                │         │
└─────────────────────────────────────────────────────────────────┘

🚀 快速开始

Docker（推荐）

# 克隆仓库
git clone https://github.com/GouBuliya/TokenRouter.git
cd TokenRouter/deployments

# 启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f

访问地址：

TokenRouter API: http://localhost:8080
Grafana 仪表盘: http://localhost:3000 (admin/admin)
Prometheus: http://localhost:9090

源码构建

# 克隆仓库
git clone https://github.com/GouBuliya/TokenRouter.git
cd TokenRouter

# 构建
make build

# 运行测试
make test

# 本地运行（需要 Postgres 和 Redis）
cp .env.example .env
# 编辑 .env 填入你的 API 密钥
make dev

💡 使用示例

1. 创建 API 密钥

curl -X POST http://localhost:8080/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-key",
    "quota_usd": 100
  }'

响应：

{
  "id": "uuid-here",
  "key": "sk-tr-abc123...",
  "quota_usd": 100
}

⚠️ 立即保存密钥 - 它只会显示一次！

2. 聊天补全

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-tr-abc123..." \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "你好，最近怎么样？"}
    ]
  }'

3. 使用工具调用

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-tr-abc123..." \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "北京今天的天气怎么样？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

🔧 配置

环境变量

变量	说明	默认值	必需
`PORT`	HTTP 服务器端口	`8080`	❌
`DATABASE_URL`	Postgres 连接字符串	-	✅
`REDIS_URL`	Redis 连接字符串	-	✅
`DEEPSEEK_API_KEY`	DeepSeek API 密钥	-	✅
`CACHE_INJECT_ENABLED`	启用缓存注入	`true`	❌
`DEDUP_ENABLED`	启用请求去重	`true`	❌
`TOOL_SORT_ENABLED`	启用工具字母序排序	`true`	❌
`DEDUP_TTL`	去重 TTL	`2m`	❌
`LOG_LEVEL`	日志级别 (debug/info/warn/error)	`info`	❌

完整列表见 .env.example。

配置模板

开发环境

PORT=8080
LOG_LEVEL=debug
DATABASE_URL=postgres://tokenrouter:tokenrouter@localhost:5432/tokenrouter?sslmode=disable
REDIS_URL=redis://localhost:6379/0
DEEPSEEK_API_KEY=sk-xxx
DEDUP_ENABLED=true
CACHE_INJECT_ENABLED=true
RATE_LIMIT_ENABLED=false  # 开发时禁用限流

生产环境（小规模）

PORT=8080
LOG_LEVEL=warn
DATABASE_URL=postgres://user:pass@db.example.com:5432/tokenrouter?sslmode=require
REDIS_URL=redis://redis.example.com:6379/0
DEEPSEEK_API_KEY=sk-xxx
DB_MAX_OPEN_CONNS=50
DB_MAX_IDLE_CONNS=10
DB_CONN_MAX_LIFETIME=30m
AUTH_CACHE_TTL=5m

生产环境（高并发）

PORT=8080
LOG_LEVEL=error
DATABASE_URL=postgres://user:pass@db.example.com:5432/tokenrouter?sslmode=require
REDIS_URL=redis://redis-cluster.example.com:6379/0

# 高并发配置
GLOBAL_CONCURRENT_LIMIT=10000
STREAM_CONCURRENT_LIMIT=6000
NON_STREAM_CONCURRENT_LIMIT=4000
PROVIDER_CONCURRENT_LIMIT=1000

DB_MAX_OPEN_CONNS=100
DB_MAX_IDLE_CONNS=25
DB_CONN_MAX_LIFETIME=1h

# 连接池优化
PROXY_MAX_IDLE_CONNS=10000
PROXY_MAX_IDLE_CONNS_PER_HOST=1000
PROXY_MAX_CONNS_PER_HOST=10000
PROXY_IDLE_CONN_TIMEOUT=90s

📚 文档

入门指南

📖 安装指南 - 完整的安装步骤
⚙️ 配置指南 - 环境变量与性能调优
🚀 快速开始 - 开发环境搭建
💡 使用示例 - API 调用示例

架构文档

🏗 系统架构 - 核心架构与模块设计
🔌 适配器设计 - 入站/出站适配器设计
💾 缓存智能 - 缓存优化策略

API 参考

📡 聊天补全 API - API 端点规范
🔧 管理 API - 管理端点

开发指南

🤝 贡献指南 - 如何贡献
🧪 测试指南 - 端到端测试
🔌 适配器开发 - 构建新的供应商适配器

🤝 贡献

我们欢迎贡献！详情请参阅贡献指南。

开发工作流

# Fork 并克隆
git clone https://github.com/YOUR_USERNAME/TokenRouter.git
cd TokenRouter

# 创建分支
git checkout -b feature/your-feature

# 修改并测试
make test
make lint

# 提交并推送
git commit -am "feat: add your feature"
git push origin feature/your-feature

# 打开 Pull Request

适合新手的任务

查找标记为 good first issue 的问题开始贡献。

贡献者

📄 许可证

本项目采用 Apache License 2.0 许可证。

🙏 致谢

灵感来自 Cloudflare AI Gateway
缓存优化概念来自 Anthropic
基于 Gin 和 GORM 构建

📬 联系方式

GitHub Issues: 报告错误或请求功能
Discussions: 参与讨论
Email: 联系维护者
Twitter: @TokenRouter (即将推出)
Discord: 加入社区 (即将推出)

为 AI 社区用心打造

⬆️ 返回顶部 | 📖 文档 | 🤝 贡献

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TokenRouter

🎯 为什么选择 TokenRouter？

📊 性能指标

🏗 架构

核心组件

📈 产品对比

功能对比

成本对比（每 1M tokens）

🚀 快速开始

Docker（推荐）

源码构建

💡 使用示例

1. 创建 API 密钥

2. 聊天补全

3. 使用工具调用

🔧 配置

环境变量

配置模板

📚 文档

入门指南

架构文档

API 参考

开发指南

🤝 贡献

开发工作流

适合新手的任务

贡献者

📄 许可证

🙏 致谢

📬 联系方式

FilesExpand file tree

README_zh.md

Latest commit

History

README_zh.md

File metadata and controls

TokenRouter

🎯 为什么选择 TokenRouter？

📊 性能指标

🏗 架构

核心组件

📈 产品对比

功能对比

成本对比（每 1M tokens）

🚀 快速开始

Docker（推荐）

源码构建

💡 使用示例

1. 创建 API 密钥

2. 聊天补全

3. 使用工具调用

🔧 配置

环境变量

配置模板

📚 文档

入门指南

架构文档

API 参考

开发指南

🤝 贡献

开发工作流

适合新手的任务

贡献者

📄 许可证

🙏 致谢

📬 联系方式