Redis 向量检索：从 RediSearch 模块到内核原生 VSS

为什么需要 Redis 向量：KV 存储与语义检索割裂的代价

传统做法中，应用要么用 Elasticsearch 做关键词匹配，要么单独部署一套向量数据库（如 Milvus、Qdrant）做语义检索。这带来两个问题：一是多一套分布式系统的运维成本，数据需要双写、双同步；二是业务中大量非结构化数据（用户会话、商品元数据、权限标记）仍然存在 Redis 里，向量检索与业务数据物理隔离，跨系统 join 变得困难。当一个推荐请求同时需要读用户画像、查相似商品、记录曝光日志时，链路会被拉得很长。

Redis 向量检索的解法是把 FT.CREATE、FT.SEARCH 这些搜索命令直接放进 Redis 内核。一份数据写入后，既能用 HGET 按 key 读取，也能通过向量索引做语义召回，还能用 FT.SEARCH 做全文过滤——三个能力共享同一份内存数据，不需要数据搬运。Redis 8.0 起连模块都不用装，二进制包自带搜索能力，这对已经部署 Redis 的团队是近乎零成本的升级。

与 FAISS 那种嵌入进程的算法库相比，Redis 是完整的数据库形态：有持久化、主从复制、集群分片和权限控制；与 Pinecone 这类全托管服务相比，Redis 可以自托管，数据不出内网。它的定位不是“最强检索性能”，而是“让已有 Redis 基础设施直接长出向量能力”。

安装与环境配置：3 步就绪

步骤一·安装：推荐用 Docker 启动 Redis Stack 8.0 镜像。该镜像内置 Search 命令族，同时附带 RedisJSON 等模块，满足混合检索所需的 JSON 索引。生产环境也可以下载官方二进制包或通过 apt/yum 安装 Redis 8.0。

步骤二·配置：默认监听 6379 端口。若需要 RedisInsight 可视化界面，改用 redis/redis-stack 镜像并暴露 8001 端口，在浏览器打开 http://localhost:8001 即可在 Workbench 中执行搜索命令。

步骤三·验证：执行 FT._LIST 命令，能正常返回（空数组表示暂无索引）即说明搜索功能可用。

# 使用 Redis Stack 8.0 镜像（含内置 Search 与 JSON 模块）docker run -d --name redis8 -p 6379:6379 redis/redis-stack-server:8.0 # 验证docker exec -it redis8 redis-cli -p 6379 FT._LIST # 原生安装方式（Ubuntu 22.04+）curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpgecho "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.listsudo apt-get update && sudo apt-get install -y redis-stack-server

快速上手：10 分钟跑通建索引与 KNN 查询

最小可用流程是“建索引 → 写入向量 → 执行 KNN 查询”。由于向量是二进制数据，直接用 redis-cli 手动输入很困难，实际开发中用 Python 客户端（redis-py）操作。按以下步骤执行：

1. 安装依赖：pip install redis numpy；

2. 运行上方 Docker 容器，确保 6379 端口可访问；

3. 执行下面的 Python 脚本，它会创建名为 doc_idx 的索引（前缀 doc:，包含一个文本字段和一个 3 维 HNSW 向量字段），写入三条带向量的文档，最后用 [0.9, 0.1, 0.0] 作为查询向量召回最相似的 2 条数据；

4. 观察输出：score 越小表示距离越近，redis 向量检索入门 应排在最前。

进阶技巧：查询时通过 dialect(4) 启用最新查询语法；需要精确召回时把索引算法改为 FLAT1，需要更高召回率时调大 EF_RUNTIME 参数。

import numpy as npimport redisfrom redis.commands.search.field import TextField, VectorFieldfrom redis.commands.search.indexDefinition import IndexDefinition, IndexTypefrom redis.commands.search.query import Query client = redis.Redis(host="localhost", port=6379) # 1. 建索引（Redis 8 使用 VSS 字段类型；若连接 Redis Stack 7.x 请改回 HNSW）schema = [    TextField("content"),    VectorField("embedding", "HNSW1", {        "TYPE": "FLOAT32", "DIM": 3, "DISTANCE_METRIC": "COSINE",    }),]client.ft("doc_idx").create_index(    schema, definition=IndexDefinition(prefix=["doc:"], index_type=IndexType.HASH)) # 2. 写入数据docs = [    ("redis 向量检索入门", [1.0, 0.0, 0.0]),    ("RAG 管道搭建指南", [0.0, 1.0, 0.0]),    ("HNSW 索引参数调优", [0.0, 0.0, 1.0]),]for i, (text, vec) in enumerate(docs):    client.hset(f"doc:{i+1}", mapping={        "content": text,        "embedding": np.array(vec, dtype=np.float32).tobytes(),    }) # 3. KNN 查询q = Query("*=>[KNN 2 @embedding $vec AS score]") \    .sort_by("score") \    .return_fields("content", "score") \    .dialect(4)res = client.ft("doc_idx").search(    q, query_params={"vec": np.array([0.9, 0.1, 0.0], dtype=np.float32).tobytes()})for d in res.docs:    print(d.content, round(float(d.score), 4))

