mindie-turbo 2.0rc1
MindIE Turbo: An LLM inference acceleration framework featuring extensive plugin collections optimized for Ascend devices.
License: Apache 2.0
Requires Python: >=3.9

# MindIE-Turbo

## 介绍
MindIE Turbo是华为为昇腾芯片开发的大语言模型推理引擎加速插件库，包含自研的大语言模型优化算法及推理引擎相关优化。MindIE Turbo提供一系列模块化和插件化接口，支持外部推理引擎的接入和加速。

目前，MindIE Turbo已支持vLLM的适配。通过与vLLM和vLLM-ascend的对接，能够提供更强的性能和更多的推理优化量化算法。在实际使用中，用户只需在对应的Python环境中安装MindIE Turbo，系统会自动检测vLLM并启用优化，无需修改代码即可完成性能提升。

## 支持框架：
**vLLM**：vLLM是伯克利大学LMSYS组织开源的大语言模型高速推理框架，旨在极大地提升实时场景下的语言模型服务的吞吐率与内存使用率，提供易用、快速、便宜的LLM服务。目前MindIE Turbo已经支持通过vLLM-Ascend一键叠加到vLLM框架并进行推理加速使能。

## 架构说明
MindIE-Turbo主要包含以下模块（部分为预留模块）:

- adaptor: 适配不同推理框架的优化实现
  - vllm: VLLM框架适配
- distributed: 分布式能力支持
- scheduler: 加速调度策略支持
- functional: 通用功能函数
- interface: 通用接口定义
- layers: 网络层实现
- moe: MoE相关实现
- quantize: 量化相关实现
- spec_decode: Speculative Decoding实现
- utils: 通用工具

## 环境准备
### 硬件环境及操作系统准备
- 目前MindIE Turbo支持的硬件环境：Atlas 800I A2 推理产品（32GB/64GB）
- 支持的操作系统请参见《MindIE安装指南》中“环境准备 > 支持的操作系统”章节

### 开发环境准备
在安装MindIE Turbo之前请检查以下组件的配套关系和安装情况：

<!-- 表格标题：组件配套驱动与固件（HDK） -->

