AgentbaseDocs
文档目录

GraphRAG、RAPTOR 与高级知识索引构建治理

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

知识索引(Index Capabilities) 是 Agentbase v2.10.0 知识库突破传统平面分块检索(Flat Chunk RAG)局限、面向复杂多跳推理与跨文档宏观归纳打造的高级派生索引治理中心。通过知识库详情页的 知识索引(Indexes) 页签,企业可以在基础向量与全文索引之上,按需开启并精细化编排 GraphRAG(实体关系知识图谱与 Leiden 社区报告)、RAPTOR(基于 GMM+BIC 的递归抽象聚类摘要树) 以及 LLM Wiki(结构化知识百科编译) 三大高阶索引能力,配合版本代际号(currentGeneration)、陈旧化原因追踪(staleReason)以及进程级双信号量模型容量保护(ModelCapacity),确保后台大规模索引构建永不抢占线上实时检索(/search)的推理与向量化配额。


功能概述与核心场景

在企业级知识中台(如项目 企业智能客服与知识中台,ID:enterprise-ai-hub-210)服务一线与二线工程师时,传统「定长切块 + Top-K 向量召回」在两类典型高难度查询上往往捉襟见肘:

Agentbase 高级知识索引构建治理 通过三大派生索引与严谨的作业调度机制彻底解决上述痛点:


核心概念与架构

三大高级派生索引构建流水线与 ModelCapacity 并发治理架构图

flowchart TB
    subgraph BaseChunks["底层就绪分块底座 (OceanBase Shared V2)"]
        ReadyDocs["kb_enterprise_support 已就绪分块 (status = ready)\n4 篇核心技术文档 + 1024 维 text-embedding-v3 向量"]
        BoundLex["已绑定项目词库 (Lexicons)\n• lex_enterprise_synonyms (同义词归一)\n• lex_support_stopwords (停用实体过滤)"]
    end

    subgraph ModelCap["进程级模型容量保护器 (ModelCapacity Dual-Semaphore)"]
        OnlinePrio["高优通道:线上实时检索 (/search)\nEmbedding & Rerank & Answer 优先放行"]
        BatchGate["受控通道:后台索引构建信号量\ngraphragEmbedBatchSize=32 / pageMaxConcurrent=4"]
    end

    subgraph GraphRAGPipeline["1. GraphRAG 知识图谱构建流水线"]
        Extract["实体与关系抽取 (qwen-plus)\n按 entityTypes 提取节点与有向关系边"]
        Disambig["跨文档/多语言消歧 + 词库增强 (lexiconEnabled=true)\n同义实体合并 (OB -> OceanBase) + 停用词剔除"]
        Leiden["Leiden 层次化社区发现算法\n划分紧密关联子图社区 (Level 0..N)"]
        CommReport["社区摘要报告生成与向量化\nqwen-plus 生成 findings/summary -> text-embedding-v3"]
    end

    subgraph RAPTORPipeline["2. RAPTOR 递归聚类摘要树流水线"]
        GMM["GMM 高斯混合模型软聚类 + BIC 最优簇选择\n支持 scope=knowledgeBase (全库) 或 document (单文档)"]
        ClusterSum["簇抽象摘要生成与递归向量化\nqwen-plus 归纳簇主题 -> text-embedding-v3 -> Level 1..maxLevels"]
    end

    subgraph WikiPipeline["3. LLM Wiki 百科编译流水线 (await_graphrag 依赖栅栏)"]
        Fence["依赖栅栏检查 (await_graphrag)\n等待同批次 GraphRAG 构建完成后启动"]
        Compile["多类型页面并发编译 (pageMaxConcurrent)\n生成 kb-index 与 9 篇专题章节页 + 冲突检测 (/wiki/conflicts)"]
    end

    ReadyDocs --> BatchGate
    BoundLex -->|实体归一化与过滤| Disambig
    BatchGate --> Extract --> Disambig --> Leiden --> CommReport
    BatchGate --> GMM --> ClusterSum
    CommReport -->|释放 await_graphrag 栅栏| Fence --> Compile

一、GraphRAG(知识图谱索引)深度原理与配置参数

GraphRAG 将非结构化文本转化为结构化的「实体(Entity)— 关系(Relation)— 社区报告(Community Report)」三层拓扑网络:

