RagBuilder 是一个工具包，可自动为您的数据创建最优的生产就绪型检索增强生成（RAG）配置。通过在各种 RAG 参数上进行超参数调优（例如：语义分块、字符分块等分块策略；1000 字、2000 字等分块大小），RagBuilder 会根据测试数据集评估这些配置，从而找出最适合您数据的方案。此外，RagBuilder 还包含多个最先进的预定义 RAG 模板，这些模板在不同数据集上均表现出色。因此，您只需提供数据，RagBuilder 就能在几分钟内生成一个生产级的 RAG 配置。

特性

• 超参数调优：使用贝叶斯优化高效地优化您的 RAG 配置
• 预定义 RAG 模板：使用经过验证的高性能模板，如图检索器、上下文分块器等
• 评估数据集选项：生成合成测试数据集或使用您自己的数据集
• 组件访问：直接访问向量存储、检索器和生成器组件
• API 部署：轻松部署为 API 服务
• 项目持久化：保存和加载优化后的 RAG 流程

安装

# 创建一个新的虚拟环境
uv venv ragbuilder

# 激活新虚拟环境
source ragbuilder/bin/activate

# 安装
uv pip install ragbuilder

更多安装选项请参见此处（链接）

快速入门

from ragbuilder import RAGBuilder

# 使用默认设置初始化并优化
builder = RAGBuilder.from_source_with_defaults(input_source='https://lilianweng.github.io/posts/2023-06-23-agent/')
results = builder.optimize()

# 通过完整流程运行查询
response = results.invoke("什么是 HNSW？")

# 查看优化摘要
print(results.summary())

设置默认模型

您可以指定在整个流程中使用的默认 LLM 和嵌入模型：

from langchain_openai import AzureChatOpenAI, AzureOpenAIEmbeddings

# 使用自定义默认值初始化
builder = RAGBuilder.from_source_with_defaults(
    input_source='data.pdf',
    default_llm=AzureChatOpenAI(model="gpt-4o", temperature=0.0),
    default_embeddings=AzureOpenAIEmbeddings(model="text-embedding-3-large"),
    n_trials=20  # 设置优化试验次数
)

# 或者在创建具有精细自定义配置的 RAGBuilder 实例时
builder = RAGBuilder(
    data_ingest_config=data_ingest_config, # 自定义数据摄入参数
    default_llm=AzureChatOpenAI(model="gpt-4o", temperature=0.0),
    default_embeddings=AzureOpenAIEmbeddings(model="text-embedding-3-large")
)
````

## 配置指南

### 基本配置
对于大多数用例，使用默认配置即可获得良好效果：

```python
builder = RAGBuilder.from_source_with_defaults(
    input_source='path/to/your/data',
    test_dataset='path/to/test/data'  # 可选
)
```

## 高级配置

如果您需要对 RAG 流程进行更精细的控制，可以自定义每个环节：

````python
from ragbuilder.config import (
    DataIngestOptionsConfig,
    RetrievalOptionsConfig,
    GenerationOptionsConfig
)

# 配置数据摄入
data_ingest_config = DataIngestOptionsConfig(
    input_source="data.pdf",
    document_loaders=[
        {"type": "pymupdf"},
        {"type": "unstructured"}
    ],
    chunking_strategies=[{
        "type": "RecursiveCharacterTextSplitter",
        "chunker_kwargs": {"separators": ["\n\n", "\n", " ", ""]}
    }],
    chunk_size={"min": 500, "max": 2000, "stepsize": 500},
    embedding_models=[{
        "type": "openai",
        "model_kwargs": {"model": "text-embedding-3-large"}
    }]
)

# 使用自定义配置初始化
builder = RAGBuilder(
    data_ingest_config=data_ingest_config,
    default_llm=AzureChatOpenAI(model="gpt-4o", temperature=0.0),
    default_embeddings=AzureOpenAIEmbeddings(model="text-embedding-3-large")
)

# 运行单个模块级别的优化
builder.optimize_data_ingest()


# 配置检索选项
retrieval_config = RetrievalOptionsConfig(
    retrievers=[
        {
            "type": "vector_similarity",
            "retriever_k": [20],
            "weight": 0.5
        },
        {
            "type": "bm25",
            "retriever_k": [20],
            "weight": 0.5
        }
    ],
    rerankers=[{
        "type": "BAAI/bge-reranker-base"
    }],
    top_k=[3, 5]
)


