# 离线 RAG 索引构建系统 (Offline RAG Indexer)

该模块负责 RAG 系统的阶段一：**离线索引构建**。它将外部的非结构化数据（如文档、PDF、网页等）清洗、切分并转化为向量，最终存入向量数据库中。

## 📊 系统工作流示意图

```mermaid
graph TD
    A[原始文档集合 <br> PDF / Word / Markdown] --> B(文档加载器 DocumentLoader)
    B --> C{文本切分策略 Splitter}
    
    C -->|基础策略| D1[固定字符长度切分 <br> Recursive Split]
    C -->|进阶策略| D2[语义边界切分 <br> Semantic Chunking]
    C -->|高级策略| D3[父子文档切分 <br> Parent-Child / Auto-merging]
    
    D1 & D2 & D3 --> E[向量化 Embedder <br> llama.cpp: embeddinggemma]
    
    E --> F[(Qdrant 向量数据库)]
    
    subgraph "元数据管理"
    G[提取作者、日期、页码等元数据 Metadata] -.附加.-> E
    end
```

---

## 🎯 演进路线与核心算法 (Roadmap)

### Level 1: 基础暴力切分 (Basic Recursive Splitting)
- **核心算法**: 递归字符切分。它按照预定义的分隔符列表（如 `["\n\n", "\n", " ", ""]`）从大到小尝试切分文本，直到每块的大小满足最大长度限制。
- **优缺点**: 实现极简单，速度快。但非常容易将一句话拦腰截断，导致上下文语义丢失。
- **实现指南**: 
  - 从 `langchain.text_splitter` 导入 `RecursiveCharacterTextSplitter`。
  - 实例化时设置 `chunk_size`（如 500）和 `chunk_overlap`（如 50），直接调用 `.split_documents(raw_docs)` 方法。

### Level 2: 语义动态切分 (Semantic Chunking)
- **核心算法**: 句子级相似度阈值算法。
  1. 将文章按标点符号按句子拆分。
  2. 使用轻量级 Embedding 模型将每一句向量化。
  3. 计算相邻两句之间的余弦相似度 (Cosine Similarity)。
  4. 当相似度低于设定阈值时（说明两句话讲的不是同一件事，语义发生了转折），在此处“切断”形成一个新的块。
- **优缺点**: 极大程度保留了段落内语义的连贯性，对 LLM 回答非常友好。但由于在切分阶段就需要调用向量模型，耗时略长。
- **实现指南**: 
  - 从 `langchain_experimental.text_splitter` 导入 `SemanticChunker`。
  - 实例化时需要传入你已经配置好的 Embedding 模型实例（如基于 `OpenAIEmbeddings` 封装的 llama.cpp 本地模型），并设置 `breakpoint_threshold_type="percentile"` 等阈值参数。

### Level 3: 高级父子块策略 (Parent-Child / Auto-merging)
- **核心算法**: 层次化双重存储与映射。
  - **切分机制**: 首先将文档粗切为较大的“父块 (Parent Chunk, 约 1000 词)”，随后将父块细切为较小的“子块 (Child Chunk, 约 200 词)”。
  - **存储机制**: 仅仅将**子块**的向量存入 Qdrant 用于精准计算距离；将**父块**的原始内容存在内存或 Document Store (如 KV 数据库) 中，通过 UUID 相互映射。
- **核心思路**: 解决 RAG 领域经典的矛盾——检索时块越小越容易精确命中（去除噪声）；但生成回答时，块越大越能给大模型提供充足的上下文背景。
- **实现指南**: 
  - 使用 `langchain.retrievers` 中的 `ParentDocumentRetriever` 模块。
  - 在写入时，你需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore` (比如原生的 `InMemoryStore` 或 `Redis`)。
  - 将两种不同的 `TextSplitter` 分别赋值给检索器的 `child_splitter` 和 `parent_splitter`，然后调用 `.add_documents()` 即可让系统自动完成映射。

### Level 4: GraphRAG 与 多模态 (Graph & Multi-modal)
- **核心算法**: LLM 实体关系抽取 (NER & Relation Extraction)。
- **核心思路**: 解决传统纯向量检索难以处理“跨文档复杂关系推理”的痛点（如：A公司的CEO是谁？他名下的B公司主要业务是什么？这种需要横跨多页 PDF 的跳跃性问题）。
- **实现指南**: 
  - 使用本地的大模型（如 `Gemma-4-E2B`）配合 `langchain_community.graphs` 模块。
  - 利用 `LLMGraphTransformer` 组件，在读取文档时，通过预设的 Prompt 强制大模型提取出实体（Node）和关系（Edge），直接写入诸如 Neo4j 这样的图数据库中，而非传统的 Qdrant 向量库。

---

## � 所需依赖与安装

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

```bash
# 基础核心库
pip install langchain langchain-core langchain-openai langchain-qdrant

# 用于复杂文档解析 (PDF, Word, Excel 等)
pip install unstructured pdf2image pdfminer.six

# 用于语义分块 (可选)
pip install langchain-experimental
```

---

## 📂 架构与文件结构设计

在 `rag_indexer/` 目录下，需创建以下核心文件：

```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
```

---



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

```bash
# 终端执行，将本地的 PDF 手册刷入向量数据库
export QDRANT_URL="http://115.190.121.151:6333"
python scripts/run_indexer.py --file data/user_docs/tech_manual.pdf
```
这相当于系统后台的**“离线学习阶段”**，你可以随时挂载定时任务去扫描文件夹，增量更新知识库。