Redis Vector Set 做语义检索：向量、元数据与过滤条件

Redis Vector Set 适合把“元素标识 + 向量 + 少量 JSON 元数据”放进同一个原生数据类型，再用 VSIM 同时完成近似向量检索和顶层属性过滤。真正需要先设计的不是命令，而是三件事：向量维度必须一致，元数据类型必须稳定，过滤条件要能在候选搜索成本与召回率之间取得平衡。

官方文档：https://redis.io/docs/latest/develop/data-types/vector-sets/

我遇到的典型场景是一个内部知识库：应用已经生成了文档 embedding，但向量放在一处、标题和分类放在 Hash、过滤逻辑又写在业务代码里。数据量不大，却要维护多套键和二次过滤。Redis 8 引入的 Vector Set 可以把这个轻量场景收回到一组原生命令里，但它不是 Redis Query Engine 的无条件替代品。

先确认这次迁移是不是 Vector Set 的范围

Vector Set 从 Redis 8.0 开始提供，底层使用近似向量搜索。它特别适合“给定一个查询向量，找最相似的若干元素，再用少量标量条件缩小结果”的任务。官方资料同时强调，它与 Redis Query Engine 是互补关系。

如果现有系统已经依赖复杂 FT.SEARCH 查询，不应仅因为 Redis 8 出现新数据类型就整体迁移。本文只处理轻量语义检索这一条边界。

把语义检索拆成四个数据对象

一个 Vector Set key 代表一个向量集合；集合里的每个 element 是稳定字符串标识；vector 是用于相似度计算的浮点数组；JSON attributes 则保存分类、语言、年份等可过滤信息。把完整正文塞进 attributes 不是好主意，它更适合小而稳定的过滤字段。

这里有两个容易踩的坑。第一，同一个集合里的向量维度必须一致。第二，过滤字段的类型要稳定，例如 year 始终使用数字，不能一部分写成 2026，另一部分写成字符串 "2026"。

旧的分散存储为什么容易让过滤失真

旧实现常把向量结果先取回应用，再去 Hash 或数据库补元数据，最后在应用层过滤。这样做会出现两个问题：相似度 Top K 被不符合条件的元素占满，过滤后剩余数量不足；向量和元数据更新不是同一条写入路径，容易出现 element 已存在但属性缺失。

Vector Set 的迁移目标不是“少写一个 key”这么简单，而是让向量、element 和过滤属性共享同一个生命周期。对于已有 element，可以用 VSETATTR 单独更新属性；需要读取属性时，用 VGETATTR 回查。

用 VADD 同时写入向量与元数据

下面用 4 维玩具向量演示命令结构。真实 embedding 往往有更高维度，必须使用模型实际输出的固定维度。VALUES 接受字符串形式的浮点数，跨平台演示更直观；如果使用 FP32 二进制 blob，官方文档要求采用 little-endian 字节序。

# 写入第一条文档向量，并把分类、语言和年份作为顶层 JSON 属性绑定。
redis-cli VADD docs:vset VALUES 4 0.82 0.11 0.43 0.36 doc:redis-filter \
  SETATTR '{"category":"redis","lang":"zh","year":2026}'

# 写入同维度的 Go 文档，保持 year 为数字类型，便于后续比较过滤。
redis-cli VADD docs:vset VALUES 4 0.21 0.76 0.31 0.49 doc:go-http \
  SETATTR '{"category":"go","lang":"zh","year":2025}'

# 写入英文 Redis 文档，为语言过滤准备一个对照元素。
redis-cli VADD docs:vset VALUES 4 0.79 0.13 0.47 0.32 doc:redis-en \
  SETATTR '{"category":"redis","lang":"en","year":2024}'

如果元数据晚于向量到达，可以补写：

# 单独更新已有 element 的 JSON 属性；空字符串可用于移除属性。
redis-cli VSETATTR docs:vset doc:redis-en \
  '{"category":"redis","lang":"en","year":2026}'

