5. sGPU介绍

sGPU是软件实现的算力切分方案，可以基于物理GPU创建最多16个虚拟GPU实例，主要面向基于容器的云端推理和小模型训练场景。

5.1. 在单机场景下使用sGPU

5.1.1. 基础环境要求

  • Docker版本≥19.03

  • 主机上已经正确安装了 MXMACA® SDK和内核态驱动

5.1.2. 安装metax-docker

  1. 获取安装包

    以 0.15.1 版本为例，从 沐曦软件中心 获取离线安装包 metax-docker_0.15.1.tar。

  2. 解压并安装

    mkdir metax-docker
tar -C metax-docker -xvf metax-docker_0.15.1.tar
cd metax-docker
sudo ./metax-docker_0.15.1.<ARCH>.run

  3. 验证安装

    metax-docker version

    显示metax-docker版本，代表安装成功。

5.1.3. 开启/停用sGPU功能

  1. 检查GPU设备状态

    mx-smi -L
GPU#序号    GPU版本 BDF         状态(UUID)
GPU#0       MXC500 0000:08:00.0 Available(UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
GPU#1       MXC500 0000:09:00.0 Available(UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

    当状态栏显示 Available 时，代表GPU状态正常。

  2. 查看当前GPU模式

    mx-smi sgpu --show-mode

    观察显示结果中 sgpu mode， Disable 代表未开启sGPU功能， Enable 代表开启sGPU功能。

  3. 配置sGPU模式

    • 开启sGPU：

      mx-smi sgpu -i UUID --enable

    • 关闭sGPU：

      mx-smi sgpu -i UUID --disable

5.1.4. 创建/销毁sGPU资源

  1. 创建sGPU资源

    在GPU <BDF>/UUID/deviceId 上，创建一个显存配额128M，计算资源配额为30%的sGPU。

    mx-smi sgpu -i <BDF>/UUID/deviceId -c --vram 128M --compute 30

  2. 验证sGPU创建

    mx-smi -L
GPU#0       MXC500 0000:08:00.0 Available   (UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
        SGPU#(sgpuid) vram compute     状态        (UUID)
        SGPU#0        30%  0.125gb     Available   (UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
GPU#1       MXC500 0000:09:00.0 Available   (UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

    当出现高亮第二行类似内容，且vram和compute参数和创建时传参一致，则代表sGPU设备创建成功。

  3. 销毁sGPU资源

    mx-smi sgpu -i <BDF>/UUID/deviceId -r sgpuid

  4. 验证sGPU销毁

    mx-smi -L
GPU#0       MXC500 0000:08:00.0 Available   (UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
GPU#1       MXC500 0000:09:00.0 Available   (UUID: GPU-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

    sGPU不再显示，代表sGPU资源已被销毁。

5.1.5. 在容器中挂载sGPU

  1. 挂载sGPU到容器

    使用metax-docker的 --gpus=[<sgpu:UUID>,<sgpu:UUID>] 参数，将sGPU挂载到容器中。

    metax-docker run -it --rm --gpus="[<sgpu:GPU-24ed2eec-7f19-7945-4c9f-825439238327>, <sgpu:GPU-24342eec-ab19-7901-4c9f-125914288327>]" ubuntu:18.04 /bin/bash

  2. 验证sGPU挂载

    mx-smi -L

    当显示sgpu设备数量和挂载数量相同且配置相等时，代表sGPU挂载成功。

    更多 metax-docker 使用方案，参见《沐曦通用GPU云原生参考手册》。

5.2. 在K8s场景下使用sGPU

通过 gpu-scheduler 或 HAMi 均可使用 sGPU，推荐使用 gpu-scheduler 方案。更多详情参见 基于k8s的GPU调度方案。 用户可根据具体需求选择对应的调度解决方案并阅读对应章节。

无论选择何种调度解决方案，均需要安装 GPU Operator 组件，以下步骤为准备 GPU Operator 的前置资源。

5.2.1. 准备 GPU Operator 所需的前置资源

备注

关于 GPU Operator 所依赖的前置资源，参见《沐曦通用GPU云原生参考手册》中“安装与维护”章节。

  1. 获取安装包

    以 0.15.1 版本为例，从 沐曦软件中心 下载离线安装包 metax-gpu-k8s-package.0.15.1.tar.gz，解压后获取以下文件：

    • metax-k8s-images.0.15.1.run：镜像资源包

    • metax-operator-0.15.1.tgz：Operator Helm Chart

    • metax-gpu-extensions-0.15.1.tgz：Extensions Helm Chart

  2. 准备内核驱动和 MXMACA® SDK 镜像

    GPU Operator 会自动管理节点上的内核驱动及 MXMACA® SDK 的部署与更新，需确保所有工作节点均可正常拉取相关镜像资源。

    内核驱动与 MXMACA® SDK 可从 沐曦软件中心 下载。

    资源包格式：

    • 内核驱动镜像包

      metax-k8s-driver-image.<VERSION>-<ARCH>.run：包含内核态驱动和配套 mx-smi 工具的资源包

    • MXMACA® SDK 镜像包

      随 MXMACA® 的发布包发布，例如 maca-native:<VERSION>-<DISTRO>-<ARCH>.container.xz 或者 maca-c500-container-*.xz

  3. 推送镜像

    # 假设容器仓库服务器域名为 DOMAIN ，用于存放沐曦Kubernetes组件镜像的项目名为 PROJECT。
