Docs
文档目录

知识库 Wiki 与 GraphRAG(索引治理)

这是什么 / 何时用

2.7.0 起知识库在基础 RAG 之上提供三类增强索引能力(Knowledge Index):GraphRAG(实体图谱)、RAPTOR(摘要树)与 LLM Wiki(把知识库内容编译成可维护的 canonical Wiki 页面)。本页覆盖它们的管理面:

何时用:知识库内容需要沉淀为结构化、可治理的 Wiki(供人或 Agent 消费),或需要用 GraphRAG / RAPTOR 增强检索质量时。基础摄取与检索见知识库、文档与摄取、检索与溯源。

前置

使用骨架

  1. 能力配置:listIndexCapabilities 分别检查 available / configured / enabled / state(部署不可用与用户未启用是不同信号);updateIndexCapability 保存 graphrag / raptor / wiki 的完整配置。

  2. 构建:带稳定 idempotencyKey 调 createIndexOperation(build / repair),轮询 getIndexOperation 到终态;需要时用 cancelIndexOperation 请求取消。

  3. Wiki 页面:createWikiPage 建页([[slug]] 链接自动抽取,未解析目标保留为红链);读 getWikiPage / listWikiPages;乐观并发更新 updateWikiPage(携带当前 contentRevision);版本历史 listWikiPageRevisions / getWikiPageRevision,恢复 restoreWikiPage(历史版本生成新 revision,不改动历史)。

  4. 提案与冲突:listWikiProposals / acceptWikiProposal 处理编译器提案;listWikiConflicts / getWikiConflictProposal / resolveWikiConflict 处理冲突页。

  5. 查询:createWikiQuery(显式库列表,1–20 个)或 createWikiProjectSearch(调用方可见的全部库);getWikiOverview 拿项目级 Wiki 状态卡片。

  6. 图谱浏览:getWikiGraph 看 Wiki 页面链接图;GraphRAG 用 getGraph(文本 / 类型 / 社区过滤或 seed + hops 有界探索)、getGraphEntityNeighbors、listGraphCommunityReports。

  7. 维护:getWikiRecommendedLimits 取编译上限建议;createWikiPageMemoryExport 导出页面为 Memory 事实;clearIndexCapability 只清派生索引;resetWiki 删除整个 canonical Wiki。

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

每个卡片可切换语言页签(全页同步)。Web 客户端 SDK 无本页全部能力面,各卡均不设 Web 页签。

能力配置与构建(含取消)

先查 available / configured / enabled / state,再分别保存 graphrag(entityTypes、lexiconEnabled、graphragEmbedBatchSize、language)、raptor(scope: "knowledgeBase" | "document" 及 GMM+BIC 聚类参数 maxLevels、clusterDimension、bicThreshold、summaryTokenBudget)与 wiki(await_graphrag、pageMaxConcurrent、sources)配置,并触发 build / repair / cancel / clear 操作;轮询 operation 到终态。

import { Capability, Kind, Scope } from 'agentbase-node-sdk';

