lijiaoqiao/docs/llm_gateway_subapi_evolution_plan_v4_1_2026-03-18.md

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

• 版本：v4.1（基线收敛版）
• 日期：2026-03-18
• 基线文档：
  • llm_gateway_prd_v0_2026-03-16.md
  • llm_gateway_product_technical_blueprint_v1_2026-03-16.md
  • subapi_integration_readiness_checklist_2026-03-16.md → 统一使用 "subapi"
  • supply_side_product_design_v1_2026-03-18.md
  • s2_staged_verification_mechanism_v1_2026-03-18.md
  • tos_compliance_engine_design_v1_2026-03-18.md
• 文档目标：在既有 PRD/技术蓝图基础上，明确"先集成 subapi，再逐步替代客户端 subapi，最终形成企业级控制面"的演进路径与边界，整合评审新增内容。

---

0. 术语字典（v3.1新增）

术语	英文	定义	备注
subapi	Subapi	开源 LLM 转发项目，本方案的核心集成对象	统一使用 "subapi"，不再使用 "sub2api"
供应方	Provider	在平台挂载多余LLM配额的个人或企业	平台的用户角色
供应商	Supplier	LLM 服务提供商（如 OpenAI、Anthropic、百度等）	上游账号来源
采购折扣系数	Procurement Discount	供应方获得官方价格的折扣比例	本方案定义为 60%
毛利率	Gross Margin	平台销售收入与采购成本的差额比例	目标 15-50%
接管率	Takeover Rate	自研 Router Core 处理请求的比例	S2目标60%（全供应商）
国内供应商	Domestic Provider	国内 LLM 服务商（百度、讯飞、腾讯等）	S2目标100%接管

---

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-18 为起点）

阶段 S0：供应侧产品设计准备（2026-03-18 至 2026-06-08，12周）

目标：验证"用户分享多余LLM套餐"独特场景的产品化可行性

本阶段为评审建议新增，聚焦平台的核心差异化场景

1. 供应侧 MVP 能力
   • 供应方入驻与实名认证
   • 套餐验证引擎 v1（L1+L2）
   • 手动定价机制
   • 基础赔付机制
2. 验收标准
   • 引入首批 10 家供应方
   • 套餐验证成功率 >= 90%

阶段 S1：Subapi 集成上线（2026-03-18 至 2026-05-15，与 S0 并行）

目标：在 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"的模式迁到"统一用我方网关"。

⚠️ 根据评审建议，增加40%中间检查点，分阶段验证

1. 客户迁移机制

   • SDK/配置迁移向导（base URL、key、模型映射）
   • 兼容层保留旧参数与错误码映射
   • 按租户分批迁移（10%/30%/40%/60%/100%）

2. 技术动作

   • 自研 Router Core 接管 >= 60% 主路径请求（全供应商口径）
   • 国内 LLM 供应商主路径请求由自研 Router Core 接管率 = 100%
   • subapi 仅保留长尾协议或备用回退
   • 完成 Provider 扩容到至少 6 家可用供应商

3. 分阶段验证（评审建议新增）

   阶段	时间	接管率	验收方式
   S2-A	W1-W4	10%	Gate A 通过
   S2-B	W5-W8	30%	Gate B 通过
   S2-C1	W9-W10	40%	Gate C1 中间检查点
   S2-C2	W11-W13	60%	Gate C2 通过

4. 商业目标

   • 新签客户默认走我方入口，不再直接依赖客户侧 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. 供应侧产品设计（评审建议新增章节）

本章节详细设计"用户分享多余LLM套餐"这一核心独特场景

5.1 供应侧业务模型

角色	定义	核心诉求
供应方（Provider）	拥有多余LLM配额的个人或企业	将闲置配额变现，回笼资金
平台（Platform）	统一网关平台	汇集供应方资源，提供稳定服务，赚取差价
需求方（Consumer）	需要LLM调用能力的企业/开发者	以优惠价格获取LLM服务，无需自建账号

5.2 统购统销定价模型

定价层级	定价方式	参数
采购价（P0）	平台统一定价收购	采购折扣系数 = 60%（供应方获得官方价格60%）
出售价（P1）	平台加价出售	毛利率目标 = 15-50%

5.3 套餐有效性验证机制

