跳转到主要内容

​
作用

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

​
使用示例

​
语料库编码与索引

以下示例展示如何使用 Retriever Server 对语料库进行编码与索引构建。
/images/yaml.svgexamples/corpus_index.yaml
# MCP Server
servers:
  retriever: servers/retriever

# MCP Client Pipeline
pipeline:
- retriever.retriever_init
- retriever.retriever_embed
- retriever.retriever_index
运行以下命令编译 Pipeline： 
ultrarag build examples/corpus_index.yaml
根据实际情况修改参数文件。下面分别展示两种典型场景：文本语料编码 与 图像语料编码。
  1. 文本语料编码
示例：使用 Qwen3-Embedding-0.6B 对文本语料进行向量化。
/images/yaml.svgexamples/parameters/corpus_index_parameter.yaml
retriever:
  backend: sentence_transformers # 我们这里以st为例
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  embedding_path: embedding/embedding.npy
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_chunk_size: 50000
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  model_name_or_path: Qwen/Qwen3-Embedding-0.6B
  overwrite: false
  1. 图像语料编码
示例：使用 jinaai/jina-embeddings-v4 对图像语料进行向量化。
/images/yaml.svgexamples/parameters/corpus_index_parameter.yaml
retriever:
  backend: sentence_transformers
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
        psg_prompt_name: null
        psg_task: retrieval
        q_prompt_name: query
        q_task: retrieval
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  corpus_path: corpora/image.jsonl
  embedding_path: embedding/embedding.npy
  faiss_use_gpu: true
  gpu_ids: 0,1
  gpu_ids: 1
  index_chunk_size: 50000
  index_path: index/index.index
  is_multimodal: false
  is_multimodal: true
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  model_name_or_path: jinaai/jina-embeddings-v4
  overwrite: false
运行以下命令执行该 Pipeline： 
ultrarag run examples/corpus_index.yaml
编码与索引阶段通常涉及大规模语料处理，耗时较长。建议使用 screen 或 nohup 将任务挂载至后台运行，例如： 
nohup ultrarag run examples/corpus_index.yaml > log.txt 2>&1 &

​
向量检索

以下示例展示如何使用 Retriever Server 在已构建的索引上执行向量检索任务。
/images/yaml.svgexamples/corpus_search.yaml
# MCP Server
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever

# MCP Client Pipeline
pipeline:
- benchmark.get_data
- retriever.retriever_init
- retriever.retriever_search
运行以下命令编译 Pipeline： 
ultrarag build examples/corpus_search.yaml
修改参数：
/images/yaml.svgexamples/parameters/corpus_search_parameter.yaml
benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
retriever:
  backend: sentence_transformers
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  model_name_or_path: Qwen/Qwen3-Embedding-0.6B
  query_instruction: ''
  top_k: 5
运行 Pipeline： 
ultrarag run examples/corpus_search.yaml

​
BM25检索

除了向量检索外，UR-2.0 还内置了经典的 BM25 文本检索算法。BM25 是一种基于 词频–逆文档频率（TF-IDF） 改进的 稀疏检索方法， 常用于快速、轻量的文本语义匹配任务。在实际应用中，BM25 可与向量检索（Dense Retrieval）互补，共同提升检索的覆盖率与召回多样性。 Step 1：构建 BM25 索引 使用 BM25 进行检索前，需要先对文档进行分词并构建稀疏索引。
/images/yaml.svgexamples/bm25_index.yaml
# MCP Server
servers:
  retriever: servers/retriever

# MCP Client Pipeline
pipeline:
- retriever.retriever_init
- retriever.bm25_index
运行以下命令编译 Pipeline： 
ultrarag build examples/bm25_index.yaml
修改参数：
/images/yaml.svgexamples/parameters/bm25_index_parameter.yaml
retriever:
  backend: sentence_transformers
  backend: bm25
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  overwrite: false
运行： 
ultrarag run examples/bm25_index.yaml
Step 2：执行 BM25 检索 索引构建完成后，即可进行基于 BM25 的文档检索。
/images/yaml.svgexamples/bm25_search.yaml
# MCP Server
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever

# MCP Client Pipeline
pipeline:
- benchmark.get_data
- retriever.retriever_init
- retriever.bm25_search
编译 Pipeline： 
ultrarag build examples/bm25_search.yaml
修改参数：
/images/yaml.svgexamples/parameters/bm25_search_parameter.yaml
benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
retriever:
  backend: sentence_transformers
  backend: bm25
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  top_k: 5
运行检索流程： 
ultrarag run examples/bm25_search.yaml

​
混合检索

在实际应用中，单一的检索方式往往难以兼顾 召回率 与 精准度。 例如，BM25 在关键词匹配上表现出色，而向量检索则在语义理解上更具优势。 因此，UR-2.0 支持将稀疏检索（BM25）与稠密检索（Dense Retrieval）进行融合， 通过混合策略（Hybrid Retrieval）综合两者的优点，进一步提升检索的多样性与鲁棒性。 以下示例展示了如何在同一个 Pipeline 中同时运行 BM25 与向量检索，并通过自定义模块进行结果合并。
你可以参考本示例，将检索方式灵活扩展为任意组合，例如结合本地知识库与在线 Web 检索，或融合文本与图像等多模态检索结果，以构建更强大的混合检索 Pipeline。
/images/yaml.svgexamples/hybrid_search.yaml
# MCP Server
servers:
  benchmark: servers/benchmark
  dense: servers/retriever
  bm25: servers/retriever
  custom: servers/custom

