> ## Documentation Index
> Fetch the complete documentation index at: https://ultrarag.openbmb.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Retriever

## `retriever_init`

**签名**

```python theme={null}
async def retriever_init(
    model_name_or_path: str,
    backend_configs: Dict[str, Any],
    batch_size: int,
    corpus_path: str,
    gpu_ids: Optional[object] = None,
    is_multimodal: bool = False,
    backend: str = "sentence_transformers",
    index_backend: str = "faiss",
    index_backend_configs: Optional[Dict[str, Any]] = None,
    is_demo: bool = False,
    collection_name: str = "",
) -> None
```

**功能**

* 初始化检索服务。
* Embedding Backend (backend): 负责将文本/图像转换为向量 (Infinity, SentenceTransformers, OpenAI, BM25)。
* Index Backend (index\_backend): 负责向量的存储与检索 (FAISS, Milvus)。
* Demo Mode: 若 is\_demo=True，强制使用 OpenAI + Milvus 配置，忽略部分参数。

***

## `retriever_embed`

**签名**

```python theme={null}
async def retriever_embed(
    embedding_path: Optional[str] = None,
    overwrite: bool = False,
    is_multimodal: bool = False,
) -> None
```

**功能**

* (非 Demo 模式) 批量计算语料库的向量表示，并保存为 .npy 文件。
* 仅适用于 Dense Retriever 后端（BM25 不支持）。

***

## `retriever_index`

**签名**

```python theme={null}
async def retriever_index(
    embedding_path: str,
    overwrite: bool = False,
    collection_name: str = "",
    corpus_path: str = ""
) -> None
```

**功能**

* 构建检索索引。
* FAISS: 读取 embedding\_path (.npy) 构建本地索引文件。
* Milvus / Demo: 读取 corpus\_path (.jsonl)，生成向量并插入到指定的 collection\_name 中。

***

## `retriever_search`

**签名**

```python theme={null}
async def retriever_search(
    query_list: List[str],
    top_k: int = 5,
    query_instruction: str = "",
    collection_name: str = "",
) -> Dict[str, List[List[str]]]
```

**功能**

* 对单条或多条查询进行检索。
* 自动处理查询向量化（添加 query\_instruction）并在指定 collection\_name (针对 Milvus) 或默认索引中查找 Top-K。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["passage 1", "passage 2"], ["..." ]]} 
```

***

## `retriever_batch_search`

**签名**

```python theme={null}
async def retriever_batch_search(
    batch_query_list: List[List[str]],
    top_k: int = 5,
    query_instruction: str = "",
    collection_name: str = "",
) -> Dict[str, List[List[List[str]]]]
```

**功能**

* etriever\_search 的批处理版本，接受嵌套列表输入。

**输出格式（JSON）**

```json theme={null}
{"ret_psg_ls": [[["psg 1-1"], ["psg 1-2"]], [["psg 2-1"]]]}
```

***

## `bm25_index`

**签名**

```python theme={null}
async def bm25_index(
    overwrite: bool = False,
) -> None
```

**功能**

* 当 `backend="bm25"` 时，构建 BM25 稀疏索引并保存。

***

## `bm25_search`

**签名**

```python theme={null}
async def bm25_search(
    query_list: List[str],
    top_k: int = 5,
) -> Dict[str, List[List[str]]]
```

**功能**

* 基于 BM25 算法进行关键词检索。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["passage 1", "passage 2"], ["..." ]]} 
```

***

## `retriever_deploy_search`

**签名**

```python theme={null}
async def retriever_deploy_search(
    retriever_url: str,
    query_list: List[str],
    top_k: int = 5,
    query_instruction: str = "",
) -> Dict[str, List[List[str]]]
```

**功能**

* 作为客户端，调用部署在 retriever\_url 的远程检索服务进行查询。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["passage 1", "passage 2"], ["..." ]]} 
```

***

## `retriever_exa_search`

**签名**

```python theme={null}
async def retriever_exa_search(
    query_list: List[str],
    top_k: Optional[int] | None = 5,
    retrieve_thread_num: Optional[int] | None = 1,
) -> Dict[str, List[List[str]]]
```

**功能**

* 调用 **Exa** Web 检索（需要 `EXA_API_KEY`）。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["snippet 1", "snippet 2"], ["..." ]]} 
```

***

## `retriever_tavily_search`

**签名**

```python theme={null}
async def retriever_tavily_search(
    query_list: List[str],
    top_k: Optional[int] | None = 5,
    retrieve_thread_num: Optional[int] | None = 1,
) -> Dict[str, List[List[str]]]
```

**功能**

* 调用 **Tavily** Web 检索（需要 `TAVILY_API_KEY`）。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["snippet 1", "snippet 2"], ["..." ]]} 
```

***

## `retriever_zhipuai_search`

**签名**

```python theme={null}
async def retriever_zhipuai_search(
    query_list: List[str],
    top_k: Optional[int] | None = 5,
    retrieve_thread_num: Optional[int] | None = 1,
) -> Dict[str, List[List[str]]]
```

**功能**

* 调用 **智谱AI** `web_search`（需要 `ZHIPUAI_API_KEY`）。

**输出格式（JSON）**

```json theme={null}
{"ret_psg": [["snippet 1", "snippet 2"], ["..." ]]} 
```

***

## 参数配置

```yaml servers/retriever/parameter.yaml icon="https://mintcdn.com/ultrarag/jCMf2kb9doVyOupz/images/yaml.svg?fit=max&auto=format&n=jCMf2kb9doVyOupz&q=85&s=400647b987b98af434dab36623e24edc" theme={null}
model_name_or_path: openbmb/MiniCPM-Embedding-Light
corpus_path: data/corpus_example.jsonl
embedding_path: embedding/embedding.npy
collection_name: wiki

