# 商用 LLM 通用转发网关演进方案（Subapi First）

- 版本：v2.0（续规划稿）
- 日期：2026-03-17
- 基线文档：
  - `llm_gateway_prd_v0_2026-03-16.md`
  - `llm_gateway_product_technical_blueprint_v1_2026-03-16.md`
  - `sub2api_integration_readiness_checklist_2026-03-16.md`
- 文档目标：在既有 PRD/技术蓝图基础上，明确“先集成 subapi，再逐步替代客户端 subapi，最终形成企业级控制面”的演进路径与边界。

## 1. 本轮续规划目标

围绕你提出的方向，形成四个连续目标：

1. 第一阶段以 `subapi` 作为集成底座，快速形成可售卖能力。
2. 逐步替代用户端 `subapi` 接入，统一到我方网关入口与控制面。
3. 后续增强“机器人客户（Bot Customer）”能力，支持自动化运营与客户成功流程。
4. 增加独立模块：
   - LLM 供应商账号导入（BYOA/BYOK）
   - 低成本 LLM 账号获取与治理（仅限合规来源）
   - 合规与审计增强（ToS、隐私、风控）

## 2. 三种演进路径对比（先决策）

### 路径 A：`subapi` 外部服务模块化（推荐）

1. 做法：
   - `subapi` 作为独立服务部署在数据面旁路。
   - 我方网关只通过内部 API 调用 `subapi` 的能力。
   - 核心账务、租户、权限、审计在我方控制面自研。
2. 优点：
   - 集成最快，风险隔离最好，回滚简单。
   - 可逐步替换，不会一次性重构核心链路。
3. 缺点：
   - 双系统运维复杂度增加。
   - 部分路由决策需跨服务，调优链路更长。

### 路径 B：反向代理链路串联（次选）

1. 做法：我方网关前置，`subapi` 作为后置中转层。
2. 优点：接入快，早期改造少。
3. 缺点：链路故障定位复杂，长期可维护性差。

### 路径 C：Fork 深度改造（谨慎）

1. 做法：维护私有 `subapi` 分支并深改为主系统。
2. 优点：短期控制力强。
3. 缺点：长期升级成本高，版本漂移和维护负担重。

结论：推荐路径 A，保持“快上线 + 可替换 + 可审计”的平衡。

## 3. 目标架构（控制面优先，数据面渐进替换）

## 3.1 架构原则

1. 控制面主权：租户、计费、权限、审计、合规全部沉淀在我方。
2. 数据面兼容：北向接口保持 OpenAI/Anthropic/Gemini 兼容，不强推客户改协议。
3. 双轨演进：短期借力 `subapi`，中期逐步把关键能力迁入自研 Router Core。
4. 风险前置：把合规和 ToS 校验纳入请求前置策略，而非事后补救。

## 3.2 分层模块

1. Ingress & Compatibility Layer
   - 统一 `/v1/*` 入口
   - 客户端兼容适配（历史 subapi 客户端参数映射）
2. Routing Orchestration Layer
   - Provider Registry
   - Policy Engine（预算、白名单、限流、回退）
   - `subapi connector`（阶段 1-2）
3. Provider Adapter Layer
   - OpenAI / Anthropic / Gemini / OpenRouter / 其他国产模型
   - 统一 usage 与错误标准化
4. Control Plane
   - Tenant/RBAC
   - Billing Ledger（pre-settle-refund）
   - Audit & Compliance
   - Provider Account Vault
5. Bot Customer Layer（后续）
   - 客户成功机器人
   - 运维机器人
   - 成本优化机器人

## 4. 分阶段路线图（以 2026-03-17 为起点）

## 阶段 S1：Subapi 集成上线（2026-03-17 至 2026-05-15）

目标：在 8 周内构建“可售卖 MVP”，验证付费与稳定性。

1. 产品能力
   - 统一入口 + 基础路由 + fallback
   - 租户/团队/Key 管理
   - 预算阈值告警 + 成本归因
   - 账单导出
2. 技术动作
   - 采用路径 A：`subapi` 外部服务模块化接入
   - 建立 `subapi connector` 与 `adapter registry`
   - 接入监控基线：错误率、P95、成本突增、熔断次数
3. Go/No-Go
   - 灰度 7 天可用性 >= 99.9%
   - 成本差错率 <= 0.1%
   - 回滚演练通过（30 分钟内）

## 阶段 S2：替代用户端 subapi（2026-05-16 至 2026-08-15）

目标：将客户“直接用 subapi”的模式迁到“统一用我方网关”。

1. 客户迁移机制
   - SDK/配置迁移向导（base URL、key、模型映射）
   - 兼容层保留旧参数与错误码映射
   - 按租户分批迁移（10%/30%/60%/100%）
