Redis Vector Search 向量数据库手册

适用版本：Redis 8.10.3 稳定版（8.12-rc2 为预发布，勿用于生产），核实于 2026-11 许可与形态：Redis 8+ 为 RSALv2 / SSPLv1 / AGPLv3 三选一（7.2 及以前 BSD-3-Clause）；单机 / 集群内存服务，向量能力内置于 Redis Open Source 一句话定位：在已有 Redis 8 实例里直接用 VADD / VSIM 或 FT.CREATE + FT.SEARCH 做向量检索，既不新增数据库，也不再需要 Redis Stack。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Redis 的向量能力不是独立服务，而是 Redis 8 内置的两套能力：Vector Sets（原生数据类型）+ Redis Query Engine（原 RediSearch，FT.*）。二者都跑在 Redis 进程内，复用现有连接、持久化（RDB / AOF）、复制与集群，无独立进程 / 端口 / 存储。

核心主题：已有 Redis 8 时，向量能力是内置功能，不是再装一个 Redis Stack，也不是再部署 Milvus / Qdrant。官方原文：「Redis 8 in Redis Open Source replaces Redis Stack, so there is no separate module to install or version」。

适合：① 已有 Redis 8 且向量规模能被内存容纳；② 需要极低延迟的在线召回；③ 向量要与 Hash / JSON / TTL / 业务 key 同实例；④ 需要「全文 + 向量」用 FT.HYBRID 一次执行；⑤ RAG 会话级 / 热点数据缓存式检索。

不适合：① 向量规模超大、内存成本不可接受；② 需要磁盘型索引、十亿级分布式分片；③ 需要 GPU 或复杂量化族；④ 现有实例是 Redis 7.2 及以前且不能升级到 8；⑤ 需要强事务型 MVCC（应看 pgvector）。

1.2 规模、链路位置与「何时该换」

链路位置：离线「文档 → Embedding → VADD 或写入 Hash 的 vec 字段」；在线「query → Embedding → VSIM 或 FT.SEARCH ... [KNN ...] → 取回业务属性 → 重排 → LLM / 展示」。Redis 常位于召回 / 缓存层，热点向量与会话态数据同实例。

该换专用向量库的信号：内存成本随向量规模线性上升且不可接受；需要磁盘型 / 十亿级分布式索引；需要复杂重排或 GPU；向量检索要独立隔离、不想与缓存争用内存与 CPU。

2. 版本、许可与官方入口

2.1 版本状态表

避坑：8.12 是 RC，相关向量特性待 GA，方案与发版公告不要把它写成稳定能力。 版本差异：Redis 8 起 RediSearch / JSON / TimeSeries / Bloom 已内置，Redis Stack 已 EOL；7.2 及以前是 BSD-3-Clause，8+ 改为三选一许可，升级前要评估许可影响。

2.2 许可与官方入口

• 许可：Redis 8+ 为 RSALv2 / SSPLv1 / AGPLv3 三选一；7.2 及以前 BSD-3-Clause。许可变更属升级时的合规事项，以官方许可文本为准。
• 能力边界：Vector Sets 与 Query Engine（原 RediSearch）在 Redis Open Source 中内置，不需要单独模块、不需要单独版本号。

2.3 版本识别与近两年变更

$ redis-cli INFO server        # 通用命令，查看 redis_version 字段，确认 ≥8
$ redis-cli COMMAND INFO VADD  # 通用命令，确认 Vector Sets 命令可用

3. 安装与启动

3.1 说明与前置条件

本类产品通常已有 Redis 实例，「安装」实为「升级到 8+ 并启用向量能力」。官方资料未提供官方安装命令、镜像 tag 与端口，部署安装以官方文档为准，勿臆测。前置条件：Redis 8+（Vector Sets 为 8.0+ 原生类型）；确认许可三选一已评估；确认内存能容纳向量与索引。

