跳到主要内容
Enterprise

华为昇腾(Huawei Ascend)

Ascend Device Plugin 将华为昇腾 NPU 注册为 Kubernetes 资源,由 HAMi 调度器选择设备。本文使用 Chart 0.4.0 和应用 v1.5.0 ,介绍与 HAMi 一起部署插件、配置切分模式及验证工作负载的方法。

插件支持 template(模板硬切分)、hami-core(运行时软切分)和 enpu 三种模式。先确认所选模式的前提,再配置 HAMi 调度支持、部署独立插件并运行作业。

前置条件​

  • Kubernetes 1.20 或更高版本,以及支持 OCI Chart 的 Helm 3。
  • 已安装 HAMi Enterprise,部署方式参见安装与部署。Ascend device plugin 可与 NVIDIA (HAMi) device plugin 在同一集群中共存,分别管理昇腾 NPU 和 NVIDIA GPU。
  • 使用前,按授权指南完成 HAMi Enterprise 授权。此要求适用于本文介绍的所有切分模式。
  • 昇腾节点已安装驱动和 ascend-docker-runtime,容器运行时已配置 ascend handler。创建 RuntimeClass 不会自动安装或配置该 handler。
  • 节点上的 npu-smi 可用,且插件容器能通过驱动目录或 /usr/local/sbin 挂载访问该工具。

Ascend 驱动和 CANN 版本要求​

驱动和 CANN 版本限制

HAMi 集成要求节点上的 Ascend 驱动版本不低于 25.5。业务镜像中的 CANN 需满足所选切分后端的要求:

模式CANN 要求
template业务镜像的 CANN 版本需与节点驱动和设备型号兼容。下述软切分运行库的构建版本不适用于模板硬切分。
hami-core随插件提供的 libvnpu 运行库使用 CANN 8.5.2 构建,业务镜像中的 CANN 环境必须与该运行库兼容。
enpu随插件提供的 ubs-virt-enpu/vCANN-RT 1.0.0 运行库使用 CANN 9.1.0 构建。运行库产物必须与业务镜像的 CANN 版本匹配,并满足对应版本的 CANN/HDK 要求。

CANN 8.5.2 和 9.1.0 分别是两套运行库的构建环境版本。使用其他 CANN 版本时,需验证节点驱动、业务镜像和所选运行库的组合兼容性。部署业务或升级 CANN 前,先确认该组合。

template 模式​

驱动需支持目标型号的虚拟化模板。HAMi 根据显存请求选择满足条件的最小模板,设备配置中的模板名称和容量应与驱动一致。

hami-core 模式​

该模式通过 libvnpu 运行库控制显存和算力,目前仅支持 ARM 平台和 HAMi 调度器。驱动和业务镜像中的 CANN 环境需满足上述版本要求。

插件在 hami-core 节点启动时自动为芯片开启 device-share。若忙碌芯片暂时拒绝切换,插件会暂停向 kubelet 和 HAMi 上报该芯片,待业务结束后重试,其他芯片仍可使用。其他类型的切换错误仍会导致插件启动失败。

enpu 模式​

当前适配 A2/910B 和 A3/910C,需按配套运行库要求启用设备共享。每个容器只能申请一个物理 DIE 上的共享份额。

ENPU 节点使用 hamiVnpuMode: enpu,业务 Pod 使用 huawei.com/vnpu-mode: enpu 和 runtimeClassName: ascend。部署前准备与 CANN/HDK 匹配的 vCANN-RT 运行库,业务镜像还需提供 /usr/bin/systemd-detect-virt 及其依赖。A3/910C 节点必须配置为单 DIE 独立模式(INDEP_POLICY);A2/910B 不需要该设置。

插件将镜像内的运行库安装到节点 /usr/local/enpu/vcann-rt。已有文件内容不同时,插件拒绝覆盖并启动失败。更新运行库前,停止目标节点上的 ENPU 业务并暂停该节点的设备插件,备份并移走以下三个文件:lib/libvruntime.so、tools/enpu-monitor 和 ld.so.preload (均相对于上述目录)。保留 hami-core 运行库,通过现有 Helm release 更新插件镜像后恢复插件,由插件安装新文件。回滚时同样先停止业务并暂停插件,再恢复备份文件和原插件镜像。

本页版本随附的 ENPU 运行库提供普通软切分,不包含 mem-swap,普通软切分不需要 enpu-manager。使用 mem-swap 需要另行准备支持该功能的运行库,还需单独部署兼容的 enpu-manager,并配置 enpu.managerURL 和 enpu.managerConfigRoot。 managerURL 必须指向插件所在节点的 manager;插件未启用 hostNetwork,不能使用 127.0.0.1 或随机转发到其他节点的 Service。

配置 Ascend 调度支持​

以下配置属于 HAMi Chart。按所选模式保存为 hami-ascend-values.yaml,合并到现有 HAMi release 的配置并更新部署。三种模式都需要 devices.ascend.enabled: true;该开关不安装 Ascend 插件。使用前确认 HAMi 版本支持 hamiVnpuMode 等字段。

template 配置​

devices:
ascend:
enabled: true
runtimeClassName: ascend
hamiVnpuMode: template

模板模式按设备模板计算可分配数量。型号、资源名和模板由 HAMi 的设备配置管理。

hami-core 配置​

devices:
ascend:
enabled: true
runtimeClassName: ascend
hamiVnpuMode: hami-core
deviceSplitCount: 10
hamiCorePolicy: spatial

deviceSplitCount 是每张物理 NPU 的虚拟设备数量上限,默认 10。显存和算力份额仍由业务 Pod 申请。

enpu 配置​

devices:
ascend:
enabled: true
runtimeClassName: ascend
hamiVnpuMode: enpu
deviceSplitCount: 10
enpuPolicy: elastic

ENPU 的有效槽位数不超过 100。enpuPolicy 支持 fixed-share、elastic 和 best-effort;Pod 可用 huawei.com/enpu-policy 覆盖默认值,同一物理 DIE 上的任务必须使用相同策略。

更新 HAMi 配置​

安装和升级方式参见安装与部署,将上述文件合并到所用部署方式的 values 中。 runtimeClassName: ascend 让 HAMi webhook 为 Ascend 作业添加 RuntimeClass,名称应与插件创建或复用的资源一致。

显式模式优先于旧的 hamiVnpuCore 布尔开关,节点模式可覆盖全局模式。切换模式前,先停止或重新调度受影响的工作负载。

部署 Ascend 设备插件​

插件与 HAMi 部署在同一命名空间。若已有插件由其他 Helm release 或原始 YAML 管理,应修改已有部署,避免重复创建 DaemonSet、RBAC 和节点 ConfigMap。

标记设备节点​

kubectl label node <ascend-node> ascend=on --overwrite

对每个目标节点执行一次。标签只决定插件部署位置,切分模式由全局或节点配置决定。

准备插件 values​

确认包含device-config.yaml 的 ConfigMap 所在命名空间和名称:

kubectl get configmap -A \
-l app.kubernetes.io/component=hami-scheduler \
-o go-template='{{range .items}}{{if index .data "device-config.yaml"}}{{.metadata.namespace}}{{"\t"}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}'

HAMi release 名为 hami 时,ConfigMap 通常名为 hami-scheduler-device。插件必须安装到该 ConfigMap 所在的命名空间。

保存以下内容为 ascend-plugin-values.yaml。这是 Ascend 插件 Chart 的配置,与前面的 HAMi values 分开维护。根据查询结果修改 ConfigMap 名称:

config:
create: false
existingDeviceConfigMapName: hami-scheduler-device
runtimeClass:
create: true
name: ascend
handler: ascend
nodeSelector:
ascend: "on"
nodeConfig: |-
nodes: []

Chart 创建 RBAC、ServiceAccount、DaemonSet、RuntimeClass 和节点 ConfigMap。若已存在可复用的 ascend RuntimeClass,将 runtimeClass.create 改为 false。nodes: [] 表示节点继承 HAMi 全局模式。

警告

config.create: false 让插件复用 HAMi 的全局设备配置。不要重复应用原始设备 ConfigMap;通过 HAMi release 管理共享配置。此时插件 Chart 的 hamiVnpuMode、deviceSplitCount 和 hamiVnpuCore.defaultPolicy 不会覆盖 HAMi 配置。

按节点配置模式和设备数量​

同一集群使用多种模式时,将插件 values 中的 nodeConfig 替换为实际节点列表:

nodeConfig: |-
nodes:
- name: ascend-node-1
hamiVnpuMode: template
- name: ascend-node-2
hamiVnpuMode: hami-core
hamiCorePolicy: spatial
vDeviceCount: 8
- name: ascend-node-3
hamiVnpuMode: enpu
vDeviceCount: 8

节点模式优先于全局模式;正数 vDeviceCount 可覆盖上报数量,ENPU 的有效上限仍为 100。节点名必须与 Kubernetes 一致。 nodeConfig 是整段 YAML 字符串,更新时保留其他节点条目;通过 Chart 修改它会触发插件滚动更新。每个节点均需满足对应模式的前提,不要在同一物理 DIE 上混用 hami-core 和 ENPU。

