vNPU ​

特性介绍 ​

vNPU是构建在容器平台之上的昇腾NPU算力切分和动态调度能力组件。它支持多个容器共享同一NPU设备的同时，具备显存和AI Core资源的隔离能力，从而显著提升NPU资源利用率。通过提供多样化调度策略、多样化算力切分模式、可观测等能力，打造一体化极简易用的昇腾NPU算力接入和纳管方案。

当用户在Kubernetes集群中运行AI训练/推理负载、希望以更细粒度共享昂贵的昇腾NPU资源、并要求按容器隔离显存与算力配额时，可使用vNPU特性。

应用场景 ​

• 多租户推理服务：同一张昇腾NPU卡上并发承载多个推理服务实例，每个实例按需申请显存和AI Core配额，降低单实例成本。
• AI开发环境共享：多名算法工程师在同一物理卡上各占一份vNPU作为开发调试环境，互不影响显存使用。
• 训练与推理混部：同一节点上同时承载训练和推理任务，通过调度策略（binpack/spread）控制Pod在节点和设备上的分布，平衡资源利用率与故障隔离。
• 资源精细化运营：通过xpu-exporter对接Prometheus采集vNPU使用率、Pod数量等指标，支撑容量规划和成本核算。

能力范围 ​

• 算力切分：支持软切分（CANN Runtime API劫持的用户态虚拟化）和硬切分（基于昇腾HDK的虚拟化）两种模式，可按节点粒度配置。
  • 软切分：单张物理NPU最多切分为20个vNPU实例，AI Core切分粒度最小1%，显存切分粒度最小1Gi；AI Core与显存隔离（显存严格隔离，AI Core为时分复用，波动小于整卡的10%）；支持只限制显存不限制AI Core；支持固定配额、弹性、争抢三种AI Core调度策略；性能损耗小于5%。
  • 硬切分：基于昇腾HDK将NPU切分为多份vNPU挂载到容器中使用。
• 集群调度：基于Volcano扩展NPU资源调度插件，支持资源共享调度、binpack/spread调度、整卡调度，以及基于DRA的调度。允许同一节点上部分容器使用整卡、部分容器共享一张卡。
• 可观测：xpu-exporter采集vNPU切分模式、调度策略、显存使用率、vNPU数量、Pod数量等指标，对接Prometheus。

亮点特征 ​

• 软切分细粒度：AI Core切分粒度最小1%、显存切分粒度最小1Gi，业界同等方案中切分粒度更细。
• 软切分性能损耗低：性能损耗小于5%，接近裸卡算力。
• AI Core调度策略丰富：固定配额、弹性、争抢三种策略，弹性策略通过时间片借用机制提升整卡利用率。
• 调度策略灵活：节点级与设备级分别支持binpack/spread，适配不同负载特征。
• 整卡与切分混部：同一节点同时支持整卡容器与共享容器，无需独立集群。

基本概念 ​

• 软切分（Soft）：基于CANN Runtime API劫持的用户态虚拟化方案。AI Core为时分复用，非严格隔离；显存严格隔离。
• 硬切分（Hard）：基于昇腾HDK的虚拟化方案，将物理NPU切分为多份vNPU挂载到容器中使用。
• vNPU：虚拟NPU，由一张物理NPU切分得到的逻辑单元，业务Pod通过huawei.com/vnpu-number等资源声明申请使用。
• dieID：NPU设备的唯一标识，用于精确指定Pod落位到某张物理卡。
• AI Core调度策略：软切分场景下AI Core时间片的分配方式，包括固定配额（fixed-share）、弹性（elastic）、争抢（best-effort）三种。
• 节点级调度策略（huawei.com/vnpu-pod-node-scheduler-policy）：控制Pod在节点间的分布，binpack紧凑调度，spread打散调度。
• 设备级调度策略（huawei.com/vnpu-pod-device-scheduler-policy）：控制vNPU在单节点NPU设备间的分布，binpack紧凑调度，spread打散调度。

实现原理 ​

vNPU由四个核心组件协作完成NPU资源的发现、调度、挂载与监控，整体工作流程如下：

1. xpu-device-plugin：通过Kubernetes Device Plugin机制向kubelet上报节点上的NPU设备及可切分资源（注册到huawei.com/vnpu-*资源），并向节点注解huawei.com/node-vnpu-register写入设备详情（dieID、芯片类型等字段）。
2. volcano-xpu-plugin：扩展Volcano调度器，在Pod调度阶段根据Pod声明的huawei.com/vnpu-*资源量、切分模式、调度策略，从候选节点的可用vNPU中筛选合适的节点和设备，完成过滤和打分。
3. client_update：在节点侧部署软切分劫持库，业务Pod启动时由device plugin挂载劫持库到容器内，实现AI Core和显存的隔离限制。
4. xpu-exporter：持续采集vNPU运行时指标（切分模式、显存利用率、vNPU数量等），通过Prometheus暴露供监控。

