LLM Service 安装部署脚本使用指南

本目录包含用于安装和部署基于 vLLM Ascend 的 LLM 模型服务的自动化脚本。这些脚本简化了从下载到部署的完整流程，帮助用户快速搭建 LLM 推理服务。

支持的操作系统

操作系统	支持的版本
BCLinux	21.10, 21.10U4
CTyunOS	22.06, 23.01
CULinux	3.0
CentOS	7.6
Debian	10
EulerOS	2.8, 2.9, 2.10, 2.12
Kylin	V10, V10Halberd, V10Lance, V10Sword, V10Tercel, V11Swan25
MTOS	22.03LTS-SP4
OpenEuler	20.03LTS, 22.03LTS, 22.03LTS-SP1, 22.03LTS-SP4, 24.03LTS-SP1
Ubuntu	18.04, 20.04, 22.04, 22.04.4, 24.04
UOS	20-1020e, 20-1050e
veLinux	1.3
VesselOS	1.0, 2.0

支持的模型

部署模式	支持模型
Atlas 800I A2 单机 / Atlas 300I A2 多卡	Qwen3.5-27B-w8a8、Qwen3.5-397B-w4a8、MiniMax-M2.5-w8a8-QuaRot、DeepSeek-V4-Flash-w8a8-mtp
Atlas 800I A2 双机	Kimi-K2.5-w4a8、GLM-5.1-w8a8
Atlas 800I A3 单机	Qwen3.5-27B-w8a8、Qwen3.5-397B-w4a8、MiniMax-M2.5-w8a8-QuaRot、Kimi-K2.5-w4a8、GLM-5.1-w8a8、DeepSeek-V4-Flash-w8a8-mtp
Atlas 800I A3 双机	DeepSeek-V4-Pro-w4a8-mtp

注意： 具体支持的操作系统版本和模型列表可通过 ./download.sh --help 查看。

目录结构

llm_service/
├── download.sh          # 下载 vLLM-Ascend 镜像和 NPU 驱动与固件，可选下载模型权重
├── install_base_sw.sh   # 安装系统基础软件（系统包、NPU 驱动、Docker Compose）
├── install_llm.sh       # 部署基于 vLLM Ascend 的 LLM 模型服务
└── README.md            # 本使用指南

安装部署流程

1. 准备工作

• 确保系统已连接网络
• 确保当前执行用户为 root 用户
• 确保磁盘空间充足（至少 100GB，取决于模型大小）
• 执行下载的机器需安装docker用于下载镜像，其余机器可通过本工具自动安装dokcer
• 克隆本代码仓：git clone https://gitcode.com/Ascend/ascend-deployer.git -b appliance_deployer
• 如需多机执行安装，推荐先配置服务器间的免密登录，可提升安全性和操作便利性。免密登录配置方法请参考相关文档或使用 ssh-copy-id 命令。
• 修改 ./ascend_deployer/inventory_file 文件配置待安装服务器的信息，示例如下：

  [worker]
  xx.xxx.xx.xx1 ansible_ssh_user="root"        # 请替换为实际待安装设备的IP（推荐免密方式）
  xx.xxx.xx.xx2 ansible_ssh_user="root"        # 请替换为实际待安装设备的IP（推荐免密方式）
  

  如未配置免密登录，也可在配置文件中填写密码：

  [worker]
  xx.xxx.xx.xx1 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       # 请替换为实际密码
  xx.xxx.xx.xx2 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       # 请替换为实际密码
  

  注意：在配置文件中填写密码存在安全风险，请在部署完成后及时清理密码信息。
• 使用双机部署 LLM 模型服务时，[worker] 的第一台设备为主节点。后续脚本执行时将基于此文件进行批量操作。

2. 下载所需软件包和模型

使用方式：

首先使用 download.sh 脚本下载 Ascend 相关软件包和所需的 LLM 模型权重：

cd ./custom_scripts/llm_service/
chmod +x *.sh
./download.sh --os <os_type> --model <model_name> [--download-model] [--stream]

参数说明：

