WangDL
69dbb72777
- 更新AI架构设计文档链接 - 整理后端待完成事项清单（12 Repository迁Prisma、AI架构、JwtAuthGuard等） - 归档已完成：AI架构决策清单 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
214 lines
7.8 KiB
Markdown
214 lines
7.8 KiB
Markdown
# 知习 AI 架构 V1：决策与执行清单
|
||
|
||
> **2026-05-16 已确认并完成**：三层架构（Provider → Gateway → Workflow），阶段 0 全部完成。
|
||
> 设计方向文档：[AI架构设计.md](./[设计中]-AI架构设计.md)
|
||
>
|
||
> **状态：✅ 阶段 0 完成 | 阶段 1 基本完成 | 阶段 2 待推进**
|
||
|
||
---
|
||
|
||
# 一、架构原则
|
||
|
||
## 核心分层
|
||
|
||
```text
|
||
业务模块层（ActiveRecall / ai-analysis）
|
||
↓ 调用
|
||
AI Workflow 层（ActiveRecallAnalysisWorkflow）
|
||
↓ 调用
|
||
AI Gateway 层（AiGatewayService：选模型、记日志、解析 JSON、超时重试）
|
||
↓ 调用
|
||
AI Provider 层（DeepSeekProvider / MiniMaxProvider / MockAiProvider）
|
||
```
|
||
|
||
**每一层的职责边界**：
|
||
|
||
| 层 | 知道什么 | 不知道什么 |
|
||
|----|---------|-----------|
|
||
| Provider | messages, model, temperature, signal | 知识点、主动回忆、FocusItem |
|
||
| Gateway | feature, promptVersion, cost, retry | 业务 Workflow 细节 |
|
||
| Workflow | 知识点、回答、分析逻辑 | 模型 API 细节 |
|
||
| 业务模块 | 自己的 CRUD | AI 调用细节 |
|
||
|
||
---
|
||
|
||
# 二、已确认决策（全部实现）
|
||
|
||
| 编号 | 决策 | 结论 | 状态 |
|
||
|------|------|------|------|
|
||
| A | 架构分层 | Provider → Gateway → Workflow 三层 | ✅ |
|
||
| B | Mock 保留 | Mock 跑通闭环，永久保留 | ✅ |
|
||
| C | 第一个 Provider | DeepSeek（V4-Flash 便宜，V4-Pro 强推理） | ✅ |
|
||
| D | 第二个 Provider | MiniMax M2.7（Coding Plan 已付费，主力分析） | ✅ |
|
||
| E | Model Router | 三层：cheap / primary / strong，显式 fallback | ✅ |
|
||
| F | Gateway 超时 | AbortController 30s + 自动重试 + fallback | ✅ |
|
||
| G | Prompt 管理 | 代码文件 + promptKey / promptVersion 追踪 | ✅ |
|
||
| H | JSON 校验 | Zod Schema + 三层容错（parse → fence → extract） | ✅ |
|
||
| I | 成本控制 | AiUsageLog + AiCostCalculatorService | ✅ |
|
||
| J | 旧代码清理 | 删除 infrastructure/ai，ai-analysis 迁到新 gateway | ✅ |
|
||
|
||
---
|
||
|
||
# 三、当前文件结构
|
||
|
||
```
|
||
src/modules/ai/
|
||
├── ai.module.ts # NestJS DI：Map<string, AiProvider>
|
||
├── ai.controller.ts # POST /ai/analyze-recall · GET /ai/models
|
||
├── model-router.ts # cheap / primary / strong 三档路由
|
||
├── gateway/
|
||
│ ├── ai-gateway.types.ts # GatewayRequest / GatewayResponse / ModelTier
|
||
│ └── ai-gateway.service.ts # 统一入口：选模型、30s超时、重试、JSON三层容错、记日志
|
||
├── providers/
|
||
│ ├── ai-provider.interface.ts # AiGenerateInput(signal) / AiGenerateOutput
|
||
│ ├── mock-ai.provider.ts # 永久保留，返回 simulated 分析结果
|
||
│ ├── deepseek.provider.ts # DeepSeek API（OpenAI 兼容）
|
||
│ └── minimax.provider.ts # MiniMax M2.7（OpenAI 兼容）
|
||
├── prompts/
|
||
│ ├── prompt-template.service.ts # key + version 注册表
|
||
│ ├── active-recall-analysis.prompt.ts # System Prompt
|
||
│ └── schemas/
|
||
│ └── active-recall-analysis.schema.ts # Zod Schema + JSON 输出示例
|
||
├── usage/
|
||
│ ├── ai-cost-calculator.service.ts # 按模型计算费用
|
||
│ └── ai-usage-log.service.ts # 写 AiUsageLog
|
||
└── workflows/
|
||
└── active-recall-analysis.workflow.ts # 第一个 Workflow：主动回忆分析
|
||
```
|
||
|
||
## 关联模块
|
||
|
||
```
|
||
src/modules/ai-analysis/ # 导入 AiModule，用 ActiveRecallAnalysisWorkflow
|
||
├── ai-analysis.module.ts
|
||
├── ai-analysis.controller.ts # POST /ai-analysis · GET /ai-analysis/:id
|
||
├── ai-analysis.service.ts
|
||
└── ai-analysis.repository.ts
|
||
|
||
src/modules/active-recall/ # 导入 AiModule，提交答案异步触发分析
|
||
├── active-recall.module.ts
|
||
├── active-recall.controller.ts # POST /active-recalls/:id/submit
|
||
├── active-recall.service.ts
|
||
└── active-recall.repository.ts
|
||
|
||
src/infrastructure/ai/ # ❌ 已删除（旧 AiService + 旧 MockAiProvider）
|
||
```
|
||
|
||
---
|
||
|
||
# 四、数据流（主动回忆分析）
|
||
|
||
```text
|
||
1. POST /active-recalls/:id/submit
|
||
↓
|
||
2. ActiveRecallService.submit() 保存回答 + 异步 analysisWorkflow.execute()
|
||
↓
|
||
3. ActiveRecallAnalysisWorkflow.execute({ userId, questionText, knowledgeItemContent, userAnswer })
|
||
↓
|
||
4. PromptTemplateService.get('active-recall-analysis', '1.0.0')
|
||
↓
|
||
5. AiGatewayService.generate({ feature, userId, tier:'primary', promptKey, messages, outputSchema })
|
||
↓
|
||
6. ModelRouter.resolve('primary') → minimax-m2.7（fallback: deepseek-v4-pro）
|
||
↓
|
||
7. Provider.generate() + AbortController(30s) → fetch()
|
||
↓
|
||
8. JSON 三层容错：直接 parse → 提取 markdown fence → 提取 { } 对象
|
||
↓
|
||
9. Zod Schema 校验 → ActiveRecallAnalysisResult
|
||
↓
|
||
10. AiUsageLogService.log() 记 tokens / cost / latency
|
||
↓
|
||
11. GatewayResponse { parsed, usage }
|
||
↓
|
||
12. Workflow 返回 ActiveRecallAnalysisResult
|
||
```
|
||
|
||
---
|
||
|
||
# 五、数据库
|
||
|
||
## AiUsageLog（已加入 schema，待 db push）
|
||
|
||
```prisma
|
||
model AiUsageLog {
|
||
id String @id @default(cuid())
|
||
userId String
|
||
feature String @db.VarChar(64)
|
||
provider String @db.VarChar(32)
|
||
model String @db.VarChar(100)
|
||
tier String @db.VarChar(32)
|
||
promptKey String @db.VarChar(128)
|
||
promptVersion String @db.VarChar(32)
|
||
inputTokens Int @default(0)
|
||
outputTokens Int @default(0)
|
||
estimatedCost Float @default(0)
|
||
latencyMs Int @default(0)
|
||
success Boolean @default(true)
|
||
errorMessage String? @db.VarChar(500)
|
||
createdAt DateTime @default(now())
|
||
|
||
user User @relation(fields: [userId], references: [id])
|
||
|
||
@@index([userId])
|
||
@@index([feature])
|
||
@@index([createdAt])
|
||
}
|
||
```
|
||
|
||
> ⚠️ `prisma db push` 待 SSH 隧道连通后执行
|
||
|
||
---
|
||
|
||
# 六、可执行任务状态
|
||
|
||
## 阶段 0：AI 地基 ✅ 14/14
|
||
|
||
| # | 任务 | 状态 |
|
||
|---|------|------|
|
||
| 1 | AiUsageLog 表（prisma schema） | ✅ |
|
||
| 2 | 统一 AiProvider 接口（generate + signal） | ✅ |
|
||
| 3 | ModelRouter（cheap / primary / strong） | ✅ |
|
||
| 4 | AiGatewayService（统一入口 + JSON 容错 + 超时重试） | ✅ |
|
||
| 5 | PromptTemplateService（key + version） | ✅ |
|
||
| 6 | DeepSeekProvider | ✅ |
|
||
| 7 | MiniMaxProvider | ✅ |
|
||
| 8 | Zod Schema（ActiveRecallAnalysisResult） | ✅ |
|
||
| 9 | AiUsageLogService + AiCostCalculatorService | ✅ |
|
||
| 10 | ActiveRecallAnalysisWorkflow | ✅ |
|
||
| 11 | AiModule（DI 注入） | ✅ |
|
||
| 12 | AiController（analyze-recall / models） | ✅ |
|
||
| 13 | MockAiProvider（保留不动） | ✅ |
|
||
| 14 | 删除旧 infrastructure/ai | ✅ |
|
||
|
||
## 阶段 1：集成打通 ✅ 4/6
|
||
|
||
| # | 任务 | 状态 |
|
||
|---|------|------|
|
||
| 15 | ai-analysis 改用 ActiveRecallAnalysisWorkflow | ✅ |
|
||
| 16 | ai-analysis.module 导入 AiModule | ✅ |
|
||
| 17 | active-recall 提交答案触发分析 | ✅ |
|
||
| 18 | Gateway AbortController 30s 超时 | ✅ |
|
||
| 19 | prisma db push 建 AiUsageLog 表 | ⚠️ 等隧道 |
|
||
| 20 | 真实 AI 切换 + Prompt 调优 | ⏳ 后续 |
|
||
|
||
## 阶段 2：待推进
|
||
|
||
| # | 任务 |
|
||
|---|------|
|
||
| 21 | 11 个业务 Repository：in-memory Map → Prisma |
|
||
| 22 | 所有 Controller 加 JwtAuthGuard |
|
||
| 23 | 真实 AI 联调 + 样本测试 + Prompt 调优 |
|
||
| 24 | 更多 Workflow（知识导入、费曼分析、复习卡片、长期趋势） |
|
||
|
||
---
|
||
|
||
# 七、一句话总结
|
||
|
||
```text
|
||
DeepSeek 只是第一个模型，不是 AI 架构本身。
|
||
知习现在有了「可替换模型、可追踪成本、可校验输出、可沉淀学习结果」的三层 AI 工作流架构：
|
||
Provider → Gateway → Workflow。
|
||
阶段 0 全部完成，阶段 1 基本完成。
|
||
```
|