| 组件         | 配套版本            | 获取链接       |
| ------------ | ------------------- | -------------- |
| **驱动与固件（HDK）** | >=24.0             | [获取链接](https://support.huawei.com/enterprise/zh/ascend-computing/ascend-hdk-pid-252764743/software)       |
| **CANN**     | >=8.0.0             | [获取链接](https://www.hiascend.com/developer/download/community/result?module=ie%2Bpt%2Bcann)      |
| **PyTorch**  | 2.5.1               | [获取链接](https://www.hiascend.com/developer/download/community/result?module=ie%2Bpt%2Bcann)       |
| **Python**   | 3.10.x、3.11.x      | -              |

1、安装配套版本的驱动与固件（HDK）、CANN软件（Toolkit、Kernels 和 NNAL）请参考《CANN 软件安装指南》，在“选择安装场景”页面，按下列指引选择：
- **安装方式**: 在物理机上安装
- **操作系统**: 根据实际情况选择
- **业务场景**: 选择训练 & 推理 & 开发调试

2、安装PyTorch，请参考组件[安装Pytorch框架](https://www.hiascend.com/document/detail/zh/Pytorch/600/configandinstg/instg/insg_0005.html)与[安装torch_npu插件](https://www.hiascend.com/document/detail/zh/Pytorch/600/configandinstg/instg/insg_0006.html)安装

## 使用说明
### 1. 安装指南
1. 联系相关人员获取 MindIE Turbo 软件包。

2. 将 MindIE Turbo 软件包上传到安装环境的任意路径（例如：`/home/package`）。

3. 进入软件包所在路径：

   ```bash
   cd /home/package
   ```
4. 执行以下命令安装 MindIE Turbo：
   ```bash
   python setup.py install
   ```
5. 返回上级目录，执行以下命令验证是否安装成功：
   ```bash
   cd ../
   pip show mindie_turbo
   ```
   如果出现如下示例结果，表示安装成功：
   ```bash
   Version: 1.0rc1
   Summary: MindIE Turbo: An LLM inference acceleration framework featuring extensive plugin collections optimized for Ascend devices.
   Home-page: 
   Author: ascend
   Author-email: 
   License: Apache 2.0
   Location: /usr/local/lib/python3.11/site-packages
   Requires: filelock, fsspec, jinja2, markupsafe, mpmath, networkx, sympy, torch, typing-extensions
   Required-by: 
   ```

### 2. 快速使用
MindIE Turbo不会修改任何使用行为，与原有框架保持一致，使得用户可以很轻松的应用并迁移项目。以vLLM框架为例：
1. 安装vLLM与vLLM-Ascend。

   请参考[vLLM-Ascend安装文档](https://vllm-ascend.readthedocs.io/en/latest/installation.html)进行安装。

2. 根据需要，进行离线批量推理或在线服务推理。
- 离线批量推理
   请参考[vLLM离线推理示例文档](https://docs.vllm.ai/en/latest/getting_started/quickstart.html#offline-batched-inference)进行推理。以下为最简单的示例（来自[vllm/examples/offline_inference/basic/basic.py](https://github.com/vllm-project/vllm/blob/main/examples/offline_inference/basic/basic.py)，请根据需要修改：
   ```python 
   from vllm import LLM, SamplingParams

   # Sample prompts.
   prompts = [
      "Hello, my name is",
      "The president of the United States is",
      "The capital of France is",
      "The future of AI is",
   ]
   # Create a sampling params object.
   sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

   # Create an LLM.
   llm = LLM(model="facebook/opt-125m")
   # Generate texts from the prompts. The output is a list of RequestOutput objects
   # that contain the prompt, generated text, and other information.
   outputs = llm.generate(prompts, sampling_params)
   # Print the outputs.
   for output in outputs:
      prompt = output.prompt
      generated_text = output.outputs[0].text
      print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
   ```
- 启动在线推理服务
请根据[vLLM在线服务示例文档](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html)启动服务。以下以Qwen2.5-1.5B-Instruct简单示例，请根据需要修改：
   ```bash
   vllm serve Qwen/Qwen2.5-1.5B-Instruct
   ```


### 3. MindIE Turbo环境变量说明
| 环境变量名                           | 默认值 | 功能说明                                      | 配置说明                                      |
|------------------------------------|--------|-------------------------------------------|-------------------------------------------|
| VLLM_OPTIMIZATION_LEVEL        | 2      | 控制MindIE Turbo在vLLM中的优化级别 | 0：不启用MindIE Turbo优化。 1：启用通用优化手段，风险最低。 2：启用性能更优的算子，可能会造成精度变化。 3：启用高度融合的算子优化。                |
| USING_SAMPLING_TENSOR_CACHE        | 0      | 是否启用张量缓存，该优化项仅用于V0 vLLM, chunkprefill和beamsearch场景下不支持 | 0：不启用。 1：启用。                    |
| USING_LCCL_COM                     | 1      | 是否启用LCCL通信，LCCL通信暂未支持多机通信 | 0：不启用。 1：启用。                    |


## 支持特性
### W8A8量化插件
目前在MindIE Turbo中已经支持了MindStudio自研的W8A8与W8A8QuantAttention算法。通过MindStudio量化的模型可以直接通过MindIE Turbo在vLLM上一键使能。

vLLM及vLLM-Ascend已实现负责量化配置解析的`QuantConfig`、负责对量化方法进行识别和选择的`Quantizer`，MindIE-Turbo将在上述基础上实现`QuantMethod`，即`AscendW8A8LinearMethod`，基于MindIE全栈提供量化实现。

具体而言，`AscendW8A8LinearMethod`提供一下四个接口：
#### get_weight接口
1. 接口功能：

   返回W8A8量化所需要的weight参数名与tensor。

2. 参数说明：


   | 参数名称     | 是否必选 | 类型 | 默认值 | 描述                                      | 安全声明                               |
   | ------------ | -------- | ---- | ------ | ----------------------------------------- | -------------------------------------- |
   | input_size   | 是       | int  | -      | W8A8 linear的输入维度大小。              | 推理强依赖数据的合法性，需由用户保证。 |
   | output_size  | 是       | int  | -      | W8A8 linear的输出维度大小。              | 推理强依赖数据的合法性，需由用户保证。 |

3. 返回值说明

   | 类型                      | 描述                                                    | 安全声明                               |
   | ------------------------- | ------------------------------------------------------- | -------------------------------------- |
   | Dict[str, torch.Tensor]    | 代表W8A8所需的weight参数名与符合形状要求的tensor。      | 推理强依赖数据的合法性，需由用户保证。 |

#### get_pertensor_param接口
1. 接口功能：

   返回W8A8量化所需要的per_tensor参数名与tensor。

2. 参数说明：
   | 参数名称      | 是否必选 | 类型           | 默认值 | 描述                                             | 安全声明                          |
   | ------------- | -------- | -------------- | ------ | ------------------------------------------------ | --------------------------------- |
   | params_dtype  | 是       | torch.dtype    | -      | W8A8 linear的输入参数类型。                      | 推理强依赖数据的合法性，需由用户保证。 |


3. 返回值说明：

   | 返回值名称       | 类型                   | 描述                                                    | 安全声明                          |
   | ---------------- | ---------------------- | ------------------------------------------------------- | --------------------------------- |
   | Dict[str, torch.Tensor] | dict[str, torch.Tensor] | 代表W8A8所需的pertensor参数名与符合形状要求的tensor。  | 推理强依赖数据的合法性，需由用户保证。 |


#### get_perchannel_param接口

1. 接口功能：

   返回W8A8量化所需要的per_channel参数名与tensor。

2. 参数说明：

   | 参数名称      | 是否必选 | 类型           | 默认值 | 描述                                             | 安全声明                          |
   | ------------- | -------- | -------------- | ------ | ------------------------------------------------ | --------------------------------- |
   | output_size   | 是       | int            | -      | W8A8 linear的输出维度大小。                      | 推理强依赖数据的合法性，需由用户保证。 |
   | params_dtype  | 是       | torch.dtype    | -      | W8A8 linear的输出参数类型。                      | 推理强依赖数据的合法性，需由用户保证。 |

3. 返回值说明：


   | 返回值名称       | 类型                   | 描述                                                    | 安全声明                          |
   | ---------------- | ---------------------- | ------------------------------------------------------- | --------------------------------- |
   | Dict[str, torch.Tensor] | dict[str, torch.Tensor] | 代表W8A8所需的perchannel参数名与符合形状要求的tensor。  | 推理强依赖数据的合法性，需由用户保证。 |

#### apply接口
1. 接口功能：

   实现W8A8 linear所需的前向计算。

2. 参数说明：

   | 参数名称      | 是否必选 | 类型             | 默认值 | 描述                                                                         | 安全声明                          |
   | ------------- | -------- | ---------------- | ------ | ---------------------------------------------------------------------------- | --------------------------------- |
   | layer         | 是       | torch.nn.Module   | -      | 被量化后的一个linear对象，并且必须注册了由get_weiget、get_perchannel_param、get_pertensor_param所给出的参数。 | 推理强依赖数据的合法性，需由用户保证。 |
   | x             | 是       | torch.Tensor      | -      | 量化linear前向计算的输入。                                                   | 推理强依赖数据的合法性，需由用户保证。 |

3. 返回值说明：

    | 类型           | 描述                                           | 安全声明                          |
    | -------------- | ---------------------------------------------- | --------------------------------- |
    | torch.Tensor   | 量化linear的前向计算结果                      | 推理强依赖数据的合法性，需由用户保证。 |

## 参与贡献

1. Fork 本仓库
2. 新建分支
3. 验证修改
4. 提交代码
5. 新建 Pull Request