(四十四)Redis8 新增的数据类型 -- Vector Set

摘要

本文介绍 Redis8 新增的数据类型 Vector Set
Redis官网：https://redis.io/

Vector Set 命令说明

一、基础管理类

命令	作用	语法	参数说明	示例
VADD	向向量集合中添加一个向量元素	`VADD key VALUES num vector element`	`key`：向量集合名 `vector`：向量数据（浮点数组） `element`：元素标识	`VADD user:embeddings VALUES 3 0.1 0.2 0.3 u1`
VREM	从向量集合中删除一个或多个元素	`VREM key element`	`key`：向量集合 `element`：元素标识	`VREM user:embeddings u1`
VCARD	返回向量集合中的元素数量	`VCARD key`	`key`：向量集合	`VCARD user:embeddings`
VDIM	获取向量集合的维度	`VDIM key`	`key`：向量集合	`VDIM user:embeddings`
VINFO	查看向量集合的元信息	`VINFO key`	`key`：向量集合	`VINFO user:embeddings`

VADD 命令参数详解

语法

bash 复制代码

VADD key
     [REDUCE dim]
     (FP32 | VALUES num) vector
     element
     [CAS]
     [NOQUANT | Q8 | BIN]
     [EF build-exploration-factor]
     [SETATTR attributes]
     [M numlinks]

必需参数

参数	参数类型	作用	语法 / 格式	说明
`key`	String	向量集合名称	`VADD key ...`	Redis 中用于存储向量集合的键名。如果不存在会自动创建集合。
`FP32 vector`	Binary	直接传入二进制浮点向量	`FP32 <binary>`	以小端序编码的 32 位浮点数组，适合客户端直接传二进制向量数据（高性能、低序列化开销）。
`VALUES num vector`	Numeric List	以数值方式传入向量	`VALUES <num> <v1> <v2> ... <vN>`	`num` 为向量维度，后面必须跟随 `num` 个浮点数。适合在 CLI 或调试场景使用。
`element`	String	向量元素 ID	`<element>`	向量在集合中的唯一标识符，可理解为向量的主键或业务 ID。

重点说明：客户端实现时推荐直接传 FP32 二进制向量，避免浮点字符串解析开销。

可选参数

参数	参数类型	作用	语法约束	说明
`REDUCE dim`	Integer	向量降维	必须紧跟在 key 后面	使用随机投影算法将原始向量降维到 `dim` 维，降低存储与计算成本。如果原始向量维度 > dim → 是"降维" 如果原始向量维度 < dim → 是"升维 / 填充映射"
`CAS`	Flag	异步构建索引	可放在 element 后	采用 Check-And-Set 风格：主线程快速返回，后台异步完成候选集构建，提高写入吞吐。
`NOQUANT`	Flag	禁用量化	仅首次创建集合时生效	不使用默认 int8 量化，保留原始浮点精度，内存占用更高。
`Q8`	Flag	启用 int8 量化（默认）	仅首次创建集合时生效	使用有符号 8 位量化，在精度、性能和内存之间取得平衡。
`BIN`	Flag	二进制量化	仅首次创建集合时生效	内存占用最小、速度最快，但相似度召回率可能下降。
`EF build-exploration-factor`	Integer	构图探索因子	可放在 element 后	HNSW 构图阶段的搜索宽度参数，默认约 200，值越大构图质量越高，但写入成本增加。
`SETATTR attributes`	JSON	设置向量属性	可放在 element 后	给元素绑定 JSON 属性，等价于调用 `VSETATTR`。
`M numlinks`	Integer	HNSW 最大连接数	可放在 element 后	每个节点允许的最大邻居数，默认 16。值越大索引更稠密，查询质量更高，但内存和写入成本上升。

示例：使用 VALUES

bash 复制代码

VADD my_vectors VALUES 3 0.1 1.2 0.5 image123
# 解释：
#    将向量 [0.1, 1.2, 0.5] 添加到键 my_vectors 对应的向量结构中。
#    元素名为 image123。
#    如果该键不存在，则创建新向量集。

示例：使用降维和量化选项

bash 复制代码

