更新

docs/plan/modules/向量知识库.md

@@ -0,0 +1,39 @@
+# 问题陈述
+为“向量知识库”单独建立可实施设计，补齐向量入库、切片、检索、审计与租户隔离能力，并与图谱知识库形成明确分工与协同。
+## 当前状态（已确认）
+* 架构文档将 Milvus 设为向量检索主方案。参考 `docs/architecture/base-services.md (13-16)`、`docs/architecture.md (8-13)`。
+* 现有 AI 表仅包含 `vector_sync_status` 字段与 `target_store=VECTOR` 同步任务，不含向量文档/切片/检索日志实体。参考 `init/pg/ai/10_create_ai_tables.sql (13-15)`、`init/pg/ai/10_create_ai_tables.sql (77-104)`。
+* 种子数据已演示 GRAPH 与 VECTOR 双任务并存，但仍是占位任务。参考 `init/pg/ai/20_init_ai_seed.sql (46-76)`。
+* `python-ai` 与 `ai-client` 当前仅有健康检查能力，未实现向量入库与检索接口。参考 `backend/python-ai/app/main.py (1-13)`、`backend/ai-client/src/main/java/com/k12study/aiclient/client/PythonAiClient.java (1-7)`。
+## 模块拆分与设计细节
+### 1) 子模块边界
+* `vector-ingestion`：文档清洗、切片、embedding 生成、重建任务。
+* `vector-storage`：向量文档、切片元数据、索引状态管理。
+* `vector-retrieval`：语义检索、召回重排、结果解释。
+* `vector-governance`：模型版本、数据有效期、删除回收、审计日志。
+### 2) 入库策略（按你给定口径）
+* 总部知识库：进入向量 + 图谱。
+* 教师班级课程/课件：仅图谱，不进入向量。
+* 在知识文件层配置 `ingest_policy`（BOTH/GRAPH_ONLY），向量任务创建器仅对 `BOTH` 生成向量任务。
+### 3) 数据模型建议（可改 `init` SQL）
+* 新增 `ai.tb_ai_vector_document`：文档级元数据（tenant/scope/model_version/index_status）。
+* 新增 `ai.tb_ai_vector_chunk`：切片文本、chunk_order、token_count、embedding_ref。
+* 新增 `ai.tb_ai_vector_index_task`：索引构建/重建任务与错误重试。
+* 新增 `ai.tb_ai_retrieval_log`：查询语句、召回范围、tenant_id、命中文档、耗时、调用端。
+* 与 `tb_ai_knowledge_file` 建立一对多映射，保留来源追溯。
+### 4) 租户隔离与端侧约束
+* 向量检索必须按 `tenant_id + knowledge_scope` 过滤；默认禁止跨租户召回。
+* 班级场景增加 `class_id/course_id` 过滤，避免跨班级内容泄漏。
+* 小程序学生端检索结果仅允许返回课堂练习/课后作业关联内容，不返回教师课件全文。
+### 5) 与图谱协同
+* 支持“图谱先召回候选 -> 向量精排”或“向量召回 -> 图谱关系扩展”双阶段策略。
+* 检索响应统一返回来源对象（课程/题目/知识点），交由业务域二次鉴权展示。
+## 问题点与风险
+* 当前缺少向量核心表结构，无法稳定支撑入库追踪、检索审计与故障重建。
+* 未定义 embedding 模型版本与重建策略，后续模型升级会导致历史索引不可比对。
+* 无检索日志会导致“召回错误/越权返回”难以追溯。
+* 若不先固化入库策略，HQ/教师内容边界容易在实现时被混用。
+## 需确认的设计决策
+* 首期是否先做“单向量模型 + 单索引集合”简化方案，再演进多模型路由。
+* 向量检索与图检索的融合策略首期采用串行还是并行（推荐串行，便于控制复杂度）。
+* 检索日志保留周期与脱敏策略（涉及学生查询内容合规）。