add dlrm-v2

FBGEMM_GPU_DTK26.04_编译安装指南.md

+# 基于 DTK 26.04 的 FBGEMM GPU 编译与安装指南（完整版）
+
+**FBGEMM GPU** 指 PyTorch 生态中的 `fbgemm_gpu` 包。本文**自包含**：从环境、拉源码、打补丁、编译、安装、验证到测试与排错，均在本页完成，**无需再读其他说明文件**。
+
+**约定**：下文路径以 **FBGEMM 仓库根目录** 为基准（克隆后的 `FBGEMM/`）。例如 `fbgemm_gpu/setup.py` 即 `FBGEMM/fbgemm_gpu/setup.py`。
+
+**重要**：**不要修改 DTK 安装目录**（如 `/opt/dtk`、`/opt/dtk-26.04-*`）内文件；仅修改 FBGEMM 源码，以及可选的系统 `librt` 符号链接（见第 2.4 节）。
+
+---
+
+## 1. 环境与版本
+
+| 项目 | 说明 |
+|------|------|
+| DTK | **26.04** 系；`ROCM_PATH` 常为 `/opt/dtk`，以本机为准 |
+| PyTorch | **HIP/ROCm** 构建（`torch.version.hip` 有版本；`torch.version.cuda` 多为 `None`） |
+| FBGEMM | **v1.3.0**（`--branch v1.3.0`） |
+| Python | 与已安装的 PyTorch wheel 一致（如 3.10） |
+| GPU 架构 | 海光 DCU 常见 **`gfx936`**，由 `PYTORCH_ROCM_ARCH` 指定 |
+
+自检：
+
+```bash
+python3 -c "import torch; print('torch', torch.__version__); print('hip', torch.version.hip); print('cuda', torch.version.cuda)"
+ls -d /opt/dtk /opt/dtk-* 2>/dev/null || true
+```
+
+`setup.py` / CMake 需要环境变量 **`BUILD_ROCM_VERSION`**，格式 **`主版本.次版本`**（与当前 ROCm/DTK 大版本一致，例如 `6.3` 或 `6.4`）：
+
+```bash
+export BUILD_ROCM_VERSION=6.3
+```
+
+---
+
+## 2. 依赖、网络、源码与子模块
+
+### 2.1 Python 包（构建）
+
+```bash
+pip install setuptools_git_versioning scikit-build tabulate ninja cmake patchelf
+```
+
+### 2.2 访问 GitHub
+
+若直连失败，请为本终端设置可用的 **`http_proxy` / `https_proxy`**，或使用 GitHub 加速前缀（示例，按你环境替换域名）：
+
+```bash
+git clone https://github.com/pytorch/FBGEMM.git --branch v1.3.0 --depth 1
+# 或使用：git clone https://<你的加速前缀>/https://github.com/pytorch/FBGEMM.git --branch v1.3.0 --depth 1
+```
+
+### 2.3 子模块
+
+```bash
+cd FBGEMM
+git submodule update --init --recursive --jobs 6
+```
+
+仓库较大，可加 `--jobs` 并行拉取。
+
+### 2.4 `librt` 链接（链接阶段常见需要）
+
+```bash
+sudo ln -sf /lib/x86_64-linux-gnu/librt.so.1 /usr/lib/x86_64-linux-gnu/librt.so
+```
+
+---
+
+## 3. 为何必须改源码、且只能改「CUDA 侧」
+
+在 **`FBGEMM_BUILD_VARIANT=rocm`** 时，CMake 会对 `fbgemm_gpu` 下大量 **`.cu` / `.cuh`** 做 **hipify**，生成 **`*.hip`、`*_hip.cuh`** 等。
+
+- **不要**把补丁只写在生成文件上；下一次 `cmake` / 清理重编会被覆盖。
+- 补丁应写在 **参与 hipify 的 CUDA 源**（以及 `setup.py`）上。
+
+---
+
+## 4. 补丁总览表
+
+以下文件均在 **`fbgemm_gpu/`** 目录下（即 `FBGEMM/fbgemm_gpu/...`）。
+
+| 目的 | 文件（相对 `fbgemm_gpu/`） |
+|------|---------------------------|
+| `setuptools_git_versioning` 返回 `Version` 非字符串 | `setup.py` |
+| ROCm 下 `CUDA_KERNEL_ASSERT2` 与 DSA/DTK 冲突 | `src/sparse_ops/common.cuh`、`include/fbgemm_gpu/utils/embedding_bounds_check_common.cuh`、`test/utils/kernel_launcher_test.cu` |
+| ROCm 下内核启动后错误检查与 PyTorch HIP API 不一致 | `include/fbgemm_gpu/utils/kernel_launcher.cuh` |
+| `getDeviceProperties` 返回 `hipDeviceProp_t_v2*` 与旧式 `cudaDeviceProp*` 声明不匹配 | `include/fbgemm_gpu/utils/kernel_launcher.cuh`（四个 `check*` 模板化）、`include/fbgemm_gpu/utils/cuda_prelude.cuh`、`src/split_embeddings_cache/reset_weight_momentum.cu`、`src/intraining_embedding_pruning_ops/intraining_embedding_pruning.cu` |
+
+---
+
+## 5. 补丁分步说明（含可复制代码）
+
+### 5.1 `setup.py`
+
+在 `package_version()` 中，将所有：
+
+```python
+gitversion.version_from_git().split("+")[0]
+```
+
+改为：
+
+```python
+str(gitversion.version_from_git()).split("+")[0]
+```
+
+（一般出现 **两处**：带 `rc` 处理的分支与不带的分支各一处。）
+
+---
+
+### 5.2 `CUDA_KERNEL_ASSERT2` 在 ROCm 下置空
+
+在下列文件中，在 **已包含** `<c10/cuda/CUDADeviceAssertion.h>`（或等价头文件）**之后**追加：
+
+```cpp
+#ifdef USE_ROCM
+#undef CUDA_KERNEL_ASSERT2
+#define CUDA_KERNEL_ASSERT2(condition) ((void)0)
+#endif
+```
+
+**文件与插入位置：**
+
+1. **`src/sparse_ops/common.cuh`**：在 `#include <c10/cuda/CUDADeviceAssertion.h>` 与 `#include <c10/cuda/CUDADeviceAssertionHost.h>` 之后。
+2. **`include/fbgemm_gpu/utils/embedding_bounds_check_common.cuh`**：在 `#include <c10/cuda/CUDADeviceAssertion.h>` 之后。
+3. **`test/utils/kernel_launcher_test.cu`**：在 `#include <c10/cuda/CUDADeviceAssertion.h>` 之后。
+
+---
+
+### 5.3 `include/fbgemm_gpu/utils/kernel_launcher.cuh`
+
+#### A. `kernelLaunchCheck`
+
+将函数体尾部「失败时」的大段 `TORCH_CHECK` 改为在 ROCm 下使用简短分支，**避免**调用当前 PyTorch HIP 构建中缺失或映射不全的 host 辅助接口。整体结构如下（保留前面的 `cudaGetLastError` 与 `C10_LIKELY` 判断不变，仅替换失败分支）：
+
+```cpp
+#ifdef USE_ROCM
+    TORCH_CHECK(
+        false,
+        context.description(),
+        " GPU Error: ",
+        cudaGetErrorString(cuda_error));
+#else
+    TORCH_CHECK(
+        false,
+        context.description(),
+        " CUDA Error: ",
+        cudaGetErrorString(cuda_error),
+        c10::cuda::get_cuda_check_suffix(),
+        "\n",
+        c10::cuda::c10_retrieve_device_side_assertion_info());
+#endif
+```
+
+#### B. 四个 `check*` 成员函数改为模板
+
+将下列函数中参数类型由 **`const cudaDeviceProp& properties`** 改为 **模板形参**（每个函数各自加一行 `template <typename DeviceProperties>`，参数写 **`const DeviceProperties& properties`**）：
+
+- `checkGridSizesInRange`
+- `checkBlockSizesInRange`
+- `checkThreadCountNotExceeded`
+- `checkSharedMemoryPerBlockNotExceeded`
+
+示例（`checkGridSizesInRange`）：
+
+```cpp
+  template <typename DeviceProperties>
+  constexpr inline void checkGridSizesInRange(
+      const DeviceProperties& properties,
+      const dim3& grid) const {
+```
+
+函数体内部逻辑**不变**（仍访问 `properties.maxGridSize` 等字段）。
+
+这样在 ROCm 下，`launch_kernel` 里 `const auto properties = *at::cuda::getDeviceProperties(device);` 推导为 **`hipDeviceProp_t_v2`**，与 PyTorch 声明一致。
+
+---
+
+### 5.4 `include/fbgemm_gpu/utils/cuda_prelude.cuh`
+
+将匿名命名空间内的 `get_device_sm_cnt_()` 从「指针变量 + 成员访问」改为**直接返回**（避免 `cudaDeviceProp*` 与 `hipDeviceProp_t_v2*` 在 hipify 后不一致）：
+
+```cpp
+inline int get_device_sm_cnt_() {
+  return at::cuda::getDeviceProperties(c10::cuda::current_device())
+      ->multiProcessorCount;
+}
+```
+
+---
+
+### 5.5 两个 `.cu` 中的 `get_sm_count_()`
+
+以下文件中命名空间内的 **`int get_sm_count_()`** 做与上相同的「单行 return」修改（原先用 `cudaDeviceProp*` 承接指针的写法删除）：
+
+- **`src/split_embeddings_cache/reset_weight_momentum.cu`**
+- **`src/intraining_embedding_pruning_ops/intraining_embedding_pruning.cu`**
+
+```cpp
+int get_sm_count_() {
+  return at::cuda::getDeviceProperties(c10::cuda::current_device())
+      ->multiProcessorCount;
+}
+```
+
+源文件保持 **CUDA 侧 API 写法**；hipify 会在 ROCm 构建中生成对应 HIP 代码。
+
+---
+
+## 6. 编译生成 wheel
+
+在 **FBGEMM 仓库根目录**执行：
+
+```bash
+cd fbgemm_gpu
+rm -rf _skbuild build
+
+export BUILD_ROCM_VERSION=6.3
+export PYTORCH_ROCM_ARCH="gfx936"
+export ROCM_PATH=/opt/dtk
+
+TORCH_PATH="$(python3 -c "import torch, os; print(os.path.join(os.path.dirname(torch.__file__), 'share/cmake/Torch'))")"
+
+python3 setup.py bdist_wheel \
+  --package_channel=release \
+  --build-target=default \
+  --build-variant=rocm \
+  -DCMAKE_PREFIX_PATH="${TORCH_PATH};${ROCM_PATH}" \
+  -DAMDGPU_TARGETS="${PYTORCH_ROCM_ARCH}" \
+  -DTORCH_DIR="${TORCH_PATH}" \
+  -DCMAKE_C_FLAGS="-Wno-return-type -Wno-ignored-attributes -O1" \
+  -DCMAKE_CXX_FLAGS="-Wno-return-type -Wno-ignored-attributes -O1" \
+  -DCMAKE_HIP_FLAGS="-Wno-return-type -O1" \
+  -DUSE_AVX512=on \
+  -DCOPY_VISIBLE_LIBRARIES=ON \
+  -DCMAKE_SHARED_LINKER_FLAGS="-Wl,--no-as-needed -ltbb -Wl,-rpath,/usr/lib/x86_64-linux-gnu" \
+  -DTBB_INCLUDE_DIR=/usr/include
+```
+
+**必须遵守：**
+
+1. 使用 **`--build-variant=rocm`**；不要指望只传 `-DFBGEMM_BUILD_VARIANT=rocm` 而不传 setup 参数。
+2. 已导出 **`BUILD_ROCM_VERSION`**。
+3. **不要**在 `CMAKE_CXX_FLAGS` / `CMAKE_HIP_FLAGS` 里加 **`-DhipDeviceProp_t=hipDeviceProp_t_v2`**：DTK 26.04 的 HIP 头文件已同时定义 `hipDeviceProp_t` 与 `hipDeviceProp_t_v2`，再加该宏易导致 **`hipDeviceProp_t_v2` 重复定义**。类型问题靠第 5.3 B、5.4、5.5 节源码解决。
+
+成功后 wheel 路径示例：
+
+```text
+fbgemm_gpu/dist/fbgemm_gpu_rocm-1.3.0-cp310-cp310-linux_x86_64.whl
+```
+
+（Python 标签、小版本号以实际输出为准。）
+
+---
+
+## 7. 安装
+
+在 **FBGEMM 仓库根目录**（与 `fbgemm_gpu/` 同级）执行：
+
+```bash
+pip install fbgemm_gpu/dist/fbgemm_gpu_rocm-*.whl
+```
+
+若当前已在 **`fbgemm_gpu/`** 目录内，则改为：
+
+```bash
+pip install dist/fbgemm_gpu_rocm-*.whl
+```
+
+若安装时拉依赖失败（例如无法访问 PyPI）：
+
+```bash
+pip install --no-deps fbgemm_gpu/dist/fbgemm_gpu_rocm-*.whl
+# 若已在 fbgemm_gpu/ 目录内：pip install --no-deps dist/fbgemm_gpu_rocm-*.whl
+```
+
+需保证本机已有匹配版本的 **`torch`**、**`numpy`** 等。
+
+---
+
+## 8. 验证导入
+
+**不要**在 `fbgemm_gpu` 源码树内作为当前工作目录运行验证（易优先加载无 `.so` 的源码包）：
+
+```bash
+cd /tmp
+unset PYTHONPATH
+python3 -c "import torch; import fbgemm_gpu; print('OK', fbgemm_gpu.__variant__, fbgemm_gpu.__file__)"
+```
+
+期望 **`__variant__`** 与 **rocm** 相关，**`__file__`** 在 `site-packages` 下。
+
+---
+
+## 9. 可选：运行测试
+
+安装 **pytest**：
+
+```bash
+pip install pytest
+```
+
+在 **FBGEMM 仓库根目录**下进入测试目录（避免从源码树误导入）：
+
+```bash
+cd fbgemm_gpu/test
+export FBGEMM_TEST_WITH_ROCM=1
+unset PYTHONPATH
+# 可选：export HIP_LAUNCH_BLOCKING=1
+
+python3 -m pytest -v -rsx --tb=short \
+  config/feature_gate_test.py \
+  sparse/pack_segments_test.py \
+  sparse/index_select_test.py \
+  sparse/cumsum_test.py \
+  quantize/fused_8bit_rowwise_test.py
+```
+
+全量测试可遍历该目录下所有 `*_test.py`，耗时可很长，需充足 GPU 显存与内存。
+
+---
+
+## 10. 常见问题与处理
+
+| 现象 | 处理 |
+|------|------|
+| `ModuleNotFoundError: setuptools_git_versioning` | 执行第 2.1 节 `pip install` |
+| `BUILD_ROCM_VERSION is not set` | `export BUILD_ROCM_VERSION=X.Y` 后再运行 `setup.py` |
+| `AttributeError: 'Version' object has no attribute 'split'` | 完成第 5.1 节 `setup.py` 修改 |
+| `redefinition of 'hipDeviceProp_t_v2'` | 编译参数中**不要**包含 `-DhipDeviceProp_t=hipDeviceProp_t_v2` |
+| `hipDeviceProp_t` / `hipDeviceProp_t_v2` 转换错误 | 完成第 5.3 B、5.4、5.5 节后 **`rm -rf _skbuild build` 再编** |
+| `import fbgemm_gpu` 报缺 `fbgemm_gpu_config.so` | `cd /tmp` 并 `unset PYTHONPATH`；勿把 `fbgemm_gpu` 源码目录放在 `PYTHONPATH` 首位 |
+| `git clone` / TLS 失败 | 配置代理或使用 GitHub 加速前缀后重试 |
+| 子模块过慢 | `git submodule update --init --recursive --jobs 6` |
+
+---
+
+## 11. 版本与维护说明
+
+- 本文针对 **DTK 26.04 + PyTorch HIP + FBGEMM v1.3.0** 整理。  
+- 若升级 DTK / PyTorch / FBGEMM 标签，请重新核对：`BUILD_ROCM_VERSION`、`ROCM_PATH`、`PYTORCH_ROCM_ARCH` 及 PyTorch 与 `getDeviceProperties` 相关头文件是否变化。