const caps = await kb.listIndexCapabilities({ knowledgeBaseId: base.$id });
// 逐项看 available / configured / enabled / state;部署不可用 ≠ 用户未启用
// 1. 配置 GraphRAG(实体类型白名单、启用词库对齐 lexiconEnabled、向量批大小 graphragEmbedBatchSize)
await kb.updateIndexCapability({
    knowledgeBaseId: 'kb_enterprise_support',
    capability: Capability.Graphrag,
    config: {
        enabled: true,
        language: 'zh',
        entityTypes: ['Product', 'Component', 'ErrorCode', 'Parameter', 'SOP'],
        lexiconEnabled: true,
        graphragEmbedBatchSize: 32,
    },
});
// 2. 配置 RAPTOR(支持 knowledgeBase 或 document 粒度,以及 GMM+BIC 层次聚类参数)
await kb.updateIndexCapability({
    knowledgeBaseId: 'kb_enterprise_support',
    capability: Capability.Raptor,
    config: {
        enabled: true,
        language: 'zh',
        scope: 'knowledgeBase',
        maxLevels: 3,
        clusterDimension: 16,
        bicThreshold: 0.15,
        summaryTokenBudget: 512,
    },
});
// 3. 配置 LLM Wiki(开启 await_graphrag 与编译并发度 pageMaxConcurrent)
await kb.updateIndexCapability({
    knowledgeBaseId: base.$id,
    capability: Capability.Wiki,
    config: {
        enabled: true,
        language: 'zh',
        await_graphrag: true,
        pageMaxConcurrent: 4,
        sources: ['rag', 'graphrag', 'memory'],
    },   // 完整替换;language: auto/zh/en/ja
});
// 4. 触发异步构建(build)或修复(repair),轮询进度或取消(cancel)
const op = await kb.createIndexOperation({
    knowledgeBaseId: base.$id,
    capability: Capability.Wiki,
    idempotencyKey: 'wiki-build-20260918-01',   // 稳定幂等键,重试复用
    kind: Kind.Build,                           // Kind.Build 或 Kind.Repair
    scope: Scope.Knowledgebase,
});
// 轮询终态 succeeded / failed / cancelled / cleared
const st = await kb.getIndexOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
await kb.cancelIndexOperation({ knowledgeBaseId: base.$id, operationId: '<operationId>' });   // 请求取消

Wiki 页面与版本恢复

页面写操作携带当前 contentRevision 做乐观并发;每次成功写入产生不可变 revision,恢复是把历史 revision 写成新 revision(历史不被改动)。

import { PageType, Status } from 'agentbase-node-sdk';

const page = await kb.createWikiPage({
    knowledgeBaseId: base.$id,
    slug: 'refund-policy',
    title: '退款政策',
    pageType: PageType.Topic,
    contentMd: '# 退款政策\n\n详见 [[order-lifecycle]]。',   // [[slug]] 链接自动抽取,未解析目标保留为红链
    status: Status.Published,
});
const cur = await kb.getWikiPage({ knowledgeBaseId: base.$id, slug: 'refund-policy' });
await kb.updateWikiPage({
    knowledgeBaseId: base.$id,
    slug: 'refund-policy',
    contentRevision: cur.contentRevision,   // 必须与当前版本一致
    page: { contentMd: '# 退款政策(v2)\n\n……' },          // 变更字段集;省略 links/aliases 则保留
    reason: '补充跨境订单条款',
});
const revs = await kb.listWikiPageRevisions({ knowledgeBaseId: base.$id, slug: 'refund-policy' });
const latest = await kb.getWikiPage({ knowledgeBaseId: base.$id, slug: 'refund-policy' });   // 更新后重读取最新 revision
await kb.restoreWikiPage({
    knowledgeBaseId: base.$id,
    slug: 'refund-policy',
    revisionId: '<revisionId>',
    contentRevision: latest.contentRevision,   // 恢复也需当前 contentRevision 栅栏
});
// 可选的破坏性操作:删除前重读页面以取得最新数值 revision。
const beforeDelete = await kb.getWikiPage({ knowledgeBaseId: base.$id, slug: 'refund-policy' });
await kb.deleteWikiPage({
    knowledgeBaseId: base.$id, slug: 'refund-policy',
    contentRevision: beforeDelete.contentRevision, confirmation: 'delete:refund-policy',
});

提案与冲突解决

编译器提案是不可变 revision,接受或解决前不会替换 canonical 内容;冲突页列出未解决项,逐项解决或提交手工合并文档。

