国产 GPU/NPU 与 ARM64 适配总览

本篇是 GPU 与异构算力子目录的入口，概述将 CubeStudio 适配到国产算力卡（GPU/NPU）与 ARM64 架构机器的整体流程。具体厂商的落地步骤见各子篇（如华为昇腾 NPU）。

国产 GPU/NPU 适配通用流程

将任意一款国产算力卡接入 CubeStudio，一般需要完成以下 8 步：

1. GPU/NPU 驱动：联系运维按国产 GPU 厂商要求安装 AI 计算卡驱动。
2. 容器运行时：使算力卡可被 docker 运行时与 containerd 运行时调用。
3. K8s 插件：按厂商提供的 k8s device-plugin 部署到 k8s 集群。
4. 资源占用约定：明确 k8s 资源占用文档——占用的资源名、禁止 pod 占用的环境变量、在 k8s 中占用「指定第 n 张卡」的环境变量配置方法。
5. 监控组件：按厂商提供的资源采集接口配置到 Prometheus，并配置相应的 Grafana 看板。
6. 平台配置：在 config.py 的 GPU_RESOURCE 中加入该国产 GPU 对应的 k8s 资源名，并按需设置默认占用卡 DEFAULT_GPU_RESOURCE_NAME。
7. 环境镜像：按厂商提供的开发环境镜像，配置为 notebook 与 pipeline 的运行镜像。
8. 框架包：按厂商提供的 TF/PyTorch 安装方法，在业务代码中安装并尝试运行。

说明：上述第 6 步对应 myapp/config.py 中的 GPU_RESOURCE（约 myapp/config.py:1242）与 DEFAULT_GPU_RESOURCE_NAME（myapp/config.py:1259，默认值 nvidia.com/gpu）。GPU_RESOURCE 已内置多家国产卡的资源名映射，例如：

• npu310 → huawei.com/Ascend310、npu310p → huawei.com/Ascend310P、npu910 → huawei.com/Ascend910（华为昇腾）
• dcu → hygon.com/dcu（海光）、mlu370 → cambricon.com/mlu370（寒武纪）、mx → metax-tech.com/gpu（沐曦）
• gcu → enrigin.com.cn/gcu（江原）、xpu → kunlunxin.com/xpu（昆仑芯）、mthread → mthreads.com/gpu（摩尔线程）

注意：config.py 注释明确「GPU_RESOURCE 的 key 必须小写；主机的 gpu-type 节点标签必须大写」（见 myapp/config.py:1241）。

以华为昇腾卡为例

华为昇腾 NPU 的落地流程（详见子篇《华为昇腾 NPU》）：

1. NPU 驱动安装。
2. 安装 Ascend Docker Runtime。
3. 将 docker NPU device 适配到云原生，使 k8s 可识别/使用 NPU 硬件。
4. 在配置文件中添加对 NPU k8s 资源的占用方式，并设置 CubeStudio 的机器卡型。
5. 部署 npu-exporter，配置 NPU k8s 监控看板，掌握资源使用情况。
6. 在 config.py 的 GPU_RESOURCE 中添加 huawei.com/Ascend910（对应 key npu910）。
7. 构建 NPU 基础镜像（开发/调试/推理），用于写代码、训练模型。
8. 构建昇腾 MindIE 推理镜像，使其在 k8s 中直接运行并提供 API。

详细步骤见 华为昇腾 NPU 子目录。

ARM64 机器部署

部署 Rancher

与 x86 架构相同。

部署 cube-studio

先按与 x86 架构相同的方式部署。部署完成后不一定全部功能正常，因为部分镜像没有 arm64 版本，需替换为 arm64 版本的镜像。

构建 arm64 版本镜像

主机 docker 构建 arm64 镜像环境初始化：

docker buildx create --use --platform=linux/arm64,linux/amd64 --name multi-platform-builder
docker buildx inspect --bootstrap
# 然后就可以同时构建 amd64 和 arm64 的镜像了
docker buildx build --platform=linux/arm64,linux/amd64 --push --tag project-name:latest -f ./project-name/Dockerfile .

1. CubeStudio 第三方基础组件，当前版本已适配 arm64。
2. 若修改了源码，可自行在 arm64 机器上重新构建 CubeStudio 前后端镜像：

docker build --network=host -t xx.xx.xx.xx/cube-studio/kubeflow-dashboard:arm64 -f install/docker/Dockerfile .
docker build --network=host -t xx.xx.xx.xx/cube-studio/kubeflow-dashboard-frontend:arm64 -f install/docker/dockerFrontend/Dockerfile .

说明：install/docker/Dockerfile 未使用 ARG TARGETARCH（见 install/docker/Dockerfile:1-4），因此无需传 --build-arg TARGETARCH=arm64；在 arm64 机器上直接 docker build 即按本机架构构建出 arm64 镜像。如需在单台机器上同时构建 amd64/arm64，可参考 Dockerfile 顶部注释的 buildx 多架构命令：docker buildx build --platform linux/amd64,linux/arm64 -t ...-enterprise:<日期tag> -f install/docker/Dockerfile . --push（后端），前端对应 install/docker/dockerFrontend/Dockerfile。

3. notebook 镜像的 arm64 版本目前仅支持 vscode 和 jupyter，修改 config.py 中的 NOTEBOOK_IMAGES：

NOTEBOOK_IMAGES=[
    ['ccr.ccs.tencentyun.com/cube-studio/notebook-enterprise:vscode-ubuntu-cpu-conda-arm64', 'vscode-conda（cpu）'],
    ['ccr.ccs.tencentyun.com/cube-studio/notebook-enterprise:vscode-ubuntu-gpu-conda-arm64', 'vscode-conda（gpu）'],
    ['ccr.ccs.tencentyun.com/cube-studio/notebook-enterprise:jupyter-ubuntu-cpu-conda-arm64', 'jupyter-conda（cpu）'],
    ['ccr.ccs.tencentyun.com/cube-studio/notebook-enterprise:jupyter-ubuntu-gpu-conda-arm64', 'jupyter-conda（gpu）'],
]

说明：以上为 arm64 部署时的示例镜像列表（带 -arm64 后缀）。config.py 默认的 NOTEBOOK_IMAGES（见 myapp/config.py:998）使用的是 amd64 / 带日期标签的镜像（如 vscode-ubuntu-cpu-conda-20260101），在 arm64 机器上需替换为 arm64 版本。

4. 任务模板镜像：只有部分模板包含 amd64 版本；对于没有 arm64 版本镜像的模板，需自己在 arm64 机器上重新构建模板镜像。

构建方法：

cd job-template && sh build-job-arm64.sh

⚠️ 待核实：仓库中未找到 job-template/build-job-arm64.sh（见 job-template/ 目录，当前仅有 build-job-encryption.sh）。build-job-encryption.sh 采用 docker buildx build --platform linux/amd64,linux/arm64 ... --push 进行多架构构建（见 job-template/build-job-encryption.sh:8）。请确认 arm64 模板镜像的实际构建脚本/方法。模板镜像的构建方式可参考二次开发段的镜像构建文档。