refactor!: 完全异步化 RAG 系统，移除 LangChain ParentDocumentRetriever 依赖

- 重写 rag_core/vector_store.py：完全异步实现 aadd_documents、asimilarity_search - 重写 app/rag/retriever.py：异步混合检索，移除同步兼容代码 - 修改 rag_indexer/index_builder.py：全链路异步调用 - 删除 rag_core/retriever_factory.py：不再使用 LangChain ParentDocumentRetriever - 清理冗余导入和代码：移除 model_services 兼容、不需要的异常导入 - 更新 rag_indexer/README.md：反映新架构核心改进： - 完全异步化：索引构建和检索全链路 async/await - 自定义实现：不再依赖 LangChain 的 ParentDocumentRetriever - 双向量支持：子文档同时存储 dense + sparse 向量到 Qdrant - 架构清晰：rag_core 公共组件、rag_indexer 索引、app/rag 检索
2026-05-04 14:33:12 +08:00
parent 4209386c77
commit a07e398739
14 changed files with 651 additions and 592 deletions
--- a/rag_indexer/README.md
+++ b/rag_indexer/README.md
@@ -11,10 +11,11 @@
 | **文档解析** | `unstructured` | 0.22+ | 多格式文档解析（PDF/DOCX/TXT等） |
 | **文本切分** | `langchain-text-splitters` | 内置 | 递归字符切分 + 语义切分 |
 | **语义切分** | `langchain-experimental` | 内置 | `SemanticChunker` 基于句子相似度 |
-| **嵌入模型** | `llama.cpp` | 本地服务 | `embeddinggemma-300M` GGUF 模型 |
-| **向量数据库** | `Qdrant` | 1.17+ | HNSW 索引，支持稠密/稀疏向量 |
+| **嵌入模型** | `llama.cpp` | 本地服务 | `Qwen3-Embedding-0.6B` GGUF 模型 |
+| **稀疏嵌入** | `fastembed` | 内置 | BM25 关键词检索 |
+| **向量数据库** | `Qdrant` | 1.17+ | HNSW 索引，支持稠密/稀疏向量 + RRF 融合 |
 | **文档存储** | `PostgreSQL` | 16+ | 异步连接池，持久化父块 |
-| **编排框架** | `asyncio` | Python 3.10+ | 异步批量处理与重试 |
+| **编排框架** | `asyncio` | Python 3.10+ | 全异步批量处理 |

 ### 数据流向总览

@@ -33,27 +34,28 @@
                       │
                       ▼
 ┌─────────────────────────────────────────────────────────────┐
-│              ParentDocumentRetriever                         │
+│           自定义父子块索引实现                                │
 │  ┌─────────────────────────────────────────────────────┐    │
 │  │              parent_splitter (粗切)                  │    │
 │  │              父块 ~1000 字符                         │    │
 │  └──────────────────────┬──────────────────────────────┘    │
 │                         │                                    │
 │  ┌──────────────────────▼──────────────────────────────┐    │
+│  │     父文档存入 PostgreSQL (UUID 映射)               │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│  ┌──────────────────────▼──────────────────────────────┐    │
 │  │              child_splitter (细切)                   │    │
 │  │              子块 ~200 字符                          │    │
 │  └──────────────────────┬──────────────────────────────┘    │
 │                         │                                    │