// 提案:列出 → 接受(contentRevision 防止覆盖更新的人工编辑)
const proposals = await kb.listWikiProposals({ knowledgeBaseId: base.$id });
const cur = await kb.getWikiPage({ knowledgeBaseId: base.$id, slug: '<slug>' });   // CAS 用当前 revision
await kb.acceptWikiProposal({
    knowledgeBaseId: base.$id, proposalId: '<proposalId>', contentRevision: cur.contentRevision,
});
// 冲突:列出 → 看编译器提案 → 解决单项或提交手工合并
const conflicts = await kb.listWikiConflicts({ knowledgeBaseId: base.$id });
const proposal = await kb.getWikiConflictProposal({ knowledgeBaseId: base.$id, slug: '<slug>' });
await kb.resolveWikiConflict({
    knowledgeBaseId: base.$id,
    slug: '<slug>',
    contentRevision: cur.contentRevision,
    resolvedConflictId: '<conflictId>',              // 解决单个冲突项
    resolvedConflictOptionText: '<chosenOption>',
    // 或手工合并:contentMd: '<merged markdown>'
    // 解决提案的一部分时:proposalId + proposalMd(剩余内容),避免未解决部分被静默丢弃
});

Wiki 查询与项目搜索

createWikiQuery 显式指定 1–20 个库;createWikiProjectSearch 覆盖调用方在项目中可见的全部库;getWikiOverview 返回按权限过滤的项目级 Wiki 状态卡片(部署可用性、启用状态、索引状态、页数、冲突数分列)。

import { Mode } from 'agentbase-node-sdk';

const overview = await kb.getWikiOverview();   // 项目级状态卡片(无参数)
const hits = await kb.createWikiQuery({
    knowledgeBaseIds: [base.$id],   // 1–20 个显式库
    query: '退款流程是什么?',
    mode: Mode.Auto,                // auto / wiki_direct / wiki_retrieved / rag_first
    topK: 5,
});
// 项目级搜索(全部可见库;能力失败在 degradedKnowledgeBases 中显式列出):
const all = await kb.createWikiProjectSearch({ query: '退款流程是什么?', mode: Mode.Auto });

图谱浏览(Wiki 链接图与 GraphRAG)

getWikiGraph 返回 canonical 页面链接图(redLink=true 为红链);GraphRAG 三个方法浏览活跃 generation 的有界快照。

const wikiGraph = await kb.getWikiGraph({ knowledgeBaseId: base.$id });   // canonical 页面 + 已解析/未解析链接
// GraphRAG:文本/类型/社区过滤,或 seed + hops 有界探索;hasMore + nextCursor 翻页,truncated=true 为子集
const graph = await kb.getGraph({ knowledgeBaseId: base.$id, seed: '<entityId>', hops: 2, limit: 50 });
const neighbors = await kb.getGraphEntityNeighbors({ knowledgeBaseId: base.$id, entityId: '<entityId>', hops: 1 });
const reports = await kb.listGraphCommunityReports({ knowledgeBaseId: base.$id, limit: 20 });

维护(推荐上限 / 导出 Memory / clear 与 reset)

clearIndexCapability 只清派生索引(保留 canonical 页面 / 链接 / 版本 / 别名);resetWiki 删除整个 canonical Wiki——两者不是同一动作,确认值与幂等键都必填。

// 编译上限建议;enableLlmRefine=false 取纯确定性建议
const limits = await kb.getWikiRecommendedLimits({ knowledgeBaseId: base.$id, enableLlmRefine: false });
// 导出单页为 Memory 事实(项目需已激活 Memory,否则 503 memory_service_unavailable)
const exported = await kb.createWikiPageMemoryExport({
    knowledgeBaseId: base.$id, slug: 'refund-policy', agentId: '<agentId>',   // agentId 可选
});
// 只清 wiki 派生 projection(canonical 保留);确认值 clear:<capability>
await kb.clearIndexCapability({
    knowledgeBaseId: base.$id, capability: Capability.Wiki,
    confirmation: 'clear:wiki', idempotencyKey: 'clear-wiki-01',
});
// 删除整个 canonical Wiki(最破坏);确认值 reset:wiki
await kb.resetWiki({
    knowledgeBaseId: base.$id, confirmation: 'reset:wiki', idempotencyKey: 'reset-wiki-01',
});

示例指引