🥤 RAGLite

RAGLite 是一个用于检索增强生成（RAG）的 Python 工具包，支持 DuckDB 或 PostgreSQL。

特性

可配置

• 🧠 可通过 LiteLLM 选择任何 LLM 提供商，包括本地的 llama-cpp-python 模型
• 💾 可选择 DuckDB 或 PostgreSQL 作为关键词和向量搜索数据库
• 🥇 可通过 rerankers 选择任何重排序器，包括默认的多语言 FlashRank

快速且宽松

• ❤️ 仅依赖轻量级、许可宽松的开源库（例如，不使用 PyTorch 或 LangChain）
• 🚀 在 macOS 上使用 Metal 加速，在 Linux 和 Windows 上使用 CUDA 加速

无限制

• 📖 基于 pdftext 和 pypdfium2 的 PDF 到 Markdown 转换
• 🧬 使用 late chunking 和 contextual chunk headings 进行多向量分块嵌入
• ✏️ 通过解决 二元整数规划问题 使用 wtpsplit-lite 实现最优句子分割
• ✂️ 通过解决 二元整数规划问题 实现最优 语义分块
• 🔍 使用数据库原生的关键词和向量搜索进行 混合搜索（FTS+VSS; tsvector+pgvector）
• 💭 自适应检索，其中 LLM 根据查询决定是否以及检索什么内容
• 💰 通过 提示缓存感知的消息数组结构 改善成本和延迟
• 🍰 通过 Anthropic 的长上下文提示格式 提升输出质量
• 🌀 通过解 正交 Procrustes 问题 得到最优的 闭式线性查询适配器

可扩展

• 🔌 内置 Model Context Protocol (MCP) 服务器，任何 MCP 客户端如 Claude desktop 都可以连接
• 💬 可选的类 ChatGPT 前端，适用于 web、Slack 和 Teams，通过 Chainlit 实现
• ✍️ 可选的将任意输入文档转换为 Markdown，使用 Pandoc
• 🔎 可选的高质量文档处理，使用 Mistral OCR 处理 PDF、图片、DOCX 和 PPTX，并自动生成图像描述
• ✅ 可选的使用 Ragas 评估检索和生成性能

安装

[!TIP] 🚀 如果你想使用本地模型，建议安装加速版的 llama-cpp-python 预编译二进制文件：

# 配置要安装的 llama-cpp-python 预编译二进制版本（⚠️ 并非所有组合都可用）：
LLAMA_CPP_PYTHON_VERSION=0.3.9
PYTHON_VERSION=310|311|312
ACCELERATOR=metal|cu121|cu122|cu123|cu124
PLATFORM=macosx_11_0_arm64|linux_x86_64|win_amd64

# 安装 llama-cpp-python：
pip install "https://github.com/abetlen/llama-cpp-python/releases/download/v$LLAMA_CPP_PYTHON_VERSION-$ACCELERATOR/llama_cpp_python-$LLAMA_CPP_PYTHON_VERSION-cp$PYTHON_VERSION-cp$PYTHON_VERSION-$PLATFORM.whl"

安装 RAGLite：

pip install raglite

若需添加类 ChatGPT 的可定制前端支持，可使用 chainlit 附加组件：

pip install raglite[chainlit]

若需支持除 PDF 之外的其他文件类型，可使用 pandoc 附加组件：

pip install raglite[pandoc]

若需支持使用 Mistral OCR 进行高质量文档处理，可使用 mistral-ocr 附加组件：

pip install raglite[mistral-ocr]

若需支持评估功能，可使用 ragas 附加组件：

pip install raglite[ragas]

使用

概述

1. 配置 RAGLite
2. 插入文档
3. 检索增强生成（RAG）
4. 计算并使用最优查询适配器
5. 检索和生成的评估
6. 运行 Model Context Protocol (MCP) 服务器
7. 提供可定制的类 ChatGPT 前端

1. 配置 RAGLite

[!TIP] 🧠 RAGLite 扩展了 LiteLLM，支持使用 llama-cpp-python 的 llama.cpp 模型。要选择一个 llama.cpp 模型（例如来自 Unsloth 的集合)，可以使用形如 "llama-cpp-python/<hugging_face_repo_id>/<filename>@<n_ctx>" 的模型标识符，其中 n_ctx 是可选参数，用于指定模型的上下文大小。

[!TIP] 💾 你可以在 neon.tech 上轻松创建一个 PostgreSQL 数据库。

首先，使用你喜欢的 DuckDB 或 PostgreSQL 数据库以及 LiteLLM 支持的任何 LLM 配置 RAGLite：

from raglite import RAGLiteConfig

