【合入来源】

如有社区issue，请关联issue链接
请勿携带内部流程信息（需求链接、问题单、内部issue等）

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

关联社区 Issue：

https://gitcode.com/Ascend/pytorch/issues/3207

【修改方案】

请描述修改内容的具体实现，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列
如果是需求或者重构类的PR，需要补充详细设计文档（说明上下游组件关系、时序图、类图、DFX能力等内容）

本 PR 为 PyTorch 原生 API 一致性测试补齐，不涉及目标 API 功能实现修改。

目标 API：

torch._C._distributed_c10d.Backend.Options

新增测试文件：

test/distributed/test_backend_options.py

1. API 功能说明

torch._C._distributed_c10d.Backend.Options 是 PyTorch 分布式通信后端
Options 的基础配置类。

构造形式为：

Backend.Options(backend, timeout=default_timeout)

其中：

1. backend 为必选参数，表示分布式通信后端名称；
2. timeout 为可选参数，类型为 datetime.timedelta；
3. 未显式传入 timeout 时，默认值为 30 分钟；
4. backend 为只读属性；
5. _timeout 为可读写属性；
6. PyTorch v2.12.0 中还包含可读写属性
   global_ranks_in_group 和 group_name。

2. 修改内容

新增测试类：

TestBackendOptions

共新增以下 6 个测试方法：

2.1 test_init_with_default_and_explicit_timeout

验证：

• 仅传入必选参数 backend；
• 返回对象类型为 Backend.Options；
• backend 属性与传入值一致；
• 默认 _timeout 为 30 分钟；
• timeout 支持位置参数；
• timeout 支持关键字参数；
• 显式超时与构造后的 _timeout 一致。

2.2 test_init_with_boundary_values

验证：

• backend 为空字符串；
• timeout 为零；
• timeout 为负数；
• 边界值构造后的属性值与传入值一致。

2.3 test_group_metadata_properties

验证 PyTorch v2.12.0 中的分组元数据属性：

• global_ranks_in_group 默认值为空列表；
• group_name 默认值为空字符串；
• global_ranks_in_group 支持写入 rank 列表；
• group_name 支持写入分组名称；
• 写入后读取结果与设置值一致。

2.4 test_property_access_and_instance_independence

验证：

• backend 为只读属性；
• 对 backend 赋值时抛出 AttributeError；
• _timeout 为可写属性；
• 修改一个实例的 _timeout 不影响其他实例；
• 不同构造调用产生相互独立的对象。

2.5 test_invalid_constructor_arguments

验证：

• 缺少必选参数 backend；
• backend 传入 None、整数、列表或字典；
• timeout 传入 None、整数、字符串、列表或字典；
• 传入额外位置参数；
• 传入未定义关键字参数。

2.6 test_invalid_timeout_assignment

验证：

• 向 _timeout 写入 None、整数、字符串、列表或字典时抛出
  TypeError；
• 非法赋值后，原有 _timeout 值保持不变。

3. 测试实现规范

新增测试符合以下要求：

1. 使用 TestCase 和 run_tests；
2. 测试结果使用 self.assert* 系列方法验证；
3. 异常行为使用 self.assertRaises 验证；
4. 未使用 try-except 屏蔽测试失败；
5. 未添加与测试无关的输出；
6. 新增文件包含 Huawei Copyright；
7. 新增文件包含 BSD 3-Clause License；
8. 新增文件包含英文模块用途说明；
9. 本 PR 仅新增
   test/distributed/test_backend_options.py。

4. PyTorch 社区用例情况及新增必要性

已检查 PyTorch 官方社区测试代码。

官方源码和测试中存在以下间接相关内容：

• 具体分布式后端 Options 类使用或继承相关基础配置；
• 部分 DeviceMesh 测试使用 C10dBackend.Options 作为类型标注；
• 部分测试使用具体后端 Options，例如
  ProcessGroupNCCL.Options。

但是，现有社区测试未针对以下精确 API 提供直接、完整的 Python 行为
验证：

torch._C._distributed_c10d.Backend.Options

现有上游测试未充分覆盖：

• backend 必选参数；
• timeout 可选参数；
• 默认超时；
• 位置参数与关键字参数；
• 空后端名称、零超时和负超时；
• backend 只读行为；
• _timeout 可写行为；
• 不同实例之间的状态独立性；
• global_ranks_in_group 的默认值及读写行为；
• group_name 的默认值及读写行为；
• 缺少参数、多余参数和非法参数类型；
• _timeout 非法赋值后的状态保持行为。

