海光 DCU 适配

在 CubeStudio 上接入海光 DCU 算力，需要装驱动、部署 k8s device plugin、配置整卡/共享/虚拟化(vDCU)资源时读这篇

02-部署安装 / GPU与异构算力

海光DCUhygonhygon.com/dcudcu-device-pluginvDCUvdcudcunumdcumemdcucoreshamiMIGhy-smiDTKROCmHIP_VISIBLE_DEVICES

海光 DCU 适配

本文介绍如何在 CubeStudio 上接入海光 DCU（Hygon DCU）算力，覆盖驱动安装、k8s device plugin 部署、整卡 / 共享 / vDCU 虚拟化的资源配置，以及容器内的挂载与路径注意事项。合并自 install/kubernetes/gpu/dcu/ 下的 readme.md（适配测试）、driver.md（驱动安装）、vdcu.md（设备插件与虚拟化）。

官方资料参考：

海光开发者社区 Kubernetes 插件文档：https://cancon.hpccube.com:65024/5/main/Kubernetes%E6%8F%92%E4%BB%B6
海光社区下载：https://download.sourcefind.cn:65024/5/main
光源（镜像/框架包）：https://sourcefind.cn/#/service-list

1. 适配概述与结论

CubeStudio 已对海光 DCU 做了全流程适配，DCU 资源整体与英伟达 GPU 类似，提供了云原生领域的完整生态：

k8s device plugin（整卡、共享、禁用等占用方式）；
类似英伟达 MIG 的虚拟化方案，以及驱动层 / HAMi 两套 vDCU 虚拟化；
exporter 资源采集组件（见同目录 dcu-exporter-v2.yaml 与 dcu-exporter-dashboard.json）；
Python 多种深度学习框架的替换包，无需学习新语言；
notebook 与深度学习框架的基础镜像，业务无需从头构建 DCU 专用镜像。

平台侧已适配的能力（基于海光平台 + DCU 的中科可控服务器 X7340H0，CPU 为 Hygon C86 7380 验证通过）：

平台全局算力变量配置，同时支持多厂商 GPU 卡（含 DCU）和虚拟化卡（含 vDCU）；
web 界面上选择 DCU，分单卡模式与共享模式；
Notebook 在线开发；
Pipeline 分布式多机多卡训练；
在线推理 / DeepSeek 等大模型部署。

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

平台用 GPU_RESOURCE 字典把"资源简称"映射到 k8s 扩展资源名，DCU 相关项见 myapp/config.py:1242（生产配置同 install/docker/config.py:1242）：

GPU_RESOURCE = {
    ...
    "dcu":  "hygon.com/dcu",                  # 海光 DCU 整卡 / 共享
    "vdcu": "hygon.com/dcunum",               # HAMi 动态虚拟化；数量值无意义，
                                              # 需同步指定 hygon.com/dcumem、hygon.com/dcucores
    "vdcu1":"hygon.com/dcu-share-30c-16g",    # 驱动层面的静态虚拟化
    ...
}

禁用 DCU（复合机器上避免被共享占用）使用的环境变量见 myapp/config.py:1264：

GPU_NONE = {
    ...
    "dcu": ['HIP_VISIBLE_DEVICES', '-1'],
}

在项目组 / 任务里用 gpu:1(dcu)、gpu:1(vdcu) 这种 数量(资源简称) 的写法占用资源，括号内的简称就是上面 GPU_RESOURCE 里定义的 key。

3. 驱动安装

3.1 驱动 / DTK 兼容列表

驱动版本	支持硬件	推荐 DTK 版本
rock-4.0-23-5.6.25	Z100/Z100L	21.04 / 21.10 / 22.04
rock-4.5.2-5.11.40	Z100/Z100L	22.04 / 22.10 / 23.04
rock-5.2.0-5.16.18	Z100/Z100L	22.10 / 23.04
rock-5.2.0-5.16.29	Z100/Z100L/K100	23.04 / 23.10
rock-5.7.1-6.2.26+	Z100/Z100L/K100/K100-AI	24.04 / 25.04
rock-6.3.8+	BW1000/K100-AI/K100/Z100L/Z100	25.04

接入 k8s device plugin（v2.3.0）时官方建议：DTK 驱动程序 ≥ 24.04、驱动版本 ≥ 6.3.15、k8s ≥ 1.18，操作系统建议 Ubuntu 20.04+ 或 CentOS 7.6+。

