agentbase-docs

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

这是什么 / 何时用

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

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

前置

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

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

先查 available / configured / enabled / state,再保存配置并触发构建;轮询 operation 到终态,需要时取消。

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

const caps = await kb.listIndexCapabilities({ knowledgeBaseId: base.$id });
// 逐项看 available / configured / enabled / state;部署不可用 ≠ 用户未启用
await kb.updateIndexCapability({
    knowledgeBaseId: base.$id,
    capability: Capability.Wiki,
    config: { enabled: true, language: 'zh', sources: ['rag', 'graphrag'] },   // 完整替换;language: auto/zh/en/ja
});
const op = await kb.createIndexOperation({
    knowledgeBaseId: base.$id,
    capability: Capability.Wiki,
    idempotencyKey: 'wiki-build-20260918-01',   // 稳定幂等键,重试复用
    kind: Kind.Build,
    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 栅栏
});
// 删除(确认值 delete:<slug>,canonical 删除,revision 审计保留):
await kb.deleteWikiPage({
    knowledgeBaseId: base.$id, slug: 'refund-policy',
    contentRevision: '<currentRevision>', 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',
});

示例指引

事实源