组件	技术选型	版本	说明
文档解析	`unstructured`	0.22+	多格式文档解析（PDF/DOCX/TXT等）
文本切分	`langchain-text-splitters`	内置	递归字符切分 + 语义切分
语义切分	`langchain-experimental`	内置	`SemanticChunker` 基于句子相似度
嵌入模型	`llama.cpp`	本地服务	`Qwen3-Embedding-0.6B` GGUF 模型
稀疏嵌入	`fastembed`	内置	BM25 关键词检索
向量数据库	`Qdrant`	1.17+	HNSW 索引，支持稠密/稀疏向量 + RRF 融合
文档存储	`PostgreSQL`	16+	异步连接池，持久化父块
编排框架	`asyncio`	Python 3.10+	全异步批量处理

数据流向总览

┌─────────────────────────────────────────────────────────────┐
│                    builder.py                               │
│                 IndexBuilder 入口                            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    loaders.py                               │
│            DocumentLoader.load_file()                        │
│            → 返回 List[Document]                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│           自定义父子块索引实现                                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              parent_splitter (粗切)                  │    │
│  │              父块 ~1000 字符                         │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │     父文档存入 PostgreSQL (UUID 映射)               │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              child_splitter (细切)                   │    │
│  │              子块 ~200 字符                          │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │  子文档生成 dense + sparse 双向量                   │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │  子文档存入 Qdrant (payload 含 parent_id)           │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

技术特性

✅ 多格式支持：PDF、DOCX、TXT、MD、HTML、PPTX、XLSX、JSON
✅ 三种切分策略：递归字符切分、语义切分、父子块策略
✅ Parent-Child 架构：子块精准检索，父块完整上下文
✅ PostgreSQL DocStore：持久化存储父块，支持异步连接池
✅ 混合检索：稠密向量（语义）+ 稀疏向量（关键词），Qdrant 原生 RRF 融合
✅ 完全异步化：索引构建、检索全链路 async / await
✅ 批量写入：高效批量处理，自动分批
✅ 上下文管理器：支持同步/异步资源管理

📂 架构与文件结构

rag_indexer/
├── __init__.py
├── index_builder.py       # 索引构建主流水线（自定义父子块实现）
├── loaders.py             # 文档加载器（多格式支持）
├── splitters.py           # 文本切分器（递归/语义/父子块）
├── config.py              # 配置管理
├── cli.py                 # 命令行接口
├── clear_qdrant.py        # 清空 Qdrant 集合
├── reset_qdrant.py        # 重置 Qdrant 集合
└── README.md              # 本文档

backend/rag_core/
├── __init__.py
├── vector_store.py        # Qdrant 混合存储（异步）
├── sparse_embedder.py     # BM25 稀疏嵌入
├── embedders.py           # 嵌入模型封装
├── doc_store.py           # PostgreSQL 文档存储
├── client.py              # Qdrant 同步/异步客户端工厂
└── config.py              # 配置管理

backend/app/rag/
├── retriever.py           # 混合检索器（异步）
├── rerank.py              # llama.cpp 远程重排序器
├── query_transform.py     # 多路查询改写生成器
├── fusion.py              # RRF 倒数排名融合算法
├── pipeline.py            # RAG 流水线编排
├── tools.py               # LangChain Tool 封装
├── evaluate.py            # 评估工具
└── README.md              # 本文档

backend/app/model_services/
├── embedding_services.py  # 嵌入服务
├── chat_services.py       # LLM 服务
└── rerank_services.py     # 重排序服务

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

Level 1: 基础暴力切分 (Basic Recursive Splitting)

核心算法: 递归字符切分。它按照预定义的分隔符列表（如 ["\n\n", "\n", "。", "！", "？", " ", ""]）从大到小尝试切分文本，直到每块的大小满足最大长度限制。
优缺点: 实现极简单，速度快。但非常容易将一句话拦腰截断，导致上下文语义丢失。
实现指南:
- 从 langchain_text_splitters 导入 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
- 实现 SemanticChunkerAdapter 继承 TextSplitter，解决类型不兼容问题
- 实例化时需要传入已配置好的 Embedding 模型实例

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

