7.1. MetaX Docker

沐曦通用GPU提供的metax-docker工具，是基于官方Docker的扩展工具，用于解决GPU选择过程繁琐以及应用镜像体积庞大的问题。用户可独立发布不包含 MXMACA^® 软件栈的容器镜像，并借助metax-docker工具在运行时获得一个完整的运行环境。

图 7.1 MetaX Docker

7.1.1. 安装metax-docker

安装metax-docker需要使用名称格式为 metax-docker_<VERSION>.tar 的离线压缩包。用户可解压后根据安装环境选择合适的包进行安装。

操作步骤

在终端上使用以下命令安装metax-docker(以0.15.3版本为例)。

mkdir metax-docker
tar -C metax-docker -xvf metax-docker_0.15.3.tar
cd metax-docker
sudo ./metax-docker_0.15.3.<ARCH>.run
# 如果用户需要在Docker Compose场景下使用CDI挂载沐曦设备，请启用 --cdi-mode=env
# sudo ./metax-docker_0.15.3.<ARCH>.run -- --cdi-mode=env

7.1.2. 使用metax-docker

用户需要安装版本≥19.03的Docker工具。同时应确保主机上已经正确安装了 MXMACA^® 软件栈。

metax-docker支持官方Docker的全部命令及参数，并支持自定义子命令如下:

表 7.1 metax-docker子命令和参数
子命令	说明
run	创建并运行容器，在容器中使用沐曦通用GPU
create	创建并运行容器，在容器中使用沐曦通用GPU
assemble	基于本地镜像与沐曦软件栈包，构建包含沐曦软件栈的新镜像

7.1.3. 使用metax-docker assemble 构建携带沐曦软件栈的镜像

示例：用户有自有镜像 ubuntu:22.04 ,需要额外追加 maca-sdk 。

校验基础镜像、沐曦软件栈包的架构为一致。
指定基础镜像名称，如 ubuntu:22.04 , 填入 --base 参数。
指定需要追加到镜像内的内容，例如maca sdk maca-sdk-x.x.x.x-deb-x86_64.tar.xz ,填入 --new-layer 参数，支持一次通过多个 --new-layer 参数添加多个内容。
指定追加层构建完成后，新镜像的标签名称，例如 ubuntu:22.04-macaxx 填入 --new-tag 参数。
指定目标镜像架构，需与基础镜像、沐曦软件栈包架构保持一致，填入 --platform 参数。

metax-docker assemble --base ubuntu:22.04 --new-layer maca-sdk-x.x.x.x-deb-x86_64.tar.xz --new-tag ubuntu:22.04-macaxx --platform amd64

metax-docker在 assemble 命令下支持额外参数，详情参见下表。

表 7.2 metax-docker assemble额外支持的参数
参数	说明
–base	本地镜像，将在该镜像基础上追加沐曦软件栈
–new-layer	沐曦软件栈资源，支持合规目录、.run 文件、.tar.xz 压缩包
–new-tag	构建完成后输出镜像的名称与标签
–platform	新镜像对应的硬件架构，需与基础镜像、沐曦软件栈包架构保持一致，例如amd64
–cache(可选参数)	指定本机地址作为缓存目录，加速镜像构建

7.1.4. 使用metax-docker run/create 快速启动使用携带metax-gpu且挂载相关软件栈的容器

用户可通过执行如下命令在容器中使用沐曦通用GPU：

metax-docker run -it --rm --gpus=all user-application:1.0 /bin/bash

metax-docker支持官方Docker run/create的全部命令及参数，并在 run 命令下支持额外参数，详情参见下表。

表 7.3 metax-docker run额外支持的参数
参数	说明
–gpus	all：将全部卡传递至容器 N：将枚举的前N张卡传递至容器 [ID1,ID2…]：将ID值为ID1和ID2的卡传递至容器 [UUID1,UUID2…]：将UUID值为UUID1和UUID2的卡传递至容器 “[<sgpu:identifier>,<sgpu:identifier\|config>]”：详情参见表 7.4
–maca	若希望使用默认安装路径之外的 MXMACA^® ，可使用此参数指定
–maca-force	默认情况下，若容器内/opt/maca路径下已存在 MXMACA^® ，metax-docker会停止将主机上的 MXMACA^® 安装进容器。设置此参数可强制容器使用主机上的 MXMACA^®
–mxdriver	若希望使用默认安装路径之外的mxdriver，可使用此参数指定。注：metax-docker需要≥0.8.2

备注

挂载sGPU需要的UUID，BDF及index参数，可以通过mx-smi获取。

表 7.4 metax sgpu Options
参数	说明
identifier	UUID BDF#index
config （多项之间使用 `;` 隔开）	alias=<string> 设置sGPU别名 compute=<int> 设置算力配额百分比，输入范围<0-100> vram=<int> 设置显存大小，默认单位为MB

备注

挂载GPU前，需要确认GPU没有开启sGPU模式。开启sGPU模式的GPU，不能挂载到容器中。

