Alauda Hyperflux
  • 简体中文

    • 升级

    本文档提供了将 Alauda Hyperflux 升级到新版本的说明。

    目录

    标准升级步骤从 v1.3.x 升级到 v1.4.x（Embedding Model 切换）升级会自动执行的操作推荐的升级前备份执行升级验证升级特殊情况：您维护了自定义知识库从 v1.2.0 升级到 v1.2.1（特殊情况）步骤 1：备份知识库步骤 2：执行升级步骤 3：恢复知识库

    标准升级步骤

    对于大多数版本升级（v1.2.0 → v1.2.1 和 v1.3.x → v1.4.x 除外），您只需在 ACP 控制台中按照以下步骤操作：

    1. 将新版本的插件包上架到 ACP Marketplace。 按照首次安装时相同的方式上传软件包。 上传完成后，请等待大约 10–15 分钟，让平台自动同步新版本信息。
    2. 确认新版本已在 Marketplace 中可用。 进入 Administrator / Marketplace / Upload Packages。 切换到 Cluster Plugin 选项卡，确认 Hyperflux 插件已显示新版本号。
    3. 在集群上执行升级操作。 导航到 Administrator / Clusters / Clusters。 找到已安装 Hyperflux 插件的集群；集群条目中会显示升级图标。 点击进入集群详情，然后切换到 Features 选项卡。 在 Hyperflux 插件卡片上，点击 Upgrade 按钮并确认操作。
    4. 验证升级结果。 升级完成后，请在 Features 选项卡中确认版本号已更新。 通过插件状态监控或日志验证其正常运行。

    从 v1.3.x 升级到 v1.4.x（Embedding Model 切换）

    重要： v1.4.0 提供了新的 embedding model（gte-multilingual-base，替换 paraphrase-multilingual-mpnet-base-v2）。向量空间不兼容，因此系统知识库 必须重新嵌入。chart 会在升级过程中自动执行此操作——但在应用升级前请先阅读本节， 尤其是您构建了自定义知识库的情况下。

    升级会自动执行的操作

    当新 chart 部署后，init container 会扫描 docvec_sys_kb 中是否存在与 smartdoc.acpKbUpgradeRules 中规则匹配的旧 mpnet collection（默认：ACP 4.1 和 ACP 4.2 的 mpnet collection），然后：

    1. 获取一个以 acpKbDataVersion 为键的 PostgreSQL advisory lock，以确保第二个 replica 的 init 能正常退出。
    2. 将进行中的切换记录到 kb_swap_state 行中（以便在 pod 在切换过程中被终止时能够恢复）。
    3. 删除 docvec_sys_kb 中的 langchain_pg_embedding 和 langchain_pg_collection 表。
    4. 从 /workspace-smart-doc/dumps/ 执行新的 gte dump 的 pg_restore（可接受关于已存在的 extensions/ schemas 的警告；硬错误会中止）。
    5. 验证新的 collection 名称已写入（SELECT count(*) ... = 1）；否则中止。
    6. 将新的 collection 重命名回旧的 collection 名称，以便运行中的 server 继续查询相同的 名称。您无需修改 pgconnect.pgCollectionName。
    7. 如果新的 dump 中未包含 ParadeDB BM25 index，则重新构建该 index（较新的 gte dumps 已包含）。
    8. 使用 003_data_swap_<old_collection>_<acpKbDataVersion> 为 schema_migrations 打上标记，并清除 正在进行中的 kb_swap_state 行。
    9. 在切换块返回后，无条件的迁移循环会针对刚恢复的表重新应用 doc_id btree （001_add_doc_id_index）以及 URL 回填（002_backfill_doc_id_from_url）——切换块会清除它们的标记，因此循环会将它们视为“未应用”并执行。

    该切换具有以下特性：

    • 幂等 — 如果 re-roll 时 acpKbDataVersion 未变化，则不会产生任何操作。
    • 崩溃安全 — 在 DROP 和 RESTORE 之间如果 pod 被终止，可在下次启动时恢复。
    • 多 replica 安全 — 以 acpKbDataVersion 为键的 PostgreSQL advisory lock 会对切换过程进行串行化。

    推荐的升级前备份

    该切换会删除旧 collection 并用新数据替换；旧的 mpnet 向量不会保留。 尽管随包提供的 dump 是可复现的，仍建议在升级前备份 docvec_sys_kb 和 docvec_user_kb， 以便在出现问题时回滚：

    # Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump both knowledge-base databases. The default password for the built-in PostgreSQL
# instance is `alauda-test`; pg_dump will prompt for it. To suppress the prompt, prefix
# with `PGPASSWORD=alauda-test ` inside the exec.
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_sys_kb -f /tmp/docvec_sys_kb.backup.dump
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_user_kb -f /tmp/docvec_user_kb.backup.dump

