AgentbaseDocs
文档目录

知识库 Wiki 与索引治理 API

知识库增强索引的管理与数据面:LLM Wiki(canonical 页面 / 不可变版本 / 编译冲突与提案 / 页面链接图谱 / 导出到 Memory / 重置)、GraphRAG 图谱浏览(node-link 图 / 社区报告 / 实体邻域),以及可插拔索引能力(graphrag / raptor / wiki)的配置、构建/修复操作与清理。

服务与资源边界

知识库 Wiki 与索引治理 API(/v1/knowledgebases/...)承载知识库(如展示项目中的 kb_enterprise_support)之上的高阶结构化知识衍生层:

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:knowledgebases.read(overview/query/search、图谱浏览、能力与操作读取、Wiki 页面/版本/冲突/提案读取、recommended-limits)、knowledgebases.write(能力配置与清理、操作创建与取消、Wiki 页面写/删/恢复/导出、冲突解决、提案接受、reset)。Wiki/GraphRAG 构建与检索经 LLM Gateway 执行;export-to-memory 另要求当前项目已启用并激活 AppBase Memory(见 memory)。

端点总览

本模块共包含 28 个端点,分为四组:项目级跨库 Wiki 概览与检索(3 个)、库级 GraphRAG 节点边图谱与社区报告浏览(3 个)、索引能力配置与异步构建/修复/清理操作管理(6 个)、以及库级 Wiki 页面、历史修订、冲突解决、提案采纳与图谱管理(16 个)。

端点清单

方法 + 路径用途
GET /knowledgebases/wiki/overview项目级 Wiki 状态卡片(按权限过滤)
POST /knowledgebases/wiki/query跨显式选定知识库查询 Wiki 索引
POST /knowledgebases/wiki/search跨全部可见知识库检索 Wiki 索引
GET /knowledgebases/{knowledgeBaseId}/graph浏览活跃 GraphRAG node-link 图
GET .../graph/community-reports活跃 GraphRAG 社区报告列表
GET .../graph/entities/{entityId}/neighbors展开实体邻域
GET /knowledgebases/{knowledgeBaseId}/index-capabilities列出索引能力与状态
PATCH .../index-capabilities/{capability}配置一个索引能力
POST .../index-capabilities/{capability}/clear排队清理能力的派生索引
`GET\POST /knowledgebases/{knowledgeBaseId}/index-operations`索引操作列表/发起构建或修复
GET .../index-operations/{operationId}索引操作详情
POST .../index-operations/{operationId}/cancel请求取消索引操作
GET /knowledgebases/{knowledgeBaseId}/wiki/pagesWiki 页面列表
POST .../wiki/pages创建人工持有的 Wiki 页面
`GET\PATCH\DELETE .../wiki/pages/{slug}(兼容标识:.../wiki/pages/{pageId}`)Wiki 页面读/CAS 更新/删除
GET .../wiki/pages/{slug}/revisions页面版本列表
GET .../wiki/pages/{slug}/revisions/{revisionId}单个版本详情
POST .../wiki/pages/{slug}/restore恢复历史版本(新 CAS 版本)
POST .../wiki/pages/{slug}/export-to-memory导出页面到 Memory 服务
GET .../wiki/conflicts未解决编译冲突页面列表
GET .../wiki/conflicts/{slug}/proposal冲突页最新编译提案
POST .../wiki/conflicts/{slug}/resolve(兼容:POST /v1/knowledgebases/{kbId}/wiki/conflicts)解决冲突(CAS)
GET .../wiki/proposals冲突页最新编译提案列表
POST .../wiki/proposals/{proposalId}/accept(兼容:POST /v1/knowledgebases/{kbId}/wiki/proposals)接受整条编译提案(CAS)
GET .../wiki/graphcanonical Wiki 页面链接图谱(含红链)
GET .../wiki/recommended-limits推荐 Wiki 编译上限
POST .../wiki/reset(动作路由别名:POST /v1/knowledgebases/{kbId}/reset:wiki)删除整个 canonical Wiki 并排队清理编译索引

端点详解

请求与响应

以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:

公共响应模型

以下模型在多个端点复用,此处给出完整字段表;各端点「输出」只列关键字段并指回本节。

**Models.KnowledgeBaseWikiPage**(Wiki 页面):

字段类型说明
$id*stringWiki 页面 ID。
$createdAt* / $updatedAt*string创建/最近更新时间(ISO 8601)。
knowledgeBaseId*string所属知识库 ID。
slug*string库内唯一 Wiki slug。
title*string页面标题。
pageType*string页面类型:entity / topic / survey / agent_practice / category_index。
contentMd*stringcanonical Markdown 内容。
summarystring页面摘要。
status*string页面状态:draft / published / conflict / archived。
pendingConflicts*object结构化的未解决冲突元数据。
conflicts*object[]面向调用方的冲突明细(见下方 KnowledgeBaseWikiConflict)。
sourceChunks* / sourceGraph* / sourceMemory*objectchunk / 图谱 / Memory 三类来源溯源。
compiledBystring编译器标识;人工持有页面为 null。
pinned*boolean是否人工置顶。
viewCount*integer页面浏览计数。
contentRevision*integer写操作要求的 CAS 版本号。
embeddingModelstring当前投影使用的模型。
projectionResultGenerationstring包含该页面版本的派生结果代。
embeddingUpdatedAtstring投影发布时间。
links*object出链,含未解析的红链。
backlinks*object其他 Wiki 页面的入链。
aliases*object指向本页的别名。
conflictEvidence*object冲突内容引用的水合证据。
divergenceRecommendations*object分歧内容选项的推荐。
conflictBlocks*object供渲染的冲突块。
internalContradictions* / ruleBasedContradictions*object规则检测的矛盾。
generalKnowledgeConflicts*object与通用知识的冲突。

**Models.KnowledgeBaseWikiConflict**(conflicts[] 元素):

字段类型说明
id*string稳定的冲突 ID。
type*string冲突检测器分类。
reason*string冲突的人读原因。
claimstring被评估的论断(如有)。
conflictingContents*string[]互相竞争的原句。
sources*object[]竞争语句归属的源文档/切片(见下)。
readOnly*boolean该冲突是否必须手工合并内容。
confidencenumber检测器置信度(如有)。
scopestring冲突范围(如有)。
recommendedOptionIndexinteger推荐选项下标;无安全推荐时为 null。

**KnowledgeBaseWikiConflictSource**(sources[] 元素):documentId(源文档 ID)、documentName(展示名)、documentTag(调用方自定义定位标签,来自 metadata.documentTag)、chunkId、conflictingContent(归属该源的冲突原句)、context(有界上下文摘录)、locator(object,页/节等位置元数据)。

**Models.KnowledgeBaseWikiRevision**(不可变版本/提案):

