已合并
[文档] 环境准备与快速入门文档可读性优化 #348
高鹏创建于 6月25日
[文档] 环境准备与快速入门文档可读性优化 #348
已合并
共 4 个文件变更+179-194
| @@ -6,7 +6,7 @@ HOST_IP="xxx.xxx.xxx.xxx" | |||
| 6 | # | 6 | # |
| 7 | # 原理说明： | 7 | # 原理说明： |
| 8 | # calico会运行在集群中的每一个服务器上（只在管理节点配置calico，该配置会应用于集群中的所有节点），因此，述表达式要保证calico能够在集群中的每台服务器都找到网卡： | 8 | # calico会运行在集群中的每一个服务器上（只在管理节点配置calico，该配置会应用于集群中的所有节点），因此，述表达式要保证calico能够在集群中的每台服务器都找到网卡： |
| 9 | -# 如果整个集群所有节点的主网卡名称(通过ip route | grep default查找)相同，例如：集群各节点主网卡名称分别为enp1（master）、enp2（worker1节点）、enp115235(worker节点2)，可以填写为enp.*。 | 9 | +# 如果整个集群所有节点的主网卡名称(通过ip route | grep default查找)前缀相同，例如：集群各节点主网卡名称分别为enp1（master）、enp2（worker1节点）、enp115235(worker节点2)，可以填写为enp.*。 |
| 10 | # 如果各节点主网卡名称不一致，需用 | 把各节点的命名规则都写进表达式。例如：多数节点主网卡为 enp 开头，个别节点主网卡 virbr0 上，可填写为 enp.*|virbr0。 | 10 | # 如果各节点主网卡名称不一致，需用 | 把各节点的命名规则都写进表达式。例如：多数节点主网卡为 enp 开头，个别节点主网卡 virbr0 上，可填写为 enp.*|virbr0。 |
| 11 | IP_AUTODETECTION_IFACE="xxx.*" | 11 | IP_AUTODETECTION_IFACE="xxx.*" |
| 12 | 12 | ||
| @@ -2,7 +2,7 @@ | |||
| 2 | 2 | ||
| 3 | ## 依赖说明 | 3 | ## 依赖说明 |
| 4 | 4 | ||
| 5 | -MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署、服务暴露、健康探针与故障重启，从而保证服务的安全运行；同时依赖 MindCluster 提供昇腾集群调度能力，实现NPU 资源调度、故障自动恢复等功能。其部署示意图如[图1 K8s集群整体部署视图](#fig698114995216)所示，依赖的具体组件名称及功能说明如[表1 依赖列表](#table9819144513712)所示。 | 5 | +MindIE Motor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署、服务暴露、健康探针与故障重启，从而保证服务的安全运行；同时依赖 MindCluster 提供昇腾集群调度能力，实现NPU 资源调度、故障自动恢复等功能。其部署示意图如[图1 K8s集群整体部署视图](#fig698114995216)所示，依赖的具体组件名称及功能说明如[表1 依赖列表](#table9819144513712)所示。 |
| 6 | 6 | ||
| 7 | **图 1** K8s集群整体部署视图<a name="fig698114995216"></a> | 7 | **图 1** K8s集群整体部署视图<a name="fig698114995216"></a> |
| 8 | 8 | ||
| @@ -23,13 +23,15 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 23 | |Ascend Docker Runtime|提供docker或containerd的昇腾容器化支持，自动挂载所需文件和设备依赖。|Y|Y| | 23 | |Ascend Docker Runtime|提供docker或containerd的昇腾容器化支持，自动挂载所需文件和设备依赖。|Y|Y| |
| 24 | |Infer Operator|创建推理实例Workload与Service，提供推理实例的手动扩缩容能力。|Y|N| | 24 | |Infer Operator|创建推理实例Workload与Service，提供推理实例的手动扩缩容能力。|Y|N| |
| 25 | 25 | ||
| 26 | -## Kubernetes安装与集群创建 | 26 | +--- |
| 27 | 27 | ||
| 28 | -### 安装方式一（Motor提供安装教程） | 28 | +## Kubernetes安装 |
| 29 | 29 | ||
| 30 | -基于镜像源安装 Kubernetes。当前支持自动化脚本安装和手动安装两种方式，推荐使用自动化脚本进行安装。 | 30 | +基于镜像源安装 Kubernetes。当前支持自动化脚本安装和手动安装两种方式，推荐使用自动化脚本进行安装。也可参考 [Kubernetes 官网](https://kubernetes.io/zh-cn/docs/setup/) 进行安装。 |
| 31 | 31 | ||
| 32 | -#### 前置检查 | 32 | +--- |
| 33 | + | ||
| 34 | +### 前置检查 | ||
| 33 | 35 | ||
| 34 | 1. 已预先安装docker。 | 36 | 1. 已预先安装docker。 |
| 35 | 37 | ||
| @@ -95,7 +97,9 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 95 | df -h | 97 | df -h |
| 96 | ``` | 98 | ``` |
| 97 | 99 | ||
| 98 | -#### (推荐)自动化脚本安装 | 100 | +--- |
| 101 | + | ||
| 102 | +### 自动安装（推荐） | ||
| 99 | 103 | ||
| 100 | 脚本默认安装 1.23.0 版本的 kubernetes、3.24.5 版本的 calico，该版本组合能够支持 motor 的正常部署。 | 104 | 脚本默认安装 1.23.0 版本的 kubernetes、3.24.5 版本的 calico，该版本组合能够支持 motor 的正常部署。 |
| 101 | 105 | ||
| @@ -108,11 +112,17 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 108 | 修改脚本配置文件env.conf，需要配置内容如下。 | 112 | 修改脚本配置文件env.conf，需要配置内容如下。 |
| 109 | 113 | ||
| 110 | ```bash | 114 | ```bash |
| 111 | - # 管理节点 IP | 115 | + # 当前节点 IP |
| 112 | HOST_IP="141.61.73.111" | 116 | HOST_IP="141.61.73.111" |
| 113 | 117 | ||
| 114 | - # Calico 网卡自动探测正则表达式 | 118 | + # Calico 网卡自动探测正则表达式 |
| 115 | - IP_AUTODETECTION_IFACE="enp.*" | 119 | + # 查询主网卡命令：ip route | grep default |
| 120 | + # | ||
| 121 | + # 原理说明： | ||
| 122 | + # calico会运行在集群中的每一个服务器上（只在管理节点配置calico，该配置会应用于集群中的所有节点），因此，述表达式要保证calico能够在集群中的每台服务器都找到网卡： | ||
| 123 | + # 如果整个集群所有节点的主网卡名称(通过ip route | grep default查找)前缀相同，例如：集群各节点主网卡名称分别为enp1（master）、enp2（worker1节点）、enp115235(worker节点2)，可以填写为enp.*。 | ||
| 124 | + # 如果各节点主网卡名称不一致，需用 | 把各节点的命名规则都写进表达式。例如：多数节点主网卡为 enp 开头，个别节点主网卡 virbr0 上，可填写为 enp.*|virbr0。 | ||
| 125 | + IP_AUTODETECTION_IFACE="xxx" | ||
| 116 | 126 | ||
| 117 | # ---------- 网络代理（可选；脚本会先测直连、再测代理，哪条通用哪条） ---------- | 127 | # ---------- 网络代理（可选；脚本会先测直连、再测代理，哪条通用哪条） ---------- |
| 118 | HTTP_PROXY="http://90.255.12.94:6666" | 128 | HTTP_PROXY="http://90.255.12.94:6666" |
| @@ -139,9 +149,11 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 139 | source env.conf && sudo -E bash deploy_k8s.sh worker | 149 | source env.conf && sudo -E bash deploy_k8s.sh worker |
| 140 | ``` | 150 | ``` |
| 141 | 151 | ||
| 142 | - 安装完毕后，请参照「连接集群服务器」小节继续后续步骤。 | 152 | + 安装完毕后，无需关注[手动安装]小节，直接跳转至「创建集群」章节。 |
| 143 | 153 | ||
| 144 | -#### 手动安装 | 154 | +--- |
| 155 | + | ||
| 156 | +### 手动安装 | ||
| 145 | 157 | ||
| 146 | 1. 获取kubernetes组件。 | 158 | 1. 获取kubernetes组件。 |
| 147 | 159 | ||
| @@ -231,7 +243,7 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 231 | >https://docker.aityp.com/s/registry.k8s.io | 243 | >https://docker.aityp.com/s/registry.k8s.io |
| 232 | >``` | 244 | >``` |
| 233 | 245 | ||
| 234 | -3. 执行以下命令清空系统网络代理环境变量。Kubernetes核心组件（kubeadm/kubelet）需直接访问API Server等服务，网络代理会拦截或篡改这类请求，可能导致Kubernetes服务不可用（**计算节点执行将本步骤执行完毕即可，后续请跳转到「连接集群服务器」小节；管理节点继续向下执行**）。 | 246 | +3. 执行以下命令清空系统网络代理环境变量。Kubernetes核心组件（kubeadm/kubelet）需直接访问API Server等服务，网络代理会拦截或篡改这类请求，可能导致Kubernetes服务不可用（**计算节点执行将本步骤执行完毕即可！！！后续请跳转至「创建集群」步骤；管理节点继续向下执行**）。 |
| 235 | 247 | ||
| 236 | ```bash | 248 | ```bash |
| 237 | rm -rf /var/lib/kubelet | 249 | rm -rf /var/lib/kubelet |
| @@ -331,7 +343,7 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 331 | >[!NOTE]说明 | 343 | >[!NOTE]说明 |
| 332 | >calico会运行在集群中的每一个服务器上（只在管理节点配置calico，该配置会应用于集群中的所有节点），因此，上述表达式要保证calico能够在集群中的每台服务器找到网卡： | 344 | >calico会运行在集群中的每一个服务器上（只在管理节点配置calico，该配置会应用于集群中的所有节点），因此，上述表达式要保证calico能够在集群中的每台服务器找到网卡： |
| 333 | > | 345 | > |
| 334 | - >如果整个集群所有节点的**主网卡名称(通过ip route | grep default查找)相同**，例如：集群各节点主网卡名称分别为enp1（master）、enp2（worker1节点）、enp115235(worker节点2)，可以填写为enp.*。 | 346 | + >如果整个集群所有节点的**主网卡名称(通过ip route | grep default查找)前缀相同**，例如：集群各节点主网卡名称分别为enp1（master）、enp2（worker1节点）、enp115235(worker节点2)，可以填写为enp.*。 |
| 335 | > | 347 | > |
| 336 | > 如果**各节点主网卡名称不一致**，需用 `|` 把各节点的命名规则都写进表达式。例如：多数节点主网卡为 enp 开头，个别节点主网卡 virbr0 上，可填写为 `enp.*|virbr0`。 | 348 | > 如果**各节点主网卡名称不一致**，需用 `|` 把各节点的命名规则都写进表达式。例如：多数节点主网卡为 enp 开头，个别节点主网卡 virbr0 上，可填写为 `enp.*|virbr0`。 |
| 337 | 349 | ||
| @@ -353,11 +365,9 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 353 | 365 | ||
| 354 |  | 366 |  |
| 355 | 367 | ||
| 356 | -### 安装方式二（Kubernetes官方安装教程） | 368 | +--- |
| 357 | 369 | ||
| 358 | -参考 [Kubernetes 官网](https://kubernetes.io/zh-cn/docs/setup/) 进行安装。 | 370 | +### 创建集群 |
| 359 | - | ||
| 360 | -### 连接集群服务器 | ||
| 361 | 371 | ||
| 362 | 通过以下步骤将计算节点接入管理节点，从而形成集群。 | 372 | 通过以下步骤将计算节点接入管理节点，从而形成集群。 |
| 363 | 373 | ||
| @@ -399,6 +409,8 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 399 | >[!NOTE]说明 | 409 | >[!NOTE]说明 |
| 400 | >重复执行步骤2、3，直到所有计算节点加入管理节点。 | 410 | >重复执行步骤2、3，直到所有计算节点加入管理节点。 |
| 401 | 411 | ||
| 412 | +--- | ||
| 413 | + | ||
| 402 | ## MindCluster组件安装 | 414 | ## MindCluster组件安装 |
| 403 | 415 | ||
| 404 | 集群管理组件依赖MindCluster中的Ascend Docker Runtime、Ascend Device Plugin、ClusterD、Volcano和Infer Operator组件。其中，**管理节点需要安装全部组件，计算节点仅需要构建Ascend Device Plugin的镜像**。推荐安装26.0.0及之后的版本。 | 416 | 集群管理组件依赖MindCluster中的Ascend Docker Runtime、Ascend Device Plugin、ClusterD、Volcano和Infer Operator组件。其中，**管理节点需要安装全部组件，计算节点仅需要构建Ascend Device Plugin的镜像**。推荐安装26.0.0及之后的版本。 |
| @@ -416,6 +428,8 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 416 | 5. 请参考《MindCluster 集群调度用户指南》的[infer_Operator](https://gitcode.com/Ascend/mind-cluster/blob/branch_v26.0.0/docs/zh/scheduling/installation_guide/03_installation/manual_installation/07_infer_operator.md)章节安装Infer Operator。 | 428 | 5. 请参考《MindCluster 集群调度用户指南》的[infer_Operator](https://gitcode.com/Ascend/mind-cluster/blob/branch_v26.0.0/docs/zh/scheduling/installation_guide/03_installation/manual_installation/07_infer_operator.md)章节安装Infer Operator。 |
| 417 | 6. 请参考《MindCluster 集群调度用户指南》的[ClusterD](https://gitcode.com/Ascend/mind-cluster/blob/branch_v26.0.0/docs/zh/scheduling/installation_guide/03_installation/manual_installation/06_clusterd.md)章节安装ClusterD。 | 429 | 6. 请参考《MindCluster 集群调度用户指南》的[ClusterD](https://gitcode.com/Ascend/mind-cluster/blob/branch_v26.0.0/docs/zh/scheduling/installation_guide/03_installation/manual_installation/06_clusterd.md)章节安装ClusterD。 |
| 418 | 430 | ||
| 431 | +--- | ||
| 432 | + | ||
| 419 | ## 设置节点标签 | 433 | ## 设置节点标签 |
| 420 | 434 | ||
| 421 | 根据服务器类型，在管理节点执行以下操作，为集群统一设置标签 | 435 | 根据服务器类型，在管理节点执行以下操作，为集群统一设置标签 |
| @@ -442,11 +456,11 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 442 | for i in $workers; | 456 | for i in $workers; |
| 443 | do | 457 | do |
| 444 | kubectl label nodes $i node-role.kubernetes.io/worker=worker --overwrite=true | 458 | kubectl label nodes $i node-role.kubernetes.io/worker=worker --overwrite=true |
| 445 | - kubectl label nodes $i workerselector=dls-worker-node --overwrite=true | 459 | + kubectl label nodes $i workerselector=dls-worker-node --overwrite=true |
| 446 | - kubectl label nodes $i host-arch=huawei-arm --overwrite=true | 460 | + kubectl label nodes $i host-arch=huawei-arm --overwrite=true |
| 447 | - kubectl label nodes $i accelerator=huawei-Ascend910 --overwrite=true | 461 | + kubectl label nodes $i accelerator=huawei-Ascend910 --overwrite=true |
| 448 | - kubectl label nodes $i accelerator-type=module-910b-8 --overwrite=true | 462 | + kubectl label nodes $i accelerator-type=module-910b-8 --overwrite=true |
| 449 | - kubectl label nodes $i nodeDEnable=on --overwrite=true | 463 | + kubectl label nodes $i nodeDEnable=on --overwrite=true |
| 450 | done | 464 | done |
| 451 | ``` | 465 | ``` |
| 452 | 466 | ||
| @@ -472,10 +486,10 @@ MindIE PyMotor 依赖 Kubernetes 提供的容器编排能力，包括 Pod 部署 | |||
| 472 | for i in $workers; | 486 | for i in $workers; |
| 473 | do | 487 | do |
| 474 | kubectl label nodes $i node-role.kubernetes.io/worker=worker --overwrite=true | 488 | kubectl label nodes $i node-role.kubernetes.io/worker=worker --overwrite=true |
| 475 | - kubectl label nodes $i workerselector=dls-worker-node --overwrite=true | 489 | + kubectl label nodes $i workerselector=dls-worker-node --overwrite=true |
| 476 | - kubectl label nodes $i host-arch=huawei-arm --overwrite=true | 490 | + kubectl label nodes $i host-arch=huawei-arm --overwrite=true |
| 477 | - kubectl label nodes $i accelerator=huawei-Ascend910 --overwrite=true | 491 | + kubectl label nodes $i accelerator=huawei-Ascend910 --overwrite=true |
| 478 | - kubectl label nodes $i accelerator-type=module-a3-16 --overwrite=true | 492 | + kubectl label nodes $i accelerator-type=module-a3-16 --overwrite=true |
| 479 | - kubectl label nodes $i nodeDEnable=on --overwrite=true | 493 | + kubectl label nodes $i nodeDEnable=on --overwrite=true |
| 480 | done | 494 | done |
| 481 | ``` | 495 | ``` |
| @@ -0,0 +1,22 @@ | |||
| 1 | +# PD分离说明 | ||
| 2 | + | ||
| 3 | +--- | ||
| 4 | + | ||
| 5 | +## 什么是PD分离？ | ||
| 6 | + | ||
| 7 | +**PD 分离**（Prefill & Decode 分离）将大语言模型推理的预填充（Prefill）与解码（Decode）两个阶段拆分到不同实例上运行，适用于对时延和吞吐要求较高的场景。通过 PD 分离可提高 NPU 利用率，减轻 Prefill 与 Decode 分时复用带来的相互干扰，在相同时延下提升整体吞吐。 | ||
| 8 | + | ||
| 9 | +两个推理阶段的含义如下： | ||
| 10 | + | ||
| 11 | +- **Prefill 阶段**：对输入 prompt 执行一次完整前向传播，生成初始隐藏状态（Hidden States），**计算密集型**；每个新输入序列都需执行一次 Prefill。 | ||
| 12 | +- **Decode 阶段**：基于 Prefill 结果逐步生成后续 token，每步仅计算最新 token 的激活与 attention，单步计算量较小，但需反复执行直至生成结束，**访存密集型**（以 KV Cache 等内存访问为主）。 | ||
| 13 | + | ||
| 14 | +本仓库采用**多机 PD 分离**部署方案：通过 K8s Service 为 Coordinator 暴露推理入口，使用多个 Deployment 分别部署 Controller（单 Pod）、Coordinator（单 Pod）以及 Server（P 实例与 D 实例各若干 Pod）。Controller 负责集群与实例管理，Coordinator 接收用户请求并调度至 P/D 实例，由 P 实例与 D 实例协同完成一次完整推理。 | ||
| 15 | + | ||
| 16 | +--- | ||
| 17 | + | ||
| 18 | +## PD 分离的主要优势有哪些？ | ||
| 19 | + | ||
| 20 | +- **资源利用更优**：Prefill 为计算密集型、Decode 为访存密集型，特性不同，分离部署可更充分利用 NPU 的计算与带宽资源。 | ||
| 21 | +- **吞吐能力提升**：Prefill 处理新请求的同时，Decode 可持续处理已有请求的解码，整体处理能力更高。 | ||
| 22 | +- **时延更可控**：两阶段分离可减少排队与等待，尤其在高并发场景下有助于降低时延。 | ||
| @@ -1,111 +1,67 @@ | |||
| 1 | # 快速入门 | 1 | # 快速入门 |
| 2 | 2 | ||
| 3 | -## 产品简介 | 3 | +本文档通过**简单快速**的部署案例（以Atlas 800I A2服务器、Qwen3-8B模型、P/D实例各一个的场景为例）指导开发者体验基于MindIE-Motor的PD分离服务部署流程。 |
| 4 | 4 | ||
| 5 | -MindIE PyMotor是面向通用大模型PD分离部署场景的推理服务化框架，通过开放、可扩展的推理服务化平台架构提供推理服务化能力，支持对接业界主流推理框架接口，满足大语言模型的高性能推理需求。 | 5 | +如果详细的PD分离部署指导，请参考[PD分离部署指导](./deployment/k8s/pd_disaggregation_deployment.md)。 |
| 6 | 6 | ||
| 7 | -## 关键特性 | 7 | +--- |
| 8 | 8 | ||
| 9 | -| 特性 | 说明 | | 9 | +## 什么是PD分离？ |
| 10 | -| ------------ | ----------------- | | ||
| 11 | -| **PD分离部署** | 模型推理的Prefill阶段和Decode阶段分别实例化部署在不同的机器资源上同时进行推理，提升推理性能，其特性介绍详情请参见[PD分离部署](https://gitcode.com/Ascend/MindIE-Motor/blob/master/docs/zh/user_guide/service_deployment/pd_separation_service_deployment.md)。 | | ||
| 12 | 10 | ||
| 13 | -## 快速开始 | 11 | +模型推理的Prefill阶段和Decode阶段分别实例化部署在不同的硬件资源上进行推理，提升推理性能，其特性介绍详情请参见[PD分离部署](./features/pd_disaggregation.md)。 |
| 14 | 12 | ||
| 15 | -### 环境准备 | 13 | +--- |
| 16 | 14 | ||
| 17 | -本文档以Atlas 800I A2 推理服务器和Qwen3-8B模型为例，让开发者快速开始使用MindIE PyMotor进行大模型PD分离部署和推理流程。 | 15 | +## 环境要求 |
| 18 | 16 | ||
| 19 | -#### 前提条件 | 17 | +- 支持Atlas 800I A2或者Atlas 800 A3 超节点服务器。 |
| 20 | 18 | ||
| 21 | -物理机部署场景，需要在物理机安装NPU驱动固件以及部署Docker，执行如下步骤判断是否已安装NPU驱动固件、K8s集群和部署Docker。 | 19 | +- 至少需要1台已完成[环境准备](./environment_preparation.md)的服务器。 |
| 22 | 20 | ||
| 23 | -- 执行以下命令查看NPU驱动固件是否安装。 | 21 | +--- |
| 24 | 22 | ||
| 25 | - ```bash | 23 | +## 模型下载 |
| 26 | - npu-smi info | ||
| 27 | - ``` | ||
| 28 | 24 | ||
| 29 | - **图1** 回显信息 | 25 | +请自行下载Qwen3-8B模型的权重文件并将权重文件上传至服务器任意目录（以`/mnt/weight`为例）。执行以下命令，修改文件权限： |
 | |||
| 30 | - | ||
| 31 | -  | ||
| 32 | - | ||
| 33 | - **表1** Atlas A2 推理系列产品 | ||
| 34 | - | ||
| 35 | - | 产品型号 | 参考文档 | | ||
| 36 | - | --- | --- | | ||
| 37 | - | Atlas 800I A2 | 《Atlas A2 中心推理和训练硬件 24.1.0 NPU驱动和固件安装指南》中的“[物理机安装与卸载](https://support.huawei.com/enterprise/zh/doc/EDOC1100438838/b1977c97)”章节 | | ||
| 38 | - | ||
| 39 | -- 执行以下命令查看K8s集群是否就绪。 | ||
| 40 | - | ||
| 41 | - ```bash | ||
| 42 | - kubectl get node -A | ||
| 43 | - ``` | ||
| 44 | - | ||
| 45 | - 回显以下信息表示K8s集群已就绪。 | ||
| 46 | - | ||
| 47 | - ```bash | ||
| 48 | - NAME STATUS ROLES AGE VERSION | ||
| 49 | - ``` | ||
| 50 | - | ||
| 51 | -- 执行以下命令查看Docker是否已安装并启动。 | ||
| 52 | - | ||
| 53 | - ```bash | ||
| 54 | - docker ps | ||
| 55 | - ``` | ||
| 56 | - | ||
| 57 | - 回显以下信息表示Docker已安装并启动。 | ||
| 58 | - | ||
| 59 | - ```bash | ||
| 60 | - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES | ||
| 61 | - ``` | ||
| 62 | - | ||
| 63 | -#### 获取模型权重 | ||
| 64 | - | ||
| 65 | -1. 请先下载权重，这里以Qwen3-8B为例，请到官方下载权重文件并将权重文件上传至服务器任意目录（如`/mnt/weight`）。 | ||
| 66 | -2. 执行以下命令，修改权重文件权限： | ||
| 67 | 26 | ||
| 68 | ```bash | 27 | ```bash |
| 69 | chmod -R 755 /mnt/weight | 28 | chmod -R 755 /mnt/weight |
| 70 | ``` | 29 | ``` |
| 71 | 30 | ||
| 72 | -#### 获取容器镜像 | 31 | +--- |
| 73 | 32 | ||
| 74 | -进入[昇腾官方镜像仓库](https://www.hiascend.com/developer/ascendhub)，根据设备型号选择下载对应的PyMotor镜像。 | 33 | +## 镜像准备 |
| 75 | 34 | ||
| 76 | -该镜像已具备模型运行所需的基础环境。 | 35 | +进入[昇腾官方镜像仓库](https://www.hiascend.com/developer/ascendhub)，在搜索框查询 `motor`，进入搜索结果后根据设备型号下载对应的MindIE-Motor镜像。 |
| 77 | 36 | ||
| 78 | -### PD分离部署 | 37 | +--- |
| 79 | 38 | ||
| 80 | -> [!NOTE]部署方式说明 | 39 | +## 服务部署 |
| 81 | -> 当前默认采用 **CRD 方式**（基于 MindCluster 的 PD 分离 CRD 与 Operator）进行部署。该方式尚未完成 RAS 能力与池化能力的适配验证。若您需要 RAS（可靠性、可用性、可服务性）或 KV 池化能力，可在 `user_config.json` 的 `motor_deploy_config.deploy_mode` 中配置为 `multi_deployment`，切换为原有的多 YAML Deployment 方式。完整部署说明请参考 [PD 分离服务部署](./deployment/k8s/pd_disaggregation_deployment.md)。 | ||
| 82 | 40 | ||
| 83 | -1. **将 examples 目录准备并上传至 K8s 集群的 master 服务器上**。 | 41 | +1. **准备服务启动脚本**。 |
| 84 | 42 | ||
| 85 | - - **（方式一）从本代码仓获取**：将仓库根目录下的 `examples` 目录上传至 master 服务器。 | 43 | + MindIE-Motor官方完整镜像内已保存服务启动脚本（`/tmp/motor/examples`），可通过以下命令将镜像内的文件拷贝至宿主机。 |
| 86 | 44 | ||
| 87 | - - **（方式二）从容器镜像获取**：若无完整代码仓，但已拉取PyMotor推理镜像，可使用镜像内预置的示例目录，路径为 **`/tmp/motor/examples`**（目录结构与仓库中的 `examples/` 一致）。在已拉取镜像的机器上执行（将 `IMAGE` 替换为实际镜像名或镜像 ID，可与 `user_config.json` 中 `motor_deploy_config.image_name` 保持一致）： | 45 | + ```bash |
| 46 | + IMAGE="<镜像名或镜像ID>" | ||
| 88 | 47 | ||
| 89 | - ```bash | 48 | + cid=$(docker create "$IMAGE") |
| 90 | - IMAGE="<镜像名或镜像ID>" | 49 | + docker cp "$cid:/tmp/motor/examples" ./examples |
| 50 | + docker rm "$cid" | ||
| 51 | + ``` | ||
| 91 | 52 | ||
| 92 | - cid=$(docker create "$IMAGE") | 53 | + 请将上述脚本目录（examples目录）上传至**k8s集群的管理节点（master节点），后续部署操作均在管理节点执行**。 |
| 93 | - docker cp "$cid:/tmp/motor/examples" ./examples | ||
| 94 | - docker rm "$cid" | ||
| 95 | - ``` | ||
| 96 | - | ||
| 97 | - 将得到的 `examples` 目录按**方式一**的方式上传至 master 服务器。若使用 Podman，将命令中的 `docker` 替换为 `podman` 即可。 | ||
| 98 | 54 | ||
| 99 | 2. **配置服务化参数**。 | 55 | 2. **配置服务化参数**。 |
| 100 | 56 | ||
| 101 | - - 打开 `examples/infer_engines/vllm/user_config.json` 文件（或 `examples/infer_engines/vllm/models/` 下对应模型配置，如 `examples/infer_engines/vllm/models/deepseek/v3_1/user_config.json`，以实际使用的为准） | 57 | + 在管理节点执行以下命令，进入服务启动脚本所在目录并修改配置文件。 |
| 102 | 58 | ||
| 103 | ```bash | 59 | ```bash |
| 104 | - cd examples/infer_engines/vllm | 60 | + cd examples/deployer/ |
| 105 | - vim user_config.json | 61 | + vim ../infer_engines/vllm/user_config.json |
| 106 | ``` | 62 | ``` |
| 107 | 63 | ||
| 108 | - - 根据实际情况修改`user_config.json`中的配置参数。（以下以Qwen3-8B为例） | 64 | + user_config.json文件**完整示例**如下（可直接复制使用，4项xxxxxx内容需用户自行修改，如需了解各字段含义可参考 [user_config 全量参数说明](./deployment/k8s/config_reference.md)。）： |
| 109 | 65 | ||
| 110 | ```json | 66 | ```json |
| 111 | { | 67 | { |
| @@ -117,9 +73,9 @@ MindIE PyMotor是面向通用大模型PD分离部署场景的推理服务化框 | |||
| 117 | "single_d_instance_pod_num": 1, | 73 | "single_d_instance_pod_num": 1, |
| 118 | "p_pod_npu_num": 4, | 74 | "p_pod_npu_num": 4, |
| 119 | "d_pod_npu_num": 4, | 75 | "d_pod_npu_num": 4, |
| 120 | - "image_name": "", | 76 | + "image_name": "xxxxxxx 镜像名称。例如：mindie-motor-vllm:dev-26.1.0.B050-800I-A2-py311-Ubuntu24.04-lts-aarch64", |
| 121 | "job_id": "mindie-motor", | 77 | "job_id": "mindie-motor", |
| 122 | - "hardware_type": "800I_A3", | 78 | + "hardware_type": "xxxxxx 硬件类型。A2：800I_A2 A3：800I_A3", |
| 123 | "weight_mount_path": "/mnt/weight/" | 79 | "weight_mount_path": "/mnt/weight/" |
| 124 | }, | 80 | }, |
| 125 | "motor_controller_config": {}, | 81 | "motor_controller_config": {}, |
| @@ -129,13 +85,13 @@ MindIE PyMotor是面向通用大模型PD分离部署场景的推理服务化框 | |||
| 129 | "motor_nodemanger_config": {}, | 85 | "motor_nodemanger_config": {}, |
| 130 | "engine_config": { | 86 | "engine_config": { |
| 131 | "served_model_name": "qwen3-8B", | 87 | "served_model_name": "qwen3-8B", |
| 132 | - "model": "/mnt/weight/qwen3_8B", | 88 | + "model": "xxxxxx。权重文件路径。例如：/mnt/weight/qwen3_8B", |
| 133 | "gpu_memory_utilization": 0.9, | 89 | "gpu_memory_utilization": 0.9, |
| 134 | "data_parallel_size": 1, | 90 | "data_parallel_size": 1, |
| 135 | - "tensor_parallel_size": 4, | 91 | + "tensor_parallel_size": 2, |
| 136 | "pipeline_parallel_size": 1, | 92 | "pipeline_parallel_size": 1, |
| 137 | - "enable_expert_parallel": false, | ||
| 138 | "data_parallel_rpc_port": 9000, | 93 | "data_parallel_rpc_port": 9000, |
| 94 | + "enable_expert_parallel": false, | ||
| 139 | "enforce-eager": true, | 95 | "enforce-eager": true, |
| 140 | "max_model_len": 2048, | 96 | "max_model_len": 2048, |
| 141 | "kv_transfer_config": { | 97 | "kv_transfer_config": { |
| @@ -155,13 +111,13 @@ MindIE PyMotor是面向通用大模型PD分离部署场景的推理服务化框 | |||
| 155 | "motor_nodemanger_config": {}, | 111 | "motor_nodemanger_config": {}, |
| 156 | "engine_config": { | 112 | "engine_config": { |
| 157 | "served_model_name": "qwen3-8B", | 113 | "served_model_name": "qwen3-8B", |
| 158 | - "model": "/mnt/weight/qwen3_8B", | 114 | + "model": "xxxxxx。权重文件路径。例如：/mnt/weight/qwen3_8B", |
| 159 | "gpu_memory_utilization": 0.9, | 115 | "gpu_memory_utilization": 0.9, |
| 160 | "data_parallel_size": 1, | 116 | "data_parallel_size": 1, |
| 161 | - "tensor_parallel_size": 4, | 117 | + "tensor_parallel_size": 2, |
| 162 | "pipeline_parallel_size": 1, | 118 | "pipeline_parallel_size": 1, |
| 163 | - "enable_expert_parallel": false, | ||
| 164 | "data_parallel_rpc_port": 9000, | 119 | "data_parallel_rpc_port": 9000, |
| 120 | + "enable_expert_parallel": false, | ||
| 165 | "max_model_len": 2048, | 121 | "max_model_len": 2048, |
| 166 | "kv_transfer_config": { | 122 | "kv_transfer_config": { |
| 167 | "kv_connector": "MooncakeLayerwiseConnector", | 123 | "kv_connector": "MooncakeLayerwiseConnector", |
| @@ -178,116 +134,109 @@ MindIE PyMotor是面向通用大模型PD分离部署场景的推理服务化框 | |||
| 178 | } | 134 | } |
| 179 | ``` | 135 | ``` |
| 180 | 136 | ||
| 181 | - 如上的参数说明如下： | 137 | +3. **配置环境变量**。 |
| 182 | 138 | ||
| 183 | - | 配置项 | 取值类型 | 取值范围 | 配置说明 | | 139 | + 执行以下命令修改环境变量配置文件。 |
| 184 | - | --- | --- | --- | --- | | ||
| 185 | - | version | string | v2.0 | 配置文件版本 | | ||
| 186 | - | p_instances_num | int | ≥1 | P实例个数 | | ||
| 187 | - | d_instances_num | int | ≥1 | D实例个数 | | ||
| 188 | - | single_p_instance_pod_num | int | ≥1 | 单个P实例所占pod容器个数 | | ||
| 189 | - | single_d_instance_pod_num | int | ≥1 | 单个D实例所占pod容器个数 | | ||
| 190 | - | p_pod_npu_num | int | ≥1 | 单个P节点pod容器所占用的NPU卡数 | | ||
| 191 | - | d_pod_npu_num | int | ≥1 | 单个D节点pod容器所占用的NPU卡数 | | ||
| 192 | - | image_name | string | 字符串 | docker加载的镜像名称，例如“vllm-ascend:b150_motor” | | ||
| 193 | - | job_id | string | 字符串 | PD分离部署任务名称，例如“mindie-pymotor” | | ||
| 194 | - | hardware_type | string | A2: 800I_A2<br>A3: 800I_A3<br>A5: 850-Atlas-8p-8 | 服务器硬件类型 | | ||
| 195 | - | weight_mount_path | string | 字符串 | 权重文件路径 | | ||
| 196 | - | motor_controller_config | dict | controller组件配置 | 在此处可以进行任意特定配置项的设置 | | ||
| 197 | - | motor_coordinator_config | dict | coordinator组件配置 | 在此处可以进行任意特定配置项的设置 | | ||
| 198 | - | engine_type | string | 字符串 | 对接的推理引擎类型，例如”vllm” | | ||
| 199 | - | motor_nodemanager_config | dict | nodemanager组件配置 | 在此处可以进行任意特定配置项的设置 | | ||
| 200 | - | served_model_name | string | 字符串 | 模型名称，例如”qwen3-8B” | | ||
| 201 | - | model | string | 文件路径 | 模型权重文件所在路径 | | ||
| 202 | - | gpu_memory_utilization | float | 0到1之间的小数 | NPU内存使用占比上限，例如”0.9” | | ||
| 203 | - | data_parallel_size | int | ≥1 | 数据并行参数 | | ||
| 204 | - | tensor_parallel_size | int | ≥1 | 张量并行参数 | | ||
| 205 | - | pipeline_parallel_size | int | ≥1 | 流水线并行参数 | | ||
| 206 | - | enable_expert_parallel | bool | [true, false] | 专家并行开关 | | ||
| 207 | - | data_parallel_rpc_port | int | 有效端口范围 | RPC通信的端口号 | | ||
| 208 | - | engine_config | dict | 推理引擎原生参数 | 与引擎 CLI 参数等价，直接以 JSON 键值填写（如 `tensor_parallel_size`、`enforce-eager`）；也可使用 [engine_config 命令行转换工具](operations/cli_to_engine_config_guide.md) 从命令行迁移 | | ||
| 209 | 140 | ||
| 210 | - - 配置 k8s 的 namespace，配置 namespace 值为 `user_config.json` 中的 `job_id`。 | 141 | + ```bash |
| 142 | + vim ../infer_engines/vllm/env.json | ||
| 143 | + ``` | ||
| 144 | + | ||
| 145 | + env.json文件**完整示例**如下（可直接复制使用）： | ||
| 146 | + | ||
| 147 | + ```bash | ||
| 148 | + { | ||
| 149 | + "version": "2.0.0", | ||
| 150 | + "motor_common_env": { | ||
| 151 | + "CANN_INSTALL_PATH": "/usr/local/Ascend", | ||
| 152 | + "MOTOR_LOG_ROOT_PATH": "/root/ascend/log" | ||
| 153 | + }, | ||
| 154 | + "motor_controller_env": {}, | ||
| 155 | + "motor_coordinator_env": {}, | ||
| 156 | + "motor_engine_prefill_env": { | ||
| 157 | + "HCCL_BUFFSIZE": 200, | ||
| 158 | + "PYTORCH_NPU_ALLOC_CONF": "expandable_segments:True", | ||
| 159 | + "HCCL_OP_EXPANSION_MODE": "AIV", | ||
| 160 | + "OMP_PROC_BIND": "false", | ||
| 161 | + "OMP_NUM_THREADS": 100, | ||
| 162 | + "ASCEND_BUFFER_POOL": "0:0" | ||
| 163 | + }, | ||
| 164 | + "motor_engine_decode_env": { | ||
| 165 | + "HCCL_BUFFSIZE": 200, | ||
| 166 | + "PYTORCH_NPU_ALLOC_CONF": "expandable_segments:True", | ||
| 167 | + "HCCL_OP_EXPANSION_MODE": "AIV", | ||
| 168 | + "OMP_PROC_BIND": "false", | ||
| 169 | + "OMP_NUM_THREADS": 100, | ||
| 170 | + "ASCEND_BUFFER_POOL": "0:0" | ||
| 171 | + }, | ||
| 172 | + "motor_kv_cache_pool_env": {}, | ||
| 173 | + "motor_kv_conductor_env": {} | ||
| 174 | + } | ||
| 175 | + ``` | ||
| 176 | + | ||
| 177 | +4. **启动与终止服务** | ||
句末符号   | |||
| 178 | + | ||
| 179 | + 创建命名空间（namespace），namespace 的值必须与 `user_config.json` 中的 `job_id`字段相同（默认值为mindie-motor）。 | ||
| 211 | 180 | ||
| 212 | ```bash | 181 | ```bash |
| 213 | kubectl create ns mindie-motor | 182 | kubectl create ns mindie-motor |
| 214 | ``` | 183 | ``` |
| 215 | 184 | ||
| 216 | -3. **配置环境变量**。 | 185 | + 执行以下命令，部署PD分离服务： |
| 217 | - | ||
| 218 | - - 打开 `examples/infer_engines/vllm/env.json` 文件 | ||
| 219 | - | ||
| 220 | - ```bash | ||
| 221 | - cd examples/infer_engines/vllm | ||
| 222 | - vim env.json | ||
| 223 | - ``` | ||
| 224 | - | ||
| 225 | - - 根据实际情况修改`env.json`中的配置参数。 | ||
| 226 | - | ||
| 227 | - ```bash | ||
| 228 | - { | ||
| 229 | - "version": "2.0.0", | ||
| 230 | - "motor_common_env": { | ||
| 231 | - "CANN_INSTALL_PATH": "/usr/local/Ascend" | ||
| 232 | - }, | ||
| 233 | - "motor_controller_env": {}, | ||
| 234 | - "motor_coordinator_env": {}, | ||
| 235 | - "motor_engine_prefill_env": {}, | ||
| 236 | - "motor_engine_decode_env": {} | ||
| 237 | - } | ||
| 238 | - ``` | ||
| 239 | - | ||
| 240 | -4. **启动服务** | ||
| 241 | - | ||
| 242 | - 在 `examples/deployer` 目录下执行，支持两种指定配置的方式： | ||
| 243 | - | ||
| 244 | - **方式一：指定配置目录（推荐）**，目录下需包含 `user_config.json` 和 `env.json`： | ||
| 245 | 186 | ||
| 246 | ```bash | 187 | ```bash |
| 247 | - cd examples/deployer | ||
| 248 | python3 deploy.py --config_dir ../infer_engines/vllm | 188 | python3 deploy.py --config_dir ../infer_engines/vllm |
| 249 | ``` | 189 | ``` |
| 250 | 190 | ||
| 251 | - **方式二：单独指定配置文件路径**，`--user_config_path` 与 `--env_config_path` 必须同时指定： | 191 | + 需要终止服务时，执行以下命令即可： |
| 252 | 192 | ||
| 253 | ```bash | 193 | ```bash |
| 254 | - cd examples/deployer | 194 | + bash delete.sh 命名空间(填入手动创建的命名空间名称，例如：mindie-motor) |
| 255 | - python3 deploy.py --user_config_path ../infer_engines/vllm/user_config.json --env_config_path ../infer_engines/vllm/env.json | ||
| 256 | ``` | 195 | ``` |
| 257 | 196 | ||
| 258 | - 也可使用简写 `--config` 和 `--env`。 | 197 | +5. **查看日志**。 |
| 259 | 198 | ||
| 260 | -5. **发送请求** | 199 | + 执行 `vim log_collect/log_config.ini` 命令，将 `name_space` 填写为命名空间名称（例如：mindie-motor），然后执行以下命令收集日志： |
| 261 | - | ||
| 262 | - 执行以下命令： | ||
| 263 | 200 | ||
| 264 | ```bash | 201 | ```bash |
| 265 | - curl -X POST http://127.0.0.1:31015/v1/chat/completions \ | 202 | + bash show_log.sh |
| 266 | - -H "Content-Type: application/json" \ | ||
| 267 | - -d '{ | ||
| 268 | - "model": "qwen3-8B", | ||
| 269 | - "messages": [ | ||
| 270 | - { | ||
| 271 | - "role": "system", | ||
| 272 | - "content": "You are a helpful assistant." | ||
| 273 | - }, | ||
| 274 | - { | ||
| 275 | - "role": "user", | ||
| 276 | - "content": "who are you?" | ||
| 277 | - } | ||
| 278 | - ], | ||
| 279 | - "max_tokens":36, | ||
| 280 | - "stream":true | ||
| 281 | - }' | ||
| 282 | ``` | 203 | ``` |
| 283 | 204 | ||
| 284 | - 返回结果如果如下，则说明尚未启动就绪： | 205 | + 所有业务日志（controller、coordinator、P/D实例）均会保存于 `examples/deployer/log_collect/log`目录下，并持续刷新，直到服务被终止。 |
| 206 | + | ||
| 207 | +--- | ||
| 208 | + | ||
| 209 | +## 推理验证 | ||
| 210 | + | ||
| 211 | +新建一个命令行窗口，在k8s集群的管理节点（master节点）执行以下命令： | ||
| 212 | + | ||
| 213 | +```bash | ||
| 214 | + curl -X POST http://127.0.0.1:31015/v1/chat/completions \ | ||
| 215 | + -H "Content-Type: application/json" \ | ||
| 216 | + -d '{ | ||
| 217 | + "model": "qwen3-8B", | ||
| 218 | + "messages": [ | ||
| 219 | + { | ||
| 220 | + "role": "system", | ||
| 221 | + "content": "You are a helpful assistant." | ||
| 222 | + }, | ||
| 223 | + { | ||
| 224 | + "role": "user", | ||
| 225 | + "content": "who are you?" | ||
| 226 | + } | ||
| 227 | + ], | ||
| 228 | + "max_tokens":36, | ||
| 229 | + "stream":true | ||
| 230 | + }' | ||
| 231 | +``` | ||
| 232 | + | ||
| 233 | +返回结果如果如下，则说明尚未启动就绪： | ||
| 285 | 234 | ||
| 286 | ```json | 235 | ```json |
| 287 | {"detail":"Service is not available"} | 236 | {"detail":"Service is not available"} |
| 288 | ``` | 237 | ``` |
| 289 | 238 | ||
| 290 | - 等待一段时间后再次尝试。回显类似如下内容说明推理服务已就绪 | 239 | +等待一段时间后再次尝试。回显类似如下内容说明推理服务已就绪： |
| 291 | 240 | ||
| 292 | ```json | 241 | ```json |
| 293 | data: {"id":"17658563046856100000c836403d","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"prompt_token_ids":null} | 242 | data: {"id":"17658563046856100000c836403d","object":"chat.completion.chunk","created":1765856304,"model":"qwen3","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"prompt_token_ids":null} |
是否有必要提供模型权重下载地址，以及其他模型在哪下载？