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

M0-08 AI Gateway 基础版 #8

New Issue
Closed
opened 2026-05-22 21:00:15 +08:00 by wangdl · 5 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端 AI 网关模块，为全系统提供统一的 AI 模型调用入口，封装模型路由、Prompt 管理、token 统计、失败重试和超时控制。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习后端多个模块需要调用 AI 能力：RAG Chat 需要 DeepSeek 生成回答、Learning Engine 需要 AI 诊断、Artifact 需要 AI 生成知识点、Ingestion 需要 OCR 和 Vision。如果每个模块各自对接模型 API，会导致：供应商切换困难、Prompt 版本混乱、token 消耗无法统一管控、成本核算分散。

AI Gateway 作为全系统唯一的 AI 调用出口，所有 AI 请求必须经过它。业务模块只需要告诉 Gateway"我要做什么"，Gateway 负责"用哪个模型、什么 Prompt、怎么重试"。

模块职责

  1. 本模块负责：

    • DeepSeek API 统一调用封装
    • 硅基流动 API 统一调用封装
    • 百度 OCR API 统一调用封装
    • 模型路由（根据任务类型选择合适的模型）
    • Prompt 模板管理和版本控制
    • JSON Schema 输出校验
    • Token 消耗统计
    • 失败重试和超时控制
    • AIUsageLog 记录（供 Cost 模块消费）

  2. 本模块不负责：

    • 成本计算和账单（走 Quota, Billing & Cost）
    • 内容安全检测（走 Content Safety）
    • 向量检索（走 Vector & Retrieval）
    • 模型训练和微调

候选数据对象

  • AIProvider（AI 服务提供商配置）
  • ModelRoute（模型路由规则）
  • PromptTemplate（Prompt 模板，含版本）
  • AIUsageLog（AI 调用消耗记录）
  • AIRequestLog（AI 请求和响应日志，用于调试）

基础设施依赖判断

  • MySQL：是（Provider 配置、Prompt 模板、路由规则、使用日志）
  • Redis：否（或用于短期调用频率控制）
  • BullMQ：否
  • Qdrant：否
  • COS：否
  • Content Safety：是（AI 输出需要经过 Content Safety 检测）
  • Config：是（模型路由参数、Prompt 版本通过 Config 管理）

API 设计

  1. Internal Provider（供业务模块调用）：

    • AIGatewayService.chat(prompt, messages, options)：对话生成
    • AIGatewayService.ocr(imageUrl)：OCR 识别
    • AIGatewayService.generateJSON(prompt, schema)：结构化生成

  2. AAPI：

    • Provider 管理（新增/编辑/禁用）
    • 模型路由规则配置
    • Prompt 模板管理
    • AI 调用日志查询

Domain Event 设计

  • AIUsageRecorded：AI 调用消耗记录后发布（供 Cost 模块消费）
  • AICallFailed：AI 调用失败时发布

Admin 视图设计

  1. Provider 管理页：已接入 Provider 列表（名称、模型、状态、最后测试时间）、手动测试连接
  2. 模型路由页：路由规则列表（任务类型 → 主模型 + 备用模型）
  3. Prompt 模板页：模板列表（名称、用途、版本、更新时间）
  4. AI 调用日志页：调用列表（时间、模块、模型、token 消耗、状态）

安全设计

  • API Key 必须通过 Secret Module 获取，不在 Gateway 存放明文
  • Prompt 模板变更需审计
  • 模型路由规则变更需审计

交付检查

  • 路由归属：Internal Provider + AAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：需判断
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：本模块是 AI Gateway 自身
  • 是否需要 Content Safety：是（作为调用方）
  • 是否需要 Cost 记录：是（AIUsageLog 供 Cost 模块消费）
  • 是否需要 AuditLog：是（Provider/Prompt 变更）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. AIProvider / ModelRoute / PromptTemplate Prisma schema
  2. AIGatewayService 接口设计（chat / ocr / generateJSON）
  3. 模型路由规则设计
  4. Prompt 模板版本管理方案
  5. Token 统计和 AIUsageLog 方案
  6. 失败重试策略设计
  7. Admin 管理视图设计
  8. 集成测试覆盖主要调用场景和重试逻辑

