RAG数据库生成

2026-04-19 15:01:40 +08:00
parent c18e8a9860
commit cc8ef41ef9
17 changed files with 1089 additions and 577 deletions
--- a/rag_indexer/README.md
+++ b/rag_indexer/README.md
@@ -51,10 +51,111 @@ graph TD
 - **核心思路**: 解决 RAG 领域经典的矛盾——检索时块越小越容易精确命中（去除噪声）；但生成回答时，块越大越能给大模型提供充足的上下文背景。
 - **实现指南**: 
  - 使用 `langchain.retrievers` 中的 `ParentDocumentRetriever` 模块。
-  - 在写入时，你需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore` (比如原生的 `InMemoryStore` 或 `Redis`)。
+  - 在写入时，你需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore`。
+  - **推荐方案**: 使用 `LocalFileStore` (默认) 或 `PostgresDocStore` 作为 docstore。
  - 将两种不同的 `TextSplitter` 分别赋值给检索器的 `child_splitter` 和 `parent_splitter`，然后调用 `.add_documents()` 即可让系统自动完成映射。

-### Level 4: GraphRAG 与 多模态 (Graph & Multi-modal)
+### Level 3.1: PostgreSQL DocStore 集成
+- **核心优势**: 利用 PostgreSQL 作为持久化存储，适合生产环境。使用同步连接池，避免异步复杂度。
+- **实现步骤**:
+  1. **安装依赖**: `pip install psycopg2-binary`
+  2. **配置连接**: 设置 `DB_URI` 环境变量或直接在代码中指定 PostgreSQL 连接字符串
+  3. **创建 docstore**: 使用 `PostgresDocStore` 类直接创建
+  4. **注入到 IndexBuilder**: 在创建 `IndexBuilder` 时通过 `docstore` 参数注入
+
+- **使用示例**:
+  ```python
+  from rag_indexer.docstore_manager import PostgresDocStore
+  from rag_indexer.builder import IndexBuilder, SplitterType
+
+  # 创建 PostgreSQL docstore
+  docstore = PostgresDocStore(
+      connection_string="postgresql://user:pass@host:5432/db",
+      table_name="parent_documents"
+  )
+
+  # 创建 IndexBuilder 并注入 docstore
+  builder = IndexBuilder(
+      collection_name="rag_documents",
+      splitter_type=SplitterType.PARENT_CHILD,
+      docstore=docstore,
+      parent_chunk_size=1000,
+      child_chunk_size=200,
+  )
+  ```
+
+### Level 3.2: 语义切分与父子块策略结合
+- **核心优势**: 结合语义切分的连贯性和父子块策略的层次化存储优势，实现更精准的检索和更丰富的上下文。
+- **实现原理**:
+  - **父块切分**: 使用递归字符切分创建大块（约1000词），提供完整的上下文背景
+  - **子块切分**: 使用语义动态切分创建小块（约200词），根据语义连贯性动态切分，提高检索精度
+  - **存储机制**: 子块向量存入Qdrant用于精准检索，父块内容存入PostgreSQL提供完整上下文
+- **使用示例**:
+  ```python
+  from rag_indexer.builder import IndexBuilder, SplitterType
+
+  # 创建 IndexBuilder，结合语义切分与父子块策略
+  builder = IndexBuilder(
+      collection_name="rag_documents",
+      splitter_type=SplitterType.PARENT_CHILD,
+      # 父子块配置
+      parent_chunk_size=1000,
+      child_chunk_size=200,
+      # 子块使用语义切分
+      child_splitter_type=SplitterType.SEMANTIC,
+      # PostgreSQL 存储配置
+      docstore_conn_string="postgresql://user:pass@host:5432/db",
+  )
+  ```
+- **配置参数**:
+  - `child_splitter_type`: 子块切分器类型，可选 `SplitterType.RECURSIVE`（默认）或 `SplitterType.SEMANTIC`
+  - 当使用语义切分时，系统会自动使用已配置的Embedding模型进行句子级相似度计算
+
+### Level 4: RAG-Fusion (多路改写与倒数排名融合)
+- **核心优势**: 通过大模型发散思维，将单一问题改写为多个相似问题，扩大搜索面，再利用数学统计算法合并结果，提高检索的全面性和准确性。
+- **实现原理**:
+  1. **多路查询改写**: 利用LLM将原始查询改写成3-5个不同表述的查询，从不同角度表达相同意图
+  2. **倒数排名融合 (RRF)**: 对每个改写查询的结果进行RRF融合，公式为 $RRF\_score(d) = \sum_{q \in Q} \frac{1}{k + rank_q(d)}$，避免单一检索结果主导
+  3. **结果去重**: 对融合后的结果进行去重，确保返回的文档唯一
+- **使用示例**:
+  ```python
+  from rag_indexer.builder import IndexBuilder, SplitterType
+  from langchain_openai import OpenAI
+
+  # 创建 IndexBuilder
+  builder = IndexBuilder(
+      collection_name="rag_documents",
+      splitter_type=SplitterType.PARENT_CHILD,
+      parent_chunk_size=1000,
+      child_chunk_size=200,
+      docstore_conn_string="postgresql://user:pass@host:5432/db",
+  )
+
+  # 创建语言模型用于查询改写
+  llm = OpenAI(
+      openai_api_base="http://localhost:8000/v1",
+      openai_api_key="no-key-needed",
+      model_name="Qwen2.5-7B-Instruct",
+      temperature=0.3,
+  )
+
+  # 使用 RAG-Fusion 检索
+  query = "如何申请项目资金？"
+  results = builder.retrieve_with_fusion(
+      query=query,
+      llm=llm,
+      num_queries=3,
+      k=5,
+      return_parent=True
+  )
+  ```
+- **配置参数**:
+  - `llm`: 语言模型实例，用于查询改写
+  - `num_queries`: 生成的查询数量，建议3-5个
+  - `k`: 返回的文档数量
+  - `return_parent`: 是否返回父块上下文
+
+### Level 5: GraphRAG 与 多模态 (Graph & Multi-modal)
 - **核心算法**: LLM 实体关系抽取 (NER & Relation Extraction)。
 - **核心思路**: 解决传统纯向量检索难以处理“跨文档复杂关系推理”的痛点（如：A公司的CEO是谁？他名下的B公司主要业务是什么？这种需要横跨多页 PDF 的跳跃性问题）。
 - **实现指南**: 
