AgentbaseDocs
文档目录

知识库版本管理(Versions)

版本管理(Versions) 是 Agentbase v2.10.0 知识库面向生产环境零停机演进与变更审计打造的不可变快照治理体系。通过知识库详情页的 版本管理(Versions) 页签,团队可以将未启用版本化的存量知识库平滑迁移至版本化管理(版本采纳 Adoption),基于任意就绪快照创建隔离的可编辑工作副本(Working Copy / DRAFT),在副本内安全完成文档增删、分块调优与高级索引构建,通过严格的就绪门禁检查(Readiness Gate)后将其封存(Seal)为不可变只读版本(READY),并一键发布(Publish)切换为线上当前激活版本,或在出现业务异常时秒级回滚(Rollback)至上一保留版本。


功能概述与核心场景

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

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

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。


核心概念与架构

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

flowchart TB
    subgraph LegacyAdoption["0. 存量库版本化采纳 (Version Adoption)"]
        Unversioned["未启用版本化的知识库"]
        AdoptionJob["异步采纳流水线 (POST /version-adoptions)\nqueued -> precheck -> marking -> verifying -> activating\n(在 marking 阶段开始前支持 Cancel 取消)"]
    end

    subgraph DraftPhase["1. 工作副本创建与编辑阶段 (Working Copy)"]
        CreateCopy["创建工作副本 (POST /versions)\n基于源 READY 版本后台复制行/对象/产物并校验\n(复制中可 Cancel,失败可 Retry / retryOf)"]
        DraftState["状态: DRAFT (可编辑草稿版本)\n可安全上传/删除文档、调优分块、构建 GraphRAG/RAPTOR/Wiki、裁决冲突"]
    end

    subgraph ReadinessAndSeal["2. 就绪门禁校验与封存阶段 (Readiness & Seal)"]
        ReadinessGate["就绪检查 (GET /versions/{versionId}/readiness)\n1. 无运行中异步任务\n2. 全部文档 status=ready 且匹配当前配置\n3. 已启用派生索引均构建完成\n4. 无未解决的 Wiki 冲突"]
        SealAction["执行封存 (POST /versions/{versionId}/seal)"]
        ReadyState["状态: READY (不可变只读快照)\n内容彻底冻结,可作为发布源或工作副本基底"]
    end

    subgraph OnlineSwitch["3. 线上原子发布、回滚与生命周期清理"]
        PublishAction["原子发布 (POST /versions/{versionId}/publish)\n校验 expectedRevision 乐观锁"]
        CurrentRole["角色: 当前激活版本 (Current Version)\n承载全部默认线上检索与问答流量"]
        RollbackRole["角色: 回滚目标 (Rollback Target)\n自动保留上一任 Current 版本"]
        RollbackAction["一键回滚 (POST /versions/{versionId}/rollback)\nCurrent 与 Rollback 角色原子互换"]
        DeleteAction["异步版本删除 (DELETE /versions/{versionId})\nqueued -> deleting -> data_cleaned (保留审计记录)"]
    end

    Unversioned --> AdoptionJob --> ReadyState
    ReadyState --> CreateCopy --> DraftState
    DraftState --> ReadinessGate -->|全部通过| SealAction --> ReadyState
    ReadyState --> PublishAction --> CurrentRole
    PublishAction -.->|原 Current 自动降为| RollbackRole
    RollbackRole --> RollbackAction --> CurrentRole
    ReadyState -->|非 Current 且非 Rollback| DeleteAction

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

概念类别标识名称详细含义与约束规则
版本状态DRAFT可编辑工作副本:后台复制与完整性校验通过后出现在版本列表中,允许增删改文档、分块与派生索引。
版本状态READY已封存只读快照:通过 Readiness 检查并执行 Seal 后的不可变版本。任何针对 READY 版本的写操作均被拒绝。
版本状态DELETING / CLEANED异步删除中 / 数据已清理:触发删除后立即不可访问,后台分批物理清除底层向量与分块数据,仅保留版本元数据作审计痕迹。
版本角色Current(当前版本)当客户端调用检索或问答接口且未显式指定版本时,默认路由命中的线上激活版本。
版本角色Rollback(回滚目标)每次执行 Publish 发布新版本时,系统自动将替换下来的前一个 Current 版本标记为唯一的回滚目标,支持秒级回退。
乐观锁修订号bindingRevision知识库版本指针绑定关系的递增修订号。调用 Publish 或 Rollback 时必须传入当前看到的修订号,防止并发覆盖。
保留策略retentionCount自动保留的历史 READY 版本数量上限(默认保留 3 个),超出保留数的旧版本按策略自动触发清理。

功能入口与权限矩阵

控制台入口、REST API、SDK 方法与权限矩阵

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

功能详解与操作指南

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

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


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

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


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

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

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

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


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

# 1. 对存量知识库发起版本采纳 (POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/version-adoptions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 2. 基于指定 READY 源版本创建 DRAFT 工作副本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVersionId": "ver_baseline_001",
    "label": "v2.10.0-q4-support-upgrade",
    "description": "Q4 客服排障手册与 Wiki 升级副本"
  }'

# 3. 查询 DRAFT 版本的就绪门禁检查报告 (GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness)
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/readiness" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 4. 就绪检查通过后封存为 READY 快照 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/seal" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 5. 发布 READY 版本为线上当前激活版本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/publish" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 1
  }'

# 6. 紧急回滚至保留的上一版本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_baseline_001/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 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。

工作副本

在 Working copies 区点击创建工作副本,选择 READY 源版本并填写标签(必填)与描述(可选)。复制在后台进行,页签内展示行数、对象数、产物与字节的复制进度;校验成功后 DRAFT 才可见,不会影响当前激活版本。复制未完成前可取消(私有副本被清理,不会生成可见 DRAFT);失败或取消的操作可重试(retryOf 指向原操作)。

就绪封存(Seal)

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

发布与回滚

版本删除

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

保留策略

自动保留设置控制保留的历史版本数(默认保留 3 个),可自定义或恢复默认;超出保留数的版本按策略清理。

使用边界

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

常见问题与排障(FAQ)

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

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

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


相关文档