wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M1-01 AI Gateway 深化 #15

New Issue
Open
opened 2026-05-22 21:03:23 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:03:23 +08:00
Owner
Copy Link

目标

在 M0-08 AI Gateway 基础版之上深化 AI 网关能力，实现基础主备降级、Admin 模型路由管理、JSON Schema 校验和成本日志闭环。

本 Issue 只做深化设计，基础能力（统一调用封装、Prompt 管理、token 统计、重试、超时）已在 M0-08 完成。

背景说明

M0-08 建立了 AI Gateway 的统一调用框架。本阶段需要在此基础上补充生产级能力：当 DeepSeek 主模型不可用时自动 fallback 到备用模型、Admin 能在页面上管理模型路由规则、AI 输出通过 JSON Schema 校验确保格式正确。

注意：本阶段只做基础主备 fallback，不做生产级自动熔断系统（复杂熔断窗口、自动健康评分、动态权重调度不在 M1 范围内）。

模块深化内容

  1. 模型降级策略：

    • Admin 配置主模型/备用模型的映射关系
    • 单次调用失败时自动尝试备用模型
    • 支持 Admin 手动禁用某个 provider
    • 降级事件日志记录

  2. Admin 模型路由管理：

    • 路由规则可视化配置页面
    • 按任务类型（chat/ocr/vision/embedding）绑定模型
    • 路由规则变更审计

  3. JSON Schema 校验：

    • 为结构化 AI 输出（如 AIAnalysisResult、KnowledgeItem 等）定义 JSON Schema
    • 校验失败时的重试或降级策略
    • Schema 版本管理

  4. 成本日志闭环：

    • AIUsageLog 标准化字段补齐
    • 与 Quota/Cost 模块的事件消费链路打通

基础设施依赖变更

相比 M0-08 基础版，新增依赖：

  • 无新增基础设施，所有能力在现有组件上深化

接口设计（新增部分）

AAPI 新增/深化：

  • 模型路由规则 CRUD
  • Provider 启用/禁用开关
  • 降级事件日志查看

Domain Event（新增）

  • ModelFallbackTriggered：降级触发
  • ModelRouteChanged：路由规则变更

交付检查

  • 路由归属：Internal Provider 深化 + AAPI 新增接口
  • 是否需要 Prisma migration：是（路由规则表、降级日志表）
  • 是否需要 MySQL：是
  • 是否需要 Redis：否
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：本模块深化
  • 是否需要 Content Safety：是（已有依赖，不变）
  • 是否需要 Cost 记录：是（AIUsageLog 闭环）
  • 是否需要 AuditLog：是（路由规则变更、Provider 禁用）
  • 是否需要 Domain Event：是（新增降级事件）
  • 是否需要 Admin 视图：是（路由管理页新增）
  • 是否需要 E2E/集成测试：是

验收标准

  1. 主备模型降级方案设计 + 实现（在 M0-08 基础上）
  2. Admin 模型路由管理页面设计
  3. JSON Schema 校验方案设计
  4. AIUsageLog 与 Cost 模块消费链路打通
  5. 集成测试覆盖降级场景

禁止事项

  • 禁止做复杂熔断窗口（如半开/全开/关闭状态机）
  • 禁止做自动健康评分和动态权重调度（手动配置即可）
  • 禁止做多供应商自动切换的生产级服务治理系统
  • 禁止降级逻辑绕过 Content Safety 和 Cost 记录

不建议当前阶段实现

  • opossum 完整熔断集成
  • 基于延迟和错误率自动选优
  • 流式输出降级方案
## 目标 在 M0-08 AI Gateway 基础版之上深化 AI 网关能力，实现基础主备降级、Admin 模型路由管理、JSON Schema 校验和成本日志闭环。 本 Issue 只做深化设计，基础能力（统一调用封装、Prompt 管理、token 统计、重试、超时）已在 M0-08 完成。 ## 背景说明 M0-08 建立了 AI Gateway 的统一调用框架。本阶段需要在此基础上补充生产级能力：当 DeepSeek 主模型不可用时自动 fallback 到备用模型、Admin 能在页面上管理模型路由规则、AI 输出通过 JSON Schema 校验确保格式正确。 注意：本阶段只做基础主备 fallback，不做生产级自动熔断系统（复杂熔断窗口、自动健康评分、动态权重调度不在 M1 范围内）。 ## 模块深化内容 1. 模型降级策略： - Admin 配置主模型/备用模型的映射关系 - 单次调用失败时自动尝试备用模型 - 支持 Admin 手动禁用某个 provider - 降级事件日志记录 2. Admin 模型路由管理： - 路由规则可视化配置页面 - 按任务类型（chat/ocr/vision/embedding）绑定模型 - 路由规则变更审计 3. JSON Schema 校验： - 为结构化 AI 输出（如 AIAnalysisResult、KnowledgeItem 等）定义 JSON Schema - 校验失败时的重试或降级策略 - Schema 版本管理 4. 成本日志闭环： - AIUsageLog 标准化字段补齐 - 与 Quota/Cost 模块的事件消费链路打通 ## 基础设施依赖变更 相比 M0-08 基础版，新增依赖： - 无新增基础设施，所有能力在现有组件上深化 ## 接口设计（新增部分） AAPI 新增/深化： - 模型路由规则 CRUD - Provider 启用/禁用开关 - 降级事件日志查看 ## Domain Event（新增） - ModelFallbackTriggered：降级触发 - ModelRouteChanged：路由规则变更 ## 交付检查 - [ ] 路由归属：Internal Provider 深化 + AAPI 新增接口 - [ ] 是否需要 Prisma migration：是（路由规则表、降级日志表） - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：否 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：本模块深化 - [ ] 是否需要 Content Safety：是（已有依赖，不变） - [ ] 是否需要 Cost 记录：是（AIUsageLog 闭环） - [ ] 是否需要 AuditLog：是（路由规则变更、Provider 禁用） - [ ] 是否需要 Domain Event：是（新增降级事件） - [ ] 是否需要 Admin 视图：是（路由管理页新增） - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. 主备模型降级方案设计 + 实现（在 M0-08 基础上） 2. Admin 模型路由管理页面设计 3. JSON Schema 校验方案设计 4. AIUsageLog 与 Cost 模块消费链路打通 5. 集成测试覆盖降级场景 ## 禁止事项 - 禁止做复杂熔断窗口（如半开/全开/关闭状态机） - 禁止做自动健康评分和动态权重调度（手动配置即可） - 禁止做多供应商自动切换的生产级服务治理系统 - 禁止降级逻辑绕过 Content Safety 和 Cost 记录 ## 不建议当前阶段实现 - opossum 完整熔断集成 - 基于延迟和错误率自动选优 - 流式输出降级方案
wangdl added this to the M1：AI / RAG 运行时与检索底座（P0~P1） milestone 2026-05-22 21:03:23 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M1：AI / RAG 运行时与检索底座（P0~P1）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#15
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?