[Build] Keep NVSHMEM available for FlashMask

[ShigureNyako]

PR Category

Environment Adaptation

PR Types

Bug fixes

Description

修复 #79170 合入后 H-Coverage / FlashMask V3 仍需要 NVSHMEM 的场景。

#79170 已经在 DeepEP 相关 CMake 入口禁用了 GPU DeepEP；但它额外在 cmake/third_party.cmake 中对所有非 XPU 构建强制 WITH_NVSHMEM=OFF。这会覆盖 H-Coverage 显式传入的 -DWITH_NVSHMEM=ON，导致 extern_nvshmem 不再进入 third_party 依赖，而 libflashmaskv2.so 运行时仍需要 NVSHMEM 相关动态库。

在 #79233 的 CI-H / Coverage test 中可复现：

RuntimeError: (PreconditionNotMet) The third-party dynamic library (libflashmaskv2.so) that Paddle depends on is not configured correctly.
(error code is nvshmem_bootstrap_uid.so.3: cannot open shared object file: No such file or directory)

本 PR 将 FlashAttention 是否会启用先计算出来，再用于收窄 NVSHMEM gate：

• 非 XPU 构建下，只有 WITH_GPU + WITH_DISTRIBUTE + sm90 + FlashAttention 同时满足时，显式 WITH_NVSHMEM=ON 才会保留。
• XPU 场景不再被非 XPU gate 误伤。
• external/nvshmem 仍在 external/flashattn 之前引入，保证 FlashAttention 开启 overlap 时可以依赖 extern_nvshmem。
• GPU DeepEP 仍保持 [Build] Retire DeepEP(GPU) and DeepGemm for non-XPU builds #79170 中的禁用状态，不在本 PR 中恢复。

相关上下文：

• 【Hackathon 10th Spring No.51】Apply yaml-cpp GCC 15 compatibility patch - part 5 #79233: CI-H / Coverage test 稳定失败
• [Build] Retire DeepEP(GPU) and DeepGemm for non-XPU builds #79170: 引入非 XPU 强制关闭 NVSHMEM
• [CI] Upgrade H-Coverage to Python 3.12 #79203: H-Coverage FA Test 现在会正确暴露 FlashMask 失败，不再被 run.sh 返回码覆盖

是否引起精度变化

否

验证

• git diff --check
• cmake-format --check cmake/third_party.cmake
• commit hook / pre-commit for cmake/third_party.cmake passed, including cmake-format and CMake Lint
• grep sanity：确认 external/nvshmem 仍早于 external/flashattn，FlashAttention 只 include 一次，且未恢复 GPU DeepEP

未运行完整 H-Coverage；该验证需要 CI 环境。

[ShigureNyako]

自查完成：

• 变更范围只包含 cmake/third_party.cmake，删除 [Build] Retire DeepEP(GPU) and DeepGemm for non-XPU builds #79170 中过宽的非 XPU WITH_NVSHMEM=OFF 覆盖。
• 原有 WITH_GPU + WITH_DISTRIBUTE + sm90 约束仍保留；没有恢复 GPU DeepEP 相关 CMake 入口。
• 已通过 git diff --check，commit hook 中 cmake-format / CMake Lint 等也通过。

@SigureMo 麻烦帮忙看一下。这个修复对应 #79233 里 CI-H / Coverage test 的 libflashmaskv2.so 缺 nvshmem_bootstrap_uid.so.3 问题。

[SigureMo]

是否可以，在 XPU OR FA 的场景下开启，感觉不用 FA 的场景也不用 nvshmem

[ShigureNyako]

已按这个方向收窄：

• 先预计算本次构建是否会启用 FlashAttention。
• 非 XPU 下，WITH_NVSHMEM=ON 只有在 WITH_GPU + WITH_DISTRIBUTE + sm90 + FlashAttention 都满足时才保留；不用 FA 的非 XPU 场景会继续关掉 NVSHMEM。
• XPU 场景不走这个非 XPU gate。
• external/nvshmem 仍然在 external/flashattn 前 include，避免 FA overlap 依赖 extern_nvshmem 时顺序出问题。

也确认没有恢复 GPU DeepEP。

[ShigureNyako]

/re-run all-failed

[Copilot]

Pull request overview

This PR adjusts Paddle’s third-party CMake dependency logic to avoid incorrectly forcing WITH_NVSHMEM=OFF in non-XPU builds, so that FlashMask/FlashAttention overlap scenarios (e.g., H-Coverage) can still pull in NVSHMEM when explicitly requested.

Changes:

• Introduces FLASHATTN_ENABLED as a precomputed flag and defers external/flashattn inclusion until after NVSHMEM handling.
• Narrows the non-XPU NVSHMEM “force-off” gate to only disable NVSHMEM when GPU + distributed + sm90 + FlashAttention conditions aren’t met.
• Preserves the intended include ordering: external/nvshmem before external/flashattn.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ShigureNyako]

