已关闭

【API一致性任务】torch.utils._foreach_utils._device_has_foreach_support NPU 测试适配方案 #4054

xin0366创建于 26 天前关闭于 7 天前

26 天前创建

torch.utils._foreach_utils._device_has_foreach_support NPU 测试适配方案

一、API 功能说明

适用版本：v2.7.1、v2.11.0、v2.12.0、master

当前状态： 有效。

可见性： 私有。该函数位于 torch.utils._foreach_utils 内部模块，没有独立文档字符串。

功能： 判断指定设备是否具备 foreach 内核支持。函数读取 device.type，当设备类型属于 foreach 支持列表并且当前不处于 TorchScript scripting 状态时返回 True；否则返回 False。foreach 支持列表包含 CUDA、XPU 和当前 PrivateUse1 后端，CPU 由该函数显式加入。

参数： device 为必填的 torch.device 对象；函数没有可选参数，也不负责把字符串、整数、列表或 None 转换为设备对象。

返回： bool，表示该设备在当前执行状态下是否支持 foreach。

设备约束： Python 定义显式涉及 CPU，并通过 foreach 内核支持设备列表处理 CUDA、XPU 和当前 PrivateUse1 后端。TorchNPU 注册的 PrivateUse1 后端可参与该判定；函数本身不创建张量或执行设备内核。

二、PyTorch 社区测试用例情况

适用版本：v2.7.1、v2.11.0、v2.12.0、master

在当前版本的 PyTorch test/ 目录中，未检索到直接调用 torch.utils._foreach_utils._device_has_foreach_support 的测试用例，但检索到 8 个通过 foreach 梯度裁剪包装函数形成的间接测试方法。

测试文件	测试方法	间接覆盖关系
`test/distributed/_composable/fsdp/test_fully_shard_clip_grad_norm_.py`	`test_clip_grad_norm_1d`、`test_clip_grad_norm_2d`	通过测试辅助方法调用 `torch.nn.utils.clip_grad_norm_`，再经 `_has_foreach_support` 或目标 API 的设备判断分支形成间接覆盖。
`test/test_nn.py`	`test_clip_grad_norm_error_if_nonfinite`、`test_clip_grad_norm_multi_device`、`test_clip_grad_value`、`test_clip_grad_norm`	通过 `clip_grad_norm_`、`clip_grad_value_`、`_get_total_norm` 和 `_clip_grads_with_norm_` 等包装函数间接进入 foreach 设备支持判断。
`test/test_torch.py`	`test_grad_scaling_clipping`、`test_grad_scaling_clipping_separate_unscale`	梯度缩放与裁剪流程调用 `torch.nn.utils.clip_grad_norm_`，间接覆盖 foreach 设备支持判断。

这些社区用例验证的是 FSDP、梯度裁剪和梯度缩放的整体功能，没有直接断言目标 API 的返回值，也没有完整覆盖 PrivateUse1/NPU、XPU、Meta、TorchScript scripting 状态、非法输入类型和参数个数边界，因此覆盖不完整。

三、API 测试用例补齐及适配方案

适配方案所属版本：v2.7.1、v2.11.0、v2.12.0、master

新增 test/test_foreach_utils.py，为私有 foreach 设备支持判定补充直接测试。

测试用例	验证场景
`test_supported_device_types`	分别传入 CPU、CUDA、XPU 和当前 PrivateUse1 后端的 `torch.device`，验证支持设备均返回 `True`。
`test_current_accelerator_and_device_index`	使用当前 accelerator 的设备类型及索引为 0 的设备，覆盖位置参数和关键字参数调用并验证返回 `True`。
`test_unsupported_device_types`	传入 Meta 和 MPS 设备，验证不在 foreach 支持集合中的设备返回 `False`。
`test_torchscript_disables_foreach_support`	模拟 TorchScript scripting 状态，验证所有原本支持的设备均返回 `False`。
`test_invalid_device_types`	传入 `None`、字符串、整数和列表，验证缺少 `device.type` 的非法输入触发 `AttributeError`。
`test_invalid_argument_count`	覆盖不传必填参数和传入多余参数的调用，验证触发 `TypeError`。

测试内容： 测试覆盖全部支持设备类别、代表性非支持设备、当前 NPU accelerator 与设备索引、TorchScript 条件分支、位置与关键字调用方式、非法输入类型以及参数个数边界。该 API 只接收 torch.device，因此测试通过当前 accelerator 获取 NPU 设备类型，不构造与接口无关的张量。

新增原因及必要性： PyTorch 社区现有 8 个用例仅通过 FSDP、clip_grad_* 和梯度缩放流程提供间接覆盖，没有直接验证该接口的返回值；PrivateUse1/NPU 路径、完整设备支持集合、TorchScript 禁用逻辑和异常输入仍缺少回归保护。新增测试用例可验证 TorchNPU 环境下接口行为与 PyTorch 实现保持一致。

四、资料变更

适用版本：v2.7.1、v2.11.0、v2.12.0

结论：不涉及。

该 API 位于以下划线命名的内部模块，属于 PyTorch 私有工具接口，不属于 TorchNPU 对外 API 资料范围；对应独立版本资料目录中也没有该接口记录，本次仅新增测试，无需补充资料。

五、接口变更

适用版本：v2.7.1、v2.11.0、v2.12.0、master