FBGEMM_GPU_构建与测试说明.md

+# FBGEMM GPU（ROCm / 海光 DTK）构建、安装与测试说明
+
+本文档与仓库内 [install_fbgemm.md](./install_fbgemm.md) 配套：`install_fbgemm.md` 侧重镜像与总体流程；本文记录在实际 **DTK 26.x + PyTorch 2.5.1 HIP** 环境下踩坑后的**可复现命令**、**代码改动原则**与**测试方法**。
+
+---
+
+## 1. 环境前提
+
+- PyTorch 为 **ROCm/HIP** 构建（`torch.version.hip` 有版本号，`torch.version.cuda` 常为 `None`）。
+- 已安装 **DTK/ROCm**（常见路径 `/opt/dtk`，具体以本机 `hipconfig`、`ROCM_PATH` 为准）。
+- **GPU 架构**：海光 DCU 常见为 `gfx936`（与 `install_fbgemm.md` 中 `PYTORCH_ROCM_ARCH` 一致，按实际驱动/设备调整）。
+- Python 构建依赖（示例）：
+
+  ```bash
+  pip install setuptools_git_versioning scikit-build tabulate ninja cmake patchelf
+  ```
+
+---
+
+## 2. 源码与网络（代理）
+
+```bash
+# 按需选用可访问 GitHub 的代理脚本（以本仓库 ws/proxy 为例）
+source /workspace/ws/proxy/set_proxy_bj.sh
+
+git clone https://github.com/pytorch/FBGEMM.git --branch v1.3.0 --depth 1
+cd FBGEMM
+git submodule update --init --recursive --jobs 6
+```
+
+说明：子模块较多（含较大仓库如 cutlass），仅北京代理可达时保留 `--jobs` 可缩短拉取时间；若某代理不可达（`No route to host`），换同目录下其他 `set_proxy_*.sh` 再执行 submodule。
+
+---
+
+## 3. 系统与小改动（与 install_fbgemm 一致部分）
+
+```bash
+sudo ln -sf /lib/x86_64-linux-gnu/librt.so.1 /usr/lib/x86_64-linux-gnu/librt.so
+```
+
+---
+
+## 4. DTK 版本差异：请勿混用旧文档里的 `hipDeviceProp_t` 宏
+
+`install_fbgemm.md` 中在 **CMAKE_CXX_FLAGS / CMAKE_HIP_FLAGS** 里增加：
+
+`-DhipDeviceProp_t=hipDeviceProp_t_v2`
+
+在 **DTK 26.x** 的 HIP 头文件中，`hipDeviceProp_t` 与 `hipDeviceProp_t_v2` **均已定义**，再全局 typedef 宏会导致 **重复定义** 编译错误。
+
+在 **DTK 26.x + PyTorch 返回 `hipDeviceProp_t_v2*`** 时，应：
+
+- **去掉**上述 `-DhipDeviceProp_t=hipDeviceProp_t_v2`；
+- 在 **CUDA 源码**侧做类型兼容（见下一节），由 **hipify** 生成 HIP 代码。
+
+---
+
+## 5. 代码补丁原则：只改会被 hipify 的 CUDA 源，不要长期改生成文件
+
+配置 ROCm 时，CMake 会对 `fbgemm_gpu` 下 **`.cu` / `.cuh`** 做 **hipify**，重新生成 `*_hip.cuh`、`*.hip` 等。  
+**直接修改生成文件会在下次配置/编译时被覆盖。**
+
+已在实践中验证有效的改法包括：
+
+| 目的 | 修改文件（示例） |
+|------|------------------|
+| `CUDA_KERNEL_ASSERT2` / DSA 与 DTK 不匹配 | `src/sparse_ops/common.cuh`、`include/.../embedding_bounds_check_common.cuh`、`test/utils/kernel_launcher_test.cu`：在 `#ifdef USE_ROCM` 下 `#undef CUDA_KERNEL_ASSERT2` 并定义为 `((void)0)` |
+| `kernelLaunchCheck` 中 HIP 辅助符号与当前 PyTorch 不一致 | `include/fbgemm_gpu/utils/kernel_launcher.cuh`：`#ifdef USE_ROCM` 时缩短 `TORCH_CHECK` 错误信息，避免依赖缺失的 host API |
+| `hipDeviceProp_t` vs `hipDeviceProp_t_v2` | `include/fbgemm_gpu/utils/kernel_launcher.cuh`：四个 `check*` 改为 `template <typename DeviceProperties>`；`include/fbgemm_gpu/utils/cuda_prelude.cuh` 与部分 `.cu` 中 `getDeviceProperties` **不要**再声明为 `cudaDeviceProp*`/`hipDeviceProp_t*`，改为直接 `return getDeviceProperties(...)->multiProcessorCount` |
+| 新版 `setuptools_git_versioning` 返回 `Version` 对象 | `setup.py`：`str(gitversion.version_from_git()).split("+")[0]` |
+
+---
+
+## 6. 编译命令（推荐）
+
+在 **`FBGEMM/fbgemm_gpu`** 目录：
+
+```bash
+cd FBGEMM/fbgemm_gpu
+rm -rf _skbuild build
+
+export BUILD_ROCM_VERSION=6.3          # 与当前 ROCm/DTK 主版本一致，格式 X.Y
+export PYTORCH_ROCM_ARCH="gfx936"     # 按实际 GPU 调整
+export ROCM_PATH=/opt/dtk             # 按实际安装路径调整
+
+TORCH_PATH="$(python3 -c "import torch, os; print(os.path.join(os.path.dirname(torch.__file__), 'share/cmake/Torch'))")"
+
+python3 setup.py bdist_wheel \
+  --package_channel=release \
+  --build-target=default \
+  --build-variant=rocm \
+  -DCMAKE_PREFIX_PATH="${TORCH_PATH};${ROCM_PATH}" \
+  -DAMDGPU_TARGETS="${PYTORCH_ROCM_ARCH}" \
+  -DTORCH_DIR="${TORCH_PATH}" \
+  -DCMAKE_C_FLAGS="-Wno-return-type -Wno-ignored-attributes -O1" \
+  -DCMAKE_CXX_FLAGS="-Wno-return-type -Wno-ignored-attributes -O1" \
+  -DCMAKE_HIP_FLAGS="-Wno-return-type -O1" \
+  -DUSE_AVX512=on \
+  -DCOPY_VISIBLE_LIBRARIES=ON \
+  -DCMAKE_SHARED_LINKER_FLAGS="-Wl,--no-as-needed -ltbb -Wl,-rpath,/usr/lib/x86_64-linux-gnu" \
+  -DTBB_INCLUDE_DIR=/usr/include
+```
+
+要点：
+
+- 必须使用 **`--build-variant=rocm`**；仅传 `-DFBGEMM_BUILD_VARIANT=rocm` 而不传 setup.py 参数时，`setup.py` 仍可能按默认 CUDA 逻辑处理部分步骤。
+- **`BUILD_ROCM_VERSION`** 为 `setup.py` / CMake 中 ROCm 工具链逻辑所需，缺省会报错。
+
+成功后 wheel 一般在：`fbgemm_gpu/dist/fbgemm_gpu_rocm-1.3.0-*.whl`（版本号以构建输出为准）。
+
+---
+
+## 7. 安装与 Python 验证
+
+```bash
+pip install fbgemm_gpu/dist/fbgemm_gpu_rocm-*.whl
+# 若 PyPI 不可用，可：pip install --no-deps <wheel路径>
+```
+
+验证（**不要**在 `fbgemm_gpu` 源码根目录下把源码当作包导入，否则可能找不到已安装的 `.so`）：
+
+```bash
+cd /tmp
+python3 -c "import torch; import fbgemm_gpu; print('OK', fbgemm_gpu.__variant__, fbgemm_gpu.__file__)"
+```
+
+---
+
+## 8. 运行测试（Pytest 子集示例）
+
+在 **`FBGEMM/fbgemm_gpu/test`** 目录：
+
+```bash
+cd FBGEMM/fbgemm_gpu/test
+export FBGEMM_TEST_WITH_ROCM=1
+export HIP_LAUNCH_BLOCKING=1    # 可选，便于定位异步错误
+unset PYTHONPATH                  # 避免优先 import 源码树中的 fbgemm_gpu
+
+python3 -m pytest -v -rsx --tb=short \
+  config/feature_gate_test.py \
+  sparse/pack_segments_test.py \
+  sparse/index_select_test.py \
+  sparse/cumsum_test.py \
+  quantize/fused_8bit_rowwise_test.py
+```
+
+全量测试可参考上游 `.github/scripts/fbgemm_gpu_test.bash` 中 `test_all_fbgemm_gpu_modules`（耗时可很长，需 ROCm 环境与足够显存/内存）。
+
+---
+
+## 9. 常见问题
+
+| 现象 | 处理 |
+|------|------|
+| `gnutls_handshake` / clone 失败 | 使用可访问 GitHub 的代理后重试 `git clone` / `submodule update` |
+| `hipDeviceProp_t_v2` 重定义 | 去掉编译参数中的 `-DhipDeviceProp_t=hipDeviceProp_t_v2`（DTK 26.x） |
+| `hipDeviceProp_t` 与 `hipDeviceProp_t_v2` 不兼容 | 确保修改 **CUDA 源**中 `kernel_launcher.cuh` 的模板化 `check*` 与 `cuda_prelude.cuh` 等，并重新配置使 hipify 再生 HIP 文件 |
+| `import fbgemm_gpu` 报缺 `fbgemm_gpu_config.so` | 当前工作目录或 `PYTHONPATH` 指到了未编译的源码包；换到 `/tmp` 或卸载路径冲突 |
+| `BUILD_ROCM_VERSION is not set` | 导出 `BUILD_ROCM_VERSION=X.Y` 后再运行 `setup.py` |
+
+---
+
+## 10. 相关文件
+
+- 环境与镜像：[install_fbgemm.md](./install_fbgemm.md)
+- 代理脚本：`/workspace/ws/proxy/set_proxy_*.sh`
+- 上游 ROCm CI：FBGEMM 仓库 `.github/workflows/fbgemm_gpu_ci_rocm.yml`
+
+---
+
+*文档基于 FBGEMM v1.3.0、PyTorch 2.5.1 HIP、DTK 26.x 类环境整理；若你方镜像仍为 DTK 25.04.2，请仍以 `install_fbgemm.md` 为准并单独验证 `hipDeviceProp_t` 宏是否仍需要。*