-│           ┌─────────────┴─────────────┐                      │
-│           ▼                           ▼                      │
-│     ┌─────────────┐           ┌─────────────────┐            │
-│     │ 子块向量     │           │ 父块原始内容     │            │
-│     │             │           │                 │            │
-│     ▼             │           ▼                 │            │
-│  ┌────────────┐   │      ┌─────────────────┐   │            │
-│  │vector_store│   │      │    store/       │   │            │
-│  │  (Qdrant)  │   │      │  (PostgreSQL)   │   │            │
-│  └────────────   │      └─────────────────┘   │            │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │  子文档生成 dense + sparse 双向量                   │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │  子文档存入 Qdrant (payload 含 parent_id)           │    │
+│  └─────────────────────────────────────────────────────┘    │
 └─────────────────────────────────────────────────────────────┘
 ```

@@ -63,7 +65,9 @@
 - ✅ **三种切分策略**：递归字符切分、语义切分、父子块策略
 - ✅ **Parent-Child 架构**：子块精准检索，父块完整上下文
 - ✅ **PostgreSQL DocStore**：持久化存储父块，支持异步连接池
- ✅ **批量写入与重试**：自动处理网络波动，确保索引完整性
+- ✅ **混合检索**：稠密向量（语义）+ 稀疏向量（关键词），Qdrant 原生 RRF 融合
+- ✅ **完全异步化**：索引构建、检索全链路 async / await
+- ✅ **批量写入**：高效批量处理，自动分批
 - ✅ **上下文管理器**：支持同步/异步资源管理

 ## 📂 架构与文件结构
@@ -71,17 +75,26 @@
 ```
 rag_indexer/
 ├── __init__.py
-├── cli.py                 # 命令行入口
-├── index_builder.py       # 索引构建主流水线
+├── index_builder.py       # 索引构建主流水线（自定义父子块实现）
 ├── loaders.py             # 文档加载器（多格式支持）
 ├── splitters.py           # 文本切分器（递归/语义/父子块）
+└── README.md              # 本文档
+```
+
+```
+backend/rag_core/
+├── __init__.py
+├── vector_store.py        # Qdrant 混合存储（异步）
+├── sparse_embedder.py     # BM25 稀疏嵌入
 ├── embedders.py           # 嵌入模型封装
-├── vector_store.py        # Qdrant 向量存储
-├── store/
-│   ├── __init__.py
-│   ├── factory.py         # DocStore 工厂函数
-│   └── postgres.py        # PostgreSQL DocStore 实现
-└── test/                  # 测试脚本
+├── store.py               # PostgreSQL 文档存储
+├── client.py              # Qdrant 同步/异步客户端工厂
+└── config.py              # 配置管理
+```
+
+```
+backend/app/rag/
+└── retriever.py           # 混合检索器（异步）
 ```

 ## 🎯 演进路线与核心算法 (Roadmap)
@@ -133,26 +146,30 @@ chunks = chunker.split_documents(documents)

 ### Level 3: 高级父子块策略 (Parent-Child / Auto-merging)

- **核心算法**: 层次化双重存储与映射。
+- **核心算法**: 层次化双重存储与映射（自定义实现）。
  - **切分机制**: 首先将文档粗切为较大的"父块 (Parent Chunk, 约 1000 字符)"，随后将父块细切为较小的"子块 (Child Chunk, 约 200 字符)"
-  - **存储机制**: 仅仅将**子块**的向量存入 Qdrant 用于精准计算距离；将**父块**的原始内容存在 PostgreSQL DocStore 中，通过 UUID 相互映射
+  - **存储机制**: 
+    - **子块**: 存入 Qdrant，同时生成 dense 向量（语义）和 sparse 向量（关键词），payload 中包含 `parent_id`
+    - **父块**: 存入 PostgreSQL，通过 UUID 与子块映射
 - **核心思路**: 解决 RAG 领域经典的矛盾——检索时块越小越容易精确命中（去除噪声）；但生成回答时，块越大越能给大模型提供充足的上下文背景。
- **实现指南**:
-  - 使用 `langchain_classic.retrievers` 中的 `ParentDocumentRetriever` 模块
-  - 在写入时，需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore`
-  - **推荐方案**: 使用 `PostgresDocStore` 作为 docstore，支持持久化存储
-  - 将两种不同的 `TextSplitter` 分别赋值给检索器的 `child_splitter` 和 `parent_splitter`，然后调用 `.add_documents()` 即可让系统自动完成映射
+- **实现**：
+  - 完全自定义实现，不依赖 LangChain 的 `ParentDocumentRetriever`
+  - 支持异步批量写入
+  - 支持双向量混合检索

 ```python
-from langchain.retrievers import ParentDocumentRetriever
+from rag_indexer.index_builder import IndexBuilder, IndexBuilderConfig
+from rag_indexer.splitters import SplitterType

-retriever = ParentDocumentRetriever(
-    vectorstore=qdrant_store,
-    docstore=postgres_docstore,
-    parent_splitter=parent_splitter,
-    child_splitter=child_splitter,
+config = IndexBuilderConfig(
+    collection_name="rag_documents",
+    splitter_type=SplitterType.PARENT_CHILD,
+    parent_chunk_size=1000,
+    child_chunk_size=200,
 )
-await retriever.aadd_documents(documents)
+
+builder = IndexBuilder(config)
+await builder.build_from_file("document.pdf")
 ```

 ### Level 3.1: PostgreSQL DocStore 集成