2. 技术动作
   - 自研 Router Core 接管 >= 60% 主路径请求（全供应商口径）
   - 国内 LLM 供应商主路径请求由自研 Router Core 接管率 = 100%
   - `subapi` 仅保留长尾协议或备用回退
   - 完成 Provider 扩容到至少 6 家可用供应商
3. 商业目标
   - 新签客户默认走我方入口，不再直接依赖客户侧 subapi
   - 迁移客户 30 天留存与成功率不低于迁移前

## 阶段 S3：机器人客户能力（2026-08-16 至 2026-10-31）

目标：把“人肉运维与客户成功”升级为“机器人辅助闭环”。

1. Bot Customer 能力包
   - 成本优化机器人：给出模型替换建议与预算调优建议
   - 运维机器人：异常解释、回滚建议、故障摘要
   - 客户成功机器人：新客户接入引导、健康巡检、续费风险提示
2. 边界
   - 机器人只提供建议和自动化执行草案，关键动作仍需审批
   - 保留审计轨迹（谁触发、依据什么策略、最终执行结果）
3. 技术依赖
   - 事件总线与规则引擎
   - 对话上下文存储
   - 可观测数据聚合与指标解释层

## 阶段 S4：供应商账号导入 + 低成本账号模块 + 合规增强（2026-11-01 至 2027-03-31）

目标：形成差异化护城河，但严格遵循合规边界。

1. 供应商账号导入（BYOA/BYOK）
   - 支持客户导入 OpenAI/Anthropic/Gemini/其他账号凭证
   - Vault 加密存储、轮换、最小权限与可撤销
   - 账号健康状态、额度状态与风险状态统一可视化
2. 低成本账号模块（仅合规来源）
   - 仅允许官方渠道或授权分销渠道
   - 建立账号来源证明、合同/授权凭证、风控评分
   - 禁止任何违反上游 ToS 的灰色接入方式
3. 合规增强
   - ToS Policy Engine：按供应商、区域、模型动态拦截
   - 数据与隐私策略：PII 脱敏、日志保留策略、跨境策略
   - 审计报表：面向法务/安全/财务的统一合规报表

## 5. 核心模块设计补充（本轮新增）

## 5.1 Provider Account Vault

1. 凭证存储：KMS + 字段级加密 + 审计日志。
2. 生命周期：导入、校验、轮换、停用、吊销。
3. 访问控制：仅策略引擎短时解密，禁止控制台明文展示。

## 5.2 ToS & Compliance Engine

1. 规则维度：供应商条款、区域限制、模型限制、使用场景限制。
2. 执行位置：请求前置硬拦截 + 请求后审计与告警。
3. 输出：
   - 合规判定结果
   - 拦截原因码
   - 审计证据链

## 5.3 Bot Customer Orchestrator

1. 事件输入：预算超阈值、错误率突增、客户健康分下降。
2. 决策输出：建议动作（降级模型、加权切换、限流、回滚）。
3. 安全机制：高风险动作必须人工审批。

## 6. 指标与验收（续规划版）

## 6.1 产品与商业指标

1. 从“客户侧 subapi”迁移到“我方网关入口”的迁移完成率。
2. 单客户月度受管成本（GMV）与毛利率。
3. 预算超限前告警命中率与执行闭环率。

## 6.2 技术与稳定性指标

1. 网关附加时延 P95（不含上游推理） <= 60ms。
2. 请求可追踪率（request_id 全链路覆盖） = 100%。
3. 账务差错率 <= 0.1%，并可追溯到请求级。
4. S2 结束时主路径接管率（全供应商） >= 60%。
5. S2 结束时国内 LLM 供应商主路径接管率 = 100%。

## 6.3 合规与风控指标

1. 高风险策略误放行率接近 0（以红线规则为硬约束）。
2. 供应商 ToS 规则覆盖率（已接入供应商） = 100%。
3. 关键管理操作审计覆盖率 = 100%。

## 7. 风险与应对（针对本轮新增能力）

1. 低成本账号模块的法律风险
   - 应对：只做合规来源，法务前置审批，建立可审计证据链。
2. 机器人误触发导致运营事故
   - 应对：高风险动作审批制 + 演练 + 回滚预案。
3. 迁移期间双轨链路复杂度上升
   - 应对：按租户灰度、双写观测、阶段性去耦目标明确。
4. `subapi` 快速迭代导致兼容性回归
   - 应对：版本锁定 + 契约测试 + 周级升级窗口 + 自动回滚。

## 8. 本周可执行动作（2026-03-17 当周）

