深入解析 Milvus Guarantee TimestampSearch 请求一致性保障的底层原理与实践【免费下载链接】milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search项目地址: https://gitcode.com/GitHub_Trending/mi/milvus本文基于仓库归档设计文档 how-guarantee-ts-works-cn.md英文版展开。Milvus 是一个存储与计算分离的分布式向量数据库Search 请求中的一致性表现依赖一套以时间戳Timestamp与同步时间戳Timetick水印为核心的机制而其对外暴露的开关就是本文主角——GuaranteeTsGuarantee Timestamp。读完本文你将理解 Milvus 的时钟/水印体系如何工作、GuaranteeTs 如何决定一次查询必须看到多少数据、四种一致性级别如何映射到 GuaranteeTs并能结合当前仓库中 Proxy 侧的真实换算源码为自研 SDK 或业务选型给出正确参数。很多同学接触 Milvus 时都会被 Search 请求里茫茫多的参数弄晕尤其对于为 Milvus 开发 SDK 客户端的开发者。Search 请求里有一个特殊参数——Guarantee Timestamp下文简称 GuaranteeTs它直接决定了这一次查询的一致性强弱、等待时长与精度表现。本文以归档于docs/archive/milvus-2.0/developer_guides/的原始设计文档为骨架结合当前仓库internal/proxy、client/entity等处的源码实现把这条链路彻底讲透。一、为什么要 GuaranteeTs存储计算分离带来的看不见的数据Milvus 与大多数分布式系统一样会为每一条进入系统的记录分配一个时间戳。同时Milvus 是一个典型的存储计算分离架构数据持久化由 DataNodes 承担数据最终会落盘到 MinIO/S3 之类的分布式对象存储Search 等计算读任务由 QueryNodes 承担。读链路会同时处理两类数据批式数据batch data已经固化、不再被更改的数据。Search 请求一定会看到批式数据里的全部数据这部分天然安全流式数据streaming dataQueryNodes 与 DataNodes 通过同一个订阅机制消费用户的插入请求构成了源源不断的增量数据。关键问题在于由于存在网络延迟QueryNodes 往往并不持有最新的流式数据。如果没有额外的保障机制直接在流式数据上执行 Search就会漏掉那些尚未被 QueryNode 消费到的插入记录从而降低查询精度。GuaranteeTs 正是为了解决这一矛盾而生的参数。分布式系统中的组件角色可进一步参阅归档文档 chap01_system_overview.md 与 chap04_message_stream.mdQueryNode/DataNode 的职责划分见 chap07_query_coordinator.md。二、Milvus 时钟机制Timestamp Timetick 水印Milvus 通过**时间戳水印timestamp watermark**来保障读链路的一致性。做法概括为两件事向消息队列插入用户数据时为每条插入记录打上时间戳与此同时不间断地向消息队列插入同步时间戳timetick/syncTs。上图中数据记录data ts1、data ts2…与同步时间戳syncTs1、syncTs2…在消息队列里按序排列。以 syncTs1 为例它的语义是当下游消费者例如 QueryNodes看到了 syncTs1就意味着syncTs1 以前的所有数据都已经被消费完毕了。换句话说时间戳比 syncTs1 更小的插入记录不会再出现在消息队列中。这是一个经典的水印watermark语义水位一旦推进到某个值水位以下的流式数据即可认为全部可见、不会再迟到。如果仍然出现比水印小的迟到记录那基本属于系统缺陷原始文档作者也特别强调——若发现此类情况应尽快反馈给社区。从当前仓库的 proto 定义与 Proxy/QueryNode 链路中可以看到GuaranteeTimestamp字段依然是 SearchRequest/QueryRequest 的标准成员这一记录打时间戳 周期性插水印的设计沿用至今是理解一致性参数的基石。三、从水印到 ServiceTimeQueryNode 的可服务时间有了水印概念ServiceTime 就水到渠成了QueryNodes 会持续从消息队列里取出插入记录与同步时间戳。每消费到一个同步时间戳QueryNodes 就把它更新为可服务时间——ServiceTime。因此 ServiceTime 的含义是当前 QueryNode 已经能够看到 ServiceTime 以前的所有数据。它本质上是 QueryNode 本地消费进度在水印坐标上的投影代表该节点此刻安全可见的数据截止点。值得注意的是ServiceTime这个词至今仍广泛出现在当前仓库代码中例如 Proxy 侧的负载均衡会使用带服务端的响应时间与队列深度做调度见 internal/proxy/shardclient/look_aside_balancer.go 中对cost.ServiceTime的统计说明服务时间这一维度贯穿了从一致性保障到调度决策的多个层面。四、GuaranteeTs把数据可见性要求写进 Search 请求有了 ServiceTime 这把尺子Milvus 针对不同用户对一致性与可用性的不同诉求提供了 GuaranteeTs用户可以显式指定 GuaranteeTs告知 QueryNodes我这次 Search 请求必须看到 GuaranteeTs 以前的所有数据。执行时的判定逻辑只有一条简单规则即比较 GuaranteeTs 与当前 ServiceTime情形一GuaranteeTs ≤ ServiceTime —— 立刻执行 Search。GuaranteeTs 落在 ServiceTime 左侧说明 QueryNode 现有的消费进度已经满足该请求的可见性要求无需等待即可开始向量检索。情形二GuaranteeTs ServiceTime —— 持续消费、等待水位推进。此时 QueryNode 必须从消息队列继续消费同步时间戳直到ServiceTime 推进到不小于 GuaranteeTs才能放行该 Search 请求。因此GuaranteeTs 本质上就是一个**等待水位参数**如果用户希望得到足够高的查询精度、对一致性要求高、对查询时延不敏感那么 GuaranteeTs 应当尽可能大追平系统最新时间代价是可能要等消息队列里的数据全部跟上反之如果用户希望尽快拿到结果、对可用性要求高、能容忍查询精度上的损失那么 GuaranteeTs 可以不必特别大甚至直接跳过等待。这段比较-等待-放行的语义在当前仓库的读路径上依然成立在 internal/proxy/task_query.go 中Proxy 会先按一致性级别把请求换算成最终 GuaranteeTs并将其与BeginTs、collection 元数据的UpdateTimestamp做比较后再下发其目的正是确保查询请求观察到足够新且完整的元数据视图。五、四种一致性级别与 GuaranteeTs 的映射关系原始的 GuaranteeTs 过于底层直接暴露给普通用户并不友好。因此 Milvus 将它收敛为四种更高层的一致性级别用户通常只声明级别由系统自动推导 GuaranteeTs。上图中时间轴自左向右GuaranteeTs 要求越来越高一致性也越来越强一致性级别GuaranteeTs 取值QueryNode 行为典型语义最终一致性Eventual设为一个特别小的值如1跳过一致性检查立刻在当前已有数据上执行最快返回可能漏掉最近未消费数据有界一致性Bounded Staleness比系统最新时间稍旧可容忍的滞后窗口在可容忍范围内立刻执行精度与时延的默认平衡点客户端一致性 / 会话一致性Sessionread-your-own-write客户端上一次写入的时间戳至少能看到自己插入的全部数据保证每个客户端读到自己的写入强一致性Strong系统最新时间戳等待 ServiceTime 推进到最新才执行精度最高代价是等待关于上述映射有两点值得展开强一致性下 GuaranteeTs 被顶到系统最新时间戳QueryNode 必须等 ServiceTime 追平才能执行是最慢但最准的选项最终一致性把 GuaranteeTs 压到极小值源码里直接取1见下文从而绕过一切等待。默认行为Milvus 默认提供有界一致性。原始文档同时说明如果用户不传入 GuaranteeTs系统会把它设为当前的最新时间戳——结合默认的有界一致性语义更准确的表述是默认请求会以系统当前最新时间为基准、按有界一致性的可容忍滞后换算规则得到实际保证时间点具体见下一节的源码换算。六、源码佐证Proxy 是如何把一致性级别换算成 GuaranteeTs 的当前仓库在 Proxy 侧实现了一致性级别 → GuaranteeTs的换算函数位于 internal/proxy/util.go。先看按一致性级别换算的入口func parseGuaranteeTsFromConsistency(ts, tMax typeutil.Timestamp, consistency commonpb.ConsistencyLevel) typeutil.Timestamp { switch consistency { case commonpb.ConsistencyLevel_Strong: ts tMax case commonpb.ConsistencyLevel_Bounded: ratio : Params.CommonCfg.GracefulTime.GetAsDuration(time.Millisecond) ts tsoutil.AddPhysicalDurationOnTs(tMax, -ratio) case commonpb.ConsistencyLevel_Eventually: ts 1 } return ts }这段代码与文档描述完全对得上并且给出了精确的数值语义StrongGuaranteeTs 直接取tMax系统当前最新时间/请求 BeginTs 的上界对应必须等到最新Bounded从最新时间tMax上向前回拨一个可配置的宽松时间窗口GracefulTime即系统时间减去容忍滞后量EventuallyGuaranteeTs 被钉死在1对应文档所述设为一个特别小的值比如 1跳过一致性检查。与它配套的还有对显式传参 特殊标记值的处理函数 parseGuaranteeTsfunc parseGuaranteeTs(ts, tMax typeutil.Timestamp) typeutil.Timestamp { switch ts { case strongTS: ts tMax case boundedTS: ratio : Params.CommonCfg.GracefulTime.GetAsDuration(time.Millisecond) ts tsoutil.AddPhysicalDurationOnTs(tMax, -ratio) } return ts }它说明客户端在自定义 GuaranteeTs 时还可以借助 SDK 预定义的标记常量强一致 / 有界两种占位符由 Proxy 统一翻译成真实时间戳。有界一致性所用的GracefulTime窗口在 configs/milvus.yaml 中定义gracefulTime: 5000 # milliseconds. it represents the interval (in ms) by which the request arrival time needs to be subtracted in the case of Bounded Consistency.即有界一致性的默认容忍滞后为5000ms可通过common.gracefulTime毫秒调大以换取更低时延或调小以获得更新鲜的数据。这一点对做一致性/时延调优的同学非常关键——有界一致性并非读旧数据而是允许比最新数据滞后至多 gracefulTime。换算发生在读路径的什么位置见 internal/proxy/task_query.goQuery 请求与 internal/proxy/task_delete.goDelete 请求Proxy 取请求自带的 GuaranteeTimestamp结合请求的 BeginTs 与一致性级别做解析并对 collection 元数据时间戳做防御性校验再下发给 QueryNode。QueryNode 侧也会在服务日志里打印guaranteeTimestamp便于排查见 internal/querynodev2/handlers.go。七、客户端视角如何传入一致性级别或 GuaranteeTs一致性级别在 SDK 层被建模为枚举常量。当前 Go 客户端在 client/entity/schema.go 中定义了与commonpb.ConsistencyLevel一一对应的五档ClStrong ConsistencyLevel ConsistencyLevel(commonpb.ConsistencyLevel_Strong) ClBounded ConsistencyLevel ConsistencyLevel(commonpb.ConsistencyLevel_Bounded) ClSession ConsistencyLevel ConsistencyLevel(commonpb.ConsistencyLevel_Session) ClEventually ConsistencyLevel ConsistencyLevel(commonpb.ConsistencyLevel_Eventually) ClCustomized ConsistencyLevel ConsistencyLevel(commonpb.ConsistencyLevel_Customized)其中**ClSession会话一致性**即原文档所称客户端一致性客户端以上一次写入的时间戳作为 GuaranteeTs从而保证每个客户端至少能看到自己插入的全部数据read-your-own-write。它主要服务于写完立即查且希望结果包含刚写入内容的场景ClCustomized允许高级用户自行指定 GuaranteeTs 数值完全掌控等待水位。在构建搜索/查询请求时客户端默认会携带使用默认一致性级别的标记创建 Collection 选项默认填入entity.DefaultConsistencyLevel见 client/milvusclient/collection_options.go读请求选项中的UseDefaultConsistency字段控制是否回落到服务端默认级别见 client/milvusclient/read_options.go。也就是说业务侧不显式指定时走的就是服务端默认的有界一致性即系统最新时间减去gracefulTime后的那个水位绝大多数场景下这是精度与时延的最佳折中。对于读多写少、可容忍轻微延迟的数据无需改动若想让某次查询立刻拿到最新插入数据则在该请求上显式声明Session/Strong或自定义 GuaranteeTs若查询对新鲜度不敏感如周期性的后台批处理、统计类检索Eventually能显著降低等待。八、一致性 × 可用性的工程权衡与选型建议综合上面的机制与源码可以给出一张实战选型速查表一致性要求越高、GuaranteeTs 越大等待可能越久场景推荐级别理由默认业务查询Bounded默认gracefulTime5000ms精度与延迟兼顾写入后立即回查如先插后查的交互链路Session保证看到自己刚写入的数据金融/强校验类、对结果新鲜度零容忍Strong等 ServiceTime 追平最新时间戳后台分析、批量扫描、对结果集敏感度低Eventually跳过等待吞吐优先自研 SDK / 高级控制Customized 自定义 GuaranteeTs精确表达看到某个时间点之前的数据需要再次提醒的三件事GuaranteeTs 的边界条件发生在QueryNode 未消费到最新消息时若 QueryNode 消费进度足够快ServiceTime 已超过 GuaranteeTs即使要求 Strong 也几乎无额外等待有界一致性的滞后窗口通过 common.gracefulTime 配置是集群级参数调整需评估对全部读请求的影响流式数据可见性由同步时间戳水印保证批式数据天然全部可见不受 GuaranteeTs 影响。九、小结GuaranteeTs 不是又一个令人迷惑的请求字段而是 Milvus 在存储计算分离 流式消费有延迟的现实下为用户提供的一把显式控制读取数据新鲜度的旋钮。它的完整链条是每行数据获得时间戳 → 消息队列周期性注入 syncTs 水印 → QueryNode 以消费到的水印维护 ServiceTime → 请求携带 GuaranteeTs 与 ServiceTime 比较 → 不满足则等待、满足则立即执行。四种一致性级别Strong / Bounded / Eventually / Session只是这把旋钮的四种预设挡位Proxy 侧的 parseGuaranteeTsFromConsistency 就是挡位与真实时间戳之间的变速箱。理解这套机制无论你是在 Milvus 上做业务选型还是在为 Milvus 开发 SDK都能准确回答同一个问题这一次 Search到底必须看到哪些数据延伸阅读本文中文原稿how-guarantee-ts-works-cn.md英文版how-guarantee-ts-works.md时钟同步与根协调器时间服务chap06_root_coordinator.md消息队列与数据流chap04_message_stream.mdProxy 请求处理与任务解析chap05_proxy.mdGo SDK 一致性枚举与默认值client/entity/schema.go、client/milvusclient/collection_options.go【免费下载链接】milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search项目地址: https://gitcode.com/GitHub_Trending/mi/milvus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考