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® 软件栈。
用户可通过执行如下命令在容器中使用沐曦通用GPU：
metax-docker run -it --rm --gpus=all user-application:1.0 /bin/bash
metax-docker支持官方Docker的全部命令及参数，并在 run 命令下支持额外参数，详情参见下表。
参数 |
说明 |
|---|---|
–gpus |
all：将全部卡传递至容器 N：将枚举的前N张卡传递至容器 [ID1,ID2…]：将ID值为ID1和ID2的卡传递至容器 [SN1,SN2…]：将SN值为SN1和SN2的卡传递至容器 “[<sgpu:identifier>,<sgpu:identifier|config>]”：详情参见表 7.2 |
–maca |
若希望使用默认安装路径之外的 MXMACA® ，可使用此参数指定 |
–maca-force |
默认情况下，若容器内/opt/maca路径下已存在 MXMACA® ，metax-docker会停止将主机上的 MXMACA® 安装进容器。设置此参数可强制容器使用主机上的 MXMACA® |
–driver |
若希望使用默认安装路径之外的mxdriver，可使用此参数指定。注：metax-docker需要≥0.8.2 |
备注
挂载sGPU需要的UUID，BDF及index参数，可以通过mx-smi获取。
参数 |
说明 |
|---|---|
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.3. 构建应用软件镜像
用户可根据此节内容构建更加适用于 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.2 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=[SN1,SN2] # 使用SN选卡
# - METAX_VISIBLE_GPUS=[0,<sgpu:0000:0b:00.0#0>] # NativeGPU+sGPU混配
...
7.2.2. 方式2： CDI规范挂载设备
需要使用此方式时，请确保安装时启用了 --cdi-mode=env 来安装metax-docker。
备注
使用CDI规范挂载设备时，Docker版本应当 >= 23.0
配置CDI设备如 metax-tech.com/gpu={id} 进行索引指定选卡或者全选卡。
CDI配置暂时不支持sGPU和UUID/SN选卡。
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