# 推理应用示例

`TUILI` 是运行于墨芯计算卡上的类 vLLM 推理引擎，提供与 OpenAI 接口兼容的 API，支持高效部署大语言模型推理服务。

## 前提条件

- 安装 Python 且版本 ≥ 3.7。
- 安装 SOLA Toolkit 且版本 ≥ 3.12.0，具体请参见 [SOLA Toolkit 安装指南](../installation/sola-toolkit-installation-guide.md)。
- 安装 MOFFETT Container Toolkit 且开启 CDI，具体请参见 [MOFFETT Container Toolkit 用户手册](../AI-Native/mct.md)。
- 安装 MoffettHub CLI 工具，具体请参见 <a href="https://pypi.org/project/moffetthub/" target="_blank">MoffettHub CLI</a>。


## 运行环境准备

### 获取大模型

1. 查看支持的模型列表。

   ```bash
   moffetthub-cli list
   ```

   支持的模型及策略如下表所示：

   ::: nested-table
   | 模型名称                                    | 支持的策略                                      |
   | ------------------------------------------ | ----------------------------------------- |
   | deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B  | pd_auto<br />speculative_cpu（仅作为 draft model 辅助使用）                          |
   | deepseek-ai/DeepSeek-R1-Distill-Qwen-32B   | decode<br />pd_separate<br />pd_separate_cpu<br />speculative<br />speculative_cpu  |
   | meta-llama/Llama-3-70B                     | decode<br />pd_separate   |
   :::

   ```{admonition} 须知
   :class: note

   - 运行 DeepSeek-R1-Distill-Qwen-32B 模型需占用 16 个设备。
   - 运行 Llama-3-70B 模型需占用 32 个设备，仅支持在部署了 8 张 S40 系列计算卡的服务器上运行。
   ```

2. 下载用于推理的模型（以 DeepSeek-R1-Distill-Qwen-1.5B 为例）。
   
   模型默认存储在用户 home 目录下的 `.moffetthub_cache` 目录中（例如：`/home/moffett/.moffetthub_cache`），可使用 `--output-dir` 参数指定模型存储的路径。

   ```
   moffetthub-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B
   ```

### 获取推理服务镜像

选择以下任意一种方式获取镜像：

- 在线拉取

  ```bash
  docker pull moffett/tuili:v0.17.2
  ```

- 离线导入

  ```bash
  wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/Ubuntu/business/tuili/tuili-v0.17.2.tar
  docker load -i tuili-v0.17.2.tar
  ```

## 部署推理服务

### 创建容器

以墨芯的 home 目录（`/home/moffett`）为例，创建名为 `tuili-test` 的容器：

1. 启动推理服务的容器。

   ```bash
   docker run -itd -v /home/moffett/.moffetthub_cache:/home/moffett/workspace/moffetthub_cache --device moffett.ai/spu=all --name tuili-test moffett/tuili:v0.17.2 
   ```

2. 进入推理服务的容器。

   ```bash
   docker exec -it tuili-test /bin/bash
   ```

```{admonition} 须知
:class: note

后续操作均在容器中进行。
```

### 设置 CPU 上执行任务的线程数

1. 查看 NUMA 节点及对应的 CPU 数量。

   ```bash
   lscpu
   ```

   ```
   ...
   NUMA:
     NUMA node(s):           2
     NUMA node0 CPU(s):      0-63
     NUMA node1 CPU(s):      64-127
   ...
   ```

2. 修改线程数配置。

   编辑 `mf_spu_backend.cc` 文件：

   ```bash
   vim /home/moffett/workspace/repos/llama_backend/python/legacy/mf_spu_backend.cc
   ```

   将 `params.cpuparams.n_threads` 的值修改为 `NUMA node0 CPU(s)` 的数量，例如：64。

   ```
   ...   
   # pybind_draft_init 函数
   params.numa = GGML_NUMA_STRATEGY_ISOLATE;
   params.cpuparams.n_threads = 64;
   ...
   ```

### 编译 backend

```bash
cd /home/moffett/workspace/repos/llama_backend/
bash build.sh
```

### 设置模型和策略

编辑 `server_config.yaml` 文件：

```bash
vim /home/moffett/workspace/repos/server_config.yaml
```

修改 `serving` 相关参数：

```
...
serving:
 strategy: pd_auto
 model: /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B
 # draft_model: ''
...
```

- `model`：指定 target model 的路径，例如：`/home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B`。
- `draft_model`（可选）：指定 draft model 的路径，仅支持 `speculative_cpu` 策略下使用，格式同 `model` 。

  ```{admonition} 须知
  :class: note

  模型的路径为挂载到容器内的路径。
  ```

- `strategy`：支持的推理策略，如下表所示。策略的优先级从上到下依次降低，推荐使用 `auto` 自动根据优先级选择策略。

  ::: nested-table
  | 策略值              | 说明                                      |
  | ------------------ | ----------------------------------------- |
  | auto               | 按照优先级从高到低的顺序自动选择以下策略。                           |
  | pd_separate        | Prefill 阶段使用 PP（Pipeline Parallelism，流水线并行）模式，Decode 阶段使用 TP（Tensor Parallelism，张量并行）模式。  |
  | pd_auto            | 自动管理 Decode 和 Prefill 阶段的调度。   |
  | decode             | Prefill 和 Decode 阶段使用同一套静态模型；该策略不支持 Llama-3-70B 模型的并发测试。      |
  | pd_separate_cpu    | Prefill 阶段在 SPU 上使用 PP 模式运行，Decode 阶段在 CPU 上运行。   |
  | speculative_cpu    | 投机方案，在 CPU 上运行 draft model, 在 SPU 上运行 target model；该策略不支持并发测试。  |
  :::

## 运行推理服务示例

1. 启动推理服务

   ```bash
   cd /home/moffett/workspace/repos
   export PYTHONPATH=$PYTHONPATH:. # 将当前路径添加到 PYTHONPATH
   python examples/server.py > stdout.log 2>&1 & # 启动推理服务
   tail -f stdout.log # 查看启动日志
   ```
2. 大模型推理测试

   - 单例测试（以 DeepSeek-R1-Distill-Qwen-1.5B 模型为例）

     ```bash
     python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B/pd_auto/
     ```

   - 并发测试（以 DeepSeek-R1-Distill-Qwen-1.5B 模型为例，`n_requests` 表示 batch 数量，最大不超过 8）     

     ```bash
     python3 tests/multi_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B/pd_auto/ --n_requests 8
     ```