RAGLight

RAGLight 是一个轻量级且模块化的 Python 库，用于实现 检索增强生成（RAG）。它通过将文档检索与自然语言推理相结合，增强了大型语言模型（LLM）的能力。

RAGLight 旨在提供简单性和灵活性，其模块化组件可以轻松集成各种 LLM、嵌入模型和向量存储，使其成为构建上下文感知 AI 解决方案的理想工具。

---

📚 目录

• 要求

• 特性

• 导入库

• 使用 CLI 立即与您的文档聊天

  • 忽略文件夹功能
  • 在配置类中忽略文件夹

• 部署为 REST API (raglight serve)

  • 启动服务器
  • 启动聊天界面
  • 端点
  • 通过环境变量配置
  • 使用 Docker Compose 部署

• 环境变量

• 提供商和数据库

  • LLM
  • 嵌入模型
  • 向量存储

• 快速入门

  • 知识库
  • RAG
  • 代理式 RAG
  • MCP 集成
  • 使用自定义管道
  • 覆盖默认处理器
  • 混合搜索（BM25 + 语义 + RRF）
  • Qdrant 向量存储
  • 查询改写
  • 流式输出
  • 对话历史
  • AWS Bedrock
  • 使用 Langfuse 进行可观测性

• 使用 Docker 运行 RAGLight

  • 构建镜像
  • 运行镜像

---

⚠️ 要求

实际上，RAGLight 支持：

• Ollama
• Google Gemini
• LMStudio
• vLLM
• OpenAI API
• Mistral API
• AWS Bedrock

如果您使用 LMStudio，需要确保已加载您想要使用的模型。 如果您使用 AWS Bedrock，请配置您的 AWS 凭证（环境变量、~/.aws/credentials 或 IAM 角色）——无需额外安装。

特性

• 嵌入模型集成：插入您偏好的嵌入模型（例如 HuggingFace 的 all-MiniLM-L6-v2），以获得紧凑高效的向量嵌入。
• LLM 无关性：可无缝集成来自不同提供商的不同 LLM（Ollama、LMStudio、Mistral、OpenAI、Google Gemini、AWS Bedrock）。
• RAG 流程：将文档检索和语言生成结合在一个统一的工作流程中。
• 代理式 RAG 流程：使用代理来提升 RAG 的性能。
• 🔌 MCP 集成：通过 MCP 服务器添加外部工具功能（例如代码执行、数据库访问）。
• 灵活的文档支持：可摄取并索引多种文档类型（例如 PDF、TXT、DOCX、Python、Javascript 等）。
• 可扩展架构：可轻松更换向量存储、嵌入模型或 LLM，以满足您的需求。
• 🔍 混合搜索（BM25 + 语义 + RRF）：将基于关键词的 BM25 检索与密集向量搜索相结合，使用倒排排名融合技术，以获得最佳结果。
• ✍️ 查询改写：利用对话历史自动将后续问题改写为独立查询，从而提高多轮对话中的检索准确性。
• 💬 对话历史：所有提供商（Ollama、OpenAI、Mistral、LMStudio、Gemini、Bedrock）均支持完整的多轮对话历史，并可选择设置 max_history 上限。
• ⚡ 流式输出：所有提供商都支持通过 generate_streaming() 进行逐 token 流式输出——无需额外配置即可与 generate() 互换使用。
• ☁️ AWS Bedrock：可使用 Claude、Titan、Llama 等 Bedrock 模型进行 LLM 推理和嵌入计算。
• 📊 Langfuse 可观测性（v3+）：可在 Langfuse 仪表板中直接跟踪每次 RAG 调用的端到端过程——检索、重新排序和生成。

---

导入库 🛠️

安装基础库：

pip install raglight

RAGLight 使用 可选依赖项 来支持不同的向量存储后端，因此您可以只安装所需的部分：

附加项	安装的包	备注
raglight[chroma]	chromadb	Windows 上需要 C++ 编译器
raglight[qdrant]	qdrant-client	纯 Python —— 在 Windows 上无需 C++ 编译器即可运行
raglight[langfuse]	langfuse	可观测性追踪

pip install "raglight[qdrant]"           # 仅 Qdrant（Windows 友好）
pip install "raglight[chroma]"           # 仅 ChromaDB
pip install "raglight[chroma,qdrant]"    # 两者
pip install "raglight[qdrant,langfuse]"  # Qdrant + 可观测性

---

使用 CLI 立即与您的文档聊天 💬

为了最快速简便地开始使用，RAGLight 提供了一个交互式命令行向导。它将引导您完成从选择文档到与文档聊天的每一个步骤，而无需编写任何一行 Python 代码。 前提条件：请确保您已运行本地 LLM 服务，例如 Ollama。

只需在终端中运行以下命令：

raglight chat

您也可以通过以下命令启动代理式 RAG 向导：

raglight agentic-chat

向导将指导您完成设置过程。以下是其界面示意图：

向导会询问您：