# 使用自定义配置运行检索优化
builder.optimize_retrieval(retrieval_config)

# 配置生成相关选项
gen_config = GenerationOptionsConfig(
    llms = [
        LLMConfig(type="azure_openai", model_kwargs={'model':'gpt-4o-mini', 'temperature':0.2}),
        LLMConfig(type="azure_openai", model_kwargs={'model':'gpt-4o', 'temperature':0.2}),
    ],
    optimization={
        "n_trials": 10, 
        "n_jobs": 1,
        "study_name": "lillog_agents_study",
        "optimization_direction": "maximize"
    },
    evaluation_config={"type": "ragas"},
)

# 使用自定义配置运行生成优化
builder.optimize_generation(gen_config)

results = builder.optimization_results
response = adv_results.invoke("什么是 HNSW？")
````


## 组件选项参考

### 文档加载器
- `unstructured`: 通用加载器
- `pymupdf`: 针对 PDF 优化
- `pypdf`: 另一种 PDF 加载器
- `web`: 网页加载器
- 通过 `custom_class` 支持自定义加载器

### 分块策略
- `RecursiveCharacterTextSplitter`: 递归字符文本分割器
- `CharacterTextSplitter`: 字符文本分割器
- `MarkdownHeaderTextSplitter`: 基于 Markdown 标题的分割器
- `HTMLHeaderTextSplitter`: 基于 HTML 标题的分割器
- `SemanticChunker`: 语义分块器
- `TokenTextSplitter`: 基于 token 的分割器
- 通过 `custom_class` 支持自定义分割器


### 检索器
- `vector_similarity`: 向量相似度搜索
- `vector_mmr`: 向量 MMR 搜索
- `bm25`: 基于 BM25 的关键词搜索
- `multi_query`: 多查询检索器
- `parent_doc_full`: 父文档全篇检索
- `parent_doc_large`: 父文档大块检索
- `graph`: 基于图的检索（需 Neo4j）
- 通过 `custom_class` 支持自定义检索器

### 重排序器
- `BAAI/bge-reranker-base`: BGE 基础重排序器
- `mixedbread-ai/mxbai-rerank-base-v1`: mxbai 重排序器基础版 v1
- `mixedbread-ai/mxbai-rerank-large-v1`: mxbai 重排序器大模型版 v1
- `cohere`: Cohere 的重排序模型
- `jina`: Jina 重排序器
- `flashrank`: Flaskrank 重排序器
- `rankllm`: RankLLM 重排序器
- `colbert`: Colbert 重排序器
- 通过 `custom_class` 自定义重排序器


## 环境变量

在你的项目目录中创建一个 `.env` 文件：

````env
# 必需
OPENAI_API_KEY=your_key_here

# 可选 - 用于附加功能
MISTRAL_API_KEY=your_key_here
COHERE_API_KEY=your_key_here
AZURE_OPENAI_API_KEY=your_key_here
AZURE_OPENAI_ENDPOINT=your_endpoint_here

# 用于基于图的 RAG
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
````

## 高级主题

### 自定义评估指标
```python
from ragbuilder import EvaluationConfig

config = EvaluationConfig(
    type="custom",
    custom_class="your_module.CustomEvaluator",
    evaluator_kwargs={
        "metrics": ["precision", "recall", "f1_score"]
    }
)
```

### 优化配置
微调优化参数：
```python
from ragbuilder import OptimizationConfig

config = OptimizationConfig(
    n_trials=20,
    n_jobs=1,
    study_name="my_optimization",
    optimization_direction="maximize"
)
```

## API 部署

RAGBuilder 可以部署为 API 服务：

````python
# 初始化并优化
builder = RAGBuilder.from_source_with_defaults('data.pdf')
results = builder.optimize()

# 部署为 API
builder.serve(host="0.0.0.0", port=8000)
````

可通过以下方式访问：
- `POST /query` - 通过 RAG 流程运行查询

## 项目管理

保存和加载优化后的 RAG 流程：

````python
# 保存项目
builder.save('rag_project/')

# 加载现有项目
builder = RAGBuilder.load('rag_project/')

# 访问组件
vectorstore = builder.data_ingest.get_vectorstore()
retriever = builder.retrieval.get_retriever()
generator = builder.generation.get_generator()
````

