AgentbaseDocs
文档目录

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

本手册对应 Agentbase v2.10.0(控制台同版本)。

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

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


功能概述与核心场景

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

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


核心概念与架构

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

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

flowchart TB
    Index["GraphRAG 已构建的结果"] --> Filters["填写 Console 查询条件"]
    Filters --> Load["手动加载图谱和报告"]
    Load --> Canvas["查看当前页节点和边"]
    Load --> Reports["查看画布下方报告卡片"]
    Canvas --> Node["点击实体:按 hops / limit 查询邻居"]
    Node --> Neighbors["邻居结果替换当前画布"]
    Neighbors --> Back["返回原图结果"]
    Back --> Canvas
    Canvas --> Group["点击分组:筛选相关报告"]
    Group --> Reports
    Reports --> Node
    Index --> Search["单库检索按需启用 useKnowledgeGraph"]
    Search --> Evidence["检查增强结果、降级信息与来源"]

图谱结果与字段说明

对象字段阅读方法
图谱结果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)

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

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:指定文档定位值后仍看到公共实体,是否代表过滤失效?

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


相关文档