避坑：旧教程第一步是「安装 Redis Stack / 加载 RediSearch 模块」。Redis 8 起不再需要，内置即可；照旧教程做会引入多余组件与版本不一致。

3.2 方式一：Vector Sets（原生类型，零配置）

$ redis-cli PING                                  # 连通性
$ redis-cli VADD points VALUES 2 1.0 1.0 pt:A   # 首次 VADD 即建立 Vector Set
$ redis-cli VADD points VALUES 2 -1.0 -1.0 pt:B
$ redis-cli VSIM points VALUES 2 0.9 0.9 COUNT 2 WITHSCORES

示例用 2 维（沿用官方 Quickstart），实际常见 768 / 1024 / 1536 维。Vector Sets 内置 HNSW，无需建索引命令。

3.3 方式二：Redis Query Engine（建二级索引）

$ redis-cli FT.CREATE idx ON HASH PREFIX 1 doc: SCHEMA \
    vec VECTOR HNSW 6 TYPE FLOAT32 DIM 3 DISTANCE_METRIC COSINE M 16 EF_CONSTRUCTION 200
$ redis-cli FT.SEARCH idx "*=>[KNN 3 @vec $vector AS score]" PARAMS 2 vector <blob> DIALECT 2

示例用 3 维便于阅读，实际常见 768 / 1024 / 1536（官方 Quickstart 示例为 DIM 768）。HNSW 6 中 6 的确切含义官方资料未核实，按官方示例写法保留。FT.SEARCH 必须带 DIALECT 2。

3.4 目录、端口与健康检查

健康检查：方式一执行 VADD + VSIM 能返回带分数的元素；方式二执行 FT.CREATE + FT.SEARCH 能返回文档。两者互相不能检索对方的数据（见 4.1）。

3.5 生产最小配置建议

认证 / TLS / ACL / 网络暴露面沿用 Redis 基线（通用运维见根目录手册）；内存上限与淘汰策略需把向量与 HNSW 索引算进去；RDB / AOF 与复制沿用现有配置，注意大 key 恢复时的索引重建时间。

⚠️ 危险：对存的向量 key 执行 FLUSHALL / 误设过短 TTL 会导致向量数据整体丢失，属数据丢失级操作，执行前必须确认实例与 key 范围。

4. 核心概念与数据模型

4.1 两套独立 API 横向对照（重点）

避坑：VADD / VSIM 与 FT.CREATE + FT.SEARCH 是两套独立 API，不能混用。VADD 写的 Vector Set 不会被 FT.SEARCH 检索到，FT.CREATE 建的索引也管不到 Vector Set；选中一条路径就全程用它。

4.2 命令语法与术语

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

• 量化：Q8 默认（int8）、BIN 二值、NOQUANT 不量化；三者互斥且只在首次 VADD 时决定，后续 VADD 改不了。
• FP32 blob 必须 little-endian（小端）：用 FP32 传二进制向量时必须按小端字节序打包，大端会得到完全错误的距离。
• 距离方向：VSIM ... WITHSCORES 的分数越大越相似；FT.SEARCH 的 score 按 DISTANCE_METRIC 语义解释（COSINE 下越大越相似）。

4.3 生命周期与一致性

VADD 首次调用即创建集合并按需建 HNSW；后续 VADD 增量插入。FT.CREATE 建索引后，符合 PREFIX 的 Hash / JSON 文档被索引，新写入自动入索引。向量与业务 key 同处 Redis 的持久化 / 复制 / 集群体系；一致性沿用 Redis 的复制模型（异步复制，非强一致事务）。

5. 快速上手：完整 CRUD 示例

示例用 2 / 3 维便于阅读；实际常见 768 / 1024 / 1536 维。

5.1 Vector Sets：完整 redis-cli CRUD

