部署推理服务

前提条件

• 已准备好Lite k8s Cluster环境，具体参考准备环境。推荐使用“西南-贵阳一”Region上的Cluster和昇腾Snt9b资源。
• 安装过程需要连接互联网git clone，确保集群可以访问公网。

Step1 上传权重文件

将权重文件上传到集群节点机器中。权重文件的格式要求为Huggingface格式。开源权重文件获取地址请参见支持的模型列表和权重文件。

如果使用模型训练后的权重文件进行推理，模型训练及训练后的权重文件转换操作可以参考相关文档章节中提供的模型训练文档。

Step2 配置pod

apiVersion: apps/v1
kind: Deployment
metadata:
  name: yourapp
  labels:
      app: infers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: infers
  template:
    metadata: 
      labels:
         app: infers
    spec:
      schedulerName: volcano
      nodeSelector:
        accelerator/huawei-npu: ascend-1980
      containers:
      - image: ${image_name}                  # 推理镜像名称
        imagePullPolicy: IfNotPresent
        name: ${container_name}
        securityContext:
          runAsUser: 0
        ports:
        - containerPort: 8080
        command: ["/bin/bash", "-c"]
        args: ["${node-path}/run_vllm.sh"]          # 节点自定义目录，该目录下包含pod配置文件config.yaml和推理服务启动脚本run_vllm.sh
        resources:
          requests:
            huawei.com/ascend-1980: "8"             # 需求卡数，key保持不变。
          limits:
            huawei.com/ascend-1980: "8"             # 限制卡数，key保持不变。
        volumeMounts:                             # 容器内部映射路径
        - name: ascend-driver               #驱动挂载，保持不动
          mountPath: /usr/local/Ascend/driver
        - name: ascend-add-ons           #驱动挂载，保持不动
          mountPath: /usr/local/Ascend/add-ons
        - name: hccn                             #驱动hccn配置，保持不动
          mountPath: /etc/hccn.conf
        - name: localtime                       
          mountPath: /etc/localtime
        - name: npu-smi                             # npu-smi
          mountPath: /usr/local/sbin/npu-smi
        - name: model-path                       # 模型权重路径
          mountPath: ${model-path}
        - name: node-path                       
          mountPath: ${node-path}
      volumes:                                   # 物理机外部路径
      - name: ascend-driver
        hostPath:
          path: /usr/local/Ascend/driver
      - name: ascend-add-ons
        hostPath:
          path: /usr/local/Ascend/add-ons
      - name: hccn
        hostPath:
          path: /etc/hccn.conf
      - name: localtime
        hostPath:
          path: /etc/localtime
      - name: npu-smi
        hostPath:
          path: /usr/local/sbin/npu-smi
      - name: model-path
        hostPath:
          path: ${model-path}
      - name: node-path
        hostPath:
          path: ${node-path}

参数说明：

• ${container_name}：容器名称，此处可以自己定义一个容器名称，例如ascend-vllm。
• ${image_name}：Step3 制作推理镜像构建的推理镜像名称。
• ${node-path}：节点自定义目录，该目录下包含pod配置文件config.yaml和推理服务启动脚本run_vllm.sh，run_vllm.sh内容见Step3 创建服务启动脚本。
• ${model-path}：Step1 上传权重文件中上传的模型权重路径。

Step3 创建服务启动脚本

run_vllm.sh脚本示例如下。

