Qdrant 1.18.3发布：分片键重分片查询错误修复，哪些集群应该升级？

文章摘要

Qdrant 1.18.3于2026年7月17日发布，本次版本只包含一项Bug修复：解决使用Shard Key进行重分片时可能出现的查询错误。更新内容虽然很少，但它影响的是多租户、大规模Collection和在线扩缩容场景。本文解释Shard Key与Resharding的关系、故障可能出现在哪些阶段、升级前如何复现和验证，以及为什么小版本修复也需要按生产级流程灰度发布。

一、这次版本修复了什么

Qdrant 1.18.3的Change Log非常短：

Fix query errors when using shard keys while resharding

也就是：

使用Shard Key
＋集群正在Resharding
→ 某些查询可能报错

这不是新功能版本，也没有大规模API调整。

但如果系统满足以下条件，需要重点关注：

• 分布式Qdrant集群；
• Collection使用Shard Key；
• 正在或计划在线重分片；
• 多租户RAG；
• 高并发查询；
• 不能接受扩容期间查询失败。

二、Shard Key是什么

默认情况下，Qdrant根据Point ID将数据分布到不同Shard。

Shard Key允许业务显式控制数据分组。

例如多租户系统：

tenant_a
→ 指定Shard Key

tenant_b
→ 另一个Shard Key

好处：

• 按租户路由；
• 降低跨Shard查询；
• 便于租户隔离；
• 可以迁移特定数据组；
• 大租户可独立扩容。

Payload示意：

{
  "tenant_id": "T001",
  "document_id": "DOC-1001"
}

写入时指定：

shard_key = T001

三、Resharding为什么复杂

当数据量和流量增长时，原来的Shard数量可能不足。

Resharding需要：

创建新Shard布局
→ 搬迁数据
→ 同步增量写入
→ 更新路由
→ 切换查询
→ 清理旧布局

在迁移期间：

• 部分Point可能仍在旧Shard；
• 部分已经迁移到新Shard；
• 新写入需要正确路由；
• 查询需要同时理解迁移状态；
• Shard Key需要映射到正确分片。

任何路由状态不一致，都可能产生：

• 查询报错；
• 结果缺失；
• 重复结果；
• 延迟升高；
• 部分租户不可用。

四、哪些RAG项目受影响最大

1. 多租户知识库

每个租户使用独立Shard Key。

扩容时如果查询路由异常，可能只有部分租户失败，导致问题不容易被整体监控发现。

2. 超大Collection

通过Shard Key把：

业务线
地区
客户
时间分区

分组管理。

3. 在线扩容

要求Resharding期间继续提供查询服务。

4. 高频Metadata过滤

查询既指定Shard Key，又使用复杂过滤和混合检索，故障链路更长。

五、哪些项目可以暂缓

如果项目是：

• 单节点；
• 不使用Shard Key；
• 没有执行Resharding；
• 开发或测试环境；
• Collection规模较小；

这项修复的直接影响较低。

但仍应结合1.18.2和1.18.x的其他安全、稳定性修复评估是否升级。

六、如何确认自己是否使用Shard Key

检查：

• Collection创建和更新脚本；
• SDK写入参数；
• Shard Key管理API；
• 多租户路由代码；
• 集群运维文档；
• Metrics和Telemetry。

不要只看Payload中有没有tenant_id。

Payload过滤
≠ Shard Key路由

只有显式使用Shard Key API或写入参数，才属于本次问题范围。

七、升级前建立专项测试

测试一：迁移前基线

记录：

查询成功率
Recall结果数
P95延迟
Shard分布
租户数据量

测试二：Resharding期间持续查询

运行：

写入
查询
删除
过滤
混合检索

并覆盖全部Shard Key。

测试三：大租户与小租户

避免只测试一个默认租户。

测试四：迁移后数量一致性

检查：

每个Shard Key的Point总数
删除标记
Payload索引
检索结果

测试五：故障恢复

在Resharding中模拟：

• 节点重启；
• 网络抖动；
• 副本切换；
• 请求超时；
• 写入积压。

八、客户端不要无限重试

如果Resharding期间查询报错，客户端可能使用重试。

必须设置：

最大重试次数
指数退避
总超时
幂等判断
熔断

查询可以有限重试，但不能：

while true

否则集群处于迁移压力时，会收到更多请求，形成重试风暴。

九、监控应该按Shard Key拆分

整体成功率99.9%，不代表所有租户都正常。

如果一个小租户持续失败，整体指标可能看不出来。

建议记录：

query_success_rate_by_shard_key
query_error_count_by_shard_key
p95_latency_by_shard_key
result_count_anomaly
resharding_progress
shard_transfer_status
replica_state

高基数标签可能增加监控成本，可以只对重点租户和异常Shard Key展开。

十、推荐升级流程

1. 备份配置和Collection信息
2. 在预生产复现Shard Key场景
3. 升级一个非关键节点或测试集群
4. 启动Resharding专项压测
5. 验证查询结果和数量
6. 灰度升级生产节点
7. 观察错误率、延迟与迁移状态
8. 完成全部节点版本一致

不要在：

大促
批量入库
模型重建
高峰流量

期间同时执行版本升级和Resharding。

十一、版本升级后的验证清单

□ 所有节点版本一致
□ 集群状态正常
□ Collection绿色
□ Replica状态正确
□ Shard Key查询成功
□ Metadata过滤正确
□ 混合检索结果一致
□ Resharding能够完成
□ 迁移中无异常查询错误
□ Point数量无明显偏差
□ 延迟没有持续升高

十二、为什么只有一项修复也值得关注

基础设施版本价值不能只按功能数量判断。

一个修复如果影响：

查询正确性
在线扩容
多租户隔离

其业务价值可能比新增多个Demo功能更高。

对于企业RAG，向量库最重要的不是“支持多少新算法”，而是：

• 查询不能错；
• 扩容不能中断；
• 数据不能跨租户；
• 失败能够恢复；
• 状态能够观测。

总结

Qdrant 1.18.3针对的是一个非常具体的生产问题：

Shard Key
＋Resharding
＋查询

使用这三个能力的集群，建议完成预生产专项验证后升级。未使用Shard Key或Resharding的项目，直接影响较低，但仍应维护清晰的版本基线和升级节奏。

延伸阅读

想持续跟踪大模型、RAG、Agent、MCP 与开发者生态的最新变化，欢迎访问 智元界：

https://www.zyentor.com/

智元界将持续分享 AI 热点解读、技术实战、工具推荐与企业落地案例。