# Embedding Backend Configuration
backend: sentence_transformers # options: infinity, sentence_transformers, openai, bm25
backend_configs:
  infinity:
    bettertransformer: false
    pooling_method: auto
    model_warmup: false
    trust_remote_code: true
  sentence_transformers:
    trust_remote_code: true
    sentence_transformers_encode:
      normalize_embeddings: false
      encode_chunk_size: 256
      q_prompt_name: query
      psg_prompt_name: document
      psg_task: null
      q_task: null
  openai:
    model_name: text-embedding-3-small
    base_url: "https://api.openai.com/v1"
    api_key: "abc"
  bm25:
    lang: en
    save_path: index/bm25

# Index Backend Configuration
index_backend: faiss # options: faiss, milvus
index_backend_configs:
  faiss:
    index_use_gpu: True
    index_chunk_size: 10000
    index_path: index/index.index
  milvus:
    uri: index/milvus_demo.db # Local file for Lite, or http://host:port
    token: null
    id_field_name: id
    vector_field_name: vector
    text_field_name: contents
    index_params:
      index_type: AUTOINDEX
      metric_type: IP

batch_size: 16
top_k: 5
gpu_ids: "1"
query_instruction: ""
is_multimodal: false
overwrite: false
retrieve_thread_num: 1
retriever_url: "http://127.0.0.1:64501"
is_demo: false
```

参数说明：

| 参数 | 类型 | 说明 |
| - | - | - |
| `model_name_or_path` | str | 检索模型路径或名称（如 HuggingFace 模型 ID） |
| `corpus_path` | str | 输入语料 JSONL 文件路径 |
| `embedding_path` | str | 向量文件保存路径（`.npy`） |
| `collection_name` | str | Milvus 集合名称 |
| `backend` | str | 选择检索后端：`infinity`、`sentence_transformers`、`openai`、`bm25` |
| `index_backend` | str | 索引后端：`faiss`, `milvus` |
| `backend_configs` | dict | 各后端的参数配置（见下表） |
| `index_backend_configs` | dict | 各索引后端的参数配置（见下表） |
| `batch_size` | int | 向量生成或检索的批大小 |
| `top_k` | int | 返回的候选段落数量 |
| `gpu_ids` | str | 指定可见 GPU 设备，如 `"0,1"` |
| `query_instruction` | str | 查询前缀（instruction-tuning 模型使用） |
| `is_multimodal` | bool | 是否启用多模态嵌入（如图像） |
| `overwrite` | bool | 若已存在嵌入或索引文件是否覆盖 |
| `retrieve_thread_num` | int | 外部 Web 检索（Exa/Tavily/Zhipu）并发线程数 |
| `retriever_url` | str | 部署 retriever server 的 url |
| `is_demo` | bool | 演示模式开关（强制使用 OpenAI+Milvus，简化配置） |

`backend_configs` 子项：

| 后端 | 参数 | 类型 | 说明 |
| - | - | - | - |
| **infinity** | `bettertransformer` | bool | 是否启用高效推理优化 |
| | `pooling_method` | str | 池化方式（如 `auto`, `mean`） |
| | `model_warmup` | bool | 是否预加载模型到显存 |
| | `trust_remote_code` | bool | 是否信任远程代码（适用于自定义模型） |
| **sentence\_transformers** | `trust_remote_code` | bool | 是否信任远程模型代码 |
| | `sentence_transformers_encode` | dict | 编码详细参数，见下表 |
| **openai** | `model_name` | str | OpenAI 模型名称（如 `text-embedding-3-small`） |
| | `base_url` | str | API 基地址 |
| | `api_key` | str | OpenAI API 密钥 |
| **bm25** | `lang` | str | 语言（决定停用词与分词器） |
| | `save_path` | str | BM25 稀疏索引的保存目录 |

`sentence_transformers_encode` 参数：

| 参数 | 类型 | 说明 |
| - | - | - |
| `normalize_embeddings` | bool | 是否归一化向量 |
| `encode_chunk_size` | int | 编码块大小（避免显存溢出） |
| `q_prompt_name` | str | 查询模板名 |
| `psg_prompt_name` | str | 段落模板名 |
| `q_task` | str | 任务描述（针对特定模型需要指定 Task 的情况） |
| `psg_task` | str | 任务描述（针对特定模型需要指定 Task 的情况） |

`index_backend_configs` 参数：

| 后端 | 参数 | 类型 | 说明 |
| - | - | - | - |
| faiss | index\_use\_gpu | bool | 是否使用 GPU 构建和检索索引 |
| | index\_chunk\_size | int | 构建索引时的分批大小 |
| | index\_path | str | FAISS 索引文件的保存路径（.index） |
| milvus | uri | str | Milvus 连接地址（本地文件路径即启用 Milvus Lite） |
| | token | str | 认证 Token（如需要） |
| | id\_field\_name | str | 主键字段名（默认 id） |
| | vector\_field\_name | str | 向量字段名（默认 vector） |
| | text\_field\_name | str | 文本内容字段名（默认 contents） |
| | id\_max\_length | int | 字符串主键的最大长度 |
| | text\_max\_length | int | 文本字段的最大长度（超过截断） |
| | metric\_type | str | 距离度量方式（如 IP 内积, L2 欧式距离） |
| | index\_params | Dict | 索引构建参数（如 index\_type: AUTOINDEX） |
| | search\_params | Dict | 检索参数（如 nprobe 等） |
| | index\_chunk\_size | int | 插入数据时的批处理大小 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.