# PR #49837 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[CI][ROCm] Make hf-xet reconstruction safe on shared NFS
- 合并时间：2026-07-27 17:23
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/49837

---

# 执行摘要

- 一句话：修复 ROCm CI 中 hf-xet 在共享 NFS 上的安全问题
- 推荐动作：低风险、高收益的 CI 稳定性修复，建议快速合并。

# 功能与动机

在共享 NFS 上运行 ROCm CI 时，高并发的 hf-xet vectored writes 可能导致数据损坏，如 Buildkite build #11196 所示。需要让 xet 的永久缓存保留在共享 NFS 上，但将临时状态移到本地存储，并禁用高性能 vectored 重建模式。

# 实现拆解

1. **检测 NFS 文件系统**：在 `initialize_native_environment()` 函数中，新增变量 `hf_fstype`，使用 `findmnt` 命令查询 `${HF_HOME}` 挂载点的文件系统类型。
2. **设置环境变量**：若类型为 `nfs` 或 `nfs4`，则设置 `HF_XET_CACHE` 为本地路径（`native_root/cache/hf-xet`），并禁用 `HF_XET_HIGH_PERFORMANCE` 和 `HF_XET_RECONSTRUCTION_USE_VECTORED_WRITE`。
3. **创建缓存目录**：使用 `mkdir -p` 确保本地缓存目录存在，失败时返回非零退出码。
4. **日志输出**：打印配置信息以便调试。

关键文件：
- `.buildkite/scripts/hardware_ci/run-amd-test.sh`（模块 CI 脚本；类别 infra；类型 infrastructure；符号 initialize_native_environment）: 唯一变更文件，包含 NFS 检测逻辑和环境变量设置。

关键符号：initialize_native_environment

## 关键源码片段

### `.buildkite/scripts/hardware_ci/run-amd-test.sh`

唯一变更文件，包含 NFS 检测逻辑和环境变量设置。

```bash
# 在 initialize_native_environment() 函数中
local hf_fstype=""

# 使用 findmnt 检测 HF_HOME 挂载的文件系统类型
if command -v findmnt >/dev/null 2>&1; then
    hf_fstype=$(findmnt -n -T "${HF_HOME}" -o FSTYPE 2>/dev/null || true)
fi

# 如果是 NFS 类型，则调整 xet 配置
if [[ "${hf_fstype}" == nfs || "${hf_fstype}" == nfs4 ]]; then
    # Keep hf-xet state local and avoid vectored writes on shared NFS.
    export HF_XET_CACHE="${native_root}/cache/hf-xet"
    export HF_XET_HIGH_PERFORMANCE=0
    export HF_XET_RECONSTRUCTION_USE_VECTORED_WRITE=0
    mkdir -p "${HF_XET_CACHE}" || return 1
    echo "Configured hf-xet for shared ${hf_fstype} cache at ${HF_HOME}"
fi

```

# 评论区精华

无显著的 review 讨论；tjtanaa 直接批准了变更。

- 暂无高价值评论线程

# 风险与影响

- 风险：低风险：仅当 `findmnt` 可用且 `HF_HOME` 在 NFS 上时才会触发变更；对非 NFS 环境无影响。潜在风险是 `findmnt` 命令在部分镜像中不可用，但已通过 `command -v` 检查。
- 影响：仅影响 ROCm CI 运行环境，特别是使用共享 NFS 存储 `HF_HOME` 的机器。预计会消除因 vectored writes 导致的 CI 不稳定，而不会影响缓存命中率。
- 风险标记：CI 脚本变更 , 低风险

# 关联脉络

- 暂无明显关联 PR