@@ -63,7 +164,7 @@ graph TD

 ---

-## <20> 所需依赖与安装
+## 所需依赖与安装

 为了支持完整的文档解析和 Qdrant 写入，需要安装以下 Python 包：

@@ -76,6 +177,12 @@ pip install unstructured pdf2image pdfminer.six

 # 用于语义分块 (可选)
 pip install langchain-experimental
+
+# 用于 PostgreSQL 存储 (可选，用于 Parent-Child 策略)
+pip install psycopg2-binary
+
+# 用于 RAG-Fusion (可选，需要语言模型)
+pip install langchain-openai
 ```

 ---
@@ -87,16 +194,109 @@ pip install langchain-experimental
 ```text
 rag_indexer/
 ├── __init__.py
-├── loaders.py          # 负责调用 unstructured 解析不同类型文件
-├── splitters.py        # 负责实现 Recursive、Semantic、Parent-Child 切分逻辑
-├── embedders.py        # 封装本地 llama.cpp 交互的 Embedding 接口
-├── vector_store.py     # 封装 Qdrant 写入、Upsert、Collection 初始化操作
-└── builder.py          # 核心编排文件，将上述模块串联成 Pipeline
+├── loaders.py            # 负责调用 unstructured 解析不同类型文件
+├── splitters.py          # 负责实现 Recursive、Semantic、Parent-Child 切分逻辑
+├── embedders.py          # 封装本地 llama.cpp 交互的 Embedding 接口
+├── vector_store.py       # 封装 Qdrant 写入、Upsert、Collection 初始化操作
+├── docstore_manager.py   # 文档存储管理器，支持 LocalFileStore 和 PostgreSQL
+└── builder.py            # 核心编排文件，将上述模块串联成 Pipeline
 ```

 ---

+## 🔄 工作流程详解

+### 数据流向总览
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │            builder.py                   │
+                    │         IndexBuilder 入口               │
+                    └─────────────────┬───────────────────────┘
+                                      │
+                    ┌─────────────────▼───────────────────────┐
+                    │           loaders.py                   │
+                    │    DocumentLoader.load_file()           │
+                    │    → 返回 List[Document]                │
+                    └─────────────────┬───────────────────────┘
+                                      │
+                    ┌─────────────────▼───────────────────────┐
+                    │     ParentDocumentRetriever.add_documents()│
+                    │  ┌─────────────────────────────────┐   │
+                    │  │   parent_splitter (粗切)         │   │
+                    │  │   父块 ~1000 词                  │   │
+                    │  └────────────┬────────────────────┘   │
+                    │               │                         │
+                    │  ┌────────────▼────────────────────┐    │
+                    │  │   child_splitter (细切)         │    │
+                    │  │   子块 ~200 词                  │    │
+                    │  └────────────┬────────────────────┘    │
+                    │               │                         │
+                    │    ┌──────────┴──────────┐              │
+                    │    ▼                      ▼              │
+                    │  子块向量                 父块原始内容    │
+                    │    │                      │              │
+                    │    ▼                      ▼              │
+                    │  ┌────────────┐  ┌─────────────────┐    │
+                    │  │vector_store│  │  docstore_manager│    │
+                    │  │  (Qdrant)  │  │  (PostgreSQL)   │    │
+                    │  └────────────┘  └─────────────────┘    │
+                    └─────────────────────────────────────────┘
+```
+
+### 文件职责详解
+
+| 文件 | 职责 | 关键类/函数 |
+|------|------|------------|
+| **builder.py** | 核心编排，负责串联整个流程 | `IndexBuilder` |
+| **loaders.py** | 解析各种文档格式（PDF、Word、TXT等） | `DocumentLoader` |
+| **splitters.py** | 文本切分策略（Recursive/Semantic/Parent-Child） | `SplitterType`, `get_splitter()` |
+| **embedders.py** | 向量化（封装 llama.cpp embedding 接口） | `LlamaCppEmbedder` |
+| **vector_store.py** | Qdrant 向量数据库操作 | `QdrantVectorStore` |
+| **docstore_manager.py** | 父文档存储（PostgreSQL/本地文件） | `PostgresDocStore`, `get_docstore()` |
+
+### 调用顺序
+
+#### 1. 创建 IndexBuilder（入口）
+
+```python
+from rag_indexer.builder import IndexBuilder, SplitterType
+
+builder = IndexBuilder(
+    collection_name="my_docs",
+    splitter_type=SplitterType.PARENT_CHILD,
+    qdrant_url="http://localhost:6333",
+    parent_chunk_size=1000,
+    child_chunk_size=200,
+)
+```
+
+#### 2. 构建索引
+
+```python
+# 方式A：从单个文件构建
+builder.build_from_file("/path/to/document.pdf")
+
+# 方式B：从目录批量构建
+builder.build_from_directory("/path/to/docs/")
+```
+
+#### 3. 检索（获取完整父块上下文）
+
+```python
+# 检索时返回完整父块
+results = builder.search_with_parent_context("查询内容")
+```
+
+### 检索流程
+
+```
+1. vector_store.similarity_search() → 从 Qdrant 找到相关子块
+2. retriever.get_relevant_documents() → 根据子块 ID 获取对应父块
+3. 返回完整父块给用户
+```
+
+---

 ### 串联与触发方式
 在你的 LangGraph 系统外，创建一个执行脚本 `scripts/run_indexer.py`：