RAGLite：把 RAG 流水线压缩进 DuckDB 或 PostgreSQL 的 Python 工具包
🥤 RAGLite is a Python toolkit for Retrieval-Augmented Generation (RAG) with DuckDB or PostgreSQL
秒懂
- 它是什么？
- RAGLite 用 LiteLLM 接入模型、用 DuckDB 或 PostgreSQL 同时承担关键词与向量检索，把分块、检索、查询适配和评测串成一条可配置的链路。它的价值在于依赖轻、环节可换，代价是它不替你决定架构，配置与数据准备都得自己动手。
- 适合谁用？
- 如果你已经选定 LiteLLM 支持的模型，并且愿意把检索层放在 DuckDB 或 PostgreSQL 上，RAGLite 值得先跑通插入文档与混合检索这两步，再决定是否引入查询适配器和 Ragas 评测。如果你需要的是开箱即用的托管式问答服务，或者团队不接受自己维护数据库与嵌入模型，它就不合适。
- 能商用吗？
- 可以，但有条件。MPL-2.0 是弱 copyleft 许可证：可以用在商业和闭源软件里，但如果你分发了对它自身文件的修改，这些修改必须以同一许可证公开。
- 还在维护吗？
- 在维护。仓库最近一次提交在 30 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它替谁省掉了哪一段工作
做 RAG 的团队通常卡在同一个位置：检索这一层要同时处理关键词匹配和向量相似度，而这两套东西往往分散在不同组件里。RAGLite 的判断是把它们压回数据库本身。README 写明它使用数据库原生的关键词与向量检索，DuckDB 走 FTS 加 VSS 扩展，PostgreSQL 走 tsvector 加 pgvector。这意味着你不需要额外部署一个向量数据库，也不需要自己写融合两路结果的排序逻辑。
目标读者是已经会用 Python 写数据管道、并且清楚自己要接哪个模型的人。README 的配置示例直接把 RAGLiteConfig 作为入口，模型通过 LiteLLM 的标识符指定，本地模型则用 llama-cpp-python 的形式。它假设你愿意读配置文档，而不是点几下按钮就得到答案。
混合检索与多向量分块如何拼在一起
从 README 列出的机制看，数据流大致是：文档先转成 Markdown，再做分块与嵌入，写入数据库；查询时关键词检索和向量检索各出一路结果，融合后交给重排器，最后进 LLM。
分块这一段不是简单的定长切分。README 提到它用 wtpsplit-lite 做句子切分，把切分当作二元整数规划问题求解，语义分块同样如此。嵌入侧采用 late chunking，也就是先对整段文本编码再切出块向量，同时给块加上上下文标题。这两步的目的都是减少块脱离上下文后语义漂移的问题。检索之后接的是 rerankers 支持的重排器，默认是支持多语言的 FlashRank。
值得注意的是自适应检索这一项：README 说由 LLM 判断是否需要检索、以及检索什么。这是一个把控制权交给模型的取舍，省掉了一次固定检索的开销，但也让行为更难预测，调试时你看到的是模型的判断而不是一条确定的规则。
安装与配置里真正要动手的地方
基础安装是一条命令：pip install raglite。前端、其他文件格式、评测分别对应三个 extra：raglite[chainlit]、raglite[pandoc]、raglite[ragas]。Mistral OCR 不在 extra 里，README 要求单独 pip install mistralai。
本地模型这一段最容易踩坑。README 的提示给出了安装预编译二进制的做法，需要先确定四个变量：LLAMA_CPP_PYTHON_VERSION、PYTHON_VERSION、ACCELERATOR、PLATFORM，然后拼出 wheel 的 URL 交给 pip。README 自己加了一句警告，说并非所有组合都存在。加速器可选 metal、cu121 到 cu124，平台可选 macosx_11_0_arm64、linux_x86_64、win_amd64。选 llama.cpp 模型时，模型标识符的格式是 llama-cpp-python/<hugging_face_repo_id>/<filename>@<n_ctx>，其中 n_ctx 可选，用来指定上下文长度。
数据库方面，README 提到可以在 neon.tech 上点几下建一个 PostgreSQL 库。至于 DuckDB 路径下 FTS 与 VSS 扩展是否需要手动加载，材料里没有说明，这一点需要你自己确认。
依赖策略的代价落在哪里
README 把「只依赖轻量且许可宽松的开源库」列为特性，点名不引入 PyTorch 和 LangChain。这个选择的直接后果是安装体积和依赖冲突面都小，但也意味着凡是依赖 PyTorch 的嵌入模型或重排器，你都不能直接用。默认重排器选 FlashRank 而不是更强的交叉编码器，和这条约束是一致的。
许可证是 MPL-2.0，属于文件级的弱 copyleft。你可以把它和闭源代码放在一起分发，但被修改过的 RAGLite 源文件本身需要以 MPL 条款公开。这是对许可证性质的描述，具体用法仍应交给法务判断。
另一个现实问题是版本节奏。仓库的发布记录显示 v0.7.0 在 2025 年 3 月，v1.0.0 在 2025 年 6 月，v1.1.1 在 2026 年 5 月。中间跨度接近一年，说明 1.x 之后 API 趋于稳定，但也说明小版本修复不会来得很快。升级前需要自己读 release notes，因为材料里没有给出向后兼容承诺。
什么时候它不该出现在你的技术栈里
RAGLite 不托管任何东西。数据库要你自己准备，嵌入模型要你自己选，检索质量出问题时也没有一层抽象替你兜底。如果团队里没有能读 Python 配置、能调数据库扩展的人，这套东西会变成负担。
它对 PostgreSQL 路径有一个隐含前提：pgvector 和 tsvector 都得就位。README 没有展开安装步骤，只说了用哪个扩展。如果你的 PostgreSQL 是托管服务且不允许装扩展，这条路径直接走不通。
自适应检索和查询适配器这两项也带有实验性质。README 把查询适配器描述为求解正交 Procrustes 问题得到的闭式线性解，代码在 src/raglite/_query_adapter.py。这类方法的效果高度依赖你的查询分布，材料里没有给出任何评测数字，所以不要把它当作默认收益。
最后，如果你的文档以扫描件和复杂版式为主，PDF 转 Markdown 走的是 pdftext 加 pypdfium2，README 把 Mistral OCR 列为可选的高质量替代。要不要为质量付费，得看你自己的样本。
和直接拼 LangChain 的差别在哪
最常见的替代方案是用 LangChain 或 LlamaIndex 这类框架自己组装。差别不在功能清单，而在控制点放在哪一层。
LangChain 的抽象层更多，换一个向量库或换一个检索策略通常改配置或换类；代价是依赖树更深，出问题时你要在多层封装之间定位。RAGLite 把检索下沉到数据库原生能力，融合和重排都在自己的代码里，链路更短，但你换数据库时能复用的部分也更少。README 明确把不依赖 LangChain 写成一条设计选择，这本身就说明两者的取舍方向相反。
另一条路是直接用 pgvector 加一段自己写的检索代码。这样最灵活，但 late chunking、上下文标题、句子切分的整数规划、查询适配器这些都得自己实现。RAGLite 提供的是这些具体机制的现成实现，而不是一层通用编排。
接入方式：MCP 服务端与 Chainlit 前端
README 列出两种对外暴露的方式。一种是内置的 Model Context Protocol 服务端，任何 MCP 客户端都可以连接，README 举的例子是 Claude desktop。另一种是可选的 Chainlit 前端，形态接近 ChatGPT，README 给出的部署目标包括 web、Slack 和 Teams。
这两条路径的定位不同。MCP 服务端适合把检索能力挂到已有的助手客户端上，你不需要自己做界面。Chainlit 前端适合你要给非技术用户一个独立入口的场景，代价是多一层部署和运维。
两者都是可选的，基础安装不含 Chainlit，需要装 raglite[chainlit]。材料里没有说明 MCP 服务端的启动命令和配置项，这部分需要查仓库文档。
评测与文档处理的可选项
README 把 Ragas 列为可选依赖，用于评测检索与生成的表现，安装方式是 raglite[ragas]。对一个检索策略可换、重排器可换的工具包来说，有没有评测决定了你能不能判断某次改动是变好还是变坏。这一点上，把评测做成可选是合理的，但你必须主动把它装上，否则调参只能靠感觉。
文档处理有两层。基础层是 PDF 转 Markdown，基于 pdftext 和 pypdfium2。扩展层是 Pandoc，装 raglite[pandoc] 之后可以处理 PDF 以外的格式。再往上是 Mistral OCR，覆盖 PDF、图片、DOCX 和 PPTX，并且带自动图片描述，需要单独装 mistralai。三条路径的质量和成本依次上升，README 没有给出它们之间的对比数据。
编辑结论
如果你已经选定 LiteLLM 支持的模型，并且愿意把检索层放在 DuckDB 或 PostgreSQL 上，RAGLite 值得先跑通插入文档与混合检索这两步，再决定是否引入查询适配器和 Ragas 评测。如果你需要的是开箱即用的托管式问答服务，或者团队不接受自己维护数据库与嵌入模型，它就不合适。动手前先确认三件事：你的数据库是否已装好 FTS 与 VSS 扩展，或者 PostgreSQL 是否已启用 tsvector 与 pgvector；你打算用的 LLM 标识符在 LiteLLM 中是否可用；以及你选的 llama-cpp-python 预编译二进制是否覆盖你的 Python 版本与加速器组合。
社区笔记