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

M0-08 AI Gateway 基础版 #8

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 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 模板变更需审计 - 模型路由规则变更需审计 ## 交付检查 - [ ] 路由归属：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）框架
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
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
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?