如何在海光 DCU DTK 环境下平滑迁移 ROCm 项目：解决版本冲突的实战指南

海光 DCU（Deep Computing Unit）作为国产 AI 算力的佼佼者，其底层软件栈 DTK（Deep-learning ToolKit）高度兼容 AMD 的 ROCm 生态。但在实际项目中，从原生 ROCm 或 CUDA 环境迁移到 DTK 时，开发者往往会遇到驱动版本不匹配、头文件路径冲突以及PyTorch/TensorFlow 框架算子报错等棘手问题。本文将带你通过一套标准化的流程，快速解决这些依赖冲突，实现算法的平滑迁移。

1. 核心痛点：为什么你的 ROCm 代码在 DCU 上跑不起来？

虽然 DTK 与 ROCm 接口相似，但主要存在以下三个层面的差异：
– API 映射差异：部分 ROCm 接口在特定 DTK 版本中被精简或重新封装。
– 库依赖版本：DTK 往往绑定了特定版本的组件（如 hipBLAS, miopen）。
– 编译环境：国产服务器通常使用特定的 Linux 发行版（如 CentOS 7.6 或麒麟），其 GLIBC 版本与主流社区版有差异。

2. 实战步骤：构建标准化的迁移流水线

第一步：环境对齐与镜像选择

不要尝试直接在物理机上配置环境。建议使用官方提供的容器镜像，这是规避依赖冲突最有效的方法。

# 查看当前 DCU 驱动版本
dtk-smi

# 建议选择与驱动对应的官方镜像，例如 DTK 23.04
docker pull image.sourcefind.com:5000/dcu/ecosystem/pytorch:2.0.1-dtk23.04-py38-ubuntu20.04

第二步：头文件与路径适配

DTK 的头文件通常位于 /opt/dtk/ 下。如果你的项目原本是为 ROCm 编写的，编译器可能会找不到 <hip/hip_runtime.h>。

解决方案：在项目的 CMakeLists.txt 或编译脚本中显式指定 DTK 根路径。

set(DTK_PATH /opt/dtk)
include_directories(${DTK_PATH}/include)
link_directories(${DTK_PATH}/lib)

第三步：解决 Python 依赖冲突

很多开发者在迁移后习惯性地执行 pip install torch，这会覆盖 DTK 镜像中适配过的国产化版本。

避坑指南：
1. 严禁混用：只能使用海光适配版 PyTorch（通常已预装在镜像中）。
2. 检查检测脚本：编写一个简单的脚本确认硬件是否被正确识别。

import torch

# 检查 DCU 是否可用
print(f\"Is DCU available: {torch.cuda.is_available()}\")
# 获取 DCU 数量
print(f\"Device count: {torch.cuda.device_count()}\")
# 获取当前设备名称
if torch.cuda.is_available():
    print(f\"Device Name: {torch.cuda.get_device_name(0)}\")

3. 常见报错解决方法 (FAQ)

Q: 报错 **libhip_hcc.so not found?**
A: 检查 LD_LIBRARY_PATH。在 DTK 23.04 及以上版本，动态库路径发生了细微变化。请执行：
export LD_LIBRARY_PATH=/opt/dtk/lib:/opt/dtk/lib64:$LD_LIBRARY_PATH

Q: 算子运行结果与 CUDA 不一致？
A: 优先检查 miopen 缓存。有时候旧的编译缓存会导致计算错误。尝试清理目录：
rm -rf ~/.cache/miopen/

总结

在海光 DCU 上迁移 ROCm 项目，核心在于「镜像优先、路径显式、依赖封闭」。通过利用官方提供的 DTK 容器，并严格控制 Python 环境的纯净性，大部分迁移工作可以在 1 小时内完成。