验证层级	验证内容	验证方式
L1 基础验证	API Key格式、供应商连通性	自动调用供应商API检查有效性
L2 额度验证	剩余配额、账户状态	调用供应商账户API获取额度信息
L3 行为验证	账户历史行为、风险评分	平台风控模型评估
L4 持续监控	配额消耗异常、账户异常	实时监控+告警

5.4 风险控制

风险类型	防控措施
套餐有效性风险	实时监控+提前告警，自动切换备用套餐
滥用风险（薅羊毛）	供应方需缴纳保证金（个人500/企业5000），实名认证
ToS 合规风险	ToS 合规引擎（详见第8章）

---

6. 核心模块设计补充

6.1 Provider Account Vault

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

6.2 ToS & Compliance Engine

1. 规则维度：供应商条款、区域限制、模型限制、使用场景限制。
2. 执行位置：请求前置硬拦截 + 请求后审计与告警。
3. 执行模式：告警+人工复核（默认），红线规则严格拦截。
4. 输出：
   • 合规判定结果
   • 拦截原因码
   • 审计证据链

6.3 Bot Customer Orchestrator

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

---

7. 指标与验收

唯一门禁口径来源：acceptance_gate_single_source_v1_2026-03-18.md。
若与其他文档阈值冲突，以该门禁表为准。

7.1 产品与商业指标

1. 从"客户侧 subapi"迁移到"我方网关入口"的迁移完成率。
2. 单客户月度受管成本（GMV）与毛利率：15-50%。
3. 预算超限前告警命中率与执行闭环率。
4. 供应侧指标：
   • S0 结束时：供应方数量 >= 10
   • S1 结束时：套餐验证成功率 >= 90%

7.2 技术与稳定性指标

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

7.3 合规与风控指标

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

---

8. ToS 合规引擎设计（评审建议新增章节）

8.1 合规规则体系

ToS 规则体系
│
├── 🔴 红线规则（Red Line）- 严格拦截
│   ├── 账号共享禁令
│   ├── 转售禁令
│   ├── 商业用途限制
│   └── 地区访问限制
│
├── 🟡 黄线规则（Yellow Line）- 告警+人工复核
│   ├── 使用量异常
│   ├── 调用模式异常
│   ├── 新型使用场景
│   └── 未明确允许的用途
│
└── 🟢 绿线规则（Green Line）- 通过

8.2 执行模式

阶段	执行模式	说明
S1	告警+人工复核	积累经验，完善规则
S2	告警+人工复核	持续优化
S3	逐步切换	黄线告警+复核，红线拦截
S4	分类执行	红线拦截，黄线复核，绿线放行

8.3 供应商合规矩阵

供应商          │ 账号共享 │ 转售 │ 代理 │ 地区限制
────────────────┼──────────┼──────┼──────┼─────────
OpenAI          │   🔴     │  🔴  │  🟡  │   🔴
Anthropic       │   🔴     │  🔴  │  🔴  │   🔴
Gemini          │   🔴     │  🔴  │  🟡  │   🔴
Azure OpenAI    │   🔴     │  🟢  │  🟢  │   🟢
国内供应商      │   🟡     │  🟡  │  🟡  │   🔴

---

9. 风险与应对

1. 低成本账号模块的法律风险

   • 应对：只做合规来源，法务前置审批，建立可审计证据链。

2. 机器人误触发导致运营事故

   • 应对：高风险动作审批制 + 演练 + 回滚预案。

3. 迁移期间双轨链路复杂度上升

   • 应对：按租户灰度、双写观测、阶段性去耦目标明确。

4. subapi 快速迭代导致兼容性回归

   • 应对：版本锁定 + 契约测试 + 周级升级窗口 + 自动回滚。

5. 国内供应商100%接管风险（评审新增）

   • 应对：S2阶段分步骤验证，40%中间检查点，未达标可回滚

6. Subapi API Key 安全漏洞（P0）

   • 问题：Subapi 的 API Key 只验证算法，不验证来源，不同部署的 Key 可互相串用
   • 应对：我们的系统必须自建 Key 体系，Key 必须包含平台标识（如 lgw-），必须数据库验证
   • 详见：security_api_key_vulnerability_analysis_v1_2026-03-18.md

---

10. 本周可执行动作（2026-03-18 当周）