• 方式一：通过OpenAI服务API接口启动服务

  （1）非多模态

  source /home/ma-user/.bashrc
  export ASCEND_RT_VISIBLE_DEVICES=${ASCEND_RT_VISIBLE_DEVICES}
  
  python -m vllm.entrypoints.openai.api_server --model ${container_model_path} \
  --max-num-seqs=256 \
  --max-model-len=4096 \
  --max-num-batched-tokens=4096 \
  --tensor-parallel-size=1 \
  --block-size=128 \
  --host=${docker_ip} \
  --port=8080 \
  --gpu-memory-utilization=0.9 \
  --num-scheduler-steps=8 \
  --trust-remote-code

  （2）llava多模态

  source /home/ma-user/.bashrc
  export ASCEND_RT_VISIBLE_DEVICES=${ASCEND_RT_VISIBLE_DEVICES}
  
  export VLLM_IMAGE_FETCH_TIMEOUT=100
  export VLLM_ENGINE_ITERATION_TIMEOUT_S=600
  # PYTORCH_NPU_ALLOC_CONF优先设置为expandable_segments:True
  # 如果有涉及虚拟显存相关的报错，可设置为expandable_segments:False
  export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
  
  python -m vllm.entrypoints.openai.api_server --model ${container_model_path} \
  --max-num-seqs=256 \
  --max-model-len=4096 \
  --max-num-batched-tokens=4096 \
  --tensor-parallel-size=1 \
  --block-size=128 \
  --chat-template ${chat_template_path} \
  --dtype ${dtype} \
  --host=${docker_ip} \
  --port=${port} \
  --gpu-memory-utilization=0.9 \
  --trust-remote-code

  多模态推理服务启动模板参数说明如下：

  • VLLM_IMAGE_FETCH_TIMEOUT：图片下载时间环境变量。
  • VLLM_ENGINE_ITERATION_TIMEOUT_S：服务间隔最大时长，超过会报timeout错误。
  • PYTORCH_NPU_ALLOC_CONF=expandable_segments:True；允许分配器最初创建一个段，然后在以后需要更多内存时扩展它的大小。开启时可能提升模型性能。报错则关闭。
  • --chat-template：对话构建模板，可选参数。如：

    （1）llava chat-template：${vllm_path}/examples/template_llava.jinja

