nobody/llm-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
llm-gateway/docs/plans/2026-05-01-llm-gateway-plan.md
root 8f550a2100 docs: add LLM Gateway implementation plan 
Plan includes 6 batches with 34 tasks:
- Batch 1: Project foundation (config, db, logging)
- Batch 2: Data models and Admin API (CRUD)
- Batch 3: Core services (transformer, router, rate limiter, budget)
- Batch 4: Provider adapters (OpenAI, Anthropic, Azure, Gemini, Bedrock)
- Batch 5: API endpoints (chat, messages, responses)
- Batch 6: Management and deployment

Estimated time: 19-25 hours

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-01 14:55:18 +08:00

11 KiB
Raw Blame History

LLM Gateway 实施计划

概述

基于已批准的设计文档 docs/plans/2026-05-01-llm-gateway-design.md，本计划将实现分为 6 个批次，每批次包含多个可验证的任务。

批次 1：项目基础架构

任务 1.1：初始化项目结构

  • 目标：创建项目目录结构和基础文件
  • 涉及文件： 
    llm-gateway/
├── app/
│   ├── __init__.py
│   ├── main.py
│   └── config.py
├── tests/
│   └── __init__.py
├── requirements.txt
├── .gitignore
└── README.md
  • 验证方式：目录结构正确，Python 可导入 app 模块
  • 完成判定：python -c "import app" 无报错

任务 1.2：配置管理模块

  • 目标：实现 Pydantic Settings 配置管理
  • 涉及文件：
    • app/config.py
    • app/.env.example
  • 验证方式：配置类可正确读取环境变量
  • 完成判定：单元测试通过

任务 1.3：数据库连接与 Schema

  • 目标：初始化 SQLite 数据库和表结构
  • 涉及文件：
    • app/db/database.py
    • app/db/schema.sql
  • 验证方式：数据库文件创建成功，表结构正确
  • 完成判定：sqlite3 data/gateway.db ".tables" 显示所有表

任务 1.4：日志配置

  • 目标：配置结构化日志
  • 涉及文件：
    • app/utils/logging.py
  • 验证方式：日志输出格式正确
  • 完成判定：单元测试验证日志格式

批次 2：数据模型与 Admin API

任务 2.1：数据模型定义

  • 目标：定义 SQLAlchemy ORM 模型
  • 涉及文件：
    • app/models/provider.py
    • app/models/api_key.py
    • app/models/project.py
    • app/models/model_alias.py
    • app/models/usage.py
    • app/models/__init__.py
  • 验证方式：模型可正确映射到数据库表
  • 完成判定：单元测试通过

任务 2.2：加密工具

  • 目标：实现 API Key 哈希和 Provider Key 加密
  • 涉及文件：
    • app/utils/crypto.py
  • 验证方式：
    • bcrypt 哈希验证
    • AES-256 加密解密验证
  • 完成判定：单元测试通过

任务 2.3：Provider 管理 API

  • 目标：实现 Provider CRUD 接口
  • 涉及文件：
    • app/api/admin/providers.py
    • app/api/admin/__init__.py
  • 验证方式：
    • POST /admin/providers 创建 Provider
    • GET /admin/providers 列表查询
    • PUT /admin/providers/{id} 更新
    • DELETE /admin/providers/{id} 删除
  • 完成判定：集成测试通过

任务 2.4：Project 管理 API

  • 目标：实现 Project CRUD 接口
  • 涉及文件：
    • app/api/admin/projects.py
  • 验证方式：CRUD 接口可用
  • 完成判定：集成测试通过

任务 2.5：API Key 管理 API

  • 目标：实现 API Key CRUD 接口
  • 涉及文件：
    • app/api/admin/keys.py
  • 验证方式：
    • 创建 Key 返回明文 key（仅一次）
    • 验证 key_hash 存储正确
  • 完成判定：集成测试通过

任务 2.6：Model Alias 管理 API

  • 目标：实现 Model Alias CRUD 接口
  • 涉及文件：
    • app/api/admin/models.py
  • 验证方式：CRUD 接口可用
  • 完成判定：集成测试通过

