RAGLight
轻量模块化的 Python RAG 框架，可自由替换 LLM、嵌入模型与向量库，让基于文档问答的应用搭建变得即插即用。
凭证经由环境变量/.env.example 管理，未在代码中硬编码（在所示证据中未见泄漏）；MCP 与 GitHub 抓取均需用户显式配置，数据流向（本地目录、GitHub URL、向量库）在 README 中说明较清楚。扣分点：Agentic 管道与 MCP 工具调用没有任何用户确认机制；CI 依赖审查工作流通过 allow-ghsas 显式放行了四个已知安全通告，属于对已知漏洞的未缓解绕过；ingest 端点可让服务器抓取任意 GitHub 仓库并写盘，无回滚或恢复机制说明；检索结果对原文来源的引用/归属未见文档化。
README 与 pyproject 总体一致（版本 3.4.7、Extras 表与 pyproject 可选依赖吻合）。扣分点：tests/__init__.py 需要伪造 langgraph.prebuilt.tool_node 符号才能让 langchain 1.2.0 导入成功，证明核心依赖组合存在版本兼容问题；CI 中 'unsafe-best-match' 索引策略放大依赖漂移风险；失败消息、错误处理路径在证据中几乎未展示。
面向从 CLI 新手（raglight chat 向导）到自建管道的开发者，多提供商（Ollama/OpenAI/Gemini/Mistral/Bedrock/vLLM）与 Windows 差异（C++ 编译器）均有交代，受众与场景描述充分。扣分点：Agent 的工具选择/触发精度仅由默认 prompt 决定，未展示；能力边界（如最大文档规模、索引性能）未量化说明。
README 结构完整（目录、安装、CLI、API、Docker、环境变量表、大量示例），pyproject 元数据规范，MIT 许可证全文在库。扣分点：没有 CHANGELOG，版本仅在 pyproject 中；无已知限制章节，仅有零散注意事项；CI 自动以 black 格式化并直接提交到 PR 分支的做法不利于审查；维护者为单人（Bessouat40），长期维护承诺证据有限。
输出可用性好：流式生成、多轮历史、CLI 向导、Streamlit UI、REST+Swagger 文档齐全，边际价值在于轻量模块化 RAG + MCP 集成。扣分点：成本效益受基础依赖列表拖累（streamlit、fastapi、transformers、sentence-transformers 等全部默认安装），与'轻量'定位自相矛盾，且检索质量、与同类框架的对比收益无证据支撑。
pyproject 与 README 的依赖/特性陈述大体可交叉核对，CI badge 与工作流文件对应。扣分点：性能与'提升 RAG 表现'等宣传性说法无基准数据或第三方佐证，主要来源是 README 自述；tests/ 目录证据极薄（仅配置常量与兼容性 stub），核心管道无可见测试体，降低可验证性。
- CI 依赖审查通过 allow-ghsas 放行了四个已知安全通告（GHSA-f4j7-r4q5-qw2c 等），部署前应自行核查这些漏洞是否影响你的依赖版本。
- raglight serve 默认绑定 0.0.0.0:8000 且无鉴权说明，/ingest 可触发服务器端 GitHub 克隆与任意目录索引，切勿直接暴露在公网。
- Agentic 管道与 MCP 服务器交互无任何用户确认或工具白名单机制，接入的 MCP 服务器将获得与配置等价的能力。
- 基础依赖非常重（streamlit、fastapi、transformers 等默认安装），且测试代码表明 langchain/langgraph 版本存在兼容性问题，升级需谨慎。
- 无 CHANGELOG，版本演进只能靠 pyproject 推断；核心管道的测试覆盖在证据中不可见。
这个 Agent 能做什么，适合哪些场景？
RAGLight 是一个用于构建检索增强生成（RAG）应用的 Python 库，通过 Builder 与 RAGPipeline 两套 API 将文档检索与大模型推理整合为统一流程。它对 LLM 提供商不可知，支持 Ollama、LMStudio、vLLM、OpenAI、Mistral、Google Gemini 和 AWS Bedrock；向量库支持 ChromaDB 与 Qdrant，均可本地或远程运行。除标准 RAG 流水线外，还提供 Agentic RAG 流水线，并可通过 MCP 服务器接入代码执行、数据库等外部工具。部署形态包括交互式 CLI 向导（raglight chat / raglight agentic-chat）、基于 FastAPI 的 REST 服务（raglight serve，可附带 Streamlit 聊天界面）以及 Docker / Docker Compose。检索方面支持语义、BM25 与 RRF 混合搜索、查询改写、多轮对话历史、逐 token 流式输出，并可通过 Langfuse 进行端到端观测。
RAGLight 读取本地文件夹或 GitHub 仓库（FolderSource / GitHubSource），按扩展名用内置处理器（PDFProcessor、CodeProcessor、TextProcessor，可自定义替换，包括基于 VLM 的 PDF 处理器）解析 PDF、TXT、DOCX 及多种代码文件，嵌入后写入 ChromaDB 或 Qdrant 向量库（本地磁盘或远程 HTTP）。生成时按 reformulate → retrieve → rerank → generate 流程执行：自动将追问改写为独立查询，支持 semantic / bm25 / hybrid（RRF 融合）三种检索方式，再交由所选 LLM 生成答案。API 包括 RAGPipeline / AgenticRAGPipeline 高层接口、Builder 链式构建器（with_embeddings / with_vector_store / with_llm），AgenticRAGConfig 可配置 mcp_config 接入 MCP 服务器。CLI 提供 raglight chat 与 raglight agentic-chat 交互式向导；raglight serve 启动 FastAPI 服务，暴露 /health、/generate、/ingest、/ingest/upload、/collections、/config 端点，全部由 RAGLIGHT_* 环境变量配置，可加 --ui 同时启动 Streamlit 聊天界面。所有提供商支持 generate_streaming() 流式输出与 max_history 多轮对话历史，并可接入 Langfuse 追踪每个 RAG 调用。
- 想在本地（如 Ollama + Qdrant）搭建私有文档问答系统、数据不出本机的开发者
- 需要为企业知识库提供 REST API，让其他应用通过 /generate 端点查询文档的后端团队
- 已有 OpenAI / Mistral / Gemini API key，希望以最小组件改动切换不同 LLM 提供商的工程师
- 处理多轮对话且用户常以「那 Python 呢？」之类追问的场景，需要查询改写与对话历史的应用
- 向量检索召回不足、需要 BM25 与语义检索 RRF 混合融合提升精度的检索系统维护者
- 希望给 Agent 接入代码执行、数据库等外部工具链的 Agentic RAG 实验者（通过 MCP 服务器）
这个 Agent 有哪些优点和局限？
- LLM 与向量库完全可插拔：Ollama、LMStudio、vLLM、OpenAI、Mistral、Gemini、Bedrock 七种 LLM 提供商与 Chroma/Qdrant 两种向量库可自由组合，避免单一厂商锁定
- 检索能力超出基础 RAG：BM25 + 语义 + RRF 混合搜索、查询改写、可选 rerank，多轮对话场景下召回精度更高
- 部署形态完整：CLI 交互向导、FastAPI REST 服务、Streamlit UI、Docker/Docker Compose，从个人试用到生产服务均有现成路径
- 通过 mcp_config 即可接入 MCP 服务器，为 Agent 增加代码执行、数据库查询等外部工具能力
- 内置 Langfuse 观测，retrieve / rerank / generate 每个环节可端到端追踪
- ChromaDB 后端在 Windows 上需要 C++ 编译器，环境配置成本较高（Qdrant 可绕过）
- 云端提供商（OpenAI、Mistral、Gemini、Bedrock）均需配置 API key 与凭证，本地提供商（LMStudio）要求模型预先加载
- 使用 Langfuse 观测需额外安装 raglight[langfuse] 并部署/配置 Langfuse 服务（如 localhost:3000），否则追踪不可用
- 较新的 Claude 模型在 Bedrock 上需使用跨区域 inference profile ID（us./eu./ap. 前缀），配置有额外细节
- README 中未见基准评测或性能数据，检索质量提升（如 RRF 带来的增益）缺乏量化证据，需要自行验证
如何安装或部署这个 Agent？
基础安装：pip install raglight
向量库与观测按需安装 extras：
pip install "raglight[qdrant]" # Qdrant（纯 Python，Windows 友好）
pip install "raglight[chroma]" # ChromaDB（Windows 需 C++ 编译器）
pip install "raglight[chroma,qdrant]" # 两者都要
pip install "raglight[qdrant,langfuse]" # Qdrant + Langfuse 观测
使用 Ollama 本地推理需先运行 Ollama 并拉取模型；使用 Mistral / OpenAI / Gemini 需设置对应 API key 环境变量；使用 AWS Bedrock 需配置 AWS 凭证（环境变量、~/.aws/credentials 或 IAM role）。使用 LMStudio 需先在其中加载目标模型。
如何使用这个 Agent？
最快上手——CLI 向导（需先运行 Ollama）：
raglight chat # 标准向导，逐步选择文档目录、向量库、嵌入模型、LLM
raglight agentic-chat部署 REST API：
raglight serve --port 8000 --ui # FastAPI + Swagger(/docs) + Streamlit UI(8501)
RAGLIGHT_LLM_MODEL=mistral-small-latest RAGLIGHT_LLM_PROVIDER=Mistral raglight servePython 高层 API：
from raglight.rag.simple_rag_api import RAGPipeline
from raglight.config.settings import Settings
from raglight.config.rag_config import RAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.models.data_source_model import FolderSource, GitHubSourcevector_store_config = VectorStoreConfig(embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
provider=Settings.HUGGINGFACE,
database=Settings.CHROMA,
persist_directory='./defaultDb',
collection_name=Settings.DEFAULT_COLLECTION_NAME)config = RAGConfig(llm=Settings.DEFAULT_LLM, provider=Settings.OLLAMA, k=5,
knowledge_base=[FolderSource(path='./docs'), GitHubSource(url='https://github.com/Bessouat40/RAGLight')])
pipeline = RAGPipeline(config, vector_store_config)
pipeline.build()print(pipeline.generate('你的问题'))
也可用链式 Builder：Builder().with_embeddings(...).with_vector_store(...).with_llm(...).build_rag(k=5)。Docker 部署参考 examples/Dockerfile.example，运行时加 --add-host=host.docker.internal:host-gateway 以访问宿主机 Ollama。
这个 Agent 与同类方案有什么区别？
README 未直接点名竞品，但定位与 LangChain、LlamaIndex 等同类 RAG 框架明显重叠；差异点在于 RAGLight 强调轻量、开箱即用的向导式 CLI 与 REST 部署，同时将 Agentic RAG 与 MCP 集成作为一等特性，适合不想引入大型编排框架的场景。