• 📂 数据源：包含文档的本地文件夹路径。
• 🚫 忽略文件夹：配置在索引过程中要排除哪些文件夹（例如 .venv、node_modules、__pycache__）。
• 💾 向量数据库：索引数据的存储位置及名称。
• 🧠 嵌入模型：用于理解文档内容的模型。
• 🤖 语言模型（LLM）：用于生成答案的 LLM。

配置完成后，它将自动索引您的文档并开始聊天会话。

忽略文件夹功能 🚫

RAGLight 会自动排除不应被索引的常见目录，例如：

• 虚拟环境（.venv、venv、env）
• Node.js 依赖项（node_modules）
• Python 缓存文件（__pycache__）
• 构建产物（build、dist、target）
• IDE 相关文件（.vscode、.idea）
• 以及更多……

您可以在 CLI 设置过程中自定义此列表，或使用默认配置。这样可以确保只有相关代码和文档被索引，从而提高性能并减少搜索结果中的噪声。

配置类中的忽略文件夹功能 🚫

忽略文件夹功能同样适用于所有配置类，允许您指定在索引过程中要排除的目录：

• RAGConfig：使用 ignore_folders 参数在 RAG 流水线索引时排除文件夹
• AgenticRAGConfig：使用 ignore_folders 参数在 AgenticRAG 流水线索引时排除文件夹
• VectorStoreConfig：使用 ignore_folders 参数在向量存储操作中排除文件夹

所有配置类都以 Settings.DEFAULT_IGNORE_FOLDERS 作为默认值，但您可以使用自定义列表进行覆盖：

# 示例：为任意配置自定义忽略文件夹
custom_ignore_folders = [
    ".venv",
    "venv",
    "node_modules",
    "__pycache__",
    ".git",
    "build",
    "dist",
    "temp_files",  # 您的自定义文件夹
    "cache"
]

# 在任意配置类中使用
config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
    ignore_folders=custom_ignore_folders  # 覆盖默认值
)

完整示例请参见 examples/ignore_folders_config_example.py，涵盖所有配置类型。

---

以 REST API 形式部署（raglight serve）🌐

raglight serve 会启动一个完全通过环境变量配置的 FastAPI 服务器——无需编写任何 Python 代码。

启动服务器

raglight serve

选项：

--host      绑定的主机地址（默认：0.0.0.0）
--port      监听的端口（默认：8000）
--reload    开发模式下启用自动重载（默认：False）
--workers   工作进程数量（默认：1）
--ui        同时启动 Streamlit 聊天 UI（默认：False）
--ui-port   Streamlit UI 的端口（默认：8501）

示例：

RAGLIGHT_LLM_MODEL=mistral-small-latest \
RAGLIGHT_LLM_PROVIDER=Mistral \
raglight serve --port 8080

Langfuse 追踪示例：

LANGFUSE_HOST=http://localhost:3000 \
LANGFUSE_PUBLIC_KEY=pk-lf-... \
LANGFUSE_SECRET_KEY=sk-lf-... \
raglight serve

当 LANGFUSE_HOST（或 LANGFUSE_BASE_URL）、LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY 均在环境中设置时，Langfuse 追踪将自动启用。 需要运行 pip install "raglight[langfuse]"。

启动聊天界面 💬

添加 --ui 即可在 REST API 旁启动 Streamlit 聊天界面——无需额外配置：

raglight serve --ui

地址	服务
http://localhost:8000	REST API + Swagger (/docs)
http://localhost:8501	Streamlit 聊天界面

该界面支持：

• 聊天：与您的文档交互——保留完整对话历史，并支持 Markdown 渲染
• 上传文件：直接从浏览器上传 PDF、TXT、代码等文件
• 导入目录：只需提供服务器上的路径即可
• 实时切换 LLM——侧边栏的 ⚙️ 模型设置面板允许您在不重启服务器的情况下更改提供商、模型和 API 基础 URL（包括 AWSBedrock 和 GoogleGemini）

使用 --ui-port 可以更改 Streamlit 的端口：

raglight serve --ui --port 8000 --ui-port 3000

两个进程共享相同的配置（环境变量），并在您停止服务器时同时终止。

端点

方法	路径	请求体	响应
GET	/health	—	{"status": "ok"}
POST	/generate	{"question": "..."}	{"answer": "..."}
POST	/ingest	{"data_path": "...", "file_paths": [...], "github_url": "...", "github_branch": "main"}	{"message": "..."}
POST	/ingest/upload	multipart/form-data — 字段 files（一个或多个文件）	{"message": "..."}
GET	/collections	—	{"collections": [...]}
GET	/config	—	{"llm_provider": "...", "llm_model": "...", "llm_api_base": "..."}
POST	/config	{"llm_provider": "...", "llm_model": "...", "llm_api_base": "..."}	{"llm_provider": "...", "llm_model": "...", "llm_api base": "..."}

交互式 API 文档（Swagger UI）会自动在 http://localhost:8000/docs 提供。

使用 curl 的示例

# 健康检查
curl http://localhost:8000/health

