沐曦 GPU 适配（C500）

本文以沐曦曦云 C500 为例，介绍如何在 k8s 中接入沐曦 GPU 并在 CubeStudio 上做全流程适配。合并自 install/kubernetes/gpu/metax/readme.md（适配测试）与 install/kubernetes/gpu/metax/部署device exporter.md（驱动/插件/exporter 安装）。

资料与镜像地址：

• 软件下载（C500 分层包）：https://developer.metax-tech.com/softnova/tools?package_kind=DC&dimension=metax&chip_name=%E6%9B%A6%E4%BA%91C500%E7%B3%BB%E5%88%97&deliver_type=%E5%88%86%E5%B1%82%E5%8C%85
• 镜像下载：https://developer.metax-tech.com/softnova/docker
• 安装与维护文档：https://developer.metax-tech.com/api/client/document/preview/864/split_files/%E5%AE%89%E8%A3%85%E4%B8%8E%E7%BB%B4%E6%8A%A4.html
• k8s 接入文档：https://developer.metax-tech.com/api/client/document/preview/897/k8s/02_start.html

1. 机器环境初始化

1. 安装沐曦驱动（参考上面"安装与维护"文档）；
2. 安装 docker 运行时；
3. 用 mx-smi 查看主机设备，确认驱动与运行时正常：

2. 平台侧资源配置（GPU_RESOURCE）

沐曦 GPU 的 k8s 扩展资源名为 metax-tech.com/gpu（install/docker/config.py:1196 的 GPU_RESOURCE）：

GPU_RESOURCE = {
    ...
    "mx": "metax-tech.com/gpu",   # 沐曦 C500 GPU
    ...
}

在项目组 / 任务里用 1(mx) 这种 数量(资源简称) 写法占用沐曦卡，括号内的 mx 即上面定义的 key。

补充能力：

• 分布式训练：分布式任务模板侧同样内置 mx → metax-tech.com/gpu 映射（job-template/job/pkgs/k8s/py_k8s.py:39），TF / PyTorch 等分布式训练任务可直接申请沐曦卡；
• sGPU 虚拟化预置：平台部署的 HAMi 调度配置已预置沐曦虚拟化资源——metax-tech.com/sgpu（切分数量）、vcore（算力核）、vmemory（显存）三维切分（install/kubernetes/gpu/vgpu/vgpu.yaml:173-185），如需单卡多任务共享可按 HAMi 官方文档启用。

3. 安装 device-plugin（metax-operator）

每台机器执行（以 0.13.2 版本包为例）：

tar xzf metax-gpu-k8s-package.0.13.2.tar.gz

# 镜像加载
./metax-k8s-images.0.13.2.run load          # 加载到 docker
./metax-k8s-images.0.13.2.run nerdctl load  # 加载到 containerd

# 镜像推送到仓库
./metax-k8s-images.0.13.2.run push DOMAIN/PROJECT          # 默认 docker 推送
./metax-k8s-images.0.13.2.run nerdctl push DOMAIN/PROJECT  # nerdctl 推送

# 用本地镜像安装（镜像已通过 run load 加载到所有节点）
helm install ./metax-operator-0.13.2.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait

部署后查看 k8s node 详情，可看到 metax-tech.com/gpu 资源：

k8s pod 即可占用沐曦 GPU，pod 内可用 mx-smi 查看分配到的卡：

4. 安装 exporter（mx-exporter）

每台主机部署 mx-exporter（DaemonSet），用于上报 GPU 监控指标：

unzip mx-exporter.zip
cd mx-exporter/deployment/mx-exporter
kubectl create -f mx-exporter-daemonset.yaml

# 验证指标
curl <mx-exporter_pod_ip>:<mx-exporter_service_port>/metrics

Grafana 看板 json：mx-exporter/deployment/grafana-dashboard/MetaX-GPU-C500.json。

5. CubeStudio 全流程适配能力

沐曦 C500 已在 CubeStudio 上完成大模型全流程适配：

Jupyter 在线开发：

资源占用查看 / Grafana 资源监控：

Pipeline 大模型训练：

推理服务网关（网关名称对应推理服务中的"模型名称-模型版本"）：

预训练模型推理（服务状态为 online 表示已启动）：

更多操作截图见 install/kubernetes/gpu/metax/readme.md（共 28 张全流程记录）。

6. 沐曦基础镜像

平台整理的沐曦镜像（config 中默认注释，按需启用）：

• 开发 / 训练（PyTorch，MACA）：ccr.ccs.tencentyun.com/cube-studio/maca-c500-pytorch:2.23.0.5-ubuntu22.04-x86_64（install/docker/config.py:1039）；
• 推理 / 微调（LLaMA-Factory）：ccr.ccs.tencentyun.com/cube-studio/llama-factory:20250601（install/docker/config.py:1275 注释，沐曦 / 昇腾共用）。