字段类型说明
$id*string版本 ID。
$createdAt*string版本创建时间。
knowledgeBaseId*string知识库 ID。
pageId*stringWiki 页面 ID。
pageSlug / pageTitlestring页面 slug / 标题(提案列表返回时携带)。
actorIdstring创建该版本的主体。
revisionType*string版本类型。
titleBefore / titleAfterstring前/后标题。
contentBefore / contentAfterstring前/后 Markdown。
reasonstring版本原因。

**Models.KnowledgeBaseIndexOperation**(索引操作):

字段类型说明
$id*string操作 ID。
$createdAt* / $updatedAt*string创建/最近更新时间。
knowledgeBaseId*string知识库 ID。
capability*string能力标识:graphrag / raptor / wiki。
kind*string操作种类(如 build / repair)。
scope*string操作范围(knowledgebase / document)。
documentIds*string[]document 范围操作的文档 ID。
status*string生命周期状态:queued / running / succeeded / failed / cancelling / cancelled / clearing / cleared。
stagestring当前处理阶段。
progress*integer完成百分比。
messagestring当前脱敏状态消息。
effectiveConfig*object冻结的生效配置。
configHash* / sourceHash*string生效配置 / 冻结源快照哈希。
resultGenerationstring暂存结果代。
resultVersionstring索引器实现版本。
retryOfstring本操作为重试时的原操作 ID。
stats*object操作统计。
error*object脱敏操作错误。
logTailstring有界脱敏日志尾部。
startedAt / heartbeatAt / finishedAtstring处理开始 / 最近 worker 心跳 / 终态完成时间。

**Models.KnowledgeBaseIndexCapability**(索引能力状态):capability*(string)、available*(boolean,部署是否提供该能力)、configured*(boolean,是否已保存配置)、enabled*(boolean)、state*(string,当前状态)、activeResultGeneration(string,活跃不可变结果代)、sourceHash / configHash(string)、resultVersion(string)、lastOperationId(string)、staleReason(string,可空,结果代过期原因)、stats*(object)、error*(object,脱敏最近错误)、config*(object,已保存配置)、limits*(object,服务端强制上限)。

**Models.KnowledgeBaseWikiMutation**(删除/重置结果):pagesDeleted*、linksDeleted*、linksNulled*(入链转红链数)、revisionsDeleted*、aliasesDeleted*(均为 integer)、clearOperationId(string,排队中的 Wiki 索引清理操作,如适用)。

项目级 Wiki 概览与检索

GET /v1/knowledgebases/wiki/overview

SDK:KnowledgeBases.getWikiOverview · scope:knowledgebases.read

返回当前项目按权限过滤的 Wiki 状态卡片:只汇总可见知识库,并把部署可用性、已保存的启用状态、索引状态、页面计数与冲突计数区分开。

输入:无 path/query/body 参数。

输出:

200,返回模型 Models.KnowledgeBaseWikiOverview。

字段类型说明
cards*object按权限过滤的逐知识库 Wiki 状态卡片(泛化对象,卡片字段以实际返回为准)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/wiki/overview" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(cards 为泛化对象,示意——字段以实际返回为准):

{
  "cards": []
}

POST /v1/knowledgebases/wiki/query

SDK:KnowledgeBases.createWikiQuery · scope:knowledgebases.read

跨显式选定的可见知识库查询 Wiki 索引:可指定路由档位(mode)或留 auto,并用 linkOptions 做有界链接扩展。不可访问的知识库不会暴露;能力故障在 degradedKnowledgeBases 中报告。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdsbodystring[]是1–20 个要查询的知识库 ID。
querybodystring是Wiki 查询文本。
modebodystring否枚举:auto / wiki_direct / wiki_retrieved / rag_firstWiki 路由档位覆盖。
topKbodyinteger否每个知识库返回的结果数。
useVectorbodyboolean否是否包含向量召回。
vectorWeightbodynumber否RRF 前的向量权重。
linkOptionsbodyobject否有界 Wiki 链接扩展选项(泛化对象)。

输出:

200,返回模型 Models.KnowledgeBaseWikiProjectSearch。

字段类型说明
results*object按知识库分组、按权限过滤的 Wiki 结果(泛化对象,结果字段以实际返回为准)。
degradedKnowledgeBases*objectWiki 不可用或未就绪的可见知识库(泛化对象)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/wiki/query" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseIds": ["kb_product_docs"],
    "query": "退款政策是什么?",
    "mode": "auto",
    "topK": 5,
    "useVector": true,
    "vectorWeight": 0.7
  }'

响应示例(results / degradedKnowledgeBases 为泛化对象,示意——字段以实际返回为准):

{
  "results": [],
  "degradedKnowledgeBases": []
}

POST /v1/knowledgebases/wiki/search

SDK:KnowledgeBases.createWikiProjectSearch · scope:knowledgebases.read

跨项目内全部可见知识库检索 Wiki 索引:返回排序且按版本围栏(revision-fenced)的结果与显式的降级知识库。需要显式选择知识库时改用 createWikiQuery。

输入:

参数位置类型必填默认/枚举说明
querybodystring是Wiki 查询文本。
modebodystring否枚举:auto / wiki_direct / wiki_retrieved / rag_firstWiki 路由档位覆盖。
topKbodyinteger否每个知识库返回的结果数。
useVectorbodyboolean否是否包含向量召回。
vectorWeightbodynumber否RRF 前的向量权重。
linkOptionsbodyobject否有界 Wiki 链接扩展选项(泛化对象)。

输出:

200,返回模型 Models.KnowledgeBaseWikiProjectSearch(字段同上:results*、degradedKnowledgeBases*)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/wiki/search" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "退款政策是什么?",
    "mode": "auto",
    "topK": 5
  }'

响应示例(泛化对象,示意——字段以实际返回为准):

{
  "results": [],
  "degradedKnowledgeBases": []
}

GraphRAG 图谱

GET /v1/knowledgebases/{knowledgeBaseId}/graph

SDK:KnowledgeBases.getGraph · scope:knowledgebases.read

浏览活跃 GraphRAG 结果代的有界快照:可按文本/类型/社区过滤实体,或给 seed + hops 做有界图探索。hasMore=true 时跟随 nextCursor 翻页;truncated=true 表示响应只是图的有界子集。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
queryquerystring否默认 ""实体文本过滤。
typequerystring否默认 ""实体类型过滤。
communityquerystring否默认 ""社区过滤。
seedquerystring否默认 ""有界 N 跳扩展的实体种子。
hopsqueryinteger否默认 1带 seed 时的邻域跳数。
limitqueryinteger否默认 100最大返回节点数。
cursorquerystring否默认 ""上一页返回的不透明游标。

输出:

200,返回模型 Models.KnowledgeBaseGraph。

