重构代码，统一config配置

backend/app/rag/README.md

@@ -0,0 +1,391 @@
+# 在线 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)

backend/app/rag/__init__.py

@@ -0,0 +1,69 @@
+"""
+RAG 检索与生成模块
+
+提供在线检索与生成功能，包括：
+- 基础向量检索（稠密向量 / 混合检索）
+- 重排序（Cross-Encoder）
+- 多路查询改写（Multi-Query）
+- RRF 融合（Reciprocal Rank Fusion）
+- 完整的 RAG 流水线
+- Agent 工具封装
+
+固定流水线：
+    用户查询 → 多路改写 → 并行检索 → RRF 融合 → 重排序 → 返回父文档
+
+示例用法：
+    >>> from app.rag.rag import RAGPipeline, create_rag_tool
+    >>> from rag_indexer.builder import IndexBuilder, IndexBuilderConfig
+    >>> from langchain_openai import ChatOpenAI
+    >>>
+    >>> # 获取基础检索器（如父子块检索器）
+    >>> config = IndexBuilderConfig(collection_name="my_docs")
+    >>> builder = IndexBuilder(config)
+    >>> retriever = builder.retriever
+    >>>
+    >>> # 创建 LLM 和流水线
+    >>> llm = ChatOpenAI(model="gpt-3.5-turbo")
+    >>> pipeline = RAGPipeline(retriever=retriever, llm=llm)
+    >>>
+    >>> # 检索
+    >>> docs = await pipeline.aretrieve("什么是 RAG？")
+    >>> context = pipeline.format_context(docs)
+    >>>
+    >>> # 创建 Agent 工具
+    >>> rag_tool = create_rag_tool(retriever=retriever, llm=llm)
+"""
+
+from .retriever import (
+    create_base_retriever,
+    create_hybrid_retriever,
+    create_qdrant_client,
+)
+from .reranker import LLaMaCPPReranker
+from .query_transform import MultiQueryGenerator
+from .fusion import reciprocal_rank_fusion
+from .pipeline import RAGPipeline
+from .tools import create_rag_tool_sync
+
+
+__all__ = [
+    # 检索器工厂函数
+    "create_base_retriever",
+    "create_hybrid_retriever",
+    "create_qdrant_client",
+    
+    # 重排序器
+    "LLaMaCPPReranker",
+    
+    # 查询改写生成器
+    "MultiQueryGenerator",
+    
+    # 融合算法
+    "reciprocal_rank_fusion",
+    
+    # 主流水线
+    "RAGPipeline",
+    
+    # 工具创建（供 Agent 使用）
+    "create_rag_tool_sync",
+]

backend/app/rag/fusion.py

@@ -0,0 +1,36 @@
+# rag/fusion.py
+
+from typing import List, Dict
+from langchain_core.documents import Document
+
+def reciprocal_rank_fusion(
+    doc_lists: List[List[Document]],
+    k: int = 60
+) -> List[Document]:
+    """
+    对多个检索结果列表进行 RRF 融合。
+    
+    Args:
+        doc_lists: 多个检索结果列表，每个列表来自一个查询
+        k: RRF 常数，通常设为 60
+    
+    Returns:
+        融合后按 RRF 得分降序排列的文档列表
+    """
+    # 使用文档内容作为唯一标识（如果内容相同但 metadata 不同，视为同一文档）
+    # 更好的做法是用 docstore 的 ID，这里简化处理：用内容 hash
+    doc_to_score: Dict[str, float] = {}
+    doc_map: Dict[str, Document] = {}
+    
+    for docs in doc_lists:
+        for rank, doc in enumerate(docs, start=1):
+            # 生成唯一标识符（内容+来源组合，避免不同文件相同内容混淆）
+            doc_id = f"{doc.page_content[:200]}_{doc.metadata.get('source', '')}"
+            if doc_id not in doc_map:
+                doc_map[doc_id] = doc
+            score = doc_to_score.get(doc_id, 0.0) + 1.0 / (k + rank)
+            doc_to_score[doc_id] = score
+    
+    # 按得分排序
+    sorted_ids = sorted(doc_to_score.keys(), key=lambda x: doc_to_score[x], reverse=True)
+    return [doc_map[doc_id] for doc_id in sorted_ids]

backend/app/rag/pipeline.py

