RAGLight

RAGLight：轻量级模块化 RAG 框架，让文档问答触手可及

从「AI 听不懂我的文档」说起

想象一个场景：你在公司内部部署了一个 AI 助手，问它「我们Q3的技术路线是什么」，它却一本正经地编造答案——因为它根本没有读过你的文档。检索增强生成（Retrieval-Augmented Generation, RAG） 就是来解决这个问题的：让 AI 先去文档库里「查资料」，再基于真实内容作答。

然而，从零搭建一套 RAG 系统往往意味着写大量胶水代码：接向量数据库、配 Embedding 模型、调 LLM 接口、搭查询路由……门槛不低。RAGLight 正是为了降低这个门槛而生的——一个 Python 轻量级框架，通过模块化设计和流畅的 API，让你用几行代码就跑通一套完整的 RAG 流程。

项目背景与作者

RAGLight 由法国开发者 Bessouat40（Roman Bessouat）于 2024 年初创建并持续维护，遵循 MIT 许可证开源。项目当前版本 3.4.7，支持 Python 3.11+，在 GitHub 上已积累 663 Stars 和 101 Forks，社区活跃度相当可观。项目配套了完整的 Mintlify 文档站点（raglight.mintlify.app），覆盖从安装到高级用法的全流程指南。

作者将 RAGLight 定位为「快速原型 + 本地实验」工具，强调轻量、灵活、可组合，与 LangChain/LlamaIndex 等重量级框架形成差异化竞争。框架的命名也体现了这一定位——Light，意味着不过度抽象、不过度封装，让用户看得见每一层的运作逻辑。

核心功能：模块化 RAG 管道

RAGLight 的核心架构围绕 三大可插拔组件 展开：

LLM 层（语言模型）：支持 7 家主流提供商——Ollama（本地）、OpenAI、Google Gemini、Mistral AI、LMStudio（本地）、AWS Bedrock（Claude/Titan/Llama）和 vLLM。无论你想用哪种模型，换一个参数就能切换，无需重写业务逻辑。

Embedding 层（向量化模型）：同样可插拔，支持 HuggingFace sentence-transformers（默认 all-MiniLM-L6-v2）、Ollama、OpenAI、Gemini 和 AWS Bedrock Embeddings。向量模型的选择直接影响检索质量，RAGLight 让对比不同 Embedding 模型变得轻而易举。

VectorStore 层（向量数据库）：支持 ChromaDB（默认）和 Qdrant 两种后端。ChromaDB 轻量易用，Qdrant 则适合生产级大规模部署。通过 Builder 模式，几行代码就能初始化一个向量数据库：

from raglight.rag.builder import Builder

rag = (Builder()
    .with_embeddings("HUGGINGFACE")
    .with_vector_store("CHROMA", persist_directory="./db")
    .with_llm("OLLAMA", model="llama3")
    .with_k(5)
    .build())

Agentic RAG：让 AI 自己决定怎么查

除了基础的「检索 → 生成」管道，RAGLight 还支持 Agentic RAG——让 LLM 扮演 Agent，自己决定是否需要查询、查询哪些内容、如何综合答案。这基于 LangGraph 实现，框架内置了 RetrieverTool 和 ClassRetrieverTool 两个工具，Agent 可以调用它们访问向量数据库。

更强大的能力是 MCP（Model Context Protocol）集成。通过 MCP，Agentic RAG 可以连接外部工具和数据源——比如连接代码执行环境、数据库、甚至 GitHub API。示例代码中直接指定 MCP 服务地址，框架自动完成握手和工具发现：

config = AgenticRAGConfig(
    provider="OPENAI",
    model="gpt-4o",
    k=10,
    mcp_config=[{"url": "http://127.0.0.1:8001/sse"}]
)

高级特性：混合搜索与可观测性

混合搜索（Hybrid Search） 是 RAGLight 的一大亮点。它将 BM25 关键词检索 与 语义向量检索 结合，再用 RRF（Reciprocal Rank Fusion） 算法融合两路结果，兼顾精确关键词匹配和语义理解。这对技术文档场景特别有效——既能找到包含确切术语的段落，又不会遗漏语义相关但表述不同的内容。

查询改写（Query Reformulation） 解决了多轮对话中的经典难题：用户的追问往往省略了上下文（「那其他供应商呢？」），框架会自动结合对话历史将追问改写为独立查询，提升检索准确性。

可观测性（Langfuse 集成）：RAGLight v3+ 支持 Langfuse 端到端追踪，覆盖检索→重排序→生成全链路，开发者可以在 Langfuse Dashboard 中直观看到每次 RAG 调用的性能瓶颈和中间结果。

多入口体验：从 CLI 到 API 到 Web UI

RAGLight 提供三种使用方式，适合不同场景：

• CLI 向导（raglight chat）：交互式问答式引导，无需写代码，适合快速验证想法
• REST API（raglight serve）：基于 FastAPI 的 HTTP 服务，附带 docker-compose.yml 示例，一条命令启动，带 Web UI 聊天界面
• Python SDK：Builder 模式和直接的 pipeline 类调用，灵活集成到现有系统

Streamlit Web UI 界面采用深色主题设计，侧边栏可配置 LLM 提供商、模型、Embedding 模型等参数，主区域展示对话历史，底部输入框接收用户提问。API 端点包括 /health、/config、/query（POST）等。

部署评估

RAGLight 的部署非常友好：核心库通过 pip install raglight 一键安装，向量数据库按需安装（推荐 pip install "raglight[qdrant]"——Qdrant 纯 Python 实现，Windows 友好）。如果想快速体验 REST API + Web UI，只需运行：

# 启动 raglight serve
raglight serve
# 然后在浏览器打开 Web UI

examples 目录提供了完整的 docker-compose.yml，Docker 镜像基于 python:3.12-slim，在容器内通过 pip 安装 raglight 并运行服务，对本地没有 Python 环境但有 Docker 的用户非常友好。

硬件需求方面，RAGLight 本身是纯 Python 实现，不需要 GPU，但作为 AI 应用，运行 LLM 推理需要相应计算资源——本地 Ollama 推荐 4GB+ 内存的机器，使用云端 API（OpenAI/Gemini）则只需能联网的轻量设备。

技术架构：站在 LangChain 肩膀上

深入代码层面，RAGLight 的技术栈很有意思：它大量依赖 LangChain（langchain-core、langchain-text-splitters、langchain-ollama/openai/mistralai 等），但在上层构建了自己的抽象层和 Builder 模式。LangGraph 被用于实现 Agentic RAG 的状态机，sentence-transformers 处理 Embedding 向量化，pymupdf 处理 PDF 文档解析。

RAG 核心类基于 LangGraph StateGraph 实现，状态包含 question、answer、context（文档列表）和 history（对话历史），图中有检索节点和生成节点，支持多轮对话和查询改写。文档处理管道则支持 PDF、TXT、DOCX、Python、JavaScript 等多种格式，通过工厂模式管理不同的处理器。

测试覆盖也相当完善：单元测试分布在 tests/ 目录，涉及 embeddings、llm、rag、vector store 等各模块，GitHub Actions CI 每次 PR 都会运行测试套件。

行业意义与局限

RAGLight 代表了一个趋势：RAG 框架从「全家桶」向「乐高化」演进。它不追求覆盖所有边缘场景，而是把核心链路做到极致流畅，降低尝鲜门槛。这种定位让它特别适合：

• AI 开发者快速验证 RAG 想法
• 数据科学团队搭建文档问答原型
• 企业内部知识库建设的起步阶段

局限性也需要正视：框架目前没有生产级高可用部署方案（无 Kubernetes manifest），Agentic RAG 的 Agent 策略相对固定不支持自定义规划逻辑，MCP 集成尚在早期。这些都是未来可以深耕的方向。

总体而言，RAGLight 是一个定位清晰、工程质量不错的 RAG 入门框架。对于想快速体验 RAG 流程、或在项目中快速集成文档问答能力的开发者，它是一个值得一试的选择。