## 最佳实践

1. **从简单开始**
   - 从 `from_source_with_defaults()` 开始
   - 仅在需要时才增加复杂性

2. **测试数据质量**
   - 提供具有代表性的测试查询
   - 使用领域特定的评估指标

3. **资源管理**
   - 监控大数据集下的内存使用情况
   - 对大型文档使用分块处理

4. **生产部署**
   - 保存优化后的项目以便重复使用
   - 监控 API 性能指标
   - 为 API 端点实施速率限制

## 使用分析

我们收集匿名使用指标以改进 RAGBuilder：
- 优化运行次数
- 成功/失败率
- 不会收集任何个人或商业数据

如需退出，请在 `.env` 中设置 `ENABLE_ANALYTICS=False`：

## 贡献

我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。

## 许可证

本项目采用 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。

RagBuilder 快速上手指南

RagBuilder 是一个自动化构建生产级检索增强生成（RAG）系统的工具包。它通过贝叶斯优化对分块策略、分块大小等超参数进行自动调优，并结合预定义的高质量模板，帮助开发者在几分钟内为特定数据找到最优的 RAG 配置。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.9 及以上
• 前置依赖：
  • 推荐使用 uv 进行虚拟环境管理（安装更快），也可使用标准 venv。
  • 需要配置大模型和 Embedding 模型的 API Key（如 OpenAI, Azure OpenAI 等）。

安装步骤

推荐使用 uv 快速创建环境并安装：

# 创建新的虚拟环境
uv venv ragbuilder

# 激活虚拟环境
# Linux/macOS:
source ragbuilder/bin/activate
# Windows (PowerShell):
ragbuilder\Scripts\Activate.ps1

# 安装 ragbuilder
uv pip install ragbuilder

提示：如果网络下载较慢，可添加国内镜像源加速安装： uv pip install ragbuilder -i https://pypi.tuna.tsinghua.edu.cn/simple

配置环境变量

在项目根目录创建 .env 文件，填入必要的 API 密钥：

# 必填：OpenAI API Key (或其他支持的模型提供商)
OPENAI_API_KEY=your_key_here

# 选填：其他服务密钥
AZURE_OPENAI_API_KEY=your_key_here
AZURE_OPENAI_ENDPOINT=your_endpoint_here
COHERE_API_KEY=your_key_here

基本使用

以下是最简单的使用流程：加载数据、自动优化配置、执行查询。

1. 快速启动与优化

使用默认配置从指定数据源（URL 或本地文件）构建并优化 RAG 管道：

from ragbuilder import RAGBuilder

# 初始化并使用默认配置进行优化
# input_source 可以是 URL 或本地文件路径 (如 'data.pdf')
builder = RAGBuilder.from_source_with_defaults(
    input_source='https://lilianweng.github.io/posts/2023-06-23-agent/'
)

# 执行自动超参数调优
results = builder.optimize()

# 通过优化后的管道运行查询
response = results.invoke("What is HNSW?")
print(response)

# 查看优化总结报告
print(results.summary())

2. 指定默认模型

如果需要指定特定的 LLM 和 Embedding 模型（例如使用 Azure OpenAI）：

from langchain_openai import AzureChatOpenAI, AzureOpenAIEmbeddings
from ragbuilder import RAGBuilder

builder = RAGBuilder.from_source_with_defaults(
    input_source='data.pdf',
    default_llm=AzureChatOpenAI(model="gpt-4o", temperature=0.0),
    default_embeddings=AzureOpenAIEmbeddings(model="text-embedding-3-large"),
    n_trials=20  # 设置优化试验次数
)

results = builder.optimize()

3. 部署为 API 服务

优化完成后，可一键将 RAG 管道部署为 API 服务：

# 初始化并优化
builder = RAGBuilder.from_source_with_defaults('data.pdf')
results = builder.optimize()

# 启动 API 服务
builder.serve(host="0.0.0.0", port=8000)

启动后，可通过 POST /query 接口调用服务。

4. 项目持久化

保存优化好的项目以便后续直接加载使用，无需重新优化：

# 保存项目
builder.save('rag_project/')

# 加载现有项目
builder = RAGBuilder.load('rag_project/')

# 直接访问内部组件
vectorstore = builder.data_ingest.get_vectorstore()
retriever = builder.retrieval.get_retriever()