安装并检查插件​

升级已有 hami-core 业务

按 Chart 0.4.0 升级指引停止受影响的业务、迁移本地共享内存状态,并在升级插件后重建业务 Pod。仅滚动更新插件不会更新运行中容器的运行库和挂载。

将命名空间改为 HAMi 实际所在的命名空间,然后安装:

HAMI_NAMESPACE=hami-system
helm upgrade --install ascend-device-plugin \
oci://ghcr.io/dynamia-ai/charts/ascend-device-plugin \
--version 0.4.0 \
--namespace "$HAMI_NAMESPACE" \
--values ascend-plugin-values.yaml

Chart 默认使用镜像 ghcr.io/dynamia-ai/ascend-device-plugin:v1.5.0。其他镜像仓库通过 image.repository 和 image.tag 配置,image.digest 优先于 tag。升级时应在 values 中保留已有配置。

kubectl -n "$HAMI_NAMESPACE" rollout status \
daemonset/hami-ascend-device-plugin --timeout=180s
kubectl -n "$HAMI_NAMESPACE" get pods \
-l app.kubernetes.io/instance=ascend-device-plugin -o wide
kubectl get node <ascend-node> -o jsonpath='{.status.allocatable}{"\n"}'

确认每个目标节点都有就绪的插件 Pod,并上报实际型号对应的 huawei.com/* 设备数量。软切分模式下,每张健康 NPU 默认上报 10 个虚拟设备槽位;节点 vDeviceCount 可覆盖该数量。槽位数不代表可以同时满足相同数量的显存或算力申请。

HAMi 更新共享设备 ConfigMap 后,需要重启插件重新读取配置:

kubectl -n "$HAMI_NAMESPACE" rollout restart daemonset/hami-ascend-device-plugin
kubectl -n "$HAMI_NAMESPACE" rollout status \
daemonset/hami-ascend-device-plugin --timeout=180s

运行 Huawei Ascend 作业​

以下示例使用 hami-scheduler 和 RuntimeClass ascend,按实际部署修改。替换业务镜像占位值,确认 CANN、驱动和切分运行库兼容;PyTorch 计算示例还需包含 torch_npu。

资源名由共享 device-config.yaml 中的 vnpus.configs 决定,必须与实际芯片型号匹配。以 Ascend 910B3 为例:

资源说明
huawei.com/Ascend910B3申请的设备数量
huawei.com/Ascend910B3-memory每张设备的显存配额,单位 MiB
huawei.com/Ascend910B3-core软切分的每张设备算力份额,正数范围为 1–100;实际约束方式取决于策略

只申请设备数量时使用整卡显存。共享同一张卡时,每个容器申请一张设备,并显式填写显存配额。hami-core 中省略 -core 或设为 0 时,调度器不预留算力,运行时上限为 100;需要算力份额时应显式申请,并设置 huawei.com/vnpu-mode: hami-core。

hami-core 多卡申请的显存和算力配额对每张卡独立生效。例如,设备数量为 2、-memory 为 16384,表示每张卡 16 GiB。所有选中设备必须使用相同配额。

内置配置还包含 Ascend910A、Ascend910B2、Ascend910B4-1、Ascend910B4、Ascend310P 和 Ascend910C 资源名。申请算力前,确认对应条目包含 resourceCoreName,且调度器和插件使用相同定义。配置中存在某个型号不代表所有切分后端都支持该型号。

template 模式​

以下 Pod 应运行在模板模式节点上。910B3 示例申请 16 GiB,310P 示例申请 3 GiB,分别对应内置模板容量。省略模式注解的 Pod 也可能匹配 hami-core 节点;混合模式集群应使用 nodeSelector 或节点亲和性限定模板节点。

Ascend 910B3​

apiVersion: v1
kind: Pod
metadata:
name: ascend-template-910b3
spec:
schedulerName: hami-scheduler
runtimeClassName: ascend
containers:
- name: workload
image: registry.example.com/your-project/ascend-workload:replace-me
command: [ "sh", "-c", "sleep 86400" ]
resources:
limits:
huawei.com/Ascend910B3: "1"
huawei.com/Ascend910B3-memory: "16384"

Ascend 310P​

apiVersion: v1
kind: Pod
metadata:
name: ascend-template-310p
spec:
schedulerName: hami-scheduler
runtimeClassName: ascend
containers:
- name: workload
image: registry.example.com/your-project/ascend-workload:replace-me
command: [ "sh", "-c", "sleep 86400" ]
resources:
limits:
huawei.com/Ascend310P: "1"
huawei.com/Ascend310P-memory: "3072"

hami-core 模式​

单卡显存和算力配额​

以下测试针对 hami-core 节点,在 Ascend 910B3 上申请 4 GiB 显存和 50% 算力份额,检查配额注入和一次真实 NPU 矩阵计算。根据实际型号替换三个资源名,并确认 HAMi 调度器名称;示例使用 hami-scheduler。

准备包含兼容 CANN、PyTorch 和 torch_npu 的业务镜像,替换以下镜像占位值,将文件保存为 ascend-smoke.yaml:

apiVersion: v1
kind: Pod
metadata:
name: ascend-smoke
annotations:
huawei.com/vnpu-mode: hami-core
huawei.com/npu-sched-policy: spatial
spec:
schedulerName: hami-scheduler
runtimeClassName: ascend
restartPolicy: Never
containers:
- name: pytorch
image: registry.example.com/your-project/pytorch-ascend:replace-me
env:
- name: TZ
value: UTC
command: [ "python3", "-u", "-c" ]
args:
- |
import os
import torch
import torch_npu
for key in ("NPU_MEMORY_LIMIT_MB", "NPU_COMPUTE_LIMIT", "NPU_SCHED_POLICY"):
print(key, os.environ.get(key))
with open("/proc/self/maps") as maps:
assert "/hami-vnpu-core/libvnpu.so" in maps.read(), "libvnpu is not loaded"
print("libvnpu loaded")
torch.npu.set_device(0)
a = torch.ones((1024, 1024), device="npu:0")
result = torch.mm(a, a)
torch.npu.synchronize()
value = result[0, 0].item()
assert value == 1024.0, value
print("NPU result:", value)
resources:
limits:
huawei.com/Ascend910B3: "1"
huawei.com/Ascend910B3-memory: "4096"
huawei.com/Ascend910B3-core: "50"

创建 Pod 并检查结果:

kubectl apply -f ascend-smoke.yaml
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/ascend-smoke --timeout=300s
kubectl logs ascend-smoke
检查项预期
Pod 状态Succeeded
NPU_MEMORY_LIMIT_MB4096
NPU_COMPUTE_LIMIT50
NPU_SCHED_POLICYspatial
运行库加载libvnpu loaded
计算结果NPU result: 1024.0

该测试验证调度、运行库注入和 NPU 计算链路,不验证显存超限拒绝、共卡隔离或吞吐比例。测试后清理:

kubectl delete pod ascend-smoke

算力策略​

默认策略为 spatial。优先级为 Pod 注解 huawei.com/npu-sched-policy、节点 hamiCorePolicy、全局 vnpus.hamiCorePolicy。

策略行为
spatial通过 CANN 设置协作式 Cube/Vector 核数预算;不等同于独占硬件分区,也不保证推理吞吐按比例分配
dynamic按相对份额进行时间调度,可借用空闲算力
fixed以运行和休眠时间比例控制目标百分比
overdraft在 dynamic 时间调度基础上,允许空闲状态下的有界借用

插件 Chart 的 hamiVnpuCore.coreUtilizationPolicy 保持默认值 default 时使用上述策略;容器显式声明的 NPU_CORE_UTILIZATION_POLICY 优先。

多卡并行推理​

多卡作业保留 huawei.com/vnpu-mode: hami-core,并按每张卡填写配额。例如,在两张 64 GiB 的 910B3 上各申请 32 GiB 和 50% 算力:

resources:
limits:
huawei.com/Ascend910B3: "2"
huawei.com/Ascend910B3-memory: "32768"
huawei.com/Ascend910B3-core: "50"

此配置合计申请 64 GiB 显存。使用 vLLM-Ascend 进行 TP=2 推理时,按每卡 32/64 的比例设置显存预算,并为运行时开销留出空间。业务镜像、模型文件和存储需另行准备。

enpu 模式​

以下示例在 910B3 上申请 16 GiB 显存和 20% 算力份额。elastic 可以借用空闲算力,因此 20% 不是严格上限。业务镜像需满足前述 ENPU 条件,并包含 PyTorch 和 torch_npu。

apiVersion: v1
kind: Pod
metadata:
name: ascend-enpu-smoke
annotations:
huawei.com/vnpu-mode: enpu
huawei.com/enpu-policy: elastic
spec:
schedulerName: hami-scheduler
runtimeClassName: ascend
restartPolicy: Never
containers:
- name: pytorch
image: registry.example.com/your-project/pytorch-ascend:replace-me
command: [ "python3", "-u", "-c" ]
args:
- |
import torch
import torch_npu
torch.npu.set_device(0)
a = torch.ones((1024, 1024), device="npu:0")
result = torch.mm(a, a)
torch.npu.synchronize()
value = result[0, 0].item()
assert value == 1024.0, value
print("ENPU result:", value)
resources:
limits:
huawei.com/Ascend910B3: "1"
huawei.com/Ascend910B3-memory: "16384"
huawei.com/Ascend910B3-core: "20"

保存为 ascend-enpu-smoke.yaml,运行并检查输出:

kubectl apply -f ascend-enpu-smoke.yaml
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/ascend-enpu-smoke --timeout=300s
kubectl logs ascend-enpu-smoke
kubectl delete pod ascend-enpu-smoke

预期输出 ENPU result: 1024.0。使用 910C 时,同时替换三个资源名并确认独立 DIE 模式。容器内使用逻辑设备 npu:0。

注意事项​

  • 资源名必须与共享设备配置和实际型号一致;有型号定义不代表所有后端都支持该型号。
  • 模板示例每个容器申请一个设备;hami-core 支持多卡且按每卡应用配额;ENPU 每个容器只支持一个物理 DIE。
  • 模板示例中的 sleep 只便于检查分配,不执行 NPU 计算。hami-core 和 ENPU 示例验证计算链路,不代替共卡隔离或性能测试。
  • 更换运行库、切换模式或更新授权时,按对应要求重建业务 Pod;仅重启业务进程不能保证重新分配。

监控​

NPU 硬件指标​

按 AscendHub 的 npu-exporter 安装说明部署 npu-exporter,并将其接入 Prometheus。npu-exporter 的作用类似 NVIDIA 的 DCGM Exporter,用于采集昇腾 NPU 的硬件指标。根据实际设备型号和驱动版本选择适用版本,并按官方说明完成部署和采集配置。

软切分与容器指标​

Ascend device plugin 提供软切分和容器级指标,可与 npu-exporter 的硬件指标配合使用。下文的 vnpuMonitor 参数只配置插件自身的指标采集资源,不会安装 npu-exporter。

hami-core 和 ENPU 节点通过 :9395/metrics 暴露指标。选择目标节点上的插件 Pod,在一个终端执行端口转发:

kubectl -n "$HAMI_NAMESPACE" get pods \
-l app.kubernetes.io/instance=ascend-device-plugin -o wide
kubectl -n "$HAMI_NAMESPACE" port-forward "pod/<plugin-pod>" 9395:9395

在另一终端检查:

curl -fsS http://localhost:9395/metrics

使用 Prometheus Operator 时,可设置 vnpuMonitor.enabled=true;默认同时创建 ServiceMonitor 和 PrometheusRule。先安装对应 CRD,并调整 vnpuMonitor.serviceMonitor.* 和 vnpuMonitor.prometheusRule.* 的命名空间及发现标签。仅需 Service 时,将两者的 create 设为 false。

排障​

kubectl -n "$HAMI_NAMESPACE" logs \
-l app.kubernetes.io/instance=ascend-device-plugin \
-c device-plugin --tail=200
kubectl describe pod ascend-smoke
现象检查
无插件 Pod节点是否带有 ascend=on 标签;是否存在阻止调度的污点或资源不足
ConfigMap 挂载失败ConfigMap 名称、命名空间,以及 device-config.yaml 键是否存在
RuntimeClass 或 handler 错误ascend RuntimeClass 与节点容器运行时 handler 是否一致
插件启动失败或无设备资源驱动、型号配置、设备过滤及日志中的 device-share 错误;确认插件容器能访问 npu-smi
Pod Pending 或分配失败实际资源名、节点模式、HAMi 调度器名称、剩余显存和槽位数
授权错误节点 hami.io/ascend-license 是否包含所选设备的有效授权;续期后是否重建业务 Pod
ENPU 分配失败CANN/运行库兼容性、systemd-detect-virt、910C 单 DIE 模式,以及运行库文件冲突

卸载​

先停止使用此插件的 Ascend 工作负载,再卸载插件 release:

helm uninstall ascend-device-plugin --namespace "$HAMI_NAMESPACE"

卸载不会删除由 HAMi 管理的共享设备 ConfigMap,也不会自动清理节点上的运行库和运行时数据。Chart 管理的 RuntimeClass 会随 release 删除,卸载前应确认其他工作负载没有依赖它。