diff --git a/docs/plans/2026-05-01-llm-gateway-plan.md b/docs/plans/2026-05-01-llm-gateway-plan.md new file mode 100644 index 0000000..eb15fe3 --- /dev/null +++ b/docs/plans/2026-05-01-llm-gateway-plan.md @@ -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 (管理功能与部署) +```