# 知识图谱检索升级方案

## 目标

解决训练营导图和内容任务在大知识库下的三个问题：

1. 不把全库原文一次性放进模型上下文；
2. 检索既快又能覆盖概念之间的关系；
3. 图谱、向量库或模型异常时仍能稳定生成并保留原文证据。

目标指标：

- 热态知识检索 P95：250ms 以内；
- 首次冷启动检索：2 秒以内；
- 内容任务最终注入：按 4,000～8,000 token 预算动态决定，不固定条数；
- 训练营标准深度规划：10～30 分钟，超过硬截止时间必须保存阶段性结果；
- 每个结论都能回溯到原始 chunk、文件和版本；
- 图谱服务异常时自动回退到现有向量 + 中文 FTS + RRF + Cross-Encoder 链路。

## 总体架构

```text
上传与索引
  ├─ 原始文件、chunk、哈希和版本
  ├─ 向量索引
  ├─ 中文 FTS 索引
  ├─ 分层底稿（文件级、分类级、知识库级）
  └─ 知识图谱（实体、关系、证据、版本）

用户查询
  → 权限和分类过滤
  → 查询理解（实体、概念、约束、目标）
  → 图谱 1～2 跳关系扩展
  → 图谱证据指向的原文 + 向量/FTS 候选召回
  → 去重与主题覆盖
  → Cross-Encoder 精排
  → 父级上下文扩展
  → token 预算注入模型
  → 生成、质检、引用回溯
```

图谱是“导航和关系路由层”，原始 chunk 是“事实证据层”。任何图谱节点和关系都必须保存来源 chunk，不允许只凭图谱结论生成内容。

## 图谱数据设计

### 实体

实体至少包括：主题、概念、方法、步骤、人物、产品、风险、适用人群、工具、章节和课程天数。每个实体保存：

- `entity_id`、组织和知识库范围；
- 规范名称、别名、类型；
- `canonical_hash`、首次出现和最后更新时间；
- 抽取模型、抽取版本和置信度；
- 对应的来源 chunk 数量。

### 关系

关系采用有向边，例如：先决条件、组成、步骤先后、适用、反例、风险、冲突、相似、引用、属于分类。每条边保存：

- `from_entity_id`、`to_entity_id`、关系类型；
- 权重和置信度；
- `source_chunk_ids`、文件、版本；
- 抽取版本、创建时间和失效时间。

### 版本与权限

图谱实体、关系和证据都必须带组织、知识库、文件版本和分类范围。查询先做权限过滤再做图扩展，不能先查全图再过滤，否则会有越权风险。

## 建图流程

### 上传时增量建图

1. 文件解析、清洗、去重和分块；
2. 根据 `content_hash + chunking_version` 判断是否已有处理结果；
3. 只对新增或发生变化的文件抽取实体和关系；
4. 对别名和同义实体做规范化合并；
5. 写入关系及来源 chunk；
6. 让受影响的分类综述和知识库总览失效；
7. 后台重新生成受影响的摘要和图谱局部；
8. 发布新的图谱版本，旧版本仍可回溯。

图谱建立使用幂等任务、租约、断点游标和阶段性进度。单文件失败不会阻塞整库，也不会把未完成状态标成完成。

### 抽取策略

- 规则抽取：标题、列表、编号、术语表、明显步骤和引用关系优先用本地规则完成；
- 模型抽取：只对规则无法判断的实体和关系做批量 AI 抽取；
- 冲突处理：保留两条关系和各自来源，标记为冲突，交给查询阶段核验；
- 低置信关系：只能用于召回扩展，不能单独作为最终证据；
- 关系重复：按规范化实体、关系类型、来源版本去重。

## 训练营导图检索

### 快速模式

1. 解析主题和用户选择的知识库/分类；
2. 图谱定位相关主题、先决条件、步骤链和冲突点；
3. 以图谱命中的实体和来源 chunk 作为定向查询词；
4. 并行执行向量和中文 FTS 召回；
5. 按知识库、分类和主题做配额，避免大库占满结果；
6. RRF 融合、去重和多样性筛选；
7. Cross-Encoder 对最多 32～64 个候选精排；
8. 回溯代表性原文，按 token 预算交给导图模型。