参数	必填	说明
--os <os_type>	是	指定操作系统类型，可直接输入数字选择
--model <model_name>	是	指定模型名称，用于根据模型匹配对应的 vLLM-Ascend 镜像版本，可直接输入数字或模型名称（如 Qwen3-8B）
--download-model	否	开关参数，加上此参数时才会使用 modelscope 下载模型权重到 model_weights/ 目录；不加则仅下载 vLLM-Ascend 镜像和 NPU 驱动，不会下载模型权重
--server-type <a2|a3>	否	指定服务器类型；不指定将自动检测，检测失败默认使用 Atlas 800I A2
--stream	否	启用流式打印下载输出
-h, --help	否	显示帮助信息，查看支持的操作系统和模型列表

示例：

# 查看帮助信息
./download.sh --help

# 仅下载软件包（vLLM-Ascend 镜像 + NPU 驱动），不下载模型权重
# --model 用于匹配该模型对应的 vLLM-Ascend 版本
./download.sh --os OpenEuler_22.03LTS-SP4_aarch64 --model Qwen3-8B

# 下载软件包并通过 --download-model 同时下载模型权重
./download.sh --os 1 --model Qwen3-8B --download-model

# 指定服务器类型，下载软件包和模型权重
./download.sh --os 1 --model Qwen3.5-27B --server-type a3 --download-model

# 流式打印输出，下载软件包和模型权重
./download.sh --os 1 --model Qwen3.5-27B --download-model --stream

--download-model 用法说明：

• --download-model 是一个开关参数，不影响其他参数的行为
• 加上该参数后，脚本会在 Ascend 软件包下载完成后，自动使用 modelscope 下载 --model 指定的模型权重
• 不加该参数时，脚本仅下载 vLLM-Ascend 镜像和 NPU 驱动，不会下载模型权重
• 模型权重下载完成后会存入 custom_scripts 同级的 model_weights/<模型名称>/ 目录
• 后续执行 install_llm.sh 部署模型时，脚本会自动将 model_weights/ 中的权重移动到 --weight_path 指定的目标目录

配置说明：

• Linux 系统中可执行 cat /etc/os-release 命令查看操作系统类型，如 PRETTY_NAME="openEuler 22.03 (LTS-SP4)" 则操作系统类型为 OpenEuler_22.03LTS-SP4
• 脚本中 DOWNLOAD_PARAMS 默认值为 vLLM-Ascend==800I-A2-v0.18.0,NPU==25.5.0
• --model 参数会根据指定的模型名称，自动查找该模型对应的 vLLM-Ascend 版本并覆盖 DOWNLOAD_PARAMS 中的 vLLM-Ascend 版本，因此即使不下载模型权重也需提供
• 下载的模型权重将存储在 custom_scripts 同级的 model_weights/ 目录下
• 该脚本会调用 common/download.sh 执行实际的下载任务

注意：

• 下载模型权重依赖 modelscope 命令行工具，可能会遇到 SSL 认证问题，需自行完成相关配置，或临时禁用 SSL 认证（不建议）

3. 安装基础软件

使用方式：

使用 install_base_sw.sh 脚本安装基础软件组件：

./install_base_sw.sh

配置说明：

默认直接安装脚本中 INSTALL_SOFTWARE 参数指定的软件，无需用户交互。可以在脚本头部修改以下配置，如已安装驱动与固件且当前版本驱动固件与 vLLM-Ascend 镜像中的 CANN 版本匹配，可将 npu 从 INSTALL_SOFTWARE 参数中移除以避免重启服务器，CANN 与驱动版本配套关系请参考CANN 与驱动版本配套关系，vLLM-Ascend 镜像配套软件版本可参考兼容性矩阵：

配置项	默认值	说明
INSTALL_SOFTWARE	sys_pkg,npu	指定要安装的软件列表
ENABLE_SOFTWARE_SELECTION	false	设置为 true 时会显示软件列表供用户选择

注意：

• 安装 NPU 驱动和固件后，建议安装完成后立即重启。单机安装执行 reboot 命令。批量安装使用前面配置的 inventory_file 执行以下命令重启所有设备（如 Ascend Deployer 部署在待安装设备上，需先屏蔽本机 IP）：

  ansible -i inventory_file all -m shell -a 'reboot'
  