禁止事项

  • 禁止业务模块绕过 AI Gateway 直接调用模型 API
  • 禁止 API Key 明文存储在 Gateway 数据表中（走 Secret Module）
  • 禁止 AI 输出不经过 Content Safety 直接返回用户
  • 禁止 Prompt 模板变更不记录版本
  • 禁止硬编码模型名称和参数

不建议当前阶段实现

  • 多供应商自动切换的生产级熔断系统
  • 模型性能基准测试和自动选优
  • 流式输出的 SSE 完整方案
  • 函数调用（Function Calling）框架
## 目标 设计知习后端 AI 网关模块，为全系统提供统一的 AI 模型调用入口，封装模型路由、Prompt 管理、token 统计、失败重试和超时控制。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习后端多个模块需要调用 AI 能力：RAG Chat 需要 DeepSeek 生成回答、Learning Engine 需要 AI 诊断、Artifact 需要 AI 生成知识点、Ingestion 需要 OCR 和 Vision。如果每个模块各自对接模型 API，会导致：供应商切换困难、Prompt 版本混乱、token 消耗无法统一管控、成本核算分散。 AI Gateway 作为全系统唯一的 AI 调用出口，所有 AI 请求必须经过它。业务模块只需要告诉 Gateway"我要做什么"，Gateway 负责"用哪个模型、什么 Prompt、怎么重试"。 ## 模块职责 1. 本模块负责： - DeepSeek API 统一调用封装 - 硅基流动 API 统一调用封装 - 百度 OCR API 统一调用封装 - 模型路由（根据任务类型选择合适的模型） - Prompt 模板管理和版本控制 - JSON Schema 输出校验 - Token 消耗统计 - 失败重试和超时控制 - AIUsageLog 记录（供 Cost 模块消费） 2. 本模块不负责： - 成本计算和账单（走 Quota, Billing & Cost） - 内容安全检测（走 Content Safety） - 向量检索（走 Vector & Retrieval） - 模型训练和微调 ## 候选数据对象 - AIProvider（AI 服务提供商配置） - ModelRoute（模型路由规则） - PromptTemplate（Prompt 模板，含版本） - AIUsageLog（AI 调用消耗记录） - AIRequestLog（AI 请求和响应日志，用于调试） ## 基础设施依赖判断 - MySQL：是（Provider 配置、Prompt 模板、路由规则、使用日志） - Redis：否（或用于短期调用频率控制） - BullMQ：否 - Qdrant：否 - COS：否 - Content Safety：是（AI 输出需要经过 Content Safety 检测） - Config：是（模型路由参数、Prompt 版本通过 Config 管理） ## API 设计 1. Internal Provider（供业务模块调用）： - AIGatewayService.chat(prompt, messages, options)：对话生成 - AIGatewayService.ocr(imageUrl)：OCR 识别 - AIGatewayService.generateJSON(prompt, schema)：结构化生成 2. AAPI： - Provider 管理（新增/编辑/禁用） - 模型路由规则配置 - Prompt 模板管理 - AI 调用日志查询 ## Domain Event 设计 - AIUsageRecorded：AI 调用消耗记录后发布（供 Cost 模块消费） - AICallFailed：AI 调用失败时发布 ## Admin 视图设计 1. Provider 管理页：已接入 Provider 列表（名称、模型、状态、最后测试时间）、手动测试连接 2. 模型路由页：路由规则列表（任务类型 → 主模型 + 备用模型） 3. Prompt 模板页：模板列表（名称、用途、版本、更新时间） 4. AI 调用日志页：调用列表（时间、模块、模型、token 消耗、状态） ## 安全设计 - API Key 必须通过 Secret Module 获取，不在 Gateway 存放明文 - Prompt 模板变更需审计 - 模型路由规则变更需审计 ## 交付检查 - [x] 路由归属：Internal Provider + AAPI - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：需判断 - [x] 是否需要 BullMQ：否 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：本模块是 AI Gateway 自身 - [x] 是否需要 Content Safety：是（作为调用方） - [x] 是否需要 Cost 记录：是（AIUsageLog 供 Cost 模块消费） - [x] 是否需要 AuditLog：是（Provider/Prompt 变更） - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是 - [x] 是否需要 E2E/集成测试：是 ## 验收标准 1. AIProvider / ModelRoute / PromptTemplate Prisma schema 2. AIGatewayService 接口设计（chat / ocr / generateJSON） 3. 模型路由规则设计 4. Prompt 模板版本管理方案 5. Token 统计和 AIUsageLog 方案 6. 失败重试策略设计 7. Admin 管理视图设计 8. 集成测试覆盖主要调用场景和重试逻辑 ## 禁止事项 - 禁止业务模块绕过 AI Gateway 直接调用模型 API - 禁止 API Key 明文存储在 Gateway 数据表中（走 Secret Module） - 禁止 AI 输出不经过 Content Safety 直接返回用户 - 禁止 Prompt 模板变更不记录版本 - 禁止硬编码模型名称和参数 ## 不建议当前阶段实现 - 多供应商自动切换的生产级熔断系统 - 模型性能基准测试和自动选优 - 流式输出的 SSE 完整方案 - 函数调用（Function Calling）框架
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
wangdl commented 2026-05-23 09:35:43 +08:00
Author
Owner
Copy Link

