跳到正文
LEo的网络日志
返回

在 kubernetes 和昇腾 npu 上部署 qwen3.8-27b

一台机器上有昇腾 npu,也有大模型文件,接下来怎样让其他程序通过接口向模型提问?

本文记录一次从准备镜像、挂载模型到调用接口的过程。我们使用两张 ascend 910B4-1、一个 qwen3.8-27b w8a8 模型和官方 vllm ascend 镜像,最终让非 root 用户在 kubernetes 容器里完成了推理。过程中还遇到了一个很像“缺少算子”的错误,最后发现普通用户的目录访问权限是值得重点检查的线索。

文章以已经具备 kubernetes、昇腾驱动、设备插件和容器运行时的环境为起点;不覆盖从裸机安装这些组件。文中名称、用户编号和存储位置是去敏后的示例,复制前请按自己的环境调整。未经实际验证的通用示例和本次实测结果会分别说明。

1 部署流程

模型文件通过只读卷交给 vllm ascend,kubernetes 为服务分配两张 npu。vllm 的作用见入门文章,多卡并行可参考 tp 和 pp 介绍。

启动后还要确认模型加载、设备分配和实际回答,而不只是 pod 运行。

2 准备好硬件、集群和存储

本次实践使用的条件如下:

项目条件
节点arm64,昇腾 ascend 910B4-1,单卡约 64 GiB 显存
npu两张可以分配的整卡
kubernetes设备插件已登记 huawei.com/Ascend910,并有适用于该节点的 RuntimeClass
运行环境使用与驱动兼容的 ascend 容器运行时;本例的 RuntimeClass 名为 ascend
资源推理容器申请 16 个 cpu 和 64 GiB 内存;另需模型存储和启动缓存空间
模型已准备 qwen3.8-27b w8a8 权重、配置和 tokenizer

在管理端先核对:

kubectl get nodes -o wide
kubectl get runtimeclass ascend
NPU_NODE="填写自己的-npu-节点名"
kubectl describe node "$NPU_NODE"

节点描述中的 Capacity 和 Allocatable 说明 kubernetes 能识别多少资源,不等于当前空闲卡数。还要检查已运行工作负载的请求;如果设备还由其他调度系统使用,也应遵循现场已有的协调方式。设备接入过程可参考昇腾 npu 如何接入 kubernetes。

本例要求节点能拉取镜像;离线或私有镜像仓库应先完成原版镜像同步与权限配置。一个 pod 要有权限使用模型 pvc,但不应因此把私有模型或仓库凭据公开给所有人。

3 选择官方镜像和模型

推理镜像

这次使用官方 a2 openeuler 版本 v0.23.0.post1-openeuler,示例固定官方 arm64 manifest 摘要:

quay.io/ascend/vllm-ascend@sha256:11125f9a4bbaecbc05d10f4af0619841f5dd1990623f97e61450e23d832872d3

固定摘要比只写可变标签更容易确认“究竟使用了哪一份镜像”。可以查看官方镜像仓库和官方安装文档,了解不同硬件和系统的镜像;官方模型教程还列出专用于 qwen 的 a2 镜像 qwen3.8-a2。后者是另一候选,本次没有对它做现场验证。

本次实践实际从内部镜像仓库使用了一份事先导入的镜像;它的配置摘要及 16 个未压缩层声明与上述官方版本一致。我们没有重新读取全部大文件并逐层计算摘要,因此这个比较不能表述为完整归档逐字节校验。导入、压缩或封装方式不同也可能让镜像 manifest 摘要不同。

下面的示例使用官方地址,不包含私有仓库地址。如果计算节点不能访问官方仓库,可使用经确认的镜像源;替换前应核对同一个 arm64 manifest 摘要。不要仅凭相同标签认定内容相同。

模型文件

官方模型教程给出了昇腾适配的 qwen3.8-27b w8a8 模型。w8a8 表示权重和激活采用相应的 8 位量化表示;--quantization ascend 是加载与昇腾实现匹配的量化模型,不会把任意模型自动量化。