参数字段类型默认值 / 标杆值详细说明与调优建议
enabledbooleantrue是否为当前知识库启用 GraphRAG 知识图谱能力。
entityTypesstring[]["产品模块", "故障码", "API接口", "配置参数", "SOP步骤", "专家角色"]限定大模型重点识别的领域实体类别;聚焦的实体类别能显著降低无意义通用名词抽取出图率。
lexiconEnabledbooleantrue图谱词库增强开关:开启后在实体抽取阶段实时应用已绑定词库的 synonym 归一规则与 stop 过滤规则。
language / outputLanguagestring"zh-CN"可选 "zh-CN"、"en-US"、"auto"。控制实体综合描述与 Leiden 社区报告的生成语言。
graphragEmbedBatchSizeinteger32(范围 1~128)实体与社区摘要向量化时的单批 Embedding 分块数,配合 ModelCapacity 控制并发吞吐。
extractionPromptstring平台内置模板可选自定义实体关系抽取提示词,支持针对数据库排障或金融合规领域定制抽取粒度。

二、RAPTOR(递归抽象处理与树状聚类索引)深度原理与配置参数

RAPTOR(Recursive Abstractive Processing for Tree-Organized Retrieval)通过自底向上构建多层级语义摘要树,弥补平面分块缺乏跨段落宏观上下文的短板:

参数字段类型默认值 / 标杆值详细说明与选型建议
enabledbooleantrue是否为当前知识库启用 RAPTOR 递归聚类摘要树能力。
scopestring"knowledgeBase"聚类作用域:<br/>• "knowledgeBase":跨文档全局树,将全库所有文档的分块放在同一向量空间聚类,适合跨手册综合问答;<br/>• "document":单文档独立树,在每篇文档内部构建专属章节摘要树,适合超长白皮书或百页合同内部汇总。
maxLevelsinteger3(范围 1~5)递归聚类树的最大层高(不含 Level 0 叶节点)。企业中型知识库推荐设为 3。
clusterSizeinteger10(范围 3~50)单个语义簇容纳的目标子节点上限,影响每层 LLM 摘要的上下文聚合宽度。
summarizationPromptstring平台内置模板可选自定义簇摘要生成提示词,指导大模型保留关键参数、阈值与因果结论。

三、LLM Wiki 编译与 await_graphrag 依赖栅栏机制

当用户在 Indexes 页签同时启用 GraphRAG 与 LLM Wiki 并批量触发构建时,Agentbase 内置了 **await_graphrag 依赖栅栏(Dependency Barrier)**:


四、双轴状态机、陈旧原因(staleReason)与 ModelCapacity 容量治理

1. 索引能力双轴状态机与 currentGeneration

每项高级索引能力(graphrag / raptor / wiki)均由两个正交状态维度及单调递增的代际号 currentGeneration 描述:

2. 六类标准陈旧原因(staleReason)字典

陈旧原因枚举值 (staleReason)触发场景说明推荐修复动作 (operation + executionMode)
document_ingested知识库新增上传了文档或对存量文档执行了重新摄取(Re-ingest)operation: "build", executionMode: "incremental"
document_deleted从知识库中删除了某篇已参与构建的文档operation: "repair" 或 executionMode: "rebuild"
chunk_updated在文档详情页手工修改了某个分块(Chunk)的正文内容或删除了分块operation: "build", executionMode: "incremental"
data_source_sync语雀等外部数据源执行增量同步(/datasources/{id}/sync)产生了新增或变更文档operation: "build", executionMode: "incremental"
config_changed通过 PATCH /index-capabilities/{capability} 修改了 entityTypes、lexiconEnabled、scope 或提示词operation: "build", executionMode: "rebuild"
manual_rebuild管理员显式请求强制全量重建operation: "build", executionMode: "rebuild"

3. 进程级 ModelCapacity 双信号量并发保护

在生产环境中,GraphRAG 的实体抽取与 RAPTOR 的多层摘要会产生密集的 LLM(qwen-plus)与 Embedding(text-embedding-v3)调用。为防止后台构建任务打满上游模型 TPM/RPM 配额而导致前台客服问答(/search)超时,Agentbase 在 Worker 与 API 进程层实现了 **ModelCapacity 双信号量隔离机制**:


功能入口与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
知识库 → 知识索引总览页/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/indexesGET /v1/knowledgebases/{kbId}/index-capabilitiesknowledgeBase.listIndexCapabilities() / list_index_capabilities()角色:owner、admin、developer、member(只读)<br/>Scope:knowledgebases.read依赖知识库内至少存在 1 篇 status=ready 的文档
配置 GraphRAG / RAPTOR / Wiki 能力参数/console/.../kb-kb_enterprise_support/indexes(点击对应卡片「配置 Configure」)PATCH /v1/knowledgebases/{kbId}/index-capabilities/{capability}knowledgeBase.updateIndexCapability()角色:owner、admin、developer<br/>Scope:knowledgebases.write依赖 dashscope-prod 中已配置 qwen-plus 与 text-embedding-v3;开启 lexiconEnabled 依赖已绑定词库
派发增量构建、修复或全量重建作业/console/.../kb-kb_enterprise_support/indexes(点击「构建 Build」或「重建 Rebuild」)POST /v1/knowledgebases/{kbId}/index-operations<br/>GET /v1/knowledgebases/{kbId}/index-operationsknowledgeBase.createIndexOperation()<br/>knowledgeBase.listIndexOperations()角色:owner、admin、developer<br/>Scope:knowledgebases.write与版本管理(Versions)就绪门禁联动
取消正在运行的索引作业最近任务列表行操作「取消(Cancel)」POST /v1/knowledgebases/{kbId}/index-operations/{operationId}/cancelknowledgeBase.cancelIndexOperation()角色:owner、admin、developer<br/>Scope:knowledgebases.write仅对 queued 或 running 状态的作业生效
清空指定派生索引数据能力卡片更多菜单「清空索引数据(Clear)」POST /v1/knowledgebases/{kbId}/index-capabilities/{capability}/clearknowledgeBase.clearIndexCapability()角色:owner、admin<br/>Scope:knowledgebases.write请求体须显式传入 "confirm": true;仅清理派生索引,不删原始文档与基础分块

功能详解与操作指南

步骤 1:配置并启用 GraphRAG、RAPTOR 与 LLM Wiki 能力


步骤 2:派发异步构建作业(build / repair)并监控代际演进


步骤 3:通过 REST API 完整操控三大索引能力与作业生命周期

# 1. 查询知识库三大高级索引能力的当前状态、代际号与陈旧原因 (GET /index-capabilities)
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-capabilities" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 2. 配置并启用 GraphRAG 索引能力,开启词库增强与自定义实体类型 (PATCH /index-capabilities/graphrag)
curl -X PATCH "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-capabilities/graphrag" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "outputLanguage": "zh-CN",
    "config": {
      "entityTypes": ["产品模块", "故障码", "API接口", "配置参数", "SOP步骤", "专家角色"],
      "lexiconEnabled": true,
      "language": "zh-CN",
      "graphragEmbedBatchSize": 32
    }
  }'

# 3. 配置并启用 RAPTOR 递归聚类摘要树能力 (PATCH /index-capabilities/raptor)
curl -X PATCH "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-capabilities/raptor" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "outputLanguage": "zh-CN",
    "config": {
      "scope": "knowledgeBase",
      "maxLevels": 3,
      "clusterSize": 10
    }
  }'

# 4. 配置并启用 LLM Wiki 能力并开启 await_graphrag 栅栏 (PATCH /index-capabilities/wiki)
curl -X PATCH "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-capabilities/wiki" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "outputLanguage": "zh-CN",
    "config": {
      "wikiLanguage": "zh-CN",
      "pageMaxConcurrent": 4,
      "await_graphrag": true
    }
  }'

# 5. 触发带幂等键的增量或全量索引构建作业 (POST /index-operations)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-operations" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "graphrag",
    "operation": "build",
    "executionMode": "incremental",
    "idempotencyKey": "iop_graphrag_kb_support_20261022_01"
  }'

# 6. 取消正在排队或运行中的构建作业 (POST /index-operations/{operationId}/cancel)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-operations/iop_7c6b5a4d3e2f1098/cancel" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 7. 安全清空指定派生索引产物(需显式传入 confirm: true,不影响原始文档与分块)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/index-capabilities/raptor/clear" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true
  }'

常见问题与排障(FAQ)

Q1:为什么我已经新上传了文档且文档状态变成了 ready,但 GraphRAG 和 RAPTOR 卡片状态变成了黄色的 stale(陈旧)?此时线上检索会报错吗?

Q2:同时触发了 GraphRAG 和 LLM Wiki 构建,为什么 Wiki 任务一直停留在等待状态(await_graphrag)没有立即开始生成页面?

Q3:开启 GraphRAG 的 lexiconEnabled: true 后,修改了项目词库 lex_enterprise_synonyms 中的同义词词条,已生成的知识图谱会自动合并旧节点吗?

Q4:执行 POST .../index-capabilities/{capability}/clear 清空索引后,我上传的 4 篇源文档和基础向量分块会被删掉吗?


相关文档