修改容器生成

QUICKSTART.md

@@ -22,15 +22,17 @@ vim .env  # 或使用你喜欢的编辑器
 
 **必需配置项**：
 - `ZHIPUAI_API_KEY` - 智谱 AI API 密钥（从 [智谱开放平台](https://open.bigmodel.cn/) 获取）
+- `DEEPSEEK_API_KEY` - DeepSeek API 密钥（从 [DeepSeek 开放平台](https://platform.deepseek.com/) 获取）
 - `LLAMACPP_API_KEY` - llama.cpp 服务认证 Token（与容器启动参数一致，默认 `token-abc123`）
 
 **可选配置项**：
-- `VLLM_BASE_URL` - LLM 服务地址（本地默认：`http://127.0.0.1:8081/v1`，Docker容器访问宿主机：`http://host.docker.internal:18000/v1`）
-- `LLAMACPP_EMBEDDING_URL` - Embedding 服务地址（本地默认：`http://127.0.0.1:8082/v1`，Docker容器访问宿主机：`http://host.docker.internal:18001/v1`）
-- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用远程服务器地址）
-- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置，使用远程服务器地址）
-
-**注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。
+- `VLLM_BASE_URL` - LLM 服务地址（本地默认：`http://127.0.0.1:8081/v1`）
+- `LLAMACPP_EMBEDDING_URL` - Embedding 服务地址（本地默认：`http://127.0.0.1:8082/v1`）
+- `DB_URI` - PostgreSQL 连接字符串（默认已配置远程服务器地址）
+- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置远程服务器地址）
+- `LOG_LEVEL` - 日志级别（`DEBUG`/`INFO`/`WARNING`/`ERROR`）
+- `ENABLE_GRAPH_TRACE` - 是否启用图流转追踪（`true`/`false`）
+- `MEMORY_SUMMARIZE_INTERVAL` - 对话摘要生成间隔（默认 `10`）
 
 #### 2. 启动服务
 
@@ -40,12 +42,9 @@ docker compose -f docker/docker-compose.yml up -d --build
 
 #### 3. 访问应用
 
-**如果配置了 Nginx 反向代理**：
-- 访问地址：`http://your-domain.com` 或 `http://your-server-ip`
-
-**如果未配置 Nginx（直接访问容器）**：
 - **前端**: http://127.0.0.1:8501
-- **后端 API**: http://127.0.0.1:8001
+- **后端 API**: http://127.0.0.1:8083
+- **健康检查**: http://127.0.0.1:8083/health
 
 #### 常用命令
 
@@ -56,11 +55,17 @@ docker compose ps
 # 查看日志
 docker compose logs -f
 
+# 查看特定服务日志
+docker compose logs -f backend
+
 # 重启特定服务
 docker compose restart backend
 
 # 停止所有服务
 docker compose down
+
+# 重新构建并启动
+docker compose up -d --build
 ```
 
 ---
@@ -83,31 +88,31 @@ pip install -r requirement.txt
 
 复制并编辑 `.env` 文件：
 
-```
-# 基于 Docker 模板创建
+```bash
 cp .env.docker .env
 vim .env
 ```
 
-**本地开发需要修改以下配置**：
+**本地开发配置示例**：
 
-``env
+```env
+# API Keys
 ZHIPUAI_API_KEY=your_api_key_here
+DEEPSEEK_API_KEY=your_deepseek_api_key_here
 LLAMACPP_API_KEY=token-abc123
 
-# 本地开发时，llama.cpp 服务在 127.0.0.1
-VLLM_BASE_URL=http://127.0.0.1:8081/v1  # 本地开发
-LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
-# 或
-VLLM_BASE_URL=http://host.docker.internal:18000/v1  # Docker容器访问宿主机
-LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机
+# LLM 服务地址（本地开发）
+VLLM_BASE_URL=http://127.0.0.1:8081/v1
+LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1
 
-# 数据库和向量存储使用远程服务器
+# 远程数据库和向量存储
 DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
 QDRANT_URL=http://115.190.121.151:6333
 
-# 本地开发时，后端也在 127.0.0.1
-API_URL=http://127.0.0.1:8083/chat
+# 日志和调试
+LOG_LEVEL=INFO
+ENABLE_GRAPH_TRACE=true
+MEMORY_SUMMARIZE_INTERVAL=10
 ```
 
 #### 3. 启动服务
@@ -119,10 +124,10 @@ python app/backend.py
 
 **终端 2 - 前端：**
 ```bash
-cd frontend && streamlit run app.py
+streamlit run frontend/frontend_main.py
 ```
 
-浏览器自动打开前端页面（如果配置了 Nginx，访问 `http://your-domain.com`；否则访问 http://127.0.0.1:8501）
+浏览器自动打开前端页面，访问 http://127.0.0.1:8501
 
 ---
 
@@ -132,7 +137,7 @@ cd frontend && streamlit run app.py
 
 | 文件 | 用途 |
 |------|------|
-| `docker-compose.yml` | 服务编排配置（仅包含 backend 和 frontend） |
+| `docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） |
 | `Dockerfile.backend` | 后端镜像构建 |
 | `Dockerfile.frontend` | 前端镜像构建 |
 | `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
@@ -141,14 +146,16 @@ cd frontend && streamlit run app.py
 
 ```yaml
 services:
-  backend:      # FastAPI 后端服务（连接远程 PostgreSQL 和 Qdrant）
-  frontend:     # Streamlit 前端界面
+  backend:      # FastAPI 后端服务（端口 8083）
+  frontend:     # Streamlit 前端界面（端口 8501）
 ```
 
 **特性：**
 - ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
 - ✅ 自动重启策略（`restart: unless-stopped`）
-- ✅ 内部网络隔离
+- ✅ 内部网络隔离（ai-network）
+- ✅ 文档目录挂载（`./data/user_docs`）
+- ✅ 日志目录挂载（`./logs`）
 
 ### 只更新特定服务
 
@@ -166,7 +173,7 @@ docker compose up -d frontend
 
 ### 添加新工具
 
-在 `app/tools.py` 中添加：
+在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加：
 
 ```python
 @tool
@@ -184,35 +191,34 @@ def my_new_tool(param: str) -> str:
     return result
 ```
 
-工具会自动注册，无需修改其他文件。
+工具会自动注册到 `AVAILABLE_TOOLS` 列表，无需修改其他文件。
 
 ### 添加新模型
 
-在 `app/agent.py` 中：
+在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中：
 
 ```python
-def _create_new_model_llm(self):
+@staticmethod
+def create_new_model():
     """创建新模型的 LLM"""
-    return YourChatModel(
+    api_key = os.getenv("NEW_MODEL_API_KEY")
+    return ChatOpenAI(
+        base_url="https://api.new-model.com/v1",
+        api_key=SecretStr(api_key),
         model="model-name",
-        api_key=os.getenv("YOUR_API_KEY"),
+        temperature=0.1,
+        streaming=True,
     )
-
-# 在 initialize() 方法中注册
-model_configs = {
-    "zhipu": self._create_zhipu_llm,
-    "local": self._create_local_llm,
-    "new_model": self._create_new_model_llm,  # 新增
-}
 ```
 
-在前端 `frontend/app.py` 中添加选项：
+然后在 `CREATORS` 字典中注册：
 
 ```python
-MODEL_OPTIONS = {
-    "智谱 GLM-4": "zhipu",
-    "本地 Gemma-4": "local",
-    "新模型": "new_model",  # 新增
+CREATORS = {
+    "local": create_local,
+    "deepseek": create_deepseek,
+    "zhipu": create_zhipu,
+    "new_model": create_new_model,  # 新增
 }
 ```
 
@@ -226,7 +232,12 @@ docker compose exec backend bash
 docker compose logs -f backend
 
 # 测试后端 API
-curl http://127.0.0.1:8001/health
+curl http://127.0.0.1:8083/health
+
+# 测试对话接口
+curl -X POST http://127.0.0.1:8083/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "你好", "model": "zhipu"}'
 ```
 
 ---
@@ -252,6 +263,7 @@ curl http://127.0.0.1:8001/health
 
 在 Gitea 仓库设置中添加：
 - `ZHIPUAI_API_KEY`
+- `DEEPSEEK_API_KEY`
 - `LLAMACPP_API_KEY`
 
 ---
@@ -282,19 +294,19 @@ curl http://115.190.121.151:6333/collections
 docker compose logs backend
 
 # 检查端口占用
-lsof -i :8001
+lsof -i :8083
 ```
 
 **常见原因：**
 - API Key 未配置或错误
-- 端口 8001 被占用
+- 端口 8083 被占用
 - 依赖包缺失
 
 #### 3. 前端无法连接后端
 
 **错误信息：**
 ```
-HTTPConnectionPool(host='backend', port=8001): Max retries exceeded
+HTTPConnectionPool(host='backend', port=8083): Max retries exceeded
 ```
 
 **解决方案：**
@@ -324,7 +336,7 @@ docker compose logs backend | grep -i "model\|error"
 ```
 
 **可能原因：**
-- 智谱 API Key 无效
+- 智谱/DeepSeek API Key 无效
 - vLLM 容器未启动（如使用本地模型）
 - 网络连接问题
 

app/rag/README.md

@@ -2,170 +2,390 @@
 
 该模块负责 RAG 系统的阶段二：**在线检索与生成**。它接收用户提问，从知识库中检索出上下文，利用各种高级策略去噪、融合，并作为增强上下文输入给大语言模型 (LLM)。
 
+## 🎯 核心架构
+
+### 技术栈
+
+| 组件 | 技术选型 | 版本 | 说明 |
+|:-----|:---------|:-----|:-----|
+| **基础检索** | `Qdrant` | 1.17+ | HNSW 稠密向量检索 |
+| **混合检索** | `Qdrant` + `BM25` | 内置 | 稠密 + 稀疏向量融合 |
+| **查询改写** | `LangChain` | 内置 | `MultiQueryGenerator` 多路改写 |
+| **RRF 融合** | 自实现 | - | `reciprocal_rank_fusion` 倒数排名融合 |
+| **重排序** | `llama.cpp` | 本地服务 | OpenAI 兼容 Rerank API |
+| **编排框架** | `asyncio` | Python 3.10+ | 异步并行检索 |
+
+### 检索流水线
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      用户提问                                │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│              MultiQueryGenerator                             │
+│           多路查询改写 (num_queries=3)                        │
+│   "如何申请项目资金？" → ["项目资金申请流程", "经费申请步骤"]  │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│              并行检索 (asyncio.gather)                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │  查询1 检索   │  │  查询2 检索   │  │  查询3 检索   │       │
+│  │  (k=20)      │  │  (k=20)      │  │  (k=20)      │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│           reciprocal_rank_fusion (RRF)                       │
+│   RRF_score(d) = Σ 1/(k + rank_q(d))  (k=60)                │
+│   融合多路检索结果，去重排序                                  │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│              LLaMaCPPReranker                                │
+│   远程重排序 (bge-reranker-v2-m3)                             │
+│   返回 Top-N (top_n=5) 最相关文档                             │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│              返回增强上下文                                  │
+│   format_context() → 格式化输出                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 技术特性
+
+- ✅ **多路查询改写**：通过 LLM 将单一问题改写为多个不同角度的查询
+- ✅ **RRF 融合算法**：Reciprocal Rank Fusion，无需评分归一化的融合算法
+- ✅ **远程重排序**：使用 llama.cpp 服务的 OpenAI 兼容 Rerank API
+- ✅ **混合检索支持**：稠密向量 + BM25 稀疏向量混合检索
+- ✅ **异步并行检索**：多路查询并行执行，提升检索速度
+- ✅ **优雅降级**：重排序器不可用时自动降级到基础融合结果
+
+## 📂 架构与文件结构
+
+```
+app/rag/
+├── __init__.py
+├── retriever.py          # Qdrant 基础检索与混合检索
+├── reranker.py           # llama.cpp 远程重排序器
+├── query_transform.py    # 多路查询改写生成器
+├── fusion.py             # RRF 倒数排名融合算法
+├── pipeline.py           # RAG 流水线编排
+└── tools.py              # LangChain Tool 封装
+```
+
 ## 🎯 演进路线与算法详解 (Roadmap)
 
 ### Level 1: 基础向量搜索 (Basic Similarity Search)
+
 - **核心算法**: 近似最近邻搜索 (ANN, 常用 HNSW 算法)。将用户问题转化为向量后，计算它与库中向量的余弦相似度 (Cosine Similarity)，取距离最近的 K 个块。
-- **优缺点**: 速度极快。但只能捕捉“语义相似”，如果用户搜索特定专有名词、编号、订单号，纯向量检索往往会失效（产生“幻觉”匹配）。
+- **优缺点**: 速度极快。但只能捕捉"语义相似"，如果用户搜索特定专有名词、编号、订单号，纯向量检索往往会失效（产生"幻觉"匹配）。
 - **实现指南**:
   - 使用 `rag_indexer.embedders.LlamaCppEmbedder` 作为嵌入模型
   - 使用 `app/rag/retriever.py` 中的 `create_base_retriever` 创建基础检索器
   - 配置 `search_kwargs={"k": 20}` 进行初步召回
 
+```python
+from app.rag.retriever import create_base_retriever
+
+retriever = create_base_retriever(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+    search_kwargs={"k": 20}
+)
+docs = retriever.invoke("什么是 RAG？")
+```
+
 ### Level 2: 混合检索与重排序 (Hybrid Search + Reranker)
-混合检索旨在结合向量的“语义泛化”与关键词的“精准匹配”，随后利用重排序模型过滤噪声。
+
+混合检索旨在结合向量的"语义泛化"与关键词的"精准匹配"，随后利用重排序模型过滤噪声。
 
 **1. 基础召回 (混合检索)**
+
 - **核心原理**: 结合基于 HNSW 的 Dense Vector 相似度搜索与基于 TF-IDF 的 BM25 稀疏检索 (Sparse Vector)。
 - **实现指南**: 使用 `app/rag/retriever.py` 中的 `create_hybrid_retriever` 函数，配置 `dense_k=10` 和 `sparse_k=10`，总召回 20 条结果。
 
+```python
+from app.rag.retriever import create_hybrid_retriever
+
+retriever = create_hybrid_retriever(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+    dense_k=10,
+    sparse_k=10,
+    score_threshold=0.3
+)
+```
+
 **2. 二次精排 (Cross-Encoder)**
-- **核心原理**: 不同于双塔模型（分别算向量再求距离），交叉编码器将“用户问题 + 检索到的单例文档”拼接后整体输入 Transformer 模型，由模型直接输出 0~1 的相关性得分，精度极高。
+
+- **核心原理**: 不同于双塔模型（分别算向量再求距离），交叉编码器将"用户问题 + 检索到的单例文档"拼接后整体输入 Transformer 模型，由模型直接输出 0~1 的相关性得分，精度极高。
 - **实现指南**:
-  - 使用 `app/rag/reranker.py` 中的 `CrossEncoderReranker` 类，加载 `BAAI/bge-reranker-base` 模型
+  - 使用 `app/rag/reranker.py` 中的 `LLaMaCPPReranker` 类，加载 `bge-reranker-v2-m3` 模型
   - 设置 `top_n=5` 保留最相关的 5 条结果
-  - 使用 `ContextualCompressionRetriever` 组合基础检索器和重排序器
+
+```python
+from app.rag.reranker import LLaMaCPPReranker
+
+reranker = LLaMaCPPReranker(
+    base_url="http://127.0.0.1:8083",
+    api_key="your-api-key",
+    top_n=5
+)
+sorted_docs = reranker.compress_documents(documents, query)
+```
 
 ### Level 3: RAG-Fusion (多路改写与倒数排名融合)
+
 RAG-Fusion 通过大模型发散思维，将单一问题改写为多个相似问题，扩大搜索面，再利用数学统计算法合并结果。
 
 **1. 多路查询改写**
+
 - **核心原理**: 克服用户初始提问词不达意或视角受限的问题。
-- **实现指南**: 使用 `app/rag/query_transform.py` 中的 `MultiQueryTransformer` 类，配置 `num_queries=3` 生成 3 个不同角度的查询。
+- **实现指南**: 使用 `app/rag/query_transform.py` 中的 `MultiQueryGenerator` 类，配置 `num_queries=3` 生成 3 个不同角度的查询。
+
+```python
+from app.rag.query_transform import MultiQueryGenerator
+
+generator = MultiQueryGenerator(llm=llm, num_queries=3)
+queries = await generator.agenerate("如何申请项目资金？")
+# 返回：["如何申请项目资金？", "项目资金申请流程是什么？", "申请项目经费需要哪些步骤？"]
+```
 
 **2. 倒数排名融合 (RRF)**
-- **核心原理**: RRF (Reciprocal Rank Fusion) 是一种无需评分归一化的融合算法。公式为 $RRF\_score(d) = \sum_{q \in Q} \frac{1}{k + rank_q(d)}$，有效避免某一极端检索结果主导全局。
-- **实现指南**: 使用 `app/rag/retriever.py` 中的 `create_ensemble_retriever` 函数，配置 `search_type="rrf"` 实现倒数排名融合。
+
+- **核心原理**: RRF (Reciprocal Rank Fusion) 是一种无需评分归一化的融合算法。公式为 `RRF_score(d) = Σ 1/(k + rank_q(d))`，有效避免某一极端检索结果主导全局。
+- **实现指南**: 使用 `app/rag/fusion.py` 中的 `reciprocal_rank_fusion` 函数，配置 `k=60` 实现倒数排名融合。
+
+```python
+from app.rag.fusion import reciprocal_rank_fusion
+
+# 多个查询的检索结果
+doc_lists = [result1, result2, result3]
+fused_docs = reciprocal_rank_fusion(doc_lists, k=60)
+```
 
 ### Level 4: Agentic RAG / Self-RAG (智能体与自我反思)
-- **核心原理**: 基于 LangGraph 的 ReAct (Reasoning and Acting) 状态机路由。大模型并非每次都去死板地执行检索，而是先判断问题：“这是闲聊？还是需要查知识库？”。如果是后者，模型输出一个 `ToolCall` 指令，触发检索。
+
+- **核心原理**: 基于 LangGraph 的 ReAct (Reasoning and Acting) 状态机路由。大模型并非每次都去死板地执行检索，而是先判断问题："这是闲聊？还是需要查知识库？"。如果是后者，模型输出一个 `ToolCall` 指令，触发检索。
 - **实现指南**: 使用 `app/rag/tools.py` 中的 `search_knowledge_base` 工具，将其绑定到 LangGraph 状态机中。
 
 - **示意图**:
-  ```mermaid
-  sequenceDiagram
-      participant User
-      participant LangGraph Agent
-      participant RAG_Tool
-      participant Qdrant
-      
-      User->>LangGraph Agent: "公司报销流程是什么？"
-      LangGraph Agent->>LangGraph Agent: 思考: 这是一个内部规章问题，需要查资料
-      LangGraph Agent->>RAG_Tool: ToolCall(search_knowledge_base, "公司报销流程")
-      RAG_Tool->>Qdrant: RAG-Fusion & 混合检索
-      Qdrant-->>RAG_Tool: 原始分块
-      RAG_Tool->>RAG_Tool: Cross-Encoder 重排过滤
-      RAG_Tool-->>LangGraph Agent: 返回最相关的5条报销规定
-      LangGraph Agent->>LangGraph Agent: 思考: 资料充分，开始撰写回答
-      LangGraph Agent-->>User: "根据知识库规定，报销流程分为以下3步..."
-  ```
+
+```
+┌──────────┐     ┌──────────────┐     ┌──────────┐     ┌────────
+│   User   │────>│ LangGraph    │────>│ RAG_Tool │────>│ Qdrant │
+│          │     │ Agent        │     │          │     │        │
+│ "公司报  │     │ 思考: 这是   │     │ ToolCall │     │ RAG-   │
+│ 销流程？"│     │ 内部规章问题 │     │ search_  │     │ Fusion │
+│          │     │ 需要查资料   │     │ knowledge│     │ & 混合 │
+│          │<────│ 资料充分，   │<────│ 返回最相 │<────│ 检索   │
+│ "根据知  │     │ 开始撰写回答 │     │ 关5条规定 │     │ Cross- │
+│ 识库规定 │     │              │     │          │     │ Encoder│
+│ ..."     │     │              │     │          │     │ 重排   │
+└──────────     └──────────────     └──────────┘     └────────┘
+```
 
 ### Level 5: GraphRAG 集成 (基于图和关系的 RAG)
+
 - **核心原理**: 结合知识图谱的结构化关系和向量检索的语义相似度，解决跨文档复杂关系推理问题。
 - **实现指南**:
   - 使用 `langchain_community.graphs` 模块构建知识图谱
-  - 配置本地大模型（如 `Gemma-4-E2B`）用于实体关系抽取
+  - 配置本地大模型（如 `Gemma-4-E4B`）用于实体关系抽取
   - 实现混合检索逻辑，结合向量相似度和图路径分析
 
----
+```python
+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)
 
-除了基础的 LangChain 包外，在线检索模块为了支持重排和稀疏检索，还需要安装：
-
-```bash
-# 用于 Cross-Encoder 重排序模型 (如 BAAI/bge-reranker-base)
-pip install sentence-transformers
-
-# 用于 BM25 关键词混合检索
-pip install rank_bm25
-
-# 基础框架
-pip install langchain langchain-core langchain-openai langchain-qdrant
-
-# 与 rag_indexer 共享的依赖
-pip install qdrant-client httpx
+# 存储到图数据库
+graph = Neo4jGraph(url="bolt://localhost:7687")
+graph.add_graph_documents(graph_documents)
 ```
 
----
+## 🔧 核心组件详解
 
-## 📂 架构与文件结构设计
+### 1. 检索器 (retriever.py)
 
-```
-app/rag/
-├── __init__.py
-├── retriever.py          # 负责 Qdrant 的基础召回与混合检索
-├── reranker.py           # 负责加载 sentence-transformers 交叉编码器
-├── query_transform.py    # 负责基于 MultiQueryRetriever 的改写逻辑
-├── pipeline.py           # 组合上述组件，暴露出核心的 retrieve() 方法
-└── tools.py              # 将 Pipeline 包装成 LangChain Tool 供 Agent 调用
+提供基于 Qdrant 的向量检索能力。
+
+**基础检索器**：
+```python
+from app.rag.retriever import create_base_retriever
+
+retriever = create_base_retriever(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+    search_kwargs={"k": 20}
+)
 ```
 
----
+**混合检索器**：
+```python
+from app.rag.retriever import create_hybrid_retriever
 
-## 🔄 与 rag_indexer 集成
+retriever = create_hybrid_retriever(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+    dense_k=10,
+    sparse_k=10,
+    score_threshold=0.3
+)
+```
 
-### 数据结构兼容性
-- **向量存储**: rag_indexer 使用 Qdrant 存储子块向量，app/rag 直接从相同集合读取
-- **文档存储**: rag_indexer 使用 PostgreSQL 存储父块，app/rag 通过 `ParentDocumentRetriever` 关联
-- **嵌入模型**: 共享 `LlamaCppEmbedder` 确保向量空间一致性
+### 2. 多路查询改写 (query_transform.py)
 
-### 配置共享
-- **环境变量**: QDRANT_URL、QDRANT_API_KEY、DB_URI 等配置在两个模块间共享
-- **集合名称**: 默认使用 "rag_documents" 集合，确保数据一致性
+通过 LLM 将用户问题改写为多个不同版本，扩大搜索面。
 
----
+```python
+from app.rag.query_transform import MultiQueryGenerator
 
-## 🚀 与现有系统整合调用 (Agentic RAG 实现)
+generator = MultiQueryGenerator(llm=llm, num_queries=3)
+queries = await generator.agenerate("如何申请项目资金？")
+```
 
-基于目前 LangGraph 系统的架构，我们将摒弃将代码堆砌在一起的旧方式，而是利用 **LangChain Tools** 的特性将 RAG 优雅地注入系统：
+### 3. RRF 融合算法 (fusion.py)
 
-1. **封装检索工具 (Tool)**:
-   从 `langchain.tools` 导入 `@tool` 装饰器。定义一个名为 `search_knowledge_base(query: str)` 的函数。在函数内部，实例化并调用我们在 `pipeline.py` 中写好的多路召回与重排逻辑。
+Reciprocal Rank Fusion 算法，公式：`RRF_score(d) = Σ 1/(k + rank_q(d))`
 
-2. **模型绑定 (Bind)**:
-   在 `app/agent.py` 或 `app/nodes/tool_call.py` 中，将这个工具引入，并通过 `llm.bind_tools([search_knowledge_base])` 绑定到现有的本地大模型实例上。
+```python
+from app.rag.fusion import reciprocal_rank_fusion
 
-3. **状态机路由 (Graph Routing)**:
-   你的 LangGraph 状态机会像处理普通对话一样自动接管：当模型判断需要调用查阅规章制度或专业资料时，它会输出 `ToolCall` 消息，流转到 `tool_node` 执行上述的 RAG 检索逻辑并返回上下文。
-   
-这让你无需修改任何前端 Streamlit 流式代码，就能平滑升级为具备超级知识库检索能力的智能体 (Agent)！
+# 多个查询的检索结果
+doc_lists = [result1, result2, result3]
+fused_docs = reciprocal_rank_fusion(doc_lists, k=60)
+```
 
----
+### 4. 重排序器 (reranker.py)
 
-## 🎯 快速开始
+使用 llama.cpp 服务的 OpenAI 兼容 Rerank API 对检索结果重排序。
+
+```python
+from app.rag.reranker import LLaMaCPPReranker
+
+reranker = LLaMaCPPReranker(
+    base_url="http://127.0.0.1:8083",
+    api_key="your-api-key",
+    top_n=5
+)
+sorted_docs = reranker.compress_documents(documents, query)
+```
+
+### 5. RAG 流水线 (pipeline.py)
+
+组合上述组件的完整检索流水线。
+
+```python
+from app.rag.pipeline import RAGPipeline
+
+pipeline = RAGPipeline(
+    retriever=retriever,
+    llm=llm,
+    num_queries=3,
+    rerank_top_n=5,
+)
+
+# 异步检索
+docs = await pipeline.aretrieve("如何申请项目资金？")
+
+# 格式化上下文
+context = pipeline.format_context(docs)
+```
+
+## 🔄 与 Agent 系统集成
+
+### 封装为 LangChain Tool
+
+```python
+from langchain_core.tools import tool
+from app.rag.pipeline import RAGPipeline
+
+@tool
+def search_knowledge_base(query: str) -> str:
+    """搜索知识库获取相关信息"""
+    docs = pipeline.retrieve(query)
+    return pipeline.format_context(docs)
+```
+
+### 绑定到 LangGraph
+
+```python
+from app.graph.graph_builder import GraphBuilder
+
+# 将 RAG 工具添加到工具列表
+tools = AVAILABLE_TOOLS + [search_knowledge_base]
+
+# 构建图
+builder = GraphBuilder(llm, tools, tools_by_name)
+graph = builder.build().compile(checkpointer=checkpointer)
+```
+
+## ⚙️ 环境配置
+
+| 变量名 | 说明 | 默认值 |
+|:-------|:-----|:-------|
+| `QDRANT_URL` | Qdrant 向量数据库地址 | `http://127.0.0.1:6333` |
+| `QDRANT_API_KEY` | Qdrant API 密钥 | - |
+| `LLAMACPP_RERANKER_URL` | llama.cpp 重排序服务地址 | `http://127.0.0.1:8083` |
+| `LLAMACPP_API_KEY` | llama.cpp API 密钥 | - |
+
+## 🚀 快速开始
 
 ```python
 # 1. 初始化嵌入模型
-from rag_indexer.embedders import LlamaCppEmbedder
-embeddings = LlamaCppEmbedder()
+from rag_core.embedders import LlamaCppEmbedder
+embedder = LlamaCppEmbedder()
+embeddings = embedder.as_langchain_embeddings()
 
-# 2. 初始化语言模型（用于 RAG-Fusion）
-from langchain_openai import OpenAI
-llm = OpenAI(
-    openai_api_base="http://localhost:8000/v1",
-    openai_api_key="no-key-needed",
-    model_name="Qwen2.5-7B-Instruct",
-    temperature=0.3,
+# 2. 创建检索器
+from app.rag.retriever import create_base_retriever
+retriever = create_base_retriever(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+    search_kwargs={"k": 20}
 )
 
 # 3. 创建 RAG 流水线
-from app.rag.pipeline import RAGPipeline, RAGLevel
+from app.rag.pipeline import RAGPipeline
 pipeline = RAGPipeline(
-    embeddings=embeddings,
+    retriever=retriever,
     llm=llm,
-    config={
-        "collection_name": "rag_documents",
-        "rag_level": RAGLevel.FUSION.value,
-        "num_queries": 3,
-        "rerank_top_n": 5,
-    },
+    num_queries=3,
+    rerank_top_n=5,
 )
 
 # 4. 执行检索
-result = pipeline.retrieve("如何申请项目资金？")
+docs = pipeline.retrieve("如何申请项目资金？")
 
 # 5. 格式化上下文
-context = pipeline.format_context(result.documents)
+context = pipeline.format_context(docs)
 print(context)
 ```
+
+## 📊 检索策略对比
+
+| 策略 | 优点 | 缺点 | 适用场景 |
+|:-----|:-----|:-----|:---------|
+| **基础向量检索** | 速度快，语义理解好 | 专有名词匹配差 | 通用问答 |
+| **混合检索** | 语义 + 关键词匹配 | 需要配置稀疏向量 | 专业术语查询 |
+| **多路改写 + RRF** | 搜索面广，结果稳定 | 延迟略高 | 复杂问题 |
+| **重排序** | 精度高 | 依赖额外模型 | 最终精排 |
+
+## 🤝 与 rag_indexer 集成
+
+- **向量存储**：共享 Qdrant 集合，确保嵌入模型一致
+- **文档存储**：使用 PostgreSQL 存储父块，通过 UUID 映射
+- **集合名称**：默认使用 `rag_documents` 集合
+
+详见 [rag_indexer/README.md](../../rag_indexer/README.md)

docker/Dockerfile.backend

@@ -29,6 +29,13 @@ ENV DEBUG=false
 # =============================================================================
 # 安装依赖
 # =============================================================================
+# 复制本地模型文件到镜像
+COPY models/*.whl /tmp/models/
+
+# 安装
+RUN pip install --no-cache-dir /tmp/models/*.whl && \
+    rm -rf /tmp/models
+
 # 设置 pip 国内镜像源
 RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
 

rag_indexer/README.md

@@ -2,88 +2,202 @@
 
 该模块负责 RAG 系统的阶段一：**离线索引构建**。它将外部的非结构化数据（如文档、PDF、网页等）清洗、切分并转化为向量，最终存入向量数据库中。
 
+## 🎯 核心架构
+
+### 技术栈
+
+| 组件 | 技术选型 | 版本 | 说明 |
+|:-----|:---------|:-----|:-----|
+| **文档解析** | `unstructured` | 0.22+ | 多格式文档解析（PDF/DOCX/TXT等） |
+| **文本切分** | `langchain-text-splitters` | 内置 | 递归字符切分 + 语义切分 |
+| **语义切分** | `langchain-experimental` | 内置 | `SemanticChunker` 基于句子相似度 |
+| **嵌入模型** | `llama.cpp` | 本地服务 | `embeddinggemma-300M` GGUF 模型 |
+| **向量数据库** | `Qdrant` | 1.17+ | HNSW 索引，支持稠密/稀疏向量 |
+| **文档存储** | `PostgreSQL` | 16+ | 异步连接池，持久化父块 |
+| **编排框架** | `asyncio` | Python 3.10+ | 异步批量处理与重试 |
+
+### 数据流向总览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    builder.py                               │
+│                 IndexBuilder 入口                            │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    loaders.py                               │
+│            DocumentLoader.load_file()                        │
+│            → 返回 List[Document]                             │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│              ParentDocumentRetriever                         │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              parent_splitter (粗切)                  │    │
+│  │              父块 ~1000 字符                         │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│  ┌──────────────────────▼──────────────────────────────┐    │
+│  │              child_splitter (细切)                   │    │
+│  │              子块 ~200 字符                          │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│           ┌─────────────┴─────────────┐                      │
+│           ▼                           ▼                      │
+│     ┌─────────────┐           ┌─────────────────┐            │
+│     │ 子块向量     │           │ 父块原始内容     │            │
+│     │             │           │                 │            │
+│     ▼             │           ▼                 │            │
+│  ┌────────────┐   │      ┌─────────────────┐   │            │
+│  │vector_store│   │      │    store/       │   │            │
+│  │  (Qdrant)  │   │      │  (PostgreSQL)   │   │            │
+│  └────────────   │      └─────────────────┘   │            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 技术特性
+
+- ✅ **多格式支持**：PDF、DOCX、TXT、MD、HTML、PPTX、XLSX、JSON
+- ✅ **三种切分策略**：递归字符切分、语义切分、父子块策略
+- ✅ **Parent-Child 架构**：子块精准检索，父块完整上下文
+- ✅ **PostgreSQL DocStore**：持久化存储父块，支持异步连接池
+- ✅ **批量写入与重试**：自动处理网络波动，确保索引完整性
+- ✅ **上下文管理器**：支持同步/异步资源管理
+
+## 📂 架构与文件结构
+
+```
+rag_indexer/
+├── __init__.py
+├── cli.py                 # 命令行入口
+├── index_builder.py       # 索引构建主流水线
+├── loaders.py             # 文档加载器（多格式支持）
+├── splitters.py           # 文本切分器（递归/语义/父子块）
+├── embedders.py           # 嵌入模型封装
+├── vector_store.py        # Qdrant 向量存储
+├── store/
+│   ├── __init__.py
+│   ├── factory.py         # DocStore 工厂函数
+│   └── postgres.py        # PostgreSQL DocStore 实现
+└── test/                  # 测试脚本
+```
+
 ## 🎯 演进路线与核心算法 (Roadmap)
 
 ### Level 1: 基础暴力切分 (Basic Recursive Splitting)
+
 - **核心算法**: 递归字符切分。它按照预定义的分隔符列表（如 `["\n\n", "\n", "。", "！", "？", " ", ""]`）从大到小尝试切分文本，直到每块的大小满足最大长度限制。
 - **优缺点**: 实现极简单，速度快。但非常容易将一句话拦腰截断，导致上下文语义丢失。
 - **实现指南**:
-  - 从 `langchain_text_splitters` 导入 `RecursiveCharacterTextSplitter`。
-  - 实例化时设置 `chunk_size`（如 500）和 `chunk_overlap`（如 50），直接调用 `.split_documents(raw_docs)` 方法。
+  - 从 `langchain_text_splitters` 导入 `RecursiveCharacterTextSplitter`
+  - 实例化时设置 `chunk_size`（如 500）和 `chunk_overlap`（如 50）
+  - 直接调用 `.split_documents(raw_docs)` 方法
+
+```python
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=500,
+    chunk_overlap=50,
+    separators=["\n\n", "\n", "。", "！", "？", " ", ""]
+)
+chunks = splitter.split_documents(documents)
+```
 
 ### Level 2: 语义动态切分 (Semantic Chunking)
+
 - **核心算法**: 句子级相似度阈值算法。
-  1. 将文章按标点符号按句子拆分。
-  2. 使用轻量级 Embedding 模型将每一句向量化。
-  3. 计算相邻两句之间的余弦相似度 (Cosine Similarity)。
-  4. 当相似度低于设定阈值时（说明两句话讲的不是同一件事，语义发生了转折），在此处"切断"形成一个新的块。
+  1. 将文章按标点符号按句子拆分
+  2. 使用轻量级 Embedding 模型将每一句向量化
+  3. 计算相邻两句之间的余弦相似度 (Cosine Similarity)
+  4. 当相似度低于设定阈值时（说明两句话讲的不是同一件事，语义发生了转折），在此处"切断"形成一个新的块
 - **优缺点**: 极大程度保留了段落内语义的连贯性，对 LLM 回答非常友好。但由于在切分阶段就需要调用向量模型，耗时略长。
 - **实现指南**:
-  - 从 `langchain_text_splitters` 导入 `TextSplitter` 作为基类。
-  - 从 `langchain_experimental.text_splitter` 导入 `SemanticChunker`。
-  - 实现 `SemanticChunkerAdapter` 继承 `TextSplitter`，解决类型不兼容问题。
-  - 实例化时需要传入你已经配置好的 Embedding 模型实例（如基于 `LlamaCppEmbedder` 封装的本地模型）。
+  - 从 `langchain_experimental.text_splitter` 导入 `SemanticChunker`
+  - 实现 `SemanticChunkerAdapter` 继承 `TextSplitter`，解决类型不兼容问题
+  - 实例化时需要传入已配置好的 Embedding 模型实例
+
+```python
+from langchain_experimental.text_splitter import SemanticChunker
+
+chunker = SemanticChunker(
+    embeddings=embeddings,
+    breakpoint_threshold_type="percentile",
+    breakpoint_threshold_amount=95,
+    min_chunk_size=100
+)
+chunks = chunker.split_documents(documents)
+```
 
 ### Level 3: 高级父子块策略 (Parent-Child / Auto-merging)
+
 - **核心算法**: 层次化双重存储与映射。
-  - **切分机制**: 首先将文档粗切为较大的"父块 (Parent Chunk, 约 1000 字符)"，随后将父块细切为较小的"子块 (Child Chunk, 约 200 字符)"。
-  - **存储机制**: 仅仅将**子块**的向量存入 Qdrant 用于精准计算距离；将**父块**的原始内容存在 PostgreSQL DocStore 中，通过 UUID 相互映射。
+  - **切分机制**: 首先将文档粗切为较大的"父块 (Parent Chunk, 约 1000 字符)"，随后将父块细切为较小的"子块 (Child Chunk, 约 200 字符)"
+  - **存储机制**: 仅仅将**子块**的向量存入 Qdrant 用于精准计算距离；将**父块**的原始内容存在 PostgreSQL DocStore 中，通过 UUID 相互映射
 - **核心思路**: 解决 RAG 领域经典的矛盾——检索时块越小越容易精确命中（去除噪声）；但生成回答时，块越大越能给大模型提供充足的上下文背景。
 - **实现指南**:
-  - 使用 `langchain_classic.retrievers` 中的 `ParentDocumentRetriever` 模块。
-  - 在写入时，你需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore`。
-  - **推荐方案**: 使用 `PostgresDocStore` 作为 docstore，支持持久化存储。
-  - 将两种不同的 `TextSplitter` 分别赋值给检索器的 `child_splitter` 和 `parent_splitter`，然后调用 `.add_documents()` 即可让系统自动完成映射。
+  - 使用 `langchain_classic.retrievers` 中的 `ParentDocumentRetriever` 模块
+  - 在写入时，需要同时准备一个底层的 `VectorStore` (即 Qdrant) 和一个 `BaseStore`
+  - **推荐方案**: 使用 `PostgresDocStore` 作为 docstore，支持持久化存储
+  - 将两种不同的 `TextSplitter` 分别赋值给检索器的 `child_splitter` 和 `parent_splitter`，然后调用 `.add_documents()` 即可让系统自动完成映射
+
+```python
+from langchain.retrievers import ParentDocumentRetriever
+
+retriever = ParentDocumentRetriever(
+    vectorstore=qdrant_store,
+    docstore=postgres_docstore,
+    parent_splitter=parent_splitter,
+    child_splitter=child_splitter,
+)
+await retriever.aadd_documents(documents)
+```
 
 ### Level 3.1: PostgreSQL DocStore 集成
+
 - **核心优势**: 利用 PostgreSQL 作为持久化存储，适合生产环境。使用异步连接池，支持高并发。
 - **实现步骤**:
   1. **配置连接**: 设置 `DB_URI` 环境变量或通过 `docstore_conn_string` 参数指定
   2. **创建 docstore**: 使用 `rag_indexer.store.create_docstore()` 工厂函数
   3. **注入到 IndexBuilder**: 通过构造函数参数注入
 
-- **使用示例**:
-  ```python
-  from rag_indexer.builder import IndexBuilder, SplitterType
+```python
+from rag_indexer.store import create_docstore
 
-  # 创建 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",
-  )
-  ```
+docstore, conn_info = create_docstore(
+    connection_string="postgresql://user:pass@host:5432/db",
+    pool_config={"min_size": 5, "max_size": 20},
+)
+```
 
 ### Level 3.2: 语义切分与父子块策略结合
+
 - **核心优势**: 结合语义切分的连贯性和父子块策略的层次化存储优势，实现更精准的检索和更丰富的上下文。
 - **实现原理**:
   - **父块切分**: 使用 `RecursiveCharacterTextSplitter` 创建大块（约1000字符），提供完整的上下文背景
   - **子块切分**: 使用 `SemanticChunkerAdapter` 创建小块，根据语义连贯性动态切分，提高检索精度
   - **存储机制**: 子块向量存入 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 模型进行句子级相似度计算
+```python
+from rag_indexer.index_builder import IndexBuilder, IndexBuilderConfig
+from rag_indexer.splitters import SplitterType
+
+config = IndexBuilderConfig(
+    collection_name="rag_documents",
+    splitter_type=SplitterType.PARENT_CHILD,
+    parent_chunk_size=1000,
+    child_chunk_size=200,
+    child_splitter_type=SplitterType.SEMANTIC,  # 子块使用语义切分
+    docstore=DocstoreConfig(
+        connection_string="postgresql://user:pass@host:5432/db",
+    ),
+)
+```
 
 ### Level 4: GraphRAG（基于图和关系的 RAG）
+
 - **核心算法**: LLM 实体关系抽取 (NER & Relation Extraction)。
 - **核心思路**: 解决传统纯向量检索难以处理"跨文档复杂关系推理"的痛点（如：A公司的CEO是谁？他名下的B公司主要业务是什么？这种需要横跨多页 PDF 的跳跃性问题）。
 - **实现原理**:
@@ -97,11 +211,24 @@
   - **集成方式**: 与向量存储并行，形成混合检索系统
 - **实现指南**:
   - 使用 `langchain_community.graphs` 模块
-  - 配置本地大模型（如 `Gemma-4-E2B`）用于实体关系抽取
+  - 配置本地大模型（如 `Gemma-4-E4B`）用于实体关系抽取
   - 构建包含实体和关系的图结构，存储到图数据库
   - 实现混合检索逻辑，结合向量相似度和图路径分析
 
+```python
+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)
+```
+
 ### Level 5: 多模态 RAG (Multi-modal RAG)
+
 - **核心算法**: 跨模态嵌入和多模态融合。
 - **核心思路**: 突破纯文本限制，支持图像、表格、音频等多种数据类型的理解和检索。
 - **实现原理**:
@@ -113,168 +240,220 @@
   - **存储**: 向量数据库 + 对象存储
   - **检索**: 混合向量检索
 
----
+## 🔧 核心组件详解
 
-## 📂 架构与文件结构设计
+### 1. 文档加载器 (loaders.py)
 
-```
-rag_indexer/
-├── __init__.py
-├── loaders.py            # 负责调用 unstructured 解析不同类型文件
-├── splitters.py          # 负责实现 Recursive、Semantic 切分逻辑及适配器
-├── embedders.py          # 封装本地 llama.cpp 交互的 Embedding 接口
-├── vector_store.py       # 封装 Qdrant 写入、Upsert、Collection 初始化操作
-├── builder.py            # 核心编排文件，将上述模块串联成 Pipeline
-├── cli.py                # 命令行入口
-└── store/
-    ├── __init__.py
-    ├── factory.py        # docstore 工厂函数
-    └── postgres.py       # PostgreSQL DocStore 实现
-```
+使用 `unstructured` 库解析多种文件格式。
 
----
-
-## 🔄 工作流程详解
-
-### 数据流向总览
-
-```
-                    ┌─────────────────────────────────────────┐
-                    │            builder.py                   │
-                    │         IndexBuilder 入口                │
-                    └─────────────────┬───────────────────────┘
-                                      │
-                    ┌─────────────────▼───────────────────────┐
-                    │           loaders.py                    │
-                    │    DocumentLoader.load_file()            │
-                    │    → 返回 List[Document]                 │
-                    └─────────────────┬───────────────────────┘
-                                      │
-                    ┌─────────────────▼───────────────────────┐
-                    │     ParentDocumentRetriever               │
-                    │  ┌─────────────────────────────────┐     │
-                    │  │   parent_splitter (粗切)        │     │
-                    │  │   父块 ~1000 字符               │     │
-                    │  └────────────┬────────────────────┘     │
-                    │               │                          │
-                    │  ┌────────────▼────────────────────┐     │
-                    │  │   child_splitter (细切)         │     │
-                    │  │   子块 ~200 字符               │     │
-                    │  └────────────┬────────────────────┘     │
-                    │               │                          │
-                    │    ┌──────────┴──────────┐                │
-                    │    ▼                      ▼                │
-                    │  子块向量                 父块原始内容     │
-                    │    │                      │               │
-                    │    ▼                      ▼               │
-                    │  ┌────────────┐  ┌─────────────────┐      │
-                    │  │vector_store│  │    store/       │      │
-                    │  │  (Qdrant)  │  │  (PostgreSQL)   │      │
-                    │  └────────────┘  └─────────────────┘      │
-                    └─────────────────────────────────────────┘
-```
-
-### 文件职责详解
-
-| 文件 | 职责 | 关键类/函数 |
-|------|------|------------|
-| **builder.py** | 核心编排，负责串联整个流程 | `IndexBuilder` |
-| **loaders.py** | 解析各种文档格式（PDF、Word、TXT等） | `DocumentLoader` |
-| **splitters.py** | 文本切分策略（Recursive/Semantic）及适配器 | `SplitterType`, `get_splitter()`, `SemanticChunkerAdapter` |
-| **embedders.py** | 向量化（封装 llama.cpp embedding 接口） | `LlamaCppEmbedder` |
-| **vector_store.py** | Qdrant 向量数据库操作 | `QdrantVectorStore` |
-| **store/postgres.py** | PostgreSQL DocStore 实现 | `PostgresDocStore` |
-| **store/factory.py** | docstore 工厂函数 | `create_docstore()` |
-
-### 核心实现细节
-
-#### 1. 文本切分
-- **递归切分**: 使用 `langchain_text_splitters.RecursiveCharacterTextSplitter`，支持中文分隔符
-- **语义切分**: 使用 `langchain_experimental.text_splitter.SemanticChunker`，通过 `SemanticChunkerAdapter` 适配 `TextSplitter` 接口
-- **父子块策略**: 父块使用递归切分（1000字符），子块可选择递归或语义切分（200字符）
-
-#### 2. 向量化
-- **Embedding API**: 使用 `LlamaCppEmbedder` 封装本地 llama.cpp 服务，支持 `embed_documents` 和 `embed_query` 方法
-- **向量维度**: 自动检测模型维度（默认 2560），创建对应大小的 Qdrant 集合
-
-#### 3. 向量存储
-- **Qdrant 集成**: 使用 `langchain_qdrant.QdrantVectorStore` 作为底层存储
-- **集合管理**: 自动创建/复用集合，支持 `force_recreate` 参数
-- **批量写入**: 支持 `batch_size` 参数，避免单次请求过大
-
-#### 4. 文档存储
-- **PostgreSQL**: 使用 `PostgresDocStore` 持久化存储父块，支持异步连接池
-- **数据映射**: 通过 UUID 将子块与父块关联，检索时返回完整父块
-
-### 调用顺序
-
-#### 1. 创建 IndexBuilder（入口）
+**支持格式**：PDF、DOCX、DOC、TXT、MD、HTML、PPTX、XLSX、JSON
 
 ```python
-from rag_indexer.builder import IndexBuilder, SplitterType
+from rag_indexer.loaders import DocumentLoader
 
-builder = IndexBuilder(
-    collection_name="my_docs",
-    splitter_type=SplitterType.PARENT_CHILD,
-    parent_chunk_size=1000,
-    child_chunk_size=200,
-    docstore_conn_string="postgresql://user:pass@host:5432/db",
+loader = DocumentLoader(
+    strategy="auto",              # 解析策略：auto/fast/hi_res/ocr_only
+    ocr_languages=["chi_sim", "eng"],  # OCR 语言
+    languages=["zh"],             # 文档主语言
+    extract_images=False,         # 是否提取图片
+    pdf_infer_table_structure=True,  # 是否识别表格
+)
+
+# 加载单个文件
+docs = loader.load_file("document.pdf")
+
+# 加载整个目录
+docs = loader.load_directory("./docs/", recursive=True)
+```
+
+### 2. 文本切分器 (splitters.py)
+
+提供三种切分策略：
+
+**递归字符切分**：
+```python
+from rag_indexer.splitters import SplitterType, get_splitter
+
+splitter = get_splitter(
+    SplitterType.RECURSIVE,
+    chunk_size=500,
+    chunk_overlap=50,
 )
 ```
 
-#### 2. 构建索引
+**语义切分**：
+```python
+splitter = get_splitter(
+    SplitterType.SEMANTIC,
+    embeddings=embeddings,
+    breakpoint_threshold_type="percentile",
+    min_chunk_size=100,
+)
+```
+
+**父子块策略**：在 `IndexBuilder` 中自动配置。
+
+### 3. 索引构建器 (index_builder.py)
+
+核心编排模块，串联整个索引构建流程。
 
 ```python
-import asyncio
+from rag_indexer.index_builder import IndexBuilder, IndexBuilderConfig, DocstoreConfig
+from rag_indexer.splitters import SplitterType
 
-# 方式A：从单个文件构建
-async def main():
-    count = await builder.build_from_file("/path/to/document.pdf")
-    print(f"已索引 {count} 个块")
+# 配置
+config = IndexBuilderConfig(
+    collection_name="rag_documents",
+    splitter_type=SplitterType.PARENT_CHILD,
+    parent_chunk_size=1000,
+    child_chunk_size=200,
+    child_splitter_type=SplitterType.SEMANTIC,
+    docstore=DocstoreConfig(
+        connection_string="postgresql://user:pass@host:5432/db",
+    ),
+)
 
-# 方式B：从目录批量构建
-async def main():
-    count = await builder.build_from_directory("/path/to/docs/")
-    print(f"已索引 {count} 个块")
-
-asyncio.run(main())
+# 构建索引
+async with IndexBuilder(config) as builder:
+    # 从单个文件构建
+    count = await builder.build_from_file("document.pdf")
+    
+    # 或从目录批量构建
+    count = await builder.build_from_directory("./docs/")
+    
+    print(f"已索引 {count} 个文档")
 ```
 
-#### 3. 检索（获取完整父块上下文）
+### 4. 向量存储 (vector_store.py)
+
+封装 Qdrant 向量数据库操作。
 
 ```python
-import asyncio
+from rag_core import QdrantVectorStore
 
-async def main():
-    # 检索时返回完整父块
-    results = await builder.search_with_parent_context("查询内容", k=5)
-    for doc in results:
-        print(doc.page_content)
+vector_store = QdrantVectorStore(
+    collection_name="rag_documents",
+    embeddings=embeddings,
+)
 
-asyncio.run(main())
+# 创建集合
+vector_store.create_collection()
+
+# 添加文档
+vector_store.add_documents(chunks)
 ```
 
-### 检索流程
+### 5. PostgreSQL DocStore (store/postgres.py)
 
-```
-1. vector_store.similarity_search() → 从 Qdrant 找到相关子块
-2. retriever.get_relevant_documents() → 根据子块 ID 获取对应父块
-3. 返回完整父块给用户
+持久化存储父块内容，支持异步连接池。
+
+```python
+from rag_core.store import create_docstore
+
+docstore, conn_info = create_docstore(
+    connection_string="postgresql://user:pass@host:5432/db",
+    pool_config={"min_size": 5, "max_size": 20},
+)
 ```
 
----
+## 📊 切分策略对比
 
-### 串联与触发方式
-使用 `cli.py` 入口脚本：
+| 策略 | 原理 | 优点 | 缺点 | 适用场景 |
+|:-----|:-----|:-----|:-----|:---------|
+| **递归字符** | 按分隔符递归切分 | 速度快，实现简单 | 可能截断语义 | 简单文档 |
+| **语义切分** | 基于句子相似度阈值 | 语义连贯性好 | 需要 Embedding 模型 | 专业文档 |
+| **父子块** | 大块存储+小块检索 | 检索精准+上下文完整 | 存储复杂度高 | 生产环境 |
+
+## 🚀 快速开始
+
+### 命令行方式
 
 ```bash
 # 设置环境变量
 export QDRANT_URL="http://115.190.121.151:6333"
-export QDRANT_API_KEY="your-api-key"
 export DB_URI="postgresql://postgres:password@host:5432/langgraph_db?sslmode=disable"
 
 # 执行索引构建
-python -m rag_indexer.cli --path data/user_docs/tech_manual.pdf
+python -m rag_indexer.cli --path data/user_docs/ --recursive
 ```
 
-这相当于系统后台的**"离线学习阶段"**，你可以随时挂载定时任务去扫描文件夹，增量更新知识库。
+### Python API 方式
+
+```python
+import asyncio
+from rag_indexer.index_builder import IndexBuilder, IndexBuilderConfig, DocstoreConfig
+from rag_indexer.splitters import SplitterType
+
+async def main():
+    config = IndexBuilderConfig(
+        collection_name="rag_documents",
+        splitter_type=SplitterType.PARENT_CHILD,
+        parent_chunk_size=1000,
+        child_chunk_size=200,
+        child_splitter_type=SplitterType.SEMANTIC,
+    )
+    
+    async with IndexBuilder(config) as builder:
+        count = await builder.build_from_directory("./user_docs/")
+        print(f"索引构建完成，共处理 {count} 个文档")
+
+asyncio.run(main())
+```
+
+## ⚙️ 环境配置
+
+| 变量名 | 说明 | 默认值 |
+|:-------|:-----|:-------|
+| `QDRANT_URL` | Qdrant 向量数据库地址 | `http://127.0.0.1:6333` |
+| `QDRANT_API_KEY` | Qdrant API 密钥 | - |
+| `DB_URI` | PostgreSQL 连接字符串 | - |
+| `LLAMACPP_EMBEDDING_URL` | Embedding 服务地址 | `http://127.0.0.1:8082/v1` |
+| `LLAMACPP_API_KEY` | llama.cpp API 密钥 | - |
+
+## 🔄 与 app/rag 集成
+
+- **向量存储**：共享 Qdrant 集合，确保嵌入模型一致
+- **文档存储**：父块存入 PostgreSQL，通过 UUID 与子块关联
+- **集合名称**：默认使用 `rag_documents` 集合
+- **嵌入模型**：使用相同的 `LlamaCppEmbedder` 确保向量空间一致
+
+详见 [app/rag/README.md](../app/rag/README.md)
+
+## 📝 高级配置
+
+### 自定义切分参数
+
+```python
+config = IndexBuilderConfig(
+    collection_name="my_docs",
+    splitter_type=SplitterType.PARENT_CHILD,
+    parent_chunk_size=1500,      # 更大的父块
+    child_chunk_size=300,        # 更大的子块
+    parent_chunk_overlap=150,    # 父块重叠
+    child_chunk_overlap=30,      # 子块重叠
+    search_k=10,                 # 检索返回数量
+)
+```
+
+### 批量处理与重试
+
+索引构建器内置自动重试机制，处理网络波动：
+
+- 最大重试次数：5 次
+- 退避策略：指数退避（2s, 4s, 8s, 16s, 32s）
+- 批量大小：10 个文档/批次
+
+### 资源管理
+
+```python
+# 方式一：上下文管理器（推荐）
+async with IndexBuilder(config) as builder:
+    await builder.build_from_directory("./docs/")
+
+# 方式二：手动管理
+builder = IndexBuilder(config)
+try:
+    await builder.build_from_directory("./docs/")
+finally:
+    await builder.aclose()
+```