本页目录展开
  1. 账号、Key 与余额
  2. 模型目录与健康检查
  3. 请求转发与用量
  4. 计费与限流
  5. 来源校验与观测
  6. 面试速答

API 平台(sseapi,server/ 约 8700 行、web/ 约 5400 行)是 AI Infra 的统一出口:对外提供 OpenAI 兼容接口与 Claude 协议适配;对内转发到 vLLM 等上游,按 token 计费、按 Key 限流。

账号、Key 与余额

控制台用集市 OAuth 登录:GET /api/auth/oauth/config、/login-url、POST /token、GET /userinfo、GET /api/auth/me;控制台会话与 API Key 是两套凭证。

Key 在控制台创建(GET/POST /api/keys、PATCH/DELETE /api/keys/:id),可绑定来源域名,复制 sk- 串填进客户端。Key 只展示一次,库里存哈希,列表只返回前缀与末四位,完整 Key 需重建。Key 与用户多对一,计费与限流都挂在 Key 上;挂用户的话,多个项目的 Key 会抢配额。

余额看 GET /api/billing/balance,流水 /ledger,汇总 /summary。每次调用写一条用量记录并带本笔之后的余额快照;只存变动额,对账要重放全部历史才能算出某时点余额。签到 GET/POST /api/billing/checkin 按「用户 + 日期」唯一,奖励入账并写流水;日期用服务端时区,否则跨时区可重复签到。

模型目录与健康检查

管理员登记上游地址、served_model_name、上游 Key、入出单价、RPM / 并发。对外只暴露平台 Slug,/v1/models 返回 Slug 列表,换上游不动客户端。

POST /api/models/test、/:id/test 发最小请求验证连通;POST /api/models/:id/test-protocol 单独验证协议兼容性(流式字段、usage 是否存在)。只 ping 通的上游可能缺 usage,计费只能靠估算。

served_model_name 必须与上游 vLLM 启动参数一致。不一致时上游返回 model not found,而网关常把它包装成 502,排查时容易误判成网络问题。

请求转发与用量

入口有五个:/v1/chat/completions(OpenAI 兼容、支持流式)、/v1/embeddings、/v1/rerank、/v1/images/generations,以及 /v1/messages(Claude 协议,经适配层转换)。前置流程统一:Bearer sk- 找 Key → 校验状态与余额 → 校验来源 → 按 Slug 找上游 → 转发 → 旁路计费。

Claude 适配在 server/src/services/claude-adapter.ts,双向转换 Anthropic 风格的 messages 请求与响应;系统提示和工具调用的字段差异都要处理,只转文本会让工具调用丢失。

流式响应逐行解析 data:,取最后一条带 usage 的事件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// server/src/routes/proxy.ts
function extractUsageFromSse(buf: string) {
let last = { prompt: 0, completion: 0, cached: 0, imageTokens: 0, found: false };
for (const line of buf.split(/\r?\n/)) {
const t = line.trim();
const data = t.startsWith('data:') ? t.slice(5).trim() : '';
if (!data || data === '[DONE]') continue;
try {
const u = readUsage(JSON.parse(data)?.usage);
if (u.found) last = u; // 取最后一条带 usage 的
} catch { /* 忽略半包 */ }
}
return last;
}

非流式直接读响应体 usage;两边都拿不到时按字符数估算(约 4 字符 1 token),并在 usage_source 标记 usage | estimate。估算前必须用 redactImagesForEstimate 替换图片,base64 字符数会把 token 估到几十万。SSE 分块会切断 JSON,解析失败要跳过,否则一个半包会毁掉整次调用。

计费与限流

单价按「每百万 token」存,输入、输出分别计价,可另设缓存价与图片价;cost = prompt_tokens / 1e6 * input_price_per_1m + completion_tokens / 1e6 * output_price_per_1m。金额用整数分或定点数累加,浮点累积误差,对账总会差几分钱。

限流维度是 Key,RPM 与并发两档,超限返回 429 并给出重试时间(管理端 GET /api/admin/rate-limits、/status)。两种约束缺一不可:只限 RPM,突发并发仍能打满上游;只限并发,慢速高频请求仍能占满连接。

余额检查必须在转发之前,不足直接拒绝;已发生的调用照常扣费。放到响应之后,欠费用户可以无限调用直到下次登录。

来源校验与观测

Key 可绑定来源列表。server/src/services/origins.ts 的 parseOriginList 按换行、逗号、分号切分配置;normalizeHost 转小写、经 new URL 取 host、去端口与路径后再比较,允许配置裸域名或完整 URL。直接比较会因大小写、端口、尾斜杠误判。Key 与 Token 只存哈希,泄露后非白名单来源无法使用。

管理端可查用户、改额度、看单人用量与明细(/api/admin/users、/api/admin/usage/by-user、/api/admin/usage/by-user/:userId/reqs);GET /api/admin/logs 记 Key、Slug、token 数、耗时、状态码,可按时间与 Key 过滤,统计在 /api/admin/stats。日志不能记请求正文——可能含隐私与密钥,排障只要元数据。文档由 /api/docs、/api/public/docs 提供元数据,docs/ 放文档。

面试速答

  • 兼容层:OpenAI 兼容 + Claude 适配;model 是 Slug,换上游不动客户端。
  • 转发:统一前置(Key → 余额 → 来源 → 上游),流式透传并旁路计费。
  • 用量:优先取上游 usage,取不到按 4 字符 1 token 估算并标记来源。
  • 计费:按每百万 token,整数分累加,流水带余额快照。
  • 限流:RPM 与并发双约束,维度为 Key;余额检查在转发前。
  • 安全:Key 只存哈希,来源按归一化 host 比较。

→ 下一篇:TTS 与 AI 研究