【合入来源】

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

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

【修改方案】

API 与交付结论

• API：torch.distributed.elastic.metrics.put_metric。
• 分类：1.3。PyTorch 官方没有直接验证 put_metric 处理结果的测试。
• 交付方式：扩展 torch-npu 现有 test/distributed/elastic/metrics/test_metrics_api.py。
• API 实现：不修改。
• test_upstream patch：不涉及。
• NPU 适配：不需要设备装饰器或 NPU Tensor。put_metric 是纯 Python、非计算类指标接口。
• 资料 PR：不涉及。2.7.1、2.9.0、2.10.0、2.11.0、2.12.0 条目均已存在且支持状态为“是，暂不支持 Ascend 950DT”。

分支

目标分支	Fork 源分支
v2.7.1	test-put-metric-v2.7.1
v2.11.0	test-put-metric-v2.11.0
v2.12.0	test-put-metric-v2.12.0
master	test-put-metric-master

PR 源仓库为 lgxxx/pytorch，目标仓库为 Ascend/pytorch，目标分支必须与上表一一对应。

任务书 Issue：Ascend/pytorch#3216。四个目标分支的 PR 均关联该 Issue。

官方用例调查

PyTorch 官方存在 test/distributed/elastic/metrics/api_test.py，但现有用例只覆盖 MetricHandler、MetricStream、prof 等行为，没有直接调用并验证 put_metric 的处理器结果。

另有 test/distributed/elastic/agent/server/test/api.py 通过 mock 间接验证 put_metric 被调用，但不验证其默认 metric_group、自定义 metric_group、metric_name、metric_value 或实际 MetricData。

因此需要在 torch-npu 现有 metrics 测试文件中新增直接行为用例，属于场景 1.3。

修改内容

新增 test_put_metric，覆盖：

1. 不传 metric_group 时使用默认 torchelastic 组。
2. 传入 custom_group 时使用自定义处理器。
3. 非空 metric_name 和空 metric_name。
4. 正值、0 和负值 metric_value。
5. handler 实际收到 MetricData，验证 group_name、name、value 和 timestamp。
6. 依赖现有 setUp/addCleanup 恢复全局默认 handler 和 metrics map。
7. 按新增用例规范补充 Huawei copyright，并在文件说明中列出 put_metric。

put_metric 的官方实现只将参数转交给 metric stream，不进行运行时类型校验，因此没有人为增加与官方行为不一致的类型异常断言。

修改文件：

test/distributed/elastic/metrics/test_metrics_api.py

【资料变更】

已检查 master 分支下以下资料条目：

docs/zh/api/native_api/pytorch_2-7-1/torch-distributed-elastic.md
docs/zh/api/native_api/pytorch_2-9-0/torch-distributed-elastic.md
docs/zh/api/native_api/pytorch_2-10-0/torch-distributed-elastic.md
docs/zh/api/native_api/pytorch_2-11-0/torch-distributed-elastic.md
docs/zh/api/native_api/pytorch_2-12-0/torch-distributed-elastic.md

五个版本均已有 torch.distributed.elastic.metrics.put_metric 条目，支持状态一致为“是，暂不支持 Ascend 950DT”，因此不创建资料 PR。该 API 为非计算类接口，资料中不涉及数据类型支持。

【接口变更】

不涉及。本次不修改 PyTorch API 实现、函数签名、返回类型或跨仓接口，只新增直接测试覆盖。

【功能验证】

本地验证环境

• 主机平台：Linux-5.10.0-216.0.0.115.oe2203sp4.aarch64-aarch64-with-glibc2.35
• Python：3.11.15
• CANN：9.1.0.beta1
• NPU：Ascend910_9382
• 可见设备数：1（物理 NPU 0）
• v2.7.1：torch 2.7.1+cpu，torch-npu 2.7.1.post4
• v2.11.0：torch 2.11.0+cu130，torch-npu 2.11.0rc1
• v2.12.0：torch 2.12.0+cu130，torch-npu 2.12.0.rc1
• master：测试源码来自 master，本地复用 v2.12.0 运行环境进行兼容性预验证；目标分支验证以 PR CI 结果为准。
• 设备说明：API 为纯 Python，测试不创建 Tensor，不需要强制迁移到 NPU；运行器仍在 NPU 环境中完成导入和环境探测。

执行命令

/workspace/user_data/tasks/scripts/run_api_python_version.sh 2.7.1 /workspace/user_data/tasks/sources/torch-npu-v2.7.1/test/distributed/elastic/metrics/test_metrics_api.py -v
/workspace/user_data/tasks/scripts/run_api_python_version.sh 2.11.0 /workspace/user_data/tasks/sources/torch-npu-v2.11.0/test/distributed/elastic/metrics/test_metrics_api.py -v
/workspace/user_data/tasks/scripts/run_api_python_version.sh 2.12.0 /workspace/user_data/tasks/sources/torch-npu-v2.12.0/test/distributed/elastic/metrics/test_metrics_api.py -v
/workspace/user_data/tasks/scripts/run_api_python_version.sh master /workspace/user_data/tasks/sources/torch-npu-master/test/distributed/elastic/metrics/test_metrics_api.py -v

本地验证结果

目标分支	测试结果
v2.7.1	Ran 7 tests in 0.054s，OK，退出码 0
v2.11.0	Ran 7 tests in 0.052s，OK，退出码 0
v2.12.0	Ran 7 tests in 0.086s，OK，退出码 0
master	master 测试源码在 v2.12.0 环境中兼容性预验证通过，Ran 7 tests in 0.086s，OK；目标分支 CI 通过

v2.12.0 及 master 源码兼容性预验证中有 CuTeDSL 可选依赖缺失提示；该提示与纯 Python metrics 测试无关，未影响测试结果或退出码。

【CheckList】

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

NPU 功能验证补充

以下为当前 PR head commit 对应的单卡 NPU 实测环境、命令和结果：

TASK 105 / PR #42809 / VALIDATION EVIDENCE
API=torch.distributed.elastic.metrics.put_metric
TARGET_BRANCH=v2.12.0
PLATFORM=Linux-5.10.0-216.0.0.115.oe2203sp4.aarch64-aarch64-with-glibc2.35
PYTHON=3.11.15
TORCH=2.12.0+cu130
TORCH_NPU=2.12.0.rc1
CANN=9.1.0.beta1
NPU=Ascend910_9382
VISIBLE_NPU=1 (PHYSICAL NPU 0)
COMMAND=scripts/run_api_python_version.sh 2.12.0
  sources/torch-npu-v2.12.0/test/distributed/elastic/metrics/test_metrics_api.py -v
RESULT:
  Ran 7 tests in 0.086s
  OK
  test_exit_code=0
NOTE=pure Python API; no NPU tensor required

说明：put_metric 是纯 Python、非计算类接口，测试不创建 Tensor；运行环境已完成 torch-npu 导入和 NPU 可用性探测。