Docs
文档目录

知识库版本管理(Versions)

版本管理(Versions) 是 Agentbase 知识库用于管理内容变更与版本切换的能力。通过知识库详情页的 版本管理(Versions) 页签,团队可以将未启用版本化的存量知识库平滑迁移至版本化管理(版本采纳 Adoption),基于任意就绪快照创建隔离的可编辑工作副本(Working Copy / DRAFT),在副本内安全完成文档增删、分块调优与高级索引构建,通过严格的就绪门禁检查(Readiness Gate)后将其封存(Seal)为不可变只读版本(READY),并一键发布(Publish)切换为线上当前激活版本,或在需要时回滚(Rollback)至保留的回滚目标。


功能概述与核心场景

在企业智能客服生产环境(如 kb_enterprise_support)中,如果知识运营人员直接在正在对外提供问答服务的线上知识库中大批量删除旧文档、上传尚未核验的新文档或触发漫长的全库重建(Reindex),会导致线上检索在变更窗口期内出现结果缺失、分块断层或回答前后矛盾。

Agentbase 的 知识库版本管理 借鉴了现代云原生数据库与软件发布工程的最佳实践,提供以下核心能力:

  1. 平滑的版本采纳(Version Adoption,POST /version-adoptions):

    • 对于尚未开启版本化管理的知识库,支持一键发起异步采纳操作,在不中断现有读取流量的前提下,将既有文档、分块、向量与派生索引完整封存为首个基准不可变版本(如 v1)。

  2. 异步完整物化的隔离工作副本(Working Copy,POST /versions):

    • 基于任意 READY 状态的历史版本创建草稿副本(DRAFT)。后台异步完成行数、对象数、产物与字节级复制及完整性校验后,草稿副本才正式对外可见,修改在工作副本中进行,当前版本继续保持激活。

  3. 四重严格就绪门禁(Readiness Gate,GET /versions/{versionId}/readiness)与封存(Seal):

    • 草稿副本要封存为 READY 快照,必须通过自动化的 Readiness 检查(确保无未完成任务、全部文档已 ready 且无需重建、已启用的 GraphRAG / RAPTOR / Wiki 索引已构建就绪、Wiki 启用时无未裁决的 Wiki 冲突)。

  4. 乐观锁保护的原子发布(Publish)与一键回滚(Rollback):

    • 发布操作将指定的 READY 版本原子切换为当前激活版本,并将先前的激活版本设置为回滚目标(Rollback Target);该目标仍受自动保留策略影响。

    • 发布与回滚均强制校验预期绑定修订号(Expected Binding Revision),防范多人并发变更冲突。

  5. 自动保留策略(Retention Policy)与不可逆安全清理:

    • 支持配置自动保留的历史版本数量(默认保留 3 个),并支持对非当前、非回滚角色的冗余版本发起异步安全清理。

尚未启用多版本的知识库

图:2.12.0 测试知识库尚未启用多版本。


核心概念与架构

知识库不可变版本生命周期状态机

知识库版本管理(Versions):流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

版本状态、角色与核心概念表

概念类别标识名称详细含义与约束规则
版本状态DRAFT可编辑工作副本:后台复制与完整性校验通过后出现在版本列表中,允许增删改文档、分块与派生索引。
版本状态READY已封存只读快照:通过 Readiness 检查并执行 Seal 后的不可变版本。任何针对 READY 版本的写操作均被拒绝。
删除状态deletionState删除操作另行记录为 REQUESTED、RUNNING、RETRYABLE_FAILED 或 COMPLETED 等状态;版本状态和删除状态分别查看。
版本角色Current(当前版本)当客户端调用检索或问答接口且未显式指定版本时,默认路由命中的线上激活版本。
版本角色Rollback(回滚目标)每次执行 Publish 发布新版本时,系统将替换下来的前一个 Current 版本设置为回滚目标;自动保留策略可能在后续清理该目标。
乐观锁修订号bindingRevision知识库版本指针绑定关系的递增修订号。调用 Publish 或 Rollback 时必须传入当前看到的修订号,防止并发覆盖。
保留策略versionRetentionCount已发布历史版本的保留数量(默认 3,不含当前版本);超出保留数量的候选版本由后台按条件处理。