1. 冻结 S1 范围和不做清单（避免范围膨胀）。
2. 明确 `subapi connector` 契约：
   - 请求标准化字段
   - usage 对账字段
   - 错误码映射表
   - 契约文档：`subapi_connector_contract_v1_2026-03-17.md`
3. 建立迁移基线文档：
   - 客户侧 subapi -> 我方网关 的迁移手册 v0
4. 和法务定义 S4 的“低成本账号模块”红线条款模板。

## 9. 已拍板决策（2026-03-17）

1. 采用路径 A：`subapi` 外部服务模块化。
2. S2 结束时：自研 Router Core 主路径接管率（全供应商） >= 60%。
3. S2 结束时：国内 LLM 供应商主路径接管率 = 100%。

## 10. 待拍板的 4 个决策

1. S3 机器人能力优先顺序（成本优化优先 or 运维优先）。
2. S4 是否把“低成本账号模块”作为独立付费包。
3. 合规策略默认是“严格拦截”还是“告警+人工复核”。
4. 迁移节奏是“行业试点优先”还是“全客户统一批次”。

## 11. `subapi` 快速迭代集成保障机制（新增）

1. 版本治理
   - 生产环境固定 `subapi` 次版本（例如 `vX.Y.*` 锁定为 `vX.Y.Z`）。
   - 仅在周级升级窗口内升级，不做临时线上直升。
2. 契约治理
   - 建立 `subapi connector` 契约测试集（请求字段、错误码、usage、流式行为）。
   - 每次升级必须通过“兼容矩阵”后才允许灰度。
3. 发布治理
   - 灰度比例：5% -> 20% -> 50% -> 100%。
   - 每阶段观察至少 2 小时关键指标（5xx、P95、token 成本偏差、fallback 比例）。
4. 回滚治理
   - 保留上一稳定版本镜像和配置快照。
   - 任一红线触发（错误率、延迟、成本偏差）立即自动回滚到上一稳定版本。
5. 变更治理
   - 每周固定一次上游变更扫描（Release/Commit/Breaking Change）。
   - 对潜在破坏性变更创建“影响单”，先评估再排期升级。

## 12. S2 执行基线文档（新增）

为落实你已确认的 S2 目标（全供应商 `>=60%`、国内供应商 `100%`），新增执行层文档：

- `router_core_takeover_execution_plan_v3_2026-03-17.md`

该文档补齐了三类执行要素：

1. 接管率统一口径与计算公式（避免统计歧义）
2. 模块拆分 + 迁移优先级 + 批次节奏
3. 可验收测试矩阵与阶段门槛（质量/账务/接管率）

## 13. S2 执行附件（新增）

在 S2 阶段，除执行基线文档外，补充两份落地附件：

1. `router_core_takeover_metrics_sql_dashboard_v1_2026-03-17.md`
   - 定义接管率统计 SQL 与看板口径（overall/cn）。
2. `router_core_s2_acceptance_test_cases_v1_2026-03-17.md`
   - 按模块展开验收测试清单与分波次门禁。

## 14. 兼容性、安全与运维可靠性设计附件（新增）

为回应“subapi 快速迭代 + 商用集成”的实施风险，补充设计文档：

1. `subapi_integration_compat_security_reliability_design_v1_2026-03-17.md`
   - 定义兼容闸门、风险分级、强制配置硬化基线与运维可靠性机制。

## 15. 风险控制执行任务单（新增）

为避免“设计有了但执行失焦”，补充两周执行任务单：

1. `subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md`
   - 以绝对日期管理实施节奏（2026-03-18 至 2026-03-31）
   - 绑定责任角色、验收标准和证据产物
   - 纳入 daily/weekly gate 与回滚演练要求

## 16. 专家审核与博弈机制（新增）

为避免实施过程出现“团队内共识偏差”，补充独立专家审核机制：

1. `subapi_expert_review_wargame_plan_v1_2026-03-17.md`
   - 明确专家构成与独立性约束（含安全/合规一票否决）
   - 通过对抗式评审验证集成可行性、替换路径可行性与商用可靠性
   - 输出 GO / CONDITIONAL GO / NO-GO 结论与整改闭环

## 17. 三角色联合评审与优化（新增，2026-03-18）

为进一步降低实施期“用户体验断层、质量门禁失效、网关替换不可逆”风险，新增：

1. `subapi_role_based_review_wargame_optimization_v1_2026-03-18.md`
   - 角色范围：用户代表、测试专家、网关专家
   - 输出三角色 Red/Blue 博弈结论与条件放行门槛
   - 绑定新增任务：`UXR-001/002`、`TST-001/002/003`、`GAT-001/002/003`、`EXP-007`