知识图谱(Graph)可视化探索与社区报告
本手册对应 Agentbase v2.10.0(控制台同版本)。
知识库的 图谱(Graph) 页签用于浏览 GraphRAG 已构建的实体、关系和社区报告。先通过关键词、实体类型或社区收窄结果,再查看节点邻居和报告证据,适合检查知识抽取结果以及分析跨文档关联。图谱展示的关联需要结合原文判断,不能仅凭节点相连就认定某条业务结论成立。
本文使用 kb_enterprise_support、ent_ob_err_4013 等示例资源说明操作;项目、知识库、实体、模型和定位值均需替换为实际资源。示例查询不代表当前环境已存在这些数据或已完成在线验收。
功能概述与核心场景
以数据库排障知识库为例,团队可以用图谱回答三个检查问题:故障现象是否关联到相关参数,处置步骤是否关联到责任角色,社区报告是否正确概括多篇手册的共同主题。检查时应保留检索条件、知识库版本和结果代数,便于同事复核相同范围的数据。
交互式图谱画布:显示节点和边,支持缩放、平移、拖动节点与悬停高亮。节点颜色按实体类型分组,节点大小参考返回的
rank;页面没有手动切换着色模式的控件。手动加载与分页:在 Console 填写关键词、实体类型、社区、种子实体和跳数,选择每页大小,再点击加载。修改输入不会立即发起查询,分页沿用已经加载的条件。
邻居探索:点击节点会按当前跳数和每页大小加载其邻居,并以邻居结果替换当前画布;可返回原图结果继续检查。
社区报告:报告卡片位于画布下方,展示标题、权重、实体以及有内容的报告/证据正文。点击画布中的分组可收窄相关报告,点击报告中的实体可查看邻居。
HTTP 图谱接口还支持 documentId、documentTag 和 subProductId 过滤。这些 API 字段与 Console 实际提供的输入项不同,不能按 API 参数列表寻找界面控件。
核心概念与架构
图谱浏览、邻居与报告的操作关系
以下为操作流程示意,实际界面以当前项目为准。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
图谱结果与字段说明
| 对象 | 字段 | 阅读方法 |
|---|---|---|
| 图谱结果 | resultGeneration、versionId | 标识结果代数与解析后的知识库版本;排查不同结果时先确认是否来自同一版本和代数。 |
| 图谱结果 | graph | 包含节点和边;画布消费 nodes / edges,节点使用 id 和标签,边使用 source / target。 |
| 图谱结果 | totalNodes、hasMore、nextCursor | 匹配节点总量及后续分页信息;游标应使用上次响应返回值,不自行拼接。 |
| 图谱 / 邻居结果 | truncated | 表示结果受边界限制;当前画布不能当成整个知识库的完整图谱。 |
| 邻居结果 | nodes、edges | 从指定实体展开得到的节点与边;与整图响应的 graph 包装不同。 |
| 社区报告 | id、communityId、title | 报告标识、所属社区和标题。 |
| 社区报告 | entities、weight、content | 报告关联实体、权重和结构化正文;Console 展示 content.report 与 content.evidences 中可显示的文本。 |
节点及边的附加属性随图谱产物而异。需要核对来源时,应检查实际返回的来源信息并进入对应文档查看原文;不要假定每个节点都具备完整分块信息,也不要把画布颜色或大小当作答案正确率。
功能入口与权限矩阵
| 功能 | Console 入口 | REST API | Node.js / Python 方法 | 前置与权限 |
|---|---|---|---|---|
| 图谱与过滤 | 知识库 → 图谱 | GET /v1/knowledgebases/{kbId}/graph | getGraph() / get_graph() | 当前用户须有知识库读取权限;API Key 需 knowledgebases.read,且已有可读图谱结果。 |
| 邻居展开 | 点击画布节点或报告中的实体 | GET /v1/knowledgebases/{kbId}/graph/entities/{entityId}/neighbors | getGraphEntityNeighbors() / get_graph_entity_neighbors() | 使用实际返回的实体标识;跳数和节点上限会限制结果。 |
| 社区报告 | 画布下方报告卡片 | GET /v1/knowledgebases/{kbId}/graph/community-reports | listGraphCommunityReports() / list_graph_community_reports() | 同一知识库和版本中的已生成报告。 |
| 图谱增强检索 | 知识库 → 检索测试;开关是否出现受部署能力控制 | POST /v1/knowledgebases/{kbId}/search | createSearch() / create_search() | 需配置相关能力与模型;答案合成另需单库 answer: true。 |
功能详解与操作指南
一、加载图谱并过滤当前查询(GET /graph)
登录 Console,进入目标项目、知识库详情,再打开 图谱(Graph) 页签。首次进入只显示加载提示,需手动点击加载。
在顶部输入框填写关键词、实体类型、社区或种子实体。实体类型与社区均为文本输入;不知道有效值时先少设条件,查看已有节点后再收窄。
设置跳数
hops(0~5,默认1),并选择每页20、50或100个节点,默认20。种子实体用于有界邻居展开。点击加载,等待请求结束后检查节点数、结果代数、画布和报告。修改条件后再次加载才会更新结果;使用上一页/下一页时,页面继续使用已经加载的查询条件。
用鼠标缩放、平移画布,悬停查看相邻关系。若希望重新检查整个查询结果,可以清除关键词、实体类型、社区和种子条件后加载。切换知识库版本会清空旧显示,需重新加载新版本结果。
通过 API 指定文档范围:Console 当前没有 documentId、documentTag、subProductId 输入框。需要这些条件时,可使用 HTTP 图谱接口,例如 subProductId = ob 或 documentTag = ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d。定位标识按精确匹配处理;独立子产品编码与定位标识一起提交时按交集过滤。替换为实际文档定位值,格式参见文档与摄取管理。
| HTTP 参数 | 作用与边界 |
|---|---|
query、type、community | 关键词、实体类型与社区过滤;HTTP 字段使用 type 和 community。 |
seed、hops | 种子实体与展开跳数;hops 为 0~5,默认 1。 |
limit、cursor | 节点上限与分页游标;API 的 limit 默认 100,范围 1~1000,与 Console 的默认每页大小分开。 |
documentId、documentTag、subProductId | 限定来源文档或子产品;定位值须满足格式约束,不能填写自由文本分类路径。 |
versionId | 可选知识库版本;核对响应的解析版本和结果代数后再比较不同查询。 |
二、查看邻居并返回原图(/graph/entities/{entityId}/neighbors)
在已加载的画布中点击一个实体,或点击报告卡片中的实体名称。Console 使用该实体 ID、当前
hops和每页大小请求邻居。请求成功后,画布显示邻居响应中的节点和边,相关报告按所选实体筛选。这里是结果视图切换,不是向原图无限追加节点,也不打开实体详情抽屉。
若需扩大或缩小范围,调整跳数和每页大小,再选择实体或重新加载。注意
truncated;请求上限可能使某些关联暂未出现在结果中。点击返回图谱结果按钮,恢复此前加载的整图结果。若要核对某条业务结论,结合实际来源文档、检索结果与报告证据检查,不依赖不存在的“一键分块原文抽屉”。
HTTP 邻居接口使用 hops,范围同样是 0~5,limit 默认 100、范围 1~1000。实体 ID 应来自当前版本返回的节点;不要使用其他知识库的 ID,也不要把显示名称默认当成实体 ID。
三、阅读社区报告并使用图谱增强检索
1. 阅读社区报告(GET /graph/community-reports)
加载图谱时会同时请求报告,报告卡片显示在画布下方。查看标题、权重与关联实体,再阅读报告及证据正文;没有对应文本时该正文区域不会显示。点击画布分组可筛选相关报告,清除报告筛选可恢复列表。图谱中的分组是当前节点关系的可视化分组,不应仅凭分组外观推断后端社区层级。
Console 的报告请求上限为 100。通过 API 获取更多报告时使用 limit / offset,limit 范围 1~1024,并检查 hasMore;接口没有层级筛选参数。报告结构中的 weight 与模型自行生成的业务评价不同,不能解释为固定的 0~10 正确率。
2. 图谱增强的单库检索(useKnowledgeGraph: true)
单库检索可设置 useKnowledgeGraph: true 请求图谱增强,并按需设置 answer: true 合成答案。答案模型取知识库的 indexingDefaults.chatModel / chatProviderRef。检查返回的能力、降级信息、命中证据与答案状态;图谱可浏览并不保证模型调用或答案合成成功。
allowDegraded 控制增强检索失败时是否允许普通结果降级,不能用来吞掉显式重排模型或 Provider 的错误。需要完整默认值、重排与答案状态说明时,参见检索测试。
3. 图谱、邻居、报告和增强检索 HTTP 示例
下列请求使用项目 API Key,示例模型需已在项目中可用。前三项是读取;第四项会调用所配置的检索及答案模型。
# 1. 查询图谱:实体类型的 HTTP 字段为 type
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/graph?query=4013&type=%E6%95%85%E9%9A%9C%E7%A0%81&subProductId=ob&limit=50" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"
# 2. 查询邻居:hops 指定展开跳数
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/graph/entities/ent_ob_err_4013/neighbors?hops=2&limit=30" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"
# 3. 分页读取社区报告
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/graph/community-reports?offset=0&limit=20" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"
# 4. 单库图谱增强检索与答案合成
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/search" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "OceanBase 报 -4013 时应先检查哪些排障步骤?",
"searchMode": "hybrid",
"vectorWeight": 0.7,
"useKnowledgeGraph": true,
"rerank": true,
"rerankModel": "qwen3.7-text-rerank",
"allowDegraded": true,
"answer": true,
"limit": 5
}'常见问题与排障(FAQ)
Q1:进入图谱页后没有节点,如何判断原因?
先区分尚未加载、加载失败和成功返回空结果。首次进入需要手动加载;若有请求错误,先按错误信息排查权限、版本与索引可用性。请求成功但节点为空时,清除过窄条件后再加载,并确认该知识库已经构建 GraphRAG。文档摄取完成不等于图谱构建完成;到高级知识索引检查构建结果,成功后回到图谱页重新加载。
Q2:同义实体没有合并,应该怎样检查?
先查看实际输入文档及已绑定的词库规则,再核对 GraphRAG 的配置与构建代数。词库或索引配置改变后,已有图谱不会仅因刷新页面而重新抽取;按索引页面支持的操作重建并检查新结果。避免仅凭显示名称相近就认定实体应合并,也不要把旧代数和新代数混在一起比较。词库使用说明见项目级词库。
Q3:指定文档定位值后仍看到公共实体,是否代表过滤失效?
同一实体可能来自多篇文档。过滤后的图谱中保留公共实体,并不能单独证明定位过滤无效。先核对传入定位值是否是目标文档的完整标识、两个过滤条件是否相交,再检查实际返回的来源及版本。定位标识和独立子产品字段的派生、清除规则见文档管理;仅清空独立字段后,读取仍可能采用已有定位标识的首段。