功能入口与权限矩阵

控制台入口、REST API 与权限

控制台入口 / 功能模块前端路由路径对应 REST API 端点写操作 API Key Scope跨模块依赖关系
存量知识库版本化采纳(Adoption)/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/versions(「启用版本化」引导)POST /v1/knowledgebases/{kbId}/version-adoptionsknowledgebases.write将存量文档、分块、向量与派生索引封存为首个 READY 版本
基于 READY 版本创建 DRAFT 工作副本/console/.../kb-kb_enterprise_support/versions(点击「创建工作副本 Create working copy」)POST /v1/knowledgebases/{kbId}/versions
GET /v1/knowledgebases/{kbId}/versions
knowledgebases.write完整物化后隔离 文档、数据源、高级索引 与 Wiki 编辑
就绪门禁校验(Readiness Gate)与封存(Seal)版本列表展开「就绪状态(Readiness)」与「封存(Seal)」按钮GET /v1/knowledgebases/{kbId}/versions/{versionId}/readiness
POST .../versions/{versionId}/seal
knowledgebases.write强制核验无运行中任务、全部文档 ready、已启用的 高级索引 已构建;Wiki 启用时无未裁决 Wiki 冲突
原子发布(Publish)与一键回滚(Rollback)版本列表「发布(Publish)」与顶部「一键回滚(Rollback)」POST /v1/knowledgebases/{kbId}/versions/{versionId}/publish
POST .../versions/{versionId}/rollback
knowledgebases.write校验 expectedBindingRevision 乐观锁,原子切换线上 混合检索 默认命中版本
异步安全清理历史版本版本列表非 Current/Rollback 行操作「删除(Delete)」DELETE /v1/knowledgebases/{kbId}/versions/{versionId}knowledgebases.write后台分批物理回收底层向量、分块与图谱存储,保留审计记录

列表、版本详情和就绪检查等读取操作需要 knowledgebases.read。控制台可用操作还取决于当前项目授权。


功能详解与操作指南

一、存量知识库启用版本化:版本采纳(POST /version-adoptions)

如果知识库创建于早期版本或尚未开启版本化治理,首次进入 Versions 页签时会看到「启用多版本」引导卡片:

  1. 点击 启用多版本 按钮(或调用 POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions)。

  2. 系统启动异步采纳操作,页面展示当前状态。操作处于 queued、preflight 或 draining,且当前阶段也属于这三者时,可以尝试取消;其他阶段是否可取消以界面和服务端返回为准。等待操作结束后再检查结果;失败时根据提示处理。

  3. 采纳完成后,知识库既有全部内容自动成为首个不可变的 READY 且 Current 基准版本。


二、创建工作副本(POST /versions)并完成增量修订

当需要为 kb_enterprise_support 新增季度排障规范或调整分块策略时,标准操作流程如下:

  1. 在 版本 页签的 工作副本 区域,点击 创建工作副本(Create working copy)。

  2. 填写工作副本创建表单:

    • 源版本(Source Version):选择当前处于 READY 状态的基准版本(如 v1.0-baseline)。

    • 版本标签(Label,必填且库内唯一):例如 v2.10.0-q4-support-upgrade。

    • 版本描述(Description,可选):例如 新增 AI 网关限流规范并完成 10 篇 Wiki 页面重编译。

  3. 点击 创建 后,后台开始异步复制源版本的文档、分块、向量与派生索引产物,界面按可用信息展示复制进度:

    • 复制中的副本不会以半成品状态出现在正式版本列表中。仅 queued、preflight、copying、validating 状态可请求取消;请求受理后先进入 cancelling,应轮询状态并等待清理完成。清理调度失败时可能等待后台协调处理。

    • 原操作为 failed 或 cancelled、源版本匹配且清理已完成时,才可重试;retryOf 指向原操作 ID。条件尚未满足时继续查看状态和错误信息。

  4. 复制校验完成、副本状态变为 DRAFT 后,在顶部版本切换器中选中该 DRAFT 版本,前往 文档、知识索引 与 Wiki 页签完成新文档摄取与索引更新。