Pod调度关键时机：

• Pod声明spec.schedulerName: volcano后，调度由Volcano接管。
• Volcano调用vxpu plugin执行NPU资源过滤与打分，选定节点与设备。
• Pod绑定到节点后，device plugin根据调度结果通过Allocate回调向容器挂载设备文件和劫持库。
• Pod启动业务进程时，劫持库接管CANN Runtime调用，按声明配额执行AI Core时间片调度和显存隔离。

与相关特性的关系 ​

• Volcano：vNPU调度依赖Volcano 1.15.0作为调度器底座，通过Volcano的扩展插件机制接入NPU资源调度。业务Pod必须显式声明spec.schedulerName: volcano。
• Ascend Docker Runtime：用于容器内挂载NPU设备，vNPU要求节点已部署Ascend Docker Runtime（建议7.2.RC1+版本）。
• 昇腾HDK驱动：NPU硬件驱动，软切分和硬切分均依赖。硬切分依赖HDK提供的设备切分能力；支持的芯片型号及HDK版本配套关系详见附录-支持的NPU型号。
• 昇腾MindCluster NPU Exporter：用于采集NPU整卡指标，vNPU的xpu-exporter仅采集vNPU切分维度指标，二者互补。
• npu-dra-plugin：vNPU提供基于DRA的调度作为Volcano调度路径的可选替代。

相关实例 ​

业务Pod使用样例请参见本文档使用vNPU-配置样例小节。更多示例与Demo工程请参考vNPU仓库。

安装 ​

前提条件 ​

• 已准备Kubernetes集群。
• 已以root用户在节点上安装昇腾HDK驱动（支持的芯片型号及HDK版本配套关系详见附录-支持的NPU型号）。
• 已部署Ascend Docker Runtime，建议使用7.2.RC1+版本。以7.2.RC1版本为例，详细部署方式请参考昇腾官方文档。
• 编译机已安装以下工具：
  • git
  • docker > 20.10
  • helm

开始安装 ​

编译构建 ​

1. 下载源码并初始化子模块。

   shell

   git clone https://gitcode.com/openFuyao/vNPU.git
   cd vNPU
   git submodule update --init --recursive

2. 进入ci目录执行构建脚本。

   shell

   cd vNPU/ci
   # 使用默认参数构建，镜像版本号默认为1.0.0
   sh build.sh
   # 指定镜像版本号为1.1.1
   sh build.sh 1.1.1

   构建产物输出在vNPU/output目录下。

在线部署 ​

1. 为需要部署vNPU组件的节点增加label。

   bash

   kubectl label node {nodename} huawei.com/vnpu=ready

2. 开启NPU设备共享模式。参考昇腾官方文档。对于910B芯片，HDK驱动25.5.0及以上版本才支持共享模式。例如，设置设备0所有芯片的容器共享模式为使能：

   bash

   npu-smi set -t device-share -i 0 -d 1

   注意：

   设备共享模式是后续Volcano调度和device plugin上报资源的前置条件，必须在部署vNPU组件前完成配置，否则Pod可能因节点未开启共享而调度失败。npu-smi命令中-i指定设备ID、-d指定共享模式（1为使能），请按实际设备替换。支持的芯片型号及HDK版本配套关系详见附录-支持的NPU型号。

3. 创建xpu Namespace。

   bash

   kubectl apply -f charts/yaml/namespace.yaml

4. 通过Helm Chart部署npu-client-update、npu-device-plugin、xpu-exporter。

   bash

   helm install vxpu oci://cr.openfuyao.cn/charts/vxpu --version 1.0.0

   说明：

   • oci://cr.openfuyao.cn/charts/vxpu会从远端OCI仓库直接拉取Chart；离线环境请改用本地tgz包，见离线部署小节。
   • --version需与实际发布的Chart版本号匹配，本文以1.0.0为例，请以vNPU仓库发布为准。

5. 在主机OS上创建Volcano日志目录并设置权限。Volcano容器以UID 1000运行，需赋予目录写权限。

   bash

   mkdir -p /var/log/volcano-{admission,controller,scheduler}
   chown -R 1000:1000 /var/log/volcano-{admission,controller,scheduler}