核心算法: 层次化双重存储与映射（自定义实现）。
- 切分机制: 首先将文档粗切为较大的"父块 (Parent Chunk, 约 1000 字符)"，随后将父块细切为较小的"子块 (Child Chunk, 约 200 字符)"
- 存储机制:
  - 子块: 存入 Qdrant，同时生成 dense 向量（语义）和 sparse 向量（关键词），payload 中包含 parent_id
  - 父块: 存入 PostgreSQL，通过 UUID 与子块映射
核心思路: 解决 RAG 领域经典的矛盾——检索时块越小越容易精确命中（去除噪声）；但生成回答时，块越大越能给大模型提供充足的上下文背景。
实现:
- 完全自定义实现，不依赖 LangChain 的 ParentDocumentRetriever
- 支持异步批量写入
- 支持双向量混合检索

Level 3.1: PostgreSQL DocStore 集成

核心优势: 利用 PostgreSQL 作为持久化存储，适合生产环境。使用异步连接池，支持高并发。
实现步骤:
1. 配置连接: 设置 DB_URI 环境变量或通过 docstore_conn_string 参数指定
2. 创建 docstore: 使用 rag_core.doc_store.create_docstore() 工厂函数
3. 注入到 IndexBuilder: 通过构造函数参数注入

Level 3.2: 语义切分与父子块策略结合

核心优势: 结合语义切分的连贯性和父子块策略的层次化存储优势，实现更精准的检索和更丰富的上下文。
实现原理:
- 父块切分: 使用 RecursiveCharacterTextSplitter 创建大块（约 1000 字符），提供完整的上下文背景
- 子块切分: 使用 SemanticChunkerAdapter 创建小块，根据语义连贯性动态切分，提高检索精度
- 存储机制: 子块向量存入 Qdrant 用于精准检索，父块内容存入 PostgreSQL 提供完整上下文

Level 3.3: 混合检索架构（稠密 + 稀疏）

核心算法: Qdrant 原生双向量存储 + RRF 分数融合
- 稠密向量 (Dense): 语义相似度检索，捕捉深层含义
- 稀疏向量 (Sparse): BM25 关键词检索，精确匹配术语
- RRF 融合 (Reciprocal Rank Fusion): 服务端分数融合，无需客户端后处理
核心思路: 结合语义理解和关键词匹配的双重优势，大幅提升召回率
实现原理:
- 每个子文档同时生成 dense 向量和 sparse 向量
- 使用 Qdrant 的 query_points API + Prefetch 并行检索
- 通过 FusionQuery 自动进行 RRF 分数融合

📦 存储结构详解

整体数据流向

                    ┌─────────────────────────────────────────┐
                    │           原始文档                        │
                    │      (Document + Metadata)              │
                    └───────────────┬─────────────────────────┘
                                    │ 切分
                    ┌───────────────▼─────────────────────────┐
                    │      父文档块 (Parent Chunks)            │
                    │   大粒度：1000-2000字符/块               │
                    │   存：PostgreSQL JSONB                  │
                    └───────────────┬─────────────────────────┘
                                    │ 再切分
                    ┌───────────────▼─────────────────────────┐
                    │      子文档块 (Child Chunks)             │
                    │   小粒度：200-400字符/块                 │
                    │   存：Qdrant (稠密+稀疏双向量)           │
                    └─────────────────────────────────────────┘

PostgreSQL 存储结构（父文档）

表结构

