# 大语言模型推理服务

`TUILI` 是运行于墨芯计算卡上的类 vLLM 推理引擎，提供与 OpenAI Chat Completions 兼容的应用程序编程接口（Application Programming Interface，API）子集，支持通过 `/v1/chat/completions` 发起流式或非流式大语言模型推理请求。

## 前提条件

- 安装 Python ≥ 3.7。
- 安装 SOLA Toolkit，详见[《SOLA Toolkit 安装指南》](../installation/sola-toolkit-installation-guide.md)。
- 安装 MOFFETT Container Toolkit ≥ 1.2.0，详见[《MOFFETT Container Toolkit 用户手册》](../AI-Native/mct.md)。
- 安装 MoffettHub CLI 工具，详见 <a href="https://pypi.org/project/moffetthub/" target="_blank">MoffettHub CLI</a>。

## 准备环境

1. 生成容器设备接口（Container Device Interface，CDI）规范文件。

   ```{include} ../_includes/cdi-environment-change.inc
   ```

   ````{tabs}

   ```{tab} SOLA 驱动安装在主机上
   ```bash
   sudo moffett-ctk cdi generate --driver-root / --output=/etc/cdi/moffett.yaml
   ```

   ```{tab} SOLA 驱动通过 SPU Operator 容器镜像安装
   ```bash
   sudo moffett-ctk cdi generate --driver-root /run/moffett/driver --output=/etc/cdi/moffett.yaml
   ```
   ````

2. 获取模型。

   ```bash
   moffetthub-cli list # 查看支持的模型及对应的推理策略
   moffetthub-cli download <model_name> [--strategy <value>] [--output-dir <output_dir>] # 下载模型
   ```

   <model_name>
   : 模型名称。

   --strategy
   : 模型推理策略。默认下载该模型支持的全部策略文件集。

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

3. 获取推理服务镜像。

   ````{tabs}

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

   ```{tab} 离线导入
   ```bash
   wget https://moffett-release.tos-cn-guangzhou.volces.com/macs/macs-v1.11/tuili/tuili-v0.17.4.tar
   docker load -i tuili-v0.17.4.tar
   ```
   ````

## 部署推理服务

1. 启动并进入名为 `tuili-test` 的容器（以墨芯的 home 目录（`/home/moffett`）为例）。

   ```bash
   # 启动容器
   docker run -itd \
          --device moffett.ai/spu=all \
          --net=host \
          --name tuili-test \
          -v /home/moffett/.moffetthub_cache:/home/moffett/workspace/moffetthub_cache \
          moffett/tuili:v0.17.4         
   # 进入容器
   docker exec -it tuili-test /bin/bash
   ```

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

   后续编译、配置和服务启动操作均在容器中进行。
   ```

2. （可选）使用 `pd_separate_cpu` 或 `speculative_cpu` 策略时，设置 CPU 上执行任务的线程数。

   ```bash
   lscpu # 查看逻辑 CPU 数量，例如 CPU(s): 112
   vim /home/moffett/workspace/repos/llama_backend/python/legacy/mf_spu_backend.cc # 将 params.cpuparams.n_threads 修改为逻辑 CPU 数量，例如：112。
   ```

3. 编译 backend。

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

4. 设置推理策略及使用的模型。

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

   仅修改以下字段，保留 `server_config.yaml` 中的其他字段及其原值：

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

   strategy
   : 推理策略。本文示例使用 `pd_auto` 加载模型目录中的 `pd_auto` 策略文件。也可设置为 `auto`，由服务按照 `pd_separate`、`pd_auto`、`decode`、`pd_separate_cpu`、`speculative_cpu` 的优先级，选择模型目录中可用的策略文件。

   model
   : target model 路径，格式为`容器内挂载的模型路径 + <model_name>`，例如：`/home/moffett/workspace/moffetthub_cache/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B`。

   draft_model（可选）
   : draft model 路径。仅当模型支持 `speculative_cpu` 策略时使用，格式同 `model`。

(start-tuili-service)=
5. 启动并检查推理服务状态。

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

   保持推理服务运行。在主机上打开新的终端，执行以下命令检查容器状态，并观察设备进程：

   ```bash
   docker ps --filter name=tuili-test
   mx-smi list
   ```

   容器的 `STATUS` 列显示 `Up` 时，表示容器正在运行。`mx-smi list` 输出的进程信息可用于辅助确认设备进程状态。服务是否能够正常推理，继续执行{ref}`测试推理服务 <test-tuili-service>`中的推理请求。

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

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

(test-tuili-service)=
## 测试推理服务

1. 在主机上打开新的终端，进入已启动的推理服务容器。

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

2. 运行测试命令。

   - 单并发测试

      ```bash
      python3 tests/one_serving_benchmark.py
      ```

   - 多并发测试

      ```bash
      python3 tests/multi_serving_benchmark.py --n_requests <num> # n_requests 指定并发数量，最大不超过 8

      # 示例
      python3 tests/multi_serving_benchmark.py --n_requests 4
      ```

   测试过程中，可通过 `tail -f stdout.log` 命令查看服务日志；可执行 `mx-smi list` 命令查看运行的进程，如果未发现相关进程，参见{ref}`“启动推理服务”步骤 <start-tuili-service>`重启服务。

(stop-tuili-service)=
## 停止推理服务

推理服务使用完成后，在主机上停止并删除专用容器，避免服务持续占用设备资源：

```bash
docker stop tuili-test
docker rm tuili-test
```

执行以下命令确认容器已删除且设备资源已释放：

```bash
docker ps -a --filter name=tuili-test
mx-smi list
```

`docker ps` 输出中不包含 `tuili-test`，且 `mx-smi list` 输出中不包含该推理服务的进程时，表示推理服务及其专用容器已停止，设备资源已释放。