Redis向量检索叠加结构化过滤

做商品、知识库或多租户内容检索时，单纯按向量相似度取 Top-K 往往不够：用户还会限定分类、租户、价格区间或发布时间。Redis 的 Query Engine 可以把这些结构化条件放在 KNN 查询左侧，先缩小候选集合，再在满足条件的文档里做向量检索。这样得到的不是“全库最相似”，而是“符合业务约束的最相似”。

核心写法是 结构化过滤=>[KNN ...]：TAG、NUMERIC、TEXT 等字段必须和 VECTOR 字段一起进入索引，查询时使用 DIALECT 2，再根据候选集大小决定是否显式设置混合过滤策略。

官方地址：https://redis.io/docs/latest/develop/ai/search-and-query/vectors/

下面用一个商品目录作为例子。代码中的向量字节只是占位符，文章重点是索引边界、过滤语法和策略选择，不把示例输出冒充成真实运行结果。

先把结构化字段建进同一个索引

过滤能否参与 KNN，首先取决于索引 schema。商品文档至少需要一个向量字段，再按业务筛选条件加入 TAG、NUMERIC 或 TEXT 字段。TAG 适合分类和租户这类精确匹配，NUMERIC 适合价格、时间戳等范围，TEXT 适合关键词检索。

# 创建 Hash 索引：分类做精确过滤，价格做范围过滤，embedding 存放向量
redis-cli FT.CREATE idx:products ON HASH PREFIX 1 product: \
  SCHEMA category TAG tenant TAG price NUMERIC title TEXT \
  embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 3 DISTANCE_METRIC COSINE

这里的 DIM 必须和写入向量的维度一致，TYPE 和距离度量也要与向量生成及比较方式匹配。不要只建立 VECTOR 字段再在应用层过滤，否则 Redis 已经返回了不符合租户或分类约束的候选，召回数量和排序都会失去业务意义。

用过滤表达式包住 KNN 子句

查询时，把结构化条件写在 => 左侧，把 KNN 写在右侧。下面的条件要求分类是 Audio、租户是 tenant-a、价格在 10 到 100 之间，然后只在这些候选里取 5 个最近邻。

# VECTOR_BYTES 应替换成与索引 DIM、TYPE 匹配的二进制向量
VECTOR_BYTES=''

# 过滤表达式先限定候选，再按 distance 升序取最近的 5 条
redis-cli FT.SEARCH idx:products \
  '(@category:{Audio} @tenant:{tenant-a} @price:[10 100])=>[KNN 5 @embedding $query_vec AS distance]' \
  PARAMS 2 query_vec "$VECTOR_BYTES" \
  SORTBY distance ASC DIALECT 2

TAG 的大括号表示精确匹配，NUMERIC 的方括号表示数值范围；过滤条件还可以包含文本或多个条件组合。AS distance 给距离字段起一个稳定名字，配合 SORTBY distance ASC 让结果顺序明确。向量检索语法需要 DIALECT 2，不要省略。

按候选集大小选择混合过滤策略

默认情况下，Redis 会根据查询和索引情况自动选择过滤方式。实际做架构取舍时，可以先问一个问题：过滤后还剩多少候选？如果租户或分类条件把候选压缩到很小的集合，ADHOC_BF 会直接检查候选的向量距离，逻辑简单；如果过滤结果仍然很大，BATCHES 会分批从向量索引取近邻，再与过滤条件交集，通常更适合大候选集。

# 候选集较小时，可显式使用按需检查的策略
redis-cli FT.SEARCH idx:products \
  '(@category:{Audio})=>[KNN 5 @embedding $query_vec AS distance HYBRID_POLICY ADHOC_BF]' \
  PARAMS 2 query_vec "$VECTOR_BYTES" SORTBY distance ASC DIALECT 2

# 候选集较大时，按批次取近邻；BATCH_SIZE 是需要结合负载调节的参数
redis-cli FT.SEARCH idx:products \
  '(@category:{Audio})=>[KNN 5 @embedding $query_vec AS distance HYBRID_POLICY BATCHES BATCH_SIZE $batch_size]' \
  PARAMS 4 query_vec "$VECTOR_BYTES" batch_size 50 \
  SORTBY distance ASC DIALECT 2

不要把 ADHOC_BF 或 BATCHES 当成固定的性能答案：候选密度、向量索引类型、返回数量和内存访问模式都会影响结果。先保留默认自动策略，再对过滤后候选规模稳定的业务做有针对性的压测；文章中的策略示例只表达选择边界，不代表某个环境的延迟承诺。

召回数量和集群代价要一起看

过滤条件越窄，越容易出现“相似度很高但结果不足”的现象。这不是 KNN 失效，而是满足业务条件的候选本来就少。可以从索引字段是否正确、TAG 值是否一致、NUMERIC 范围是否写对、查询向量维度是否匹配四个方向排查。

在 Redis Cluster 中，还要关注每个分片为 Top-K 提供多少候选。官方查询参数支持 SHARD_K_RATIO，它在召回质量和跨分片成本之间做取舍；比例过低可能减少候选，比例过高会增加查询开销。生产配置应结合分片数量、过滤分布和可接受的召回损失决定。

常见问题

能不能先做全库 KNN，再在应用层过滤？ 可以作为临时原型，但会浪费召回名额；正式查询应把条件写入 Redis 的过滤表达式。

TAG 和 NUMERIC 能同时使用吗？ 可以，只要两类字段都在同一个索引 schema 中，过滤表达式就能组合使用。

为什么过滤后结果数量少？ 先确认过滤字段的索引类型和值格式，再检查候选规模、向量维度和 Top-K 设置，不要直接把 KNN 数量无限调大。