检查GPU是否开启sGPU模式：

mx-smi sgpu --show-mode

Attached GPUs                 :4
GPU#0 MXC500 0000:09:00.0
                sgpu mode:    :Enable
GPU#1 MXC500 0000:0a:00.0
                sgpu mode:    :Disable
GPU#2 MXC500 0000:0b:00.0
                sgpu mode:    :Disable
GPU#3 MXC500 0000:0c:00.0
                sgpu mode:    :Disable

当 sgpu mode 为 Disable 时，代表GPU没有开启sGPU模式，可以通过 --gpus 参数挂载到容器中。

7.1.5. 构建应用软件镜像

用户可根据此节内容构建更加适用于 MetaX Docker 以及云场景的容器镜像。

操作步骤

假设用户软件具有如下目录结构，源代码放置在项目的src目录下。

samples/
   ├──Dockerfile
   └──src
       ├──Makefile
       ├──sample1.cpp
       └──sample2.cpp

用户可使用如下内容的Dockerfile制作应用软件镜像。

#intermediate builder image
FROM cr.metax-tech.com/library/mxc500-maca:2.24.0.0 AS builder

WORKDIR/workspace

COPY src src

#build user application and put artifacts under /workspace/dist

RUN make -C ./src OUT=./dist

#artifact mage
FROM ubuntu:20.04
RUN apt-get update && \
  apt-get install -y libnuma1 libelf1 && \
  apt-get clean
COPY --from=builder /workspace/dist /applications
CMD ["/applications/foo"]

完成Dockerfile的编写后，用户可在项目根目录下执行如下命令完成镜像的构建。
```
docker build -t user-application:1.0 .
```

7.2. Docker Compose 支持

metax-docker 于 0.16.0 引入了 Docker Compose 支持。

metax-docker 提供以下2种导入设备的方式以支持用户通过docker compose拉起包含Metax GPU的容器：

7.2.1. 方式1：环境变量注入

配置 METAX_VISIBLE_GPUS 环境变量选卡，支持全选，数量选卡，指定选卡。

在使用指定选卡时，支持sGPU和Native GPU混配，sGPU配置详情参见表 7.4 metax sgpu Options。

docker-compose.yml 样例如下：

version: '3.8'

services:
  env-gpu-all:
    ...
    runtime:metax  # 强制选择metax-runtime作为运行时
    enviroment:
      - METAX_VISIBLE_GPUS=all  # 全选
      # - METAX_VISIBLE_GPUS=2  # 选前2张卡
      # - METAX_VISIBLE_GPUS=[2]  # 选第3张卡
      # - METAX_VISIBLE_GPUS=[UUID1,UUID2]  # 使用UUID选卡
      # - METAX_VISIBLE_GPUS=[0,<sgpu:0000:0b:00.0#0>]  # NativeGPU+sGPU混配
    ...

7.2.2. 方式2： CDI规范挂载设备

需要使用此方式时，请确保安装时启用了 --cdi-mode=env 来安装metax-docker。

如果未使用 --cdi-mode=env 来安装 metax-docker，可以参考 GPU 设备变更后的 CDI 设备列表更新来手动注册 CDI Spec 以使用 CDI 规范挂载设备。

备注

使用CDI规范挂载设备时，Docker版本应当 >= 23.0

配置CDI设备如 metax-tech.com/gpu={id} 进行索引指定选卡或者全选卡。

CDI配置暂时不支持sGPU和UUID选卡。

docker-compose.yml 样例如下：

version: '3.8'

services:
  env-gpu-all:
    ...
    runtime:metax  # 强制选择metax-runtime作为运行时
    devices:
      - metax-tech.com/gpu=0  # 选第1张
      - metax-tech.com/gpu=1  # 选第2张
      # - metax-tech.com/gpu=all  # 全选
    ...

7.2.3. GPU 设备变更后的 CDI 设备列表更新

CDI 规范要求将可用设备信息生成到静态设备描述文件 /etc/cdi/metax.json 中。安装 MetaX 软件时，安装程序会根据当前节点上的 GPU 硬件配置自动生成该文件。

当节点上的 GPU 硬件配置发生变化（例如新增、移除或更换 GPU）后，需要根据最新的硬件状态重新生成 CDI 设备描述文件。安装程序会根据系统环境自动配置相应的更新机制：

systemd 系统：自动创建 metax-cdi-generator.service，在系统启动时自动重新生成 CDI 设备描述文件。
非 systemd 系统：如果系统安装了 cron，自动创建 /etc/cron.d/metax-cdi-generator，在系统启动时自动重新生成 CDI 设备描述文件。

如果系统既不支持 systemd，也未安装 cron，则无法自动完成 CDI 设备描述文件的更新。此时，在 GPU 硬件配置发生变化并重启系统后，请运维人员手动执行以下命令重新生成 CDI 设备描述文件：

sudo mx-ctk-installer --generate-cdi