【合入来源】

关联任务issue: https://gitcode.com/Ascend/pytorch/issues/3146

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

【修改方案】

torch.distributed.checkpoint.default_planner._EmptyStateDictLoadPlanner
PyTorch 官方社区在 test/distributed/composable/test_composability/test_pp_composability.py 中有间接测试，但未针对该 API 编写直接独立测试，因此自行编写用例并提交到 test 目录。
该 API 为纯 Python 元数据操作，不涉及 NPU 适配，不需要代码修改。
新增 test/distributed/checkpoint/test_empty_state_dict_load_planner.py，验证 EmptyStateDictLoadPlanner 的加载功能及异常处理

【资料变更】

涉及。上游 PyTorch 在 test/distributed/composable/test_composability/test_pp_composability.py 中有相关测试，但仅作为 PP+DCP 集成测试的工具使用，未针对 EmptyStateDictLoadPlanner 公开 API 编写独立测试。本次提交补充了 15个测试方法，覆盖 keys 参数传参与不传参、异常场景的核心行为，测试文件位于 test/distributed/checkpoint/test_empty_state_dict_load_planner.py。

【接口变更】

不涉及

【功能介绍】

torch.distributed.checkpoint.default_planner._EmptyStateDictLoadPlanner 是 PyTorch 分布式检查点系统的内部工具类，继承自 DefaultLoadPlanner。用于从空 state_dict 加载 DCP 检查点，通过读取元数据重建 state_dict 结构，适用于未初始化模型时加载检查点的场景（如 DCP checkpoint 转 Torch save 文件）。

【功能验证】

test_empty_state_dict_load_planner.py (_EmptyStateDictLoadPlanner)

• test_init_without_keys — 不传 keys 构造 planner， keys 为 None
• test_init_with_keys — 传入 keys=["model"] ，确认被保存
• test_set_up_planner_with_non_empty_state_dict — state_dict 非空时 set_up_planner 抛 AssertionError
• test_set_up_planner_without_metadata — metadata=None 时抛 AssertionError
• test_set_up_planner_success — 空 state_dict + 合法 metadata，重建出正确 shape/dtype 的张量并保存 metadata
• test_set_up_planner_with_is_coordinator — 接受并保存 is_coordinator 标志
• test_keys_none_loads_all — keys=None 时加载 metadata 中全部 key
• test_keys_filter_loads_subset — keys={"x","z"} 只加载指定子集
• test_keys_filter_loads_nothing_when_no_match — keys 无匹配时 state_dict 保持为空
• test_keys_filter_with_planner_data — 通过 planner_data 嵌套路径（ model.layer.weight ）匹配并构建嵌套 dict
• test_create_local_plan_after_setup — setup 后 create_local_plan 返回含 TENSOR ReadItem 的 LoadPlan
• test_create_local_plan_empty_when_keys_filter_all — key 全被过滤时 local plan 为空
• test_create_global_plan — 单个 rank 时返回 1 个 LoadPlan
• test_create_global_plan_multiple_ranks — 多 rank 返回对应数量 plan
• test_finish_plan_passthrough — finish_plan 恒等返回原 plan

运行命令：
python -m pytest /workspace/user_data/pytorch-v2.7.1/test/distributed/checkpoint/test_empty_state_dict_load_planner.py -x
运行结果：

=============================================== test session starts ================================================
platform linux -- Python 3.12.13, pytest-9.1.1, pluggy-1.6.0
rootdir: /workspace/user_data/pytorch-v2.7.1
configfile: pyproject.toml
plugins: hypothesis-6.156.6
collected 15 items                                                                                                 

user_data/pytorch-v2.7.1/test/distributed/checkpoint/test_empty_state_dict_load_planner.py ...............   [100%]

================================================ 15 passed in 4.03s ================================================

【CheckList】

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

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