$ redis-cli DEL points
# 1) 插入（首次 VADD 建集合，默认 Q8 量化）
$ redis-cli VADD points VALUES 2 1.0 1.0 pt:A
$ redis-cli VADD points VALUES 2 -1.0 -1.0 pt:B
$ redis-cli VADD points VALUES 2 0.9 0.8 pt:C

# 2) 相似度检索（分数越大越相似）
$ redis-cli VSIM points VALUES 2 0.9 0.9 COUNT 2 WITHSCORES

# 3) 带标量过滤的检索：先设属性，再用 FILTER
$ redis-cli VSETATTR points pt:A '{"category":"tech"}'
$ redis-cli VSETATTR points pt:B '{"category":"life"}'
$ redis-cli VSIM points VALUES 2 0.9 0.9 COUNT 2 WITHSCORES FILTER '<过滤表达式>'

# 4) 强制精确扫描（对照近似结果，验证召回）
$ redis-cli VSIM points VALUES 2 0.9 0.9 COUNT 2 WITHSCORES TRUTH

# 5) 更新：同 element 再 VADD（可带 CAS）
$ redis-cli VADD points VALUES 2 1.0 1.2 pt:A

# 6) 删除成员  7) 查看信息  8) 清理
$ redis-cli VREM points pt:C
$ redis-cli VCARD points
$ redis-cli VDIM points
$ redis-cli VINFO points
$ redis-cli DEL points

FILTER 的表达式语法官方资料未给出逐字写法，按 VSIM 官方文档填写 <过滤表达式>；可确认的是它配合 FILTER-EF max-filtering-effort 控制过滤探索力度。

5.2 Redis Query Engine：完整 redis-cli CRUD

$ redis-cli FT.DROPINDEX idx           # 若已存在（首次可跳过）
# 1) 建索引（向量存 Hash 的 vec 字段）
$ redis-cli FT.CREATE idx ON HASH PREFIX 1 doc: SCHEMA \
    vec VECTOR HNSW 6 TYPE FLOAT32 DIM 3 DISTANCE_METRIC COSINE M 16 EF_CONSTRUCTION 200 \
    category TAG

# 2) 插入文档（vec 为 little-endian FP32 blob）
$ redis-cli HSET doc:1 vec <blob> category tech
$ redis-cli HSET doc:2 vec <blob> category tech
$ redis-cli HSET doc:3 vec <blob> category life

# 3) KNN 检索（必须 DIALECT 2）
$ redis-cli FT.SEARCH idx "*=>[KNN 3 @vec $vector AS score]" PARAMS 2 vector <blob> DIALECT 2

# 4) 带标量过滤的检索：过滤前置条件的逐字语法官方资料未核实，按官方文档构造
#    FT.SEARCH idx "<过滤条件>=>[KNN 3 @vec $vector AS score]" PARAMS 2 vector <blob> DIALECT 2

# 5) 更新  6) 删除  7) 清理
$ redis-cli HSET doc:1 vec <new_blob> category tech
$ redis-cli DEL doc:3
$ redis-cli FT.DROPINDEX idx
$ redis-cli DEL doc:1 doc:2

避坑：<blob> 必须是 little-endian FP32，不能是 JSON 数组字符串；FT.SEARCH 少了 DIALECT 2 会失败或行为不符预期。

5.3 输出怎么读与 Python 等价示例

import struct
import redis

VEC = [1.0, 2.0, 3.0]                 # 示例 3 维，实际常见 768 / 1024 / 1536
blob = struct.pack("<3f", *VEC)        # little-endian FP32：必须小端，勿用大端
r = redis.Redis(host="127.0.0.1", port=6379, decode_responses=False)
res = r.execute_command(
    "FT.SEARCH", "idx",
    "*=>[KNN 3 @vec $vector AS score]",
    "PARAMS", "2", "vector", blob,
    "DIALECT", "2",
)
print(res)

