*Redis FT.HYBRID 命令

FT.HYBRID 执行混合查询，结合向量相似度搜索和文本过滤条件，在 RediSearch 中实现语义搜索 + 结构化过滤。

---

*语法

FT.HYBRID index
  query
  [PARAMS name value [name value ...]]
  [DIALECT dialect]
  [TIMEOUT ms]

---

*参数说明

参数	类型	必填	说明
index	String	是	索引名称
query	String	是	混合查询表达式（向量 + 文本条件）
PARAMS	Keyword	否	查询参数，用于传入向量 blob（如 blob 参数）
DIALECT	Integer	否	查询语法版本（推荐 2）
TIMEOUT	Integer	否	查询超时（毫秒）

---

*返回值

• Array：搜索结果数组，包含文档 ID 和字段

---

*时间复杂度

取决于向量维度和索引类型。HNSW 索引 O(log(N) * D)，FLAT 索引 O(N * D)，D 为维度。

---

*示例

*向量搜索 + 文本过滤

> FT.HYBRID idx:images "@image_vector:[VECTOR_RANGE $radius $vec] @category:{clothing}"
  PARAMS 4 radius 0.5 vec "\x00\x00\x00\x00..."
  DIALECT 2
1) (integer) 2
2) "image:100"
3) 1) "category"
   2) "clothing"
   3) "similarity"
   4) "0.42"

*语义搜索 + 标签过滤

> FT.HYBRID idx:products "@embedding:[VECTOR_RANGE 0.2 $embedding] @brand:{nike} @price:[0 200]"
  PARAMS 2 embedding "\x00\x00\x00\x00..."
  DIALECT 2

---

*常见错误

错误	原因	解决
Index not found	索引不存在	确认索引名称
Vector field not found	向量字段未定义	检查索引 schema 中的 VECTOR 字段
Invalid vector blob	向量数据格式错误	确认向量是二进制 blob 或正确编码

---

*最佳实践

• 使用 HNSW 索引算法提升向量搜索性能
• 优先使用结构化过滤（TAG、NUMERIC）减少向量搜索范围
• 向量数据通过 PARAMS 传入，避免查询字符串编码问题
• 使用 DIALECT 2 获取更现代的查询语法支持

---

*FAQ

Q1: FT.HYBRID 和 FT.SEARCH 的 KNN 查询有什么区别？ A: FT.HYBRID 专注于向量范围搜索 + 过滤；FT.SEARCH 的 KNN（K-Nearest Neighbors）用于 Top-K 相似度搜索。两者可结合使用。

Q2: 向量参数如何传入？ A: 通过 PARAMS 传入二进制 blob，或根据客户端库支持传入数组/列表。

Q3: 混合查询中过滤条件顺序重要吗？ A: RediSearch 优化器会自动选择最优执行顺序，但通常结构化过滤优先于向量计算。

Q4: 支持多向量字段搜索吗？ A: 支持，索引中可定义多个 VECTOR 字段，查询中可分别指定。