Redis 向量检索的过滤查询：Tag 与 Numeric 字段过滤坑点-编程实验室

Redis 向量检索的过滤查询：Tag 与 Numeric 字段过滤坑点

在真实的企业级 RAG 应用中，纯粹的“全局最近邻向量搜索”其实很少出现。绝大多数线上检索请求都带着明确的业务标量过滤条件：

例如：只检索tenant_id == 'dept_dev'租户下的知识；
例如：只检索created_at >= 1700000000且is_public == true的公开文档；
例如：只在category IN ['python', 'database']分类中寻找答案。

Redis（RediSearch 模块）支持在FT.SEARCH中将TagField（标签字段）、NumericField（数值字段）与VectorField（向量字段）组合成混合查询。然而，如果不了解 Redis 内部的前置过滤（Pre-filtering）与后置过滤（Post-filtering）机制，线上查询极易踩中性能暴跌或返回结果为空的深坑。

Redis 向量过滤的执行模式：Dialect 2 与 Batched KNN

在旧版 RediSearch（Dialect 1）中，向量检索采用的是朴素的后置过滤：先在整个向量索引中找出 Top-K 个最近邻，然后再用标量条件去过滤。如果 Top-K 里的文档全部属于其他租户，最终返回给用户的有效结果就是 0 条！

从RediSearch 2.6+（强制使用 DIALECT 2 或更高）开始，Redis 引入了Batched KNN（分批探查前置过滤）机制：

向量引擎首先通过标量索引（Tag/Numeric 的倒排列表或数字范围树）拿到符合过滤条件的文档 ID 位图（Bitmap）；
在 HNSW 图或 FLAT 数组遍历时，只有命中位图的节点才会被计入候选队列并计算向量距离；
如果当前探查批次未填满 Top-K，引擎会自动扩大图搜索范围，直到找满所需的有效候选或遍历耗尽。

这一机制彻底解决了“返回空结果”的问题，但在使用中必须注意 Schema 设计与语法陷阱。

生产环境五大核心避坑点

1. TagField 默认的分词与特殊字符转义

TagField专门用来存储租户 ID、UUID、状态枚举或标签。

默认行为：Redis 会默认用逗号,分割 Tag 字符串中的值，并且会自动将大写字符转为小写（除非显式声明CASESENSITIVE）。
避坑点：如果你的租户 ID 或文档 ID 包含中划线-、下划线_或冒号:（如tenant-user:1001），在查询时如果不转义，Redis 会把中划线误认为“减法/非操作符”！
- 错误写法：@tenant_id:{tenant-user:1001}（会解析失败或报错语法错误）；
- 正确写法：必须使用双反斜杠转义特殊字符：@tenant_id:{tenant\-user\:1001}。

2. NumericField 的开闭区间语法

NumericField用来存储时间戳、价格、阅读量等连续数值。

闭区间：@created_at:[1700000000 1710000000]（包含两端）；
开区间：使用(前缀表示不包含端点，如@created_at:[(1700000000 +inf]；
负无穷与正无穷：使用-inf与+inf。

3. 混合查询语句中的 KNN 语法与 Dialect 2

将标量条件与向量 KNN 结合时，语法格式有严格的拓扑顺序：

FT.SEARCH idx:kb "(@tenant_id:{finance} @created_at:[1700000000 +inf])=>[KNN 10 @vec $B AS score]" PARAMS 2 B "\x01\x02..." DIALECT 2

关键细节：

必须将所有标量过滤条件放在=>箭头的左侧括号内；
必须显式在命令末尾声明DIALECT 2（Python 客户端中通过.dialect(2)传递）。如果不加DIALECT 2，查询会退化回旧版语法，导致语法报错或过滤失效。

Python 生产级安全封装代码

import redis from redis.commands.search.query import Query import numpy as np import re def escape_tag_value(value: str) -> str: """转义 Redis Tag 查询中的所有保留特殊字符""" return re.sub(r'([,.<>{}\[\]"\'\:;!@#$%^&*()\-+=~| ])', r'\\\1', str(value)) def query_with_hybrid_filter( redis_client: redis.Redis, index_name: str, query_vec: np.ndarray, tenant_id: str, min_timestamp: int, categories: list, top_k: int = 5 ): # 1. 安全转义租户 ID 与分类标签 safe_tenant = escape_tag_value(tenant_id) safe_cats = "|".join([escape_tag_value(cat) for cat in categories]) # 2. 构造组合标量过滤表达式 # 逻辑：tenant_id 匹配 AND created_at >= min_timestamp AND category IN (cats) filter_expr = f"(@tenant_id:{{{safe_tenant}}} @created_at:[{min_timestamp} +inf] @category:{{{safe_cats}}})" # 3. 构造 KNN 混合查询 query_str = f"{filter_expr}=>[KNN {top_k} @embedding $vec_param AS score]" q = ( Query(query_str) .sort_by("score") .return_fields("id", "score", "title", "tenant_id", "created_at") .paging(0, top_k) .dialect(2) ) raw_bytes = query_vec.astype(np.float32).tobytes() results = redis_client.ft(index_name).search(q, query_params={"vec_param": raw_bytes}) return results.docs