VADD my_vectors REDUCE 50 VALUES 5 0.02 0.89 0.77 0.56 0.33 pic_001 Q8 EF 300 M 32
# 解释：
#    对向量 REDUCE 到 50 维，这里原始数据维度小，实际上是升维
#    向量为 5 维浮点数值。
#    使用默认的带符号 8 位量化（Q8）。
#    设置 HNSW 图探索因子为 300。
#    每节点连接数上限为 32。

# 获取向量维度
127.0.0.1:6379> VDIM my_vectors
(integer) 50
# 获取向量信息，输出内容见下表中的说明
127.0.0.1:6379> VINFO my_vectors
 1) quant-type
 2) int8
 3) hnsw-m
 4) (integer) 32
 5) vector-dim
 6) (integer) 50
 7) projection-input-dim
 8) (integer) 5
 9) size
10) (integer) 1
11) max-level
12) (integer) 0
13) attributes-count
14) (integer) 0
15) vset-uid
16) (integer) 0
17) hnsw-max-node-uid
18) (integer) 1

VINFO 输出字段说明表

字段名	当前值	类型	含义说明	工程解读 / 使用价值
`quant-type`	`int8`	String	向量量化方式	当前使用 Q8（8位有符号整数量化），在精度、性能、内存之间平衡。
`hnsw-m`	`32`	Integer	HNSW 每节点最大连接数（M 参数）	图结构较稠密，召回率高，但内存占用和写入成本上升。
`vector-dim`	`50`	Integer	索引内部真实使用的向量维度	REDUCE 后的目标维度，VSIM / VRANGE 查询均基于此维度计算。
`projection-input-dim`	`5`	Integer	投影前输入向量的原始维度	说明你输入的是 5维向量，然后被映射到 50 维。
`size`	`1`	Integer	当前向量元素数量	集合中仅有 1 条向量数据（item42）。
`max-level`	`0`	Integer	HNSW 当前最大层级	数据量太小，仅构建了 0 层（尚未形成多层索引结构）。
`attributes-count`	`0`	Integer	当前已存储的属性对象数量	说明 SETATTR 没有成功写入或尚未设置属性。
`vset-uid`	`0`	Integer	向量集合内部唯一 ID	内部调试字段，对业务无直接影响。
`hnsw-max-node-uid`	`1`	Integer	HNSW 当前最大节点 ID	当前仅存在 1 个节点。

示例：添加带属性的向量

bash 复制代码

VADD my_vectors VALUES 4 0.15 0.26 0.47 0.88 item42 SETATTR "{\"type\":\"product\",\"price\":29.99}"
# 解释：
   # 插入 4 维向量并给 item42 设置 JSON 属性 type 和 price。

# 获取向量属性
127.0.0.1:6379> VGETATTR my_vectors item42
"{\"type\":\"product\",\"price\":29.99}"

示例：插入多条数据

只有维度、quant-type 和 hnsw-m都相同的数据才会被加入同一个 VectorSet

VectorSet 在第一次创建时就固定了相关的属性

bash 复制代码

127.0.0.1:6379> VADD my_vectors VALUES 4 0.15 0.26 0.47 0.88 item42 SETATTR "{\"type\":\"product\",\"price\":29.99}"
(integer) 1
127.0.0.1:6379> VADD my_vectors VALUES 4 0.25 0.20 0.57 0.98 item43
127.0.0.1:6379> VADD my_vectors VALUES 4 0.25 0.20 0.57 0.98 item44 Q8 EF 300 M 16
(integer) 1
127.0.0.1:6379> VADD my_vectors VALUES 4 0.25 0.20 0.57 0.98 item44 Q8 EF 300 M 16
(integer) 0  # 添加重复元素标识，返回 0

# 获取向量数量
127.0.0.1:6379> VCARD my_vectors
(integer) 3
# 获取向量信息
127.0.0.1:6379> VINFO my_vectors
 1) quant-type
 2) int8
 3) hnsw-m
 4) (integer) 16
 5) vector-dim
 6) (integer) 4
 7) projection-input-dim
 8) (integer) 0
 9) size
10) (integer) 2
11) max-level
12) (integer) 0
13) attributes-count
14) (integer) 2
15) vset-uid
16) (integer) 2
17) hnsw-max-node-uid
18) (integer) 2

二、向量元素访问与判断

