ragbuilder

环境要求

• Python 环境（README 使用 uv 管理虚拟环境）
• 已安装 uv 工具（README 的安装命令基于 uv）
• 在代码中调用时需准备 LLM 与嵌入模型（如 Azure OpenAI）的凭据
• 需要一个数据目录 input_source，可选一份测试数据集

安装与启动步骤

1. 1创建虚拟环境

   README 使用 uv 创建名为 ragbuilder 的虚拟环境，会在当前目录生成同名文件夹。

   uv venv ragbuilder

   复制

2. 2激活虚拟环境

   激活刚创建的虚拟环境，激活后后续安装的包才会装进该环境。

   source ragbuilder/bin/activate

   复制

3. 3安装 ragbuilder

   用 uv pip 安装 ragbuilder 包；更多安装方式见官方文档 quickstart 页。

   uv pip install ragbuilder

   复制

4. 4用默认配置构建

   不用写复杂参数，只要给出数据路径即可创建 RAGBuilder 实例，测试数据集可选。

   from ragbuilder import RAGBuilder
   
   builder = RAGBuilder.from_source_with_defaults(
       input_source='path/to/your/data',
       test_dataset='path/to/test/data'  # Optional
   )

   复制

5. 5自定义模型配置

   需要指定 LLM 与嵌入模型时，可在构造 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")
   )

   复制

6. 6运行参数优化

   可分别对数据摄入、检索、生成三部分做模块级优化，并读取优化结果。

   from ragbuilder.config import (
       DataIngestOptionsConfig,
       RetrievalOptionsConfig,
       GenerationOptionsConfig
   )
   
   builder.optimize_data_ingest()
   builder.optimize_retrieval(retrieval_config)
   builder.optimize_generation(gen_config)
   
   results = builder.optimization_results

   复制

7. 7查询与部署 API

   用 invoke 直接跑查询；或调用 serve 把 RAG 流水线部署成 API 服务对外提供。

   response = results.invoke("What is HNSW?")
   
   builder.serve(host="0.0.0.0", port=8000)

   复制

关键配置

如何确认成功

Python 中执行 results.invoke("What is HNSW?") 能返回答案，或部署后 POST /query 请求成功返回结果，即表示运行正常。

常见问题

注意事项

• README 中的安装命令基于 uv，若本机没有 uv 需先自行准备该工具。
• 构造 RAGBuilder 时需要自行提供 LLM 与嵌入模型的配置和凭据，README 未给出具体 Key 的填写位置。
• 步骤中的 path/to/your/data 等路径是占位示例，请替换为你的真实数据路径。
• 部分安装选项与更完整文档在 https://docs.ragbuilder.io/quickstart/ 上。