知识库 Wiki 与 GraphRAG(索引治理)
这是什么 / 何时用
2.7.0 起知识库在基础 RAG 之上提供三类增强索引能力(Knowledge Index):GraphRAG(实体图谱)、RAPTOR(摘要树)与 LLM Wiki(把知识库内容编译成可维护的 canonical Wiki 页面)。本页覆盖它们的管理面:
- 索引治理:能力配置(
index-capabilities)与异步构建操作(index-operations,含取消)。 - Wiki 内容:页面创建 / 读取 / 更新 / 删除、不可变版本与恢复、编译器提案接受、冲突解决、页面链接图、推荐上限、重置、导出到 Memory。
- GraphRAG 图浏览:活跃 generation 的图谱快照、实体邻居、社区报告。
- Wiki 检索:跨库 Wiki 查询与项目级 Wiki 搜索、项目 Wiki 概览。
何时用:知识库内容需要沉淀为结构化、可治理的 Wiki(供人或 Agent 消费),或需要用 GraphRAG / RAPTOR 增强检索质量时。基础摄取与检索见知识库、文档与摄取、检索与溯源。
前置
- 知识库已创建且有就绪文档(ingestion
ready);调用 LLM 的能力(GraphRAG / RAPTOR / Wiki)需先在知识库indexingDefaults里配置共享 Chat LLM。 - API Key scopes:
knowledgebases.read(读 / 检索)、knowledgebases.write(配置、构建、写 Wiki)。 - 导出 Wiki 页面到 Memory 要求当前项目已启用并激活 Memory(启用 Knowledge Bases 不会自动创建 Memory 项目)。
- SDK 面:增强索引管理面只同步到 Node / Python / Go / Java Server SDK 与 Console(Java / Python / Go 的 console 包同面);Web 客户端 SDK 没有任何 Wiki / GraphRAG / 索引治理方法。
使用骨架
- 能力配置:
listIndexCapabilities分别检查available/configured/enabled/state(部署不可用与用户未启用是不同信号);updateIndexCapability保存graphrag/raptor/wiki的完整配置。 - 构建:带稳定
idempotencyKey调createIndexOperation(build/repair),轮询getIndexOperation到终态;需要时用cancelIndexOperation请求取消。 - Wiki 页面:
createWikiPage建页([[slug]]链接自动抽取,未解析目标保留为红链);读getWikiPage/listWikiPages;乐观并发更新updateWikiPage(携带当前contentRevision);版本历史listWikiPageRevisions/getWikiPageRevision,恢复restoreWikiPage(历史版本生成新 revision,不改动历史)。 - 提案与冲突:
listWikiProposals/acceptWikiProposal处理编译器提案;listWikiConflicts/getWikiConflictProposal/resolveWikiConflict处理冲突页。 - 查询:
createWikiQuery(显式库列表,1–20 个)或createWikiProjectSearch(调用方可见的全部库);getWikiOverview拿项目级 Wiki 状态卡片。 - 图谱浏览:
getWikiGraph看 Wiki 页面链接图;GraphRAG 用getGraph(文本 / 类型 / 社区过滤或seed+hops有界探索)、getGraphEntityNeighbors、listGraphCommunityReports。 - 维护:
getWikiRecommendedLimits取编译上限建议;createWikiPageMemoryExport导出页面为 Memory 事实;clearIndexCapability只清派生索引;resetWiki删除整个 canonical Wiki。
关键参数与返回
- 能力标识
capability:graphrag/raptor/wiki;操作kind:build/repair;scope:knowledgebase/document(RAPTOR 配置为 document 级时,operation 也必须scope=document并传已有 active chunks 的documentIds,两侧 scope 必须匹配)。 - 能力配置
config:完整替换语义;config.language控制生成输出语言——auto(默认,按源内容检测)/zh/en/ja,显式值覆盖源语言检测。Wiki 的sources可配rag/graphrag/memory(RAPTOR 摘要自动增强rag,不是独立 source 值)。 - Wiki 页面:
pageType∈entity/topic/survey/agent_practice/category_index;status∈draft/published/conflict/archived;写操作一律携带contentRevision做乐观并发。 - Wiki 查询
mode:auto(默认)/wiki_direct/wiki_retrieved/rag_first;topK、useVector、vectorWeight、linkOptions(有界链接扩展)可选。 - 破坏型确认值:
clearIndexCapability用clear:<capability>,deleteWikiPage用delete:<slug>,resetWiki用reset:wiki——三者都配幂等键;clear与delete保留 canonical 内容 / revision,只有resetWiki删除 canonical Wiki。 recommended-limits返回max_entities/max_topics/max_surveys/rag_max_docs/rag_max_chunks_per_doc/evidence_max_chunks_to_embed等建议值与strategy/signals;enableLlmRefine=false取纯确定性建议。- 嵌入输入上限:LLM Gateway Provider 的
maxInputTokens会成为 Wiki projection 的有效 embedding 输入上限——索引器只截断 embedding 投影并按上限打包 batch,不修改 canonical Wiki 内容;null表示不限。 - 图谱浏览都是有界快照:
hasMore/nextCursor翻页,truncated=true表示只返回子集;hops只影响图探索,不改变 GraphRAG 检索算法。
错误与边界
- 启用部署不可用的能力返回
knowledge_index_capability_unavailable;禁用能力保留已有 generation 与历史。索引器临时不健康不会抹掉已存配置与活跃 generation。 contentRevision不匹配(更新 / 删除 / 恢复 / 接受提案 / 解决冲突)即乐观并发失败——重读页面再重试。- operation 是异步且要求幂等键:
force=true会先请求取消冲突中的活跃 operation 再排队;取消是 attempt-fenced(旧 worker 不能在新 attempt 接管后发布结果);轮询到succeeded/failed/cancelled/cleared终态,失败读 operation 的 error 后换新幂等键,不要循环重试同一个。 - 冲突解决:
resolveWikiConflict可解决单个冲突项(resolvedConflictId+resolvedConflictOptionText)或提交手工合并文档(contentMd);解决提案的一部分时必须传proposalId与剩余proposalMd,避免未解决部分被静默丢弃。 export-to-memory:Memory 服务未激活 / 初始化中 / 不可用时返回503 memory_service_unavailable;响应只标识导出的 Memory 记录,不暴露任何模型或 Provider 凭据。- 跨库查询 / 项目搜索不暴露不可见库;项目级 Wiki 搜索的能力故障在
degradedKnowledgeBases中显式列出。单库createSearch响应使用capabilities/degradedCapabilities表示增强检索状态;其allowDegraded服务端默认值为true,遇到可降级错误时会回退基础 RAG,需要失败即返回错误时显式传false(见检索与溯源)。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):Node / Python / Go / Java 均为全量管理面(能力配置、operation、Wiki 页面 / 版本 / 提案 / 冲突、图谱、查询);Python 为 snake_case 关键字参数,Go 为位置参数 + 服务方法
With*选项,Java 为位置参数 + 强类型模型返回。 - 客户端 SDK(client-sdk/web.md):Web 无任何 Wiki / GraphRAG / 索引治理方法,浏览器场景经服务端转调。
- Console SDK:Java / Python / Go 的 console 包与 Server 面同构;JS Console SDK 的 KnowledgeBases 不含这些管理面方法。
各语言调用示例
每个卡片可切换语言页签(全页同步)。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 到终态。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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>' }); // 请求取消import io.agentbase.enums.Capability;
import io.agentbase.enums.Kind;
import io.agentbase.enums.Scope;
import java.util.Map;
var caps = kb.listIndexCapabilities(base.getId());
// 逐项看 available / configured / enabled / state
kb.updateIndexCapability("kb_enterprise_support", Capability.GRAPHRAG,
Map.of("enabled", true, "language", "zh", "lexiconEnabled", true, "graphragEmbedBatchSize", 32,
"entityTypes", java.util.List.of("Product", "Component", "ErrorCode", "Parameter", "SOP")));
kb.updateIndexCapability("kb_enterprise_support", Capability.RAPTOR,
Map.of("enabled", true, "language", "zh", "scope", "knowledgeBase",
"maxLevels", 3, "clusterDimension", 16, "bicThreshold", 0.15, "summaryTokenBudget", 512));
kb.updateIndexCapability(base.getId(), Capability.WIKI,
Map.of("enabled", true, "language", "zh", "await_graphrag", true, "pageMaxConcurrent", 4,
"sources", java.util.List.of("rag", "graphrag"))); // 完整替换
var op = kb.createIndexOperation(base.getId(), Capability.WIKI, "wiki-build-20260918-01",
Kind.BUILD, Scope.KNOWLEDGEBASE, null, null, null, null); // documentIds / config / force / retryOf (Kind.REPAIR 时传 retryOf)
var st = kb.getIndexOperation(base.getId(), op.getId()); // 轮询终态
kb.cancelIndexOperation(base.getId(), "<operationId>"); // 请求取消from agentbase.enums.capability import Capability
from agentbase.enums.kind import Kind
from agentbase.enums.scope import Scope
caps = kb.list_index_capabilities(knowledge_base_id=base['$id'])
# 逐项看 available / configured / enabled / state
kb.update_index_capability(knowledge_base_id='kb_enterprise_support', capability=Capability.GRAPHRAG,
config={'enabled': True, 'language': 'zh', 'lexiconEnabled': True, 'graphragEmbedBatchSize': 32,
'entityTypes': ['Product', 'Component', 'ErrorCode', 'Parameter', 'SOP']})
kb.update_index_capability(knowledge_base_id='kb_enterprise_support', capability=Capability.RAPTOR,
config={'enabled': True, 'language': 'zh', 'scope': 'knowledgeBase',
'maxLevels': 3, 'clusterDimension': 16, 'bicThreshold': 0.15, 'summaryTokenBudget': 512})
kb.update_index_capability(knowledge_base_id=base['$id'], capability=Capability.WIKI,
config={'enabled': True, 'language': 'zh', 'await_graphrag': True, 'pageMaxConcurrent': 4,
'sources': ['rag', 'graphrag']}) # 完整替换
op = kb.create_index_operation(knowledge_base_id=base['$id'], capability=Capability.WIKI,
idempotency_key='wiki-build-20260918-01', kind=Kind.BUILD, scope=Scope.KNOWLEDGEBASE)
st = kb.get_index_operation(knowledge_base_id=base['$id'], operation_id=op['$id']) # 轮询终态
kb.cancel_index_operation(knowledge_base_id=base['$id'], operation_id='<operationId>') # 请求取消caps, err := kb.ListIndexCapabilities(base.Id)
// 逐项看 available / configured / enabled / state
_, err = kb.UpdateIndexCapability("kb_enterprise_support", "graphrag",
map[string]interface{}{"enabled": true, "language": "zh", "lexiconEnabled": true, "graphragEmbedBatchSize": 32,
"entityTypes": []string{"Product", "Component", "ErrorCode", "Parameter", "SOP"}})
_, err = kb.UpdateIndexCapability("kb_enterprise_support", "raptor",
map[string]interface{}{"enabled": true, "language": "zh", "scope": "knowledgeBase",
"maxLevels": 3, "clusterDimension": 16, "bicThreshold": 0.15, "summaryTokenBudget": 512})
_, err = kb.UpdateIndexCapability(base.Id, "wiki",
map[string]interface{}{"enabled": true, "language": "zh", "await_graphrag": true, "pageMaxConcurrent": 4,
"sources": []string{"rag", "graphrag"}}) // 完整替换
op, err := kb.CreateIndexOperation(base.Id, "wiki", "wiki-build-20260918-01",
kb.WithCreateIndexOperationKind("build"), kb.WithCreateIndexOperationScope("knowledgebase"))
st, err := kb.GetIndexOperation(base.Id, op.Id) // 轮询终态
_, err = kb.CancelIndexOperation(base.Id, "<operationId>") // 请求取消curl -sS "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/index-capabilities" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS -X PATCH "$APPBASE_ENDPOINT/knowledgebases/kb_enterprise_support/index-capabilities/graphrag" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"config":{"enabled":true,"language":"zh","entityTypes":["Product","Component","ErrorCode","Parameter","SOP"],"lexiconEnabled":true,"graphragEmbedBatchSize":32}}'
curl -sS -X PATCH "$APPBASE_ENDPOINT/knowledgebases/kb_enterprise_support/index-capabilities/raptor" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"config":{"enabled":true,"language":"zh","scope":"knowledgeBase","maxLevels":3,"clusterDimension":16,"bicThreshold":0.15,"summaryTokenBudget":512}}'
curl -sS -X PATCH "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/index-capabilities/wiki" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"config":{"enabled":true,"language":"zh","await_graphrag":true,"pageMaxConcurrent":4,"sources":["rag","graphrag"]}}'
# 构建/修复:POST .../index-operations {"capability":"wiki","kind":"build"|"repair","scope":"knowledgebase"|"document","idempotencyKey":"..."}
# 轮询:GET .../index-operations/{operationId};取消:POST .../index-operations/{operationId}/cancelWiki 页面与版本恢复
页面写操作携带当前 contentRevision 做乐观并发;每次成功写入产生不可变 revision,恢复是把历史 revision 写成新 revision(历史不被改动)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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',
});import io.agentbase.enums.PageType;
import io.agentbase.enums.Status;
import java.util.Map;
var page = kb.createWikiPage(base.getId(), "refund-policy", "退款政策",
PageType.TOPIC, "# 退款政策\n\n详见 [[order-lifecycle]]。", null,
Status.PUBLISHED, null, null, null, null); // summary / pinned / links / aliases / reason
var cur = kb.getWikiPage(base.getId(), "refund-policy");
kb.updateWikiPage(base.getId(), "refund-policy", cur.getContentRevision(),
Map.of("contentMd", "# 退款政策(v2)\n\n……"), // page:变更字段集
null, null, "补充跨境订单条款"); // links / aliases / reason
var revs = kb.listWikiPageRevisions(base.getId(), "refund-policy", 20L);
var latest = kb.getWikiPage(base.getId(), "refund-policy"); // 更新后重读取最新 revision
kb.restoreWikiPage(base.getId(), "refund-policy", "<revisionId>", latest.getContentRevision(), null, null);
kb.deleteWikiPage(base.getId(), "refund-policy", latest.getContentRevision(), "delete:refund-policy");from agentbase.enums.page_type import PageType
from agentbase.enums.status import Status
page = kb.create_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy', title='退款政策',
page_type=PageType.TOPIC, content_md='# 退款政策\n\n详见 [[order-lifecycle]]。',
status=Status.PUBLISHED)
cur = kb.get_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy')
kb.update_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy',
content_revision=cur['contentRevision'], # 必须与当前版本一致
page={'contentMd': '# 退款政策(v2)\n\n……'}, # 变更字段集;省略 links/aliases 则保留
reason='补充跨境订单条款')
revs = kb.list_wiki_page_revisions(knowledge_base_id=base['$id'], slug='refund-policy')
latest = kb.get_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy') # 更新后重读取最新 revision
kb.restore_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy',
revision_id='<revisionId>', content_revision=latest['contentRevision'])
kb.delete_wiki_page(knowledge_base_id=base['$id'], slug='refund-policy',
content_revision=latest['contentRevision'], confirmation='delete:refund-policy')page, err := kb.CreateWikiPage(base.Id, "refund-policy", "退款政策",
kb.WithCreateWikiPagePageType("topic"),
kb.WithCreateWikiPageContentMd("# 退款政策\n\n详见 [[order-lifecycle]]。"),
kb.WithCreateWikiPageStatus("published"))
cur, err := kb.GetWikiPage(base.Id, "refund-policy")
_, err = kb.UpdateWikiPage(base.Id, "refund-policy", cur.ContentRevision,
map[string]interface{}{"contentMd": "# 退款政策(v2)\n\n……"}, // page:变更字段集
kb.WithUpdateWikiPageReason("补充跨境订单条款"))
revs, err := kb.ListWikiPageRevisions(base.Id, "refund-policy")
latest, err := kb.GetWikiPage(base.Id, "refund-policy") // 更新后重读取最新 revision
_, err = kb.RestoreWikiPage(base.Id, "refund-policy", "<revisionId>", latest.ContentRevision)
_, err = kb.DeleteWikiPage(base.Id, "refund-policy", latest.ContentRevision, "delete:refund-policy")curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/wiki/pages" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"slug":"refund-policy","title":"退款政策","pageType":"topic","contentMd":"# 退款政策\n\n详见 [[order-lifecycle]]。","status":"published"}'
# 更新:PATCH .../wiki/pages/{slug} {"contentRevision":<n>,"page":{...},"reason":"..."}
# 版本:GET .../wiki/pages/{slug}/revisions;恢复:POST .../wiki/pages/{slug}/restore {"revisionId":"...","contentRevision":<n>}
# 删除:DELETE .../wiki/pages/{slug} {"contentRevision":<n>,"confirmation":"delete:<slug>"}提案与冲突解决
编译器提案是不可变 revision,接受或解决前不会替换 canonical 内容;冲突页列出未解决项,逐项解决或提交手工合并文档。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 提案:列出 → 接受(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(剩余内容),避免未解决部分被静默丢弃
});var proposals = kb.listWikiProposals(base.getId(), 20L);
var cur = kb.getWikiPage(base.getId(), "<slug>"); // CAS 用当前 revision
kb.acceptWikiProposal(base.getId(), "<proposalId>", cur.getContentRevision());
var conflicts = kb.listWikiConflicts(base.getId(), 20L, 0L);
var proposal = kb.getWikiConflictProposal(base.getId(), "<slug>");
// resolveWikiConflict(kbId, slug, contentRevision, contentMd, resolvedConflictId,
// resolvedConflictOptionText, proposalId, proposalMd, links, reason)
kb.resolveWikiConflict(base.getId(), "<slug>", cur.getContentRevision(),
null, "<conflictId>", "<chosenOption>", null, null, null, null);proposals = kb.list_wiki_proposals(knowledge_base_id=base['$id'])
cur = kb.get_wiki_page(knowledge_base_id=base['$id'], slug='<slug>') # CAS 用当前 revision
kb.accept_wiki_proposal(knowledge_base_id=base['$id'], proposal_id='<proposalId>',
content_revision=cur['contentRevision'])
conflicts = kb.list_wiki_conflicts(knowledge_base_id=base['$id'])
proposal = kb.get_wiki_conflict_proposal(knowledge_base_id=base['$id'], slug='<slug>')
kb.resolve_wiki_conflict(knowledge_base_id=base['$id'], slug='<slug>',
content_revision=cur['contentRevision'],
resolved_conflict_id='<conflictId>', # 解决单个冲突项
resolved_conflict_option_text='<chosenOption>')
# 或手工合并:content_md='<merged markdown>';解决提案一部分时加 proposal_id + proposal_mdproposals, err := kb.ListWikiProposals(base.Id)
cur, err := kb.GetWikiPage(base.Id, "<slug>") // CAS 用当前 revision
_, err = kb.AcceptWikiProposal(base.Id, "<proposalId>", cur.ContentRevision)
conflicts, err := kb.ListWikiConflicts(base.Id)
proposal, err := kb.GetWikiConflictProposal(base.Id, "<slug>")
_, err = kb.ResolveWikiConflict(base.Id, "<slug>", cur.ContentRevision,
kb.WithResolveWikiConflictResolvedConflictId("<conflictId>"),
kb.WithResolveWikiConflictResolvedConflictOptionText("<chosenOption>"))
// 手工合并:kb.WithResolveWikiConflictContentMd(...);部分提案:ProposalId + ProposalMdcurl -sS "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/wiki/proposals" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 接受:POST .../wiki/proposals/{proposalId}/accept {"contentRevision":<n>}
# 冲突列表:GET .../wiki/conflicts;提案:GET .../wiki/conflicts/{slug}/proposal
# 解决:POST .../wiki/conflicts/{slug}/resolve
# {"contentRevision":<n>,"resolvedConflictId":"...","resolvedConflictOptionText":"..."}
# 或 {"contentRevision":<n>,"contentMd":"<merged markdown>"}Wiki 查询与项目搜索
createWikiQuery 显式指定 1–20 个库;createWikiProjectSearch 覆盖调用方在项目中可见的全部库;getWikiOverview 返回按权限过滤的项目级 Wiki 状态卡片(部署可用性、启用状态、索引状态、页数、冲突数分列)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 });import io.agentbase.enums.Mode;
import java.util.List;
var overview = kb.getWikiOverview();
var hits = kb.createWikiQuery(List.of(base.getId()), "退款流程是什么?",
Mode.AUTO, 5L, null, null, null); // topK / useVector / vectorWeight / linkOptions
var all = kb.createWikiProjectSearch("退款流程是什么?", Mode.AUTO, null, null, null, null);from agentbase.enums.mode import Mode
overview = kb.get_wiki_overview() # 项目级状态卡片(无参数)
hits = kb.create_wiki_query(knowledge_base_ids=[base['$id']], # 1–20 个显式库
query='退款流程是什么?', mode=Mode.AUTO, top_k=5)
all_ = kb.create_wiki_project_search(query='退款流程是什么?', mode=Mode.AUTO)overview, err := kb.GetWikiOverview()
hits, err := kb.CreateWikiQuery([]string{base.Id}, "退款流程是什么?",
kb.WithCreateWikiQueryMode("auto"), kb.WithCreateWikiQueryTopK(5))
all, err := kb.CreateWikiProjectSearch("退款流程是什么?", kb.WithCreateWikiProjectSearchMode("auto"))curl -sS "$APPBASE_ENDPOINT/knowledgebases/wiki/overview" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/wiki/query" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"knowledgeBaseIds":["kb_product_docs"],"query":"退款流程是什么?","mode":"auto","topK":5}'
# 项目级搜索:POST /knowledgebases/wiki/search {"query":"...","mode":"auto"}图谱浏览(Wiki 链接图与 GraphRAG)
getWikiGraph 返回 canonical 页面链接图(redLink=true 为红链);GraphRAG 三个方法浏览活跃 generation 的有界快照。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 });var wikiGraph = kb.getWikiGraph(base.getId()); // canonical 页面 + 已解析/未解析链接
// getGraph(kbId, query, type, community, seed, hops, limit, cursor)
var graph = kb.getGraph(base.getId(), null, null, null, "<entityId>", 2L, 50L, null);
var neighbors = kb.getGraphEntityNeighbors(base.getId(), "<entityId>", 1L, null);
var reports = kb.listGraphCommunityReports(base.getId(), 20L, 0L);wiki_graph = kb.get_wiki_graph(knowledge_base_id=base['$id']) # canonical 页面 + 已解析/未解析链接
graph = kb.get_graph(knowledge_base_id=base['$id'], seed='<entityId>', hops=2, limit=50)
neighbors = kb.get_graph_entity_neighbors(knowledge_base_id=base['$id'], entity_id='<entityId>', hops=1)
reports = kb.list_graph_community_reports(knowledge_base_id=base['$id'], limit=20)wikiGraph, err := kb.GetWikiGraph(base.Id) // canonical 页面 + 已解析/未解析链接
graph, err := kb.GetGraph(base.Id, kb.WithGetGraphSeed("<entityId>"),
kb.WithGetGraphHops(2), kb.WithGetGraphLimit(50))
neighbors, err := kb.GetGraphEntityNeighbors(base.Id, "<entityId>", kb.WithGetGraphEntityNeighborsHops(1))
reports, err := kb.ListGraphCommunityReports(base.Id, kb.WithListGraphCommunityReportsLimit(20))curl -sS "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/wiki/graph" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# GraphRAG 快照(seed + hops 有界探索;跟随 nextCursor 翻页):
curl -sS --get "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/graph" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode 'seed=<entityId>' --data-urlencode 'hops=2' --data-urlencode 'limit=50'
# 邻居:GET .../graph/entities/{entityId}/neighbors;社区报告:GET .../graph/community-reports维护(推荐上限 / 导出 Memory / clear 与 reset)
clearIndexCapability 只清派生索引(保留 canonical 页面 / 链接 / 版本 / 别名);resetWiki 删除整个 canonical Wiki——两者不是同一动作,确认值与幂等键都必填。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 编译上限建议;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',
});var limits = kb.getWikiRecommendedLimits(base.getId(), false); // 纯确定性建议
var exported = kb.createWikiPageMemoryExport(base.getId(), "refund-policy", "<agentId>"); // agentId 可传 null
kb.clearIndexCapability(base.getId(), Capability.WIKI, "clear:wiki", "clear-wiki-01"); // 只清 projection
kb.resetWiki(base.getId(), "reset:wiki", "reset-wiki-01"); // 删除整个 canonical Wikilimits = kb.get_wiki_recommended_limits(knowledge_base_id=base['$id'], enable_llm_refine=False)
exported = kb.create_wiki_page_memory_export(knowledge_base_id=base['$id'],
slug='refund-policy', agent_id='<agentId>') # agent_id 可选;Memory 未激活返回 503
kb.clear_index_capability(knowledge_base_id=base['$id'], capability=Capability.WIKI,
confirmation='clear:wiki', idempotency_key='clear-wiki-01') # 只清 projection
kb.reset_wiki(knowledge_base_id=base['$id'],
confirmation='reset:wiki', idempotency_key='reset-wiki-01') # 删除整个 canonical Wikilimits, err := kb.GetWikiRecommendedLimits(base.Id, kb.WithGetWikiRecommendedLimitsEnableLlmRefine(false))
exported, err := kb.CreateWikiPageMemoryExport(base.Id, "refund-policy",
kb.WithCreateWikiPageMemoryExportAgentId("<agentId>")) // 可选;Memory 未激活返回 503
_, err = kb.ClearIndexCapability(base.Id, "wiki", "clear:wiki", "clear-wiki-01") // 只清 projection
_, err = kb.ResetWiki(base.Id, "reset:wiki", "reset-wiki-01") // 删除整个 canonical Wikicurl -sS --get "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/wiki/recommended-limits" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-urlencode 'enableLlmRefine=false'
# 导出:POST .../wiki/pages/{slug}/export-to-memory {"agentId":"..."}(Memory 未激活 503)
# 清 projection:POST .../index-capabilities/wiki/clear {"confirmation":"clear:wiki","idempotencyKey":"..."}
# 重置:POST .../wiki/reset {"confirmation":"reset:wiki","idempotencyKey":"..."}示例指引
- JavaScript(Node 端 Wiki / GraphRAG 调用全集):examples/javascript.md 的「Knowledge Wiki」小节。
- 各语言 SDK 初始化与功能面映射:server-sdk/nodejs.md、server-sdk/java.md、server-sdk/python.md、server-sdk/go.md。
事实源
skills/ob-agentbase/references/knowledge-bases.md(Knowledge Index / Wiki 管理面、确认值、maxInputTokens 口径)skills/ob-agentbase/references/release-2.7.0.md(Knowledge Index 为 2.7.0 能力增量;Web SDK 无 Wiki 方法)- agentbase-sdks v2.8.0(tag
v2.8.0):specs/open-api3-latest-server.json(/knowledgebases/wiki/*、/knowledgebases/{id}/wiki/*、/knowledgebases/{id}/graph*、/knowledgebases/{id}/index-*端点与枚举);packages/sdks/server-nodejs/src/services/knowledge-bases.ts、server-python/agentbase/services/knowledge_bases.py、server-go/knowledgebases/、server-java/src/main/java/io/agentbase/services/KnowledgeBases.java方法签名