# 默认使用docker进行镜像推送
metax-k8s-images.0.15.1.run push DOMAIN/PROJECT
# 使用nerdctl进行镜像推送
metax-k8s-images.0.15.1.run nerdctl push DOMAIN/PROJECT

    备注

    • 自 0.13.0 起，该工具支持多种运行时：docker、nerdctl、ctr。

    • 若未显式指定，默认使用docker。若主机未安装docker，系统将自动检测可用运行时并执行镜像推送。

    • 若远程registry为http协议registry，push方式参见《沐曦通用GPU云原生参考手册》“支持”章节。

  4. 推送 Helm Charts

    helm push ./k8s/metax-operator-0.15.1.tgz oci://DOMAIN/PROJECT

5.2.2. gpu-scheduler 方案

5.2.2.1. 安装 GPU Operator

  1. 安装 GPU Operator

    • 若集群内所有节点都需要启用 sGPU 功能

    以容器镜像仓库地址为 DOMAIN/PROJECT 为例，在 Kubernetes 管理节点执行以下命令安装 GPU Operator 。

    helm install ./k8s/metax-operator-0.15.1.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT \
  --set gpuScheduler.deploy=true \
  --set gpuScheduler.version=v2 \
  --set gpuDevice.config.mode=sgpu \
  --set gpuDevice.config.sgpuHybrid=false \
  --set gpuDevice.config.deviceAllocationStrategy=cdi-env

    • 若集群内部分节点需要启用 sGPU 功能

    以容器镜像仓库地址为 DOMAIN/PROJECT 为例，在 Kubernetes 管理节点执行以下命令安装 GPU Operator 。

    helm install ./k8s/metax-operator-0.15.1.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT \
  --set gpuScheduler.deploy=true \
  --set gpuScheduler.version=v2

    在 Kubernetes 管理节点执行以下命令创建 ConfigMap 配置集群级别和节点级别的 gpu-device 的运行模式。 参考以下配置将 sample-node1 节点配置为 sgpu 模式。

    cat << "EOF" | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: metax-device-config
  namespace: metax-operator
data:
  version: v1
  cluster-config: |
    mode: "native"
  nodes-config: |
    - nodeName: "sample-node1"
      mode: "sgpu"
      sgpuHybrid: false
      deviceAllocationStrategy: "cdi-env"
EOF

  2. 验证安装状态

    在 Kubernetes 管理节点执行以下命令检查 Pod 是否处于 Running 状态。

    kubectl get pod -n metax-operator
NAME                                           READY   STATUS      RESTARTS   AGE
metax-container-runtime-4lsd7                  1/1     Running     0          31s
metax-gpu-device-7774b                         1/1     Running     0          31s
metax-gpu-label-l5tkf                          1/1     Running     0          31s
metax-gpu-scheduler-69b58895fd-gcgcz           2/2     Running     0          31s
metax-operator-1755847288-77bfc94568-7wqlh     1/1     Running     0          31s
...

  3. 检查节点资源配置

    以 sample-node1 节点为例，在 Kubernetes 管理节点执行以下命令检查节点资源配置。

    kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/sgpu")))'

# 示例输出
{
  "metax-tech.com/sgpu": "128"
}

5.2.2.2. 编写任务 YAML

创建 sample.yaml，用户可参考以下示例编写任务文件。

apiVersion: v1
kind: Pod
metadata:
  name: sample-pod
spec:
  schedulerName: metax-gpu-scheduler
  containers:
    - name: ubuntu
      image: ubuntu:22.04
      imagePullPolicy: IfNotPresent
      command: ['bash', '-c']
      args: ["sleep infinity"]
      resources:
        limits:
          metax-tech.com/sgpu: 1 # requesting 1 GPU
          metax-tech.com/vcore: 60 # requesting 60% compute of full GPU
          metax-tech.com/vmemory: 4 # requesting 4 GiB device memory of full GPU

5.2.2.3. 提交任务

在 Kubernetes 管理节点执行以下命令提交任务。

kubectl create -f sample.yaml

5.2.2.4. 检查调度结果

在 Kubernetes 管理节点执行以下命令检查任务的调度节点。

kubectl get pod -owide
NAME                        READY   STATUS      RESTARTS   AGE   NODE
sample-pod                  1/1     Running     0          31s   sgpu-node

5.2.2.5. 检查 sGPU 设备

检查 sGPU 设备是否与预期一致。

