Upload folder using huggingface_hub

.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "Bash(/data/huangjie/miniforge3/envs/cad/bin/python --version)",
+      "Bash(/data/huangjie/miniforge3/envs/cad/bin/pip show *)",
+      "Bash(timeout 5 /data/huangjie/miniforge3/envs/cad/bin/python -c \"import pymupdf; print\\('pymupdf OK, version:', pymupdf.version\\)\")",
+      "Bash(python:*)"
+    ]
+  }
+}

.env.example

@@ -1,47 +1,46 @@
+# ============================================================
+#  环境变量配置
 
-# # LLM API(OpenAI API格式) 
-# EMBEDDING_MODEL_PATH = "/data/huangjie/.cache/modelscope/hub/models/Qwen/Qwen3-VL-Embedding-2B"
-EMBEDDING_API_BASE_URL = "http://10.126.102.211:8010/v1/"
-# EMBEDDING_API_KEY = "xxx"
-EMBEDDING_API_PORT = 8010
-EMBEDDING_MODEL_NAME = "AXERA-TECH/Qwen3-VL-Embedding-2B"
+# .env 配置
+OCR_ENGINE=api                                 # 改为 api 模式
+OCR_API_BASE=http://127.0.0.1:8015/v1          # vLLM 服务地址
+OCR_API_MODEL=AXERA-TECH/PaddleOCR-VL-1.5        # 模型名
+OCR_API_KEY=not-needed
+OCR_TASK=ocr                                   # 任务类型
 
 
-# # VLM API(OpenAI API格式)
-# VLM_MODEL_PATH = "/data/huangjie/.cache/modelscope/hub/models/Qwen/Qwen3-VL-2B-Instruct"
-VLM_API_BASE_URL = "http://10.126.102.211:8011/v1/"
-# VLM_API_KEY = "xxxx"
-VLM_API_PORT = 8011
-VLM_MODEL_NAME = "AXERA-TECH/Qwen3-VL-2B-Instruct"
+EMBEDDING_MODEL_NAME=AXERA-TECH/Qwen3-Embedding-0.6B
+EMBEDDING_API_BASE=http://127.0.0.1:8014/v1
+EMBEDDING_API_KEY=sk-08ab126e77f04a0c99bb30154ab0876f
+EMBEDDING_BATCH_SIZE=4
 
 
-# # LLM API(OpenAI API格式) 
-# LLM_MODEL_PATH = "/data/huangjie/.cache/modelscope/hub/models/Qwen/Qwen3-VL-Embedding-2B"
-LLM_API_BASE_URL = "http://10.126.102.211:8012/v1/"
-# LLM_API_KEY = "xxx"
-LLM_API_PORT = 8012
-LLM_MODEL_NAME = "AXERA-TECH/Qwen3-1.7B"
+LLM_API_BASE =http://127.0.0.1:8013/v1
+LLM_API_KEY = not-needed
+LLM_MODEL_NAME =AXERA-TECH/Qwen3-1.7B-GPTQ-Int4
+LLM_TEMPERATURE=0.1
+LLM_MAX_TOKENS=2048
 
 
-# # ASR API 
-SHERPA_MODEL_DIR = "/root/huangjie/AXERA-TECH/SenseVoice"
-SHERPA_ASR_URL = "http://10.126.102.211:8013"
-# ASR_API_KEY = "xxx"
-SHERPA_ASR_API_PORT = 8013
-SHERPA_MODEL_FILE = "/root/huangjie/AXERA-TECH/SenseVoice/ax650/model-10-seconds.axmodel"
+# ---- 向量数据库 ----
+VECTOR_STORE_TYPE=chroma
+CHROMA_COLLECTION_NAME=pdf_ocr_knowledge
 
+# ---- PDF 渲染 ----
+PDF_RENDER_DPI=300
+MAX_FILE_SIZE_MB=50
 
-# # Tokenizer API 
-Tokenizer_MODEL_PATH = "./VideoAgent/_llm/tokenizer_model/Qwen/Qwen3-1.7B"  # Tokenizer 文件夹(含tokenizer_config.json, tokenizer.json, vocab.json文件)
-Tokenizer_API_BASE_URL = "http://0.0.0.0:8014/"
-Tokenizer_API_KEY = "xxxx"
-Tokenizer_API_PORT = 8014
+# ---- 文本分割与检索 ----
+CHUNK_SIZE=800
+CHUNK_OVERLAP=150
+RETRIEVAL_TOP_K=5
 
+# ---- 日志 ----
+LOG_LEVEL=INFO
 
-
-VIDEORAG_VIDEO_SEGMENT_LENGTH = "10"
-VIDEORAG_ROUGH_NUM_FRAMES_PER_SEGMENT = "5"
-VIDEORAG_RETRIEVAL_TOPK_CHUNKS = "2"
-VIDEORAG_QUERY_BETTER_THAN_THRESHOLD = "0.2"
-VIDEORAG_CHUNK_TOKEN_SIZE = "800"
-VIDEORAG_SEGMENT_RETRIEVAL_TOP_K = "2"
+OCR_VL_BACKEND=native
+OCR_USE_LAYOUT=false
+OCR_LAYOUT_THRESHOLD=0.5
+OCR_USE_CHART=false
+OCR_MAX_NEW_TOKENS=4096
+OCR_TEMPERATURE=0.0

.gitattributes

@@ -44,3 +44,11 @@ image-10.png filter=lfs diff=lfs merge=lfs -text
 image-7.png filter=lfs diff=lfs merge=lfs -text
 image-8.png filter=lfs diff=lfs merge=lfs -text
 image-9.png filter=lfs diff=lfs merge=lfs -text
+assets/image-1.png filter=lfs diff=lfs merge=lfs -text
+assets/image-13.png filter=lfs diff=lfs merge=lfs -text
+assets/image-14.png filter=lfs diff=lfs merge=lfs -text
+assets/image-16.png filter=lfs diff=lfs merge=lfs -text
+assets/image.png filter=lfs diff=lfs merge=lfs -text
+assets/OCR_RAG.mp4 filter=lfs diff=lfs merge=lfs -text
+test.png filter=lfs diff=lfs merge=lfs -text
+国药准字H37020386_布洛芬片.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,2 +1,5 @@
 .env
-uphg.py
+uphg.py
+.claude/
+.vscode/
+__pycache__/

README.md

@@ -1,40 +1,88 @@
-# VideoAgent — 视频理解分析(基于 AX650N)
+# 基于 OCR + RAG 的文档智能问答系统
 
-基于 AX650N 芯片平台，构建多模态 VideoAgent，面向视频理解与检索，支持长视频智能分析与自然语言问答。
+基于 **PaddleOCR-VL** + **Qwen3-Embedding** + **Qwen3** + **LangChain RAG** 的文档智能问答系统，支持 PDF、扫描件及常见图片格式的端到端识别与检索问答。
 
-<p align="center">
-  <img src="https://img.shields.io/badge/platform-AX650N-blue" alt="Platform">
-  <img src="https://img.shields.io/badge/python-3.10+-green" alt="Python">
-  
-</p>
+## 模型栈
 
