【合入来源】

• 需求

• 问题单

• issue/工单

• 重构优化

• 资料更新

• 关联 issue: https://gitcode.com/Ascend/pytorch/issues/2911

• 任务分类：1.3（PyTorch 官方缺少对 torch._refs._maybe_broadcast 的直接测试）

• pytorch 社区没有针对 torch._refs._maybe_broadcast 的独立测试用例，故新增该测试文件，用于验证该 API 的正确性。

【修改方案】

一、API 功能说明

torch._refs._maybe_broadcast(*args, preserve_cpu_scalar_tensors=True) 是 PyTorch 内部辅助函数，用于将一组 TensorLike / Number / None 参数广播到共同形状。它计算各 Tensor 输入的公共广播形状，对兼容形状的张量调用 .expand()，对 CPU scalar 张量根据 preserve_cpu_scalar_tensors 决定是否保留，对不兼容形状抛出 RuntimeError。该 API 为 PyTorch 私有接口。

二、测试用例完备性说明

PyTorch 官方 test/ 目录中没有直接调用 torch._refs._maybe_broadcast 的测试用例，现有测试仅通过 elementwise_meta 等内部路径间接使用，无法验证广播行为、CPU scalar 保留/展开策略及异常路径。本次新增 test/test_library_refs.py，直接验证：

• 相同形状 NPU Tensor 直接返回原张量；
• 兼容形状 NPU Tensor 广播到共同形状；
• Number 参数原样返回；
• None 参数原样返回；
• preserve_cpu_scalar_tensors=True 时 CPU scalar 张量被保留；
• preserve_cpu_scalar_tensors=False 时 CPU scalar 张量被展开；
• 0-dim scalar 张量在 preserve_cpu_scalar_tensors=False 时被广播到共同形状；
• 不兼容形状抛出 RuntimeError。

三、版本适用范围

torch._refs._maybe_broadcast 为 PyTorch 内部私有接口，在 PyTorch v2.7.1、v2.9.0、v2.10.0、v2.11.0、v2.12.0、master 各目标分支均存在且函数签名一致，因此本测试用例需提交到上述全部分支。

四、NPU 适配

测试涉及 Tensor 创建与广播，非 scalar 参与计算的 Tensor 均通过 device_type = acc.type if (acc := torch.accelerator.current_accelerator()) else "cpu" 迁移到 NPU；CPU scalar 张量仅在测试 preserve_cpu_scalar_tensors 行为时保留在 CPU，这是该参数的测试目的。

【资料变更】

不涉及

torch._refs._maybe_broadcast 为 PyTorch 私有接口，且 docs/zh/api/native_api 中无需额外刷新资料。

【接口变更】

不涉及

仅新增测试用例，未修改任何业务代码。

【功能验证】

• v2.7.1 本地 NPU 运行
  • 环境：Ubuntu 22.04 / Python 3.11.15 / PyTorch 2.7.1+cpu / Torch-NPU 2.7.1.post4 / CANN 9.0 / Ascend 910B3
  • 命令：TORCH_DEVICE_BACKEND_AUTOLOAD=0 python test/test_library_refs.py
  • 结果：Ran 8 tests in 0.771s, OK

【CheckList】

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR 标题正确使用类型标签，如：feat、fix、refactor、docs、test 等
• PR 持续集成流水线（CI）执行通过，代码检查无异常