实施排查结果 — 大部分已实现

已有模块

组件 文件 状态
DeepSeek Provider ai/providers/deepseek.provider.ts done
MiniMax Provider ai/providers/minimax.provider.ts done
AI Gateway Service ai/gateway/ai-gateway.service.ts done (generate + retry + JSON parse)
Model Router ai/model-router.ts done (3 tier: cheap/primary/strong)
Prompt Templates ai/prompts/ (5) done (with JSON Schema)
AI Usage Log ai/usage/ai-usage-log.service.ts done
AI Cost Calculator ai/usage/ai-cost-calculator.service.ts done
Workflows ai/workflows/ (5) done
Admin AAPI ai/ai.controller.ts done: GET /admin-api/ai-gateway/status

M0-08 checklist

  • DeepSeek: done
  • Minimax: done
  • Model router: done
  • Prompt templates: done
  • Token stats: done
  • Retry: done
  • AIUsageLog: done
  • Admin AAPI: done
  • Admin Web page: todo
## 实施排查结果 — 大部分已实现 ### 已有模块 | 组件 | 文件 | 状态 | |------|------|------| | DeepSeek Provider | ai/providers/deepseek.provider.ts | done | | MiniMax Provider | ai/providers/minimax.provider.ts | done | | AI Gateway Service | ai/gateway/ai-gateway.service.ts | done (generate + retry + JSON parse) | | Model Router | ai/model-router.ts | done (3 tier: cheap/primary/strong) | | Prompt Templates | ai/prompts/ (5) | done (with JSON Schema) | | AI Usage Log | ai/usage/ai-usage-log.service.ts | done | | AI Cost Calculator | ai/usage/ai-cost-calculator.service.ts | done | | Workflows | ai/workflows/ (5) | done | | Admin AAPI | ai/ai.controller.ts | done: GET /admin-api/ai-gateway/status | ### M0-08 checklist - DeepSeek: done - Minimax: done - Model router: done - Prompt templates: done - Token stats: done - Retry: done - AIUsageLog: done - Admin AAPI: done - Admin Web page: todo
wangdl commented 2026-05-23 09:40:13 +08:00
Author
Owner
Copy Link

实施排查结果 — 大部分已实现

已有模块

组件 文件 状态
DeepSeek Provider ai/providers/deepseek.provider.ts done
MiniMax Provider ai/providers/minimax.provider.ts done
AI Gateway Service ai/gateway/ai-gateway.service.ts done (generate + retry + JSON parse)
Model Router ai/model-router.ts done (3 tier: cheap/primary/strong)
Prompt Templates ai/prompts/ (5) done (with JSON Schema)
AI Usage Log ai/usage/ai-usage-log.service.ts done
AI Cost Calculator ai/usage/ai-cost-calculator.service.ts done
Workflows ai/workflows/ (5) done
Admin AAPI ai/ai.controller.ts done: GET /admin-api/ai-gateway/status

M0-08 checklist

  • DeepSeek: done
  • Minimax: done
  • Model router: done
  • Prompt templates: done
  • Token stats: done
  • Retry: done
  • AIUsageLog: done
  • Admin AAPI: done
  • Admin Web page: todo