----
-
-## 核心功能
+| 模型类型 | 模型名称 | 说明 |
+|---------|---------|------|
+| **OCR** | [PaddleOCR-VL-1.5](https://huggingface.co/AXERA-TECH/PaddleOCR-VL-1.5) |  OCR 识别模型 |
+| **LLM** | [Qwen3-1.7B](https://huggingface.co/AXERA-TECH/Qwen3-1.7B-GPTQ-Int4) | 大语言模型 |
+| **Embedding** | [Qwen3-Embedding-0.6B](https://huggingface.co/AXERA-TECH/Qwen3-Embedding-0.6B) | 文本嵌入模型 |
 
-- **芯片平台部署** — 基于 AX650N 芯片部署全部模型，端到端运行完整流程
-- **视频智能索引** — 自动分段、特征提取、多模态信息融合（ASR + VLM）
-- **向量检索** — 高效相似度检索与结果融合，支持跨模态查询
-- **自然语言问答** — 用自然语言提问，基于视频内容生成回答
+## 支持格式
 
----
+- PDF（文字型 / 扫描版）
+- PNG / JPG / JPEG / BMP / TIF / TIFF
 
-## 模型配置
+## 架构
 
-基于 AX650N 芯片平台运行前，请下载以下模型并参照相关文档完成部署：
+```
+文件上传 (PDF/PNG/JPG/BMP/TIF)
+               │
+               ▼
+┌─────────────────────────────────┐
+│  PaddleOCR-VL                    │
+│  端到端识别: 文本 + 版面 + 表格   │
+│  输出: Markdown / JSON           │
+└──────────────┬──────────────────┘
+               │  LangChain Documents
+               ▼
+┌─────────────────────────────────┐
+│  文本处理                        │
+│  Markdown 清洗 → 语义感知分割    │
+│  表格/公式 独立提取              │
+└──────────────┬──────────────────┘
+               │  Document Chunks
+               ▼
+┌─────────────────────────────────┐
+│  Qwen3-Embedding                │
+│  instruct-aware 向量嵌入        │
+└──────────────┬──────────────────┘
+               │  Vector Embeddings
+               ▼
+┌─────────────────────────────────┐
+│  Chroma / FAISS 向量数据库      │
+│  相似度检索 / MMR / 元数据过滤   │
+└──────────────┬──────────────────┘
+               │  Top-K 相关文档
+               ▼
+┌─────────────────────────────────┐
+│  Qwen3-1.7B                     │
+│  LangChain LCEL RAG 链          │
+│  多轮对话 + 来源引用             │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│  Web UI (Gradio)                │
+│  上传 | 问答 | 来源 | 状态       │
+└─────────────────────────────────┘
+```
 
-| 模型类型 | 模型名称 | 说明 |
-|---------|---------|------|
-| **ASR** | [SenseVoiceSmall-axmodel](https://huggingface.co/M5Stack/SenseVoiceSmall-axmodel) | 多语言语音理解模型 |
-| **VLM** | [Qwen3-VL-2B-Instruct-GPTQ-Int4](https://huggingface.co/AXERA-TECH/Qwen3-VL-2B-Instruct-GPTQ-Int4) | 多模态视觉语言模型 |
-| **LLM** | [Qwen3-1.7B](https://huggingface.co/AXERA-TECH/Qwen3-1.7B) | 大语言模型 |
-| **Embedding** | [Qwen3-VL-Embedding-2B-AX650](https://huggingface.co/AXERA-TECH/Qwen3-VL-Embedding-2B-AX650-C128_P1280_CTX1407) | 多模态嵌入模型 |
+## 项目结构
 
----
+```
+pdfocr/
+├── requirements.txt      # Python 依赖
+├── .env.example          # 环境变量模板
+├── config.py             # 全局配置中心
+├── ocr_loader.py         # PaddleOCR-VL 加载器 (支持多格式)
+├── text_processor.py     # Markdown 清洗 + 智能分割
+├── embeddings.py         # Qwen3-Embedding 向量嵌入
+├── vector_store.py       # 向量数据库管理 (Chroma/FAISS)
+├── rag_chain.py          # RAG 问答链 (Qwen3)
+├── app.py                # Web UI
+└── data/                 # 运行时数据
+    ├── uploads/
+    ├── ocr_output/
+    ├── vector_db/
+    └── logs/
+```
 
 ## 快速开始
 
-### 1. 安装依赖
+### 1. 环境准备
 
 ```bash
 pip install -r requirements.txt
@@ -42,7 +90,7 @@ pip install -r requirements.txt
 
 ### 2. 配置环境变量
 
-Embedding、VLM、LLM、ASR、Tokenizer 均通过环境变量配置。其中 Embedding、VLM、LLM 兼容 OpenAI API 格式。
+OCR、LLM、Embedding 均通过环境变量配置，兼容 OpenAI API 格式。
 
 ```bash
 cp .env.example .env
@@ -53,22 +101,24 @@ cp .env.example .env
 
 ```ini
 # LLM API（OpenAI API 格式）
-LLM_MODEL_PATH = "/data/huangjie/.cache/modelscope/hub/models/Qwen/Qwen3-VL-Embedding-2B"
-LLM_API_BASE_URL = "http://0.0.0.0:8012/v1/"
-LLM_API_KEY = "xxx"
-LLM_MODEL_NAME = "AXERA-TECH/Qwen3-1.7B"
-LLM_API_PORT = 8012
-
-# ASR API
-SHERPA_MODEL_DIR = "/root/huangjie/AXERA-TECH/SenseVoice"
-SHERPA_ASR_URL = "http://0.0.0.0:8013"
-SHERPA_ASR_API_PORT = 8013
-SHERPA_MODEL_FILE = "/root/huangjie/AXERA-TECH/SenseVoice/ax650/model-10-seconds.axmodel"
-
-# Tokenizer API
-Tokenizer_MODEL_PATH = "/root/huangjie/project/VideoAgent_api507/VideoAgent/_llm/tokenizer_model/Qwen/Qwen3-1.7B"
-Tokenizer_API_BASE_URL = "http://0.0.0.0:8014"
-Tokenizer_API_PORT = 8014
+LLM_API_KEY=not-needed
+LLM_API_BASE=http://127.0.0.1:8013/v1
+LLM_MODEL_NAME=AXERA-TECH/Qwen3-1.7B-GPTQ-Int4
+LLM_TEMPERATURE=0.1
+LLM_MAX_TOKENS=2048
+
+# Embedding API
+EMBEDDING_MODEL_NAME=AXERA-TECH/Qwen3-Embedding-0.6B
+EMBEDDING_API_BASE=http://127.0.0.1:8014/v1
+EMBEDDING_API_KEY=not-needed
+EMBEDDING_BATCH_SIZE=4
+
+# OCR API
+OCR_ENGINE=api
+OCR_API_BASE=http://127.0.0.1:8015/v1
+OCR_API_MODEL=AXERA-TECH/PaddleOCR-VL-1.5
+OCR_API_KEY=not-needed
+OCR_TASK=ocr
 ```
 
 ### 3. 启动模型服务
@@ -76,86 +126,158 @@ Tokenizer_API_PORT = 8014
 基于 AX650N 芯片启动各模型服务：
 
 ```bash
-# Embedding 服务 — 端口 8010
-axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-VL-Embedding-2B-AX650-C128_P1280_CTX1407 --port 8010
+# LLM 服务 — 端口 8013
+axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-1.7B --port 8013
+
+# Embedding 服务 — 端口 8014
+axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-Embedding-0.6B --port 8014
 
-# VLM 服务 — 端口 8011
-axllm serve /root/huangjie/AXERA-TECH/Qwen3-VL-2B-Instruct-GPTQ-Int4 --port 8011
+# OCR 服务 — 端口 8015
+axllm serve /root/huangjie/AXERA-TECH/PaddleOCR-VL-1.5 --port 8015
+```
 
-# LLM 服务 — 端口 8012
-axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-1.7B --port 8012
+## 使用方式
 
-# ASR 服务 — 端口 8013
-python VideoAgent/_server/sherpa_asr_server.py
+### 1. Web UI（推荐）
 
-# Tokenizer 服务 — 端口 8014
-python VideoAgent/_server/tokenizer_server.py
+```bash
+python app.py
 ```
 
-### 4. 使用方式
+浏览器访问 **http://localhost:7860**
 
-#### Web UI（推荐）
+**问答界面**
 
-```bash
-python webui.py
+![alt text](assets/image-16.png)
+
+**预览界面**
+
+![alt text](assets/image-1.png)
+
+**设置界面**
+
+![alt text](assets/image.png)
+
+### 2. Python API
+
+```python
+from rag_chain import PDFRAGPipeline
+
+# 初始化流水线
+pipeline = PDFRAGPipeline()
+
+# 处理文档 (支持 PDF/PNG/JPG/BMP/TIF)
+pipeline.ingest("document.pdf")
+pipeline.ingest("scan.png")
+
+# 问答
+result = pipeline.ask("文档主要内容是什么?")
+print(result["answer"])
+print(result["sources"])
+
+# 多轮对话
+result = pipeline.ask_with_history(
+    "那第二章呢?",
+    chat_history=[
+        {"role": "user", "content": "文档主要讲什么?"},
+        {"role": "assistant", "content": "文档主要介绍了..."},
+    ]
+)
+
+# 流式输出
+for chunk in pipeline.ask_stream("请总结文档"):
+    print(chunk, end="", flush=True)
 ```
 
-浏览器访问 **http://localhost:7869**
+### 3. 命令行
 
-| 索引界面 | 检索界面 |
-|---------|---------|
-| ![索引界面](image-5.png) | ![检索界面](image-4.png) |
+```bash
+# 直接对文件提问
+python rag_chain.py document.pdf "文档主要内容是什么?"
+
+# OCR 识别并输出 Markdown
+python ocr_loader.py scan.png --md
+
+# OCR 识别并输出 JSON
+python ocr_loader.py document.pdf --json
+```
 
-#### Python SDK
+### 4. 分步使用
 
 ```python
-from VideoAgent import VideoRAG, QueryParam
+from ocr_loader import PaddleOCRLoader
+from text_processor import TextProcessingPipeline
+from vector_store import build_vector_store
+from rag_chain import RAGChain
+
+# 1. OCR
+loader = PaddleOCRLoader("document.pdf", dpi=300)
+documents = loader.load()
 
-# 初始化 RAG 系统
-rag = VideoRAG(working_dir="./working_dir")
+# 2. 文本处理
+pipeline = TextProcessingPipeline(chunk_size=800, chunk_overlap=150)
+chunks = pipeline.process(documents)
 
-# 索引视频文件
-rag.insert_video(video_path_list=["video1.mp4", "video2.mp4"])
+# 3. 向量化
+manager = build_vector_store(chunks)
 
-# 查询视频内容
-result = rag.query(query="视频中什么时候出现张飞？", param=QueryParam())
-print(result)
+# 4. 问答
+chain = RAGChain(vector_store_manager=manager)
+result = chain.query("文档主要内容?")
 ```
 
 ---
 
-## 工作流程
+## 案例演示
 
-### 视频索引流程
+### 演示视频
 
-![索引流程](image-2.png)
-### 查询流程
+[观看演示视频](assets/OCR_RAG.mp4)
 
+### 使用步骤
 
-![查询流程](image-3.png)
+**1. 在 AX650N 芯片上启动模型服务**
 
+LLM 服务
 
----
+![alt text](assets/image-4.png)
 
-## 项目结构
+Embedding 服务
 
-```
-VideoAgent-AX650N/
-├── VideoAgent/                 # 核心包
-│   ├── _llm/                   # 模型定义层
-│   ├── _server/                # 服务层（FastAPI）
-│   ├── _storage/               # 存储层
-│   ├── _videoutil/             # 视频处理工具
-│   └── vidrag_pipeline.py      # 核心管道
-├── working_dir/                # 运行时数据目录
-├── webui.py                    # Gradio Web 入口
-├── videorag_longervideos.py    # 测试脚本
-└── README.md                   # 项目文档
-```
+![alt text](assets/image-3.png)
 
----
+OCR 服务
+
+![alt text](assets/image-2.png)
+
+运行启动服务
+
+![alt text](assets/image-5.png)
+
+**2. 上传原始文件**
+
+支持 PDF / PNG / JPG / BMP / TIF
+
+![alt text](assets/image-12.png)
+
+**3. 进行 OCR 识别**
+
+OCR 识别并输出文本，支持原始文件和 OCR 结果同时查看：
+
+![alt text](assets/image-13.png)
+
+![alt text](assets/image-14.png)
+
+**4. RAG 智能问答**
+
+根据输入内容检索相关文本片段并返回结果。
+
+例如提问「布洛芬每日用量」，系统检索到说明书中关于用量的文本片段，依据该文本进行回答：
+
+![alt text](assets/image-15.png)
 
-## 参考项目
+## 硬件资源使用
 
-- 香港大学数据科学实验室（HKUDS）— [VideoRAG](https://github.com/HKUDS/VideoRAG)：超长视频跨模态检索增强生成框架
+基于 AX650N 平台运行本项目时，内存（CMM）、Flash 占用情况如下：
 
+![alt text](assets/image-7.png)

app.py

@@ -0,0 +1,629 @@
+"""
+============================================================
+OCR RAG 智能问答系统 - Web UI (FastAPI)
+============================================================
+
+启动:
+    python app.py
+访问: http://localhost:7860
+
+"""
+
+import gc
+import time
+import shutil
+from pathlib import Path
+from typing import List, Optional, Dict, Any, Tuple
+
+
+
+def _apply_env_patches():
+    """尽早修复已知的环境兼容性问题"""
+    import sys
+    import types
+
+    # Step 1: Mock `langchain_text_splitters` 以避免其 __init__.py
+    #         触发 sentence_transformers → transformers 损坏链
+    if "langchain_text_splitters" not in sys.modules:
+        mock_lts = types.ModuleType("langchain_text_splitters")
+        mock_lts.__path__ = []
+        sys.modules["langchain_text_splitters"] = mock_lts
+
+    # Step 2: 将我们的 RecursiveCharacterTextSplitter 注入到 mock 模块
+    mock_lts = sys.modules["langchain_text_splitters"]
+    from text_processor import RecursiveCharacterTextSplitter as OurSplitter
+    mock_lts.RecursiveCharacterTextSplitter = OurSplitter
+
+    # Step 3: 确保 torch 对 transformers 可用
+    if "torch" not in sys.modules:
+        try:
+            import torch  # noqa: F401
+        except ImportError:
+            pass
+
+
+_apply_env_patches()
+
+from fastapi import FastAPI, File, Form, UploadFile, HTTPException
+from fastapi.responses import HTMLResponse, FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from loguru import logger
+
+import config
+from rag_chain import PDFRAGPipeline, RAGChain
+from vector_store import VectorStoreManager
+from ocr_loader import PaddleOCRLoader
+from text_processor import TextProcessingPipeline
+
+
+# ============================================================
+# 全局状态
+# ============================================================
+
+_pipeline: Optional[PDFRAGPipeline] = None
+_processed_files: List[Dict[str, Any]] = []
+_chat_history: List[Dict[str, str]] = []
+
+# OCR 文本持久化目录
+_OCR_OUTPUT_DIR = config.OCR_OUTPUT_DIR
+_FILES_JSON = _OCR_OUTPUT_DIR / "_files.json"
+
+
+def _load_files_from_disk():
+    """启动时从磁盘恢复已处理文件列表"""
+    global _processed_files
+    if _FILES_JSON.exists():
+        try:
+            import json
+            data = json.loads(_FILES_JSON.read_text(encoding="utf-8"))
+            _processed_files = data.get("files", [])
+            logger.info(f"从磁盘恢复 {len(_processed_files)} 个已处理文件")
+        except Exception as e:
+            logger.warning(f"恢复文件列表失败: {e}")
+
+
+def _save_files_to_disk():
+    """将已处理文件列表持久化到磁盘"""
+    import json
+    _FILES_JSON.parent.mkdir(parents=True, exist_ok=True)
+    _FILES_JSON.write_text(
+        json.dumps({"files": _processed_files}, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _get_ocr_text_path(filename: str) -> Path:
+    """获取 OCR 文本的磁盘路径"""
+    return _OCR_OUTPUT_DIR / f"{Path(filename).stem}.txt"
+
+
+def _save_ocr_text(filename: str, text: str):
+    """保存 OCR 文本到磁盘"""
+    path = _get_ocr_text_path(filename)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _load_ocr_text(filename: str) -> str:
+    """从磁盘读取 OCR 文本"""
+    path = _get_ocr_text_path(filename)
+    if path.exists():
+        return path.read_text(encoding="utf-8")
+    return ""
+
+
+def _delete_ocr_text(filename: str):
+    """从磁盘删除 OCR 文本"""
+    path = _get_ocr_text_path(filename)
+    if path.exists():
+        path.unlink()
+
+
+def get_pipeline() -> PDFRAGPipeline:
+    global _pipeline
+    if _pipeline is None:
+        _pipeline = PDFRAGPipeline(verbose=False)
+    return _pipeline
+
+
+# ============================================================
+# 核心处理逻辑 (从原 Gradio 回调中提取)
+# ============================================================
+
+def process_file_impl(
+    file_path: Path,
+    chunk_size: int = 800,
+    chunk_overlap: int = 150,
+) -> Tuple[Dict[str, Any], str]:
+    """处理上传的文件: OCR → 分割 → 向量化入库"""
+    global _pipeline, _processed_files, _chat_history
+
+    suffix = file_path.suffix.lower()
+
+    if suffix not in config.SUPPORTED_FORMATS:
+        raise ValueError(
+            f"不支持的文件格式: {suffix}\n支持: {', '.join(sorted(config.SUPPORTED_FORMATS))}"
+        )
+
+    file_size_mb = file_path.stat().st_size / (1024 * 1024)
+    if file_size_mb > config.MAX_FILE_SIZE_MB:
+        raise ValueError(f"文件过大: {file_size_mb:.1f}MB (限制: {config.MAX_FILE_SIZE_MB}MB)")
+
+    # 复用 pipeline 对象避免重复创建 LLM 实例
+    if _pipeline is None:
+        _pipeline = PDFRAGPipeline(
+            chunk_size=int(chunk_size),
+            chunk_overlap=int(chunk_overlap),
+            verbose=False,
+        )
+
+    loader = PaddleOCRLoader(str(file_path), verbose=False)
+    raw_docs = loader.load()
+
+    # 逐页写入 OCR 文本到磁盘，避免内存中构建完整副本
+    ocr_path = _get_ocr_text_path(file_path.name)
+    ocr_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(ocr_path, "w", encoding="utf-8") as ocr_f:
+        preview_parts = []
+        for i, doc in enumerate(raw_docs):
+            page_num = doc.metadata.get("page", i + 1)
+            ocr_f.write(f"--- 第 {page_num} 页 ---\n{doc.page_content}\n\n")
+            if i < 3:
+                preview_parts.append(
+                    f"--- 第 {page_num} 页 ---\n{doc.page_content[:200]}..."
+                )
+        if len(raw_docs) > 3:
+            preview_parts.append(f"\n... (共 {len(raw_docs)} 页/文档)")
+    preview = "\n\n".join(preview_parts)
+
+    # 文本分割
+    pipeline = TextProcessingPipeline(
+        chunk_size=int(chunk_size),
+        chunk_overlap=int(chunk_overlap),
+    )
+    chunks = pipeline.process(raw_docs)
+
+    # 释放 raw_docs 引用，让 GC 可以回收
+    raw_docs.clear()
+
+    # 向量化入库
+    _pipeline._vector_store_manager = VectorStoreManager(
+        store_type=config.VECTOR_STORE_TYPE,
+    )
+    _pipeline._vector_store_manager.clear()
+    _pipeline._vector_store_manager.add_documents(chunks)
+
+    _pipeline._rag_chain = RAGChain(
+        vector_store_manager=_pipeline._vector_store_manager,
+        llm=_pipeline.llm,
+    )
+
+    _chat_history = []
+
+    file_info = {
+        "name": file_path.name,
+        "format": suffix,
+        "pages": len(raw_docs) if raw_docs else _count_ocr_pages(ocr_path),
+        "chunks": len(chunks),
+        "size_mb": round(file_size_mb, 2),
+        "time": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "path": str(file_path),
+    }
+    _processed_files.append(file_info)
+
+    # 强制 GC 回收 OCR 过程中产生的临时对象
+    del chunks
+    gc.collect()
+
+    logger.info(f"文件处理成功: {file_path.name}, {file_info['pages']} 页, {file_info['chunks']} 块")
+    return file_info, preview
+
+
+def _count_ocr_pages(ocr_path: Path) -> int:
+    """从保存的 OCR 文件统计页数"""
+    try:
+        text = ocr_path.read_text(encoding="utf-8")
+        return text.count("--- 第") or 1
+    except Exception:
+        return 1
+
+
+def ask_question_impl(question: str) -> Dict[str, Any]:
+    """执行 RAG 问答"""
+    global _pipeline, _chat_history
+
+    if _pipeline is None or not _pipeline.is_ready:
+        raise RuntimeError("请先上传并处理文件")
+
+    result = _pipeline.ask_with_history(question, _chat_history)
+
+    _chat_history.append({"role": "user", "content": question})
+    _chat_history.append({"role": "assistant", "content": result["answer"]})
+    # 限制历史长度以防止内存无限增长 (保留最近 20 轮)
+    if len(_chat_history) > 40:  # 20 pairs
+        _chat_history = _chat_history[-40:]
+
+    sources = []
+    for src in result.get("sources", []):
+        sources.append({
+            "rank": src["rank"],
+            "document": src["document"],
+            "page": src["page"],
+            "content_type": src.get("content_type", ""),
+            "content": src["content"][:200],
+        })
+
+    return {"answer": result["answer"], "sources": sources}
+
+
+def clear_chat_impl():
+    global _chat_history
+    _chat_history = []
+
+
+def get_system_status_impl() -> Dict[str, Any]:
+    global _pipeline, _processed_files
+
+    def _mask_key(key: str) -> str:
+        if not key or key == "not-needed":
+            return ""
+        if len(key) <= 8:
+            return "*" * len(key)
+        return key[:4] + "****" + key[-4:]
+
+    status = {
+        "embedding": {
+            "model": config.EMBEDDING_MODEL_NAME,
+            "api_base": config.EMBEDDING_API_BASE,
+            "api_key": _mask_key(config.EMBEDDING_API_KEY),
+        },
+        "llm": {
+            "model": config.LLM_MODEL_NAME,
+            "api_base": config.LLM_API_BASE,
+            "api_key": _mask_key(config.LLM_API_KEY),
+        },
+        "ocr": {
+            "engine": config.OCR_ENGINE,
+            "model": config.OCR_API_MODEL,
+            "api_base": config.OCR_API_BASE,
+            "api_key": _mask_key(config.OCR_API_KEY),
+        },
+        "vector_store": config.VECTOR_STORE_TYPE,
+        "params": {
+            "chunk_size": config.CHUNK_SIZE,
+            "chunk_overlap": config.CHUNK_OVERLAP,
+            "retrieval_top_k": config.RETRIEVAL_TOP_K,
+        },
+        "document_count": 0,
+        "files": _processed_files,
+    }
+
+    if _pipeline is not None:
+        try:
+            stats = _pipeline.stats
+            status["document_count"] = stats.get("document_count", 0)
+        except Exception:
+            pass
+
+    return status
+
+
+def preload_ocr_engine():
+    """启动时预热 OCR 引擎, 避免首次上传等待模型加载"""
+    if config.OCR_ENGINE == "paddle":
+        try:
+            logger.info("预热 PaddleOCR-VL 引擎...")
+            from ocr_loader import _get_ocr_vl_pipeline
+            _get_ocr_vl_pipeline()
+            logger.info("OCR 引擎预热完成 ✓")
+        except Exception as e:
+            logger.warning(f"OCR 引擎预热跳过: {e}")
+    elif config.OCR_ENGINE == "api":
+        logger.info(f"OCR API 模式, 跳过预热 (endpoint: {config.OCR_API_BASE})")
+
+
+# ============================================================
+# FastAPI App
+# ============================================================
+
+app = FastAPI(title="PDF OCR 智能问答系统", version="2.0")
+
+# Static files
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+STATIC_DIR.mkdir(exist_ok=True)
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+
+class ChatRequest(BaseModel):
+    question: str
+
+
+class ChatResponse(BaseModel):
+    answer: str
+    sources: List[Dict[str, Any]]
+
+
+# ── Routes ──
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    """Serve the main frontend"""
+    index_path = STATIC_DIR / "index.html"
+    if index_path.exists():
+        return FileResponse(index_path)
+    return HTMLResponse("<h1>Frontend not found</h1>", status_code=404)
+
+
+@app.post("/api/upload")
+async def upload_files(
+    files: List[UploadFile] = File(...),
+    chunk_size: int = Form(800),
+    chunk_overlap: int = Form(150),
+):
+    """Upload and process multiple documents"""
+    if not files or all(not f.filename for f in files):
+        raise HTTPException(400, "No files provided")
+
+    upload_dir = config.UPLOAD_DIR
+    upload_dir.mkdir(parents=True, exist_ok=True)
+
+    results = []
+    all_errors = []
+
+    for file in files:
+        if not file.filename:
+            continue
+
+        tmp_path = upload_dir / file.filename
+        try:
+            with open(tmp_path, "wb") as f:
+                shutil.copyfileobj(file.file, f)
+
+            file_info, preview = process_file_impl(tmp_path, chunk_size, chunk_overlap)
+
+            results.append({
+                "success": True,
+                "name": file_info["name"],
+                "format": file_info["format"],
+                "pages": file_info["pages"],
+                "chunks": file_info["chunks"],
+                "size_mb": file_info["size_mb"],
+                "time": file_info["time"],
+                "preview": preview,
+                "message": "处理完成",
+            })
+        except ValueError as e:
+            all_errors.append(f"{file.filename}: {e}")
+        except Exception as e:
+            logger.error(f"处理失败 {file.filename}: {e}")
+            import traceback
+            traceback.print_exc()
+            all_errors.append(f"{file.filename}: {e}")
+
+    if not results and all_errors:
+        raise HTTPException(500, "; ".join(all_errors))
+
+    _save_files_to_disk()
+
+    return {
+        "success": True,
+        "results": results,
+        "errors": all_errors,
+        "total": len(results),
+    }
+
+
+@app.delete("/api/files/{index}")
+async def delete_file(index: int):
+    """Remove a processed file from the list by index"""
+    global _processed_files
+    if 0 <= index < len(_processed_files):
+        removed = _processed_files.pop(index)
+        _delete_ocr_text(removed["name"])
+        _save_files_to_disk()
+        logger.info(f"已移除文件: {removed['name']}")
+        return {"success": True, "removed": removed["name"]}
+    raise HTTPException(404, "File index not found")
+
+
+@app.get("/api/preview/{index}")
+async def get_preview(index: int):
+    """Get full OCR text for a processed file (reads from disk)"""
+    if 0 <= index < len(_processed_files):
+        filename = _processed_files[index]["name"]
+        text = _load_ocr_text(filename)
+        if text:
+            return {"success": True, "text": text, "index": index, "filename": filename}
+        return {"success": False, "text": "", "message": "OCR text file not found on disk"}
+    raise HTTPException(404, "File index out of range")
+
+
+@app.get("/api/file/{index}")
+async def get_original_file(index: int):
+    """Serve the original uploaded file for preview"""
+    if 0 <= index < len(_processed_files):
+        filename = _processed_files[index]["name"]
+        # 1) 尝试存储的路径
+        file_path = _processed_files[index].get("path", "")
+        if file_path and Path(file_path).exists():
+            return FileResponse(file_path)
+        # 2) 回退: 在 upload 目录中按文件名查找
+        fallback = config.UPLOAD_DIR / filename
+        if fallback.exists():
+            return FileResponse(str(fallback))
+        raise HTTPException(404, f"Original file not found: {filename}")
+    raise HTTPException(404, f"File index {index} out of range (total: {len(_processed_files)})")
+
+
+@app.post("/api/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    """Ask a question about the processed document"""
+    try:
+        result = ask_question_impl(req.question)
+        return ChatResponse(**result)
+    except RuntimeError as e:
+        return {"answer": str(e), "sources": []}
+    except Exception as e:
+        logger.error(f"问答失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return {"answer": f"问答失败: {str(e)}", "sources": []}
+
+
+@app.delete("/api/chat")
+async def clear_chat():
+    """Clear chat history"""
+    clear_chat_impl()
+    return {"success": True}
+
+
+@app.get("/api/status")
+async def get_status():
+    """Get system status"""
+    return get_system_status_impl()
+
+
+# ── Config API ──
+
+CONFIG_KEYS = {
+    "EMBEDDING_API_BASE", "EMBEDDING_MODEL_NAME", "EMBEDDING_API_KEY",
+    "LLM_API_BASE", "LLM_MODEL_NAME", "LLM_API_KEY",
+    "OCR_API_BASE", "OCR_API_MODEL", "OCR_API_KEY", "OCR_ENGINE",
+    "CHUNK_SIZE", "CHUNK_OVERLAP", "RETRIEVAL_TOP_K",
+}
+
+
+def _update_env_file(updates: Dict[str, str]):
+    """将配置变更写入 .env 文件"""
+    env_path = config.BASE_DIR / ".env"
+    if env_path.exists():
+        lines = env_path.read_text(encoding="utf-8").splitlines()
+    else:
+        lines = []
+
+    updated_keys = set()
+    new_lines = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#") and "=" in stripped:
+            key = stripped.split("=", 1)[0].strip()
+            if key in updates:
+                new_lines.append(f"{key}={updates[key]}")
+                updated_keys.add(key)
+                continue
+        new_lines.append(line)
+
+    for k, v in updates.items():
+        if k not in updated_keys:
+            new_lines.append(f"{k}={v}")
+
+    env_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+
+
+@app.get("/api/config")
+async def get_config():
+    """获取当前 API 配置"""
+    return {
+        "embedding": {
+            "api_base": config.EMBEDDING_API_BASE,
+            "model_name": config.EMBEDDING_MODEL_NAME,
+            "api_key": config.EMBEDDING_API_KEY,
+        },
+        "llm": {
+            "api_base": config.LLM_API_BASE,
+            "model_name": config.LLM_MODEL_NAME,
+            "api_key": config.LLM_API_KEY,
+        },
+        "ocr": {
+            "engine": config.OCR_ENGINE,
+            "api_base": config.OCR_API_BASE,
+            "model_name": config.OCR_API_MODEL,
+            "api_key": config.OCR_API_KEY,
+        },
+        "retrieval": {
+            "chunk_size": config.CHUNK_SIZE,
+            "chunk_overlap": config.CHUNK_OVERLAP,
+            "top_k": config.RETRIEVAL_TOP_K,
+        },
+    }
+
+
+@app.post("/api/config")
+async def update_config(updates: Dict[str, str]):
+    """更新 API 配置 (写入 .env 并即时生效)"""
+    import os as _os
+
+    applied = {}
+    for key in updates:
+        if key in CONFIG_KEYS:
+            applied[key] = str(updates[key])
+            _os.environ[key] = str(updates[key])
+
+    if applied:
+        _update_env_file(applied)
+
+        # 重新加载 config 模块以生效
+        import importlib
+        importlib.reload(config)
+
+        # 重置全局单例使新配置生效
+        from embeddings import reset_embedding_model
+        reset_embedding_model()
+
+        logger.info(f"配置已更新: {list(applied.keys())}")
+
+    return {"success": True, "updated": list(applied.keys())}
+
+
+# ============================================================
+# Main
+# ============================================================
+
+def main():
+    import uvicorn
+
+    logger.remove()
+    logger.add(
+        config.LOG_DIR / "app_{time:YYYY-MM-DD}.log",
+        level=config.LOG_LEVEL,
+        format=config.LOG_FORMAT,
+        rotation="100 MB",
+        retention="30 days",
+        encoding="utf-8",
+    )
+    logger.add(
+        lambda msg: print(msg, end=""),
+        level="INFO",
+        format="<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | <level>{message}</level>",
+        colorize=True,
+    )
+
+    logger.info("=" * 50)
+    logger.info("  PDF OCR 智能问答系统 启动中...")
+    logger.info("=" * 50)
+    logger.info(f"  OCR: PaddleOCR-VL-1.5 ({config.OCR_VL_BACKEND})")
+    logger.info(f"  嵌入: {config.EMBEDDING_MODEL_NAME} (API: {config.EMBEDDING_API_BASE})")
+    logger.info(f"  LLM: {config.LLM_MODEL_NAME} (API: {config.LLM_API_BASE})")
+    logger.info(f"  OCR: {config.OCR_ENGINE} ({config.OCR_API_BASE if config.OCR_ENGINE == 'api' else 'local'})")
+    logger.info(f"  向量数据库: {config.VECTOR_STORE_TYPE}")
+    logger.info(f"  支持格式: {sorted(config.SUPPORTED_FORMATS)}")
+
+    # 从磁盘恢复已处理文件列表
+    _load_files_from_disk()
+
+    # 预热 OCR 引擎
+    preload_ocr_engine()
+
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=7860,
+        reload=False,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

assets/OCR_RAG.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8c39f595d1822c620fde84ef317c2ea95b24edb8568214e06aec97e3f5251bed
+size 2590191

config.py

@@ -0,0 +1,124 @@
+"""
+============================================================
+OCR RAG 智能问答系统 - 全局配置
+============================================================
+
+"""
+
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# ---- 项目路径 ----
+BASE_DIR = Path(__file__).resolve().parent
+DATA_DIR = BASE_DIR / "data"
+UPLOAD_DIR = DATA_DIR / "uploads"
+OCR_OUTPUT_DIR = DATA_DIR / "ocr_output"
+VECTOR_DB_DIR = DATA_DIR / "vector_db"
+LOG_DIR = DATA_DIR / "logs"
+
+for d in [DATA_DIR, UPLOAD_DIR, OCR_OUTPUT_DIR, VECTOR_DB_DIR, LOG_DIR]:
+    d.mkdir(parents=True, exist_ok=True)
+
+# ============================================================
+# PaddleOCR-VL-1.5 配置 
+# ============================================================
+# PaddleOCR-VL-1.5: 0.9B 视觉语言模型, OmniDocBench v1.5 94.5% 精度
+# 支持: PDF / PNG / JPG / BMP / TIF
+# OCR 引擎:
+#   paddle       - PaddleOCR pipeline (默认, 版面分析 + 页面级解析, 推荐)
+#   transformers - transformers v5 原生推理 (元素级识别, 轻量)
+# PaddleOCR 后端 (仅 engine=paddle 时生效):
+#   native          - 本地 PaddlePaddle 推理
+#   vllm-server     - vLLM 服务端 (高吞吐)
+#   llama-cpp-server - llama.cpp GGUF (边缘设备)
+
+OCR_ENGINE = os.getenv("OCR_ENGINE", "paddle")  # paddle / api
+
+# OCR API 配置 (OCR_ENGINE=api, 通过 OpenAI 兼容 API 调用)
+# vLLM 部署:
+#   python -m vllm.entrypoints.openai.api_server \
+#     --model PaddlePaddle/PaddleOCR-VL-1.5 --trust-remote-code --port 8002
+OCR_API_BASE = os.getenv("OCR_API_BASE", "http://127.0.0.1:8002/v1")
+OCR_API_KEY = os.getenv("OCR_API_KEY", "not-needed")
+OCR_API_MODEL = os.getenv("OCR_API_MODEL", "PaddleOCR-VL-1.5")
+OCR_TASK = os.getenv("OCR_TASK", "ocr")  # ocr / table / chart / formula / spotting / seal
+
+OCR_VL_BACKEND = os.getenv("OCR_VL_BACKEND", "native")
+OCR_VL_SERVER_URL = os.getenv("OCR_VL_SERVER_URL", "http://127.0.0.1:8080/v1")
+
+OCR_USE_LAYOUT = os.getenv("OCR_USE_LAYOUT", "true").lower() == "true"
+OCR_LAYOUT_THRESHOLD = float(os.getenv("OCR_LAYOUT_THRESHOLD", "0.5"))
+OCR_USE_CHART = os.getenv("OCR_USE_CHART", "false").lower() == "true"
+
+OCR_MAX_NEW_TOKENS = int(os.getenv("OCR_MAX_NEW_TOKENS", "4096"))
+OCR_TEMPERATURE = float(os.getenv("OCR_TEMPERATURE", "0.0"))
+
+PDF_RENDER_DPI = int(os.getenv("PDF_RENDER_DPI", "300"))
+
+SUPPORTED_IMAGE_FORMATS = {".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff"}
+SUPPORTED_FORMATS = {".pdf"} | SUPPORTED_IMAGE_FORMATS
+
+MAX_FILE_SIZE_MB = int(os.getenv("MAX_FILE_SIZE_MB", "50"))
+
+# ============================================================
+# 文本分割
+# ============================================================
+CHUNK_SIZE = int(os.getenv("CHUNK_SIZE", "800"))
+CHUNK_OVERLAP = int(os.getenv("CHUNK_OVERLAP", "150"))
+SEPARATORS = ["\n\n", "\n", "。", "！", "？", "；", ".", "!", "?", ";", " ", ""]
+
+# ============================================================
+# Embedding API 配置 (OpenAI 兼容格式)
+# ============================================================
+
+
+EMBEDDING_MODEL_NAME = os.getenv(
+    "EMBEDDING_MODEL_NAME", "Qwen/Qwen3-Embedding-0.6B"
+)
+EMBEDDING_API_BASE = os.getenv(
+    "EMBEDDING_API_BASE", "http://127.0.0.1:8001/v1"
+)
+EMBEDDING_API_KEY = os.getenv("EMBEDDING_API_KEY", "not-needed")
+EMBEDDING_BATCH_SIZE = int(os.getenv("EMBEDDING_BATCH_SIZE", "10"))
+
+# ============================================================
+# 向量数据库
+# ============================================================
+VECTOR_STORE_TYPE = os.getenv("VECTOR_STORE_TYPE", "chroma")
+CHROMA_COLLECTION_NAME = os.getenv("CHROMA_COLLECTION_NAME", "pdf_ocr_knowledge")
+RETRIEVAL_TOP_K = int(os.getenv("RETRIEVAL_TOP_K", "3"))
+
+# ============================================================
+# LLM API 配置 (OpenAI 兼容格式)
+# ============================================================
+
+
+LLM_API_KEY = os.getenv("LLM_API_KEY", "not-needed")
+LLM_API_BASE = os.getenv("LLM_API_BASE", "http://127.0.0.1:8000/v1")
+LLM_MODEL_NAME = os.getenv("LLM_MODEL_NAME", "Qwen/Qwen3-8B")
+LLM_TEMPERATURE = float(os.getenv("LLM_TEMPERATURE", "0.1"))
+LLM_MAX_TOKENS = int(os.getenv("LLM_MAX_TOKENS", "512"))
+
+# ============================================================
+# 系统 Prompt
+# ============================================================
+SYSTEM_PROMPT = """根据以下文档内容，简洁回答用户问题。只依据文档内容回答，不要编造。使用中文。"""
+
+RAG_PROMPT_TEMPLATE = """{system_prompt}
+
+## 参考文档内容:
+{context}
+
+## 用户问题:
+{question}
+
+## 回答:"""
+
+# ============================================================
+# 日志
+# ============================================================
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
+LOG_FORMAT = "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}"

embeddings.py

@@ -0,0 +1,198 @@
+"""
+============================================================
+向量嵌入模块 (OpenAI 兼容 API)
+============================================================
+直接使用 openai 客户端, 兼容:
+  - 阿里云 DashScope (text-embedding-v4 等)
+  - vLLM 部署的 Qwen3-Embedding
+  - 任意 OpenAI 兼容嵌入服务
+
+用法:
+    model = get_embedding_model()
+    vec = model.embed_query("查询文本")
+    vecs = model.embed_documents(["文本1", "文本2"])
+"""
+
+from typing import List, Optional
+import numpy as np
+
+from langchain_core.embeddings import Embeddings
+from openai import OpenAI
+
+from loguru import logger
+
+import config
+
+
+# ============================================================
+# 通用 OpenAI 兼容嵌入类
+# ============================================================
+
+class OpenAICompatEmbeddings(Embeddings):
+    """
+    轻量级 OpenAI 兼容嵌入类
+
+    直接使用 openai 客户端发送请求, 避免 langchain_openai 的额外封装
+    导致的 API 兼容性问题 (如 DashScope 的参数校验差异)。
+    """
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        batch_size: Optional[int] = None,
+        dimensions: Optional[int] = None,
+    ):
+        self.model = model or config.EMBEDDING_MODEL_NAME
+        self.batch_size = batch_size if batch_size is not None else config.EMBEDDING_BATCH_SIZE
+        self.dimensions = dimensions
+
+        self._client = OpenAI(
+            api_key=api_key or config.EMBEDDING_API_KEY,
+            base_url=base_url or config.EMBEDDING_API_BASE,
+        )
+
+        logger.info(
+            f"Embedding API 连接: model={self.model}, "
+            f"base_url={base_url or config.EMBEDDING_API_BASE}"
+        )
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """批量嵌入文档"""
+        if not texts:
+            return []
+
+        all_embeddings = []
+
+        for i in range(0, len(texts), self.batch_size):
+            batch = texts[i : i + self.batch_size]
+            kwargs = dict(model=self.model, input=batch)
+            if self.dimensions:
+                kwargs["dimensions"] = self.dimensions
+
+            response = self._client.embeddings.create(**kwargs)
+            # response.data 按输入顺序返回
+            batch_embeddings = [item.embedding for item in response.data]
+            all_embeddings.extend(batch_embeddings)
+
+            if len(texts) > self.batch_size:
+                logger.debug(
+                    f"嵌入进度: {min(i + self.batch_size, len(texts))}/{len(texts)}"
+                )
+
+        return all_embeddings
+
+    def embed_query(self, text: str) -> List[float]:
+        """嵌入查询文本"""
+        kwargs = dict(model=self.model, input=text)
+        if self.dimensions:
+            kwargs["dimensions"] = self.dimensions
+
+        response = self._client.embeddings.create(**kwargs)
+        return response.data[0].embedding
+
+
+# ============================================================
+# 全局单例
+# ============================================================
+
+_embedding_model: Optional[Embeddings] = None
+
+
+def get_embedding_model(
+    model_name: Optional[str] = None,
+    api_base: Optional[str] = None,
+) -> Embeddings:
+    """获取全局嵌入模型单例"""
+    global _embedding_model
+    if _embedding_model is None:
+        _embedding_model = OpenAICompatEmbeddings(
+            model=model_name,
+            base_url=api_base,
+        )
+    return _embedding_model
+
+
+def reset_embedding_model():
+    """重置嵌入模型单例"""
+    global _embedding_model
+    _embedding_model = None
+    logger.info("嵌入模型已重置")
+
+
+# ============================================================
+# 工具函数
+# ============================================================
+
+def compute_similarity(vec1: List[float], vec2: List[float]) -> float:
+    """计算余弦相似度"""
+    v1, v2 = np.array(vec1), np.array(vec2)
+    denom = np.linalg.norm(v1) * np.linalg.norm(v2)
+    if denom == 0:
+        return 0.0
+    return float(np.dot(v1, v2) / denom)
+
+
+def batch_embed(
+    texts: List[str],
+    model: Optional[Embeddings] = None,
+    batch_size: Optional[int] = None,
+    show_progress: bool = False,
+) -> List[List[float]]:
+    """批量嵌入文本 (支持自定义 batch_size)"""
+    if model is None:
+        model = get_embedding_model()
+
+    all_embeddings = []
+    total = len(texts)
+    bs = batch_size or config.EMBEDDING_BATCH_SIZE
+
+    for i in range(0, total, bs):
+        batch = texts[i : i + bs]
+        embeddings = model.embed_documents(batch)
+        all_embeddings.extend(embeddings)
+
+        if show_progress and i + bs < total:
+            logger.debug(f"嵌入进度: {min(i + bs, total)}/{total}")
+
+    return all_embeddings
+
+
+# ============================================================
+# 测试入口
+# ============================================================
+
+if __name__ == "__main__":
+    print("测试 Embedding API 连接...\n")
+    print(f"API: {config.EMBEDDING_API_BASE}")
+    print(f"模型: {config.EMBEDDING_MODEL_NAME}")
+
+    try:
+        model = get_embedding_model()
+
+        test_texts = [
+            "这是第一段测试文本，用于验证嵌入API是否正常工作。",
+            "这是第二段完全不同的文本内容，涉及人工智能话题。",
+            "向量嵌入是自然语言处理中的基础技术。",
+        ]
+
+        print("\n测试单文本嵌入 (embed_query)...")
+        query_vec = model.embed_query("嵌入模型测试")
+        print(f"  维度: {len(query_vec)}")
+
+        print("\n测试批量嵌入 (embed_documents)...")
+        doc_vecs = model.embed_documents(test_texts)
+        print(f"  数量: {len(doc_vecs)}, 维度: {len(doc_vecs[0])}")
+
+        print("\n测试相似度计算...")
+        sim1 = compute_similarity(doc_vecs[2], query_vec)
+        sim2 = compute_similarity(doc_vecs[0], query_vec)
+        print(f"  查询 vs 向量嵌入文本: {sim1:.4f}")
+        print(f"  查询 vs 无关文本:      {sim2:.4f}")
+
+        print(f"\n✓ Embedding API 测试通过")
+
+    except Exception as e:
+        print(f"\n✗ API 连接失败: {e}")
+        print(f"  请确保 Embedding API 服务已启动: {config.EMBEDDING_API_BASE}")

ocr_loader.py

@@ -0,0 +1,829 @@
+"""
+============================================================
+PaddleOCR-VL-1.5 文档加载器
+============================================================
+模型: PaddleOCR-VL-1.5 (0.9B 视觉语言模型, OmniDocBench v1.5 94.5% 精度)
+支持格式: PDF / PNG / JPG / JPEG / BMP / TIF / TIFF
+
+功能:
+  1. 文档 (PDF/图片) → PaddleOCR-VL-1.5 端到端识别
+  2. 输出 Markdown/JSON 结构化结果 (含版面/表格/公式/印章)
+  3. 转换为 LangChain Document 对象
+"""
+
+import gc
+import time
+import warnings
+from pathlib import Path
+from typing import List, Optional, Iterator, Dict, Any, Union
+from dataclasses import dataclass, field
+
+import fitz  # PyMuPDF: PDF 页面渲染和元数据提取
+import numpy as np
+from PIL import Image
+
+from langchain_core.documents import Document
+
+from loguru import logger
+
+import config
+
+warnings.filterwarnings("ignore")
+
+
+# ============================================================
+# PaddleOCR-VL-1.5 全局单例
+# ============================================================
+
+_ocr_vl_pipeline = None
+
+
+def _get_ocr_vl_pipeline():
+    """懒加载 PaddleOCR-VL-1.5 模型 (单例)"""
+    global _ocr_vl_pipeline
+    if _ocr_vl_pipeline is None:
+        from paddleocr import PaddleOCRVL
+        logger.info(
+            f"正在初始化 PaddleOCR-VL-1.5 模型 "
+            f"(backend={config.OCR_VL_BACKEND})..."
+        )
+
+        kwargs = dict(
+            use_layout_detection=config.OCR_USE_LAYOUT,
+            use_chart_recognition=config.OCR_USE_CHART,
+            merge_layout_blocks=True,
+            layout_threshold=config.OCR_LAYOUT_THRESHOLD,
+        )
+
+        if config.OCR_VL_BACKEND == "vllm-server":
+            kwargs["vl_rec_backend"] = "vllm-server"
+            kwargs["vl_rec_server_url"] = config.OCR_VL_SERVER_URL
+        elif config.OCR_VL_BACKEND == "llama-cpp-server":
+            kwargs["vl_rec_backend"] = "llama-cpp-server"
+            kwargs["vl_rec_server_url"] = config.OCR_VL_SERVER_URL
+
+        _ocr_vl_pipeline = PaddleOCRVL(**kwargs)
+        logger.info("PaddleOCR-VL-1.5 模型初始化完成 ✓")
+    return _ocr_vl_pipeline
+
+
+# ============================================================
+# 数据结构
+# ============================================================
+
+@dataclass
+class OCRResult:
+    """单页/单图 OCR 结果"""
+    page_num: int = 0
+    markdown_text: str = ""
+    json_data: Optional[Dict[str, Any]] = None
+    text_blocks: List[Dict[str, Any]] = field(default_factory=list)
+    tables: List[Dict[str, Any]] = field(default_factory=list)
+    formulas: List[Dict[str, Any]] = field(default_factory=list)
+    images_in_page: List[Dict[str, Any]] = field(default_factory=list)
+    layout_regions: List[Dict[str, Any]] = field(default_factory=list)
+    ocr_time_ms: float = 0.0
+    source_format: str = ""  # pdf / png / jpg / ...
+
+
+# ============================================================
+# PaddleOCR-VL-1.5 文本提取器
+# ============================================================
+
+class VLOCRExtractor:
+    """使用 PaddleOCR-VL-1.5 从文档中提取结构化内容"""
+
+    @staticmethod
+    def extract(image_or_path: Union[str, Path, np.ndarray]) -> List[OCRResult]:
+        """
+        对单张图片或 PDF 执行 OCR 识别
+
+        Args:
+            image_or_path: 图片路径 / PDF路径 / numpy 数组
+
+        Returns:
+            OCRResult 列表 (PDF 为多页, 图片为单页)
+        """
+        pipeline = _get_ocr_vl_pipeline()
+        start_time = time.time()
+
+        logger.info("PaddleOCR-VL 正在推理中 (首次调用较慢, CPU 约 30-60s/页) ...")
+        raw_output = pipeline.predict(image_or_path)
+        logger.info(f"推理完成, 耗时 {time.time() - start_time:.1f}s")
+        results = []
+        for i, res in enumerate(raw_output):
+            page_result = OCRResult(
+                page_num=i + 1,
+                ocr_time_ms=(time.time() - start_time) * 1000 / len(raw_output),
+            )
+
+            # 尝试获取 structured JSON
+            try:
+                json_data = res.json
+                if json_data:
+                    page_result.json_data = json_data
+                    # 解析结构化内容
+                    page_result.text_blocks = VLOCRExtractor._parse_text_blocks(json_data)
+                    page_result.tables = VLOCRExtractor._parse_tables(json_data)
+                    page_result.formulas = VLOCRExtractor._parse_formulas(json_data)
+            except Exception as e:
+                logger.debug(f"JSON 解析跳过: {e}")
+
+            # 获取 Markdown 文本
+            try:
+                md = res.markdown
+                if isinstance(md, dict):
+                    page_result.markdown_text = md.get("text", "") or ""
+                elif isinstance(md, str):
+                    page_result.markdown_text = md
+                else:
+                    page_result.markdown_text = str(md) if md else ""
+            except Exception:
+                page_result.markdown_text = ""
+
+            # 回退: markdown 为空时从 JSON blocks 构建文本
+            if not page_result.markdown_text and page_result.json_data:
+                page_result.markdown_text = VLOCRExtractor._build_text_from_blocks(
+                    page_result.json_data
+                )
+
+            results.append(page_result)
+
+        return results
+
+    @staticmethod
+    def extract_text(image_or_path: Union[str, Path, np.ndarray]) -> str:
+        """便捷方法: 只返回纯文本 (合并所有页)"""
+        results = VLOCRExtractor.extract(image_or_path)
+        return "\n\n".join(r.markdown_text for r in results if r.markdown_text)
+
+    @staticmethod
+    def extract_to_markdown(image_or_path: Union[str, Path, np.ndarray]) -> str:
+        """返回完整的 Markdown 格式文本"""
+        return VLOCRExtractor.extract_text(image_or_path)
+
+    @staticmethod
+    def extract_to_json(
+        image_or_path: Union[str, Path, np.ndarray],
+        save_path: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """返回结构化 JSON 或保存到文件"""
+        results = VLOCRExtractor.extract(image_or_path)
+        output = {
+            "pages": [],
+            "total_pages": len(results),
+        }
+        for r in results:
+            page_data = {
+                "page_num": r.page_num,
+                "markdown": r.markdown_text,
+                "json": r.json_data,
+                "tables": r.tables,
+                "formulas": r.formulas,
+            }
+            output["pages"].append(page_data)
+
+        if save_path:
+            import json
+            save_path = Path(save_path)
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(save_path, "w", encoding="utf-8") as f:
+                json.dump(output, f, ensure_ascii=False, indent=2)
+            logger.info(f"OCR 结果已保存: {save_path}")
+
+        return output
+
+    # ---- 结构化解析辅助 ----
+
+    @staticmethod
+    def _get_parsing_list(json_data: Dict) -> List[Dict]:
+        """从 PaddleOCR-VL JSON 中提取 parsing_res_list"""
+        res = json_data.get("res", json_data)
+        return res.get("parsing_res_list", [])
+
+    @staticmethod
+    def _parse_text_blocks(json_data: Dict) -> List[Dict[str, Any]]:
+        """从 parsing_res_list 中提取文本块"""
+        blocks = []
+        for item in VLOCRExtractor._get_parsing_list(json_data):
+            label = item.get("block_label", "")
+            content = item.get("block_content", "")
+            bbox = item.get("block_bbox", [])
+            if content and label not in ("image",):
+                blocks.append({
+                    "type": label,
+                    "text": content,
+                    "bbox": bbox,
+                })
+        return blocks
+
+    @staticmethod
+    def _parse_tables(json_data: Dict) -> List[Dict[str, Any]]:
+        """从 parsing_res_list 中提取表格"""
+        tables = []
+        for item in VLOCRExtractor._get_parsing_list(json_data):
+            if item.get("block_label") == "table":
+                tables.append({
+                    "text": item.get("block_content", ""),
+                    "html": item.get("block_html", ""),
+                    "markdown": item.get("block_markdown", ""),
+                    "bbox": item.get("block_bbox", []),
+                })
+        return tables
+
+    @staticmethod
+    def _parse_formulas(json_data: Dict) -> List[Dict[str, Any]]:
+        """从 parsing_res_list 中提取公式"""
+        formulas = []
+        for item in VLOCRExtractor._get_parsing_list(json_data):
+            if item.get("block_label") == "formula":
+                formulas.append({
+                    "latex": item.get("block_latex", ""),
+                    "text": item.get("block_content", ""),
+                    "bbox": item.get("block_bbox", []),
+                })
+        return formulas
+
+    @staticmethod
+    def _build_text_from_blocks(json_data: Dict) -> str:
+        """从 parsing_res_list 构建纯文本"""
+        lines = []
+        for item in VLOCRExtractor._get_parsing_list(json_data):
+            label = item.get("block_label", "")
+            content = item.get("block_content", "")
+            if not content:
+                continue
+            if label == "table":
+                lines.append(f"[表格] {content}")
+            elif label == "formula":
+                lines.append(f"[公式] {content}")
+            elif label in ("paragraph_title", "header"):
+                lines.append(f"## {content}")
+            elif label == "image":
+                continue  # 跳过纯图片块
+            else:
+                lines.append(content)
+        return "\n\n".join(lines)
+
+
+# ============================================================
+# OCR API 提取器 (OpenAI 兼容格式, 无需本地推理)
+# ============================================================
+
+_ocr_api_client = None
+
+
+def _get_ocr_api_client():
+    """懒加载 OCR API 客户端"""
+    global _ocr_api_client
+    if _ocr_api_client is None:
+        from openai import OpenAI
+        _ocr_api_client = OpenAI(
+            api_key=config.OCR_API_KEY,
+            base_url=config.OCR_API_BASE,
+        )
+        logger.info(
+            f"OCR API 连接: model={config.OCR_API_MODEL}, "
+            f"base_url={config.OCR_API_BASE}"
+        )
+    return _ocr_api_client
+
+
+class OCRApiExtractor:
+    """
+    基于 OpenAI 兼容 API 的 PaddleOCR-VL-1.5 提取器
+
+    通过 vLLM 或其他 OpenAI 兼容服务调用, 无需本地 GPU 推理。
+
+    支持任务: ocr / table / formula / chart / spotting / seal
+    """
+
+    PROMPTS = {
+        "ocr": "OCR:",
+        "table": "Table Recognition:",
+        "formula": "Formula Recognition:",
+        "chart": "Chart Recognition:",
+        "spotting": "Spotting:",
+        "seal": "Seal Recognition:",
+    }
+
+    @staticmethod
+    def extract(
+        image_or_path: Union[str, Path, np.ndarray],
+        task: Optional[str] = None,
+        max_new_tokens: int = 2048,
+    ) -> List[OCRResult]:
+        """
+        通过 API 执行 OCR 识别
+
+        Args:
+            image_or_path: 图片路径 / numpy 数组
+            task: 任务类型
+            max_new_tokens: 最大生成 token 数
+
+        Returns:
+            OCRResult 列表
+        """
+        import base64
+        import io
+
+        task = task or config.OCR_TASK
+        client = _get_ocr_api_client()
+
+        start_time = time.time()
+        logger.info(f"OCR API 推理中 (task={task}) ...")
+
+        # 图片 → base64 data URL
+        if isinstance(image_or_path, (str, Path)):
+            with open(image_or_path, "rb") as f:
+                img_bytes = f.read()
+        elif isinstance(image_or_path, np.ndarray):
+            img = Image.fromarray(image_or_path).convert("RGB")
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            img_bytes = buf.getvalue()
+        else:
+            img_bytes = image_or_path
+
+        b64 = base64.b64encode(img_bytes).decode("utf-8")
+        image_url = f"data:image/png;base64,{b64}"
+
+        messages = [{
+            "role": "user",
+            "content": [
+                {"type": "image_url", "image_url": {"url": image_url}},
+                {"type": "text", "text": OCRApiExtractor.PROMPTS[task]},
+            ],
+        }]
+
+        response = client.chat.completions.create(
+            model=config.OCR_API_MODEL,
+            messages=messages,
+            max_tokens=max_new_tokens,
+        )
+
+        result_text = response.choices[0].message.content.strip()
+        elapsed = (time.time() - start_time) * 1000
+
+        result = OCRResult(
+            page_num=1,
+            markdown_text=result_text,
+            ocr_time_ms=elapsed,
+            source_format="image",
+            text_blocks=[{"type": task, "text": result_text, "bbox": []}],
+        )
+
+        logger.info(f"OCR API 完成, 耗时 {elapsed:.0f}ms, {len(result_text)} 字符")
+        return [result]
+
+    @staticmethod
+    def extract_text(
+        image_or_path: Union[str, Path, np.ndarray],
+        task: Optional[str] = None,
+    ) -> str:
+        """便捷方法: 只返回识别文本"""
+        results = OCRApiExtractor.extract(image_or_path, task=task)
+        return "\n".join(r.markdown_text for r in results)
+
+
+# ============================================================
+# 统一提取器入口
+# ============================================================
+
+def _extract_ocr(image_or_path: Union[str, Path, np.ndarray]) -> List[OCRResult]:
+    """根据配置选择 OCR 引擎并执行识别"""
+    if config.OCR_ENGINE == "api":
+        return OCRApiExtractor.extract(image_or_path)
+    else:
+        return VLOCRExtractor.extract(image_or_path)
+
+
+# ============================================================
+# PDF 工具
+# ============================================================
+
+class PDFUtils:
+    """PDF 处理工具: 渲染和元数据提取"""
+
+    @staticmethod
+    def render_page_to_image(page: fitz.Page, dpi: int = 300) -> np.ndarray:
+        """将 PyMuPDF 页面渲染为 numpy 图片数组 (RGB)"""
+        zoom = dpi / 72.0
+        matrix = fitz.Matrix(zoom, zoom)
+        pix = page.get_pixmap(matrix=matrix)
+        img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
+        return np.array(img)
+
+    @staticmethod
+    def get_page_count(pdf_path: Path) -> int:
+        """获取 PDF 页数"""
+        doc = fitz.open(str(pdf_path))
+        count = len(doc)
+        doc.close()
+        return count
+
+    @staticmethod
+    def is_scanned_pdf(pdf_path: Path, sample_pages: int = 3) -> bool:
+        """
+        检测 PDF 是否为扫描版 (图片型 PDF)
+
+        通过检查前几页是否包含可提取的文本层来判断
+        """
+        doc = fitz.open(str(pdf_path))
+        text_chars = 0
+        pages_to_check = min(sample_pages, len(doc))
+
+        for i in range(pages_to_check):
+            text_chars += len(doc[i].get_text().strip())
+
+        doc.close()
+        # 如果前几页几乎没有文本, 认为是扫描版
+        return text_chars < 100 * pages_to_check
+
+    @staticmethod
+    def extract_text_layer(pdf_path: Path) -> List[Dict[str, Any]]:
+        """
+        提取 PDF 内嵌文本层 (非 OCR, 用于数字原生 PDF)
+        返回每页的文本和元数据
+        """
+        doc = fitz.open(str(pdf_path))
+        pages = []
+
+        for i in range(len(doc)):
+            page = doc[i]
+            text = page.get_text("text")
+            if text.strip():
+                pages.append({
+                    "page_num": i + 1,
+                    "text": text,
+                    "char_count": len(text),
+                    "has_text_layer": True,
+                })
+
+        doc.close()
+        return pages
+
+
+# ============================================================
+# LangChain PaddleOCR-VL-1.5 文档加载器
+# ============================================================
+
+class PaddleOCRLoader:
+    """
+    LangChain 兼容的 PaddleOCR-VL-1.5 文档加载器
+
+    支持格式: PDF / PNG / JPG / JPEG / BMP / TIF / TIFF
+
+    用法:
+        # 加载 PDF
+        loader = PaddleOCRLoader("document.pdf")
+        documents = loader.load()
+
+        # 加载图片
+        loader = PaddleOCRLoader("scan.png")
+        documents = loader.load()
+
+        # 延迟加载 (大文件推荐)
+        for doc in loader.lazy_load():
+            process(doc)
+    """
+
+    def __init__(
+        self,
+        file_path: Union[str, Path],
+        dpi: int = config.PDF_RENDER_DPI,
+        verbose: bool = True,
+    ):
+        self.file_path = Path(file_path)
+        if not self.file_path.exists():
+            raise FileNotFoundError(f"文件不存在: {self.file_path}")
+
+        self.suffix = self.file_path.suffix.lower()
+        if self.suffix not in config.SUPPORTED_FORMATS:
+            raise ValueError(
+                f"不支持的文件格式: {self.suffix}. "
+                f"支持: {config.SUPPORTED_FORMATS}"
+            )
+
+        self.dpi = dpi
+        self.verbose = verbose
+        self._doc_name = self.file_path.stem
+        self._is_pdf = (self.suffix == ".pdf")
+
+    def load(self) -> List[Document]:
+        """完整加载文档, 返回 LangChain Document 列表"""
+        return list(self.lazy_load())
+
+    def lazy_load(self) -> Iterator[Document]:
+        """逐页延迟加载"""
+
+        if self._is_pdf:
+            yield from self._load_pdf()
+        else:
+            yield from self._load_image()
+
+    def _load_pdf(self) -> Iterator[Document]:
+        """加载 PDF 文件"""
+        total_start = time.time()
+        page_count = PDFUtils.get_page_count(self.file_path)
+        self._log(f"开始处理 PDF: {self.file_path.name} ({page_count} 页, DPI={self.dpi})")
+
+        pdf_doc = fitz.open(str(self.file_path))
+
+        for page_idx in range(page_count):
+            page_start = time.time()
+
+            # 渲染页面为高清图片
+            page = pdf_doc[page_idx]
+            image = PDFUtils.render_page_to_image(page, dpi=self.dpi)
+
+            # PaddleOCR-VL-1.5 识别
+            results = _extract_ocr(image)
+
+            # 释放页面图像内存 (高DPI图片可能占用数百MB)
+            del image
+
+            ocr_time = (time.time() - page_start) * 1000
+
+            for ocr_result in results:
+                ocr_result.page_num = page_idx + 1
+                ocr_result.source_format = "pdf"
+
+                text = ocr_result.markdown_text
+                if not text and ocr_result.json_data:
+                    text = self._extract_text_from_json(ocr_result.json_data)
+
+                if isinstance(text, dict):
+                    text = text.get("text", "") or ""
+                if not text or not str(text).strip():
+                    self._log(f"  第 {page_idx + 1} 页: 未检测到文本")
+                    continue
+
+                # 构建元数据
+                metadata = {
+                    "source": str(self.file_path),
+                    "document_name": self._doc_name,
+                    "page": page_idx + 1,
+                    "total_pages": page_count,
+                    "ocr_text_length": len(text),
+                    "ocr_time_ms": round(ocr_time, 1),
+                    "dpi": self.dpi,
+                    "source_format": "pdf",
+                    "tables_count": len(ocr_result.tables),
+                    "formulas_count": len(ocr_result.formulas),
+                    "text_blocks_count": len(ocr_result.text_blocks),
+                }
+
+                # 附加表格/公式数据
+                if ocr_result.tables:
+                    metadata["tables_markdown"] = [
+                        t.get("markdown", "") for t in ocr_result.tables
+                    ]
+                    metadata["tables_html"] = [
+                        t.get("html", "") for t in ocr_result.tables
+                    ]
+                if ocr_result.formulas:
+                    metadata["formulas_latex"] = [
+                        f.get("latex", "") for f in ocr_result.formulas
+                    ]
+
+                doc = Document(page_content=text, metadata=metadata)
+
+                self._log(
+                    f"  第 {page_idx + 1}/{page_count} 页: "
+                    f"{len(text)} 字符, "
+                    f"表格={metadata['tables_count']}, "
+                    f"公式={metadata['formulas_count']}, "
+                    f"耗时 {ocr_time:.0f}ms"
+                )
+
+                yield doc
+
+        pdf_doc.close()
+        gc.collect()  # 强制回收页面渲染残留内存
+        self._log(f"PDF 处理完成, 总耗时 {time.time() - total_start:.1f}s")
+
+    def _load_image(self) -> Iterator[Document]:
+        """加载单张图片"""
+        total_start = time.time()
+        self._log(f"开始处理图片: {self.file_path.name}")
+
+        # 验证图片可读
+        try:
+            img = Image.open(self.file_path)
+            img.verify()
+            img = Image.open(self.file_path)  # verify 后需重新打开
+        except Exception as e:
+            raise ValueError(f"无法读取图片文件: {e}")
+
+        # PaddleOCR-VL-1.5 可以直接接受图片路径
+        results = _extract_ocr(str(self.file_path))
+        ocr_time = (time.time() - total_start) * 1000
+
+        for ocr_result in results:
+            ocr_result.source_format = self.suffix.lstrip(".")
+            # print("ocr_result: ",ocr_result)
+            text = ocr_result.markdown_text
+
+            if not text and ocr_result.json_data:
+                text = self._extract_text_from_json(ocr_result.json_data)
+
+            if isinstance(text, dict):
+                text = text.get("text", "") or ""
+            if not text or not str(text).strip():
+                self._log("  未检测到文本")
+                continue
+
+            metadata = {
+                "source": str(self.file_path),
+                "document_name": self._doc_name,
+                "page": 1,
+                "total_pages": 1,
+                "ocr_text_length": len(text),
+                "ocr_time_ms": round(ocr_time, 1),
+                "dpi": self.dpi,
+                "source_format": self.suffix.lstrip("."),
+                "image_width": img.width,
+                "image_height": img.height,
+                "tables_count": len(ocr_result.tables),
+                "formulas_count": len(ocr_result.formulas),
+                "text_blocks_count": len(ocr_result.text_blocks),
+            }
+
+            if ocr_result.tables:
+                metadata["tables_markdown"] = [
+                    t.get("markdown", "") for t in ocr_result.tables
+                ]
+                metadata["tables_html"] = [
+                    t.get("html", "") for t in ocr_result.tables
+                ]
+            if ocr_result.formulas:
+                metadata["formulas_latex"] = [
+                    f.get("latex", "") for f in ocr_result.formulas
+                ]
+
+            doc = Document(page_content=text, metadata=metadata)
+            yield doc
+
+        self._log(f"图片处理完成, 耗时 {time.time() - total_start:.1f}s")
+
+    def load_with_ocr_results(self) -> List[OCRResult]:
+        """返回 OCRResult 对象列表 (包含更丰富的结构化信息)"""
+        if self._is_pdf:
+            pdf_doc = fitz.open(str(self.file_path))
+            all_results = []
+            for page_idx in range(len(pdf_doc)):
+                page = pdf_doc[page_idx]
+                image = PDFUtils.render_page_to_image(page, dpi=self.dpi)
+                results = _extract_ocr(image)
+                for r in results:
+                    r.page_num = page_idx + 1
+                    r.source_format = "pdf"
+                all_results.extend(results)
+            pdf_doc.close()
+            return all_results
+        else:
+            results = _extract_ocr(str(self.file_path))
+            for r in results:
+                r.source_format = self.suffix.lstrip(".")
+            return results
+
+    @staticmethod
+    def _extract_text_from_json(json_data: Dict) -> str:
+        """从 PaddleOCR-VL JSON 结构中提取所有文本"""
+        return VLOCRExtractor._build_text_from_blocks(json_data)
+
+    def _log(self, msg: str):
+        if self.verbose:
+            logger.info(msg)
+
+
+# ============================================================
+# 批量加载器
+# ============================================================
+
+class PaddleOCRDirectoryLoader:
+    """批量加载目录下的所有支持的文档文件"""
+
+    def __init__(
+        self,
+        directory: Union[str, Path],
+        glob_patterns: Optional[List[str]] = None,
+        **loader_kwargs,
+    ):
+        self.directory = Path(directory)
+        self.glob_patterns = glob_patterns or [
+            "**/*.pdf", "**/*.png", "**/*.jpg", "**/*.jpeg",
+            "**/*.bmp", "**/*.tif", "**/*.tiff",
+        ]
+        self.loader_kwargs = loader_kwargs
+
+    def load(self) -> List[Document]:
+        """加载目录下所有支持的文档"""
+        all_docs = []
+        files = []
+        for pattern in self.glob_patterns:
+            files.extend(self.directory.glob(pattern))
+        files = sorted(set(files))
+
+        if not files:
+            logger.warning(f"目录 {self.directory} 中未找到支持的文档文件")
+            return all_docs
+
+        logger.info(f"在 {self.directory} 中找到 {len(files)} 个文件")
+
+        for file_path in files:
+            try:
+                loader = PaddleOCRLoader(file_path, **self.loader_kwargs)
+                docs = loader.load()
+                all_docs.extend(docs)
+                logger.info(f"  ✓ {file_path.name}: {len(docs)} 页/块")
+            except Exception as e:
+                logger.error(f"  ✗ {file_path.name}: {e}")
+
+        logger.info(f"批量加载完成, 共 {len(all_docs)} 个文档块")
+        return all_docs
+
+    def lazy_load(self) -> Iterator[Document]:
+        """延迟加载"""
+        files = []
+        for pattern in self.glob_patterns:
+            files.extend(self.directory.glob(pattern))
+        files = sorted(set(files))
+
+        for file_path in files:
+            try:
+                loader = PaddleOCRLoader(file_path, **self.loader_kwargs)
+                yield from loader.lazy_load()
+            except Exception as e:
+                logger.error(f"加载失败 {file_path.name}: {e}")
+
+
+# ============================================================
+# 便捷函数
+# ============================================================
+
+def load_document(file_path: Union[str, Path], **kwargs) -> List[Document]:
+    """便捷函数: 加载单个文档 (自动识别格式)"""
+    loader = PaddleOCRLoader(file_path, **kwargs)
+    return loader.load()
+
+
+def load_directory(directory: Union[str, Path], **kwargs) -> List[Document]:
+    """便捷函数: 加载目录下所有文档"""
+    loader = PaddleOCRDirectoryLoader(directory, **kwargs)
+    return loader.load()
+
+
+def ocr_to_markdown(file_path: Union[str, Path]) -> str:
+    """便捷函数: OCR 识别并返回 Markdown"""
+    return VLOCRExtractor.extract_to_markdown(file_path)
+
+
+def ocr_to_json(file_path: Union[str, Path], save_path: Optional[str] = None) -> Dict:
+    """便捷函数: OCR 识别并返回 JSON"""
+    return VLOCRExtractor.extract_to_json(file_path, save_path)
+
+
+# ============================================================
+# 测试入口
+# ============================================================
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print(f"用法: python {__file__} <file_path> [--json] [--md]")
+        print(f"支持格式: {config.SUPPORTED_FORMATS}")
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+    output_mode = "doc"  # doc / json / md
+    if "--json" in sys.argv:
+        output_mode = "json"
+    elif "--md" in sys.argv:
+        output_mode = "md"
+
+    loader = PaddleOCRLoader(file_path, verbose=True)
+
+    if output_mode == "json":
+        result = ocr_to_json(file_path)
+        import json
+        print(json.dumps(result, ensure_ascii=False, indent=2)[:5000])
+    elif output_mode == "md":
+        md = ocr_to_markdown(file_path)
+        print(md[:5000])
+    else:
+        documents = loader.load()
+        print(f"\n{'='*60}")
+        print(f"共加载 {len(documents)} 页/文档")
+        print(f"{'='*60}")
+        for i, doc in enumerate(documents):
+            print(f"\n--- 第 {doc.metadata.get('page', '?')} 页 "
+                  f"({len(doc.page_content)} 字符) ---")
+            print(doc.page_content[:500])
+            if len(doc.page_content) > 500:
+                print("...")
+            print(f"  元数据: source={doc.metadata.get('document_name')}, "
+                  f"tables={doc.metadata.get('tables_count', 0)}, "
+                  f"formulas={doc.metadata.get('formulas_count', 0)}")

rag_chain.py

@@ -0,0 +1,440 @@
+"""
+============================================================
+RAG 检索增强生成问答链
+============================================================
+LLM: Qwen3-8B (通过 OpenAI 兼容 API 调用)
+嵌入: Qwen3-Embedding (通过 OpenAI 兼容 API 调用)
+
+所有模型均通过 API 调用, 无需本地推理:
+  - Embedding API: /v1/embeddings
+  - LLM API:       /v1/chat/completions
+
+支持任意 OpenAI 兼容 API:
+  - vLLM 部署的 Qwen3 / Llama / DeepSeek 等
+  - 第三方 API (DeepSeek, 通义千问, 智谱 GLM 等)
+  - OpenAI 官方 API
+
+功能:
+  1. LangChain LCEL RAG 问答链
+  2. 多轮对话
+  3. 流式输出
+  4. 来源引用
+"""
+
+from typing import List, Optional, Dict, Any, Iterator
+
+from langchain_core.documents import Document
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnableParallel
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from langchain_openai import ChatOpenAI
+
+from loguru import logger
+
+import config
+from vector_store import VectorStoreManager
+
+
+# ============================================================
+# LLM 工厂 (纯 API 模式)
+# ============================================================
+
+def create_llm(
+    model_name: Optional[str] = None,
+    api_base: Optional[str] = None,
+    api_key: Optional[str] = None,
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+) -> ChatOpenAI:
+    """
+    创建 OpenAI 兼容的 LLM 实例
+
+    Args:
+        model_name:  模型名称, 如 Qwen/Qwen3-8B
+        api_base:    API 地址
+        api_key:     API Key
+        temperature: 生成温度
+        max_tokens:  最大输出 token 数
+
+    Returns:
+        ChatOpenAI 实例
+    """
+    return ChatOpenAI(
+        model=model_name or config.LLM_MODEL_NAME,
+        api_key=api_key or config.LLM_API_KEY,
+        base_url=api_base or config.LLM_API_BASE,
+        temperature=temperature or config.LLM_TEMPERATURE,
+        max_tokens=max_tokens or config.LLM_MAX_TOKENS,
+    )
+
+
+# ============================================================
+# RAG 问答链
+# ============================================================
+
+class RAGChain:
+    """
+    RAG 检索增强生成链
+
+    流程:
+      Query → Embedding API 检索 → 上下文格式化 →
+      Prompt 模板 → LLM API 生成 → 结构化回答 (含来源)
+
+    用法:
+        rag = RAGChain(vector_store_manager)
+        result = rag.query("文档主要内容是什么?")
+    """
+
+    def __init__(
+        self,
+        vector_store_manager: VectorStoreManager,
+        llm: Optional[BaseChatModel] = None,
+        top_k: int = config.RETRIEVAL_TOP_K,
+        system_prompt: Optional[str] = None,
+        search_type: str = "similarity",
+    ):
+        self.vector_store_manager = vector_store_manager
+        self.llm = llm or create_llm()
+        self.top_k = top_k
+        self.system_prompt = system_prompt or config.SYSTEM_PROMPT
+        self.search_type = search_type
+        self._chain = self._build_chain()
+
+        logger.info(
+            f"RAG 问答链初始化完成 (LLM={config.LLM_MODEL_NAME}, "
+            f"top_k={top_k}, search={search_type})"
+        )
+
+    def _build_chain(self):
+        """使用 LangChain LCEL 构建 RAG 链"""
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", "{system_prompt}"),
+            ("human", config.RAG_PROMPT_TEMPLATE),
+        ])
+
+        chain = (
+            RunnableParallel({
+                "context": lambda inputs: self._retrieve_and_format(inputs["query"]),
+                "question": lambda inputs: inputs["query"],
+                "system_prompt": lambda _: self.system_prompt,
+            })
+            | prompt
+            | self.llm
+            | StrOutputParser()
+        )
+
+        return chain
+
+    def _retrieve_and_format(self, query: str) -> str:
+        docs = self._retrieve(query)
+        return self._format_docs(docs)
+
+    def _retrieve(self, query: str) -> List[Document]:
+        if self.search_type == "mmr":
+            return self.vector_store_manager.max_marginal_relevance_search(
+                query, k=self.top_k
+            )
+        elif self.search_type == "similarity_score":
+            results = self.vector_store_manager.similarity_search_with_score(
+                query, k=self.top_k
+            )
+            return [doc for doc, _ in results]
+        else:
+            return self.vector_store_manager.similarity_search(query, k=self.top_k)
+
+    MAX_CONTEXT_CHARS = 1800  # 总上下文字符上限 (适配小显存 1152 token 限制)
+
+    @classmethod
+    def _format_docs(cls, docs: List[Document]) -> str:
+        if not docs:
+            return "（未找到相关文档内容）"
+
+        # 控制每个文档块长度，避免超过小显存的 token 限制
+        max_chunk_chars = cls.MAX_CONTEXT_CHARS // max(len(docs), 1)
+
+        parts = []
+        for i, doc in enumerate(docs, 1):
+            page = doc.metadata.get("page", "未知")
+            doc_name = doc.metadata.get("document_name", "未知文档")
+
+            content = doc.page_content
+            if len(content) > max_chunk_chars:
+                content = content[:max_chunk_chars] + "..."
+
+            header = f"[{i}] {doc_name} p{page}"
+            parts.append(f"{header}\n{content}")
+
+        return "\n\n---\n\n".join(parts)
+
+    # ---- 查询接口 ----
+
+    def query(self, question: str) -> Dict[str, Any]:
+        """
+        单次问答
+
+        Returns:
+            {"query": str, "answer": str, "sources": [...], "context": str}
+        """
+        logger.info(f"RAG 查询: {question[:100]}...")
+
+        retrieved_docs = self._retrieve(question)
+        answer = self._chain.invoke({"query": question})
+
+        sources = self._build_sources(retrieved_docs)
+
+        logger.info(f"生成完成: {len(answer)} 字符, {len(sources)} 个来源")
+        return {
+            "query": question,
+            "answer": answer,
+            "sources": sources,
+            "context": self._format_docs(retrieved_docs),
+        }
+
+    def query_stream(self, question: str) -> Iterator[str]:
+        """流式问答"""
+        logger.info(f"RAG 流式查询: {question[:100]}...")
+        for chunk in self._chain.stream({"query": question}):
+            yield chunk
+
+    def query_with_history(
+        self,
+        question: str,
+        chat_history: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """带对话历史的多轮问答"""
+        chat_history = chat_history or []
+
+        history_context = self._format_history(chat_history)
+        retrieved_docs = self._retrieve(question)
+        context = self._format_docs(retrieved_docs)
+
+        messages = [
+            SystemMessage(content=(
+                f"{self.system_prompt}\n\n"
+                f"## 对话历史:\n{history_context}"
+            )),
+            HumanMessage(content=config.RAG_PROMPT_TEMPLATE.format(
+                system_prompt="",
+                context=context,
+                question=question,
+            )),
+        ]
+
+        response = self.llm.invoke(messages)
+        answer = response.content
+
+        return {
+            "query": question,
+            "answer": answer,
+            "sources": self._build_sources(retrieved_docs),
+            "context": context,
+        }
+
+    @staticmethod
+    def _build_sources(docs: List[Document]) -> List[Dict[str, Any]]:
+        return [
+            {
+                "rank": i,
+                "content": doc.page_content[:300],
+                "page": doc.metadata.get("page", "未知"),
+                "document": doc.metadata.get("document_name", "未知"),
+                "content_type": doc.metadata.get("content_type", "text"),
+            }
+            for i, doc in enumerate(docs, 1)
+        ]
+
+    @staticmethod
+    def _format_history(chat_history: List[Dict[str, str]]) -> str:
+        if not chat_history:
+            return "（无历史对话）"
+        parts = []
+        for turn in chat_history[-8:]:  # 仅保留最近 4 轮对话
+            role = "用户" if turn.get("role") == "user" else "助手"
+            parts.append(f"{role}: {turn.get('content', '')}")
+        return "\n".join(parts)
+
+
+# ============================================================
+# PDF 完整问答流水线
+# ============================================================
+
+class PDFRAGPipeline:
+    """
+    PDF 智能问答完整流水线 (全 API 模式)
+
+    一步完成: 文档上传 → OCR → 清洗 → 分割 → API嵌入 → 入库 → API问答
+
+    用法:
+        pipeline = PDFRAGPipeline()
+        pipeline.ingest("document.pdf")
+        result = pipeline.ask("文档主要内容是什么?")
+    """
+
+    def __init__(
+        self,
+        llm: Optional[BaseChatModel] = None,
+        store_type: Optional[str] = None,
+        chunk_size: int = config.CHUNK_SIZE,
+        chunk_overlap: int = config.CHUNK_OVERLAP,
+        verbose: bool = True,
+    ):
+        self.llm = llm or create_llm()
+        self.store_type = store_type or config.VECTOR_STORE_TYPE
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.verbose = verbose
+
+        self._vector_store_manager: Optional[VectorStoreManager] = None
+        self._rag_chain: Optional[RAGChain] = None
+
+    def ingest(self, file_path: str, clear_existing: bool = True) -> int:
+        """
+        处理文档并构建向量数据库
+
+        支持格式: PDF / PNG / JPG / BMP / TIF
+        """
+        from ocr_loader import PaddleOCRLoader
+        from text_processor import TextProcessingPipeline
+
+        logger.info(f"开始入库: {file_path}")
+
+        # Step 1: OCR
+        self._log("Step 1/4: PaddleOCR-VL-1.5 识别...")
+        loader = PaddleOCRLoader(file_path, verbose=False)
+        raw_docs = loader.load()
+        self._log(f"  ✓ 识别完成: {len(raw_docs)} 页/文档")
+
+        # Step 2: 处理
+        self._log("Step 2/4: 文本清洗与分割...")
+        pipeline = TextProcessingPipeline(
+            chunk_size=self.chunk_size,
+            chunk_overlap=self.chunk_overlap,
+        )
+        chunks = pipeline.process(raw_docs)
+        self._log(f"  ✓ 分割完成: {len(chunks)} 个文本块")
+
+        # Step 3: 向量化 (通过 Embedding API)
+        self._log("Step 3/4: Embedding API 向量化...")
+        self._vector_store_manager = VectorStoreManager(store_type=self.store_type)
+        if clear_existing:
+            self._vector_store_manager.clear()
+        chunk_count = self._vector_store_manager.add_documents(chunks)
+        self._log(f"  ✓ 入库完成: {chunk_count} 个文本块")
+
+        # Step 4: 初始化 RAG
+        self._log("Step 4/4: 初始化 RAG 引擎...")
+        self._rag_chain = RAGChain(
+            vector_store_manager=self._vector_store_manager,
+            llm=self.llm,
+        )
+        self._log("  ✓ 问答引擎就绪")
+        self._log("入库完成! 可以开始提问。")
+
+        return chunk_count
+
+    def ingest_multiple(self, file_paths: List[str], clear_existing: bool = True) -> int:
+        total = 0
+        for i, fp in enumerate(file_paths):
+            total += self.ingest(fp, clear_existing=(clear_existing and i == 0))
+        return total
+
+    def ask(self, question: str) -> Dict[str, Any]:
+        if self._rag_chain is None:
+            self._vector_store_manager = VectorStoreManager(store_type=self.store_type)
+            if self._vector_store_manager.get_document_count() == 0:
+                raise RuntimeError("向量数据库为空! 请先调用 ingest() 处理文档。")
+            self._rag_chain = RAGChain(
+                vector_store_manager=self._vector_store_manager,
+                llm=self.llm,
+            )
+        return self._rag_chain.query(question)
+
+    def ask_stream(self, question: str) -> Iterator[str]:
+        if self._rag_chain is None:
+            raise RuntimeError("请先调用 ingest() 处理文档。")
+        return self._rag_chain.query_stream(question)
+
+    def ask_with_history(
+        self, question: str,
+        chat_history: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        if self._rag_chain is None:
+            raise RuntimeError("请先调用 ingest() 处理文档。")
+        return self._rag_chain.query_with_history(question, chat_history)
+
+    @property
+    def is_ready(self) -> bool:
+        try:
+            if self._vector_store_manager is None:
+                self._vector_store_manager = VectorStoreManager(store_type=self.store_type)
+            return self._vector_store_manager.get_document_count() > 0
+        except Exception:
+            return False
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        if self._vector_store_manager is None:
+            return {"status": "not_initialized"}
+        return self._vector_store_manager.get_stats()
+
+    def _log(self, msg: str):
+        if self.verbose:
+            print(msg)
+
+
+# ============================================================
+# 便捷函数
+# ============================================================
+
+def quick_qa(file_path: str, question: str) -> Dict[str, Any]:
+    """便捷函数: 直接对文档提问 (一次性)"""
+    from ocr_loader import PaddleOCRLoader
+    from text_processor import TextProcessingPipeline
+    from vector_store import build_vector_store
+
+    loader = PaddleOCRLoader(file_path, verbose=False)
+    raw_docs = loader.load()
+    pipeline = TextProcessingPipeline()
+    chunks = pipeline.process(raw_docs)
+    manager = build_vector_store(chunks, clear_existing=True)
+    chain = RAGChain(vector_store_manager=manager)
+    return chain.query(question)
+
+
+# ============================================================
+# 测试入口
+# ============================================================
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 3:
+        print(f"用法: python {__file__} <file_path> <question>")
+        print(f"示例: python {__file__} document.pdf '文档主要内容是什么?'")
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+    question = sys.argv[2]
+
+    print(f"\n{'='*60}")
+    print(f"  PDF/文档 智能问答测试")
+    print(f"  文件: {file_path}")
+    print(f"  问题: {question}")
+    print(f"{'='*60}")
+
+    result = quick_qa(file_path, question)
+
+    print(f"\n{'='*60}")
+    print(f"  回答:")
+    print(f"{'='*60}")
+    print(result["answer"])
+
+    print(f"\n{'='*60}")
+    print(f"  参考来源:")
+    print(f"{'='*60}")
+    for src in result["sources"]:
+        print(f"  [{src['rank']}] {src['document']} 第{src['page']}页 ({src['content_type']})")
+        print(f"      {src['content'][:150]}...")

requirements.txt

@@ -1,18 +1,32 @@
-python-dotenv==1.2.1
+# ============================================================
+# PDF OCR 智能问答系统 依赖
+# 模型栈: PaddleOCR-VL-0.9B (API) + Qwen3-Embedding-0.6B (API) + Qwen3-1.7B (API)#
+# 需事先启动 vLLM 或其他兼容 API 服务
+# ============================================================
 
-numpy==2.2.6
-Pillow==12.0.0
-fastapi==0.135.1
-uvicorn==0.41.0
-openai==2.20.0
-requests==2.32.5
-pydantic==2.12.5
-gradio==6.8.0
-moviepy==1.0.3
-opencv-python
-modelscope==1.34.0
-qwen-vl-utils==0.0.14
-funasr==1.3.1
-nano-vectordb==0.0.4.3
-tqdm==4.67.3
-soundfile
+
+# --- PDF & 图片处理 ---
+PyMuPDF>=1.24.0
+Pillow>=10.0.0
+numpy>=1.24.0
+
+# --- LangChain 生态 ---
+langchain>=0.3.0
+langchain-core>=0.3.0
+langchain-community>=0.3.0
+langchain-text-splitters>=0.3.0
+langchain-openai>=0.2.0          # OpenAI 兼容 API 客户端 (Embedding + LLM)
+
+# --- 向量数据库 ---
+chromadb>=0.5.0
+# faiss-cpu  (可选)
+
+# --- Web UI ---
+fastapi>=0.110.0
+uvicorn>=0.29.0
+python-multipart>=0.0.9
+
+# --- 工具 ---
+python-dotenv>=1.0.0
+tqdm>=4.66.0
+loguru>=0.7.0

run.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+============================================================
+PDF OCR 智能问答系统 — 端到端运行脚本
+============================================================
+
+用法:
+    # 交互模式: 处理文档后进入问答 REPL
+    python run.py -f document.pdf
+
+    # 单次问答
+    python run.py -f document.pdf -q "文档主要内容是什么?"
+
+    # 批量处理多个文档
+    python run.py -f doc1.pdf doc2.png scan3.jpg
+
+    # 指定分块参数
+    python run.py -f document.pdf --chunk-size 1000 --chunk-overlap 200
+
+    # 从已有向量库加载 (跳过 OCR, 直接问答)
+    python run.py --load
+
+    # 清空旧数据重新处理
+    python run.py -f document.pdf --clear
+
+    # 显示检索到的原文
+    python run.py -f document.pdf -q "问题" --show-sources
+
+环境变量 (或 .env 文件):
+    EMBEDDING_API_BASE   Embedding API 地址
+    EMBEDDING_MODEL_NAME Embedding 模型名
+    LLM_API_BASE         LLM API 地址
+    LLM_API_KEY          LLM API Key
+    LLM_MODEL_NAME       LLM 模型名
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import List, Optional
+
+# ---- 环境补丁 (必须在其他导入之前) ----
+def _patch():
+    import types as _types
+    if "langchain_text_splitters" not in sys.modules:
+        m = _types.ModuleType("langchain_text_splitters")
+        m.__path__ = []
+        sys.modules["langchain_text_splitters"] = m
+    try:
+        import torch  # noqa: F401
+    except ImportError:
+        pass
+
+
+_patch()
+
+# 项目导入
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import config
+from ocr_loader import PaddleOCRLoader
+from text_processor import TextProcessingPipeline, RecursiveCharacterTextSplitter
+from embeddings import get_embedding_model
+from vector_store import VectorStoreManager, build_vector_store
+from rag_chain import RAGChain, create_llm, PDFRAGPipeline
+
+# 将内置分割器注入到 mock 模块
+import sys as _sys
+_lts = _sys.modules.get("langchain_text_splitters")
+if _lts is not None:
+    _lts.RecursiveCharacterTextSplitter = RecursiveCharacterTextSplitter
+
+from loguru import logger
+
+# ============================================================
+# Banner
+# ============================================================
+
+BANNER = r"""
+  ┌──────────────────────────────────────────────────────┐
+  │         📄 PDF OCR 智能问答系统                        │
+  │                                                      │
+  │  OCR:   PaddleOCR-VL-1.5 (本地)                      │
+  │  嵌入:  {emb_model}                                  │
+  │  LLM:   {llm_model}                                  │
+  │  向量库: {vec_store}                                  │
+  └──────────────────────────────────────────────────────┘
+"""
+
+
+def print_banner():
+    emb_name = config.EMBEDDING_MODEL_NAME
+    llm_name = config.LLM_MODEL_NAME
+    vs = config.VECTOR_STORE_TYPE
+    # 截断过长的模型名
+    if len(emb_name) > 35:
+        emb_name = emb_name[:32] + "..."
+    if len(llm_name) > 35:
+        llm_name = llm_name[:32] + "..."
+    print(BANNER.format(emb_model=emb_name, llm_model=llm_name, vec_store=vs))
+
+
+# ============================================================
+# 步骤函数
+# ============================================================
+
+def _save_documents(docs: list, path: Path, label: str = "文档"):
+    """将 LangChain Document 列表保存为 JSON"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = []
+    for doc in docs:
+        data.append({
+            "page_content": doc.page_content,
+            "metadata": {k: v for k, v in doc.metadata.items()
+                         if isinstance(v, (str, int, float, bool, type(None)))}
+        })
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+    print(f"  💾 {label}已保存: {path} ({len(data)} 条)")
+
+
+def step_ocr(file_paths: List[str], output_dir: Optional[Path] = None) -> list:
+    """Step 1: OCR 识别所有文件, 全部结果合并保存到一个文件"""
+    all_docs = []
+    for fp in file_paths:
+        fp = Path(fp)
+        if not fp.exists():
+            logger.error(f"文件不存在: {fp}")
+            continue
+        suffix = fp.suffix.lower()
+        if suffix not in config.SUPPORTED_FORMATS:
+            logger.warning(f"跳过不支持格式: {fp} (支持: {config.SUPPORTED_FORMATS})")
+            continue
+
+        icon = "📄" if suffix == ".pdf" else "🖼️"
+        print(f"  {icon} 正在识别: {fp.name} ...", end=" ", flush=True)
+        t0 = time.time()
+        loader = PaddleOCRLoader(str(fp), verbose=True)
+        docs = loader.load()
+        elapsed = time.time() - t0
+        print(f"{len(docs)} 页/文档 ({elapsed:.1f}s)")
+        all_docs.extend(docs)
+
+    # 所有文件识别完后统一保存
+    if output_dir and all_docs:
+        save_path = output_dir / "ocr_results.json"
+        _save_documents(all_docs, save_path, "OCR结果 ")
+
+    return all_docs
+
+
+def step_process(
+    documents: list, chunk_size: int, chunk_overlap: int,
+    output_dir: Optional[Path] = None
+) -> list:
+    """Step 2: 文本清洗 + 分割, 全部结果合并保存到一个文件"""
+    print(f"  ✂️  正在分割: {len(documents)} 个文档 ...", end=" ", flush=True)
+    t0 = time.time()
+    pipeline = TextProcessingPipeline(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+    )
+    chunks = pipeline.process(documents)
+    elapsed = time.time() - t0
+    print(f"→ {len(chunks)} 个文本块 ({elapsed:.1f}s)")
+
+    if output_dir and chunks:
+        save_path = output_dir / "chunks.json"
+        _save_documents(chunks, save_path, "分块结果 ")
+
+    return chunks
+
+
+def step_embed(chunks: list) -> VectorStoreManager:
+    """Step 3: 向量嵌入 + 入库"""
+    print(f"  🧠 正在向量化: {len(chunks)} 个文本块 ...", end=" ", flush=True)
+    t0 = time.time()
+    manager = build_vector_store(chunks, clear_existing=True)
+    elapsed = time.time() - t0
+    print(f"完成 ({elapsed:.1f}s)")
+    return manager
+
+
+def step_rag(manager: VectorStoreManager):
+    """Step 4: 初始化 RAG 链"""
+    llm = create_llm()
+    chain = RAGChain(vector_store_manager=manager, llm=llm)
+    return chain
+
+
+# ============================================================
+# 核心流程
+# ============================================================
+
+def run_ingest(
+    file_paths: List[str],
+    chunk_size: int = config.CHUNK_SIZE,
+    chunk_overlap: int = config.CHUNK_OVERLAP,
+    clear: bool = True,
+    output_dir: Optional[Path] = None,
+) -> VectorStoreManager:
+    """完整入库流程: OCR → 处理 → 嵌入 → 入库"""
+    print("\n" + "─" * 55)
+    print("  📥 阶段 1: 文档入库")
+    print("─" * 55)
+
+    # Step 1: OCR
+    t_start = time.time()
+    documents = step_ocr(file_paths, output_dir=output_dir)
+    if not documents:
+        logger.error("未识别到任何文本内容, 请检查文件是否包含可读文字")
+        sys.exit(1)
+    print(f"      总计: {len(documents)} 个原始文档页")
+
+    # Step 2: 处理
+    chunks = step_process(documents, chunk_size, chunk_overlap,
+                          output_dir=output_dir)
+
+    # Step 3: 嵌入入库
+    manager = step_embed(chunks)
+
+    total_time = time.time() - t_start
+    print(f"\n  ✅ 入库完成 (总耗时 {total_time:.1f}s)")
+    print(f"     文档: {len(documents)} 页 → {len(chunks)} 个文本块")
+    print(f"     向量维度: {config.EMBEDDING_MODEL_NAME}")
+    print(f"     存储: {config.VECTOR_STORE_TYPE} @ {config.VECTOR_DB_DIR}")
+
+    return manager
+
+
+def run_qa(chain: RAGChain, question: str, show_sources: bool = False):
+    """执行单次问答"""
+    print("\n" + "─" * 55)
+    print(f"  ❓ 问题: {question}")
+    print("─" * 55)
+
+    t0 = time.time()
+    result = chain.query(question)
+    elapsed = time.time() - t0
+
+    print(f"\n  🤖 回答 ({elapsed:.1f}s):")
+    print("─" * 55)
+    print(result["answer"])
+
+    if show_sources:
+        print(f"\n  📚 参考来源 ({len(result['sources'])} 条):")
+        print("─" * 55)
+        for src in result["sources"]:
+            print(f"  [{src['rank']}] {src['document']} | 第{src['page']}页 "
+                  f"| {src['content_type']}")
+            print(f"      {src['content'][:120]}...")
+
+    return result
+
+
+def run_repl(chain: RAGChain):
+    """交互式问答 REPL"""
+    print("\n" + "─" * 55)
+    print("  💬 交互问答模式")
+    print("─" * 55)
+    print("  输入问题后回车, 输入 :s 切换来源显示")
+    print("  输入 :q 退出, :c 清屏, :h 帮助")
+    print("─" * 55)
+
+    chat_history = []
+    show_sources = False
+
+    while True:
+        try:
+            user_input = input("\n  🔍 > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n  再见! 👋")
+            break
+
+        if not user_input:
+            continue
+
+        # 命令处理
+        if user_input.startswith(":"):
+            cmd = user_input[1:].strip().lower()
+            if cmd in ("q", "quit", "exit"):
+                print("  再见! 👋")
+                break
+            elif cmd == "s":
+                show_sources = not show_sources
+                print(f"  来源显示: {'开启' if show_sources else '关闭'}")
+            elif cmd == "c":
+                os.system("clear" if os.name != "nt" else "cls")
+            elif cmd == "h":
+                print("  命令: :q 退出 | :s 切换来源 | :c 清屏 | :h 帮助")
+            else:
+                print(f"  未知命令: {user_input}")
+            continue
+
+        # 问答
+        t0 = time.time()
+        result = chain.query_with_history(user_input, chat_history)
+        elapsed = time.time() - t0
+
+        print(f"\n  🤖 ({elapsed:.1f}s):")
+        print(f"  {result['answer']}")
+
+        if show_sources:
+            print(f"\n  📚 来源 ({len(result['sources'])} 条):")
+            for src in result["sources"]:
+                print(f"  [{src['rank']}] {src['document']} "
+                      f"第{src['page']}页 | {src['content_type']}")
+
+        chat_history.append({"role": "user", "content": user_input})
+        chat_history.append({"role": "assistant", "content": result["answer"]})
+
+
+# ============================================================
+# API 连通性检查
+# ============================================================
+
+def check_apis() -> bool:
+    """检查 Embedding API 和 LLM API 是否可达"""
+    import urllib.request
+
+    all_ok = True
+
+    # 检查 Embedding API
+    emb_url = config.EMBEDDING_API_BASE.rstrip("/")
+    try:
+        req = urllib.request.Request(f"{emb_url}/models", method="HEAD")
+        urllib.request.urlopen(req, timeout=5)
+        print(f"  ✅ Embedding API: {emb_url}")
+    except Exception as e:
+        print(f"  ⚠️  Embedding API: {emb_url} — {e}")
+        all_ok = False
+
+    # 检查 LLM API
+    llm_url = config.LLM_API_BASE.rstrip("/")
+    try:
+        req = urllib.request.Request(f"{llm_url}/models", method="HEAD")
+        urllib.request.urlopen(req, timeout=5)
+        print(f"  ✅ LLM API: {llm_url}")
+    except Exception as e:
+        print(f"  ⚠️  LLM API: {llm_url} — {e}")
+        all_ok = False
+
+    return all_ok
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="PDF OCR 智能问答系统 — 端到端运行脚本",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  python run.py -f document.pdf                    # 交互问答
+  python run.py -f doc.pdf -q "主要内容?"           # 单次问答
+  python run.py -f a.pdf b.png --clear             # 批量处理
+  python run.py --load                             # 加载已有向量库
+        """,
+    )
+    parser.add_argument(
+        "-f", "--files", nargs="+",
+        default=["/data/huangjie/Project/dProject/pdfocr/过滤网modify.pdf",
+                 "/data/huangjie/Project/dProject/pdfocr/videoagent.png",
+                 "/data/huangjie/Project/dProject/pdfocr/biaozhun.jpg"],
+        help="要处理的文档路径 (PDF/PNG/JPG/BMP/TIF)",
+    )
+    parser.add_argument(
+        "-q", "--question",
+        help="单次问答 (不进入交互模式)",
+    )
+    parser.add_argument(
+        "--load", action="store_true",
+        help="加载已有向量库, 跳过 OCR 处理",
+    )
+    parser.add_argument(
+        "--clear", action="store_true",
+        help="清空旧向量库数据后重新处理",
+    )
+    parser.add_argument(
+        "--chunk-size", type=int, default=config.CHUNK_SIZE,
+        help=f"文本块大小 (默认: {config.CHUNK_SIZE})",
+    )
+    parser.add_argument(
+        "--chunk-overlap", type=int, default=config.CHUNK_OVERLAP,
+        help=f"块间重叠字符数 (默认: {config.CHUNK_OVERLAP})",
+    )
+    parser.add_argument(
+        "--show-sources", action="store_true",
+        help="在回答中显示参考来源",
+    )
+    parser.add_argument(
+        "--top-k", type=int, default=config.RETRIEVAL_TOP_K,
+        help=f"检索返回文档数 (默认: {config.RETRIEVAL_TOP_K})",
+    )
+    parser.add_argument(
+        "--skip-api-check", action="store_true",
+        help="跳过 API 连通性检查",
+    )
+    parser.add_argument(
+        "--output-dir", type=str, default=None,
+        help=f"中间结果保存目录 (默认: {config.OCR_OUTPUT_DIR})",
+    )
+
+    args = parser.parse_args()
+
+    # Banner
+    print_banner()
+
+    # API 检查
+    if not args.skip_api_check:
+        print("  🔌 API 连通性检查:")
+        check_apis()
+        print()
+
+    # 模式判断
+    if args.load:
+        # 加载已有向量库
+        print("  📂 加载已有向量库...")
+        manager = VectorStoreManager(store_type=config.VECTOR_STORE_TYPE)
+        count = manager.get_document_count()
+        if count == 0:
+            logger.error("向量库为空! 请先用 -f 指定文件进行入库")
+            sys.exit(1)
+        print(f"  ✅ 已加载: {count} 个文档块")
+    elif args.files:
+        # 处理文件
+        output_dir = Path(args.output_dir) if args.output_dir else config.OCR_OUTPUT_DIR
+        manager = run_ingest(
+            args.files,
+            chunk_size=args.chunk_size,
+            chunk_overlap=args.chunk_overlap,
+            clear=args.clear,
+            output_dir=output_dir,
+        )
+    else:
+        parser.print_help()
+        print("\n  ❌ 请指定 -f/--files 或 --load")
+        sys.exit(1)
+
+    # 初始化 RAG 链
+    print("\n" + "─" * 55)
+    print("  🔗 阶段 2: 初始化 RAG 问答引擎")
+    print("─" * 55)
+    llm = create_llm()
+    chain = RAGChain(
+        vector_store_manager=manager,
+        llm=llm,
+        top_k=args.top_k,
+    )
+    print(f"  ✅ RAG 引擎就绪 (LLM={config.LLM_MODEL_NAME})")
+
+    # 问答
+    if args.question:
+        run_qa(chain, args.question, show_sources=args.show_sources)
+    else:
+        run_repl(chain)
+
+
+if __name__ == "__main__":
+    main()

static/index.html

@@ -0,0 +1,637 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>OCR RAG — 智能问答系统</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+<style>
+:root {
+  --bg-root: #07090f;
+  --bg-surface: #0c0f17;
+  --bg-elevated: #111620;
+  --bg-overlay: #181d29;
+  --border-default: #1e2533;
+  --border-active: #2a3347;
+  --text-primary: #e4e7ee;
+  --text-secondary: #8b92a3;
+  --text-muted: #545b6d;
+  --accent-amber: #e8a840;
+  --accent-amber-dim: rgba(232,168,64,0.12);
+  --accent-amber-glow: rgba(232,168,64,0.25);
+  --accent-steel: #7eb8da;
+  --accent-steel-dim: rgba(126,184,218,0.1);
+  --accent-green: #4db88d;
+  --accent-red: #e0556a;
+  --radius-sm: 6px;
+  --radius-md: 10px;
+  --radius-lg: 14px;
+  --font-body: 'Outfit', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', 'SF Mono', monospace;
+  --transition-smooth: 0.25s cubic-bezier(0.22,0.61,0.36,1);
+}
+
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+html,body{height:100%;background:var(--bg-root);color:var(--text-primary);font-family:var(--font-body);font-weight:400;line-height:1.6;overflow:hidden}
+body::before{content:'';position:fixed;inset:0;background:radial-gradient(ellipse 60% 50% at 20% 50%, rgba(126,184,218,0.04) 0%,transparent 70%),radial-gradient(ellipse 50% 60% at 85% 40%, rgba(232,168,64,0.03) 0%,transparent 70%);pointer-events:none;z-index:0}
+body::after{content:'';position:fixed;inset:0;background-image:radial-gradient(circle, rgba(255,255,255,0.025) 1px, transparent 1px);background-size:28px 28px;pointer-events:none;z-index:0}
+#app{position:relative;z-index:1;display:flex;height:100vh;width:100vw}
+
+/* ── Sidebar ── */
+#sidebar{width:340px;min-width:340px;background:var(--bg-surface);border-right:1px solid var(--border-default);display:flex;flex-direction:column;overflow-y:auto;overflow-x:hidden;z-index:2}
+.sidebar-brand{padding:24px 24px 20px;border-bottom:1px solid var(--border-default)}
+.sidebar-brand .logo{display:flex;align-items:center;gap:10px;text-decoration:none;color:inherit}
+.sidebar-brand .logo-icon{width:34px;height:34px;background:linear-gradient(135deg,var(--accent-amber),#d4952a);border-radius:var(--radius-sm);display:flex;align-items:center;justify-content:center;font-size:18px;color:#0a0d14;font-weight:700}
+.sidebar-brand h1{font-family:var(--font-mono);font-size:15px;font-weight:600;letter-spacing:-0.02em;color:var(--text-primary);line-height:1.2}
+.sidebar-brand .subtitle{font-size:11px;color:var(--text-muted);font-family:var(--font-mono);letter-spacing:0.04em;text-transform:uppercase}
+.sidebar-section{padding:20px 24px;border-bottom:1px solid var(--border-default)}
+.sidebar-section-header{display:flex;align-items:center;gap:8px;margin-bottom:14px}
+.sidebar-section-header .dot{width:7px;height:7px;border-radius:50%;background:var(--accent-amber);box-shadow:0 0 6px var(--accent-amber-glow)}
+.sidebar-section-header span{font-family:var(--font-mono);font-size:11px;font-weight:500;letter-spacing:0.06em;text-transform:uppercase;color:var(--text-secondary)}
+.sidebar-section-header .count-badge{font-family:var(--font-mono);font-size:10px;font-weight:600;background:var(--bg-elevated);border:1px solid var(--border-active);padding:2px 8px;border-radius:100px;color:var(--text-secondary);margin-left:auto}
+
+.upload-zone{border:2px dashed var(--border-active);border-radius:var(--radius-md);padding:24px 20px;text-align:center;cursor:pointer;transition:all var(--transition-smooth);background:var(--bg-elevated)}
+.upload-zone:hover,.upload-zone.drag-over{border-color:var(--accent-amber);background:var(--accent-amber-dim)}
+.upload-zone .upload-icon{font-size:28px;margin-bottom:8px;opacity:0.7}
+.upload-zone .upload-text{font-size:13px;color:var(--text-secondary);font-weight:500}
+.upload-zone .upload-hint{font-size:11px;color:var(--text-muted);margin-top:4px;font-family:var(--font-mono)}
+
+.file-queue{margin-top:10px;max-height:160px;overflow-y:auto}
+.file-queue-item{display:flex;align-items:center;gap:8px;padding:8px 10px;border-radius:var(--radius-sm);font-size:12px;margin-top:4px;background:var(--bg-elevated);border:1px solid var(--border-default);transition:all var(--transition-smooth)}
+.file-queue-item:hover{border-color:var(--border-active)}
+.file-queue-item .fq-icon{font-size:15px;flex-shrink:0}
+.file-queue-item .fq-info{flex:1;min-width:0}
+.file-queue-item .fq-name{font-weight:500;color:var(--text-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;font-size:12px}
+.file-queue-item .fq-meta{font-family:var(--font-mono);font-size:10px;color:var(--text-muted)}
+.file-queue-item .fq-remove{width:22px;height:22px;flex-shrink:0;border-radius:50%;border:1px solid var(--border-default);background:transparent;color:var(--text-muted);cursor:pointer;display:flex;align-items:center;justify-content:center;font-size:14px;line-height:1;transition:all var(--transition-smooth)}
+.file-queue-item .fq-remove:hover{border-color:var(--accent-red);color:var(--accent-red);background:rgba(224,85,106,0.08)}
+
+.btn{display:inline-flex;align-items:center;justify-content:center;gap:6px;border:none;border-radius:var(--radius-sm);font-family:var(--font-body);font-size:13px;font-weight:500;cursor:pointer;transition:all var(--transition-smooth);padding:10px 18px;white-space:nowrap}
+.btn-primary{width:100%;background:linear-gradient(135deg,var(--accent-amber),#d4952a);color:#0a0d14;font-weight:600;font-size:14px;padding:12px 24px;letter-spacing:0.02em}
+.btn-primary:hover{filter:brightness(1.1);transform:translateY(-1px)}
+.btn-primary:active{transform:translateY(0)}
+.btn-primary:disabled{opacity:0.4;cursor:not-allowed;filter:none;transform:none}
+.btn-sm{padding:6px 14px;font-size:12px;border-radius:var(--radius-sm);width:auto}
+
+.status-row{display:flex;align-items:center;gap:8px;padding:10px 14px;border-radius:var(--radius-sm);background:var(--bg-elevated);margin-top:8px;font-size:12px}
+.status-dot{width:8px;height:8px;border-radius:50%;flex-shrink:0}
+.status-dot.idle{background:var(--text-muted)}
+.status-dot.processing{background:var(--accent-amber);animation:pulse 1.2s ease-in-out infinite}
+.status-dot.ready{background:var(--accent-green);box-shadow:0 0 6px rgba(77,184,141,0.4)}
+.status-dot.error{background:var(--accent-red)}
+@keyframes pulse{0%,100%{opacity:1;box-shadow:0 0 4px var(--accent-amber-glow)}50%{opacity:0.4;box-shadow:0 0 12px var(--accent-amber-glow)}}
+
+.process-log{margin-top:10px;background:var(--bg-root);border-radius:var(--radius-sm);padding:12px;font-family:var(--font-mono);font-size:11px;color:var(--text-muted);max-height:140px;overflow-y:auto;line-height:1.7;display:none}
+.process-log.visible{display:block}
+.process-log .log-entry{opacity:0;animation:logReveal 0.3s ease forwards}
+.process-log .log-entry:nth-child(1){animation-delay:0.05s}
+.process-log .log-entry:nth-child(2){animation-delay:0.15s}
+.process-log .log-entry:nth-child(3){animation-delay:0.25s}
+.process-log .log-entry:nth-child(4){animation-delay:0.35s}
+.process-log .log-entry:nth-child(5){animation-delay:0.45s}
+@keyframes logReveal{from{opacity:0;transform:translateX(-8px)}to{opacity:1;transform:translateX(0)}}
+
+/* ── Sidebar file list ── */
+.sb-pf-item{display:flex;align-items:center;gap:6px;padding:7px 10px;border-radius:var(--radius-sm);margin-top:3px;background:var(--bg-elevated);border:1px solid transparent;cursor:pointer;transition:all var(--transition-smooth)}
+.sb-pf-item:hover{border-color:var(--border-active)}
+.sb-pf-item.selected{border-color:var(--accent-amber);background:var(--accent-amber-dim)}
+.sb-pf-item .sb-icon{font-size:13px;flex-shrink:0;opacity:0.7}
+.sb-pf-item .sb-name{font-size:11px;font-weight:500;color:var(--text-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;flex:1}
+.sb-pf-item .sb-meta{font-family:var(--font-mono);font-size:9px;color:var(--text-muted);white-space:nowrap}
+.sb-pf-item .sb-del{width:18px;height:18px;border-radius:50%;border:none;background:transparent;color:var(--text-muted);cursor:pointer;font-size:11px;display:none;align-items:center;justify-content:center;flex-shrink:0;transition:all var(--transition-smooth)}
+.sb-pf-item:hover .sb-del{display:flex}
+.sb-pf-item .sb-del:hover{background:rgba(224,85,106,0.12);color:var(--accent-red)}
+.sb-pf-empty{font-size:11px;color:var(--text-muted);text-align:center;padding:16px 0}
+
+/* ── Main ── */
+#main{flex:1;display:flex;flex-direction:column;min-width:0;background:var(--bg-root)}
+.tab-nav{display:flex;gap:0;border-bottom:1px solid var(--border-default);padding:0 20px;background:var(--bg-surface)}
+.tab-btn{padding:14px 22px;background:none;border:none;color:var(--text-muted);font-family:var(--font-mono);font-size:12px;font-weight:500;cursor:pointer;letter-spacing:0.04em;position:relative;transition:color var(--transition-smooth)}
+.tab-btn:hover{color:var(--text-secondary)}
+.tab-btn.active{color:var(--accent-amber)}
+.tab-btn.active::after{content:'';position:absolute;bottom:-1px;left:0;right:0;height:2px;background:var(--accent-amber);box-shadow:0 0 8px var(--accent-amber-glow)}
+.tab-btn .tab-badge{font-size:10px;background:var(--accent-amber-dim);color:var(--accent-amber);padding:1px 7px;border-radius:100px;margin-left:6px}
+.tab-panel{display:none;flex:1;overflow:hidden}
+.tab-panel.active{display:flex;flex-direction:column}
+
+/* ── Chat ── */
+#chat-panel{display:none;flex:1;flex-direction:column;overflow:hidden}
+#chat-panel.active{display:flex}
+.chat-messages{flex:1;overflow-y:auto;padding:24px 28px;display:flex;flex-direction:column;gap:18px}
+.chat-empty{flex:1;display:flex;flex-direction:column;align-items:center;justify-content:center;color:var(--text-muted);text-align:center;gap:12px}
+.chat-empty .empty-icon{font-size:48px;opacity:0.3}
+.chat-empty .empty-title{font-size:18px;font-weight:500;color:var(--text-secondary)}
+.chat-empty .empty-desc{font-size:13px;max-width:400px;line-height:1.6}
+.quick-prompts{display:flex;flex-wrap:wrap;gap:8px;justify-content:center;margin-top:8px}
+.quick-prompt{padding:6px 14px;border-radius:100px;font-size:12px;font-weight:500;cursor:pointer;border:1px solid var(--border-active);background:var(--bg-elevated);color:var(--text-secondary);transition:all var(--transition-smooth);white-space:nowrap}
+.quick-prompt:hover{border-color:var(--accent-amber);color:var(--accent-amber);background:var(--accent-amber-dim)}
+.message{display:flex;gap:12px;animation:msgIn 0.35s cubic-bezier(0.22,0.61,0.36,1)}
+@keyframes msgIn{from{opacity:0;transform:translateY(12px)}to{opacity:1;transform:translateY(0)}}
+.message .msg-avatar{width:32px;height:32px;border-radius:var(--radius-sm);display:flex;align-items:center;justify-content:center;font-size:15px;flex-shrink:0;font-weight:600}
+.message.user .msg-avatar{background:var(--accent-steel-dim);color:var(--accent-steel);font-family:var(--font-mono);font-size:13px}
+.message.assistant .msg-avatar{background:var(--accent-amber-dim);color:var(--accent-amber)}
+.message .msg-bubble{max-width:75%;padding:12px 16px;border-radius:var(--radius-md);font-size:14px;line-height:1.65}
+.message.user .msg-bubble{background:var(--bg-overlay);color:var(--text-primary);border:1px solid var(--border-default)}
+.message.assistant .msg-bubble{background:var(--bg-elevated);color:var(--text-primary);border:1px solid var(--border-active)}
+.chat-input-area{padding:16px 24px 20px;border-top:1px solid var(--border-default);background:var(--bg-surface)}
+.chat-input-row{display:flex;gap:10px;align-items:flex-end}
+.chat-input-row textarea{flex:1;background:var(--bg-root);border:1px solid var(--border-active);border-radius:var(--radius-md);color:var(--text-primary);font-family:var(--font-body);font-size:14px;padding:12px 16px;resize:none;outline:none;min-height:46px;max-height:120px;line-height:1.5;transition:border-color var(--transition-smooth)}
+.chat-input-row textarea:focus{border-color:var(--accent-amber);box-shadow:0 0 0 3px var(--accent-amber-dim)}
+.chat-input-row textarea::placeholder{color:var(--text-muted)}
+.chat-input-row .btn-send{width:46px;height:46px;border-radius:var(--radius-md);background:var(--accent-amber);border:none;color:#0a0d14;font-size:18px;cursor:pointer;transition:all var(--transition-smooth);display:flex;align-items:center;justify-content:center;flex-shrink:0}
+.chat-input-row .btn-send:hover{filter:brightness(1.1)}
+.chat-input-row .btn-send:disabled{opacity:0.3;cursor:not-allowed;filter:none}
+
+/* ── Documents tab (merged Preview + Documents) ── */
+#preview-panel{display:flex;flex-direction:column;overflow:hidden;flex:1}
+
+/* File cards row */
+.doc-cards-wrap{padding:16px 24px;border-bottom:1px solid var(--border-default);overflow-x:auto;flex-shrink:0}
+.doc-cards-wrap h3{font-family:var(--font-mono);font-size:11px;font-weight:500;letter-spacing:0.06em;color:var(--text-muted);text-transform:uppercase;margin-bottom:12px;display:flex;align-items:center;gap:8px}
+.doc-cards-wrap h3::before{content:'';width:7px;height:7px;border-radius:50%;background:var(--accent-amber);box-shadow:0 0 6px var(--accent-amber-glow)}
+.doc-cards{display:flex;gap:12px;padding-bottom:4px}
+.doc-card{flex:0 0 auto;width:220px;background:var(--bg-elevated);border:2px solid var(--border-default);border-radius:var(--radius-md);padding:16px;cursor:pointer;transition:all var(--transition-smooth);position:relative}
+.doc-card:hover{border-color:var(--border-active);background:var(--bg-overlay)}
+.doc-card.selected{border-color:var(--accent-amber);box-shadow:0 0 12px var(--accent-amber-dim);background:var(--bg-overlay)}
+.doc-card .dc-icon{width:38px;height:38px;border-radius:var(--radius-sm);display:flex;align-items:center;justify-content:center;font-family:var(--font-mono);font-size:12px;font-weight:700;margin-bottom:10px}
+.doc-card .dc-icon.pdf{background:rgba(224,85,106,0.12);color:var(--accent-red)}
+.doc-card .dc-icon.img{background:var(--accent-steel-dim);color:var(--accent-steel)}
+.doc-card .dc-name{font-weight:600;font-size:13px;color:var(--text-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;margin-bottom:8px;line-height:1.3}
+.doc-card .dc-stats{display:flex;gap:10px;font-family:var(--font-mono);font-size:10px;color:var(--text-muted)}
+.doc-card .dc-stats span{display:flex;align-items:center;gap:2px}
+.doc-card .dc-stats .dc-val{color:var(--text-secondary)}
+.doc-card .dc-delete{position:absolute;top:8px;right:8px;width:22px;height:22px;border-radius:50%;border:1px solid transparent;background:transparent;color:var(--text-muted);cursor:pointer;display:flex;align-items:center;justify-content:center;font-size:12px;transition:all var(--transition-smooth);opacity:0}
+.doc-card:hover .dc-delete{opacity:1;border-color:var(--border-default)}
+.doc-card .dc-delete:hover{border-color:var(--accent-red);color:var(--accent-red);background:rgba(224,85,106,0.08)}
+
+/* Preview pane */
+.doc-preview-wrap{flex:1;display:flex;flex-direction:column;overflow:hidden}
+.doc-preview-header{display:flex;align-items:center;gap:12px;padding:12px 24px;background:var(--bg-surface);border-bottom:1px solid var(--border-default);flex-shrink:0}
+.doc-preview-header .dph-title{font-weight:600;font-size:14px;color:var(--text-primary)}
+.doc-preview-header .dph-meta{font-family:var(--font-mono);font-size:11px;color:var(--text-muted);margin-left:auto}
+.doc-preview-body{flex:1;overflow-y:auto;padding:24px 28px;font-family:var(--font-mono);font-size:13px;line-height:1.8;color:var(--text-secondary);white-space:pre-wrap;word-break:break-word}
+.doc-preview-empty{flex:1;display:flex;align-items:center;justify-content:center;text-align:center;color:var(--text-muted)}
+.doc-preview-empty .dpe-icon{font-size:48px;opacity:0.15;margin-bottom:10px}
+.doc-preview-empty .dpe-text{font-size:14px}
+.pv-page-header{color:var(--accent-amber);font-weight:600;font-size:12px;letter-spacing:0.04em;padding:8px 0;border-bottom:1px solid var(--border-default);margin:16px 0 12px}
+.pv-page-header:first-child{margin-top:0}
+
+.doc-empty-state{display:flex;flex-direction:column;align-items:center;justify-content:center;height:100%;text-align:center;color:var(--text-muted)}
+.doc-empty-state .de-icon{font-size:56px;opacity:0.12;margin-bottom:12px}
+.doc-empty-state .de-title{font-size:16px;color:var(--text-secondary);font-weight:500}
+.doc-empty-state .de-desc{font-size:13px;margin-top:6px;max-width:360px}
+
+/* ── Split preview ── */
+.pv-split-wrap{flex:1;display:flex;flex-direction:column;overflow:hidden}
+.pv-split-header{display:flex;align-items:center;gap:12px;padding:10px 24px;background:var(--bg-surface);border-bottom:1px solid var(--border-default);flex-shrink:0}
+.pv-split-body{flex:1;display:flex;overflow:hidden}
+.pv-left{flex:1;overflow:auto;background:var(--bg-root);display:flex;align-items:center;justify-content:center;min-width:0}
+.pv-left iframe{width:100%;height:100%;border:none;background:#fff}
+.pv-left img{max-width:100%;max-height:100%;object-fit:contain}
+.pv-left-placeholder{color:var(--text-muted);font-size:13px;text-align:center}
+.pv-divider{width:4px;background:var(--border-default);flex-shrink:0;cursor:col-resize;transition:background var(--transition-smooth)}
+.pv-divider:hover{background:var(--accent-amber)}
+.pv-right{flex:1;overflow-y:auto;padding:20px 24px;font-family:var(--font-mono);font-size:13px;line-height:1.8;color:var(--text-secondary);white-space:pre-wrap;word-break:break-word;min-width:0}
+.pv-right-placeholder{text-align:center;color:var(--text-muted);font-size:13px;padding-top:60px}
+
+/* ── Status ── */
+#status-panel{padding:24px 28px;overflow-y:auto;flex:1}
+.status-card{background:var(--bg-elevated);border:1px solid var(--border-default);border-radius:var(--radius-md);padding:20px;margin-bottom:16px}
+.status-card h3{font-family:var(--font-mono);font-size:12px;font-weight:500;letter-spacing:0.06em;color:var(--text-muted);text-transform:uppercase;margin-bottom:14px;display:flex;align-items:center;gap:8px}
+.status-card h3::before{content:'';width:8px;height:8px;border-radius:2px;background:var(--accent-steel)}
+.status-card h3 .sc-btn{margin-left:auto;cursor:pointer}
+.status-card h3 .sc-btn::before{content:none}
+.model-stack{display:grid;grid-template-columns:1fr 1fr;gap:10px}
+.model-item{background:var(--bg-surface);border-radius:var(--radius-sm);padding:12px 14px;border:1px solid var(--border-default)}
+.model-item .model-label{font-size:10px;font-family:var(--font-mono);color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:4px}
+.model-item .model-value{font-size:13px;font-weight:600;color:var(--text-primary)}
+.model-item .model-sub{font-family:var(--font-mono);font-size:10px;color:var(--text-muted);margin-top:2px;word-break:break-all}
+.param-row{display:flex;justify-content:space-between;align-items:center;padding:8px 0;border-bottom:1px solid rgba(255,255,255,0.03);font-size:13px}
+.param-row:last-child{border-bottom:none}
+.param-row .param-label{color:var(--text-secondary)}
+.param-row .param-value{font-family:var(--font-mono);font-size:12px;color:var(--accent-steel);font-weight:500}
+.param-edit{display:flex;align-items:center;gap:8px}
+.param-edit input[type="range"]{-webkit-appearance:none;width:120px;height:4px;border-radius:2px;background:var(--border-active);outline:none}
+.param-edit input[type="range"]::-webkit-slider-thumb{-webkit-appearance:none;width:14px;height:14px;border-radius:50%;background:var(--accent-amber);cursor:pointer;border:2px solid var(--bg-root)}
+.param-edit .pe-val{font-family:var(--font-mono);font-size:12px;color:var(--accent-amber);min-width:45px;text-align:right}
+.param-edit input[type="number"]{width:70px;padding:6px 8px;background:var(--bg-root);border:1px solid var(--border-default);border-radius:var(--radius-sm);color:var(--text-primary);font-family:var(--font-mono);font-size:12px;outline:none;text-align:center}
+.param-edit input[type="number"]:focus{border-color:var(--accent-amber)}
+.config-section{margin-bottom:16px;padding-bottom:12px;border-bottom:1px solid var(--border-default)}
+.config-section:last-child{border-bottom:none;margin-bottom:0}
+.config-section h4{font-size:13px;font-weight:600;color:var(--text-secondary);margin-bottom:8px}
+.form-group{margin-bottom:8px}
+.form-group label{display:block;font-size:11px;font-weight:500;color:var(--text-muted);margin-bottom:4px;text-transform:uppercase;letter-spacing:0.05em}
+.form-group input,.form-group select{width:100%;padding:8px 10px;background:var(--bg-root);border:1px solid var(--border-default);border-radius:var(--radius-sm);color:var(--text-primary);font-family:var(--font-mono);font-size:12px;outline:none;transition:var(--transition-smooth)}
+.form-group input:focus,.form-group select:focus{border-color:var(--accent-amber);box-shadow:0 0 0 2px var(--accent-amber-dim)}
+.form-group .input-row{display:flex;gap:6px}
+.form-group .input-row input{flex:1}
+.form-group .toggle-vis{width:34px;flex-shrink:0;background:var(--bg-elevated);border:1px solid var(--border-default);border-radius:var(--radius-sm);color:var(--text-muted);cursor:pointer;font-family:var(--font-mono);font-size:11px;display:flex;align-items:center;justify-content:center;transition:var(--transition-smooth)}
+.form-group .toggle-vis:hover{border-color:var(--border-active);color:var(--text-secondary)}
+.config-readonly{font-family:var(--font-mono);font-size:11px;color:var(--text-muted);padding:4px 0}
+.sources-toggle{padding:8px 24px;font-size:11px;font-family:var(--font-mono);color:var(--text-muted);cursor:pointer;user-select:none;border-top:1px solid var(--border-default);background:var(--bg-surface);display:flex;align-items:center;gap:6px;transition:color var(--transition-smooth)}
+.sources-toggle:hover{color:var(--text-secondary)}
+.sources-content{background:var(--bg-elevated);border-top:1px solid var(--border-default);max-height:200px;overflow-y:auto;display:none;padding:12px 24px}
+.sources-content.open{display:block}
+.source-item{padding:8px 12px;border-left:2px solid var(--accent-steel);margin-bottom:8px;font-size:12px;background:var(--bg-surface);border-radius:0 var(--radius-sm) var(--radius-sm) 0}
+.source-item .src-header{display:flex;gap:12px;font-family:var(--font-mono);font-size:10px;color:var(--accent-amber);margin-bottom:4px}
+.source-item .src-excerpt{color:var(--text-secondary);font-size:12px;line-height:1.5}
+.typing-indicator{display:flex;gap:5px;padding:4px 0}
+.typing-indicator span{width:6px;height:6px;border-radius:50%;background:var(--text-muted);animation:typingBounce 1.2s ease-in-out infinite}
+.typing-indicator span:nth-child(2){animation-delay:0.15s}
+.typing-indicator span:nth-child(3){animation-delay:0.3s}
+@keyframes typingBounce{0%,60%,100%{transform:translateY(0);opacity:0.4}30%{transform:translateY(-6px);opacity:1}}
+::-webkit-scrollbar{width:5px}
+::-webkit-scrollbar-track{background:transparent}
+::-webkit-scrollbar-thumb{background:var(--border-active);border-radius:3px}
+::-webkit-scrollbar-thumb:hover{background:var(--text-muted)}
+.toast{position:fixed;bottom:24px;right:24px;background:var(--bg-overlay);border:1px solid var(--border-active);border-radius:var(--radius-md);padding:14px 20px;font-size:13px;z-index:100;opacity:0;transform:translateY(12px);transition:all 0.3s ease;pointer-events:none;max-width:360px}
+.toast.show{opacity:1;transform:translateY(0)}
+.toast.error{border-color:var(--accent-red)}
+.toast.success{border-color:var(--accent-green)}
+.progress-bar-wrap{height:3px;background:var(--border-default);border-radius:2px;margin-top:10px;overflow:hidden;display:none}
+.progress-bar-wrap.active{display:block}
+.progress-bar-fill{height:100%;background:linear-gradient(90deg,var(--accent-amber),#d4952a);border-radius:2px;width:0%;transition:width 0.3s ease}
+@media(max-width:860px){
+  #app{flex-direction:column}
+  #sidebar{width:100%;min-width:100%;max-height:40vh;border-right:none;border-bottom:1px solid var(--border-default)}
+  .doc-card{width:180px}
+  .model-stack{grid-template-columns:1fr}
+}
+</style>
+</head>
+<body>
+
+<div id="app">
+  <!-- ═══ SIDEBAR ═══ -->
+  <aside id="sidebar">
+    <div class="sidebar-brand">
+      <a class="logo" href="/"><div class="logo-icon">◈</div><div><h1>OCR RAG</h1><div class="subtitle">Intelligent Q&A System</div></div></a>
+    </div>
+    <div class="sidebar-section">
+      <div class="sidebar-section-header"><div class="dot"></div><span>Document Upload</span><span class="count-badge" id="queueCount">0</span></div>
+      <div class="upload-zone" id="uploadZone">
+        <div class="upload-icon">↓</div>
+        <div class="upload-text">Drop files here or click to browse</div>
+        <div class="upload-hint">PDF · PNG · JPG · BMP · TIF</div>
+      </div>
+      <input type="file" id="fileInput" accept=".pdf,.png,.jpg,.jpeg,.bmp,.tif,.tiff" multiple hidden>
+      <div class="file-queue" id="fileQueue"></div>
+      <button class="btn btn-primary" id="processBtn" disabled>→ Process Documents</button>
+      <div class="progress-bar-wrap" id="progressWrap"><div class="progress-bar-fill" id="progressFill"></div></div>
+      <div class="status-row">
+        <div class="status-dot idle" id="statusDot"></div>
+        <span id="statusText">Ready — upload files to begin</span>
+      </div>
+      <div class="process-log" id="processLog"></div>
+    </div>
+    <div class="sidebar-section" style="flex:1;overflow-y:auto" id="sidebarFileSection">
+      <div class="sidebar-section-header"><div class="dot"></div><span>Processed Files</span><span class="count-badge" id="sidebarPfCount">0</span></div>
+      <div id="sidebarFileList"><div class="sb-pf-empty">No files processed yet</div></div>
+    </div>
+  </aside>
+
+  <!-- ═══ MAIN ═══ -->
+  <main id="main">
+    <nav class="tab-nav">
+      <button class="tab-btn active" data-tab="chat">Chat</button>
+      <button class="tab-btn" data-tab="preview">Preview <span class="tab-badge" id="docTabBadge">0</span></button>
+      <button class="tab-btn" data-tab="status">System Status</button>
+    </nav>
+
+    <!-- Chat -->
+    <div class="tab-panel active" id="tab-chat">
+      <div id="chat-panel" class="active">
+        <div class="chat-messages" id="chatMessages">
+          <div class="chat-empty" id="chatEmpty">
+            <div class="empty-icon">◈</div>
+            <div class="empty-title">Ask questions about your documents</div>
+            <div class="empty-desc">Upload and process documents first, then ask questions. The AI will search through the documents to find relevant answers.</div>
+            <div class="quick-prompts">
+              <span class="quick-prompt" data-question="请对这份文档进行详细摘要，列出各章节的主要内容">Summary</span>
+              <span class="quick-prompt" data-question="文档中提到了哪些关键数据和重要信息？请分点列出">Key Data</span>
+              <span class="quick-prompt" data-question="文档中的表格包含了什么内容？请整理说明">Tables</span>
+              <span class="quick-prompt" data-question="文档的核心观点和结论是什么？">Core Ideas</span>
+            </div>
+          </div>
+        </div>
+        <div class="sources-toggle" id="sourcesToggle" style="display:none">↓ Sources &amp; References</div>
+        <div class="sources-content" id="sourcesContent"></div>
+        <div class="chat-input-area">
+          <div class="chat-input-row">
+            <textarea id="questionInput" placeholder="Ask a question about the documents..." rows="1"></textarea>
+            <button class="btn-send" id="sendBtn" disabled>↑</button>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Preview -->
+    <div class="tab-panel" id="tab-preview">
+      <div id="preview-panel">
+        <!-- Top: file card row -->
+        <div class="doc-cards-wrap" id="docCardsWrap">
+          <h3>Processed Files</h3>
+          <div class="doc-cards" id="docCards"></div>
+        </div>
+        <div class="doc-empty-state" id="docEmptyState">
+          <div class="de-icon">◈</div>
+          <div class="de-title">No documents processed yet</div>
+          <div class="de-desc">Upload and process files from the sidebar — they will appear here. Click on a file card to preview the original file and OCR result side by side.</div>
+        </div>
+        <!-- Split preview pane -->
+        <div class="pv-split-wrap" id="pvSplitWrap" style="display:none">
+          <div class="pv-split-header">
+            <span class="dph-title" id="dphTitle">—</span>
+            <span class="dph-meta" id="dphMeta"></span>
+          </div>
+          <div class="pv-split-body">
+            <div class="pv-left" id="pvOriginal">
+              <div class="pv-left-placeholder">Select a file to preview</div>
+            </div>
+            <div class="pv-divider"></div>
+            <div class="pv-right" id="pvOcrText">
+              <div class="pv-right-placeholder">OCR result will appear here</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Status -->
+    <div class="tab-panel" id="tab-status">
+      <div id="status-panel">
+        <div class="status-card"><h3>Model Stack</h3>
+          <div class="model-stack">
+            <div class="model-item"><div class="model-label">OCR Engine</div><div class="model-value" id="sOCRModel">—</div><div class="model-sub" id="sOCRBase">—</div></div>
+            <div class="model-item"><div class="model-label">Embedding</div><div class="model-value" id="sEmbedModel">—</div><div class="model-sub" id="sEmbedBase">—</div></div>
+            <div class="model-item"><div class="model-label">LLM</div><div class="model-value" id="sLLMModel">—</div><div class="model-sub" id="sLLMBase">—</div></div>
+            <div class="model-item"><div class="model-label">Vector DB</div><div class="model-value" id="sVectorDB">—</div></div>
+          </div>
+        </div>
+        <div class="status-card"><h3>Processing Parameters</h3>
+          <div class="param-row">
+            <span class="param-label">Chunk Size</span>
+            <div class="param-edit"><input type="range" id="sChunkSize" min="200" max="2000" value="800" step="50"><span class="pe-val" id="sChunkSizeVal">800</span><span style="font-size:10px;color:var(--text-muted)">chars</span></div>
+          </div>
+          <div class="param-row">
+            <span class="param-label">Overlap</span>
+            <div class="param-edit"><input type="range" id="sChunkOverlap" min="0" max="500" value="150" step="25"><span class="pe-val" id="sChunkOverlapVal">150</span><span style="font-size:10px;color:var(--text-muted)">chars</span></div>
+          </div>
+          <div class="param-row" style="margin-top:10px">
+            <span class="param-label">Retrieval Top-K</span>
+            <div class="param-edit"><input type="number" id="sRetrievalK" min="1" max="20" value="5"></div>
+          </div>
+          <button class="btn btn-primary btn-sm" onclick="saveProcessingParams()" style="margin-top:14px">Save Parameters</button>
+          <span id="paramsMsg" style="font-size:12px;margin-left:10px"></span>
+        </div>
+        <div class="status-card" id="configCard">
+          <h3><span>API Configuration</span><button class="btn btn-primary btn-sm sc-btn" id="editConfigBtn">Edit</button></h3>
+          <div id="configDisplay"><div id="configContent"></div></div>
+          <div id="configEdit" style="display:none">
+            <div class="config-section"><h4>OCR API</h4>
+              <div class="form-group"><label>Engine</label><select id="cfgOcrEngine"><option value="paddle">paddle (local)</option><option value="api">api (remote)</option></select></div>
+              <div class="form-group"><label>API Base URL</label><input id="cfgOcrBase" placeholder="http://127.0.0.1:8002/v1"></div>
+              <div class="form-group"><label>API Key</label><div class="input-row"><input id="cfgOcrKey" type="password" placeholder="not-needed"><button class="toggle-vis" onclick="togglePassword('cfgOcrKey',this)">👁</button></div></div>
+              <div class="form-group"><label>Model Name</label><input id="cfgOcrModel" placeholder="PaddleOCR-VL-1.5"></div>
+            </div>
+            <div class="config-section"><h4>Embedding API</h4>
+              <div class="form-group"><label>API Base URL</label><input id="cfgEmbedBase" placeholder="https://dashscope.aliyuncs.com/compatible-mode/v1"></div>
+              <div class="form-group"><label>API Key</label><div class="input-row"><input id="cfgEmbedKey" type="password" placeholder="sk-..."><button class="toggle-vis" onclick="togglePassword('cfgEmbedKey',this)">👁</button></div></div>
+              <div class="form-group"><label>Model Name</label><input id="cfgEmbedModel" placeholder="text-embedding-v4"></div>
+            </div>
+            <div class="config-section"><h4>LLM API</h4>
+              <div class="form-group"><label>API Base URL</label><input id="cfgLLMBase" placeholder="http://0.0.0.0:8013/v1"></div>
+              <div class="form-group"><label>API Key</label><div class="input-row"><input id="cfgLLMKey" type="password" placeholder="not-needed"><button class="toggle-vis" onclick="togglePassword('cfgLLMKey',this)">👁</button></div></div>
+              <div class="form-group"><label>Model Name</label><input id="cfgLLMModel" placeholder="Qwen/Qwen3-4B-Instruct-2507"></div>
+            </div>
+            <div style="display:flex;gap:8px;margin-top:12px"><button class="btn btn-primary btn-sm" onclick="saveConfig()">Save</button><button class="btn btn-sm" onclick="cancelConfigEdit()">Cancel</button></div>
+            <div id="configMsg" style="margin-top:8px;font-size:13px"></div>
+          </div>
+        </div>
+        <div class="status-card"><h3>Database</h3><div id="sDBStats">No documents indexed</div></div>
+      </div>
+    </div>
+  </main>
+</div>
+
+<div class="toast" id="toast"></div>
+
+<script>
+const $=s=>document.querySelector(s);
+const $$=s=>document.querySelectorAll(s);
+const state={files:[],ready:false,processing:false,fileList:[],selectedDoc:-1};
+
+const D={
+  uploadZone:$('#uploadZone'),fileInput:$('#fileInput'),fileQueue:$('#fileQueue'),
+  queueCount:$('#queueCount'),processBtn:$('#processBtn'),
+  progressWrap:$('#progressWrap'),progressFill:$('#progressFill'),
+  statusDot:$('#statusDot'),statusText:$('#statusText'),processLog:$('#processLog'),
+  chatMessages:$('#chatMessages'),chatEmpty:$('#chatEmpty'),
+  questionInput:$('#questionInput'),sendBtn:$('#sendBtn'),
+  sToggle:$('#sourcesToggle'),sContent:$('#sourcesContent'),
+  docCards:$('#docCards'),docCardsWrap:$('#docCardsWrap'),docEmptyState:$('#docEmptyState'),
+  pvSplitWrap:$('#pvSplitWrap'),pvOriginal:$('#pvOriginal'),pvOcrText:$('#pvOcrText'),
+  dphTitle:$('#dphTitle'),dphMeta:$('#dphMeta'),docTabBadge:$('#docTabBadge'),
+  toast:$('#toast'),
+};
+
+// ─── Toast ──────────────────────────────────────────────
+let tt;function showToast(m,t){clearTimeout(tt);D.toast.textContent=m;D.toast.className='toast '+t+' show';tt=setTimeout(()=>D.toast.classList.remove('show'),3500)}
+
+// ─── Log / Progress ��────────────────────────────────────
+function addLog(m){D.processLog.classList.add('visible');const d=document.createElement('div');d.className='log-entry';d.textContent='> '+m;D.processLog.appendChild(d);D.processLog.scrollTop=D.processLog.scrollHeight}
+function clearLog(){D.processLog.innerHTML='';D.processLog.classList.remove('visible')}
+function setProgress(p){D.progressFill.style.width=p+'%'}
+function showProgress(s){D.progressWrap.classList.toggle('active',s)}
+function setStatus(st,t){D.statusDot.className='status-dot '+st;D.statusText.textContent=t}
+
+// ─── File queue ─────────────────────────────────────────
+const VE=['.pdf','.png','.jpg','.jpeg','.bmp','.tif','.tiff'];
+function renderQueue(){
+  if(!state.files.length){D.fileQueue.innerHTML='';D.processBtn.disabled=true;D.processBtn.textContent='→ Process Documents';D.queueCount.textContent='0';setStatus('idle','Ready — upload files to begin');return}
+  D.fileQueue.innerHTML=state.files.map((f,i)=>`<div class="file-queue-item"><span class="fq-icon">${f.name.toLowerCase().endsWith('.pdf')?'📄':'🖼️'}</span><div class="fq-info"><div class="fq-name" title="${f.name}">${f.name}</div><div class="fq-meta">${(f.size/1024/1024).toFixed(1)} MB</div></div><button class="fq-remove" onclick="removeFile(${i})" title="Remove">×</button></div>`).join('');
+  D.processBtn.disabled=false;D.processBtn.textContent=`→ Process ${state.files.length} File${state.files.length>1?'s':''}`;
+  D.queueCount.textContent=state.files.length;setStatus('idle',`${state.files.length} file${state.files.length>1?'s':''} queued`);
+}
+function addFiles(a){for(const f of a){const e='.'+f.name.split('.').pop().toLowerCase();if(!VE.includes(e)){showToast('Skipped: '+f.name,'error');continue}if(state.files.some(x=>x.name===f.name&&x.size===f.size))continue;state.files.push(f)}renderQueue()}
+function removeFile(i){state.files.splice(i,1);renderQueue()}
+
+// ─── Upload events ──────────────────────────────────────
+D.uploadZone.addEventListener('click',()=>D.fileInput.click());
+D.uploadZone.addEventListener('dragover',e=>{e.preventDefault();D.uploadZone.classList.add('drag-over')});
+D.uploadZone.addEventListener('dragleave',()=>D.uploadZone.classList.remove('drag-over'));
+D.uploadZone.addEventListener('drop',e=>{e.preventDefault();D.uploadZone.classList.remove('drag-over');if(e.dataTransfer.files.length)addFiles(e.dataTransfer.files)});
+D.fileInput.addEventListener('change',()=>{if(D.fileInput.files.length){addFiles(D.fileInput.files);D.fileInput.value=''}});
+
+// ─── Process ────────────────────────────────────────────
+D.processBtn.addEventListener('click',async()=>{
+  if(!state.files.length||state.processing)return;
+  state.processing=true;D.processBtn.disabled=true;D.processBtn.textContent='Processing...';
+  clearLog();showProgress(true);setProgress(5);setStatus('processing','Processing documents...');
+  addLog(`Processing ${state.files.length} file(s)...`);
+  const fd=new FormData();state.files.forEach(f=>fd.append('files',f));
+  fd.append('chunk_size',$('#sChunkSize').value);fd.append('chunk_overlap',$('#sChunkOverlap').value);
+  const sim=setInterval(()=>{const w=parseFloat(D.progressFill.style.width)||5;setProgress(Math.min(w+(100-w)*0.15,92))},400);
+  try{
+    const r=await fetch('/api/upload',{method:'POST',body:fd});clearInterval(sim);setProgress(100);
+    if(!r.ok){const e=await r.json();throw new Error(e.detail||'Upload failed')}
+    const d=await r.json();state.ready=true;
+    if(d.results&&d.results.length){d.results.forEach(r=>addLog(`✓ ${r.name}: ${r.pages}p · ${r.chunks}c`));setStatus('ready',`${d.total} file(s) processed · Ready for Q&A`);showToast(d.total+' document(s) processed!','success')}
+    if(d.errors&&d.errors.length)d.errors.forEach(e=>addLog(`ERROR: ${e}`));
+    refreshFileList();refreshStatus();D.chatEmpty.style.display='none';D.sendBtn.disabled=false;D.questionInput.focus();
+    state.files=[];renderQueue();
+  }catch(e){clearInterval(sim);setProgress(0);setStatus('error','Processing failed');addLog(`ERROR: ${e.message}`);showToast(e.message,'error')}
+  finally{showProgress(false);state.processing=false;D.processBtn.textContent='→ Process Documents';D.processBtn.disabled=state.files.length===0}
+});
+
+// ─── Escape HTML ────────────────────────────────────────
+function esc(s){const d=document.createElement('div');d.textContent=s;return d.innerHTML}
+
+// ─── Documents tab — load preview ───────────────────────
+async function loadPreview(idx){
+  state.selectedDoc=idx;
+  const f=state.fileList[idx];if(!f)return;
+  // Highlight card & sidebar item
+  $$('.doc-card').forEach((c,i)=>c.classList.toggle('selected',i===idx));
+  $$('.sb-pf-item').forEach((c,i)=>c.classList.toggle('selected',i===idx));
+  // Show split view
+  D.pvSplitWrap.style.display='flex';D.docEmptyState.style.display='none';
+  D.dphTitle.textContent=f.name;D.dphMeta.textContent='';
+
+  // Left: original file
+  const isPdf=f.format==='.pdf';
+  D.pvOriginal.innerHTML=isPdf
+    ? `<iframe src="/api/file/${idx}"></iframe>`
+    : `<img src="/api/file/${idx}" alt="${f.name}">`;
+
+  // Right: loading
+  D.pvOcrText.innerHTML='<div style="text-align:center;color:var(--text-muted);padding:60px">Loading OCR result...</div>';
+
+  // Fetch OCR
+  try{
+    const r=await fetch('/api/preview/'+idx);
+    if(!r.ok){D.pvOcrText.innerHTML=`<div style="text-align:center;color:var(--accent-red);padding:60px">OCR text not available (${r.status})</div>`;return}
+    const d=await r.json();
+    if(d.success&&d.text){
+      const parts=d.text.split(/--- 第 (\d+) 页 ---/g);let h='';
+      for(let i=1;i<parts.length;i+=2)h+=`<div class="pv-page-header">Page ${parts[i]}</div><div>${esc(parts[i+1]||'')}</div>`;
+      if(!h&&d.text)h=`<div>${esc(d.text)}</div>`;
+      D.pvOcrText.innerHTML=h||'<div style="text-align:center;color:var(--text-muted);padding:60px">No text content</div>';
+      const pg=parts.length>>1;
+      D.dphMeta.textContent=`${pg} pages · ${d.text.length} chars`;
+    }else{D.pvOcrText.innerHTML='<div style="text-align:center;color:var(--text-muted);padding:60px">OCR result is empty</div>'}
+  }catch(e){D.pvOcrText.innerHTML=`<div style="text-align:center;color:var(--accent-red);padding:60px">Failed to load: ${e.message}</div>`}
+}
+
+// ─── Documents tab — file list ──────────────────────────
+async function refreshFileList(){
+  try{const r=await fetch('/api/status');const d=await r.json();state.fileList=d.files||[];
+    // Sidebar list
+    const sfl=$('#sidebarFileList');
+    const spc=$('#sidebarPfCount');
+    if(state.fileList.length){
+      sfl.innerHTML=state.fileList.map((f,i)=>`<div class="sb-pf-item${i===state.selectedDoc?' selected':''}" onclick="switchTab('preview');loadPreview(${i})"><span class="sb-icon">${f.format==='.pdf'?'📄':'🖼️'}</span><span class="sb-name" title="${f.name}">${f.name}</span><span class="sb-meta">${f.pages}p·${f.chunks}c</span><button class="sb-del" onclick="event.stopPropagation();deleteDoc(${i})" title="Remove">×</button></div>`).join('');
+      spc.textContent=state.fileList.length;
+    }else{
+      sfl.innerHTML='<div class="sb-pf-empty">No files processed yet</div>';
+      spc.textContent='0';
+    }
+    // Documents tab
+    if(state.fileList.length){
+      D.docCardsWrap.style.display='';D.docEmptyState.style.display='none';
+      D.docCards.innerHTML=state.fileList.map((f,i)=>`<div class="doc-card${i===state.selectedDoc?' selected':''}" onclick="loadPreview(${i})"><div class="dc-icon ${f.format==='.pdf'?'pdf':'img'}">${f.format==='.pdf'?'PDF':'IMG'}</div><div class="dc-name" title="${f.name}">${f.name}</div><div class="dc-stats"><span>📄 <span class="dc-val">${f.pages}</span>p</span><span>🧩 <span class="dc-val">${f.chunks}</span>c</span><span>💾 <span class="dc-val">${f.size_mb}</span>MB</span></div><button class="dc-delete" onclick="event.stopPropagation();deleteDoc(${i})" title="Remove">✕</button><div style="font-family:var(--font-mono);font-size:9px;color:var(--text-muted);margin-top:6px">${f.time}</div></div>`).join('');
+      if(state.selectedDoc>=0&&state.selectedDoc<state.fileList.length)D.pvSplitWrap.style.display='flex';
+    }else{
+      D.docCardsWrap.style.display='none';D.docCards.innerHTML='';D.docEmptyState.style.display='flex';
+      D.pvSplitWrap.style.display='none';state.selectedDoc=-1;
+    }
+    D.docTabBadge.textContent=state.fileList.length;
+  }catch(e){}
+}
+
+function switchTab(name){
+  $$('.tab-btn').forEach(x=>x.classList.remove('active'));
+  $$('.tab-panel').forEach(x=>x.classList.remove('active'));
+  const btn=document.querySelector(`[data-tab="${name}"]`);
+  if(btn)btn.classList.add('active');
+  const panel=$('#tab-'+name);
+  if(panel)panel.classList.add('active');
+  if(name==='status')refreshStatus();
+  if(name==='preview')refreshFileList();
+}
+
+async function deleteDoc(idx){
+  try{const r=await fetch('/api/files/'+idx,{method:'DELETE'});if(r.ok){if(state.selectedDoc===idx)state.selectedDoc=-1;refreshFileList();refreshStatus();showToast('File removed','success')}else showToast('Failed to remove','error')}catch(e){showToast(e.message,'error')}
+}
+
+// ─── Status ─────────────────────────────────────────────
+async function refreshStatus(){
+  try{const r=await fetch('/api/status');const d=await r.json();
+    if(d.ocr){$('#sOCRModel').textContent=d.ocr.model||'PaddleOCR-VL-1.5';$('#sOCRBase').textContent=d.ocr.api_base||(d.ocr.engine==='paddle'?'local':'')}
+    if(d.embedding){$('#sEmbedModel').textContent=d.embedding.model||'���';$('#sEmbedBase').textContent=d.embedding.api_base||''}
+    if(d.llm){$('#sLLMModel').textContent=d.llm.model||'—';$('#sLLMBase').textContent=d.llm.api_base||''}
+    if(d.vector_store)$('#sVectorDB').textContent=d.vector_store;
+    if(d.params){$('#sChunkSize').value=d.params.chunk_size;$('#sChunkSizeVal').textContent=d.params.chunk_size;$('#sChunkOverlap').value=d.params.chunk_overlap;$('#sChunkOverlapVal').textContent=d.params.chunk_overlap;$('#sRetrievalK').value=d.params.retrieval_top_k}
+    if(d.document_count!==undefined)$('#sDBStats').innerHTML=`<div class="param-row"><span class="param-label">Indexed Chunks</span><span class="param-value">${d.document_count}</span></div>`;
+    $('#configContent').innerHTML=`<div class="config-readonly">OCR: ${d.ocr.engine} | ${d.ocr.model||'—'} ${d.ocr.api_key?'| key: '+d.ocr.api_key:''}</div><div class="config-readonly">Embed: ${d.embedding.model} ${d.embedding.api_key?'| key: '+d.embedding.api_key:''}</div><div class="config-readonly">LLM: ${d.llm.model} ${d.llm.api_key?'| key: '+d.llm.api_key:''}</div>`;
+    const cr=await fetch('/api/config');const c=await cr.json();
+    if(c.ocr){$('#cfgOcrEngine').value=c.ocr.engine||'paddle';$('#cfgOcrBase').value=c.ocr.api_base||'';$('#cfgOcrKey').value=c.ocr.api_key||'';$('#cfgOcrModel').value=c.ocr.model_name||''}
+    if(c.embedding){$('#cfgEmbedBase').value=c.embedding.api_base||'';$('#cfgEmbedKey').value=c.embedding.api_key||'';$('#cfgEmbedModel').value=c.embedding.model_name||''}
+    if(c.llm){$('#cfgLLMBase').value=c.llm.api_base||'';$('#cfgLLMKey').value=c.llm.api_key||'';$('#cfgLLMModel').value=c.llm.model_name||''}
+  }catch(e){}
+}
+
+// ─── Params ─────────────────────────────────────────────
+$('#sChunkSize').addEventListener('input',()=>$('#sChunkSizeVal').textContent=$('#sChunkSize').value);
+$('#sChunkOverlap').addEventListener('input',()=>$('#sChunkOverlapVal').textContent=$('#sChunkOverlap').value);
+async function saveProcessingParams(){
+  const u={CHUNK_SIZE:$('#sChunkSize').value,CHUNK_OVERLAP:$('#sChunkOverlap').value,RETRIEVAL_TOP_K:$('#sRetrievalK').value};
+  try{const r=await fetch('/api/config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(u)});const d=await r.json();
+    if(d.success){$('#paramsMsg').innerHTML='<span style="color:var(--accent-green)">Saved</span>';setTimeout(()=>$('#paramsMsg').innerHTML='',2000)}else $('#paramsMsg').innerHTML='<span style="color:var(--accent-red)">Failed</span>';
+  }catch(e){$('#paramsMsg').innerHTML='<span style="color:var(--accent-red)">'+e.message+'</span>'}
+}
+
+// ─── Chat ───────────────────────────────────────────────
+function addMessage(role,content){D.chatEmpty.style.display='none';const d=document.createElement('div');d.className='message '+role;d.innerHTML=`<div class="msg-avatar">${role==='user'?'You':'AI'}</div><div class="msg-bubble">${fmt(content)}</div>`;D.chatMessages.appendChild(d);D.chatMessages.scrollTop=D.chatMessages.scrollHeight}
+function addTyping(){const d=document.createElement('div');d.className='message assistant';d.id='typingMsg';d.innerHTML='<div class="msg-avatar">AI</div><div class="msg-bubble"><div class="typing-indicator"><span></span><span></span><span></span></div></div>';D.chatMessages.appendChild(d);D.chatMessages.scrollTop=D.chatMessages.scrollHeight}
+function remTyping(){const e=document.getElementById('typingMsg');if(e)e.remove()}
+function fmt(t){if(!t)return'';let h=t.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/\*\*(.+?)\*\*/g,'<strong>$1</strong>').replace(/\*(.+?)\*/g,'<em>$1</em>').replace(/`([^`]+)`/g,'<code>$1</code>');return'<p>'+h.replace(/\n\n/g,'</p><p>').replace(/\n/g,'<br>')+'</p>'}
+async function sendQuestion(){
+  const q=D.questionInput.value.trim();if(!q||!state.ready)return;
+  D.questionInput.value='';D.sendBtn.disabled=true;D.questionInput.style.height='auto';
+  addMessage('user',q);addTyping();
+  try{const r=await fetch('/api/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({question:q})});if(!r.ok){const e=await r.json();throw new Error(e.detail||'Chat failed')}const d=await r.json();remTyping();addMessage('assistant',d.answer);
+    if(d.sources&&d.sources.length){const sh=d.sources.map(s=>`<div class="source-item"><div class="src-header"><span>#${s.rank}</span><span>${s.document||''}</span><span>Page ${s.page}</span><span>${s.content_type||''}</span></div><div class="src-excerpt">${esc((s.content||'').substring(0,200))}...</div></div>`).join('');D.sToggle.style.display='flex';D.sContent.innerHTML=sh}
+  }catch(e){remTyping();addMessage('assistant','Error: '+e.message);showToast(e.message,'error')}
+  finally{D.sendBtn.disabled=false;D.questionInput.focus()}
+}
+D.sendBtn.addEventListener('click',sendQuestion);
+D.questionInput.addEventListener('keydown',e=>{if(e.key==='Enter'&&!e.shiftKey){e.preventDefault();sendQuestion()}});
+D.questionInput.addEventListener('input',()=>{D.questionInput.style.height='auto';D.questionInput.style.height=Math.min(D.questionInput.scrollHeight,120)+'px'});
+document.addEventListener('click',e=>{if(e.target.classList.contains('quick-prompt')){D.questionInput.value=e.target.dataset.question;D.questionInput.focus();D.questionInput.style.height='auto';D.questionInput.style.height=Math.min(D.questionInput.scrollHeight,120)+'px'}});
+D.sToggle.addEventListener('click',()=>{D.sContent.classList.toggle('open');D.sToggle.textContent=D.sContent.classList.contains('open')?'↑ Hide Sources & References':'↓ Sources & References'});
+
+// ─── Tabs ───────────────────────────────────────────────
+$$('.tab-btn').forEach(b=>b.addEventListener('click',()=>{$$('.tab-btn').forEach(x=>x.classList.remove('active'));$$('.tab-panel').forEach(x=>x.classList.remove('active'));b.classList.add('active');const t=$('#tab-'+b.dataset.tab);if(t)t.classList.add('active');if(b.dataset.tab==='status')refreshStatus();if(b.dataset.tab==='preview')refreshFileList()}));
+
+// ─── Config ─────────────────────────────────────────────
+function togglePassword(id,btn){const i=document.getElementById(id);if(i.type==='password'){i.type='text';btn.textContent='—'}else{i.type='password';btn.textContent='👁'}}
+function toggleConfigEdit(){const d=$('#configDisplay'),e=$('#configEdit'),b=$('#editConfigBtn');if(e.style.display==='none'){d.style.display='none';e.style.display='block';b.textContent='Cancel';refreshStatus()}else cancelConfigEdit()}
+function cancelConfigEdit(){$('#configDisplay').style.display='block';$('#configEdit').style.display='none';$('#editConfigBtn').textContent='Edit';$('#configMsg').innerHTML=''}
+async function saveConfig(){const u={};u['OCR_ENGINE']=$('#cfgOcrEngine').value;u['OCR_API_BASE']=$('#cfgOcrBase').value;u['OCR_API_KEY']=$('#cfgOcrKey').value;u['OCR_API_MODEL']=$('#cfgOcrModel').value;u['EMBEDDING_API_BASE']=$('#cfgEmbedBase').value;u['EMBEDDING_API_KEY']=$('#cfgEmbedKey').value;u['EMBEDDING_MODEL_NAME']=$('#cfgEmbedModel').value;u['LLM_API_BASE']=$('#cfgLLMBase').value;u['LLM_API_KEY']=$('#cfgLLMKey').value;u['LLM_MODEL_NAME']=$('#cfgLLMModel').value;
+  try{const r=await fetch('/api/config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(u)});const d=await r.json();if(d.success){$('#configMsg').innerHTML='<span style="color:var(--accent-green)">Config saved. Restart to apply.</span>';setTimeout(()=>{cancelConfigEdit();refreshStatus()},1500)}else $('#configMsg').innerHTML='<span style="color:var(--accent-red)">Save failed</span>'}catch(e){$('#configMsg').innerHTML='<span style="color:var(--accent-red)">'+e.message+'</span>'}
+}
+document.getElementById('editConfigBtn').addEventListener('click',toggleConfigEdit);
+
+// ─── Clear chat ─────────────────────────────────────────
+async function clearChat(){try{await fetch('/api/chat',{method:'DELETE'})}catch(e){}D.chatMessages.innerHTML='';D.chatMessages.appendChild(D.chatEmpty);D.chatEmpty.style.display='flex';D.sToggle.style.display='none';D.sContent.innerHTML='';D.sContent.classList.remove('open');D.questionInput.value='';D.questionInput.focus()}
+document.addEventListener('keydown',e=>{if(e.ctrlKey&&e.shiftKey&&e.key==='K'){e.preventDefault();clearChat()}});
+D.chatMessages.addEventListener('contextmenu',e=>{e.preventDefault();if(confirm('Clear all chat history?'))clearChat()});
+
+// ─── Init ───────────────────────────────────────────────
+renderQueue();refreshStatus();refreshFileList();
+</script>
+</body>
+</html>

text_processor.py

@@ -0,0 +1,606 @@
+"""
+============================================================
+文本处理模块: Markdown 清洗 + 智能分割 (Chunking)
+============================================================
+适配 PaddleOCR-VL-1.5 输出的 Markdown 格式文本
+
+功能:
+  1. Markdown 文本清洗 (保留表格/公式结构)
+  2. 基于 LangChain 的语义感知分割
+  3. 表格/公式专项处理
+"""
+
+import re
+from typing import List, Optional, Callable
+
+from langchain_core.documents import Document
+
+from loguru import logger
+
+import config
+
+
+# ============================================================
+# 内置递归文本分割器 (替代 langchain_text_splitters)
+# ============================================================
+# 避免 langchain_text_splitters → sentence_transformers → transformers
+# 的传递依赖链在部分环境中导致的兼容性问题
+
+
+class RecursiveCharacterTextSplitter:
+    """
+    递归字符文本分割器
+
+    与 langchain_text_splitters.RecursiveCharacterTextSplitter 接口兼容,
+    按分隔符优先级逐级分割, 保持语义完整性。
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = 800,
+        chunk_overlap: int = 150,
+        separators: Optional[List[str]] = None,
+        add_start_index: bool = True,
+        length_function: Callable[[str], int] = len,
+        keep_separator: bool = True,
+        strip_whitespace: bool = True,
+    ):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.separators = separators or ["\n\n", "\n", "。", "！", "？", "；", ".", "!", "?", ";", " ", ""]
+        self.add_start_index = add_start_index
+        self.length_function = length_function
+        self.keep_separator = keep_separator
+        self.strip_whitespace = strip_whitespace
+
+    def split_documents(self, documents: List[Document]) -> List[Document]:
+        """分割 Document 列表"""
+        chunks = []
+        for doc in documents:
+            doc_chunks = self.split_text(doc.page_content, doc.metadata)
+            chunks.extend(doc_chunks)
+        return chunks
+
+    def split_text(self, text: str, metadata: Optional[dict] = None) -> List[Document]:
+        """分割单个文本, 返回 Document 列表"""
+        metadata = metadata or {}
+        splits = self._split(text, self.separators)
+        chunks = self._merge(splits)
+
+        docs = []
+        for i, chunk in enumerate(chunks):
+            chunk_meta = {**metadata}
+            if self.add_start_index:
+                chunk_meta["start_index"] = text.find(chunk) if chunk in text else 0
+            docs.append(Document(page_content=chunk, metadata=chunk_meta))
+        return docs
+
+    def create_documents(
+        self, texts: List[str], metadatas: Optional[List[dict]] = None
+    ) -> List[Document]:
+        """从文本列表创建 Document 列表"""
+        metadatas = metadatas or [{}] * len(texts)
+        docs = []
+        for text, meta in zip(texts, metadatas):
+            docs.extend(self.split_text(text, meta))
+        return docs
+
+    def _split(self, text: str, separators: List[str]) -> List[str]:
+        """递归分割"""
+        # 使用最合适的分隔符
+        sep = separators[-1]  # 默认用最后一个 (空字符串, 按字符分割)
+        for s in separators:
+            if s == "":
+                sep = s
+                break
+            if s in text:
+                sep = s
+                break
+
+        # 按分隔符分割
+        if sep == "":
+            # 按字符分割
+            splits = list(text)
+        else:
+            if self.keep_separator:
+                # 保留分隔符在片段末尾
+                parts = text.split(sep)
+                splits = []
+                for i, part in enumerate(parts):
+                    if i > 0:
+                        splits.append(sep + part)
+                    else:
+                        splits.append(part)
+            else:
+                splits = text.split(sep)
+
+        # 去除空白并过滤空字符串
+        if self.strip_whitespace:
+            splits = [s.strip() for s in splits]
+        splits = [s for s in splits if s]
+
+        # 递归处理超长片段
+        final_splits = []
+        for split in splits:
+            if self.length_function(split) <= self.chunk_size:
+                final_splits.append(split)
+            else:
+                # 片段仍超长, 用下一级分隔符递归分割
+                if len(separators) > 1:
+                    next_seps = separators[separators.index(sep) + 1 :]
+                    final_splits.extend(self._split(split, next_seps))
+                else:
+                    # 无法再分, 强制按字符切分
+                    forced = self._force_split(split)
+                    final_splits.extend(forced)
+
+        return final_splits
+
+    def _force_split(self, text: str) -> List[str]:
+        """强制按字符数切分 (兜底)"""
+        chunks = []
+        for i in range(0, len(text), self.chunk_size - self.chunk_overlap):
+            chunk = text[i : i + self.chunk_size]
+            if self.strip_whitespace:
+                chunk = chunk.strip()
+            if chunk:
+                chunks.append(chunk)
+        return chunks
+
+    def _merge(self, splits: List[str]) -> List[str]:
+        """合并短片段为 chunk_size 大小的块"""
+        if not splits:
+            return []
+
+        chunks = []
+        current = ""
+        current_len = 0
+
+        for split in splits:
+            split_len = self.length_function(split)
+
+            if current_len + split_len <= self.chunk_size:
+                if current:
+                    current += "\n\n" + split
+                    current_len += 2 + split_len
+                else:
+                    current = split
+                    current_len = split_len
+            else:
+                if current:
+                    chunks.append(current)
+                # 重叠: 保留前一块的尾部
+                if self.chunk_overlap > 0 and current:
+                    overlap_text = current[-self.chunk_overlap:]
+                    current = overlap_text + "\n\n" + split
+                    current_len = self.length_function(current)
+                else:
+                    current = split
+                    current_len = split_len
+
+        if current:
+            chunks.append(current)
+
+        return chunks
+
+
+# ============================================================
+# Markdown 文本清洗器
+# ============================================================
+
+class MarkdownTextCleaner:
+    """PaddleOCR-VL-1.5 Markdown 输出清洗"""
+
+    @staticmethod
+    def clean(text: str, preserve_structure: bool = True) -> str:
+        """
+        清洗 Markdown 文本
+        - 保留表格 (|...|) 和公式 ($...$ / $$...$$)
+        - 规范化空白和换行
+        - 移除 OCR 残留噪声
+        """
+        if not text:
+            return ""
+
+        cleaned = text.strip()
+
+        # 移除控制字符 (保留换行和制表符)
+        cleaned = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]', '', cleaned)
+
+        # 统一换行符
+        cleaned = cleaned.replace('\r\n', '\n').replace('\r', '\n')
+
+        # 规范化空白 (但不影响表格结构)
+        if preserve_structure:
+            # 保护表格行和代码块
+            lines = cleaned.split('\n')
+            cleaned_lines = []
+            in_table = False
+            in_code = False
+
+            for line in lines:
+                # 检测 Markdown 表格
+                if line.strip().startswith('|') and '|' in line.strip()[1:]:
+                    in_table = True
+                    cleaned_lines.append(line.rstrip())
+                elif in_table and re.match(r'^[\s\|:\-]+$', line):
+                    # 表格分隔行
+                    cleaned_lines.append(line.rstrip())
+                elif in_table and not line.strip().startswith('|'):
+                    in_table = False
+                    if line.strip():
+                        cleaned_lines.append(line.strip())
+                    elif cleaned_lines and cleaned_lines[-1] != '':
+                        cleaned_lines.append('')
+                elif line.strip().startswith('```'):
+                    in_code = not in_code
+                    cleaned_lines.append(line.rstrip())
+                elif in_code:
+                    cleaned_lines.append(line.rstrip())
+                else:
+                    # 普通行: 去除首尾空白, 合并多个空格
+                    stripped = re.sub(r' +', ' ', line.strip())
+                    if stripped:
+                        cleaned_lines.append(stripped)
+                    elif cleaned_lines and cleaned_lines[-1] != '':
+                        cleaned_lines.append('')
+
+            cleaned = '\n'.join(cleaned_lines)
+        else:
+            cleaned = re.sub(r' +', ' ', cleaned)
+            cleaned = re.sub(r' *\n *', '\n', cleaned)
+
+        # 压缩过多连续空行
+        cleaned = re.sub(r'\n{4,}', '\n\n\n', cleaned)
+
+        return cleaned.strip()
+
+    @staticmethod
+    def clean_documents(documents: List[Document]) -> List[Document]:
+        """批量清洗 Document 列表"""
+        cleaned_docs = []
+        for doc in documents:
+            original_len = len(doc.page_content)
+            cleaned_text = MarkdownTextCleaner.clean(doc.page_content)
+            cleaned_len = len(cleaned_text)
+
+            if cleaned_text:
+                cleaned_doc = Document(
+                    page_content=cleaned_text,
+                    metadata={
+                        **doc.metadata,
+                        "cleaned": True,
+                        "original_length": original_len,
+                        "cleaned_length": cleaned_len,
+                    },
+                )
+                cleaned_docs.append(cleaned_doc)
+            else:
+                logger.debug(
+                    f"页面 {doc.metadata.get('page', '?')} 清洗后为空, 已跳过"
+                )
+
+        logger.info(
+            f"文本清洗: {len(documents)} → {len(cleaned_docs)} 个文档 "
+            f"(移除 {len(documents) - len(cleaned_docs)} 个空白页)"
+        )
+        return cleaned_docs
+
+    @staticmethod
+    def extract_tables_as_chunks(documents: List[Document]) -> List[Document]:
+        """
+        将 Markdown 表格提取为独立的文本块
+        PaddleOCR-VL-1.5 已输出标准 Markdown 表格格式
+        """
+        table_docs = []
+        for doc in documents:
+            tables_html = doc.metadata.get("tables_html", [])
+            tables_md = doc.metadata.get("tables_markdown", [])
+
+            for i, (html, md) in enumerate(
+                zip(tables_html, tables_md or [""] * len(tables_html))
+            ):
+                content = md or html
+                if content.strip():
+                    table_doc = Document(
+                        page_content=f"[表格数据]\n{content}",
+                        metadata={
+                            **doc.metadata,
+                            "content_type": "table",
+                            "table_index": i,
+                            "table_html": html,
+                            "table_markdown": md,
+                        },
+                    )
+                    table_docs.append(table_doc)
+
+        if table_docs:
+            logger.info(f"提取了 {len(table_docs)} 个表格块")
+        return table_docs
+
+    @staticmethod
+    def extract_formulas_as_chunks(documents: List[Document]) -> List[Document]:
+        """将 LaTeX 公式提取为独立块"""
+        formula_docs = []
+        for doc in documents:
+            formulas_latex = doc.metadata.get("formulas_latex", [])
+            for i, latex in enumerate(formulas_latex):
+                if latex.strip():
+                    formula_doc = Document(
+                        page_content=f"[公式]\n$${latex}$$",
+                        metadata={
+                            **doc.metadata,
+                            "content_type": "formula",
+                            "formula_index": i,
+                            "formula_latex": latex,
+                        },
+                    )
+                    formula_docs.append(formula_doc)
+
+        if formula_docs:
+            logger.info(f"提取了 {len(formula_docs)} 个公式块")
+        return formula_docs
+
+
+# ============================================================
+# 智能文本分割器
+# ============================================================
+
+class DocumentSplitter:
+    """
+    文档智能分割器
+
+    针对 PaddleOCR-VL-1.5 的 Markdown 输出优化:
+      - 在 Markdown 标题处分段
+      - 保护表格完整性
+      - 保护代码块完整性
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = config.CHUNK_SIZE,
+        chunk_overlap: int = config.CHUNK_OVERLAP,
+        separators: Optional[List[str]] = None,
+    ):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.separators = separators or config.SEPARATORS
+
+        self._splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=self.separators,
+            add_start_index=True,
+            length_function=len,
+            keep_separator=True,
+            strip_whitespace=True,
+        )
+
+    def split_documents(self, documents: List[Document]) -> List[Document]:
+        """分割文档列表"""
+        if not documents:
+            return []
+
+        chunks = self._splitter.split_documents(documents)
+        logger.info(
+            f"文本分割: {len(documents)} → {len(chunks)} 个文本块 "
+            f"(块大小={self.chunk_size}, 重叠={self.chunk_overlap})"
+        )
+        return chunks
+
+    def split_text(self, text: str, metadata: Optional[dict] = None) -> List[Document]:
+        """分割单个文本"""
+        return self._splitter.create_documents(
+            [text], metadatas=[metadata or {}]
+        )
+
+
+class MarkdownAwareSplitter:
+    """
+    Markdown 感知分割器
+
+    在 Markdown 结构边界处分割:
+      - ## 标题 → 新段
+      - 表格 → 保持完整
+      - 代码块 → 保持完整
+    """
+
+    def __init__(
+        self,
+        target_chunk_size: int = config.CHUNK_SIZE,
+        min_chunk_size: int = 100,
+    ):
+        self.target_chunk_size = target_chunk_size
+        self.min_chunk_size = min_chunk_size
+
+    def split_documents(self, documents: List[Document]) -> List[Document]:
+        """基于 Markdown 结构分割"""
+        all_chunks = []
+
+        for doc in documents:
+            sections = self._split_by_headers(doc.page_content)
+            chunks = self._merge_sections(
+                sections, doc.metadata, self.target_chunk_size, self.min_chunk_size
+            )
+            all_chunks.extend(chunks)
+
+        logger.info(
+            f"Markdown 感知分割: {len(documents)} → {len(all_chunks)} 个文本块"
+        )
+        return all_chunks
+
+    @staticmethod
+    def _split_by_headers(text: str) -> List[str]:
+        """
+        按 Markdown 标题 (# ## ###) 和段落分割
+        保护表格和代码块完整性
+        """
+        # 先在代码块和表格处做保护标记
+        protected = []
+        protection_map = {}
+
+        def protect(match):
+            key = f"__PROTECTED_{len(protected)}__"
+            protected.append(match.group(0))
+            protection_map[key] = match.group(0)
+            return key
+
+        # 保护代码块
+        text = re.sub(r'```[\s\S]*?```', protect, text)
+        # 保护表格 (连续的 | 行)
+        text = re.sub(
+            r'(?:^\|.+\|\n)+(?:^\|[\s\-:]+\|\n)?(?:^\|.+\|\n?)+',
+            protect,
+            text,
+            flags=re.MULTILINE,
+        )
+
+        # 按 Markdown 标题分割
+        raw_sections = re.split(r'\n(?=#{1,3}\s)', text)
+
+        # 恢复保护的内容
+        sections = []
+        for section in raw_sections:
+            for key, original in protection_map.items():
+                section = section.replace(key, original)
+            section = section.strip()
+            if section:
+                sections.append(section)
+
+        return sections
+
+    @staticmethod
+    def _merge_sections(
+        sections: List[str],
+        base_metadata: dict,
+        target_size: int,
+        min_size: int,
+    ) -> List[Document]:
+        """将段落合并为目标大小的块"""
+        chunks = []
+        current = ""
+        start_idx = 0
+
+        for i, section in enumerate(sections):
+            if not current:
+                current = section
+                start_idx = i
+            elif len(current) + len(section) + 2 <= target_size:
+                current += "\n\n" + section
+            else:
+                if len(current) >= min_size:
+                    meta = {
+                        **base_metadata,
+                        "chunk_sections": f"{start_idx}-{i - 1}",
+                        "chunk_type": "markdown_semantic",
+                    }
+                    chunks.append(Document(page_content=current, metadata=meta))
+                current = section
+                start_idx = i
+
+        # 最后一个块
+        if current and len(current) >= min_size:
+            meta = {
+                **base_metadata,
+                "chunk_sections": f"{start_idx}-{len(sections) - 1}",
+                "chunk_type": "markdown_semantic",
+            }
+            chunks.append(Document(page_content=current, metadata=meta))
+        elif current and chunks:
+            chunks[-1].page_content += "\n\n" + current
+
+        return chunks
+
+
+# ============================================================
+# 完整处理流水线
+# ============================================================
+
+class TextProcessingPipeline:
+    """
+    文本处理流水线
+
+    用法:
+        pipeline = TextProcessingPipeline()
+        chunks = pipeline.process(raw_documents)
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = config.CHUNK_SIZE,
+        chunk_overlap: int = config.CHUNK_OVERLAP,
+        split_method: str = "recursive",
+        extract_tables: bool = True,
+        extract_formulas: bool = False,
+        clean_text: bool = True,
+    ):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.split_method = split_method
+        self.extract_tables = extract_tables
+        self.extract_formulas = extract_formulas
+        self.clean_text = clean_text
+
+        if split_method == "markdown":
+            self.splitter = MarkdownAwareSplitter(
+                target_chunk_size=chunk_size,
+                min_chunk_size=max(50, chunk_size // 4),
+            )
+        else:
+            self.splitter = DocumentSplitter(
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+            )
+
+    def process(self, documents: List[Document]) -> List[Document]:
+        """
+        完整处理流水线:
+          原始文档 → 清洗 → 提取表格/公式 → 分割 → 最终块
+        """
+        docs = list(documents)
+        logger.info(f"文本处理流水线启动: {len(docs)} 个原始文档")
+
+        # Step 1: 文本清洗
+        if self.clean_text:
+            docs = MarkdownTextCleaner.clean_documents(docs)
+
+        # Step 2: 提取表格和公式为独立块
+        extra_docs = []
+        if self.extract_tables:
+            extra_docs.extend(MarkdownTextCleaner.extract_tables_as_chunks(docs))
+        if self.extract_formulas:
+            extra_docs.extend(MarkdownTextCleaner.extract_formulas_as_chunks(docs))
+
+        # Step 3: 分割
+        chunks = self.splitter.split_documents(docs)
+
+        # Step 4: 合并特殊内容块
+        if extra_docs:
+            chunks.extend(extra_docs)
+            logger.info(f"合并特殊块后总计: {len(chunks)} 个文本块")
+
+        # Step 5: 添加块 ID
+        for i, chunk in enumerate(chunks):
+            chunk.metadata["chunk_id"] = f"chunk_{i:06d}"
+
+        logger.info(f"文本处理完成: {len(documents)} 页 → {len(chunks)} 个文本块")
+        return chunks
+
+
+# ============================================================
+# 便捷函数
+# ============================================================
+
+def process_documents(
+    documents: List[Document],
+    chunk_size: int = config.CHUNK_SIZE,
+    chunk_overlap: int = config.CHUNK_OVERLAP,
+    **kwargs,
+) -> List[Document]:
+    """便捷函数: 一键文本处理"""
+    pipeline = TextProcessingPipeline(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        **kwargs,
+    )
+    return pipeline.process(documents)

vector_store.py

@@ -0,0 +1,307 @@
+"""
+============================================================
+向量数据库存储模块
+============================================================
+嵌入模型: Qwen3-Embedding 系列
+向量数据库: Chroma / FAISS
+
+功能:
+  1. 文档批量向量化入库
+  2. 相似度检索 / MMR / 元数据过滤
+  3. 持久化与增量更新
+"""
+
+from pathlib import Path
+from typing import List, Optional, Dict, Any, Callable
+
+from langchain_core.documents import Document
+from langchain_core.embeddings import Embeddings
+from langchain_core.vectorstores import VectorStore
+
+from langchain_community.vectorstores import Chroma, FAISS
+
+from loguru import logger
+
+import config
+from embeddings import get_embedding_model
+
+
+# ============================================================
+# 向量数据库工厂
+# ============================================================
+
+class VectorStoreFactory:
+
+    @staticmethod
+    def create_chroma(
+        persist_directory: Optional[str | Path] = None,
+        collection_name: str = config.CHROMA_COLLECTION_NAME,
+        embedding_function: Optional[Embeddings] = None,
+    ) -> Chroma:
+        persist_dir = str(persist_directory or config.VECTOR_DB_DIR / "chroma")
+        embedding = embedding_function or get_embedding_model()
+
+        logger.info(f"创建 Chroma 向量数据库: {persist_dir} (集合: {collection_name})")
+
+        return Chroma(
+            collection_name=collection_name,
+            embedding_function=embedding,
+            persist_directory=persist_dir,
+            collection_metadata={
+                "hnsw:space": "cosine",  # Qwen3-Embedding 使用余弦相似度
+                "hnsw:construction_ef": 200,
+                "hnsw:M": 48,
+            },
+        )
+
+    @staticmethod
+    def create_faiss(
+        embedding_function: Optional[Embeddings] = None,
+    ) -> FAISS:
+        embedding = embedding_function or get_embedding_model()
+        logger.info("创建 FAISS 向量数据库 (flat L2 index)")
+        # FAISS.from_documents 会创建合适的索引
+        return FAISS(
+            embedding_function=embedding,
+            index=None,
+            docstore=None,
+            index_to_docstore_id={},
+        )
+
+    @staticmethod
+    def create(store_type: Optional[str] = None, **kwargs) -> VectorStore:
+        store_type = store_type or config.VECTOR_STORE_TYPE
+        if store_type == "chroma":
+            return VectorStoreFactory.create_chroma(**kwargs)
+        elif store_type == "faiss":
+            return VectorStoreFactory.create_faiss(**kwargs)
+        else:
+            raise ValueError(f"不支持的向量数据库: {store_type}. 可选: chroma, faiss")
+
+
+# ============================================================
+# 向量数据库管理器
+# ============================================================
+
+class VectorStoreManager:
+
+    def __init__(
+        self,
+        vector_store: Optional[VectorStore] = None,
+        store_type: Optional[str] = None,
+        embedding_function: Optional[Embeddings] = None,
+        persist_directory: Optional[str | Path] = None,
+    ):
+        self.store_type = store_type or config.VECTOR_STORE_TYPE
+        self.embedding_function = embedding_function or get_embedding_model()
+        self.persist_directory = str(persist_directory or config.VECTOR_DB_DIR)
+        self._store = vector_store or self._init_store()
+
+    def _init_store(self) -> VectorStore:
+        if self.store_type == "chroma":
+            return self._init_chroma()
+        elif self.store_type == "faiss":
+            return self._init_faiss()
+        else:
+            raise ValueError(f"不支持的向量数据库: {self.store_type}")
+
+    def _init_chroma(self) -> Chroma:
+        persist_dir = Path(self.persist_directory) / "chroma"
+        if persist_dir.exists() and any(persist_dir.iterdir()):
+            logger.info(f"加载已有 Chroma 数据库: {persist_dir}")
+            return Chroma(
+                persist_directory=str(persist_dir),
+                embedding_function=self.embedding_function,
+                collection_name=config.CHROMA_COLLECTION_NAME,
+            )
+        return VectorStoreFactory.create_chroma(
+            persist_directory=str(persist_dir),
+            embedding_function=self.embedding_function,
+        )
+
+    def _init_faiss(self) -> FAISS:
+        index_path = Path(self.persist_directory) / "faiss_index"
+        if index_path.exists():
+            logger.info(f"加载已有 FAISS 数据库: {index_path}")
+            return FAISS.load_local(
+                str(index_path),
+                self.embedding_function,
+                allow_dangerous_deserialization=True,
+            )
+        return VectorStoreFactory.create_faiss(
+            embedding_function=self.embedding_function,
+        )
+
+    @property
+    def store(self) -> VectorStore:
+        return self._store
+
+    # ---- 入库 ----
+
+    def add_documents(
+        self,
+        documents: List[Document],
+        batch_size: int = 50,
+        progress_callback: Optional[Callable[[int, int], None]] = None,
+    ) -> int:
+        if not documents:
+            logger.warning("文档列表为空, 跳过入库")
+            return 0
+
+        total = len(documents)
+        logger.info(f"开始向量化入库: {total} 个文档块 (批大小={batch_size})")
+
+        for i in range(0, total, batch_size):
+            batch = documents[i : i + batch_size]
+            self._store.add_documents(batch)
+            if progress_callback:
+                progress_callback(min(i + batch_size, total), total)
+
+        self._persist()
+        logger.info(f"向量化入库完成: {total} 个文档块")
+        return total
+
+    def add_texts(
+        self,
+        texts: List[str],
+        metadatas: Optional[List[dict]] = None,
+        batch_size: int = 50,
+    ) -> List[str]:
+        if not texts:
+            return []
+        all_ids = []
+        for i in range(0, len(texts), batch_size):
+            batch_texts = texts[i : i + batch_size]
+            batch_metas = metadatas[i : i + batch_size] if metadatas else None
+            ids = self._store.add_texts(batch_texts, batch_metas)
+            all_ids.extend(ids)
+        self._persist()
+        return all_ids
+
+    # ---- 检索 ----
+
+    def similarity_search(
+        self,
+        query: str,
+        k: int = config.RETRIEVAL_TOP_K,
+        filter: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> List[Document]:
+        if filter and isinstance(self._store, Chroma):
+            kwargs["filter"] = filter
+        return self._store.similarity_search(query, k=k, **kwargs)
+
+    def similarity_search_with_score(
+        self,
+        query: str,
+        k: int = config.RETRIEVAL_TOP_K,
+        filter: Optional[Dict[str, Any]] = None,
+        score_threshold: float = 0.3,
+        **kwargs,
+    ) -> List[tuple]:
+        if filter and isinstance(self._store, Chroma):
+            kwargs["filter"] = filter
+        raw = self._store.similarity_search_with_relevance_scores(
+            query, k=k, **kwargs
+        )
+        # Qwen3-Embedding 余弦相似度通常 > 0.5 为相关
+        return [(doc, score) for doc, score in raw if score >= score_threshold]
+
+    def max_marginal_relevance_search(
+        self,
+        query: str,
+        k: int = config.RETRIEVAL_TOP_K,
+        fetch_k: int = 20,
+        lambda_mult: float = 0.5,
+        filter: Optional[Dict[str, Any]] = None,
+    ) -> List[Document]:
+        if filter and isinstance(self._store, Chroma):
+            return self._store.max_marginal_relevance_search(
+                query, k=k, fetch_k=fetch_k, lambda_mult=lambda_mult, filter=filter,
+            )
+        return self._store.max_marginal_relevance_search(
+            query, k=k, fetch_k=fetch_k, lambda_mult=lambda_mult,
+        )
+
+    # ---- 过滤查询 ----
+
+    def search_by_document(
+        self, query: str, document_name: str, k: int = config.RETRIEVAL_TOP_K
+    ) -> List[Document]:
+        return self.similarity_search(query, k=k, filter={"document_name": document_name})
+
+    def search_by_page_range(
+        self, query: str, start_page: int, end_page: int,
+        k: int = config.RETRIEVAL_TOP_K,
+    ) -> List[Document]:
+        return self.similarity_search(
+            query, k=k, filter={"page": {"$gte": start_page, "$lte": end_page}}
+        )
+
+    # ---- 管理 ----
+
+    def _persist(self):
+        if self.store_type == "faiss":
+            index_path = Path(self.persist_directory) / "faiss_index"
+            index_path.mkdir(parents=True, exist_ok=True)
+            self._store.save_local(str(index_path))
+
+    def clear(self):
+        if self.store_type == "chroma":
+            self._store.delete_collection()
+            self._store = VectorStoreFactory.create_chroma(
+                persist_directory=Path(self.persist_directory) / "chroma",
+                embedding_function=self.embedding_function,
+            )
+        elif self.store_type == "faiss":
+            self._store = VectorStoreFactory.create_faiss(
+                embedding_function=self.embedding_function,
+            )
+        logger.info("向量数据库已清空")
+
+    def get_document_count(self) -> int:
+        try:
+            if self.store_type == "chroma":
+                return self._store._collection.count()
+            elif self.store_type == "faiss":
+                return self._store.index.ntotal if self._store.index else 0
+        except Exception:
+            return 0
+
+    def get_stats(self) -> Dict[str, Any]:
+        return {
+            "store_type": self.store_type,
+            "persist_directory": self.persist_directory,
+            "document_count": self.get_document_count(),
+            "embedding_model": config.EMBEDDING_MODEL_NAME,
+        }
+
+
+# ============================================================
+# 便捷函数
+# ============================================================
+
+def build_vector_store(
+    documents: List[Document],
+    store_type: Optional[str] = None,
+    embedding_model: Optional[Embeddings] = None,
+    clear_existing: bool = False,
+) -> VectorStoreManager:
+    manager = VectorStoreManager(
+        store_type=store_type,
+        embedding_function=embedding_model,
+    )
+    if clear_existing:
+        manager.clear()
+    manager.add_documents(documents)
+    return manager
+
+
+def load_vector_store(
+    store_type: Optional[str] = None,
+    embedding_model: Optional[Embeddings] = None,
+) -> VectorStoreManager:
+    return VectorStoreManager(
+        store_type=store_type,
+        embedding_function=embedding_model,
+    )

国药准字H37020386_布洛芬片.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:22954cb51781e685a42d5dd1abac0bde98906af75a6097871e3a937bdeaa4cdf
+size 125946