faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
385 lines
36 KiB
Markdown
385 lines
36 KiB
Markdown
# 模块理解确认书 — ai
|
||
|
||
> AI 标识：ai12（复核与长期演进接手）← ai06（初稿，2026-07-09）
|
||
> 负责模块：ai（P5）— 按 [ai-allocation.md §3.2](../../../docs/architecture/ai-allocation.md) v1.0 最新分配，ai 由 ai12 专责
|
||
> 语言：Python 3.12+ / FastAPI 0.115+
|
||
> 阶段：架构设计外包 · 阶段 1（全局理解，ai06 初稿 + ai12 长期演进复核）
|
||
> 日期：2026-07-09（ai06 初稿）/ 2026-07-09（ai12 复核与补充）
|
||
> 关联文档：[ai-allocation.md](../../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features.md](../../../docs/architecture/roadmap/pending-features.md)、[coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md)、[known-issues.md](../../../docs/troubleshooting/known-issues.md)
|
||
>
|
||
> **ai12 接手说明**：本确认书初稿由 ai06 在 ai-allocation v0.x 阶段（ai06 同时负责 data-ana + ai）撰写。ai-allocation.md v1.0 将 ai 模块独立分配给 ai12。ai12 在 ai06 初稿基础上执行：作者归属更正、长期架构演进补充、P5 交付物覆盖度核对、向前兼容性铺垫。**所有 ai12 新增内容用「ai12 增补」标注**，ai06 原文保留并标注「ai06 初稿」。
|
||
|
||
---
|
||
|
||
## 阶段 1 必读清单完成确认
|
||
|
||
按 ai-allocation.md §4，ai12 必读 7 份全局文档 + 全部 `.proto` + `services/data-ana/`、`services/ai/` 骨架源码：
|
||
|
||
| # | 文档 | 状态 |
|
||
| --- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|
||
| 1 | [README.md](../../../README.md) | ✅ 已读 |
|
||
| 2 | [MIGRATION_GUIDE.md](../../../MIGRATION_GUIDE.md) | ✅ 已读 |
|
||
| 3 | [004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) | ✅ 已读（重点 §1.2/§4.1/§4.2/§7.2/§9.3/§11.5/§12.2/§15） |
|
||
| 4 | [pending-features.md](../../../docs/architecture/roadmap/pending-features.md) | ✅ 已读（重点 P5 沟通与 AI 阶段） |
|
||
| 5 | [project_rules.md](../../../.trae/rules/project_rules.md) | ✅ 已读（workspace 规则，重点 §3.6 Python/§6 事件驱动/§9 问题记录/§10 AI 工作流程） |
|
||
| 6 | [coding-standards.md](../../../docs/standards/coding-standards.md) | ✅ 已读（重点 §4 Python 规范） |
|
||
| 7 | [multi-ai-collaboration.md](../../../docs/standards/multi-ai-collaboration.md) | ✅ 已读 |
|
||
| 8 | `packages/shared-proto/proto/*.proto`（8 份） | ✅ 已读（重点 ai.proto/analytics.proto/content.proto/events.proto） |
|
||
| 9 | `services/ai/src/` 全部源码（main.py/config.py/llm_client.py/health/health.py） | ✅ 已读 |
|
||
| 10 | `services/data-ana/src/` 全部源码（参考 Python 服务实现模式 + 跨服务 gRPC 契约对齐） | ✅ 已读（ai12 增补：跨服务 gRPC 契约对齐用） |
|
||
| 11 | [coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md) | ✅ 已读（ai12 增补：理解 7 项已仲裁共性问题） |
|
||
|
||
> ai12 与 ai06 不同：ai-allocation.md v1.0 §4 矩阵 ai06 列对黄金模板为 "—"，ai12 列同为 "—"（Python 服务无需对照 TS 黄金模板），但需对照 `services/data-ana/` 作为 Python 服务实现参考（lifespan/structlog/OTel/metrics 模式）。
|
||
|
||
---
|
||
|
||
## 1. 我在架构中的位置
|
||
|
||
### 1.1 架构定位（ai06 初稿 + ai12 增补）
|
||
|
||
- **层级**：业务微服务层（L5），属 **D6 智能洞察领域**（004 §1.1b，与 data-ana 共享领域）
|
||
- **领域细分**（ai12 增补）：D6 内部分两个子域
|
||
- **D6.a 分析子域**（data-ana 负责）：基于历史数据计算学情、掌握度、趋势
|
||
- **D6.b 生成子域**（ai 负责）：基于学情上下文 + LLM 推理生成教学内容
|
||
- 两子域通过 gRPC 同步查询耦合，构成"分析→生成"闭环
|
||
- **上游**：
|
||
- api-gateway 直接 HTTP 代理 `/api/v1/ai/*` → ai:3008（见 [api-gateway main.go](../../api-gateway/main.go)）
|
||
- teacher-bff 聚合 AI 出题/优化能力（004 §4.1：BFF → ai，P5 起转 gRPC）
|
||
- **ai12 增补**：student-bff（P3+）/ parent-bff（P4+）未来可能调用 AI 服务用于学生自适应学习、家长学情报告 AI 解读
|
||
- **下游**：
|
||
- content 服务（gRPC 查询知识点 / 题库，004 §4.1：AI → Content gRPC）
|
||
- data-ana 服务（gRPC 查询学情数据，004 §4.1：AI → DataAna gRPC）
|
||
- LLM Provider（外部 HTTP，OpenAI 兼容 REST API）
|
||
- **ai12 增补**：iam 服务（gRPC 查询 `GetEffectiveDataScope`，用于多租户/多学校用量配额校验；当前 iam.proto 未提供此 RPC，coord 已仲裁 P4 补全）
|
||
- **ai12 增补**：msg 服务（Kafka 事件 `edu.notification.events` 由 msg 消费，ai 不直接调用；但 AI 异常告警可能走 msg 推送给管理员，长期可考虑）
|
||
- **通信方式**：
|
||
- 入口：当前 REST（`/ai/chat`、`/ai/chat/stream`、`/ai/generate/question`、`/ai/optimize/expression`）；目标态（ai.proto）转 **gRPC** 暴露 `AiService`（含 `StreamChat` 流式 RPC），004 §4.2 明确 P5 启用
|
||
- 出口：gRPC 调 content / data-ana（**当前未实现，仅 LLM HTTP 调用**）；SSE 流式对前端；Kafka 事件外发用量计费
|
||
- **端口**：3008（HTTP）+ 50058（gRPC，**ai12 增补**：004 §1.2 gRPC 端口规则 `HTTP+10050`，需在 §1.2 端口矩阵补登，提请 coord 同步）
|
||
|
||
### 1.2 服务边界与无状态原则（ai12 增补）
|
||
|
||
ai 是**严格无状态服务**，这与 data-ana 的"无 MySQL 写但有 ClickHouse 读模型"形成鲜明对比。无状态原则的含义与边界：
|
||
|
||
| 维度 | ai（无状态） | data-ana（有读模型） |
|
||
| ---------- | ----------------------------------------------------- | ----------------------------------------- |
|
||
| 持久化存储 | 无独占 DB | ClickHouse 宽表（读模型） |
|
||
| 会话状态 | 单次请求内（无跨请求会话，聊天历史由前端维护） | 无 |
|
||
| 缓存 | Redis（Prompt 模板、限流计数、响应缓存） | Redis（DataScope 缓存） |
|
||
| 事件发布 | `AIUsageRecorded`（派生数据，豁免 Outbox，004 §12.2） | `MasteryUpdated`（派生数据，豁免 Outbox） |
|
||
| 水平扩展 | 直接加副本，无状态同步问题 | CDC 消费者需 consumer group 协调 |
|
||
|
||
**无状态原则的例外**（需 coord 长期跟踪）：
|
||
|
||
- 长运行工作流（备课工作流的"教师审核"步骤可能跨越数小时甚至数天）的状态需持久化，不能依赖内存。ai12 提请 coord 在 P6 评估引入 Temporal 或自建 workflow_state 表（详见 02-architecture-design.md §2.4）
|
||
|
||
## 2. 我的限界上下文
|
||
|
||
### 2.1 聚合职责（ai06 初稿 + ai12 增补）
|
||
|
||
- **聚合职责**：LLM 调用网关 + 教学场景 AI 编排（备课 / 出题 / 表达优化），承载 **D6 智能洞察领域**的"生成"子域
|
||
- **聚合根 / 实体**：
|
||
- `ChatConversation`（聊天会话，**待实现**，当前无状态）
|
||
- `GeneratedQuestion`（生成的题目，待审核入库）
|
||
- `PromptTemplate`（Prompt 模板，**待实现**）
|
||
- `UsageRecord`（用量计费记录，**待实现**，通过事件外发不落本服务 DB）
|
||
- **ai12 增补**：`LessonPreparationWorkflow`（备课工作流实例，长运行状态需持久化）
|
||
- **ai12 增补**：`EvaluationResult`（生成结果质量评估结果，待实现，用于 RLHF 数据收集与质量门禁）
|
||
- **业务领域**：D6 智能洞察（与 data-ana 共享，data-ana 偏"分析"，ai 偏"生成"）
|
||
- **我不负责**：
|
||
- 不负责题库存储（→ content 服务，ai 生成后调 content.CreateQuestions 入库）
|
||
- 不负责学情计算（→ data-ana 服务，ai 查询学情用于个性化出题）
|
||
- 不负责通知投递（→ msg 服务）
|
||
- 不负责用户身份认证（→ iam + Gateway，ai 信任 `x-user-id`/`x-user-roles` 头）
|
||
- **ai12 增补**：不负责教学大纲管理（→ content 服务的 Textbook/Chapter/KnowledgePoint）
|
||
- **ai12 增补**：不负责学生作业批改（→ core-edu，ai 仅生成题目与解析，不批改学生作答）
|
||
- **数据自治**：**无独占数据库**（设计上无状态；用量计费通过 Kafka 事件外发；长运行工作流状态待 P6 决策是否引入持久化）
|
||
|
||
### 2.2 ai12 增补：与 content / data-ana / msg 的边界精细化
|
||
|
||
为避免未来跨服务职责漂移，明确以下边界（参考 004 §1.1b D6/D4/D5 划分）：
|
||
|
||
| 业务能力 | 归属服务 | 边界说明 |
|
||
| -------------------- | ---------- | ----------------------------------------------------------------- |
|
||
| 题目生成（LLM 调用） | ai | ai 调 LLM 生成题目文本，返回给 BFF；不入 content 题库 |
|
||
| 题目入库 | content | BFF 拿 ai 生成的题目 → 调 content.CreateQuestions 入库 |
|
||
| 知识点前置依赖查询 | content | ai 调 content.KnowledgeGraphService.GetPrerequisites |
|
||
| 学生学情查询 | data-ana | ai 调 data-ana.AnalyticsService.GetStudentWeakness |
|
||
| 班级整体学情查询 | data-ana | ai 调 data-ana.AnalyticsService.GetClassPerformance |
|
||
| 生成结果质量评估 | ai | ai 内部 LLM-as-judge / 规则校验，不外发 |
|
||
| 用量计费落库 | data-ana | ai 发 `edu.insight.ai.usage` 事件，data-ana 消费落 ClickHouse |
|
||
| AI 异常告警通知 | msg | ai 异常 → 日志 + metrics，告警由 Prometheus Alertmanager 触发 msg |
|
||
| 教师审核备课结果 | BFF + 前端 | ai 仅生成与暂存（Redis 短期），审核状态由 BFF 编排 |
|
||
|
||
## 3. 我与外部的契约
|
||
|
||
### 3.1 消费的 proto message（ai06 初稿 + ai12 增补）
|
||
|
||
| 来源 | message / service | 用途 | 状态 |
|
||
| --------------- | ---------------------------------------------------------- | ----------------------------------------- | ------------------------- |
|
||
| content.proto | `KnowledgeGraphService.GetPrerequisites` | 查询知识点前置依赖用于出题上下文 | proto 已定义 |
|
||
| content.proto | `KnowledgeGraphService.GetLearningPath` | 查询学生学习路径用于个性化出题 | proto 已定义 |
|
||
| content.proto | `TextbookService.ListTextbooks` | 查询教材上下文（章节关联知识点） | proto 已定义（ai12 增补） |
|
||
| analytics.proto | `AnalyticsService.GetStudentWeakness` | 查询学生薄弱知识点用于靶向出题 | proto 已定义 |
|
||
| analytics.proto | `AnalyticsService.GetLearningTrend` | 查询学习趋势用于难度调节 | proto 已定义 |
|
||
| analytics.proto | `AnalyticsService.GetClassPerformance` | 查询班级整体学情用于备课工作流 | proto 已定义（ai12 增补） |
|
||
| iam.proto | `IamService.GetEffectiveDataScope`（**待 coord P4 补全**） | 查询用户 DataScope 用于多学校用量配额校验 | proto 待补全（ai12 增补） |
|
||
| ai.proto | `ChatRequest` 等 | gRPC 暴露契约（**待实现 gRPC server**） | proto 已定义 |
|
||
|
||
### 3.2 暴露的 API / 事件
|
||
|
||
**HTTP 端点**（当前实现，见 [main.py](../src/ai/main.py)）：
|
||
|
||
| method | path | 说明 |
|
||
| ------ | ------------------------- | ---------------------------- |
|
||
| GET | `/healthz` | liveness |
|
||
| GET | `/readyz` | readiness（含 LLM 是否配置） |
|
||
| GET | `/metrics` | Prometheus 指标 |
|
||
| POST | `/ai/chat` | LLM 聊天（非流式） |
|
||
| POST | `/ai/chat/stream` | LLM 流式聊天（SSE） |
|
||
| POST | `/ai/generate/question` | 生成题目 |
|
||
| POST | `/ai/optimize/expression` | 优化表达 |
|
||
|
||
**ai12 增补：待新增 HTTP 端点**（P5 交付）：
|
||
|
||
| method | path | 说明 |
|
||
| ------ | ------------------------------------- | ---------------------------------------------- |
|
||
| POST | `/ai/lesson/preparation` | 备课工作流启动（分析学情→推荐知识点→生成题目） |
|
||
| GET | `/ai/lesson/preparation/{id}` | 查询备课工作流状态（异步流程） |
|
||
| POST | `/ai/lesson/preparation/{id}/confirm` | 教师确认入库（触发 content.CreateQuestions） |
|
||
| GET | `/ai/prompts` | Prompt 模板列表（CRUD） |
|
||
| POST | `/ai/prompts` | 创建 Prompt 模板 |
|
||
| PUT | `/ai/prompts/{id}` | 更新 Prompt 模板（版本化） |
|
||
| GET | `/ai/usage/me` | 当前用户用量统计（短期查询，长期查 data-ana） |
|
||
|
||
**gRPC 契约**（ai.proto，**待实现 server**）：
|
||
|
||
- `Chat(ChatRequest) → ChatResponse`
|
||
- `StreamChat(ChatRequest) → stream ChatChunk`（流式 RPC）
|
||
- `GenerateQuestion(GenerateQuestionRequest) → GeneratedQuestion`
|
||
- `OptimizeExpression(OptimizeExpressionRequest) → OptimizedExpression`
|
||
|
||
**ai12 增补：proto 待补全项**（提请 coord 在 P5 前补全）：
|
||
|
||
- `GenerateLessonPlan(GenerateLessonPlanRequest) → LessonPlanResponse`：备课工作流 RPC
|
||
- `StreamGenerateQuestion(...) → stream GeneratedQuestionChunk`：题目逐字流式生成（满足 ai-allocation.md §5 "题目逐字生成"）
|
||
- `ChatRequest` 增加可选字段：`user_id`（透传，用于个性化）、`session_id`（用于多轮对话上下文）、`data_scope`（透传 DataScope 元数据）
|
||
- `GenerateQuestionRequest` 增加字段：`grade`、`knowledge_point_ids`、`question_type`、`count`
|
||
|
||
**ai12 增补：发布的领域事件**
|
||
|
||
- 当前无发布（ai06 初稿）
|
||
- 设计上发布 `AIUsageRecorded` 事件（用量计费），由 data-ana 消费落 ClickHouse。**004 §7.2 已确认 topic `edu.insight.ai.usage`**（coord 仲裁已通过，§15.3 #4）
|
||
- **ai12 增补：长期可发布事件**（P6+ 评估）：
|
||
- `AIContentGenerated`（topic: `edu.insight.ai.generated`）：生成内容审计事件，供 data-ana 落库用于质量分析
|
||
- `AIFeedbackRecorded`（topic: `edu.insight.ai.feedback`）：教师对生成结果的反馈（采纳/拒绝/修改），用于 RLHF 数据集构建
|
||
|
||
- **错误码前缀**：`AI_*`（详见阶段 2 §6.2）
|
||
- **降级策略**：LLM API key 为空或调用失败时返回 `degraded: true` 骨架响应（见 [llm_client.py](../src/ai/llm_client.py)）
|
||
|
||
### 3.3 ai12 增补：响应信封对齐
|
||
|
||
按 004 §11.5 强制约束（coord 仲裁：Python 服务信封必须改为 ActionState，禁止 `{success, data, degraded}` 偏离结构）：
|
||
|
||
- 当前 ai 实现违反约束（main.py 返回 `{success: true, data: ..., degraded: false}`）
|
||
- P5 实施必须改为 ActionState：
|
||
- 成功：`{success: true, data: T}`
|
||
- 失败：`{success: false, error: {code, message, details?, traceId?}}`
|
||
- 降级：`details: {degraded: true}`（degraded 作为 details 子字段，非顶层字段）
|
||
- 提请 coord 在 known-issues.md §2.9 ai-gateway 分区记录此约束
|
||
|
||
## 4. 我的技术栈
|
||
|
||
### 4.1 当前技术栈（ai06 初稿）
|
||
|
||
- 语言：Python 3.12+
|
||
- 框架：FastAPI 0.115+ / uvicorn
|
||
- LLM 客户端：`httpx` 异步直接调 OpenAI 兼容 REST API（**不依赖 openai SDK**，见 [llm_client.py:1-7](../src/ai/llm_client.py)）
|
||
- 配置：`pydantic-settings` BaseSettings（env_prefix=""）
|
||
- 可观测：
|
||
- 日志：`structlog`
|
||
- 指标：`prometheus-client` + `make_asgi_app()`
|
||
- 链路：`opentelemetry-sdk` + `OTLPSpanExporter` + `FastAPIInstrumentor`（dev_mode=true 时跳过 exporter 初始化避免本地无 collector 报错）
|
||
- 流式响应：FastAPI `StreamingResponse` + `AsyncGenerator`，SSE 格式 `data: <chunk>\n\n`
|
||
- 测试：pytest（**当前 0% 覆盖率**）
|
||
|
||
### 4.2 ai12 增补：长期技术栈演进路线
|
||
|
||
为支撑 P5 交付物 + 未来多模态/RAG/Agent 演进，规划如下技术栈演进：
|
||
|
||
| 类别 | 当前 | P5（M14-M16） | P6+（长期演进） | 选型理由 |
|
||
| ---------- | ---------- | --------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
|
||
| LLM 客户端 | httpx 直连 | LLMProvider 抽象 + 4 适配器 | + Embedding Provider + Multimodal Provider | 抽象隔离 Provider API 差异，便于切换 |
|
||
| 工作流编排 | 无 | FastAPI BackgroundTasks | Temporal（如 coord 仲裁引入） | 简单 4 步用 BackgroundTasks；长运行（教师审核）需 Temporal |
|
||
| RAG 检索 | 无 | gRPC 调 content 查询 | + 向量库（pgvector / Chroma）+ Embedding | P5 复用 content；P6+ 评估独立向量库支持语义检索 |
|
||
| 模板管理 | 硬编码 | YAML 文件 + Jinja2 | + DB 持久化 + 版本化 + A/B 测试 | P5 用文件简单；P6+ 评估迁移 DB 支持动态更新 |
|
||
| 缓存 | 无 | Redis（hash + 令牌桶） | + 语义缓存（embedding 相似度） | P5 用 hash 缓存；P6+ 评估语义缓存减少重复 LLM 调用 |
|
||
| 限流 | 无 | Redis 令牌桶（用户/IP） | + 学校级配额 + token 级预算 | P5 用户/IP 级；P6+ 多租户配额管理 |
|
||
| 评估 | 无 | 规则校验 + LLM-as-judge | + 人工评估 + 在线指标 + RLHF 数据集 | P5 自动化校验；P6+ 闭环反馈持续提升质量 |
|
||
| 测试 | 0% | pytest ≥ 80% | + 集成测试 + 契约测试 + LLM 评估测试 | P5 单元 + 集成；P6+ 评估测试保证生成质量 |
|
||
|
||
**关键选型决策记录**（ai12 增补，供 coord 备案）：
|
||
|
||
1. **不引入 openai SDK**：保持 httpx 直连，避免 SDK 版本绑定 + 减少 attack surface；OpenAI 兼容 REST API 已成为事实标准（百川/Ollama/vLLM 均兼容）
|
||
2. **P5 不引入 LangChain**：LangChain 抽象过重，与 LLMProvider 抽象层职责重叠；按 004 §2.3 列出的 LangGraph 待 P6+ 评估时再决定
|
||
3. **P5 不引入向量库**：RAG 检索复用 content 服务的 Neo4j + ES（content 已规划 ES），避免数据冗余
|
||
4. **不引入 openai SDK 但保留兼容性**：所有 LLM Provider 适配器实现 OpenAI 兼容 REST 接口，便于切换；非兼容 Provider（如 Anthropic 原生 API）在适配器内部转换
|
||
|
||
## 5. 我的阶段归属
|
||
|
||
### 5.1 阶段定位（ai06 初稿 + ai12 增补）
|
||
|
||
- **P5 沟通与 AI 阶段（M14-M16）**：建 AI 网关 + LLM Provider 适配 + 流式 SSE + 用量计费
|
||
- **退出标准**（pending-features P5）：
|
||
- AI 辅助出题流式返回
|
||
- 题库全文检索 < 200ms（**注**：ES 部分由 content 服务承担，ai 不直接负责）
|
||
- AI 网关流式 SSE 三层透传（AI → BFF → 前端）
|
||
- **ai12 增补细化**（基于 ai-allocation.md §5 ai12 交付清单）：
|
||
- LLM Provider 适配器模式（OpenAI/百川/本地模型，统一接口）✅
|
||
- SSE 流式响应（题目逐字生成 + 前端打字机效果）✅
|
||
- 出题 Prompt 模板管理（模板 CRUD + 参数注入：年级/学科/难度/知识点）✅
|
||
- 备课工作流编排（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库）✅
|
||
- 用量计费/频率限制（按用户/按 IP/按 token 消耗）✅
|
||
- **依赖上游**：
|
||
- P1 地基：api-gateway 路由
|
||
- P2 身份：iam 服务（鉴权 + DataScope）
|
||
- P4 内容分析：content 服务（gRPC 查询知识点 / 题库）+ data-ana 服务（gRPC 查询学情）
|
||
- 外部：LLM Provider API key（OpenAI / Anthropic / 百川 / 本地模型 Ollama）
|
||
- **下游依赖我**：
|
||
- P5 teacher-bff 聚合 AI 出题 mutation（004 §9.3：教师用 AI 出题并发布到班级）
|
||
- P5 teacher-portal SSE 流式 AI 对话（前端）
|
||
- **ai12 增补**：P5+ student-bff（学生自适应学习，未来阶段）
|
||
- **ai12 增补**：P5+ parent-bff（家长学情报告 AI 解读，未来阶段）
|
||
|
||
### 5.2 ai12 增补：阶段交付里程碑细分
|
||
|
||
将 P5（M14-M16，3 个月）细分为 3 个里程碑，便于优先级排序：
|
||
|
||
| 里程碑 | 时间 | 交付内容 | 退出标准 |
|
||
| ------ | ----- | ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
||
| M14 | 第1月 | LLMProvider 抽象 + OpenAI/百川/Ollama 适配器 + gRPC server（Chat/StreamChat）+ Redis 限流 | gRPC 流式 RPC 可调通，多 Provider 切换可用 |
|
||
| M15 | 第2月 | Prompt 模板管理（YAML + Jinja2）+ 出题工作流 + 题目逐字流式生成 + 用量计费事件 | 教师可发起 AI 出题，流式返回，用量落 ClickHouse |
|
||
| M16 | 第3月 | 备课工作流 4 步编排 + 教师审核 + 入库 + 评估框架（规则 + LLM-as-judge） | 备课工作流端到端跑通，质量门禁生效 |
|
||
|
||
## 6. 我需要对齐的黄金模板项（对照 classes 服务 + Python 规范）
|
||
|
||
### 6.1 对齐清单（ai06 初稿 + ai12 增补）
|
||
|
||
- [ ] 权限装饰器等价物：**当前 HTTP 端点全部裸露，无权限校验**。阶段 2 需设计 FastAPI Depends 权限依赖（AI 出题需 `AI_QUESTION_GENERATE` 权限，表达优化需 `AI_EXPRESSION_OPTIMIZE`）
|
||
- [ ] 错误码前缀统一：**当前无错误码体系**，降级时返回 `degraded: true` 但无业务错误码。**阶段 2 需定义 `AI_*` 错误码清单**
|
||
- [x] logger / metrics / tracer 三支柱（已具备）
|
||
- [x] `/healthz` + `/readyz` 健康检查（已具备，readyz 含 LLM 配置状态）
|
||
- [ ] 优雅关闭 SIGTERM：当前 lifespan 无显式 drain（LLM 流式请求需等待完成）
|
||
- [ ] 测试覆盖率 ≥ 80%：**当前 0%**，无 tests/ 目录
|
||
- [ ] Dockerfile 多阶段构建：**当前单阶段**（`FROM python:3.12-slim`）
|
||
- [ ] Pydantic 输入验证：**当前仅 `ChatRequest` 是 BaseModel，`generate/question` 和 `optimize/expression` 直接接收 `prompt: str` / `text: str` query param，无请求体模型**。阶段 2 需补完整 Pydantic 请求/响应模型
|
||
- [x] 配置通过 pydantic-settings 管理（已具备）
|
||
- [x] 异步优先（httpx async + AsyncGenerator stream）
|
||
- [x] 类型注解强制（已基本符合，main.py 函数返回值已标注）
|
||
- [ ] LLM Provider 适配器模式：**当前仅 OpenAI 兼容 REST**，未抽象 Provider 接口。阶段 2 需设计 `LLMProvider` 抽象 + OpenAI/Anthropic/百川/本地 多适配器
|
||
- [ ] Prompt 模板管理：**当前 Prompt 硬编码在 main.py**，阶段 2 需设计模板管理（DB 或文件）
|
||
- [ ] 用量计费 / 频率限制：**当前无用量记录和限流**，阶段 2 需设计（Kafka 事件 + Redis 限流）
|
||
- [ ] 备课工作流：**当前未实现**，pending-features P5 要求"分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库"完整工作流
|
||
- [ ] ruff check 零错误：需阶段 2 验证
|
||
|
||
### 6.2 ai12 增补：响应信封对齐（P0 强制）
|
||
|
||
- [ ] **响应信封改为 ActionState**（004 §11.5 强制约束）
|
||
- 当前违反：`{success: true, data: ..., degraded: false}` 顶层 degraded 字段
|
||
- 必须改为：`{success: true, data: ...}` + 失败时 `{success: false, error: {code, message, details: {degraded: true}, traceId}}`
|
||
- 影响：所有 HTTP 端点 + gRPC RPC 返回值
|
||
- 提请 coord 在 known-issues §2.9 记录
|
||
|
||
### 6.3 ai12 增补：长期架构对齐项
|
||
|
||
- [ ] **API 版本化策略**：当前无版本前缀，建议 P5 加 `/ai/v1/*` 前缀，便于未来破坏性变更
|
||
- [ ] **gRPC server interceptor 透传 trace context**：当前 HTTP 用 FastAPIInstrumentor 自动埋点，gRPC server 需补 `grpc.aio.ServerInterceptor` 透传 W3C traceparent
|
||
- [ ] **下游 gRPC client interceptor**：调 content / data-ana 的 gRPC client 需补 client interceptor 注入 trace context + 失败重试 + 熔断
|
||
- [ ] **PII 脱敏**：学生姓名、家长手机号等 PII 数据在写入 prompt 前必须脱敏（防止泄露给 LLM Provider）
|
||
- [ ] **Prompt 注入防御**：用户输入的 prompt 必须经 sanitize（去除 SQL/HTML/JS 注入模式）后再拼入 system prompt
|
||
- [ ] **输出内容审核**：LLM 输出必须经敏感词过滤 + 安全校验后再返回（防止生成不当内容）
|
||
- [ ] **生成结果质量门禁**：题目生成必须经规则校验（题型匹配/答案非空/解析合理）+ LLM-as-judge（质量评分），不达标重新生成或降级
|
||
- [ ] **多租户用量配额**：按学校/年级/教师维度配置 token 预算，超额拒绝调用（避免单一学校耗尽预算）
|
||
|
||
---
|
||
|
||
## 服务审计表 — ai12（ai 部分）
|
||
|
||
> 对照 ai-allocation.md §10 审计模板。ai 为 Python/FastAPI，黄金模板对齐按 Python 规范（coding-standards §4）评估。
|
||
> 符号说明：✅ 已实现 | ❌ 缺失 | ⚠️ 部分实现 | 📋 P5 待实现 | 🔮 P6+ 长期演进
|
||
|
||
| 服务 | 权限校验 | 错误码前缀 | logger | metrics | tracer | /healthz | /readyz | 优雅关闭 | 测试覆盖率 | Dockerfile | 响应信封 | gRPC server | Provider 适配 | Prompt 模板 | 限流/计费 | 备课工作流 | PII 脱敏 | 质量门禁 |
|
||
| ---- | -------- | ---------- | ------------ | ------------- | ------------------- | -------- | ----------------- | ------------------- | ---------- | ---------- | -------- | ----------- | ------------- | ----------- | --------- | ---------- | -------- | -------- |
|
||
| ai | ❌ | ❌ | ✅ structlog | ✅ prometheus | ✅ OTel（dev 跳过） | ✅ | ✅（含 LLM 状态） | ⚠️ 仅 lifespan 关闭 | 0% | ❌ 单阶段 | ❌ 偏离 | ❌ 待实现 | ❌ 待实现 | ❌ 硬编码 | ❌ 待实现 | ❌ 待实现 | ❌ 缺失 | ❌ 缺失 |
|
||
|
||
### 审计发现的关键差距（按优先级）
|
||
|
||
#### P0 阻塞 P5 交付（ai06 初稿 + ai12 增补）
|
||
|
||
1. **P0 权限校验缺失**：所有 `/ai/*` 端点裸露，AI 出题等敏感操作无权限校验
|
||
2. **P0 gRPC server 未实现**：ai.proto 定义了 `AiService`（含 `StreamChat` 流式 RPC）但 ai 当前仅 HTTP。阶段 2 需引入 `grpc.aio` 实现 gRPC server + 流式 RPC
|
||
3. **P0 gRPC client 未实现**：004 §4.1 明确 AI → Content / AI → DataAna 走 gRPC，当前未实现。阶段 2 需设计 gRPC client 调用 content / data-ana
|
||
4. **P0 响应信封偏离 ActionState**（ai12 增补）：004 §11.5 强制约束，当前违反
|
||
5. **P0 LLM Provider 适配器缺失**：当前 `llm_client.py` 仅 OpenAI 兼容 REST，未抽象 Provider 接口。pending-features P5 + ai-allocation.md §5 要求"LLM Provider 适配（OpenAI/百川/本地模型）"
|
||
6. **P0 Prompt 模板管理缺失**：system prompt 硬编码在 main.py，无模板管理。ai-allocation.md §5 要求"模板 CRUD + 参数注入：年级/学科/难度/知识点"
|
||
7. **P0 备课工作流缺失**：pending-features P5 + ai-allocation.md §5 要求"分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库"完整工作流，当前仅"生成题目"单步
|
||
8. **P0 用量计费 / 频率限制缺失**：无用量记录（token 消耗）、无频率限制（用户可无限调用 LLM）。ai-allocation.md §5 要求"按用户/按 IP/按 token 消耗"
|
||
|
||
#### P1 P5 阶段需补齐（ai12 增补）
|
||
|
||
9. **P1 题目逐字流式生成缺失**：当前 `/ai/chat/stream` 仅支持聊天流式，未实现题目生成的逐字流式（ai-allocation.md §5 "题目逐字生成 + 前端打字机效果"）
|
||
10. **P1 Prompt 模板 CRUD API 缺失**：ai-allocation.md §5 要求"模板 CRUD"，当前无 API
|
||
11. **P1 多维度限流缺失**：ai-allocation.md §5 要求"按用户/按 IP/按 token 消耗"三维度，当前仅设计用户级
|
||
12. **P1 测试覆盖率 0%**：无 tests/ 目录
|
||
13. **P1 Dockerfile 单阶段**：未做多阶段构建
|
||
14. **P1 Pydantic 输入验证不完整**：`generate/question` 和 `optimize/expression` 直接接收 query param，无请求体模型
|
||
|
||
#### P2 P6+ 长期演进（ai12 增补）
|
||
|
||
15. **P2 PII 脱敏缺失**：学生姓名/家长手机号等写入 prompt 前未脱敏，存在数据泄露风险
|
||
16. **P2 Prompt 注入防御缺失**：用户输入未 sanitize，存在 SQL/HTML 注入风险
|
||
17. **P2 输出内容审核缺失**：LLM 输出未过滤敏感词，存在生成不当内容风险
|
||
18. **P2 生成结果质量门禁缺失**：题目未校验题型/答案/解析合理性，可能生成不可用题目
|
||
19. **P2 多租户用量配额缺失**：无学校/年级级配额，单一学校可能耗尽预算
|
||
20. **P2 评估框架缺失**：无 LLM-as-judge / 人工评估机制，无法持续提升生成质量
|
||
21. **P2 RAG 语义检索缺失**：当前仅基于 content 知识点查询，无向量库语义检索
|
||
22. **P2 多模态支持缺失**：未规划图片/音频题目生成（数学几何题/英语听力题）
|
||
23. **P2 语义缓存缺失**：仅 hash 缓存，无基于 embedding 相似度的语义缓存
|
||
24. **P2 A/B 测试基础设施缺失**：无法对比不同 prompt/模型的效果
|
||
25. **P2 RLHF 数据收集缺失**：无教师反馈（采纳/拒绝/修改）记录机制
|
||
26. **P2 长运行工作流持久化缺失**：备课工作流的"教师审核"步骤可能跨数小时/天，无持久化机制
|
||
|
||
---
|
||
|
||
## 阶段 1 待 coord 交叉审查的跨模块契约对齐项
|
||
|
||
### ai06 初稿提请项（已在 coord 交叉审查报告中仲裁）
|
||
|
||
| # | 议题 | 涉及方 | 仲裁结论 |
|
||
| --- | ----------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 2 | **ai 是否发布 `edu.insight.ai.usage` 用量事件** | ai → data-ana | ✅ 已仲裁：coord 补登 topic，见 004 §7.2；events.proto 待补 `AIUsageEvent` message（coord 负责） |
|
||
| 3 | **data-ana / ai 是否需要实现 gRPC server** | data-ana / ai ← teacher-bff / student-bff / ai | ✅ 已仲裁：分阶段启用，见 004 §4.2 gRPC 启用阶段矩阵；ai 在 P5 启用（含 StreamChat） |
|
||
| 6 | **ai 备课工作流是否引入 Temporal** | ai + coord | ⚠️ 部分仲裁：004 §2.3 列出 Temporal 用于"工作流编排（考试生命周期、AI 编排）"，P3 已引入试点；ai12 建议简单工作流用 BackgroundTasks，长运行评估 Temporal，待 P6 决策 |
|
||
| 7 | **LLM Provider 切换的配置化** | ai + coord | ⚠️ 部分仲裁：ai12 设计 `LLMProvider` 抽象 + 配置化路由（按 model 名路由）；本地模型走 Ollama REST API；待 P6 评估是否提取到 shared-py |
|
||
|
||
### ai12 新增提请项（待 coord 仲裁）
|
||
|
||
| # | 议题 | 涉及方 | ai12 建议 |
|
||
| --- | ----------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||
| A1 | **ai gRPC 端口 50058**：004 §1.2 端口矩阵需补登 | ai + coord | ai HTTP 3008 + gRPC 50058（HTTP+10050 规则）；提请 coord 同步 004 §1.2 + 全局端口表 `infra/port-allocation.md` |
|
||
| A2 | **ai.proto 待补全**：备课工作流 RPC + 题目逐字流式 RPC + ChatRequest/GenerateQuestionRequest 字段扩展 | ai + coord | 见 §3.2 ai12 增补待补全项；建议 coord 在 P5 启动前完成 proto 升级到 v1 完整版 |
|
||
| A3 | **events.proto 待补 `AIUsageEvent` message**：004 §7.2 已确认 topic 但 proto 未定义 | ai + coord + data-ana | 协调 data-ana ai11 共同定义 payload schema；ai12 已在 02-architecture-design.md §5.2 给出建议 schema |
|
||
| A4 | **iam `GetEffectiveDataScope` gRPC RPC**：ai 需查询用户 DataScope 用于多租户配额校验 | ai + coord + iam | coord 已仲裁 P4 补全（§15.3 #5），ai12 在 P5 实施时调用 |
|
||
| A5 | **响应信封偏离 ActionState 强制整改**：004 §11.5 已约束，ai 当前违反 | ai + coord | P5 实施时必须整改；提请 coord 在 known-issues §2.9 记录 |
|
||
| A6 | **Prompt 模板存储位置**：YAML 文件 vs DB | ai + coord | ai12 建议 P5 用 YAML 文件（`services/ai/src/ai/prompts/*.yaml`），P6+ 评估迁移 DB；与 ai06 初稿一致 |
|
||
| A7 | **长运行工作流持久化**：备课工作流"教师审核"步骤可能跨数小时/天 | ai + coord | ai12 建议 P5 用 Redis 暂存（短期 24h TTL）+ BFF 编排审核状态；P6 评估迁移 Temporal 或自建 workflow_state 表 |
|
||
| A8 | **多模态支持规划**：图片/音频题目生成（数学几何/英语听力） | ai + coord | ai12 建议 P5 仅文本，P6+ 评估多模态；proto v2 预留 `multimodal_content` 字段 |
|
||
| A9 | **评估框架归属**：LLM-as-judge 在 ai 内部 vs 独立 evaluation 服务 | ai + coord | ai12 建议 P5/P6 在 ai 内部实现（避免服务拆分过早）；P7+ 评估独立 |
|
||
| A10 | **RLHF 数据收集**：教师反馈事件 `AIFeedbackRecorded` 是否新增 topic | ai + coord + data-ana | ai12 建议 P6+ 评估；topic: `edu.insight.ai.feedback`；data-ana 落 ClickHouse 供未来 fine-tune |
|
||
|
||
---
|
||
|
||
**AI Agent**: ai12 (ai) ← ai06（初稿）
|
||
**Branch**: 单仓库并行模式（直接提交 main）
|
||
**Coordinator**: coord-ai
|