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