1. 上线前的背景与整体思路1.1 为什么要在 Doris 里做向量检索先说背景。我们有一套推荐系统之前召回环节用的是 Elasticsearch 做向量近邻搜索数据量大概几千万条维度 768。后来因为业务侧希望把用户行为明细、物品画像、向量特征放在同一个存储里做联合过滤减少跨系统同步的链路就把目光投向了 Doris。Doris 从 2.0 版本开始支持 ANNApproximate Nearest Neighbor近似最近邻向量索引底层用的是 HNSW 算法能在 SQL 里直接写ORDER BY l2_distance(...) LIMIT k这种查询对已经用 Doris 做数仓的团队来说迁移成本看起来很低。但“看起来低”和“实际能跑”是两回事。我们前后折腾了将近两周踩了七个比较典型的坑从建表、导数据、建索引、查询到集群参数几乎每个环节都出过问题。这篇文章就把这七个现场完整记录下来每个现场都附上可直接复制的命令和排查思路希望能帮后面要上这个功能的人省点时间。适合谁看如果你正在评估 Doris 的向量检索能力或者已经建了表但查询结果不对、性能不达预期那这篇基本能覆盖你 80% 的疑问。如果你还没接触过 ANN 和 HNSW也不用担心我会在涉及原理的地方用生活化的方式解释清楚。1.2 整体方案选型与核心考量我们最终确定的方案是Doris 存全量向量和标量字段用 HNSW 索引加速近邻查询查询时用 SQL 做标量过滤加向量排序。选 HNSW 而不是 IVF 系列主要原因是 HNSW 在召回率和查询延迟上的平衡更好而且 Doris 当前版本对 HNSW 的支持最成熟参数暴露得也比较全。这里有个关键决策点向量索引是建在表上的而不是独立的索引服务。这意味着索引的构建、更新、查询都跟 Doris 的存储引擎绑在一起。好处是运维简单坏处是索引构建会消耗 BE 的 CPU 和内存而且索引不是实时生效的需要等 compaction 或者手动触发。这一点在后面第三个现场里会详细说。另一个决策点是分桶策略。Doris 是 MPP 架构数据按分桶键分散到各个 BE。向量检索本身是计算密集型的如果分桶不合理会导致查询时数据倾斜某些 BE 负载过高。我们一开始按用户 ID 哈希分桶后来发现查询时经常要跨所有分桶扫描反而放大了延迟。后面改成按向量所属的业务分区做 Range 分桶配合分区裁剪性能才稳定下来。提示向量检索场景下分桶键的选择比普通 OLAP 查询更敏感。如果查询总是带某个标量过滤条件优先考虑用那个字段做分桶或分区让向量计算尽量落在少数据量的分片上。2. 七个排查现场与实操命令2.1 现场一建表时向量列类型选错导致索引建不上第一个坑出现在建表阶段。我们一开始把向量列定义成ARRAYFLOAT因为文档里说支持数组类型。建完表导数据都正常但执行CREATE INDEX时直接报错提示索引类型不支持。排查过程先看 Doris 官网的向量索引文档发现 HNSW 索引只支持ARRAYFLOAT且必须指定index_type hnsw但还有一个隐藏条件——向量维度必须在建表时通过PROPERTIES里的dimension指定而且这个属性是表级别的不是列级别的。我们漏了这个属性导致索引创建时无法推断维度。正确的建表语句长这样CREATE TABLE vector_items ( item_id BIGINT, category_id INT, embedding ARRAYFLOAT, create_time DATETIME ) ENGINEOLAP DUPLICATE KEY(item_id) DISTRIBUTED BY HASH(item_id) BUCKETS 32 PROPERTIES ( replication_num 3, dimension 768, index_type hnsw, metric_type l2_distance );注意dimension和metric_type都是表级属性。metric_type支持l2_distance和inner_product选哪个取决于你的向量是否归一化。如果向量已经归一化内积和余弦相似度等价用inner_product性能略好如果没归一化老老实实用l2_distance。注意dimension一旦设定不能修改改维度只能重建表。所以上线前一定要确认好模型输出的维度别等导了几亿条数据才发现维度写错了。2.2 现场二数据导入后索引没生效查询走全表扫描表建好了数据也通过 Stream Load 导进去了但查询时发现延迟很高用EXPLAIN看执行计划发现根本没有用到向量索引走的是全表扫描加排序。这里要理解 Doris 向量索引的生效机制。HNSW 索引是在数据写入后异步构建的不是导入即生效。索引构建的触发时机有两个一是 BE 的 compaction 过程二是手动执行BUILD INDEX。我们当时数据刚导完就去查索引还没建好自然用不上。排查命令-- 查看索引构建状态 SHOW INDEX FROM vector_items; -- 手动触发索引构建 BUILD INDEX ON vector_items;SHOW INDEX会返回索引名、列名、索引类型和状态。状态是FINISHED才表示可用。如果是PENDING或RUNNING说明还在构建。数据量大的时候构建可能几十分钟甚至几小时取决于 BE 的资源和数据量。另一个容易忽略的点是查询必须写成 Doris 能识别为向量检索的形式。比如SELECT item_id, l2_distance(embedding, [0.1, 0.2, ...]) AS dist FROM vector_items ORDER BY dist LIMIT 10;这里ORDER BY必须直接作用在距离函数上且LIMIT不能太大。如果写成子查询或者加了复杂的WHERE条件导致优化器无法下推索引也可能不生效。实测下来LIMIT在 100 以内索引利用最充分超过 1000 优化器可能直接放弃索引走暴力扫描。2.3 现场三HNSW 参数没调优召回率惨不忍睹索引生效后查询延迟确实降下来了从秒级降到几十毫秒。但做召回率评测时发现Top 10 的召回率只有 60% 左右而之前用 ES 能到 95% 以上。这就是 HNSW 的近似性带来的问题——它为了速度牺牲了部分精度。HNSW 有两个核心参数M和ef_construction。M是每个节点在图中保留的邻居数越大图越密召回率越高但内存占用和构建时间也越大。ef_construction是构建时的候选队列大小越大构建越慢但图质量越好。查询时还有一个ef_search参数控制搜索时的候选队列大小越大召回率越高但延迟也越高。Doris 里这些参数通过索引属性设置CREATE INDEX idx_embedding ON vector_items(embedding) USING ANN PROPERTIES ( index_type hnsw, metric_type l2_distance, M 32, ef_construction 200 );查询时的ef_search通过会话变量控制SET ann_ef_search 200;我们的调优过程先把M从默认的 16 提到 32ef_construction从 100 提到 200召回率升到 85% 左右。再把ef_search从 64 提到 200召回率到 93%延迟从 30ms 升到 80ms。最后把M提到 48召回率到 96%但内存占用涨了将近一倍。综合考虑最终定在M32、ef_construction200、ef_search150召回率 94%P99 延迟 120ms满足业务要求。参数默认值调优值影响M1632召回率提升内存增加ef_construction100200构建变慢图质量提升ef_search64150查询变慢召回率提升实操心得调参不要一次全改每次只动一个参数观察召回率和延迟的变化曲线。另外召回率评测要用真实的查询向量集不要用随机向量随机向量的分布和真实分布差异很大评测结果没有参考价值。2.4 现场四标量过滤加向量排序执行计划跑偏业务查询通常不是纯向量检索而是带条件的。比如“在某个分类下找最相似的 10 个物品”。我们一开始的写法是SELECT item_id, l2_distance(embedding, [..]) AS dist FROM vector_items WHERE category_id 123 ORDER BY dist LIMIT 10;结果发现延迟忽高忽低有时候几十毫秒有时候几秒。用EXPLAIN看发现优化器有时候先做标量过滤再算向量距离有时候先算向量距离再过滤。前者在分类下数据量少时很快后者在分类下数据量多时反而慢。Doris 的优化器对向量索引和标量条件的组合处理还不够智能需要手动干预。我们的做法是用子查询强制先做向量检索再在外层做标量过滤SELECT * FROM ( SELECT item_id, category_id, l2_distance(embedding, [..]) AS dist FROM vector_items ORDER BY dist LIMIT 1000 ) t WHERE t.category_id 123 LIMIT 10;这样内层先用向量索引取 Top 1000外层再过滤。代价是如果分类下数据很少可能 1000 条里只有几条符合条件召回不全。所以LIMIT的大小要根据标量条件的筛选率来定。筛选率高的条件比如只筛掉 10%LIMIT可以小一点筛选率低的条件比如只保留 1%LIMIT要放大到几万甚至几十万。更好的方案是用分区或分桶把标量条件前置。比如按category_id做分区查询时分区裁剪直接定位到目标分区向量索引只在分区内生效。这样既保证了召回又控制了计算量。我们最后就是改成了按天分区加分类分桶查询性能稳定在 100ms 以内。2.5 现场五BE 内存被打满索引加载失败数据量涨到五千万条以后集群开始不稳定。表现是查询偶尔报错BE 日志里出现failed to load index或者memory limit exceeded。登录 BE 节点看内存占用一直在 90% 以上。原因是 HNSW 索引是全内存加载的。每个 BE 上加载的索引大小取决于该 BE 负责的数据分片。五千万条 768 维 float 向量原始数据大概 150GBHNSW 索引本身还要额外占用 1.5 到 2 倍的内存也就是 200GB 到 300GB。我们三个 BE每个 BE 要扛 70GB 到 100GB 的索引内存加上查询时的临时内存直接把 BE 的 128GB 内存打爆了。排查命令# 查看 BE 内存使用 curl http://be_host:8040/api/memory_usage # 查看索引内存占用 curl http://be_host:8040/api/compaction/show解决方案有三个方向一是加 BE 节点分摊内存二是降低向量维度比如用 PCA 降到 256 维三是用量化技术压缩索引但 Doris 当前版本对量化的支持有限。我们选了加节点加降维的组合BE 从 3 个加到 6 个维度从 768 降到 384内存占用降到每个 BE 40GB 左右稳定了。注意BE 的内存规划要留足余量。除了索引本身查询时的ef_search候选队列、排序缓冲区、以及 compaction 都需要内存。建议索引内存不超过 BE 总内存的 50%剩下的留给查询和系统。2.6 现场六索引重建期间查询不可用有一次我们调整了 HNSW 参数需要重建索引。执行DROP INDEX再CREATE INDEX后发现查询直接报错提示索引不存在。原来 Doris 的索引重建不是原子的删掉旧索引到新索引构建完成之间有一个空窗期这期间向量检索查询会失败。正确的做法是先建新索引再删旧索引但 Doris 不支持同列多索引。所以只能接受空窗期或者用别名切换。我们的做法是建一张新表把数据导过去在新表上建好索引然后通过视图或者应用层切换表名。这样旧表继续服务新表准备好后一次性切换空窗期为零。-- 新表建好后切换视图 ALTER VIEW vector_items_view AS SELECT * FROM vector_items_new;如果数据量太大全量导不现实可以用INSERT INTO ... SELECT做增量同步但要注意向量索引在增量导入后也需要重新构建。Doris 的BUILD INDEX支持增量构建但实测下来增量构建的图质量和全量构建有差距召回率会低几个百分点。所以如果对召回率要求高还是建议定期全量重建。2.7 现场七查询结果不稳定同一向量两次查询结果不同最后一个坑比较隐蔽。测试时发现同一个查询向量连续查两次返回的 Top 10 结果居然不完全一样。虽然差异不大但排序有变化。一开始怀疑是数据在变后来确认数据没变是 HNSW 的随机性导致的。HNSW 在构建图的时候有随机性同一批数据两次构建出来的图可能不同。查询时如果ef_search不够大搜索路径可能走到不同的局部最优导致结果有细微差异。这不是 bug是近似算法的固有特性。解决办法有两个一是把ef_search调大到接近暴力扫描的水平结果就稳定了但延迟会上去二是在应用层做结果缓存同一个查询向量缓存一段时间。我们选了后者因为业务上对同一向量的重复查询很多缓存命中率能到 70% 以上既保证了稳定性又控制了延迟。# 应用层缓存示例 import hashlib import json from functools import lru_cache def vector_key(vec): return hashlib.md5(json.dumps(vec).encode()).hexdigest() lru_cache(maxsize10000) def query_similar(vec_key, top_k): # 实际查询 Doris pass实操心得如果业务对结果一致性要求极高比如法律、金融场景建议不要用 ANN直接用暴力扫描。Doris 也支持暴力扫描只是延迟高。ANN 适合推荐、搜索这类对轻微差异不敏感的场景。3. 常见问题速查与避坑清单3.1 问题速查表现象可能原因排查命令解决方向索引建不上缺 dimension 属性或类型不对SHOW CREATE TABLE检查表属性查询不走索引索引未构建完成SHOW INDEX执行 BUILD INDEX召回率低HNSW 参数太小查看索引属性调大 M 和 ef_search延迟忽高忽低执行计划跑偏EXPLAIN用子查询强制顺序BE 内存打满索引全内存加载curl memory_usage加节点或降维重建期间不可用索引非原子切换无新表切换或视图结果不稳定HNSW 随机性无调大 ef_search 或缓存3.2 上线前的检查清单确认向量维度与模型输出一致且已写入表属性确认metric_type与向量是否归一化匹配确认 BE 内存足够容纳索引建议不超过 50%确认分区分桶策略与查询模式匹配确认索引构建完成后再切流量确认有索引重建的灰度方案确认应用层有结果缓存或一致性兜底3.3 几个容易被忽略的细节第一Doris 的向量索引不支持 NULL 值。如果向量列有 NULL索引构建会跳过这些行查询时也查不到。所以导入前要确保向量列没有 NULL或者用默认向量填充。第二向量索引对数据更新不友好。Doris 的更新是标记删除加追加索引不会自动更新。如果向量频繁变更索引会越来越“脏”召回率下降。建议向量数据尽量只增不改或者定期重建索引。第三查询向量的维度必须和表属性一致。如果传了一个 512 维的查询向量到 768 维的表Doris 不会报错但会返回空结果或者乱序结果。这个坑很隐蔽因为不报错只是结果不对。建议在应用层做维度校验。第四ann_ef_search是会话变量不是全局变量。每个连接都要单独设置或者通过连接池的初始化 SQL 统一设置。我们一开始只在测试连接上设了线上连接没设导致线上召回率比测试低了一截排查了半天才发现是变量没生效。4. 性能对比与选型建议4.1 Doris 向量检索 vs 专用向量库我们内部也对比过 Doris 和专用向量库比如 Milvus、Faiss 服务化的差异。纯向量检索场景专用库在延迟和召回率上确实有优势尤其是亿级数据量下专用库的索引压缩和量化技术更成熟。但 Doris 的优势在于向量和标量在同一个系统里省去了数据同步和跨系统查询的复杂度。维度Doris专用向量库纯向量延迟中等低标量过滤原生支持需要额外处理运维复杂度低复用现有集群高独立集群数据一致性强最终一致适合场景向量标量混合查询纯向量大规模检索我们的结论是如果向量数据在千万级以内且查询总是带标量条件Doris 是更省心的选择。如果向量数据上亿且查询以纯向量为主专用库更合适。4.2 和 ClickHouse 的简单对比社区里经常有人问 Doris 和 ClickHouse 做向量检索怎么选。ClickHouse 也有 ANN 索引但它的实现更偏向实验性参数暴露少而且 ClickHouse 的更新能力弱向量数据频繁变更时比较痛苦。Doris 在 SQL 兼容性和更新支持上更好一些但 ClickHouse 在单表扫描性能上有优势。如果团队已经用了其中一个建议直接在现有系统上试不要为了向量检索单独引入新系统。4.3 后续可以扩展的方向如果 Doris 的向量检索满足不了需求有几个扩展方向。一是把向量检索下沉到应用层用 Faiss 做本地索引Doris 只存原始向量和标量字段查询时先从 Doris 拉候选集再本地精排。二是用 Doris 的 UDF 能力接入外部向量计算库但性能损耗比较大。三是等 Doris 后续版本对量化索引的支持量化能把索引内存压缩 4 到 8 倍对大规模场景很关键。我个人在实际操作中的体会是Doris 的向量检索能力已经能覆盖大部分中小规模的推荐和搜索场景但前提是你要接受它的近似性和内存开销。上线前一定要做召回率评测和内存规划不要等出了问题再补。另外索引重建和参数调优是常态不是一次性的工作建议把这部分做成自动化脚本减少人工操作。
1. 上线前的背景与整体思路1.1 为什么要在 Doris 里做向量检索先说背景。我们有一套推荐系统之前召回环节用的是 Elasticsearch 做向量近邻搜索数据量大概几千万条维度 768。后来因为业务侧希望把用户行为明细、物品画像、向量特征放在同一个存储里做联合过滤减少跨系统同步的链路就把目光投向了 Doris。Doris 从 2.0 版本开始支持 ANNApproximate Nearest Neighbor近似最近邻向量索引底层用的是 HNSW 算法能在 SQL 里直接写ORDER BY l2_distance(...) LIMIT k这种查询对已经用 Doris 做数仓的团队来说迁移成本看起来很低。但“看起来低”和“实际能跑”是两回事。我们前后折腾了将近两周踩了七个比较典型的坑从建表、导数据、建索引、查询到集群参数几乎每个环节都出过问题。这篇文章就把这七个现场完整记录下来每个现场都附上可直接复制的命令和排查思路希望能帮后面要上这个功能的人省点时间。适合谁看如果你正在评估 Doris 的向量检索能力或者已经建了表但查询结果不对、性能不达预期那这篇基本能覆盖你 80% 的疑问。如果你还没接触过 ANN 和 HNSW也不用担心我会在涉及原理的地方用生活化的方式解释清楚。1.2 整体方案选型与核心考量我们最终确定的方案是Doris 存全量向量和标量字段用 HNSW 索引加速近邻查询查询时用 SQL 做标量过滤加向量排序。选 HNSW 而不是 IVF 系列主要原因是 HNSW 在召回率和查询延迟上的平衡更好而且 Doris 当前版本对 HNSW 的支持最成熟参数暴露得也比较全。这里有个关键决策点向量索引是建在表上的而不是独立的索引服务。这意味着索引的构建、更新、查询都跟 Doris 的存储引擎绑在一起。好处是运维简单坏处是索引构建会消耗 BE 的 CPU 和内存而且索引不是实时生效的需要等 compaction 或者手动触发。这一点在后面第三个现场里会详细说。另一个决策点是分桶策略。Doris 是 MPP 架构数据按分桶键分散到各个 BE。向量检索本身是计算密集型的如果分桶不合理会导致查询时数据倾斜某些 BE 负载过高。我们一开始按用户 ID 哈希分桶后来发现查询时经常要跨所有分桶扫描反而放大了延迟。后面改成按向量所属的业务分区做 Range 分桶配合分区裁剪性能才稳定下来。提示向量检索场景下分桶键的选择比普通 OLAP 查询更敏感。如果查询总是带某个标量过滤条件优先考虑用那个字段做分桶或分区让向量计算尽量落在少数据量的分片上。2. 七个排查现场与实操命令2.1 现场一建表时向量列类型选错导致索引建不上第一个坑出现在建表阶段。我们一开始把向量列定义成ARRAYFLOAT因为文档里说支持数组类型。建完表导数据都正常但执行CREATE INDEX时直接报错提示索引类型不支持。排查过程先看 Doris 官网的向量索引文档发现 HNSW 索引只支持ARRAYFLOAT且必须指定index_type hnsw但还有一个隐藏条件——向量维度必须在建表时通过PROPERTIES里的dimension指定而且这个属性是表级别的不是列级别的。我们漏了这个属性导致索引创建时无法推断维度。正确的建表语句长这样CREATE TABLE vector_items ( item_id BIGINT, category_id INT, embedding ARRAYFLOAT, create_time DATETIME ) ENGINEOLAP DUPLICATE KEY(item_id) DISTRIBUTED BY HASH(item_id) BUCKETS 32 PROPERTIES ( replication_num 3, dimension 768, index_type hnsw, metric_type l2_distance );注意dimension和metric_type都是表级属性。metric_type支持l2_distance和inner_product选哪个取决于你的向量是否归一化。如果向量已经归一化内积和余弦相似度等价用inner_product性能略好如果没归一化老老实实用l2_distance。注意dimension一旦设定不能修改改维度只能重建表。所以上线前一定要确认好模型输出的维度别等导了几亿条数据才发现维度写错了。2.2 现场二数据导入后索引没生效查询走全表扫描表建好了数据也通过 Stream Load 导进去了但查询时发现延迟很高用EXPLAIN看执行计划发现根本没有用到向量索引走的是全表扫描加排序。这里要理解 Doris 向量索引的生效机制。HNSW 索引是在数据写入后异步构建的不是导入即生效。索引构建的触发时机有两个一是 BE 的 compaction 过程二是手动执行BUILD INDEX。我们当时数据刚导完就去查索引还没建好自然用不上。排查命令-- 查看索引构建状态 SHOW INDEX FROM vector_items; -- 手动触发索引构建 BUILD INDEX ON vector_items;SHOW INDEX会返回索引名、列名、索引类型和状态。状态是FINISHED才表示可用。如果是PENDING或RUNNING说明还在构建。数据量大的时候构建可能几十分钟甚至几小时取决于 BE 的资源和数据量。另一个容易忽略的点是查询必须写成 Doris 能识别为向量检索的形式。比如SELECT item_id, l2_distance(embedding, [0.1, 0.2, ...]) AS dist FROM vector_items ORDER BY dist LIMIT 10;这里ORDER BY必须直接作用在距离函数上且LIMIT不能太大。如果写成子查询或者加了复杂的WHERE条件导致优化器无法下推索引也可能不生效。实测下来LIMIT在 100 以内索引利用最充分超过 1000 优化器可能直接放弃索引走暴力扫描。2.3 现场三HNSW 参数没调优召回率惨不忍睹索引生效后查询延迟确实降下来了从秒级降到几十毫秒。但做召回率评测时发现Top 10 的召回率只有 60% 左右而之前用 ES 能到 95% 以上。这就是 HNSW 的近似性带来的问题——它为了速度牺牲了部分精度。HNSW 有两个核心参数M和ef_construction。M是每个节点在图中保留的邻居数越大图越密召回率越高但内存占用和构建时间也越大。ef_construction是构建时的候选队列大小越大构建越慢但图质量越好。查询时还有一个ef_search参数控制搜索时的候选队列大小越大召回率越高但延迟也越高。Doris 里这些参数通过索引属性设置CREATE INDEX idx_embedding ON vector_items(embedding) USING ANN PROPERTIES ( index_type hnsw, metric_type l2_distance, M 32, ef_construction 200 );查询时的ef_search通过会话变量控制SET ann_ef_search 200;我们的调优过程先把M从默认的 16 提到 32ef_construction从 100 提到 200召回率升到 85% 左右。再把ef_search从 64 提到 200召回率到 93%延迟从 30ms 升到 80ms。最后把M提到 48召回率到 96%但内存占用涨了将近一倍。综合考虑最终定在M32、ef_construction200、ef_search150召回率 94%P99 延迟 120ms满足业务要求。参数默认值调优值影响M1632召回率提升内存增加ef_construction100200构建变慢图质量提升ef_search64150查询变慢召回率提升实操心得调参不要一次全改每次只动一个参数观察召回率和延迟的变化曲线。另外召回率评测要用真实的查询向量集不要用随机向量随机向量的分布和真实分布差异很大评测结果没有参考价值。2.4 现场四标量过滤加向量排序执行计划跑偏业务查询通常不是纯向量检索而是带条件的。比如“在某个分类下找最相似的 10 个物品”。我们一开始的写法是SELECT item_id, l2_distance(embedding, [..]) AS dist FROM vector_items WHERE category_id 123 ORDER BY dist LIMIT 10;结果发现延迟忽高忽低有时候几十毫秒有时候几秒。用EXPLAIN看发现优化器有时候先做标量过滤再算向量距离有时候先算向量距离再过滤。前者在分类下数据量少时很快后者在分类下数据量多时反而慢。Doris 的优化器对向量索引和标量条件的组合处理还不够智能需要手动干预。我们的做法是用子查询强制先做向量检索再在外层做标量过滤SELECT * FROM ( SELECT item_id, category_id, l2_distance(embedding, [..]) AS dist FROM vector_items ORDER BY dist LIMIT 1000 ) t WHERE t.category_id 123 LIMIT 10;这样内层先用向量索引取 Top 1000外层再过滤。代价是如果分类下数据很少可能 1000 条里只有几条符合条件召回不全。所以LIMIT的大小要根据标量条件的筛选率来定。筛选率高的条件比如只筛掉 10%LIMIT可以小一点筛选率低的条件比如只保留 1%LIMIT要放大到几万甚至几十万。更好的方案是用分区或分桶把标量条件前置。比如按category_id做分区查询时分区裁剪直接定位到目标分区向量索引只在分区内生效。这样既保证了召回又控制了计算量。我们最后就是改成了按天分区加分类分桶查询性能稳定在 100ms 以内。2.5 现场五BE 内存被打满索引加载失败数据量涨到五千万条以后集群开始不稳定。表现是查询偶尔报错BE 日志里出现failed to load index或者memory limit exceeded。登录 BE 节点看内存占用一直在 90% 以上。原因是 HNSW 索引是全内存加载的。每个 BE 上加载的索引大小取决于该 BE 负责的数据分片。五千万条 768 维 float 向量原始数据大概 150GBHNSW 索引本身还要额外占用 1.5 到 2 倍的内存也就是 200GB 到 300GB。我们三个 BE每个 BE 要扛 70GB 到 100GB 的索引内存加上查询时的临时内存直接把 BE 的 128GB 内存打爆了。排查命令# 查看 BE 内存使用 curl http://be_host:8040/api/memory_usage # 查看索引内存占用 curl http://be_host:8040/api/compaction/show解决方案有三个方向一是加 BE 节点分摊内存二是降低向量维度比如用 PCA 降到 256 维三是用量化技术压缩索引但 Doris 当前版本对量化的支持有限。我们选了加节点加降维的组合BE 从 3 个加到 6 个维度从 768 降到 384内存占用降到每个 BE 40GB 左右稳定了。注意BE 的内存规划要留足余量。除了索引本身查询时的ef_search候选队列、排序缓冲区、以及 compaction 都需要内存。建议索引内存不超过 BE 总内存的 50%剩下的留给查询和系统。2.6 现场六索引重建期间查询不可用有一次我们调整了 HNSW 参数需要重建索引。执行DROP INDEX再CREATE INDEX后发现查询直接报错提示索引不存在。原来 Doris 的索引重建不是原子的删掉旧索引到新索引构建完成之间有一个空窗期这期间向量检索查询会失败。正确的做法是先建新索引再删旧索引但 Doris 不支持同列多索引。所以只能接受空窗期或者用别名切换。我们的做法是建一张新表把数据导过去在新表上建好索引然后通过视图或者应用层切换表名。这样旧表继续服务新表准备好后一次性切换空窗期为零。-- 新表建好后切换视图 ALTER VIEW vector_items_view AS SELECT * FROM vector_items_new;如果数据量太大全量导不现实可以用INSERT INTO ... SELECT做增量同步但要注意向量索引在增量导入后也需要重新构建。Doris 的BUILD INDEX支持增量构建但实测下来增量构建的图质量和全量构建有差距召回率会低几个百分点。所以如果对召回率要求高还是建议定期全量重建。2.7 现场七查询结果不稳定同一向量两次查询结果不同最后一个坑比较隐蔽。测试时发现同一个查询向量连续查两次返回的 Top 10 结果居然不完全一样。虽然差异不大但排序有变化。一开始怀疑是数据在变后来确认数据没变是 HNSW 的随机性导致的。HNSW 在构建图的时候有随机性同一批数据两次构建出来的图可能不同。查询时如果ef_search不够大搜索路径可能走到不同的局部最优导致结果有细微差异。这不是 bug是近似算法的固有特性。解决办法有两个一是把ef_search调大到接近暴力扫描的水平结果就稳定了但延迟会上去二是在应用层做结果缓存同一个查询向量缓存一段时间。我们选了后者因为业务上对同一向量的重复查询很多缓存命中率能到 70% 以上既保证了稳定性又控制了延迟。# 应用层缓存示例 import hashlib import json from functools import lru_cache def vector_key(vec): return hashlib.md5(json.dumps(vec).encode()).hexdigest() lru_cache(maxsize10000) def query_similar(vec_key, top_k): # 实际查询 Doris pass实操心得如果业务对结果一致性要求极高比如法律、金融场景建议不要用 ANN直接用暴力扫描。Doris 也支持暴力扫描只是延迟高。ANN 适合推荐、搜索这类对轻微差异不敏感的场景。3. 常见问题速查与避坑清单3.1 问题速查表现象可能原因排查命令解决方向索引建不上缺 dimension 属性或类型不对SHOW CREATE TABLE检查表属性查询不走索引索引未构建完成SHOW INDEX执行 BUILD INDEX召回率低HNSW 参数太小查看索引属性调大 M 和 ef_search延迟忽高忽低执行计划跑偏EXPLAIN用子查询强制顺序BE 内存打满索引全内存加载curl memory_usage加节点或降维重建期间不可用索引非原子切换无新表切换或视图结果不稳定HNSW 随机性无调大 ef_search 或缓存3.2 上线前的检查清单确认向量维度与模型输出一致且已写入表属性确认metric_type与向量是否归一化匹配确认 BE 内存足够容纳索引建议不超过 50%确认分区分桶策略与查询模式匹配确认索引构建完成后再切流量确认有索引重建的灰度方案确认应用层有结果缓存或一致性兜底3.3 几个容易被忽略的细节第一Doris 的向量索引不支持 NULL 值。如果向量列有 NULL索引构建会跳过这些行查询时也查不到。所以导入前要确保向量列没有 NULL或者用默认向量填充。第二向量索引对数据更新不友好。Doris 的更新是标记删除加追加索引不会自动更新。如果向量频繁变更索引会越来越“脏”召回率下降。建议向量数据尽量只增不改或者定期重建索引。第三查询向量的维度必须和表属性一致。如果传了一个 512 维的查询向量到 768 维的表Doris 不会报错但会返回空结果或者乱序结果。这个坑很隐蔽因为不报错只是结果不对。建议在应用层做维度校验。第四ann_ef_search是会话变量不是全局变量。每个连接都要单独设置或者通过连接池的初始化 SQL 统一设置。我们一开始只在测试连接上设了线上连接没设导致线上召回率比测试低了一截排查了半天才发现是变量没生效。4. 性能对比与选型建议4.1 Doris 向量检索 vs 专用向量库我们内部也对比过 Doris 和专用向量库比如 Milvus、Faiss 服务化的差异。纯向量检索场景专用库在延迟和召回率上确实有优势尤其是亿级数据量下专用库的索引压缩和量化技术更成熟。但 Doris 的优势在于向量和标量在同一个系统里省去了数据同步和跨系统查询的复杂度。维度Doris专用向量库纯向量延迟中等低标量过滤原生支持需要额外处理运维复杂度低复用现有集群高独立集群数据一致性强最终一致适合场景向量标量混合查询纯向量大规模检索我们的结论是如果向量数据在千万级以内且查询总是带标量条件Doris 是更省心的选择。如果向量数据上亿且查询以纯向量为主专用库更合适。4.2 和 ClickHouse 的简单对比社区里经常有人问 Doris 和 ClickHouse 做向量检索怎么选。ClickHouse 也有 ANN 索引但它的实现更偏向实验性参数暴露少而且 ClickHouse 的更新能力弱向量数据频繁变更时比较痛苦。Doris 在 SQL 兼容性和更新支持上更好一些但 ClickHouse 在单表扫描性能上有优势。如果团队已经用了其中一个建议直接在现有系统上试不要为了向量检索单独引入新系统。4.3 后续可以扩展的方向如果 Doris 的向量检索满足不了需求有几个扩展方向。一是把向量检索下沉到应用层用 Faiss 做本地索引Doris 只存原始向量和标量字段查询时先从 Doris 拉候选集再本地精排。二是用 Doris 的 UDF 能力接入外部向量计算库但性能损耗比较大。三是等 Doris 后续版本对量化索引的支持量化能把索引内存压缩 4 到 8 倍对大规模场景很关键。我个人在实际操作中的体会是Doris 的向量检索能力已经能覆盖大部分中小规模的推荐和搜索场景但前提是你要接受它的近似性和内存开销。上线前一定要做召回率评测和内存规划不要等出了问题再补。另外索引重建和参数调优是常态不是一次性的工作建议把这部分做成自动化脚本减少人工操作。
