2ba4250165
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
# ai AI 网关服务
|
||
|
||
> 版本：0.1（骨架）
|
||
> 日期：2026-07-07
|
||
> 状态：P5 待交付
|
||
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)
|
||
|
||
---
|
||
|
||
## 1. 模块职责
|
||
|
||
ai 是 AI 网关限界上下文（Python 实现），管理 LLMCall、Prompt、Generation 聚合。
|
||
统一封装 LLM 调用（多模型路由、重试、限流、成本控制），提供辅助出题、表达优化、分层提问等能力。
|
||
通过 gRPC 查询 content 题库与 data-ana 学情数据，结合知识图谱生成个性化内容。
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
| 类别 | 技术 | 版本 | 用途 |
|
||
|------|------|------|------|
|
||
| 语言 | Python | 3.12+ | AI 生态 |
|
||
| 框架 | FastAPI | 0.110+ | 异步 API |
|
||
| LLM SDK | openai / anthropic | - | 多模型调用 |
|
||
| 编排 | LangGraph | - | LLM 工作流编排 |
|
||
| 检索 | Elasticsearch | 8.x | 题库检索（RAG） |
|
||
| 缓存 | Redis | 7.x | Prompt 缓存、结果缓存 |
|
||
| 校验 | pydantic | 2.x | 运行时校验 |
|
||
| 追踪 | OpenTelemetry | - | LLM 调用链追踪 |
|
||
|
||
---
|
||
|
||
## 3. 架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
BFF[BFF 聚合层] -->|gRPC| AI[ai 服务]
|
||
AI --> ROUTER[ModelRouter<br/>多模型路由]
|
||
AI --> ORCH[LangGraph 编排]
|
||
AI --> RAG[RAG 检索增强]
|
||
RAG -->|gRPC| CONTENT[content 题库]
|
||
RAG -->|gRPC| ANA[data-ana 学情]
|
||
AI -->[(ES<br/>题库检索)]
|
||
AI -->[(Redis<br/>结果缓存)]
|
||
AI --> LLM[LLM API<br/>OpenAI/Claude]
|
||
```
|
||
|
||
> 待 P5 交付时补充完整的分层架构图与 LLM 编排图。
|
||
|
||
---
|
||
|
||
## 4. 核心流程图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant T as 教师
|
||
participant BFF as BFF
|
||
participant AI as ai 服务
|
||
participant CONTENT as content
|
||
participant ANA as data-ana
|
||
participant LLM as LLM API
|
||
|
||
T->>BFF: AI 辅助出题
|
||
BFF->>AI: gRPC GenerateQuestions(topic, difficulty)
|
||
AI->>CONTENT: gRPC 查询相关题目 + 知识点
|
||
AI->>ANA: gRPC 查询学情掌握度
|
||
AI->>AI: LangGraph 编排 Prompt
|
||
AI->>LLM: 调用 LLM 生成
|
||
LLM-->>AI: 生成结果
|
||
AI->>AI: 质量校验 + 缓存
|
||
AI-->>BFF: 生成的题目列表
|
||
```
|
||
|
||
> 待 P5 交付时补充：表达优化流程、分层提问流程、差异化建议流程。
|
||
|
||
---
|
||
|
||
## 5. 对外契约
|
||
|
||
- **gRPC 服务**：AIService（GenerateQuestions、OptimizeExpression、SuggestDifferentiation、GenerateLayeredQuestions）（待 P5 定义 protobuf）
|
||
- **消费事件**：无（按需 gRPC 调用）
|
||
- **发布事件**：`edu.ai.generation.completed`（可选，用于审计）
|
||
- **缓存**：Redis 存储生成结果（相同 prompt 24 小时缓存）
|
||
|
||
> 待 P5 交付时补充完整 protobuf 定义与 Prompt 模板规范。
|
||
|
||
---
|
||
|
||
## 6. 依赖关系
|
||
|
||
- **上游**：teacher-bff（AI 辅助功能）
|
||
- **下游**：LLM API（OpenAI/Claude）、Elasticsearch、Redis、content（gRPC）、data-ana（gRPC）
|
||
- **跨服务**：gRPC 调用 content 题库与 data-ana 学情，不消费事件
|
||
|
||
---
|
||
|
||
## 7. 架构约束
|
||
|
||
1. LLM 调用必须经 ModelRouter，支持多模型故障切换
|
||
2. 生成内容必须经质量校验，禁止直接返回未校验结果
|
||
3. 调用成本必须记录，按用户/学校维度限额
|
||
4. Prompt 模板必须版本化管理，禁止硬编码
|
||
5. RAG 检索必须优先于 LLM 生成，减少幻觉
|
||
|
||
> 待 P5 交付时补充完整约束清单。
|
||
|
||
---
|
||
|
||
## 8. 架构决策
|
||
|
||
> 待 P5 交付时补充 ADR 记录，预计包括：Python+FastAPI 选型、LangGraph 编排选型、多模型路由策略、RAG 检索策略、成本控制策略。
|