字段类型说明
resultGeneration*string活跃 GraphRAG 结果代。
graph*object过滤后的 node-link 图快照({nodes, edges} 结构,字段以实际返回为准)。
totalNodes*integer匹配当前过滤条件的节点总数。
hasMore*boolean是否还有下一页。
nextCursorstring下一页的不透明游标。
truncated*boolean返回图是否为有界子集。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph?query=退款&limit=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "resultGeneration": "gen_0007",
  "graph": {
    "nodes": [
      {
        "id": "ent_ob_paxos",
        "name": "OceanBase Paxos 日志同步",
        "type": "Component",
        "communityId": "comm_ha_01",
        "degree": 9,
        "description": "OceanBase 多副本多数派强一致日志复制协议核心模块"
      },
      {
        "id": "ent_clog_disk_full",
        "name": "CLOG 盘满告警 (ERROR 4016)",
        "type": "ErrorCode",
        "communityId": "comm_ha_01",
        "degree": 6,
        "description": "日志盘使用率达到 log_disk_utilization_limit_threshold 触发写停止"
      }
    ],
    "edges": [
      {
        "source": "ent_clog_disk_full",
        "target": "ent_ob_paxos",
        "relation": "BLOCKS_REPLICATION",
        "weight": 0.94,
        "evidenceChunkIds": ["chk_0042"]
      }
    ]
  },
  "totalNodes": 2,
  "hasMore": false,
  "nextCursor": "",
  "truncated": false
}

GET /v1/knowledgebases/{knowledgeBaseId}/graph/community-reports

SDK:KnowledgeBases.listGraphCommunityReports · scope:knowledgebases.read

列出活跃 GraphRAG 结果代的社区报告:每份含社区标识、标题、实体、权重与报告载荷。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
limitqueryinteger否默认 100最大返回报告数。
offsetqueryinteger否默认 0跳过的报告数。

输出:

200,返回模型 Models.KnowledgeBaseGraphCommunityReportList。

字段类型说明
resultGeneration*string活跃 GraphRAG 结果代。
reports*object[]社区报告列表(元素为 Models.KnowledgeBaseGraphCommunityReport,子字段见下)。
id*string社区报告记录 ID。
communityId*string社区标识。
title*string报告标题。
entities*string[]报告覆盖的实体。
weight*number报告权重。
content*object结构化报告内容与证据(泛化对象)。
hasMore*boolean是否还有更多报告。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph/community-reports?limit=100&offset=0" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "resultGeneration": "gen_0007",
  "reports": [
    {
      "id": "cr_0001",
      "communityId": "community_3",
      "title": "退款与售后",
      "entities": ["ent_0123"],
      "weight": 0.82,
      "content": {}
    }
  ],
  "hasMore": false
}

GET /v1/knowledgebases/{knowledgeBaseId}/graph/entities/{entityId}/neighbors

SDK:KnowledgeBases.getGraphEntityNeighbors · scope:knowledgebases.read

在活跃 GraphRAG 结果代中展开单个实体的有界邻域。hops 只作用于图探索,不改变 GraphRAG 检索算法。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
entityIdpathstring是图实体 ID。
hopsqueryinteger否默认 1邻域跳数。
limitqueryinteger否默认 100最大返回节点数。

输出:

200,返回模型 Models.KnowledgeBaseGraphNeighbors。

字段类型说明
resultGeneration*string活跃 GraphRAG 结果代。
nodes*object从种子到达的节点(泛化对象)。
edges*object由到达节点诱导的边(泛化对象)。
truncated*boolean扩展是否触达请求上限。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/graph/entities/ent_0123/neighbors?hops=1&limit=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(nodes / edges 为泛化对象,示意——字段以实际返回为准):

{
  "resultGeneration": "gen_0007",
  "nodes": [
    {
      "id": "ent_0123",
      "name": "OceanBase 向量索引 (HNSW)",
      "type": "Component",
      "communityId": "comm_vec_02"
    },
    {
      "id": "ent_ob_mem",
      "name": "ob_vector_memory_limit_percentage",
      "type": "Parameter",
      "communityId": "comm_vec_02"
    }
  ],
  "edges": [
    {
      "source": "ent_0123",
      "target": "ent_ob_mem",
      "relation": "DEPENDS_ON_PARAMETER",
      "weight": 0.91
    }
  ],
  "truncated": false
}

索引能力(index-capabilities)

GET /v1/knowledgebases/{knowledgeBaseId}/index-capabilities

SDK:KnowledgeBases.listIndexCapabilities · scope:knowledgebases.read

列出 GraphRAG、RAPTOR 与 LLM Wiki 三个可插拔索引能力的部署可用性、已保存配置、生命周期状态、活跃结果代、上限、统计与脱敏错误。available、enabled、state 是三个独立信号:索引器临时不健康不会抹掉已保存配置或活跃结果代。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。

输出:

200,返回模型 Models.KnowledgeBaseIndexCapabilityList。

字段类型说明
capabilities*object[]能力列表,元素为 Models.KnowledgeBaseIndexCapability(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-capabilities" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "capabilities": [
    {
      "capability": "wiki",
      "available": true,
      "configured": true,
      "enabled": true,
      "state": "ready",
      "activeResultGeneration": "gen_0007",
      "sourceHash": "sha256:…",
      "configHash": "sha256:…",
      "resultVersion": "1.0.0",
      "lastOperationId": "op_0001",
      "staleReason": null,
      "stats": {},
      "error": {},
      "config": {
        "enabled": true
      },
      "limits": {}
    }
  ]
}

PATCH /v1/knowledgebases/{knowledgeBaseId}/index-capabilities/{capability}

SDK:KnowledgeBases.updateIndexCapability · scope:knowledgebases.write

整体替换一个 graphrag / raptor / wiki 能力的已保存配置。对会调用 Chat LLM 的能力,先配置知识库的 indexingDefaults。启用部署不可用的能力返回 knowledge_index_capability_unavailable;禁用会保留既有结果代与历史。