6. 通过charts/yaml/volcano-deployment.yaml部署Volcano。

   bash

   kubectl apply -f charts/yaml/volcano-deployment.yaml

离线部署 ​

1. 为需要部署vNPU组件的节点增加label。

   bash

   kubectl label node {nodename} huawei.com/vnpu=ready

2. 开启NPU设备共享模式。参考昇腾官方文档。对于910B芯片，HDK驱动25.5.0及以上版本才支持共享模式。例如，设置设备0所有芯片的容器共享模式为使能：

   bash

   npu-smi set -t device-share -i 0 -d 1

   注意：

   设备共享模式是后续Volcano调度和device plugin上报资源的前置条件，必须在部署vNPU组件前完成配置，否则Pod可能因节点未开启共享而调度失败。npu-smi命令中-i指定设备ID、-d指定共享模式（1为使能），请按实际设备替换。支持的芯片型号及HDK版本配套关系详见附录-支持的NPU型号。

3. 创建xpu Namespace。

   bash

   kubectl apply -f charts/yaml/namespace.yaml

4. 导入离线镜像包。以containerd本地镜像为例，镜像包名称请以实际为准。

   shell

   ctr -n k8s.io images import acl_client_update-1.0.0-aarch64.tar
   ctr -n k8s.io images import npu_device_plugin-1.0.0-aarch64.tar
   ctr -n k8s.io images import xpu_exporter-1.0.0-aarch64.tar
   ctr -n k8s.io images import vc_controller_manager-1.15.0-aarch64.tar
   ctr -n k8s.io images import vc_scheduler-1.15.0-aarch64.tar
   ctr -n k8s.io images import vc_webhook_manager-1.15.0-aarch64.tar

5. 通过Helm Chart部署npu-client-update、npu-device-plugin、xpu-exporter。

   bash

   helm upgrade --install vxpu vxpu-1.0.0.tgz -n xpu --wait

6. 在主机OS上创建Volcano日志目录并设置权限。Volcano容器以UID 1000运行，需赋予目录写权限。

   bash

   mkdir -p /var/log/volcano-{admission,controller,scheduler}
   chown -R 1000:1000 /var/log/volcano-{admission,controller,scheduler}

7. 通过charts/yaml/volcano-deployment.yaml部署Volcano。

   bash

   kubectl apply -f charts/yaml/volcano-deployment.yaml

使用vNPU ​

前提条件 ​

• Kubernetes集群已就绪。

• 节点已安装昇腾HDK驱动（支持的芯片型号及HDK版本配套关系详见附录-支持的NPU型号）。

• 已部署Ascend Docker Runtime（建议7.2.RC1+版本）。

• 已按安装章节完成vNPU组件部署，且节点已添加huawei.com/vnpu=ready标签。

• 业务Pod所在集群中Volcano可用，且spec.schedulerName设置为volcano。可通过以下命令确认Volcano组件运行状态：

  bash

  kubectl get deployment -n volcano-system
  kubectl get pod -n volcano-system

背景信息 ​

业务Pod只需声明所需的vNPU资源，无需修改业务代码。vNPU的调度器（volcano-xpu-plugin）和device plugin（xpu-device-plugin）负责自动调度Pod到合适的节点、合适的NPU设备上并挂载设备。Pod可通过注解配置切分模式（soft/hard）、AI CPU分配策略、软切分算力调度策略、节点级和设备级调度策略，以及精确指定dieID和NPU设备类型。

软切分AI Core调度策略对比如下。

表1 软切分AI Core调度策略对比

调度策略对比如下。

表2 调度策略对比

使用限制 ​

• 软切分：一个容器最多只能申请一个vNPU；一个容器只能有一个进程可以使用vNPU；只支持切分和限制AI Core及显存容量，不支持AI CPU、VPC、VDEC、JPEGD等核的切分控制；业务容器不允许为特权容器。
• 支持的NPU芯片型号：310P3、910B4（软切分+硬切分均支持）；910C暂不支持（详见附录-支持的NPU型号）。
• huawei.com/vnpu-number取值范围为1 ~ 单节点物理设备总数；大于1表示分配整卡；若为软/硬切分，则只能为1。
• huawei.com/vnpu-cores单位为1%；软切分fixed-share/elastic策略取值范围1~100，best-effort策略取值范围0~100；硬切分取值范围1~100；不配置则默认100。
• huawei.com/vnpu-memory.1Gi单位为1Gi；软切分不允许配置为0，不配置则默认使用单卡显存总量；硬切分无需配置。
• 910B芯片软/硬切分要求HDK驱动25.5.0及以上版本才支持共享模式。
• 业务Pod的spec.schedulerName必须为volcano。

