*Redis VSIM 命令
VSIM 返回与给定向量或元素相似的结果，用于在向量集合（Vector Set）中执行近似或精确的相似度搜索。
*语法
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 | String | 是 | 向量集合的键名 |
| ELE / FP32 / VALUES num | Keyword | 是 | 查询方式：ELE 引用现有元素，FP32 传入二进制浮点，VALUES 传入字符串化的浮点列表 |
| vector / element | String / Bytes | 是 | 查询向量数据或元素名称 |
| WITHSCORES | Flag | 否 | 返回相似度分数（1 表示完全相同，0 表示相反） |
| WITHATTRIBS | Flag | 否 | 返回元素的 JSON 属性（Redis 8.2.0+） |
| COUNT num | Integer | 否 | 限制返回结果数量 |
| EPSILON delta | Float | 否 | 只返回相似度 >= (1 - delta) 的结果 |
| EF search-exploration-factor | Integer | 否 | 搜索探索因子，越大召回率越高但速度越慢 |
| FILTER expression | String | 否 | 使用属性过滤表达式筛选结果 |
| FILTER-EF max-filtering-effort | Integer | 否 | 过滤尝试的最大次数 |
| TRUTH | Flag | 否 | 强制精确线性扫描（O(N)），用于基准测试 |
| NOTHREAD | Flag | 否 | 在主线程执行搜索，可能阻塞服务器 |
*返回值
- Array：匹配的元素列表
- Array with scores：带 WITHSCORES 时，每个元素后紧跟相似度分数
- Array with attribs：带 WITHATTRIBS 时，每个元素后紧跟分数和 JSON 属性
- Empty Array：键不存在时返回空数组
- Error：元素不存在时返回错误
*时间复杂度
O(log(N))，N 为向量集合中的元素数量。TRUTH 模式下为 O(N)。
*示例
*基本相似度查询
> VSIM word_embeddings ELE apple
1) "apple"
2) "apples"
3) "pear"
4) "fruit"
5) "berry"
6) "pears"
7) "strawberry"
8) "peach"
9) "potato"
10) "grape"
*带分数和属性（Redis 8.2.0+）
> VSETATTR word_embeddings apple "{\"len\": 5}"
(integer) 1
> VSIM word_embeddings ELE apple WITHSCORES WITHATTRIBS COUNT 3
1) "apple"
2) "0.9998867657923256"
3) "{\"len\": 5}"
4) "apples"
5) "0.859852746129036"
6) (nil)
*使用 VALUES 传入向量
> VSIM myset VALUES 3 0.1 0.2 0.3 COUNT 5
1) "item_a"
2) "item_b"
3) "item_c"
4) "item_d"
5) "item_e"
*带 FILTER 过滤
> VSIM word_embeddings ELE apple WITHSCORES COUNT 5 FILTER "type == 'fruit'"
1) "apple"
2) "0.9998867657923256"
3) "pear"
4) "0.8226882070302963"
*常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
| ERR wrong number of arguments | 参数数量不足 | 检查 key、查询方式和向量/元素参数 |
| ERR Invalid vector format | 向量格式错误 | 确保 FP32 或 VALUES 的格式正确 |
| ERR Unknown element | ELE 引用的元素不存在 | 确认元素已存在于向量集合中 |
| WRONGTYPE | key 不是向量集合 | 检查 key 的数据类型 |
*最佳实践
- 默认使用近似搜索（HNSW 图），平衡速度和召回率
- 需要高召回率时增大 EF 值（通常 50-1000），典型值 200
- 使用 EPSILON 限制最相似结果，避免返回相关性低的结果
- 大结果集使用 COUNT 限制返回数量，减少网络传输
- 基准测试或计算召回率时使用 TRUTH 选项进行精确扫描
- 属性过滤与向量搜索结合，实现语义 + 结构化筛选
*FAQ
Q1: VSIM 的相似度分数范围是多少？ A: 分数范围是 0 到 1，其中 1 表示完全相同，0 表示完全相反的向量。
Q2: EF 参数应该如何设置？ A: EF 是探索因子，值越大搜索越彻底、召回率越高但速度越慢。通常设置在 50-1000 之间，根据数据量和召回率要求调整。
Q3: TRUTH 和默认搜索有什么区别？ A: 默认搜索使用 HNSW 近似图搜索，速度快；TRUTH 强制线性扫描所有元素，速度为 O(N)，但结果 100% 精确，主要用于基准测试和召回率计算。
Q4: FILTER 表达式支持哪些操作？
A: 支持属性字段的比较运算，如 ==、!=、>、<、>=、<=，以及逻辑运算符 &&、||。具体语法参考 Redis 向量集合文档。
Q5: WITHATTRIBS 需要 Redis 什么版本？ A: WITHATTRIBS 选项从 Redis 8.2.0 开始支持。