redis-search

Redis 搜索

Redis 搜索的统一指南，涵盖词法、数值、地理、JSON 路径和向量查询。向量字段与 TEXT/TAG/NUMERIC 字段一样，属于同一套 FT.CREATE 机制；FT.HYBRID 则通过一条命令融合词法和向量排序，因此本技能将它们一并介绍。

适用场景

• 创建、修改或检查 Redis 搜索索引（FT.CREATE、FT.ALTER）。
• 编写或优化 FT.SEARCH、FT.AGGREGATE 或 FT.HYBRID 查询。
• 在 TEXT、TAG、NUMERIC、GEO、GEOSHAPE、VECTOR 或 JSON 路径字段之间进行选择。
• 定义 VECTOR 字段、选择 HNSW 或 FLAT、调整 HNSW 参数。
• 构建检索增强生成（RAG）流水线。
• 在不停机的情况下推出新的索引架构。
• 使用 FT.EXPLAIN、FT.PROFILE、FT.INFO 排查结果为空、查询缓慢或分词问题。

1. 选择合适的命令

有 3 个查询命令。选择符合需求的最精简命令。

命令	适用场景	思维模型	Redis 最低版本
FT.SEARCH	文档检索，可排序或排名。最佳默认选择。	直接返回匹配的文档。	2.0（模块）/ 8.0（内置）
FT.AGGREGATE	分面、计算字段、自定义输出格式、分析。	声明式流水线：LOAD、APPLY、GROUPBY、REDUCE、SORTBY。	2.0 / 8.0
FT.HYBRID	融合词法（BM25）与向量相似度，并支持配置融合方式。	包含显式 SEARCH + VSIM 分支和 COMBINE 融合阶段的流水线。	8.4.0

# FT.SEARCH — most common
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]" LIMIT 0 20 RETURN 3 name price category

# FT.AGGREGATE — top categories by avg price
FT.AGGREGATE idx:products "*" GROUPBY 1 @category REDUCE AVG 1 @price AS avg_price SORTBY 2 @avg_price DESC

# FT.HYBRID (Redis ≥ 8.4) — lexical + vector fusion
FT.HYBRID idx:docs
  SEARCH "@title:transformers" SCORER BM25 YIELD_SCORE_AS lexscore
  VSIM embedding $vec KNN count 1 K 50 YIELD_SCORE_AS vecscore
  COMBINE RRF 2 CONSTANT 60
  PARAMS 2 vec "..."
  DIALECT 2

对于 Redis < 8.4，可通过 FT.SEARCH 预过滤 + =>[KNN ...] 近似实现词法与向量融合。请参阅 references/command-selection.md 和 references/hybrid-search.md。

2. 架构基础 — FT.CREATE

FT.CREATE 会为匹配 PREFIX 的 Hash 或 JSON 文档建立索引。务必设置 PREFIX。使用 DIALECT 2（自 Redis 8 起为默认值；向量查询必需）。

FT.CREATE idx:products ON HASH PREFIX 1 product:
    SCHEMA
        name TEXT WEIGHT 2.0
        category TAG SORTABLE
        price NUMERIC SORTABLE
        location GEO
        embedding VECTOR HNSW 6
            TYPE FLOAT32
            DIM 1536
            DISTANCE_METRIC COSINE

选择能满足访问模式的最精简字段类型：

字段类型	适用场景	备注
TEXT	全文搜索	会进行分词和词干提取；不适用于精确匹配
TAG	精确匹配/过滤	添加 SORTABLE UNF 可让标签查询更快
NUMERIC	范围查询、排序	价格、计数、时间戳
GEO	经纬度点	商店、用户
GEOSHAPE	多边形/区域查询	配送区域、地区
VECTOR	相似度搜索	HNSW 或 FLAT；参见 §4
JSON $.path AS alias	嵌套 JSON 字段	使用 ON JSON；参见 references/json-indexing.md

常见错误是因为类别或状态字段“是字符串”，就使用 TEXT；对于精确匹配过滤，TAG 的速度大约快 10 倍。

请参阅 references/index-creation.md、references/field-types.md、references/dialect.md、references/ft-create-options.md、references/json-indexing.md。

3. 常见查询

使用过滤条件缩小范围；只返回所需内容。

# Tag filter + numeric range, sorted by price
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
    SORTBY price ASC
    LIMIT 0 20
    RETURN 3 name price category

# Text + tag filter
FT.SEARCH idx:products "wireless headphones @category:{audio}"

# Negation and OR
FT.SEARCH idx:products "@category:{audio} -@brand:{generic} (@price:[0 100] | @on_sale:{true})"

值得记住的运算符：空格 = AND，| = OR，- = NOT，~ = 可选（提高评分），=>{$weight: N} = 加权提升。TAG 值中的连字符和特殊字符需转义（@sku:{ABC\\-123}）。如需了解 DSL 语法，请参阅 references/query-syntax.md 和 references/search-syntax-primitives.md。

如需了解分词相关注意事项（词干提取、停用词、语言），请参阅 references/text-tokenization.md。如需调整结果格式（SORTBY、RETURN、HIGHLIGHT、SUMMARIZE、NOCONTENT），请参阅 references/result-shaping.md。如需了解性能优化手段（预过滤、SORTABLE 字段、精简 RETURN、FT.PROFILE），请参阅 references/query-optimization.md。

4. 向量基础

以下三个向量设置必须与嵌入模型完全匹配：

• DIM — 输出维度（例如，OpenAI text-embedding-3-small 为 1536）。不匹配会导致结果悄然变得毫无意义。
• DISTANCE_METRIC — 对于归一化文本嵌入，使用 COSINE（常见情况）；对于未归一化的内积，使用 IP；对于原始欧几里得距离，使用 L2。
• TYPE — 通常为 FLOAT32。只有在内存是主要限制时，才使用 FLOAT16 或量化变体。

# Index
FT.CREATE idx:docs ON HASH PREFIX 1 doc:
    SCHEMA
        content TEXT
        embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE

# Pure KNN query (top 5 by cosine similarity)
FT.SEARCH idx:docs "*=>[KNN 5 @embedding $vec AS score]"
    PARAMS 2 vec "..."
    SORTBY score
    DIALECT 2

算法	速度	准确度	内存	适用场景
HNSW	快（近似）	召回率约为 95% 以上（可调）	较高	生产环境：超过 10k 个向量、对延迟敏感
FLAT	慢（精确）	100%	较低	小型语料库（少于 10k 个向量）、需要精确匹配

HNSW 调优参数：M（16–64，每个节点的连接数）、EF_CONSTRUCTION（100–500，构建质量）、EF_RUNTIME（查询时的候选列表）。

参见 references/vector-query.md、references/algorithm-choice.md。

5. 混合检索

两种截然不同的模式都被称为“混合”。请根据意图选择。

先过滤再进行向量搜索（任何 Redis 版本）——应用属性过滤器，让引擎在进行向量比较之前缩小搜索范围。

FT.SEARCH idx:docs "(@category:{tech} @date:[2024 +inf])=>[KNN 10 @embedding $vec AS score]"
    PARAMS 2 vec "..."
    SORTBY score
    DIALECT 2

词法 + 向量融合（Redis ≥ 8.4）——结合 BM25 文本评分与向量相似度，并使用 RRF 或 LINEAR 进行融合。使用 FT.HYBRID（参见 §1）。

不要先获取范围很广且未经筛选的结果，再在客户端过滤——这样更慢、准确度也更低。参见 references/hybrid-search.md。

6. 聚合与结果整形

FT.AGGREGATE 是用于声明式结果整形的命令。通过多个阶段构建处理管道。

# Top 5 categories by total revenue
FT.AGGREGATE idx:orders "@status:{shipped}"
    LOAD 2 @category @amount
    GROUPBY 1 @category
        REDUCE SUM 1 @amount AS revenue
    SORTBY 2 @revenue DESC
    LIMIT 0 5

常用阶段：LOAD、APPLY（计算字段）、FILTER（查询后过滤）、GROUPBY + REDUCE（SUM、COUNT、AVG、FIRST_VALUE、TOLIST）、SORTBY、LIMIT。

对于运行时间较长的结果集，使用 WITHCURSOR + FT.CURSOR READ 在服务端分页。参见 references/aggregate-pipeline.md 和 references/aggregate-cursors.md。

7. RAG 模式

标准流程：嵌入查询，对 Redis 执行向量搜索，再将 top-K 上下文传递给大模型。

实用技巧：

• 匹配度量指标与嵌入模型保持一致（对于归一化文本模型，几乎总是使用 COSINE）。
• 将长文档切分成块（通常，200–500 个 token 的文本块比对整页建立索引效果更好）。
• 批量插入，而非每条记录调用一次。
• 在向量搜索前使用属性进行预过滤（租户、时效、文档类型）——参见 §5。
• 如果准确率比召回率更重要，则在流程前段进行重排序。

参见 references/rag-pattern.md。

8. 运维

实现零停机架构变更：让应用查询始终指向一个别名，然后切换其底层索引。

FT.CREATE idx:products_v2 ON HASH PREFIX 1 product: SCHEMA ...
FT.ALIASUPDATE products idx:products_v2
# App queries are stable:
FT.SEARCH products "@category:{electronics}"

实用管理命令：FT.INFO、FT.DROPINDEX、FT._LIST、FT.ALIASADD/UPDATE/DEL。参见 references/index-management.md。

使用 FT.EXPLAIN（显示查询的解析方式）和 FT.PROFILE（显示执行统计信息）排查查询结果为空或查询缓慢的问题。参见 references/debugging.md。

9. 客户端示例

本 SKILL.md 中的内联示例采用 CLI / RESP 格式——这是每个客户端序列化使用的线协议。如需特定客户端的惯用代码片段：

• redis-py（Python，原始客户端）：references/clients/python-redis-py.md
• Jedis（Java）：references/clients/java-jedis.md
• RedisVL（Python，基于 redis-py 的更高层级 SDK）：references/clients/python-redisvl.md

其他客户端（Lettuce、node-redis、go-redis、NRedisStack、.NET）也会将相同的 CLI 格式转换为各自的形式；相关支持情况将作为后续工作跟踪。

参考资料

• Redis：搜索和查询
• Redis：向量
• Redis：查询语法
• Redis：查询方言
• Redis：RAG 快速入门
• FT.CREATE · FT.SEARCH · FT.AGGREGATE · FT.HYBRID
• RedisVL 文档