# 在线 RAG 检索与生成系统 (Online RAG Retriever) 该模块负责 RAG 系统的阶段二：**在线检索与生成**。它接收用户提问，从知识库中检索出上下文，利用各种高级策略去噪、融合，并作为增强上下文输入给大语言模型 (LLM)。 ## 🎯 核心架构 ### 技术栈 | 组件 | 技术选型 | 版本 | 说明 | |:-----|:---------|:-----|:-----| | **基础检索** | `Qdrant` | 1.17+ | HNSW 稠密向量检索 | | **混合检索** | `Qdrant` + `BM25` | 内置 | 稠密 + 稀疏向量融合 | | **查询改写** | `LangChain` | 内置 | `MultiQueryGenerator` 多路改写 | | **RRF 融合** | 自实现 | - | `reciprocal_rank_fusion` 倒数排名融合 | | **重排序** | `llama.cpp` | 本地服务 | OpenAI 兼容 Rerank API | | **编排框架** | `asyncio` | Python 3.10+ | 异步并行检索 | ### 检索流水线 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户提问 │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ MultiQueryGenerator │ │ 多路查询改写 (num_queries=3) │ │ "如何申请项目资金？" → ["项目资金申请流程", "经费申请步骤"] │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 并行检索 (asyncio.gather) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 查询1 检索 │ │ 查询2 检索 │ │ 查询3 检索 │ │ │ │ (k=20) │ │ (k=20) │ │ (k=20) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ reciprocal_rank_fusion (RRF) │ │ RRF_score(d) = Σ 1/(k + rank_q(d)) (k=60) │ │ 融合多路检索结果，去重排序 │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LLaMaCPPReranker │ │ 远程重排序 (bge-reranker-v2-m3) │ │ 返回 Top-N (top_n=5) 最相关文档 │ └──────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 返回增强上下文 │ │ format_context() → 格式化输出 │ └─────────────────────────────────────────────────────────────┘ ``` ### 技术特性 - ✅ **多路查询改写**：通过 LLM 将单一问题改写为多个不同角度的查询 - ✅ **RRF 融合算法**：Reciprocal Rank Fusion，无需评分归一化的融合算法 - ✅ **远程重排序**：使用 llama.cpp 服务的 OpenAI 兼容 Rerank API - ✅ **混合检索支持**：稠密向量 + BM25 稀疏向量混合检索 - ✅ **异步并行检索**：多路查询并行执行，提升检索速度 - ✅ **优雅降级**：重排序器不可用时自动降级到基础融合结果 ## 📂 架构与文件结构 ``` app/rag/ ├── __init__.py ├── retriever.py # Qdrant 基础检索与混合检索 ├── reranker.py # llama.cpp 远程重排序器 ├── query_transform.py # 多路查询改写生成器 ├── fusion.py # RRF 倒数排名融合算法 ├── pipeline.py # RAG 流水线编排 └── tools.py # LangChain Tool 封装 ``` ## 🎯 演进路线与算法详解 (Roadmap) ### Level 1: 基础向量搜索 (Basic Similarity Search) - **核心算法**: 近似最近邻搜索 (ANN, 常用 HNSW 算法)。将用户问题转化为向量后，计算它与库中向量的余弦相似度 (Cosine Similarity)，取距离最近的 K 个块。 - **优缺点**: 速度极快。但只能捕捉"语义相似"，如果用户搜索特定专有名词、编号、订单号，纯向量检索往往会失效（产生"幻觉"匹配）。 - **实现指南**: - 使用 `rag_indexer.embedders.LlamaCppEmbedder` 作为嵌入模型 - 使用 `app/rag/retriever.py` 中的 `create_base_retriever` 创建基础检索器 - 配置 `search_kwargs={"k": 20}` 进行初步召回 ```python from app.rag.retriever import create_base_retriever retriever = create_base_retriever( collection_name="rag_documents", embeddings=embeddings, search_kwargs={"k": 20} ) docs = retriever.invoke("什么是 RAG？") ``` ### Level 2: 混合检索与重排序 (Hybrid Search + Reranker) 混合检索旨在结合向量的"语义泛化"与关键词的"精准匹配"，随后利用重排序模型过滤噪声。 **1. 基础召回 (混合检索)** - **核心原理**: 结合基于 HNSW 的 Dense Vector 相似度搜索与基于 TF-IDF 的 BM25 稀疏检索 (Sparse Vector)。 - **实现指南**: 使用 `app/rag/retriever.py` 中的 `create_hybrid_retriever` 函数，配置 `dense_k=10` 和 `sparse_k=10`，总召回 20 条结果。 ```python from app.rag.retriever import create_hybrid_retriever retriever = create_hybrid_retriever( collection_name="rag_documents", embeddings=embeddings, dense_k=10, sparse_k=10, score_threshold=0.3 ) ``` **2. 二次精排 (Cross-Encoder)** - **核心原理**: 不同于双塔模型（分别算向量再求距离），交叉编码器将"用户问题 + 检索到的单例文档"拼接后整体输入 Transformer 模型，由模型直接输出 0~1 的相关性得分，精度极高。 - **实现指南**: - 使用 `app/rag/reranker.py` 中的 `LLaMaCPPReranker` 类，加载 `bge-reranker-v2-m3` 模型 - 设置 `top_n=5` 保留最相关的 5 条结果 ```python from app.rag.reranker import LLaMaCPPReranker reranker = LLaMaCPPReranker( base_url="http://127.0.0.1:8083", api_key="your-api-key", top_n=5 ) sorted_docs = reranker.compress_documents(documents, query) ``` ### Level 3: RAG-Fusion (多路改写与倒数排名融合) RAG-Fusion 通过大模型发散思维，将单一问题改写为多个相似问题，扩大搜索面，再利用数学统计算法合并结果。 **1. 多路查询改写** - **核心原理**: 克服用户初始提问词不达意或视角受限的问题。 - **实现指南**: 使用 `app/rag/query_transform.py` 中的 `MultiQueryGenerator` 类，配置 `num_queries=3` 生成 3 个不同角度的查询。 ```python from app.rag.query_transform import MultiQueryGenerator generator = MultiQueryGenerator(llm=llm, num_queries=3) queries = await generator.agenerate("如何申请项目资金？") # 返回：["如何申请项目资金？", "项目资金申请流程是什么？", "申请项目经费需要哪些步骤？"] ``` **2. 倒数排名融合 (RRF)** - **核心原理**: RRF (Reciprocal Rank Fusion) 是一种无需评分归一化的融合算法。公式为 `RRF_score(d) = Σ 1/(k + rank_q(d))`，有效避免某一极端检索结果主导全局。 - **实现指南**: 使用 `app/rag/fusion.py` 中的 `reciprocal_rank_fusion` 函数，配置 `k=60` 实现倒数排名融合。 ```python from app.rag.fusion import reciprocal_rank_fusion # 多个查询的检索结果 doc_lists = [result1, result2, result3] fused_docs = reciprocal_rank_fusion(doc_lists, k=60) ``` ### Level 4: Agentic RAG / Self-RAG (智能体与自我反思) - **核心原理**: 基于 LangGraph 的 ReAct (Reasoning and Acting) 状态机路由。大模型并非每次都去死板地执行检索，而是先判断问题："这是闲聊？还是需要查知识库？"。如果是后者，模型输出一个 `ToolCall` 指令，触发检索。 - **实现指南**: 使用 `app/rag/tools.py` 中的 `search_knowledge_base` 工具，将其绑定到 LangGraph 状态机中。 - **示意图**: ``` ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────── │ User │────>│ LangGraph │────>│ RAG_Tool │────>│ Qdrant │ │ │ │ Agent │ │ │ │ │ │ "公司报 │ │ 思考: 这是 │ │ ToolCall │ │ RAG- │ │ 销流程？"│ │ 内部规章问题 │ │ search_ │ │ Fusion │ │ │ │ 需要查资料 │ │ knowledge│ │ & 混合 │ │ │<────│ 资料充分， │<────│ 返回最相 │<────│ 检索 │ │ "根据知 │ │ 开始撰写回答 │ │ 关5条规定 │ │ Cross- │ │ 识库规定 │ │ │ │ │ │ Encoder│ │ ..." │ │ │ │ │ │ 重排 │ └────────── └────────────── └──────────┘ └────────┘ ``` ### Level 5: GraphRAG 集成 (基于图和关系的 RAG) - **核心原理**: 结合知识图谱的结构化关系和向量检索的语义相似度，解决跨文档复杂关系推理问题。 - **实现指南**: - 使用 `langchain_community.graphs` 模块构建知识图谱 - 配置本地大模型（如 `Gemma-4-E4B`）用于实体关系抽取 - 实现混合检索逻辑，结合向量相似度和图路径分析 ```python from langchain_community.graphs import Neo4jGraph from langchain_experimental.graph_transformers import LLMGraphTransformer # 实体关系抽取 transformer = LLMGraphTransformer(llm=local_llm) graph_documents = transformer.convert_to_graph_documents(documents) # 存储到图数据库 graph = Neo4jGraph(url="bolt://localhost:7687") graph.add_graph_documents(graph_documents) ``` ## 🔧 核心组件详解 ### 1. 检索器 (retriever.py) 提供基于 Qdrant 的向量检索能力。 **基础检索器**： ```python from app.rag.retriever import create_base_retriever retriever = create_base_retriever( collection_name="rag_documents", embeddings=embeddings, search_kwargs={"k": 20} ) ``` **混合检索器**： ```python from app.rag.retriever import create_hybrid_retriever retriever = create_hybrid_retriever( collection_name="rag_documents", embeddings=embeddings, dense_k=10, sparse_k=10, score_threshold=0.3 ) ``` ### 2. 多路查询改写 (query_transform.py) 通过 LLM 将用户问题改写为多个不同版本，扩大搜索面。 ```python from app.rag.query_transform import MultiQueryGenerator generator = MultiQueryGenerator(llm=llm, num_queries=3) queries = await generator.agenerate("如何申请项目资金？") ``` ### 3. RRF 融合算法 (fusion.py) Reciprocal Rank Fusion 算法，公式：`RRF_score(d) = Σ 1/(k + rank_q(d))` ```python from app.rag.fusion import reciprocal_rank_fusion # 多个查询的检索结果 doc_lists = [result1, result2, result3] fused_docs = reciprocal_rank_fusion(doc_lists, k=60) ``` ### 4. 重排序器 (reranker.py) 使用 llama.cpp 服务的 OpenAI 兼容 Rerank API 对检索结果重排序。 ```python from app.rag.reranker import LLaMaCPPReranker reranker = LLaMaCPPReranker( base_url="http://127.0.0.1:8083", api_key="your-api-key", top_n=5 ) sorted_docs = reranker.compress_documents(documents, query) ``` ### 5. RAG 流水线 (pipeline.py) 组合上述组件的完整检索流水线。 ```python from app.rag.pipeline import RAGPipeline pipeline = RAGPipeline( retriever=retriever, llm=llm, num_queries=3, rerank_top_n=5, ) # 异步检索 docs = await pipeline.aretrieve("如何申请项目资金？") # 格式化上下文 context = pipeline.format_context(docs) ``` ## 🔄 与 Agent 系统集成 ### 封装为 LangChain Tool ```python from langchain_core.tools import tool from app.rag.pipeline import RAGPipeline @tool def search_knowledge_base(query: str) -> str: """搜索知识库获取相关信息""" docs = pipeline.retrieve(query) return pipeline.format_context(docs) ``` ### 绑定到 LangGraph ```python from app.graph.graph_builder import GraphBuilder # 将 RAG 工具添加到工具列表 tools = AVAILABLE_TOOLS + [search_knowledge_base] # 构建图 builder = GraphBuilder(llm, tools, tools_by_name) graph = builder.build().compile(checkpointer=checkpointer) ``` ## ⚙️ 环境配置 | 变量名 | 说明 | 默认值 | |:-------|:-----|:-------| | `QDRANT_URL` | Qdrant 向量数据库地址 | `http://127.0.0.1:6333` | | `QDRANT_API_KEY` | Qdrant API 密钥 | - | | `LLAMACPP_RERANKER_URL` | llama.cpp 重排序服务地址 | `http://127.0.0.1:8083` | | `LLAMACPP_API_KEY` | llama.cpp API 密钥 | - | ## 🚀 快速开始 ```python # 1. 初始化嵌入模型 from rag_core.embedders import LlamaCppEmbedder embedder = LlamaCppEmbedder() embeddings = embedder.as_langchain_embeddings() # 2. 创建检索器 from app.rag.retriever import create_base_retriever retriever = create_base_retriever( collection_name="rag_documents", embeddings=embeddings, search_kwargs={"k": 20} ) # 3. 创建 RAG 流水线 from app.rag.pipeline import RAGPipeline pipeline = RAGPipeline( retriever=retriever, llm=llm, num_queries=3, rerank_top_n=5, ) # 4. 执行检索 docs = pipeline.retrieve("如何申请项目资金？") # 5. 格式化上下文 context = pipeline.format_context(docs) print(context) ``` ## 📊 检索策略对比 | 策略 | 优点 | 缺点 | 适用场景 | |:-----|:-----|:-----|:---------| | **基础向量检索** | 速度快，语义理解好 | 专有名词匹配差 | 通用问答 | | **混合检索** | 语义 + 关键词匹配 | 需要配置稀疏向量 | 专业术语查询 | | **多路改写 + RRF** | 搜索面广，结果稳定 | 延迟略高 | 复杂问题 | | **重排序** | 精度高 | 依赖额外模型 | 最终精排 | ## 🤝 与 rag_indexer 集成 - **向量存储**：共享 Qdrant 集合，确保嵌入模型一致 - **文档存储**：使用 PostgreSQL 存储父块，通过 UUID 映射 - **集合名称**：默认使用 `rag_documents` 集合 详见 [rag_indexer/README.md](../../rag_indexer/README.md)