@@ -0,0 +1,91 @@
+# rag/pipeline.py
+
+import asyncio
+import os
+from ..config import LLAMACPP_RERANKER_URL, LLAMACPP_API_KEY
+from typing import List
+from langchain_core.documents import Document
+from langchain_core.language_models import BaseLanguageModel
+
+from .reranker import LLaMaCPPReranker
+from .query_transform import MultiQueryGenerator
+from .fusion import reciprocal_rank_fusion
+
+class RAGPipeline:
+    """
+    固定流程的 RAG 检索流水线：
+    多路改写 → 并行检索 → RRF融合 → 重排序 → 返回父文档
+    """
+    
+    def __init__(
+        self,
+        retriever,  # 基础检索器（应返回父文档，例如 ParentDocumentRetriever 实例）
+        llm: BaseLanguageModel,
+        num_queries: int = 3,
+        rerank_top_n: int = 5,
+    ):
+        """
+        Args:
+            retriever: 基础检索器对象，需实现 ainvoke(query) 异步方法
+            llm: 用于生成多路查询的语言模型
+            num_queries: 生成的查询变体数量
+            rerank_top_n: 最终返回的文档数量
+            rerank_model: 重排序模型名称
+        """
+        self.retriever = retriever
+        self.llm = llm
+        self.num_queries = num_queries
+        self.rerank_top_n = rerank_top_n
+        
+        # 初始化组件
+        self.query_generator = MultiQueryGenerator(llm=llm, num_queries=num_queries)
+        self.reranker = LLaMaCPPReranker(
+                base_url=LLAMACPP_RERANKER_URL,
+                api_key=LLAMACPP_API_KEY,
+                top_n=rerank_top_n,
+            )
+    
+    async def aretrieve(self, query: str) -> List[Document]:
+        """
+        异步执行完整检索流程
+        """
+        # Step 1: 生成多路查询
+        queries = await self.query_generator.agenerate(query)
+        # 包含原始查询，确保至少有一条
+        if query not in queries:
+            queries.insert(0, query)
+        else:
+            # 如果原始查询已在列表中，将其移至首位
+            queries.remove(query)
+            queries.insert(0, query)
+        
+        # Step 2: 并行检索（每个查询获取文档列表）
+        tasks = [self.retriever.ainvoke(q) for q in queries]
+        doc_lists = await asyncio.gather(*tasks)
+        
+        # Step 3: RRF 融合
+        fused_docs = reciprocal_rank_fusion(doc_lists)
+        
+        # Step 4: 重排序
+        try:
+            final_docs = self.reranker.compress_documents(fused_docs, query)
+        except Exception:
+            # 若重排序器不可用，直接返回融合后的前 N 条
+            final_docs = fused_docs[:self.rerank_top_n]
+        
+        return final_docs
+    
+    def retrieve(self, query: str) -> List[Document]:
+        """同步检索入口（内部调用异步方法）"""
+        return asyncio.run(self.aretrieve(query))
+    
+    def format_context(self, documents: List[Document]) -> str:
+        """将文档列表格式化为上下文字符串"""
+        if not documents:
+            return ""
+        
+        parts = []
+        for i, doc in enumerate(documents, 1):
+            source = doc.metadata.get("source", "未知来源")
+            parts.append(f"【资料 {i}】来源：{source}\n{doc.page_content}\n---\n")
+        return "\n".join(parts)

backend/app/rag/query_transform.py

@@ -0,0 +1,43 @@
+# rag/query_transform.py
+
+from typing import List
+from langchain_core.language_models import BaseLanguageModel
+from langchain_core.prompts import PromptTemplate
+
+MULTI_QUERY_PROMPT = PromptTemplate.from_template(
+    """你是一个专业的查询改写助手。你的任务是将用户的问题改写成 {num_queries} 个不同的版本。
+这些版本应该从不同的角度、使用不同的关键词来表达相同或相关的意图。
+
+原始问题: {question}
+
+请生成 {num_queries} 个不同版本的查询，每个版本一行。
+确保每个版本都是独立、完整的查询语句。
+
+生成 {num_queries} 个查询:"""
+)
+
+class MultiQueryGenerator:
+    """多路查询生成器（不依赖 LangChain 的 MultiQueryRetriever）"""
+    
+    def __init__(self, llm: BaseLanguageModel, num_queries: int = 3):
+        self.llm = llm
+        self.num_queries = num_queries
+        self.prompt = MULTI_QUERY_PROMPT
+    
+    def generate(self, query: str) -> List[str]:
+        """同步生成多个查询变体"""
+        prompt_str = self.prompt.format(num_queries=self.num_queries, question=query)
+        response = self.llm.invoke(prompt_str)
+        # 处理响应内容，按行分割并去除空行和首尾空白
+        lines = response.content.strip().split('\n')
+        queries = [line.strip() for line in lines if line.strip()]
+        # 确保至少返回原始查询
+        return queries[:self.num_queries] if queries else [query]
+    
+    async def agenerate(self, query: str) -> List[str]:
+        """异步生成多个查询变体"""
+        prompt_str = self.prompt.format(num_queries=self.num_queries, question=query)
+        response = await self.llm.ainvoke(prompt_str)
+        lines = response.content.strip().split('\n')
+        queries = [line.strip() for line in lines if line.strip()]
+        return queries[:self.num_queries] if queries else [query]