dlrm-v2_inference.md

+# DLRM-v2 下载、安装、模型与数据准备说明
+
+本文档覆盖从 `https://github.com/mlcommons/inference` 下载代码，到环境安装，再到 `dlrm_v2` 模型和数据下载，以及合成数据快速跑通方法。
+
+## 1. 仓库下载（固定 v5.1）
+
+```bash
+cd /workspace
+git clone --branch v5.1 --recurse-submodules https://github.com/mlcommons/inference.git inference-master
+```
+
+若已下载可跳过，直接进入：
+
+```bash
+cd /workspace/inference-master
+```
+
+若仓库已存在且需要切到 `v5.1`：
+
+```bash
+cd /workspace/inference-master
+git fetch --tags
+git checkout v5.1
+git submodule update --init --recursive
+```
+
+## 1.1 容器环境启动（参考）
+
+可参考以下方式启动推理容器环境（基于你提供的命令整理）：
+
+```bash
+docker run -it --network=host \
+  --name=inference_mlcommons \
+  --privileged=true \
+  --shm-size=1024G \
+  --device=/dev/kfd \
+  --device=/dev/mkfd \
+  --device=/dev/dri/ \
+  --cap-add=SYS_PTRACE \
+  --security-opt seccomp=unconfined \
+  --ulimit memlock=-1:-1 \
+  --ipc=host \
+  --group-add video \
+  -v /home/models:/workspace/models \
+  -v /home/ws:/workspace/ws \
+  -v /opt/hyhal:/opt/hyhal:ro \
+  harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.11.0-ubuntu22.04-dtk26.04-0130-py3.10-20260211 \
+  /bin/bash
+```
+
+进入容器后再执行本文后续步骤（代码下载、依赖安装、模型/数据准备和运行）。
+
+## 2. 环境安装（DLRM-v2）
+
+### 2.1 基础 Python 依赖
+
+```bash
+python -m pip install --user pybind11 scikit-learn tqdm
+python -m pip install --user torchsnapshot
+```
+
+### 2.2 安装 LoadGen
+
+```bash
+cd /workspace/inference-master/loadgen
+CFLAGS="-std=c++14" python setup.py install --user
+```
+
+### 2.3 DLRM 关键版本建议（当前环境验证通过）
+
+- `torch`：按机器当前可用版本
+- `fbgemm_gpu`：`1.3.0`
+- `torchrec`：建议与 `fbgemm_gpu` 对齐为 `1.3.0`
+
+示例：
+
+```bash
+python -m pip install --user --no-deps --force-reinstall torchrec==1.3.0
+python -m pip install --user iopath pyre-extensions tensordict torchmetrics==1.0.3
+```
+
+### 2.4 FBGEMM 编译安装参考
+
+`fbgemm_gpu` 的编译和安装请参考以下文档，并按文档中的版本约束执行：
+
+- `/workspace/mlcommon_inference/FBGEMM_GPU_DTK26.04_编译安装指南.md`
+
+在本项目（`dlrm_v2`）中，建议保持：
+
+- `fbgemm_gpu==1.3.0`
+- `torchrec==1.3.0`（与 `fbgemm_gpu` 对齐）
+
+## 3. 使用代理与镜像（可选）
+
+如果外网不稳定，可先启用代理（示例）：
+
+```bash
+source /workspace/ws/proxy/set_proxy_bj.sh
+```
+
+使用清华源安装（示例）：
+
+```bash
+python -m pip install --user -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn scikit-learn
+```
+
+## 4. 模型和数据下载（正式大规模）
+
+> 注意：正式数据和权重很大。模型约 97GB，数据集更大（单文件可达 142GB 级别）。
+
+### 4.1 创建目录
+
+```bash
+mkdir -p /workspace/inference-master/recommendation/dlrm_v2/pytorch/model
+mkdir -p /workspace/inference-master/recommendation/dlrm_v2/pytorch/dataset
+```
+
+### 4.2 下载模型权重
+
+```bash
+cd /workspace/inference-master/recommendation/dlrm_v2/pytorch/model
+bash <(curl -s https://raw.githubusercontent.com/mlcommons/r2-downloader/refs/heads/main/mlc-r2-downloader.sh) -d . \
+  https://inference.mlcommons-storage.org/metadata/dlrm-v2-model-weights.uri
+```
+
+### 4.3 下载预处理数据集
+
+```bash
+cd /workspace/inference-master/recommendation/dlrm_v2/pytorch/dataset
+bash <(curl -s https://raw.githubusercontent.com/mlcommons/r2-downloader/refs/heads/main/mlc-r2-downloader.sh) -d . \
+  https://inference.mlcommons-storage.org/metadata/dlrm-v2-preprocessed-dataset.uri
+```
+
+## 5. 合成数据快速跑通（推荐先做）
+
+适用于先验证流程，不下载超大模型和数据。
+
+### 5.1 生成合成数据
+
+```bash
+cd /workspace/inference-master/recommendation/dlrm_v2/pytorch/tools
+bash make_fake_criteo.sh
+```
+
+数据目录：
+
+- `/workspace/inference-master/recommendation/dlrm_v2/pytorch/tools/fake_criteo`
+
+### 5.2 GPU 运行命令（已验证）
+
+```bash
+cd /workspace/inference-master/recommendation/dlrm_v2/pytorch
+
+export DATA_DIR=/workspace/inference-master/recommendation/dlrm_v2/pytorch/tools/fake_criteo
+export MODEL_DIR=/workspace/inference-master/recommendation/dlrm_v2/pytorch/model
+export WORLD_SIZE=1
+
+python python/main.py \
+  --profile dlrm-debug-pytorch \
+  --model dlrm \
+  --model-path "$MODEL_DIR/dlrm_debug.pytorch" \
+  --dataset debug \
+  --dataset-path "$DATA_DIR" \
+  --output /workspace/inference-master/recommendation/dlrm_v2/pytorch/output/pytorch-gpu/dlrm_synth \
+  --scenario Offline \
+  --count-samples 64 \
+  --samples-to-aggregate-fix 128 \
+  --max-batchsize 128 \
+  --samples-per-query-offline 1 \
+  --use-gpu
+```
+
+## 6. 成功标志
+
+日志中出现以下信息即表示跑通：
+
+- `Using X GPU(s)...`
+- `TestScenario.Offline qps=...`
+
+输出目录示例：
+
+- `/workspace/inference-master/recommendation/dlrm_v2/pytorch/output/pytorch-gpu/dlrm_synth`
+
+## 7. 常见问题
+
+### 7.1 `run_local.sh` 报 `unrecognized arguments`
+
+可直接使用本文第 5.2 节 `python/main.py` 命令绕过。
+
+### 7.2 `model` 目录为空是否正常
+
+若仅跑 `debug` 合成数据场景，正常。该模式不依赖完整 97GB 正式权重。
+
+### 7.3 依赖安装慢或失败
+
+优先检查代理、镜像源和磁盘空间，再重试。