升级 Qdrant 服务端与 SDK…

在需要升级 Qdrant 服务端或 SDK 时，按版本兼容规则、预升级检查清单和逐版本迁移步骤安全升级，避免停机与数据损坏。

适用场景

解决思路

1. 遵循版本兼容规则：Qdrant 与 SDK 的主次版本应匹配（如 Qdrant 1.17.x 对应 SDK 1.17.x）；次版本间测试了向后兼容（如 Qdrant 1.17.x 兼容 SDK 1.16.x，Qdrant 1.16.x 也兼容 SDK 1.17.x，但仅限 1.16.x 已有的功能子集）。
2. 迁移到下一个次版本时，先升级 SDK 到下一个次版本，再升级 Qdrant 服务端。
3. 存储兼容性仅保证跨一个次版本（如 1.16.x 的数据兼容 1.17.x）；若需跨多个次版本迁移，必须逐次版本升级（如从 1.15.x 到 1.17.x，先升到 1.16.x 再升到 1.17.x）。注意 Qdrant Cloud 会自动处理该过程，可直接从 1.15.x 升到 1.17.x。
4. 副本因子（replication factor）为 2 或更高的 Qdrant 集群可通过滚动升级实现零停机：一次升级一个节点，其他节点继续处理请求，从而在升级期间保持应用可用。
5. 在 Qdrant Cloud 中管理版本升级可使用 qcloud CLI 工具（https://github.com/qdrant/qcloud-cli）。
6. 预升级检查清单第 1 项：先备份。升级前建议做备份或快照以便回滚；若升级失败或需回退，可恢复升级前的快照。Qdrant Cloud 在升级时会应用数据迁移，因此不支持在线降级。
7. 预升级检查清单第 2 项：查看 release notes（https://github.com/qdrant/qdrant/releases），关注默认值和行为变更，而不仅是弃用项。版本升级可能引入默认设置、校验规则或查询行为的变化，即使 API 保持兼容也可能影响现有工作负载。
8. 预升级检查清单第 3 项：先在非生产环境用目标服务端版本测试客户端应用，并在切换前查看 SDK release notes 中已弃用/移除的方法。
9. 预升级检查清单第 4 项：建议每个节点至少 2 个 CPU 核心。升级期间 Qdrant 可能在处理常规操作的同时执行后台优化；只有 1 个核心时这些任务会争抢 CPU 资源，显著拖慢升级过程。
10. 预升级检查清单第 5 项：若需要零停机滚动升级，使用副本因子 2 或更高；副本因子为 1 时升级需要停机窗口。
11. 跨多个次版本升级（运行版本落后目标版本两个或更多次版本）时，自托管部署需逐一遍历每个中间次版本，并在每个版本上先升到该版本的最新补丁版再继续（如从 1.15 到 1.17，先升到最新的 1.16.x，再升到 1.17.x）。
12. 跨多个次版本升级时，每一步都是一次独立的滚动重启，总耗时是单版本升级的倍数，比单次升级更久，需提前规划并尽量选择非高峰时段。
13. 跨多个次版本升级时，Qdrant Cloud 会自动串联中间更新，因此 1.15.x 到 1.17.x 只需一次操作。
14. 定期按节奏升级，使未来的跳跃保持在一个次版本以内；定期升级也能避免大幅版本跳跃，降低未来迁移的复杂度。
15. 升级后若结果、分数或延迟出现异常，排查时查看源版本与目标版本之间的 release notes/changelog，关注弃用项、默认值变更和可能影响工作负载的行为变更。
16. 升级后对比相对排名和召回率与升级前基线，而不是对比绝对分数值；评分内部实现可能在不同版本间变化但仍属正确。

适用边界 · 注意事项

• 不要把绝对分数在不同版本间保持一致作为验收标准。
• 不要只读目标版本的说明而跳过中间次版本和补丁版本的说明。
• 不要在自托管部署上一次跳跃多个次版本。
• 不要在没有确认每个节点都报告目标版本的情况下就认为滚动升级已完成。