> ## 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.

# Generation

## `generation_init`

**签名**

```python theme={null}
def generation_init(
    backend_configs: Dict[str, Any],
    sampling_params: Dict[str, Any],
    extra_params: Optional[Dict[str, Any]] = None,
    backend: str = "vllm",
) -> None
```

**功能**

* 初始化推理后端与采样参数。
* 支持 `vllm`, `openai`, `hf` 三种后端。
* `extra_params` 可用于传递 `chat_template_kwargs` 或其他特定后端的参数。

***

## `generate`

**签名**

```python theme={null}
async def generate(
    prompt_ls: List[Union[str, Dict[str, Any]]],
    system_prompt: str = "",
) -> Dict[str, List[str]]
```

**功能**

* 纯文本对话生成。
* 自动处理列表中的 Prompt，支持字符串或 OpenAI 格式的字典。

**输出格式（JSON）**

```json theme={null}
{"ans_ls": ["answer for prompt_0", "answer for prompt_1", "..."]}
```

***

## `multimodal_generate`

**签名**

```python theme={null}
async def multimodal_generate(
    multimodal_path: List[List[str]],
    prompt_ls: List[Union[str, Dict[str, Any]]],
    system_prompt: str = "",
    image_tag: Optional[str] = None,
) -> Dict[str, List[str]]
```

**功能**

* 文图多模态对话生成。
* `multimodal_path`: 对应每个 Prompt 的图片路径列表（支持本地路径或 URL）。
* `image_tag`: 如果指定（如 `<img>`），则将图片插入到 Prompt 中该标签的位置；否则默认追加到 Prompt 末尾。

**输出格式（JSON）**

```json theme={null}
{"ans_ls": ["answer with images for prompt_0", "..."]}
```

***

## `multiturn_generate`

**签名**

```python theme={null}
async def multiturn_generate(
    messages: List[Dict[str, str]],
    system_prompt: str = "",
) -> Dict[str, List[str]]
```

**功能**

* 多轮对话生成。
* 仅支持单次调用的生成，不处理批量 Prompt。

**输出格式（JSON）**

```json theme={null}
{"ans_ls": ["assistant response"]}
```

***

## `vllm_shutdown`

**签名**

```python theme={null}
def vllm_shutdown() -> None
```

**功能**

* 显式关闭 vLLM 引擎并释放显存资源。
* 仅在使用 `vllm` 后端时有效。

***

## 参数配置

```yaml servers/generation/parameter.yaml icon="https://mintcdn.com/ultrarag/T7GffHzZitf6TThi/images/yaml.svg?fit=max&auto=format&n=T7GffHzZitf6TThi&q=85&s=69b41e79144bc908039c2ee3abbb1c3b" theme={null}
# servers/generation/parameter.yaml
backend: vllm # options: vllm, openai
backend_configs:
  vllm:
    model_name_or_path: openbmb/MiniCPM4-8B
    gpu_ids: "2,3"
    gpu_memory_utilization: 0.9
    dtype: auto
    trust_remote_code: true
  openai:
    model_name: MiniCPM4-8B
    base_url: http://localhost:8000/v1
    api_key: "abc"
    concurrency: 8
    retries: 3
    base_delay: 1.0
  hf:
    model_name_or_path: openbmb/MiniCPM4-8B
    gpu_ids: '2,3'
    trust_remote_code: true
    batch_size: 8
sampling_params:
  temperature: 0.7
  top_p: 0.8
  max_tokens: 2048
extra_params:
  chat_template_kwargs:
    enable_thinking: false
system_prompt: ""
image_tag: null
```

参数说明：

| 参数                | 类型   | 说明                                             |
| ----------------- | ---- | ---------------------------------------------- |
| `backend`         | str  | 指定生成后端，可选 `vllm`、`openai` 或 `hf`（Transformers） |
| `backend_configs` | dict | 各后端模型及运行环境配置                                   |
| `sampling_params` | dict | 采样参数，用于控制生成多样性与长度                              |
| `extra_params`    | dict | 额外参数，如 `chat_template_kwargs`                  |
| `system_prompt`   | str  | 全局系统提示，将作为 `system` 消息加入上下文                    |
| `image_tag`       | str  | 图像占位符标签（如需）                                    |

`backend_configs` 详细说明：

| 后端         | 参数                       | 说明                        |
| ---------- | ------------------------ | ------------------------- |
| **vllm**   | `model_name_or_path`     | 模型名称或路径                   |
|            | `gpu_ids`                | 使用的 GPU ID（如 `"0,1"`）     |
|            | `gpu_memory_utilization` | GPU 显存占用比例（0–1）           |
|            | `dtype`                  | 数据类型（如 `auto`、`bfloat16`） |
|            | `trust_remote_code`      | 是否信任远程代码                  |
| **openai** | `model_name`             | OpenAI 模型名称或自建兼容模型        |
|            | `base_url`               | API 接口地址                  |
|            | `api_key`                | API 密钥                    |
|            | `concurrency`            | 最大并发请求数                   |
|            | `retries`                | API 重试次数                  |
|            | `base_delay`             | 每次重试基础等待时间（秒）             |
| **hf**     | `model_name_or_path`     | Transformers 模型路径         |
|            | `gpu_ids`                | GPU ID（同上）                |
|            | `trust_remote_code`      | 是否信任远程代码                  |
|            | `batch_size`             | 每次推理批量大小                  |

`sampling_params` 详细说明：

| 参数            | 类型    | 说明                  |
| ------------- | ----- | ------------------- |
| `temperature` | float | 控制随机性，越高生成越多样       |
| `top_p`       | float | nucleus sampling 阈值 |
| `max_tokens`  | int   | 生成最大词元数             |