一种准备方法是先在可访问共享存储的下载机器上安装 modelscope 工具,再下载模型。下面的目录只是示例,它应是 nfs 服务端实际导出的模型目录;运行前核对磁盘空间、网络、模型许可及目标目录权限:

python3 -m venv "$HOME/.venvs/modelscope"
. "$HOME/.venvs/modelscope/bin/activate"
python3 -m pip install modelscope

MODEL_DIR=/srv/nfs/qwen3.8-27b-w8a8
modelscope download --model Eco-Tech/Qwen3.8-27B-w8a8 --local_dir "$MODEL_DIR"
ls -lh "$MODEL_DIR"

下载前应在模型仓库确认所需版本;长期复现时用 modelscope 的 --revision 指定你核实过的 commit 或 tag,并保存完整文件清单和摘要。modelscope 命令说明介绍了这些选项。本文实践中的模型是已准备好的 w8a8 版本,其上游仓库 revision 未核实;上面的公开下载地址是官方教程推荐的候选,不能说下载到的每个文件必然与本次实践逐字节相同。

例如,可在下载完成后创建一份本地校验记录,便于以后发现文件变化:

cd "$MODEL_DIR"
find . -type f -print0 | sort -z | xargs -0 sha256sum > ../qwen3.8-27b-w8a8.sha256

这份摘要记录用于后续对比,不能单独证明文件来自官方或内容正确。模型目录应至少包含模型配置、量化配置、tokenizer 和完整权重分片;保证推理用户有读取权限。

4 让 pod 以普通用户运行

原版镜像中的一个自定义算子目录在本次检查中属于 root 组,权限为 750;推理进程如果使用一个不在该组的普通用户,可能无法读取算子库。另外,镜像的身份文件中不一定有该用户编号。

这次没有重建镜像,也没有修改宿主机账户或系统权限。清单使用两个短暂的 init container:

  1. 第一个以普通用户运行,将镜像原有的 /etc/passwd、/etc/group 复制到 pod 的临时卷,补充当前用户和组;推理容器只读挂载副本。
  2. 第二个也使用非 root uid,但其主组临时设为 gid 0,以 root 组权限读取镜像内的算子目录,将其复制到另一个 pod 临时卷;推理容器仍以普通 uid 和普通 gid 运行,并只读挂载副本。

这里的 gid 0 不等同于 root uid,但它确实允许这个初始化容器读取镜像内 root 组可读的内容。示例不启用特权模式、不允许提权、不挂宿主机目录,也不挂服务账户令牌;如果你的集群策略不允许 gid 0,应该由管理员评估受支持的非 root 镜像或其他授权方式,而不是擅自放宽集群策略。init container 和 emptyDir 的生命周期由 kubernetes 管理。

示例的 uid 10001、gid 20001 只是教学值,并不是某个现场用户。应按自己的身份映射统一调整 runAsUser、runAsGroup、fsGroup、USER、LOGNAME 及初始化命令中的 uid 检查。使用 nfs 或 csi 时,先核对存储驱动对 fsGroup、权限及所有权的行为,避免修改共享数据权限。

5 创建模型 pvc

下面使用已有 nfs 共享作为例子;如果已有能够从 npu 节点读取模型的 pvc,可以复用它并跳过静态 pv 创建。本例的 REPLACE_WITH_NFS_SERVER 是占位符,必须替换成自己的 nfs 服务端地址;示例路径必须指向包含模型文件的目录本身。不要把整个共享盘挂进容器。

先确认 llm-demo、pv 与 pvc 的名称没有被占用,创建独立命名空间,再把下面内容保存为 qwen-storage.yaml:

kubectl create namespace llm-demo
apiVersion: v1
kind: PersistentVolume
metadata:
  name: qwen-weights-pv
spec:
  capacity:
    storage: 100Gi
  volumeMode: Filesystem
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  storageClassName: ""
  nfs:
    server: REPLACE_WITH_NFS_SERVER
    path: /srv/nfs/qwen3.8-27b-w8a8
    readOnly: true
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: qwen-weights
  namespace: llm-demo
