Star94
60
代码
代码
Issues21
Pull Requests9
流水线
讨论
Wiki
分析
Star94
60
ascend-robotascend-robot新增LLM模型自动化部署
1bf846c4创建于 24 天前历史提交
文件最后提交记录最后更新时间
README.md
新增LLM模型自动化部署24 天前
install_base_sw.sh
新增WebUI页面实现可视化的部署流程管理1 个月前
install_llm.sh
新增WebUI页面实现可视化的部署流程管理1 个月前
install_opencode.sh
新增WebUI页面实现可视化的部署流程管理1 个月前
opencode_download.sh
新增LLM模型自动化部署24 天前
README.md

OpenCode 安装部署脚本使用指南

本目录包含用于安装和部署 OpenCode 系统的一系列自动化脚本。这些脚本简化了从下载到安装的完整流程，帮助用户快速搭建 OpenCode 环境。

目录结构

opencode/
├── opencode_download.sh   # 下载OpenCode一体机相关软件包和模型权重
├── install_base_sw.sh     # 安装系统基础软件，如操作系统依赖、NPU驱动和Docker等
├── install_llm.sh         # 部署基于vLLM Ascend的LLM模型服务，支持多种机型和模型
├── install_opencode.sh    # 部署和配置OpenCode服务，支持多实例部署
└── README.md              # 本使用指南

安装部署流程

1. 准备工作

  • 确保系统已连接网络
  • 确保当前执行用户为root用户
  • 确保磁盘空间充足（至少100GB，取决于模型大小）
  • 克隆本代码仓（如果未克隆）：git clone https://gitcode.com/Ascend/ascend-deployer.git
  • 切换至appliance_deployer分支：git checkout appliance_deployer
  • 如需多机执行安装时需参考配置批量待安装场景的方式一修改./ascend_deployer/inventory_file文件配置待安装服务器的信息，执行脚本后则会同时在配置的待安装设备上执行安装，示例如下:
    [worker]
xx.xxx.xx.xx1 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       #请替换为实际待安装设备的IP
xx.xxx.xx.xx2 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       #请替换为实际待安装设备的IP

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

使用方式：

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

cd ./kadt/opencode/
chmod +x *.sh
./opencode_download.sh --os <os_type> [--model <model_name>] [--stream]

参数说明：

  • --os <os_type>：指定操作系统类型（必填），可直接输入数字选择
  • --model <model_name>：可选，指定要下载的模型名称，可直接输入数字选择
  • --stream：可选，启用流式打印下载输出
  • --server-type <a2|a3>：可选，指定服务器类型；如果未指定，将自动检测服务器类型，检测失败则默认使用 Atlas 800I A2
  • -h, --help：显示帮助信息，查看支持的操作系统和模型列表

支持列表：

  • 操作系统：OpenEuler,BCLinux,CTyunOS,CULinux,CentOS,Debian,EulerOS,Kylin,MTOS,UOS,Ubuntu,VesselOS,veLinux等
  • 模型：Qwen3-8B,Qwen3-14B,MiniMax-M2.5,Qwen3.5-27B,Qwen3.5-35B-A3B-w8a8-mtp,Kimi-K2.5-W4A8等

示例：

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

# 通过名称指定操作系统和模型
./opencode_download.sh --os OpenEuler_22.03LTS-SP4_aarch64 --model Qwen/Qwen3.5-27B

# 通过数字选择操作系统和模型
./opencode_download.sh --os 1 --model 5

# 指定下载Atlas 800I A3版本的vllm-ascend镜像
./opencode_download.sh --os 1 --model Qwen/Qwen3.5-27B --server-type a3