核心能力详解：4 大支柱

支柱一·双索引算法：FLAT1 与 HNSW1。FLAT1 是暴力扫描，逐个计算查询向量与库内所有向量的距离，结果完全精确，但时间复杂度 O(N)，适合百万级以下或对延迟不敏感的场景。HNSW1 基于分层小世界图（HNSW 是一种近似最近邻算法，通过多层级图结构在检索时快速缩小候选范围），召回速度快一到两个数量级，但结果是近似的，通过 M（每层最大连接数）、EF_CONSTRUCTION（建索引时探索范围）和 EF_RUNTIME（查询时探索范围）三个参数在速度与召回率之间权衡。Redis 8.0 的 VSS 字段类型同时支持这两种算法。

支柱二·三种距离度量。L2（欧氏距离）适合向量各维度尺度一致的场景，数值越小越相似；IP（内积）通常配合归一化向量使用，等价于余弦相似度但计算更快；COSINE（余弦相似度）关注方向而非模长，是文本 embedding 最常用的度量。距离度量在建索引时指定，之后无法修改，选型前应先确认 embedding 模型的输出特性。

支柱三·KNN 与混合查询。核心语法是 *=>[KNN k @embedding $vec AS score]，其中 k 是召回数量，$vec 是查询向量。它不只是一个检索操作符，还能与全文过滤组合成混合查询，例如 (@content:(redis))=>[KNN 5 @embedding $vec AS score] 表示“先过滤出内容包含 redis 的文档，再在其中做向量召回”。结果可以 SORTBY score ASC 按距离排序。

支柱四·AI 生态集成。官方提供 RedisVL 库封装了向量索引生命周期管理；LangChain 与 LlamaIndex 的 Redis vector store 直接基于这套 FT 命令实现。向量库、对话缓存、会话状态共用一个 Redis 实例，使 RAG 应用的组件从三个降为一个。

生产部署与监控：从上线到运维

部署方式一：Docker / Kubernetes 自建。单实例适合开发验证；生产环境建议以 Redis Cluster 模式部署，数据按哈希槽散列到多个分片，向量索引也随之分布到对应分片，查询由客户端或代理层聚合。用 StatefulSet 管理有状态节点，配合 redis.conf 开启 appendonly yes 做 AOF 持久化，防止数据丢失。

部署方式二：Redis Cloud / Redis Enterprise。Redis Cloud 提供免费 30MB 实例用于测试，生产版按吞吐量计费，由平台负责分片、主从切换和备份。Redis Enterprise 适合部署在自有机房，提供多活和跨地域复制能力，索引数据自动跟随分片分布，运维成本远低于自建 Cluster。

可观测性：FT.INFO <index> 返回索引内存占用、文档数量、索引构建状态等关键指标；INFO memory 监控整体内存水位；SLOWLOG GET 定位慢查询。接入 Prometheus 时用 redis_exporter 暴露指标，重点告警项包括索引内存超过节点内存 50%、HNSW 查询耗时超过 100ms、主从复制延迟超过 1s。

<p class=“para-label“>避坑清单：</p><ul class=”dash-list”><li>Redis 7.x 社区版默认没有搜索功能：直接 docker run redis:7 后执行 FT.CREATE 会报 unknown command，必须改用 redis-stack 镜像或手动加载 redi-search.so；Redis 8 才内置。</li><li>二进制向量无法用 redis-cli 直接输入：HSET 的 embedding 字段是浮点数的字节串，在 redis-cli 中手敲必然失真，务必用 redis-py 等客户端写入。</li><li>维度不匹配直接拒写：FT.CREATE 声明 DIM=3 后写入 4 维向量会报错，且不同 embedding 模型输出的维度往往不同，切换模型后必须重建索引。</li></ul>

版本迭代

Redis 的向量能力经历了“模块引入 → Stack 集成 → 内核内置”三个阶段。2022 年 RediSearch 2.4 首次引入向量索引，需独立加载模块；2023-2024 年随 Redis Stack 7.2/7.4 分发并持续优化混合查询；2025 年 5 月 Redis 8.0 将搜索整体移入内核，新增 VSS 字段类型，向量检索成为开箱即用的核心能力。

AI 应用场景

常见误区

面试题

参考来源

• webpageRedis University 官方课程含 Vector Search 免费课程与认证