spec:
  accessModes:
    - ReadOnlyMany
  resources:
    requests:
      storage: 100Gi
  storageClassName: ""
  volumeName: qwen-weights-pv

修改占位符后创建并检查:

kubectl create -f qwen-storage.yaml
kubectl get pv qwen-weights-pv
kubectl get pvc -n llm-demo qwen-weights

Bound 表示 pvc 已绑定,不证明容器能读取模型。nfs 的 100Gi 是这里的资源声明,不自动为目录分配或限制实际容量;请使用已有存储系统的容量和配额能力。Retain 用于保留底层数据,清理资源前仍应确认实际存储行为。

6 创建双卡推理服务

把下面清单保存为 qwen-ascend.yaml。它包含一个 deployment 和一个仅供集群内部访问的 service。示例基于实际成功清单去敏:公开镜像地址、命名空间、pvc、用户编号和节点选择条件都已替换;这些通用替换没有在另一套集群独立实测,需要按前面的准备条件复核。

GLOO_SOCKET_IFNAME 和 HCCL_SOCKET_IFNAME 示例均为 eth0,实际容器网络接口不同则需要调整。runtimeClassName 和设备资源名也应以集群中的实际配置为准。如果改用私有仓库,还需在自己的命名空间配置有权拉取镜像的 imagePullSecrets,不要把凭据写进文章或清单。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qwen-ascend
  namespace: llm-demo
  labels:
    app: qwen-ascend
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: qwen-ascend
  template:
    metadata:
      labels:
        app: qwen-ascend
    spec:
      automountServiceAccountToken: false
      nodeSelector:
        kubernetes.io/arch: arm64
      runtimeClassName: ascend
      securityContext:
        fsGroup: 20001
      containers:
      - image: quay.io/ascend/vllm-ascend@sha256:11125f9a4bbaecbc05d10f4af0619841f5dd1990623f97e61450e23d832872d3
        command:
        - vllm
        - serve
        - /models
        - --served-model-name
        - qwen3.8-27b
        - --host
        - 0.0.0.0
        - --port
        - '8000'
        - --tensor-parallel-size
        - '2'
        - --pipeline-parallel-size
        - '1'
        - --max-model-len
        - '8192'
        - --gpu-memory-utilization
        - '0.85'
        - --quantization
        - ascend
        - --max-num-seqs
        - '1'
        env:
        - name: ASCEND_CUSTOM_OPP_PATH
          value: /vllm-workspace/vllm-ascend/vllm_ascend/_cann_ops_custom/vendors/custom_transformer
        - name: PATH
          value: /usr/local/Ascend/cann-9.1.0/bin:/usr/local/Ascend/cann-9.1.0/tools/ccec_compiler/bin:/usr/local/Ascend/cann-9.1.0/tools/profiler/bin:/usr/local/Ascend/cann-9.1.0/tools/ascend_system_advisor/asys:/usr/local/Ascend/cann-9.1.0/tools/show_kernel_debug_data:/usr/local/Ascend/cann-9.1.0/tools/msobjdump:/usr/local/python3.12.13/bin:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/bin:/usr/local/Ascend/ascend-toolkit/latest/bin:/usr/local/Ascend/ascend-toolkit/latest/compiler/ccec_compiler/bin:/usr/local/Ascend/ascend-toolkit/latest/tools/ccec_compiler/bin:/usr/local/python3.12.13/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
        - name: XDG_CACHE_HOME
          value: /tmp/vllm-cache/xdg
        - name: ASCEND_HOME_PATH
          value: /usr/local/Ascend/cann-9.1.0
        - name: TORCHINDUCTOR_CACHE_DIR
          value: /tmp/vllm-cache/torchinductor
        - name: USER
          value: uid10001
        - name: VLLM_CACHE_ROOT
          value: /tmp/vllm-cache/vllm
        - name: HOME
          value: /tmp
        - name: LOGNAME
          value: uid10001
        - name: PYTHONPATH
          value: '/usr/local/Ascend/cann-9.1.0/python/site-packages:/usr/local/Ascend/cann-9.1.0/opp/built-in/op_impl/ai_core/tbe:/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:/usr/local/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe:'
        - name: ASCEND_OPP_PATH
          value: /usr/local/Ascend/cann-9.1.0/opp
        - name: GLOO_SOCKET_IFNAME
          value: eth0
        - name: HCCL_SOCKET_IFNAME
          value: eth0
        - name: HF_HOME
          value: /tmp/vllm-cache/huggingface
        - name: LD_LIBRARY_PATH
          value: '/vllm-workspace/vllm-ascend/vllm_ascend/_cann_ops_custom/vendors/custom_transformer/op_api/lib:/usr/local/Ascend/cann-9.1.0/lib64:/usr/local/Ascend/cann-9.1.0/lib64/plugin/opskernel:/usr/local/Ascend/cann-9.1.0/lib64/plugin/nnengine:/usr/local/Ascend/cann-9.1.0/opp/built-in/op_impl/ai_core/tbe/op_tiling/lib/linux/aarch64:/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/lib64:/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/lib:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/examples:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/tests/atbopstest:/usr/local/Ascend/ascend-toolkit/latest/tools/aml/lib64:/usr/local/Ascend/ascend-toolkit/latest/tools/aml/lib64/plugin:/usr/local/Ascend/ascend-toolkit/latest/lib64:/usr/local/Ascend/ascend-toolkit/latest/lib64/plugin/opskernel:/usr/local/Ascend/ascend-toolkit/latest/lib64/plugin/nnengine:/usr/local/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe/op_tiling:/usr/local/python3.12.13/lib:'
        resources:
          limits:
            cpu: '16'
            huawei.com/Ascend910: '2'
            memory: 64Gi
          requests:
            cpu: '16'
            huawei.com/Ascend910: '2'
            memory: 64Gi
        securityContext:
          allowPrivilegeEscalation: false
          runAsGroup: 20001
          runAsUser: 10001
          runAsNonRoot: true
        name: vllm
        imagePullPolicy: IfNotPresent
        ports:
        - name: http
          containerPort: 8000
        volumeMounts:
        - mountPath: /models
          name: mount-0
          readOnly: true
        - name: runtime-identity
          mountPath: /etc/passwd
          subPath: passwd
          readOnly: true
        - name: runtime-identity
          mountPath: /etc/group
          subPath: group
          readOnly: true
        - name: accessible-operators
          mountPath: /vllm-workspace/vllm-ascend/vllm_ascend/_cann_ops_custom/vendors
          readOnly: true
        startupProbe:
          httpGet:
            path: /health
            port: http
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 180
        readinessProbe:
          httpGet:
            path: /health
            port: http
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
      volumes:
      - name: mount-0
        persistentVolumeClaim:
          claimName: qwen-weights
      - name: runtime-identity
        emptyDir: {}
      - name: accessible-operators
        emptyDir:
          sizeLimit: 256Mi
      initContainers:
      - name: prepare-runtime-identity
        image: quay.io/ascend/vllm-ascend@sha256:11125f9a4bbaecbc05d10f4af0619841f5dd1990623f97e61450e23d832872d3
        imagePullPolicy: IfNotPresent
        command:
        - /bin/bash
        - -c
        - |
          set -eu
          uid="$(id -u)"
          gid="$(id -g)"
          user="uid${uid}"
          group="gid${gid}"
          umask 022
          cp /etc/passwd /identity/passwd
          cp /etc/group /identity/group
          if awk -F: -v u="$user" -v id="$uid" '$1==u && $3!=id {exit 1}' /identity/passwd; then :; else echo 'user name collision' >&2; exit 1; fi
          if ! awk -F: -v id="$uid" '$3==id {found=1} END {exit !found}' /identity/passwd; then
              printf '%s:x:%s:%s:K8s inference user:/tmp:/sbin/nologin\n' "$user" "$uid" "$gid" >> /identity/passwd
          fi
          if awk -F: -v g="$group" -v id="$gid" '$1==g && $3!=id {exit 1}' /identity/group; then :; else echo 'group name collision' >&2; exit 1; fi
          if ! awk -F: -v id="$gid" '$3==id {found=1} END {exit !found}' /identity/group; then
              printf '%s:x:%s:\n' "$group" "$gid" >> /identity/group
          fi
          echo "prepared temporary identity for uid=$uid gid=$gid"
        securityContext:
          runAsUser: 10001
          runAsGroup: 20001
          runAsNonRoot: true
          allowPrivilegeEscalation: false
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: '1'
            memory: 512Mi
        volumeMounts:
        - name: runtime-identity
          mountPath: /identity
      - name: copy-operators-for-user
        image: quay.io/ascend/vllm-ascend@sha256:11125f9a4bbaecbc05d10f4af0619841f5dd1990623f97e61450e23d832872d3
        imagePullPolicy: IfNotPresent
        command:
        - /bin/bash
        - -c
        - |
          set -eu
          src=/vllm-workspace/vllm-ascend/vllm_ascend/_cann_ops_custom/vendors
          test "$(id -u)" = 10001
          test "$(id -g)" = 0
          test -x "$src"
          test -r "$src/custom_transformer/op_api/lib/libcust_opapi.so"
          cp -R "$src"/. /operators/
          test -r /operators/custom_transformer/op_api/lib/libcust_opapi.so
          test -x /operators/custom_transformer/op_api/lib
          echo "operator files copied into Pod temporary volume"
        securityContext:
          runAsUser: 10001
          runAsGroup: 0
          runAsNonRoot: true
          allowPrivilegeEscalation: false
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: '1'
            memory: 512Mi
        volumeMounts:
        - name: accessible-operators
          mountPath: /operators