backend/app/rag/reranker.py

@@ -0,0 +1,75 @@
+"""
+重排序器模块 (适配版)
+使用远程 llama.cpp 服务 (兼容 OpenAI Rerank API) 替代本地 Cross-Encoder
+"""
+import requests
+from typing import List
+from langchain_core.documents import Document
+
+class LLaMaCPPReranker:
+    """使用远程 llama.cpp 服务对检索结果重排序。"""
+
+    def __init__(self, 
+                 base_url: str, 
+                 api_key: str,
+                 top_n: int = 5,
+                 timeout: int = 60):
+        """
+        初始化远程重排序器
+        
+        Args:
+            base_url: llama.cpp 服务的地址和端口，默认为环境变量 LLAMACPP_RERANKER_URL 或 "http://127.0.0.1:8083"。
+            top_n: 返回前 N 个结果。
+            api_key: API 密钥，默认为环境变量 LLAMACPP_API_KEY 或 "huang1998"。
+            timeout: 请求超时时间（秒）。
+        """
+        self.base_url = base_url 
+        self.api_key = api_key 
+        self.top_n = top_n
+        self.timeout = timeout
+        self.endpoint = f"{self.base_url}/rerank"
+        
+    def compress_documents(
+        self, documents: List[Document], query: str
+    ) -> List[Document]:
+        """
+        对文档进行重排序
+        
+        Args:
+            documents: 待排序的文档列表
+            query: 查询字符串
+        
+        Returns:
+            排序后的文档列表
+        """
+        if not documents:
+            return []
+
+        # 准备请求体
+        # 根据 llama.cpp 的 OpenAI 兼容性，文档是一个字符串列表
+        payload = {
+            "model": "bge-reranker-v2-m3",
+            "query": query,
+            "documents": [doc.page_content for doc in documents],
+            "top_n": self.top_n
+        }
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}"
+        }
+
+        try:
+            response = requests.post(self.endpoint, json=payload, headers=headers, timeout=self.timeout)
+            response.raise_for_status()  # 检查请求是否成功
+            results = response.json()
+            
+            # 解析返回结果
+            # 返回格式: {"results": [{"index": 0, "document": "...", "relevance_score": 0.8}, ...]}
+            # 按相关性得分降序排列
+            sorted_indices = [item["index"] for item in results["results"]]
+            sorted_docs = [documents[idx] for idx in sorted_indices]
+            return sorted_docs
+            
+        except Exception as e:
+            print(f"警告: 远程重排序过程出错，将使用原始排序。错误: {e}")
+            return documents[:self.top_n]

backend/app/rag/retriever.py