• 该脚本会调用 common/base_install.sh 执行实际的安装任务

4. 安装和配置 LLM 模型服务

前提条件：

• 执行部署 LLM 模型服务前，请先确保要使用的 NPU 未被占用，否则可能会导致模型服务启动失败
• 下载的模型权重目录名必须与模型名称一致，否则 vLLM 服务启动时会报错。如 --model 参数输入的模型名称为 Qwen3-8B，--weight_path 参数指定的权重路径为 /data/weights，则模型权重目录的绝对路径应为 /data/weights/Qwen3-8B
• 使用双机部署时，inventory_file 中 [worker] 的第一台设备为主节点

使用方式：

使用 install_llm.sh 脚本安装和配置 vLLM Ascend 模型服务，成功安装后会提示模型服务信息：

./install_llm.sh --model <model_name> --port <port> --api-key <api_key> [--weight_path <weight_path>] [--devices <device_list|card_count>] [--dual-node] [--privileged <true|false>]

参数说明：

参数	必填	说明
-m, --model	是	指定模型名称，支持直接输入数字选择，也支持直接输入模型名称（如 Qwen3-8B）
-p, --port	是	指定模型服务端口号
-k, --api-key	是	指定模型服务的 API KEY
-w, --weight_path	否	指定模型权重所在的父目录，默认值 /data/weights，若使用本工具下载的模型权重，工具会自动将下载的权重从工具目录移动到该目录
-d, --devices	否	指定 vLLM 容器挂载的卡列表或卡数，默认使用配置文件中的值；格式：[0,1,2,3] 或 4（自动生成 [0,1,2,3]）
--dual-node	否	使用双机部署模式，默认单机模式
--privileged <true|false>	否	是否使用特权容器，默认 false；使用特权容器后会将服务器所有卡挂载到容器，如未指定 --devices，默认使用前 N 张卡部署模型
-sn, --served-model-name	否	指定服务模型名称，用于 API 调用时使用的模型标识，默认与 --model 参数相同
-h, --help	否	显示帮助信息，查看支持的模型列表及各机型支持情况

示例：

# 查看帮助信息（包含支持的模型和机型列表）
./install_llm.sh --help

# 通过数字选择模型安装 LLM 服务
./install_llm.sh --model 1 --port 8000 --api-key vllm12#$

# 通过名称选择模型安装 LLM 服务（双机部署）
./install_llm.sh --model Qwen3-8B --port 8000 --api-key vllm12#$ --dual-node

# 指定权重路径安装 LLM 服务
./install_llm.sh --model Qwen3.5-27B --port 8000 --api-key vllm12#$ --weight_path /data/models --devices 8

# 开启特权容器安装 LLM 服务，且在 4,5,6,7 四张卡上部署模型
./install_llm.sh --model Qwen3.5-27B --port 8000 --api-key vllm12#$ --devices [4,5,6,7] --privileged true

注意事项：

• 执行该安装脚本会自动将 model_weights/ 目录下的模型权重移动到 --weight_path 指定的目标目录
• 安装成功后会在 --weight_path 对应目录下的模型权重目录中生成启动脚本run_container_{IP}_{容器名}.sh。如启动 vLLM 服务失败，可以通过命令"docker logs 容器名"来查看日志
• 由于模型服务拉起耗时较长，安装脚本最多等待 15 分钟。如 15 分钟内模型服务未启动成功，安装脚本按安装失败处理，请自行检查日志确认是否成功拉起模型服务
• 安装脚本会自动拉起以 vllm_ascend_x 命名的容器，如有重名容器会自动增加数字后缀。如安装失败不会自动删除相应容器，如有需要请手动删除
• 该脚本会调用 common/vllm_server.sh 执行实际的部署任务

5. 卸载模型服务

使用方式：

如需卸载已部署的 LLM 模型服务，执行以下命令：

# 停止容器
docker stop <容器名>

# 删除容器
docker rm <容器名>