三个能力都接受 config.language 控制生成语言:auto(默认,按源内容检测)/ zh / en / ja;显式值覆盖源语言检测。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID(如 kb_enterprise_support)。
capabilitypathstring是枚举:graphrag / raptor / wiki索引能力标识。
configbodyobject是完整能力配置对象(按 capability 区分具体子字段,见下表)。
config.enabledbodyboolean是true / false是否启用当前索引能力。
config.languagebodystring否枚举:auto / zh / en / ja(默认 auto)实体抽取、聚类摘要与 Wiki 页面生成的目标语言。
config.entityTypes(graphrag)bodystring[]否如 ["Product","Component","ErrorCode","Parameter","SOP"]GraphRAG 允许抽取的本体实体类型白名单。
config.lexiconEnabled(graphrag)bodyboolean否默认 true是否在 GraphRAG 实体抽取与消歧阶段联动知识库已绑定的项目词库(如 lex_enterprise_synonyms)做标准名对齐。
config.graphragEmbedBatchSize(graphrag)bodyinteger否默认 32,范围 1–128GraphRAG 实体与关系描述向量化批大小。
config.maxGleaningRounds(graphrag)bodyinteger否默认 1,范围 0–3实体遗漏补抽(Gleaning)迭代轮数。
config.communityLevel(graphrag)bodyinteger否默认 2,范围 1–4Leiden 社区层次聚类深度。
config.scope(raptor)bodystring否枚举:"knowledgeBase" / "document"RAPTOR 层次聚类树构建范围:"knowledgeBase"(跨全库文档构建统一语义树)或 "document"(单文档独立构建语义树)。
config.maxLevels(raptor)bodyinteger否默认 3,范围 1–5RAPTOR 树最大递归聚类层数。
config.clusterDimension(raptor)bodyinteger否默认 16,范围 2–64UMAP 降维后用于高斯混合模型(GMM)聚类的目标维度。
config.bicThreshold(raptor)bodynumber否默认 0.15,范围 0.01–1.0贝叶斯信息准则(BIC)最优簇数量收敛阈值。
config.summaryTokenBudget(raptor)bodyinteger否默认 512,范围 128–2048每个父节点聚类摘要生成的最大 Token 预算。
config.await_graphrag(wiki)bodyboolean否默认 true编译 LLM Wiki 前是否等待活跃 GraphRAG 索引构建完成并引用其社区与实体结构。
config.pageMaxConcurrent(wiki)bodyinteger否默认 4,范围 1–16Wiki 页面并行编译的最大并发度。
config.sources(wiki)bodystring[]否枚举组合:["rag","graphrag","memory"]Wiki 编译输入源。

输出:

200,返回模型 Models.KnowledgeBaseIndexCapability(字段见「公共响应模型」)。

**调用示例(分别配置 graphrag、raptor 与 wiki 三大能力)**:

# 1. 配置 GraphRAG 能力(指定实体类型、开启词库标准词对齐与向量批大小)
curl -X PATCH "https://appbuild-sit.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 '{
    "config": {
      "enabled": true,
      "language": "zh",
      "entityTypes": ["Product", "Component", "ErrorCode", "Parameter", "SOP"],
      "lexiconEnabled": true,
      "graphragEmbedBatchSize": 32,
      "maxGleaningRounds": 1,
      "communityLevel": 2
    }
  }'

# 2. 配置 RAPTOR 层次聚类摘要能力(GMM + BIC 聚类参数,支持 knowledgeBase 或 document 粒度)
curl -X PATCH "https://appbuild-sit.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 '{
    "config": {
      "enabled": true,
      "language": "zh",
      "scope": "knowledgeBase",
      "maxLevels": 3,
      "clusterDimension": 16,
      "bicThreshold": 0.15,
      "summaryTokenBudget": 512
    }
  }'

# 3. 配置 LLM Wiki 编译能力(开启 await_graphrag 与并发控制)
curl -X PATCH "https://appbuild-sit.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 '{
    "config": {
      "enabled": true,
      "language": "zh",
      "await_graphrag": true,
      "pageMaxConcurrent": 4,
      "sources": ["rag", "graphrag", "memory"]
    }
  }'

响应示例:

{
  "capability": "wiki",
  "available": true,
  "configured": true,
  "enabled": true,
  "state": "ready",
  "activeResultGeneration": "gen_0007",
  "sourceHash": "sha256:…",
  "configHash": "sha256:…",
  "resultVersion": "1.0.0",
  "lastOperationId": "op_0001",
  "staleReason": null,
  "stats": {},
  "error": {},
  "config": {
    "enabled": true,
    "language": "auto"
  },
  "limits": {}
}

POST /v1/knowledgebases/{knowledgeBaseId}/index-capabilities/{capability}/clear

SDK:KnowledgeBases.clearIndexCapability · scope:knowledgebases.write

排队清理一个能力的派生索引。confirmation 必须是 clear:<capability>;idempotencyKey 使重试安全。源文档、切片、其他能力与 canonical Wiki 页面/版本都被保留——删除 canonical Wiki 内容要用 resetWiki。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
capabilitypathstring是枚举:graphrag / raptor / wiki能力标识。
confirmationbodystring是形如 clear:<capability>显式确认。
idempotencyKeybodystring是去重重试的稳定键。

输出:

202,返回模型 Models.KnowledgeBaseIndexOperation(清理操作,字段见「公共响应模型」);轮询 GET index-operations/{operationId} 至终态。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-capabilities/wiki/clear" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation": "clear:wiki",
    "idempotencyKey": "clear-wiki-20260918-0001"
  }'

响应示例:

{
  "$id": "op_0002",
  "$createdAt": "2026-09-18T03:00:00.000+00:00",
  "$updatedAt": "2026-09-18T03:00:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "capability": "wiki",
  "kind": "build",
  "scope": "knowledgebase",
  "documentIds": [],
  "status": "queued",
  "stage": "",
  "progress": 0,
  "message": "",
  "effectiveConfig": {},
  "configHash": "sha256:…",
  "sourceHash": "sha256:…",
  "stats": {},
  "error": {}
}

索引操作(index-operations)

GET /v1/knowledgebases/{knowledgeBaseId}/index-operations

SDK:KnowledgeBases.listIndexOperations · scope:knowledgebases.read

列出知识库的索引操作:可按能力与生命周期状态过滤并分页。能力被禁用或不可用时操作历史仍可见。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
capabilityquerystring否枚举:graphrag / raptor / wiki能力过滤。
statusquerystring否枚举:queued / running / succeeded / failed / cancelling / cancelled / clearing / cleared操作状态过滤。
limitqueryinteger否默认 25最大返回操作数。
offsetqueryinteger否默认 0跳过的操作数。

输出:

200,返回模型 Models.KnowledgeBaseIndexOperationList。

字段类型说明
total*integer匹配查询的操作总数。
operations*object[]操作列表,元素为 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations?capability=wiki&status=running&limit=25" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "operations": [
    {
      "$id": "op_0001",
      "$createdAt": "2026-09-18T02:40:00.000+00:00",
      "$updatedAt": "2026-09-18T02:41:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "capability": "wiki",
      "kind": "build",
      "scope": "knowledgebase",
      "documentIds": [],
      "status": "running",
      "stage": "compile",
      "progress": 40,
      "message": "",
      "effectiveConfig": {},
      "configHash": "sha256:…",
      "sourceHash": "sha256:…",
      "stats": {},
      "error": {}
    }
  ]
}

POST /v1/knowledgebases/{knowledgeBaseId}/index-operations

SDK:KnowledgeBases.createIndexOperation · scope:knowledgebases.write

为可插拔索引能力排队一次 build 或 repair 操作。要点:

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
capabilitybodystring是枚举:graphrag / raptor / wiki能力标识。
kindbodystring否枚举:build / repair操作种类。
scopebodystring否枚举:knowledgebase / document操作范围。
documentIdsbodystring[]否document 范围操作的文档 ID。
configbodyobject否操作级配置覆盖(泛化对象)。
forcebodyboolean否排队前先取消另一个活跃操作。
idempotencyKeybodystring是去重重试的稳定键。
retryOfbodystring否要修复的先前失败/取消的操作。