• 方式二：通过vLLM服务API接口启动服务

  source /home/ma-user/.bashrc
  export ASCEND_RT_VISIBLE_DEVICES=${ASCEND_RT_VISIBLE_DEVICES}
  
  python -m vllm.entrypoints.api_server --model ${container_model_path} \
  --max-num-seqs=256 \
  --max-model-len=4096 \
  --max-num-batched-tokens=4096 \
  --tensor-parallel-size=1 \
  --block-size=128 \
  --host=${docker_ip} \
  --port=8080 \
  --gpu-memory-utilization=0.9 \
  --trust-remote-code

  推理服务基础参数说明如下：

  • ${ASCEND_RT_VISIBLE_DEVICES}：使用的NPU卡，单卡设为0即可，4卡可设为0,1,2,3。
  • ${model_path}：Step1 上传权重文件中上传的模型权重路径。
  • --tensor-parallel-size：并行卡数。
  • --host：服务部署的IP，使用本机IP 0.0.0.0。
  • --port：服务部署的端口8080。
  • --max-model-len：最大数据输入+输出长度，不能超过模型配置文件config.json里面定义的“max_position_embeddings”和“seq_length”；如果设置过大，会占用过多显存，影响kvcache的空间。不同模型推理支持的max-model-len长度不同，具体差异请参见附录：基于vLLM不同模型推理支持最小卡数和最大序列说明。
  • --trust-remote-code：是否相信远程代码。
  • --dtype：模型推理的数据类型。支持FP16和BF16数据类型推理。float16表示FP16，bfloat16表示BF16。如果不指定，则根据输入数据自动匹配数据类型。使用不同的dtype会影响模型精度。如果使用开源权重，建议不指定dtype，使用开源权重默认的dtype。
  • --block-size：kv-cache的block大小，推荐设置为128。当前仅支持64和128。
  • --num-scheduler-steps: 默认为1，推荐设置为8。用于mult-step调度。每次调度生成多个token，可以降低时延。开启multi-step后，在流式返回中，会一次返回num-scheduler-steps个token。开启投机推理后无需配置该参数。
  • --gpu-memory-utilization：NPU使用的显存比例，复用原vLLM的入参名称，默认为0.9。
  • --trust-remote-code：是否相信远程代码。
  • --distributed-executor-backend：多卡推理启动后端，可选值为"ray"或者"mp"，其中"ray"表示使用ray进行启动多卡推理，"mp"表示使用python多进程进行启动多卡推理。默认使用"mp"后端启动多卡推理。
  高阶参数说明：

  • --enable-prefix-caching：如果prompt的公共前缀较长或者多轮对话场景下推荐使用prefix-caching特性。在推理服务启动脚本中添加此参数表示使用prefix-caching特性，不添加表示不使用。开启该特性后，如果模型长度>8192，则需要在启动推理服务前添加如下环境变量降低显存占用；否则在长序列的推理中会触发Out of Memory，导致推理服务不可用。

    export USE_PREFIX_HIGH_PRECISION_MODE=1

  • 如果需要使用multi-lora特性；需要在推理服务启动命令中额外添加如下命令。

    --enable-lora \
    --lora-modules lora1=/path/to/lora/adapter1/ lora2=/path/to/lora/adapter2/ \
    --max-lora-rank=16 \
    --max-loras=32 \
    --max-cpu-loras=32

    --enable-lora表示开启lora挂载。

    --lora-modules后面添加挂载的lora列表，要求lora地址权重是huggingface格式，当前支持QKV-proj、O-proj、gate_up_proj、down_proj模块的挂载。

    --max-lora-rank表示挂载lora的最大rank数量，支持8、16、32、64。

    --max-loras 表示支持的最大lora个数，最大32。

    --max-cpu-loras要求配置和--max-loras相同。

    发请求时model指定为lora1或者lora2即为LoRA推理。

  • --quantization：推理量化参数。当使用量化功能，则在推理服务启动脚本中增加该参数，如果未使用量化功能，则无需配置。根据使用的量化方式配置，可选择awq或smoothquant方式。该参数可与投机推理配合使用，实现投机校验模型的量化功能。
  • --speculative-model ${container_draft_model_path}：投机草稿模型地址，模型格式是HuggingFace的目录格式。即Step1 上传权重文件上传的HuggingFace权重文件存放目录。投机草稿模型为与--model入参同系列，但是权重参数远小于--model指定的模型。如果未使用投机推理功能，则无需配置。
  • --speculative-draft-tensor-parallel-size: 投机模型使用tp数，因为投机模型较小，多卡并行时通信会降低性能，故此处需要设置为1。
  • --num-speculative-tokens：投机推理草稿模型每次推理的token数。如果未使用投机推理功能，则无需配置。参数--num-speculative-tokens需要和--speculative-model ${container_draft_model_path}同时使用。
  • --use-v2-block-manager：vllm启动时使用V2版本的BlockSpaceManger来管理KVCache索引，如果不使用该功能，则无需配置。注意：如果使用投机推理功能，必须开启此参数。
  • --served-model-name：vllm服务后台id。
    可在run_vllm.sh增加如下环境变量开启高阶配置：

    1. 配置环境变量。

       export USE_PFA_HIGH_PRECISION_MODE=1
       # PFA算子（全量prefill阶段的flash-attention）是否使用高精度模式；默认值为1表示开启。针对Qwen2-7B模型和Qwen2-57b模型，必须开启此配置，否则精度会异常；其他模型不建议开启，会影响首token时延增加5%~10%。
       
       export USE_IFA_HIGH_PRECISION_MODE=1
       # IFA算子（增量decode阶段的flash-attention）是否使用高精度模式；默认值为0表示不开启。针对Qwen2-7B、Qwen2-57b、Qwen2-72B，在长序列下需要开启，否则会有概率性精度异常；其他模型不建议开启，会影响增量时延增加5%~10%。
       
       export USE_PREFIX_HIGH_PRECISION_MODE=1
       # 针对Qwen2-7B、Qwen2-72B模型，在开启prefix-caching时，需要同时使用带有prefix-caching的高精度attention算子避免精度异常。需要和prefix-caching特性一起使用，如果不使用prefix-caching特性则不配置该环境变量。

    2. 如果要开启图模式，请配置以下5个环境变量，并且启动服务时不要添加enforce-eager参数。

       export INFER_MODE=PTA  # 开启PTA模式，如果不使用图模式，请关闭该环境变量
       export PTA_TORCHAIR_DECODE_GEAR_ENABLE=1   # 开启动态分档功能
       export PTA_TORCHAIR_DECODE_GEAR_LIST=2,4,6,8,16,32    # 设置动态分档的档位，根据实际情况设置，另外请不要设置档位1(DeepSeek V2 236B W8A8 模型建议最大设置4个档位)
       export VLLM_ENGINE_ITERATION_TIMEOUT_S=1500    # 设置vllm请求超时时间(DeepSeek V2 236B W8A8 模型建议调大为6000)
       export HCCL_OP_EXPANSION_MODE=AIV    #可选

       通过PTA_TORCHAIR_DECODE_GEAR_LIST设置动态分档位后，在PTA模式下，会根据服务启动时的max_num_seqs参数对档位进行调整，使得最终的最大档位为max_num_seqs，因此，请根据使用场景合理设置动态分档以及max_num_seqs参数，避免档位过大导致图编译错误。

       在MoE模型和小模型上推荐使用图模式部署，包括mixtral-8x7B、qwen2-57B、deepseek-v2-lite-16B、deepseek-v2-236B-W8A8；和Qwen2-1.5B、Qwen2-0.5B。当前MoE模型图模式启动不支持multi step。

       MoE模型依赖MindSpeed，当使用MoE模型推理时，需提前安装：

       git clone https://gitee.com/ascend/MindSpeed.git
       cd MindSpeed
       git checkout a956b907ef3b0787d2a38577eb5b702f5b7e715d #推荐commit
       pip install -e .

       开启图模式后，服务第一次响应请求时会有一个较长时间的图编译过程，并且会在当前目录下生成.torchair_cache文件夹来保存图编译的缓存文件。当服务第二次启动时，可通过缓存文件来快速完成图编译的过程，避免长时间的等待，并且基于图编译缓存文件来启动服务可获得更优的推理性能，因此请在有图编译缓存文件的前提下启动服务。另外，当启动服务时的模型或者参数发生改变时，请删除.torchair_cache文件夹，避免由于缓存文件与实际推理不匹配而报错。

    3. 如果要使用eagle投机，配置环境变量，使eagle投机对齐实验室版本实现。目前默认开启此模式，如果不开启，目前vllm0.6.0版本与实验室版本权重无法对齐，会导致小模型精度问题。

       export EAGLE_USE_SAFE_AI_LAB_STYLE=1  # eagle投机对基于 https://github.com/SafeAILab/EAGLE/ 版本实现
       export ENABLE_SPEC_METRIC=0  # 是否关闭投机推理的metric采集功能，关闭有助于提升投机推理性能，默认关闭

       如果需要使用eagle投机推理功能，需要进入 lm_tools/spec_decode/EAGLE 文件夹，使用convert_eagle_ckpt_to_vllm_compatible.py脚本进行权重转换。转换命令为

       python convert_eagle_ckpt_to_vllm_compatible.py --base-path 大模型权重地址 --draft-path 小模型权重地址 --base-weight-name 大模型包含lm_head的权重文件名 --draft-weight-name 小模型权重文件名

       具体可参考7 eagle投机小模型训练 步骤五：训练生成权重转换成可以支持vLLM推理的格式