CREATE TABLE parent_documents (
    key TEXT PRIMARY KEY,
    value JSONB NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

数据格式（JSONB）

{
    "page_content": "这是一个父文档块，包含完整的上下文信息，用于最终给 LLM 生成回答...",
    "metadata": {
        "source": "file_name.pdf",
        "page": 10,
        "chunk_id": "parent-12345",
        "timestamp": "2024-05-04T12:34:56Z"
    }
}

Qdrant 存储结构（子文档）

集合配置：

支持 dense 向量配置：根据嵌入模型输出维度，距离函数使用 Cosine
支持 sparse 向量配置：BM25 稀疏向量

点结构（Point）：

id: 子文档唯一标识
vector: 包含 dense 和 sparse 双向量
payload: 包含文本内容、parent_id、来源元数据

🔄 完整数据流

索引构建阶段

原始文档
    ↓
切分为父块（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)。
核心思路: 解决传统纯向量检索难以处理"跨文档复杂关系推理"的痛点（如：A公司的CEO是谁？他名下的B公司主要业务是什么？这种需要横跨多页 PDF 的跳跃性问题）。
实现原理:
1. 实体提取: 利用 LLM 从文档中提取实体（如人物、组织、地点、事件等）
2. 关系抽取: 识别实体之间的关系（如"CEO of"、"founded by"、"located in"等）
3. 图构建: 将实体作为节点，关系作为边，构建知识图谱
4. 混合检索: 结合向量检索和图查询，同时利用语义相似性和结构关系
技术栈:
- 图数据库: Neo4j 或 RedisGraph
- LLM 工具: LLMGraphTransformer 或自定义 Prompt
- 集成方式: 与向量存储并行，形成混合检索系统
实现指南:
- 使用 langchain_community.graphs 模块
- 配置本地大模型（如 Gemma-4-E4B）用于实体关系抽取
- 构建包含实体和关系的图结构，存储到图数据库
- 实现混合检索逻辑，结合向量相似度和图路径分析

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.add_graph_documents(graph_documents)

核心算法: 跨模态嵌入和多模态融合。
核心思路: 突破纯文本限制，支持图像、表格、音频等多种数据类型的理解和检索。
实现原理:
1. 多模态嵌入: 使用 CLIP 等模型将不同模态数据映射到统一向量空间
2. 多模态索引: 为不同类型的内容创建专用索引
3. 跨模态检索: 支持以文搜图、以图搜文等跨模态查询
技术栈:
- 多模态模型: CLIP、BLIP 等
- 存储: 向量数据库 + 对象存储
- 检索: 混合向量检索

🔧 核心组件详解

1. 文档加载器 (loaders.py)

使用 unstructured 库解析多种文件格式。

支持格式：PDF、DOCX、DOC、TXT、MD、HTML、PPTX、XLSX、JSON

2. 文本切分器 (splitters.py)

提供三种切分策略：

递归字符切分：

使用 SplitterType.RECURSIVE 类型
可配置 chunk_size 和 chunk_overlap

语义切分：

使用 SplitterType.SEMANTIC 类型
基于句子相似度阈值动态切分
需要 Embedding 模型支持

父子块策略：在 IndexBuilder 中自动配置。

3. 索引构建器 (index_builder.py)

核心编排模块，串联整个索引构建流程。

主要功能：

支持单块切分模式和父子块切分模式
自动管理 PostgreSQL 文档存储和 Qdrant 向量存储
支持异步批量写入和重试机制
提供上下文管理器资源管理

4. 向量存储 (vector_store.py)

封装 Qdrant 向量数据库操作。

主要功能：

创建和管理向量集合
支持 dense 和 sparse 双向量写入
提供同步和异步客户端
自动处理批量操作和重试

5. PostgreSQL DocStore (doc_store.py)

持久化存储父块内容，支持异步连接池。

主要功能：

异步连接池管理
文档的增删改查
批量操作支持
UUID 映射管理

📊 切分策略对比

策略	原理	优点	缺点	适用场景
递归字符	按分隔符递归切分	速度快，实现简单	可能截断语义	简单文档
语义切分	基于句子相似度阈值	语义连贯性好	需要 Embedding 模型	专业文档
父子块	大块存储+小块检索	检索精准+上下文完整	存储复杂度高	生产环境

