Skip to main content

​
Function

The Retriever Server is the core retrieval module in UltraRAG, integrating model loading, text encoding, index construction, and retrieval query functions. It natively supports multiple backend interfaces such as Sentence-Transformers, Infinity, and OpenAI, enabling flexible adaptation to corpora of different scales and types to meet the needs of large-scale vectorization and efficient document recall.

​
Usage Examples

​
Corpus Encoding and Indexing

The following example shows how to use the Retriever Server to perform encoding and index construction on a corpus.
examples/corpus_index.yaml
Run the following command to compile the Pipeline:
Modify the parameter file according to the actual situation. Two typical scenarios are shown below: Text Corpus Encoding and Image Corpus Encoding.
  1. Text Corpus Encoding
Example: Using Qwen3-Embedding-0.6B to vectorize text corpus.
examples/parameters/corpus_index_parameter.yaml
  1. Image Corpus Encoding
Example: Using jinaai/jina-embeddings-v4 to vectorize image corpus.
examples/parameters/corpus_index_parameter.yaml
Run the following command to execute this Pipeline:
The encoding and indexing phase usually involves large-scale corpus processing and takes a long time. It is recommended to use screen or nohup to mount the task to run in the background, for example:

​
Vector Retrieval

The following example shows how to use the Retriever Server to perform vector retrieval tasks on the constructed index.
examples/corpus_search.yaml
Run the following command to compile the Pipeline:
Modify parameters:
examples/parameters/corpus_search_parameter.yaml
Run Pipeline:

​
BM25 Retrieval

In addition to vector retrieval, UltraRAG also has a built-in classic BM25 text retrieval algorithm. BM25 is a sparse retrieval method improved based on Term Frequency-Inverse Document Frequency (TF-IDF), often used for fast, lightweight text semantic matching tasks. In practical applications, BM25 can complement dense retrieval to improve retrieval coverage and recall diversity. Step 1: Build BM25 Index Before using BM25 for retrieval, you need to tokenize the document and build a sparse index.
examples/bm25_index.yaml
Run the following command to compile the Pipeline:
Modify parameters:
examples/parameters/bm25_index_parameter.yaml
Run:
Step 2: Execute BM25 Retrieval After the index construction is completed, document retrieval based on BM25 can be performed.
examples/bm25_search.yaml
Compile Pipeline:
Modify parameters:
examples/parameters/bm25_search_parameter.yaml
Run retrieval process:

​
Hybrid Retrieval

In practical applications, a single retrieval method is often difficult to balance recall and precision. For example, BM25 excels at keyword matching, while vector retrieval has advantages in semantic understanding. Therefore, UltraRAG supports fusing sparse retrieval (BM25) with dense retrieval (Dense Retrieval), comprehensively utilizing the advantages of both through hybrid strategies (Hybrid Retrieval) to further improve retrieval diversity and robustness. The following example demonstrates how to run BM25 and vector retrieval simultaneously in the same Pipeline, and merge results through a custom module.
You can refer to this example to flexibly extend retrieval methods into any combination, such as combining local knowledge bases with online Web retrieval, or fusing multi-modal retrieval results such as text and images, to build a more powerful hybrid retrieval Pipeline.
examples/hybrid_search.yaml
This Pipeline involves Parameter Renaming and Module Reuse mechanisms. You can click the links to view detailed instructions.
Run the following command to compile the Pipeline:
Modify parameters:
examples/parameters/hybrid_search_parameter.yaml
Run Hybrid Search Pipeline:

​
Deploy Retrieval Model

UltraRAG is fully compatible with the OpenAI API interface specification, so any Embedding model that conforms to this interface standard can be directly accessed without additional adaptation or code modification. The following example shows how to deploy a local retrieval model using vLLM. Step 1: Background Model Deployment It is recommended to use the Screen method to run in the background to view logs and status in real time. Enter a new Screen session:
Execute the following command to deploy the model (taking Qwen3-Embedding-0.6B as an example):
script/vllm_serve_emb.sh
Seeing output similar to the following indicates that the model service has started successfully:
Press Ctrl + A + D to exit and keep the service running in the background. If you need to re-enter the session, execute:
Step 2: Modify Pipeline Parameters Taking corpus_search Pipeline as an example, just switch the retrieval backend to openai and point base_url to the local vLLM service:
examples/parameters/corpus_search_parameter.yaml
After completing the configuration, you can run it just like using ordinary vector retrieval.

​
Web Search API

UltraRAG natively integrates three mainstream Web retrieval APIs: Tavily, Exa, and GLM. These APIs can be directly used as the retrieval backend of the Retriever Server to achieve online information retrieval and real-time knowledge enhancement. Step 1: Configure API Key You need to set the API Key of the corresponding service before use. You can manually export environment variables before running the Pipeline:
It is recommended to use the .env configuration file for unified management: In the UltraRAG root directory, rename the template file .env.dev to .env, and fill in your key information, for example:
UltraRAG will automatically read this file and load relevant configurations at startup. Step 2: Web Search The following example demonstrates how to use Tavily API for Web retrieval:
examples/web_search.yaml
Compile Pipeline:
Fill in the data path and retrieval parameters in the automatically generated parameter file:
examples/parameters/web_search_parameter.yaml
Execute the following command to start the Web retrieval process:
You can replace retriever_tavily_search with retriever_exa_search or retriever_zhipuai_search as the Web retrieval source.

​
Deploy Retriever Server

When testing multiple benchmarks or model performances under the same corpus, if the retriever server is re-initialized every time, the large corpus and index will be repeatedly loaded, which is time-consuming and inefficient. Therefore, UltraRAG provides a Resident Retriever Server Deployment Script, which allows the retriever to run on the CPU or GPU for a long time, avoiding repeated loading and accelerating the experimental process. Step 1: Parameter Settings Similar to ordinary retriever server, you need to prepare the configuration file first:
script/deploy_retriever_config.json
Step 2: Background Deployment It is recommended to use Screen so that the retriever can run in the background for a long time and logs can be viewed at any time. Create Screen session:
Start retriever server:
script/deploy_retriever_server.py
After the Server starts, it will reside in memory without repeated loading of corpus and index. Step 3: Online Retrieval During online retrieval, there is no need to re-initialize the retriever, just specify the deployed address in the pipeline:
examples/deploy_corpus_search.yaml
Run the following command to compile the Pipeline:
Modify parameters:
examples/parameters/deploy_corpus_search_parameter.yaml
Run Pipeline: