# 知识库 GraphRAG

GraphRAG 为 Xpert 知识库增加图谱感知检索能力。它不会改变现有默认向量 RAG 行为，而是在开启后为文档异步构建轻量知识图谱，让检索可以同时利用实体、关系和源文档证据。

## 解决什么问题

向量检索适合直接语义匹配，但当问题需要跨多个 chunk 连接概念时，单纯向量相似度可能不稳定。GraphRAG 会从已索引文档中抽取显式实体和关系，把它们绑定回来源 chunk，并在检索时从命中的实体扩展到局部关系邻域。

典型场景包括：

- 查找与某个产品、客户、团队、指标、事故、政策或系统相关的全部事实
- 回答依赖多个 chunk 之间关系的问题
- 提升名称、别名、实体类型和关系很重要的领域知识召回
- 保留可追溯来源，通过 `documentId` 和 `chunkId` 回到证据片段

## 检索模式

知识库检索支持三种模式：

| 模式     | 行为                                                                                         | 适用场景                             |
| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `vector` | 使用现有向量相似度检索流程。默认仍然是该模式。                                               | 通用语义检索，以及保持当前生产行为。 |
| `graph`  | 使用 query embedding 召回图谱实体，扩展局部关系邻域，再返回证据 chunks。                     | 以实体为中心的问题、关系查询。       |
| `hybrid` | 合并 vector 和 graph chunks，按 chunk 去重，通过 `graphWeight` 融合分数，并复用已有 rerank。 | 大多数生产 GraphRAG 场景。           |

如果 GraphRAG 未开启，或 hybrid 检索中的图谱检索失败，现有向量检索路径仍然可用。

## 索引流程

开启 GraphRAG 后，文档入库仍会先完成现有 chunk 落库和向量写入。向量写入成功后，Xpert 会异步投递图谱索引任务。

图谱索引器会：

- 优先使用知识库配置的对话模型抽取实体、关系、别名、描述、证据 quote 和 confidence；未配置时回退到主模型
- 只按显式 `type` 与规范化名称合并实体
- 按知识库、源实体、目标实体和关系类型去重关系
- 将 mention 作为证据绑定到 `documentId` 和 `chunkId`
- 将实体摘要写入图谱实体向量集合
- 独立维护 graph job 状态，不影响文档向量入库状态

GraphRAG 索引失败不会改变文档已完成的向量入库状态，也不会阻断 Agent retriever 工具。

## 配置项

进入知识库配置页，在 Retrieval Settings 中启用 GraphRAG。

核心配置：

| 配置                      | 说明                                                   |
| ------------------------- | ------------------------------------------------------ |
| `enabled`                 | 是否为该知识库启用 GraphRAG 索引与图谱检索。默认关闭。 |
| `entityTopK`              | 从图谱实体向量集合召回的候选实体数量。                 |
| `neighborHops`            | 局部图谱扩展跳数。MVP 支持 1 到 2 跳。                 |
| `graphWeight`             | hybrid 检索中图谱分数的融合权重。                      |
| `extractionBatchSize`     | 每次抽取发送给 LLM 的 chunk 数量。                     |
| `extractionMaxCharacters` | 每批抽取输入的最大字符数。                             |

启用 GraphRAG 后，需要在配置页点击重建图谱。配置页会展示图谱状态、实体数量和关系数量。

## 状态说明

知识库会展示图谱状态：

| 状态               | 含义                                           |
| ------------------ | ---------------------------------------------- |
| `disabled`         | GraphRAG 未启用。                              |
| `rebuild_required` | GraphRAG 已启用，但需要先重建图谱。            |
| `indexing`         | 图谱索引任务正在排队或执行。                   |
| `ready`            | 图谱索引已成功完成。                           |
| `failed`           | 一个或多个图谱索引任务失败。向量检索仍然可用。 |

文档列表也会展示最近的 graph index job 状态，便于区分文档向量入库与图谱索引进度。

## 测试检索

在知识库测试页，可以在运行查询前选择 `Vector`、`Graph` 或 `Hybrid`。测试请求会把当前检索模式和 GraphRAG 参数发送到知识库测试接口。

建议优先用 `hybrid` 验证效果，因为它能看到 GraphRAG 如何增强现有向量召回，同时保留向量检索兜底能力。

## 图谱可视化与维护

启用 GraphRAG 后，知识库侧边栏会提供 `Graph` 页面。该页面使用交互式力导向图展示实体节点和关系边，并支持按关键词、实体类型、关系类型、来源、可见性、焦点实体、扩展深度和返回数量过滤。

Graph 页面会展示当前用于 GraphRAG 抽取的对话模型，并提供返回知识库配置页的入口。模型本身仍在知识库级别配置，而不是放在图谱编辑器中配置。

运营人员可以从图谱或右侧列表中选择实体或关系。详情面板会展示当前选中对象、关联关系，以及只读 evidence mention，保留 `documentId` 和 `chunkId` 的来源追溯。

GraphRAG v1 支持人工维护：

- 手动创建实体和关系
- 编辑抽取实体的名称、类型、别名、描述和可见性
- 编辑关系端点、类型、描述、权重和可见性
- 隐藏实体或关系，而不是物理删除
- mention/evidence 只读，不直接编辑证据链

手动创建和人工维护的数据会在文档重新索引和图谱 rebuild 后保留。Rebuild 会刷新抽取证据和抽取来源的 active 行，但不会删除 manual、curated 或 hidden 行。Hidden 实体和关系默认不参与图谱检索、图谱可视化和实体向量同步。

## API 概览

GraphRAG 新增以下知识库 API：

| Endpoint                                                       | 用途                                                    |
| -------------------------------------------------------------- | ------------------------------------------------------- |
| `POST /knowledgebase/:id/graph/rebuild`                        | 重建抽取图谱数据，并保留 manual、curated 和 hidden 行。 |
| `GET /knowledgebase/:id/graph/status`                          | 返回图谱聚合状态、数量统计和最近图谱任务。              |
| `GET /knowledgebase/:id/graph/entities`                        | 列出该知识库的图谱实体。                                |
| `GET /knowledgebase/:id/graph/entities/:entityId/neighborhood` | 返回实体局部邻域、关系和证据 mentions。                 |
| `GET /knowledgebase/:id/graph/visualization`                   | 返回可视化所需的节点、边和类型筛选项。                  |
| `GET /knowledgebase/:id/graph/relations`                       | 列出图谱关系及其源实体、目标实体。                      |
| `GET /knowledgebase/:id/graph/mentions`                        | 按实体、关系、文档或 chunk 列出只读证据 mentions。      |
| `POST /knowledgebase/:id/graph/entities`                       | 创建手动实体。                                          |
| `PATCH /knowledgebase/:id/graph/entities/:entityId`            | 维护实体，或通过 `visibility` 恢复/隐藏实体。           |
| `DELETE /knowledgebase/:id/graph/entities/:entityId`           | 软隐藏实体及其关联关系。                                |
| `POST /knowledgebase/:id/graph/relations`                      | 创建手动关系。                                          |
| `PATCH /knowledgebase/:id/graph/relations/:relationId`         | 维护关系，或通过 `visibility` 恢复/隐藏关系。           |
| `DELETE /knowledgebase/:id/graph/relations/:relationId`        | 软隐藏关系。                                            |
| `POST /knowledgebase/:id/test`                                 | 支持传入检索模式和 GraphRAG 参数，用于检索测试。        |

## MVP 范围

当前 GraphRAG 版本聚焦局部图检索和人工维护：

- Postgres 和 TypeORM 图谱表
- 异步图谱索引任务
- LLM 实体关系抽取
- 实体向量召回
- 1 到 2 跳邻域扩展
- `vector`、`graph`、`hybrid` 三种检索模式
- 配置、重建、状态、测试、图谱可视化，以及实体/关系维护 UI

当前 MVP 不包含社区/global search，不引入 Neo4j 或 Fuseki，也不提供自由编辑 mention/evidence 的能力。