/re-run all-failed

[SigureMo]

merge 下最新 develop 吧，build 一直挂

[ShigureNyako]

已 merge 最新 develop 并推送，当前 head 是 89bbdcf1f1。

本次 merge 带入了 develop 上的 .gitmodules / third_party/gloo 更新；本地检查通过：

• git diff --check HEAD^1..HEAD
• pre-commit run --files .gitmodules cmake/third_party.cmake

新一轮 CI 已开始，继续看 Linux-build 结果。

[ShigureNyako]

/re-run all-failed

[swgu98]

@ShigureNyako build挂了，看下为什么

[ShigureNyako]

看了当前失败的 Linux-build / Build（job 79465067697），这次失败不在 NVSHMEM / FlashMask 编译路径上。

关键信息：

• 本轮 bdist_wheel 已完成，日志里能看到 Build Time: 827s，flashattn.h / flashmaskv2.h / flashattnv3.h 也已进入 wheel 打包流程。
• 失败发生在 ci/run_setup.sh 后置生成 API spec 时：切到 develop 后，因 dev wheel 缓存未命中，执行 git submodule update --init。
• 此时 third_party/gloo 已被 cmake/external/gloo.cmake 的 GLOO_PATCH_COMMAND 切到旧的 GLOO_TAG v0.0.3（8b6b61d...）并打了 patches/gloo/types.h.patch，submodule 处于 dirty 状态。
• 但最新 develop 通过 [ThirdParty] Update gloo submodule to PFCCLab paddle branch #79230 已将 third_party/gloo 指针更新到 5a4c337...，所以 checkout 被 dirty 的 gloo/types.h 挡住：

M third_party/gloo
error: Your local changes to the following files would be overwritten by checkout:
    gloo/types.h
Unable to checkout '5a4c337dd9a99f09aa0a688aa2088ed1f9c1cbcd' in submodule path '../third_party/gloo'

结论：这是 develop 上 gloo submodule 指针与 cmake/external/gloo.cmake 仍 checkout 旧 tag 不一致导致的 CI 后置步骤失败，不是本 PR 的 NVSHMEM / FlashMask 变更导致。当前不继续盲目 rerun；gloo 侧同步修复或 dev wheel 缓存可用后再触发即可。

[ShigureNyako]

@swgu98 我看了当前这次 Linux-build / Build 失败（job 79465067697），不是这次 CMake/NVSHMEM 变更触发的编译错误。

失败点在 CI 后处理切分/切分前切分支时，third_party/gloo 子模块工作区已经有本地改动，导致 checkout 被 git 拒绝：

M	third_party/gloo
error: Your local changes to the following files would be overwritten by checkout:
	gloo/types.h
Aborting
Unable to checkout '5a4c337dd9a99f09aa0a688aa2088ed1f9c1cbcd' in submodule path '../third_party/gloo'

这条更像 runner 工作区 / submodule 状态污染；日志里没有看到 cmake/third_party.cmake、NVSHMEM 或 FlashAttention 相关的编译报错。当前 PR diff 仍只包含 cmake/third_party.cmake，我会继续等剩余 Coverage/平台 CI 收敛。

[SigureMo]

@ShigureNyako 你真的 merge 最新 develop 了吗？ShigureNyako/Paddle@fix/keep-nvshmem-for-flashmask...PaddlePaddle:Paddle:develop 显示 4 behind！

[SigureMo]

另外没事不要 force push，都看不到你的改动

[ShigureNyako]

已同步，这次使用普通 merge/push，没有 force push。

刚才 develop 又前进了 4 个 commit，我已重新 merge 最新 upstream/develop，当前 head 是 da334fd929，compare 里已没有 behind。

本地检查：

• git diff --check HEAD^1..HEAD
• pre-commit run --files cmake/third_party.cmake

另外收到，后续非必要不再 force push，避免影响看 diff。

[ShigureNyako]

/re-run all-failed

[SigureMo]

@ShigureNyako 看起来不是 merge 能解决的，看来是 #79230 引入的问题，定位下问题并解决下吧，不然永远合入不了

[SigureMo]

应该是两层 patch 导致的，@gouzil 在将 repo 内 patch 移到 PFCCLab/gloo，你先别改吧，等 @gouzil 通知，完事之后应该就可以清理掉 patch 并更新 PFCCLab/gloo commit 了

[ShigureNyako]

收到，我先不改 gloo 相关文件，等 @gouzil 通知。