1. 冻结 S0 范围和不做清单（避免范围膨胀）。
2. 明确供应侧产品MVP范围：
   • 供应方入驻流程
   • 套餐验证L1+L2
   • 统购统销定价（采购60%，毛利15-50%）
3. 明确 subapi connector 契约。
4. 和法务定义 S4 的"低成本账号模块"红线条款模板。
5. 启动 S2 分阶段验证机制的技术设计。

---

11. 已拍板决策

编号	决策项	决策结果	日期
D0-1	演进路径	路径 A：subapi 外部服务模块化	2026-03-17
D0-2	S2 全供应商接管率	>= 60%	2026-03-17
D0-3	S2 国内供应商接管率	= 100%	2026-03-17
D1	采购折扣系数	60%	2026-03-18
D2	毛利率目标	15-50%	2026-03-18
D3	合规策略默认模式	告警+人工复核	2026-03-18
D4	S3 机器人能力优先级	运维优先	2026-03-18
D5	S2 中间检查点	40%	2026-03-18
D6	S2 接管率过程预警区间	40-60%（仅过程预警，不作为终验口径）	2026-03-18
D7	S0 周期	12周	2026-03-18
D8	S2 周期	13周	2026-03-18

12. 待拍板的决策

1. S3 机器人能力优先顺序 → 已拍板：运维优先
2. 合规策略默认模式 → 已拍板：告警+人工复核
3. S4 低成本账号模块 → 已拍板：不作为独立付费包，并入Enterprise，属于阶段性供应链功能增强
4. 迁移节奏 → 已拍板：优先用户迁移

---

13. 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）。
   • 对潜在破坏性变更创建"影响单"，先评估再排期升级。

---

14. S2 分阶段验证机制（评审建议新增）

详见独立文档：s2_staged_verification_mechanism_v1_2026-03-18.md

核心要点：

• 三阶段推进：10% → 30% → 40% → 60%
• 40% 中间检查点作为关键决策点
• 明确的 Gate 验收标准和红灯阈值
• 回滚机制和责任矩阵

---

15. 关联文档清单

文档	状态	说明
llm_gateway_prd_v0_2026-03-16.md	已有	产品需求文档
llm_gateway_product_technical_blueprint_v1_2026-03-16.md	已有	技术蓝图
supply_side_product_design_v1_2026-03-18.md	新增	供应侧产品设计
s2_staged_verification_mechanism_v1_2026-03-18.md	新增	S2分阶段验证机制
tos_compliance_engine_design_v1_2026-03-18.md	新增	ToS合规引擎设计
business_model_profitability_design_v1_2026-03-18.md	新增	商业模式与盈利能力设计
supply_feature_technical_analysis_v1_2026-03-18.md	新增	Subapi技术能力分析
supply_detailed_design_v1_2026-03-18.md	新增	用户供应完整详细设计
security_api_key_vulnerability_analysis_v1_2026-03-18.md	新增	API Key安全漏洞分析
resource_assessment_plan_v1_2026-03-18.md	新增	资源评估与补充方案
s2_takeover_buffer_strategy_v1_2026-03-18.md	新增	S2接管率目标Buffer策略
acceptance_gate_single_source_v1_2026-03-18.md	新增	唯一验收门禁表（Single Source）
test_plan_go_aligned_v1_2026-03-18.md	新增	Go主测试链路对齐方案
technical_architecture_optimized_v2_2026-03-18.md	新增	优化技术架构（最小栈+触发式扩容）
tos_legal_communication_plan_v1_2026-03-18.md	新增	ToS合规法务前置沟通方案
security_solution_v1_2026-03-18.md	新增	安全解决方案(P0修复)
architecture_solution_v1_2026-03-18.md	新增	架构解决方案(P0修复)
api_solution_v1_2026-03-18.md	新增	API设计解决方案(P0修复)
business_solution_v1_2026-03-18.md	新增	业务解决方案(P0修复)
p1_optimization_solution_v1_2026-03-18.md	新增	P1优化问题解决方案

---

16. P0/P1问题修复汇总

16.1 P0问题修复状态