# 提问
curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"question": "What is RAGLight?"}'

# 导入本地文件夹
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"data_path": "./my_documents"}'

# 导入 GitHub 仓库
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"github_url": "https://github.com/Bessouat40/RAGLight", "github_branch": "main"}'

# 直接上传文件（multipart）
curl -X POST http://localhost:8000/ingest/upload \
  -F "files=@./rapport.pdf" \
  -F "files=@./notes.txt"

# 列出集合
curl http://localhost:8000/collections

通过环境变量配置

所有服务器设置都从 RAGLIGHT_* 环境变量中读取。将 examples/serve_example/.env.example 复制到 .env 文件中，并根据需要调整值。

变量	默认值	描述
RAGLIGHT_LLM_MODEL	llama3	LLM 模型名称
RAGLIGHT_LLM_PROVIDER	Ollama	LLM 提供商（Ollama、Mistral、OpenAI、LmStudio、GoogleGemini）
RAGLIGHT_LLM_API_BASE	http://localhost:11434	LLM API 基础 URL
RAGLIGHT_EMBEDDINGS_MODEL	all-MiniLM-L6-v2	嵌入模型名称
RAGLIGHT_EMBEDDINGS_PROVIDER	HuggingFace	嵌入提供商（HuggingFace、Ollama、OpenAI、GoogleGemini）
RAGLIGHT_EMBEDDINGS_API_BASE	http://localhost:11434	嵌入 API 基础 URL
RAGLIGHT_DB	Chroma	向量存储后端（Chroma 或 Qdrant）
RAGLIGHT_PERSIST_DIR	./raglight_db	本地持久化目录（当未设置 RAGLIGHT_DB_HOST 时使用）
RAGLIGHT_COLLECTION	default	集合名称
RAGLIGHT_K	5	每次查询检索的文档数量
RAGLIGHT_SYSTEM_PROMPT	(默认提示)	LLM 的自定义系统提示
RAGLIGHT_DB_HOST	—	远程向量存储主机（留空则使用本地磁盘存储）
RAGLIGHT_DB_PORT	—	远程向量存储端口
RAGLIGHT_API_TIMEOUT	300	Streamlit UI 的请求超时时间（秒）（对于速度较慢的模型可适当增加）

使用 Docker Compose 部署

在生产环境中快速部署的方法：

cd examples/serve_example
cp .env.example .env   # 根据需要编辑值
docker-compose up

docker-compose.yml 文件使用了 extra_hosts: host.docker.internal:host-gateway，以便容器能够访问宿主机上运行的 Ollama 实例。

---

环境变量

你可以设置多个环境变量来更改 RAGLight 的配置：

提供商凭据及 URLs

• 如果你想使用 Mistral API，可以设置 MISTRAL_API_KEY。
• 如果你有自定义的 Ollama URL，可以设置 OLLAMA_CLIENT_URL。
• 如果你有自定义的 LMStudio URL，可以设置 LMSTUDIO_CLIENT。
• 如果你有自定义的 OpenAI URL 或 vLLM URL，可以设置 OPENAI_CLIENT_URL。
• 如果你需要 OpenAI 密钥，可以设置 OPENAI_API_KEY。
• 如果你需要 Google Gemini API 密钥，可以设置 GEMINI_API_KEY。
• 对于 AWS Bedrock，可以设置 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_DEFAULT_REGION（或者使用 ~/.aws/credentials 文件或 IAM 角色）。

REST API 服务器 (raglight serve)

完整列表请参见上方的 通过环境变量配置 部分。

提供商与数据库

LLM

对于 LLM 推理，你可以使用以下提供商：

• LMStudio (Settings.LMSTUDIO)
• Ollama (Settings.OLLAMA)
• Mistral API (Settings.MISTRAL)
• vLLM (Settings.VLLM)
• OpenAI (Settings.OPENAI)
• Google Gemini (Settings.GOOGLE_GEMINI)
• AWS Bedrock (Settings.AWS_BEDROCK)

嵌入

对于嵌入模型，你可以使用以下提供商：

• Huggingface (Settings.HUGGINGFACE)
• Ollama (Settings.OLLAMA)
• vLLM (Settings.VLLM)
• OpenAI (Settings.OPENAI)
• Google Gemini (Settings.GOOGLE_GEMINI)
• AWS Bedrock (Settings.AWS_BEDROCK)

向量存储

对于向量存储，你可以使用：

提供商	常量	其他	Windows（无 C++）
ChromaDB	Settings.CHROMA	raglight[chroma]	否 — 需要 C++ 编译器
Qdrant	Settings.QDRANT	raglight[qdrant]	是 — 纯 Python 客户端

两者都支持本地（磁盘）和远程（HTTP）模式。

快速入门 🚀

知识库

知识库是一种在 RAG 初始化过程中将数据导入向量存储的方式。当你调用 build 函数时，就会进行数据导入：

