Metadata-Version: 2.4
Name: modular-rag
Version: 0.1.1
Summary: 可扩展、可替换抽象的 RAG 库：多格式读取、结构化切分、RRF 混合召回、主表+附表多版本、回调与中间件
Author: ragkit contributors
License-Expression: MIT
Keywords: rag,retrieval,vector-database,embeddings,rrf,chunking,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.23; extra == "pdf"
Provides-Extra: word
Requires-Dist: python-docx>=1.0; extra == "word"
Provides-Extra: ppt
Requires-Dist: python-pptx>=0.6; extra == "ppt"
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"
Provides-Extra: rtf
Requires-Dist: striprtf>=0.0.26; extra == "rtf"
Provides-Extra: rerank
Requires-Dist: sentence-transformers>=2.2; extra == "rerank"
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.7; extra == "qdrant"
Provides-Extra: weaviate
Requires-Dist: weaviate-client>=4.4; extra == "weaviate"
Provides-Extra: office
Requires-Dist: python-docx>=1.0; extra == "office"
Requires-Dist: python-pptx>=0.6; extra == "office"
Requires-Dist: openpyxl>=3.1; extra == "office"
Provides-Extra: all
Requires-Dist: pymupdf>=1.23; extra == "all"
Requires-Dist: python-docx>=1.0; extra == "all"
Requires-Dist: python-pptx>=0.6; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: striprtf>=0.0.26; extra == "all"
Requires-Dist: sentence-transformers>=2.2; extra == "all"
Requires-Dist: qdrant-client>=1.7; extra == "all"
Requires-Dist: weaviate-client>=4.4; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# ragkit

一个**可扩展、可替换抽象**的 RAG 库。核心零第三方依赖即可运行，PDF / 模型重排等重依赖按需安装、延迟导入。

```python
from ragkit import RAGPipeline, PipelineConfig

pipe = RAGPipeline(PipelineConfig())
pipe.ingest("docs/guide.md")
for r in pipe.retrieve("超时设置默认值是多少？"):
    print(r.rank, r.score, r.chunk.title_path, r.chunk.text[:60])
```

---

## 目录

