tokrouter

LLM API 路由器 - 多 Provider 路由 + 监控 + 格式转换

专为个人用户设计的客户端聚合工具，统一管理多个 LLM API Provider。

功能特性

核心功能

• 多 Provider 路由: 支持 OpenAI、Anthropic、智谱、Google Gemini 等
• 5 种智能策略: quota_first、price_first、latency_first、round_robin、manual
• Quota 管理: 追踪流量使用，自动切换 Provider，支持预警阈值
• 格式转换: OpenAI ↔ Anthropic 格式自动转换
• 透明代理: 请求透传转发，支持 Streaming SSE 流式响应
• Function Calling: 支持 Tools/Tool_calls 格式转换

安全与监控

• HTTPS/TLS: 可选 TLS 加密传输
• Trace ID: 请求追踪，便于调试
• Prometheus Metrics: 完整的请求统计指标
• 结构化日志: JSON 格式，敏感信息自动脱敏
• 请求验证: 参数校验，防止异常请求

可扩展性

• Provider 插件化: 支持自定义 Provider 实现
• 配置热更新: 监听配置变化，无需重启
• OpenAPI 文档: 标准 API 规范

安装

编译安装

cd tokrouter
go build ./cmd/tokrouter

运行依赖

• Go 1.19+
• SQLite 3 (用于用量统计)

配置

创建 config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  tls_cert: ""   # TLS 证书路径 (可选)
  tls_key: ""    # TLS 密钥路径 (可选)

providers:
  openai:
    enabled: true
    format: openai
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.openai.com/v1"
    quota_limit: 1000000  # 月度 token 限额
    models:
      - name: "gpt-4"
        pricing:
          input: 0.03    # 美元/千 tokens
          output: 0.06
        max_tokens: 8192
      - name: "gpt-3.5-turbo"
        pricing:
          input: 0.0015
          output: 0.002
        max_tokens: 4096

  anthropic:
    enabled: true
    format: anthropic
    api_key: "${ANTHROPIC_API_KEY}"
    base_url: "https://api.anthropic.com/v1"
    quota_limit: 500000
    models:
      - name: "claude-3-opus"
        pricing:
          input: 0.015
          output: 0.075
        max_tokens: 200000

  zhipu:
    enabled: true
    format: openai
    api_key: "${ZHIPU_API_KEY}"
    base_url: "https://open.bigmodel.cn/api/paas/v4"
    quota_limit: 200000
    models:
      - name: "glm-4"
        pricing:
          input: 0.001
          output: 0.001
        max_tokens: 128000

router:
  default_strategy: "quota_first"
  fallback_chain: ["openai", "anthropic", "zhipu"]
  retry:
    max_retries: 2
    timeout: "30s"
    backoff: "exponential"

meter:
  enabled: true
  db_path: "./data/tokmeter.db"
  alert_thresholds:
    - percent: 80
      level: "warn"
    - percent: 90
      level: "warn"
    - percent: 95
      level: "error"

adapter:
  enabled: true
  auto_detect: true

metrics:
  enabled: true
  path: "/metrics"

trace:
  enabled: true
  header: "x-request-id"

health_check:
  enabled: true
  interval: "30s"
  timeout: "10s"
  failure_threshold: 3

log:
  level: "info"
  format: "json"
  output: "stdout"

环境变量

API Key 支持环境变量:

export OPENAI_API_KEY="sk-xxx"
export ANTHROPIC_API_KEY="sk-ant-xxx"
export ZHIPU_API_KEY="xxx"

tokrouter serve

CLI 命令

启动服务

# 默认端口 8080
tokrouter serve

# 指定端口
tokrouter serve --port 3000

# 指定配置文件
tokrouter serve --config /path/to/config.yaml

# 启用 HTTPS (需配置 tls_cert/tls_key)
tokrouter serve

状态查看

# 显示 Provider 状态和 Quota
tokrouter status

# 输出示例:
# Provider   Format    Healthy  Quota%   Models
# openai     openai    true     45.2%    gpt-4, gpt-3.5-turbo
# anthropic  anthropic true     12.8%    claude-3-opus
# zhipu      openai    true     78.5%    glm-4

策略切换

# 切换到价格优先策略
tokrouter switch price_first

# 切换到延迟优先策略
tokrouter switch latency_first

# 切换到轮询策略
tokrouter switch round_robin

统计查看

# 查看本月统计
tokrouter summary --month

# 查看指定 Provider 统计
tokrouter summary --provider openai

# 查看指定时间范围
tokrouter summary --start 2024-01-01 --end 2024-01-31

配置管理

# 验证配置
tokrouter config validate

# 显示当前配置
tokrouter config show

其他命令

# 显示版本
tokrouter version

# 显示帮助
tokrouter help

API 端点

Chat 端点

