尧图网页设计 
Haystack QueryExpander 组件详解用 LLM 查询扩展提升 RAG 检索召回率【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackQueryExpander 是 Haystack 提供的查询处理组件它利用大语言模型LLM将用户输入的单条查询扩展为多条语义相近的变体查询从而显著提升 RAG检索增强生成系统中基于关键词或向量检索的召回率。读完本文你将掌握 QueryExpander 的初始化参数、运行机制、序列化方式并能把它与 MultiQuery 系列检索器组合进真实的 Haystack 流水线中。组件定位与核心思想在 RAG 系统中召回率recall往往受限于用户查询的措辞用户说 green energy sources但相关文档可能只包含 renewable power 这样的表述直接检索容易漏掉相关内容。QueryExpander 的解法是让 LLM 基于原始查询生成一组语义等价、措辞多样的变体查询再把这组查询一起交给检索器扩大命中文档的覆盖面。从源码结构看该组件位于 haystack/components/query/query_expander.py并在 haystack/components/query/init.py 中以QueryExpander名义导出可通过from haystack.components.query import QueryExpander引入。它是 Haystack 的component装饰组件因此天然支持接入Pipeline进行组合编排。QueryExpander 的核心工作流对应 query_expander.py 中run方法的实现如下先对底层的 chat generator 执行warm_up()加载模型环境通过内置PromptBuilder把query和n_expansions渲染成提示词将提示词包装为ChatMessage.from_user(...)发给 chat generator从生成回复中解析 JSON提取queries列表对结果去重、截断到请求数量并按需追加原始查询若 LLM 调用或 JSON 解析失败则优雅降级——仅返回原始查询保证流水线不中断。初始化参数详解QueryExpander.__init__的完整签名如下来自 query_expander.pydef __init__(*, chat_generator: ChatGenerator | None None, prompt_template: str | None None, n_expansions: int 4, include_original_query: bool True) - None参数类型默认值说明chat_generatorChatGenerator \| NoneNone负责生成扩展查询的聊天生成器。为None时使用默认的OpenAIChatGenerator(modelgpt-4.1-mini)并内置temperature0.7、JSON Schema 输出约束与固定随机种子seed42详见 query_expander.py。也可替换为任意兼容的 Chat Generator如 Anthropic、Azure OpenAI 等prompt_templatestr \| None内置默认模板自定义提示词模板必须同时包含query与n_expansions两个 Jinja 变量并引导 LLM 返回{queries: [...]}形式的 JSON。模板缺少任一变量时会输出警告日志n_expansionsint4需要生成的备选查询数量不含原始查询必须为正整数否则在初始化时抛出ValueError(n_expansions must be positive)include_original_queryboolTrue输出结果中是否包含原始查询本身几个关键实现细节值得注意参数校验前置n_expansions 0的检查发生在__init__中query_expander.py测试用例 test_query_expander.py 也验证了传入-1或0都会立即报错。模板变量自检构造时会检查模板中是否出现query与n_expansionsquery_expander.py并基于PromptBuilder(template..., required_variables[n_expansions, query])构建内部提示构建器运行时若变量缺失会得到更明确的错误。默认模型能力依赖默认走OpenAI的gpt-4.1-mini因此直接使用默认配置需要设置OPENAI_API_KEY环境变量可参考集成测试 test_query_expander.py 中对该前置条件的说明。默认提示词模板若不传prompt_template组件使用DEFAULT_PROMPT_TEMPLATE定义于 query_expander.py。该模板包含任务指令明确要求把输入查询扩展为{{ n_expansions }}条语义相似的查询以提升检索召回率Few-shot 示例如climate change effects→[impact of climate change, consequences of global warming, effects of environmental changes]生成准则使用不同措辞与同义词、保持核心语义与意图不变、聚焦对关键词检索友好的变体、与输入查询保持同一语言输出硬约束必须返回包含queries数组的 JSON 对象。该默认模板保证扩展结果换词不换意且语言与原始查询一致run方法文档也明确承诺保留原查询语言。基本使用示例官方文档给出的最小用法如下与 query_expander.py 中的 Usage example 一致from haystack.components.generators.chat.openai import OpenAIChatGenerator from haystack.components.query import QueryExpander expander QueryExpander( chat_generatorOpenAIChatGenerator(modelgpt-4.1-mini), n_expansions3 ) result expander.run(querygreen energy sources) print(result[queries]) # Output: [alternative query 1, alternative query 2, alternative query 3, green energy sources] # Note: Up to 3 additional queries 1 original query (if include_original_queryTrue)关于查询总数的两种控制方式expander QueryExpander(n_expansions2, include_original_queryTrue) # 最多共 3 条 # 或 expander QueryExpander(n_expansions3, include_original_queryFalse) # 恰好 3 条run方法签名query_expander.pycomponent.output_types(querieslist[str]) def run(query: str, n_expansions: int | None None) - dict[str, list[str]]query需要扩展的原始查询n_expansions运行时覆盖初始化值None时使用构造参数必须为正整数否则抛出ValueError返回值键为queries的字典值为扩展查询列表include_original_queryTrue时原始查询会追加在备选查询之后。值得注意的是run方法在每次调用时都会先执行warm_up()query_expander.py确保底层生成器可用。扩展查询的解析、去重与降级策略JSON 解析与健壮性LLM 返回的原始文本由静态方法_parse_expanded_queriesquery_expander.py处理先尝试从回复文本中解析 JSON 字典并提取queries键若queries不是列表、内容非法或无法解析则返回空列表并记录警告对列表逐项过滤仅保留非空字符串并按首次出现顺序去重混合类型响应如混入数字或空字符串会被安全跳过测试见 test_query_expander.py。数量截断如果 LLM 生成的查询数超过请求数组件会记录警告日志Generated {N} queries but only {M} were requested. Truncating...并截断到前n_expansions条query_expander.py。截断发生在去重之后对应测试 test_query_expander.py 验证了先去重再截断的顺序。原始查询的去重追加当include_original_queryTrue时若扩展结果中已包含与原始查询相同的文本忽略大小写则不会重复追加query_expander.py避免冗余查询影响检索效率测试见 test_query_expander.py。失败降级整个扩展过程包裹在try/except中无论 LLM 调用异常、返回空回复还是 JSON 解析失败组件都会记录异常日志并回退为仅返回原始查询query_expander.py。这一设计保证了即使外部 LLM 服务不稳定下游检索流程也不会中断——对应的单元测试覆盖了生成器抛异常返回空回复非法 JSON三类场景test_query_expander.py。空查询空白字符串也会被提前拦截直接返回原样结果并告警query_expander.py。异步支持与组件生命周期QueryExpander 提供了与run等价的异步入口run_asyncquery_expander.py接口与返回结构完全一致。其实现细节若底层 chat generator 实现了run_async则直接调用若只有同步run则通过_execute_component_async放入线程池执行避免阻塞事件循环对应测试 test_query_expander.py 使用了一个仅含同步run的假生成器验证回退路径。组件还完整实现了 Haystack 的标准生命周期方法query_expander.py方法作用回退行为warm_up()预热底层 chat generator无warm_up时静默跳过warm_up_async()在服务事件循环上预热无warm_up_async时回退到同步warm_upclose()/close_async()释放生成器资源异步缺失时回退到同步实现生命周期方法的全部分支均有测试覆盖test_query_expander.py包括生成器完全不含生命周期方法时的安全跳过场景。此外同步与异步run都会通过_trace_chat_generator_run在追踪系统中记录haystack.chat_generator.run跨度并携带 token 用量等输出标签query_expander.py便于观测每次扩展调用的成本与延迟对应测试见 test_query_expander.py。序列化to_dict 与 from_dict与其他 Haystack 组件一致QueryExpander 支持标准的字典序列化/反序列化便于保存到 YAML/JSON 或与Pipeline.dumps/loads配合使用。to_dictquery_expander.py返回包含type与init_parameters的字典其中chat_generator通过component_to_dict递归序列化默认情况下会包含api_key的env_var引用即OPENAI_API_KEYprompt_template、n_expansions、include_original_query原样保存。from_dictquery_expander.py在反序列化前调用deserialize_chatgenerator_inplace把chat_generator还原为可运行的组件实例。序列化往返的完整断言包括type路径、init_parameters结构、模型名等见 test_query_expander.py。序列化后的组件类型标识为haystack.components.query.query_expander.QueryExpander这也是在 YAML 流水线声明中引用该组件时的type字段取值。自定义提示词模板默认模板面向通用场景当需要领域化扩展例如只关注技术术语、限定专业领域措辞时可传入自定义模板from haystack.components.query import QueryExpander custom_template You are a search query expansion assistant. Generate {{ n_expansions }} alternative search queries for: {{ query }} Return a JSON object with a queries array containing the expanded queries. Focus on technical terminology and domain-specific variations. expander QueryExpander(prompt_templatecustom_template, n_expansions4) result expander.run(querymachine learning optimization)使用自定义模板时需遵守两个约束源码与测试均有明确依据必须包含query与n_expansions变量否则构造时会收到The prompt template does not contain the ... variable警告query_expander.py测试见 test_query_expander.py必须指示 LLM 输出{queries: [query1, query2, ...]}结构的 JSON因为组件只会解析该键对应的字符串数组。运行时会先经PromptBuilder把query与n_expansions渲染进模板再封装为用户消息发送给 chat generatorquery_expander.py因此模板中的 Jinja 变量占位符写法与 Haystack 其他 PromptBuilder 完全一致。与 MultiQuery 检索器组合实战QueryExpander 单独运行时只是查询变换器其价值在接入检索流水线后才能真正释放。它专门面向接受多条查询的检索器设计最常见的流水线位置是位于MultiQueryTextRetriever或MultiQueryEmbeddingRetriever之前见 queryexpander.mdx 与 multiquerytextretriever.mdx。这两个检索器的run方法签名均接收queries: list[str]multi_query_text_retriever.py基于关键词BM25检索多个查询在ThreadPoolExecutor中并行执行随后对文档去重并按相关度降序排序multi_query_text_retriever.pymulti_query_embedding_retriever.py基于向量嵌入检索同样并行处理多条查询。组合示例from haystack import Pipeline from haystack.components.query import QueryExpander from haystack.components.retrievers import InMemoryBM25Retriever from haystack.components.retrievers import MultiQueryTextRetriever pipeline Pipeline() pipeline.add_component(query_expander, QueryExpander(n_expansions3)) pipeline.add_component( retriever, MultiQueryTextRetriever(retrieverInMemoryBM25Retriever(document_storedocument_store)), ) pipeline.connect(query_expander.queries, retriever.queries) result pipeline.run({query_expander: {query: green energy sources}})在这个流程中QueryExpander输出的多条查询会并行检索MultiQueryTextRetriever负责把各查询命中的文档合并去重并按分数排序最终只输出一份高质量的结果列表——这正是以查询扩展提升召回率以多查询合并保证精排质量的完整闭环。需要说明的是上述MultiQueryTextRetriever与MultiQueryEmbeddingRetriever的具体初始化参数如文档存储、嵌入模型等以 docs-website/docs/pipeline-components/retrievers 目录下对应页面为准。小结QueryExpander 是 Haystack 查询处理链路中以小博大的关键组件成本仅是一次 LLM 调用收益却是检索召回率的显著提升。其设计处处体现了生产级组件的工程考量——JSON 解析的健壮性、去重截断的一致性、异常时的优雅降级、同步/异步双通道与完整的序列化生命周期支持。建议读者结合本文引用的源码路径 query_expander.py 与测试文件 test_query_expander.py 深入研读并参考 queryexpander.mdx 将组件接入真实流水线验证效果。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Haystack QueryExpander 组件详解：用 LLM 查询扩展提升 RAG 检索召回率
Haystack QueryExpander 组件详解用 LLM 查询扩展提升 RAG 检索召回率【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackQueryExpander 是 Haystack 提供的查询处理组件它利用大语言模型LLM将用户输入的单条查询扩展为多条语义相近的变体查询从而显著提升 RAG检索增强生成系统中基于关键词或向量检索的召回率。读完本文你将掌握 QueryExpander 的初始化参数、运行机制、序列化方式并能把它与 MultiQuery 系列检索器组合进真实的 Haystack 流水线中。组件定位与核心思想在 RAG 系统中召回率recall往往受限于用户查询的措辞用户说 green energy sources但相关文档可能只包含 renewable power 这样的表述直接检索容易漏掉相关内容。QueryExpander 的解法是让 LLM 基于原始查询生成一组语义等价、措辞多样的变体查询再把这组查询一起交给检索器扩大命中文档的覆盖面。从源码结构看该组件位于 haystack/components/query/query_expander.py并在 haystack/components/query/init.py 中以QueryExpander名义导出可通过from haystack.components.query import QueryExpander引入。它是 Haystack 的component装饰组件因此天然支持接入Pipeline进行组合编排。QueryExpander 的核心工作流对应 query_expander.py 中run方法的实现如下先对底层的 chat generator 执行warm_up()加载模型环境通过内置PromptBuilder把query和n_expansions渲染成提示词将提示词包装为ChatMessage.from_user(...)发给 chat generator从生成回复中解析 JSON提取queries列表对结果去重、截断到请求数量并按需追加原始查询若 LLM 调用或 JSON 解析失败则优雅降级——仅返回原始查询保证流水线不中断。初始化参数详解QueryExpander.__init__的完整签名如下来自 query_expander.pydef __init__(*, chat_generator: ChatGenerator | None None, prompt_template: str | None None, n_expansions: int 4, include_original_query: bool True) - None参数类型默认值说明chat_generatorChatGenerator \| NoneNone负责生成扩展查询的聊天生成器。为None时使用默认的OpenAIChatGenerator(modelgpt-4.1-mini)并内置temperature0.7、JSON Schema 输出约束与固定随机种子seed42详见 query_expander.py。也可替换为任意兼容的 Chat Generator如 Anthropic、Azure OpenAI 等prompt_templatestr \| None内置默认模板自定义提示词模板必须同时包含query与n_expansions两个 Jinja 变量并引导 LLM 返回{queries: [...]}形式的 JSON。模板缺少任一变量时会输出警告日志n_expansionsint4需要生成的备选查询数量不含原始查询必须为正整数否则在初始化时抛出ValueError(n_expansions must be positive)include_original_queryboolTrue输出结果中是否包含原始查询本身几个关键实现细节值得注意参数校验前置n_expansions 0的检查发生在__init__中query_expander.py测试用例 test_query_expander.py 也验证了传入-1或0都会立即报错。模板变量自检构造时会检查模板中是否出现query与n_expansionsquery_expander.py并基于PromptBuilder(template..., required_variables[n_expansions, query])构建内部提示构建器运行时若变量缺失会得到更明确的错误。默认模型能力依赖默认走OpenAI的gpt-4.1-mini因此直接使用默认配置需要设置OPENAI_API_KEY环境变量可参考集成测试 test_query_expander.py 中对该前置条件的说明。默认提示词模板若不传prompt_template组件使用DEFAULT_PROMPT_TEMPLATE定义于 query_expander.py。该模板包含任务指令明确要求把输入查询扩展为{{ n_expansions }}条语义相似的查询以提升检索召回率Few-shot 示例如climate change effects→[impact of climate change, consequences of global warming, effects of environmental changes]生成准则使用不同措辞与同义词、保持核心语义与意图不变、聚焦对关键词检索友好的变体、与输入查询保持同一语言输出硬约束必须返回包含queries数组的 JSON 对象。该默认模板保证扩展结果换词不换意且语言与原始查询一致run方法文档也明确承诺保留原查询语言。基本使用示例官方文档给出的最小用法如下与 query_expander.py 中的 Usage example 一致from haystack.components.generators.chat.openai import OpenAIChatGenerator from haystack.components.query import QueryExpander expander QueryExpander( chat_generatorOpenAIChatGenerator(modelgpt-4.1-mini), n_expansions3 ) result expander.run(querygreen energy sources) print(result[queries]) # Output: [alternative query 1, alternative query 2, alternative query 3, green energy sources] # Note: Up to 3 additional queries 1 original query (if include_original_queryTrue)关于查询总数的两种控制方式expander QueryExpander(n_expansions2, include_original_queryTrue) # 最多共 3 条 # 或 expander QueryExpander(n_expansions3, include_original_queryFalse) # 恰好 3 条run方法签名query_expander.pycomponent.output_types(querieslist[str]) def run(query: str, n_expansions: int | None None) - dict[str, list[str]]query需要扩展的原始查询n_expansions运行时覆盖初始化值None时使用构造参数必须为正整数否则抛出ValueError返回值键为queries的字典值为扩展查询列表include_original_queryTrue时原始查询会追加在备选查询之后。值得注意的是run方法在每次调用时都会先执行warm_up()query_expander.py确保底层生成器可用。扩展查询的解析、去重与降级策略JSON 解析与健壮性LLM 返回的原始文本由静态方法_parse_expanded_queriesquery_expander.py处理先尝试从回复文本中解析 JSON 字典并提取queries键若queries不是列表、内容非法或无法解析则返回空列表并记录警告对列表逐项过滤仅保留非空字符串并按首次出现顺序去重混合类型响应如混入数字或空字符串会被安全跳过测试见 test_query_expander.py。数量截断如果 LLM 生成的查询数超过请求数组件会记录警告日志Generated {N} queries but only {M} were requested. Truncating...并截断到前n_expansions条query_expander.py。截断发生在去重之后对应测试 test_query_expander.py 验证了先去重再截断的顺序。原始查询的去重追加当include_original_queryTrue时若扩展结果中已包含与原始查询相同的文本忽略大小写则不会重复追加query_expander.py避免冗余查询影响检索效率测试见 test_query_expander.py。失败降级整个扩展过程包裹在try/except中无论 LLM 调用异常、返回空回复还是 JSON 解析失败组件都会记录异常日志并回退为仅返回原始查询query_expander.py。这一设计保证了即使外部 LLM 服务不稳定下游检索流程也不会中断——对应的单元测试覆盖了生成器抛异常返回空回复非法 JSON三类场景test_query_expander.py。空查询空白字符串也会被提前拦截直接返回原样结果并告警query_expander.py。异步支持与组件生命周期QueryExpander 提供了与run等价的异步入口run_asyncquery_expander.py接口与返回结构完全一致。其实现细节若底层 chat generator 实现了run_async则直接调用若只有同步run则通过_execute_component_async放入线程池执行避免阻塞事件循环对应测试 test_query_expander.py 使用了一个仅含同步run的假生成器验证回退路径。组件还完整实现了 Haystack 的标准生命周期方法query_expander.py方法作用回退行为warm_up()预热底层 chat generator无warm_up时静默跳过warm_up_async()在服务事件循环上预热无warm_up_async时回退到同步warm_upclose()/close_async()释放生成器资源异步缺失时回退到同步实现生命周期方法的全部分支均有测试覆盖test_query_expander.py包括生成器完全不含生命周期方法时的安全跳过场景。此外同步与异步run都会通过_trace_chat_generator_run在追踪系统中记录haystack.chat_generator.run跨度并携带 token 用量等输出标签query_expander.py便于观测每次扩展调用的成本与延迟对应测试见 test_query_expander.py。序列化to_dict 与 from_dict与其他 Haystack 组件一致QueryExpander 支持标准的字典序列化/反序列化便于保存到 YAML/JSON 或与Pipeline.dumps/loads配合使用。to_dictquery_expander.py返回包含type与init_parameters的字典其中chat_generator通过component_to_dict递归序列化默认情况下会包含api_key的env_var引用即OPENAI_API_KEYprompt_template、n_expansions、include_original_query原样保存。from_dictquery_expander.py在反序列化前调用deserialize_chatgenerator_inplace把chat_generator还原为可运行的组件实例。序列化往返的完整断言包括type路径、init_parameters结构、模型名等见 test_query_expander.py。序列化后的组件类型标识为haystack.components.query.query_expander.QueryExpander这也是在 YAML 流水线声明中引用该组件时的type字段取值。自定义提示词模板默认模板面向通用场景当需要领域化扩展例如只关注技术术语、限定专业领域措辞时可传入自定义模板from haystack.components.query import QueryExpander custom_template You are a search query expansion assistant. Generate {{ n_expansions }} alternative search queries for: {{ query }} Return a JSON object with a queries array containing the expanded queries. Focus on technical terminology and domain-specific variations. expander QueryExpander(prompt_templatecustom_template, n_expansions4) result expander.run(querymachine learning optimization)使用自定义模板时需遵守两个约束源码与测试均有明确依据必须包含query与n_expansions变量否则构造时会收到The prompt template does not contain the ... variable警告query_expander.py测试见 test_query_expander.py必须指示 LLM 输出{queries: [query1, query2, ...]}结构的 JSON因为组件只会解析该键对应的字符串数组。运行时会先经PromptBuilder把query与n_expansions渲染进模板再封装为用户消息发送给 chat generatorquery_expander.py因此模板中的 Jinja 变量占位符写法与 Haystack 其他 PromptBuilder 完全一致。与 MultiQuery 检索器组合实战QueryExpander 单独运行时只是查询变换器其价值在接入检索流水线后才能真正释放。它专门面向接受多条查询的检索器设计最常见的流水线位置是位于MultiQueryTextRetriever或MultiQueryEmbeddingRetriever之前见 queryexpander.mdx 与 multiquerytextretriever.mdx。这两个检索器的run方法签名均接收queries: list[str]multi_query_text_retriever.py基于关键词BM25检索多个查询在ThreadPoolExecutor中并行执行随后对文档去重并按相关度降序排序multi_query_text_retriever.pymulti_query_embedding_retriever.py基于向量嵌入检索同样并行处理多条查询。组合示例from haystack import Pipeline from haystack.components.query import QueryExpander from haystack.components.retrievers import InMemoryBM25Retriever from haystack.components.retrievers import MultiQueryTextRetriever pipeline Pipeline() pipeline.add_component(query_expander, QueryExpander(n_expansions3)) pipeline.add_component( retriever, MultiQueryTextRetriever(retrieverInMemoryBM25Retriever(document_storedocument_store)), ) pipeline.connect(query_expander.queries, retriever.queries) result pipeline.run({query_expander: {query: green energy sources}})在这个流程中QueryExpander输出的多条查询会并行检索MultiQueryTextRetriever负责把各查询命中的文档合并去重并按分数排序最终只输出一份高质量的结果列表——这正是以查询扩展提升召回率以多查询合并保证精排质量的完整闭环。需要说明的是上述MultiQueryTextRetriever与MultiQueryEmbeddingRetriever的具体初始化参数如文档存储、嵌入模型等以 docs-website/docs/pipeline-components/retrievers 目录下对应页面为准。小结QueryExpander 是 Haystack 查询处理链路中以小博大的关键组件成本仅是一次 LLM 调用收益却是检索召回率的显著提升。其设计处处体现了生产级组件的工程考量——JSON 解析的健壮性、去重截断的一致性、异常时的优雅降级、同步/异步双通道与完整的序列化生命周期支持。建议读者结合本文引用的源码路径 query_expander.py 与测试文件 test_query_expander.py 深入研读并参考 queryexpander.mdx 将组件接入真实流水线验证效果。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考