AgentbaseDocs
文档目录

知识库版本管理 API

知识库多版本生命周期接口:版本列出与读取、工作副本(working copy)创建与操作查询/取消、就绪检查与封存(seal)、发布(publish)与回滚(rollback)、版本删除(不可逆异步清理)及删除操作查询、版本采纳(adoption)及其查询/取消。骨架与产品语义见 知识库 API。

服务与资源边界

知识库版本管理 API 为企业生产知识库提供不可变快照封存、灰度验证与秒级回滚能力:通过将日常文档编辑隔离在 DRAFT 工作副本(Working Copy)中,经 readiness 就绪检查通过后封存(seal)为只读 READY 版本,再通过 publish / rollback 原子切换线上检索流量指向的 CURRENT 版本,避免文档摄取或切片调整过程中出现检索结果抖动。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。查询类端点需 knowledgebases.read,全部写操作需 knowledgebases.write。接受类写端点(创建工作副本、seal、delete、adoption 创建/取消、工作副本取消)另要求稳定的 Idempotency-Key 头:同一 key 与同一请求重放返回原操作,复用 key 提交不同输入返回 idempotency_key_reused(409)。

端点总览

本模块共包含 16 个端点,覆盖:版本列表与详情查询、从既有 READY 版本异步克隆 DRAFT 工作副本、就绪探针(readiness)与版本封存(seal)、线上版本发布(publish)与回滚(rollback)、存量非版本化知识库采纳(version-adoptions)以及异步版本物理删除(version-delete-operations)。

端点清单