# 使用 PostgreSQL 数据库和 OpenAI LLM 的示例“远程”配置：
my_config = RAGLiteConfig(
    db_url="postgresql://my_username:my_password@my_host:5432/my_database",
    llm="gpt-4o-mini",  # 或者任何 LiteLLM 支持的 LLM
    embedder="text-embedding-3-large",  # 或者任何 LiteLLM 支持的嵌入模型
)

# 使用 DuckDB 数据库和 llama.cpp LLM 的示例“本地”配置：
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="llama-cpp-python/unsloth/Qwen3-8B-GGUF/*Q4_K_M.gguf@8192",
    embedder="llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512", # 超过 512 个 token 会降低 bge-m3 的性能
)

你也可以配置 rerankers 支持的任何重排序器：

from rerankers import Reranker

# 基于远程 API 的重排序器示例：
my_config = RAGLiteConfig(
    db_url="postgresql://my_username:my_password@my_host:5432/my_database"
    reranker=Reranker("rerank-v3.5", model_type="cohere", api_key=COHERE_API_KEY, verbose=0)  # 多语言
)

# 按语言划分的本地交叉编码器重排序器示例（这是默认设置）：
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    reranker={
        "en": Reranker("ms-marco-MiniLM-L-12-v2", model_type="flashrank", verbose=0),  # 英语
        "other": Reranker("ms-marco-MultiBERT-L-12", model_type="flashrank", verbose=0),  # 其他语言
    }
)

自查询功能也已支持，允许 LLM 根据用户输入自动生成并应用元数据过滤器，以优化搜索结果。要启用自查询功能，请在 RAGLiteConfig 中将 self_query 设置为 True：

my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="gpt-4o-mini",
    embedder="text-embedding-3-large",
    self_query=True,  # 启用自查询
)

2. 插入文档

[!TIP] ✍️ 若要插入 PDF 以外的文档，请使用 pip install raglite[pandoc] 安装 pandoc 插件。

[!TIP] 🔎 为了获得更高质量的文档处理效果，并实现自动图像描述功能，可使用 pip install raglite[mistral-ocr] 安装 mistral-ocr 插件，并按如下方式配置：

from raglite import RAGLiteConfig, MistralOCRConfig

my_config = RAGLiteConfig(
    document_processor=MistralOCRConfig(
        include_image_descriptions=True,  # 将图片、图表和示意图描述为文本
        image_types=frozenset({"chart", "diagram", "photo", "table", "logo", "icon"}),  # 自定义图片类别
        exclude_image_types=frozenset({"logo", "icon"}),  # 从输出中过滤掉特定类型的图片
    ),
)

image_types 参数定义了 Mistral 对每张图片进行分类的类别——你可以使用默认值，也可以提供自己领域的特定类型。使用 exclude_image_types 可以过滤掉任何对检索无用的已分类类型。

接下来，将一些文档插入数据库。RAGLite 会负责将其转换为 Markdown 格式（src/raglite/_markdown.py）、进行最优的四级语义分块（src/raglite/_split_chunks.py）以及执行延迟分块的多向量嵌入（src/raglite/_embed.py）：

# 根据文件路径插入文档
from pathlib import Path
from raglite import Document, insert_documents

documents = [
    Document.from_path(Path("论智力的测量.pdf")),
    Document.from_path(Path("狭义相对论.pdf")),
]
insert_documents(documents, config=my_config)

# 根据纯文本或 Markdown 内容插入文档
content = """
# 论运动物体的电动力学
## 爱因斯坦 1905年6月30日
众所周知，麦克斯韦……
"""
documents = [
    Document.from_text(content, author="爱因斯坦", topic="物理学", year=1905)
]
insert_documents(documents, config=my_config)

[!TIP] 📝 文档可以通过向 Document.from_text() 或 Document.from_path() 传递关键字参数来包含元数据。这些元数据随后可用于检索时的过滤。 对于列表类型的值，元数据会原样存储（例如 domain=["open", "music"]）。

你还可以在插入之前扩展文档的元数据：

from typing import Annotated
from pydantic import Field
from raglite import expand_document_metadata

# 扩展文档的元数据。
metadata_fields = {
    "title": Annotated[str, Field(..., description="文档标题。")],
    "author": Annotated[str, Field(..., description="主要作者。")],
    "topics": Annotated[list[Literal["A", "B", "C"]], Field(..., description="关键主题。")],
}
documents = list(expand_document_metadata(documents, metadata_fields, config=my_config))

# 根据纯文本或 Markdown 内容插入文档
insert_documents(documents, config=my_config)

3. 检索增强生成 (RAG)