---
apiVersion: v1
kind: Service
metadata:
  name: qwen-ascend
  namespace: llm-demo
  labels:
    app: qwen-ascend
spec:
  type: ClusterIP
  selector:
    app: qwen-ascend
  ports:
  - name: http
    port: 8000
    targetPort: http

创建前先确认对象名和双卡资源未被其他人占用,再执行:

kubectl create --dry-run=server -f qwen-ascend.yaml
kubectl create -f qwen-ascend.yaml
kubectl get pods -n llm-demo -l app=qwen-ascend -o wide
kubectl get deployment,service -n llm-demo -l app=qwen-ascend

这里使用 kubectl create,同名对象存在时会报错,避免不经核对覆盖已有服务。首次启动要加载权重和编译计算图,可能需要几分钟。Running 只说明容器进程运行,应该继续等待 deployment 1/1 Ready,并查看日志:

kubectl logs -n llm-demo -l app=qwen-ascend -c prepare-runtime-identity
kubectl logs -n llm-demo -l app=qwen-ascend -c copy-operators-for-user
kubectl logs -n llm-demo -l app=qwen-ascend -c vllm --tail=100
kubectl describe pod -n llm-demo -l app=qwen-ascend

7 这些启动参数是什么意思

参数本例值作用
--tensor-parallel-size2两张卡协作处理同一份模型中的计算
--pipeline-parallel-size1不把模型分成多个流水线阶段
--max-model-len8192单次请求输入和输出合计的 token 上限
--gpu-memory-utilization0.85推理引擎规划显存使用的目标比例
--quantizationascend使用与当前 w8a8 文件匹配的昇腾量化实现
--max-num-seqs1引擎一轮最多处理一条序列,其他请求可能排队
--served-model-nameqwen3.8-27b客户端发送请求时使用的模型名

