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 Permalink 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

风险与待确认项

Provider API Key 获取：需要各 Provider 的 API Key 用于测试
AWS 凭证：Bedrock 需要 AWS 凭证配置
并发写入性能：SQLite 高并发写入可能成为瓶颈，需测试验证
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 (管理功能与部署)

11 KiB Raw Permalink Blame History Unescape Escape

LLM Gateway 实施计划

概述

批次 1：项目基础架构

任务 1.1：初始化项目结构

任务 1.2：配置管理模块

任务 1.3：数据库连接与 Schema

任务 1.4：日志配置

批次 2：数据模型与 Admin API

任务 2.1：数据模型定义

任务 2.2：加密工具

任务 2.3：Provider 管理 API

任务 2.4：Project 管理 API

任务 2.5：API Key 管理 API

任务 2.6：Model Alias 管理 API

批次 3：核心服务层

任务 3.1：Request Transformer 基础

任务 3.2：Router 实现

任务 3.3：Rate Limiter 实现

任务 3.4：Budget Controller 实现

任务 3.5：Circuit Breaker 实现

任务 3.6：Fallback/Retry 实现

批次 4：Provider Adapters

任务 4.1：Adapter 基类与接口

任务 4.2：OpenAI Adapter

任务 4.3：Anthropic Adapter

任务 4.4：Azure OpenAI Adapter

任务 4.5：Google Gemini Adapter

任务 4.6：AWS Bedrock Adapter

批次 5：API 端点与集成

任务 5.1：Load Balancer 实现

任务 5.2：Health Check 实现

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

任务 5.4：/v1/messages 端点

任务 5.5：/v1/responses 端点

任务 5.6：认证中间件

任务 5.7：请求日志中间件

批次 6：管理功能与部署

任务 6.1：Usage Dashboard API

任务 6.2：审计日志

任务 6.3：Provider Health Check API

任务 6.4：Docker 配置

任务 6.5：文档与示例

验证命令

单元测试

集成测试

全部测试

类型检查

代码风格

启动服务

风险与待确认项

时间估算

依赖关系

11 KiB

Raw Permalink Blame History