3.1 自适应 RAG

现在你可以运行一个自适应 RAG 流程，该流程包括将用户提示添加到消息历史记录中，并流式传输 LLM 的响应：

from raglite import rag

# 创建用户消息
messages = []  # 或者从现有的消息历史开始
messages.append({
    "role": "user",
    "content": "智力是如何衡量的？"
})

# 自适应地决定是否需要检索并流式传输响应
chunk_spans = []
stream = rag(messages, on_retrieval=lambda x: chunk_spans.extend(x), config=my_config)
for update in stream:
    print(update, end="")

# 获取 RAG 上下文中引用的文档
documents = [chunk_span.document for chunk_span in chunk_spans]

LLM 会根据用户提示的复杂程度自适应地决定是否需要检索信息。如果需要检索，LLM 会生成搜索查询，RAGLite 则会通过混合搜索和重排序来检索最相关的 chunk spans（每个 chunk span 是一系列连续的 chunks）。检索结果会被发送到 on_retrieval 回调函数中，并作为工具输出附加到消息历史记录中。最后，助手的响应会被流式传输并附加到消息历史记录中。

3.2 可编程 RAG

如果你需要手动控制 RAG 流程，可以运行一个简单但强大的流程：首先使用混合搜索和重排序检索最相关的 chunk spans，然后将用户提示转换为 RAG 指令并将其附加到消息历史记录中，最后生成 RAG 响应：

from raglite import add_context, rag, retrieve_context, vector_search

# 选择一种搜索方法
from dataclasses import replace
my_config = replace(my_config, search_method=vector_search)  # 或者 `hybrid_search`、`search_and_rerank_chunks` 等
user_prompt = "智力是如何衡量的？"
chunk_spans = retrieve_context(
    query=user_prompt, 
    num_chunks=5, 
    metadata_filter={"author": "爱因斯坦"},  # 可选：按元数据过滤
    config=my_config
)

# 根据用户提示和上下文向消息历史中追加一条 RAG 指令
messages = []  # 或者从现有的消息历史开始
messages.append(add_context(user_prompt=user_prompt, context=chunk_spans, config=my_config))

# 流式输出 RAG 响应并将其追加到消息历史中
stream = rag(messages, config=my_config)
for update in stream:
    print(update, end="")

# 访问 RAG 上下文中引用的文档
documents = [chunk_span.document for chunk_span in chunk_spans]

[!TIP] 🥇 重排序可以显著提升 RAG 应用程序的输出质量。要在你的应用程序中添加重排序功能：首先搜索更大规模的 20 个相关块，然后使用 rerankers 提供的重排序器对这些块进行重排序，最后保留前 5 个块。

RAGLite 还提供了对完整 RAG 流程中各个步骤更高级的控制：

1. 使用关键词、向量或混合搜索查找相关块
2. 从数据库中检索这些块
3. 对块进行重排序并选择前 5 个结果
4. 扩展块及其邻近块，并将它们分组为块跨度
5. 将用户提示转换为 RAG 指令并将其追加到消息历史中
6. 将 LLM 响应流式传输到消息历史中
7. 从块跨度中访问引用的文档

使用 RAGLite 实现完整的 RAG 流程非常简单：

# 搜索块
from raglite import hybrid_search, keyword_search, vector_search

user_prompt = "如何衡量智力？"
chunk_ids_vector, _ = vector_search(user_prompt, num_results=20, config=my_config)
chunk_ids_keyword, _ = keyword_search(user_prompt, num_results=20, config=my_config)
chunk_ids_hybrid, _ = hybrid_search(
    user_prompt, num_results=20, metadata_filter={"topic": "physics"}, config=my_config
)  # 过滤结果，仅包含主题为“物理”的文档中的块（适用于任何搜索方法）

# 在单个字段中使用多值过滤器时采用 OR 语义：
chunk_ids_or, _ = hybrid_search(
    user_prompt,
    num_results=20,
    metadata_filter={"domain": ["open", "music"]},
    config=my_config,
)  # 返回 domain 包含 "open" 或 "music" 的块。

# 检索块
from raglite import retrieve_chunks

chunks_hybrid = retrieve_chunks(chunk_ids_hybrid, config=my_config)

# 对块进行重排序并保留前 5 个（可选，但建议）
from raglite import rerank_chunks

chunks_reranked = rerank_chunks(user_prompt, chunks_hybrid, config=my_config)
chunks_reranked = chunks_reranked[:5]

# 扩展块及其邻近块，并将其分组为块跨度
from raglite import retrieve_chunk_spans

chunk_spans = retrieve_chunk_spans(chunks_reranked, config=my_config)