结论：不涉及。

适配内容仅新增 test/test_foreach_utils.py，未修改 API 实现、函数声明、设备注册、跨仓依赖或客户可见行为，因此不涉及接口变更。

六、功能验证

v2.7.1

执行命令：

python test_foreach_utils.py -v

结果：

test_current_accelerator_and_device_index (__main__.TestForeachUtils.test_current_accelerator_and_device_index) ... ok
test_invalid_argument_count (__main__.TestForeachUtils.test_invalid_argument_count) ... ok
test_invalid_device_types (__main__.TestForeachUtils.test_invalid_device_types) ... ok
test_supported_device_types (__main__.TestForeachUtils.test_supported_device_types) ... ok
test_torchscript_disables_foreach_support (__main__.TestForeachUtils.test_torchscript_disables_foreach_support) ... ok
test_unsupported_device_types (__main__.TestForeachUtils.test_unsupported_device_types) ... ok

----------------------------------------------------------------------
Ran 6 tests in 0.029s

OK

v2.11.0

执行命令：

python test_foreach_utils.py -v

结果：

test_current_accelerator_and_device_index (__main__.TestForeachUtils.test_current_accelerator_and_device_index) ... ok
test_invalid_argument_count (__main__.TestForeachUtils.test_invalid_argument_count) ... ok
test_invalid_device_types (__main__.TestForeachUtils.test_invalid_device_types) ... ok
test_supported_device_types (__main__.TestForeachUtils.test_supported_device_types) ... ok
test_torchscript_disables_foreach_support (__main__.TestForeachUtils.test_torchscript_disables_foreach_support) ... ok
test_unsupported_device_types (__main__.TestForeachUtils.test_unsupported_device_types) ... ok

----------------------------------------------------------------------
Ran 6 tests in 0.029s

OK

v2.12.0

执行命令：

python test_foreach_utils.py -v

结果：

W0815 13:07:18.652000 360813 <absolute-path>/cutedsl_utils.py:55] CuTeDSL operators require optional Python packages `nvidia-cutlass-dsl` and `apache-tvm-ffi`; missing optional dependency `nvidia_cutlass_dsl` (importlib.util.find_spec(nvidia_cutlass_dsl) failed)
test_current_accelerator_and_device_index (__main__.TestForeachUtils.test_current_accelerator_and_device_index) ... ok
test_invalid_argument_count (__main__.TestForeachUtils.test_invalid_argument_count) ... ok
test_invalid_device_types (__main__.TestForeachUtils.test_invalid_device_types) ... ok
test_supported_device_types (__main__.TestForeachUtils.test_supported_device_types) ... ok
test_torchscript_disables_foreach_support (__main__.TestForeachUtils.test_torchscript_disables_foreach_support) ... ok
test_unsupported_device_types (__main__.TestForeachUtils.test_unsupported_device_types) ... ok

----------------------------------------------------------------------
Ran 6 tests in 0.029s

OK

master

执行命令：

python test_foreach_utils.py -v

结果：

W0815 13:07:26.568000 360887 <absolute-path>/cutedsl_utils.py:55] CuTeDSL operators require optional Python packages `nvidia-cutlass-dsl` and `apache-tvm-ffi`; missing optional dependency `nvidia_cutlass_dsl` (importlib.util.find_spec(nvidia_cutlass_dsl) failed)
test_current_accelerator_and_device_index (__main__.TestForeachUtils.test_current_accelerator_and_device_index) ... ok
test_invalid_argument_count (__main__.TestForeachUtils.test_invalid_argument_count) ... ok
test_invalid_device_types (__main__.TestForeachUtils.test_invalid_device_types) ... ok
test_supported_device_types (__main__.TestForeachUtils.test_supported_device_types) ... ok
test_torchscript_disables_foreach_support (__main__.TestForeachUtils.test_torchscript_disables_foreach_support) ... ok
test_unsupported_device_types (__main__.TestForeachUtils.test_unsupported_device_types) ... ok

----------------------------------------------------------------------
Ran 6 tests in 0.029s

OK

X xin0366

26 天前关联了看板：FrameworkPTAdapter 版本issue看板

X xin0366

26 天前修改了issue 的描述

X xin0366

26 天前关联了pull request：test：torch.utils._foreach_utils._device_has_foreach_support is a private, hardware-dependent API. Upstream test cases do not cover some core scenarios, so new test case files need to be added.

X xin0366

xin0366

26 天前评论：

任务issue地址：https://gitcode.com/Ascend/pytorch-ecosystem/issues/136

TorchNPU-Bot成员

25 天前添加了label：bot-triaged

TorchNPU-Bot成员

25 天前评论：

检测到当前 issue 已关联 PR !44681，自动添加标签：bot-triaged

X xin0366

24 天前修改标题为 “【API一致性任务】torch.utils._foreach_utils._device_has_foreach_support NPU 测试适配方案”，原标题为“torch.utils._foreach_utils._device_has_foreach_support NPU 测试适配方案”

TorchNPU-Bot成员

24 天前添加了label：help-wantedevent: api-consistency

TorchNPU-Bot成员

24 天前评论：

检测到社区任务相关 issue，自动添加标签：event: api-consistency、help-wanted

ascend-robot成员

7 天前关闭了 issue

ascend-robot成员

7 天前添加了label：resolved