快速模式不再声称通读全库，返回检索范围、图谱覆盖主题和未覆盖主题。

### 标准/深度模式

1. 先读知识库级和分类级底稿；
2. 从图谱确定相关主题簇、依赖链和冲突区域；
3. 只对相关文件和代表性资料定点回查原文；
4. 对关键缺口和冲突做二次检索；
5. 生成导图和每日递进关系；
6. 保存覆盖范围、引用、未完成主题和可续跑游标。

完整模式不再按 30 万段原文逐批重新交给模型。摘要和图谱按内容哈希增量复用，只有新增、变化或被主题路由命中的区域需要处理。

## 内容任务 Agent 检索

1. 由导图节点、标题、标签、产品和上一段锚点生成查询；
2. 图谱扩展相关概念、步骤、风险和先决条件；
3. 向量 + FTS 初召回 30～60 条；
4. 权限、分类、禁用和消费状态过滤；
5. RRF 融合和近重复去重；
6. Cross-Encoder 精排 16～32 条；
7. 命中 child chunk 后合并同一 parent 的相邻内容；
8. 按 4,000～8,000 token 预算动态注入 6～12 条或更少/更多的来源；
9. 只预留真正注入的片段，生成成功后再标记 consumed；
10. 生成后记录引用、锚点和图谱关系，供下一段承接。

“已读/已摘要”和“已消费”必须保持独立状态。预读不会占用内容任务的消费额度。

## 存储选型

第一阶段保留现有本地向量和 FTS 架构，在业务数据库增加图谱索引或独立的图谱表，先验证质量和延迟。当前不建议为了图谱立即迁移 Qdrant 或 Neo4j，避免在检索质量尚未有评测数据时增加运维单点。

当图谱边和实体规模、并发写入或多租户查询超过本地数据库能力时，再将图谱迁移到 Neo4j/ Memgraph 或 PostgreSQL 图扩展；迁移必须保留 `source_chunk_ids`、版本和权限字段，并提供只读回退。

向量库迁移到 Qdrant只在以下条件满足时进行：现有向量召回 P95 持续超标、索引更新阻塞检索、或需要多副本高并发。迁移前先用同一批标注问题做 Recall@10、MRR、NDCG 和 P95 对比。

## 稳定性和降级

- 图谱不可用：回退向量 + FTS + RRF；
- Cross-Encoder 未加载：回退 RRF；
- FTS 索引预热中：先返回向量召回并标记状态；
- AI 抽取超时：保留原文和已完成图谱，任务可续跑；
- 生成超时：保存阶段结果、游标、费用和未完成主题；
- 所有后台任务采用原子租约、唯一执行键和幂等写入；
- 生产环境不把图谱构建放在 FastAPI 请求线程。

## 验收方法

建立 100～300 条人工标注问题，覆盖主题、步骤、先决条件、冲突和跨文件关系。比较改造前后：

- Recall@10、MRR、NDCG；
- 内容段质检通过率、事实错误率、重复率；
- 来源可追溯率；
- 热态和冷态 P50/P95；
- 图谱不可用时的回退成功率；
- 增量上传后受影响范围是否正确；
- 跨用户、跨组织和分类权限隔离。

## 实施顺序

### P0：观测和基准

保留当前稳定链路，记录候选数量、过滤数量、精排数量、注入 token、引用数量和各阶段耗时，建立标注集。

### P1：图谱增量底座

加入实体、关系、证据、版本和抽取任务；先从标题、术语、步骤和引用关系开始，建立局部图谱和来源回溯。

### P2：图谱路由接入

训练营导图先用图谱定位主题簇和依赖链，再定点回查；内容任务先用图谱补充查询，再走混合召回。

### P3：精排与上下文扩展

启用已部署的本地 Cross-Encoder，接入 parent-child 上下文和 token 预算，做 A/B 评测后调整候选数。

### P4：规模化

只有当指标证明当前本地架构成为瓶颈时，再迁移 Qdrant 或独立图数据库，并保留降级路径。