配置说明：

  • Linux系统中可执行cat /etc/os-release命令查看操作系统类型，如PRETTY_NAME="openEuler 22.03 (LTS-SP4)"则操作系统类型为OpenEuler_22.03LTS-SP4
  • 脚本中DOWNLOAD_PARAMS参数指定了要下载的软件列表（默认：OpenCode-image(OpenCode镜像),DockerCompose==v5.0.0-rc.2(Docker Compose),vLLM-Ascend==800I-A2-v0.18.0(Atlas 800I A2 vllm-ascend镜像),NPU==25.5.0(NPU驱动与固件)）
  • 可选参数 --server-type <a2|a3> 指定服务器类型，用于选择vLLM-Ascend镜像版本，若未指定，将自动检测服务器类型，检测失败则默认使用 Atlas 800I A2 版本的 vLLM-Ascend 镜像
  • 如需安装Atlas 800I A3的驱动与固件，请前往昇腾驱动与固件下载页面下载所需版本与架构的驱动与固件（如25.5.1版本的A3驱动固件文件名为Atlas-A3-hdk-npu_25.5.1_linux-aarch64.zip），并保存在./ascend_deployer/resources/npu目录下
  • 下载的模型权重将存储在kadt同级的 model_weights/ 目录下

注意：

  • 下载Docker Compose需要保证服务器可访问Docker Compose页面，如无法访问可去掉脚本DOWNLOAD_PARAMS参数中的DockerCompose==v5.0.0-rc.2，并手动下载对应架构的Docker Compose二进制文件（如docker-compose-linux-aarch64）后放置在./ascend_deployer/resources/DockerCompose目录下。
  • 脚本使用modelscope命令行下载模型权重，可能会遇到SSL认证问题，需自行完成相关配置，或临时禁用SSL认证（不建议）。
  • 该脚本会调用common/download.sh脚本执行实际的下载任务

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,docker_compose）
  • ENABLE_SOFTWARE_SELECTION：是否启用用户选择功能（默认：false），设置为true时会显示软件列表供用户选择

注意：

  • 安装NPU驱动和固件后，建议安装完成后立即重启，单机安装时重启请执行reboot命令。批量安装则执行以下命令重启所有设备。
    • 如果Ascend Deployer工具是部署在某一台待安装设备上，需要先在“inventory_file”屏蔽本机IP地址，否则执行重启时可能还未发送重启命令到其他服务器，本机就已重启，导致其他服务器无法重启。如果Ascend Deployer工具未部署在待安装服务器可以跳过本步骤直接执行重启服务器。
    # 本机IP address ansible_ssh_user="root" # 屏蔽本机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'，如使用openclaw_download.sh脚本下载模型权重，默认会将在--weight_path参数指定的目录下创建与模型名称一致的子目录存储模型权重
  • 使用双机部署时需参考配置批量待安装场景的方式一修改./ascend_deployer/inventory_file文件配置待安装服务器的信息，[worker]的第一台待安装设备为主节点，示例如下:
    [worker]
xx.xxx.xx.xx1 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       #请替换为实际待安装设备的IP
xx.xxx.xx.xx2 ansible_ssh_user="root" ansible_ssh_pass="xxxxxxx"       #请替换为实际待安装设备的IP

使用方式：

使用 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]

参数说明：

  • -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张卡部署模型，可结合--devices参数指定部署模型的卡，如--devices [4,5]则表示在4,5两张卡上部署模型
  • -h, --help：显示帮助信息，查看支持的模型列表及各机型支持情况

支持模型列表：

  • Atals 800I A2 单机 / Atlas 300I A2 多卡：Qwen3-8B、Qwen3-14B、Qwen3.5-27B、Qwen3.5-35B-A3B-w8a8-mtp等
  • Atals 800I A2 双机：MiniMax-M2.5等
  • Atals 800I A3 单机：Qwen3-8B、Qwen3-14B、Qwen3.5-27B、Qwen3.5-35B-A3B-w8a8-mtp、Kimi-K2.5-W4A8、MiniMax-M2.5等
  • Atals 800I A3 双机：Kimi-K2.5-W4A8等

示例：

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

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

# 通过名称选择模型安装LLM服务（双机部署）
./install_llm.sh --model Qwen3-8B --port 8000 --api-key vllm12#$ --devices [0,1,2,3] --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

安装成功后会提示模型服务信息，包括模型名称、API、API KEY等，如下图所示：

模型服务信息

注意事项：

  • 执行该安装脚本会自动在--weight_path参数对应目录下的模型权重目录中生成容器启动脚本run_container_{IP}_{容器名}.sh。如启动 vLLM 服务失败，可以通过命令"docker logs 容器名"来查看日志

  • 由于模型服务拉起耗时较长，安装脚本最多等待15分钟，如15分钟内模型服务未启动成功，安装脚本按安装失败处理，请自行检查日志确认是否成功拉起模型服务

  • 安装脚本会自动拉起以vllm_ascend_x命名的容器，如有重名容器会自动增加数字后缀，如安装失败不会自动删除相应容器，如有需要请手动删除相应容器

  • 该脚本会调用common/vllm_server.sh脚本执行实际的部署任务