命令	作用	语法	参数说明	示例
VISMEMBER	判断元素是否存在于向量集合中	`VISMEMBER key element`	`key`：向量集合 `element`：元素标识	`VISMEMBER user:embeddings u1`
VRANDMEMBER	随机返回一个或多个向量元素	`VRANDMEMBER key [count]`	`count`：返回数量，默认为1（可选）	`VRANDMEMBER user:embeddings 2`
VRANGE	返回向量集合中指定范围的元素（按内部顺序）	`VRANGE key start stop [count]`	`start` / `stop`：说明见下表	`VRANGE user:embeddings - + -1`

VRANGE

参数说明

参数	类型	是否必须	描述
`key`	key	是	向量集合的键名
`start`	string	是	范围起始元素（字典序）可用：`[` 前缀表示包含，`(` 前缀表示排除，`-` 表示最小元素
`end`	string	是	范围结束元素（字典序）可用：`[` 前缀表示包含，`(` 前缀表示排除，`+` 表示最大元素
`count`	integer	否	最多返回元素数量若为负数，则返回范围内所有匹配元素（注意可能阻塞）

参数举例说明

参数值	说明
`-`	最小元素（等同 open-ended 从头开始）
`+`	最大元素（等同 open-ended 到尾结束）
`[Redis`	从字典序 ≥ `"Redis"` 的元素开始（包含 `"Redis"`）
`(a7`	从字典序 > `"a7"` 的元素开始（不包含 `"a7"`）

示例 1：返回从 "Redis"（包含）开始的前 10 个元素

bash 复制代码

