以 root 身份运行 Multi-NPU vLLM Ascend 推理

概述

某些 vLLM-ascend 镜像在 Modelcar 和服务容器以 UID 1000 运行时,无法可靠地初始化 Multi-NPU 推理。张量并行度大于 1 时,通常会出现此问题,例如使用 --tensor-parallel-size=2 在两个 Ascend NPU 上运行 Qwen3.6-27B。

经过测试,如果同一服务在 Modelcar 和服务容器以 root 身份(UID 0)运行时能够启动,则可以将 root 模式用作兼容性临时解决方案。本指南介绍如何为 Multi-NPU InferenceService 配置此模式。

WARNING

对于尚未支持 UID 1000 的镜像或驱动集成,root 模式是一种兼容性临时解决方案。它会在集群级别更改 Modelcar 工作负载使用的 UID。请使用专用 runtime,采用能够允许该工作负载运行的最小范围命名空间安全策略,并在不再需要 root 模式时恢复非 root 配置。

本指南不能替代张量并行配置。服务仍必须请求所需数量的 NPU,并向 vLLM 传递匹配的 --tensor-parallel-size 值。

何时使用 root 模式

仅当满足以下所有条件时,才使用 root 模式:

  • 服务在 Ascend NPU 上运行,并使用 Multi-NPU 推理(TP > 1)。
  • 所选的 vLLM-ascend 镜像已针对所需模型和硬件进行测试。
  • 服务在分布式初始化期间以 UID 1000 运行时失败,而相同工作负载以 UID 0 运行时能够启动;并且在为 UID 1000提供 passwd 条目后,故障仍然存在。
  • 服务所有者接受更改 Modelcar UID 对集群造成的影响。

典型症状包括:

ERR02200 DIST call hccl api failed
HcclGetCommAsyncError
Engine core initialization failed. See root cause above.

这些消息表明存在分布式初始化或设备访问故障,但不能证明 root 是正确的长期解决方案。请记录 runtime 镜像、驱动程序、CANN、torch_npu、vLLM 和 vLLM Ascend 版本,以便向镜像或设备集成负责人报告此问题。

配置范围

Root 模式要求以下位置的设置保持一致:

设置位置Root 模式值
Modelcar UIDAmlClusteruidModelcar: 0
容器 UIDRoot 专用的 ClusterServingRuntimerunAsUser: 0
非 root 限制Root 专用的 ClusterServingRuntime移除 runAsNonRoot: true,或将其设置为 false
设备组InferenceService在节点上的设备文件所有权有此要求时,为 supplementalGroups 配置设备组 ID
Namespace Pod Security Admission包含该服务的 namespace通常为 baseline

uidModelcar 是集群级设置。它会影响集群中的 Modelcar 工作负载,而不仅仅是本指南中所述的推理服务。请与其他 Modelcar 工作负载的负责人一起规划此项更改。

先决条件

  • 一个可用于创建或更新 InferenceService 的 namespace。
  • 一个拥有模型所需数量 NPU 的 Ascend 节点。对于 TP=2,同一个 Pod 必须能够看到两个 NPU。
  • 一个支持目标模型和 Ascend 软件栈的 vLLM-ascend runtime 镜像。
  • 一个可复制到 Root 专用 runtime 中的现有 ClusterServingRuntime。
  • 拥有集群管理员访问权限,以便更新 AmlCluster 和 namespace 的 Pod Security Admission 设置。

配置 Namespace 安全策略

在创建 Root 模式服务之前,将 namespace 的 Pod Security Admission Enforce 级别设置为 baseline。在平台控制台中,打开 Project > Namespace,选择目标 namespace,并更新其 Pod Security Admission 设置。

仅当生成的 Pod 包含 baseline 会拒绝的要求时(例如 host namespace 或其他明确的特权设置),才使用 privileged。仅以 UID 0 运行并不需要将 namespace 设置为 privileged。

Audit 和 Warn 级别不会决定是否准入 Pod。如果 Pod 被 Pod Security Admission 拒绝,请检查 Enforce 级别。

在 AmlCluster 中设置 Modelcar UID

更新 AmlCluster 资源,使 KServe Modelcar 使用 UID 0:

spec:
  components:
    kserve:
      values:
        kserve:
          storage:
            uidModelcar: 0

