Skip to main content

​
作用

Retriever Server 是 UltraRAG 中的核心检索模块，集成了 模型加载、文本编码、索引构建与检索查询 等一体化功能。 它原生支持 Sentence-Transformers、Infinity 以及 OpenAI 等多种后端接口， 可灵活适配不同规模与类型的语料库，满足 大规模向量化 与 高效文档召回 的需求。

​
使用示例

​
语料库编码与索引

以下示例展示如何使用 Retriever Server 对语料库进行编码与索引构建。
examples/corpus_index.yaml
运行以下命令编译 Pipeline：
根据实际情况修改参数文件。下面分别展示两种典型场景：文本语料编码 与 图像语料编码。
  1. 文本语料编码
示例：使用 Qwen3-Embedding-0.6B 对文本语料进行向量化。
examples/parameters/corpus_index_parameter.yaml
  1. 图像语料编码
示例：使用 jinaai/jina-embeddings-v4 对图像语料进行向量化。
examples/parameters/corpus_index_parameter.yaml
运行以下命令执行该 Pipeline：
编码与索引阶段通常涉及大规模语料处理，耗时较长。建议使用 screen 或 nohup 将任务挂载至后台运行，例如：

​
向量检索

以下示例展示如何使用 Retriever Server 在已构建的索引上执行向量检索任务。
examples/corpus_search.yaml
运行以下命令编译 Pipeline：
修改参数：
examples/parameters/corpus_search_parameter.yaml
运行 Pipeline：

​
BM25检索

除了向量检索外，UltraRAG 还内置了经典的 BM25 文本检索算法。BM25 是一种基于 词频–逆文档频率（TF-IDF） 改进的 稀疏检索方法， 常用于快速、轻量的文本语义匹配任务。在实际应用中，BM25 可与向量检索（Dense Retrieval）互补，共同提升检索的覆盖率与召回多样性。 Step 1：构建 BM25 索引 使用 BM25 进行检索前，需要先对文档进行分词并构建稀疏索引。
examples/bm25_index.yaml
运行以下命令编译 Pipeline：
修改参数：
examples/parameters/bm25_index_parameter.yaml
运行：
Step 2：执行 BM25 检索 索引构建完成后，即可进行基于 BM25 的文档检索。
examples/bm25_search.yaml
编译 Pipeline：
修改参数：
examples/parameters/bm25_search_parameter.yaml
运行检索流程：

​
混合检索

在实际应用中，单一的检索方式往往难以兼顾 召回率 与 精准度。 例如，BM25 在关键词匹配上表现出色，而向量检索则在语义理解上更具优势。 因此，UltraRAG 支持将稀疏检索（BM25）与稠密检索（Dense Retrieval）进行融合， 通过混合策略（Hybrid Retrieval）综合两者的优点，进一步提升检索的多样性与鲁棒性。 以下示例展示了如何在同一个 Pipeline 中同时运行 BM25 与向量检索，并通过自定义模块进行结果合并。
你可以参考本示例，将检索方式灵活扩展为任意组合，例如结合本地知识库与在线 Web 检索，或融合文本与图像等多模态检索结果，以构建更强大的混合检索 Pipeline。
examples/hybrid_search.yaml
该 Pipeline 涉及 参数重命名 与 模块复用 机制，可点击链接查看详细说明。
运行以下命令编译 Pipeline：
修改参数：
examples/parameters/hybrid_search_parameter.yaml
运行混合检索 Pipeline：

​
部署检索模型

UltraRAG 完全兼容 OpenAI API 接口规范，因此任何符合该接口标准的Embedding 模型都可以直接接入，无需额外适配或修改代码。 以下示例展示如何使用 vLLM 部署本地检索模型。 step1: 后台部署模型 推荐使用 Screen 方式后台运行，以便实时查看日志和状态。 进入一个新的 Screen 会话：
执行以下命令部署模型（以 Qwen3-Embedding-0.6B 为例）：
script/vllm_serve_emb.sh
出现类似以下输出，表示模型服务启动成功：
按下 Ctrl + A + D 可退出并保持服务在后台运行。 如需重新进入该会话，可执行：
Step 2：修改 Pipeline 参数 以 corpus_search Pipeline 为例，只需将检索后端切换为 openai， 并将 base_url 指向本地 vLLM 服务即可：
examples/parameters/corpus_search_parameter.yaml
完成配置后，即可像使用普通向量检索一样运行.

​
Web Serach API

UltraRAG 原生集成了三种主流 Web 检索 API：Tavily、Exa 以及 GLM。 这些 API 可直接作为 Retriever Server 的检索后端使用，实现在线信息检索与实时知识增强。 Step 1：配置 API Key 使用前需设置对应服务的 API Key。你可以在运行 Pipeline 前手动导出环境变量：
更推荐使用 .env 配置文件 进行统一管理： 在 UltraRAG 根目录下，将模板文件 .env.dev 重命名为 .env， 并填写你的密钥信息，例如：
UltraRAG 会在启动时自动读取该文件并加载相关配置。 Step 2：Web Search 以下示例演示如何使用 Tavily API 进行 Web 检索：
examples/web_search.yaml
编译 Pipeline：
在自动生成的参数文件中，填写数据路径与检索参数：
examples/parameters/web_search_parameter.yaml
执行以下命令即可启动 Web 检索流程：
你可以将 retriever_tavily_search 替换为 retriever_exa_search 或 retriever_zhipuai_search 作为 Web 检索源。

​
部署 Retriever Server

在同一语料库下测试多种 benchmark 或模型性能时，如果每次都重新初始化 retriever server，都会重复加载大型语料库和索引，耗时且低效。 为此，UltraRAG 提供了 常驻式 Retriever Server 部署脚本，可让 retriever 长时间运行在 CPU 或 GPU 上，避免重复加载，加速实验流程。 step1: 参数设置 与普通 retriever server 相同，需先准备配置文件：
script/deploy_retriever_config.json
step2: 后台部署 推荐使用 Screen 以便让 retriever 后台长期运行、随时查看日志。 创建 Screen 会话：
启动 retriever server：
script/deploy_retriever_server.py
Server 启动后，将常驻内存，无需重复加载语料与索引。 step3: 在线检索 在线检索时，无需重新初始化 retriever，只需在 pipeline 中指定已部署的地址：
examples/deploy_corpus_search.yaml
运行以下命令编译 Pipeline：
修改参数：
examples/parameters/deploy_corpus_search_parameter.yaml
运行 Pipeline：