现有继承关系、类型标注和间接使用不能替代目标 API 的直接一致性验证。

因此，有必要在 Ascend for PyTorch 的 test 目录新增独立专项测试。

5. 各版本差异说明

各分支测试范围根据对应 PyTorch 版本中
Backend.Options 的实际接口能力进行区分：

版本	测试方法数	接口差异
v2.7.1	5	包含 backend 和 _timeout
v2.11.0	6	增加 global_ranks_in_group 和 group_name
v2.12.0	6	与 v2.11.0 一致
master	6	当前 PyTorch 2.13.0 的目标属性范围与 v2.11.0、v2.12.0 一致

具体说明：

1. v2.7.1 中不存在 global_ranks_in_group 和 group_name，因此不包含
   test_group_metadata_properties；
2. v2.11.0 开始支持 global_ranks_in_group 和 group_name，因此增加
   分组元数据属性测试；
3. v2.11.0 与 v2.12.0 的目标 API 能力一致，对应测试文件内容一致；
4. 修正后的 master 测试范围也与当前 PyTorch 2.13.0 实际接口保持一致；
5. 各分支测试差异来自 PyTorch 上游接口演进，不是测试覆盖遗漏。

【资料变更】

请确认是否涉及资料变更。如涉及，需要在PR中体现，并简要说明修改内容。如不涉及，需填写“不涉及”

不涉及资料文件修改。

已检查 Ascend for PyTorch master 分支下的原生 API 资料目录：

docs/zh/api/native_api

目标 API 位于：

torch._C._distributed_c10d

其中 torch._C 和 _distributed_c10d 均属于 PyTorch 内部实现模块，
目标 API 属于 PyTorch 私有接口，不是客户可见的公开 API。

根据 Torch-NPU API 一致性任务要求，PyTorch 私有接口不需要在公开原生
API 支持清单中补充资料。

因此，本任务无需新增 Docs PR，也不修改资料目录。

【接口变更】

请确认是否涉及跨代码仓或者客户面可见的接口变更。如涉及，需要详细说明接口以及对应的变更内容，同时需要在资料中体现。如不涉及，需填写“不涉及”

不涉及。

本 PR 仅新增：

test/distributed/test_backend_options.py

用于验证：

torch._C._distributed_c10d.Backend.Options

本 PR 未修改目标 API 的：

• API 名称；
• 构造函数签名；
• 输入参数；
• 默认参数；
• 属性定义；
• 返回行为；
• 异常行为；
• Python 绑定；
• 底层 C++ 实现。

本 PR 不涉及跨代码仓修改，也不涉及客户可见接口变更。

【功能验证】

说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤
新增/变更内容是否已新增/适配UT测试用例看护，并补充测试自验证截图

1. 验证分支和提交

目标分支：

v2.12.0

测试分支：

test-backend-options-v2.12.0

测试提交：

2cfb1d2b750c980c055fe2d1632a592a42e29db0

验证前已确认本地与远端提交一致：

Local commit:
2cfb1d2b750c980c055fe2d1632a592a42e29db0

Remote commit:
2cfb1d2b750c980c055fe2d1632a592a42e29db0

本提交仅新增：

test/distributed/test_backend_options.py

2. 测试环境

本次验证使用与目标分支匹配的独立 Python 环境：

Python executable:
/workspace/venvs/api3205-v2_12_0/bin/python

Python:
3.11.13

torch:
2.12.0+cu130

Expected torch:
2.12.0

Torch version match:
True

其中：

+cu130

是当前安装的 PyTorch wheel 构建标识。

目标 API 不执行 CUDA 算子，本测试也不依赖 CUDA 设备。

3. NPU 适配说明

目标 API 是分布式后端配置对象，不接收 PyTorch Tensor，也不执行：

• NPU 算子；
• NPU Kernel；
• CUDA 算子；
• HCCL 集合通信；
• CPU/NPU 数据迁移；
• 与 dtype、shape 或 device 有关的计算。

因此，本测试不创建与目标 API 无关的 NPU Tensor，也不初始化 HCCL
进程组。

验证时设置：

TORCH_DEVICE_BACKEND_AUTOLOAD=0

用于避免在独立版本环境中自动加载与目标配置类无关的设备后端。

该设置不会跳过或替代 Backend.Options 的任何接口行为验证。