输出:

202,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。

调用示例:

# 1. 触发全库 GraphRAG 构建(kind=build)
curl -X POST "https://appbuild-sit.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",
    "kind": "build",
    "scope": "knowledgebase",
    "idempotencyKey": "build-graphrag-20261022-01"
  }'

# 2. 触发单文档范围 RAPTOR 修复操作(kind=repair, scope=document)
curl -X POST "https://appbuild-sit.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": "raptor",
    "kind": "repair",
    "scope": "document",
    "documentIds": ["doc_manual_v2"],
    "retryOf": "op_0000",
    "idempotencyKey": "repair-raptor-20261022-01"
  }'

# 3. 触发 LLM Wiki 构建(kind=build)
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "wiki",
    "kind": "build",
    "scope": "knowledgebase",
    "idempotencyKey": "build-wiki-20260918-0001"
  }'

响应示例:

{
  "$id": "op_0001",
  "$createdAt": "2026-09-18T02:40:00.000+00:00",
  "$updatedAt": "2026-09-18T02:40:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "capability": "wiki",
  "kind": "build",
  "scope": "knowledgebase",
  "documentIds": [],
  "status": "queued",
  "stage": "",
  "progress": 0,
  "message": "",
  "effectiveConfig": {},
  "configHash": "sha256:…",
  "sourceHash": "sha256:…",
  "stats": {},
  "error": {}
}

GET /v1/knowledgebases/{knowledgeBaseId}/index-operations/{operationId}

SDK:KnowledgeBases.getIndexOperation · scope:knowledgebases.read

读取单个索引操作:冻结的生效配置、源/配置哈希、进度、有界日志尾、结果代、统计、脱敏错误与时间戳。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
operationIdpathstring是索引操作 ID。

输出:

200,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations/op_0001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "op_0001",
  "$createdAt": "2026-09-18T02:40:00.000+00:00",
  "$updatedAt": "2026-09-18T02:44:30.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "capability": "wiki",
  "kind": "build",
  "scope": "knowledgebase",
  "documentIds": [],
  "status": "succeeded",
  "stage": "publish",
  "progress": 100,
  "message": "",
  "effectiveConfig": {},
  "configHash": "sha256:…",
  "sourceHash": "sha256:…",
  "resultGeneration": "gen_0007",
  "resultVersion": "1.0.0",
  "stats": {},
  "error": {},
  "logTail": "",
  "startedAt": "2026-09-18T02:40:05.000+00:00",
  "heartbeatAt": "2026-09-18T02:44:25.000+00:00",
  "finishedAt": "2026-09-18T02:44:30.000+00:00"
}

POST /v1/knowledgebases/{knowledgeBaseId}/index-operations/{operationId}/cancel

SDK:KnowledgeBases.cancelIndexOperation · scope:knowledgebases.write

请求取消一个排队中或运行中的索引操作。取消按 attempt 围栏:更新的 attempt 接管后,过期 worker 无法再发布结果。轮询操作直至变为 cancelled 或其他终态。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
operationIdpathstring是索引操作 ID。

无请求体。

输出:

202,返回模型 Models.KnowledgeBaseIndexOperation(字段见「公共响应模型」)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/index-operations/op_0001/cancel" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "op_0001",
  "$createdAt": "2026-09-18T02:40:00.000+00:00",
  "$updatedAt": "2026-09-18T02:41:10.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "capability": "wiki",
  "kind": "build",
  "scope": "knowledgebase",
  "documentIds": [],
  "status": "cancelling",
  "stage": "compile",
  "progress": 40,
  "message": "",
  "effectiveConfig": {},
  "configHash": "sha256:…",
  "sourceHash": "sha256:…",
  "stats": {},
  "error": {}
}

Wiki 页面

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages

SDK:KnowledgeBases.listWikiPages · scope:knowledgebases.read

列出知识库中的 canonical Wiki 页面:可按页面类型或发布状态过滤并分页。列表返回 canonical 页面记录;需要最新详情时调用 getWikiPage。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
pageTypequerystring否枚举:entity / topic / survey / agent_practice / category_index页面类型过滤。
statusquerystring否枚举:draft / published / conflict / archived页面状态过滤。
limitqueryinteger否默认 50最大返回页数。
offsetqueryinteger否默认 0跳过的页数。

输出:

200,返回模型 Models.KnowledgeBaseWikiPageList。

字段类型说明
total*integer匹配查询的页面总数。
pages*object[]页面列表,元素为 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages?pageType=entity&status=published&limit=50" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "pages": [
    {
      "$id": "wp_0001",
      "$createdAt": "2026-09-10T08:00:00.000+00:00",
      "$updatedAt": "2026-09-17T09:30:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "slug": "refund-policy",
      "title": "退款政策",
      "pageType": "entity",
      "contentMd": "# 退款政策\n…",
      "summary": "退款条件与时效",
      "status": "published",
      "pendingConflicts": [],
      "conflicts": [],
      "sourceChunks": [],
      "sourceGraph": {},
      "sourceMemory": [],
      "compiledBy": null,
      "pinned": false,
      "viewCount": 12,
      "contentRevision": 3,
      "links": [],
      "backlinks": [],
      "aliases": [],
      "conflictEvidence": {},
      "divergenceRecommendations": {},
      "conflictBlocks": [],
      "internalContradictions": [],
      "ruleBasedContradictions": [],
      "generalKnowledgeConflicts": []
    }
  ]
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages

SDK:KnowledgeBases.createWikiPage · scope:knowledgebases.write

创建人工持有的 canonical Wiki 页面:可带 Markdown、别名与显式出链;Markdown 中的 [[slug]] 链接也会被服务端提取,未解析目标保留为红链。本操作创建首个不可变版本。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugbodystring是库内唯一 Wiki 页面 slug。
titlebodystring是页面标题。
pageTypebodystring否枚举:entity / topic / survey / agent_practice / category_index页面类型。
contentMdbodystring否canonical Markdown 内容。
summarybodystring否页面摘要。
statusbodystring否枚举:draft / published / conflict / archived页面状态。
pinnedbodyboolean否是否人工置顶。
linksbodyobject否显式出链(泛化对象)。
aliasesbodyobject否人工别名(泛化对象)。
reasonbodystring否版本原因。

输出:

201,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "refund-policy",
    "title": "退款政策",
    "pageType": "entity",
    "contentMd": "# 退款政策\n\n签收后 7 日内可申请退款,详见 [[after-sale-flow]]。",
    "summary": "退款条件与时效",
    "status": "published",
    "reason": "人工整理退款政策"
  }'

响应示例:

{
  "$id": "wp_0001",
  "$createdAt": "2026-09-18T03:10:00.000+00:00",
  "$updatedAt": "2026-09-18T03:10:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "refund-policy",
  "title": "退款政策",
  "pageType": "entity",
  "contentMd": "# 退款政策\n\n签收后 7 日内可申请退款,详见 [[after-sale-flow]]。",
  "summary": "退款条件与时效",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": null,
  "pinned": false,
  "viewCount": 0,
  "contentRevision": 1,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}(兼容标识:GET /v1/knowledgebases/{kbId}/wiki/pages/{pageId})

SDK:KnowledgeBases.getWikiPage · scope:knowledgebases.read

按页面 slug(或页面 $id / pageId)读取 canonical Wiki 页面:出链、入链、别名、来源溯源、投影结果代、未解决冲突与水合冲突证据。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。

输出:

200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。关键字段:contentRevision*(后续写操作的 CAS 版本号)、conflicts*、links* / backlinks* / aliases*。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "wp_0001",
  "$createdAt": "2026-09-18T03:10:00.000+00:00",
  "$updatedAt": "2026-09-18T03:10:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "refund-policy",
  "title": "退款政策",
  "pageType": "entity",
  "contentMd": "# 退款政策\n…",
  "summary": "退款条件与时效",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": null,
  "pinned": false,
  "viewCount": 12,
  "contentRevision": 1,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

PATCH /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}(兼容标识:PATCH /v1/knowledgebases/{kbId}/wiki/pages/{pageId})

SDK:KnowledgeBases.updateWikiPage · scope:knowledgebases.write

以乐观并发更新 canonical Wiki 页面(路径支持传入页面 slug 或 pageId):contentRevision 必须与当前页面版本一致。page 对象承载变更字段;省略 links / aliases 表示保留。成功写入创建不可变版本并刷新检索投影。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是当前 Wiki 页面 slug。
contentRevisionbodyinteger是期望的当前内容版本号。
pagebodyobject是要更新的字段:slug、title、pageType、contentMd、summary、status 或 pinned。
linksbodyobject否替换出链;省略则保留。
aliasesbodyobject否替换人工别名;省略则保留。
reasonbodystring否版本原因。

输出:

200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentRevision": 1,
    "page": {
      "contentMd": "# 退款政策\n\n签收后 7 日内可申请退款(定制商品除外),详见 [[after-sale-flow]]。"
    },
    "reason": "补充定制商品例外"
  }'

响应示例:

{
  "$id": "wp_0001",
  "$createdAt": "2026-09-18T03:10:00.000+00:00",
  "$updatedAt": "2026-09-18T03:25:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "refund-policy",
  "title": "退款政策",
  "pageType": "entity",
  "contentMd": "# 退款政策\n\n签收后 7 日内可申请退款(定制商品除外),详见 [[after-sale-flow]]。",
  "summary": "退款条件与时效",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": null,
  "pinned": false,
  "viewCount": 12,
  "contentRevision": 2,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

DELETE /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}

SDK:KnowledgeBases.deleteWikiPage · scope:knowledgebases.write

删除一个 canonical Wiki 页面:confirmation 必须是 delete:<slug>,contentRevision 必须与当前版本一致。这是破坏性操作,删除 canonical 页面,版本/审计行为按服务端定义保留(DELETE 携带 JSON 请求体)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
contentRevisionbodyinteger是期望的当前页面版本号。
confirmationbodystring是形如 delete:<slug>显式确认。

输出:

200,返回模型 Models.KnowledgeBaseWikiMutation(字段见「公共响应模型」)。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentRevision": 2,
    "confirmation": "delete:refund-policy"
  }'

响应示例:

{
  "pagesDeleted": 1,
  "linksDeleted": 1,
  "linksNulled": 0,
  "revisionsDeleted": 2,
  "aliasesDeleted": 0,
  "clearOperationId": "op_0003"
}

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/revisions

SDK:KnowledgeBases.listWikiPageRevisions · scope:knowledgebases.read

列出一个 canonical Wiki 页面的不可变版本:含主体、版本类型、前后内容、原因与创建时间,可配合 restoreWikiPage 使用。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
limitqueryinteger否默认 50最大返回版本数。

输出:

200,返回模型 Models.KnowledgeBaseWikiRevisionList。

字段类型说明
total*integer匹配查询的版本总数。
revisions*object[]版本列表,元素为 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/revisions?limit=50" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "revisions": [
    {
      "$id": "rev_0007",
      "$createdAt": "2026-09-18T03:10:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "pageId": "wp_0001",
      "revisionType": "create",
      "titleAfter": "退款政策",
      "contentAfter": "# 退款政策\n…",
      "reason": "人工整理退款政策"
    }
  ]
}

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/revisions/{revisionId}

SDK:KnowledgeBases.getWikiPageRevision · scope:knowledgebases.read

读取 canonical Wiki 页面的单个不可变版本。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
revisionIdpathstring是Wiki 版本 ID。

输出:

200,返回模型 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/revisions/rev_0007" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "rev_0007",
  "$createdAt": "2026-09-18T03:10:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "pageId": "wp_0001",
  "revisionType": "create",
  "titleAfter": "退款政策",
  "contentAfter": "# 退款政策\n…",
  "reason": "人工整理退款政策"
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/restore

SDK:KnowledgeBases.restoreWikiPage · scope:knowledgebases.write

把一个历史版本恢复为新版本:contentRevision 提供乐观并发围栏;历史版本本身永不被改写。省略 links 表示保留当前出链。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
revisionIdbodystring是要恢复的版本 ID。
contentRevisionbodyinteger是期望的当前内容版本号。
linksbodyobject否替换出链;省略则保留。
reasonbodystring否恢复原因。

输出:

200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/restore" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "revisionId": "rev_0007",
    "contentRevision": 2,
    "reason": "回退到人工整理版"
  }'

响应示例:

{
  "$id": "wp_0001",
  "$createdAt": "2026-09-18T03:10:00.000+00:00",
  "$updatedAt": "2026-09-18T03:40:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "refund-policy",
  "title": "退款政策",
  "pageType": "entity",
  "contentMd": "# 退款政策\n…",
  "summary": "退款条件与时效",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": null,
  "pinned": false,
  "viewCount": 12,
  "contentRevision": 3,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/pages/{slug}/export-to-memory

SDK:KnowledgeBases.createWikiPageMemoryExport · scope:knowledgebases.write

把一个 canonical Wiki 页面作为事实导出到既有 AppBase Memory 服务。前提:当前项目已有活跃的 AppBase Memory 项目(启用知识库不会自动创建);Memory 服务禁用/初始化中/缺失/不可用时返回 503 memory_service_unavailable。调用方须能写知识库与目标 Memory scope;响应不暴露任何模型或 provider 凭据。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
agentIdbodystring否导出事实的 Memory agent 身份。

输出:

201,返回模型 Models.KnowledgeBaseWikiMemoryExport。

字段类型说明
memory*objectMemory 服务对导出页面的响应(泛化对象,字段以实际返回为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/pages/refund-policy/export-to-memory" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_support_bot"
  }'

响应示例(memory 为泛化对象,示意——字段以实际返回为准):

{
  "memory": {}
}

Wiki 冲突与提案

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts

SDK:KnowledgeBases.listWikiConflicts · scope:knowledgebases.read

列出仍含未解决编译冲突的 canonical Wiki 页面:每页含当前 contentRevision、原始 pendingConflicts 元数据与面向调用方的 conflicts 数组。响应 total 是未解决冲突页总数,不是当前页返回数。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
limitqueryinteger否默认 100最大返回冲突页数。
offsetqueryinteger否默认 0跳过的冲突页数。

输出:

200,返回模型 Models.KnowledgeBaseWikiPageList(total* + pages*[],页面字段见「公共响应模型」;conflicts[] 含稳定冲突 id、检测器 type、人读 reason、精确 conflictingContents 与归属 sources)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts?limit=100&offset=0" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "pages": [
    {
      "$id": "wp_0002",
      "$createdAt": "2026-09-12T08:00:00.000+00:00",
      "$updatedAt": "2026-09-17T10:00:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "slug": "shipping-time",
      "title": "发货时效",
      "pageType": "topic",
      "contentMd": "# 发货时效\n…",
      "status": "conflict",
      "pendingConflicts": [],
      "conflicts": [
        {
          "id": "cf_0001",
          "type": "contradiction",
          "reason": "两处来源对发货时效表述不一致",
          "conflictingContents": ["48 小时内发货", "72 小时内发货"],
          "sources": [
            {
              "documentId": "doc_manual_v2",
              "documentName": "售后手册 v2",
              "chunkId": "chk_0042",
              "conflictingContent": "48 小时内发货",
              "context": "…工作日订单 48 小时内发货…",
              "locator": {}
            }
          ],
          "readOnly": false,
          "confidence": 0.91
        }
      ],
      "sourceChunks": [],
      "sourceGraph": {},
      "sourceMemory": [],
      "compiledBy": "wiki-compiler",
      "pinned": false,
      "viewCount": 3,
      "contentRevision": 5,
      "links": [],
      "backlinks": [],
      "aliases": [],
      "conflictEvidence": {},
      "divergenceRecommendations": {},
      "conflictBlocks": [],
      "internalContradictions": [],
      "ruleBasedContradictions": [],
      "generalKnowledgeConflicts": []
    }
  ]
}

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts/{slug}/proposal

SDK:KnowledgeBases.getWikiConflictProposal · scope:knowledgebases.read

读取冲突 Wiki 页面的最新编译提案:返回的不可变版本可在逐条解决冲突或接受整条提案前查阅。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。

输出:

200,返回模型 Models.KnowledgeBaseWikiRevision(字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts/shipping-time/proposal" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "rev_0009",
  "$createdAt": "2026-09-17T10:05:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "pageId": "wp_0002",
  "revisionType": "compile_proposal",
  "titleBefore": "发货时效",
  "titleAfter": "发货时效",
  "contentBefore": "# 发货时效\n…",
  "contentAfter": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
  "reason": "编译器合并提案"
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/conflicts/{slug}/resolve

SDK:KnowledgeBases.resolveWikiConflict · scope:knowledgebases.write

以乐观并发解决 Wiki 冲突:要么解决一条精确冲突选项,要么提交手工合并后的文档。解决提案的一部分时,传 proposalId 与剩余提案 Markdown(proposalMd),避免未解决部分被静默丢弃。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
slugpathstring是Wiki 页面 slug。
contentRevisionbodyinteger是期望的当前内容版本号。
contentMdbodystring否手工合并后的 Markdown。
resolvedConflictIdbodystring否要解决的精确待决冲突 ID。
resolvedConflictOptionTextbodystring否为该冲突选定的选项文本。
proposalIdbodystring否正在部分解决的编译提案 ID。
proposalMdbodystring否更新后的未解决提案 Markdown。
linksbodyobject否替换出链;省略则保留。
reasonbodystring否解决原因。

输出:

200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/conflicts/shipping-time/resolve" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentRevision": 5,
    "resolvedConflictId": "cf_0001",
    "resolvedConflictOptionText": "48 小时内发货",
    "reason": "以售后手册 v2 为准"
  }'

响应示例:

{
  "$id": "wp_0002",
  "$createdAt": "2026-09-12T08:00:00.000+00:00",
  "$updatedAt": "2026-09-18T04:00:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "shipping-time",
  "title": "发货时效",
  "pageType": "topic",
  "contentMd": "# 发货时效\n\n工作日订单 48 小时内发货。",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": "wiki-compiler",
  "pinned": false,
  "viewCount": 3,
  "contentRevision": 6,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/proposals

SDK:KnowledgeBases.listWikiProposals · scope:knowledgebases.read

列出知识库中冲突 Wiki 页面的最新编译提案:提案是不可变版本,被显式接受或解决前不会替换 canonical 内容。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
limitqueryinteger否默认 100最大返回提案数。

输出:

200,返回模型 Models.KnowledgeBaseWikiRevisionList(total* + revisions*[],版本字段见「公共响应模型」)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/proposals?limit=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "revisions": [
    {
      "$id": "rev_0009",
      "$createdAt": "2026-09-17T10:05:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "pageId": "wp_0002",
      "pageSlug": "shipping-time",
      "pageTitle": "发货时效",
      "revisionType": "compile_proposal",
      "contentAfter": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
      "reason": "编译器合并提案"
    }
  ]
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/proposals/{proposalId}/accept

SDK:KnowledgeBases.acceptWikiProposal · scope:knowledgebases.write

把一条精确的编译提案接受为 canonical Wiki 页面:contentRevision 必须与当前页面版本一致,因此提案无法覆盖更新的人工编辑。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
proposalIdpathstring是精确的编译提案版本 ID。
contentRevisionbodyinteger是期望的当前页面版本号。

输出:

200,返回模型 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/proposals/rev_0009/accept" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contentRevision": 5
  }'

响应示例:

{
  "$id": "wp_0002",
  "$createdAt": "2026-09-12T08:00:00.000+00:00",
  "$updatedAt": "2026-09-18T04:10:00.000+00:00",
  "knowledgeBaseId": "kb_product_docs",
  "slug": "shipping-time",
  "title": "发货时效",
  "pageType": "topic",
  "contentMd": "# 发货时效\n\n工作日订单 48 小时内发货(以售后手册 v2 为准)。",
  "status": "published",
  "pendingConflicts": [],
  "conflicts": [],
  "sourceChunks": [],
  "sourceGraph": {},
  "sourceMemory": [],
  "compiledBy": "wiki-compiler",
  "pinned": false,
  "viewCount": 3,
  "contentRevision": 6,
  "links": [],
  "backlinks": [],
  "aliases": [],
  "conflictEvidence": {},
  "divergenceRecommendations": {},
  "conflictBlocks": [],
  "internalContradictions": [],
  "ruleBasedContradictions": [],
  "generalKnowledgeConflicts": []
}

