scylladb-vector-search

ScyllaDB 向量搜索

如果任务超出此技能的范围，请使用上级 scylladb 技能了解 ScyllaDB 概览及其他 ScyllaDB 技能列表。如果未安装，请从 https://raw.githubusercontent.com/scylladb/agent-skills/main/skills/scylladb/SKILL.md 获取。

向量搜索会将嵌入存储在 vector<float, N> 列中，并通过 HNSW 向量索引执行近似最近邻（ANN）查询。生产环境中仅 ScyllaDB Cloud 提供此功能。索引在表之外维护，因此 TRUNCATE 不会清除索引。

何时使用此技能

• 用户希望在 ScyllaDB 中存储嵌入并运行相似度搜索
• 用户正在 ScyllaDB 上构建语义搜索、RAG 或推荐系统
• 用户正在创建向量索引或调整 HNSW 参数
• 用户需要将 ANN 查询与其他列上的筛选条件结合使用
• 用户希望通过量化减少向量索引的内存占用
• 用户需要支持 vector CQL 类型的驱动程序版本
• 用户希望通过 Docker 在本地或 CI 中试用向量搜索

对于相关主题，请改用对应的同级技能：

• 非向量部分的分区键和表设计：scylladb-data-modeling
• 连接 Cloud 集群并选择驱动程序：scylladb-cloud-setup
• 通过 DynamoDB API 而不是 CQL 执行相似度搜索：scylladb-alternator

向量搜索的运行位置

• 生产环境：仅 ScyllaDB Cloud。 向量搜索在专用索引节点上运行，这些节点由 ScyllaDB Cloud 管理，并通过 CDC 与存储节点同步。不支持自托管和本地部署。如果用户计划在生产环境中采用这些部署方式，请告知他们，向量搜索需要启用了向量搜索的标准 ScyllaDB Cloud 集群。
• 开发和测试：本地 Docker。 运行一个 ScyllaDB 容器和一个单独的 scylladb/vector-store 容器（索引服务），并将它们连接起来。请参阅 local-docker。

核心原则

1. 先了解，再构建 — 验证用例，确保向量搜索是合适的解决方案
2. 先检查架构 — 在提出建议之前，检查现有表和索引
3. 先说明，再执行 — 说明将创建哪些索引，并在继续之前获得确认
4. 从默认值开始 — 使用默认 HNSW 参数且不启用量化；仅在需要时调整

工作流

1. 需求发现阶段

了解用例：

• 他们要搜索什么类型的数据？（文本、图像、音频、结构化数据）
• 他们正在使用或计划使用哪种嵌入模型？
• 他们将存储多少个向量？（这会影响量化决策）
• 他们是否需要在相似度搜索时进行筛选？（这会影响索引类型：全局索引还是本地索引）
• 他们对延迟和吞吐量有什么要求？

常见用例：

• 语义搜索 — 查找与查询含义相符的文档或段落
• RAG（检索增强生成） — 为大模型提供相关上下文
• 推荐系统 — 查找与用户交互过的项目相似的项目
• 图像／音频搜索 — 查找视觉或听觉上相似的媒体
• 异常检测 — 识别在向量空间中远离聚类的离群点
• 去重 — 查找近似重复的记录

2. 确定需求

创建表和索引之前，请确定：

参数	确定方法
维度	根据嵌入模型确定（例如，384、768、1536）
相似度函数	根据嵌入模型文档确定（COSINE 是默认值，适用于大多数情况）
是否需要筛选？	查询是否会将相似度搜索与元数据约束结合？
数据集大小	< 1M 个向量 → 不使用量化；1M-10M → 考虑使用 i8；> 10M → 考虑使用 b1

3. 查阅参考文件

在推荐索引或查询之前，务必查阅 快速参考 中对应的文件。

4. 实现

典型的实现顺序：

