lijiaoqiao/docs/llm_gateway_subapi_evolution_plan_v2_2026-03-17.md

商用 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