批次 3：核心服务层

任务 3.1：Request Transformer 基础

  • 目标：实现请求格式转换基础框架
  • 涉及文件：
    • app/core/transformer.py
    • app/schemas/openai.py
    • app/schemas/anthropic.py
  • 验证方式：
    • OpenAI → Anthropic 转换测试
    • Anthropic → OpenAI 转换测试
  • 完成判定：单元测试通过

任务 3.2：Router 实现

  • 目标：实现模型别名解析和路由逻辑
  • 涉及文件：
    • app/core/router.py
  • 验证方式：
    • 简单别名解析
    • 路由组加权选择
    • Fallback 链解析
  • 完成判定：单元测试通过

任务 3.3：Rate Limiter 实现

  • 目标：实现 RPM/TPM 限流
  • 涉及文件：
    • app/core/rate_limiter.py
  • 验证方式：
    • 超过限制返回 429
    • 响应头正确
    • 窗口重置正确
  • 完成判定：单元测试通过

任务 3.4：Budget Controller 实现

  • 目标：实现 Key/Project 级预算控制
  • 涉及文件：
    • app/core/budget.py
  • 验证方式：
    • 超过 hard_limit 返回 402
    • soft_limit 告警日志
  • 完成判定：单元测试通过

任务 3.5：Circuit Breaker 实现

  • 目标：实现熔断器
  • 涉及文件：
    • app/core/circuit_breaker.py
  • 验证方式：
    • CLOSED → OPEN → HALF_OPEN → CLOSED 状态转换
  • 完成判定：单元测试通过

任务 3.6：Fallback/Retry 实现

  • 目标：实现重试和降级逻辑
  • 涉及文件：
    • app/core/fallback.py
  • 验证方式：
    • 指数退避重试
    • Fallback 到备用 Provider
  • 完成判定：单元测试通过

批次 4：Provider Adapters

任务 4.1：Adapter 基类与接口

  • 目标：定义 Provider Adapter 抽象接口
  • 涉及文件：
    • app/adapters/base.py
    • app/adapters/__init__.py
  • 验证方式：接口定义完整
  • 完成判定：代码审查通过

任务 4.2：OpenAI Adapter

  • 目标：实现 OpenAI Provider 适配器
  • 涉及文件：
    • app/adapters/openai.py
  • 验证方式：
    • 非流式请求测试
    • 流式请求测试
    • Token 计数测试
  • 完成判定：集成测试通过（使用 Mock 或真实 API）

任务 4.3：Anthropic Adapter

  • 目标：实现 Anthropic Provider 适配器
  • 涉及文件：
    • app/adapters/anthropic.py
  • 验证方式：
    • Messages API 格式请求
    • 流式响应处理
  • 完成判定：集成测试通过

任务 4.4：Azure OpenAI Adapter

  • 目标：实现 Azure OpenAI Provider 适配器
  • 涉及文件：
    • app/adapters/azure.py
  • 验证方式：
    • deployment_name 配置正确
    • api_base 路径正确
  • 完成判定：集成测试通过

任务 4.5：Google Gemini Adapter

  • 目标：实现 Google Gemini Provider 适配器
  • 涉及文件：
    • app/adapters/gemini.py
  • 验证方式：
    • Gemini API 格式转换
    • safety settings 处理
  • 完成判定：集成测试通过

任务 4.6：AWS Bedrock Adapter

  • 目标：实现 AWS Bedrock Provider 适配器
  • 涉及文件：
    • app/adapters/bedrock.py
  • 验证方式：
    • AWS 认证正确
    • model_id 格式正确
  • 完成判定：集成测试通过

批次 5：API 端点与集成

任务 5.1：Load Balancer 实现

  • 目标：实现负载均衡逻辑
  • 涉及文件：
    • app/core/load_balancer.py
  • 验证方式：
    • 加权轮询正确
    • 健康检查集成
  • 完成判定：单元测试通过

任务 5.2：Health Check 实现

  • 目标：实现 Provider 健康检查
  • 涉及文件：
    • app/core/health_checker.py
  • 验证方式：
    • 定时检查执行
    • 状态更新正确
  • 完成判定：单元测试通过