3.2 安装依赖包

# CentOS
yum install -y rpm-build gcc-c++ cmake automake elfutils-libelf-devel libdrm libdrm-devel pciutils
yum install -y kernel-devel-`uname -r` kernel-modules-extra
# Ubuntu
apt install -y gcc g++ cmake automake libelf-dev libdrm-amdgpu1 libtinfo5 pciutils libdrm-dev
apt install -y linux-headers-`uname -r` linux-modules-extra

3.3 安装驱动

# 1) 下载驱动：https://cancon.hpccube.com:65024/6/main/latest%E9%A9%B1%E5%8A%A8
# 2) 赋可执行权限
chmod +x rock*.run
# 3) 安装
./rock*.run
# 4) 重启驱动服务
systemctl restart hymgr

注意事项：

安装参数可通过 ./rock*.run -h 查看；
安装新驱动无需先卸载旧驱动，安装过程会自动卸载老驱动；
安装时会询问 Do you want to remove legacy hymgr config file? [Y/n]，选 yes 会重新生成 /etc/hymgr.cfg，选 no 保留原文件；
K100/K100-AI 环境会提示 Update vbios? [y/N]，首次安装建议更新 vbios 并重启物理机；云计算场景对重启敏感，可不更新；
新版本驱动要求 cmake ≥ 3.2、gcc ≥ 7.3；kernel 版本要与 kernel-devel 一致；
6.2.* 及以前驱动的内核模块名是 hydcu，6.3.* 及以后是 hycu；
6.3.* 驱动下 docker 调用时建议挂载 /sys/kernel/debug，否则容器内无法获取 DCU 进程信息。

3.4 校验驱动加载

# 6.2.x 及以下
lsmod | grep -E "hydcu|hycu"   # 应出现 hydcu / hydcu_sched / hyttm / hykcl 等模块
# 6.3.x 及以上
lsmod | grep -E "hydcu|hycu"   # 应出现 hycu / hycu_sched / hyttm / hykcl 等模块

# 查看驱动版本
hy-smi --showdriverversion
# 查看卡资源
hy-smi virtual -show-device-info

4. k8s device plugin 部署（整卡 / 共享）

# 给节点打标签（标准模式）
kubectl label node <node-name> hygon.com/dcu=true --overwrite
# 部署 DCU device 插件
kubectl apply -f dcu-device.yaml

设备插件镜像为 image.sourcefind.cn:5000/dcu/admin/base/dcu-device-plugin:v2.3.0（见 install/kubernetes/gpu/dcu/dcu-device.yaml:36）。v2.3.0 支持标准模式和 MIG；MIG 功能官方即将弃用，且开启 MIG 后 vDCU 虚拟化不可用。

说明：标准模式节点需打标签 hygon.com/dcu=true。dcu-device.yaml 的节点亲和要求 hygon.com/dcu In ["true"]（见 install/kubernetes/gpu/dcu/dcu-device.yaml:21-34），dcu-exporter-v2.yaml 也用 nodeSelector: hygon.com/dcu: "true"（见 install/kubernetes/gpu/dcu/dcu-exporter-v2.yaml:32）；仓库内没有自动打标组件，故须手动打该标签，否则设备插件/exporter 不会被调度到该节点。原 vdcu.md:15 写的 dcu=true 与此 key 不同，不满足该亲和。此外该亲和还要求 dcu-mode NotIn ["mig"]、dcu NotIn ["on"]（dcu=on 用于区分 vDCU 虚拟化混用模式，见 5.1 节）。

部署成功后用 kubectl describe node <node-name> 可看到 hygon.com/dcu 资源。web 界面上即可按单卡模式或共享模式使用 DCU。

5. vDCU 虚拟化

DCU 提供两种 vDCU 虚拟化路线：驱动层手动静态切分（与物理卡混用）和 HAMi 动态切分。

5.1 驱动层手动切分（与物理卡混用）

用 hy-smi virtual 在驱动层手动切分 vDCU：

# 均匀切分：把 0 号物理卡均分为 4 个 vDCU
hy-smi virtual -d 0 --create-vdevices 4

# 不均匀切分（按算力单元与显存指定，可能失败需多调试）
hy-smi virtual -d 0 --create-vdevices 4 \
  --vdevice-compute-units "40,30,30,20" \
  --vdevice-memory-size "25000,15000,15000,10000"