尽管参数名中写着 gpu,在这套适配中它用于控制推理设备的显存预算。0.85 不意味着实际占用一定恰好是 85%,也不是吞吐或并发能力的承诺。环境变量中的 cann、nnal 和算子路径来自本次镜像运行配置;指定 command 会覆盖镜像默认入口,不能只复制一行 vllm serve 而忽略环境初始化。

8 验证是否真的完成推理

先确认推理进程不是 root,以及设备分配和双卡加载情况:

kubectl exec -n llm-demo deployment/qwen-ascend -c vllm -- id
kubectl get pod -n llm-demo -l app=qwen-ascend -o wide
kubectl logs -n llm-demo -l app=qwen-ascend -c vllm --tail=500 | grep -E 'world_size=2|Worker_TP[01].*Loading model weights'
POD=$(kubectl get pod -n llm-demo -l app=qwen-ascend -o jsonpath='{.items[0].metadata.name}')
kubectl get pod -n llm-demo "$POD" -o jsonpath='{.metadata.annotations.huawei\.com/AscendReal}{"\n"}'
kubectl exec -n llm-demo "$POD" -c vllm -- sh -c \
  'readelf -Ws /vllm-workspace/vllm-ascend/vllm_ascend/_cann_ops_custom/vendors/custom_transformer/op_api/lib/libcust_opapi.so | grep aclnnAddRmsNormBias'