问题ID	问题	解决方案	状态
S-01	计费数据防篡改缺失	双重记账 + 审计日志	✅
S-02	跨租户隔离不完善	RLS + 强制验证	✅
S-03	密钥轮换机制缺失	生命周期管理	✅
A-01	Router Core自研风险	增加40%中间检查点与分阶段止损（终验目标仍为>=60%）	✅
A-02	subapi耦合风险	Adapter抽象层	✅
A-03	数据一致性风险	同步预扣+异步确认	✅
API-01	API版本管理缺失	URL版本策略	✅
API-02	错误码体系不完善	完整错误码设计	✅
API-03	SDK规划缺失	Python/Node SDK	✅
B-01	资金池合规风险	资金托管+税务合规	✅
B-02	计费精度风险	Decimal精确计算	✅
B-03	供应方结算风险	对账+保证金+阶梯	✅

16.2 P1问题修复状态

问题ID	问题	解决方案	状态
S-04	ToS合规检测不完整	动态监控	✅
S-05	激活码安全强度不足	HMAC-SHA256	✅
A-04	缺乏容量规划	基线测试+公式	✅
A-05	故障隔离不完善	断路器+舱壁	✅
A-06	可观测性不足	SLI/SLO体系	✅
API-04	限流设计不足	多维度限流	✅
API-05	缺乏批量操作	Batch API	✅
API-06	Webhooks缺失	Webhook机制	✅
B-04	毛利率不稳定	动态定价引擎	✅
B-05	风控覆盖不完整	需求方风控	✅
B-06	定价模型不清晰	明确定价公式	✅

详见独立文档：

• supply_feature_technical_analysis_v1_2026-03-18.md - 技术评估
• supply_side_product_design_v1_2026-03-18.md - 产品设计
• supply_detailed_design_v1_2026-03-18.md - 完整详细设计

16.1 Subapi 技术评估结论

维度	评估
技术了解深度	充分 - 已有详细 Connector 契约
供应商覆盖	10+ 供应商，100+ 模型
集成可行性	可行 - 路径 A 风险可控

16.2 Subapi 供应商能力

类别	供应商
海外主力	OpenAI, Anthropic, Gemini, Antigravity, Sora, Bedrock
国内支持	百度文心, 讯飞星火, 腾讯混元

16.3 Subapi 安全能力评估

能力	支持情况	说明
API Key 鉴权	✅	平台统一管理 Key
Token 级计费	✅	精确追踪
并发/速率限制	✅	可配置
IP 白名单	⚠️	有限支持
ToS 合规检测	❌	无专门检测

16.4 关键发现：用户供应功能

⚠️ Subapi 不支持"用户分享LLM供应"功能

• Subapi 模式：平台方统一管理上游账号 → 分发给用户使用
• 用户需求：用户可挂载自己账号 → 平台售卖 → 收益分成

结论：用户供应功能需平台层自研，不在 subapi 范围内

16.5 用户供应功能详细设计

16.5.1 安全机制

模块	功能
账号挂载	格式校验 → 有效性验证 → 额度查询 → ToS检查 → 风险评估 → 加密存储
调用验证	API Key → 套餐有效性 → 额度检查 → 风控 → ToS合规
防欺诈	额度异常/短时大量/新账号高额/跨地区/账号共享检测
保证金	个人¥500 / 企业¥5,000

16.5.2 核心数据模型

表名	说明
supply_accounts	供应方账号表
supply_packages	供应套餐表
supply_orders	订单表
supply_usage_records	使用记录表(每次调用)
supply_earnings	供应方收益表
supply_settlements	结算记录表

16.5.3 调度策略

策略	说明
最低价格	选择售价最低的套餐
负载均衡	选择负载最低的套餐
轮询	依次选择各套餐
供应商偏好	优先特定供应商

16.6 用户供应功能阶段规划

阶段	时间	任务
S0-a	W1-W2	账号挂载模块(挂载/验证/下架)
S0-b	W3-W4	套餐发布模块(上架/定价/展示)
S0-c	W5-W6	调度与计费模块(实时调度/扣减/账单)
S0-d	W7-W8	风控模块(健康监控/欺诈检测/合规)
S0-e	W9-W10	内部测试
S0-f	W11-W12	首批供应方引入(10家)

---

文档版本：v4.1（整合评审建议 + 基线收敛版） 下次评审：S0 阶段结束（预计2026-06-08）

文档状态：v4.1（整合评审建议 + 基线收敛版） 下次评审：S0 阶段结束（预计2026-06-08）