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>
This commit is contained in:
root
parent
bebe8c1bb5
commit
8f550a2100
419
docs/plans/2026-05-01-llm-gateway-plan.md
Normal file
419
docs/plans/2026-05-01-llm-gateway-plan.md
Normal file
@ -0,0 +1,419 @@
|
|||||||
|
# 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`
|
||||||
|
- **验证方式**：文档完整可读
|
||||||
|
- **完成判定**：代码审查通过
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 验证命令
|
||||||
|
|
||||||
|
### 单元测试
|
||||||
|
```bash
|
||||||
|
pytest tests/unit -v
|
||||||
|
```
|
||||||
|
|
||||||
|
### 集成测试
|
||||||
|
```bash
|
||||||
|
pytest tests/integration -v
|
||||||
|
```
|
||||||
|
|
||||||
|
### 全部测试
|
||||||
|
```bash
|
||||||
|
pytest -v --cov=app
|
||||||
|
```
|
||||||
|
|
||||||
|
### 类型检查
|
||||||
|
```bash
|
||||||
|
mypy app
|
||||||
|
```
|
||||||
|
|
||||||
|
### 代码风格
|
||||||
|
```bash
|
||||||
|
ruff check app
|
||||||
|
```
|
||||||
|
|
||||||
|
### 启动服务
|
||||||
|
```bash
|
||||||
|
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 (管理功能与部署)
|
||||||
|
```
|
||||||
Loading…
x
Reference in New Issue
Block a user