---
slug: vllm-ascend-modelarts-deploy
displayName: vLLM on Ascend → ModelArts 部署
version: 1.2.1
summary: 把 vllm-ascend 官方教程页的部署配置改写成 ModelArts 可直接运行的部署目录：rank table 分发、group 0 约束、NIC 绑定、PD 分离，一条命令在所有节点执行。
license: MIT
author: xuopoj
homepage: https://github.com/xuopoj/ascend-delivery
name: vllm-ascend-modelarts-deploy
description: 用于在华为云 ModelArts 的 Ascend NPU 上部署 vLLM 模型（Atlas 800 A2/A3、Atlas 300I DUO，以及上游教程记录的其他 Ascend 平台），或审查已有的 ModelArts 部署目录。根据上游 vllm-ascend 教程生成自包含的部署目录，处理 rank table 分发、group 0 约束和 PD 接线；也可按相同规则审查已有目录，先报告问题再修改。不适用于 NVIDIA GPU 上的 vLLM，也不适用于 ModelArts 以外的 Ascend 主机。
---

# 将 vLLM on Ascend 部署到 ModelArts

上游教程假设你写脚本时已经知道每个节点的 IP。ModelArts 在部署时才分配
节点，并通过 rank table 发布地址；部署目录挂载到 `/scripts`，权重挂载到
`/model`，**所有节点执行同一条启动命令**。本技能负责适配这部分差异。

## 两种模式

**生成（Generate）** — 根据上游教程页生成部署目录，按下方流程执行。

**审查（Review）** — 审查已有部署目录并提出修改建议，无论它是否由本技能
生成。参见 `references/review.md`。按严重程度报告问题后停止，由用户决定
应用哪些修改。

## 生成流程

1. **查找并获取上游页面。** 页面位于
   `https://docs.vllm.ai/projects/ascend/en/latest/tutorials/models/<Page>.html`，
   但 `<Page>` 是页面名，不一定是模型名。同一模型家族可能拆成多个页面：
   `Qwen3-Dense.html` 包含 Qwen3-32B，`Qwen3-235B-A22B.html` 则是独立页面。
   直接根据模型名猜 URL 经常得到 404。

   **先列出上游仓库目录，再匹配模型与文件名：**
   `https://api.github.com/repos/vllm-project/vllm-ascend/contents/docs/source/tutorials/models`。
   未认证请求可能触发 API 限流，返回限流 JSON 而非目录列表。这时直接探测
   候选文件名：
   `curl -o /dev/null -w '%{http_code}' https://raw.githubusercontent.com/vllm-project/vllm-ascend/main/docs/source/tutorials/models/<Name>.md`。
   同时尝试带连字符和不带连字符的名称，例如页面名是 `GLM5.3`，不是
   `GLM-5.3`。渲染后的模型索引页只是没有链接的占位页，不能用于查找。
   确认 HTTP 状态码为 200 后再读取内容。

   从实际 HTML 提取标题；摘要式抓取可能编造看似合理、实际不存在的章节
   结构。以 “Online Service Deployment” 下的子章节为可选拓扑，不得生成
   页面未记录的拓扑。**检查标签页中的变体**（A2 / A3 / dspark），并读取
   **第 4 节**的镜像标签；两者都可能因平台而异，容易遗漏。
   参见 `references/output-shape.md`。
2. **列出所有拓扑，再让用户选择。** 列出页面记录的每种拓扑，包括节点数、
   结构和取舍，不得自行选择。**列出页面覆盖的所有平台**，不限于 A2/A3。
   300I DUO 或 310P 标签页也是有效选项；即使不熟悉，也应说明其要求，
   由用户决定。页面只在正文提及、没有配置代码块的结构，要明确标注：
   只能搭建骨架，不能生成完整配置。
3. **与用户确认部署目标：** 平台、节点数，以及 ModelArts 推理版本
   （1.0 或 2.0），不得猜测。

   **A3 仅支持 ModelArts 推理 2.0**，不得为 A3 生成推理 1.0 方案。

   同时确认权重大小和准备方式：2.0 权重大于 100 GB 时强烈推荐模型预热；
   1.0 不支持模型预热，可使用实验性本地缓存方案：OBS 权重仍挂载到 `/model`，
   本地缓存挂载到 `/model_local`。确认缓存检查模式：`sha256` 使用预先生成的
   清单校验本地文件；`filename_size` 仅比较相对路径和大小，可能复用错误内容。
   仅复制缺失或不匹配的文件，完成后从 `/model_local` 加载。
   细节见 `references/adaptation.md` §1。

   对于 2.0，还要确认**部署单元**划分：多节点使用两个部署单元，第一个
   包含一个资源实例，第二个包含其余资源实例，使 group 0 恰好有一个节点；
   单节点使用一个部署单元，包含一个资源实例。
   参见 `references/modelarts-spine.md`。

   **A2 每节点呈现 8 个设备，A3 每节点呈现 16 个设备。** A3 的 8 个 NPU
   每个包含两个芯片，因此页面可能写成 `128GB × 8` 或 `64GB × 16`。
   计算页面配置的 `dp_local × tp`，检查结果是否为 8 或 16。
   参见 `references/topology-matrix.md`。