避坑：旧教程会写 import redisstack / 提示先装 Redis Stack，或用 struct.pack(">3f", ...)（大端）。Redis 8 不需要 Stack，且 FP32 blob 必须 little-endian。 redis 客户端属通用第三方库，方法名以所用驱动版本文档为准；redis-cli / REST 等价示例：本篇主示例已是 redis-cli，无独立 REST 向量接口。

6. 索引与检索进阶

6.1 参数调优表

6.2 recall 与延迟、精确对照

EF / FILTER-EF 是主旋钮，调大 → 召回↑、延迟↑。用 VSIM ... TRUTH 强制精确扫描跑 ground truth，再对同一批 query 算 recall@COUNT，逐步加 EF 到达标。TRUTH 本身是重要的验收工具，不要只在近似模式下凭感觉判断召回。

6.3 过滤、混合检索与多向量

• Vector Sets 过滤：VSETATTR 设属性 + VSIM ... FILTER <expression> + FILTER-EF；属性可用 VGETATTR / WITHATTRIBS 读回。
• 混合检索：8.4 GA 起 FT.HYBRID 支持全文 + 向量一次执行，可用 RRF 或线性加权融合（官方资料未给出逐字参数，按官方文档构造）。
• 多向量 / 稀疏 / 重排：Query Engine 可对多字段建索引；两阶段「ANN 取候选 + 业务权重重排」为经验做法；SVS-VAMANA（8.2 增加）相关细节官方资料未核实，以官方文档为准。

6.4 量化与容量估算（经验公式，非官方承诺）

FP32 原始向量体积 ≈ 4 × dim 字节；dim=768 → 3072 B ≈ 3.0 KB / 条
Q8（int8）量化后 ≈ 1 × dim 字节 → 约 768 B / 条（约为 FP32 的 1/4）
总量 ≈ 单条体积 × 条数 + HNSW 图连接开销（M 越大越占内存）+ Redis key / 属性开销
BIN 二值、NOQUANT 不量化分别对应更省 / 更占内存

系数为经验区间，非官方承诺；用 MEMORY USAGE <key> / VINFO 对真实 key 实测后做容量规划。内存是 Redis 向量方案的首要约束。

7. 生产部署与运维

• 高可用：向量 key 随 Redis 主从复制与集群分片；Vector Set 是单个 key，大集合会落在单分片，需评估热点与内存倾斜（经验性）。
• 备份恢复：RDB / AOF 沿用现有配置；恢复时 Query Engine 索引重建耗时纳入 RTO；FT.DROPINDEX 后需重建索引。
• 监控（沿用 Redis 监控体系，无独立端点）：

