# 【合入来源】 https://gitcode.com/Ascend/pytorch/issues/3216 - [ ] 需求 - [ ] 问题单 - [x] 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 环境中完成导入和环境探测。 ## 执行命令 ```bash /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】 - [x] 代码注释完备，正确记录错误日志 - [x] 代码实现进行了返回值、空指针等校验 - [x] PR 标题正确使用 `test:` 类型标签 - [x] PR 持续集成流水线（CI）执行通过，代码检查无异常 ## NPU 功能验证补充 以下为当前 PR head commit 对应的单卡 NPU 实测环境、命令和结果： ```text 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 可用性探测。