上面的注解是本次使用的设备插件提供的信息,其他插件版本可能不同。还应在 npu 节点运行 npu-smi info,查看设备状态、进程和显存变化;并结合 pod 的设备分配及两个 worker 的日志判断。不要只根据 yaml 中写了两张卡,就宣称模型真的使用了两张卡。

service 默认只在集群内部提供访问。在一台有 kubectl 权限的机器上开启本地转发:

kubectl port-forward -n llm-demo service/qwen-ascend 18000:8000

保持此终端运行,在同一台机器的另一个终端执行:

curl --noproxy '*' --fail --silent http://127.0.0.1:18000/health
curl --noproxy '*' --fail --silent http://127.0.0.1:18000/v1/models
curl --noproxy '*' --fail --silent http://127.0.0.1:18000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3.8-27b","messages":[{"role":"user","content":"What is 2 + 3? Answer with a single number."}],"temperature":0,"max_tokens":32,"chat_template_kwargs":{"enable_thinking":false}}'

/health 返回成功状态即可,响应体可能为空;/v1/models 应列出 qwen3.8-27b;聊天接口应在 choices 中返回模型生成的内容。本例不设置 api 密钥,只用于受控的内部验证;正式服务还应根据自己的访问策略配置认证、网络隔离和权限。

本次实际使用官方原版镜像、两张 npu 和普通用户完成了基础验证:健康检查和模型列表返回 http 200,三次短问答依次返回 5、15、5;两个推理 worker 的进程映射显示加载了自定义算子库。首次请求约 50 秒,后续两次约 0.5 秒。这些数字只是单次观察,不是性能报告。

9 普通用户和算子权限

本次原版镜像启动时,普通用户无法遍历自定义算子目录,出现类似算子缺失的错误;使用上面的临时卷后,两个 worker 加载了算子库并完成问答。相同报错也可能有其他原因,不能直接认定都是权限问题。身份解析、算子访问的排查过程及权限边界见普通用户故障排查。

这里使用 root 组读取算子的初始化步骤依赖集群策略,禁止该权限时需评估其他方案;不要直接修改宿主机权限或将推理进程改为 root。

10 清楚这次验证的边界

本次验证覆盖一个已准备的 w8a8 模型、一个普通用户身份、两张 npu 和三次简短问答。它没有覆盖所有用户的镜像和模型授权、长上下文、多并发、吞吐、长期稳定性或生产安全。日志中仍有文件属主和 cpu 亲和性告警,不能因为回答正确就当作告警已经解决。

如果要复现,先检查自己的驱动、设备、存储、身份和网络条件;如果要面向更多用户开放,还要单独完成授权和相应的业务验证。把每一层的结果记录清楚,下一次遇到问题时,才能知道故障发生在设备、镜像、模型还是服务接口。



上一篇
开发工程师的 dots 实用工作流
下一篇
从 tp 和 pp 到 vllm ascend 看懂大模型推理配置