@@ -191,11 +208,232 @@ config = IndexBuilderConfig(
    child_chunk_size=200,
    child_splitter_type=SplitterType.SEMANTIC,  # 子块使用语义切分
    docstore=DocstoreConfig(
-        connection_string="postgresql://user:pass@host:5432/db",
+        connection_string="postgresql://user:***@host:5432/db",
    ),
 )
 ```

+### Level 3.3: 混合检索架构（稠密 + 稀疏）
+
+- **核心算法**: Qdrant 原生双向量存储 + RRF 分数融合
+  - **稠密向量 (Dense)**: 语义相似度检索，捕捉深层含义
+  - **稀疏向量 (Sparse)**: BM25 关键词检索，精确匹配术语
+  - **RRF 融合 (Reciprocal Rank Fusion)**: 服务端分数融合，无需客户端后处理
+- **核心思路**: 结合语义理解和关键词匹配的双重优势，大幅提升召回率
+- **实现原理**:
+  - 每个子文档同时生成 dense 向量和 sparse 向量
+  - 使用 Qdrant 的 `query_points` API + `Prefetch` 并行检索
+  - 通过 `FusionQuery` 自动进行 RRF 分数融合
+
+```python
+from app.rag.retriever import create_parent_hybrid_retriever
+
+# 创建父子文档混合检索器
+retriever = create_parent_hybrid_retriever(
+    collection_name="rag_documents",
+    search_k=5
+)
+
+# 异步检索相关文档
+docs = await retriever.ainvoke("用户查询")
+```
+
+---
+
+## 📦 存储结构详解
+
+### 整体数据流向
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │           原始文档                        │
+                    │      (Document + Metadata)              │
+                    └───────────────┬─────────────────────────┘
+                                    │ 切分
+                    ┌───────────────▼─────────────────────────┐
+                    │      父文档块 (Parent Chunks)            │
+                    │   大粒度：1000-2000字符/块               │
+                    │   存：PostgreSQL JSONB                  │
+                    └───────────────┬─────────────────────────┘
+                                    │ 再切分
+                    ┌───────────────▼─────────────────────────┐
+                    │      子文档块 (Child Chunks)             │
+                    │   小粒度：200-400字符/块                 │
+                    │   存：Qdrant (稠密+稀疏双向量)           │
+                    └─────────────────────────────────────────┘
+```
+
+---
+
+### PostgreSQL 存储结构（父文档）
+
+#### 表结构
+
+```sql
+CREATE TABLE parent_documents (
+    key TEXT PRIMARY KEY,
+    value JSONB NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+#### 数据格式（JSONB）
+
+```json
+{
+    "page_content": "这是一个父文档块，包含完整的上下文信息，用于最终给 LLM 生成回答...",
+    "metadata": {
+        "source": "file_name.pdf",
+        "page": 10,
+        "chunk_id": "parent-12345",
+        "timestamp": "2024-05-04T12:34:56Z"
+    }
+}
+```
+
+---
+
+### Qdrant 存储结构（子文档）
+
+#### 集合配置
+
+```python
+vectors_config = {
+    "dense": VectorParams(
+        size=2048,  # 或 1024、4096，取决于嵌入模型
+        distance=Distance.COSINE
+    )
+}
+
+sparse_vectors_config = {
+    "sparse": SparseVectorParams()
+}
+```
+
+#### 点结构（Point）
+
+```json
+{
+    "id": "child-12345",
+    "vector": {
+        "dense": [0.123, 0.456, ...],
+        "sparse": {
+            "indices": [10, 50, 234, ...],
+            "values": [0.8, 0.5, 0.3, ...]
+        }
+    },
+    "payload": {
+        "text": "这是一个子文档块，用于检索...",
+        "parent_id": "parent-12345",
+        "source": "file_name.pdf",
+        "page": 10,
+        "chunk_index": 0
+    }
+}
+```
+
+---
+
+## 🔄 完整数据流
+
+### 索引构建阶段
+
+```
+原始文档
+    ↓
+切分为父块（1000字符/块）
+    ↓
+为每个父块分配唯一 ID (parent_id)
+    ↓
+存父块到 PostgreSQL (key=parent_id, value=Document)
+    ↓
+每个父块再切分为子块（200字符/块）
+    ↓
+为每个子块生成：
+  - dense 向量
+  - sparse 向量
+  - payload 中加入 parent_id
+    ↓
+存子块到 Qdrant
+```
+
+### 检索阶段
+
+```
+用户查询
+    ↓
+生成查询的 dense + sparse 向量
+    ↓
+Qdrant 混合检索（RRF 分数融合）
+    ↓
+得到相关子文档列表
+    ↓
+收集子文档的 parent_id（去重）
+    ↓
+用 parent_id 批量查询 PostgreSQL
+    ↓
+得到完整的父文档
+    ↓
+返回给 LLM
+```
+
+---
+
+## 📊 存储消耗分析（估算）
+
+假设我们有 **100 个 PDF 文档，平均每个文档 100,000 字符**，总字符数 10,000,000。
+
+| 存储类型 | 数量 | 单条大小 | 总大小 |
+|---------|------|---------|--------|
+| **PostgreSQL 父文档** | ~10,000 块 | 1KB (text) + 0.5KB (metadata) | **15MB** |
+| **Qdrant 子文档** | ~50,000 块 | 见下文 | **~450-500MB** |
+
+### Qdrant 单条子文档详细分解
+
+| 项 | 说明 | 大小 |
+|---|-------|------|
+| dense 向量 | float32[2048] | 8,192 bytes (~8KB) |
+| sparse 向量 | 平均 50-100 非零维 | 400-800 bytes |
+| payload | 子文本 + metadata | 200-500 bytes |
+| **合计** | | **~9-10KB / 条** |
+
+对于 50,000 条子文档：**~450-500MB**
+
+---
+
+## ⚡ 优化策略
+
+### 1. 分层存储
+
+- **热数据（频繁访问）**：父文档 + 子文档都在 Qdrant（更快）
+- **冷数据（不常访问）**：父文档在 PostgreSQL，子文档在 Qdrant（更省）
+
+### 2. 向量压缩
+
+- Qdrant 支持 Scalar Quantization (SQ) 或 Product Quantization (PQ)
+- 可将 dense 向量从 8KB 压缩到 2-4KB，节省 50-75%
+
+### 3. 稀疏向量优化
+
+- BM25 可以剪枝（prune）低权重的词
+- 保留 top 50 关键词即可，不用全量
+
+### 4. 父子块大小调整
+
+- 父块：1000-2000（平衡上下文完整性）
+- 子块：100-300（平衡检索精度）
+
+---
+
+## ✨ 核心优势总结
+
+| 特性 | 说明 |
+|------|------|
+| **检索精度** | 子块小 → 语义更精准 |
+| **回答质量** | 父块大 → 上下文完整 |
+| **混合检索** | dense（语义）+ sparse（关键词）= 召回率高 |
+| **存储效率** | 父子分离 → 不用重复存储大段文本 |
+
 ### Level 4: GraphRAG（基于图和关系的 RAG）

 - **核心算法**: LLM 实体关系抽取 (NER & Relation Extraction)。
@@ -329,9 +567,9 @@ async with IndexBuilder(config) as builder:
 封装 Qdrant 向量数据库操作。

 ```python
-from rag_core import QdrantVectorStore
+from rag_core import QdrantHybridStore

-vector_store = QdrantVectorStore(
+vector_store = QdrantHybridStore(
    collection_name="rag_documents",
    embeddings=embeddings,
 )