# 根据用户提示和上下文向消息历史中追加一条 RAG 指令
from raglite import add_context

messages = []  # 或者从现有的消息历史开始
messages.append(add_context(user_prompt=user_prompt, context=chunk_spans, config=my_config))

# 流式输出 RAG 响应并将其追加到消息历史中
from raglite import rag

stream = rag(messages, config=my_config)
for update in stream:
    print(update, end="")

# 访问 RAG 上下文中引用的文档
documents = [chunk_span.document for chunk_span in chunk_spans]

4. 计算并使用最优查询适配器

RAGLite 可以计算并应用一个 最优闭式查询适配器 到提示嵌入中，以提高 RAG 的输出质量。要从中受益，首先使用 insert_evals 生成一组评估数据，然后使用 update_query_adapter 计算并存储最优查询适配器：

# 使用最优查询适配器改进 RAG
from raglite import insert_evals, update_query_adapter

insert_evals(num_evals=100, config=my_config)
update_query_adapter(config=my_config)  # 从此以后，每次向量搜索都会使用该查询适配器

5. 检索与生成的评估

如果你安装了 ragas 附加组件，就可以使用 RAGLite 回答评估问题，然后使用 Ragas 评估 RAG 检索和生成两个步骤的质量：

# 评估检索和生成
from raglite import answer_evals, evaluate, insert_evals

insert_evals(num_evals=100, config=my_config)
answered_evals_df = answer_evals(num_evals=10, config=my_config)
evaluation_df = evaluate(answered_evals_df, config=my_config)

6. 运行模型上下文协议 (MCP) 服务器

RAGLite 自带一个基于 FastMCP 实现的 MCP 服务器，它公开了一个 search_knowledge_base 工具。要使用该服务器：

1. 安装 Claude 桌面版
2. 安装 uv，以便 Claude 桌面版能够启动服务器
3. 配置 Claude 桌面版使用 uv 启动 MCP 服务器，命令如下：