kubectl exec -it sample-pod -- mx-smi sgpu
mx-smi version: 2.2.1
==================== MetaX System Management Interface Log ====================
Timestamp                           : Tue Jan  6 10:22:39 2026
Attached GPUs                       : 1
+------------------------------------------------------------------------------+
| Gpu 0             TS(ms): 10          Sched-Class: best effort               |
+------------------------------------------------------------------------------+
| SgpuId   Minor     Priority    Vram Quota(MB)    Compute Quota         Alias |
|==============================================================================|
|   0       002       Normal         4096          60%   k8s:sample-pod:ubuntu |
+------------------------------------------------------------------------------+

5.2.3. HAMi 方案

5.2.3.1. 安装 GPU Operator

  1. 安装 GPU Operator

    • 若集群内所有节点都需要启用 sGPU 功能

    以容器镜像仓库地址为 DOMAIN/PROJECT 为例，在 Kubernetes 管理节点执行以下命令安装 GPU Operator 。

    helm install ./k8s/metax-operator-0.15.1.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT \
  --set gpuDevice.sGPUHybridMode=true

    • 若集群内部分节点需要启用 sGPU 功能

    以容器镜像仓库地址为 DOMAIN/PROJECT 为例，在 Kubernetes 管理节点执行以下命令安装 GPU Operator 。

    helm install ./k8s/metax-operator-0.15.1.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT

    在 Kubernetes 管理节点执行以下命令创建 ConfigMap 配置集群级别和节点级别的 gpu-device 的运行模式。 参考以下配置将 sample-node1 节点配置为 sgpu 模式。

    cat << "EOF" | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: metax-device-config
  namespace: metax-operator
data:
  version: v1
  cluster-config: |
    mode: "native"
  nodes-config: |
    - nodeName: "sample-node1"
      mode: "sgpu"
EOF

  2. 验证安装状态

    在 Kubernetes 管理节点执行以下命令检查 Pod 是否处于 Running 状态。

    kubectl get pod -n metax-operator
NAME                                           READY   STATUS      RESTARTS   AGE
metax-container-runtime-4lsd7                  1/1     Running     0          31s
metax-gpu-device-7774b                         1/1     Running     0          31s
metax-gpu-label-l5tkf                          1/1     Running     0          31s
metax-operator-1755847288-77bfc94568-7wqlh     1/1     Running     0          31s
...

  3. 检查节点资源配置

    以 sample-node1 节点为例，在 Kubernetes 管理节点执行以下命令检查节点资源配置。

    kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/sgpu")))'

# 示例输出
{
  "metax-tech.com/sgpu": "128"
}

5.2.3.2. 安装 HAMi

备注

HAMi 版本需≥2.6.0。

  1. 安装 HAMi

    在 Kubernetes 管理节点执行以下命令安装 HAMi 。

    helm repo add hami-charts https://project-hami.github.io/HAMi/
helm install hami hami-charts/hami -n hami --create-namespace

    更多相关信息可参见 通过 Helm 在线安装（推荐）。 如果集群无法直接访问外部网络，操作步骤参见离线安装 。

  2. 验证安装状态

    在 Kubernetes 管理节点执行以下命令检查 Pod 是否处于 Running 状态。

    kubectl get pod -n hami
NAME                                           READY   STATUS      RESTARTS   AGE
hami-scheduler-5888f74b95-l8s6p                2/2     Running     0          31s

5.2.3.3. 编写任务 YAML

创建 sample.yaml，用户可参考以下示例编写任务文件。

apiVersion: v1
kind: Pod
metadata:
  name: sample-pod
spec:
  schedulerName: hami-scheduler
  containers:
    - name: ubuntu
      image: ubuntu:22.04
      imagePullPolicy: IfNotPresent
      command: ['bash', '-c']
      args: ["sleep infinity"]
      resources:
        limits:
          metax-tech.com/sgpu: 1 # requesting 1 GPU
          metax-tech.com/vcore: 60 # requesting 60% compute of full GPU
          metax-tech.com/vmemory: 4 # requesting 4 GiB device memory of full GPU

5.2.3.4. 提交任务

在 Kubernetes 管理节点执行以下命令提交任务。

kubectl create -f sample.yaml

5.2.3.5. 检查调度结果

在 Kubernetes 管理节点执行以下命令检查任务的调度节点。

kubectl get pod -owide
NAME                        READY   STATUS      RESTARTS   AGE   NODE
sample-pod                  1/1     Running     0          31s   sgpu-node

5.2.3.6. 检查 sGPU 设备

检查 sGPU 设备是否与预期一致。

kubectl exec -it sample-pod -- mx-smi sgpu
mx-smi version: 2.2.1
==================== MetaX System Management Interface Log ====================
Timestamp                           : Tue Jan  6 10:22:39 2026
Attached GPUs                       : 1
+------------------------------------------------------------------------------+
| Gpu 0             TS(ms): 10          Sched-Class: best effort               |
+------------------------------------------------------------------------------+
| SgpuId   Minor     Priority    Vram Quota(MB)    Compute Quota         Alias |
|==============================================================================|
|   0       002       Normal         4096          60%   k8s:sample-pod:ubuntu |
+------------------------------------------------------------------------------+