✨ 使用 Qdrant 原生混合检索功能

- 用 langchain-qdrant 的 RetrievalMode.HYBRID
- 自动检测 Qdrant 集合是否有 sparse_vectors_config
- 有则用 Qdrant 原生混合检索，无则优雅回退纯稠密
- 接口完全兼容，0 改动现有代码
- 语法检查通过

backend/app/rag/retriever.py

@@ -1,12 +1,13 @@
 """
 Qdrant 向量检索器模块
 
-提供基于 Qdrant 的基础向量检索和混合检索（Dense + BM25）功能。
+提供基于 Qdrant 的基础向量检索和混合检索（Dense + Sparse）功能。
 
 核心原理：
-- 同时调用 Qdrant 稠密检索（语义理解）和 BM25Retriever（关键词匹配）
+- 使用 langchain-qdrant 的 RetrievalMode
-- 结果合并去重，获得更好的检索效果
+- Qdrant 原生混合检索（如果集合已配置 sparse_vectors）
-- 完全兼容现有代码，无需修改 Qdrant 集合配置
+- 如果集合未配置，优雅回退到纯稠密检索
+- 完全兼容现有代码，无接口改动
 
 使用示例：
     >>> from app.rag.retriever import create_hybrid_retriever
@@ -14,14 +15,15 @@ Qdrant 向量检索器模块
     >>> docs = retriever.invoke("什么是 RAG？")
 """
 
-from typing import Dict, Any, Optional, List
+from typing import Dict, Any, Optional
 from qdrant_client import QdrantClient
 from qdrant_client.http.exceptions import UnexpectedResponse
-from langchain_qdrant import QdrantVectorStore
+from langchain_qdrant import (
+    QdrantVectorStore,
+    RetrievalMode,
+)
 from langchain_core.embeddings import Embeddings
 from langchain_core.retrievers import BaseRetriever
-from langchain_core.documents import Document
-from langchain_community.retrievers import BM25Retriever
 
 from rag_core import QDRANT_URL, QDRANT_API_KEY
 from rag_core.client import create_qdrant_client as create_core_qdrant_client
@@ -93,17 +95,17 @@ def create_hybrid_retriever(
     embeddings: Embeddings | None = None,
 ) -> BaseRetriever:
     """
-    创建混合检索器（稠密向量 + BM25 稀疏向量）。
+    创建混合检索器（使用 Qdrant 自身的 RetrievalMode.HYBRID）。
 
-    ⚡️ 真实实现：
+    ⚡️ Qdrant 原生混合检索：
-    - 同时调用 Qdrant 稠密检索（语义理解）和 BM25Retriever（关键词匹配）
+    - 如果 Qdrant 集合已配置 sparse_vectors：启用 Qdrant 原生混合检索
-    - 结果合并去重，获得更好的检索效果
+    - 如果未配置：优雅回退到纯稠密检索
-    - 完全兼容现有代码，无需修改 Qdrant 集合配置
+    - 完全兼容现有代码，接口不变
 
     Args:
         collection_name: Qdrant 集合名称。
         dense_k: 稠密向量检索返回数量，默认 10。
-        sparse_k: BM25 检索返回数量，默认 10。
+        sparse_k: 稀疏向量检索返回数量，默认 10。
         score_threshold: 相似度阈值，默认 0.3。
         client: 可选的 Qdrant 客户端实例。
         embeddings: 可选的嵌入模型实例。若未提供，将自动获取统一嵌入服务。
@@ -111,62 +113,66 @@ def create_hybrid_retriever(
     Returns:
         BaseRetriever 实例，配置了混合搜索参数。
     """
-    # 创建基础稠密检索器
+    total_k = dense_k + sparse_k
-    dense_retriever = create_base_retriever(
-        collection_name=collection_name,
-        search_kwargs={"k": dense_k, "score_threshold": score_threshold},
-        client=client,
-        embeddings=embeddings,
-    )
 
-    # 从 Qdrant 加载所有文档到 BM25Retriever
+    search_kwargs = {
-    bm25_retriever = None
+        "k": total_k,
+        "search_type": "similarity_score_threshold",
+        "score_threshold": score_threshold,
+    }
+
+    # 默认使用统一嵌入服务（已内置降级机制）
+    if embeddings is None:
+        embeddings = get_embedding_service()
+        info("✅ 使用统一嵌入服务（本地 llama.cpp → 智谱 API 自动降级）")
+
+    # 创建或复用 Qdrant 客户端
     if client is None:
         client = create_core_qdrant_client()
 
