Skip to main content

ragkit

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

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])

目录


特性

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

安装

# 从 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.0-py3-none-any.whl 与 .tar.gz
pip install dist/modular_rag-0.1.0-py3-none-any.whl

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

也可以单独安装:

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。


快速开始

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("超时默认值")

一次入库多种来源:

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 未传则自动计算)
自定义扩展字段 使用者 见下

扩展字段怎么赋值

方式一:通过主表记录(推荐,随版本管理)

@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(适合批量场景)

pipe.ingest(path, metadata={"department": "研发", "tenant": "acme"})
  • 传入的普通键自动写入 filter,可直接参与前置过滤
  • 传入 locator / filter / evidence / provenance 子字典则按键合并,不覆盖其它字段
  • 优先级最高,可覆盖框架默认值(如自定义 page_no)

方式三:构造 Document 时直接写 metadata(适合自定义 Reader)

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

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

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

按后缀自动路由

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

PDF 选项

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 问答
from ragkit import SplitConfig

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

换切分策略

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 归一化:

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 归一化:

ollama serve
ollama pull bge-m3          # 1024 维;也可用 nomic-embed-text(768 维)
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。也可以按注册名创建:

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

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

三种向量库后端

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. 召回

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;也可单独调用:

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]
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:强制重新解析(例如换了切分参数或嵌入模型)
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。

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 过滤叠加

字段扩展(三方接入必读)

方式一:声明式子类(有类型提示、可生成表列)

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 动态字段

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(),因此可直接做前置过滤:
pipe.retrieve("超时", filter_fn=lambda m: m["filter"].get("tenant") == "acme")

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

主表落真实库

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

建议的表结构

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) 拿到全部列名:

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

7. 版本与权限

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

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 为空视为公开
  • 叠加版本择优:旧版本同时被排除

也可以完全自定义:

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

8. 回调与进度

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

订阅方式

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

实时进度(防"看起来卡死")

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

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 按概率采样降噪
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. 中间件

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

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,所以所有会修改这两个字段的中间件都必须排在缓存之前。例如:

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

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

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


扩展指南

所有组件都面向基类,两种扩展方式:注册名(全局按名引用)或构造注入(局部替换)。

新增读取器

from ragkit.readers.base import BaseReader, READERS
from ragkit.core.schema import Document

@READERS.register("my_format")
class MyFormatReader(BaseReader):
    name = "my_format"

    def read(self, source, **kwargs):
        text = parse_my_format(source)
        return [Document(text=text)]

按后缀自动路由需在 readers/__init__.py 的 _SUFFIX_MAP 加一行。

新增切分器

from ragkit.splitters.base import BaseSplitter, SPLITTERS

@SPLITTERS.register("sliding")
class SlidingSplitter(BaseSplitter):
    name = "sliding"

    def split(self, document, **kwargs):
        # _sentences 按句/段边界切;_iter_chunks 施加块长/重叠与元数据
        return self._iter_chunks(self._sentences(document.text), document.metadata)

新增嵌入 / 向量库 / 召回 / 重排

from ragkit import RAGPipeline, BaseEmbedder
from ragkit.store.base import BaseVectorStore
from ragkit.retrieval.retrievers import BaseRetriever
from ragkit.rerank.base import BaseReranker

class MyVectorStore(BaseVectorStore):      # 接 Milvus / pgvector / 自己实现
    def add(self, chunks, vectors): ...
    def search(self, query_vec, top_k, filter_fn=None): ...
    def clear(self): ...
    def __len__(self): ...

class MyReranker(BaseReranker):            # 自动获得超时兜底
    def score(self, query, chunks):
        return [my_score(query, c.chunk.text) for c in chunks]

pipe = RAGPipeline(
    embedder=MyEmbedder(),      # 输出须 L2 归一化
    store=MyVectorStore(),
    retriever=MyRetriever(),
    reranker=MyReranker(),
)

自定义表记录

from dataclasses import dataclass
from ragkit import FileRecord, ChunkRecord

@dataclass
class TenantFile(FileRecord):
    tenant: str = ""

@dataclass
class TenantChunk(ChunkRecord):
    tenant: str = ""

自定义 ChunkRecord 需同时覆写 BaseChunkStore 的写入逻辑,或直接在 extra 里挂字段(无需改后端)。


配置参考

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 验证映射逻辑)。

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_md5.py         # MD5 指纹与内容未变跳过
python tests/test_usage.py       # README 示例可执行性

当前共 361 项断言,全部通过。

示例(按场景递进,全部可直接运行,见 examples/README.md):

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 及以下会直接拒绝连接)。

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
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 与向量检索)。

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

# 打开 http://localhost:3000,连接地址填 http://localhost:8080
# 方式二:一键起数据库 + 管理端(本项目自带 docker-compose.yml)
docker compose up -d
# Weaviate  http://localhost:8080
# 管理端    http://localhost:3000

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

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

验证 CORS 是否生效:

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]" 安装可选依赖。

Metadata

Release files for modular-rag 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for modular-rag 0.1.0
File Size Uploaded Provenance Actions
modular_rag-0.1.0.tar.gz 141.4 kB Without provenance Details for modular_rag-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for modular-rag 0.1.0
File Interpreter ABI Platform Actions
modular_rag-0.1.0-py3-none-any.whl Python 3 none any Details for modular_rag-0.1.0-py3-none-any.whl

Total release size: 239.2 kB

Release files / modular_rag-0.1.0.tar.gz

Download URL modular_rag-0.1.0.tar.gz
Size 141.4 kB
Tags Source
SHA-256 checksum
How to use checksums
c6c56ecd001d05bb4d1c09203df867507dd87bd85abd23f5e5a6d535c90570b6
BLAKE2b-256 checksum
How to use checksums
5dfdcc8b9b97541fe1c99b9e50c03b8404dbb0afcd88f83f56c0ab260166c689
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Release files / modular_rag-0.1.0-py3-none-any.whl

Download URL modular_rag-0.1.0-py3-none-any.whl
Size 97.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a4cc8bf22c9a079d59043bf8479d317a2260a08045e4adccb530351e9148a212
BLAKE2b-256 checksum
How to use checksums
06996bc1b79bfce2ad7889c3b7bf8a495620a4c04faa693a380e976d0c661f51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Security for modular-rag 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page