后续等 PFCCLab/gloo 侧 patch 准备好后，我再只做对应的同步动作：清理 Paddle repo 内的 gloo patch，并更新 third_party/gloo 到新的 PFCCLab/gloo commit；同时保持本 PR 的 NVSHMEM / FlashMask 变更范围不扩大。

[ShigureNyako]

更新一下当前 head da334fd929 的 CI 结论：

• Coverage build 已通过，Coverage test 也已通过（job 79491377752），其中 FA Test step 成功；这条能覆盖本 PR 修复的 FlashMask / NVSHMEM 路径。
• 剩余非绿项目前看不是本 PR 的 NVSHMEM / CMake 改动导致：
  • PR-CI-Inference / Build（job 79472674598）失败在下载 Paddle.tar.gz / update test branch 阶段，未进入构建；
  • Linux-build / Build（job 79472676369）仍是 third_party/gloo / gloo/types.h checkout 冲突，等待 [ThirdParty] Update gloo and remove local patch application #79245 合入处理；
  • Linux-DCU / Build（job 79473109657）结论是 cancelled，但 Run build 和上传产物步骤均已成功，未看到编译错误。

我先不改 gloo 相关内容，也不继续 rerun，等 #79245 进展后再同步/复查。

[swgu98]

从 CMake 配置语义上看，这个方向还可以再收一下：用户显式传入的 -DWITH_NVSHMEM=ON 优先级应该最高，不太应该被后续逻辑静默覆盖成 OFF。

当前 PR 相比 #79170 已经明显收窄了影响范围，能恢复 FlashMask / H-Coverage 需要 NVSHMEM 的场景，作为止血修复是合理的。但现在非 XPU 下仍然会根据 WITH_GPU + WITH_DISTRIBUTE + sm90+ + FlashAttention 这组条件把用户传入的 WITH_NVSHMEM=ON 改成 OFF。这会让配置结果和用户输入不一致，排查时也比较隐蔽。

我倾向于把“用户是否请求 NVSHMEM”和“当前构建是否满足 NVSHMEM 支持条件”分开处理：

• 如果用户没有显式开启 NVSHMEM，可以按内部依赖关系决定是否启用；
• 如果用户显式传了 WITH_NVSHMEM=ON，但当前平台 / 架构 / 依赖条件不满足，建议 message(FATAL_ERROR ...)，至少也应该 message(WARNING ...)，而不是静默 set(WITH_NVSHMEM OFF)；
• 可以考虑引入类似 NVSHMEM_AVAILABLE / NVSHMEM_REQUIRED_BY_FLASHATTN 这类 effective 变量，避免把用户输入变量当作内部派生状态反复改写。

也就是说，这个 PR 现在作为修复 FlashMask 缺 NVSHMEM 的补丁可以接受，但从长期可维护性看，更合理的是尊重用户显式 CMake 参数：能构建就按用户要求构建，不能构建就明确失败并说明原因。

[swgu98]

@ShigureNyako 狗子已经合入了，拉新吧，并且关注下我的评论，我建议你不要太hack过CI，尊重用户的cmake参数，不要盲目nvshmem设为OFF（虽然原本就这么乱写的）

[ShigureNyako]

#79245 已合入，我已用普通 merge/push 同步最新 develop，当前 head 是 0dc25f401c（没有 force push）。

同步后本 PR 相对最新 develop 的 diff 仍只剩 cmake/third_party.cmake，gloo patch 清理和 third_party/gloo 更新已由 develop 带入。

本地检查：

• git diff --check HEAD^1..HEAD
• pre-commit run --files cmake/third_party.cmake cmake/external/gloo.cmake cmake/external/yaml.cmake patches/yaml-cpp/emitterutils.cpp.patch

新一轮 CI 已重新开始，继续看结果。

[ShigureNyako]

@swgu98 已按你的 CMake 语义意见处理，并且 #79245 合入后也已经拉了最新 develop；这次仍是普通 push，没有 force push。当前 head 是 6d8c56681e。

这次补充改动只在 cmake/third_party.cmake：

• 用 WITH_NVSHMEM_USER_DEFINED 识别用户通过 CMake cache 显式传入的 -DWITH_NVSHMEM=ON；
• 用 NVSHMEM_AVAILABLE 表达当前构建是否满足 NVSHMEM 支持条件；
• XPU 构建不受非 XPU 的 GPU/FlashAttention gate 限制；
• 非 XPU 下仍要求 WITH_GPU + WITH_DISTRIBUTE + sm90+ + FLASHATTN_ENABLED；
• 如果用户显式 WITH_NVSHMEM=ON 但条件不满足，现在会 message(FATAL_ERROR ...)，不再静默改成 OFF；
• 非显式/内部派生场景仍保留原来的 fallback 行为，可以在不可用时设为 OFF。

本地检查通过：