# 回查属性，确认应用写入的字段名和类型与过滤表达式一致。
redis-cli VGETATTR docs:vset doc:redis-en

用 VSIM 同时做相似度与过滤

VSIM 可以直接接收查询向量，也可以使用集合中已有 element 的向量。FILTER 在 JSON attributes 上做标量判断，COUNT 控制返回数量，WITHSCORES 和 WITHATTRIBS 便于应用同时取得相似度信息与属性。

# 查询与输入向量最相似的 5 条中文 Redis 文档，并返回分数和属性。
redis-cli VSIM docs:vset VALUES 4 0.80 0.12 0.44 0.35 \
  COUNT 5 WITHSCORES WITHATTRIBS \
  FILTER '.category == "redis" && .lang == "zh"'

# 过滤较稀有时提高候选检查量，换取更完整的过滤后结果。
redis-cli VSIM docs:vset VALUES 4 0.80 0.12 0.44 0.35 \
  COUNT 5 FILTER '.category == "redis" && .year >= 2026' \
  FILTER-EF 1000

过滤表达式支持算术、比较、逻辑、in 和括号，但只能访问顶层字段。字段缺失、JSON 无效或字段类型与表达式不匹配时，该 element 会被静默跳过，而不是返回错误。这也是“明明相似却搜不到”最常见的原因之一。

FILTER-EF 控制为了凑齐过滤后结果而检查多少候选节点，默认值是 COUNT * 100。过滤条件越稀有，越可能需要提高它；设置为 0 会按需要继续扫描，但代价是更高的查询开销。不要把它固定成极大值后就忘记，应结合延迟与召回做压测。

回归检查要覆盖维度、量化和召回

Vector Set 默认会对向量做量化，因此 VEMB 读回的坐标不一定与写入值完全相同。量化能节省内存并提升性能，但会影响精度。若业务对召回敏感，应在代表性数据集上比较默认模式、NOQUANT 或其他量化选项，而不是只看一两个样例。

• 用 VDIM docs:vset 确认集合维度，用 VCARD docs:vset 确认元素数量。
• 随机抽查 VGETATTR，确认过滤字段存在且数字、字符串类型一致。
• 分别执行无过滤与有过滤的 VSIM，观察结果数量和相关性变化。
• 召回不足时先提高 EF 或 FILTER-EF，再评估延迟与 CPU 代价。
• 用 TRUTH 做小规模基准对照，但不要把线性扫描直接当成高并发生产默认值。
• 确认客户端、托管服务或部署版本支持 Redis 8 的 Vector Set 命令；该能力的 API 仍应以当前版本文档为准。

迁移上线清单

1. 先确定是否只需要轻量向量检索与顶层元数据过滤；复杂混合查询继续使用 Redis Query Engine。
2. 冻结 embedding 模型与维度，定义稳定的 element 命名规则。
3. 把可过滤元数据扁平化，固定字段名和数据类型。
4. 批量写入前先用小集合验证 VADD、VSETATTR 和 VSIM 的客户端支持。
5. 用真实查询集测量无过滤、有过滤和稀有过滤的召回与延迟。
6. 保留旧查询路径作为回退，完成双读对比后再切换生产流量。

常见问题

Vector Set 能直接保存文档正文吗？

element 本身是字符串标识，attributes 适合保存小型 JSON 过滤字段。大段正文可继续放在 Hash、JSON 或外部存储，通过 element 做关联。

为什么加了 FILTER 后结果少于 COUNT？

可能是候选中符合条件的元素不足，也可能是字段缺失、类型不匹配或过滤候选检查量不够。先用 VGETATTR 检查属性，再评估提高 FILTER-EF。

元数据可以使用嵌套 JSON 吗？

可以保存 JSON，但过滤表达式只支持顶层字段访问。需要按嵌套对象过滤时，应先扁平化字段，或改用支持复杂索引的 Redis Query Engine。

VSIM 是精确检索吗？

常规查询基于近似向量搜索。可以用 EF 调整搜索探索程度，并用 TRUTH 做精确线性扫描对照，但后者更慢。