# Copy them to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_sys_kb.backup.dump ./docvec_sys_kb.backup.dump
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_user_kb.backup.dump ./docvec_user_kb.backup.dump

    docvec_user_kb 和聊天历史数据库 不会 被该切换影响——但备份总是一个低成本的保险措施。

    执行升级

    按照上面的 标准升级步骤 操作。当 smart-doc pod 在新版本上首次重启时， init container 会自动执行切换。

    验证升级

    查看 init container 日志尾部，确认切换已完成：

    kubectl -n cpaas-system logs -l app=smart-doc -c init-database | grep '\[upgrade\]'

    成功的切换会输出如下内容：

    [upgrade] swap docvec_mpnet_acp_4_1_1215 (in docvec_sys_kb) -> dump docvec_gte_acp_4_1_20260508.dump; final name=docvec_gte_acp_4_3_20260508
[upgrade] 003_data_swap_docvec_mpnet_acp_4_1_1215_20260508-gte-acp-4-x applied.

    切换完成后的 re-roll 不会再输出任何 [upgrade] 行——规则扫描不会找到匹配的 collection（在第 6 步中 OLD 名称已重命名为 pgconnect.pgCollectionName），因此切换块会静默退出。后续 re-roll 中没有日志行属于预期的切换后状态。

    [upgrade] ... already applied, skipping. 这一行保留给恢复场景：当某个 kb_swap_state 行对应的标记已经应用，但 inflight 行尚未清除时（例如，pod 在标记写入后但 在 inflight 行清除前被终止）。这不是正常的幂等 re-roll 输出。

    当 smart-doc pod 变为 Ready 后，在 chat UI 中运行一个具有代表性的问题，以确认答案是基于新的语料库生成的。

    特殊情况：您维护了自定义知识库

    如果您之前按照 Build a Custom Knowledge Base 使用 v1.3.x 的 mpnet model， 则自定义 collection 中的向量与 v1.4.0 server 不兼容。您必须：

    1. 在升级前： 使用 gte-multilingual-base 重新构建自定义 KB（请参见链接的指南）。
    2. 将随包提供的 acpKbUpgradeRules 替换为仅针对自定义 collection 的单条规则： 
      smartdoc:
  acpKbDataVersion: "20260512-custom-gte"  # bump to re-arm the swap
  acpKbUpgradeRules: |
    <your_mpnet_collection_name>  <your-gte-collection-name>.dump  <your-gte-collection-name>
      这里不适用随包提供的 ACP 规则——自定义 KB 部署在 v1.3.x 中已经替换了这些 collection，因此随包提供的 OLD 名称不会匹配。保留它们在规则列表中不会有害，但会显得冗余。
    3. 应用升级。

    注意： init container 每次运行只处理 在 docvec_sys_kb 中找到的第一条 OLD collection 规则，然后退出切换块。DROP 并恢复会清空整个 langchain_pg_collection 表，因此该 chart 一次只支持一个 system-KB collection。如果您 需要同时保留自定义语料库和随包提供的 ACP 语料库，请在同一次 prepare 运行中导入它们 （请参见 build-custom-kb 指南中的 Caveats），并提供一个单独的合并 dump。

    如果跳过步骤 1，chart 仍然可以升级，但针对旧的自定义 collection 的检索将返回零命中，答案会回退为“我没有足够的信息”。

    从 v1.2.0 升级到 v1.2.1（特殊情况）

    重要： 从 v1.2.0 升级到 v1.2.1 会导致知识库重新初始化。您必须手动备份并恢复数据库，以防止数据丢失。

    步骤 1：备份知识库

    在执行升级之前，请运行以下命令：

    # Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump the database to a file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -d <your-database-name> -F c -f /tmp/hyperflux_backup.dump

# Copy the dump file to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/hyperflux_backup.dump ./hyperflux_backup.dump

    步骤 2：执行升级

    按照上文所述的 标准升级步骤，通过 ACP 控制台升级插件版本。

    步骤 3：恢复知识库

    升级完成后，恢复您的数据：

    # Get the new PostgreSQL pod name
kubectl -n cpaas-system get pod | grep postgre-vec

# Copy the backup dump file back to the pod
kubectl -n cpaas-system cp ./hyperflux_backup.dump <postgre-vec-xxx>:/tmp/hyperflux_backup.dump

# Restore the database from the dump file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_restore -U postgres -d <your-database-name> /tmp/hyperflux_backup.dump

# (Optional) Update configuration if your database/collection name changed
kubectl -n cpaas-system edit configmap smart-doc-config
# Update `PG_CONN_DB` and `PG_COLLECTION_NAME` fields if necessary.
# (Env-var rename: `PG_CONN_DB` was split into `PG_SYS_KB_DB` / `PG_HISTORY_DB` /
#  `PG_USER_KB_DB` in later versions. For a v1.4.x upgrade, see the embedding-switch
#  section above instead — the chart handles the data swap automatically.)

    等待 Alauda Hyperflux pods 重启，并确认知识库已成功恢复。