三、检查就绪门禁(Readiness Gate)并执行封存(POST /versions/{versionId}/seal)

在将 DRAFT 工作副本封存为 READY 快照之前,系统会强制执行四项就绪门禁检查。在 Versions 页签展开该 DRAFT 版本的 就绪状态(Readiness Summary),核对以下四项指标是否全部为绿色通过:

就绪检查项阻塞封存(Seal Blocked)的典型原因解决与修复方式
1. 活动任务检查 (activeTaskCount)当前版本仍有正在排队或运行中的文档摄取、数据源同步或索引构建任务等待异步任务执行完毕,或手动取消不需要的任务
2. 文档就绪与配置一致性 (documents)存在处于 failed / processing 状态的文档,或修改了默认分块参数但尚未对存量文档执行重建修复失败文档并触发重新摄取(Re-ingest)或整库重建(Reindex),确保全部文档为 ready
3. 派生索引完整性 (capabilities)已启用 GraphRAG、RAPTOR 或 Wiki 开关,但最新文档变更后尚未完成构建或构建失败前往 索引 页签构建;确认构建操作为 succeeded,且各已启用能力状态为 ready 并有活动结果代数。若变为 stale,需重新构建
4. Wiki 冲突清零 (wikiConflicts)Wiki 已启用且当前版本存在尚未解决的跨文档 Wiki 知识冲突单前往 Wiki -> 冲突工作台(Conflicts) 逐条完成冲突裁决(Resolve)

当上述四项检查全部通过(sealable = true)后,点击该版本右侧的 封存(Seal) 按钮。版本状态立即由 DRAFT 变为不可变的 READY(注意:封存仅冻结快照,不会自动将其发布为线上当前版本)。


四、执行原子发布(Publish)、一键回滚(Rollback)与 REST API 操作

  1. 发布新版本(Publish):

    • 在版本列表中找到已处于 READY 状态的 v2.10.0-q4-support-upgrade,点击 发布(Publish)。

    • 确认弹窗后,该版本立即成为新的 当前版本(Current),未显式指定版本的检索使用新当前版本;原当前版本初始成为 回滚目标(Rollback Target),后续仍受保留策略影响。

  2. 异常一键回滚(Rollback):

    • 若新版本上线后业务反馈检索效果不符合预期,在 Versions 页签顶部点击 一键回滚(Rollback),系统立即将保留的回滚目标恢复为当前激活版本,并将刚才撤下的版本互换为新的回滚目标。

  3. 完整的版本生命周期 REST API 调用示例:

以下示例中的 ID 和修订号仅作说明。每次写操作前先从当前知识库和版本读取最新修订号;采纳与工作副本返回 202 后,应查询操作状态并等待完成。每个新的采纳、复制或封存操作使用独立的 Idempotency-Key;重试同一请求时沿用原值。

将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),并确认项目与凭据属于该环境。

先采纳版本管理。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/version-adoptions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "Idempotency-Key: example-adoption-001" \
  -H "Content-Type: application/json" \
  -d '{"expectedBindingRevision": 0}'
)

采纳完成后读取最新绑定修订号,再创建工作副本。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "Idempotency-Key: example-copy-001" \
  -H "Content-Type: application/json" \
  -d '{"sourceVersionId": "ver_baseline_001", "expectedSourceVersionRevision": 1, "expectedBindingRevision": 1, "label": "support-update"}'
)