端点	格式	说明
/v1/chat/completions	OpenAI	OpenAI 兼容，支持 Streaming
/v1/messages	Anthropic	Anthropic 兼容，支持 Streaming

请求示例

OpenAI 格式:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-request-id: req-001" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Anthropic 格式:

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-opus",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

Function Calling:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "What is the weather?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          }
        }
      }
    }]
  }'

状态端点

端点	说明
/status	Provider 状态 + Quota 信息
/health	服务健康检查 (JSON 格式)
/metrics	Prometheus 指标
/openapi.json	OpenAPI 规范文档

状态响应示例

curl http://localhost:8080/status

# 响应:
[
  {
    "name": "openai",
    "format": "openai",
    "healthy": true,
    "enabled": true,
    "latency": 245,
    "quota_limit": 1000000,
    "quota_used": 452000,
    "quota_percent": 45.2,
    "models": ["gpt-4", "gpt-3.5-turbo"]
  }
]

健康检查响应

curl http://localhost:8080/health

# 响应:
{
  "status": "ok",
  "version": "v0.1.0"
}

路由策略

策略	选择逻辑	适用场景
quota_first	Quota 占用率最低的 Provider	成本控制，均衡使用
price_first	价格最低的 Provider	成本最优
latency_first	延迟最低的 Provider	性能优先
round_robin	轮询分配	均衡负载
manual	用户设定的优先级	自定义控制

Streaming 支持

支持 Server-Sent Events (SSE) 流式响应:

# Streaming 请求
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

# 响应格式:
data: {"id":"1","choices":[{"delta":{"content":"Once"}}]}
data: {"id":"1","choices":[{"delta":{"content":" upon"}}]}
data: {"id":"1","choices":[{"delta":{"content":" a time"}}]}
data: [DONE]

Quota 管理

预警阈值

配置预警阈值后，达到阈值时会触发告警:

meter:
  alert_thresholds:
    - percent: 80   # 80% 时 warn 日志
      level: "warn"
    - percent: 90   # 90% 时 warn 日志
      level: "warn"
    - percent: 95   # 95% 时 error 日志
      level: "error"

Quota 耗尽处理

当 Provider quota 耗尽时:

1. 自动跳过该 Provider
2. 尝试 fallback_chain 中的下一个 Provider
3. 若全部耗尽，返回 no available provider 错误

Prometheus Metrics

访问 /metrics 获取指标:

# 请求统计
tokrouter_requests_total 1523
tokrouter_success_total 1498
tokrouter_errors_total 25

# 延迟统计
tokrouter_latency_avg_ms 245.32

# Provider 统计
tokrouter_provider_requests{provider="openai"} 850
tokrouter_provider_tokens{provider="openai"} 125000
tokrouter_provider_errors{provider="openai"} 12

# Model 统计
tokrouter_model_requests{model="gpt-4"} 520
tokrouter_model_tokens{model="gpt-4"} 89000

# 状态码统计
tokrouter_status_codes{code="200"} 1498
tokrouter_status_codes{code="429"} 15
tokrouter_status_codes{code="503"} 10

# 运行时间
tokrouter_uptime_seconds 3600

Provider 插件化

支持自定义 Provider 实现:

package main

import (
    "tokflux/tokrouter"
    "tokflux/tokrouter/strategy"
)

// 自定义 Provider 插件
type MyProviderPlugin struct {}

func (p *MyProviderPlugin) Name() string {
    return "my-provider"
}

func (p *MyProviderPlugin) Create(cfg tokrouter.ProviderConfig) (*strategy.Provider, error) {
    return &strategy.Provider{
        Name:    "my-provider",
        Format:  cfg.Format,
        BaseURL: cfg.BaseURL,
        APIKey:  cfg.APIKey,
        Models:  makeModelsFromConfig(cfg),
    }, nil
}

func (p *MyProviderPlugin) OnRequest(req *http.Request) error {
    // 自定义请求处理
    return nil
}

func (p *MyProviderPlugin) OnResponse(resp *http.Response) error {
    // 自定义响应处理
    return nil
}

func main() {
    // 注册插件
    tokrouter.RegisterProviderPlugin(&MyProviderPlugin{})
}

配置热更新

启用配置热更新后，修改配置文件无需重启:

# 修改配置后自动生效:
# - Provider 启用/禁用
# - 路由策略切换
# - Quota 预警阈值

日志输出:

{"level":"info","message":"config reloaded","trace_id":"","Fields":{"version":2}}
{"level":"info","message":"strategy switched","trace_id":"","Fields":{"strategy":"price_first"}}

项目结构

