
R2R 高级 RAG 实战指南HyDE 与 RAG-Fusion 的运行时切换与源码级解析【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2RR2R 在标准语义检索之外内置了两种开箱即用的高级 RAGRetrieval-Augmented Generation技术——HyDEHypothetical Document Embeddings与 RAG-Fusion只需在search_settings中切换search_strategy参数即可在运行时启用无需改动任何代码或重新部署。本篇指南以 advanced-rag.md 为骨架结合 R2R 仓库中的检索服务实现、提示词模板与集成测试系统讲解这两种技术的工作原理、配置方式、可组合参数以及底层调用链帮助你针对特定检索场景快速实验并优化召回质量。注意Beta 特性高级 RAG 技术在 R2R 中仍处于 beta 阶段目前不支持在 agentic 工作流中使用并且在启用后可能存在可观测性与分析observability and analytics方面的限制。支持的两种高级 RAG 技术R2R 当前支持两种高级 RAG 技术二者都基于同一个核心思路——先用 LLM 对原始查询进行变换query transformation再进行多路检索最后融合或重排结果HyDEHypothetical Document Embeddings基于查询生成若干假设文档对假设文档做嵌入后执行检索从而增强零样本场景下的稠密检索效果。RAG-Fusion将 RAG 与 Reciprocal Rank FusionRRF结合从原始查询派生出多个子查询、分别检索再对多路排名结果进行融合排序提升检索质量与召回覆盖面。运行时切换search_strategy启用哪种技术完全由检索设置中的search_strategy参数决定。从源码看该字段定义在 py/shared/abstractions/search.py 的SearchSettings中默认值为vanilla可选值包括vanilla、hyde、rag_fusion等search_strategy: str Field( defaultvanilla, descriptionSearch strategy to use (e.g., vanilla, query_fusion, hyde), )R2RClientPython SDK会把这个设置原样传给后端。R2R 的检索服务在 py/core/main/services/retrieval_service.py 中按策略进行分发strategy search_settings.search_strategy.lower() if strategy hyde: return await self._hyde_search(query, search_settings) elif strategy rag_fusion: return await self._rag_fusion_search(query, search_settings) else: # vanilla, basic, or anything else... return await self._basic_search(query, search_settings)可以看到未命中hyde/rag_fusion时统一回退到普通检索_basic_search因此切换策略是零成本、无侵入的。三种策略最终都返回同一个AggregateSearchResult其中同时包含 chunk 检索结果与知识图谱检索结果。HyDE用假设文档增强稠密检索工作原理HyDE 是一种增强稠密检索的创新方法尤其适合零样本zero-shot场景。其流程分为四步查询扩展Query Expansion用一个语言模型基于用户查询生成假设性的答案或文档增强嵌入Enhanced Embedding对这些假设文档进行嵌入构造出更丰富的语义搜索空间相似度检索Similarity Search用这些嵌入在数据库中查找最相关的真实文档有依据的生成Informed Generation将检索到的文档与原始查询一起交给 LLM生成最终回答。从 R2R 源码实现看retrieval_service.py 的_hyde_searchHyDE 在服务端的执行细节是调用_run_hyde_generation生成 N 个假设文档N 由num_sub_queries控制对每个假设文档并行执行_fanout_chunk_and_graph_search——先对假设文本做嵌入再用该向量同时执行 chunk 检索与图谱检索合并所有路结果后用原始用户查询通过completion_embedding.arerank对 chunk 结果做一次语义重排以limit × num_sub_queries为上限截取图谱结果按分数降序排列后与 chunk 结果一起封装进AggregateSearchResult返回。实现流程图下图展示了 HyDE 在 R2R 中的完整数据流为简洁起见省略了 GraphRAG 工作流在 R2R 中使用 HyDE通过 Python SDK 调用时只需把search_strategy设为hydeclient.retrieval.rag( What are the main themes in the DeepSeek paper?, search_settings{ search_strategy: hyde, limit: 10 } )一个真实场景下的响应示例节选自文档RAGResponse( generated_answerDeepSeek-R1 is a model that demonstrates impressive performance across various tasks, leveraging reinforcement learning (RL) and supervised fine-tuning (SFT) to enhance its capabilities. It excels in writing tasks, open-domain question answering, and benchmarks like IF-Eval, AlpacaEval2.0, and ArenaHard [1], [2]. ..., search_resultsAggregateSearchResult( chunk_search_results[ChunkSearchResult(score0.643, textDocument Title: DeepSeek_R1.pdf ...)] ), citations[Citation(index1, rawIndex1, startIndex305, endIndex308, snippetStartIndex288, snippetEndIndex315, sourceTypechunk, ide760bb76-1c6e-52eb-910d-0ce5b567011b, document_ide43864f5-a36f-548e-aacd-6f8d48b30c7f, owner_id2acb499e-8428-543b-bd85-0d9098718220, collection_ids[122fdf6a-e116-546b-a8f6-e4cb2e2c0a09], score0.6433466439465674, textDocument Title: DeepSeek_R1.pdf\n\nText: could achieve an accuracy of over 70%. ...)], metadata{id: chatcmpl-B0BaZ0vwIa58deI0k8NIuH6pBhngw, choices: [...], created: 1739384247, model: gpt-4o-2024-08-06, ...} )响应中的generated_answer是最终回答search_results携带带分数score的检索结果citations则给出与回答中[1]、[2]等编号对应的引用片段及文档/集合 ID方便溯源。HyDE 提示词模板假设文档由 LLM 按模板生成。R2R 将提示词存放在数据库提示词目录中HyDE 模板见 py/core/providers/database/prompts/hyde.yamlhyde: template: ### Instruction: Given the query that follows write a double newline separated list of {num_outputs} single paragraph distinct attempted answers to the given query. DO NOT generate any single answer which is likely to require information from multiple distinct documents, EACH single answer will be used to carry out a cosine similarity semantic search over distinct indexed documents, such as varied medical documents. FOR EXAMPLE if asked how do the key themes of Great Gatsby compare with 1984, the two attempted answers would be The key themes of Great Gatsby are ... ANSWER_CONTINUED and The key themes of 1984 are ... ANSWER_CONTINUED, where ANSWER_CONTINUED IS TO BE COMPLETED BY YOU in your response. Here is the original user query to be transformed into answers: ### Query: {message} ### Response: input_types: num_outputs: int message: str模板中的{num_outputs}与{message}两个占位符分别对应SearchSettings.num_sub_queries生成的假设文档数量和用户原始查询服务端在_run_hyde_generation中从提示词数据库读取该模板并填充后调用 LLMretrieval_service.py。RAG-Fusion多查询检索 RRF 融合排序工作原理RAG-Fusion 将 RAG 与 Reciprocal Rank FusionRRF结合用以提升检索信息的质量与相关性流程分为四步查询扩展Query Expansion基于原始查询生成多个相关查询为用户问题提供不同视角多路检索Multiple Retrievals用每个生成的查询分别从数据库检索相关文档倒数排名融合Reciprocal Rank Fusion用 RRF 算法对多路检索的排名结果进行重排融合增强生成Enhanced RAG将重排后的文档连同原始查询与生成查询一起交给 LLM 生成最终回答。相比传统 RAG这一方案能够捕获更广泛的上下文可能召回更相关的信息。实现流程图下图展示了 RAG-Fusion 的工作流同样省略了图谱流程在 R2R 中使用 RAG-Fusionrag_fusion_response client.retrieval.rag( What are the main themes in DeepSeeks paper?, search_settings{ search_strategy: rag_fusion, limit: 20 } )服务端实现细节R2R 的_rag_fusion_searchretrieval_service.py执行如下将原始查询放入子查询集合首位保证不丢失用户意图当num_sub_queries 1时再调用_generate_similar_queries生成num_sub_queries - 1个改写查询对每个子查询分别执行_basic_search收集各自的 chunk 与图谱结果列表分别用_reciprocal_rank_fusion_chunks与_reciprocal_rank_fusion_graphs做 RRF 融合得到最终结果。_generate_similar_queriesretrieval_service.py使用fast_llm、max_tokens128、temperature0.8的生成配置调用 LLM按行解析出候选子查询并截取前num_sub_queries条。RRF 的核心打分公式在_reciprocal_rank_fusion_chunks中实现retrieval_service.py默认常数k 60.0score(chunk) Σ (1 / (k rank_i)) # 对每个包含该 chunk 的子查询排名求和即一个 chunk 在越多子查询结果中排名越靠前其融合分数越高融合后按分数降序输出。该实现同时适用于 chunk 结果与图谱结果_reciprocal_rank_fusion_graphs默认同样k 60.0。子查询生成所使用的提示词模板见 py/core/providers/database/prompts/rag_fusion.yaml其{num_outputs}同样由num_sub_queries控制并明确要求每个子查询尽量面向单一文档主题避免生成需要跨多个文档才能回答的查询。与其他检索 / 生成设置的组合高级 RAG 技术可以与其他检索设置自由组合。例如同时开启 HyDE 与混合检索语义 全文并自定义生成模型与温度custom_rag_response client.retrieval.rag( What are the main themes in the DeepSeek paper?, search_settings{ search_strategy: hyde, limit: 15, use_hybrid_search: True }, rag_generation_config{ model: anthropic/claude-3-opus-20240229, temperature: 0.7 } )常用可组合参数结合 py/shared/abstractions/search.py 中SearchSettings的定义常用的可组合字段包括参数类型默认值说明search_strategystrvanilla检索策略可选vanilla/hyde/rag_fusionlimitint10返回结果条数上限11000offsetint0分页偏移use_semantic_searchboolTrue是否启用语义向量检索use_fulltext_searchboolFalse是否启用全文关键词检索use_hybrid_searchboolFalse等价于同时开启语义 全文检索filtersdict{}检索过滤条件支持$eq、$in、$overlap、$and等运算符num_sub_queriesint5使用hyde/rag_fusion时生成的假设文档 / 子查询数量hybrid_settings.full_text_weightfloat1.0混合检索中全文检索的权重hybrid_settings.semantic_weightfloat5.0混合检索中语义检索的权重hybrid_settings.rrf_kint50混合检索内部 RRF 融合的 K 值chunk_settings.enabledboolTrue是否启用 chunk 检索生成侧则通过rag_generation_configGenerationConfig控制常用字段包括model未显式指定时由 API 端点回退到config.app.quality_llm、temperature、max_tokens、stream等完整说明见 retrieval_router.py。关于search_mode的补充说明/v3/retrieval/rag与/v3/retrieval/search端点还提供search_mode快捷入口retrieval_router.pybasic简单的纯语义检索search_strategyvanilla关闭全文检索advanced语义 全文的混合检索且默认直接启用search_strategyhyde见 search.py 中get_default(advanced)的实现custom完全由search_settings控制默认值。因此如果你只想快速体验 HyDE也可以直接使用search_modeadvanced而不必手写search_settings。集成测试中的行为验证仓库的集成测试对两种策略均有覆盖可帮助你理解预期行为py/tests/integration/test_retrieval.pytest_search_hyde_modeL656创建一批带test_hyde_fulltext元数据的文档后以search_strategyhyde、limit5、num_sub_queries5查询断言返回25 条chunk 结果即limit × num_sub_queries对应 HyDE 多路检索 重排后的结果量test_search_rag_fusion_modeL705以search_strategyrag_fusion、limit5查询断言返回5 条chunk 结果RRF 融合后按limit截取test_rag_fusion_mode_with_subqueriesL740验证传入num_sub_queries3时服务不会报错可用于确认多子查询路径的健壮性。这些测试确认了search_strategy参数能够被端到端地解析、分发并产生结构完整的AggregateSearchResult是理解两种策略返回形态最直接的参考。结论通过search_strategy这一个运行时参数R2R 可以在普通 RAG、HyDE 与 RAG-Fusion 之间自由切换并结合limit、use_hybrid_search、filters、num_sub_queries、rag_generation_config等设置进行细粒度调优。其底层实现脉络清晰SearchSettings定义参数py/shared/abstractions/search.py→ 检索服务按策略分发retrieval_service.py→ HyDE / RAG-Fusion 各自的提示词模板驱动 LLM 完成查询变换hyde.yaml、rag_fusion.yaml→ 多路检索后经语义重排HyDE或 RRF 融合RAG-Fusion输出结果。建议在实际项目中针对自己的语料与业务场景实验不同的策略、参数与提示词变体找到最适合特定用例的配置组合。利用 R2R 的运行时灵活性你可以持续迭代检索与生成质量适应不断变化的需求。【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考