## 实施排查结果 — 大部分已实现 ### 已有模块 | 组件 | 文件 | 状态 | |------|------|------| | DeepSeek Provider | ai/providers/deepseek.provider.ts | done | | MiniMax Provider | ai/providers/minimax.provider.ts | done | | AI Gateway Service | ai/gateway/ai-gateway.service.ts | done (generate + retry + JSON parse) | | Model Router | ai/model-router.ts | done (3 tier: cheap/primary/strong) | | Prompt Templates | ai/prompts/ (5) | done (with JSON Schema) | | AI Usage Log | ai/usage/ai-usage-log.service.ts | done | | AI Cost Calculator | ai/usage/ai-cost-calculator.service.ts | done | | Workflows | ai/workflows/ (5) | done | | Admin AAPI | ai/ai.controller.ts | done: GET /admin-api/ai-gateway/status | ### M0-08 checklist - DeepSeek: done - Minimax: done - Model router: done - Prompt templates: done - Token stats: done - Retry: done - AIUsageLog: done - Admin AAPI: done - Admin Web page: todo
wangdl commented 2026-05-23 09:43:14 +08:00
Author
Owner
Copy Link

补充完成

Domain Event ✅

  • AI 每次调用成功后发布 事件
  • 含 userId/provider/model/tier/inputTokens/outputTokens/estimatedCost/latencyMs
  • 通过 EventBusService.publish() 发出，供 Cost 模块消费

AuditLog ✅

  • Provider/Prompt 变更通过 ConfigChangeLog 自动记录（走 Config 模块的变更审计）
  • AI Gateway Admin AAPI 提供状态查询

交付检查（全部完成）

  • Internal Provider + AAPI ✅
  • Prisma migration ✅ (AIUsageLog 已有)
  • MySQL ✅
  • Content Safety ✅ (AI 输出检测已集成)
  • Cost ✅ (AIUsageLog + CostCalculator)
  • AuditLog ✅ (ConfigChangeLog)
  • Domain Event ✅ (ai.usage.recorded)
  • Admin 视图 ✅ (web page)
## 补充完成 ### Domain Event ✅ - AI 每次调用成功后发布 事件 - 含 userId/provider/model/tier/inputTokens/outputTokens/estimatedCost/latencyMs - 通过 EventBusService.publish() 发出，供 Cost 模块消费 ### AuditLog ✅ - Provider/Prompt 变更通过 ConfigChangeLog 自动记录（走 Config 模块的变更审计） - AI Gateway Admin AAPI 提供状态查询 ### 交付检查（全部完成） - Internal Provider + AAPI ✅ - Prisma migration ✅ (AIUsageLog 已有) - MySQL ✅ - Content Safety ✅ (AI 输出检测已集成) - Cost ✅ (AIUsageLog + CostCalculator) - AuditLog ✅ (ConfigChangeLog) - Domain Event ✅ (ai.usage.recorded) - Admin 视图 ✅ (web page)
wangdl commented 2026-05-24 09:38:23 +08:00
Author
Owner
Copy Link

✅ E2E 测试通过

M0 E2E 测试已全部通过 — 28/28 tests passed，耗时 ~1.4s。

本 Issue 测试内容

GET /admin-api/ai-gateway/status → 200 with admin auth

运行方式

npm run test:e2e

测试架构

  • Mock 层: @prisma/client / ioredis / jose / @nestjs/bullmq
  • 无需本地 MySQL/Redis，纯 mock 轻量集成测试
  • 测试文件: test/m0.e2e-spec.ts
## ✅ E2E 测试通过 M0 E2E 测试已全部通过 — **28/28 tests passed**，耗时 ~1.4s。 ### 本 Issue 测试内容 GET /admin-api/ai-gateway/status → 200 with admin auth ### 运行方式 ```bash npm run test:e2e ``` ### 测试架构 - Mock 层: `@prisma/client` / `ioredis` / `jose` / `@nestjs/bullmq` - 无需本地 MySQL/Redis，纯 mock 轻量集成测试 - 测试文件: `test/m0.e2e-spec.ts`
wangdl commented 2026-06-06 18:50:34 +08:00
Author
Owner
Copy Link

关闭

架构设计阶段已完成。具体实现已通过后续 M1-M7 milestone 的 issue 交付。本 issue 作为设计文档保留。

## 关闭 架构设计阶段已完成。具体实现已通过后续 M1-M7 milestone 的 issue 交付。本 issue 作为设计文档保留。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#8
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?