API Edge 实施计划
提供客户模型 API、协议兼容和流式转发
目标与范围
提供客户模型 API、协议兼容和流式转发。Core 负责身份、价格和账务；独立网关负责供应选择及实际执行。Edge 不维护客户钱包、供应渠道后台或第二份客户数据库。
需求输入与确认
以公共模型接口、兼容接口和媒体任务接口逐项确定支持范围。首条链路为模型发现与文本生成；用户已明确需要 OpenAI Chat/Responses、Anthropic Messages 与 Gemini 原生等标准格式。当前按第二阶段目标核对实际入口并验证受控透传，供应商格式转换交 uumi；上游占位路由和未联调能力不列为已支持。
设计与原型
设计请求上下文、Core Client、网关 Client、流式事件与用量交接的边界。以可回放的流式样本验证首包、结束事件、上游错误、客户端断开和背压；模拟依赖必须明确标注。定义何时已可能执行付费请求，避免错误重试。
API 与文档交付
复用 new-api router/relay、格式解析、流式 helpers 与错误映射。GET /v1/models、POST /v1/chat/completions 优先；completions、messages、embeddings、rerank 等按接口范围扩展。
内部契约定义 Core 授权、预留、结算与查询；供应凭据仅由内部网关 Client 使用。交付每种协议的 Schema、请求/流式/错误样例、兼容差异与配置说明。
实施步骤与交付物
| 步骤 | 实施内容 | 交付物与退出条件 |
|---|---|---|
| EDGE-01 工程 | 固定 Go 与依赖、配置、探针、超时和关闭行为 | 可独立构建启动；依赖缺失时不开放虚假业务就绪状态 |
| EDGE-02 模型发现 | 接 Core 可用模型与权限，映射兼容模型响应 | 已授权模型可见；未知/禁用模型、无效 Key 按协议拒绝 |
| EDGE-03 文本协议 | 迁入 chat/completions 解析、普通响应和流式转发 | 固定回放验证字段、事件结束和错误；不缓冲全部输出 |
| EDGE-04 授权计费接入 | Core 服务鉴权、Key/模型/IP 限制、原子预留、用量与结算查询 | 依赖失败时不越过准入；禁止重复扣费与盲目重提 |
| EDGE-05 真实网关联调 | 内部凭据调用网关，关联平台与供应请求 | 一次真实文本输出与客户账务可核对；断流/超时/响应丢失通过 |
| EDGE-06 协议扩展 | 按需要加入 messages、embeddings、rerank 和媒体入口 | 每个协议独立记录支持范围、计量单位和兼容用例 |
| EDGE-07 容量与运行 | 并发长连接、背压、限流、滚动退出和依赖故障 | 环境、负载、时延、错误率及资源报告；观测关联可查询 |
依赖与接入顺序
EDGE-01 后可独立做解析回放；真实 EDGE-02/04 依赖 Core 权威准入和目录。EDGE-05 依赖网关内部调用配置与 Core 结算。对应 CE-01/03/05/06；媒体入口依赖媒体联调计划。
验收标准
- 客户 Key 不交给供应端；Core 拒绝、撤销、余额不足时不执行。
- 正常与流式响应兼容；上游错误、客户端断开、Core 不可用均有明确行为。
- 请求、用量、结算有稳定关联；重复交接不重复收费。
- 记录实测并发与资源，框架选择不能替代容量证明。
待定项与后续范围
首发协议组合、授权缓存撤销时限、连接/请求限制、目标并发与超时参数按接口和容量测试确定。媒体插件并非全量默认启用。
本文定义计划，不累积执行日志。实际版本、完成状态和验证证据见项目进度；任务状态登记到本机工作台，并关联本文步骤。