本次版本验证不依赖 torch_npu、CUDA 或 NPU 算子执行，验证对象为目标
API 的 Python 绑定及属性行为。

4. API 探针

实际环境探针结果：

version_label: v2.12.0
python: /workspace/venvs/api3205-v2_12_0/bin/python
torch: 2.12.0+cu130
expected_torch: 2.12.0
torch_version_match: True

options_type:
<class 'torch._C._distributed_c10d.Backend.Options'>

backend:
hccl

_timeout:
0:30:00

has_global_ranks_in_group:
True

has_group_name:
True

属性行为探针结果：

backend_assignment_result:
AttributeError property of 'Backend.Options' object has no setter

timeout_assignment_result:
0:00:07

timeout_changed:
True

global_ranks_in_group_default:
[]

global_ranks_in_group_updated:
[0, 2, 4]

group_name_default:
''

group_name_updated:
'api3207-test-group'

API probe exit code:
0

以上结果说明：

1. 目标对象类型正确；
2. 默认 backend 和 _timeout 正确；
3. backend 为只读属性；
4. _timeout 支持修改；
5. global_ranks_in_group 支持读写；
6. group_name 支持读写；
7. 目标 API 在 PyTorch 2.12.0 环境中真实存在并符合预期。

5. 测试方法检查

实际检测到以下 6 个测试方法：

test_init_with_default_and_explicit_timeout
test_init_with_boundary_values
test_group_metadata_properties
test_property_access_and_instance_independence
test_invalid_constructor_arguments
test_invalid_timeout_assignment

检查结果：

Expected test count: 6
Actual test count: 6
Test method inspection exit code: 0

6. Python 语法检查

执行命令：

PYTHONDONTWRITEBYTECODE=1 \
TORCH_DEVICE_BACKEND_AUTOLOAD=0 \
/workspace/venvs/api3205-v2_12_0/bin/python \
  -m py_compile \
  /tmp/api3207_all_versions_latest/v2_12_0/test_backend_options.py

执行结果：

py_compile exit code: 0

7. Git 差异检查

执行命令：

git diff --check \
  test-backend-options-v2.12.0^ \
  test-backend-options-v2.12.0 \
  -- test/distributed/test_backend_options.py

执行结果：

git diff --check exit code: 0

8. unittest 验证

执行命令：

cd /tmp

PYTHONPATH= \
TORCH_DEVICE_BACKEND_AUTOLOAD=0 \
PYTHONDONTWRITEBYTECODE=1 \
/workspace/venvs/api3205-v2_12_0/bin/python \
  /tmp/api3207_all_versions_latest/v2_12_0/test_backend_options.py \
  -v

实际结果：

test_group_metadata_properties ... ok
test_init_with_boundary_values ... ok
test_init_with_default_and_explicit_timeout ... ok
test_invalid_constructor_arguments ... ok
test_invalid_timeout_assignment ... ok
test_property_access_and_instance_independence ... ok

----------------------------------------------------------------------
Ran 6 tests in 1.2 s

OK

执行结果：

unittest exit code: 0

9. pytest 验证

执行命令：

cd /tmp

PYTHONPATH= \
TORCH_DEVICE_BACKEND_AUTOLOAD=0 \
PYTHONDONTWRITEBYTECODE=1 \
/workspace/venvs/api3205-v2_12_0/bin/python \
  -m pytest -q \
  /tmp/api3207_all_versions_latest/v2_12_0/test_backend_options.py

实际结果：

......                                                     [100%]
6 passed, 14 subtests passed in 4.345 s

执行结果：

pytest exit code: 0

10. 验证结果汇总

ENV_EXIT=0
METHOD_PARSE_EXIT=0
API_EXIT=0
COMPILE_EXIT=0
DIFF_EXIT=0
UNITTEST_EXIT=0
PYTEST_EXIT=0

最终结果：

RESULT: API #3207 v2.12.0 validation PASSED

完整日志：

/workspace/api3207_all_versions_latest/v2_12_0.log

11. 四版本验证说明

本任务分别在以下目标版本环境执行测试：

v2.7.1
v2.11.0
v2.12.0
master

每个版本均使用对应分支、对应 PyTorch 版本和独立运行日志，不使用其他
版本的运行结果代替当前分支验证结果。

四版本汇总文件：

/workspace/api3207_all_versions_latest/all_versions_summary.md

【CheckList】

PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

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