M1-01 AI Gateway 深化 #15

New Issue

wangdl · 2026-05-22T21:03:23+08:00

wangdl commented

2026-05-22 21:03:23 +08:00

目标

在 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 范围内）。

模块深化内容

模型降级策略：
- Admin 配置主模型/备用模型的映射关系
- 单次调用失败时自动尝试备用模型
- 支持 Admin 手动禁用某个 provider
- 降级事件日志记录
Admin 模型路由管理：
- 路由规则可视化配置页面
- 按任务类型（chat/ocr/vision/embedding）绑定模型
- 路由规则变更审计
JSON Schema 校验：
- 为结构化 AI 输出（如 AIAnalysisResult、KnowledgeItem 等）定义 JSON Schema
- 校验失败时的重试或降级策略
- Schema 版本管理
成本日志闭环：
- 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/集成测试：是

验收标准

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

禁止事项

禁止做复杂熔断窗口（如半开/全开/关闭状态机）
禁止做自动健康评分和动态权重调度（手动配置即可）
禁止做多供应商自动切换的生产级服务治理系统
禁止降级逻辑绕过 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：路由规则变更 ## 交付检查 - [x] 路由归属：Internal Provider 深化 + AAPI 新增接口 - [x] 是否需要 Prisma migration：是（路由规则表、降级日志表） - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否 - [x] 是否需要 BullMQ：否 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：本模块深化 - [x] 是否需要 Content Safety：是（已有依赖，不变） - [x] 是否需要 Cost 记录：是（AIUsageLog 闭环） - [x] 是否需要 AuditLog：是（路由规则变更、Provider 禁用） - [x] 是否需要 Domain Event：是（新增降级事件） - [x] 是否需要 Admin 视图：是（路由管理页新增） - [x] 是否需要 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

wangdl commented

2026-05-24 10:03:05 +08:00

✅ M1-01 实施完成

交付内容

模块	文件	说明
DB 驱动路由配置	`prisma/schema.prisma` (ModelRoute/ProviderConfig/FallbackEvent)	3 张新表，migration `20260524000000_add_model_route`
ModelRouter 重写	`src/modules/ai/model-router.ts`	从硬编码改为数据库驱动，含默认回退和 `loadFromDb()` 热加载
降级事件记录	`src/modules/ai/gateway/ai-gateway.service.ts`	preferred→fallback 切换时记录 FallbackEvent 并发布 ModelFallbackTriggered
成本事件闭环	`src/modules/ai/gateway/ai-gateway.service.ts`	每次成功调用发布 AIUsageRecorded 供 Cost 模块消费
Admin 路由管理 AAPI	`src/modules/ai/ai.controller.ts`	路由规则 CRUD、Provider 启用/禁用、降级事件日志查询

E2E 测试

8 个测试全部通过（test/m1.e2e-spec.ts M1-01 章节）：

端点	测试
`GET /admin-api/ai-gateway/status`	返回 routes/providers 信息
`GET /admin-api/ai-gateway/routes`	路由规则列表 + 401 校验
`POST /admin-api/ai-gateway/routes`	创建路由 + 缓存重载
`PUT /admin-api/ai-gateway/routes/:id`	更新路由
`GET /admin-api/ai-gateway/providers`	Provider 列表
`PUT /admin-api/ai-gateway/providers/:name`	启用/禁用 Provider
`GET /admin-api/ai-gateway/fallback-events`	降级事件日志

运行

npx jest --config ./test/jest-e2e.json   # 36 passed (28 M0 + 8 M1)

## ✅ M1-01 实施完成 ### 交付内容 | 模块 | 文件 | 说明 | |------|------|------| | DB 驱动路由配置 | `prisma/schema.prisma` (ModelRoute/ProviderConfig/FallbackEvent) | 3 张新表，migration `20260524000000_add_model_route` | | ModelRouter 重写 | `src/modules/ai/model-router.ts` | 从硬编码改为数据库驱动，含默认回退和 `loadFromDb()` 热加载 | | 降级事件记录 | `src/modules/ai/gateway/ai-gateway.service.ts` | preferred→fallback 切换时记录 FallbackEvent 并发布 ModelFallbackTriggered | | 成本事件闭环 | `src/modules/ai/gateway/ai-gateway.service.ts` | 每次成功调用发布 AIUsageRecorded 供 Cost 模块消费 | | Admin 路由管理 AAPI | `src/modules/ai/ai.controller.ts` | 路由规则 CRUD、Provider 启用/禁用、降级事件日志查询 | ### E2E 测试 8 个测试全部通过（`test/m1.e2e-spec.ts` M1-01 章节）： | 端点 | 测试 | |------|------| | `GET /admin-api/ai-gateway/status` | 返回 routes/providers 信息 | | `GET /admin-api/ai-gateway/routes` | 路由规则列表 + 401 校验 | | `POST /admin-api/ai-gateway/routes` | 创建路由 + 缓存重载 | | `PUT /admin-api/ai-gateway/routes/:id` | 更新路由 | | `GET /admin-api/ai-gateway/providers` | Provider 列表 | | `PUT /admin-api/ai-gateway/providers/:name` | 启用/禁用 Provider | | `GET /admin-api/ai-gateway/fallback-events` | 降级事件日志 | ### 运行 ```bash npx jest --config ./test/jest-e2e.json # 36 passed (28 M0 + 8 M1) ```

~~wangdl referenced this issue 2026-06-05 19:34:43 +08:00~~

H0-09 知识库订阅（KnowledgeBaseSubscription） #54

~~wangdl referenced this issue 2026-06-05 19:36:08 +08:00~~

H0-09 知识库订阅（KnowledgeBaseSubscription） #54

wangdl closed this issue

2026-06-06 18:50:36 +08:00

wangdl commented

2026-06-06 18:50:36 +08:00