+    # 验证集合是否存在
     try:
-        # 尝试从 Qdrant 加载少量样本文档（用于演示 BM25）
+        client.get_collection(collection_name)
-        # 实际使用中，建议从外部加载完整文档列表
+    except UnexpectedResponse as e:
-        from langchain_core.vectorstores import VectorStoreRetriever
+        if e.status_code == 404:
-        vector_store = getattr(dense_retriever, 'vectorstore', None)
+            warning(f"⚠️ Qdrant 集合 '{collection_name}' 不存在，请先创建并索引文档")
-        
+            raise ValueError(f"Qdrant 集合 '{collection_name}' 不存在")
-        # 这里我们做一个简单的混合：先返回稠密结果，提示说明这是真实混合检索框架
+        raise
-        # 如果需要加载完整文档进行 BM25，请提供 bm25_documents 参数
-        
-        class HybridRetriever(BaseRetriever):
-            def __init__(
-                self,
-                dense_retriever: BaseRetriever,
-                dense_k: int = 10,
-                sparse_k: int = 10,
-            ):
-                self.dense_retriever = dense_retriever
-                self.dense_k = dense_k
-                self.sparse_k = sparse_k
-
-            def _get_relevant_documents(
-                self,
-                query: str,
-                *,
-                run_manager: Optional[Any] = None,
-            ) -> List[Document]:
-                # 获取稠密检索结果
-                dense_docs = self.dense_retriever._get_relevant_documents(query, run_manager=run_manager)
-                
-                info(f"✅ 混合检索框架已启用，当前使用稠密检索（{len(dense_docs)} 个结果）")
-                info(f"ℹ️ 若要启用完整 BM25 关键词检索，请提供 bm25_documents 参数")
-                
-                return dense_docs
-
-        return HybridRetriever(
-            dense_retriever=dense_retriever,
-            dense_k=dense_k,
-            sparse_k=sparse_k,
-        )
 
+    # 检查 Qdrant 集合是否有稀疏向量配置
+    sparse_available = False
+    try:
+        collection_info = client.get_collection(collection_name)
+        if hasattr(collection_info, 'config'):
+            params = collection_info.config.params
+            if hasattr(params, 'sparse_vectors') and params.sparse_vectors:
+                sparse_available = True
+                info("✅ 检测到 Qdrant 集合有稀疏向量配置，启用 Qdrant 原生混合检索")
     except Exception as e:
-        warning(f"⚠️ 初始化 BM25Retriever 失败: {e}，回退到纯稠密检索")
+        warning(f"⚠️ 检查 Qdrant 集合稀疏向量配置失败: {e}")
-        return dense_retriever
+
+    # 如果有稀疏向量配置，用 Qdrant 原生混合检索
+    if sparse_available:
+        try:
+            vector_store = QdrantVectorStore(
+                client=client,
+                collection_name=collection_name,
+                embedding=embeddings,
+                retrieval_mode=RetrievalMode.HYBRID,
+            )
+            info(f"✅ Qdrant 原生混合检索器初始化成功 (k={total_k})")
+            return vector_store.as_retriever(search_kwargs=search_kwargs)
+        except Exception as e:
+            warning(f"⚠️ Qdrant 原生混合检索初始化失败: {e}，回退到纯稠密检索")
+
+    # 如果没有稀疏向量配置，回退到纯稠密检索
+    info("ℹ️ Qdrant 集合未配置稀疏向量，使用纯稠密检索（完全兼容）")
+    return create_base_retriever(
+        collection_name=collection_name,
+        search_kwargs=search_kwargs,
+        client=client,
+        embeddings=embeddings,
+    )
 
 
 # 可选：提供异步友好的辅助函数

backend/requirements.txt

@@ -18,7 +18,6 @@ zhipuai==2.0.1
 
 # Vector DB
 qdrant-client==1.17.1
-fastembed>=0.3.0  # 用于 Qdrant BM25 稀疏向量
 
 # Memory
 mem0ai==1.0.11