7. 容器相关场景支持

曦云系列GPU提供对Docker和Kubernetes的支持。Kubernetes的详细介绍，参见《曦云^® 系列通用GPU云原生参考手册》。

7.1. 官方Docker支持

开发人员可以借助于容器引擎，运行预先构建好的容器镜像，快速建立软件开发或运行所需的环境。曦云系列GPU提供预构建的MXMACA容器镜像。开发人员仅需执行一条 docker run 命令就可获得一个干净而完整的板卡开发环境。

在运行MXMACA容器镜像前，请确认环境满足以下条件：

已正确安装曦云GPU的内核驱动。详细内容请参见 3 安装与维护。
已安装Docker，Docker版本≥19.03。

7.1.1. 获取MXMACA容器镜像

MXMACA容器镜像是以离线形式发布。用户可在随本文档发布的软件包中找到相关压缩包。本文档中以maca-native-3.5.3.0-ubuntu22.04-amd64.container.xz为例，用户应根据实际收到的软件包版本对版本字段进行相应替换。

操作步骤

执行以下命令，完成容器镜像的加载。

docker load < ./maca-native-3.5.3.0-ubuntu22.04-amd64.container.xz

7.1.2. 在Docker容器中使用板卡

7.1.2.1. 使用全部GPU

操作步骤

执行以下命令：

docker run -it --device=/dev/mxcd --device=/dev/dri --group-add video \
cr.metax-tech.com/library/maca-native:3.5.3.0-ubuntu22.04-amd64 /bin/bash

7.1.2.2. 使用指定GPU

正确安装内核驱动后，默认在/dev/dri目录下为每一个GPU创建了一个card设备文件和一个renderD设备文件。通过绑定设备文件来指定期望使用的板卡。如何确认板卡的ID与/dev/dri目录下设备文件之间的对应关系，请参见 7.1.3 GPU设备文件查询。

操作步骤

例如，指定的板卡所对应的设备文件为/dev/dri/card1和/dev/dri/renderD129。

执行以下命令：

docker run -it --device=/dev/mxcd --device=/dev/dri/card1 \
--device=/dev/dri/renderD128 --group-add video \
cr.metax-tech.com/library/maca-native:3.5.3.0-ubuntu22.04-amd64 /bin/bash

7.1.3. GPU设备文件查询

操作步骤

使用 mx-smi 工具来查看。

mx-smi --show-sysinfo

输出如下：

mx-smi version: 2.3.1

================== MetaX System Management Interface Log ==================
Timestamp                                  : Mon Jan 20 10:00:00 2026

Attached GPUs                              : 3

GPU#0  MXC500 0000:0e:00.0
   Sys info
      driver gpu id         : 22597
      node id               : 2
      render id             : renderD128
      card id               : card1

GPU#1  MXC500 0000:11:00.0
   Sys info
      driver gpu id         : 24589
      node id               : 3
      render id             : renderD129
      card id               : card2