方法 + 路径用途
GET /knowledgebases/{knowledgeBaseId}/versions列出版本(status / role 过滤,cursor 分页)(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/versions创建工作副本(异步,202 + 操作)(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}获取版本(见 版本管理)
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId}请求不可逆删除(异步,202 + 删除操作)(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish发布 READY 版本为当前版本(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback回滚到保留的回滚目标(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal就绪检查通过后封存 DRAFT 为 READY(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness就绪摘要(sealable + 阻塞原因)(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/version-adoptions列出采纳操作(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/version-adoptions为未版本化库启动采纳(异步,202)(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}获取采纳操作(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel请求取消采纳(异步,202)(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}查询版本删除操作(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations列出工作副本操作(见 版本管理)
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}获取工作副本操作(见 版本管理)
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel请求取消工作副本操作(见 版本管理)

端点详解

所有改变版本拓扑的写操作均强制结合 Idempotency-Key 请求头与预期修订号(expectedSourceVersionRevision / expectedBindingRevision)执行双重并发校验:既保证网络超时重发安全返回同一异步操作,又防止基于过期元数据发起冲突发布。

请求与响应

通用约定:认证头 X-Appwrite-Project / X-Appwrite-Key(见 通用约定);异步端点返回 202 + Location 头指向对应操作查询端点,客户端轮询至终态;操作模型对调用方脱敏(不暴露 provider locator、物理表、bucket/file、manifest 或 checkpoint)。示例中 kb_product_docs、ver_001 等请替换为实际值。

GET /v1/knowledgebases/{knowledgeBaseId}/versions

列出指定知识库中对调用方可见的版本;只返回已提交的版本(物化中的工作副本不以半成品 DRAFT 出现)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
limitqueryinteger否默认 25每页最大版本数。
cursorquerystring否默认 ""版本 ID 分页游标。
statusquerystring否枚举:draft / ready按生命周期状态过滤。
rolequerystring否枚举:current / rollback / none按路由角色过滤。

输出:200,返回模型 KnowledgeBaseVersionList:total + versions[](模型 KnowledgeBaseVersion,字段见下)。

POST /v1/knowledgebases/{knowledgeBaseId}/versions

从一个 READY 且 deletionState=NONE 的版本创建完全物化的工作副本;复制与校验完成后新版本才以隔离 DRAFT 可见,parentVersionId 记录逻辑源版本。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
sourceVersionIdbodystring是源版本 ID(READY 且未进入删除流程)。
expectedSourceVersionRevisionbodyinteger是预期源版本修订号。
expectedBindingRevisionbodyinteger是预期知识库绑定修订号。
labelbodystring是工作副本标签,非空且唯一。
descriptionbodystring否工作副本描述。
retryOfbodystring否被重试的失败/取消操作 ID。

输出:202,返回模型 KnowledgeBaseWorkingCopyOperation(status: queued / preflight / copying / validating / reconciling / cancelling / succeeded / failed / cancelled,含 operationRevision、progress、errorCode/errorSummary、result.versionId、retryOf);Location 头指向工作副本操作查询端点。

调用示例:

curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: wc-create-v20261022-01" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVersionId": "ver_initial_ready_01",
    "expectedSourceVersionRevision": 1,
    "expectedBindingRevision": 2,
    "label": "v2026.10.22-rc1",
    "description": "新增 OceanBase V4.3 排障手册与多模态架构图切片"
  }'

**响应示例(202 Accepted)**:

{
  "$id": "wcop_99201a",
  "$createdAt": "2026-10-22T06:10:00.000+00:00",
  "$updatedAt": "2026-10-22T06:10:00.000+00:00",
  "knowledgeBaseId": "kb_enterprise_support",
  "kind": "create_working_copy",
  "status": "queued",
  "operationRevision": 1,
  "progress": 0,
  "result": {
    "versionId": "ver_draft_20261022"
  }
}

GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}

获取单个版本的状态、角色、逻辑父版本、修订号与处理进度摘要;跨库或不存在的版本统一按不可见处理。

输入:

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

输出:200,返回模型 KnowledgeBaseVersion。

字段类型说明
$id*string版本 ID。
$createdAt* / $updatedAt*string创建/更新时间(ISO 8601)。
parentVersionIdstring直属逻辑父版本 ID;根版本为 null。
label*string版本标签。
descriptionstring版本描述。
status*string生命周期状态:DRAFT / READY。
deletionState*string删除状态:NONE / REQUESTED / RUNNING / RETRYABLE_FAILED / COMPLETED;仅 NONE 允许数据访问。
role*string路由角色:CURRENT / ROLLBACK / NONE。
versionRevision*integer版本元数据与生命周期修订号。
definitionRevision*integer版本内容与配置修订号。
documentProcessingRevision*integer文档处理配置修订号。
readinessobject只读就绪摘要(不含源内容与 provider locator)。

DELETE /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}

请求对一个非活跃版本做不可逆清理。仅 role=NONE、deletionState=NONE 且状态为 DRAFT/READY 的版本可删;接受后访问立即被撤销且不可撤回,物理清理由后台 Worker 有界分批异步执行。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
versionIdpathstring是目标版本 ID。
expectedVersionRevisionbodyinteger是预期版本生命周期修订号。

输出:202,返回模型 KnowledgeBaseVersionDeleteOperation(status: queued / running / retryable_failed / completed);Location: /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}。retryable_failed 时访问保持被撤销,需换新幂等键重新提交 DELETE 重排队同一操作。

POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish

将未删除的 READY 版本发布为线上 CURRENT;同一事务内切换 currentVersionId 与 rollbackVersionId,先前的 CURRENT 成为唯一 ROLLBACK 目标。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
versionIdpathstring是目标 READY 版本 ID。
expectedBindingRevisionbodyinteger是预期知识库绑定修订号。
expectedVersionRevisionbodyinteger是预期版本生命周期修订号。

输出:200,返回模型 KnowledgeBaseVersion(发布后的版本)。

调用示例:

curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/publish" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: ver-publish-20261022-01" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 3,
    "expectedVersionRevision": 2
  }'

POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback

将 Binding 保留的 ROLLBACK 角色指向的未删除 READY 版本恢复为线上 CURRENT;原子交换 currentVersionId 与 rollbackVersionId,不能指定任意历史版本作为回滚目标。

输入:与 publish 相同——knowledgeBaseId、versionId(path,必填),expectedBindingRevision、expectedVersionRevision(body,integer,必填)。

输出:200,返回模型 KnowledgeBaseVersion(回滚后的当前版本)。

调用示例:

curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_initial_ready_01/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: ver-rollback-20261022-01" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 4,
    "expectedVersionRevision": 2
  }'

POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal

在全部就绪检查通过后将 DRAFT 版本设为 READY;活动任务、未就绪/待重建文档、stale/failed 的已启用索引能力与 Wiki 冲突都会拒绝转换。成功后的 READY 版本只读,不自动发布。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
versionIdpathstring是目标 DRAFT 版本 ID。
expectedDefinitionRevisionbodyinteger是预期版本内容/配置修订号。
expectedVersionRevisionbodyinteger是预期版本生命周期修订号。

输出:200,返回模型 KnowledgeBaseVersion(封存后的 READY 版本)。

调用示例:

curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/seal" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: ver-seal-20261022-01" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedDefinitionRevision": 5,
    "expectedVersionRevision": 1
  }'

GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness

获取版本的只读就绪摘要:状态与修订号、文档/索引/活动任务计数、是否可封存及按数量聚合的阻塞原因。

输入:

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

输出:200,返回模型 KnowledgeBaseVersionReadiness。

字段类型说明
versionId*string版本 ID。
status*string生命周期状态:DRAFT / READY。
versionRevision*integer当前版本生命周期修订号。
definitionRevision*integer当前版本内容/配置修订号。
documentProcessingRevision*integer当前文档处理修订号。
sealable*boolean是否无就绪阻塞(可设为 READY)。
summary*object就绪计数(不含文档内容与 provider 引用)。
blockers*object稳定阻塞码与计数(如 active_tasks、documents_not_ready、documents_rebuild_required、capabilities_stale、capabilities_failed、wiki_conflicts)。

调用示例:

curl -X GET "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_20261022/readiness" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

**响应示例(200 OK)**:

{
  "versionId": "ver_draft_20261022",
  "status": "DRAFT",
  "versionRevision": 1,
  "definitionRevision": 5,
  "documentProcessingRevision": 4,
  "sealable": true,
  "summary": {
    "documentsTotal": 12,
    "documentsReady": 12,
    "activeTasks": 0
  },
  "blockers": {
    "active_tasks": 0,
    "documents_not_ready": 0,
    "documents_rebuild_required": 0,
    "capabilities_stale": 0,
    "capabilities_failed": 0,
    "wiki_conflicts": 0
  }
}

GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions

列出本知识库的采纳操作历史。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
limitqueryinteger否默认 25每页最大操作数。
cursorquerystring否默认 ""操作 ID 分页游标。
statusquerystring否按操作状态过滤。

输出:200,返回采纳操作列表模型(total + adoptions[],元素为采纳操作模型,见下)。

POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions

为尚未启用版本的 Shared V2 知识库启动采纳:后台 Worker 完成 schema reconciliation、drain、标记、验证与激活,成功前不切换 currentVersionId。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID(须未启用版本化)。
expectedBindingRevisionbodyinteger是预期知识库绑定修订号。
retryOfbodystring否被重试的终态采纳操作 ID。

输出:202,返回采纳操作模型(KnowledgeBaseVersionAdoptionOperation 口径,字段与工作副本操作同构:$id、时间戳、kind、status、operationRevision、progress、errorCode/errorSummary、result、retryOf;status 枚举含 queued / preflight / storage_reconciling / draining / backfilling / marking / validating / activating / reconciling / cancelling / succeeded / failed / cancelled);Location 头指向采纳操作查询端点。模型名以 spec 为准。

调用示例:

curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/version-adoptions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Idempotency-Key: adopt-kb-20261022-01" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 1
  }'

GET /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}

获取单个采纳操作的当前状态与进度。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
adoptionIdpathstring是采纳操作 ID。

输出:200,返回采纳操作模型(同上,模型名以 spec 为准)。

POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel

在采纳尚未进入不可取消阶段时请求取消;成功接受后由后台流程完成一致性收敛。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
adoptionIdpathstring是采纳操作 ID。
expectedOperationRevisionbodyinteger是预期采纳操作修订号。

输出:202,返回采纳操作模型(进入 cancelling,最终收敛至 cancelled 或继续原流程;模型名以 spec 为准)。

GET /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}

查询单个版本删除操作用于轮询;仅接受发起 DELETE 的同一知识库的 operationId(跨库按 version_not_found 处理)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID(须与删除操作所属库一致)。
operationIdpathstring是删除操作 ID。

输出:200,返回模型 KnowledgeBaseVersionDeleteOperation。

GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations

列出本知识库的工作副本操作。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
limitqueryinteger否默认 25每页最大操作数。
cursorquerystring否默认 ""操作 ID 分页游标。
statusquerystring否按操作状态过滤。

输出:200,返回模型 KnowledgeBaseWorkingCopyOperationList:total + operations[](模型 KnowledgeBaseWorkingCopyOperation)。

GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}

获取单个工作副本操作的当前状态、进度与结果。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
operationIdpathstring是工作副本操作 ID。

输出:200,返回模型 KnowledgeBaseWorkingCopyOperation。

POST /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel

请求取消非终态的工作副本操作;取消为异步——响应通常为 cancelling,继续轮询至 cancelled。私有候选副本会被清理,不会生成可见 DRAFT。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
operationIdpathstring是工作副本操作 ID。
expectedOperationRevisionbodyinteger是预期工作副本操作修订号。

输出:200,返回模型 KnowledgeBaseWorkingCopyOperation(status=cancelling)。

错误与边界

与 Server SDK 的对应

service.method端点
KnowledgeBases.listVersionsGET /knowledgebases/{id}/versions
KnowledgeBases.createVersionPOST /knowledgebases/{id}/versions
KnowledgeBases.getVersionGET .../versions/{versionId}
KnowledgeBases.deleteVersionDELETE .../versions/{versionId}
KnowledgeBases.publishVersionPOST .../versions/{versionId}/publish
KnowledgeBases.rollbackVersionPOST .../versions/{versionId}/rollback
KnowledgeBases.sealVersionPOST .../versions/{versionId}/seal
KnowledgeBases.getVersionReadinessGET .../versions/{versionId}/readiness
KnowledgeBases.listVersionAdoptions / createVersionAdoption`GETPOST .../version-adoptions`
KnowledgeBases.getVersionAdoption / cancelVersionAdoptionGET .../version-adoptions/{adoptionId}、POST .../{adoptionId}/cancel
KnowledgeBases.getVersionDeleteOperationGET .../version-delete-operations/{operationId}
KnowledgeBases.listWorkingCopyOperations / getWorkingCopyOperation / cancelWorkingCopyOperationGET .../working-copy-operations、`GETPOST .../working-copy-operations/{operationId}(/cancel)`

事实源