tokrouter/
├── router.go              # 路由 Engine
├── forward.go             # 请求转发 + Streaming
├── config.go              # 配置加载
├── validation.go          # 请求验证
├── errors.go              # 错误定义
├── ratelimit.go           # 限流器
├── log.go                 # 结构化日志
├── metrics.go             # Prometheus 指标
├── openapi.go             # OpenAPI 规范
├── provider_registry.go   # Provider 插件注册
├── config_watcher.go      # 配置热更新
├── strategy/              # 5 种路由策略
│   ├── interface.go
│   ├── quota.go
│   ├── price.go
│   ├── latency.go
│   ├── round.go
│   └── manual.go
├── adapter/               # 格式转换
│   ├── unified.go         # 统一格式定义
│   ├── openai.go          # OpenAI 格式
│   ├── anthropic.go       # Anthropic 格式
│   └── detect.go          # 格式检测
├── meter/                 # 监控 + Quota
│   ├── quota.go           # Quota 追踪 + 预警
│   ├── pricing.go         # 价格估算
│   ├── estimate.go        # Token 估算
│   └── storage/           # SQLite 存储
│       ├── storage.go
│       ├── record.go
│       └── query.go
├── cli/                   # CLI 命令
│   ├── root.go
│   ├── serve.go
│   ├── status.go
│   ├── switch.go
│   ├── summary.go
│   └ config.go
└── cmd/tokrouter/         # 入口
    └── main.go

使用场景

个人聚合管理

多个 Agent/API 客户端 → tokrouter (统一 endpoint) → 多 Provider

- Provider quota 耗尽 → 自动切换
- 不同格式请求 → 自动转换
- 集中管理 API Key → 统一监控
- 成本控制 → quota 预警

集成示例

package main

import (
    "context"
    "tokflux/tokrouter"
)

func main() {
    // 加载配置
    cfg, err := tokrouter.Load("config.yaml")
    if err != nil {
        panic(err)
    }

    // 创建 Engine
    engine, err := tokrouter.NewEngine(cfg)
    if err != nil {
        panic(err)
    }
    defer engine.Close()

    // 选择 Provider
    provider, err := engine.SelectProvider("gpt-4", tokrouter.FormatOpenAI)
    if err != nil {
        panic(err)
    }

    // 转发请求
    req := createRequest()
    resp, err := engine.Forward(context.Background(), provider, req)

    // 记录使用
    engine.RecordUsage(&tokrouter.UsageRecord{
        Provider:     provider.Name,
        Model:        "gpt-4",
        TotalTokens:  150,
    })
}

Agent 工具集成示例

将 tokrouter 作为各类 AI Agent 工具的后端代理。优先使用配置文件方式。

Claude Code

Anthropic API 格式端点 /v1/messages。

配置文件方式（推荐）

// ~/.claude/settings.json 或 .claude/settings.local.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080"
  }
}

配置文件优先级：用户全局 (~/.claude/settings.json) → 项目配置 (.claude/settings.json) → 项目本地 (.claude/settings.local.json)

命令行参数方式

claude --settings '{"env": {"ANTHROPIC_BASE_URL": "http://localhost:8080"}}'

aider

OpenAI 格式端点 /v1/chat/completions。

配置文件方式（推荐）

# ~/.aider.conf.yml
openai-api-base: http://localhost:8080/v1
openai-api-key: your-tokrouter-key
model: gpt-4
pretty: true
show-diffs: true

Cursor IDE

OpenAI 格式端点 /v1/chat/completions。

配置文件方式

// ~/.cursor/settings.json
{
  "cursor.ai.openaiBaseUrl": "http://localhost:8080/v1",
  "cursor.ai.openaiKey": "your-tokrouter-key"
}

llm CLI

OpenAI 格式端点 /v1/chat/completions。

配置文件方式

# ~/.config/llm/openai-models.yaml
- name: tokrouter-gpt4
  model_id: gpt-4
  api_base: http://localhost:8080/v1

- name: tokrouter-claude
  model_id: claude-3-opus
  api_base: http://localhost:8080/v1

# 设置 API key
llm keys set openai
# 输入 your-tokrouter-key

# 使用
llm -m tokrouter-gpt4 "your prompt"

codex-cli (OpenAI)

OpenAI 格式端点 /v1/chat/completions。

配置文件方式

# ~/.codex/config.toml
api_base_url = "http://localhost:8080/v1"
api_key = "your-tokrouter-key"
model = "o4-mini"
approval_mode = "suggest"

其他 OpenAI 兼容工具

通用配置模式适用于大多数工具：

工具类型	配置文件	API Base 配置项
YAML 格式	config.yaml	api_base
JSON 格式	config.json	api_base / openaiBaseUrl
TOML 格式	config.toml	api_base_url

端点映射

tokrouter 端点	API 格式	适用工具
/v1/chat/completions	OpenAI	aider, Cursor, llm, codex-cli
/v1/messages	Anthropic	Claude Code

安全注意事项

• API Key 存储: 配置文件明文存储，建议使用环境变量
• 敏感信息日志: API Key、Token 自动脱敏
• HTTPS: 生产环境建议启用 TLS
• 输入验证: 限制 max_tokens、temperature、content 长度

License

MIT