raglite \
    --db-url duckdb:///raglite.db \
    --llm llama-cpp-python/unsloth/Qwen3-4B-GGUF/*Q4_K_M.gguf@8192 \
    --embedder llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512 \
    mcp install

如果使用基于 API 的 LLM，请确保将凭据放入 .env 文件中，或直接在命令行中提供：

export OPENAI_API_KEY=sk-...
raglite \
    --llm gpt-4o-mini \
    --embedder text-embedding-3-large \
    mcp install

现在，当你启动 Claude 桌面版时，应该会在提示框的右下角看到一个 🔨 图标，表明 Claude 已成功连接到 MCP 服务器。

在适当的时候，Claude 会建议使用 MCP 服务器提供的 search_knowledge_base 工具。你也可以明确要求 Claude 搜索知识库，以确保它一定会执行此操作。

7. 提供可自定义的类 ChatGPT 前端

如果你安装了 chainlit 附加组件，你可以通过以下命令提供一个可自定义的类 ChatGPT 前端：

raglite chainlit

该应用还可以部署到 web、Slack 和 Teams 平台。

你可以在 Chainlit 前端直接指定数据库 URL、LLM 和嵌入器，也可以通过 CLI 指定，如下所示：

raglite \
    --db-url duckdb:///raglite.db \
    --llm llama-cpp-python/unsloth/Qwen3-4B-GGUF/*Q4_K_M.gguf@8192 \
    --embedder llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512 \
    chainlit

如果要使用基于 API 的 LLM，请确保将你的凭据添加到 .env 文件中，或者直接在命令行中提供：

OPENAI_API_KEY=sk-... raglite --llm gpt-4o-mini --embedder text-embedding-3-large chainlit

贡献

先决条件

1. 生成 SSH 密钥并 将 SSH 密钥添加到你的 GitHub 账户。

2. 配置 SSH 自动加载你的 SSH 密钥：

   cat << EOF >> ~/.ssh/config
   
   Host *
     AddKeysToAgent yes
     IgnoreUnknown UseKeychain
     UseKeychain yes
     ForwardAgent yes
   EOF
   

3. 安装 Docker Desktop。

4. 安装 VS Code 和 VS Code 的 Dev Containers 扩展。或者，也可以安装 PyCharm。

5. 可选: 安装一种 Nerd Font，例如 FiraCode Nerd Font，并 配置 VS Code 或 PyCharm 使用它。

开发环境

支持以下开发环境：

1. ⭐️ GitHub Codespaces: 点击 在 GitHub Codespaces 中打开 即可在浏览器中开始开发。

2. ⭐️ VS Code Dev Container (带容器卷): 点击 在 Dev Containers 中打开 将此仓库克隆到容器卷中，并使用 VS Code 创建一个 Dev Container。

3. ⭐️ uv: 克隆此仓库，在仓库根目录下运行以下命令：

   # 创建并安装虚拟环境
   uv sync --python 3.10 --all-extras
   
   # 激活虚拟环境
   source .venv/bin/activate
   
   # 安装 pre-commit 钩子
   pre-commit install --install-hooks
   

4. VS Code Dev Container: 克隆此仓库，用 VS Code 打开，然后按 Ctrl/⌘ + ⇧ + P → Dev Containers: 在容器中重新打开。

5. PyCharm Dev Container: 克隆此仓库，用 PyCharm 打开，创建带有挂载源的 Dev Container，并在 /opt/venv/bin/python 处 配置现有的 Python 解释器。

开发

• 本项目遵循 Conventional Commits 标准，以借助 Commitizen 自动化 语义版本控制 和 Keep A Changelog。
• 在开发环境中运行 poe 可以打印出适用于该项目的 Poe the Poet 任务列表。
• 在开发环境中运行 uv add {package} 可以安装运行时依赖项，并将其添加到 pyproject.toml 和 uv.lock 中。添加 --dev 参数可以安装开发依赖项。
• 在开发环境中运行 uv sync --upgrade 可以将所有依赖项升级到 pyproject.toml 允许的最新版本。添加 --only-dev 参数则仅升级开发依赖项。
• 运行 cz bump 可以提升软件包版本、更新 CHANGELOG.md 并创建一个 Git 标签。随后使用 git push origin main --tags 推送更改和 Git 标签。

星标历史

RAGLite 快速上手指南

RAGLite 是一个轻量级、高性能的 Python RAG（检索增强生成）工具包，支持 DuckDB 或 PostgreSQL 数据库，兼容本地模型与云端大模型。

环境准备

• 系统要求：macOS、Linux 或 Windows
• Python 版本：3.10 / 3.11 / 3.12
• 可选加速：
  • macOS：Metal 加速
  • Linux/Windows：CUDA 加速（需安装对应版本的 llama-cpp-python）

💡 若使用本地大模型（如 llama.cpp），推荐预先安装加速版二进制文件：

LLAMA_CPP_PYTHON_VERSION=0.3.9
PYTHON_VERSION=312
ACCELERATOR=metal  # 或 cu124（根据平台选择）
PLATFORM=macosx_11_0_arm64  # 或 linux_x86_64 / win_amd64

pip install "https://github.com/abetlen/llama-cpp-python/releases/download/v$LLAMA_CPP_PYTHON_VERSION-$ACCELERATOR/llama_cpp_python-$LLAMA_CPP_PYTHON_VERSION-cp$PYTHON_VERSION-cp$PYTHON_VERSION-$PLATFORM.whl"

安装步骤

基础安装：

pip install raglite

按需扩展功能：

# 添加 Chainlit 前端支持（类似 ChatGPT 的 Web 界面）
pip install raglite[chainlit]

# 支持更多文档格式（DOCX, PPTX 等，需 Pandoc）
pip install raglite[pandoc]

# 启用高质量 OCR 文档处理（含图像描述）
pip install raglite[mistral-ocr]

# 添加 RAG 性能评估支持
pip install raglite[ragas]

基本使用

1. 配置 RAGLite

支持远程（PostgreSQL + OpenAI）或本地（DuckDB + llama.cpp）配置：

from raglite import RAGLiteConfig

# 本地配置示例（DuckDB + 本地模型）
my_config = RAGLiteConfig(
    db_url="duckdb:///raglite.db",
    llm="llama-cpp-python/unsloth/Qwen3-8B-GGUF/*Q4_K_M.gguf@8192",
    embedder="llama-cpp-python/lm-kit/bge-m3-gguf/*F16.gguf@512",
)

2. 插入文档

支持 PDF、Markdown 或纯文本，自动完成分块、嵌入与索引：

from pathlib import Path
from raglite import Document, insert_documents

# 从文件路径插入
documents = [
    Document.from_path(Path("example.pdf")),
]
insert_documents(documents, config=my_config)

# 从文本内容插入（可附带元数据）
content = "# 相对论\n由爱因斯坦提出..."
documents = [
    Document.from_text(content, author="Einstein", topic="physics", year=1905)
]
insert_documents(documents, config=my_config)

3. 执行 RAG 查询

调用 rag 函数进行自适应检索与生成：

from raglite import rag

messages = [{"role": "user", "content": "什么是狭义相对论？"}]
response = rag(messages, config=my_config)

print(response["content"])

即可完成一次完整的检索增强生成流程。