【合入来源】

如有社区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 的基础配置类。

PyTorch v2.7.1 中的构造形式为：

Backend.Options(backend, timeout=default_timeout)

其中：

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

PyTorch v2.7.1 的 Backend.Options 不包含后续版本增加的：

global_ranks_in_group
group_name

因此，本分支只针对 v2.7.1 实际存在的构造参数及属性进行验证。

2. 修改内容

新增测试类：

TestBackendOptions

共新增以下 5 个测试方法。

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_property_access_and_instance_independence

验证：

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

2.4 test_invalid_constructor_arguments

验证：

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

2.5 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 可写行为；
• 不同实例之间的状态独立性；
• 缺少参数、多余参数和非法参数类型；
• _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中体现，并简要说明修改内容。如不涉及，需填写“不涉及”

不涉及资料文件修改。

目标 API 位于：

torch._C._distributed_c10d

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

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

同时，任务资料只要求在 master 分支检查和补充；本 API 经核查无需新增
公开资料，因此：

• 不新增 Docs PR；
• 不修改 docs/zh/api/native_api；
• 不在 v2.7.1 分支增加资料文件。

【接口变更】

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

不涉及。

本 PR 仅新增：

test/distributed/test_backend_options.py

用于验证：

torch._C._distributed_c10d.Backend.Options

本 PR 未修改目标 API 的：

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

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

【功能验证】

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

1. 验证分支和提交

目标分支：

v2.7.1

测试分支：

test-backend-options-v2.7.1

测试提交：

b92962601fcd726f88bb66a2feeeb225e9fe131e

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

Local commit:
b92962601fcd726f88bb66a2feeeb225e9fe131e

Remote commit:
b92962601fcd726f88bb66a2feeeb225e9fe131e

本提交只新增：

test/distributed/test_backend_options.py

提交包含：

Signed-off-by: nannan-2026 <1794949109@qq.com>

2. 测试环境

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

Python executable:
/workspace/venvs/api3151-py271/bin/python

Python:
3.11.13

torch:
2.7.1+cpu

Expected torch:
2.7.1

Torch version match:
True

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

目标 API 不执行 Tensor 运算，也不依赖 CUDA、NPU 或其他设备算子，
因此 CPU 构建不影响该 Python 绑定配置类的行为验证。

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 探针

执行目标 API 探针，验证对象类型、默认属性、属性可写性以及
v2.7.1 版本特征。

实际结果应记录为：

version_label:
v2.7.1

python_executable:
/workspace/venvs/api3151-py271/bin/python

torch:
2.7.1+cpu

expected_torch:
2.7.1

torch_version_match:
True

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

backend:
hccl

_timeout:
0:30:00

has_global_ranks_in_group:
False

has_group_name:
False

backend_assignment:
AttributeError

updated_timeout:
0:00:07

expected_group_metadata:
False

API probe valid:
True

API probe exit code:
0

以上结果说明：

1. 目标对象类型正确；
2. 默认 backend 和 _timeout 正确；
3. backend 为只读属性；
4. _timeout 支持修改；
5. v2.7.1 不包含后续版本的分组元数据属性；
6. 目标 API 的实际接口范围与本分支测试内容一致。

5. 测试方法检查

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

test_init_with_default_and_explicit_timeout
test_init_with_boundary_values
test_property_access_and_instance_independence
test_invalid_constructor_arguments
test_invalid_timeout_assignment

检查结果：

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

6. Python 语法检查

执行命令：

PYTHONDONTWRITEBYTECODE=1 \
TORCH_DEVICE_BACKEND_AUTOLOAD=0 \
/workspace/venvs/api3151-py271/bin/python \
  -m py_compile \
  /tmp/api3207_all_versions_latest/v2_7_1/test_backend_options.py

执行结果：

py_compile exit code: 0

7. Git 差异检查

执行命令：

git diff --check \
  test-backend-options-v2.7.1^ \
  test-backend-options-v2.7.1 \
  -- 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/api3151-py271/bin/python \
  /tmp/api3207_all_versions_latest/v2_7_1/test_backend_options.py \
  -v

实际结果：

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 5 tests in 1.532 s

OK

执行结果：

unittest exit code: 0

9. pytest 验证

执行命令：

cd /tmp

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

实际结果：

.....                                                      [100%]
5 passed, 14 subtests passed in  1.3s

执行结果：

pytest exit code: 0

10. 验证结果汇总

四版本测试脚本完成后，v2.7.1 对应退出码应填写为实际输出：

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.7.1 validation PASSED

完整日志：

/workspace/api3207_all_versions_latest/v2_7_1.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）执行通过，代码检查无异常