from raglight import RAGPipeline
pipeline = RAGPipeline(knowledge_base=[
    FolderSource(path="<你的 PDF 文件夹路径>/knowledge_base"),
    GitHubSource(url="https://github.com/Bessouat40/RAGLight")
    ],
    model_name="llama3",
    provider=Settings.OLLAMA,
    k=5)

pipeline.build()

你可以定义两种不同的知识库：

1. 文件夹知识库

该目录下的所有文件/文件夹都会被导入到向量存储中：

from raglight import FolderSource
FolderSource(path="<你的 PDF 文件夹路径>/knowledge_base"),

2. GitHub 知识库

你可以声明想要存储到向量存储中的 GitHub 仓库：

from raglight import GitHubSource
GitHubSource(url="https://github.com/Bessouat40/RAGLight")

RAG

您可以使用 RAGLight 轻松设置您的 RAG：

from raglight.rag.simple_rag_api import RAGPipeline
from raglight.models.data_source_model import FolderSource, GitHubSource
from raglight.config.settings import Settings
from raglight.config.rag_config import RAGConfig
from raglight.config.vector_store_config import VectorStoreConfig

Settings.setup_logging()

knowledge_base=[
    FolderSource(path="<您包含 PDF 文件的文件夹路径>/knowledge_base"),
    GitHubSource(url="https://github.com/Bessouat40/RAGLight")
    ]

vector_store_config = VectorStoreConfig(
    embedding_model = Settings.DEFAULT_EMBEDDINGS_MODEL,
    api_base = Settings.DEFAULT_OLLAMA_CLIENT,
    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 = Settings.DEFAULT_K,
        # cross_encoder_model = Settings.DEFAULT_CROSS_ENCODER_MODEL,
        # system_prompt = Settings.DEFAULT_SYSTEM_PROMPT,
        # knowledge_base = knowledge_base
    )

pipeline = RAGPipeline(config, vector_store_config)

pipeline.build()

response = pipeline.generate("如何使用 raglight 框架创建一个简单的 RAGPipeline？请提供 Python 实现")
print(response)

您只需填写想要使用的模型即可。

⚠️ 默认情况下，LLM 提供商会是 Ollama。

代理式 RAG

此管道通过引入一个额外的代理来扩展检索增强生成（RAG）的概念。该代理可以从您的向量存储中检索数据。

您可以在配置中修改多个参数：

• provider：您的 LLM 提供商（Ollama、LMStudio、Mistral）
• model：您想要使用的模型
• k：您将检索的文档数量
• max_steps：代理使用的最大反思步骤数
• api_key：您的 Mistral API 密钥
• api_base：您的 API URL（Ollama URL、LM Studio URL 等）
• num_ctx：您的上下文最大长度
• verbosity_level：日志的详细级别
• ignore_folders：索引过程中要排除的文件夹列表（例如，[".venv", "node_modules", "pycache" ]）

from raglight.config.settings import Settings
from raglight.rag.simple_agentic_rag_api import AgenticRAGPipeline
from raglight.config.agentic_rag_config import AgenticRAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.settings import Settings
from dotenv import load_dotenv

load_dotenv()
Settings.setup_logging()

persist_directory = './defaultDb'
model_embeddings = Settings.DEFAULT_EMBEDDINGS_MODEL
collection_name = Settings.DEFAULT_COLLECTION_NAME

vector_store_config = VectorStoreConfig(
    embedding_model = model_embeddings,
    api_base = Settings.DEFAULT_OLLAMA_CLIENT,
    database=Settings.CHROMA,
    persist_directory = persist_directory,
    # host='localhost',
    # port='8001',
    provider = Settings.HUGGINGFACE,
    collection_name = collection_name
)

# 自定义忽略文件夹 - 您可以覆盖默认列表
custom_ignore_folders = [
    ".venv",
    "venv",
    "node_modules",
    "__pycache__",
    ".git",
    "build",
    "dist",
    "my_custom_folder_to_ignore"  # 在此处添加您自定义的文件夹
]

config = AgenticRAGConfig(
            provider = Settings.MISTRAL,
            model = "mistral-large-2411",
            k = 10,
            system_prompt = Settings.DEFAULT_AGENT_PROMPT,
            max_steps = 4,
            api_key = Settings.MISTRAL_API_KEY, # os.environ.get('MISTRAL_API_KEY')
            ignore_folders = custom_ignore_folders,  # 使用自定义的忽略文件夹
            # api_base = ... # 如果您有自定义的客户端 URL
            # num_ctx = ... # 最大上下文长度
            # verbosity_level = ... # 默认 = 2
            # knowledge_base = knowledge_base
        )

agenticRag = AgenticRAGPipeline(config, vector_store_config)
agenticRag.build()

response = agenticRag.generate("请为我实现一个受 RAGPipeline 和 AgenticRAG 及 RAG 启发的 AgenticRAGPipeline")

print('response : ', response)

MCP 集成

RAGLight 支持 MCP 服务器集成，以增强您的代理的推理能力。MCP 允许代理通过标准化的服务器接口与外部工具（例如代码执行环境、数据库工具或搜索代理）进行交互。

