⚠️ 前情提要： 本手册不包含昇腾固件与驱动安装步骤，请确认固件与驱动是否正确安装！

​

1. 安装CANN开发套件

1.1 下载CANN相关安装包

https://www.hiascend.com/developer/download/community/result?module=cann&cann=8.3.RC1

1. Ascend-cann-kernels-910_8.3.RC1_linux-aarch64.run

2. Ascend-cann-nnal_8.3.RC1_linux-aarch64.run

3. Ascend-cann-toolkit_8.3.RC1_linux-aarch64.run

1.2 安装

1.2.1 安装cann-kernels

chmod +x Ascend-cann-kernels-910_8.3.RC1_linux-aarch64.run
./Ascend-cann-kernels-910_8.3.RC1_linux-aarch64.run --install

1.2.2 安装cann-toolkit

chmod +x Ascend-cann-toolkit_8.3.RC1_linux-aarch64.run
./Ascend-cann-toolkit_8.3.RC1_linux-aarch64.run --install

1.2.3 安装cann-nnal

• 需要在系统全局配置文件中添加环境变量

  安装cann-nnal之前需要将cann-toolkit添加到系统环境变量中，否则会报安装atb错误。

  # 1. 编辑系统全局配置文件，添加环境变量
  vi /etc/profile
  ​
  # 2. 在文件末尾添加以下内容（对应你的 CANN 安装路径 /usr/local/Ascend）
  # 配置 ASCEND_TOOLKIT_HOME（指定 toolkit 安装目录）
  export ASCEND_TOOLKIT_HOME=/usr/local/Ascend/ascend-toolkit/8.3.RC1
  # 配置 ASCEND_NNAE_HOME（兼容要求，与 toolkit 路径一致即可）
  export ASCEND_NNAE_HOME=$ASCEND_TOOLKIT_HOME
  # 配置 LD_LIBRARY_PATH（确保库文件可被找到）
  export LD_LIBRARY_PATH=$ASCEND_TOOLKIT_HOME/lib64:$LD_LIBRARY_PATH
  # 刷新环境变量（与已有的 set_env.sh 联动）
  source /usr/local/Ascend/ascend-toolkit/set_env.sh
  ​
  # 3. 保存退出 vi 编辑器（Esc → :wq → 回车）
  ​
  # 4. 使环境变量立即生效（无需重启服务器）
  source /etc/profile
  ​

• 安装cann-nnal

  chmod +x Ascend-cann-nnal_8.3.RC1_linux-aarch64.run
  ./Ascend-cann-nnal_8.3.RC1_linux-aarch64.run --install

2. vllm-ascend镜像

2.1 跨架构拉取vllm-ascend镜像

docker pull --platform linux/arm64/v8 quay.io/ascend/vllm-ascend:v0.11.0-openeuler

2.2 拉起vllm-ascend容器

• 拉取镜像导出tar包/导入镜像

  docker save -o XXX.tar 镜像:标签
  docker load -i XXX.tar

• 拉起容器

  docker run -d \
  --name vllm_qwen_0_5b \  # 容器名
  --privileged \
  --device /dev/davinci6 \  # 挂载NPU
  --device /dev/davinci7 \
  --device /dev/davinci_manager \
  --device /dev/devmm_svm \
  --device /dev/hisi_hdc \
  -v /usr/local/Ascend:/usr/local/Ascend:ro \
  -v /dev/models/Qwen2___5-0___5B-Instruct:/data/models/Qwen2___5-0___5B-Instruct:ro \  # 模型权重映射
  -v /var/log/npu:/var/log/npu:ro \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ 
  -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
  -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /root/.cache:/root/.cache \ 
  -p 1028:8000 \  ## 宿主机端口1028，容器内服务端口8000
  -it quay.io/ascend/vllm-ascend:v0.11.0-openeuler  # 镜像

4. vllm部署模型服务

4.1 vllm启动服务

