Knowledge Base Version Management (Versions)
Version Management (Versions) is an immutable snapshot governance system built into the Agentbase v2.10.0 knowledge base for zero-downtime production evolution and change auditing. Through the Version Management (Versions) tab on the knowledge base detail page, teams can smoothly migrate existing non-versioned knowledge bases to versioned management (Version Adoption), create isolated editable working copies (Working Copy / DRAFT) from any ready snapshot, safely complete document additions/deletions, chunk tuning, and advanced index building inside the copy, and after passing the strict Readiness Gate check seal (Seal) it as an immutable read-only version (READY), then with one click publish (Publish) to switch it to the currently active online version, or in the event of a business anomaly roll back (Rollback) to the previous retained version within seconds.
Feature overview and core scenarios
In an enterprise intelligent customer service production environment (e.g., kb_enterprise_support), if knowledge operations staff directly delete documents in bulk, upload unverified new documents, or trigger a lengthy full-repository reindex on a live knowledge base that is actively serving Q&A, online retrieval may suffer missing results, chunk discontinuities, or contradictory answers during the change window.
Agentbase's knowledge base version management draws on the best practices of modern cloud-native databases and software release engineering to provide the following core capabilities:
Smooth version adoption (Version Adoption,
POST /version-adoptions):For knowledge bases without version management enabled, an asynchronous adoption operation can be initiated with one click; without interrupting existing read traffic, it completely seals existing documents, chunks, vectors, and derived indexes as the first baseline immutable version (e.g.,
v1).
Copy-on-Write isolated working copies (Working Copy,
POST /versions):Create a draft copy (
DRAFT) from any historical version inREADYstatus. The draft copy only becomes publicly visible after the backend asynchronously completes row-, object-, artifact-, and byte-level copying and integrity verification; the entire copy and edit process has zero interference with the currently active online version (Current Version).
Four-fold strict Readiness Gate (
GET /versions/{versionId}/readiness) and Seal:To seal a draft copy as a
READYsnapshot, it must pass automated Readiness checks (ensuring no unfinished tasks, all documents arereadyand need no rebuild, all enabledGraphRAG/RAPTOR/Wikiindexes are built and ready, and there are no unresolved Wiki conflicts).
Optimistic-lock-protected atomic publish (Publish) and one-click rollback (Rollback):
The publish operation atomically switches the specified
READYversion to the currently active version and automatically converts the previous active version into the sole rollback target (Rollback Target).Both publish and rollback mandatorily validate the expected binding revision (Expected Binding Revision) to guard against concurrent change conflicts by multiple users.
Automatic retention policy (Retention Policy) and irreversible safe cleanup:
Supports configuring the number of historical versions to retain automatically (default retains
3), and supports launching asynchronous safe cleanup of redundant versions that are neither current nor rollback targets.
Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.
Core Concepts and Architecture
Knowledge Base Immutable Version Lifecycle State Machine
Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.
View the flow diagram in full size
Version Status, Roles, and Core Concepts Table
| Concept Category | Identifier Name | Detailed Meaning and Constraint Rules |
|---|---|---|
| Version status | DRAFT | Editable working copy: appears in the version list after backend copying and integrity verification pass; allows adding, deleting, and modifying documents, chunks, and derived indexes. |
| Version status | READY | Sealed read-only snapshot: an immutable version created after passing Readiness checks and executing Seal. Any write operation against a READY version is rejected. |
| Version status | DELETING / CLEANED | Asynchronously deleting / data cleaned up: inaccessible immediately after deletion is triggered; the backend physically clears underlying vector and chunk data in batches, retaining only version metadata as an audit trail. |
| Version role | Current(当前版本) | The currently active online version hit by default routing when a client calls a retrieval or Q&A endpoint without explicitly specifying a version. |
| Version role | Rollback(回滚目标) | Each time Publish publishes a new version, the system automatically marks the replaced previous Current version as the sole rollback target, supporting second-level rollback. |
| Optimistic-lock revision number | bindingRevision | The incrementing revision number of the knowledge base version pointer binding. When calling Publish or Rollback, the currently observed revision number must be passed in to prevent concurrent overwrites. |
| Retention policy | retentionCount | The upper limit on the number of historical READY versions retained automatically (default retains 3); old versions beyond the retention count automatically trigger cleanup according to policy. |
Feature Entrypoints and Permission Matrix
Console Entry Points, REST API, SDK Methods, and Permission Matrix
| Console entrypoint / feature module | Frontend route path | Corresponding REST API endpoint | Server SDK method (Node.js / Python) | Required RBAC role / API Key scope | Cross-module dependency |
|---|---|---|---|---|---|
| Versioning adoption (Adoption) for existing knowledge bases | /console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/versions (the "Adopt Versioning" wizard) | POST /v1/knowledgebases/{kbId}/version-adoptions | knowledgeBase.adoptVersioning() | Roles: owner, admin, developerScope: knowledgebases.write | Seal existing documents, chunks, vectors and derived indexes as the first READY version |
Create a DRAFT working copy from a READY version | /console/.../kb-kb_enterprise_support/versions (click "Create working copy") | POST /v1/knowledgebases/{kbId}/versionsGET /v1/knowledgebases/{kbId}/versions | knowledgeBase.createVersion()knowledgeBase.listVersions() | Roles: owner, admin, developerScope: knowledgebases.write | Copy-on-write isolation for document, data source, advanced index and Wiki edits |
| Readiness Gate validation and sealing (Seal) | Expand "Readiness" and "Seal" buttons in the version list | GET /v1/knowledgebases/{kbId}/versions/{versionId}/readinessPOST .../versions/{versionId}/seal | knowledgeBase.getVersionReadiness()knowledgeBase.sealVersion() | Roles: owner, admin, developerScope: knowledgebases.write | Enforces verification that no tasks are running, all documents are ready, advanced indexes are built, and there are no unresolved Wiki conflicts |
| Atomic publish and one-click rollback (Rollback) | "Publish" in the version list and "Rollback" at the top | POST /v1/knowledgebases/{kbId}/versions/{versionId}/publishPOST .../versions/{versionId}/rollback | knowledgeBase.publishVersion()knowledgeBase.rollbackVersion() | Roles: owner, admin (and authorized publishers)Scope: knowledgebases.write | Validates expectedBindingRevision optimistic locking and atomically switches the default version hit by live hybrid retrieval |
| Asynchronous safe cleanup of historical versions | "Delete" action on non-Current/Rollback rows in the version list | DELETE /v1/knowledgebases/{kbId}/versions/{versionId} | knowledgeBase.deleteVersion() | Roles: owner, adminScope: knowledgebases.write | The backend physically reclaims underlying vectors, chunks and knowledge graph storage in batches while retaining audit records |
Feature Details and Operation Guide
Step One: Enabling versioning for an existing knowledge base: version adoption (POST /version-adoptions)
If the knowledge base was created in an earlier release or versioning governance has not yet been enabled, you will see the "Adopt Versioning" wizard card when you first open the Versions tab:
Click the Adopt Versioning (Adopt Versioning) button (or call
POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions).The system starts an asynchronous adoption pipeline and displays five convergence phases in real time in the UI:
排队中(queued)->环境预检(precheck)->数据标记(marking)->完整性验证(verifying)->正式激活(activating)。Cancellation window constraint: before entering the
marking(data marking) phase, an administrator can click Cancel at any time to abort adoption; once marking begins, the system will automatically complete the subsequent verification and activation to ensure data consistency.
After adoption completes, all existing knowledge base content automatically becomes the first immutable
READYandCurrentbaseline version.
Step Two: Creating a working copy (POST /versions) and completing incremental revisions
When you need to add quarterly troubleshooting guidelines to kb_enterprise_support or adjust the chunking strategy, the standard workflow is as follows:
In the Working copies area of the Versions tab, click Create working copy (Create working copy).
Fill in the working copy creation form:
Source Version: select the baseline version currently in the
READYstate (e.g.,v1.0-baseline).Version label (Label, required and unique within the knowledge base): for example,
v2.10.0-q4-support-upgrade.Version description (Description, optional): for example,
新增 AI 网关限流规范并完成 10 篇 Wiki 页面重编译.
After clicking Create, the backend starts asynchronously copying the source version's documents, chunks, vectors and derived index artifacts, and the UI displays a real-time copy progress bar showing row count, object count, artifact count and byte count:
Until the copy completes, the copy will not appear in the official version list in a half-finished state, and you can click Cancel (after cancellation, private half-finished data is automatically and thoroughly purged).
If the copy fails due to transient storage jitter or is cancelled, you can directly click Retry (at the API layer,
retryOfis automatically linked to the original operation ID).
After copy verification completes and the copy status becomes
DRAFT, select thatDRAFTversion in the top version switcher and go to the Documents, knowledge index and Wiki tabs to complete new document ingestion and index updates.
Step Three: Checking the Readiness Gate and performing sealing (POST /versions/{versionId}/seal)
Before a DRAFT working copy is sealed as a READY snapshot, the system enforces four readiness gate checks. In the Versions tab, expand the Readiness Summary for the DRAFT version and verify that all four of the following metrics are green and passing:
| Readiness check item | Typical causes of Seal Blocked | Resolution and remediation |
|---|---|---|
1. Active task check (activeOperations) | The current version still has document ingestion, data source sync or index build tasks queued or running | Wait for the asynchronous tasks to finish, or manually cancel unneeded tasks |
2. Document readiness and configuration consistency (documentsReadiness) | Documents in failed / processing state exist, or default chunking parameters were modified but a rebuild has not been run on existing documents | Fix failed documents and trigger Re-ingest or a full-knowledge-base Reindex, ensuring all documents are ready |
3. Derived index integrity (indexCapabilitiesReadiness) | The GraphRAG, RAPTOR or Wiki switch is enabled, but the latest document changes have not finished building or the build failed | Go to the Indexes tab and click Build until the status becomes completed |
4. Zero Wiki conflicts (wikiConflictsReadiness) | The current version has unresolved cross-document Wiki knowledge conflict tickets | Go to Wiki -> Conflicts and resolve each conflict (Resolve) one by one |
When all four checks above pass (readyToSeal = true), click the Seal button to the right of that version. The version status immediately changes from DRAFT to the immutable READY (note: sealing only freezes the snapshot and does not automatically publish it as the live current version).
Step Four: Performing atomic publish, one-click rollback (Rollback) and REST API operations
Publishing a new version (Publish):
In the version list, locate the
v2.10.0-q4-support-upgradealready in theREADYstate and click Publish.After confirming the dialog, that version immediately becomes the new Current, and all live retrieval requests sent to
kb_enterprise_supportand agent workbench Q&A seamlessly switch to the new version; meanwhile, the original current version is automatically retained as the sole Rollback Target.
One-click rollback on anomaly (Rollback):
If, after a new version goes live, business feedback indicates that retrieval quality does not meet expectations, click Rollback at the top of the Versions tab; the system immediately restores the retained rollback target as the currently active version, and swaps the just-retired version in as the new rollback target.
Complete version lifecycle REST API call example:
# 1. Initiate version adoption for an existing knowledge base (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. Create a DRAFT working copy from the specified READY source version (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. Query the readiness gate check report of the DRAFT version (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. After the readiness check passes, seal as a READY snapshot (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. Publish the READY version as the currently active online version (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. Emergency rollback to the retained previous version (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
}'Lifecycle
A version passes through the following stages in its lifecycle:
| Stage | Meaning |
|---|---|
| DRAFT | Working copy: an editable draft version; it appears in the version list only after the backend copy and verification pass |
| READY | Sealed read-only snapshot: can be published or used as a rollback target |
| Current | New version resolution requests use this version by default |
| Rollback Target (Rollback) | The previous current version automatically retained at publish time, used for one-click rollback |
A DRAFT becomes READY via sealing; a READY becomes the current version via publishing; rollback restores the retained rollback target as the current version.
State relationship diagram (not a Console screenshot):
DRAFT ── Seal(Readiness 通过)──> READY ── Publish──> Current
│ │
│ └─ 下一个 READY 发布后
│ 保留为 Rollback target
└─ 仍是只读快照
Rollback target ── Rollback──> CurrentTo safely publish new content, first create a working copy from a READY source version, complete edits and readiness checks in DRAFT, then seal it as READY. Sealing does not automatically change the live Current; confirm the version content before executing Publish.
Working copies
In the Working copies area, click Create working copy, select a READY source version and fill in the label (required) and description (optional). Copying happens in the background, and the tab shows copy progress for rows, objects, artifacts and bytes; the DRAFT becomes visible only after verification succeeds, without affecting the currently active version. Before copying completes, you can cancel (the private copy is cleaned up and no visible DRAFT is generated); failed or cancelled operations can be retried (retryOf points to the original operation).
Readiness sealing (Seal)
A DRAFT must pass readiness checks before it can be set to READY. The tab shows the Readiness summary and blocking reasons for each version: unfinished active tasks, documents not ready or requiring rebuilds under the current configuration, enabled index capabilities pending rebuild or failed builds, and unresolved Wiki conflicts all block sealing. After sealing succeeds, the version becomes a read-only snapshot and is not automatically published.
Publish and rollback
Publish: switches a READY version to the currently active version; subsequent version resolution requests use the new current version, and the previous current version is automatically retained as the sole rollback target.
Rollback: restores the retained rollback target as the current version; the original current version becomes the new rollback target. You cannot designate an arbitrary historical version as the rollback target.
Version deletion
Only versions that are neither current nor in the rollback role can be deleted. Deletion is an irreversible asynchronous operation: once the request is accepted, the version becomes immediately inaccessible, and the backend cleans up data in batches; the tab shows the deletion operation status (queued, deleting, needs attention, data purged), and progress can be queried. Versions whose cleanup fails remain inaccessible, and deletion can be retried. After deletion completes, the version record is retained as an audit trail; the data is purged and cannot be recovered.
Retention policy
The auto-retention setting controls how many historical versions are retained (default is 3); it can be customized or restored to default; versions beyond the retention count are cleaned up according to policy.
Usage boundaries
Publish and rollback require that the expected bound revision number submitted matches the current one; concurrent version status changes by others will be rejected — refresh the page to see the latest status and retry.
Deleted versions cannot be recovered: once a version enters the deletion process it is inaccessible, and after the data is purged it cannot be retrieved.
The version list only shows committed versions; working copies still undergoing copy verification will not appear as half-finished DRAFTs.
Labels must be unique; creating a working copy with an identical label will be rejected.
Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.
FAQ (Frequently Asked Questions and Troubleshooting)
Q1: What should I do when clicking "Publish" or "Rollback" reports a revision conflict (Revision Mismatch / 409 Conflict)?
Root cause analysis: Publish and rollback operations are protected by
expectedBindingRevisionoptimistic locking. After you open the page, if another administrator on your team has just published or rolled back a version, the server-side current bound revision number has incremented, and your stale page request will be safely rejected to prevent accidental overwrites.Resolution: Simply refresh the current page (or call
GET /v1/knowledgebases/{kbId}/versionsagain) to fetch the latest version status andbindingRevision, confirm everything is correct, and then execute the publish or rollback operation again.
Q2: Why can't I directly select any earlier historical version in the list and click "Rollback"?
Root cause analysis: To ensure determinism and extremely fast convergence of the production emergency rollback path, Agentbase specifies that the rollback operation only targets the single "Rollback Target" version automatically retained at release time (i.e., the immediately preceding
Currentversion).Resolution: If you want to switch the live environment back to an earlier historical
READYversion (rather than the current Rollback Target), you simply need to publish (Publish) that historicalREADYversion directly (POST .../versions/{versionId}/publish), which atomically sets it as the currently active version.
Q3: After deleting a historical version, can the document chunk data inside it be recovered?
Root cause analysis: Version deletion is an irreversible asynchronous physical cleanup operation (it can only be initiated on versions that are neither
CurrentnorRollbackroles). Once the request is accepted, the version immediately becomes inaccessible, and a background Worker physically purges its associated underlying chunks, vectors, and derived index data in batches.Resolution: After cleanup completes, the list retains only a lightweight audit record marked "Data Cleaned (
data_cleaned)"; the data itself cannot be recovered. Before deleting a critical milestone version, please confirm it is no longer needed as a working copy base.
Related Documentation
External data source integration and incremental sync with Yuque
GraphRAG, RAPTOR, and Advanced Knowledge Index Build Governance
Knowledge Graph Visualization Exploration and Community Reports
Knowledge Base Wiki Compilation, Conflict Adjudication, and Memory Export
Project-level lexicons and retrieval/knowledge graph/agent collaborative governance
Knowledge Base Settings Hub, Default Policies, and Multimodal Image Understanding (VLM)