• 扩缩容：以 6.4 估算为起点；内存优先，避免与缓存争用；集群模式注意大 Vector Set 的单 key 限制。
• 升级迁移：升到 8+ 即可获得内置能力；从 Redis Stack 迁移时核对「不再需要单独模块与版本」；许可从 BSD-3-Clause 变为三选一需合规评估。
• 安全 / 日志：ACL、TLS、网络暴露面沿用 Redis 基线；向量命令同样受 ACL 约束（通用运维见根目录手册）。日志由 Redis 配置决定，无独立向量日志。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：还在装 Redis Stack / 加载 RediSearch 模块。原因：旧教程沿用 8 以前的做法。怎么做：Redis 8 起不再需要 Redis Stack，能力已内置。
2. 现象：VADD 写的数据 FT.SEARCH 查不到。原因：两套独立 API 不能混用。怎么做：Vector Sets 用 VADD/VSIM，Query Engine 用 FT.CREATE/FT.SEARCH，全程一致。
3. 现象：FT.SEARCH 报语法 / 行为异常。原因：缺 DIALECT 2。怎么做：向量查询一律带 DIALECT 2。
4. 现象：FP32 blob 检索结果完全错。原因：blob 必须 little-endian。怎么做：struct.pack("<3f", ...) 小端打包，勿用大端。
5. 现象：后续 VADD 改 NOQUANT / BIN 没生效。原因：量化档位仅首次 VADD 生效且三者互斥。怎么做：首个 VADD 就定好档位，改档需重建集合。
6. 现象：近似结果召回不足却判断为「数据少了」。原因：未用精确基线对照。怎么做：VSIM ... TRUTH 强制精确扫描跑 ground truth 再算 recall。
7. 现象：文档 / 方案写 Redis 8.12 新特性。原因：8.12 是 RC，向量特性待 GA。怎么做：生产写 8.10.3，RC 能力标注「以官方 GA 为准」。
8. 现象：升级后许可不合规。原因：8+ 改为 RSALv2 / SSPLv1 / AGPLv3 三选一。怎么做：升级前做许可评估。
9. 现象：FT.CREATE 后搜不到文档。原因：PREFIX 与 Hash key 前缀不匹配。怎么做：对齐 PREFIX 1 doc: 与 doc:*。
10. 现象：内存被向量撑爆、业务 key 被淘汰。原因：向量与缓存同实例争用内存。怎么做：⚠️ 独立实例或量化，检查 maxmemory-policy，可能引发线上事故。
11. 现象：HNSW 6 里的 6 被当成维度或版本。原因：官方资料未核实其含义，易被臆测。怎么做：按官方示例写法保留，勿自行解释。
12. 现象：FLUSHALL / 短 TTL 后向量全丢。原因：向量就是普通 Redis key。怎么做：⚠️ 确认实例与 key 范围，纳入备份，属数据丢失级操作。

10. 速查表

11. 参考与延伸

官方链接清单：https://redis.io/docs/latest/develop/data-types/vector-sets/ ｜ https://redis.io/docs/latest/commands/vadd/ ｜ https://redis.io/docs/latest/commands/vsim/ ｜ https://redis.io/docs/latest/commands/ft.create/ ｜ https://redis.io/docs/interact/search-and-query/advanced-concepts/vectors/ ｜ https://redis.io/docs/latest/operate/rs/installing-upgrading/modules-lifecycle/ ｜ https://github.com/redis/redis/releases 。官网、镜像仓库、控制台 URL 官方资料未提供，勿臆测。

与同册其他产品的关系：已有 Redis → 本篇；已有 PG → pgvector.md；已有 ES / OpenSearch → Elasticsearch-OpenSearch.md；已有 ClickHouse → ClickHouse.md；已有国产关系库 → 国产数据库向量能力.md；内存放不下 / 需磁盘型分布式 → 01-专用向量数据库 分册。

进阶阅读：VADD / VSIM 完整参数与量化档位；Query Engine 的 FT.CREATE 向量字段与 FT.HYBRID；Redis 8 模块生命周期与许可变更说明。

本篇「未核实 / 以官方为准」事项：

1. Redis 8.12（RC）向量特性待 GA（清单第 8 条），生产版本只写 8.10.3。
2. VSIM 的 FILTER 表达式逐字语法、Query Engine 带过滤查询体的前置条件写法未核实，示例中以占位符标注，按官方文档构造。
3. FT.CREATE ... HNSW 6 中 6 的确切含义未核实，按官方示例保留，勿自行解释。
4. SVS-VAMANA（8.2 增加）与 FT.HYBRID（8.4 GA）的逐字参数未核实，只写能力与版本。
5. 8.2 / 8.12-rc2 的具体发布日期未核实（官方资料仅给 8.10.3、8.4、8.0 日期）。
6. 官网 / 镜像仓库 / 控制台 URL、安装命令、镜像 tag、HTTP 端口均官方资料未提供，勿臆测；端口 6379 为通用默认值。
7. redis 客户端方法、redis-cli 的 MODULE LIST / INFO / MEMORY USAGE 属通用命令与经验性表述，以所用版本文档为准。
8. 规模、QPS、容量公式、告警阈值均为经验值，非官方承诺，须实测。