05.6.9.1 RediSearch 向量索引与命令
所属:全栈开发面试题库 / 05 数据库与存储 / 05.6 向量数据库与语义检索 / 05.6.9 RedisStack 向量检索
覆盖范围
- FT.CREATE 向量字段定义:TYPE、DIM、DISTANCE_METRIC、算法与属性计数
- FLAT 与 HNSW 索引参数:M、EF_CONSTRUCTION、EF_RUNTIME、INITIAL_CAP、BLOCK_SIZE、EPSILON
- 向量在 Hash 中的二进制 blob 存储与 JSON 数组存储差异
- FT.SEARCH 的 KNN 语法、PARAMS 传参、AS score、DIALECT 版本要求
- 标量过滤与 KNN 组合、FT.AGGREGATE 分工、索引别名、删除重建、FT.INFO
- 内存占用、排序限制、端序编码、常见语法错误
命令主线
FT.CREATE 索引 ON HASH PREFIX 1 前缀 SCHEMA 字段 VECTOR 算法 count TYPE DIM DISTANCE_METRIC 属性
↓ 写入:HSET 文档 向量字段 <二进制 blob> 标量字段 <值>
FT.SEARCH 索引 "(*)=>[KNN k @向量字段 $blob AS 得分]" PARAMS 2 blob <字节> DIALECT 2
↓ 返回:文档 + 距离得分;过滤子句与 KNN 组合在查询表达式内
高频题速览
| 编号 | 题目 | 难度 | 频率 |
|---|---|---|---|
| 05.6.9.1-002 | FT.CREATE 语法整体拆解 | 基础 | ★★★★★ |
| 05.6.9.1-003 | VECTOR 字段的算法与 count 计数 | 进阶 | ★★★★★ |
| 05.6.9.1-006 | DISTANCE_METRIC 三种度量 | 进阶 | ★★★★★ |
| 05.6.9.1-008 | HNSW 建图与查询参数 | 进阶 | ★★★★★ |
| 05.6.9.1-015 | FT.SEARCH KNN 基本语法 | 进阶 | ★★★★★ |
| 05.6.9.1-018 | DIALECT 版本与向量 KNN 要求 | 基础 | ★★★★★ |
| 05.6.9.1-024 | 索引别名命令 | 进阶 | ★★★★☆ |
| 05.6.9.1-029 | 向量索引内存占用构成 | 高级 | ★★★★☆ |
| 05.6.9.1-038 | 二进制编码端序要求 | 高级 | ★★★★☆ |
| 05.6.9.1-048 | 完整建索引到检索模板 | 高级 | ★★★★★ |
05.6.9.1-001 RediSearch 在 Redis Stack 中承担什么检索角色?
频率 ★★★★☆ | 难度 基础
一句话结论
RediSearch(Redis Stack 的搜索与查询模块)在 Redis 数据结构之上提供倒排、标量过滤与向量近邻检索能力,向量字段配合 HNSW/FLAT 索引完成语义 KNN 召回。
概念解释
- 模块定位:在 Hash/JSON 文档之上建二级索引,检索命令属于模块命令而非原生 Redis 命令。
- 向量能力:为嵌入向量建专用索引,查询表达式中以 KNN 子句召回近邻。
- 共存关系:Redis 原生数据结构与持久化、集群机制见 05.5.1,本题只讲检索模块增量。
原理流程
Hash/JSON 文档写入 Redis → RediSearch 按索引 schema 提取字段建索引
FT.SEARCH → 标量过滤 + 向量 KNN → 返回文档与得分
代码 / 命令
# 前置:模块已加载,FT._LIST / FT.INFO 可执行
常见误区
- 误区:向量检索是 Redis 原生命令。正解:它由 RediSearch 模块提供,未加载模块时 FT. 命令不可用。
- 误区:有向量字段就能被检索。正解:必须先 FT.CREATE 建立对应向量索引。
追问
- 问:怎么确认模块可用?答:执行 FT._LIST 或查看模块列表,命令报错说明模块未加载。
- 问:RediSearch 与向量专用库怎么选?答:容量边界与迁移路径见 05.6.9.2 章节。
05.6.9.1-002 FT.CREATE 命令的整体结构怎么拆解?
频率 ★★★★★ | 难度 基础
一句话结论
FT.CREATE 由索引名、数据类型(ON HASH/JSON)、前缀绑定、SCHEMA 字段定义四部分组成;向量字段在 SCHEMA 内以 VECTOR 关键字声明算法、属性计数与类型参数。
概念解释
- 索引名:后续 FT.SEARCH、FT.INFO、别名命令引用的标识。
- 数据类型与前缀:ON HASH/JSON 指定文档结构,PREFIX 限定纳入索引的 key 前缀。
- SCHEMA:逐字段声明类型(TAG、NUMERIC、TEXT、VECTOR 等)。
原理流程
FT.CREATE <索引>
ON HASH | JSON
PREFIX 1 <前缀>
SCHEMA
<标量字段> <类型> ...
<向量字段> VECTOR <算法> <count> <TYPE/DIM/DISTANCE_METRIC> ...
代码 / 命令
FT.CREATE idx:demo ON HASH PREFIX 1 doc: SCHEMA
title TEXT
category TAG
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:PREFIX 可以省略不绑前缀。正解:索引按前缀匹配文档,前缀与写入 key 不一致则文档不被索引。
- 误区:SCHEMA 字段类型可以事后随意加。正解:索引结构变更通常需要 DROPINDEX 后重建。
追问
- 问:一个索引能绑多个前缀吗?答:PREFIX 后的数量参数决定前缀个数,具体写法以官方 FT.CREATE 文档为准。
- 问:JSON 文档用哪个子句?答:ON JSON,向量在 JSON 中以数组形式存放,见 013 题。
05.6.9.1-003 VECTOR 字段里的 algorithm 与 count 分别是什么?
频率 ★★★★★ | 难度 进阶
一句话结论
algorithm 指定向量索引算法(FLAT、HNSW、SVS-VAMANA 等,可用集合随版本变化);count 是后续属性键值对的计数,按属性 token 数量计算,不是属性对数,写错是高频语法错误。
概念解释
- 算法选择:FLAT 暴力扫描适合小数据集,HNSW 图索引适合大数据集,SVS-VAMANA 为另一类图算法(版本支持待确认)。
- count 规则:官方示例中 3 个属性对(TYPE/DIM/DISTANCE_METRIC)写 count 为 6,即每个属性对占 2 个 token。
- 校验:count 与实际属性 token 数不符时建索引报错。
原理流程
VECTOR <field> <algorithm> <count>
TYPE <类型> DIM <维度> DISTANCE_METRIC <度量>
count = 2 × 属性对数量
代码 / 命令
# 3 个属性对 → count = 6
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:count 等于属性对个数。正解:count 按 token 计数,一对属性占 2,写成 3 会导致解析错位报错。
- 误区:算法名可以自由拼写。正解:必须是版本支持的算法枚举,未识别算法建索引失败。
追问
- 问:count 写错报什么现象?答:FT.CREATE 返回语法/参数错误,索引未创建,需对照示例修正计数。
- 问:SVS-VAMANA 是否可用?答:以当前 RediSearch 版本向量索引文档为准,不支持的版本不要写入该算法名。
05.6.9.1-004 TYPE 支持哪些向量元素类型?
频率 ★★★★☆ | 难度 进阶
一句话结论
TYPE 声明向量元素编码,常见取值 FLOAT32、FLOAT64、FLOAT16、BFLOAT16;不同精度影响存储体积与计算精度,查询侧编码必须与字段 TYPE 一致。
概念解释
- FLOAT32:单精度浮点,最常用,4 字节每维。
- FLOAT64:双精度,8 字节每维,精度高但存储翻倍。
- FLOAT16/BFLOAT16:半精度变体,存储省,精度与版本支持以官方文档为准。
- 一致性:写入 blob 的字节宽度必须匹配 TYPE。
原理流程
选嵌入精度需求 → 选 TYPE → 客户端按对应宽度序列化向量
→ 入库校验 → 检索侧按同一 TYPE 编码查询向量
代码 / 命令
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:FLOAT32 与 FLOAT64 可以混存同一字段。正解:字段 TYPE 固定,编码宽度不符会导致向量解析错误。
- 误区:半精度类型所有版本都支持。正解:支持范围随版本变化,建索引前核对官方字段类型文档。
追问
- 问:小内存场景选什么?答:优先 FLOAT32 评估,半精度需验证召回精度,不盲目降精度。
- 问:TYPE 能事后改吗?答:属于索引结构参数,需 DROPINDEX 重建并重新入库向量。
05.6.9.1-005 DIM 维度怎么约束写入与查询?
频率 ★★★★☆ | 难度 基础
一句话结论
DIM 声明向量维度,写入文档向量与查询向量的长度都必须等于 DIM;维度不符时写入或检索解析失败,换 Embedding 模型通常意味着维度变化,需要重建索引。
概念解释
- 写入校验:blob 解码后的元素个数必须等于 DIM。
- 查询校验:查询向量参数长度同样受 DIM 约束。
- 模型一致:维度由嵌入模型决定,入库与查询必须使用同一模型同一版本。
原理流程
建索引 DIM=N → 写入向量长度=N → 入库校验通过
查询向量长度=N → KNN 计算
模型变更 → 新维度 → 新建索引重建
代码 / 命令
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:DIM 可以按首条向量自动确定。正解:RediSearch 向量字段需显式声明 DIM,与某些数据库的隐式维度行为不同。
- 误区:不同模型向量可混写。正解:维度与语义空间都不同,混写导致距离结果失真。
追问
- 问:维度不符报什么现象?答:写入或查询返回向量维度错误类报错,文档/请求被拒绝。
- 问:降维模型怎么迁移?答:新维度建新索引,全量重算向量后切换别名。
05.6.9.1-006 DISTANCE_METRIC 有哪几种,方向怎么理解?
频率 ★★★★★ | 难度 进阶
一句话结论
支持 L2(欧氏距离)、IP(内积)、COSINE(余弦)三种度量;L2 越小越相似,COSINE/IP 方向按得分排序规则不同,选择要与向量归一化方式匹配。
概念解释
- L2:欧氏距离,几何距离越小越近,对向量幅度敏感。
- IP:内积,幅度与方向共同影响得分,未归一化向量幅度直接参与比较。
- COSINE:余弦相似度,比较方向,归一化后与单位向量内积等价。
- 归一化配合:COSINE 通常配合归一化向量;IP 按业务是否保留幅度选择。
原理流程
向量是否归一化 / 是否保留幅度 → 选度量
L2:距离小者近;COSINE:方向接近者近;IP:内积大者靠前(按索引排序约定)
代码 / 命令
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:三种度量的得分方向一致。正解:L2 是距离(越小越好),IP/COSINE 为相似度类得分,排序方向需按命令返回说明确认。
- 误区:未归一化向量也适合 COSINE。正解:余弦对幅度不敏感但计算基于方向,写入前归一化更稳妥。
追问
- 问:推荐偏好类向量用哪种?答:需要保留幅度强度时评估 IP;纯方向匹配用 COSINE。
- 问:度量能事后改吗?答:索引固化度量,修改需重建索引并重灌向量。
05.6.9.1-007 FLAT 索引适合什么场景,有哪些参数?
频率 ★★★★☆ | 难度 进阶
一句话结论
FLAT 对向量做暴力扫描,结构简单、无建图成本,适合百万级以下或数据量小、更新频繁的数据集;参数包括 TYPE、DIM、DISTANCE_METRIC、INITIAL_CAP 与 BLOCK_SIZE。
概念解释
- 检索方式:查询时遍历全部向量计算距离,无 ANN 近似误差。
- 规模边界:官方指南建议 FLAT 用于约一百万向量以内,超出后评估 HNSW;具体阈值以版本文档为准。
- 参数:INITIAL_CAP 预留初始容量,BLOCK_SIZE 控制扫描块大小。
原理流程
小数据集 / 高频更新 / 需精确扫描 → FLAT
查询:遍历块内向量 → 计算度量 → 取 TopK
代码 / 命令
embedding VECTOR FLAT 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
INITIAL_CAP 10000 BLOCK_SIZE 1024
常见误区
- 误区:FLAT 就是不建索引。正解:FLAT 是一种暴力检索索引结构,仍受索引管理与容量参数约束。
- 误区:大数据量用 FLAT 也能靠堆硬件扛住。正解:遍历成本随向量数线性增长,规模上来后延迟不可控。
追问
- 问:FLAT 召回是精确的吗?答:暴力扫描在数据完整时给出全量距离排序,不做近似截断。
- 问:BLOCK_SIZE 影响什么?答:影响扫描分块与内存组织,取值对遍历效率的影响需压测确认。
05.6.9.1-008 HNSW 索引有哪些建图与查询参数?
频率 ★★★★★ | 难度 进阶
一句话结论
HNSW 参数包括 M(每节点连接数)、EF_CONSTRUCTION(建图候选宽度)、EF_RUNTIME(查询期候选宽度),另有 INITIAL_CAP 预留容量;建图参数影响图质量与写入成本,EF_RUNTIME 直接影响查询召回与延迟。
概念解释
- M:图节点出边上限,越大图越密、内存越高。
- EF_CONSTRUCTION:构建阶段候选列表宽度,影响建图精度与写入速度。
- EF_RUNTIME:查询期遍历候选宽度,越大召回越充分、查询越慢。
- 默认值:M 默认 16、EF_CONSTRUCTION 默认 200、EF_RUNTIME 默认 10(以官方文档为准)。
原理流程
写入向量 → 按 EF_CONSTRUCTION 建边 → 按 M 保留连接
查询 → 按 EF_RUNTIME 遍历候选 → 返回 TopK
代码 / 命令
embedding VECTOR HNSW 12 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
M 16 EF_CONSTRUCTION 200 EF_RUNTIME 10
常见误区
- 误区:EF_RUNTIME 是建图参数。正解:它是查询期候选参数,可在查询或索引配置中调整,不等同 EF_CONSTRUCTION。
- 误区:M 越大召回线性提升。正解:边际收益递减而内存与建图成本上升,需压测权衡。
追问
- 问:查询召回不足先调哪个?答:先调大 EF_RUNTIME 观察 recall 与延迟,再评估建图参数。
- 问:参数能在线改吗?答:建图参数属于索引结构,修改需重建;EF_RUNTIME 调整方式以当前版本命令文档为准。
05.6.9.1-009 EPSILON 参数在什么场景使用?
频率 ★★★☆☆ | 难度 高级
一句话结论
EPSILON 用于向量范围(radius)查询的距离容差,控制近邻半径边界;它属于算法/查询相关参数,适用算法与默认值以官方文档为准,KNN TopK 查询不依赖该参数。
概念解释
- 作用:半径查询中允许的距离误差边界。
- 适用对象:范围检索而非 TopK 截断。
- 待确认:当前版本 EPSILON 支持的算法类型与默认取值,需对照向量字段选项文档。
原理流程
范围查询:以查询向量为中心 → 半径 + EPSILON 容差 → 返回边界内向量
KNN 查询:按候选数取 TopK,不使用半径容差
代码 / 命令
# 待确认:EPSILON 语法位置、默认值与支持算法,以 RediSearch 官方向量文档为准
常见误区
- 误区:EPSILON 调大能提高 KNN 召回。正解:它服务半径范围查询,与 TopK 候选宽度是不同参数。
- 误区:所有算法都支持 EPSILON。正解:支持范围随算法与版本变化,未确认前不要写入配置。
追问
- 问:范围查询怎么写?答:见 036 题,向量距离过滤子句结合半径参数。
- 问:参数拿不准怎么验证?答:在测试实例建带 EPSILON 的索引,观察是否接受并核对官方默认值。
05.6.9.1-010 INITIAL_CAP 与 BLOCK_SIZE 各起什么作用?
频率 ★★★☆☆ | 难度 高级
一句话结论
INITIAL_CAP 为索引预留初始向量容量,避免频繁扩容;BLOCK_SIZE 组织向量存储块,影响内存布局与扫描/遍历效率;两者都是容量与组织参数,不改变检索算法本身。
概念解释
- INITIAL_CAP:预估向量数量级,建索引时预留空间。
- BLOCK_SIZE:存储块大小,FLAT 扫描与 HNSW 内存组织均可能涉及。
- 调整依据:按预估规模与压测结果设置,容量明显失配时再评估重建。
原理流程
预估向量规模 → INITIAL_CAP 预留容量
向量按 BLOCK_SIZE 分块存储 → 检索按块读取/遍历
代码 / 命令
INITIAL_CAP 100000 BLOCK_SIZE 1024
常见误区
- 误区:INITIAL_CAP 是硬上限。正解:它是初始预留容量,超出后索引可扩容,只是预留不足会增加扩容开销。
- 误区:BLOCK_SIZE 越大越快。正解:块大小影响内存局部性与扫描粒度,需结合数据量压测。
追问
- 问:容量预估偏差大怎么办?答:观察 FT.INFO 中的向量数与容量指标,必要时规划重建调整预留。
- 问:这两个参数属于哪类配置?答:索引级容量参数,与度量、算法选择分开评估。
05.6.9.1-011 向量属性 count 计数错误为什么是高频坑?
频率 ★★★☆☆ | 难度 高级
一句话结论
count 必须等于后续属性 token 总数(属性对数 × 2),写成属性对数会导致解析错位、后续参数被误读为字段,FT.CREATE 直接报错;对照官方示例逐 token 数是最稳妥的排错方式。
概念解释
- 计数对象:TYPE/FLOAT32、DIM/768 这类键值各占一个 token,一对两个 token。
- 错位后果:count 偏小则剩余参数被当成 SCHEMA 字段定义,类型解析失败。
- 核对方法:列出全部属性键与值,token 总数即为 count。
原理流程
属性对:TYPE FLOAT32 / DIM 768 / DISTANCE_METRIC COSINE
token 数 = 6 → count 写 6
多加 M 16 等参数 → 重新计数
代码 / 命令
# 错误示例(count 写成属性对数 3):
# embedding VECTOR HNSW 3 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
# 正确:
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:count 只是提示性参数。正解:解析器按 count 读取固定数量 token,写错必然报错或错位。
- 误区:加了额外参数不用改 count。正解:每加一对属性都要把 count 加 2。
追问
- 问:报错信息怎么定位?答:FT.CREATE 返回参数数量/类型错误时,先核对 count 与属性清单。
- 问:HNSW 加 M/EF 参数后 count 是多少?答:3 个基础对 + 3 个参数对 = 12 个 token,count 写 12。
05.6.9.1-012 Hash 文档中的向量以什么形式存储?
频率 ★★★★★ | 难度 进阶
一句话结论
Hash 结构里向量字段存放的是按 TYPE 序列化后的二进制 blob,不是可读的浮点数组;客户端写入时要把浮点数序列化为对应字节流,检索参数同样以字节 blob 传入。
概念解释
- 存储形态:二进制字节串,按元素类型宽度编码。
- 写入命令:HSET 文档 key 向量字段 blob。
- 读取:FT.SEARCH 命中后向量字段可作为 blob 返回,不做浮点展开。
原理流程
浮点数组 → 按 TYPE(如 FLOAT32)序列化为字节流
→ HSET 写入 Hash 字段
→ 索引解析 blob 解码出向量
代码 / 命令
# 伪代码:float32 little-endian 序列化为字节数组后作为 HSET 值
HSET doc:1001 title "示例" embedding <二进制 blob>
常见误区
- 误区:Hash 里直接存 JSON 数组字符串。正解:Hash 向量字段要求二进制编码,数组形式是 JSON 文档的存放方式。
- 误区:blob 内容可读可直接调试。正解:需按字节宽度与端序解码后才能核对向量数值。
追问
- 问:怎么核对入库向量是否正确?答:解码 blob 比对元素个数、模长与数值范围。
- 问:blob 大小怎么算?答:DIM × 每维字节数,FLOAT32 即 DIM × 4 字节。
05.6.9.1-013 JSON 文档里的向量以什么形式存放?
频率 ★★★☆☆ | 难度 高级
一句话结论
ON JSON 索引下向量字段以浮点数组形式存放在 JSON 文档中,由模块在索引时完成序列化;客户端写入数组即可,不需要自行处理二进制编码。
概念解释
- 存储形态:JSON 内的数值数组,可读性好。
- 索引转换:模块把数组编码为内部向量表示。
- 与 Hash 对比:Hash 由客户端序列化 blob,JSON 由模块处理数组。
原理流程
JSON 文档 → 向量字段为 [0.1, -0.2, ...] 数组
→ 模块按 TYPE/DIM 校验并编码 → 建向量索引
代码 / 命令
# 待确认:当前版本 JSON 向量数组的写入命令与字段路径语法,以官方 JSON 索引文档为准
常见误区
- 误区:JSON 向量也要传二进制 blob。正解:JSON 路径下直接写数组,编码由模块完成。
- 误区:Hash 与 JSON 可以在同一索引混用。正解:索引 ON 子句选定一种文档结构,前缀与结构要一致。
追问
- 问:JSON 数组维度不符怎么报错?答:索引校验阶段拒绝或标记异常文档,按 FT.INFO 与写入日志排查。
- 问:选 Hash 还是 JSON?答:复杂嵌套元数据用 JSON,简单键值文档用 Hash,序列化成本与客户端能力一起评估。
05.6.9.1-014 怎么向 Hash 写入向量二进制?
频率 ★★★★★ | 难度 进阶
一句话结论
把浮点数组按字段 TYPE 序列化为字节数组(FLOAT32 每维 4 字节,注意端序),通过 HSET 写入文档的向量字段;写入前校验维度、模长与字节长度。
概念解释
- 序列化:元素顺序与数组一致,按类型宽度排列。
- 端序:常见小端(little-endian)编码,跨语言客户端必须保持一致。
- 前置校验:维度等于 DIM、无 NaN/Inf、模长非零。
原理流程
校验数组长度与数值 → 按 TYPE 序列化字节流
→ HSET 写入 → 索引解析解码
代码 / 命令
# 客户端伪代码:
# bytes = float_array.pack('f<') # FLOAT32 小端
# redis.hset(key, 'embedding', bytes)
常见误区
- 误区:字节序不影响结果。正解:端序错误会让解码出的向量完全错乱,距离结果不可用。
- 误区:先写字符串数组再转 blob。正解:必须直接序列化数值,中间转字符串会引入精度与编码问题。
追问
- 问:写入失败怎么排查?答:先核对 blob 长度是否等于 DIM×字节宽度,再检查端序与类型。
- 问:空向量怎么处理?答:入库前拦截零模长与非法数值,避免污染索引。
05.6.9.1-015 FT.SEARCH 的 KNN 基本语法怎么写?
频率 ★★★★★ | 难度 进阶
一句话结论
KNN 子句写在查询表达式中,形如 (*)=>[KNN k @字段 $参数 AS 得分名],查询向量通过 PARAMS 以字节 blob 传入;* 表示初始匹配全部文档,再由 KNN 条件过滤出近邻。
概念解释
- 子句结构:
=>[KNN <k> <@向量字段> <$参数> AS <得分>]。 - 参数绑定:PARAMS 声明参数名与 blob,避免向量直接写进表达式。
- 得分别名:AS 后的名称用于在结果中引用距离得分。
原理流程
FT.SEARCH <索引> "(*)=>[KNN 10 @embedding $blob AS score]"
PARAMS 2 blob <查询向量 blob> DIALECT 2
→ 取 Top10 近邻 → 返回文档与 score
代码 / 命令
FT.SEARCH idx:demo "(*)=>[KNN 10 @embedding $blob AS dist]"
PARAMS 2 blob <查询向量字节>
DIALECT 2
常见误区
- 误区:KNN 是独立于 FT.SEARCH 的命令。正解:它是 FT.SEARCH 查询表达式内的 KNN 子句。
- 误区:查询向量直接写在表达式里。正解:二进制向量经 PARAMS 绑定参数传入。
追问
- 问:k 与索引 EF_RUNTIME 什么关系?答:k 是返回条数,EF_RUNTIME 是遍历候选宽度,两者共同影响召回。
- 问:结果按什么排序?答:按 KNN 距离得分排序,得分方向依度量类型确认,见 031 题。
05.6.9.1-016 PARAMS 传参怎么组织?
频率 ★★★★☆ | 难度 进阶
一句话结论
PARAMS 后接参数个数与「参数名 参数值」对,向量 blob 作为参数值传入;参数名在表达式中以 $ 引用,blob 字节编码必须与字段 TYPE/DIM 一致。
概念解释
- 计数:PARAMS 2 表示 1 个参数名值对(2 个 token),与 FT.CREATE 的 count 同理按 token 计数。
- 值类型:向量参数为二进制字节数组,不是字符串数组。
- 一致性:查询向量编码宽度、端序与入库 blob 规则相同。
原理流程
序列化查询向量 → PARAMS 2 blob <bytes>
表达式内 $blob 引用 → 索引解码计算距离
代码 / 命令
PARAMS 2 blob <查询向量字节数组>
常见误区
- 误区:PARAMS 后数字是参数个数。正解:按 token 计数,1 个参数对占 2,写 1 会导致解析错位。
- 误区:查询向量可以传浮点列表文本。正解:必须传与入库一致的二进制编码。
追问
- 问:多个参数怎么写?答:参数个数按 token 总数写,名称与值成对列出,具体语法以官方查询文档为准。
- 问:参数名能复用吗?答:表达式内引用名与 PARAMS 声明名必须一致,大小写敏感。
05.6.9.1-017 AS 得分名与结果排序怎么对应?
频率 ★★★☆☆ | 难度 基础
一句话结论
AS 为 KNN 距离得分定义别名,命中结果按该得分排序;别名出现在返回结果的得分位置,具体升序还是降序由度量类型决定,不能默认所有得分都是越大越相关。
概念解释
- 别名作用:在结果字段中标识哪一个是向量距离分。
- 排序方向:L2 距离越小越近,COSINE/IP 得分方向按索引实现约定。
- 与标量排序区别:KNN 排序由向量距离驱动,SORTBY 作用于标量字段。
原理流程
KNN 子句计算距离 → 写入 AS 别名得分
→ 结果按该度量排序 → 返回文档列表与得分
代码 / 命令
(*)=>[KNN 10 @embedding $blob AS dist]
常见误区
- 误区:AS 后面是展示文案可随意改名。正解:它是结果中引用得分的标识名,排序依据仍是度量本身。
- 误区:得分统一越大越好。正解:L2 为距离值,方向与相似度得分相反,需按度量确认。
追问
- 问:结果里多个得分怎么区分?答:KNN 得分用 AS 别名标识,标量打分/聚合结果按返回结构区分。
- 问:想按业务字段二次排序怎么办?答:用 SORTBY 对标量字段排序,见 05.6.9.2-007。
05.6.9.1-018 为什么向量 KNN 查询必须指定 DIALECT 2 或更高?
频率 ★★★★★ | 难度 基础
一句话结论
RediSearch 查询方言版本决定表达式语法支持范围,向量 KNN 子句是在较新方言中引入的;低版本 DIALECT 无法解析 KNN 语法,查询必须显式指定 DIALECT 2 或更高,具体最低版本以官方文档为准。
概念解释
- 方言作用:控制查询表达式解析规则与功能可用性。
- KNN 依赖:KNN 箭头子句、参数绑定等语法需要新方言。
- 兼容问题:客户端默认方言可能偏低,不显式指定会报语法错误。
原理流程
FT.SEARCH ... DIALECT 2
→ 解析器按新方言识别 KNN 子句
→ 低方言:KNN 语法不被识别,查询失败
代码 / 命令
FT.SEARCH idx:demo "(*)=>[KNN 10 @embedding $blob AS dist]"
PARAMS 2 blob <bytes> DIALECT 2
常见误区
- 误区:模块版本新就不用写 DIALECT。正解:查询侧仍需显式声明方言版本,默认方言不自动升级。
- 误区:DIALECT 数字越大越兼容旧语法。正解:应使用当前客户端与模块共同支持的方言版本,以官方兼容说明为准。
追问
- 问:没写 DIALECT 报什么错?答:表达式解析错误,KNN 子句不被识别。
- 问:DIALECT 版本在哪确认?答:对照 RediSearch 查询语法文档中各方言支持的功能清单。
05.6.9.1-019 FT.SEARCH 返回哪些字段和得分?
频率 ★★★☆☆ | 难度 基础
一句话结论
返回命中文档的 key、请求返回的字段值与 KNN 距离得分;可用 RETURN 限定返回字段,未声明时按默认行为返回,向量 blob 与大字段按需取用避免传输膨胀。
概念解释
- 返回结构:文档 key 列表 + 各文档字段 + 得分。
- RETURN 子句:指定需要返回的标量字段,减少回表传输。
- 得分位置:KNN AS 别名对应的距离值。
原理流程
KNN 召回 TopK → RETURN 指定字段回表
→ 组装文档 key、字段值、距离得分返回
代码 / 命令
FT.SEARCH idx:demo "(*)=>[KNN 10 @embedding $blob AS dist]"
PARAMS 2 blob <bytes> DIALECT 2
RETURN 2 title category
常见误区
- 误区:返回结果自动带原文全文。正解:按 RETURN 或默认规则返回字段,大字段需显式取用。
- 误区:向量 blob 必须返回给客户端。正解:检索到 key 后按需要回表取字段,避免每条都传大 blob。
追问
- 问:返回总数代表什么?答:FT.SEARCH 头部返回的匹配计数受 KNN 截断与方言行为影响,见 041 题。
- 问:字段不存在会怎样?答:该字段返回空值,不影响其他字段命中。
05.6.9.1-020 TAG 过滤条件怎么与 KNN 组合?
频率 ★★★★☆ | 难度 进阶
一句话结论
在查询表达式中把 TAG 条件与 KNN 子句并列组合,先按 TAG 圈定文档子集,再在子集内做 KNN 近邻检索;TAG 字段建索引时声明为 TAG 类型。
概念解释
- 条件写法:TAG 等值匹配表达式与
=>[KNN ...]子句用查询语法组合。 - 过滤顺序:标量条件先缩小候选,向量检索在合规子集内执行。
- 多值 TAG:字段可存多个标签,匹配其一即命中。
原理流程
(@category:{tech})=>[KNN 10 @embedding $blob AS dist]
→ 先匹配 category=tech → 子集内 KNN 召回
代码 / 命令
FT.SEARCH idx:demo "(@category:{tech})=>[KNN 10 @embedding $blob AS dist]"
PARAMS 2 blob <bytes> DIALECT 2
常见误区
- 误区:TAG 条件写在 KNN 之后才生效。正解:组合表达式按过滤与 KNN 的执行路径处理,条件作用于候选子集。
- 误区:TAG 值不需要建索引。正解:SCHEMA 中必须声明 TAG 类型才能过滤匹配。
追问
- 问:多 TAG 条件怎么组合?答:按查询语法用 AND/OR 连接标签表达式,具体操作符以官方查询文档为准。
- 问:TAG 含特殊字符怎么转义?答:按查询语法转义规则处理,标签内容提前规范化。
05.6.9.1-021 NUMERIC 范围过滤怎么与 KNN 组合?
频率 ★★★☆☆ | 难度 高级
一句话结论
数值字段在 SCHEMA 中声明为 NUMERIC,查询表达式内用范围条件与 KNN 子句组合,先按数值区间圈定子集再做向量近邻;范围选择率会影响 KNN 候选规模。
概念解释
- 数值索引:NUMERIC 字段支持区间过滤。
- 组合方式:范围表达式与 KNN 子句并列写入查询。
- 选择率影响:过窄的数值区间可能把候选压到很小,KNN 返回条数不足。
原理流程
(@price:[100 500])=>[KNN 10 @embedding $blob AS dist]
→ 数值区间过滤 → 子集内 KNN
代码 / 命令
# 待确认:当前版本 NUMERIC 范围语法边界写法,以官方查询文档为准
常见误区
- 误区:NUMERIC 字段可以像 TAG 一样等值列举。正解:NUMERIC 走区间比较,语法与 TAG 不同。
- 误区:范围过滤不影响向量召回。正解:低选择率区间缩小候选子集,近邻数量与质量随之变化。
追问
- 问:数值过滤后结果为空怎么排查?答:先单独执行数值条件看命中集合,再判断是数据缺失还是区间过窄。
- 问:大区间过滤性能如何?答:高选择率条件过滤成本低,低选择率需关注候选遍历规模。
05.6.9.1-022 KNN 与全文检索子句怎么组合?
频率 ★★★☆☆ | 难度 高级
一句话结论
TEXT 全文子句与 KNN 子句可在同一查询表达式内组合,实现词项匹配与语义近邻的混合召回;组合语法与分数合并方式受方言版本约束,复杂混合应在测试实例验证。
概念解释
- 文本路:TEXT 字段按分词匹配词项。
- 向量路:KNN 子句召回语义近邻。
- 组合限制:RediSearch 表达式内的组合能力与 ES/OpenSearch 服务端融合管线不同,跨产品写法不可照搬。
原理流程
查询表达式:TEXT 条件 + KNN 子句
→ 文档同时/分别满足两路 → 按表达式规则排序返回
代码 / 命令
# 待确认:当前版本 TEXT 与 KNN 组合的表达式写法、分数合并规则,以官方查询文档为准
常见误区
- 误区:RediSearch 内置 RRF 融合。正解:是否提供服务端排名融合取决于版本能力,不要假设与 ES rrf retriever 行为一致。
- 误区:全文与向量路分数可直接相加。正解:分数尺度不同,组合规则需按官方实现确认。
追问
- 问:混合召回需要客户端二次合并怎么办?答:分别取两路候选,在应用层按排名或归一化合并。
- 问:怎么验证组合生效?答:分别跑纯 TEXT、纯 KNN 与组合查询,对比命中集合与头部结果。
05.6.9.1-023 FT.AGGREGATE 与向量检索怎么分工?
频率 ★★★☆☆ | 难度 高级
一句话结论
FT.AGGREGATE 在检索结果集合上做分组、统计与聚合分析,向量近邻召回由 FT.SEARCH 的 KNN 子句完成;聚合作用于过滤/召回后的文档集合,不替代向量近邻排序。
概念解释
- 分工边界:KNN 解决「找最近邻」,AGGREGATE 解决「对集合做分组统计」。
- 输入集合:聚合基于查询表达式命中的文档。
- 向量能力:KNN 是否能直接嵌入聚合流程取决于版本支持,待确认。
原理流程
FT.SEARCH KNN 召回 → 取文档集合
FT.AGGREGATE 在集合上分组/计数/统计
代码 / 命令
# 待确认:当前版本 FT.AGGREGATE 对向量 KNN 的支持范围与语法,以官方聚合文档为准
常见误区
- 误区:聚合命令也能直接返回向量近邻。正解:聚合输出分组统计,近邻 TopK 走 FT.SEARCH KNN。
- 误区:聚合可以跨索引全量统计。正解:聚合作用于指定索引命中集合,口径与过滤条件相关。
追问
- 问:想按类别统计近邻结果分布怎么办?答:先 KNN 召回,再对结果集按 TAG 字段聚合分组。
- 问:聚合字段需要什么类型?答:TAG/NUMERIC 等可分组字段,向量字段不参与聚合分组。
05.6.9.1-024 索引别名怎么管理?
频率 ★★★★☆ | 难度 进阶
一句话结论
通过 FT.ALIASADD 把别名指向索引、FT.ALIASDEL 解除别名绑定;别名用于重建索引期间的平滑切换,应用侧始终引用别名,后端索引可更换。
概念解释
- 别名作用:解耦调用方与具体索引名,支持双写重建与切流。
- 命令:ADD 绑定,DEL 解绑;别名与索引的映射可通过索引信息查看。
- 重建流程:新索引建好 → 别名指向新索引 → 旧索引下线。
原理流程
FT.ALIASADD <别名> <新索引>
应用查询走别名 → 后端索引可切换
FT.ALIASDEL <别名> <旧索引>(解绑时机按流程)
代码 / 命令
FT.ALIASADD alias:demo idx:demo-v2
常见误区
- 误区:别名可以在 DROPINDEX 后自动保留指向。正解:索引删除后别名绑定需单独检查与清理。
- 误区:一个别名同时指向两个索引做联合检索。正解:别名与索引映射关系以官方文档为准,不要假设跨索引联合。
追问
- 问:重建切换怎么保证连续?答:新索引数据齐备后切别名,旧索引保留一个观察窗口再下线。
- 问:怎么查别名指向?答:用索引查看命令或 FT.INFO 对照,具体命令名以官方文档为准。
05.6.9.1-025 删除文档对向量索引有什么影响?
频率 ★★★☆☆ | 难度 基础
一句话结论
删除 Hash/JSON 文档后,RediSearch 会移除该文档的索引条目,向量不再参与近邻检索;索引内部的空间回收与图结构维护按模块机制进行,删除后应验证近邻结果不再包含该文档。
概念解释
- 索引一致性:文档 key 删除触发对应索引条目清理。
- 空间回收:向量与图条目释放节奏由模块内部管理,不等于删除命令执行后立即回收内存。
- 校验:删除后用已知查询确认该文档不再出现在 KNN 结果中。
原理流程
DEL 文档 key → 模块清理倒排/标量/向量条目
→ 后续检索跳过该文档 → 内部空间逐步回收
代码 / 命令
# 删除后校验:查询原文档应不再命中;检查 FT.INFO 文档计数
常见误区
- 误区:只删 Hash 不清索引会自动永久悬挂。正解:模块按 key 关联清理条目,需验证清理结果。
- 误区:删除后内存立即下降。正解:内部回收有延迟,内存观察需留出窗口。
追问
- 问:覆盖更新文档会重建向量条目吗?答:更新写入后索引同步更新对应条目,见 044 题。
- 问:索引条目残留怎么排查?答:对照 FT.INFO 计数与实际 key 数量,必要时重建索引。
05.6.9.1-026 FT.DROPINDEX 与索引重建怎么操作?
频率 ★★★☆☆ | 难度 进阶
一句话结论
FT.DROPINDEX 删除索引定义与索引数据(是否同时删除底层文档由命令参数控制,以官方文档为准);结构参数变更、维度更换或条目异常时,重建流程是建新索引、灌入数据、校验后切换别名。
概念解释
- 删除对象:索引结构与索引条目;底层 Hash/JSON 文档是否保留取决于 DROPINDEX 参数。
- 重建场景:改 TYPE/DIM/度量/算法、修复残留条目、存量数据补索引。
- 平滑切换:先建新索引并灌数据,再切别名,避免直接 drop 线上索引。
原理流程
新建目标索引 → 批量写入文档与向量 → 校验召回与计数
→ 别名切到新索引 → 观察窗口后删除旧索引
代码 / 命令
# 待确认:FT.DROPINDEX 是否删除文档的参数名与默认行为,以官方文档为准
常见误区
- 误区:DROPINDEX 一定连文档一起删。正解:需核对参数语义,避免误删业务数据。
- 误区:重建可以在原索引上原地改参数。正解:向量结构参数不可原地变更,必须新建索引。
追问
- 问:重建期间旧索引还能查吗?答:保留旧索引承接线上流量,新索引并行灌入后再切流。
- 问:重建后怎么校验一致?答:对比文档数、抽样向量解码与判断集 recall@k。
05.6.9.1-027 FT.INFO 能看哪些索引统计?
频率 ★★★☆☆ | 难度 基础
一句话结论
FT.INFO 返回索引的字段定义、文档计数、向量配置与索引构建状态等统计信息,用于核对 schema、观察索引进度与排查条目残留。
概念解释
- 结构信息:字段类型、向量算法/维度/度量配置。
- 计数信息:已索引文档数、向量条目数。
- 构建状态:后台索引进度,存量数据灌入时可观察是否完成。
原理流程
FT.INFO <索引>
→ 核对 schema 与向量参数
→ 观察文档/向量计数与构建进度
代码 / 命令
FT.INFO idx:demo
常见误区
- 误区:FT.INFO 能返回向量具体数值。正解:它给统计与配置,不展开文档向量。
- 误区:计数与 key 数量不一致一定是残留。正解:先排除索引后台构建未完成与前缀匹配差异。
追问
- 问:存量数据索引中怎么判断完成?答:对比 FT.INFO 计数与实际 key 数,观察构建进度字段稳定。
- 问:INFO 里参数和建索引时不一致?答:核对命令历史与别名指向,确认查看的是目标索引。
05.6.9.1-028 存量未索引数据怎么补建索引?
频率 ★★★☆☆ | 难度 进阶
一句话结论
索引创建前已存在的文档不会自动纳入新索引,需要按前缀扫描存量 key,批量重新写入或触发索引构建,使存量 Hash/JSON 被索引条目覆盖;完成后用 FT.INFO 计数校验。
概念解释
- 触发机制:索引只覆盖创建后按前缀匹配的文档(存量回填行为以版本实现为准,待确认)。
- 回填流程:扫描前缀 → 读取文档 → 重新写入/重建索引 → 校验计数。
- 节奏控制:批量限速,避免一次性灌入挤占内存与 CPU。
原理流程
建索引 → 扫描存量 key 前缀
→ 批量回写/重建 → FT.INFO 计数对齐 → 校验抽样召回
代码 / 命令
# 待确认:当前版本创建索引时是否自动索引存量文档,回填命令以官方文档为准
常见误区
- 误区:FT.CREATE 后存量文档自动可搜。正解:需确认版本行为,必要时显式回填。
- 误区:回填不影响在线实例。正解:批量读取与写入有内存/CPU 压力,应限速错峰。
追问
- 问:怎么判断哪些文档缺索引?答:对比前缀下 key 总数与 FT.INFO 文档计数,差值即待回填量。
- 问:回填失败怎么处理?答:记录失败 key 批次,幂等重试后复核计数。
05.6.9.1-029 RediSearch 向量索引内存占用由哪些部分构成?
频率 ★★★★☆ | 难度 高级
一句话结论
内存包括向量本体(DIM × 每维字节 × 向量数)、HNSW 图结构连接开销、Hash/JSON 中存储的原始 blob 与标量字段;索引结构与业务数据各占一份,容量估算不能只算向量本体。
概念解释
- 向量本体:编码后的元素字节。
- 图结构:HNSW 节点连接与元数据,随向量数与 M 增长。
- 原始数据:Hash 内 blob 或 JSON 数组本身也占用内存,索引不替代原始文档存储。
原理流程
单条 ≈ 向量字节 + 图条目分摊 + 原始 blob + 标量字段
总量 × 向量数 → 加索引结构元数据 → 内存预算
代码 / 命令
# 粗估:向量字节 = N × D × bytes_per_dim
# 图与原始 blob 开销按样本实例实测回填系数
常见误区
- 误区:向量入库后只算索引内存。正解:原始文档 blob 仍在 Hash/JSON 中,与索引条目并存。
- 误区:FLAT 没有结构开销。正解:FLAT 无图连接,但向量存储与块组织仍有固定开销。
追问
- 问:怎么实测真实占用?答:导入样本集后对比实例内存与 FT.INFO 计数,反推单条占用。
- 问:内存紧张先压哪部分?答:降维、降精度、清理过期文档,评估是否需要专用向量库。
05.6.9.1-030 向量字段能不能声明 SORTABLE?
频率 ★★★☆☆ | 难度 基础
一句话结论
SORTABLE 是标量字段的排序配置,向量字段不参与 SORTBY 标量排序;向量结果的顺序由 KNN 距离得分决定,不能把向量字段当可排序标量使用。
概念解释
- 排序对象:TAG/NUMERIC/TEXT 等标量字段可配置排序。
- 向量排序:KNN 检索输出距离分,排序由距离计算驱动。
- 二次排序:需要业务字段排序时,对该标量字段使用 SORTBY。
原理流程
标量字段 SORTABLE → SORTBY 排序
向量字段 → KNN 距离排序,不进 SORTBY
代码 / 命令
# SCHEMA 中 SORTABLE 只加在标量字段上,向量字段不声明该选项
常见误区
- 误区:给向量字段加 SORTABLE 就能按向量排序。正解:向量排序由 KNN 完成,SORTABLE 不适用。
- 误区:距离得分可以用 SORTBY 再排一次。正解:KNN 结果已按距离排序,标量 SORTBY 会改变排序口径。
追问
- 问:想在近邻结果里按时间排序怎么办?答:时间戳写 NUMERIC 字段,KNN 召回后按业务规则二次排序。
- 问:SORTABLE 有什么内存代价?答:标量字段排序值额外存储,具体以官方字段选项文档为准。
05.6.9.1-031 三种度量的距离分方向怎么区分?
频率 ★★★★★ | 难度 进阶
一句话结论
L2 是距离值,越小表示越近;COSINE 衡量方向相似度;IP 为内积,受向量幅度影响;结果排序方向与得分解释必须按所用度量区分,不能统一按「分高即相关」处理。
概念解释
- L2:欧氏距离,近邻排序取距离最小。
- COSINE:方向相似度,值越大方向越接近(按实现约定映射为得分)。
- IP:内积,幅度参与结果,未归一化时模长大的向量内积占优。
原理流程
选度量 → 计算对应距离/相似度
→ 按度量方向排序:L2 升序,COSINE/IP 按索引得分约定
代码 / 命令
# 度量与得分方向对照以官方 vectors 文档为准
常见误区
- 误区:L2 得分和 COSINE 得分可以横向比较。正解:量纲与方向不同,不可跨度量比较。
- 误区:IP 结果一定等于余弦。正解:未归一化时 IP 保留幅度信息,排序与余弦不同。
追问
- 问:业务展示相似度百分比怎么做?答:按度量把距离换算到统一口径后再展示,不直接暴露原始距离值。
- 问:混用度量会怎样?答:同一索引固定一种度量,跨度量比较需要重新归一化计算。
05.6.9.1-032 EF_RUNTIME 查询期参数怎么调?
频率 ★★★☆☆ | 难度 进阶
一句话结论
EF_RUNTIME 控制 HNSW 查询遍历的候选宽度,调大提高召回但增加单查询计算量;它是查询期行为参数,与建图的 EF_CONSTRUCTION 分工不同,调优要在判断集上对比 recall 与延迟。
概念解释
- 查询期宽度:遍历时考察的邻居候选数。
- 召回关系:候选越宽,真正近邻被纳入的概率越高。
- 成本关系:宽度越大,距离计算量与 P99 越高。
原理流程
固定查询集 → 梯度调整 EF_RUNTIME
→ 记录 recall@k 与 P99 → 选拐点固化
代码 / 命令
# 待确认:EF_RUNTIME 在当前版本是建索引配置还是查询参数,以官方文档为准
常见误区
- 误区:EF_RUNTIME 影响建图质量。正解:建图由 EF_CONSTRUCTION 控制,二者不要混淆。
- 误区:调大 EF_RUNTIME 没有副作用。正解:候选宽度上升直接增加查询计算成本。
追问
- 问:召回不足先调什么?答:先调 EF_RUNTIME,再评估 M 与 EF_CONSTRUCTION 等建图参数。
- 问:高并发下怎么保延迟?答:限制 EF_RUNTIME 与 k,结合压测 P99 设定上限。
05.6.9.1-033 FLAT 的 BLOCK_SIZE 与动态增删有什么关系?
频率 ★★★☆☆ | 难度 高级
一句话结论
BLOCK_SIZE 决定 FLAT 向量存储块的组织方式,增删文档时块内空间维护按模块机制进行;FLAT 结构简单但遍历成本随总量线性增长,频繁增删下的空间效率需结合实例观察。
概念解释
- 块组织:向量按块连续存储,扫描按块读取。
- 增删影响:删除条目后的空间回收不保证立即紧凑。
- 适用边界:FLAT 更适合规模稳定、更新不极端频繁的小数据集。
原理流程
向量按 BLOCK_SIZE 入块
新增 → 追加/扩容块;删除 → 标记清理
查询 → 遍历块内有效向量
代码 / 命令
# 待确认:FLAT 块回收机制与 BLOCK_SIZE 默认值,以官方向量文档为准
常见误区
- 误区:FLAT 增删不需要维护结构。正解:条目清理与块组织仍有内部成本,只是没有图重建。
- 误区:BLOCK_SIZE 越大遍历越快。正解:块大小影响内存局部性,需按数据规模压测。
追问
- 问:高频更新选 FLAT 还是 HNSW?答:小数据集 FLAT 结构轻;规模上来后评估 HNSW 写入与维护成本。
- 问:删除很多后空间不回落怎么办?答:观察模块回收窗口,长期不回收可重建索引整理。
05.6.9.1-034 PREFIX 与 ON HASH/JSON 怎么绑定?
频率 ★★★☆☆ | 难度 基础
一句话结论
PREFIX 限定哪些 key 纳入索引,ON 子句指定文档结构类型;写入 key 的前缀与结构必须和索引声明一致,否则文档不会被索引。
概念解释
- 前缀匹配:key 以声明前缀开头才纳入。
- 结构一致:Hash 索引用 HSET 写入,JSON 索调用 JSON 写入命令。
- 多前缀:数量参数后跟多个前缀(能力以版本文档为准)。
原理流程
FT.CREATE idx ON HASH PREFIX 1 doc: SCHEMA ...
写入 key:doc:1001 → 命中前缀 → 入索引
其他前缀 key → 不纳入
代码 / 命令
FT.CREATE idx:demo ON HASH PREFIX 1 doc: SCHEMA title TEXT embedding VECTOR ...
常见误区
- 误区:写入任意 key 都能被索引搜到。正解:必须匹配声明前缀且结构一致。
- 误区:HASH 索引里存 JSON 字符串也行。正解:结构不匹配会导致字段提取失败。
追问
- 问:同一前缀需要分两套索引怎么办?答:用不同前缀区分,或评估多索引绑定关系。
- 问:前缀改动要重建吗?答:索引前缀属于结构定义,变更需新建索引。
05.6.9.1-035 一个索引可以定义多个向量字段吗?
频率 ★★★☆☆ | 难度 进阶
一句话结论
可以在同一 SCHEMA 中定义多个 VECTOR 字段,分别对应不同内容的嵌入;查询时 KNN 子句指定目标向量字段,多字段检索的组合方式需按版本能力确认。
概念解释
- 多字段场景:标题向量、正文向量、图像向量分字段存放。
- 查询指定:每个 KNN 子句绑定一个 @向量字段。
- 成本叠加:每路向量都占用本体与结构内存。
原理流程
SCHEMA: title_vec VECTOR ..., passage_vec VECTOR ...
检索:KNN 子句指向目标字段;多路组合见 022 题
代码 / 命令
title_vec VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
passage_vec VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:多个向量字段可以互相替代检索。正解:字段独立编码与索引,查询必须指明目标字段。
- 误区:多字段共享一份向量存储。正解:每个字段独立占用向量本体与结构开销。
追问
- 问:多向量字段内存怎么估?答:逐字段累加本体与图开销,再合并标量与原始文档占用。
- 问:两路向量需要融合排序怎么办?答:按版本能力在表达式内组合或应用层合并候选。
05.6.9.1-036 向量范围(radius)查询怎么写?
频率 ★★★☆☆ | 难度 高级
一句话结论
范围检索以查询向量为中心、按距离半径返回边界内文档,配合 EPSILON 容差;其表达式语法与 KNN TopK 不同,具体写法与支持算法以当前版本官方文档为准。
概念解释
- 半径语义:距离小于等于阈值的向量集合。
- 与 KNN 区别:KNN 按数量取 TopK,范围查询按距离阈值取集合。
- 适用场景:需要「相似度达到某水平以上」的召回,而非固定条数。
原理流程
查询向量 + 半径 → 计算各向量距离 → 落在半径(含容差)内返回
代码 / 命令
# 待确认:半径查询表达式、半径参数名与 EPSILON 支持范围,以官方向量检索文档为准
常见误区
- 误区:范围查询等价于大 k 的 KNN。正解:一个按距离阈值,一个按条数截断,结果口径不同。
- 误区:半径单位与度量无关。正解:半径阈值对应 L2/COSINE/IP 的距离口径,不能跨度量套用。
追问
- 问:范围查询结果为空怎么调?答:先放宽半径验证向量可计算,再逐步收紧阈值。
- 问:半径阈值怎么标定?答:在判断集上统计近邻距离分布,按业务可接受下限取值。
05.6.9.1-037 向量建索引与查询有哪些高频语法错误?
频率 ★★★★☆ | 难度 基础
一句话结论
高频错误包括:count 计数错位、TYPE/DIM 与实际向量不符、缺少 DIALECT 2、blob 端序或宽度错误、前缀不匹配、KNN 字段名写错、参数名与 PARAMS 不一致;逐项对照官方示例可快速定位。
概念解释
- 建索引类:count、算法枚举、类型枚举、度量枚举错误。
- 写入类:blob 长度、端序、空值/非法数值。
- 查询类:方言版本、参数绑定、字段名、表达式括号。
原理流程
报错分类:建索引失败 → 核对 count/枚举
写入失败 → 核对 blob 长度/端序
查询失败 → 核对 DIALECT/PARAMS/字段名
代码 / 命令
# 自查清单:
# 1) count = 属性 token 总数
# 2) TYPE/DIM/DISTANCE_METRIC 与向量一致
# 3) DIALECT 2+,PARAMS 参数名一致
# 4) blob 宽度/端序正确,前缀匹配写入 key
常见误区
- 误区:报错只看最后一行。正解:解析错位类错误要回溯到 count 与参数顺序。
- 误区:语法错误与数据错误混为一谈。正解:先排除命令语法,再查向量编码与数据。
追问
- 问:怎么建立防错习惯?答:封装建索引与写入客户端,统一序列化与参数校验,避免手写裸命令。
- 问:跨版本语法差异怎么处理?答:上线前在目标版本实例跑通最小示例,不照搬其他产品命令。
05.6.9.1-038 二进制向量的端序与宽度怎么保证一致?
频率 ★★★★☆ | 难度 高级
一句话结论
blob 按元素类型宽度编码并采用固定端序(常见小端),入库与查询两侧必须使用相同序列化规则;宽度或端序不一致会导致解码向量错乱,距离结果完全不可用。
概念解释
- 宽度:FLOAT32 4 字节、FLOAT64 8 字节,字节长度 = DIM × 宽度。
- 端序:多字节数值的高低字节排列顺序,跨语言/跨客户端必须统一。
- 校验:解码后检查元素个数、模长与抽样数值是否合理。
原理流程
浮点数组 → 固定宽度 + 固定端序序列化
→ 入库 blob / 查询 blob 同一规则
→ 解码后逐维比对校验
代码 / 命令
# 待确认:当前版本 blob 端序约定,以官方 vectors 文档为准;常见为小端
# 校验:blob 长度 == DIM × 每维字节;解码模长非零
常见误区
- 误区:端序只在跨机器时有影响。正解:同一进程内不同客户端/语言库的默认端序也可能不同。
- 误区:blob 长度对了就没问题。正解:宽度对但端序错,解码出的数值依然错乱。
追问
- 问:怎么定位端序错误?答:抽样解码几个维度,与原始浮点值对照,符号与量级明显异常即为端序问题。
- 问:换语言客户端要注意什么?答:确认序列化库的字节序设置,与入库侧保持一致后再批量写入。
05.6.9.1-039 查询向量参数为什么必须是字节数组?
频率 ★★★☆☆ | 难度 进阶
一句话结论
KNN 参数绑定的查询向量按内部二进制格式接收,客户端需把查询浮点数组序列化为与字段 TYPE 匹配的字节数组;传字符串数组或文本数字列表无法被正确解码。
概念解释
- 参数类型:二进制字节流,与入库 blob 同规则。
- 序列化位置:客户端 SDK 负责把浮点列表打包为字节。
- 校验:查询前检查字节长度与维度。
原理流程
查询文本 → 嵌入模型 → 浮点数组
→ 序列化为字节数组 → PARAMS 绑定 → 索引解码计算
代码 / 命令
# SDK 侧:vector_to_bytes(float_list) → 作为 blob 参数传入
常见误区
- 误区:SDK 会自动把浮点列表转 blob。正解:需按库提供的序列化方法显式转换,具体 API 名以对应客户端文档为准。
- 误区:查询向量可以复用入库的字符串格式。正解:两侧都要求二进制编码。
追问
- 问:查询向量编码错误表现是什么?答:距离结果异常或报错,抽样解码与预期向量比对即可发现。
- 问:同一客户端能否复用序列化函数?答:入库与查询共用同一序列化逻辑,避免两侧规则漂移。
05.6.9.1-040 SVS-VAMANA 算法是什么定位?
频率 ★★★☆☆ | 难度 高级
一句话结论
SVS-VAMANA 是一种图类向量索引算法(Vamana 路线),在部分版本中作为 HNSW 之外的可选算法;其参数、适用规模与版本支持需以官方文档为准,未确认前不要在生产索引中选用。
概念解释
- 算法类别:近邻图索引,与 HNSW 同属 ANN 图路线,构建与遍历细节不同。
- 版本依赖:可用算法集合随 RediSearch 版本演进,存在新增或弃用。
- 选型方法:在目标版本实例上建索引压测召回与延迟,对比 HNSW/FLAT 后再决定。
原理流程
确认版本支持 VAMANA → 建索引指定算法与参数
→ 样本压测 recall@k / P99 / 内存 → 对比其他算法选型
代码 / 命令
# 待确认:SVS-VAMANA 在当前版本的参数项、默认值与限制,以官方 vectors 文档为准
常见误区
- 误区:新算法一定优于 HNSW。正解:选型必须按自有数据压测,算法优势有数据集前提。
- 误区:算法可以在建索引后切换。正解:算法属于索引结构,切换需重建索引。
追问
- 问:怎么查版本支持哪些算法?答:对照 FT.CREATE 向量字段文档的算法枚举与版本说明。
- 问:实验性算法能上生产吗?答:先在非生产验证稳定性与召回,确认官方支持状态后再评估。
05.6.9.1-041 FT.SEARCH 返回的总数与 KNN 截断是什么关系?
频率 ★★★☆☆ | 难度 基础
一句话结论
FT.SEARCH 头部返回的匹配计数受查询表达式、KNN 候选截断与方言行为影响;KNN TopK 只返回距离最近的 k 条,计数不等于全量可匹配文档数,业务分页不要把它当全量总数。
概念解释
- 计数口径:返回结果数量与检索截断规则相关。
- KNN 截断:候选经过近邻排序后只取 k 条。
- 分页配合:需要翻页时结合 LIMIT/OFFSET 与候选深度评估,见 05.6.9.2-008。
原理流程
表达式匹配 → KNN 取 TopK → 返回列表与计数
业务展示:按返回条数与距离判断是否还有更多候选
代码 / 命令
# 待确认:当前版本匹配计数的精确口径,以官方 FT.SEARCH 文档为准
常见误区
- 误区:返回总数等于索引内相关文档总量。正解:KNN 截断后计数只反映本次召回结果。
- 误区:计数为零说明索引为空。正解:先排查过滤条件、向量编码与 DIALECT,再判断数据问题。
追问
- 问:需要精确全量匹配数怎么办?答:对纯标量/全文条件单独统计,向量近邻结果不承担全量计数。
- 问:计数与实际返回条数不符?答:检查 KNN k、LIMIT 截断与方言行为,对照官方返回结构说明。
05.6.9.1-042 标量字段与向量字段在 SCHEMA 中怎么并列定义?
频率 ★★★☆☆ | 难度 基础
一句话结论
SCHEMA 内逐行列出标量字段(TEXT/TAG/NUMERIC 等)与 VECTOR 字段,字段名在查询表达式中以 @字段名 引用;类型决定该字段可参与的过滤与检索方式。
概念解释
- 字段分工:标量负责过滤与展示,向量负责近邻。
- 命名引用:表达式中 @category、@embedding 与 SCHEMA 名一致。
- 类型约束:字段声明类型后,查询子句必须匹配其类型。
原理流程
SCHEMA
category TAG
price NUMERIC
embedding VECTOR ...
查询:@category:{x} 与 @embedding KNN 引用
代码 / 命令
FT.CREATE idx:demo ON HASH PREFIX 1 doc: SCHEMA
category TAG
title TEXT
embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
常见误区
- 误区:字段不声明类型也能在查询中使用。正解:未入 SCHEMA 的字段不被索引,表达式引用不到。
- 误区:TAG 字段可以做全文分词匹配。正解:TAG 是精确标签匹配,全文匹配用 TEXT。
追问
- 问:多余字段怎么处理?答:未声明字段不参与索引,原始文档仍可在回表时读取。
- 问:字段名大小写敏感吗?答:表达式引用需与 SCHEMA 声明一致,按官方命名规则核对。
05.6.9.1-043 索引构建是后台异步的吗,怎么观察延迟?
频率 ★★★☆☆ | 难度 进阶
一句话结论
文档写入后索引条目的构建存在后台处理过程,尤其是批量灌入时;可通过 FT.INFO 的计数与构建状态观察进度,写入到可检索之间存在短暂延迟,在线业务需接受或监控这一窗口。
概念解释
- 后台构建:条目建立、向量编码与图维护异步完成。
- 进度观察:FT.INFO 文档/向量计数与构建状态字段。
- 一致性窗口:刚写入的文档可能短暂不可被检索命中。
原理流程
写入文档 → 后台索引构建 → 条目可检索
观察:FT.INFO 计数增长与状态稳定
代码 / 命令
# 待确认:当前版本索引异步性的具体机制与状态字段,以官方文档为准
常见误区
- 误区:HSET 返回成功立即可被 KNN 命中。正解:存在索引构建窗口,需观察计数与进度。
- 误区:计数不增长是写入失败。正解:先区分写入未成功与索引后台未完成两种情况。
追问
- 问:写后立即检索怎么保证?答:关键链路查询前核对索引进度,或业务侧短重试。
- 问:批量灌入积压怎么识别?答:FT.INFO 计数落后于 key 增长,构建状态长期未稳定。
05.6.9.1-044 重复写入或覆盖更新文档时向量条目怎么更新?
频率 ★★★☆☆ | 难度 进阶
一句话结论
同一文档 key 重复写入时,索引按最新内容更新对应标量与向量条目;更新向量后旧向量被替换,不再参与后续近邻检索,更新链路要保证向量与原文一致写入。
概念解释
- 覆盖语义:同 key 新值替换旧值,索引条目同步更新。
- 向量替换:旧 blob 条目失效,新向量进入索引。
- 一致性:原文、标量与向量应在同一写入流程中更新,避免字段错位。
原理流程
更新文档 → 新原文/标量/向量写入
→ 索引替换旧条目 → 检索使用新向量
代码 / 命令
# 更新后校验:抽样文档解码新向量,确认旧向量不再出现在近邻结果
常见误区
- 误区:只更新原文不更新向量,索引仍保持旧向量。正解:向量字段不重写就保留旧值,语义检索滞后。
- 误区:部分字段更新会清空其他字段。正解:Hash 更新按字段覆盖,未写字段保留,具体命令语义需核对。
追问
- 问:向量失败更新怎么兜底?答:记录更新批次,比对 FT.INFO 与文档向量,失败幂等重试。
- 问:频繁更新对 HNSW 有什么影响?答:图条目维护成本随更新增加,需观察内存与召回稳定性。
05.6.9.1-045 客户端 SDK 里向量怎么序列化与调用?
频率 ★★★☆☆ | 难度 进阶
一句话结论
各语言客户端提供 RediSearch 命令封装与向量序列化辅助;使用时先把浮点列表打包为字节数组,再按命令语法传索引名、查询表达式、PARAMS 与 DIALECT,具体 API 名称以对应客户端文档为准。
概念解释
- 客户端职责:命令封装、参数编码、结果解析。
- 序列化:向量转 blob 的工具函数或参数类型。
- 跨语言一致性:序列化规则(宽度、端序)必须与入库侧统一。
原理流程
SDK 初始化连接 → 定义/读取索引
→ 序列化向量 → 构造 FT.SEARCH 表达式与 PARAMS
→ 解析返回文档与得分
代码 / 命令
# 待确认:各客户端(redis-py / node-redis / NRedisStack / go-redis)的向量 API 名称
# 集成示例见 05.6.9.2 章节
常见误区
- 误区:所有客户端向量 API 同名同义。正解:封装方式随语言库不同,需对照各自文档。
- 误区:SDK 自动处理 DIALECT。正解:调用时仍需在命令参数中指定方言版本。
追问
- 问:选客户端看什么?答:模块命令支持完整度、向量序列化辅助、连接池与维护活跃度。
- 问:调试 SDK 调用怎么对照?答:先用裸命令在实例跑通最小示例,再映射到 SDK 调用。
05.6.9.1-046 TAG 多值字段怎么存储与匹配?
频率 ★★★☆☆ | 难度 进阶
一句话结论
TAG 字段可存储多个标签值,写入时按字段类型约定的分隔符组织;查询时匹配任一标签即命中,多值 TAG 常用于类别、租户、权限等可枚举过滤维度。
概念解释
- 多值存储:单字段包含多个标签,索引为每个标签建条目。
- 分隔约定:标签分隔符在字段类型选项中配置,默认分隔符以官方文档为准。
- 匹配方式:TAG 表达式按标签精确匹配,不做分词。
原理流程
写入多标签 → 按分隔符拆分 → 逐标签索引
查询:@field:{tag} → 命中包含该标签的文档
代码 / 命令
# 待确认:TAG 多值分隔符配置项与默认值,以官方字段类型选项文档为准
常见误区
- 误区:TAG 多值用逗号就无需配置。正解:分隔规则按索引选项解析,不匹配会导致标签整体成为一个值。
- 误区:TAG 支持部分匹配。正解:TAG 是精确标签匹配,前缀/模糊匹配需用 TEXT 或额外处理。
追问
- 问:标签含空格或特殊字符怎么办?答:写入前规范化,按转义规则处理查询表达式。
- 问:租户隔离用 TAG 怎么建?答:租户标识作为 TAG 字段,查询强制携带租户标签条件。
05.6.9.1-047 上线前怎么检查模块加载与命令可用?
频率 ★★★☆☆ | 难度 基础
一句话结论
先确认 RediSearch 模块已加载、版本满足向量语法要求,再执行 FT._LIST 与最小 FT.CREATE/FT.SEARCH 示例打通闭环;模块缺失或版本过低时,FT. 命令会返回未知命令错误。
概念解释
- 模块状态:服务端模块列表与版本号。
- 能力验证:最小示例覆盖建索引、写入、KNN 查询。
- 版本对照:向量算法、DIALECT 与参数支持以版本矩阵为准。
原理流程
查模块列表/版本 → FT._LIST 可用
→ 最小示例建索引 → 写入样本 → KNN 查询成功
→ 再接入业务数据
代码 / 命令
# 待确认:查看模块列表的具体命令,以官方运维文档为准
常见误区
- 误区:Redis Stack 镜像一定带 RediSearch。正解:需确认实际部署加载的模块与版本。
- 误区:命令报错是查询语法问题。正解:先排除模块未加载/版本不满足的基础问题。
追问
- 问:版本过低缺能力怎么办?答:按升级兼容矩阵升级模块,或降级使用版本支持的索引/查询写法。
- 问:测试与生产模块版本要一致吗?答:应保持一致,避免语法在测试可用、生产报错。
05.6.9.1-048 给出一套从建索引到 KNN 检索的完整模板。
频率 ★★★★★ | 难度 高级
一句话结论
完整链路:FT.CREATE 声明标量与 HNSW 向量字段 → HSET 写入二进制向量与元数据 → FT.SEARCH 带 PARAMS 与 DIALECT 执行 KNN → 校验召回与得分;上线前用样本数据跑通全闭环。
概念解释
- 链路三段:建索引声明前缀/结构/向量参数,写入序列化 blob 并校验维度端序,检索用 KNN 子句绑定参数按距离返回。
原理流程
FT.CREATE 定义 schema → 批量写入 blob 向量与标量 → FT.SEARCH KNN 召回 TopK → 抽样校验维度、模长与得分方向
代码 / 命令
FT.CREATE idx:demo ON HASH PREFIX 1 doc: SCHEMA
category TAG
title TEXT
embedding VECTOR HNSW 12 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE
M 16 EF_CONSTRUCTION 200 EF_RUNTIME 10
# 写入(blob 由客户端按 FLOAT32 序列化)
HSET doc:1001 category "tech" title "示例标题" embedding <blob>
# 检索
FT.SEARCH idx:demo "(@category:{tech})=>[KNN 10 @embedding $blob AS dist]"
PARAMS 2 blob <查询向量字节>
DIALECT 2
RETURN 2 title category
常见误区
- 误区:模板参数可直接上生产。正解:维度、度量、HNSW 参数与候选宽度需按自有数据压测校准。
- 误区:只验证建索引不验证检索。正解:必须跑通写入到 KNN 返回的完整闭环并抽样核对向量。
追问
- 问:上线前还需校验什么?答:内存占用估算、召回基线、过滤组合与异常向量拦截。
- 问:后续接入混合过滤与集群部署?答:见 05.6.9.2 章节的过滤、集群与集成实战内容。
参考来源
- Redis RediSearch 向量概念与命令:https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/
- RediSearch 字段类型与索引选项:https://redis.io/docs/latest/develop/ai/search-and-query/indexing/field-and-type-options/
- Redis 向量数据库入门:https://redis.io/docs/latest/develop/get-started/vector-database/
- RediSearch 查询语法:https://redis.io/docs/latest/develop/interact/search-and-query/query/