从零搭建国产DCU开发环境：一份写给新手的实操指南

从零搭建国产DCU开发环境一份写给新手的实操指南如果你刚拿到一台搭载海光DCU的服务器第一反应可能是“这东西怎么用”这不是你一个人的困惑。国产加速卡最大的门槛从来不在硬件本身而在于环境怎么搭、软件怎么装、代码怎么跑。驱动装不上、DTK版本对不上、PyTorch找不到卡——每一个坑都足以让新手劝退。这篇文章我把DCU环境部署的完整流程拆解出来从硬件检查到跑通第一个模型手把手带你走一遍。一、环境部署到底要装什么在动手之前先搞清楚DCU软件栈的层次结构驱动Driver最底层让操作系统认识DCU硬件DTKDCU Toolkit开发工具包提供编译器、数学库、通信库等DASDCU AI Software StackAI软件栈包含PyTorch、vLLM等框架的DCU适配版可以这样理解驱动是“让DCU能工作”DTK是“让开发者能编程”DAS是“让AI模型能跑起来”。三者缺一不可。二、动手前先做三件事第一件事检查DCU硬件状态用lspci命令看看DCU是否被正确识别lspci|grep-iCo-processor正常输出应该看到类似这样的信息05:00.0 Co-processor: Chengdu C-3000 IC Design Co., Ltd. BW (rev 01)重点关注rev后面的数字rev 01表示设备正常可以继续安装如果看到rev ff说明设备已经工作异常需要硬重启恢复【文档1.1】。第二件事检查BAR地址DCU支持的BAR寄存器地址在44bit以内需要确认分配地址没有超限【文档1.1】lspci-vvvd1d94:6320|grep-iregion如果地址超出44bit12位十六进制位需要在BIOS中调整MMIO High Base设置【文档1.1】。第三件事安装系统依赖不同操作系统的依赖包略有不同以CentOS/Red Hat系为例【文档1.2】yuminstall-ypciutils policycoreutils-python yum-utilswgetnumactl-devel mlocate yuminstall-ykernel-devel-$(uname-r)kernel-modules-extra-$(uname-r)yuminstall-yautomake gcc-c rpm-build cmake elfutils-libelf-devel⚠️版本要求gcc需要7.3cmake需要3.5【文档1.2】。如果系统自带版本过低需要先升级。三、安装驱动让DCU“活”起来下载驱动从光合开发者社区下载对应型号的驱动包https://download.sourcefind.cn:65024/6/main/latest驱动驱动包命名格式为rock-{版本号}-{包版本号}.run例如rock-6.3.28-V1.3.0b.run【文档1.3】。安装驱动chmodx rock-*.run ./rock-6.3.28-V1.3.0b.run推荐使用-A参数进行全自动安装驱动会自动升级所有内容驱动、配置文件、DCU VBIOS、HY Switch固件【文档1.3】。安装过程中会询问几个问题是否升级VBIOS建议选Y是否升级HY Switch固件选Y若升级则需要重启物理机是否需要指定互联类型BW系列DCU支持通过-t参数指定互联拓扑【文档1.3】验证驱动从6.3.*版本开始驱动模块名称改为hycu之前叫hydcu【文档1.4】lsmod|grephycu hy-smi# 查看DCU状态如果hy-smi能正常显示DCU的温度、功耗、显存使用率等信息说明驱动安装成功【文档3.3】。⚠️版本选择小贴士如果打算用Ollama等工具建议安装6.2.x以下版本驱动标识为hydcu因为Ollama目前只识别这个标识。如果主要做AI开发6.3.*版本功能更完整。四、安装DTK给开发者一把“钥匙”DTKDCU Toolkit是DCU上的开发工具包相当于NVIDIA的CUDA Toolkit。下载与解压https://download.sourcefind.cn:65024/1/main → DTK Toolkit选择对应操作系统版本的压缩包下载tarxvf DTK-25.04.4-CentOS8.5-x86_64.tar.gz-C/optln-s/opt/DTK-25.04.4 /opt/dtk# 创建软链接方便后续版本切换配置环境变量方式一直接加载脚本【文档3.2】source/opt/dtk/env.shechosource /opt/dtk/env.sh~/.bashrc方式二使用Environment Module推荐多版本管理场景【文档3.2】yuminstall-yenvironment-modules# 在/opt/dtk/下创建module文件后module load dtk/25.04.4验证DTKrocminfo|grep-igfx# 应该能看到gfx936等DCU代号如果能看到DCU设备信息说明DTK安装成功【文档3.3】。五、安装DAS让AI模型跑起来DAS是DCU上的AI软件栈提供了PyTorch、vLLM等框架的DCU适配版本。版本匹配是关键DAS组件的版本必须与DTK版本严格对应【文档4.2.1】。例如DTK版本PyTorch版本vLLM版本24.04.22.3.0das.opt1.dtk240420.5.0das.opt1.dtk2404225.042.4.1das.opt2.dtk25040.6.2das.opt3.dtk250425.04.22.7.1das.opt1.dtk250420.9.2das.opt1.dtk25042⚠️踩坑提醒不要混装不同DTK版本的包否则会出现符号找不到、算子报错等各种诡异问题。安装PyTorch从光合开发者社区下载对应版本的wheel包pipinstalltorch-2.3.0das.opt2.dtk24043-cp310-cp310-manylinux_2_28_x86_64.whl验证安装python-cimport torch; print(torch.__version__); print(torch.cuda.is_available())# 预期输出2.3.0 和 True如果输出True说明PyTorch能正常调用DCU。安装vLLM可选pipinstallvllm-0.6.2das.opt1.dtk24043-cp310-cp310-manylinux_2_28_x86_64.whl python-cimport vllm; print(vllm.__version__)六、进阶方案容器化部署强烈推荐手动部署的坑实在太多了——依赖版本对不上、环境变量没配好、内核模块没加载……每一个问题都够折腾半天。强烈推荐直接用DCU容器镜像。光合开发者社区提供了大量预装好DTK和AI框架的Docker镜像dockerpull image.sourcefind.cn:5000/dcu/admin/base/pytorch:2.3.0-py3.10-dtk24.04.3启动容器dockerrun-it\--networkhost\--ipchost\--shm-size64G\--device/dev/kfd\--device/dev/dri\-v/opt/hyhal:/opt/hyhal\--group-add video\--cap-addSYS_PTRACE\--security-optseccompunconfined\image.sourcefind.cn:5000/dcu/admin/base/pytorch:2.3.0-py3.10-dtk24.04.3\/bin/bash几个关键参数说明【文档5.1】--device/dev/kfd和--device/dev/dri让容器访问DCU设备--shm-size64G共享内存要足够大默认64M完全不够用-v /opt/hyhal:/opt/hyhal挂载DTK运行时库DTK 23.10以上版本必须--group-add video普通用户使用DCU需要加入video组进入容器后直接hy-smi检查DCU状态然后就能开始跑模型了【文档5.1】。七、常见问题速查Q驱动装完重启后DCU不见了A检查BIOS中是否开启了nomodeset启动参数。如果开启了驱动可能无法正常加载【文档3.1】。Q容器里找不到DCUA检查是否挂载了/opt/hyhal目录以及--device参数是否正确。6.3.*版本驱动下还需要挂载/sys/kernel/debug路径。Qtorch.cuda.is_available()返回FalseA先确认hy-smi能看到DCU再确认DTK版本与PyTorch wheel包版本匹配。Q驱动安装时提示rev ffA设备已工作异常需要硬重启断电重启恢复【文档1.1】。八、总结从零搭建DCU开发环境核心就三步装驱动让DCU硬件被系统识别装DTK获得开发工具和基础库装DAS获得AI框架支持每一步都有版本匹配的要求——驱动版本要匹配硬件型号【文档1.3】DTK版本要匹配驱动版本DAS组件版本要匹配DTK版本【文档4.2.1】。任何一个环节对不上都可能让你卡上半天。如果你只是想快速上手直接走容器化路线——拉一个官方镜像几分钟就能拥有一个完整的DCU开发环境。等跑通了、熟悉了再回头研究手动部署也不迟。国产化硬件的发展确实“任重道远”但工具链正在快速成熟。从驱动到DTK再到DAS海光DCU的软件栈已经覆盖了从底层到上层的完整链条。剩下的就是开发者们多踩坑、多填坑让这条路越走越宽。