RuntimeError: Configured ROCm binary not found at /opt/app-root/lib64/python3.12/site-packages/bitsandbytes/libbitsandbytes_rocm84.so

快速结论：该报错通常出现在 ROCm 环境下导入 bitsandbytes 时：已安装版本只包含针对特定 ROCm ABI 的预编译库，而本机 ROCm 版本与库文件名不匹配（例如只有 rocm84 后缀的二进制，但预期版本不同），导致 RuntimeError: Configured ROCm binary not found at /opt/app-root/lib64/python3.12/site-packages/bitsandbytes/libbitsandbytes_rocm84.so。优先排查 bitsandbytes 版本是否已包含对应 ROCm 版本的构建，以及是否有可用的检测/回退机制。

适用环境：已在 Issue 中确认的环境：RHEL 9.6、Python 3.12.9、ROCm 7.14、GPU MI350P、bitsandbytes 0.49.2；非标准安装路径 /opt/app-root；构建方式为带网络隔离的 hermetic build。Issue 中未确认 CUDA、PyTorch 等版本。

最快修复方案：暂无确认的一步修复方案。Issue 中给出的修复组合是 #1889、#1980、#2007，其中 #2007 增加了 ROCm 7.14 构建，#1889 与 #1980 改进了检测并在缺少较新构建时自动回退到 7.2 构建。维护者表示这些改动将在 v0.50.0 发布到 PyPI，同时提供了从 main 构建的 wheels（continuous-release_main）可临时使用。

注意事项：使用从 main 构建的 wheels 属于非正式发布版本，可能与 PyPI 稳定版行为存在差异；#2007 增加的 ROCm 7.14 构建与自动回退逻辑需以实际发布的 v0.50.0 为准。在 v0.50.0 发布前，若继续使用 0.49.2 且没有兼容二进制，问题可能仍会出现。

问题场景

用户在 RHEL 9.6、Python 3.12.9、ROCm 7.14、GPU MI350P 环境下，通过 hermetic build（网络隔离）安装 bitsandbytes 0.49.2 后，执行 python -c 'import bitsandbytes' 触发库加载失败。报错指向 bitsandbytes 在 /opt/app-root/lib64/python3.12/site-packages/bitsandbytes/ 下找不到所配置的 ROCm 二进制文件。

报错原文

Installing collected packages: bitsandbytes
Successfully installed bitsandbytes-0.49.2
(app-root) /opt/app-root$ python -c 'import bitsandbytes'
bitsandbytes library load error: Configured ROCm binary not found at /opt/app-root/lib64/python3.12/site-packages/bitsandbytes/libbitsandbytes_rocm84.so
Traceback (most recent call last):
  File "/opt/app-root/lib64/python3.12/site-packages/bitsandbytes/cextension.py", line 320, in <module>
    lib = get_native_library()
          ^^^^^^^^^^^^^^^^^^^^
  File "/opt/app-root/lib64/python3.12/site-packages/bitsandbytes/cextension.py", line 288, in get_native_library
    raise RuntimeError(f"Configured {BNB_BACKEND} binary not found at {cuda_binary_path}")
RuntimeError: Configured ROCm binary not found at /opt/app-root/lib64/python3.12/site-packages/bitsandbytes/libbitsandbytes_rocm84.so

原因分析

最可能的原因是 bitsandbytes 在加载原生库时，根据当前配置/检测结果去查找某个特定 ROCm 后缀的二进制文件（示例中为 libbitsandbytes_rocm84.so），但该文件在安装目录中不存在，导致导入失败。结合 Issue 标题“ROCm 8.4 binary not found (latest ROCm is 7.14)”，说明安装包或构建环境中针对的 ROCm 版本与用户实际使用的 ROCm 7.14 不一致；在缺少与当前 ROCm 匹配的构建时，旧版 bitsandbytes 也没有自动回退到已有构建的能力。

环境排查

确认 bitsandbytes 版本（Issue 中为 0.49.2），并核对安装后 site-packages/bitsandbytes 下实际存在的 libbitsandbytes_*.so 文件名。
确认 ROCm 版本（Issue 中为 7.14）及 ROCm 安装路径。
确认 Python 版本（Issue 中为 3.12.9）与安装路径（Issue 中为 /opt/app-root/lib64/python3.12/site-packages）。
确认是否使用 hermetic build/网络隔离环境，因为这会限制安装可选构建或回退构建的可用性。
确认是否存在与 ROCm 7.14 对应的 bitsandbytes 构建，或是否已包含 #1889、#1980、#2007 的修复。

解决步骤

先确认当前安装的 bitsandbytes 版本是否为 0.49.2，并检查安装目录下是否存在报错中提到的 libbitsandbytes_rocm84.so。
若目标环境允许升级，优先升级到包含 #1889、#1980、#2007 的版本；维护者表示这些改动会在 v0.50.0 发布到 PyPI。
如果暂时无法等待 v0.50.0，可使用维护者在 Issue 中提供的从 main 构建的 wheels（continuous-release_main）进行验证或临时替换。
在 hermetic build/网络隔离环境下，需要提前将对应 wheel 或构建产物准备好，否则无法在离线环境中直接获取新版本。

验证方法

完成上述处理后，重新执行 python -c 'import bitsandbytes'，确认不再出现 RuntimeError: Configured ROCm binary not found ...；并可进一步确认 bitsandbytes 加载的原生库与当前 ROCm 7.14 环境匹配，或已按 #1889/#1980 的逻辑自动回退到可用的 7.2 构建。