VRANGE mykey [Redis + 10

示例 2：分段迭代所有元素

bash 复制代码

VRANGE mykey - + 10
# 输出：从最小到最大按每次 10 个元素迭代遍历（客户端可用结果接续下一段）。
# 比如输出最后一个元素是 "Redis"，则下一次迭代从 "Redis" 后面开始。
VRANGE mykey (Redis + 10

示例 3：返回指定范围所有元素（无数量上限）

bash 复制代码

VRANGE mykey - + -1
# 输出：返回整个集合所有元素。注意：若集合很大可能阻塞 Redis。

三、向量属性（Metadata / Attributes）管理

用于给向量元素绑定结构化元数据（如标签、业务字段）

命令	作用	语法	参数说明	示例
VSETATTR	为向量元素设置属性	`VSETATTR key element "{ JSON obj }"`	JSON obj	设置元数据：`VSETATTR key element "{\"type\": \"fruit\", \"color\": \"red\"}"` 清除元数据：`VSETATTR key element ""`
VGETATTR	获取向量元素的属性	`VGETATTR key element`		`VGETATTR user:embeddings u1`

四、向量相似度与检索类（核心）

命令	作用	语法	参数说明	示例
VSIM	基于向量相似度进行近邻搜索（KNN）	详见下面的说明		`VSIM word_embeddings ELE apple`
VLINKS	查看向量之间的近邻链接关系（图结构）	`VLINKS key element [WITHSCORES]`	`element`：向量元素 ID	`VLINKS user:embeddings u1`

VSIM

VSIM 用于在向量集合（vector set）中执行相似度搜索，返回与指定参考向量或已存在元素向量最相似的元素列表。可以进行近似（默认 HNSW 索引）或精确（TRUTH）查询。
语法

bash 复制代码

VSIM key (ELE | FP32 | VALUES num) (vector | element)
   [WITHSCORES] [WITHATTRIBS] [COUNT num]
   [EPSILON delta] [EF search-exploration-factor] [FILTER expression] [FILTER-EF max-filtering-effort]
   [TRUTH] [NOTHREAD]

参数说明

参数 / 选项	类型	是否必需	描述
`key`	key	是	向量集合的键名
`ELE`	literal with element name	是（三者不能同时出现）	使用集合中已有的元素名称作为查询向量
`FP32`	literal	是（三者不能同时出现）	使用二进制 float32 格式提供查询向量
`VALUES num`	literal with integer	是（三者不能同时出现）	使用后续 `num` 个字符串 float 值提供查询向量
`vector` / `element`	vector values or element name	是	查询向量本身（或元素名）
`WITHSCORES`	flag	否	返回每个匹配项的相似度分数
`WITHATTRIBS`	flag	否	返回每个匹配项关联的 JSON 属性（如有）
`COUNT num`	integer	否	限制返回的相似项数量
`EPSILON delta`	float	否	过滤出距离不大于 delta 的结果（score ≥ 1−delta）
`EF search-exploration-factor`	integer	否	调整 HNSW 搜索探索因子（值越高搜索更深、更准确但更慢）。
`FILTER expression`	string	否	对属性进行过滤表达式约束（仅返回满足的元素）
`FILTER-EF max-filtering-effort`	integer	否	限制 FILTER 表达式的评估尝试次数
`TRUTH`	flag	否	强制精确线性扫描（不使用图索引）
`NOTHREAD`	flag	否	在主线程执行搜索而非后台线程

参数/选项说明细节

bash 复制代码

输入向量方式
   ELE elementName：以集合中已有元素的向量作为查询参考。
   FP32：提供 little-endian 编码的二进制浮点向量。
   VALUES num ...：直接以 float 字符串序列作为查询向量，其后跟 num 个浮点值。

输出控制
   WITHSCORES：输出时每个结果后附带 similarity 分数（1 = 完全相同, 0 = 完全不同）。
   WITHATTRIBS：若集合元素有 JSON 属性，则返回对应属性值。
   COUNT num：指定最多返回匹配数量。

搜索行为控制
   EPSILON delta：仅返回与查询向量 distance <= delta 的元素。
   EF search-exploration-factor：HNSW 图搜索的探索因子（值越高搜索更深、更准确但更慢）。
   FILTER expression：基于元素属性进行过滤，例如按年份、分类等。
   FILTER-EF max-filtering-effort：限制 FILTER 表达式的评估尝试次数。
   TRUTH：执行精确线性扫描而非近似图索引。
   NOTHREAD：禁用后台线程，在主线程执行搜索（可能阻塞）。

示例 1 --- 基于现有元素查询（取最相似前 10 个）

bash 复制代码

VSIM my_vectors ELE apple WITHSCORES COUNT 10
# 返回元素 "apple" 最相似的前 10 个元素及其相似度分数。"apple" 必须在集合中存在。

示例 2 --- 基于明确定义的向量查询

bash 复制代码

VSIM my_vectors VALUES 3 0.12 0.34 0.56 WITHSCORES COUNT 5
# 使用向量 [0.12, 0.34, 0.56] 作为查询参考，返回 最相似 的前 5 个结果及分数。

示例 3 --- 精确线性扫描用于基准或严格匹配

bash 复制代码

VSIM my_vectors ELE targetElement TRUTH WITHSCORES
# 绕过 HNSW 索引，执行全量扫描以获取精确的相似度结果。

示例 4 --- 使用属性过滤

bash 复制代码

# 假设集合元素有 JSON 属性如 { "price": 20.99 }
VSIM my_vectors VALUES 4 0.15 0.26 0.47 0.88 FILTER '.price >= 20' COUNT 10

示例 5 --- 使用 EPSILON 控制相似度范围

bash 复制代码

VSIM my_vectors ELE queryElem EPSILON 0.2 COUNT 50
# 仅返回相似度 ≥ 0.8（即距离 ≤ 0.2）且最多 50 个的匹配项。

五、向量嵌入（Embedding）相关

命令	作用	语法	参数说明	示例
VEMB	从向量集合（vector set）中检索给定元素的向量（embedding）	`VEMB key element [RAW]`	`key`: 向量集合的键名（即 vector set 名称）。 `element`：目标元素名称，其向量将被检索。 `RAW`: 如果指定，返回原始内部表示（量化信息 + 载体数据），而不是简单的反归一化向量。	`VEMB my_vectors item42`

示例 1 --- 获取向量（embedding）

bash 复制代码

# 添加元素
VADD my_vectors VALUES 4 0.15 0.26 0.47 0.88 item42
# 查询元素的向量
VEMB my_vectors item42
## 输出
1) "0.15244093537330627"
2) "0.2633070647716522"
3) "0.47118112444877625"
4) "0.8799999952316284"

示例 2 --- 使用 RAW 选项

bash 复制代码

VEMB my_vectors item42 RAW
## 输出
1) int8              # quantization type，字符串：如 fp32、bin、q8
2) "\x16&D\x7f"      # raw data blob ，二进制向量原始数据
3) "1.041825294494629"  # L2 norm，归一化前向量的 L2 范数
4) "0.844671368598938"  # quantization range (仅 q8 时)，量化范围，用于恢复真实值