要使用 MCP，只需将 mcp_config 参数传递给您的 AgenticRAGConfig，其中每个配置都定义了 MCP 服务器的 URL（以及可选的传输方式）。

只需将此参数添加到您的 AgenticRAGPipeline 中：

config = AgenticRAGConfig(
    provider = Settings.OPENAI,
    model = "gpt-4o",
    k = 10,
    mcp_config = [
        {"url": "http://127.0.0.1:8001/sse"}  # 您的 MCP 服务器 URL
    ],
    ...
)

📚 文档：了解如何使用 MCPClient.server_parameters 配置并启动 MCP 服务器。

使用自定义管道

1. 配置您的管道

您也可以设置自己的管道：

from raglight.rag.builder import Builder
from raglight.config.settings import Settings

rag = Builder() \
    .with_embeddings(Settings.HUGGINGFACE, model_name=model_embeddings) \
    .with_vector_store(Settings.CHROMA, persist_directory=persist_directory, collection_name=collection_name) \
    .with_llm(Settings.OLLAMA, model_name=model_name, system_prompt_file=system_prompt_directory, provider=Settings.LMStudio) \
    .build_rag(k = 5)

2. 将文档摄入您的向量存储

然后您可以将数据摄入您的向量存储。

1. 您可以使用默认管道来摄入非代码数据：

rag.vector_store.ingest(data_path='./data')

2. 或者您可以使用代码管道：

rag.vector_store.ingest(repos_path=['./repository1', './repository2'])

此管道会将代码嵌入摄入到您的集合中：collection_name。但此管道还会从您的代码库中提取所有签名，并将其摄入到：collection_name_classes。

您可以在 VectorStore 类中访问两个不同的函数：similarity_search 和 similarity_search_class，用于在不同的集合中进行搜索。

3. 查询管道

使用 RAG 管道检索并生成答案：

response = rag.generate("我该如何优化我的马拉松训练？")
print(response)

✚ 更多示例

您可以在 examples 目录中找到所有这些用例的更多示例。

覆盖默认处理器

RAGLight 内置了基于文件扩展名的文档处理器：

• pdf → PDFProcessor
• py、js、ts、java、cpp、cs → CodeProcessor
• txt、md、html → TextProcessor

您可以在构建向量存储时，使用 custom_processors 参数覆盖这些默认设置。这在需要对某些文件类型应用自定义逻辑时特别有用，例如对于包含图表和图像的 PDF 文件，可以使用 视觉语言模型（VLM） 进行处理。RAGLight 也提供了基于 VLM 的处理器。

在构建器中注册自定义处理器

from raglight.document_processing.vlm_pdf_processor import VlmPDFProcessor
from raglight.llm.ollama_model import OllamaModel
from raglight.rag.builder import Builder
from raglight.config.settings import Settings

from dotenv import load_dotenv
import os

load_dotenv()
Settings.setup_logging()

persist_directory = './defaultDb'
model_embeddings = Settings.DEFAULT_EMBEDDINGS_MODEL
collection_name = Settings.DEFAULT_COLLECTION_NAME
data_path = os.environ.get('DATA_PATH')

# 视觉语言模型（以 Ollama 为例）
vlm = OllamaModel(
    model_name="ministral-3:3b",
    system_prompt="You are a technical documentation visual assistant.",
)

custom_processors = {
    "pdf": VlmPDFProcessor(vlm),  # 覆盖默认的 PDF 处理器
}

vector_store = Builder() \
    .with_embeddings(Settings.HUGGINGFACE, model_name=model_embeddings) \
    .with_vector_store(
        Settings.CHROMA,
        persist_directory=persist_directory,
        collection_name=collection_name,
        custom_processors=custom_processors,
    ) \
    .build_vector_store()

vector_store.ingest(data_path=data_path)

通过这种配置，所有 .pdf 文件都将由您自定义的 VlmPDFProcessor 处理，而其他类型的文件则继续使用默认处理器。

混合检索（BM25 + 语义 + RRF）🔍

RAGLight 支持三种检索策略，可通过 search_type 参数进行配置。同时支持 Chroma 和 Qdrant 后端。

模式	描述
"semantic"	密集向量相似度检索（默认）
"bm25"	基于关键词的 BM25 检索
"hybrid"	BM25 与语义检索结合，使用倒数排名融合（RRF）

使用构建器 API

from raglight.rag.builder import Builder
from raglight.config.settings import Settings

# 可用于 Settings.CHROMA 或 Settings.QDRANT
rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name="all-MiniLM-L6-v2")
    .with_vector_store(
        Settings.QDRANT,                     # 或 Settings.CHROMA
        persist_directory="./myDb",
        collection_name="my_collection",
        search_type=Settings.SEARCH_HYBRID,  # "semantic" | "bm25" | "hybrid"
        alpha=0.5,                           # RRF 中语义与 BM25 的权重
    )
    .with_llm(Settings.OLLAMA, model_name="llama3.1:8b")
    .build_rag(k=5)
)

