FT.HYBRID
结合文本搜索和向量相似度搜索进行混合搜索
语法
FT.HYBRID index SEARCH query [SCORER scorer] [YIELD SCORE AS name] VSIM vector field $vector param [KNN count K k [EF RUNTIME ef runtime]] [SHARD K RATIO shard k ratio]] [RANGE count RADIUS radius [EPSILON epsilon]] [YIELD SCORE AS name] [FILTER] count filter-expression [POLICY [ADHOC/BATCHES] BATCH SIZE batch-size-value] [COMBINE RRF count [CONSTANT constant] [WINDOW window] [YIELD SCORE AS name]] [COMBINE LINEAR count [[ALPHA alpha] [BETA beta]] [WINDOW window] [YIELD SCORE AS name]] [LIMIT offset num] [SORTBY count sortby [ASC | DESC]] [NOSORT] [LOAD count field [field ...]] [LOAD *] [GROUPBY nargs property [property ...] [GROUPBY nargs property [property ...] [REDUCE function nargs arg [arg ...] [AS name] [REDUCE function nargs arg [arg ...] [AS name] ...]] ...]] [APPLY expression AS name [APPLY expression AS name ...]] [FILTER filter] PARAMS nargs vector param vector blob [name value ...] [TIMEOUT timeout]
引入版本：8.4.0
复杂度摘要：O(N+M)
通过可配置的融合方法，执行将文本搜索和向量相似度相结合的混合搜索。
FT.HYBRID 提供了一个统一的接口，用于在单个查询中结合传统的全文搜索和基于向量的搜索。它支持混合检索用例，例如语义搜索、检索增强生成 (RAG) 和智能代理应用程序。该命令建立在熟悉的 FT.SEARCH 和 FT.AGGREGATE 查询语法的基础上，简化了混合查询构造，同时通过聚合功能实现灵活的后处理。
[!NOTE] 此命令将仅返回用户具有读取访问权限的文档 ID (
keyid) 和分数。要检索整个文档，请使用带有LOAD *或LOAD <count> field...的投影。
必需参数
index
是索引的名称。您必须首先使用 FT.CREATE 创建索引。
SEARCH "search-expression"
定义混合查询的文本搜索组件。搜索表达式使用与 FT.SEARCH 查询相同的语法，支持所有文本搜索功能，包括特定于字段的搜索、布尔运算和短语匹配。
VSIM @vector_field "vector-data"
定义混合查询的向量相似度组件。 @vector_field 指定要搜索索引中的哪个向量字段（例如，$vector），"vector-data" 包含用于相似性比较的查询向量（例如，PARAMS 2 $vector <vector-blob>）。
可选参数
SCORER algorithm params...
指定文本搜索组件的评分算法和参数。支持别名并遵循参数计数约定，其中第一个数字表示后续参数的总数。
示例：SCORER 4 BM25 1.2 0.75 使用 BM25 算法，参数为 1.2 和 0.75。
YIELD_SCORE_AS alias-search-score
为搜索分数分配一个别名，以便在后处理操作中使用，例如 APPLY 或 SORTBY。
KNN count K top-k [EF_RUNTIME ef-value] [SHARD_K_RATIO shard-k-ratio] [YIELD_SCORE_AS name]
配置K近邻搜索向量相似度。 count 参数表示以下参数的数量。 K 指定要查找的最近邻居的数量。 EF_RUNTIME 控制搜索精度与速度的权衡。 SHARD_K_RATIO 控制每个分片相对于集群设置中请求的 top_k 检索的结果数量。 YIELD_SCORE_AS 为分数值分配一个别名。有关 SHARD_K_RATIO 的更多信息，请参阅 矢量搜索 文档。
RANGE count RADIUS radius-value [EPSILON epsilon-value] [YIELD_SCORE_AS name]
配置指定半径内基于范围的矢量搜索。 count 参数表示以下参数的数量。 RADIUS 定义匹配的最大距离。 EPSILON 提供额外的精确控制。
FILTER "filter-expression"
对矢量搜索结果应用预过滤，或在 COMBINE 步骤之后用作后处理时应用后过滤。此过滤器会影响哪些文档被视为矢量相似性，但不会影响评分。相反，SEARCH 组件会影响过滤和评分。 FILTER语法使用与FT.SEARCH语法相同的搜索表达式，支持所有文本搜索功能，包括特定于字段的搜索、布尔运算和短语匹配
POLICY [ADHOC_BF|BATCHES] [BATCH_SIZE batch-size-value]
控制向量查询的预过滤策略。 ADHOC_BF 按需处理过滤器，BATCHES 以可配置的批量大小处理。请参阅 预过滤策略 了解更多信息。
COMBINE method params...
指定如何融合文本搜索和向量相似度结果。支持多种融合方式：
- RRF（倒数秩融合）：默认方法。参数包括
WINDOW（默认20）和CONSTANT（默认60）。 - LINEAR：与
ALPHA和BETA权重的线性组合。 - FUNCTION：自定义融合功能（未来支持）。
示例：COMBINE RRF 4 WINDOW 40 CONSTANT 1.5
YIELD_SCORE_AS alias-combined-score
为组合融合分数分配一个别名，以便在后处理操作中使用。
LOAD count field...
指定结果中返回哪些字段。 count 参数指示后面的字段数。
示例：LOAD 3 @category @brand @price
GROUPBY count field... REDUCE function...
按指定字段对结果进行分组并应用归约函数。遵循参数计数约定。 count 参数指示后面的字段数。
示例：GROUPBY 4 category brand REDUCE 2 COUNT 0
APPLY expression AS field
应用转换来创建新字段。可以参考别名分数和距离。
示例：APPLY "@vector_distance+@score" AS final_score
SORTBY count field [ASC|DESC]
将最终结果按指定字段升序或降序排序。 count 参数指示后面的字段数。
LIMIT offset num
限制最终结果。未指定时，默认限制为 10。 offset 参数是零索引的。
PARAMS count key value...
定义查询的参数替换。可以使用 $parameter_name 在搜索表达式中引用参数。
示例：PARAMS 4 min_price 50 max_price 200
EXPLAINSCORE
返回每个结果的综合得分如何计算的解释。在 Redis 8.10 及更高版本中可用。
每个结果都有一个 score 字段，其中包含一个二元素数组：组合分数，后跟一个嵌套的解释树。您不需要 WITHSCORES。该树显示：
- 最终得分公式及其参数的融合方法：
RRF与window和constant，或LINEAR与alpha、beta和window。 - 文本分支：记分员名称，例如
BM25STD，以及记分员自己的细分。使用RRF，它显示文本排名。使用LINEAR，它显示文本贡献和标准化文本得分。 - 向量分支：
KNN或RANGE及其半径和 epsilon。使用RRF，它显示向量排名。使用LINEAR，它显示向量贡献和归一化向量得分。RANGE还显示文档是否在半径内匹配。
与文档不匹配的分支显示<no match>。
EXPLAINSCORE 不能与GROUPBY 组合。该命令返回错误 EXPLAINSCORE is not supported with GROUPBY。
TIMEOUT timeout
设置查询执行的运行时超时（以毫秒为单位）。当查询超时时，应用 search-on-timeout 策略。使用 RETURN 或 RETURN_STRICT，该命令返回迄今为止累积的结果，并在 warnings 中报告超时。对于 FAIL，它会返回错误。
默认值和行为
FT.HYBRID 提供合理的默认值以简化入门：
- 查询计数：2（需要1个SEARCH和1个VSIM组件）
- 默认限制: 10 个结果
- 默认记分器：BM25STD，用于文本搜索
- 默认KNN K：10个邻居
- 默认 RRF 窗口: 20
- 默认 RRF 常量: 60
- 默认EF_RUNTIME: 10（作为向量 KNN 默认）
- 默认EPSILON: 0.01（作为向量 RANGE 默认）
参数计数约定
所有多参数选项均使用包含以下所有标记的计数前缀：
KNN 4 K 10 EF_RUNTIME 100- 2个键值对PARAMS 4 min_price 50 max_price 200- 2个键值对COMBINE RRF 4 WINDOW 40 CONSTANT 1.5- 具有 2 个键值对的 RRF 方法
唯一的例外是 AS 的别名使用，不计算在内： - APPLY "@vector_distance+@score" AS final_score - LOAD 3 @category AS cat @brand AS brd @price AS prc
保留字段
以下字段保留供内部使用：
@__key- 保留用于在需要时加载键 ID@__score- 保留用于组合分数（可以使用别名）@vector_distance- 产生向量距离（可以是别名）@__combined_score- 来自 COMBINE 步骤的融合分数
示例
Basic hybrid search
将“laptop”的文本搜索与向量相似度相结合，执行简单的混合搜索：
127.0.0.1:6379> FT.HYBRID products-idx SEARCH“笔记本电脑”VSIM @description_vector $query_vec KNN 2 K 10 PARAMS 2 query_vec
Hybrid search with custom scoring and fusion
搜索具有自定义 BM25 参数和 RRF 融合的电子产品：
127.0.0.1:6379> FT.HYBRID products-idx SEARCH "@category: electronics" SCORER 4 BM25 1.5 0.8 YIELD_SCORE_AS text_score VSIM @features_vector $query_vec KNN 4 K 20 EF_RUNTIME 200 YIELD_SCORE_AS vector_score 组合 RRF 4 WINDOW 50 CONSTANT 80 YIELD_SCORE_AS Hybrid_score SORTBY 2 Hybrid_Score DESC LIMIT 0 20 PARAMS 2 query_vec
Hybrid search with pre-filtering
矢量预过滤和后处理搜索：
127.0.0.1:6379> FT.HYBRID products-idx 搜索“智能手机”VSIM @image_vector $query_vec KNN 2 K 15 过滤器“@price:[100 500]”组合线性 4 ALPHA 0.7 BETA 0.3 负载 4 @title @price @category @ rating 应用“@price * 0.9" AS 折扣价格 SORTBY 2 评级 DESC PARAMS 2 query_vec
Hybrid search with parameters
使用参数替换进行动态查询：
127.0.0.1:6379> FT.HYBRID products-idx SEARCH "@brand:$brand_name" VSIM @content_vector $query_vector RANGE 4 RADIUS 0.8 EPSILON 0.1 FILTER "@availability:$stock_status" PARAMS 6 Brand_name "Apple" query_vector
Explain hybrid scores
返回最高结果及其 RRF 分数的解释。该文档在文本和矢量分支中均排名第一：
127.0.0.1:6379> FT.HYBRID products-idx SEARCH“鞋子”VSIM @embedding $query_vec KNN 2 K 3 EXPLAINSCORE LIMIT 0 1 PARAMS 2 query_vec
复杂性
FT.HYBRID 复杂性取决于文本搜索和向量相似性组件： - 文本搜索：简单术语搜索的 O(n)，其中 n 是匹配文档的数量。在使用 INTERSECT 或 UNION 的多术语查询中，或者使用模糊或前缀匹配时，复杂性与跨所有参与术语扫描的条目总数成比例增加。 - 向量搜索：使用 HNSW 索引的 KNN 为 O(log n)，范围查询为 O(n) - 融合：O(k)，其中 k 是要组合的结果数量 - 总体复杂性通常由更昂贵的组件主导
Redis Software 与 Redis Cloud 兼容性
| Redis 软件 |
Redis软件 Flex |
Redis Cloud |
说明 |
|---|---|---|---|
| ✅ 标准 |
❌ 不支持 | ✅ 标准 |
返回值
RESP2
以下之一： * 数组，第一个元素是结果总数，后跟文档 ID 及其字段值对，如 数组。 * 简单错误回复 在这些情况下：没有这样的索引，查询中有语法错误。
RESP3
以下之一： * 地图 包含以下字段： - total_results：整数 - 结果总数 - execution_time：包含混合查询执行时间的 双 - warnings：警告消息 数组 指示由于索引错误或 MAXPREFIXEXPANSIONS、内存不足情况以及达到 TIMEOUT 导致的部分结果 - results： 数组 或 地图 包含文档信息 * 简单错误回复 在这些情况下：没有这样的索引，查询中有语法错误。
参见
FT.CREATE | FT.SEARCH | FT.AGGREGATE
相关主题
资料来源：Redis 官方 FT.HYBRID 文档；中文内容参考 Redis 文档许可。