Edu/docs/modules/ai/README.md

ai AI 网关服务

版本：0.1（骨架） 日期：2026-07-07 状态：P5 待交付 关联文档：架构影响地图

---

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. 架构图

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. 核心流程图

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 检索策略、成本控制策略。