rag.vector_store.ingest(data_path="./docs")
response = rag.generate("What is Reciprocal Rank Fusion?")
print(response)

使用高级 RAGPipeline API

from raglight.rag.simple_rag_api import RAGPipeline
from raglight.config.rag_config import RAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.settings import Settings
from raglight.models.data_source_model import FolderSource

vector_store_config = VectorStoreConfig(
    embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
    provider=Settings.HUGGINGFACE,
    database=Settings.CHROMA,
    persist_directory="./myDb",
    collection_name="my_collection",
    search_type=Settings.SEARCH_HYBRID,   # 或 SEARCH_SEMANTIC / SEARCH_BM25
    hybrid_alpha=0.5,
)

config = RAGConfig(
    llm="llama3.1:8b",
    provider=Settings.OLLAMA,
    k=5,
    knowledge_base=[FolderSource(path="./docs")],
)

pipeline = RAGPipeline(config, vector_store_config)
pipeline.build()
response = pipeline.generate("Explain the retrieval pipeline")
print(response)

RRF 的工作原理：每种检索模式都会返回各自的文档排序列表。RRF 会为每个列表中的文档分配一个分数 1 / (k + rank)，并将这些分数相加——在两个列表中都排名靠前的文档会被优先提升，而仅出现在其中一个列表中的文档则会被保留，但排名会较低。这种方式使混合模式比单独使用任一模式都能获得更好的召回率和精确率。

完整示例请参见 examples/hybrid_search_example.py。

---

Qdrant 向量存储 🗄️

Qdrant 是 ChromaDB 的纯 Python 替代方案——无需 C++ 编译器，因此在 Windows 系统上是推荐的选择。

pip install "raglight[qdrant]"

本地模式（磁盘存储，无需服务器）

import uuid
from raglight.rag.builder import Builder
from raglight.config.settings import Settings

rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name="all-MiniLM-L6-v2")
    .with_vector_store(
        Settings.QDRANT,
        persist_directory="./qdrantDb",
        collection_name=str(uuid.uuid4()),
    )
    .with_llm(Settings.OLLAMA, model_name="llama3.1:8b")
    .build_rag(k=5)
)

rag.vector_store.ingest(data_path="./docs")
response = rag.generate("What is RAGLight?")
print(response)

远程模式（Qdrant 服务器）

使用 Docker 启动 Qdrant 服务器：

docker run -p 6333:6333 qdrant/qdrant

然后将构建器指向该服务器：

rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name="all-MiniLM-L6-v2")
    .with_vector_store(
        Settings.QDRANT,
        host="localhost",
        port=6333,
        collection_name="my_collection",
    )
    .with_llm(Settings.OLLAMA, model_name="llama3.1:8b")
    .build_rag(k=5)
)

完整示例请参见 examples/qdrant_example.py。

---

查询改写 ✍️

RAGLight 会在检索之前自动将后续问题改写成独立的查询。这在多轮对话中显著提高了准确性，尤其是在用户的问题引用了之前的上下文时（例如 "and for Python?" → "How do I do X in Python?"）。

查询改写功能 默认启用。当前使用的 LLM 会用来改写问题；如果尚未有对话历史，则问题会保持不变传递下去。

使用高级 RAGPipeline API

from raglight.config.rag_config import RAGConfig
from raglight.config.settings import Settings

# 默认启用
config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
)

# 如需禁用
config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
    reformulation=False,
)

使用构建器 API

from raglight.rag.builder import Builder
from raglight.config.settings import Settings

rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name="all-MiniLM-L6-v2")
    .with_vector_store(Settings.CHROMA, persist_directory="./myDb", collection_name="my_collection")
    .with_llm(Settings.OLLAMA, model_name="llama3.1:8b")
    .build_rag(k=5, reformulation=True)  # 默认为 True
)

经过改写的查询会在 INFO 级别被记录，以便您可以检查 LLM 的输出内容。

启用改写功能的管道流程：

改写 → 检索 → [重排序？] → 生成

---

流式输出 ⚡

所有提供商都支持通过 generate_streaming() 进行逐 token 流式输出。它会运行完整的管道（改写 → 检索 → 重排序），并在 LLM 产生答案片段时将其逐步返回。

使用 RAGPipeline

pipeline = RAGPipeline(config, vector_store_config)
pipeline.build()

for chunk in pipeline.generate_streaming("RAGLight 是如何工作的？"):
    print(chunk, end="", flush=True)
print()

使用构建器 API

rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name="all-MiniLM-L6-v2")
    .with_vector_store(Settings.CHROMA, persist_directory="./myDb", collection_name="col")
    .with_llm(Settings.OLLAMA, model_name="llama3.1:8b")
    .build_rag(k=5)
)

for chunk in rag.generate_streaming("请解释检索流程")：
    print(chunk，end=""，flush=True)
print()

所有提供商均支持流式输出：Ollama、OpenAI、vLLM、LMStudio、Mistral、Google Gemini 和 AWS Bedrock。流式传输结束时，对话历史会自动更新。