5. 安装和配置OpenCode服务

使用方式： 使用 install_opencode.sh 脚本安装和配置OpenCode服务实例,会拉起指定实例数量的OpenCode容器,安装成功后会提示容器名及OpenCode访问信息：

./install_opencode.sh --port <base_port> --model <model_name> --api-key <api_key> --url <vllm_url> [--count <instance_count>] [--data_path <data_path>]

参数说明：

  • -p, --port：多OpenCode实例的起始端口（必填）,端口号依次累加，如创建2个实例，起始端口为9080，则会占用9080~9081两个端口，请确保端口不会冲突
  • -m, --model：推理服务模型名称（必填）
  • -u, --url：推理服务URL（必填）,格式为http://0.0.0.0:8000/v1
  • -k, --api-key：模型服务的API KEY（必填）
  • -c, --count：要启动的OpenCode实例数量（可选，默认：1）
  • -d, --data_path：OpenCode数据存储目录（可选，默认：/data/opencode）
  • -h, --help：显示帮助信息

示例：

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

# 安装OpenCode服务
./install_opencode.sh --port 9080 --model Qwen3-8B --url http://0.0.0.0:8000/v1
./install_opencode.sh --port 9080 --model Qwen3-8B --url http://0.0.0.0:8000/v1 --count 2 --data_path /data/opencode_data

访问OpenCode服务：

在本地安装了opencode之后，可在cmd窗口中通过opencode attach http://{服务器IP}:{port}来访问opencode服务，其中port为安装OpenCode服务时--port指定，随实例数递增，例如--port 9080 --count 2，则端口为9080和9081

WebUI 可视化部署（测试中）

注意：WebUI 功能目前处于测试阶段，可能存在不稳定或功能不完整的情况，建议仅用于测试和体验。生产环境部署请使用命令行方式。

WebUI 提供可视化的部署流程管理界面，支持单步执行、实时日志查看、任务中止等功能。

启动 WebUI

cd ./kadt/webui
./launcher.sh

默认端口：8080

自定义端口

./launcher.sh 9000

launcher.sh 功能

启动脚本会自动完成以下操作：

  1. 检查 Python 环境：验证 Python 3 是否可用
  2. 自动安装依赖：检测并安装 Flask、PyYAML（如未安装）
  3. 获取本机 IP：自动获取服务器 IP 地址用于远程访问
  4. 启动服务：启动 Flask 应用

启动后显示访问地址：

访问地址:
  本机: http://127.0.0.1:8080
  远程: http://10.10.10.10:8080

WebUI 操作流程

  1. 选择部署场景：在首页选择 opencode profile
  2. 查看部署步骤：左侧显示完整 workflow（下载 → 基础软件 → LLM 服务 → OpenCode 服务）
  3. 执行单步操作：
    • 点击当前步骤进入参数填写页面
    • 填写必要参数（操作系统、模型、端口等）
    • 点击"开始执行"
    • 实时查看执行日志
    • 支持中止正在运行的任务
  4. 继续下一步：当前步骤完成后可跳转至下一步

WebUI 功能特性

  • 配置驱动：参数通过 YAML 配置文件定义，易于扩展
  • 实时日志：实时显示脚本输出，支持 ANSI 颜色高亮
  • 模型兼容性过滤：根据服务器类型自动过滤可选模型
  • 任务状态持久化：WebUI 重启后可恢复任务状态
  • 服务器配置：支持配置目标服务器列表（用于 Ansible 批量部署）

WebUI 目录结构

webui/
├── app.py                  # Flask 主应用
├── script_runner.py        # 脚本执行引擎
├── scripts_config.yaml     # 配置文件
├── launcher.sh             # 启动脚本
├── templates/              # HTML 模板
├── static/                 # CSS/JS 文件
└── logs/                   # 任务日志存储

常见问题和注意事项

  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

故障排除

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