- [特性](#特性)
- [安装](#安装)
- [快速开始](#快速开始)
- [核心概念](#核心概念)
- [使用指南](#使用指南)
  - [1. 数据读取](#1-数据读取)
  - [2. 切分](#2-切分)
  - [3. 嵌入与向量库](#3-嵌入与向量库)
  - [4. 召回](#4-召回)
  - [5. 重排](#5-重排)
  - [6. 主表 + 附表（多版本）](#6-主表--附表多版本)
  - [7. 版本与权限](#7-版本与权限)
  - [8. 回调与进度](#8-回调与进度)
  - [9. 中间件](#9-中间件)
  - [10. 日志](#10-日志)
  - [11. 召回测试台（可视化前端）](#11-召回测试台可视化前端)
  - [12. 文档入库页（同界面 Tab）](#12-文档入库页同界面-tab)
- [扩展指南](#扩展指南)
  - [扩展点地图](#扩展点地图)
  - [1. 注册式扩展：读取器 / 切分器 / 嵌入 / 重排](#1-注册式扩展读取器--切分器--嵌入--重排)
  - [2. 构造注入：向量库 / 召回 / 主表 / 附表](#2-构造注入向量库--召回--主表--附表)
  - [3. 自定义表记录（扩展列）](#3-自定义表记录扩展列)
  - [4. 中间件：横切逻辑](#4-中间件横切逻辑)
  - [5. 回调与事件](#5-回调与事件)
  - [扩展时的通用约束](#扩展时的通用约束)
- [配置参考](#配置参考)
- [目录结构](#目录结构)
- [测试](#测试)
- [注意事项](#注意事项)

---

## 特性

| 能力 | 说明 |
|---|---|
| **多格式读取** | Markdown / PDF / Word / PPT / Excel / CSV / HTML / EPUB / RTF / JSON，全部走基类扩展 |
| **结构化切分** | 递归 / 标题层级（保留完整路径）/ 表格（表头+行）/ 问答对；块长与重叠可配 |
| **自己实现的 RRF** | 多路召回融合，公式 `Σ wᵢ/(k+rankᵢ)`，不依赖向量库 |
| **可配置召回** | 默认混合（向量 + 关键词），可切单路；权重、候选数、top_k 可调 |
| **多方式重排** | 规则 / CrossEncoder / LLM，统一超时兜底 |
| **主表 + 附表** | 文件级与分段级两张表，同业务 id 多版本自动取最高版本 |
| **三套向量库** | 内存 / Qdrant / Weaviate，同一接口互换 |
| **可观测** | 生命周期事件、实时进度、错误上报、指标、审计、告警 |
| **可干预** | 中间件可改 query、调参数、过滤结果、短路、重试、熔断 |
| **零依赖可跑** | 核心仅标准库；重依赖延迟导入并给出明确安装提示 |

---

## 安装

```bash
# 从 PyPI（包名 modular-rag，import 名仍是 ragkit）
pip install modular-rag
pip install "modular-rag[all]"  # 含全部可选依赖

# 本地开发（可编辑安装）
pip install -e .
pip install -e ".[dev]"       # 含 pytest / build / twine

# 从源码构建并安装
python -m build               # 产出 dist/modular_rag-0.1.1-py3-none-any.whl 与 .tar.gz
pip install dist/modular_rag-0.1.1-py3-none-any.whl
```

**可选依赖分组**：`pdf` / `word` / `ppt` / `excel` / `office` / `rtf` / `rerank` / `qdrant` / `weaviate` / `all` / `dev`。

也可以单独安装：

```bash
pip install pymupdf          # PDF（去页眉页脚/目录、表格、扫描件）
pip install python-docx      # Word .docx
pip install python-pptx      # PowerPoint
pip install openpyxl         # Excel
pip install sentence-transformers   # CrossEncoder 重排
pip install qdrant-client    # Qdrant 后端
pip install weaviate-client  # Weaviate 后端
pip install striprtf         # 更完整的 RTF 解析（可选）
```

> 不装任何可选依赖也能跑通核心流程：读取 txt/md/json/csv/html/epub、切分、内存向量库、混合召回、规则重排。

> OCR 不内置，通过 `ocr_fn(page_index, png_bytes) -> str` 钩子注入，可接 pytesseract。

---

## 快速开始

```python
from ragkit import RAGPipeline, PipelineConfig, SplitConfig, RetrievalConfig

pipe = RAGPipeline(PipelineConfig(
    split=SplitConfig(chunk_size=800, chunk_overlap=120),
    retrieval=RetrievalConfig(mode="hybrid", top_k=10),
))

pipe.ingest("docs/")                       # 目录、文件、Document 列表都支持
results = pipe.retrieve("超时默认值")
```

一次入库多种来源：

```python
pipe.ingest(["a.md", "b.pdf", "c.docx"])
pipe.ingest(Document(text="# 标题\n\n内容", metadata={"filter": {"doc_type": "markdown"}}))
```

---

## 核心概念

**数据流**

```
原始文件 → Reader → Document → Splitter → Chunk → Embedder → VectorStore
                                                              ↓
查询文本 → Retriever（向量 + 关键词）→ RRF 融合 → Reranker → 结果
```

**元数据四类**（贯穿全库）

| 类别 | 字段 |
|---|---|
| `locator` 定位 | `doc_id` / `title_path` / `section` / `page_no` / `chunk_index` / `prev_chunk_id` / `next_chunk_id` |
| `filter` 过滤 | `business_id` / `version` / `status` / `owner` / `md5` / `doc_type` / `language` / `acl` |
| `evidence` 证据链 | `model_id` / `dimension` / `normalization` / `chunk_params` / `imported_at` |
| `provenance` 溯源 | `source_uri` / `parse_flags` / `front_matter` |

**这些字段由谁填？** 骨架全部由库自动创建和填充，使用者只需提供业务字段：

| 字段 | 谁填 | 何时 |
|---|---|---|
| `metadata` 四类骨架 | 库 | `Document` 创建时初始化 |
| `title_path` / `chunk_index` / 邻接 | Splitter | 切分时 |
| `page_no` | Reader（PDF/PPT） | 解析时 |
| `doc_type` | Reader 路由 | 读取时 |
| `source_uri` / `parse_flags` / `front_matter` | Reader | 解析时 |
| `model_id` / `dimension` / `normalization` / `chunk_params` / `imported_at` | Pipeline | 入库时 |
| `business_id` / `version` / `status` / `owner` / `md5` | 主表 `FileRecord` | 传 `record=` 时（`md5` 未传则自动计算） |
| **自定义扩展字段** | **使用者** | 见下 |

**扩展字段怎么赋值**

方式一：通过主表记录（推荐，随版本管理）

```python
@dataclass
class MyFileRecord(FileRecord):
    department: str = ""

pipe.ingest(path, record=MyFileRecord("guide", "v1", department="研发"))

# 或者动态挂
rec = FileRecord("guide", "v1")
rec.set_extra("tenant", "acme")
pipe.ingest(path, record=rec)
```

方式二：`ingest(metadata=...)`，不必构造 Document（适合批量场景）

```python
pipe.ingest(path, metadata={"department": "研发", "tenant": "acme"})
```

- 传入的**普通键**自动写入 `filter`，可直接参与前置过滤
- 传入 `locator` / `filter` / `evidence` / `provenance` 子字典则按键合并，不覆盖其它字段
- 优先级最高，可覆盖框架默认值（如自定义 `page_no`）

方式三：构造 `Document` 时直接写 metadata（适合自定义 Reader）

```python
Document(text=..., metadata={"filter": {"department": "研发", "acl": []}})
```

三种方式最终都落到同一处：`chunk.metadata["filter"]`，因此都能用于检索过滤：

```python
pipe.retrieve("超时", filter_fn=lambda m: m["filter"].get("department") == "研发")
```

落库时，非标准键会自动收进 `ChunkRecord.extra`，取回时再合并回 filter，不丢字段。

**三条扩展路径**

| 方式 | 适用 | 特点 |
|---|---|---|
| 注册表 | 新增内置没有的实现 | `@READERS.register("xxx")`，可按名创建 |
| 构造注入 | 局部替换某个实现 | `RAGPipeline(reader=MyReader())`，不影响全局 |
| 中间件 | 干预流程 | 改参数、拦结果、短路、重试 |

---

## 使用指南

### 1. 数据读取

| 格式 | 后缀 | 依赖 | 说明 |
|---|---|---|---|
| 纯文本 | `.txt` `.log` | 无 | 直接读取 |
| Markdown | `.md` `.markdown` | 无 | front matter→元数据；代码块/表格原子切分 |
| JSON 问答 | `.json` `.jsonl` | 无 | `q/a` 或 `question/answer` |
| CSV / TSV | `.csv` `.tsv` | 无 | 转 Markdown 表格 |
| HTML | `.html` `.htm` | 无 | 提取正文，`h1-h6`→标题，忽略 script/style |
| EPUB | `.epub` | 无 | 每章一个 Document |
| RTF | `.rtf` | 可选 striprtf | 无依赖时内置正则兜底 |
| PDF | `.pdf` | pymupdf | 去页眉页脚/目录、表格提取、扫描件 OCR 钩子 |
| Word | `.docx` `.docm` | python-docx | 保持段落+表格顺序，标题样式→Markdown |
| Word 旧版 | `.doc` | antiword/libreoffice | 外部转换 |
| PowerPoint | `.pptx` | python-pptx | 每页一个 Document |
| Excel | `.xlsx` | openpyxl | 每个 sheet 一个 Document |

**按后缀自动路由**

```python
from ragkit.readers import read
docs = read("report.pdf")            # 自动选 PDFReader
docs = read("report.pdf", reader="pdf")        # 指定注册名
docs = read("report.pdf", reader=MyPDFReader()) # 指定实例
```

**PDF 选项**

```python
from ragkit.readers import PDFReader

reader = PDFReader(
    drop_header_footer=True,   # 跨页重复行按页眉页脚去除
    drop_toc=True,             # 目录页识别并跳过
    extract_tables=True,       # 版面表格转 Markdown
    ocr_fn=lambda i, png: my_ocr(png),   # 扫描件 OCR 钩子
    min_text_chars=30,         # 少于此字符数视为疑似扫描件
)
pipe = RAGPipeline(reader=reader)
```

**Word 解析细节**：按文档流顺序输出「段落 + 表格」，`Heading 1` / `标题 1` / `Title` 样式自动转 `#`，页眉页脚文本会被剔除。

---

### 2. 切分

| 策略 | 注册名 | 适用 |
|---|---|---|
| 递归字符 | `recursive` | 纯文本、PDF、PPT |
| 标题层级 | `markdown` | Markdown、Word、HTML、EPUB |
| 表格 | `table` | CSV、Excel |
| 问答对 | `qa` | JSON 问答 |

```python
from ragkit import SplitConfig

SplitConfig(
    chunk_size=800,      # 块长上限
    chunk_overlap=120,   # 重叠（必须 < chunk_size）
    min_chunk_size=80,   # 过小的块会与相邻块合并
)
```

**换切分策略**

```python
from ragkit.splitters import splitter_for, RecursiveSplitter

pipe.ingest(path, splitter=splitter_for("pdf"))          # 按类型
pipe.ingest(path, splitter=RecursiveSplitter(SplitConfig(chunk_size=500)))  # 强制指定
```

**Markdown 结构化切分**保证：
- 代码块（``` / ~~~）与表格整体保留，绝不从中间切断
- 块内前缀带完整标题路径：`> 路径：用户指南 / 安装 / 参数配置`
- 只有超长段落才递归切分

**表格切分**：小表整表保留；超过 `whole_table_max_chars` 的大表按「表头 + N 行」复合块拆分，**每块重复表头**。

---

### 3. 嵌入与向量库

**接入真实嵌入模型**——继承 `BaseEmbedder`，输出必须 L2 归一化：

```python
from ragkit import BaseEmbedder
from ragkit.core.embeddings import l2_normalize

class MyEmbedder(BaseEmbedder):
    name = "my-embedder"
    dimension = 1024

    def embed(self, texts):
        vectors = my_model.encode(texts)     # 你的模型 / API
        return [l2_normalize(list(map(float, v))) for v in vectors]
```

> 内置 `HashEmbedder` 仅用于测试与演示，区分度差，**不要用于生产**。

**本地 Ollama 嵌入（零第三方依赖）**

框架内置 `OllamaEmbedder`，走本机 Ollama 的 `/api/embed`，支持批量、自动学习维度、L2 归一化：

```bash
ollama serve
ollama pull bge-m3          # 1024 维；也可用 nomic-embed-text（768 维）
```

```python
from ragkit import OllamaEmbedder, RAGPipeline, PipelineConfig

embedder = OllamaEmbedder(
    model="bge-m3",                       # 或 nomic-embed-text
    base_url="http://localhost:11434",
    dimension=None,                       # 首次调用后自动确定；也可显式填
    timeout=120, batch_size=8,
)
pipe = RAGPipeline(PipelineConfig(embed_model_id="ollama/bge-m3"),
                   embedder=embedder)
```

模型缺失时提示 `ollama pull <model>`，服务不可用时提示 `ollama serve`。也可以按注册名创建：

```python
from ragkit.core.embeddings import EMBEDDERS
embedder = EMBEDDERS.create("ollama", model="bge-m3")
```

维度会在首次嵌入后回填到主表 `FileRecord.embed_dimension`，与 `embed_model_id` / `normalization` 一起构成证据链。完整示例见 [`examples/11_ollama.py`](examples/11_ollama.py)；与 Weaviate 组合的端到端示例见 [`examples/12_ollama_weaviate.py`](examples/12_ollama_weaviate.py)——先用 embedder 探测维度再建 collection，避免不同模型的维度混用。

**通义千问嵌入（DashScope，零第三方依赖）**

内置 `QianwenEmbedder` 走百炼的 OpenAI 兼容接口，同样支持批量、维度配置、L2 归一化：

```bash
export DASHSCOPE_API_KEY=sk-...     # 从 https://bailian.console.aliyun.com/ 获取
```

```python
from ragkit import QianwenEmbedder, RAGPipeline, PipelineConfig

embedder = QianwenEmbedder(
    model="text-embedding-v3",       # 或 text-embedding-v4
    dimensions=1024,                 # v3: 1024/768/512/256/128/64；v4 额外支持 2048/1536
    batch_size=10,                   # DashScope 单次最多 10 条
)
pipe = RAGPipeline(PipelineConfig(embed_model_id="qianwen/text-embedding-v3"),
                   embedder=embedder)
```

API Key 也可通过 `api_key=` 直接传入；不传时读环境变量 `DASHSCOPE_API_KEY`，不会写进日志或文件。注册名有两个：`qianwen` 与 `dashscope`。鉴权失败会明确提示检查 Key。云服务默认走系统代理（与 Ollama 相反），可用 `use_proxy=False` 关闭。

**三种向量库后端**

```python
from ragkit import RAGPipeline, InMemoryChunkStore
from ragkit.store import InMemoryVectorStore, QdrantVectorStore, WeaviateVectorStore, create_store

# 内存（默认，零依赖）
pipe = RAGPipeline(store=InMemoryVectorStore())

# Qdrant
pipe = RAGPipeline(store=QdrantVectorStore(
    collection="ragkit_chunks", file_collection="ragkit_files",
    url="http://localhost:6333", dimension=1024, oversample=5))

# Weaviate
pipe = RAGPipeline(store=WeaviateVectorStore(
    class_name="RagChunk", file_class_name="RagFile",
    url="https://xxx.weaviate.cloud", api_key="..."))

# 按名创建
store = create_store("qdrant", collection="rag", url="http://localhost:6333")
```

**后端实现要点**

- 每个后端承载**两张表**：chunk 表（带向量、负责检索）+ 文档表（`FileRecord`，负责版本管理）
- 表字段由 `FileRecord` / `ChunkRecord` 的 dataclass 定义**自动派生**，三方扩展字段会自动成为新列
- `filter_fn` 是任意 Python 谓词，无法通用下推到各库，采用 **oversample → 本地过滤 → 截断 top_k**，与内存实现行为一致
- `list_chunks()` 支撑附表审计/回滚：Qdrant 用 `scroll`，Weaviate 用 `fetch_objects`

---

### 4. 召回

```python
from ragkit import RetrievalConfig

RetrievalConfig(
    mode="hybrid",        # hybrid（默认）/ vector / keyword
    top_k=10,             # 最终返回条数
    candidate_k=50,       # 每路先取多少再融合
    rrf_k=60,             # RRF 平滑常数
    rrf_weights={"vector": 1.0, "keyword": 0.8},
    enable_prefilter=True # 是否做版本/权限前置过滤
)
```

**RRF 融合自己实现**（`retrieval/fusion.py`）：

```
score(d) = Σᵢ  wᵢ / (k + rankᵢ(d))
```

未出现在某路结果中的文档该路贡献 0；也可单独调用：

```python
from ragkit.retrieval import reciprocal_rank_fusion

fused = reciprocal_rank_fusion(
    [vector_hits, keyword_hits], k=60,
    weights=[1.0, 0.8], sources=["vector", "keyword"])
```

**关键词召回**是自实现的 BM25（纯 Python，CJK 单字 + 英文词分token），无需外部依赖。

---

### 5. 重排

| 实现 | 注册名 | 依赖 | 说明 |
|---|---|---|---|
| 规则重排 | `rule` | 无 | 字面覆盖率 + 标题路径匹配，默认与兜底 |
| CrossEncoder | `cross_encoder` | sentence-transformers | 语义重排，效果最好 |
| LLM 重排 | `llm` | 注入 callable | `scorer(query, texts) -> List[float]` |

```python
from ragkit import PipelineConfig, RerankConfig
from ragkit.rerank import RuleReranker, CrossEncoderReranker, LLMReranker

# 默认规则重排（不传 reranker 即为 RuleReranker）
pipe = RAGPipeline(PipelineConfig(
    rerank=RerankConfig(enabled=True, timeout=2.0, fallback="keep_order", top_n=5)))

# CrossEncoder
pipe = RAGPipeline(reranker=CrossEncoderReranker(
    RerankConfig(timeout=3.0), model_name="cross-encoder/ms-marco-MiniLM-L-6-v2"))

# 自定义 LLM 打分
pipe = RAGPipeline(reranker=LLMReranker(
    RerankConfig(timeout=5.0),
    scorer=lambda q, texts: my_llm_score(q, texts)))

# 关闭重排
pipe = RAGPipeline(PipelineConfig(rerank=RerankConfig(enabled=False)))
```

**超时兜底**：重排超过 `timeout` 或抛异常时，自动按 `fallback` 返回：
- `keep_order`：保留召回原顺序
- `keep_score`：保留召回原分数

兜底原因记录在 `reranker.last_fallback`，并会触发 `rerank:fallback` 事件（`reason` = `timeout` / `error` / `invalid_scores`）。

---

### 6. 主表 + 附表（多版本）

**主表 `FileRecord`**：`business_id`（业务 id，跨版本稳定）、`version`、`status`、`owner`、`md5`、`file_name`、`created_at`、`updated_at`、`extra`。

**证据链字段**（入库时自动填充，也可显式指定）：`embed_model_id`（嵌入模型标识）、`embed_dimension`（维度）、`normalization`（归一化方式）、`chunk_strategy`（切分策略）、`chunk_size` / `chunk_overlap`。换模型或改切分参数时，能据此判断该版本要不要重建。`(business_id, version)` 唯一。

**`md5` 会自动计算**：文件按字节流式计算、目录按「相对路径 + 各文件 MD5」聚合、`Document` 按文本内容。未显式传入时自动填充，显式传入则以其为准。

**内容未变则跳过**（默认开启，由 `PipelineConfig.reingest_unchanged` 控制）：

- 同一 `(business_id, version)` 且 MD5 相同 → 跳过解析与向量化，`ingest()` 返回空列表，并发出 `ingest:skipped` 事件
- MD5 不同 → 正常重新解析入库（覆盖该版本）
- 换版本号（如 `v1` → `v2`）即使内容相同也会入库（版本管理语义）
- `reingest_unchanged=True`：强制重新解析（例如换了切分参数或嵌入模型）

```python
from ragkit import PipelineConfig

# 默认：内容没变就不重复解析
pipe = RAGPipeline(PipelineConfig())
pipe.ingest("guide.md", record=FileRecord("guide", "v1"))   # 首次，写入 N 块
pipe.ingest("guide.md", record=FileRecord("guide", "v1"))   # 返回 []，命中 MD5 跳过

# 强制重新解析
pipe = RAGPipeline(PipelineConfig(reingest_unchanged=True))
```

**附表 `ChunkRecord`**：`chunk_id`、`business_id`、`version`（外键）、`chunk_index`、`page_no`、`title_path`、`section`、`text`、`acl`、`doc_type`、`language`、`vector`、`metadata`、`extra`。

```python
from ragkit import (RAGPipeline, FileRecord, InMemoryCatalog, InMemoryChunkStore)

pipe = RAGPipeline(catalog=InMemoryCatalog(), chunk_store=InMemoryChunkStore())

pipe.ingest(doc_v1,  record=FileRecord("guide", "v1",  status="deprecated",
                                       owner="alice", md5="aaa"))
pipe.ingest(doc_v10, record=FileRecord("guide", "v10", status="active",
                                       owner="alice", md5="bbb"))

pipe.retrieve("超时默认值")        # 只召回 v10 那组，v1 不召回
pipe.versions("guide")            # ['v1', 'v10']
rows = pipe.chunks_of("guide", "v1")   # List[ChunkRecord]，用于审计/回滚
```

**版本择优规则**

- 语义化比较，不是字符串比较：`v1.10 > v1.9`、`v3.1.2 > v3.1`
- 默认在 `status="active"` 里取最高版本；最高版若 `deprecated`，自动退到次高 `active`
- 不同业务 id 互不影响
- 与生效时间、ACL 过滤叠加

**字段扩展（三方接入必读）**

方式一：声明式子类（有类型提示、可生成表列）

```python
from dataclasses import dataclass
from ragkit import FileRecord

@dataclass
class MyFileRecord(FileRecord):
    department: str = ""
    retention_days: int = 30

rec = MyFileRecord("guide", "v1", department="研发", retention_days=90)
MyFileRecord.columns()   # 基类列 + 子类列 + extra
rec.to_dict()            # 扁平字典，含 department / retention_days
```

方式二：`extra` 动态字段

```python
rec = FileRecord("guide", "v1")
rec.set_extra("tenant", "acme").set_extra("biz_line", "payments")
rec.get_extra("tenant")        # 'acme'
```

两者都会：
- 出现在 `to_dict()` / `columns()` / 表结构中
- 自动并入 `to_filter_meta()`，因此**可直接做前置过滤**：

```python
pipe.retrieve("超时", filter_fn=lambda m: m["filter"].get("tenant") == "acme")
```

> 子类新增字段必须给默认值（Python dataclass 继承规则）。`from_dict()` 会把未知键自动归入 `extra`。

**主表落真实库**

```python
from ragkit import StoreCatalog, InMemoryChunkStore
from ragkit.store import WeaviateVectorStore

store = WeaviateVectorStore(class_name="RagChunk", file_class_name="RagFile",
                            url="...", api_key="...")
pipe = RAGPipeline(catalog=StoreCatalog(store),
                   chunk_store=InMemoryChunkStore(store))
```

**建议的表结构**

```sql
CREATE TABLE files (
  business_id TEXT, version TEXT, status TEXT, owner TEXT,
  md5 TEXT, file_name TEXT, created_at TEXT, updated_at TEXT,
  extra JSON, PRIMARY KEY (business_id, version)
);

CREATE TABLE chunks (
  id TEXT PRIMARY KEY, business_id TEXT, version TEXT,
  chunk_index INT, page_no INT, title_path TEXT, section TEXT,
  text TEXT, acl JSON, doc_type TEXT, language TEXT,
  vector BLOB, metadata JSON, extra JSON,
  FOREIGN KEY (business_id, version) REFERENCES files(business_id, version)
);
```

建表可直接用 `property_columns(ChunkRecord)` 拿到全部列名：

```python
from ragkit.catalog.scalar import property_columns
property_columns(ChunkRecord)   # ['chunk_id', 'business_id', ..., 'metadata_json', 'extra_json']
```

---

### 7. 版本与权限

检索前用元数据做**前置过滤**，避免过期/越权内容进入候选集：

```python
from ragkit import PipelineConfig

pipe = RAGPipeline(PipelineConfig(
    query_time="2026-06-01T00:00:00Z",   # 指定时间点（默认当前）
    user_acls=["dept:eng"],              # 用户权限标签
))
```

**规则**

- 生效时间：`effective_from <= now < effective_to`，过期或未生效都不召回
- 权限：`acl ∩ user_acls ≠ ∅`；`acl` 为空视为公开
- 叠加版本择优：旧版本同时被排除

也可以完全自定义：

```python
pipe.retrieve("q", filter_fn=lambda meta: meta["filter"].get("language") == "zh")
```

---

### 8. 回调与进度

回调是**只读观察者**：看事件、报错误、追进度，不改变流程结果。

**订阅方式**

```python
from ragkit import RAGPipeline, CallbackManager, Event

cb = CallbackManager()
cb.on(Event.ERROR, lambda p: print("失败:", p["stage"], p["error_info"].message))
cb.on(Event.RETRIEVE_END, lambda p: print("召回", p["count"], "条"))

pipe = RAGPipeline(callbacks=cb)
# 或：callbacks={Event.ERROR: fn}  /  callbacks=single_callable
# 或：RAGPipeline(on_error=fn, on_progress=fn)
```

**事件表**

| 阶段 | 事件 | 关键字段 |
|---|---|---|
| 入库 | `ingest:start` / `ingest:end` | `source` / `count`, `duration_ms`, `md5` |
| 跳过入库 | `ingest:skipped` | `business_id`, `version`, `md5`, `reason` |
| 进度 | `ingest:progress` | `stage`, `current`, `total`, `percent`, `eta_ms` |
| 读取 | `read:end` | `documents`, `count` |
| 切分 | `split:end` | `chunks`, `count`, `strategy` |
| 嵌入 | `embed:end` | `count`, `dimension` |
| 落库 | `store:end` | `count` |
| 检索 | `retrieve:start` / `retrieve:end` | `query`, `top_k`, `results` |
| 召回 | `recall:end` | `results`, `count` |
| 重排 | `rerank:end` | `results`, `fallback` |
| 重排兜底 | `rerank:fallback` | `reason` |
| 错误 | `error` / `ingest:error` / `retrieve:error` | `stage`, `error_info` |

**实时进度（防"看起来卡死"）**

大文件入库时，向量化和写库分批处理，每批上报：

```python
pipe = RAGPipeline(
    PipelineConfig(progress_batch_size=32, progress_interval=0.2),
    on_progress=lambda p: print(
        f"{p['stage']} {p['current']}/{p['total']} {p['percent']}% "
        f"ETA {p['eta_ms']}ms"),
)
```

- `progress_batch_size`：每批块数（越小越细，回调越频繁）
- `progress_interval`：节流间隔（默认 0.2s），**到 100% 一定强制发一次**
- 未注册 `on_progress` 时零开销

**内置回调**

| 类 | 用途 |
|---|---|
| `LoggingCallbacks` | 打日志 |
| `TimingCallbacks` | 阶段耗时汇总 `summary()` |
| `TraceCollector` | 全链路 trace `dump()` |
| `ProgressBarCallbacks` | 终端进度条（原地刷新） |
| `MetricsCallbacks` | 计数/错误/耗时 `snapshot()`，接监控 |
| `JsonlAuditCallbacks` | 事件写 JSONL 审计文件 |
| `ErrorAlertCallbacks` | 错误告警（注入 notifier，带冷却防风暴） |
| `SamplingCallbacks` | 按概率采样降噪 |

```python
from ragkit import (CallbackManager, Event, MetricsCallbacks, TimingCallbacks,
                    TraceCollector, ProgressBarCallbacks, JsonlAuditCallbacks,
                    ErrorAlertCallbacks)

cb = CallbackManager()
metrics = MetricsCallbacks(); metrics.attach_to(cb)     # 全量指标
timing = TimingCallbacks()
cb.on(Event.INGEST_END, timing); cb.on(Event.RETRIEVE_END, timing)
cb.on(Event.PROGRESS, ProgressBarCallbacks())           # 进度条
JsonlAuditCallbacks("audit.jsonl").attach_to(cb)        # 审计落盘
cb.on(Event.ERROR, ErrorAlertCallbacks(lambda info: send_alert(info.to_dict())))

pipe = RAGPipeline(callbacks=cb)
metrics.snapshot()   # {"events": {...}, "errors": {...}, "durations": {...}}
timing.summary()     # {"retrieve:end": {"count": 3, "avg_ms": 12.4, ...}}
```

> 回调自身抛错不会影响主流程，记录在 `cb.callback_errors`。

---

### 9. 中间件

中间件是**拦截器**：能改参数、改结果、短路、重试、熔断。

```python
from ragkit import (RAGPipeline, BaseMiddleware, MiddlewareChain,
                    GuardMiddleware, QueryNormalizeMiddleware, TopKClampMiddleware,
                    CacheMiddleware, DedupMiddleware, RetryMiddleware,
                    ResultFilterMiddleware, CircuitBreakerMiddleware, AuditMiddleware)

class RewriteQuery(BaseMiddleware):
    stage_filter = {"retrieve"}          # 只在检索阶段生效
    def before(self, stage, ctx):
        ctx["query"] = ctx["query"] + " 配置项"   # 改查询
        ctx["top_k"] = 5                          # 调召回数

class DropLowScore(BaseMiddleware):
    stage_filter = {"retrieve"}
    def after(self, stage, ctx, result):
        return [r for r in result if r.score > 0.3]   # 改结果

pipe = RAGPipeline(middleware=[
    GuardMiddleware(),                 # 空查询短路
    QueryNormalizeMiddleware(),        # 全角转半角、折叠空白
    TopKClampMiddleware(max_k=20),     # 防 top_k 过大（要在缓存之前）
    CacheMiddleware(),                 # 相同 query 走缓存
    RewriteQuery(),
    DedupMiddleware(),                 # chunk_id 去重
    DropLowScore(),
    CircuitBreakerMiddleware(threshold=5, cooldown=30),
    RetryMiddleware(times=2, stages={"ingest"}),
    AuditMiddleware(sink=my_audit_sink),
])
```

**三个钩子**

| 钩子 | 时机 | 能力 |
|---|---|---|
| `before(stage, ctx)` | 阶段前 | 改 `ctx`；返回 `False` 短路（结果取 `ctx["short_circuit"]`） |
| `after(stage, ctx, result)` | 阶段后 | 返回值替换结果 |
| `on_error(stage, ctx, exc, retry)` | 阶段抛错 | 返回非 `None` 降级；`RETRY` 或 `retry()` 重试 |

**ctx 可改字段**

- `ingest`：`source` / `record` / `splitter` / `chunks`
- `retrieve`：`query` / `top_k` / `filter_fn` / `results`

**内置中间件**

| 类 | 用途 |
|---|---|
| `LoggingMiddleware` | 阶段耗时日志 |
| `RetryMiddleware` | 失败自动重试 |
| `CacheMiddleware` | query→结果缓存 |
| `GuardMiddleware` | 空查询短路 |
| `ResultFilterMiddleware` | 按谓词裁剪结果 |
| `DedupMiddleware` | 按 chunk_id 去重 |
| `TopKClampMiddleware` | 钳制 top_k 上下界 |
| `QueryNormalizeMiddleware` | NFKC 全角转半角、折叠空白、去标点 |
| `CircuitBreakerMiddleware` | 连续失败熔断 + 冷却半开 |
| `AuditMiddleware` | 审计记录（sink 或 logger） |

**顺序很关键**：`before` 正序、`after` 逆序（洋葱模型）。

缓存类中间件尤其要注意：它的 key 依赖 `query` 和 `top_k`，所以**所有会修改这两个字段的中间件都必须排在缓存之前**。例如：

```python
# 正确
middleware=[QueryNormalizeMiddleware(), TopKClampMiddleware(max_k=20), CacheMiddleware()]
# 错误：TopKClamp 在缓存之后，第一次缓存 key 用 100、第二次用 20，永远命中不了
middleware=[QueryNormalizeMiddleware(), CacheMiddleware(), TopKClampMiddleware(max_k=20)]
```

中间件自身异常会包成 `MiddlewareError`，与业务异常区分。

**callback vs middleware**：只需埋点/进度/错误上报 → callback；需要改参数、拦结果、短路、重试 → middleware。

### 10. 日志

框架内置标准 `logging` 分级日志，**默认静默**（不配置就不输出任何东西，也不污染使用方日志）。

```python
from ragkit.log import configure_logging, get_logger

configure_logging(level="INFO")     # 或 DEBUG / WARNING
log = get_logger("my.app")          # 内部统一加 ragkit. 前缀
log.info("开始处理 %s", doc_id)
```

也可不写代码实现：`RAGKIT_LOG_LEVEL=INFO python your_script.py`。

分级约定：

| 级别 | 内容 |
|---|---|
| `DEBUG` | 详细参数：切分配置、ACL、candidate_k、嵌入模型/batch、HTTP 调用 |
| `INFO` | 阶段边界：ingest/retrieve 开始与完成、读取/切分/向量化条数、召回条数、耗时、MD5 跳过 |
| `WARNING` | 可恢复异常：重排兜底、ingest/retrieve 失败、读取主表失败 |

日志带 `ragkit.pipeline` / `ragkit.embeddings` 等名字，可用 `logging.getLogger("ragkit")` 统一调级别。它与 `LoggingCallbacks`（事件回调日志）互补：前者看运行过程，后者做结构化埋点。

### 11. 召回测试台（可视化前端）

纯标准库实现的单页前端，把任意 `RAGPipeline` 挂上去即可在浏览器里交互式测试召回——无需 npm、无第三方依赖。

```python
from ragkit import RecallUI

RecallUI(pipe).serve(port=8765)
# 打开 http://localhost:8765
```

一行快捷写法：`from ragkit import serve_recall_ui; serve_recall_ui(pipe)`。

**功能**

- 查询框 + 模式切换（`hybrid` / `vector` / `keyword`）、top_k、重排开关
- ACL 与状态过滤（填 `dept:eng`、选 `active`）
- 结果卡片：排名、分数、召回来源（vector/keyword/hybrid 标签）、正文、业务 id@版本、页码、标题路径、切分策略
- 顶部概览：分段总数、嵌入模型与维度、文档列表

**说明**

- 界面里切换模式/重排/ACL 只影响**本次请求**，查询结束自动恢复 pipeline 原配置，不会污染代码里的设置。
- **数据早已入库的情况**：关键词索引是内存态、不持久化。`RecallUI` 构造时会自动从向量库枚举已有分段重建关键词索引，所以重启后 `keyword` / `hybrid` 依然有结果；不需要重新 ingest。不想重建可传 `RecallUI(pipe, rebuild_index=False)`。
- 后端是 `ThreadingHTTPServer`，`Ctrl+C` 退出。
- 完整可运行示例见 [`examples/13_recall_ui.py`](examples/13_recall_ui.py)（有本地 Ollama 用 bge-m3，没有则退回零依赖哈希嵌入演示界面）。

**接口**（如需自己接前端）

```
GET  /api/overview          # 分段数、嵌入器、版本列表
GET  /api/health
GET  /api/ingest/config     # 读取器/切分器列表与默认参数
POST /api/query             # {"query":"...", "mode":"hybrid", "top_k":5,
                            #  "rerank":null|true|false, "acl":"dept:eng", "status":"active"}
POST /api/ingest            # {"content":"文本或base64:", "filename":"a.md",
                            #  "business_id":"...", "version":"v1", "status":"active",
                            #  "doc_type":"auto", "splitter":"auto",
                            #  "chunk_size":800, "chunk_overlap":120,
                            #  "acl":"dept:eng", "metadata":{"team":"ops"}}
```

### 12. 文档入库页（同界面 Tab）

召回测试台顶部切到**文档入库**，即可在浏览器里解析并入库文档，无需写代码：

- **上传文件**：点击选择或拖拽，支持 md/txt/csv/json/pdf/docx/pptx/xlsx/html 等（按后缀自动路由读取器）
- **粘贴文本**：直接输入内容，指定 doc_type
- **业务参数**：business_id（留空用文件名）、version、status、owner
- **解析参数**：读取器、切分器、chunk_size、chunk_overlap
- **过滤扩展**：ACL、自定义字段（写入 filter，可用于召回过滤）
- 入库后自动重建本地关键词索引，切回召回页立刻能查到；本次切分参数用完即恢复，不污染全局配置

这一切走上面同一套 `/api/ingest` 接口，也可脱离页面直接调用。

---

## 扩展指南

框架的每个环节都面向基类，可用两种方式替换：

| 方式 | 做法 | 适用场景 |
|---|---|---|
| **注册名** | 继承基类 → `@注册表.register("名字")` → 配置里用名字引用 | 想让新实现像内置组件一样按名复用、可序列化进配置 |
| **构造注入** | 直接把符合接口的对象传给 `RAGPipeline(...)` | 局部替换、带构造参数、临时实验；无需注册 |

### 扩展点地图

| 环节 | 基类 | 注册表 | 必须实现 | Pipeline 注入参数 |
|---|---|---|---|---|
| 读取 | `BaseReader` | `READERS` | `read(source, **kwargs) -> List[Document]` | `reader=` |
| 切分 | `BaseSplitter` | `SPLITTERS` | `split(document, **kwargs) -> List[Chunk]` | `splitter=`（`ingest` 时传） |
| 嵌入 | `BaseEmbedder` | `EMBEDDERS` | `embed(texts) -> List[List[float]]`（**须 L2 归一化**） | `embedder=` |
| 主表 | `BaseCatalog` | — | `upsert/get/latest/all` 等 | `catalog=` |
| 附表 | `BaseChunkStore` | — | `add/chunks_of/search` | `chunk_store=` |
| 向量库 | `BaseVectorStore` | — | `add/search/clear/__len__` | `store=`（也可由 `chunk_store` 内部使用） |
| 召回 | `BaseRetriever` | — | `retrieve(query, top_k, filter_fn)` | `retriever=` |
| 重排 | `BaseReranker` | `RERANKERS` | `score(query, chunks) -> List[float]` | `reranker=` |
| 中间件 | `BaseMiddleware` | — | `before/after/on_error`（均有默认实现） | `middleware=` |
| 回调 | `CallbackManager` | — | 无，直接 `.on(Event.X, fn)` | `callbacks=` / `on_error=` / `on_progress=` |

内置注册表可用 `注册表.list()` 查看全部名字，`注册表.create("名字", **kwargs)` 按名构造。

### 1. 注册式扩展：读取器 / 切分器 / 嵌入 / 重排

这四类有全局注册表，注册后即可像内置组件一样按名引用。

```python
from ragkit.readers.base import BaseReader, READERS
from ragkit.splitters.base import BaseSplitter, SPLITTERS
from ragkit.core.embeddings import BaseEmbedder, EMBEDDERS
from ragkit.rerank.base import BaseReranker, RERANKERS
from ragkit.core.schema import Document

# 读取器：把任意来源解析成 Document 列表
@READERS.register("my_format")
class MyFormatReader(BaseReader):
    name = "my_format"
    def read(self, source, **kwargs) -> List[Document]:
        return [Document(text=parse(source), metadata={"filter": {"doc_type": "my_format"}})]

# 切分器：_sentences 按句/段边界切，_iter_chunks 施加块长/重叠与元数据
@SPLITTERS.register("sliding")
class SlidingSplitter(BaseSplitter):
    name = "sliding"
    def split(self, document, **kwargs):
        return self._iter_chunks(self._sentences(document.text), document.metadata)

# 嵌入：输出必须与输入等长、等序、已 L2 归一化
@EMBEDDERS.register("my_embed")
class MyEmbedder(BaseEmbedder):
    name, dimension = "my_embed", 768
    def embed(self, texts):
        return [l2_normalize(my_model.encode(t)) for t in texts]

# 重排：只需实现 score；超时/异常兜底由基类统一处理
@RERANKERS.register("my_rank")
class MyReranker(BaseReranker):
    name = "my_rank"
    def score(self, query, chunks):
        return [my_score(query, c.chunk.text) for c in chunks]
```

按名构造：

```python
reader = READERS.create("my_format")
embedder = EMBEDDERS.create("my_embed")
reranker = RERANKERS.create("my_rank", timeout=1.5)
```

切分器是**按文档**注入的（不在 Pipeline 构造参数里）：

```python
pipe.ingest("doc.txt", splitter=SlidingSplitter())   # 本次入库用自定义切分器
pipe.ingest("other.txt")                             # 其余仍按 doc_type 自动路由
```

**读取器按后缀自动路由**：在 `readers/__init__.py` 的 `_SUFFIX_MAP` 里加一行 `".my": "my_format"`，否则只能显式 `reader=` 注入。切分器按 `doc_type` 路由的逻辑在同文件的 `splitter_for()`。

### 2. 构造注入：向量库 / 召回 / 主表 / 附表

这些环节没有全局注册表，直接实现接口并传给 Pipeline。

```python
from ragkit import RAGPipeline, BaseEmbedder
from ragkit.store.base import BaseVectorStore
from ragkit.retrieval.retrievers import BaseRetriever

class MyVectorStore(BaseVectorStore):
    def add(self, chunks, vectors): ...          # 写入分段
    def search(self, query_vec, top_k, filter_fn=None): ...  # 返回 [(Chunk, score)]
    def clear(self): ...
    def __len__(self): ...
    # 可选：list_chunks / upsert_files / list_files（主表持久化需要）

class MyRetriever(BaseRetriever):
    def retrieve(self, query, top_k, filter_fn=None): ...    # 返回 List[ScoredChunk]
    def add(self, chunks, **kwargs): ...         # 可选：需要建索引时实现

pipe = RAGPipeline(
    embedder=MyEmbedder(),
    store=MyVectorStore(),
    retriever=MyRetriever(),
)
```

⚠️ 自定义 `store` 若实现了 `__len__`，空库时是 falsy——框架用的是 `is not None` 判断，不会误替换成默认实现。

### 3. 自定义表记录（扩展列）

`FileRecord` / `ChunkRecord` 是 dataclass，继承它们加字段。两种落库方式：

**方式 A：扩展列（推荐，可查询、可过滤）**

把子类传给后端和分组器，声明字段直接成为数据库列（Weaviate/Qdrant 自动建 schema）：

```python
from dataclasses import dataclass
from ragkit import (FileRecord, ChunkRecord, InMemoryChunkStore,
                    WeaviateVectorStore, StoreCatalog, RAGPipeline)

@dataclass
class TenantFile(FileRecord):
    department: str = ""
    retention_days: int = 30

@dataclass
class TenantChunk(ChunkRecord):
    tenant_scope: str = "internal"
    quality_score: float = 0.0

store = WeaviateVectorStore(client=client, dimension=1024,
                            file_model=TenantFile,     # 文档表按子类建列
                            chunk_model=TenantChunk)   # 分段表按子类建列
chunk_store = InMemoryChunkStore(store, record_cls=TenantChunk)

pipe = RAGPipeline(..., store=store, catalog=StoreCatalog(store),
                   chunk_store=chunk_store)
pipe.ingest(path, record=TenantFile("guide", "v1", department="平台组"),
            metadata={"tenant_scope": "internal", "quality_score": 0.9})
```

`ingest(metadata=...)` 里与子类字段同名的键会自动赋到该列，其余键落 `extra`。完整可运行示例见 [`examples/10_weaviate_extended.py`](examples/10_weaviate_extended.py)。

**方式 B：动态 `extra`（不改后端）**

只想挂几个不查询的字段时，无需子类和后端配置：

```python
record = FileRecord("guide", "v1", extra={"source_system": "confluence"})
pipe.ingest(path, record=record, metadata={"my_tag": "keep-me"})
# 可从 read 回来的对象取回：record.get_extra("source_system")
```

### 4. 中间件：横切逻辑

实现 `BaseMiddleware`，四个钩子都有默认实现（无操作），按需覆写：

```python
from ragkit.middleware import BaseMiddleware, MiddlewareChain

class TimingMiddleware(BaseMiddleware):
    stage_filter = {"ingest", "query"}   # 只拦这两个阶段；不设则拦全部

    def before(self, stage, ctx):
        ctx["t0"] = time.perf_counter()

    def after(self, stage, ctx, result):
        print(stage, "耗时", time.perf_counter() - ctx["t0"])

    def on_error(self, stage, ctx, exc, handler):
        ...   # 可降级/重跑/改上下文；抛错则中断

pipe = RAGPipeline(middleware=MiddlewareChain([TimingMiddleware()]))
```

内置中间件：`LoggingMiddleware` / `CacheMiddleware` / `RetryMiddleware` / `CircuitBreakerMiddleware` / `GuardMiddleware` / `DedupMiddleware` / `TopKClampMiddleware` / `QueryNormalizeMiddleware` / `ResultFilterMiddleware` / `AuditMiddleware`。

### 5. 回调与事件

不需要继承，直接监听：

```python
from ragkit import CallbackManager, Event, RAGPipeline

cb = CallbackManager()
cb.on(Event.INGEST_SKIPPED, lambda p: print("跳过", p["business_id"]))
cb.on(Event.ERROR, lambda p: print("出错", p))
cb.on(Event.PROGRESS, lambda p: print(p["stage"], p["percent"], "%"))

pipe = RAGPipeline(callbacks=cb)
# 快捷写法：RAGPipeline(on_error=fn, on_progress=fn)
```

主要事件：`ingest:start/end/skipped`、`read:end`、`split:end`、`embed:end`、`store:end`、`retrieve:start/end`、`recall:end`、`rerank:end/fallback`、`ingest:error/retrieve:error`、`error`、`callback:error`，以及细粒度 `PROGRESS`（值为 `ingest:progress`）。完整列表见 `ragkit/callbacks/events.py` 的 `Event` 枚举。也可以用 `MetricsCallbacks` 自动收集计数与耗时。

### 扩展时的通用约束

1. **嵌入输出必须 L2 归一化**——否则余弦相似度与点积不等价，召回结果不可信。
2. **`embed` 的输入输出等长等序**——Pipeline 按位置把向量和分段配对写库。
3. **`search` 返回 `[(Chunk, score)]`**，分数越大越相关；`filter_fn(metadata) -> bool` 必须被尊重（权限过滤就靠它）。
4. **向量维度一旦建库就固定**——换模型/换维度要换 collection 名或重建，不要往同一张表混写。
5. **重排器只需 `score`**，`rerank()` 基类的超时兜底会自动生效。
6. **所有重依赖延迟导入**：第三方库放在方法内部 `try: import ...`，缺失时给出明确安装提示，保持核心零依赖。

---

## 配置参考

**SplitConfig**

| 字段 | 默认 | 说明 |
|---|---|---|
| `chunk_size` | 800 | 块长上限 |
| `chunk_overlap` | 120 | 重叠，须 `< chunk_size` |
| `min_chunk_size` | 80 | 小于此值的块与相邻合并 |

**RetrievalConfig**

| 字段 | 默认 | 说明 |
|---|---|---|
| `mode` | `hybrid` | `hybrid` / `vector` / `keyword` |
| `top_k` | 10 | 最终返回数 |
| `candidate_k` | 50 | 每路候选数 |
| `rrf_k` | 60 | RRF 平滑常数 |
| `rrf_weights` | None | 各路权重 |
| `enable_prefilter` | True | 版本/权限前置过滤 |

**RerankConfig**

| 字段 | 默认 | 说明 |
|---|---|---|
| `enabled` | True | 是否重排 |
| `timeout` | 2.0 | 超时秒数 |
| `fallback` | `keep_order` | `keep_order` / `keep_score` |
| `top_n` | None | 重排后截断 |

**PipelineConfig**

| 字段 | 默认 | 说明 |
|---|---|---|
| `split` / `retrieval` / `rerank` | 见上 | 子配置 |
| `embed_model_id` | `hash-embedder` | 写入证据链 |
| `reingest_unchanged` | False | MD5 相同是否仍重新解析入库 |
| `progress_batch_size` | 32 | 分批大小 |
| `progress_interval` | 0.2 | 进度节流（秒） |
| `query_time` | None | 时间点过滤（ISO） |
| `user_acls` | `[]` | 权限标签 |

---

## 目录结构

```
ragkit/
├── core/        数据模型 / 配置 / 嵌入基类 / 版本权限过滤
├── readers/     读取器（base + text/md/json/csv/html/epub/rtf/pdf/office）+ markdown_parser
├── splitters/   切分器（base + recursive/heading/table/qa）
├── store/       向量库（base + memory/qdrant/weaviate）
├── catalog/     主表+附表（models / base / chunk_store / scalar / store_catalog / version）
├── retrieval/   召回（base + vector/keyword + RRF 融合 + hybrid 编排）
├── rerank/      重排（base + rule/cross_encoder/llm + 超时兜底）
├── callbacks/   事件 / 进度 / 错误 / 8 个内置回调
├── middleware/  10 个内置中间件
├── utils/       注册表 + 超时兜底
└── pipeline.py  端到端编排
```

---

## 测试

纯标准库即可运行，无需外部服务（Qdrant/Weaviate 用假 client 验证映射逻辑）。

```bash
python tests/test_smoke.py       # 端到端冒烟
python tests/test_catalog.py     # 主表+附表、版本择优
python tests/test_stores.py      # Qdrant/Weaviate 字段映射与两表
python tests/test_extend.py      # 记录字段扩展
python tests/test_readers.py     # 格式解析
python tests/test_markdown.py    # Markdown 结构化解析
python tests/test_callbacks.py   # 回调机制
python tests/test_progress.py    # 实时进度
python tests/test_middleware.py  # 中间件
python tests/test_builtins.py    # 内置回调/中间件
python tests/test_ollama.py        # Ollama 嵌入器（假 HTTP 服务，无需真实 Ollama）
python tests/test_qianwen.py       # 千问嵌入器（假 HTTP 服务，无需真实 Key）
python tests/test_recall_ui.py     # 召回测试台 + 日志分级
python tests/test_md5.py         # MD5 指纹与内容未变跳过
python tests/test_usage.py       # README 示例可执行性
```

当前共 **415 项断言**，全部通过。

示例（按场景递进，全部可直接运行，见 [`examples/README.md`](examples/README.md)）：

```bash
python examples/01_quickstart.py       # 最小闭环
python examples/02_multi_format.py     # Markdown/CSV/JSON 混合入库
python examples/03_multi_version.py    # 主表+附表多版本、回滚
python examples/04_recall_compare.py   # vector/keyword/hybrid + 重排 A/B
python examples/05_observability.py    # 进度条、指标、trace、审计
python examples/06_middleware.py       # 短路、缓存、钳制、去重、熔断
python examples/07_custom_extension.py # 自定义各层抽象
python examples/09_weaviate.py       # Weaviate 真实后端（需 Docker）
python examples/10_weaviate_extended.py  # file/chunk 扩展字段 + 证据链
python examples/11_ollama.py       # 本地 Ollama 嵌入模型（需 ollama serve）
python examples/12_ollama_weaviate.py  # Ollama 嵌入 + Weaviate 真实向量库
```

### 用 Docker 跑 Weaviate

`weaviate-client 4.24` 要求**服务端 ≥ 1.27**（1.25 及以下会直接拒绝连接）。

```bash
docker run -d --name weaviate-ragkit \
  -p 8080:8080 -p 50051:50051 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  -e DEFAULT_VECTORIZER_MODULE=none \
  cr.weaviate.io/semitechnologies/weaviate:latest

# 等待就绪（返回 200 即可）
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/v1/.well-known/ready
```

```python
import weaviate
from ragkit import WeaviateVectorStore, StoreCatalog, InMemoryChunkStore

client = weaviate.connect_to_local(host="localhost", port=8080, grpc_port=50051)
store = WeaviateVectorStore(class_name="RagChunk", file_class_name="RagFile",
                            client=client, dimension=1024)
pipe = RAGPipeline(catalog=StoreCatalog(store),
                   chunk_store=InMemoryChunkStore(store))
# ... 使用完毕后
client.close()
```

清理：`docker stop weaviate-ragkit && docker rm weaviate-ragkit`

### 可视化管理端（Weaviate Manager）

官方镜像只有数据库本体。可视化查看用社区开源的 **Weaviate Manager**（中文界面，可浏览 collection / 对象 / 执行 GraphQL 与向量检索）。

```bash
# 方式一：单独拉起管理端（连已有 Weaviate）
docker run -d --name weaviate-manager -p 3000:80 \
  ghcr.io/aicode-world/weaviate-manager:latest

# 打开 http://localhost:3000，连接地址填 http://localhost:8080
```

```bash
# 方式二：一键起数据库 + 管理端（本项目自带 docker-compose.yml）
docker compose up -d
# Weaviate  http://localhost:8080
# 管理端    http://localhost:3000
```

⚠️ **必须给 Weaviate 开 CORS**，否则管理端页面能打开但连不上：

```bash
docker run -d ... -e CORS_ALLOWED_ORIGINS='*' cr.weaviate.io/semitechnologies/weaviate:latest
```

验证 CORS 是否生效：

```bash
curl -s -I http://localhost:8080/v1/schema -H 'Origin: http://localhost:3000' \
  | grep -i access-control-allow-origin
# 应输出 Access-Control-Allow-Origin: *
```

其他可选项：`Weavit UI`（桌面客户端）、`LibreDB Studio`（只读浏览器）。

---

## 注意事项

1. **不要用 `HashEmbedder` 上生产**——它是确定性哈希，只保证接口可用，区分度很差。
2. **向量必须在入库前 L2 归一化**，否则余弦相似度会失真。
3. **`chunk_overlap` 必须小于 `chunk_size`**，否则构造配置时直接报错。
4. **关键词索引不要手写分批重建**——`KeywordRetriever.add()` 只累积语料，检索前统一重建；多次 `ingest` 的语料会自动累加，所以混合召回在有主表/附表时也能正常工作。
5. **重排兜底是静默的**，如果发现重排没生效，去看 `rerank:fallback` 事件的 `reason`。
6. **中间件顺序有意义**：所有会修改 `query` / `top_k` 的中间件必须排在缓存之前，否则缓存永远命中不了。
7. **`ingest` 支持目录**，会递归读取已知后缀并跳过隐藏文件/未知格式。
8. **多版本必须给 `business_id` + `version`**，否则不登记主表，也就没有版本择优。
9. **PDF 扫描件需要自己提供 OCR**，库只负责调用钩子，不捆绑 OCR 引擎。
10. **无需安装即可使用核心功能**；`pip install -e .` 或 `pip install -e ".[all]"` 安装可选依赖。