---

对话历史 💬

RAGLight 会自动在多次调用 generate() 之间维护对话历史。每一轮都会将用户和助手的消息追加到下一次调用传递给 LLM 的消息中，从而实现真正的多轮对话，且适用于所有提供商。

默认情况下，对话历史上限为 20 条消息（约 10 轮）。您可以通过 max_history 参数调整此限制，或将该参数设置为 None 以取消限制：

# 通过 RAGConfig（高级 API）
config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
    max_history=20,  # 保留最近 20 条消息（约 10 轮）
)

# 通过 Builder
rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE，model_name="all-MiniLM-L6-v2")
    .with_vector_store(Settings.CHROMA，persist_directory="./myDb"，collection_name="col")
    .with_llm(Settings.OLLAMA，model_name="llama3.1:8b")
    .build_rag(k=5，max_history=20)
)

提示：将 max_history 设置为您希望保留的轮数的大致两倍（每轮包含两条消息）。

---

AWS Bedrock ☁️

RAGLight 支持使用 AWS Bedrock 进行 LLM 推理和嵌入计算。身份验证依赖于标准的 boto3 凭证链（环境变量、~/.aws/credentials 文件或 IAM 角色）。

AWS 凭证（三者之一）：

• 环境变量：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION
• AWS 凭证文件：~/.aws/credentials
• IAM 角色（EC2 / ECS / Lambda）

支持的模型（示例）：

类型	模型 ID
LLM	anthropic.claude-3-5-sonnet-20241022-v2:0
LLM	anthropic.claude-3-haiku-20240307-v1:0
嵌入	amazon.titan-embed-text-v2:0
嵌入	cohere.embed-english-v3

跨区域推理配置文件：较新的 Claude 模型（Claude 3.7+、Claude 4）需要使用跨区域推理配置文件 ID，而不是单纯的模型 ID。请使用 us.、eu. 或 ap. 前缀——例如 us.anthropic.claude-sonnet-4-6。运行 aws bedrock list-inference-profiles 可查看您账户中可用的配置文件列表。

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 GitHubSource

Settings.setup_logging()

vector_store_config = VectorStoreConfig(
    provider=Settings.AWS_BEDROCK,
    embedding_model=Settings.AWS_BEDROCK_EMBEDDING_MODEL,  # amazon.titan-embed-text-v2:0
    database=Settings.CHROMA,
    persist_directory="./bedrockDb",
    collection_name="bedrock_collection",
)

config = RAGConfig(
    provider=Settings.AWS_BEDROCK,
    llm=Settings.AWS_BEDROCK_LLM_MODEL,  # anthropic.claude-3-5-sonnet-20241022-v2:0
    knowledge_base=[GitHubSource(url="https://github.com/Bessouat40/RAGLight")],
)

pipeline = RAGPipeline(config，vector_store_config)
pipeline.build()
response = pipeline.generate("我该如何使用 raglight 创建一个 RAGPipeline？")
print(response)

完整的工作示例请参见 examples/bedrock_example.py。

---

使用 Langfuse 实现可观测性

RAGLight 支持 Langfuse 4.0.0，可全面监控您的 RAG 流程。每次调用 generate() 都会被记录为一条单独的 Langfuse 跟踪，并且每个 LangGraph 节点（检索、重排序、生成）都会作为独立的跨度显示。

无论是 generate() 还是 generate_streaming()，都会自动在所有提供商（Ollama、OpenAI、Mistral、Gemini、LMStudio、Bedrock）上传播 Langfuse 回调。

注意：如果未配置 Langfuse 凭证，RAGLight 会自动将 LANGFUSE_TRACING_ENABLED 设置为 false，以防止 Langfuse v4 在启动时尝试连接到 localhost:3000。

安装额外依赖项

pip install "raglight[langfuse]"

# 或者直接：
pip install "langfuse==4.0.0"

与 RAGPipeline 配合使用

from raglight.config.rag_config import RAGConfig
from raglight.config.vector_store_config import VectorStoreConfig
from raglight.config.langfuse_config import LangfuseConfig
from raglight.config.settings import Settings
from raglight.rag.simple_rag_api import RAGPipeline

langfuse_config = LangfuseConfig(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://localhost:3000",  # 或您的 Langfuse Cloud URL
)

config = RAGConfig(
    llm=Settings.DEFAULT_LLM,
    provider=Settings.OLLAMA,
    langfuse_config=langfuse_config,
)

vector_store_config = VectorStoreConfig(
    embedding_model=Settings.DEFAULT_EMBEDDINGS_MODEL,
    provider=Settings.HUGGINGFACE,
    database=Settings.CHROMA,
    persist_directory="./myDb",
    collection_name="my_collection",
)

pipeline = RAGPipeline(config, vector_store_config)
pipeline.build()
response = pipeline.generate("What is RAGLight?")
print(response)

使用 Builder API