Wiki 图谱与治理

GET /v1/knowledgebases/{knowledgeBaseId}/wiki/graph

SDK:KnowledgeBases.getWikiGraph · scope:knowledgebases.read

读取 canonical Wiki 页面链接图谱:含 canonical 页面与已解析/未解析链接;目标页为 null 或 redLink=true 表示目标页尚不存在的红链。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。

输出:

200,返回模型 Models.KnowledgeBaseWikiGraph。

字段类型说明
pages*object[]Wiki 图谱页面,元素为 Models.KnowledgeBaseWikiPage(字段见「公共响应模型」)。
links*object已解析与红链边(泛化对象;目标页为 null 或 redLink=true 表示红链)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/graph" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例(links 为泛化对象,示意——字段以实际返回为准):

{
  "pages": [
    {
      "$id": "wp_0001",
      "$createdAt": "2026-09-18T03:10:00.000+00:00",
      "$updatedAt": "2026-09-18T03:25:00.000+00:00",
      "knowledgeBaseId": "kb_product_docs",
      "slug": "refund-policy",
      "title": "退款政策",
      "pageType": "entity",
      "contentMd": "# 退款政策\n…",
      "status": "published",
      "pendingConflicts": [],
      "conflicts": [],
      "sourceChunks": [],
      "sourceGraph": {},
      "sourceMemory": [],
      "compiledBy": null,
      "pinned": false,
      "viewCount": 12,
      "contentRevision": 2,
      "links": [],
      "backlinks": [],
      "aliases": [],
      "conflictEvidence": {},
      "divergenceRecommendations": {},
      "conflictBlocks": [],
      "internalContradictions": [],
      "ruleBasedContradictions": [],
      "generalKnowledgeConflicts": []
    }
  ],
  "links": []
}

SDK:KnowledgeBases.getWikiRecommendedLimits · scope:knowledgebases.read

根据当前文档、GraphRAG 与 Memory 源信号推荐有界的 Wiki 编译上限。enableLlmRefine=false 时只给确定性推荐;否则知识库的共享 Chat 模型可参与修正。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
enableLlmRefinequeryboolean否默认 true是否允许共享 Knowledge chat 模型修正确定性推荐。

输出:

200,返回模型 Models.KnowledgeBaseWikiLimits。

字段类型说明
max_entities*integer推荐的最大实体页数。
max_topics*integer推荐的最大主题页数。
max_surveys*integer推荐的最大综述页数。
rag_max_docs*integer推荐的 RAG 文档预算。
rag_max_chunks_per_doc*integer推荐的每文档切片数。
evidence_max_chunks_to_embed*integer推荐的证据 Embedding 预算。
strategy*stringheuristic 或 ai。
signals*object推荐使用的有界 Knowledge 源信号(泛化对象)。

调用示例:

curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/recommended-limits?enableLlmRefine=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "max_entities": 200,
  "max_topics": 60,
  "max_surveys": 20,
  "rag_max_docs": 500,
  "rag_max_chunks_per_doc": 40,
  "evidence_max_chunks_to_embed": 2000,
  "strategy": "heuristic",
  "signals": {}
}

POST /v1/knowledgebases/{knowledgeBaseId}/wiki/reset(动作路由别名:POST /v1/knowledgebases/{kbId}/reset:wiki)

SDK:KnowledgeBases.resetWiki · scope:knowledgebases.write

删除整个 canonical Wiki 并排队删除其编译投影(支持调用 POST /v1/knowledgebases/{knowledgeBaseId}/wiki/reset 或动作路由别名 POST /v1/knowledgebases/{kbId}/reset:wiki)。confirmation 必须是 reset:wiki;idempotencyKey 使派生索引清理请求可安全重试。比 clearIndexCapability 更具破坏性——后者保留 canonical Wiki 内容。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是知识库 ID。
confirmationbodystring是固定 reset:wiki显式确认。
idempotencyKeybodystring是去重重试的稳定键。

输出:

202,返回模型 Models.KnowledgeBaseWikiMutation(字段见「公共响应模型」);clearOperationId 指向排队中的索引清理操作。

调用示例:

curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/wiki/reset" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation": "reset:wiki",
    "idempotencyKey": "reset-wiki-20260918-0001"
  }'

响应示例:

{
  "pagesDeleted": 42,
  "linksDeleted": 87,
  "linksNulled": 3,
  "revisionsDeleted": 120,
  "aliasesDeleted": 15,
  "clearOperationId": "op_0004"
}

错误与边界

与 Server SDK 的对应

service.method端点
KnowledgeBases.getWikiOverviewGET /knowledgebases/wiki/overview
KnowledgeBases.createWikiQueryPOST /knowledgebases/wiki/query
KnowledgeBases.createWikiProjectSearchPOST /knowledgebases/wiki/search
KnowledgeBases.getGraphGET .../graph
KnowledgeBases.listGraphCommunityReportsGET .../graph/community-reports
KnowledgeBases.getGraphEntityNeighborsGET .../graph/entities/{entityId}/neighbors
KnowledgeBases.listIndexCapabilitiesGET .../index-capabilities
KnowledgeBases.updateIndexCapability / clearIndexCapabilityPATCH .../index-capabilities/{capability}、POST .../clear
KnowledgeBases.listIndexOperations / createIndexOperationGET / POST .../index-operations
KnowledgeBases.getIndexOperation / cancelIndexOperationGET .../index-operations/{operationId}、POST .../cancel
KnowledgeBases.listWikiPages / createWikiPageGET / POST .../wiki/pages
KnowledgeBases.getWikiPage / updateWikiPage / deleteWikiPageGET / PATCH / DELETE .../wiki/pages/{slug}
KnowledgeBases.listWikiPageRevisions / getWikiPageRevisionGET .../revisions、GET .../revisions/{revisionId}
KnowledgeBases.restoreWikiPagePOST .../wiki/pages/{slug}/restore
KnowledgeBases.createWikiPageMemoryExportPOST .../wiki/pages/{slug}/export-to-memory
KnowledgeBases.listWikiConflicts / getWikiConflictProposal / resolveWikiConflictGET .../wiki/conflicts、GET .../conflicts/{slug}/proposal、POST .../resolve
KnowledgeBases.listWikiProposals / acceptWikiProposalGET .../wiki/proposals、POST .../proposals/{proposalId}/accept
KnowledgeBases.getWikiGraphGET .../wiki/graph
KnowledgeBases.getWikiRecommendedLimitsGET .../wiki/recommended-limits
KnowledgeBases.resetWikiPOST .../wiki/reset

事实源