容器名默认为 vllm_ascend_x 格式（如 vllm_ascend_0、vllm_ascend_1 等），可通过 docker ps -a 查看所有容器。

示例：

# 查看所有容器
docker ps -a

# 停止并删除 vllm_ascend_0 容器
docker stop vllm_ascend_0
docker rm vllm_ascend_0

注意：

• 卸载容器不会删除模型权重文件，如需彻底清理请手动删除 --weight_path 指定的模型权重目录

模型配置管理

模型配置文件位于 conf/model_config/ 目录下，按模型系列和名称组织。

目录结构

conf/model_config/
└── <模型系列>/
    └── <模型名>/
        ├── <模型名>-800i-a2-single.json    # A2 单机部署配置
        ├── <模型名>-800i-a2-double.json    # A2 双机部署配置
        ├── <模型名>-800i-a3-single.json    # A3 单机部署配置
        └── <模型名>-800i-a3-double.json    # A3 双机部署配置

文件名命名规则

文件名的关键字决定了该模型支持哪些部署模式，脚本通过解析文件名自动将模型分类到对应的部署模式列表中。命名格式为：

<模型名>-<机型>-<部署模式>.json

关键字	说明
800i-a2	Atlas 800I A2 / 300I A2
800i-a3	Atlas 800I A3
single	单机部署
double	双机部署

注意： 文件名中必须包含上述关键字，否则脚本无法正确识别该模型支持的部署模式。

JSON 配置字段

每个 JSON 文件的配置内容如下：

{
    "download_model_name": "<modelscope模型名称>",
    "vllm_ascend_version": "<vLLM-Ascend版本>",
    "sever_params": {},
    "env_vars": {}
}

字段	必填	说明
download_model_name	是	模型在 ModelScope 上的完整名称，用于下载模型权重和展示可用模型列表
vllm_ascend_version	否	指定模型对应的 vLLM-Ascend 镜像版本；不填则按服务器类型使用默认版本

新增模型配置

1. 在 conf/model_config/ 下创建 <模型系列>/<模型名>/ 目录
2. 根据部署模式创建对应的 JSON 配置文件，遵循文件名命名规则
3. 填写配置字段，执行 ./install_llm.sh --help 验证新模型已出现在支持列表中

修改模型配置

1. 使用 find conf/model_config -name "*<模型名>*" 定位配置文件
2. 编辑 JSON 文件修改配置字段
3. 注意：修改 vllm_ascend_version 后需重新下载镜像；修改 download_model_name 后需重新下载模型权重；已部署的服务不受配置修改影响，需重新执行 install_llm.sh 应用新配置

常见问题和注意事项

1. 权限问题

   • 确保所有脚本都具有执行权限：chmod +x *.sh
   • 请使用 root 用户执行

2. 网络问题

   • 确保系统已连接到可靠的网络
   • 模型下载可能需要较长时间，请耐心等待

3. 磁盘空间

   • 确保有足够的磁盘空间用于存储模型和软件包
   • 单个 LLM 模型可能需要数十 GB 的磁盘空间

4. 端口冲突

   • 如果指定的端口已被占用，请使用 --port 参数指定其他端口

5. Ansible 回调模块无效问题

   • 当看到如下报错信息：ERROR! Invalid callback for stdout specified: community.general.yaml，表明 Ansible 环境缺少 community.general 这个 Ansible 集合，可进入 ./ascend_deployer/resources/sources/ansible_collections 目录下执行以下命令安装该集合：

ansible-galaxy collection install community-general-*.tar.gz ```

6. "Get ACL JitCompile default value failed" 报错处理
   • 在 Atlas 800T A2 服务器上，当操作系统内核版本低于 5.10 时，可能会遇到此报错
   • 解决方案：
     • 方案一：使用特权容器部署，在 install_llm.sh 中添加 --privileged true 参数
     • 方案二：升级操作系统内核至 5.10 或更高版本

故障排除

• 如果安装失败，请检查错误信息并根据提示进行修复
• 确保所有依赖项已正确安装
• 检查网络连接和权限设置
• 查看日志文件以获取更详细的错误信息