Step4 创建pod

在节点自定义目录${node_path}下执行如下命令创建pod。

kubectl apply -f config.yaml

检查pod启动情况，执行下述命令。如果显示“1/1 running”状态代表启动成功。

kubectl get pod -A

图1 启动pod成功

执行如下命令查看pod日志，如果打印类似下图信息表示服务启动成功。

kubectl logs -f ${pod_name}

参数说明：

• ${pod_name}：pod名，例如图1${pod_name}为yourapp-87d9b5b46-c46bk。

图2 启动服务成功

Step5 推理请求

执行如下命令进入容器。

kubectl exec -it {pod_name} bash

参数说明：

• ${pod_name}：pod名，例如图1${pod_name}为yourapp-87d9b5b46-c46bk。

使用命令测试推理服务是否正常启动。服务启动命令中的参数设置请参见表1。

• 方式一：通过OpenAI服务API接口启动服务使用以下推理测试命令。${model_path}请替换为实际使用的模型名称。

  curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "${model_path}",
      "messages": [
          {
              "role": "user",
              "content": "hello"
          }
      ],
      "max_tokens": 100,
      "top_k": -1,
      "top_p": 1,
      "temperature": 0,
      "ignore_eos": false,
      "stream": false
  }'

• 方式二：通过vLLM服务API接口启动服务使用以下推理测试命令。下面以Llama系列模型采样方式支持presence_penalty参数的发送请求为例。此处的接口8080需和Step3 创建服务启动脚本中设置的宿主机端口保持一致。

  curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "hello",
  "max_tokens": 100,
  "temperature": 0,
  "ignore_eos": false,
  "presence_penalty":2
   }'

  下面以Llama系列模型采样方式支持length_penalty参数的发送请求为例。

  curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "hello",
  "max_tokens": 100,
  "top_p": 1,
  "temperature": 0,
  "ignore_eos": false,
  "top_k": -1,
  "use_beam_search":true,
  "best_of":2,
  "length_penalty":2
   }'