• 启动vllm服务

  （可选）cd /data/models  
  （可选）ln -s Qwen2___5-0___5B-Instruct qwen2.5-0.7b  # vllm模型是根据权重路径，若文件夹名称过长可以做个映射
  ​
  # 加载环境变量
  source /usr/local/Ascend/nnal/atb/set_env.sh
  ​
  nohup python -m vllm.entrypoints.openai.api_server \
    --model /data/models/qwen2.5-0.7b \
    --tensor-parallel-size 2 \  # npu数量
    --gpu-memory-utilization 0.95 \  # 显存设置
    --trust-remote-code \  # 允许加载模型的自定义代码（Qwen 模型必备）
    --max-model-len 30000 \  # 模型最大上下文长度，可根据需求调整
    --port 8000 \  #  服务端口
    --host 0.0.0.0 \
    --load-format auto \  # 模型加载格式
    --max-num-seqs 50 \  # 最大并发请求数
    --generation-config vllm \
    > /logs/vllm_server.logs 2>&1 &

• vllm参数含义

  • 必须参数

    必须参数
    --model 或 -model # 要加载的模型路径或Hugging Face模型ID
    ​
    例：
    --model meta-llama/Llama-2-7b-chat-hf
    --model /path/to/local/model

  • 主要服务器参数

    --host 和 --port  # API服务器的监听地址和端口
    例：--host 127.0.0.1 --port 8080
    ​
    --served-model-name #在API响应中显示的模型名称（0.11.0版本不好用，不知道为什么）
    例： --served-model-name llama-2-chat

  • 模型加载参数

    --tokenizer 或 --tokenizer-model # 指定自定义tokenizer路径（默认使用与模型相同的tokenizer）
    ​
    --tokenizer-mode # tokenizer的处理模式（auto, slow）
    默认: auto
    ​
    --trust-remote-code  # 信任远程代码（加载自定义模型时需要）
    类型: 布尔标志
    ​
    --download-dir # 模型下载的缓存目录
    默认: 使用Hugging Face默认缓存
    ​
    --load-format # 模型加载格式（auto（默认）, pt, safetensors, npcache, dummy）
    默认: auto

  • 推理参数

    --tensor-parallel-size 或 -tp # 张量并行度（GPU数量）
    默认: 1
    例：--tensor-parallel-size 2  # 使用2个GPU
    ​
    --max-model-len # 模型支持的最大序列长度
    ​
    --gpu-memory-utilization # GPU内存使用率（0.0到1.0）
    默认：0.9
    ​
    --swap-space # CPU交换空间大小（GB）
    默认: 4
    ​
    --max-num-batched-tokens # 单个批处理的最大token数
    默认: 自动计算
    ​
    --max-num-seqs # 最大并发请求数
    默认: 256

  • 量化参数

    --quantization # 量化方法（awq, gptq, squeezellm, None）
    ​
    --enforce-eager # 强制使用eager模式（调试用）
    类型: 布尔标志

  • 调度参数

    --disable-log-stats # 禁用日志统计
    类型: 布尔标志
    ​
    --engine-use-ray # 使用Ray进行分布式服务
    类型: 布尔标志
    ​
    --disable-log-requests #  禁用请求日志
    类型: 布尔标志

  • API参数

    --api-key # API密钥（启用认证）
    例：--api-key sk-xxx
    ​
    --root-path # API根路径前缀
    例：--root-path /v1

4.2 curl测试模型

• 获取模型列表

  curl http://XXX:XXX/v1/models

• 调用模型生成接口

  ⚠注意： vllm模型名称与mindie不同，他是起服务时模型权重路径。第三方应用中配置vllm模型时API endpoint中的模型名称要对应。

  curl --location --request POST 'XXX:XXX/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "model": "/data/models/qwen2.5-0.7b",
      "messages": [
          {
              "role": "user",
              "content": "帮我生成50000字有关下雪的散文。"
          }
      ],
      "max_tokens": 20000,
      "presence_penalty": 1.03,
      "frequency_penalty": 1.0,
      "seed": null,
      "temperature": 0.8,
      "top_p": 0.95,
      "stream": true
  }'