1. 创建一个键空间（默认启用 tablets）
2. 创建一个包含 vector<float, N> 列的表
3. 插入向量（来自你的嵌入流水线）
4. 创建向量索引（CREATE CUSTOM INDEX ... USING 'vector_index'）
5. 执行 ANN 查询（ORDER BY vec_col ANN OF [...] LIMIT k）
6. 如有需要，添加过滤条件（出于性能考虑，优先使用本地索引）
7. 如有需要，添加量化以节省内存

5. 验证

设置完成后，请确认：

• ANN 查询能返回结果（插入向量后等待约 1 秒，以考虑写入到查询的延迟）
• 相似度分数处于预期范围内（0-1，越高表示越相似）
• 过滤查询能正确返回经过筛选的结果

应避免的反模式

使用本地索引即可满足需求时，绝不要在向量搜索中使用 ALLOW FILTERING： 全局向量索引在添加 WHERE 子句时需要使用 ALLOW FILTERING，而且总是比本地索引慢得多。请合理设计架构，将过滤列纳入分区键，并使用本地向量索引。

绝不要混用嵌入模型： 不同嵌入模型生成的向量位于彼此不兼容的向量空间中。如果更换模型，就必须重新嵌入并重新索引所有数据。

绝不要省略 LIMIT 子句： ANN 查询必须包含 LIMIT——否则 ScyllaDB 会拒绝该查询。

处理边缘情况

用户尚未准备好嵌入模型：

• 建议从 all-MiniLM-L6-v2 开始（384 维、开放权重、通用性强）
• 用于生产环境时，建议评估 OpenAI 或 Cohere 的嵌入模型

用户的集群未启用 Vector Search：

• 指引他们前往 ScyllaDB Cloud UI → 集群设置 → 启用 Vector Search
• 设置方法参见 Vector Search 部署
• 在本地 Docker 环境中，检查 vector-store 容器是否正在运行，以及 ScyllaDB 是否设置了 --vector-store-primary-uri（参见 本地 Docker）

查询未返回结果：

• 检查写入到查询的延迟（插入后延迟约 1 秒）
• 确认查询向量的维度与索引维度一致
• 确认索引已成功创建
• 确保索引和查询使用的是同一个嵌入模型

需要 TTL：

• 向量索引不支持 TTL。解决方法：使用应用层删除，并通过后台任务删除过期行。

用户想清除所有向量（重置表）：

• TRUNCATE 不会清除向量索引。向量存储仅通过 CDC 更新索引，而 TRUNCATE 不会传播到 CDC——CUSTOM INDEX 仍然存在，先前索引的向量也仍会留在内存中。
• 唯一正确的解决方案是删除并重新创建表和自定义索引。具体 DDL 参见 向量类型与索引。

快速参考

• vector-type-and-indexing — vector 类型、对 tablets 的要求、CREATE CUSTOM INDEX ... USING 'vector_index'、相似度函数、HNSW 参数，以及 TRUNCATE 不会清空索引的原因。在创建向量表或索引前，或用户想要重置向量数据时，请查阅。
• ann-queries — ORDER BY ... ANN OF ... LIMIT 语法、相似度分数、写入到查询的延迟，以及 ANN 查询不支持的 CQL 功能。在编写或调试 ANN 查询时，请查阅。
• filtering — 全局与本地向量索引、用于筛选搜索和多租户搜索的架构设计及其局限性。在 ANN 查询需要 WHERE 子句时，请查阅。
• quantization — 量化级别（f16、bf16、i8、b1）、过采样、重新评分，以及索引选项在创建后无法更改的原因。在数据集超过约 1M 个向量或关注索引内存时，请查阅。
• driver-integration — 支持 vector 类型的最低驱动版本，以及 Python、Java、Go 和 Node.js 中的插入与查询示例。在编写读取或写入向量的应用代码时，请查阅。
• local-docker — 在 Docker 中同时运行 ScyllaDB 和 Vector Store 服务、用于连接二者的标志和环境变量，以及此配置不适用于生产环境的原因。用户想要在本地、CI 或测试中使用 Vector Search，或没有 ScyllaDB Cloud 集群时，请查阅。