Docs
文档目录

知识图谱(Graph)可视化探索与社区报告

知识库的 图谱(Graph) 页签用于浏览 GraphRAG 已构建的实体、关系和社区报告。先通过关键词、实体类型或社区收窄结果,再查看节点邻居和报告证据,适合检查知识抽取结果以及分析跨文档关联。图谱展示的关联需要结合原文判断,不能仅凭节点相连就认定某条业务结论成立。

本文使用 kb_enterprise_support、ent_ob_err_4013 等示例资源说明操作;项目、知识库、实体、模型和定位值均需替换为实际资源。示例查询不代表当前环境已存在这些数据或已完成在线验收。


功能概述与核心场景

以数据库排障知识库为例,团队可以用图谱回答三个检查问题:故障现象是否关联到相关参数,处置步骤是否关联到责任角色,社区报告是否正确概括多篇手册的共同主题。检查时应保留检索条件、知识库版本和结果代数,便于同事复核相同范围的数据。

  1. 交互式图谱画布:显示节点和边,支持缩放、平移、拖动节点与悬停高亮。节点颜色按实体类型分组,节点大小参考返回的 rank;页面没有手动切换着色模式的控件。

  2. 手动加载与分页:在 Console 填写关键词、实体类型、社区、种子实体和跳数,选择每页大小,再点击加载。修改输入不会立即发起查询,分页沿用已经加载的条件。

  3. 邻居探索:点击节点会按当前跳数和每页大小加载其邻居,并以邻居结果替换当前画布;可返回原图结果继续检查。

  4. 社区报告:报告卡片位于画布下方,展示标题、权重、实体以及有内容的报告/证据正文。点击画布中的分组可收窄相关报告,点击报告中的实体可查看邻居。

HTTP 图谱接口还支持 documentId、documentTag 和 subProductId 过滤。这些 API 字段与 Console 实际提供的输入项不同,不能按 API 参数列表寻找界面控件。


核心概念与架构

图谱浏览、邻居与报告的操作关系

以下为操作流程示意,实际界面以当前项目为准。

知识图谱(Graph)可视化探索与社区报告:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

图谱结果与字段说明

对象字段阅读方法
图谱结果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 APINode.js / Python 方法前置与权限
图谱与过滤知识库 → 图谱GET /v1/knowledgebases/{kbId}/graphgetGraph() / get_graph()当前用户须有知识库读取权限;API Key 需 knowledgebases.read,且已有可读图谱结果。
邻居展开点击画布节点或报告中的实体GET /v1/knowledgebases/{kbId}/graph/entities/{entityId}/neighborsgetGraphEntityNeighbors() / get_graph_entity_neighbors()使用实际返回的实体标识;跳数和节点上限会限制结果。
社区报告画布下方报告卡片GET /v1/knowledgebases/{kbId}/graph/community-reportslistGraphCommunityReports() / list_graph_community_reports()同一知识库和版本中的已生成报告。
图谱增强检索知识库 → 检索测试;开关是否出现受部署能力控制POST /v1/knowledgebases/{kbId}/searchcreateSearch() / create_search()需配置相关能力与模型;答案合成另需单库 answer: true。

功能详解与操作指南

一、加载图谱并过滤当前查询(GET /graph)

  1. 登录 Console,进入目标项目、知识库详情,再打开 图谱(Graph) 页签。首次进入只显示加载提示,需手动点击加载。

  2. 在顶部输入框填写关键词、实体类型、社区或种子实体。实体类型与社区均为文本输入;不知道有效值时先少设条件,查看已有节点后再收窄。

  3. 设置跳数 hops(0~5,默认 1),并选择每页 20、50 或 100 个节点,默认 20。种子实体用于有界邻居展开。

  4. 点击加载,等待请求结束后检查节点数、结果代数、画布和报告。修改条件后再次加载才会更新结果;使用上一页/下一页时,页面继续使用已经加载的查询条件。

  5. 用鼠标缩放、平移画布,悬停查看相邻关系。若希望重新检查整个查询结果,可以清除关键词、实体类型、社区和种子条件后加载。切换知识库版本会清空旧显示,需重新加载新版本结果。

通过 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)

  1. 在已加载的画布中点击一个实体,或点击报告卡片中的实体名称。Console 使用该实体 ID、当前 hops 和每页大小请求邻居。

  2. 请求成功后,画布显示邻居响应中的节点和边,相关报告按所选实体筛选。这里是结果视图切换,不是向原图无限追加节点,也不打开实体详情抽屉。

  3. 若需扩大或缩小范围,调整跳数和每页大小,再选择实体或重新加载。注意 truncated;请求上限可能使某些关联暂未出现在结果中。

  4. 点击返回图谱结果按钮,恢复此前加载的整图结果。若要核对某条业务结论,结合实际来源文档、检索结果与报告证据检查,不依赖不存在的“一键分块原文抽屉”。

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,示例模型需已在项目中可用。前三项是读取;第四项会调用所配置的检索及答案模型。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
# 1. 查询图谱:实体类型的 HTTP 字段为 type
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "${APPBASE_ENDPOINT}/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: ${APPBASE_PROJECT_ID}" \
  --header @-

# 2. 查询邻居:hops 指定展开跳数
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/graph/entities/ent_ob_err_4013/neighbors?hops=2&limit=30" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-

# 3. 分页读取社区报告
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/graph/community-reports?offset=0&limit=20" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-

# 4. 单库图谱增强检索与答案合成
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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:指定文档定位值后仍看到公共实体,是否代表过滤失效?

同一实体可能来自多篇文档。过滤后的图谱中保留公共实体,并不能单独证明定位过滤无效。先核对传入定位值是否是目标文档的完整标识、两个过滤条件是否相交,再检查实际返回的来源及版本。定位标识和独立子产品字段的派生、清除规则见文档管理;仅清空独立字段后,读取仍可能采用已有定位标识的首段。


相关文档

社区展开与过期图谱

进入图谱后,支持社区目录的构建结果会自动加载社区实体和关系,显示已加载数量。点击社区名称聚焦,使用独立“收起”按钮隐藏成员;加载时可以取消,失败后可以重试。多个社区可并行加载,已展开节点保持位置;超过显示预算时按提示收起社区或缩小搜索范围。旧构建没有社区目录时只能展示有限实体,需重新构建才能获得社区概览。

安全的文档/分块更新之后,页面可以继续展示上次成功图谱及明确的过期提示;这不会自动启用过期图谱检索。点击“完整重建”只跳到当前库的索引页,再选择 GraphRAG 创建任务。来源删除或禁用、模型/配置变化、版本不符、快照损坏或检查超预算时,旧图谱仍不可读取。