1用户与场景
| 用户 | 诉求 | 典型调用 |
|---|---|---|
| 内部产品后端（解梦/GEO 审计等） | 一个稳定、便宜、不用管多家 key 的推理入口 | 实时 chat/completions、embeddings |
| 内容流水线（programmatic-SEO 批量） | 大批量、可异步、成本最低 | Batch 提交 + 轮询结果 |
| 运营/财务 | 看清每个产品/模型的用量与成本 | 管理端用量查询 |
| 平台管理员 | 配渠道、配路由、发/吊 key、设配额 | 管理端配置 API |
2用户故事
- US-1：作为产品后端，我用 OpenAI SDK 把 baseURL 指向网关、用内部 key，就能调用，无需改动业务代码。
- US-2：作为产品后端，当我请求一个"逻辑模型名"（如
cheap-default），引擎自动路由到当前最划算的真实模型并在故障时回退，我无感。 - US-3：作为内容流水线，我提交 1,000 条可异步任务，引擎走 Batch 用更低价完成并回调/可轮询。
- US-4：作为运营，我能按 产品 / 模型 / 日 查询调用数、token、成本、命中率。
- US-5：作为管理员，我能新增一个渠道、调整路由权重、给某产品设日配额与 RPM，改配置不改代码。
- US-6：作为管理员，当某产品 key 异常飙升，我能立即吊销该 key 并收到告警。
3功能需求 FR
| ID | 需求 | 里程碑 |
|---|---|---|
| FR-1 | OpenAI 兼容 POST /v1/chat/completions，支持 stream:true SSE 与非流式 | M1 |
| FR-2 | OpenAI 兼容 POST /v1/embeddings、GET /v1/models（返回逻辑模型清单） | M2 |
| FR-3 | 内部 API key：签发/校验/吊销，按产品隔离，Authorization: Bearer sk-... | M1 |
| FR-4 | 逻辑模型 → 渠道映射；分层路由（免费兜底→便宜默认→高价值升级） | M2 |
| FR-5 | 失败回退：上游 429/5xx/超时 → 按优先级切换备用渠道；权重负载均衡 | M2 |
| FR-6 | 响应缓存（KV，可配 TTL，按规范化请求哈希）；prompt 缓存透传 | M2 |
| FR-7 | 令牌桶限流：每 key RPM 与并发上限；超限返回 429 + Retry-After | M1/M2 |
| FR-8 | 配额：每 key 日/月额度（按倍率折算的"额度单位"）；超额拒绝 | M2 |
| FR-9 | 计费记账：每请求记 model/in-out tokens/cost/latency/cache 命中/渠道，落 D1 | M1 |
| FR-10 | 管理端 API：渠道/模型/路由/key/配额 的 CRUD；用量聚合查询 | M2 |
| FR-11 | Batch 异步：提交批任务 → Queues 处理（可用厂商 Batch 价）→ 结果可取 | M3 |
| FR-12 | 声明式配置：渠道/路由/定价以配置（D1+可版本化文件）驱动，热更新 | M2 |
| FR-13 | 可观测：用量/成本/错误率/延迟/命中率指标 + 关键告警 | M3 |
| FR-14 | 红线护栏：渠道准入仅限合法来源白名单；非白名单渠道无法启用 | M2 |
4非功能需求 NFR
| 维度 | 目标 |
|---|---|
| 网关自身开销 | 路由+鉴权+记账的额外延迟 P50 < 30ms、P95 < 80ms（不含上游） |
| 缓存命中 | 命中时端到端 < 50ms、零上游成本 |
| 可用性 | 引擎层 99.9%；任一上游故障不致整体不可用（回退） |
| 成本 | 引擎自身基础设施月固定成本 ≤ $5（Workers Paid 起）；token COGS 由路由+缓存最小化 |
| 扩展性 | 新增渠道/模型仅改配置，无需改核心代码 |
| 安全 | 上游真实 key 不下发客户端；内部 key 可吊销；全链路 TLS |
| 可观测 | 每请求可追踪（request id）；用量/成本日聚合可查 |
| 合规 | 仅合法来源；数据使用对内部产品透明（哪些渠道会训练，见 01/08） |
5验收标准（样例，Given/When/Then）
AC-1（直通+记账）
Given 一个有效内部 key 与逻辑模型 cheap-default，When 调用 /v1/chat/completions，Then 返回 OpenAI 格式响应，且 D1 requests 新增一行含 model/tokens/cost/latency。
AC-2（回退）
Given 首选渠道返回 429，When 同一请求处理中，Then 引擎自动切到次优渠道并成功返回，响应头 x-gw-channel 标记实际渠道，记账标记 fallback=true。
AC-3（缓存）
Given 同一规范化请求二次到达且在 TTL 内，When 调用，Then 命中缓存、不调上游、x-gw-cache: hit、记账 cost=0。
AC-4（配额/限流）
Given 某 key 当日额度已用尽，When 再次调用，Then 返回 429 + 错误体 quota_exceeded；RPM 超限返回 429 + Retry-After。
AC-5（红线护栏）
Given 尝试把一个非白名单（逆向/养号）端点配置为渠道，When 保存配置，Then 被拒绝并记审计日志。
6成功指标
≥80%
高频场景缓存命中率（目标）
10~25%
接入产品的 token COGS 占收入
<80ms
引擎自身 P95 额外延迟
100%
请求被记账（可对账）