使用集群的常规管理工作流,将更改应用到现有的 default AmlCluster。不要创建第二个 AmlCluster。在推出推理服务之前,确认控制器已协调新值:

kubectl get amlcluster default
WARNING

不要在共享集群上随意更改此值。平台默认值为 UID 1000;将其更改为 0 也会更改其他服务新生成的 Modelcar 工作负载。

创建 Root 专用 ClusterServingRuntime

复制现有的 Ascend runtime,并为副本指定一个不同的名称。保留已验证 runtime 中的模型路径处理、Ascend toolkit 初始化、共享内存卷、探针和镜像版本。将以下片段合并到完整的 runtime 副本中;它不是独立的清单。保留 supportedModelFormats、protocolVersions 和其他 runtime 字段。有关起始配置,请参阅自定义 Ascend runtime 示例,并选择支持你的模型的镜像。按如下方式更改容器安全上下文:

apiVersion: serving.kserve.io/v1alpha1
kind: ClusterServingRuntime
metadata:
  name: aml-vllm-ascend-root
  labels:
    aml.cpaas.io/runtime-type: vllm
    cpaas.io/accelerator-type: ascend
spec:
  containers:
    - name: kserve-container
      image: quay.io/ascend/vllm-ascend:<validated-tag>
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        privileged: false
        runAsNonRoot: false
        runAsUser: 0
        seccompProfile:
          type: RuntimeDefault

调整现有非 root runtime 时:

  • 移除 runAsNonRoot: true,或将其设置为 false。
  • 将 runAsUser: 1000 替换为 runAsUser: 0。
  • 容器级安全上下文字段优先于对应的 Pod 级字段。如果容器未指定 runAsNonRoot,则会继承 Pod 级设置。检查每个生成的容器(包括 Modelcar),确认其继承的非 root 限制不会与 UID 0 冲突。
  • 如果镜像会写入缓存或临时文件,请确保 HOME 指向可写路径,例如 /tmp。
  • 除非已验证的镜像需要且 namespace 策略允许,否则不要移除 seccompProfile、已删除的 capabilities 或其他限制。

保留 runtime 命令中的 "$@" 转发设置,以便服务专用的 vLLM 参数能够传递给服务器。在下方所示的 InferenceService model.args 字段中设置 TP 值。不要在 runtime 命令和服务中同时定义相互冲突的 tensor parallel 值。

创建 InferenceService

选择 Root 专用 runtime,并为 TP=2 部署请求两个 NPU。具体的 Ascend 资源键取决于集群:

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: qwen3-6-27b
  namespace: <namespace>
  annotations:
    aml-model-repo: Qwen3.6-27B
    serving.kserve.io/deploymentMode: Standard
  labels:
    aml.cpaas.io/runtime-type: vllm
spec:
  predictor:
    model:
      args:
        - --tensor-parallel-size=2
        - --gpu-memory-utilization=0.7
      modelFormat:
        name: transformers
      protocolVersion: v2
      resources:
        limits:
          huawei.com/Ascend910B4-1: '2'
          memory: 32Gi
        requests:
          huawei.com/Ascend910B4-1: '2'
          memory: 32Gi
      runtime: aml-vllm-ascend-root
      storageUri: oci://<registry>/<repository>:<tag>
    securityContext:
      seccompProfile:
        type: RuntimeDefault

Root 模式无需使用 fsGroup 来访问设备。只有当存储后端或其他工作负载需求需要时,才保留 fsGroup。服务是否需要 supplementalGroups 取决于节点上 Ascend 设备文件的所有权;请参阅授予对 Ascend 设备文件的访问权限。

--gpu-memory-utilization 的值仅为示例。它用于控制每个实例可用于模型权重、激活值和 KV cache 的设备内存预算;它不能替代 --tensor-parallel-size=2,也无法解决 UID 或 HCCL 初始化失败问题。

授予对 Ascend 设备文件的访问权限

以 UID 0 运行容器,并不会自动授予其访问 Ascend 设备文件的权限。Root 专用 runtime 会删除所有 Linux capabilities,包括 CAP_DAC_OVERRIDE,因此 UID 0 仍受这些文件的常规所有者、组和权限检查约束。

在许多 Ascend 节点上,NPU 驱动会以 HwHiAiUser 所有者和组以及 crw-rw---- 权限创建设备文件。请检查运行服务的节点上的文件所有权:

ls -l /dev/davinci* /dev/davinci_manager /dev/devmm_svm /dev/hisi_hdc
id HwHiAiUser

示例输出:

crw-rw---- 1 HwHiAiUser HwHiAiUser 237, 0 ... /dev/davinci0
crw-rw---- 1 HwHiAiUser HwHiAiUser 238, 0 ... /dev/davinci_manager
crw-rw---- 1 HwHiAiUser HwHiAiUser 236, 0 ... /dev/devmm_svm
crw-rw---- 1 HwHiAiUser HwHiAiUser 235, 0 ... /dev/hisi_hdc
uid=1000(HwHiAiUser) gid=1000(HwHiAiUser) groups=1000(HwHiAiUser)

如果设备文件未授予其他用户任何访问权限(如本例所示),请将设备组 ID 添加到 InferenceService 的 Pod 级 supplementalGroups 中:

spec:
  predictor:
    securityContext:
      seccompProfile:
        type: RuntimeDefault
      supplementalGroups:
        - 1000 # Replace with the group ID that owns /dev/davinci* on your nodes.

如果没有设备组,vLLM worker 进程将无法打开 NPU 设备,并会在初始化期间退出。有关日志消息和诊断操作步骤,请参阅vLLM Ascend worker 无法打开 NPU 设备。

建议使用设备组,而不是向 runtime 添加 CAP_DAC_OVERRIDE。该 capability 会绕过容器内所有文件的权限检查,而设备组只授予对属于该组的文件的访问权限。不要移除 drop: [ALL],也不要将 privileged: true 设置为变通解决此故障。

部署和验证

将合并后的完整 runtime 保存为 vllm-ascend-root-runtime.yaml,并将服务保存为 qwen3-6-27b.yaml。将镜像标签、命名空间、模型 URI 和资源键替换为已在你的环境中验证的值,然后应用配置:

kubectl apply -f vllm-ascend-root-runtime.yaml
kubectl apply -f qwen3-6-27b.yaml -n <namespace>
kubectl get pods -n <namespace> -w

检查生成的 Pod,并验证生效的设置:

kubectl get pod <pod-name> -n <namespace> -o yaml
kubectl get inferenceservice qwen3-6-27b -n <namespace> -o yaml
kubectl logs <pod-name> -n <namespace> -c kserve-container

确认以下所有事项:

  • Pod 在同一节点上请求并获得两个 NPU。
  • serving 容器以 UID 0 运行(id -u 返回 0)。
  • 如果节点上的设备文件归属于某个组,serving 容器中的 id -G 会包含该设备组 ID。
  • 生成的 vLLM 参数中恰好包含 --tensor-parallel-size=2。
  • 日志显示 HCCL/分布式初始化和模型加载成功。
  • InferenceService 达到 Ready,并能处理测试请求。

如果 Pod 在启动前被拒绝,请检查命名空间事件中是否存在 PSA 违规。如果 Pod 已启动但 HCCL 仍然失败,请先收集第一个 worker 错误和完整的软件版本矩阵,再更改其他安全设置。

恢复非 root 模式

当镜像或 vLLM Ascend 集成支持 UID 1000 时,恢复更安全的默认设置:

  1. 在 AmlCluster 中,将 uidModelcar 恢复为 1000。
  2. 等待 Modelcar 配置完成协调。将受影响的服务切换到标准的非 root ClusterServingRuntime,并使用 runAsNonRoot: true 和 runAsUser: 1000,同时从非 root 示例中恢复所需的设备组和存储组设置。
  3. 逐步部署受影响的服务,并验证其替换容器的生效 UID、服务就绪状态以及测试请求。
  4. 确认替换后的 Pod 符合命名空间 PSA 要求后,恢复工作负载所需的 PSA 级别。
  5. 确认没有服务在使用 root 专用 runtime 后,将其移除。

报告兼容性问题

报告 UID 1000 故障时,请提供模型、TP 大小、NPU 型号和数量、runtime 镜像摘要、CANN 和驱动程序版本、vLLM 和 vLLM Ascend 版本、生效的 Pod 安全上下文,以及第一个 HCCL/DIST 错误。这些信息有助于区分设备权限问题与模型、内存或分布式拓扑问题。

相关文档