工作副本操作完成后,使用回执中的版本 ID 检查就绪状态。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X GET "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_draft_002/readiness" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210"
)

就绪检查通过后,读取最新修订号再封存。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_draft_002/seal" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "Idempotency-Key: example-seal-001" \
  -H "Content-Type: application/json" \
  -d '{"expectedDefinitionRevision": 1, "expectedVersionRevision": 1}'
)

确认已封存并读取最新修订号后,再按需发布。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_draft_002/publish" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "Content-Type: application/json" \
  -d '{"expectedBindingRevision": 1, "expectedVersionRevision": 2}'
)

仅在确需回滚时,读取最新修订号和回滚目标后单独执行。

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/versions/ver_baseline_001/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "Content-Type: application/json" \
  -d '{"expectedBindingRevision": 2, "expectedVersionRevision": 2}'
)

生命周期

一个版本在生命周期中依次经历:

阶段含义
DRAFT工作副本:可编辑的草稿版本,后台复制与校验通过后才出现在版本列表
READY已封存的只读快照:可被发布或作为回滚目标
当前版本(Current)新的版本解析请求默认使用该版本
回滚目标(Rollback)发布时自动保留的上一当前版本,用于一键回滚

DRAFT 经封存变为 READY;READY 经发布成为当前版本;回滚则把保留的回滚目标恢复为当前版本。

状态关系示意(非 Console 截图):

DRAFT ── Seal(Readiness 通过)──> READY ── Publish──> Current
                                           │                 │
                                           │                 └─ 下一个 READY 发布后
                                           │                    保留为 Rollback target
                                           └─ 仍是只读快照

Rollback target ── Rollback──> Current

需要安全发布新内容时,先从 READY 源版本创建工作副本,在 DRAFT 中完成编辑和就绪检查,再封存为 READY。封存不会自动改变线上使用的 Current;确认版本内容后再执行 Publish。

工作副本

在 工作副本 区点击创建工作副本,选择 READY 源版本并填写标签(必填)与描述(可选)。复制在后台进行,页签内按可用信息展示复制进度;校验成功后 DRAFT 才可见,不会影响当前激活版本。仅 queued、preflight、copying、validating 可请求取消;受理后先进入 cancelling,需轮询并等待清理完成。原操作为 failed 或 cancelled、源版本匹配且清理完成后才可重试(retryOf 指向原操作)。

就绪封存(Seal)

DRAFT 需通过就绪检查才能置为 READY。页签展示各版本的 Readiness 摘要与阻塞原因:活动任务未完成、文档未就绪或需按当前配置重建、已启用索引能力待重建或构建失败、Wiki 启用时存在未解决的 Wiki 冲突,都会阻止封存。封存成功后版本变为只读快照,不会自动发布。

发布与回滚

版本删除

仅非当前、非回滚角色的版本可删除。删除为不可逆的异步操作:请求接受后版本立即不可访问,后台分批清理数据;页签内以删除操作展示状态(已排队、删除中、需关注、数据已清理),可查询进度。清理失败的版本保持不可访问,可重试删除。删除完成后版本记录保留为审计痕迹,数据已清除且无法恢复。

保留策略

自动保留设置控制已发布历史版本的保留数量,默认 3 个且不包含当前版本;可以自定义或恢复默认。超出保留数量的候选版本由后台按条件处理,不代表所有 READY 草稿都会自动删除。设为 0 时已发布版本只保留当前版本,后台可能清除回滚目标,之后不能依赖该目标回退。

使用边界

常见问题与排障(FAQ)

Q1:点击「发布(Publish)」或「回滚(Rollback)」时提示修订号冲突(Revision Mismatch / 409 Conflict)怎么办?

Q2:为什么我无法直接选择列表里任意一个更早的历史版本点击「回滚」?

Q3:删除一个历史版本后,还能找回里面的文档分块数据吗?


相关文档