ScyllaDB Vector Search 向量搜索在 NoSQL 存储上构建语义相似度查询【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文基于仓库文档docs/features/vector-search.rst及其对应实现源码展开先说明 Vector Search 解决什么问题、适用于哪些工作负载、以及当前的可用性范围再结合 vector_index 实现、vector_store_client 客户端、相似度函数 与 SELECT 执行路径深入讲解向量索引的创建约束、HNSW 索引参数、相似度查询的执行链路以及服务端与向量存储vector store之间的配置与故障切换机制。读完后你可以完整理解 ScyllaDB 中向量搜索“从建索引到出结果”的整条技术脉络。什么是向量搜索Vector SearchVector Search 使应用能够基于高维数据的相似性进行查询而不是精确匹配。它的作用对象是向量嵌入embeddings——把文本、图片、音频、用户行为等数据转成的、能捕捉语义含义的数值表示。典型查询包括“找出与这段话相似的文档”“找出与用户刚浏览的商品相似的商品”“找出与此工单相关的历史工单”与依赖精确值或关键字的传统查询不同Vector Search 按向量之间的距离或相似度返回结果。这一能力正被大量用于现代 AI 工作负载AI 驱动的搜索、推荐系统以及检索增强生成RAG流水线。为什么在 ScyllaDB 上做向量搜索很多应用已经依赖 ScyllaDB 提供高吞吐、低且可预测的延迟以及大规模数据存储。Vector Search 在此基础上补齐了新一类工作负载文本或文档的语义搜索基于用户/商品相似度的推荐包括 RAG 流水线在内的 AI/ML 应用异常检测与模式识别也就是说ScyllaDB 可以作为 AI 应用的相似度搜索后端与原有业务数据共存于同一套高吞吐存储中。当前可用性根据 官方特性文档Vector Search目前仅在 ScyllaDB Cloud全托管 ScyllaDB 服务中提供。具体使用方式以 ScyllaDB Cloud 文档为准开源仓库中提供的是该特性所需的索引定义、查询语法、客户端与服务端配置等完整支撑代码。向量索引的定义与约束ScyllaDB 中向量索引是一种外部索引external index索引类型名为vector搜索类型名为 “Vector Search”见 index/vector_index.hh。它不存储 ScyllaDB 自身维护的倒排结构而是把检索请求委托给配套的向量存储服务vector store。索引目标列规则从 vector_index.cc 的 check_target() 可以看到对目标列的硬性校验第一目标列必须是向量列且类型必须是“float 向量”vectorfloat否则报错 “Vector indexes are only supported on columns of vectors of floats”其后可以附加过滤列filtering columns只支持可作为主键列使用的原生类型如ascii、boolean、int、bigint、text、timestamp、uuid、decimal等不支持 counter、duration 等类型还支持**局部索引local index**语法以(p1, p2)形式的分区键列表 向量列即按分区键范围约束搜索。目标序列化的格式在 serialize_targets() 中实现内部用 JSON 键表示tc向量目标列、pk分区键列局部索引用、fc过滤列例如(v) - v (v, f1, f2) - {tc:v,fc:[f1,f2]} ((p1, p2), v) - {tc:v,pk:[p1,p2]} ((p1, p2), v, f1) - {tc:v,pk:[p1,p2],fc:[f1]}索引选项index options索引支持的全部选项定义在 vector_index.cc 的 vector_index_options 表 中未知选项会被直接拒绝“Unsupported option ... for vector index”。各选项的含义、约束与底层作用如下选项取值 / 范围说明similarity_functioncosine/euclidean/dot_product向量相似度计算方法向量存储在索引构建与查询内部使用CQL 侧有对应的similarity_*函数见下文maximum_node_connections正整数上限 512HNSW 图索引参数单个节点最大连接数construction_beam_width正整数上限 4096HNSW 索引参数构建时的搜索束宽度search_beam_width正整数上限 4096HNSW 索引参数查询时的搜索束宽度quantizationf32/f16/bf16/i8/b1向量在向量存储中的量化压缩方式注意不压缩基表中的原始向量Scylla 用它判断是否启用 rescoringoversampling1.0 100.0 的浮点系数从向量存储拉取候选数量的放大倍数可提升 ANN 精度尤其配合量化 rescoring 时rescoringtrue/false量化场景下对候选重新计算相似度得分以恢复精度source_model任意字符串Cassandra SAI 兼容选项记录产生向量的嵌入模型名ScyllaDB 接受但不使用其中 HNSW 三参数被源码注释明确标注为“define HNSW index parameters, Used internally by vector store”即由向量存储解释而oversampling的注释写明“Used by Scylla during query processing to increase query limit sent to vector store”——它由Scylla 侧在查询处理时消费见下文执行链路。rescoring 的启用条件在 is_rescoring_enabled() 中实现量化方式不是f32即真的做了压缩且rescoring true才生效get_oversampling()在选项缺省时返回 1.0。建索引的前置条件validate() 汇总了所有建索引校验要求使用 Tablets 分区策略check_uses_tablets目标列类型校验上文主键列总数上限 255分区键 聚簇键因为向量存储的 InvariantKey 最多支持 255 个键列见 check_key_column_count()CDC 约束不允许在 CDC 被显式关闭的表上建向量索引check_cdc_not_explicitly_disabled() 的报错文案给出了具体参数要求——CDC TTL 必须至少 24 小时且 CDC 的 delta mode 需为full或开启 postimage之后才能创建向量索引。相似度查询语法与执行链路CQL 相似度函数ScyllaDB 在 CQL 层实现了三个原生标量相似度函数定义于 cql3/functions/vector_similarity_fcts.hhsimilarity_cosinesimilarity_euclideansimilarity_dot_product三者都是float (*)(spanconst float, spanconst float)形态的原生标量函数返回float。索引未显式指定similarity_function时CQL 侧默认对应similarity_cosine见 get_cql_similarity_function_name()。ANN 排序ORDER BY ... ann()向量近邻ANN查询通过ORDER BY子句中的ann(列, 查询向量)排序函数表达例如SELECT ... FROM ks.t ORDER BY ks.ann(v, [0.1, 0.2, 0.3]) LIMIT 5可参考 test/cqlpy/test_invalid_ann_queries.py 中的写法。查询的语义与限制集中在 vector_indexed_table_select_statement.cc必须指定LIMIT否则报错 “Vector ANN queries must have a limit specified”L191-L197不支持 per-partition limitPER PARTITION LIMIT不支持聚合查询ANN()暂不支持出现在 WHERE 子句中做分数阈值过滤prepare() 中的注释threshold filtering 尚未实现LIMIT不得超过max_ann_query_limit超出会报 “Use of ANN OF in an ORDER BY clause requires a LIMIT that is not greater than ...”L207-L210。执行链路先取主键再回表核心执行逻辑在 execute_search()计算取回候选数fetch ceil(limit × oversampling)即按索引的oversampling选项放大发给向量存储的查询数量把 WHERE 过滤条件序列化为 JSON filter_prepared_filter.to_json(options)连同超时控制的 abort source 一起调用vector_store_client().ann(keyspace, index, schema, 查询向量, fetch, filter)向向量存储请求近邻主键列表按相似度降序若候选数超过LIMIT且未启用 rescoring直接截断到LIMIT条若启用 rescoring则保留全部候选交由重打分保证精度最后query_base_table()用主键列表回查 ScyllaDB 基表取回完整行数据返回给客户端。这个“ANN 取主键 → 回表取行”的两段式设计使得向量存储只需维护主键与向量的映射基表数据仍由 ScyllaDB 的常规读取路径提供天然继承其低延迟与过滤能力。相似度得分语义向量存储返回的每条主键都携带similarity得分语义定义在 vector_store_client.hh 的 primary_key 结构值越高越相似结果集按得分降序排列cosine与euclidean的得分范围是[0.0, 1.0]非归一化向量下的dot_product得分无界。服务端与向量存储的通信机制ScyllaDB 节点通过 vector_search/vector_store_client 这个 peering sharded service 与外部向量存储通信。除ann()之外它还暴露了bm25(keyspace, index, schema, 查询串, limit)请求向量存储返回全文检索BM25 相关性得分降序的主键列表说明该向量存储同时兼任全文检索后端get_index_status(keyspace, index)查询单个向量索引的运行状态index_status 枚举分为三档creating索引尚未就绪初始化中、未被发现或向量存储不可达backfilling索引正在对基表做初始全量扫描回填查询可以服务但结果不完整serving初始扫描完成索引完全可用。故障处理方面ann_error是一个 variant包含disabled客户端未配置、功能关闭、aborted超时/取消、addr_unavailable无可用节点、service_unavailable、service_error、service_reply_format_error等类型vector_store_client.hh查询失败时会经由ann_error_visitor转换为 CQL 异常抛给客户端。目录下的 load_balancer.hh、dns.cc、truststore.cc 分别负责多节点负载均衡、DNS 解析与 TLS 信任链管理clients.cc 管理主/备两组向量存储节点池。端到端行为健康检查、故障切换、DNS 刷新等由 test/vector_search/vector_store_client_test.cc 系统性覆盖其中包含大量针对ann()在节点不可用场景下的切换断言。相关服务端配置项向量搜索相关的服务端参数定义在 db/config.cc“Vector search settings”分组声明见 db/config.hh配置项默认值说明vector_store_primary_uri空主向量存储节点 URI 的逗号分隔列表向量搜索优先使用这些节点vector_store_secondary_uri空备向量存储节点 URI 列表仅当所有主节点不可用时作为 fallback通常部署在不同可用区以获得高可用vector_store_unreachable_node_detection_time_in_ms3000判定节点不可达的时间窗口毫秒同时作用于 TCP 连接超时、keepalive 参数、TCP_USER_TIMEOUT以及健康检查请求的 deadline任一机制在该窗口内检测到节点不可达客户端即切换到下一个可用节点vector_store_encryption_options空HTTPS 连接的加密选项目前提供truststore存放受信服务器证书未设置时使用系统 truststore前三项均为LiveUpdate级别支持在线修改。这些配置解释了vector_store_client为什么以“URI 列表 健康检测窗口”的方式工作节点在启动时即按配置建立主/备节点池并在运行中按上述不可达窗口持续做故障切换。此外还有一个生态兼容开关 enable_cassio_compatibility开启后 ScyllaDB 会把 CassIO 对 map 条目发起的 SAI 索引 DDL如CREATE CUSTOM INDEX ... ON table(ENTRIES(col))重写为普通二级索引使 LangChain/CassIO 应用无需改 DDL 即可运行默认关闭。相关测试与验证入口仓库中与向量搜索直接相关的测试test/cqlpy/test_vector_similarity.pyCQL 层similarity_*函数与ORDER BY ann()的端到端行为test/cqlpy/test_vector_search_rescoring_with_mock.py量化 rescoring 场景下的取回与截断逻辑test/cqlpy/cassandra_tests/vector_invalid_query_test.py非法向量查询的报错路径test/vector_search/vector_store_client_test.cc向量存储客户端的 C 单元测试可用 vector_store_client_tester 注入 DNS 解析器、超时等test/cqlpy/test_invalid_ann_queries.pyann()排序查询的非法用法验证。小结ScyllaDB 的 Vector Search 是一套“CQL 语法 外部向量存储”的组合vector索引负责声明目标列、HNSW 参数、量化与 rescoring 策略并强制 Tablets 与 CDC 前置条件查询经ORDER BY ann()与 CQLsimilarity_*函数表达执行时按oversampling放大候选、向向量存储取主键、再回表取行服务端则以主/备 URI 列表加不可达检测窗口实现向量存储节点的高可用故障切换。该特性目前仅在 ScyllaDB Cloud 提供但上述索引、查询、配置与通信机制均已完整存在于本仓库源码中可作为理解与验证这一特性的全部依据。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ScyllaDB Vector Search 向量搜索：在 NoSQL 存储上构建语义相似度查询
ScyllaDB Vector Search 向量搜索在 NoSQL 存储上构建语义相似度查询【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文基于仓库文档docs/features/vector-search.rst及其对应实现源码展开先说明 Vector Search 解决什么问题、适用于哪些工作负载、以及当前的可用性范围再结合 vector_index 实现、vector_store_client 客户端、相似度函数 与 SELECT 执行路径深入讲解向量索引的创建约束、HNSW 索引参数、相似度查询的执行链路以及服务端与向量存储vector store之间的配置与故障切换机制。读完后你可以完整理解 ScyllaDB 中向量搜索“从建索引到出结果”的整条技术脉络。什么是向量搜索Vector SearchVector Search 使应用能够基于高维数据的相似性进行查询而不是精确匹配。它的作用对象是向量嵌入embeddings——把文本、图片、音频、用户行为等数据转成的、能捕捉语义含义的数值表示。典型查询包括“找出与这段话相似的文档”“找出与用户刚浏览的商品相似的商品”“找出与此工单相关的历史工单”与依赖精确值或关键字的传统查询不同Vector Search 按向量之间的距离或相似度返回结果。这一能力正被大量用于现代 AI 工作负载AI 驱动的搜索、推荐系统以及检索增强生成RAG流水线。为什么在 ScyllaDB 上做向量搜索很多应用已经依赖 ScyllaDB 提供高吞吐、低且可预测的延迟以及大规模数据存储。Vector Search 在此基础上补齐了新一类工作负载文本或文档的语义搜索基于用户/商品相似度的推荐包括 RAG 流水线在内的 AI/ML 应用异常检测与模式识别也就是说ScyllaDB 可以作为 AI 应用的相似度搜索后端与原有业务数据共存于同一套高吞吐存储中。当前可用性根据 官方特性文档Vector Search目前仅在 ScyllaDB Cloud全托管 ScyllaDB 服务中提供。具体使用方式以 ScyllaDB Cloud 文档为准开源仓库中提供的是该特性所需的索引定义、查询语法、客户端与服务端配置等完整支撑代码。向量索引的定义与约束ScyllaDB 中向量索引是一种外部索引external index索引类型名为vector搜索类型名为 “Vector Search”见 index/vector_index.hh。它不存储 ScyllaDB 自身维护的倒排结构而是把检索请求委托给配套的向量存储服务vector store。索引目标列规则从 vector_index.cc 的 check_target() 可以看到对目标列的硬性校验第一目标列必须是向量列且类型必须是“float 向量”vectorfloat否则报错 “Vector indexes are only supported on columns of vectors of floats”其后可以附加过滤列filtering columns只支持可作为主键列使用的原生类型如ascii、boolean、int、bigint、text、timestamp、uuid、decimal等不支持 counter、duration 等类型还支持**局部索引local index**语法以(p1, p2)形式的分区键列表 向量列即按分区键范围约束搜索。目标序列化的格式在 serialize_targets() 中实现内部用 JSON 键表示tc向量目标列、pk分区键列局部索引用、fc过滤列例如(v) - v (v, f1, f2) - {tc:v,fc:[f1,f2]} ((p1, p2), v) - {tc:v,pk:[p1,p2]} ((p1, p2), v, f1) - {tc:v,pk:[p1,p2],fc:[f1]}索引选项index options索引支持的全部选项定义在 vector_index.cc 的 vector_index_options 表 中未知选项会被直接拒绝“Unsupported option ... for vector index”。各选项的含义、约束与底层作用如下选项取值 / 范围说明similarity_functioncosine/euclidean/dot_product向量相似度计算方法向量存储在索引构建与查询内部使用CQL 侧有对应的similarity_*函数见下文maximum_node_connections正整数上限 512HNSW 图索引参数单个节点最大连接数construction_beam_width正整数上限 4096HNSW 索引参数构建时的搜索束宽度search_beam_width正整数上限 4096HNSW 索引参数查询时的搜索束宽度quantizationf32/f16/bf16/i8/b1向量在向量存储中的量化压缩方式注意不压缩基表中的原始向量Scylla 用它判断是否启用 rescoringoversampling1.0 100.0 的浮点系数从向量存储拉取候选数量的放大倍数可提升 ANN 精度尤其配合量化 rescoring 时rescoringtrue/false量化场景下对候选重新计算相似度得分以恢复精度source_model任意字符串Cassandra SAI 兼容选项记录产生向量的嵌入模型名ScyllaDB 接受但不使用其中 HNSW 三参数被源码注释明确标注为“define HNSW index parameters, Used internally by vector store”即由向量存储解释而oversampling的注释写明“Used by Scylla during query processing to increase query limit sent to vector store”——它由Scylla 侧在查询处理时消费见下文执行链路。rescoring 的启用条件在 is_rescoring_enabled() 中实现量化方式不是f32即真的做了压缩且rescoring true才生效get_oversampling()在选项缺省时返回 1.0。建索引的前置条件validate() 汇总了所有建索引校验要求使用 Tablets 分区策略check_uses_tablets目标列类型校验上文主键列总数上限 255分区键 聚簇键因为向量存储的 InvariantKey 最多支持 255 个键列见 check_key_column_count()CDC 约束不允许在 CDC 被显式关闭的表上建向量索引check_cdc_not_explicitly_disabled() 的报错文案给出了具体参数要求——CDC TTL 必须至少 24 小时且 CDC 的 delta mode 需为full或开启 postimage之后才能创建向量索引。相似度查询语法与执行链路CQL 相似度函数ScyllaDB 在 CQL 层实现了三个原生标量相似度函数定义于 cql3/functions/vector_similarity_fcts.hhsimilarity_cosinesimilarity_euclideansimilarity_dot_product三者都是float (*)(spanconst float, spanconst float)形态的原生标量函数返回float。索引未显式指定similarity_function时CQL 侧默认对应similarity_cosine见 get_cql_similarity_function_name()。ANN 排序ORDER BY ... ann()向量近邻ANN查询通过ORDER BY子句中的ann(列, 查询向量)排序函数表达例如SELECT ... FROM ks.t ORDER BY ks.ann(v, [0.1, 0.2, 0.3]) LIMIT 5可参考 test/cqlpy/test_invalid_ann_queries.py 中的写法。查询的语义与限制集中在 vector_indexed_table_select_statement.cc必须指定LIMIT否则报错 “Vector ANN queries must have a limit specified”L191-L197不支持 per-partition limitPER PARTITION LIMIT不支持聚合查询ANN()暂不支持出现在 WHERE 子句中做分数阈值过滤prepare() 中的注释threshold filtering 尚未实现LIMIT不得超过max_ann_query_limit超出会报 “Use of ANN OF in an ORDER BY clause requires a LIMIT that is not greater than ...”L207-L210。执行链路先取主键再回表核心执行逻辑在 execute_search()计算取回候选数fetch ceil(limit × oversampling)即按索引的oversampling选项放大发给向量存储的查询数量把 WHERE 过滤条件序列化为 JSON filter_prepared_filter.to_json(options)连同超时控制的 abort source 一起调用vector_store_client().ann(keyspace, index, schema, 查询向量, fetch, filter)向向量存储请求近邻主键列表按相似度降序若候选数超过LIMIT且未启用 rescoring直接截断到LIMIT条若启用 rescoring则保留全部候选交由重打分保证精度最后query_base_table()用主键列表回查 ScyllaDB 基表取回完整行数据返回给客户端。这个“ANN 取主键 → 回表取行”的两段式设计使得向量存储只需维护主键与向量的映射基表数据仍由 ScyllaDB 的常规读取路径提供天然继承其低延迟与过滤能力。相似度得分语义向量存储返回的每条主键都携带similarity得分语义定义在 vector_store_client.hh 的 primary_key 结构值越高越相似结果集按得分降序排列cosine与euclidean的得分范围是[0.0, 1.0]非归一化向量下的dot_product得分无界。服务端与向量存储的通信机制ScyllaDB 节点通过 vector_search/vector_store_client 这个 peering sharded service 与外部向量存储通信。除ann()之外它还暴露了bm25(keyspace, index, schema, 查询串, limit)请求向量存储返回全文检索BM25 相关性得分降序的主键列表说明该向量存储同时兼任全文检索后端get_index_status(keyspace, index)查询单个向量索引的运行状态index_status 枚举分为三档creating索引尚未就绪初始化中、未被发现或向量存储不可达backfilling索引正在对基表做初始全量扫描回填查询可以服务但结果不完整serving初始扫描完成索引完全可用。故障处理方面ann_error是一个 variant包含disabled客户端未配置、功能关闭、aborted超时/取消、addr_unavailable无可用节点、service_unavailable、service_error、service_reply_format_error等类型vector_store_client.hh查询失败时会经由ann_error_visitor转换为 CQL 异常抛给客户端。目录下的 load_balancer.hh、dns.cc、truststore.cc 分别负责多节点负载均衡、DNS 解析与 TLS 信任链管理clients.cc 管理主/备两组向量存储节点池。端到端行为健康检查、故障切换、DNS 刷新等由 test/vector_search/vector_store_client_test.cc 系统性覆盖其中包含大量针对ann()在节点不可用场景下的切换断言。相关服务端配置项向量搜索相关的服务端参数定义在 db/config.cc“Vector search settings”分组声明见 db/config.hh配置项默认值说明vector_store_primary_uri空主向量存储节点 URI 的逗号分隔列表向量搜索优先使用这些节点vector_store_secondary_uri空备向量存储节点 URI 列表仅当所有主节点不可用时作为 fallback通常部署在不同可用区以获得高可用vector_store_unreachable_node_detection_time_in_ms3000判定节点不可达的时间窗口毫秒同时作用于 TCP 连接超时、keepalive 参数、TCP_USER_TIMEOUT以及健康检查请求的 deadline任一机制在该窗口内检测到节点不可达客户端即切换到下一个可用节点vector_store_encryption_options空HTTPS 连接的加密选项目前提供truststore存放受信服务器证书未设置时使用系统 truststore前三项均为LiveUpdate级别支持在线修改。这些配置解释了vector_store_client为什么以“URI 列表 健康检测窗口”的方式工作节点在启动时即按配置建立主/备节点池并在运行中按上述不可达窗口持续做故障切换。此外还有一个生态兼容开关 enable_cassio_compatibility开启后 ScyllaDB 会把 CassIO 对 map 条目发起的 SAI 索引 DDL如CREATE CUSTOM INDEX ... ON table(ENTRIES(col))重写为普通二级索引使 LangChain/CassIO 应用无需改 DDL 即可运行默认关闭。相关测试与验证入口仓库中与向量搜索直接相关的测试test/cqlpy/test_vector_similarity.pyCQL 层similarity_*函数与ORDER BY ann()的端到端行为test/cqlpy/test_vector_search_rescoring_with_mock.py量化 rescoring 场景下的取回与截断逻辑test/cqlpy/cassandra_tests/vector_invalid_query_test.py非法向量查询的报错路径test/vector_search/vector_store_client_test.cc向量存储客户端的 C 单元测试可用 vector_store_client_tester 注入 DNS 解析器、超时等test/cqlpy/test_invalid_ann_queries.pyann()排序查询的非法用法验证。小结ScyllaDB 的 Vector Search 是一套“CQL 语法 外部向量存储”的组合vector索引负责声明目标列、HNSW 参数、量化与 rescoring 策略并强制 Tablets 与 CDC 前置条件查询经ORDER BY ann()与 CQLsimilarity_*函数表达执行时按oversampling放大候选、向向量存储取主键、再回表取行服务端则以主/备 URI 列表加不可达检测窗口实现向量存储节点的高可用故障切换。该特性目前仅在 ScyllaDB Cloud 提供但上述索引、查询、配置与通信机制均已完整存在于本仓库源码中可作为理解与验证这一特性的全部依据。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考