服务的API与vLLM官网相同，此处介绍关键参数。详细参数解释请参见官网https://docs.vllm.ai/en/stable/dev/sampling_params.html。

表1 请求服务参数说明

参数	是否必选	默认值	参数类型	描述
model	是	无	Str	通过OpenAI服务API接口启动服务时，推理请求必须填写此参数。取值必须和启动推理服务时的model ${model_path}参数保持一致。 通过vLLM服务API接口启动服务时，推理请求不涉及此参数。
prompt	是	-	Str	请求输入的问题。
max_tokens	否	16	Int	每个输出序列要生成的最大tokens数量。
top_k	否	-1	Int	控制要考虑的前几个tokens的数量的整数。设置为-1表示考虑所有tokens。 适当降低该值可以减少采样时间。
top_p	否	1.0	Float	控制要考虑的前几个tokens的累积概率的浮点数。必须在 (0, 1] 范围内。设置为1表示考虑所有tokens。
temperature	否	1.0	Float	控制采样的随机性的浮点数。较低的值使模型更加确定性，较高的值使模型更加随机。0表示贪婪采样。
stop	否	None	None/Str/List	用于停止生成的字符串列表。返回的输出将不包含停止字符串。 例如：["你"，"好"]，生成文本时遇到"你"或者"好"将停止文本生成。
stream	否	False	Bool	是否开启流式推理。默认为False，表示不开启流式推理。
n	否	1	Int	返回多条正常结果。 约束与限制： 不使用beam_search场景下，n取值建议为1≤n≤10。如果n>1时，必须确保不使用greedy_sample采样。也就是top_k > 1; temperature > 0。 使用beam_search场景下，n取值建议为1<n≤10。如果n=1，会导致推理请求失败。 说明： n建议取值不超过10，n值过大会导致性能劣化，显存不足时，推理请求会失败。
use_beam_search	否	False	Bool	是否使用beam_search替换采样。 约束与限制：使用该参数时，如下参数需按要求设置： n>1 top_p = 1.0 top_k = -1 temperature = 0.0
presence_penalty	否	0.0	Float	presence_penalty表示会根据当前生成的文本中新出现的词语进行奖惩。取值范围[-2.0,2.0]。
frequency_penalty	否	0.0	Float	frequency_penalty会根据当前生成的文本中各个词语的出现频率进行奖惩。取值范围[-2.0,2.0]。
length_penalty	否	1.0	Float	length_penalty表示在beam search过程中，对于较长的序列，模型会给予较大的惩罚。 如果要使用length_penalty，必须添加如下三个参数，并且需将use_beam_search参数设置为true，best_of参数设置大于1，top_k固定为-1。 "top_k": -1 "use_beam_search":true "best_of":2
ignore_eos	否	False	Bool	ignore_eos表示是否忽略EOS并且继续生成token。
guided_json	否	None	Union[str, dict, BaseModel]	使用openai启动服务，如果需要使用JSON Schema时要配置guided_json参数。 JSON Schema使用专门的关键字来描述数据结构，例如标题title、 类型type、属性properties，必需属性required 、定义definitions等，JSON Schema通过定义对象属性、类型、格式的方式来引导模型生成一个包含用户信息的JSON对象。 如果希望使用JSON Schema，guided_json的写法可参考outlines: Structured Text Generation中的“Efficient JSON generation following a JSON Schema”样例，如下图所示。 图3 guided_json样例 如果想在发送的请求中包含上述guided_json架构，可参考以下代码。如果prompt未提供充足信息可能导致返回的json文件部分结果为空。 curl -X POST http://${docker_ip}:8080/v1/completions \ -H "Content-Type: application/json" \ -d '{ "model": "${container_model_path}", "prompt": "Meet our valorous character, named Knight, who has reached the age of 32. Clad in impenetrable plate armor, Knight is well-prepared for any battle. Armed with a trusty sword and boasting a strength score of 90, this character stands as a formidable warrior on the field.Please provide details for this character, including their Name, Age, preferred Armor, Weapon, and Strength", "max_tokens": 200, "temperature": 0, "guided_json": "{\"title\": \"Character\", \"type\": \"object\", \"properties\": {\"name\": {\"title\": \"Name\", \"maxLength\": 10, \"type\": \"string\"}, \"age\": {\"title\": \"Age\", \"type\": \"integer\"}, \"armor\": {\"$ref\": \"#/definitions/Armor\"}, \"weapon\": {\"$ref\": \"#/definitions/Weapon\"}, \"strength\": {\"title\": \"Strength\", \"type\": \"integer\"}}, \"required\": [\"name\", \"age\", \"armor\", \"weapon\", \"strength\"], \"definitions\": {\"Armor\": {\"title\": \"Armor\", \"description\": \"An enumeration.\", \"enum\": [\"leather\", \"chainmail\", \"plate\"], \"type\": \"string\"}, \"Weapon\": {\"title\": \"Weapon\", \"description\": \"An enumeration.\", \"enum\": [\"sword\", \"axe\", \"mace\", \"spear\", \"bow\", \"crossbow\"], \"type\": \"string\"}}}" }'