# 查看 vDCU
hy-smi virtual -show-vdevice-info
# 销毁 vDCU
hy-smi virtual -d 0 --destroy-vdevices

要让手动切分的 vDCU 与物理卡混用，需把 dcu-device-plugin 的环境变量 RESOURCE_REGISTER_STRATEGY 设为 mixed（仓库内 install/kubernetes/gpu/dcu/dcu-device.yaml:43-44 默认即为 mixed）。

切分后 kubectl describe node 会显示 hygon.com/dcu、hygon.com/dcu-share-xxc-xg 等资源；据此在平台 GPU_RESOURCE 中配置对应资源名（如 myapp/config.py:1252 的 "vdcu1":"hygon.com/dcu-share-30c-16g"）。使用时写 gpu:1(dcu) / gpu:1(<自定义vdcu简称>) 即可。

5.2 HAMi 动态切分

# 给节点打标签（HAMi 模式）
kubectl label node <node-name> dcu=on --overwrite
# 依次部署
kubectl apply -f hami/vdcu-admission-webhook.yaml
kubectl apply -f hami/vdcu-scheduler.yaml
kubectl apply -f hami/k8s-dcu-plugin-hami.yaml

HAMi 版设备插件镜像同为 image.sourcefind.cn:5000/dcu/admin/base/dcu-device-plugin:v2.3.0，其 RESOURCE_REGISTER_STRATEGY=hami、nodeSelector 为 dcu: "on"（见 install/kubernetes/gpu/dcu/hami/k8s-dcu-plugin-hami.yaml:18-30）。

部署前需修改 vdcu-admission-webhook.yaml、vdcu-scheduler.yaml：

nodeSelector: node-role.kubernetes.io/control-plane: ""：高可用集群按 master 节点实际 control-plane 标签调整（kubectl get node <node-name> --show-labels 确认）；
nodeName: master：改成自己 control 节点的 nodename（kubectl describe node <node-name> | grep Name:）；
volumes -> kubelet -> hostPath.path: /usr/local/bin/kubelet：确认本地 kubelet 二进制路径，不同则替换。

删除 vdcu-scheduler.yaml、k8s-dcu-plugin-hami.yaml 时需同步清理：

kubectl delete secrets -n kube-system admission-webhook-dcu-certs
kubectl delete mutatingwebhookconfigurations mutating-webhook-dcu-cfg

部署成功后 kubectl describe node <node-name> 会显示 hygon.com/dcunum（vDCU 资源名），据此配置 GPU_RESOURCE 中的 "vdcu":"hygon.com/dcunum"（myapp/config.py:1251）。使用时写 gpu:1(vdcu) 即可。

注意：HAMi 模式下 hygon.com/dcunum 的数量值本身无意义，须同步指定 hygon.com/dcumem、hygon.com/dcucores 来确定可分配规格；只指定 hygon.com/dcunum:1 而不指定显存 / 算力，则一块 vDCU 占用整张物理卡。

6. 容器内挂载与路径注意事项

正常情况下 device 会自动挂载，若未自动挂载或出现库路径错误，可：

在环境变量中添加：

LD_LIBRARY_PATH=/opt/dtk/lib:/opt/dtk/hipblas/lib:/opt/hyhal/lib:/usr/lib64:/lib64:/usr/lib:/lib

启动命令中添加：bash /opt/dtk/env.sh

手动挂载（pvc + hostpath 形式）：

kubeflow-user-workspace(pvc):/mnt,/opt/hyhal(hostpath):/opt/hyhal,/dev(hostpath):/dev,/dev/kfd(hostpath):/dev/kfd,/dev/dri(hostpath):/dev/dri

7. DCU 基础镜像

平台预置/示例镜像（见 myapp/config.py，默认注释掉，按需启用）：

Notebook / 开发：image.sourcefind.cn:5000/dcu/admin/base/jupyterlab-pytorch:2.4.1-ubuntu22.04-dtk25.04.1-py3.10-devel（myapp/config.py:1019）；
推理（vllm）：image.sourcefind.cn:5000/dcu/admin/base/vllm:0.8.5-ubuntu22.04-dtk25.04.1-py3.10（myapp/config.py:1332 注释）。

更多框架包与镜像见光源：https://sourcefind.cn/#/service-list

最后更新 2026-07-04完整文档以官方仓库为准：GitHub Wiki