pyLLMSearch - 高级 RAG

文档

本包旨在提供一个基于简单 YAML 配置的高级问答系统（RAG），支持与本地文档集合进行交互。除了基础的 LLM-based RAG 外，我们特别关注系统各组件的优化——更高效的文档解析、混合检索、HyDE 技术、聊天历史记录、深度链接、重排序、自定义嵌入能力等。该包设计用于与自定义的大语言模型（LLM）协同工作，无论这些模型来自 OpenAI 还是本地部署。

用户可以通过内置前端与本包交互，也可以通过暴露 MCP 服务器来实现，从而允许 Cursor、Windsurf 或 VSCode GH Copilot 等客户端与 RAG 系统进行对接。

特性

• 快速解析并嵌入中等规模的文档库（已测试过高达数 GB 的 Markdown 和 PDF 文件）。

• 支持增量更新新文档，无需重新索引整个文档库。

• 支持的文档格式：

  • 内置解析器：
    • .md — 根据标题、子标题和代码块等逻辑结构分割文件，并支持清理图片链接、添加自定义元数据等功能。
    • .pdf — 基于 MuPDF 的解析器。
    • .docx — 自定义解析器，支持嵌套表格。
  • 其他常见格式由 Unstructured 预处理工具支持：
    • 格式列表请参见 这里。

• 基于 FastAPI 的 API + MCP 服务器，允许通过任何 MCP 客户端与 RAG 通信，包括 VSCode、Windsurf、Cursor 等。

• 文档内深度链接——可直接跳转到 PDF 的特定页面或 Markdown 文件中的某个标题。

• 支持与嵌入式文档交互，内部兼容以下模型和方法（包括本地部署）：

  • OpenAI 兼容模型及 API。
  • Hugging Face 模型。

• 通过 OpenAI API 实现与 LiteLLM + Ollama 的互操作性，支持数百种不同模型（详见 LiteLLM 模型配置示例）。

• SSE MCP 服务器，便于与主流 MCP 客户端对接。

• 混合检索与重排序：

  • 从文档文件夹中生成密集嵌入，并将其存储在向量数据库（如 ChromaDB）中。
  • 支持的嵌入模型包括：
    • Hugging Face 嵌入。
    • Sentence-transformers 系列模型。
    • Instructor 系列模型。
    • OpenAI 嵌入。
  • 使用 SPLADE（https://github.com/naver/splade）生成稀疏嵌入，以实现稀疏与密集的混合检索。
  • 支持“检索并重排序”策略用于语义搜索，详情请参阅 这里。
    • 除原始的 ms-marco-MiniLM 交叉编码器外，还支持更现代的 bge-reranker-v2-m3 和 zerank-2。

• 支持通过开源工具 gmft（https://github.com/conjuncts/gmft）或 Azure Document Intelligence 解析表格。

• 可选支持使用 Gemini API 解析图像。

• 支持 HyDE（假设文档嵌入）技术——详情请参阅 这里。

  • 警告：启用 HyDE（通过配置文件或 Web 应用）可能会显著影响结果质量。请务必在启用前阅读相关论文。
  • 根据我的实验，在用户难以用专业术语准确表达问题的情境下（例如学习新主题时），启用 HyDE 可显著提升输出质量。

• 支持多查询机制，灵感来源于 RAG Fusion——https://towardsdatascience.com/forget-rag-the-future-is-rag-fusion-1147298d8ad1。

  • 当开启多查询功能时（可通过配置文件或 Web 应用设置），原始查询将被替换成同一问题的三个变体，从而弥合术语差异，并按照原文所述“提供不同的角度或视角”。

• 可选支持带有上下文感知的聊天历史记录。

• 其他特性：

  • 简单的 Web 界面。
  • 可将响应保存至离线数据库，以便后续分析。

演示

文档

浏览文档

llm-search 快速上手指南

llm-search (pyLLMSearch) 是一个高级的检索增强生成（RAG）系统，支持通过简单的 YAML 配置与本地文档集合进行交互。它提供了比基础 RAG 更强大的功能，包括混合搜索、重排序（Re-ranking）、HyDE、多查询扩展以及深度链接等。

环境准备

系统要求

• 操作系统: Linux, macOS 或 Windows (推荐 Linux 环境以获得最佳兼容性)
• Python: 3.9 或更高版本
• 硬件:
  • 若使用本地大模型或嵌入模型，建议配备 NVIDIA GPU (显存视模型大小而定)。
  • 若仅调用 OpenAI 等云端 API，对本地硬件要求较低。

前置依赖

确保已安装以下基础工具：

• git
• pip (Python 包管理工具)
• (可选) poppler-utils (用于 PDF 解析，Linux 下可通过 apt-get install poppler-utils 安装)

安装步骤

1. 克隆项目

git clone https://github.com/snexus/llm-search.git
cd llm-search

2. 创建虚拟环境并激活

python -m venv venv
source venv/bin/activate  # Windows 用户使用: venv\Scripts\activate

3. 安装依赖

国内加速方案：推荐使用清华或阿里镜像源加速安装。

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果需要使用特定的额外功能（如完整的非结构化文档解析支持），可能需要安装额外依赖：

pip install "unstructured[all-docs]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

llm-search 的核心是通过 YAML 文件进行配置，随后启动服务。

1. 准备文档

将你需要问答的文档（支持 .md, .pdf, .docx 等格式）放入一个本地文件夹，例如 ./docs。

2. 配置 YAML

复制示例配置文件并根据实际情况修改。主要需配置文档路径、嵌入模型和 LLM 模型。

cp sample_templates/config.yaml my_config.yaml

编辑 my_config.yaml，关键配置项示例如下：

# 文档设置
document_settings:
  docs_folder: "./docs"  # 你的文档路径
  parser_type: "auto"    # 自动识别或使用特定解析器

# 嵌入模型设置 (以 HuggingFace 本地模型为例)
embeddings:
  model_name: "BAAI/bge-small-zh-v1.5" # 推荐中文模型
  model_type: "huggingface"

# LLM 设置 (以 Ollama 本地部署为例，也可配置 OpenAI)
llm:
  provider: "ollama"
  model_name: "qwen2.5:7b" # 或其他支持的模型
  api_base: "http://localhost:11434"

# 高级功能 (可选)
features:
  hybrid_search: true      # 启用混合搜索 (稠密 + 稀疏)
  rerank: true             # 启用重排序
  hyde: false              # 谨慎启用 HyDE

3. 构建索引

首次运行或文档更新时，需要构建向量索引。

llmsearch index --config my_config.yaml

注：如果是增量更新文档，系统会自动处理，无需全量重建。

4. 启动服务

启动内置的 FastAPI 服务和 Web 界面，或通过 MCP 协议连接编辑器插件。

llmsearch run --config my_config.yaml

启动后：

• Web 界面: 访问终端输出的地址（通常为 http://127.0.0.1:8000）进行对话测试。
• MCP 客户端: 配置 Cursor、Windsurf 或 VSCode Copilot 连接到该 MCP 服务器，即可在 IDE 中直接询问本地文档内容。

5. (可选) Google Colab 体验

如果你希望在不配置本地环境的情况下快速体验，可以直接点击项目 README 中的 "Open In Colab" 按钮，在云端运行演示 Notebook。