一、基本原则
- 容器里不包含内核驱动，驱动只装在宿主机。
- Container Toolkit 负责在容器启动时把 GPU 设备和用户态驱动库挂载进去。
- 宿主机升级驱动后，需要重启正在运行的容器。
二、安装 MT Container Toolkit
按 容器运行时套件安装指导，安装 mtml 与 mt-container-toolkit 两个 deb 包，再把运行时注册到 Docker。该安装指导写的是 v2.0.0 / Docker 20.10，版本较旧，实际版本号以下载页面为准：
sudo dpkg -i mtml_*.deb mt-container-toolkit_*.deb
(cd /usr/bin/musa && sudo ./docker setup $PWD) # 会把默认运行时设为 mthreads 并自动重启 Docker三、关键环境变量
以下来自 MT Container Toolkit 使用手册：
| 变量 | 取值 | 说明 |
|---|---|---|
MTHREADS_VISIBLE_DEVICES | all、序号（如 0,1）、UUID；void 或不设置 | 选择挂载的 GPU；不设置时与普通 runc 行为一致 |
MTHREADS_DRIVER_CAPABILITIES | compute、graphics、utility、video、all | 默认 compute,utility |
MTHREADS_QOS_MEMORY_LIMIT / MTHREADS_QOS_COMPUTING_POWER_WEIGHT | 按手册 | sGPU 显存上限与算力权重 |
MTHREADS_GDS | enable | 启用 GPU Direct Storage |
在 Kubernetes Pod 中，以同名环境变量的方式使用。
四、官方分层镜像
MUSA SDK 5.2.0 Docker 镜像使用指南 提供三种镜像，标签格式为 registry.mthreads.com/mcconline/musa_sdk:5.2.0-<层>-ubuntu22.04-s5000：
| 层 | 主要内容 | 适用 |
|---|---|---|
| base | musart 运行时与配置 | 最小运行环境 |
| runtime | base + muBLAS 1.13.0、muFFT 1.12.0、muDNN 3.4.0.0、MTML 2.4.2、MCCL 2.4.0、CMake 模块 | 部署运行镜像 |
| devel | runtime + mtcc 5.2.0、moore-perf-system 1.8.0、moore-perf-compute 1.3.0、musify 1.3.0、muPTI 1.3.0、头文件 | 开发、编译、性能分析 |
五、启动开发容器
docker run --rm -it \
-e MTHREADS_VISIBLE_DEVICES=all \
-e MTHREADS_DRIVER_CAPABILITIES=compute,utility \
--shm-size=16g \
-v "$PWD":/workspace -w /workspace \
registry.mthreads.com/mcconline/musa_sdk:5.2.0-devel-ubuntu22.04-s5000 bash没有装 Container Toolkit 时，官方给出了手动挂载设备的方式，大意如下（完整的库挂载列表以官方文档为准）：
docker run --rm -it \
--device /dev/mtgpu0 --device /dev/dri \
-v /usr/lib/x86_64-linux-gnu/libmusa.so.1:/usr/lib/x86_64-linux-gnu/libmusa.so.1 \
registry.mthreads.com/mcconline/musa_sdk:5.2.0-devel-ubuntu22.04-s5000 bash六、容器内验证
musa_version_query
which mcc
musaInfo再编译一个最小程序，确认编译器和运行时都可用：
// vectorAdd.mu
#include <musa_runtime.h>
#include <cstdio>
#include <vector>
__global__ void add(const float* a, const float* b, float* c, int n) {
int i = blockIdx.x * blockDim.x + threadIdx.x;
if (i < n) c[i] = a[i] + b[i];
}
int main() {
const int n = 1 << 20; size_t bytes = n * sizeof(float);
std::vector<float> ha(n, 1.0f), hb(n, 2.0f), hc(n, 0.0f);
float *a, *b, *c;
musaMalloc(&a, bytes); musaMalloc(&b, bytes); musaMalloc(&c, bytes);
musaMemcpy(a, ha.data(), bytes, musaMemcpyHostToDevice);
musaMemcpy(b, hb.data(), bytes, musaMemcpyHostToDevice);
add<<<(n + 255) / 256, 256>>>(a, b, c, n);
musaMemcpy(hc.data(), c, bytes, musaMemcpyDeviceToHost);
printf("c[0] = %f (expect 3.0), err = %s\n", hc[0], musaGetErrorString(musaGetLastError()));
musaFree(a); musaFree(b); musaFree(c);
return 0;
}mcc vectorAdd.mu -lmusart -L/usr/local/musa/lib -o vectorAdd # 官方编译命令
./vectorAdd上面的源码由本站编写，API 与 CUDA Runtime 一一对应（cuda* → musa*）。用 CMake 构建时，官方方式为 find_package(MUSA) 加 musa_add_executable。
七、构建运行镜像
开发用 devel，部署用 runtime，把编译好的产物复制进去：
FROM registry.mthreads.com/mcconline/musa_sdk:5.2.0-runtime-ubuntu22.04-s5000
WORKDIR /app
COPY ./vectorAdd /app/vectorAdd
CMD ["/app/vectorAdd"]八、与推理镜像的关系
vLLM-MUSA 提供单独的推理镜像 registry.mthreads.com/mcconline/inference/vllm/vllm-openai:v0.28.0。据 vLLM-MUSA v0.28.0 docker/README：对 vLLM-MUSA 来说，MUSA_VISIBLE_DEVICES 才是决定可见设备的变量；示例中的 --privileged 仅用于隔离的测试主机，生产环境应换成最小权限的设备策略。详见第 10 模块第 1 课。
九、常见问题
| 现象 | 排查方向 |
|---|---|
| 容器内看不到 GPU | 宿主机 mthreads-gmi 是否正常；Toolkit 是否已注册到 Docker；MTHREADS_VISIBLE_DEVICES 是否设置 |
| 宿主机升级驱动后容器报错 | 重启容器 |
mcc: command not found | 当前使用的是 base 或 runtime 镜像，换 devel |
| S4000 机器上通信异常 | 官方 5.2.0 镜像内置的是 mccl-s5000，仅面向 S5000 |
| DataLoader 报共享内存不足 | 加大 --shm-size |
十、回滚
容器本身是一次性的；回滚只需改回旧镜像标签。若需撤销 Toolkit 的注册，使用官方命令 (cd /usr/bin/musa && sudo ./docker cleanup $PWD)；也建议在 setup 前备份 /etc/docker/daemon.json。