@@ -0,0 +1,199 @@
+"""
+Qdrant 向量检索器模块
+
+提供基于 Qdrant 的基础向量检索和混合检索（Dense + Sparse）功能。
+
+核心原理：
+- 基础检索：将查询文本转换为向量，在 Qdrant 中进行近似最近邻（ANN）搜索，
+  使用余弦相似度返回最相似的 k 个文档。
+- 混合检索：结合稠密向量检索（语义相似）和 BM25 稀疏向量检索（关键词匹配），
+  通过加权或分数融合提高召回精度。
+
+使用示例：
+    >>> from rag_core import LlamaCppEmbedder
+    >>> embedder = LlamaCppEmbedder()
+    >>> embeddings = embedder.as_langchain_embeddings()
+    >>>
+    >>> # 创建基础检索器
+    >>> retriever = create_base_retriever(
+    ...     collection_name="my_docs",
+    ...     embeddings=embeddings,
+    ...     search_kwargs={"k": 10}
+    ... )
+    >>>
+    >>> # 执行检索
+    >>> docs = retriever.invoke("什么是 RAG？")
+"""
+
+from typing import Optional, Dict, Any
+from qdrant_client import QdrantClient
+from qdrant_client.http.exceptions import UnexpectedResponse
+from langchain_qdrant import QdrantVectorStore
+from langchain_core.embeddings import Embeddings
+from langchain_core.retrievers import BaseRetriever
+
+from rag_core import QDRANT_URL, QDRANT_API_KEY
+
+# 模块级常量
+DEFAULT_SEARCH_K = 20
+DEFAULT_SCORE_THRESHOLD = 0.3
+
+
+def create_qdrant_client(
+    url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    timeout: int = 30,
+) -> QdrantClient:
+    """
+    创建并返回一个配置好的 Qdrant 客户端。
+
+    优先使用传入参数，若未提供则回退到环境变量 QDRANT_URL 和 QDRANT_API_KEY。
+
+    Args:
+        url: Qdrant 服务地址，例如 "http://localhost:6333"。
+             默认从环境变量 QDRANT_URL 读取。
+        api_key: API 密钥（若 Qdrant 启用了认证）。
+                 默认从环境变量 QDRANT_API_KEY 读取。
+        timeout: 请求超时时间（秒），默认 30 秒。
+
+    Returns:
+        配置好的 QdrantClient 实例。
+
+    Raises:
+        ValueError: 如果 url 为空且环境变量也未设置。
+    """
+    effective_url = url or QDRANT_URL
+    if not effective_url:
+        raise ValueError(
+            "Qdrant URL 未提供，请设置参数 url 或环境变量 QDRANT_URL"
+        )
+
+    effective_api_key = api_key or QDRANT_API_KEY
+
+    client_kwargs = {
+        "url": effective_url,
+        "timeout": timeout,
+    }
+    if effective_api_key:
+        client_kwargs["api_key"] = effective_api_key
+
+    return QdrantClient(**client_kwargs)
+
+
+def create_base_retriever(
+    collection_name: str,
+    embeddings: Embeddings,
+    search_kwargs: Optional[Dict[str, Any]] = None,
+    client: Optional[QdrantClient] = None,
+) -> BaseRetriever:
+    """
+    创建基础向量检索器（仅稠密向量检索）。
+
+    该检索器使用嵌入模型将查询转为向量，在 Qdrant 集合中执行 ANN 搜索，
+    返回语义上最相似的文档块。
+
+    Args:
+        collection_name: Qdrant 集合名称（需预先创建并索引）。
+        embeddings: LangChain 兼容的嵌入模型实例。
+        search_kwargs: 搜索参数，可包含：
+            - k (int): 返回的文档数量，默认 20。
+            - score_threshold (float): 相似度阈值，仅返回高于此分数的文档。
+            - filter (dict): Qdrant 过滤条件。
+            若为 None，则使用默认值 {"k": 20}。
+        client: 可选的 Qdrant 客户端实例。若未提供，将自动创建。
+
+    Returns:
+        BaseRetriever 实例，可直接调用 .invoke(query) 或 .ainvoke(query) 检索。
+
+    Raises:
+        ValueError: 如果集合不存在或嵌入模型无效。
+    """
+    # 合并默认搜索参数
+    merged_search_kwargs = {"k": DEFAULT_SEARCH_K}
+    if search_kwargs:
+        merged_search_kwargs.update(search_kwargs)
+
+    # 创建或复用 Qdrant 客户端
+    if client is None:
+        client = create_qdrant_client()
+
+    # 验证集合是否存在（可选，便于提前发现问题）
+    try:
+        client.get_collection(collection_name)
+    except UnexpectedResponse as e:
+        if e.status_code == 404:
+            raise ValueError(
+                f"Qdrant 集合 '{collection_name}' 不存在，请先创建并索引文档。"
+            )
+        raise
+
+    # 构建向量存储
+    vector_store = QdrantVectorStore(
+        client=client,
+        collection_name=collection_name,
+        embedding=embeddings,
+    )
+
+    # 返回检索器
+    return vector_store.as_retriever(search_kwargs=merged_search_kwargs)
+
+
+def create_hybrid_retriever(
+    collection_name: str,
+    embeddings: Embeddings,
+    dense_k: int = 10,
+    sparse_k: int = 10,
+    score_threshold: Optional[float] = DEFAULT_SCORE_THRESHOLD,
+    client: Optional[QdrantClient] = None,
+) -> BaseRetriever:
+    """
+    创建混合检索器（稠密向量 + BM25 稀疏向量）。
+
+    混合检索结合了语义相似度（Dense）和关键词匹配（Sparse），
+    能够更好地处理专有名词、精确匹配等场景。
+
+    注意：此功能要求 Qdrant 集合已配置稀疏向量字段并生成了 BM25 索引。
+    若集合未配置稀疏向量，将回退到纯稠密检索（不会报错，但检索效果降级）。
+
+    Args:
+        collection_name: Qdrant 集合名称。
+        embeddings: 嵌入模型（用于稠密向量）。
+        dense_k: 稠密向量检索返回数量，默认 10。
+        sparse_k: 稀疏向量检索返回数量，默认 10。
+        score_threshold: 相似度阈值，默认 0.3。
+        client: 可选的 Qdrant 客户端实例。
+
+    Returns:
+        BaseRetriever 实例，配置了混合搜索参数。
+    """
+    total_k = dense_k + sparse_k
+
+    search_kwargs = {
+        "k": total_k,
+    }
+    if score_threshold is not None:
+        search_kwargs["score_threshold"] = score_threshold
+
+    # 复用基础检索器创建逻辑，只需调整搜索参数
+    return create_base_retriever(
+        collection_name=collection_name,
+        embeddings=embeddings,
+        search_kwargs=search_kwargs,
+        client=client,
+    )
+
+
+# 可选：提供异步友好的辅助函数
+async def acreate_base_retriever(
+    collection_name: str,
+    embeddings: Embeddings,
+    search_kwargs: Optional[Dict[str, Any]] = None,
+    client: Optional[QdrantClient] = None,
+) -> BaseRetriever:
+    """
+    异步创建基础向量检索器（与同步版本功能相同）。
+
+    适用于需要异步初始化的场景（例如在 FastAPI 启动事件中）。
+    """
+    # 由于 QdrantVectorStore 初始化本身是同步的，这里直接调用同步版本即可
+    return create_base_retriever(collection_name, embeddings, search_kwargs, client)