注意：

• 业务容器不允许为特权容器，否则软切分劫持库无法生效，资源隔离失效。
• 软切分场景一个容器只允许一个进程使用vNPU，多进程并发使用同一vNPU可能导致AI Core时间片调度异常。
• huawei.com/vnpu-memory.1Gi在软切分模式下不允许配置为0，否则Pod调度失败。

配置说明 ​

Pod支持的全部注解与资源字段如下。

表3 Pod vNPU配置字段说明

查看节点注解huawei.com/node-vnpu-register中NPU设备详情（dieID、芯片类型等字段）的命令示例：

# 输出节点 vnpu-register 注解的完整内容
kubectl get node {nodename} -o jsonpath='{.metadata.annotations.huawei\.com/node-vnpu-register}'
# 输出字段之间以分号分隔，第2个字段为dieID，第5个字段为芯片类型

说明：

• resources.limits与resources.requests中相同字段的取值必须一致，否则kubelet校验失败。
• 软切分模式申请整卡（huawei.com/vnpu-number > 1）不被支持，请使用硬切分或显式声明huawei.com/vnpu-mode: "hard"。
• huawei.com/vnpu-use-npu-dieID与huawei.com/vnpu-use-npu-type配合使用可精确指定目标NPU；单独使用其中之一时，匹配维度仅限该字段。

配置样例 ​

样例1：软切分固定配额模式，声明1个vNPU、50%的AI Core、8Gi显存。

apiVersion: v1
kind: Pod
metadata:
  name: testpod
  annotations:
    huawei.com/vnpu-soft-scheduler-policy: "fixed-share"
spec:
  schedulerName: volcano
  containers:
  - name: test-container
    image: {业务镜像}
    resources:
      limits:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 50
        huawei.com/vnpu-memory.1Gi: 8
      requests:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 50
        huawei.com/vnpu-memory.1Gi: 8

样例2：软切分争抢模式，只限制显存为8Gi，不限制AI Core。

apiVersion: v1
kind: Pod
metadata:
  name: testpod
  annotations:
    huawei.com/vnpu-soft-scheduler-policy: "best-effort"
spec:
  schedulerName: volcano
  containers:
  - name: test-container
    image: {业务镜像}
    resources:
      limits:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 0
        huawei.com/vnpu-memory.1Gi: 8
      requests:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 0
        huawei.com/vnpu-memory.1Gi: 8

样例3：硬切分低配模式，申请50%的AI Core。

apiVersion: v1
kind: Pod
metadata:
  name: testpod
  annotations:
    huawei.com/vnpu-mode: "hard"
    huawei.com/vnpu-hard-aicpu-level: "low"
spec:
  schedulerName: volcano
  containers:
  - name: test-container
    image: {业务镜像}
    resources:
      limits:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 50  # AI Core百分比
      requests:
        huawei.com/vnpu-number: 1
        huawei.com/vnpu-cores: 50

样例4：声明使用两张整卡。

apiVersion: v1
kind: Pod
metadata:
  name: testpod
spec:
  schedulerName: volcano
  containers:
  - name: test-container
    image: {业务镜像}
    resources:
      limits:
        huawei.com/vnpu-number: 2
      requests:
        huawei.com/vnpu-number: 2

样例5：完整配置示例（同时设置切分模式、调度策略、指定dieID和设备类型）。

apiVersion: v1
kind: Pod
metadata:
  name: testpod
  annotations:
    huawei.com/vnpu-mode: "hard"                                                          # 切分模式
    huawei.com/vnpu-hard-aicpu-level: "low"                                               # 硬切分模式AI CPU分配策略
    huawei.com/vnpu-soft-scheduler-policy: "elastic"                                     # 软切分算力调度模式
    huawei.com/vnpu-pod-node-scheduler-policy: "spread"                                  # 节点级调度策略
    huawei.com/vnpu-pod-device-scheduler-policy: "binpack"                              # 设备级调度策略
    huawei.com/vnpu-use-npu-dieID: "37E96E64-20C10A5A-8C747124-6E78030A-BF003019"        # 指定NPU卡的dieID
    huawei.com/vnpu-use-npu-type: "NPU-ASCEND-310P3"                                      # 指定NPU设备类型
