| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
【API】Add custom validation cases for HealthCheckServer APIs Co-authored-by: JfanLiu<1300083451@qq.com> # message auto-generated for no-merge-commit merge: !34498 merge test-healthcheck-server-api-master into master 【API】Add custom validation cases for HealthCheckServer APIs Created-by: JfanLiu Commit-by: JfanLiu Merged-by: ascend-robot Description: 环境信息 操作系统：AlmaLinux 8.10 架构：aarch64 CANN 软件版本：8.5.0 安装的软件版本：torch 2.11.0+cpu、torch-npu 2.11.0rc1 一、4 个 API 功能如下： 1. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer elastic agent 健康检查服务的接口类。构造函数接收 alive_callback、port、timeout，并将三项配置保存到实例属性 _alive_callback、_port、_timeout，供后续 health check server 实现复用。当前社区实现是 noop health check server，不创建 socket、不启动后台线程、不访问设备资源。 2. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer.start 健康检查服务启动入口。当前社区实现保持 noop 行为，只通过 health_check_server logger 输出 WARNING 日志 No health check server started。该接口用于保持 elastic agent 健康检查启动链路的统一调用形态。 3. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer.stop 健康检查服务停止入口。当前社区实现保持 noop 行为，只通过 health_check_server logger 输出 INFO 日志 Stopping noop health check server.。该接口不维护额外运行状态，也不释放外部资源。 4. torch.distributed.elastic.agent.server.health_check_server.create_healthcheck_server 模块级 factory 函数。函数接收 alive_callback、port、timeout，返回 HealthCheckServer(alive_callback, port, timeout)。该函数的核心语义是返回类型固定、三项参数原样透传、创建阶段不执行 alive_callback。 二、社区用例对这 4 个 API 的验证完整性分析 搜索了官方 test 目录，搜了 HealthCheckServer、health_check_server、create_healthcheck_server，没有搜到，说明 4 个 API 没有直接测试用例。 1. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer 官方 test 目录未发现直接构造 HealthCheckServer 并校验 _alive_callback、_port、_timeout 的用例，也未发现构造阶段不触发 callback 的断言。构造参数保存和无副作用构造语义缺少直接覆盖。 2. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer.start 官方 test 目录未发现调用 start() 并校验 logger 名称、日志级别、日志内容的用例。当前 noop start 的外部可观察行为缺少直接覆盖。 3. torch.distributed.elastic.agent.server.health_check_server.HealthCheckServer.stop 官方 test 目录未发现调用 stop() 并校验 logger 名称、日志级别、日志内容的用例，也未发现 stop() 重复调用稳定性的验证。当前 noop stop 的外部可观察行为和幂等调用语义缺少直接覆盖。 4. torch.distributed.elastic.agent.server.health_check_server.create_healthcheck_server 官方 test 目录未发现调用 create_healthcheck_server() 并校验返回类型、alive_callback/port/timeout 参数透传、创建阶段不触发 callback 的用例。factory 函数的类型约束、参数传递和无副作用创建语义缺少直接覆盖。 三、NPU 适配 3.1 API 适配 这 4 个 API 属于 torch.distributed.elastic.agent.server.health_check_server 控制面逻辑。 这些 API 不执行 Tensor 计算，不涉及 NPU kernel、算子适配、计算图构建、精度对比、CANN runtime 或 HCCL 通信。 3.2 测试用例适配 本 PR 在 torch-npu test 目录新增自定义测试文件： - test/distributed/elastic/agent/server/test_healthcheckserver_api.py 测试文件覆盖以下用例： 1. test_init：直接构造 HealthCheckServer(alive_callback, 0, 30)，校验 _alive_callback、_port、_timeout 与入参一致，并校验构造阶段没有调用 alive_callback。 2. test_create_healthcheck_server：调用 create_healthcheck_server(alive_callback, 0, 45)，校验返回对象是 HealthCheckServer，校验 alive_callback、port、timeout 原样传入实例，并校验 factory 阶段没有调用 alive_callback。 3. test_start_logs_warning：调用 start()，使用 assertLogs 捕获 torch.distributed.elastic.agent.server.health_check_server logger 的 WARNING 记录，校验只产生 1 条日志，且 message 精确等于 No health check server started。 4. test_stop_logs_info：调用 stop()，使用 assertLogs 捕获 torch.distributed.elastic.agent.server.health_check_server logger 的 INFO 记录，校验只产生 1 条日志，且 message 精确等于 Stopping noop health check server.。 5. test_start_stop_lifecycle_safe：按 start() -> stop() 顺序执行完整生命周期调用，校验 noop 实现不抛异常，覆盖常规调用链。 6. test_stop_idempotent：执行 start() 后连续调用 stop() 三次，校验重复 stop() 不抛异常，覆盖停止接口的幂等调用场景。 3.3 文档修改 本测试 PR 不修改 docs 文件。docs 支持项由独立 docs PR 补齐。 四、运行日志 python test/distributed/elastic/agent/server/test_healthcheckserver_api.py ...W0428 12:04:53.104000 12150 torch_npu_master/lib/python3.11/site-packages/torch/distributed/elastic/agent/server/health_check_server.py:48] No health check server started .W0428 12:04:53.106000 12150 torch_npu_master/lib/python3.11/site-packages/torch/distributed/elastic/agent/server/health_check_server.py:48] No health check server started .. ---------------------------------------------------------------------- Ran 6 tests in 1.351s OK See merge request: Ascend/pytorch!34498 | 4 个月前 | |
test(distributed): add testcase for torch.distributed.elastic.events.record Co-authored-by: dinglaiping<1016581171@qq.com> # message auto-generated for no-merge-commit merge: !34025 merge add-testcase-torch.distributed.elastic.events.record-master into master test(distributed): add testcase for torch.distributed.elastic.events.record and torch.distributed.elastic.events.api.EventMetadataValue Created-by: dinglaiping Commit-by: dinglaiping Merged-by: ascend-robot Description: <!-- PR描述模板更新日期：20260203 --> # 【合入来源】 - [ ] 问题单 pytorch社区用例没有验证torch.distributed.elastic.events.record和torch.distributed.elastic.events.api.EventMetadataValue，故新增该测试用例文件，用于验证这两个api的正确性。 # 【修改方案】 一、API 功能说明 1. torch.distributed.elastic.events.record 是 PyTorch 分布式弹性训练（Elastic Training）模块下的纯 Python 层事件日志记录 API，核心功能如下： 事件上报核心能力：接收 Event 类型的事件对象，将事件（包含名称、来源、时间戳、元数据等）转发到指定的日志目的地（如 null 空目的地、console 控制台等）。 灵活的日志目的地支持：支持多类日志输出目标（默认 null，即不输出；可指定 console 输出到控制台，也可扩展其他目的地）。 自动 / 自定义时间戳：事件可手动指定时间戳（毫秒级整数），若未指定则自动生成合法的非负整数时间戳。 多类型元数据兼容：支持字符串、整数、浮点数、布尔值、None、列表、嵌套字典等多种类型的元数据，无需额外序列化即可记录。 无状态并发安全：多次调用 record 不会相互干扰，底层通过 _get_or_create_logger 获取专属日志器，保证多事件记录的独立性。 2. torch.distributed.elastic.events.api.EventMetadataValue 是 PyTorch 分布式弹性训练事件模块中用于约束事件元数据值类型的类型别名，核心定义与能力如下： 类型定义：本质为 Optional[Union[str, int, float, bool]]，明确限定元数据值仅支持字符串、整数、浮点数、布尔值、None 五类基础类型。 类型校验支撑：为事件元数据的类型合法性校验提供底层定义，是 record API 兼容多类型元数据的基础。 序列化适配：该类型别名适配 JSON 序列化规则，确保合法类型的元数据可无丢失完成「序列化-反序列化」往返过程。 二、测试文件 test_events_api.py 完整验证该 API 的原因 该测试用例针对 torch.distributed.elastic.events.record 和 torch.distributed.elastic.events.api.EventMetadataValue 两个 API，从功能完整性、边界条件、底层逻辑、兼容性四个维度全覆盖验证，具体体现在： 1. 对 record API 的验证 核心功能验证 test_record_null_destination/test_record_console_destination：验证核心的「事件记录到指定目的地」能力，确认 null/console 等不同目的地均不抛出异常（API 基础可用性）。 test_record_with_timestamp：覆盖「自定义时间戳」和「自动生成时间戳」两种场景，验证时间戳的合法性（非负整数、非空、类型正确）。 test_record_with_various_metadata_types：全覆盖元数据类型（字符串/整数/浮点数/布尔值/None/列表/嵌套字典），验证 API 对多元数据类型的兼容能力。 test_record_multiple_events：验证多事件连续记录的独立性，确认事件间元数据不混淆、状态不污染。 边界条件验证 test_record_event_name_empty：验证「空事件名称」边界场景下 API 仍能正常工作，保障鲁棒性。 test_record_event_name_special_chars：覆盖含空格、特殊符号、Unicode 字符、超长字符串的事件名称，验证 API 对特殊命名的兼容。 test_record_all_event_sources：遍历 EventSource 枚举的所有值，验证 API 对所有事件来源类型的兼容。 底层逻辑验证 test_record_calls_get_or_create_logger：通过 Mock 验证 API 底层正确调用 _get_or_create_logger 获取日志器，并调用 logger.info 传入序列化后的事件，确保核心逻辑正确性。 2. 对 EventMetadataValue API 的验证 类型定义验证 test_event_metadata_value_is_defined：验证 EventMetadataValue 已正确导出且为 Union 类型，确保类型别名存在性。 test_event_metadata_value_type_structure：精准校验类型别名的构成（Optional[Union[str, int, float, bool]]），确认仅包含指定五类基础类型。 合法值兼容性验证 test_event_metadata_value_legal_primitives：覆盖正负整数、零值浮点数、显式 None 等边缘元数据值，验证所有合法类型值均可被元数据接收并正常记录。 test_event_metadata_value_none_explicit：单独验证 None 作为元数据值的合法性，排除特殊值兼容漏洞。 test_event_metadata_value_mixed_dict：验证包含所有合法类型的元数字典可正常构造并被 record API 记录。 序列化完整性验证 test_event_metadata_value_serialization_roundtrip：验证合法类型元数据经 Event.serialize() 序列化-反序列化后，类型与值均无丢失。 test_event_serialize_empty_metadata：验证空元数据字典的序列化正确性，覆盖空值边界场景。 非法值边界验证 test_event_serialize_unsupported_metadata_type：验证集合、字节、自定义对象等不支持的类型在序列化时抛出 TypeError，明确 API 错误边界。 3. 测试隔离性保障 tearDown 方法清空全局 _events_loggers 缓存、清除 get_logging_handler 缓存、停止所有 Mock，确保每个测试用例独立无干扰，避免跨用例的状态污染或 Mock 泄漏，保证对两个 API 验证结果的准确性。 综上，该文件覆盖了 record API 的「正常场景 + 边界场景 + 底层逻辑 + 隔离性」，以及 EventMetadataValue API 的「类型定义 + 合法值 + 序列化 + 非法值边界」，是对两个关联 API 功能的完整且严谨的验证。 三、NPU适配 torch.distributed.elastic.events.record 和 torch.distributed.elastic.events.api.EventMetadataValue 均具备硬件无关性、纯 Python 层实现、无底层算子依赖三大核心特征，决定了其无需针对昇腾 NPU 做修改，具体分析： 1. 纯 Python 层抽象，无硬件相关逻辑 - record API：仅负责事件的序列化和日志转发，是「事件日志记录」的纯 Python 抽象接口，不涉及任何硬件相关的计算、存储、通信逻辑（如 NPU 算子、NPU 内存管理、NPU 通信协议等）。 - EventMetadataValue API：是 Python 类型别名（基于 typing 模块的 Union/Optional），仅用于约束元数据类型，无任何硬件相关的逻辑或依赖。 2. 无底层算子 / 内核依赖 - 两个 API 内部仅调用 Python 标准库（logging 日志模块、time 时间模块、json 序列化模块、typing 类型模块）和 PyTorch 纯 Python 层的枚举/数据结构（Event/EventSource），未依赖 CUDA/NPU 等硬件相关的扩展库、内核函数或底层驱动。 - EventMetadataValue 的类型校验仅基于 Python 原生类型系统，无需调用任何硬件相关接口。 3. 核心逻辑与硬件解耦 - 日志目的地解耦：record API 的日志目的地（null/console/扩展目的地）是逻辑层面的输出目标，与硬件架构无关 —— 无论是 CPU/GPU/NPU 环境，日志的「记录 - 转发」逻辑完全一致，无需针对 NPU 调整。 - 元数据模型解耦：EventMetadataValue 定义的元数据类型是通用 Python 基础类型，无硬件绑定属性；record API 接收的 Event 对象（名称、来源、时间戳、元数据）是通用数据结构，不包含任何硬件相关字段，昇腾 NPU 环境下可直接复用。 - 序列化逻辑解耦：元数据的序列化/反序列化基于 JSON 标准，与硬件无关，NPU 环境下序列化规则无需调整；非法类型的异常抛出逻辑（TypeError）是纯 Python 层判断，与硬件架构无关联。 简言之，record 和 EventMetadataValue 均是「硬件无关的纯 Python 层抽象」，核心逻辑不耦合任何特定硬件（包括 GPU/NPU/CPU），因此适配昇腾 NPU 时无需修改两个 API 本身，可直接复用。 # 【资料变更】 > 不涉及 # 【接口变更】 > 不涉及 # 【功能验证】 > 说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤\ > 新增/变更内容是否已新增/适配UT测试用例看护，并补充测试自验证截图 在2.7.1 2.8.0 2.9.0 2.10.0 2.11.0版本上执行该用例，均通过，日志如下： root@hostname-fqv42:/home# python /root/torchnpuapi/test_events_api.py ..........{"name": "test_event_console", "source": "AGENT", "timestamp": 0, "metadata": {"stage": "init"}} ....... ---------------------------------------------------------------------- Ran 17 tests in 0.046s OK root@hostname-fqv42:/home# # 【CheckList】 > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] - [x] 代码注释完备，正确记录错误日志 - [x] 代码实现进行了返回值、空指针等校验 - [x] PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等 - [x] PR持续集成流水线（CI）执行通过，代码检查无异常 See merge request: Ascend/pytorch!34025 | 4 个月前 | |
test(distributed):add test for torch.distributed.elastic.metrics.api.ConsoleMetricHandler, torch.distributed.elastic.metrics.api.NullMetricHandler and torch.distributed.elastic.metrics.configure Co-authored-by: m0_73361278<1241425935@qq.com> # message auto-generated for no-merge-commit merge: !34701 merge test-metrics-api into master test(distributed):add test for torch.distributed.elastic.metrics.api.ConsoleMetricHandler, torch.distributed.elastic.metrics.api.NullMetricHandler and torch.distributed.elastic.metrics.configure Created-by: m0_73361278 Commit-by: m0_73361278 Merged-by: ascend-robot Description: <!-- PR描述模板更新日期：20260203 --> # 【合入来源】 > <font color="red">**如有社区issue，请关联issue链接**</font>\ > <font color="red">**请勿携带内部流程信息（需求链接、问题单、内部issue等）**</font> - [ ] 需求 - [ ] 问题单 - [ ] issue/工单 - [ ] 重构优化 - [ ] 资料更新 pytorch 社区用例没有验证 torch.distributed.elastic.metrics.api.ConsoleMetricHandler、torch.distributed.elastic.metrics.api.NullMetricHandler 和 torch.distributed.elastic.metrics.configure，故新增该测试用例文件，用于验证这三个 API 的正确性。 # 【修改方案】 一、API 功能说明 <span style="color:#000000;">1. torch.distributed.elastic.metrics.api.ConsoleMetricHandler</span> 是 PyTorch 分布式弹性训练 metrics 模块下的指标输出处理器，核心功能如下： 控制台输出能力：通过 emit(metric_data) 接收 MetricData 指标对象，并将指标内容输出到控制台。 指标字段承载能力：可处理包含 timestamp、group_name、name、value 等字段的 MetricData 对象。 Handler 基类兼容：ConsoleMetricHandler 是 MetricHandler 类型实例，可作为 metrics 模块统一的指标处理器使用。 与 configure 联动：配置为默认 handler 或指定 group handler 后，可通过 metrics_api.getStream(...).add_value(...) 触发指标输出。 2.torch.distributed.elastic.metrics.api.NullMetricHandler 是 PyTorch 分布式弹性训练 metrics 模块下的空指标处理器，核心功能如下： 空处理能力：通过 emit(metric_data) 接收 MetricData 指标对象，但不产生控制台输出。 无副作用返回：调用 emit 后返回 None，不会打印内容。 Handler 基类兼容：NullMetricHandler 是 MetricHandler 类型实例，可作为 metrics 模块统一的指标处理器使用。 与 configure 联动：配置为默认 handler 或指定 group handler 后，可屏蔽对应指标流的输出。 3.torch.distributed.elastic.metrics.configure 是 PyTorch 分布式弹性训练 metrics 模块下的指标处理器配置 API，核心功能如下： 默认 handler 配置：调用 configure(handler) 时，可配置全局默认 metrics handler。 group 级 handler 配置：调用 configure(handler, group="xxx") 时，可为指定 group 单独配置 metrics handler。 指标流分发能力：通过 metrics_api.getStream(group_name).add_value(metric_name, value) 上报指标时，会按照 group 配置选择对应 handler。 默认与 group 配置隔离：指定 group 的 handler 只影响对应 group，不影响其他 group 使用默认 handler。 二、测试文件 test_metrics_api.py 完整验证该 API 的原因 该测试用例针对 ConsoleMetricHandler、NullMetricHandler 和 configure 三个 API 进行验证，覆盖 handler 基础行为、默认配置、group 级配置和测试隔离性。 对 ConsoleMetricHandler 的验证 test_console_metric_handler_emit：验证 ConsoleMetricHandler.emit 能正常接收 MetricData，返回值为 None，并通过 print 输出包含 timestamp/value、group name 和 metric name 的指标信息；同时验证 ConsoleMetricHandler 是 MetricHandler 的实例。 对 NullMetricHandler 的验证 test_null_metric_handler_emit：验证 NullMetricHandler.emit 能正常接收 MetricData，返回值为 None，且不会触发任何控制台输出；同时验证 NullMetricHandler 是 MetricHandler 的实例。 对 configure 默认 handler 配置的验证 test_configure_default_console_metric_handler：验证通过 configure(handler) 将默认 handler 配置为 ConsoleMetricHandler 后，调用 metrics_api.getStream(...).add_value(...) 能正常触发控制台输出。 test_configure_default_null_metric_handler：验证通过 configure(handler) 将默认 handler 配置为 NullMetricHandler 后，调用 metrics_api.getStream(...).add_value(...) 不会产生控制台输出，且返回值为 None。 对 configure group 级 handler 配置的验证 test_configure_group_specific_console_metric_handler：验证为指定 group 配置 ConsoleMetricHandler 后，仅该 group 的指标会上报到控制台，默认 group 仍使用默认 handler，二者互不干扰。 test_configure_group_specific_null_metric_handler：验证为指定 group 配置 NullMetricHandler 后，仅该 group 的指标不会输出，其他 group 仍可使用默认 ConsoleMetricHandler 正常输出。 测试隔离性保障 setUp 和 _restore_metrics_state：在每个测试前保存原始 _default_metrics_handler 和 _metrics_map，测试结束后恢复全局 metrics 状态，避免不同测试用例之间的 handler 配置互相污染。 综上，该文件覆盖了 ConsoleMetricHandler 的控制台输出行为、NullMetricHandler 的空处理行为、configure 的默认 handler 配置能力、group 级 handler 配置能力，以及测试间全局状态隔离能力，是对这三个 metrics API 的基础功能验证。 三、NPU适配 torch.distributed.elastic.metrics.api.ConsoleMetricHandler、torch.distributed.elastic.metrics.api.NullMetricHandler 和 torch.distributed.elastic.metrics.configure 均具备硬件无关性、纯 Python 层实现、无底层算子依赖三大核心特征，决定了其无需针对昇腾 NPU 做修改 # 【资料变更】 不涉及 # 【接口变更】 不涉及 # 【功能验证】 在2.7.1 2.8.0 2.9.0 2.10.0 2.11.0版本上执行该用例，均通过，日志如下（以2.11.0为例）： [root@82bc9d38ec90 workspace]# python /workspace/2.11.0/pytorch/test/distributed/elastic/metrics/test_metrics_api.py ...... Ran 6 tests in 0.037s OK # 【CheckList】 > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] - [ ] 代码注释完备，正确记录错误日志 - [ ] 代码实现进行了返回值、空指针等校验 - [ ] PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等 - [ ] PR持续集成流水线（CI）执行通过，代码检查无异常 See merge request: Ascend/pytorch!34701 | 4 个月前 |