摘要
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。值越大索引更稠密，查询质量更高，但内存和写入成本上升。 |
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
| 字段名 |
当前值 |
类型 |
含义说明 |
工程解读 / 使用价值 |
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
bash
复制代码
VRANGE mykey - + 10
# 输出：从最小到最大按每次 10 个元素迭代遍历（客户端可用结果接续下一段）。
# 比如输出最后一个元素是 "Redis"，则下一次迭代从 "Redis" 后面开始。
VRANGE mykey (Redis + 10
bash
复制代码
VRANGE mykey - + -1
# 输出：返回整个集合所有元素。注意：若集合很大可能阻塞 Redis。
- 用于给向量元素绑定结构化元数据（如标签、业务字段）
| 命令 |
作用 |
语法 |
参数说明 |
示例 |
| 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" 必须在集合中存在。
bash
复制代码
VSIM my_vectors VALUES 3 0.12 0.34 0.56 WITHSCORES COUNT 5
# 使用向量 [0.12, 0.34, 0.56] 作为查询参考，返回 最相似 的前 5 个结果及分数。
bash
复制代码
VSIM my_vectors ELE targetElement TRUTH WITHSCORES
# 绕过 HNSW 索引，执行全量扫描以获取精确的相似度结果。
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 |
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"
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 时)，量化范围，用于恢复真实值