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

问题陈述

为“向量知识库”单独建立可实施设计，补齐向量入库、切片、检索、审计与租户隔离能力，并与图谱知识库形成明确分工与协同。

当前状态（已确认）

• 架构文档将 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/教师内容边界容易在实现时被混用。

需确认的设计决策

• 首期是否先做“单向量模型 + 单索引集合”简化方案，再演进多模型路由。
• 向量检索与图检索的融合策略首期采用串行还是并行（推荐串行，便于控制复杂度）。
• 检索日志保留周期与脱敏策略（涉及学生查询内容合规）。