qdrant-version-upgrade

Qdrant 版本升级

Qdrant 对版本兼容性作出以下保证：

• Qdrant 和 SDK 的主版本与次版本预计应保持一致。例如，Qdrant 1.17.x 与 SDK 1.17.x 兼容。

• 客户端 SDK 经过测试，可向后兼容 Qdrant 最新的 3 个次版本。例如，SDK 1.17.x 可与 Qdrant 1.15.x 至 1.17.x 搭配使用，但只能使用服务器版本支持的功能。升级

• 迁移到下一个次版本时，建议先将 SDK 升级到下一个次版本，再升级 Qdrant 服务。

• 存储兼容性仅保证覆盖一个次版本。例如，使用 Qdrant 1.16.x 存储的数据预计与 Qdrant 1.17.x 兼容。如果需要跨越一个以上的次版本迁移，则必须逐步升级，每次升级一个次版本。例如，从 1.15.x 迁移到 1.17.x，需要先升级到 1.16.x，再升级到 1.17.x。注意：Qdrant Cloud 会自动完成此过程，因此你可以直接从 1.15.x 升级到 1.17.x，无需中间步骤。

• 复制因子为 2 或更高的 Qdrant 集群可以通过滚动升级实现无停机升级。这意味着你可以一次升级一个节点，同时由其他节点继续处理请求。这样可以在升级过程中保持应用程序可用。有关复制因子的更多信息：复制因子

要在 Qdrant Cloud 中管理 Qdrant 版本升级，可以使用 qcloud 命令行工具。

升级前检查清单

1. 首先备份：建议在更新前创建备份或快照，以便回滚。如果升级失败或需要恢复，你可以还原升级前的快照。Qdrant Cloud 会在升级期间执行数据迁移，因此无法在线降级。快照 Cloud 备份

2. 查看发行说明，了解默认设置和行为的变化，而不只是弃用信息。版本升级可能会改变默认设置、验证规则或查询行为，即使 API 保持兼容，也可能影响现有工作负载。

3. 先在非生产环境中使用目标服务器版本测试客户端应用，并在切换前查看 SDK 发行说明，确认是否有已弃用或已移除的方法。

4. 建议每个节点至少运行 2 个 CPU 核心。升级期间，Qdrant 可能会在处理常规操作的同时执行后台优化。如果只有 1 个核心，这些任务会争用 CPU 资源，可能显著拖慢升级过程。

5. 如果需要零停机滚动升级，请使用复制因子 2 或更高的配置。复制因子为 1 时，升级需要安排停机时间。

跨越多个次要版本

适用场景：当前运行的版本比目标版本落后两个或更多次要版本。

• 可自托管：逐一升级到每个中间次要版本，并先升级到该版本的最新补丁版，再继续下一步。从 1.15 升级到 1.17 时，先升级到最新的 1.16.x，再升级到 1.17.x。升级 Qdrant
• 每一步都需要单独进行滚动重启，因此总耗时是单版本升级耗时的倍数。升级耗时比只升级一个版本更长，因此请做好规划，并尽量选择非高峰时段。
• Qdrant Cloud 会自动为你逐步完成中间版本的更新，因此从 1.15.x 升级到 1.17.x 只需执行一次操作。更新 Qdrant Cloud 集群
• 定期升级，以确保今后每次只需跨越一个次要版本。定期升级还可以避免大幅跨版本升级，从而降低未来迁移的复杂度。

升级后出现行为变化时的故障排查

适用场景：新版本上线后，结果、评分或延迟与之前不同。

• 调查升级后出现的错误或异常行为时，请检查源版本与目标版本之间的发布说明/变更日志，了解可能影响工作负载的弃用项、默认值变更和行为变更。

• 将相对排名和召回率与升级前的基线进行比较，而非比较绝对评分值。不同版本的评分内部机制可能发生变化，但结果仍然正确。

请勿执行的操作

• 将绝对评分完全一致作为跨版本验收标准
• 只阅读目标版本的说明，跳过中间的次要版本和补丁版本
• 在可自托管的部署中一次跨越多个次要版本
• 未确认每个节点都报告目标版本，就认定滚动升级已完成