知识库版本管理 API
知识库多版本生命周期接口:版本列出与读取、工作副本(working copy)创建与操作查询/取消、就绪检查与封存(seal)、发布(publish)与回滚(rollback)、版本删除(不可逆异步清理)及删除操作查询、版本采纳(adoption)及其查询/取消。骨架与产品语义见 知识库 API。
服务与资源边界
知识库版本管理 API 为企业生产知识库提供不可变快照封存、灰度验证与秒级回滚能力:通过将日常文档编辑隔离在 DRAFT 工作副本(Working Copy)中,经 readiness 就绪检查通过后封存(seal)为只读 READY 版本,再通过 publish / rollback 原子切换线上检索流量指向的 CURRENT 版本,避免文档摄取或切片调整过程中出现检索结果抖动。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/knowledgebases/{knowledgeBaseId}。层级:知识库
{knowledgeBaseId}→ 版本{versionId};旁路资源:采纳操作{adoptionId}、工作副本操作{operationId}、删除操作{operationId}。生命周期:
DRAFT(工作副本)→READY(seal 后只读快照)→CURRENT/ROLLBACK(publish / rollback 的路由角色);删除后版本进入deletionState流转且不可逆。
认证与权限
认证与请求头约定见 通用约定。查询类端点需 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 出现)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大版本数。 |
cursor | query | string | 否 | 默认 "" | 版本 ID 分页游标。 |
status | query | string | 否 | 枚举:draft / ready | 按生命周期状态过滤。 |
role | query | string | 否 | 枚举:current / rollback / none | 按路由角色过滤。 |
输出:200,返回模型 KnowledgeBaseVersionList:total + versions[](模型 KnowledgeBaseVersion,字段见下)。
POST /v1/knowledgebases/{knowledgeBaseId}/versions
从一个 READY 且 deletionState=NONE 的版本创建完全物化的工作副本;复制与校验完成后新版本才以隔离 DRAFT 可见,parentVersionId 记录逻辑源版本。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
sourceVersionId | body | string | 是 | 源版本 ID(READY 且未进入删除流程)。 | |
expectedSourceVersionRevision | body | integer | 是 | 预期源版本修订号。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
label | body | string | 是 | 工作副本标签,非空且唯一。 | |
description | body | string | 否 | 工作副本描述。 | |
retryOf | body | string | 否 | 被重试的失败/取消操作 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}
获取单个版本的状态、角色、逻辑父版本、修订号与处理进度摘要;跨库或不存在的版本统一按不可见处理。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 版本 ID。 |
输出:200,返回模型 KnowledgeBaseVersion。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 版本 ID。 |
$createdAt* / $updatedAt* | string | 创建/更新时间(ISO 8601)。 |
parentVersionId | string | 直属逻辑父版本 ID;根版本为 null。 |
label* | string | 版本标签。 |
description | string | 版本描述。 |
status* | string | 生命周期状态:DRAFT / READY。 |
deletionState* | string | 删除状态:NONE / REQUESTED / RUNNING / RETRYABLE_FAILED / COMPLETED;仅 NONE 允许数据访问。 |
role* | string | 路由角色:CURRENT / ROLLBACK / NONE。 |
versionRevision* | integer | 版本元数据与生命周期修订号。 |
definitionRevision* | integer | 版本内容与配置修订号。 |
documentProcessingRevision* | integer | 文档处理配置修订号。 |
readiness | object | 只读就绪摘要(不含源内容与 provider locator)。 |
DELETE /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}
请求对一个非活跃版本做不可逆清理。仅 role=NONE、deletionState=NONE 且状态为 DRAFT/READY 的版本可删;接受后访问立即被撤销且不可撤回,物理清理由后台 Worker 有界分批异步执行。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标版本 ID。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出: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 目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标 READY 版本 ID。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出: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 版本只读,不自动发布。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标 DRAFT 版本 ID。 | |
expectedDefinitionRevision | body | integer | 是 | 预期版本内容/配置修订号。 | |
expectedVersionRevision | body | integer | 是 | 预期版本生命周期修订号。 |
输出: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
获取版本的只读就绪摘要:状态与修订号、文档/索引/活动任务计数、是否可封存及按数量聚合的阻塞原因。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | path | string | 是 | 目标版本 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
列出本知识库的采纳操作历史。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大操作数。 |
cursor | query | string | 否 | 默认 "" | 操作 ID 分页游标。 |
status | query | string | 否 | 按操作状态过滤。 |
输出:200,返回采纳操作列表模型(total + adoptions[],元素为采纳操作模型,见下)。
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions
为尚未启用版本的 Shared V2 知识库启动采纳:后台 Worker 完成 schema reconciliation、drain、标记、验证与激活,成功前不切换 currentVersionId。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID(须未启用版本化)。 | |
expectedBindingRevision | body | integer | 是 | 预期知识库绑定修订号。 | |
retryOf | body | string | 否 | 被重试的终态采纳操作 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}
获取单个采纳操作的当前状态与进度。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
adoptionId | path | string | 是 | 采纳操作 ID。 |
输出:200,返回采纳操作模型(同上,模型名以 spec 为准)。
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel
在采纳尚未进入不可取消阶段时请求取消;成功接受后由后台流程完成一致性收敛。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
adoptionId | path | string | 是 | 采纳操作 ID。 | |
expectedOperationRevision | body | integer | 是 | 预期采纳操作修订号。 |
输出:202,返回采纳操作模型(进入 cancelling,最终收敛至 cancelled 或继续原流程;模型名以 spec 为准)。
GET /v1/knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId}
查询单个版本删除操作用于轮询;仅接受发起 DELETE 的同一知识库的 operationId(跨库按 version_not_found 处理)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID(须与删除操作所属库一致)。 | |
operationId | path | string | 是 | 删除操作 ID。 |
输出:200,返回模型 KnowledgeBaseVersionDeleteOperation。
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations
列出本知识库的工作副本操作。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 25 | 每页最大操作数。 |
cursor | query | string | 否 | 默认 "" | 操作 ID 分页游标。 |
status | query | string | 否 | 按操作状态过滤。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperationList:total + operations[](模型 KnowledgeBaseWorkingCopyOperation)。
GET /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}
获取单个工作副本操作的当前状态、进度与结果。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
operationId | path | string | 是 | 工作副本操作 ID。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperation。
POST /v1/knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel
请求取消非终态的工作副本操作;取消为异步——响应通常为 cancelling,继续轮询至 cancelled。私有候选副本会被清理,不会生成可见 DRAFT。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
operationId | path | string | 是 | 工作副本操作 ID。 | |
expectedOperationRevision | body | integer | 是 | 预期工作副本操作修订号。 |
输出:200,返回模型 KnowledgeBaseWorkingCopyOperation(status=cancelling)。
错误与边界
修订号预期不符被拒:
expectedBindingRevision/expectedVersionRevision/expectedDefinitionRevision/expectedOperationRevision漂移、生命周期/角色/删除状态不合规或并发 Binding 变化,返回version_concurrently_modified(409)——刷新后重读状态再决定是否重试。seal 前置:
sealVersion要求就绪检查全部通过(readiness.sealable=true),否则拒绝转换。publish 仅 READY:只有未删除的
READY版本可发布;发布/回滚不创建任何摄取、同步、索引或 Memory 任务。delete 不可逆异步:接受即撤销访问且不可撤回;物理清理异步执行,
retryable_failed需换新幂等键重新提交;完成后数据清除、版本记录保留为审计痕迹。adoption 仅未版本化库:已启用版本化的库不能再发起采纳;进入不可取消阶段后取消失败(revision 漂移同样失败)。
幂等键复用不同输入返回
idempotency_key_reused(409);工作副本标签重复返回version_label_already_exists;不支持版本化的存储模式返回version_storage_mode_not_supported。列表与查询对跨库/不存在的资源统一按不可见处理(404
version_not_found),不泄露存在性。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
KnowledgeBases.listVersions | GET /knowledgebases/{id}/versions |
KnowledgeBases.createVersion | POST /knowledgebases/{id}/versions |
KnowledgeBases.getVersion | GET .../versions/{versionId} |
KnowledgeBases.deleteVersion | DELETE .../versions/{versionId} |
KnowledgeBases.publishVersion | POST .../versions/{versionId}/publish |
KnowledgeBases.rollbackVersion | POST .../versions/{versionId}/rollback |
KnowledgeBases.sealVersion | POST .../versions/{versionId}/seal |
KnowledgeBases.getVersionReadiness | GET .../versions/{versionId}/readiness |
KnowledgeBases.listVersionAdoptions / createVersionAdoption | GET|POST .../version-adoptions |
KnowledgeBases.getVersionAdoption / cancelVersionAdoption | GET .../version-adoptions/{adoptionId}、POST .../{adoptionId}/cancel |
KnowledgeBases.getVersionDeleteOperation | GET .../version-delete-operations/{operationId} |
KnowledgeBases.listWorkingCopyOperations / getWorkingCopyOperation / cancelWorkingCopyOperation | GET .../working-copy-operations、GET|POST .../working-copy-operations/{operationId}(/cancel) |