🚀 快速开始

命令行方式

使用 rag_indexer/cli.py 提供的命令行工具：

build: 从文件或目录构建索引
clear: 清空指定 Qdrant 集合
reset: 重置指定 Qdrant 集合

Python API 方式

使用 IndexBuilder 类进行程序化索引构建：

配置 IndexBuilderConfig 设置切分策略和存储参数
使用 build_from_file() 从单个文件构建
使用 build_from_directory() 从目录批量构建
推荐使用异步上下文管理器 async with 自动管理资源

⚙️ 环境配置

变量名	说明	默认值
`QDRANT_URL`	Qdrant 向量数据库地址	`http://127.0.0.1:6333`
`QDRANT_API_KEY`	Qdrant API 密钥	-
`DB_HOST`	PostgreSQL 主机	`127.0.0.1`
`DB_PORT`	PostgreSQL 端口	`5432`
`DB_USER`	PostgreSQL 用户	`postgres`
`DB_PASSWORD`	PostgreSQL 密码	`postgres`
`DB_NAME`	PostgreSQL 数据库	`rag_db`
`LLAMACPP_EMBEDDING_URL`	Embedding 服务地址	`http://127.0.0.1:18001`
`LLAMACPP_API_KEY`	llama.cpp API 密钥	`huang1998`

🔄 与 app/rag 集成

向量存储：共享 Qdrant 集合，确保嵌入模型一致
文档存储：父块存入 PostgreSQL，通过 UUID 与子块关联
集合名称：默认使用 rag_documents 集合
服务接入：使用 model_services 统一获取嵌入、LLM、重排序服务

详见 app/rag/README.md

📝 高级配置

自定义切分参数

IndexBuilderConfig 支持以下配置：

collection_name: 集合名称
splitter_type: 切分器类型（RECURSIVE/SEMANTIC/PARENT_CHILD）
parent_chunk_size: 父块大小（默认 1000）
child_chunk_size: 子块大小（默认 200）
parent_chunk_overlap: 父块重叠
child_chunk_overlap: 子块重叠
child_splitter_type: 子块切分器类型
search_k: 检索返回数量

批量处理与重试

索引构建器内置自动重试机制，处理网络波动：

最大重试次数：5 次
退避策略：指数退避（2s, 4s, 8s, 16s, 32s）
批量大小：10 个文档/批次

资源管理

推荐使用异步上下文管理器自动管理资源，也支持手动 await builder.aclose() 释放。

README.md Unescape Escape

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

🎯 核心架构

技术栈

数据流向总览

技术特性

📂 架构与文件结构

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

Level 1: 基础暴力切分 (Basic Recursive Splitting)

Level 2: 语义动态切分 (Semantic Chunking)

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

Level 3.1: PostgreSQL DocStore 集成

Level 3.2: 语义切分与父子块策略结合

Level 3.3: 混合检索架构（稠密 + 稀疏）

📦 存储结构详解

整体数据流向

PostgreSQL 存储结构（父文档）

表结构

数据格式（JSONB）

Qdrant 存储结构（子文档）

🔄 完整数据流

索引构建阶段

检索阶段

📊 存储消耗分析（估算）

Qdrant 单条子文档详细分解

⚡ 优化策略

1. 分层存储

2. 向量压缩

3. 稀疏向量优化

4. 父子块大小调整

✨ 核心优势总结

Level 4: GraphRAG（基于图和关系的 RAG）

Level 5: 多模态 RAG (Multi-modal RAG)

🔧 核心组件详解

1. 文档加载器 (loaders.py)

2. 文本切分器 (splitters.py)

3. 索引构建器 (index_builder.py)

4. 向量存储 (vector_store.py)

5. PostgreSQL DocStore (doc_store.py)

📊 切分策略对比

🚀 快速开始

命令行方式

Python API 方式

⚙️ 环境配置

🔄 与 app/rag 集成

📝 高级配置

自定义切分参数

批量处理与重试

资源管理

README.md