4. **逐字节复制公共启动脚本（spine）。** 从 `assets/spine/` 复制到新目录：
   所有布局都需要 `start.sh`，多节点布局还需要 `setup_rank_env.sh`。
   不得修改副本；如需修复，应修改源资产后重新复制，确保各布局内容一致。

   `setup_rank_env.sh` 通过 source 加载，不直接执行，因此其文件权限模式
   不影响加载。`start.sh` 是服务启动入口，复制后执行 `chmod 755`。
   修改权限不等于修改文件内容，逐字节一致要求针对内容。
   单节点布局无需 rank table、角色分发或 NIC 初始化段，但仍需 `start.sh`。
5. **编写脚本。** 从 `assets/templates/` 开始，应用
   `references/adaptation.md` 中的每条改写规则；该文件定义了实际适配工作。
6. **编写 `meta.yaml` 和 `README.md`。** 记录来源 URL、当天日期、第 4 节
   的镜像标签、`verified: false`，以及所有未解决项。
   **说明性文字使用中文**，参见 `references/output-shape.md`。

需要自定义指标采集时，检查每个节点是否运行多个 vLLM API 服务，以及平台
是否只接受一个指标端点。设计前阅读 `references/metrics.md`，确认端点限制
的作用范围和端口归属，尤其注意 PD proxy 是否已占用 `8080`。
优先使用随目录提供的指标实现和现有依赖，不要求客户在运行容器中安装
`prometheus-client`，不得在启动时安装新包，具体规则见 `references/metrics.md`。

执行第 5 步之前，先阅读 `references/modelarts-spine.md`；脚本的设计依赖
rank table 和 group 0 约束。

## 规则

- **适配部署环境，保留引擎配置。** 可适配路径、地址、端口、环境变量和
  角色分发，这些信息由平台分配。所有引擎参数，包括 `--additional-config`
  中的每一项，都保持上游页面的配置。
- **生成结果均未经过硬件验证。** 明确说明“根据上游页面适配，未在硬件上
  验证”，不得暗示已确认可用。
- **不得修改布局中的 spine 副本。** 修改 `assets/spine/` 后重新复制；
  修改前先阅读 `assets/README.md`。
- **不得编造页面未提供的值。** 在脚本中保留 `TODO(gap):`，在 `meta.yaml`
  中记录并告知用户。看似合理的猜测不能替代明确标记的未解决项。
- **必须检查 group 0 约束。** 提供 API 的 rank 必须位于 group 0，headless
  rank 必须位于其外。`run.sh` 必须校验，不满足时立即报错退出。
- **模型路径使用确认后的实际加载路径。** 默认使用 `/model`；1.0 使用本地
  缓存方案时，OBS 源保持 `/model`，引擎从 `/model_local` 加载。挂载配置需与用户
  确认。不得沿用上游权重路径，也不得放在 `/root` 下；其 `0700` 权限会阻止
  1.0 的 `ma-user` 访问。
- **注释保持精简。** 只解释代码本身无法表达的内容，设计理由放在 README。
- **审查只报告，不修改。** 先列出问题及各自的具体修改建议，仅应用用户
  选定的修改。生产目录与上游页面的差异可能是有意为之。

## 参考文件

| 文件 | 阅读时机 |
|---|---|
| `references/adaptation.md` | 编写脚本时：适配规则 |
| `references/modelarts-spine.md` | 理解 rank table、`AISHIPBOX_*`、group 0 和 NIC 初始化段 |
| `references/topology-matrix.md` | 选择拓扑和资源规格时 |
| `references/troubleshooting.md` | 部署出现异常时 |
| `references/output-shape.md` | 确认部署目录应包含哪些文件时 |
| `references/review.md` | 审查已有部署目录时 |
| `references/metrics.md` | 自定义指标采集、通过单端点汇集 PD 多服务指标时 |

## 作者

作者：[xuopoj](https://github.com/xuopoj)。
源码：<https://github.com/xuopoj/ascend-delivery>。

有问题、修正建议，或发现本技能无法妥善处理的教程页，请提交 issue：
<https://github.com/xuopoj/ascend-delivery/issues>。
欢迎反馈硬件验证结果；只有在真实 NPU 上运行后，生成的部署配置才算经过
硬件验证。