• git diff --check
• pre-commit run --files cmake/third_party.cmake

新 commit 导致之前 approve 被 dismiss 了，新一轮 CI 已开始，麻烦再看一下。

[SigureMo]

从 CMake 配置语义上看，这个方向还可以再收一下：用户显式传入的 -DWITH_NVSHMEM=ON 优先级应该最高，不太应该被后续逻辑静默覆盖成 OFF。

当前 PR 相比 #79170 已经明显收窄了影响范围，能恢复 FlashMask / H-Coverage 需要 NVSHMEM 的场景，作为止血修复是合理的。但现在非 XPU 下仍然会根据 WITH_GPU + WITH_DISTRIBUTE + sm90+ + FlashAttention 这组条件把用户传入的 WITH_NVSHMEM=ON 改成 OFF。这会让配置结果和用户输入不一致，排查时也比较隐蔽。

我倾向于把“用户是否请求 NVSHMEM”和“当前构建是否满足 NVSHMEM 支持条件”分开处理：

• 如果用户没有显式开启 NVSHMEM，可以按内部依赖关系决定是否启用；
• 如果用户显式传了 WITH_NVSHMEM=ON，但当前平台 / 架构 / 依赖条件不满足，建议 message(FATAL_ERROR ...)，至少也应该 message(WARNING ...)，而不是静默 set(WITH_NVSHMEM OFF)；
• 可以考虑引入类似 NVSHMEM_AVAILABLE / NVSHMEM_REQUIRED_BY_FLASHATTN 这类 effective 变量，避免把用户输入变量当作内部派生状态反复改写。

也就是说，这个 PR 现在作为修复 FlashMask 缺 NVSHMEM 的补丁可以接受，但从长期可维护性看，更合理的是尊重用户显式 CMake 参数：能构建就按用户要求构建，不能构建就明确失败并说明原因。

你怎么比我家猫还人机 @swgu98

[ShigureNyako]

/re-run all-failed

[ShigureNyako]

Model-Benchmark rerun 也看过了，当前失败仍是同一个外部 PaddleX benchmark/harness 问题，不是这个 PR 的 NVSHMEM/CMake 变更导致的。

日志里失败点在 PaddleX_semantic_segmentation_Deeplabv3-R50_bs4_fp32_DP_dynamic_N1C1：

paddlex.utils.errors.others.UnsupportedParamError: 'Deeplabv3-R50' is not a registered model name.
...
ERROR!!! too few logs printed
...
result_FLAG: 10
...
fail; Runtime error, please contact RD for repair.

这次 rerun job 是：
https://github.com/PaddlePaddle/Paddle/actions/runs/26960704164/job/79573628880

本 PR 当前相对 develop 的有效改动仍只在 cmake/third_party.cmake，与 PaddleX 模型注册/benchmark case 无关。这个失败已 rerun 后复现，我这边不再重复触发 rerun，继续等剩余 CI（Coverage test / Linux-DCU）。

[ShigureNyako]

Coverage test 已完成且通过了；当前 head 剩余失败是：

• Linux-DCU / Test
• Model-Benchmark / Benchmark test

Linux-DCU 这边日志看起来也是无关 flaky / harness 行为：初始阶段有 test_initializer 断言、test_for_enumerate SIGSEGV、test_cdist 150s timeout 等失败，但 job 内部 rerun 后 test_for_enumerate、test_onednn_conv_affine_channel_fuse_pass_pir、test_cdist、test_initializer 都通过了，最后是 harness 因 “success rate is less than 50%” 仍汇总为 1200 - test_cdist (Timeout)。本 PR 当前有效 diff 仍只在 cmake/third_party.cmake，没有涉及 DCU / test_cdist。

Model-Benchmark 的复现问题前面已留证，是外部 PaddleX benchmark/harness 的 Deeplabv3-R50 注册问题：
#79240 (comment)

我这边尝试过直接 rerun Linux-DCU job，但 GitHub Actions 权限不允许；PR 的 rerun workflow 也没有单独 DCU 入口。因此等 Coverage 结束后，对当前剩余 failed checks 统一做一次 all-failed rerun。

/re-run all-failed

[ShigureNyako]

最终同步一下当前 head 6d8c56681e 的 CI 状态：

• 当前 PR 已是 APPROVED，mergeStateStatus=CLEAN。
• 所有 checks 已通过：当前显示 82 个 checks 全部通过。
• 之前最后剩余的 Coverage test 也已通过：job 79601101310。
• 前面提到的 Linux-DCU / Test、Fleet Unit test single/multi、Model-Benchmark / Benchmark test、Coverage build、Build Fleet whl 也都已是 success。

本 PR 当前没有新的 NVSHMEM / CMake / FlashMask 相关失败，可以合入了。