spec:
  schedulerName: volcano  # 指定调度器名称为volcano
  containers:
  - name: test-container
    image: {业务镜像}
    resources:
      limits:
        huawei.com/vnpu-number: 1        # 必选，vNPU数量
        huawei.com/vnpu-cores: 5        # 可选，容器可使用的aicore使用率
        huawei.com/vnpu-memory.1Gi: 8   # 可选，容器可使用的显存
      requests:
        huawei.com/vnpu-number: 1        # 和limits配置相同
        huawei.com/vnpu-cores: 5        # 和limits配置相同
        huawei.com/vnpu-memory.1Gi: 8   # 和limits配置相同

操作步骤 ​

1. 设置节点切分模式。

   vNPU支持软切分和硬切分两种模式，可按节点粒度设置切分模式。节点默认为软切分模式。通过Helm部署npu-device-plugin服务时可通过values.yaml或Helm命令行参数设置节点切分模式。

   • 方式一：在values.yaml中设置节点切分模式，然后通过Helm部署。

     yaml

     vnpuNodeMode:
       worker1:        # 节点名
         mode: "hard"  # 节点切分模式，hard|soft，默认为soft
       worker2:
         mode: "soft"

   • 方式二：通过Helm命令行参数设置。

     bash

     helm upgrade --install vxpu ./vxpu-1.0.0.tgz -n xpu --set vnpuNodeMode.worker1.mode="hard"

     说明：

     • 节点名（worker1）需与kubectl get nodes输出的节点名一致。
     • vnpuNodeMode未配置的节点默认使用软切分（soft）模式。
     • 同一节点切分模式不可与Pod注解huawei.com/vnpu-mode冲突，否则Pod调度失败。

2. 创建使用vNPU的Pod。

   业务Pod在spec.schedulerName指定为volcano后，通过resources.limits/resources.requests声明所需的vNPU数量、AI Core使用率、显存大小，通过metadata.annotations配置切分模式与调度策略。完整字段说明见配置说明，可用样例见配置样例。

后续操作 ​

• 部署完成后，通过kubectl get pod -n xpu查看npu-client-update、npu-device-plugin、xpu-exporter组件运行状态，确认DaemonSet就绪。
• 检查节点注解huawei.com/node-vnpu=ready是否存在，以及节点注解huawei.com/node-vnpu-register中是否已上报NPU设备详情（dieID、芯片类型等字段）。查看命令见配置说明小节。
• 如需对接监控系统，请参见vNPU指标监控小节配置Prometheus抓取xpu-exporter。
• 如需调整某节点的切分模式，通过Helm重新部署时设置vnpuNodeMode.<nodename>.mode即可，无需重建节点。切分模式变更仅对新调度到该节点的Pod生效，已运行Pod不受影响；如需让已运行Pod应用新的切分模式，请重启对应Pod。

相关操作 ​

xpu-exporter支持采集vNPU相关的监控指标，对接Prometheus实现对NPU资源的精细化监控。NPU整卡指标可安装昇腾MindCluster的NPU Exporter采集。vNPU支持采集的指标如下。

表4 vNPU监控指标

说明：

• 上述指标由xpu-exporter以Prometheus exposition格式暴露在/metrics端点，默认侦听端口请以部署Chart的values.yaml为准。
• NPU整卡指标（温度、功耗、整卡显存等）需另行安装昇腾MindCluster的NPU Exporter采集，与vNPU指标互补。
• xpu_vnpu_soft_scheduler_policy仅在软切分模式下有值，硬切分节点不暴露此指标。

通过kubectl describe node {nodename}查看节点上huawei.com/vnpu-*资源的Capacity/Allocatable，确认NPU切分资源已正确注册。节点注解huawei.com/node-vnpu-register中包含每张NPU卡的dieID、芯片类型等详情，Pod可通过huawei.com/vnpu-use-npu-dieID和huawei.com/vnpu-use-npu-type精确指定落位。查看节点注解的命令见配置说明小节。

附录 ​

代码结构 ​

• volcano-xpu-plugin：Volcano插件，实现NPU虚拟化资源调度。
• xpu-device-plugin：设备插件，实现NPU资源上报和分配。
• client_update：负责软切分劫持库的部署。
• xpu-exporter：负责vNPU指标的上报。
• ci：编译构建脚本。
• charts：vNPU组件部署相关的文件。

支持的NPU型号 ​

vNPU支持的NPU芯片型号及软件版本配套关系如下。

表5 支持的NPU型号及软件版本配套

说明：

以上芯片型号及软件版本配套已经过充分验证，不在此范围内的软硬件未经验证，可能存在兼容性问题。310P3与910B4芯片软/硬切分均要求HDK驱动25.5.0及以上版本才支持设备共享模式。

支持的Volcano版本 ​

当前支持Volcano 1.15.0版本，最新版本待规划。