• 方式三 online_serving.py 发送请求（单图单轮对话）

由于多模态推理涉及图片的编解码，所以采用脚本方式调用服务API。脚本中需要配置的参数如表2脚本参数说明所示。

import base64
import requests
import argparse
# Function to encode the image
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')
def post_img(args):
    # Path to your image
    image_path = args.image_path
    # Getting the base64 string
    image_base64 = encode_image(image_path)
    headers = {
      "Content-Type": "application/json"
    }
    payload = {
      "model": args.model_path,
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": args.text
            },
            {
              "type": "image_url",
              "image_url": {
                "url": f"data:image/jpeg;base64,{image_base64}"
              }
            }
          ]
        }
      ],
      "max_tokens": args.max_tokens,
      "temperature": args.temperature,
      "ignore_eos": args.ignore_eos,
      "stream": args.stream,
      "top_k": args.top_k,
      "top_p": args.top_p 
    }
    response = requests.post(f"http://{args.docker_ip}:{args.served_port}/v1/chat/completions", headers=headers, json=payload)
    print(response.json())

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    # 必填
    parser.add_argument("--model-path", type=str, required=True)
    parser.add_argument("--image-path", type=str, required=True)
    parser.add_argument("--docker-ip", type=str, required=True)
    parser.add_argument("--served-port", type=str, required=True)
    parser.add_argument("--text", type=str, required=True)
    # 选填
    parser.add_argument("--temperature", type=float, default=0) # 输出结果的随机性。可选
    parser.add_argument("--ignore-eos", type=bool, default=False) # 在生成过程中是否忽略结束符号，在生成EOS token后继续生成token。可选
    parser.add_argument("--top-k", type=int, default=-1) # 参数控制着生成结果的多样性。其值越小，生成的文本就越独特，但可能缺乏连贯性。相反，其值越大，文本就越连贯，但多样性也会降低。可选
    parser.add_argument("--top-p", type=int, default=1.0) # 参数的取值范围为0到1。值越小，生成的内容就越意外，但可能牺牲连贯性。值越大，内容就越连贯，但意外性也会减弱。可选
    parser.add_argument("--stream", type=int, default=False) # 是否开启流式推理。默认为False，表示不开启流式推理。
    parser.add_argument("--max_tokens", type=int, default=16) # 生成序列的最大长度。必选
    args = parser.parse_args()
    post_img(args)

运行此脚本：

python online_serving.py --model-path ${container_model_path} --image-path ${image_path} --docker-ip ${docker_ip} --served-port ${port} --text 图片内容是什么