backend/app/rag/test.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+RAG 系统使用示例（重构版）
+
+演示：
+1. 使用 IndexBuilder 获取父子块检索器
+2. 创建固定流程的 RAGPipeline（多路改写 → RRF融合 → 重排序 → 返回父文档）
+3. 将流水线封装为 LangChain 工具，供 Agent 调用
+"""
+
+import asyncio
+import sys
+import os
+
+from dotenv import load_dotenv
+
+# 加载环境变量（Qdrant URL、PostgreSQL 连接等）
+load_dotenv()
+
+# 添加项目根目录到路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../.."))
+
+from rag_indexer.index_builder import IndexBuilderConfig
+from rag_indexer.splitters import SplitterType
+from .pipeline import RAGPipeline
+from .tools import create_rag_tool_sync
+from pydantic import SecretStr
+# 使用本地 LLM（通过 OpenAI 兼容接口）
+from langchain_openai import ChatOpenAI
+from rag_core.retriever_factory import create_parent_retriever
+
+load_dotenv()
+
+def create_llm():
+        """创建本地 vLLM 服务 LLM"""
+        vllm_base_url = os.getenv(
+            "VLLM_BASE_URL",
+            "http://127.0.0.1:8081/v1"
+        )
+        
+        return ChatOpenAI(
+            base_url=vllm_base_url,
+            api_key=SecretStr(os.getenv("LLAMACPP_API_KEY", "token-abc123")),
+            model="gemma-4-E2B-it",
+            timeout=60.0,          # 请求超时时间（秒）
+            max_retries=2,          # 失败后自动重试次数
+            streaming=True,         # 确保开启流式输出
+        )
+
+async def demonstrate_full_pipeline():
+    """
+    完整流水线演示：
+    - 从 IndexBuilder 获取 ParentDocumentRetriever
+    - 创建 RAGPipeline
+    - 执行检索并打印结果
+    """
+    print("=" * 60)
+    print("演示：固定流程 RAG 检索（多路改写 + RRF + 重排序 + 父文档）")
+    print("=" * 60)
+
+    retriever = create_parent_retriever(collection_name="rag_documents", search_k=5)
+
+    if retriever is None:
+        print("错误：检索器未初始化，请确保索引已构建。")
+        return
+
+    # 3. 创建 LLM 用于查询改写
+    llm = create_llm()
+
+    # 4. 创建 RAGPipeline（固定流程）
+    pipeline = RAGPipeline(
+        retriever=retriever,
+        llm=llm,
+        num_queries=3,          # 生成 3 个查询变体
+        rerank_top_n=5,         # 最终返回 5 个父文档
+    )
+
+    # 5. 执行检索
+    query = "打虎英雄是谁？"
+    print(f"\n查询: {query}")
+    print("-" * 40)
+
+    try:
+        documents = await pipeline.aretrieve(query)
+        print(f"返回 {len(documents)} 个父文档\n")
+
+        # 打印结果预览
+        for i, doc in enumerate(documents, 1):
+            content_preview = doc.page_content.replace("\n", " ")[:150]
+            source = doc.metadata.get("source", "未知来源")
+            print(f"{i}. 【来源：{source}】")
+            print(f"   {content_preview}...\n")
+
+        # 可选：格式化完整上下文
+        # context = pipeline.format_context(documents)
+        # print(context)
+
+    except Exception as e:
+        print(f"检索失败: {e}")
+        import traceback
+        traceback.print_exc()
+
+async def demonstrate_tool_creation():
+    """
+    演示创建 RAG 工具（供 Agent 使用）
+    """
+    print("\n" + "=" * 60)
+    print("演示：创建 RAG 工具（供 LangGraph Agent 调用）")
+    print("=" * 60)
+
+    # 1. 获取检索器（同上）
+    config = IndexBuilderConfig(
+        collection_name="rag_documents",
+        splitter_type=SplitterType.PARENT_CHILD,
+    )
+    retriever = retriever = create_parent_retriever(collection_name="rag_documents", search_k=5)
+
+    # 2. 创建 LLM
+    llm = create_llm()
+
+    # 3. 创建工具
+    rag_tool = create_rag_tool_sync(
+        retriever=retriever,
+        llm=llm,
+        num_queries=3,
+        rerank_top_n=5,
+        collection_name="rag_documents",
+    )
+
+    print(f"工具名称: {rag_tool.name}")
+    print(f"工具描述: {rag_tool.description[:100]}...")
+
+    # 4. 模拟 Agent 调用工具
+    query = "请告诉我 打虎英雄是谁？"
+    print(f"\n模拟调用: {query}")
+    print("-" * 40)
+
+    result = await rag_tool.ainvoke({"query": query})
+    print(result[:800] + "..." if len(result) > 800 else result)
+
+async def main():
+    await demonstrate_full_pipeline()
+    await demonstrate_tool_creation()
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/app/rag/tools.py

@@ -0,0 +1,54 @@
+"""
+RAG 工具模块
+
+将检索功能封装为 LangChain Tool，供 Agent 调用。
+采用固定流水线：多路改写 → 并行检索 → RRF 融合 → 重排序 → 返回父文档。
+"""
+from typing import Callable
+from langchain_core.tools import tool
+from langchain_core.language_models import BaseLanguageModel
+from langchain_core.retrievers import BaseRetriever
+from .pipeline import RAGPipeline
+
+def create_rag_tool_sync(
+    retriever: BaseRetriever,
+    llm: BaseLanguageModel,
+    num_queries: int = 3,
+    rerank_top_n: int = 5,
+    collection_name: str = "rag_documents",
+) -> Callable:
+    """
+    创建一个配置好的 RAG 检索工具（同步版本，用于不支持异步的旧版 Agent）。
+
+    参数同 create_rag_tool。
+    """
+    pipeline = RAGPipeline(
+        retriever=retriever,
+        llm=llm,
+        num_queries=num_queries,
+        rerank_top_n=rerank_top_n,
+    )
+
+    @tool
+    def search_knowledge_base_sync(query: str) -> str:
+        """在知识库中搜索与查询相关的文档片段（同步版本）。
+
+        功能与异步版本相同：多路改写 → RRF融合 → 重排序 → 返回父文档。
+
+        Args:
+            query: 用户提出的问题或查询字符串
+
+        Returns:
+            格式化后的相关文档内容。
+        """
+        try:
+            documents = pipeline.retrieve(query)  # 内部调用异步方法并等待
+            if not documents:
+                return f"在知识库 '{collection_name}' 中未找到与 '{query}' 相关的信息。"
+
+            context = pipeline.format_context(documents)
+            return context
+        except Exception as e:
+            return f"检索过程中发生错误: {str(e)}"
+
+    return search_knowledge_base_sync