[ROCm] gfx1201 (Navi 48) support – compilation guide and known issues

基于 Issue bitsandbytes-foundation/bitsandbytes #1955 的讨论链，以下是整理的排错指南。

[ROCm] gfx1201 (Navi 48) support – compilation guide and known issues

快速结论：该问题通常发生在 AMD Radeon AI PRO R9700 (Navi 48 / gfx1201) 用户使用 `pip install bitsandbytes` 安装时，ROCm 后端缺失或编译过程中遇到 `gfx1153` 无效 target ID 或符号缺失错误。优先排查 ROCm 版本（≥6.4 官方支持）和编译分支（需使用 main 分支，非 multi-backend-refactor）。

问题场景

用户在 AMD Radeon AI PRO R9700 (gfx1201 / Navi 48) 显卡上运行 bitsandbytes 时，直接使用 pip install bitsandbytes 安装的版本没有 ROCm 后端，需从源码编译。编译过程中可能因 ROCm 版本或 CMake 配置错误导致失败，且导入时可能因 BNB_BACKEND 环境变量未设置或路径问题而报错。

报错原文

# 编译时错误：gfx1153 无效 target ID
clang++: error: invalid target ID 'gfx1153'

# 运行时符号缺失错误
OSError: undefined symbol: _Z36__device_stub__kOptimizer32bit1StateI12hip_bfloat16Li2E...

# 导入错误（editable install 路径问题）
bitsandbytes.__path__ points to parent directory instead of module directory, causing import to fail silently.

原因分析

主要诱因：

• gfx1153 无效 target ID：ROCm 6.3 的 CMake 模块内建了无效的 target gfx1153，导致编译失败。这是 ROCm 6.3 的 bug；ROCm 7.2.3 已修复，编译器能正确接受 gfx1153。
• multi-backend-refactor 分支符号缺失：该分支已弃用，编译出的 .so 缺少 kOptimizer32bit1StateI12hip_bfloat16Li2E 符号。
• editable install 路径问题：使用 pip install -e . 后，bitsandbytes.__path__ 可能指向父目录而非模块目录，导致导入失败。在 ROCm 7.2.3 上未重现此问题。
• BNB_BACKEND 环境变量问题：用户尝试设置 os.environ['BNB_BACKEND'] = 'rocm'，但实际 bitsandbytes 不读取此变量；后端通过 torch.version.hip 自动检测。

可能原因：ROCm 版本低于 6.4 时，bitsandbytes 官方 PyPI 轮子不包含 gfx1201 目标，必须从源码编译；且旧版本 Toolchains 可能导致 target 列表不兼容。

环境排查

• ROCm 版本：确认是否为 6.3 或 7.2.3+。ROCm 6.4+ 官方已支持 gfx1201。
• Python 版本：3.11.15（源自 Issue 环境）。
• PyTorch 版本：2.9.1+rocm6.3（源自 Issue 环境）。
• bitsandbytes 版本：0.50.0.dev0（从源码编译）。
• 显卡型号：AMD Radeon AI PRO R9700 (Navi 48 / gfx1201)。
• 编译分支：确认使用 main 分支，非 multi-backend-refactor（已弃用）。
• CMake 命令：确认 AMDGPU_TARGETS 环境变量是否设置，且 -DCMAKE_HIP_ARCHITECTURES="gfx1201" 是否配置。

解决步骤

1. 更新 ROCm 版本：若使用 ROCm 6.3，建议升级至 6.4+ 或 7.2.3+，以自动支持 gfx1201 并避免 target ID 问题。
   注意：ROCm 6.3 需手动设置 export AMDGPU_TARGETS="gfx1201" 覆盖无效的 gfx1153；ROCm 7.2.3 无需此操作。

2. 使用正确的 Git 分支：从 main 分支克隆源代码，避免 multi-backend-refactor 分支（已弃用且缺失符号）。
   执行：git clone https://github.com/bitsandbytes-foundation/bitsandbytes.git。

3. 编译前设置环境变量（仅 ROCm 6.3）：
   export PATH=/opt/rocm/bin:/usr/local/bin:$PATH
export AMDGPU_TARGETS="gfx1201"

4. CMake 编译与安装：
   cmake -DCOMPUTE_BACKEND=hip -DCMAKE_BUILD_TYPE=Release -DCMAKE_HIP_ARCHITECTURES="gfx1201" -S . -B build
cmake --build build -j$(nproc)
pip3.11 install -e . --no-cache-dir

5. 解决 editable install 路径问题（仅 ROCm 6.3）：
   若导入仍失败，手动添加 PYTHONPATH：
   export PYTHONPATH=/root/bitsandbytes:$PYTHONPATH

6. 不要设置 BNB_BACKEND：该环境变量无效，bitsandbytes 会自动检测 ROCm 后端。用户代码中不应包含 os.environ['BNB_BACKEND'] = 'rocm'。

验证方法

执行以下命令验证 bitsandbytes 是否成功导入且识别 ROCm 后端：

python3 -c "
import sys
sys.path.insert(0, '/root/bitsandbytes')
import bitsandbytes as bnb
print(bnb.__version__)
print(bnb.supported_torch_devices)
"

预期输出：0.50.0.dev0 及设备列表包含 ROCm 设备。

参考来源

bitsandbytes-foundation/bitsandbytes #1955

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。