任务 5.3：/v1/chat/completions 端点

  • 目标：实现 OpenAI-compatible Chat Completions API
  • 涉及文件：
    • app/api/v1/chat.py
    • app/api/v1/__init__.py
  • 验证方式：
    • 使用 OpenAI SDK 调用成功
    • 流式响应正确
  • 完成判定：端到端测试通过

任务 5.4：/v1/messages 端点

  • 目标：实现 Anthropic Messages API
  • 涉及文件：
    • app/api/v1/messages.py
  • 验证方式：
    • 使用 Anthropic SDK 调用成功
  • 完成判定：端到端测试通过

任务 5.5：/v1/responses 端点

  • 目标：实现 OpenAI Responses API
  • 涉及文件：
    • app/api/v1/responses.py
  • 验证方式：
    • Responses API 格式正确处理
  • 完成判定：端到端测试通过

任务 5.6：认证中间件

  • 目标：实现 Virtual Key 认证
  • 涉及文件：
    • app/middleware/auth.py
  • 验证方式：
    • 有效 Key 通过
    • 无效 Key 返回 401
  • 完成判定：集成测试通过

任务 5.7：请求日志中间件

  • 目标：实现请求日志记录
  • 涉及文件：
    • app/middleware/logging.py
  • 验证方式：
    • 日志写入数据库
    • 包含所有必要字段
  • 完成判定：集成测试通过

批次 6：管理功能与部署

任务 6.1：Usage Dashboard API

  • 目标：实现使用统计查询接口
  • 涉及文件：
    • app/api/admin/usage.py
  • 验证方式：
    • GET /admin/usage/stats 返回正确统计
    • 按时间/模型/Provider 分组
  • 完成判定：集成测试通过

任务 6.2：审计日志

  • 目标：实现审计日志记录
  • 涉及文件：
    • app/middleware/audit.py
  • 验证方式：
    • 管理操作记录审计日志
  • 完成判定：集成测试通过

任务 6.3：Provider Health Check API

  • 目标：实现健康检查接口
  • 涉及文件：
    • app/api/admin/health.py
  • 验证方式：
    • GET /health 返回服务状态
    • GET /admin/providers/{id}/health 返回 Provider 状态
  • 完成判定：集成测试通过

任务 6.4：Docker 配置

  • 目标：创建 Docker 和 Docker Compose 配置
  • 涉及文件：
    • Dockerfile
    • docker-compose.yml
  • 验证方式：
    • docker build 成功
    • docker-compose up 服务正常
  • 完成判定：容器启动并可访问 API

任务 6.5：文档与示例

  • 目标：完善 README 和 API 文档
  • 涉及文件：
    • README.md
    • docs/api.md
    • docs/deployment.md
  • 验证方式：文档完整可读
  • 完成判定：代码审查通过

验证命令

单元测试

pytest tests/unit -v

集成测试

pytest tests/integration -v

全部测试

pytest -v --cov=app

类型检查

mypy app

代码风格

ruff check app

启动服务

uvicorn app.main:app --reload

风险与待确认项

  1. Provider API Key 获取：需要各 Provider 的 API Key 用于测试
  2. AWS 凭证：Bedrock 需要 AWS 凭证配置
  3. 并发写入性能：SQLite 高并发写入可能成为瓶颈，需测试验证
  4. Token 计数准确性：不同 Provider 的 Token 计数方式可能不同

时间估算

批次 任务数 预计时间
批次 1 4 2-3 小时
批次 2 6 3-4 小时
批次 3 6 4-5 小时
批次 4 6 4-5 小时
批次 5 7 4-5 小时
批次 6 5 2-3 小时
总计 34 19-25 小时

依赖关系

批次 1 (基础架构)
    ↓
批次 2 (数据模型与 Admin API)
    ↓
批次 3 (核心服务层) ←─┐
    ↓                 │
批次 4 (Provider Adapters)
    ↓
批次 5 (API 端点与集成)
    ↓
批次 6 (管理功能与部署)