8. MacaRT-vLLM-metax
8.1. MacaRT-vLLM-metax介绍
vLLM-metax是专为曦云系列GPU打造的vLLM框架后端插件，用于使vLLM推理框架能够在沐曦GPU上高效运行。当前兼容vLLM v0.11.0版本。
8.1.1. 分支说明
已发布vLLM-metax版本与MXMACA版本的映射关系，参见表 8.1。
vLLM-metax |
vLLM |
PyTorch |
|---|---|---|
v0.10.2 |
v0.10.2 |
2.6 |
v0.11.0 |
v0.11.0 |
2.6 |
8.2. MacaRT-vLLM-metax功能与局限性
MacaRT-vLLM-metax兼容适配了vLLM v0.11.0版本，包含了以下功能和特性，以及局限性：
功能和特性：
兼容vLLM v0.11.0支持的所有模型BFLOAT16推理和部分模型FLOAT16推理，支持官方多模态模型
兼容原生LLM、Engine、Kernel的API接口
兼容原生server和OpenAI server接口
支持Lora特性
支持GPTQ和AWQ量化方式
支持ray和mp方式启动单机多卡推理；设置
--distributed-executor-backend可以指定不同后端进行多卡推理，默认使用ray支持prefix_cache方式
支持
enforce_eager=False方式。需通过显式配置，默认为True。另外，需要额外设置MACA环境变量来获取加速效果：export MACA_GRAPH_LAUNCH_MODE=1
局限性：
不支持FP8类型KV Cache和相关FP8模型
包含Ubuntu 20、Ubuntu 22、kylin2309a系统版本，后续完善支持其他系统
8.3. MacaRT-vLLM-metax使用流程
本章节介绍MacaRT-vLLM-metax的安装和使用步骤，功能主要分为离线推理、吞吐测试和Sever服务。
8.3.1. 环境准备
使用MacaRT-vLLM-metax进行推理需要准备好环境。目前提供两种方式：镜像和wheel包。 如果您想开发、调试或测试 vLLM-metax 的最新功能，可以从源码构建 vLLM-metax 并将其安装到 Docker 环境中。 vLLM-metax源码构建请参考：MacaRT-vLLM-metax源码构建。
8.3.1.1. 使用vLLM镜像
从发布的软件包中获取vLLM镜像并启动，参见《曦云® 系列通用GPU用户指南》中“容器相关场景支持”章节。
8.3.1.2. 安装wheel包
操作步骤
预先安装沐曦平台的torch、flash attn、mcoplib、xformer（可选）环境。
获取MacaRT-vLLM压缩包 maca-vllm-metax-0.11.0-py310-xxx-${OS_Version}.tar.xz 并解压。
pip安装以下wheel包：
vllm_metax-0.11.0+xxx.whl
flash_attn+xxx.whl （适配vLLM新加速whl包）
ray-2.48.0-cp310-cp310_${OS_Version}.whl
mcoplib-0.1.0-+macaxxx-cp310-cp310_${OS_Version}.whl
vllm-0.11.0-cp310-xxx_${OS_Version}.whl
vLLM-metax、vLLM、mcoplib安装后需要手动执行
mcoplib_init命令。
除了上述wheel包，其他依赖环境可以通过外部镜像源进行安装。安装过程中有其他依赖，需要提前配置好Python的pip源。
8.3.1.3. 源代码构建教程
从MetaX开发社区中获取vLLM镜像并启动，参见《曦云® 系列通用GPU用户指南》中“容器相关场景支持”章节。
8.3.1.4. 设置环境变量
# setup MACA path
export MACA_PATH="/opt/maca"
# cu-bridge
export CUCC_PATH="${MACA_PATH}/tools/cu-bridge"
export CUDA_PATH=/root/cu-bridge/CUDA_DIR
export CUCC_CMAKE_ENTRY=2
# update PATH
export PATH=${MACA_PATH}/mxgpu_llvm/bin:${MACA_PATH}/bin:${CUCC_PATH}/tools:${CUCC_PATH}/bin:${PATH}
export LD_LIBRARY_PATH=${MACA_PATH}/lib:${MACA_PATH}/ompi/lib:${MACA_PATH}/mxgpu_llvm/lib:${LD_LIBRARY_PATH}
export VLLM_INSTALL_PUNICA_KERNELS=1
8.3.1.5. 构建vLLM
克隆vLLM项目：
git clone --depth 1 --branch v0.11.0 https://github.com/vllm-project/vllm
cd vllm
构建官方版本vLLM：
python use_existing_torch.py
pip install -r requirements/build.txt
VLLM_TARGET_DEVICE=empty pip install -v . --no-build-isolation
8.3.1.6. 构建vLLM-metax
安装所需组件：
python use_existing_metax.py
pip install -r requirements/build.txt
安装vLLM：
pip install . -v --no-build-isolation
如果想要开发vLLM，请以可编辑模式安装：
pip install -e . -v --no-build-isolation
（可选）构建可移植的wheel包：
python -m build -w -n
pip install dist/*.whl
8.3.2. 离线推理
离线推理代码示例如下：
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)
def main():
# 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.
print("\nGenerated Outputs:\n" + "-" * 60)
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}")
print(f"Output: {generated_text!r}")
print("-" * 60)
if __name__ == "__main__":
main()
其中主要配置为：
LLM初始化类：指定模型路径（可配置为本地路径，如果不是本地路径，会根据网络下载外网模型）、tensor切分数量、模型数据类型（可不配置，如果没指定，将通过 model config 读取）、模型最大处理长度（可不配置，如果没设置，将从 model config 读取）
SamplingParams：设置采样算法方式。参数配置可参照官方vLLM v0.11.0版本进行配置。
8.3.3. 吞吐测试
吞吐测试代码可参考官方vLLm-0.11.0 benchmark_throughput.py。
吞吐测试代码的运行方式示例1：
python -m vllm.entrypoints.cli.main bench throughput --model XXX --tensor-parallel-size 1 --num-prompts 8 --trust-remote-code --input-len 1024 --output-len 512
模型为XXX，tensor并行为1，8条请求数量，信任模型路径的tokenizer方式，每条输入长度为1024个token，输出为512个token。
吞吐测试代码的运行方式示例2：
vllm bench throughput --model XXX --tensor-parallel-size 1 --num-prompts 8 --trust-remote-code --dataset XXX.json
模型为XXX，tensor并行为1，8条请求数量，信任模型路径的tokenizer方式，通过从dataset选取语料进行真实模拟。 json格式可参考ShareGPT_V3_unfiltered_cleaned_split.json。
运行程序后，结果打印如下：
Throughout: XXX request/s, XXXX token/s
打印结果指示每秒能接受多少请求，以及每秒处理的token数量（包括输入token）。
8.3.4. Server服务
Server请求服务参数设置可参考官方vLLM-0.11.0版本：
API server参数配置可参考api_server.py。
OpenAI server参数配置可参考api_server.py。
参考示例如下：
python -m vllm.entrypoints.api_server --model XXX #普通server方式
python -m vllm.entrypoints.openai.api_server --model XXX --host localhost --chat-template XXX.jinja ## openai 方式的请求
vllm server --model XXX