# MCP Client Pipeline
pipeline:
- benchmark.get_data
- dense.retriever_init
- bm25.retriever_init
- dense.retriever_search:
    output:
      ret_psg: dense_psg
- bm25.bm25_search:
    output:
      ret_psg: sparse_psg
- custom.merge_passages:
    input:
      ret_psg: dense_psg
      temp_psg: sparse_psg
该 Pipeline 涉及 参数重命名 与 模块复用 机制，可点击链接查看详细说明。
运行以下命令编译 Pipeline： 
ultrarag build examples/hybrid_search.yaml
修改参数：
/images/yaml.svgexamples/parameters/hybrid_search_parameter.yaml
benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
bm25:
  backend: sentence_transformers
  backend: bm25
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  top_k: 5
custom: {}
dense:
  backend: sentence_transformers
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      model_name: text-embedding-3-small
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  index_path: index1/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  model_name_or_path: Qwen/Qwen3-Embedding-0.6B
  query_instruction: ''
  top_k: 5
运行混合检索 Pipeline： 
ultrarag run examples/hybrid_search.yaml

​
部署检索模型

UR-2.0 完全兼容 OpenAI API 接口规范，因此任何符合该接口标准的Embedding 模型都可以直接接入，无需额外适配或修改代码。 以下示例展示如何使用 vLLM 部署本地检索模型。 step1: 后台部署模型 推荐使用 Screen 方式后台运行，以便实时查看日志和状态。 进入一个新的 Screen 会话： 
screen -S retriever
执行以下命令部署模型（以 Qwen3-Embedding-0.6B 为例）：
script/vllm_serve_emb.sh
CUDA_VISIBLE_DEVICES=1 python -m vllm.entrypoints.openai.api_server \
    --served-model-name qwen-embedding \
    --model Qwen/Qwen3-Embedding-0.6B \
    --trust-remote-code \
    --host 127.0.0.1 \
    --port 65502 \
    --task embed \
    --gpu-memory-utilization 0.9
出现类似以下输出，表示模型服务启动成功： 
(APIServer pid=2270761) INFO:     Started server process [2270761]
(APIServer pid=2270761) INFO:     Waiting for application startup.
(APIServer pid=2270761) INFO:     Application startup complete.
按下 Ctrl + A + D 可退出并保持服务在后台运行。 如需重新进入该会话，可执行： 
screen -r retriever
Step 2：修改 Pipeline 参数 以 corpus_search Pipeline 为例，只需将检索后端切换为 openai， 并将 base_url 指向本地 vLLM 服务即可：
/images/yaml.svgexamples/parameters/corpus_search_parameter.yaml
benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
retriever:
  backend: sentence_transformers
  backend: openai
  backend_configs:
    bm25:
      lang: en
    infinity:
      bettertransformer: false
      device: cuda
      model_warmup: false
      pooling_method: auto
      trust_remote_code: true
    openai:
      api_key: ''
      base_url: https://api.openai.com/v1
      base_url: http://127.0.0.1:65502/v1
      model_name: text-embedding-3-small
      model_name: qwen-embedding
    sentence_transformers:
      device: cuda
      sentence_transformers_encode:
        encode_chunk_size: 10000
        normalize_embeddings: false
        psg_prompt_name: document
        psg_task: null
        q_prompt_name: query
        q_task: null
      trust_remote_code: true
  batch_size: 16
  corpus_path: data/corpus_example.jsonl
  faiss_use_gpu: true
  gpu_ids: 0,1
  index_path: index/index.index
  is_multimodal: false
  model_name_or_path: openbmb/MiniCPM-Embedding-Light
  query_instruction: ''
  top_k: 5
完成配置后，即可像使用普通向量检索一样运行.

​
Web Serach API

UR-2.0 原生集成了三种主流 Web 检索 API：Tavily、Exa 以及 GLM。 这些 API 可直接作为 Retriever Server 的检索后端使用，实现在线信息检索与实时知识增强。 Step 1：配置 API Key 使用前需设置对应服务的 API Key。你可以在运行 Pipeline 前手动导出环境变量： 
export TAVILY_API_KEY="your retriever key"
更推荐使用 .env 配置文件 进行统一管理： 在 UR-2.0 根目录下，将模板文件 .env.dev 重命名为 .env， 并填写你的密钥信息，例如： 
LLM_API_KEY=
RETRIEVER_API_KEY=
TAVILY_API_KEY=tvly-dev-yourapikeyhere
EXA_API_KEY=
ZHIPUAI_API_KEY=
UR-2.0 会在启动时自动读取该文件并加载相关配置。 Step 2：Web Search 以下示例演示如何使用 Tavily API 进行 Web 检索：
/images/yaml.svgexamples/web_search.yaml
# MCP Server
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever

# MCP Client Pipeline
pipeline:
- benchmark.get_data
- retriever.retriever_tavily_search
编译 Pipeline： 
ultrarag build examples/web_search.yaml
在自动生成的参数文件中，填写数据路径与检索参数：
/images/yaml.svgexamples/parameters/web_search_parameter.yaml
benchmark:
  benchmark:
    key_map:
      gt_ls: golden_answers
      q_ls: question
    limit: -1
    name: nq
    path: data/sample_nq_10.jsonl
    seed: 42
    shuffle: false
retriever:
  retrieve_thread_num: 1
  top_k: 5
执行以下命令即可启动 Web 检索流程： 
ultrarag run examples/web_search.yaml
你可以将 retriever_tavily_search 替换为 retriever_exa_search 或 retriever_zhipuai_search Web 检索源。