RedisVL 不仅支持基本的向量相似性搜索还提供了多种高级查询类型帮助您构建更智能、更精准的检索应用。本指南将深入讲解三种核心高级查询——TextQuery全文搜索、HybridQuery混合搜索和MultiVectorQuery多向量搜索。 前提条件在开始之前请确保您已具备以下环境安装 RedisVLpip install redisvl一个运行中的 Redis 实例推荐 Redis 8 或 Redis Cloud如需使用HybridQuery需要 Redis 8.4.0 且redis-py 7.1.0 该要使用TextQuery进行全文搜索并灵活调整评分算法利用HybridQuery和AggregateHybridQuery将文本搜索与向量搜索相结合获得“语义 关键词”的双重优势通过MultiVectorQuery跨多个向量字段如文本向量、图像向量进行联合检索配置索引级或查询级停用词优化文本搜索效果 数据准备与索引定义首先准备一组商品数据包含文本描述、类别、价格、评分以及两种向量文本嵌入和图像嵌入。这些数据将贯穿全文示例。importnumpyasnpfromjupyterutilsimportresult_print data[{product_id:prod_1,brief_description:comfortable running shoes for athletes,full_description:Engineered with a dual-layer EVA foam midsole...,category:footwear,price:89.99,rating:4.5,text_embedding:np.array([0.1,0.2,0.1],dtypenp.float32).tobytes(),image_embedding:np.array([0.8,0.1],dtypenp.float32).tobytes(),},# ... 更多商品省略具体内容与原文一致]定义索引模式Schema索引模式决定了 Redis 如何存储和索引字段。本例中我们定义了字段名类型用途product_id,categoryTag精确过滤brief_description,full_descriptionText全文搜索price,ratingNumeric数值范围过滤text_embedding(3维)Vector文本语义向量image_embedding(2维)Vector图像语义向量schema{index:{name:advanced_queries,prefix:products,storage_type:hash,},fields:[{name:product_id,type:tag},{name:category,type:tag},{name:brief_description,type:text},{name:full_description,type:text},{name:price,type:numeric},{name:rating,type:numeric},{name:text_embedding,type:vector,attrs:{dims:3,distance_metric:cosine,algorithm:flat,datatype:float32}},{name:image_embedding,type:vector,attrs:{dims:2,distance_metric:cosine,algorithm:flat,datatype:float32}}],}创建索引并加载数据fromredisvl.indeximportSearchIndex indexSearchIndex.from_dict(schema,redis_urlredis://localhost:6379)index.create(overwriteTrue)keysindex.load(data)print(f已加载{len(keys)}个产品)1️⃣ TextQuery全文搜索TextQuery是面向关键词的搜索工具支持多种相关性评分算法BM25、TF‑IDF并可结合过滤器、多字段权重及停用词优化。基本原理全文搜索的核心是倒排索引。Redis 将文本字段分词后构建索引查询时根据词项匹配情况计算文档与查询的相关性分数。评分算法直接影响排序效果BM25BM25STD一种基于概率检索模型的成熟算法考虑词频、文档长度等因素通常比 TF‑IDF 更精准。TF‑IDF经典算法计算简单适合快速原型。基本用法fromredisvl.queryimportTextQuery text_queryTextQuery(textrunning shoes,text_field_namebrief_description,return_fields[product_id,brief_description,category,price],num_results5)resultsindex.query(text_query)result_print(results)输出显示匹配到的商品并按相关性分数降序排列。评分算法对比您可以显式指定text_scorer参数# BM25 标准评分默认bm25_queryTextQuery(...,text_scorerBM25STD)# TF‑IDF 评分tfidf_queryTextQuery(...,text_scorerTFIDF)建议对于一般应用BM25 通常表现更佳若需快速实现或简单场景TF‑IDF 也可胜任。结合过滤器使用filter_expression可以缩小搜索范围例如只搜索某类别或价格区间的商品fromredisvl.query.filterimportTag,Num# 只查找 footwear 类别中的 shoesfilteredTextQuery(textshoes,text_field_namebrief_description,filter_expressionTag(category)footwear,...)# 价格小于 100price_filteredTextQuery(textcomfortable,filter_expressionNum(price)100,...)多字段加权搜索有时不同字段的重要性不同例如brief_description比full_description更能代表商品核心信息。您可以给每个字段分配权重weighted_queryTextQuery(textshoes,text_field_name{brief_description:1.0,full_description:0.5},...)这样命中brief_description的文档会比仅命中full_description的获得更高分数。停用词Stopwords详解停用词是指那些出现频率极高但对语义贡献很小的词如 “the”, “for”。Redis 允许在查询级别和索引级别配置停用词两者作用机制不同配置层级作用时机影响范围查询级TextQuery.stopwords查询时客户端过滤查询词仅影响当前查询索引级Index.stopwords索引创建时服务器决定哪些词被收录影响整个索引所有查询查询级停用词示例# 使用英语默认停用词过滤 the, for 等query_englishTextQuery(textthe best shoes for running,stopwordsenglish,...)# 自定义停用词列表只过滤 for, withquery_customTextQuery(textprofessional equipment for athletes,stopwords[for,with],...)# 完全不禁用停用词保留所有词query_noneTextQuery(textthe best shoes for running,stopwordsNone,...)索引级停用词在创建索引时可通过index.stopwords字段控制哪些词不被索引。默认 Redis 会使用内置停用词列表。若要禁用所有停用词即索引所有词可设置为空列表[]即STOPWORDS 0。这在搜索专有名词如 “Bank of America”时非常有用因为 “of” 不会被过滤掉。stopwords_schema{index:{name:company_index,stopwords:[]# 禁用所有停用词},fields:[...]}⚠️注意索引级停用词在索引创建时生效且修改后需重建索引。查询级停用词则更灵活可按需调整。2️⃣ HybridQuery混合搜索混合搜索将全文检索与向量语义检索相结合既利用关键词精准匹配又借助向量捕获深层语义显著提升检索质量。Redis 从 8.4.0 开始原生支持FT.HYBRID命令RedisVL 提供了HybridQuery类新和AggregateHybridQuery旧两种实现。版本说明HybridQuery需要 Redis 8.4.0 且 redis-py 7.1.0支持更丰富的功能如 RRF、运行时参数。AggregateHybridQuery兼容旧版 Redis基于FT.AGGREGATE实现功能略少不支持 RRF且不支持运行时参数。以下示例默认使用HybridQuery若环境不满足则会降级使用AggregateHybridQuery。混合搜索的工作原理混合搜索并行执行文本查询和向量查询分别得到两个分数文本相关度和向量相似度然后通过组合方法将二者融合为一个最终得分。下图展示了这一流程文本分数向量相似度最终得分用户查询文本检索向量检索得分融合排序结果组合方法RedisVL 支持两种融合策略线性组合LINEARfinal_score α * text_score (1 - α) * vector_score其中α控制文本与向量的权重。默认α 0.3即向量占 70%。倒数排名融合RRF不直接使用分数而是基于各自排名进行融合公式为RRF Σ 1/(k rank)。这种方法对排名靠前的文档给予更高权重能有效缓解分数尺度不一致的问题。基本用法fromredisvl.queryimportHybridQuery hybrid_queryHybridQuery(textrunning shoes,text_field_namebrief_description,vector[0.1,0.2,0.1],# 查询向量vector_field_nametext_embedding,return_fields[product_id,brief_description,category,price],num_results5,yield_text_score_astext_score,yield_vsim_score_asvector_similarity,combination_methodLINEAR,yield_combined_score_ashybrid_score,)resultsindex.query(hybrid_query)输出中会包含文本分数、向量相似度以及融合后的混合分数。调整 alpha 参数通过调整linear_alphaHybridQuery或alphaAggregateHybridQuery可以控制文本和向量的权重alpha1.0纯文本搜索alpha0.0纯向量搜索alpha0.1文本占 10%向量占 90%向量优先# 向量优先查询vector_heavyHybridQuery(...,linear_alpha0.1,combination_methodLINEAR)注意AggregateHybridQuery中的alpha含义相反——它表示向量权重所以alpha0.9表示向量占 90%文本占 10%。使用 RRF仅 HybridQueryrrf_queryHybridQuery(...,combination_methodRRF,rrf_window60,# 可选默认 60rrf_constant1,# 可选默认 1)混合搜索 过滤器与TextQuery类似您也可以添加过滤条件filtered_hybridHybridQuery(...,filter_expressionNum(price)100,)运行时参数仅 HybridQuery对于 HNSW 索引可以通过ef_runtime参数在查询时动态调整搜索范围以平衡精度与速度。HybridQuery支持此参数而AggregateHybridQuery不支持因为它使用FT.AGGREGATE。hybrid_with_runtimeHybridQuery(...,ef_runtime200,# 针对 HNSW 索引)3️⃣ MultiVectorQuery多向量搜索当您的数据包含多种模态的向量如文本向量、图像向量、音频向量时MultiVectorQuery允许您同时对这些向量字段进行检索并按权重综合排序。原理每个查询向量都带有一个权重最终得分为所有向量相似度的加权和combined_score w1 * sim1 w2 * sim2 ... wn * simn其中wi为第 i 个向量的权重simi为其与查询向量的相似度余弦距离转换为相似度1 - 距离。基本用法fromredisvl.queryimportMultiVectorQuery,Vector# 定义每个向量查询text_vectorVector(vector[0.1,0.2,0.1],field_nametext_embedding,dtypefloat32,weight0.7)image_vectorVector(vector[0.8,0.1],field_nameimage_embedding,dtypefloat32,weight0.3)multi_queryMultiVectorQuery(vectors[text_vector,image_vector],return_fields[product_id,brief_description],num_results5)resultsindex.query(multi_query)结果中会显示每个向量的单独得分和组合得分。调整权重您可以通过修改weight来突出某个模态的重要性例如更侧重图像相似性text_vec.weight0.2image_vec.weight0.8结合过滤器同样支持过滤filtered_multiMultiVectorQuery(...,filter_expressionTag(category)footwear,) 三种查询类型对比为了让您更直观地选择合适的方法下表对比了各自特点查询类型核心能力适用场景关键参数TextQuery纯关键词全文搜索精准匹配、传统搜索引擎文本评分器、多字段权重、停用词HybridQuery文本 向量融合兼顾精确与语义适用于大多数搜索场景组合方法LINEAR/RRF、alpha、运行时参数MultiVectorQuery多模态向量联合检索多模态搜索图文、音视频等向量权重、多向量组合下图为决策流程图帮助您快速定位是否是是否否是否开始需要关键词匹配是否需要语义理解TextQuery是否有多个向量字段MultiVectorQueryHybridQuery是否有多个向量字段纯向量搜索VectorQuery不在本指南 最佳实践TextQuery 适用场景当查询词明确、需要精确匹配时如产品型号、专有名词。若数据量不大且实时性要求高文本搜索性能优越。HybridQuery 推荐对于电商、内容推荐等混合场景混合搜索能同时捕获用户意图向量和关键词文本效果更好。建议先用默认 alpha0.3测试再根据业务调整。MultiVectorQuery 多模态利器如果您的数据有图像、音频等多种向量多向量查询可以让您统一打分排序避免分别检索再合并的繁琐。停用词策略如果您的数据包含常见的停用词且这些词具有业务含义如公司名称中的 “of”请在索引级别禁用停用词如果只是查询时想忽略某些词使用查询级停用词更灵活。版本兼容生产环境务必检查 Redis 和 redis-py 版本以决定使用HybridQuery还是AggregateHybridQuery。建议升级到 Redis 8.4 以享受完整功能。 清理资源示例结束后可以删除测试索引以释放资源index.delete(dropTrue)