# 推理应用示例

`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>。

## 运行环境准备

### 生成 CDI 配置文件

执行以下命令生成 CDI 配置文件，具体请参见 [MOFFETT Container Toolkit 用户手册](../AI-Native/mct.md)。

```bash
sudo moffett-ctk cdi generate --output=/etc/cdi/moffett.yaml
```

### 获取大模型

1. 查看模型支持的策略。

   ```bash
   moffetthub-cli list
   ```

2. 下载模型。
   
   ```
   moffetthub-cli download <model_name> [--strategy <value>] [--output-dir <output_dir>]
   ```

   - `<model_name>`：指定下载的模型，目前支持：deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B、deepseek-ai/DeepSeek-R1-Distill-Qwen-32B、meta-llama/Llama-3-70B。

   - `--strategy`：指定要下载的运行策略文件集。不同模型支持的值如下表，默认值为 `all`（下载该模型支持的全部策略文件集）。不受支持的策略会报错，请先查看 `moffetthub-cli list`。

     ::: nested-table
     | 模型                                       | 策略值 -> 对应文件集                                   |
     | ------------------------------------------ | ----------------------------------------- |
     | deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B  | pd_auto -> 📂pd_auto<br />speculative_cpu -> 📄decode_cpu.gguf              |
     | deepseek-ai/DeepSeek-R1-Distill-Qwen-32B   | decode -> 📂decode<br />pd_separate -> 📂prefill + 📂decode<br />pd_separate_cpu -> 📂prefill + 📄decode_cpu.gguf<br />speculative -> 📂speculative<br />speculative_cpu -> 📄decode_cpu.gguf  |
     | meta-llama/Llama-3-70B                     | decode -> 📂decode<br />pd_separate -> 📂prefill + 📂decode   |
     :::

   - `--output-dir`：指定模型存储的路径，默认为 home 目录下的 `.moffetthub_cache`，例如：`/home/moffett/.moffetthub_cache`。

### 获取推理服务镜像

````{tabs}

```{tab} 在线拉取
```Bash
docker pull moffett/tuili:v0.17.2
```

```{tab} 离线导入
```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` 的容器。

```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
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 阶段使用同一套静态模型。<br />该策略不支持 DeepSeek-R1-Distill-Qwen-32B、Llama-3-70B 模型的并发测试。      |
  | pd_separate_cpu    | Prefill 阶段在 SPU 上使用 PP 模式运行，Decode 阶段在 CPU 上运行。   |
  | speculative_cpu    | 投机方案，在 SPU 上运行 target model，在 CPU 上运行 draft model。<br />该策略不支持并发测试。  |
  :::

## 运行推理服务

### 操作步骤

1. 启动推理服务

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

   ```{admonition} 注意
   :class: caution

   修改 `server_config.yaml` 中的模型及策略后，需重启推理服务，再运行推理测试。
   ```

2. 执行以下命令运行推理服务测试，包括单例测试和并发测试。

   ```
   # 单例测试
   python3 tests/one_serving_benchmark.py --tokenizer <tokenizer>
   ```

   ```bash
   # 并发测试
   python3 tests/multi_serving_benchmark.py --tokenizer <tokenizer> --n_requests <num>
   ```

   支持的参数如下：
   
   - `--n_requests`：指定 batch 的数量，最大不超过 8。
   - `--tokenizer`：指定模型的 tokenizer，具体如下表所示。

     ::: nested-table
     | 模型                                        | --tokenizer 配置                          |
     | ------------------------------------------ | ----------------------------------------- |
     | deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B  | <model_path>/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B/pd_auto                          |
     | deepseek-ai/DeepSeek-R1-Distill-Qwen-32B   | <model_path>/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/prefill<br /><model_path>/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/decode<br /><model_path>/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/speculative|
     | meta-llama/Llama-3-70B                     | <model_path>/meta-llama/Llama-3-70B/prefill<br /><model_path>/meta-llama/Llama-3-70B/decode |
     :::

     ```{admonition} 注意
     :class: caution

     - DeepSeek-R1-Distill-Qwen-32B 和 Llama-3-70B 模型的 `--tokenizer` 设置建议与 `server_config.yaml` 中指定的推理策略（`strategy`）保持一致。如果 `strategy` 设置为 `auto`，则对应  `--tokenizer` 为 `pd_auto` 或 `prefill`。
     - 使用 DeepSeek-R1-Distill-Qwen-32B 模型推理需占用 16 个 Device。
     - 使用 Llama-3-70B 模型推理需占用 32 个 Device，仅支持在部署了 8 张 S40 系列计算卡的服务器上运行。
     ```

### 测试用例

- 单例测试用例

  ```bash
  # DeepSeek-R1-Distill-Qwen-1.5B

  # strategy = auto or pd_auto
  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-32B

  # strategy = auto, pd_separate, or pd_separate_cpu
  python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/prefill/

  # strategy = decode
  python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/decode/

  # strategy = speculative_cpu
  python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/speculative/
  ```
  ```bash
  # Llama-3-70B

  # strategy = auto, pd_separate, or pd_separate_cpu
  python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/meta-llama/Llama-3-70B/prefill/

  # strategy = decode
  python3 tests/one_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/meta-llama/Llama-3-70B/decode/
  ```

- 并发测试用例  

  ```bash
  # DeepSeek-R1-Distill-Qwen-1.5B

  # strategy = auto or pd_auto
  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
  ```

  ```bash
  # DeepSeek-R1-Distill-Qwen-32B

  # strategy = auto, pd_separate, or pd_separate_cpu
  python3 tests/multi_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B/prefill/ --n_requests 8
  ```

  ```bash
  # Llama-3-70B
  
  # strategy = auto, pd_separate, or pd_separate_cpu
  python3 tests/multi_serving_benchmark.py --tokenizer /home/moffett/workspace/moffetthub_cache/deepseek-ai/meta-llama/Llama-3-70B/prefill/ --n_requests 8
  ```

## 结束推理服务

推理服务使用完成后，需在主机上结束相关进程，避免持续占用设备资源影响其他操作（如升级 SOLA Toolkit 版本）。步骤如下：

1. 查询并结束运行中的推理服务相关进程。
   
   ```
   mx-smi list 
   sudo pkill python    # 结束推理服务相关进程
   sudo kill -9 <PID>   # 结束其他进程
   ```

2. 停用并删除推理服务的容器。

   ```
   docker ps -a | grep <tuili-name>
   docker stop <tuili-name> && docker rm <tuili-name>
   ```