from raglight.rag.builder import Builder
from raglight.config.langfuse_config import LangfuseConfig
from raglight.config.settings import Settings

langfuse_config = LangfuseConfig(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://localhost:3000",
)

rag = (
    Builder()
    .with_embeddings(Settings.HUGGINGFACE, model_name=Settings.DEFAULT_EMBEDDINGS_MODEL)
    .with_vector_store(Settings.CHROMA, persist_directory="./myDb", collection_name="my_collection")
    .with_llm(Settings.OLLAMA, model_name=Settings.DEFAULT_LLM)
    .build_rag(k=5, langfuse_config=langfuse_config)
)

rag.vector_store.ingest(data_path="./docs")
response = rag.generate("Explain the retrieval pipeline")
print(response)

会话 ID

默认情况下，每个 RAG 实例只会生成一个 UUID，并在每次调用 generate() 时重复使用，因此同一对话的所有轮次都会被归入同一个 Langfuse 跟踪中。

您可以通过 LangfuseConfig(session_id="my-session-42", ...) 来固定自定义的会话 ID。

---

在 Docker 中使用 RAGLight

您可以轻松地在 Docker 容器中使用 RAGLight。 Dockerfile 示例请参见：examples/Dockerfile.example

构建您的镜像

只需进入 examples 目录并运行：

docker build -t docker-raglight -f Dockerfile.example .

运行您的镜像

为了让容器能够与 Ollama 或 LMStudio 通信，您需要添加自定义的主机到 IP 映射：

docker run --add-host=host.docker.internal:host-gateway docker-raglight

我们使用 --add-host 标志来允许 Ollama 的调用。

RAGLight 快速上手指南

RAGLight 是一个轻量级、模块化的 Python 库，用于构建检索增强生成（RAG）应用。它支持多种大语言模型（LLM）、嵌入模型和向量数据库，旨在帮助开发者快速搭建上下文感知的 AI 解决方案。

环境准备

在开始之前，请确保满足以下要求：

• Python 版本：建议 Python 3.9 或更高版本。
• 本地 LLM 服务（可选但推荐）：若使用本地模型，需预先安装并运行 Ollama、LMStudio 或 vLLM。
  • 例如使用 Ollama：确保模型已加载（如 ollama run llama3）。
• API Key（如需云服务）：若使用 OpenAI、Mistral、Google Gemini 或 AWS Bedrock，请准备好相应的 API Key 或配置好 AWS 凭证。
• 编译器（仅 Windows + ChromaDB）：如果计划在 Windows 上使用 ChromaDB 向量库，需要安装 C++ 编译工具链；或者选择无需编译器的 Qdrant。

安装步骤

1. 安装基础库

使用 pip 安装核心功能：

pip install raglight

国内加速建议：如遇下载缓慢，可使用清华或阿里镜像源：

pip install raglight -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装向量数据库扩展（可选）

RAGLight 采用按需安装策略，根据你选择的向量后端安装额外依赖：

• 推荐方案（Qdrant，纯 Python，Windows 友好）：

  pip install "raglight[qdrant]"
  

• ChromaDB 方案（Windows 需 C++ 编译器）：

  pip install "raglight[chroma]"
  

• 可观测性方案（集成 Langfuse）：

  pip install "raglight[qdrant,langfuse]"
  

基本使用

RAGLight 提供了两种极速启动方式：命令行交互向导（无需写代码）和 REST API 部署。

方式一：命令行交互向导（最快上手）

这是最简单的入门方式。RAGLight 会引导你选择文档文件夹、配置模型并直接开始对话。

1. 确保本地 LLM 服务（如 Ollama）正在运行。
2. 在终端执行以下命令：

raglight chat

若需体验智能体增强版 RAG，可运行：

raglight agentic-chat

向导流程说明：

• 📂 数据源：输入包含文档（PDF, TXT, Code 等）的本地文件夹路径。
• 🚫 忽略文件夹：自动排除 .venv, node_modules, __pycache__ 等无关目录（支持自定义）。
• 💾 向量库：选择存储位置和名称。
• 🧠 嵌入模型 & 🤖 LLM：选择用于理解文档和生成回答的模型。

配置完成后，系统将自动索引文档并开启聊天会话。

方式二：部署为 REST API 服务

你可以一键启动一个带有 Swagger 文档和 Streamlit 聊天界面的 FastAPI 服务器，完全通过环境变量配置，无需编写 Python 代码。

启动命令：

raglight serve --ui

常用参数：

• --port：API 端口（默认 8000）
• --ui-port：聊天界面端口（默认 8501）
• --reload：开发模式下自动重载

示例：指定模型并启动服务

RAGLIGHT_LLM_MODEL=mistral-small-latest \
RAGLIGHT_LLM_PROVIDER=Mistral \
raglight serve --port 8080 --ui

启动后访问：

• REST API & 文档: http://localhost:8000 (Swagger UI 位于 /docs)
• Web 聊天界面: http://localhost:8501

在 Web 界面中，你可以直接上传文件、切换模型并进行多轮对话。