Docs
文档目录

版本管理

这是什么 / 何时用

2.8.0 起知识库支持多版本:以 READY 版本为源创建工作副本(异步复制为隔离 DRAFT)→ 就绪检查通过后 Seal 为只读 READY → Publish 切换为当前激活版本,Rollback 则恢复保留的回滚目标;未启用版本化的库先走 Adoption 采纳。所有写路径携带预期修订号做并发保护,操作类变更为异步(幂等键 + 轮询)。产品语义与 Console 入口见版本管理(产品手册)。

使用骨架

  1. 列出与读取:listVersions(knowledgeBaseId, limit, cursor, status, role)(limit、cursor、status、role 均可选) 分页取版本(status 过滤 draft / ready,role 过滤 current / rollback / none),getVersion 读单个版本;列表不包含仍在物化的工作副本。

  2. 创建工作副本:createVersion({ knowledgeBaseId, sourceVersionId, expectedSourceVersionRevision, expectedBindingRevision, label, description, retryOf })(description、retryOf 均可选) 返回 KnowledgeBaseWorkingCopyOperation——校验成功前 DRAFT 不可见,用 listWorkingCopyOperations / getWorkingCopyOperation 轮询,cancelWorkingCopyOperation 请求取消。

  3. 就绪检查与封存:getVersionReadiness 返回 sealable 与阻塞原因;sealVersion(携带 expectedDefinitionRevision + expectedVersionRevision + 幂等键)把 DRAFT 置为 READY,不自动发布。

  4. 发布与回滚:publishVersion / rollbackVersion(均携带 expectedBindingRevision + expectedVersionRevision)原子切换 currentVersionId / rollbackVersionId,返回 KnowledgeBaseVersion。

  5. 删除:deleteVersion({ knowledgeBaseId, versionId, expectedVersionRevision }) 发起不可逆异步清理,返回 KnowledgeBaseVersionDeleteOperation;getVersionDeleteOperation 轮询至 completed。CURRENT / ROLLBACK 角色的版本不可删除。

  6. 采纳:createVersionAdoption({ knowledgeBaseId, expectedBindingRevision, retryOf })(retryOf 可选) 为未版本化库启动采纳(返回 202 + operation);listVersionAdoptions / getVersionAdoption 查询,cancelVersionAdoption(携带 expectedOperationRevision)仅在版本标记开始前可取消。

关键参数与返回

错误与边界

各语言调用示例

以下代码块是独立步骤:先初始化 client、kb,读取目标知识库 base 和源 READY 版本 ready(Node.js 中为 readyVersion)。REST 的 APPBASE_ENDPOINT 包含 /v1;替换所有占位符及修订号,确保项目和凭据属于目标环境。创建与封存使用不同的稳定幂等键;SDK 的客户端头对后续请求持续生效。

  1. 创建工作副本。

client.addHeader('Idempotency-Key', '<CREATE_KEY>');
const op = await kb.createVersion({ knowledgeBaseId: base.$id,
  sourceVersionId: readyVersion.$id, expectedSourceVersionRevision: readyVersion.versionRevision,
  expectedBindingRevision: base.bindingRevision, label: 'draft-v2' });
console.log(op.$id);
  1. 查询该操作;只有 succeeded 才从结果的 result.versionId 取得 versionId / version_id。failed、cancelled 时停止;其他状态稍后再查询。

const st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
if (st.status !== 'succeeded') throw new Error(`Working copy is ${st.status}; check again or inspect the failure`);
const result = st.result as { versionId?: unknown };
if (typeof result?.versionId !== 'string' || !result.versionId) throw new Error('Operation did not return a version ID');
const versionId = result.versionId;
console.log(versionId);
  1. 先查询版本 readiness,确认 sealable 为 true 后再执行封存。REST 先调用版本 /readiness 获取最新修订号,并用返回值替换下面的示例数字。

const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId });
if (!readiness.sealable) throw new Error('Version is not ready to seal');
client.addHeader('Idempotency-Key', '<SEAL_KEY>');
const sealed = await kb.sealVersion({ knowledgeBaseId: base.$id, versionId,
  expectedDefinitionRevision: readiness.definitionRevision,
  expectedVersionRevision: readiness.versionRevision });
console.log(sealed.$id, sealed.versionRevision);
  1. 只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。

const latest = await kb.get({ knowledgeBaseId: base.$id });
const published = await kb.publishVersion({ knowledgeBaseId: base.$id, versionId: sealed.$id,
  expectedBindingRevision: latest.bindingRevision, expectedVersionRevision: sealed.versionRevision });
console.log(published.$id);