| test(package): add testcase for PackageExporter additional APIs Co-authored-by: PAGEMRW<985608880@qq.com> # message auto-generated for no-merge-commit merge: !37841 merge test-package-exporter-additional-api-v2.9.0 into v2.9.0 test(package): add testcase for PackageExporter additional APIs Created-by: PAGEMRW Commit-by: PAGEMRW Merged-by: ascend-robot Description: # 【合入来源】 - 问题单 PyTorch 社区用例对以下 torch.package.PackageExporter API 缺少充分且直接的验证： torch.package.PackageExporter.add_dependency torch.package.PackageExporter.all_paths torch.package.PackageExporter.close torch.package.PackageExporter.dependency_graph_string torch.package.PackageExporter.get_unique_id torch.package.PackageExporter.register_intern_hook 因此新增 test_package_exporter_additional_api.py 测试文件，用于验证上述 6 个 API 的正确性，并补充异常路径验证，覆盖显式依赖添加、依赖图路径查询、依赖图字符串输出、唯一 ID 生成、intern hook 注册/移除、PackageExporter 正常关闭及重复关闭异常等场景。 # 【修改方案】 一、API 功能说明 1. torch.package.PackageExporter.add_dependency 是 PyTorch torch.package.PackageExporter 中用于手动向包导出器依赖图添加模块依赖的 API，核心功能如下： 依赖图补充能力：接收指定模块名，并根据用户预先配置的 extern、intern、mock、deny 等规则，将该模块加入 PackageExporter 的依赖分析流程。 规则驱动处理：模块最终是被打包进 archive、作为外部依赖记录、替换为 mock 模块，还是被拒绝，取决于导出器中已有的依赖匹配规则。 递归依赖分析支持：当 dependencies=True 时，会进一步分析该模块源码中的 import 依赖，并将相关依赖继续纳入处理。 手动依赖声明：适用于测试或特殊打包场景中显式补充某个模块依赖，避免完全依赖 save_module、save_pickle 等接口的自动扫描。 纯 Python 打包辅助：该 API 主要操作模块依赖关系和导出规则，不涉及张量计算，也不要求运行在 NPU/GPU 设备上。 2. torch.package.PackageExporter.all_paths 是 PyTorch PackageExporter 中用于查询两个模块之间依赖路径的调试分析 API，核心功能如下： 依赖路径追踪：接收源模块 src 和目标模块 dst，返回从 src 到 dst 的所有依赖路径。 DOT 图格式输出：返回结果为 DOT 格式字符串，可用于 Graphviz 等工具可视化依赖子图。 依赖原因定位：常用于分析某个模块为什么会被 PackageExporter 作为依赖引入，帮助定位间接 import 链路。 子图级别查看：相比完整依赖图，该 API 只关注指定源模块到目标模块之间的路径，便于缩小调试范围。 静态调试属性：该 API 只读取和展示 PackageExporter 内部依赖图信息，不会执行实际模型计算或张量运算。 3. torch.package.PackageExporter.close 是 PyTorch PackageExporter 中用于结束打包并将 package 写入目标位置的收尾 API，核心功能如下： 包写出能力：将前面通过 save_module、save_pickle、save_text、save_binary、save_source_string 等接口收集到的代码、对象和资源正式写入文件系统或二进制 IO 对象。 导出流程终止：调用 close() 后，PackageExporter 进入关闭状态，后续再调用保存、依赖添加等导出相关接口将不再合法。 上下文管理器等价：通常推荐使用 with PackageExporter(...) as exporter 的形式自动触发关闭逻辑，避免忘记手动调用 close()。 规则完整性检查：在关闭阶段会完成打包收尾检查，例如未解析依赖、非法依赖或未匹配规则可能在关闭时触发异常。 资源释放作用：用于确保底层 zip/package 归档结构被完整写入并释放相关写入资源。 4. torch.package.PackageExporter.dependency_graph_string 是 PyTorch PackageExporter 中用于输出完整包依赖图的调试 API，核心功能如下： 完整依赖图查看：返回当前 PackageExporter 已记录的 package 依赖关系图。 字符串化输出：返回值为字符串形式的依赖图表示，可直接打印到控制台或写入日志文件。 打包调试支持：用于观察哪些模块被纳入依赖图、模块之间存在怎样的依赖关系。 与局部路径分析互补：all_paths(src, dst) 适合查看两个模块之间的路径，而 dependency_graph_string() 适合查看整体依赖结构。 无副作用查询：该 API 只读取依赖图状态，不会修改打包内容，也不涉及张量或设备相关操作。 5. torch.package.PackageExporter.get_unique_id 是 PyTorch PackageExporter 中用于生成包内唯一标识符的辅助 API，核心功能如下： 唯一 ID 生成：返回一个字符串 ID，并保证该 ID 在当前 package 导出过程中只会被分配一次。 避免命名冲突：常用于生成临时模块名、资源路径或中间文件名，防止与已有模块和资源发生冲突。 自定义打包支持：在自定义 __reduce_package__ 等高级打包逻辑中，可用该 API 为动态生成的资源分配唯一名称。 包内范围唯一：其唯一性主要保证在当前 PackageExporter 管理的 package 内成立，不用于全局分布式唯一标识。 轻量级工具属性：该 API 只生成字符串标识，不涉及依赖扫描、文件写入或张量运算。 6. torch.package.PackageExporter.register_intern_hook 是 PyTorch PackageExporter 中用于注册 intern 模块匹配回调函数的 API，核心功能如下： intern 回调注册：向导出器注册一个 hook，当某个模块匹配 intern() 规则并准备被打包进 package 时，该 hook 会被触发。 自定义处理能力：hook 函数可接收 exporter 和 module_name，从而在模块被 intern 时执行额外逻辑，例如记录日志、统计模块、补充资源或检查模块名。 多 hook 顺序执行：支持注册多个 intern hook，并按照注册顺序依次调用，便于组合多个自定义处理逻辑。 可移除句柄支持：注册后会返回 RemovableHandle，后续可通过 handle.remove() 移除该 hook。 打包流程扩展点：该 API 提供对 PackageExporter 内部模块处理流程的扩展能力，适合测试 hook 调用顺序、移除机制和模块匹配行为。 二、测试文件 test_package_exporter_additional_api.py 完整验证该 API 的原因 `` 该测试用例针对 torch.package.PackageExporter.add_dependency、torch.package.PackageExporter.all_paths、torch.package.PackageExporter.dependency_graph_string、torch.package.PackageExporter.get_unique_id、torch.package.PackageExporter.register_intern_hook 和 torch.package.PackageExporter.close 六个 API，从显式依赖处理、异常依赖处理、依赖图路径查询、依赖图字符串输出、唯一标识生成、Hook 注册与移除机制、包写入闭环、重复关闭异常等维度进行直接验证，具体体现在： 1. 对 add_dependency API 的验证 显式依赖添加验证 test_add_dependency：通过创建 PackageExporter，并直接调用 add_dependency("math") 手动加入 math 模块依赖，验证 API 能够将指定模块加入 PackageExporter 的依赖分析流程。测试通过 dependency_graph.nodes 校验 math 已被加入依赖图节点，说明 add_dependency 能够正确记录显式添加的依赖。随后关闭 exporter，并使用 PackageImporter 从内存 package 中重新加载 math 模块，验证导入结果与系统原生 math 模块一致，说明显式添加的依赖不仅在导出阶段被正确记录，也能在导入阶段保持正确解析。 不存在模块异常路径验证 test_add_dependency_nonexistent_module_raises：通过 add_dependency("nonexistent_module_for_package_exporter_test") 手动添加一个不存在的模块依赖，并在 exporter.close() 阶段断言抛出 PackagingError。该测试验证 add_dependency 对非法/不可解析模块依赖的处理符合预期：依赖可以先进入导出器依赖处理流程，但最终关闭打包时会进行完整性检查并暴露打包错误，避免生成包含无效依赖的 package。 2. 对 all_paths API 的验证 依赖路径查询验证 test_all_paths：手动向 dependency_graph 中添加 a -> b、b -> c、a -> d 三条边，然后调用 all_paths("a", "c") 查询从 a 到 c 的依赖路径。测试断言结果中包含 "a" -> "b" 和 "b" -> "c"，说明 API 能够正确返回目标路径上的依赖边；同时断言结果中不包含 "a" -> "d"，说明 API 不会错误返回与目标节点 c 无关的分支路径。该测试覆盖了依赖图路径提取的正确性和无关路径过滤能力。 3. 对 dependency_graph_string API 的验证 依赖图字符串输出验证 test_dependency_graph_string：通过向 dependency_graph 中添加 a -> b 依赖边，再调用 dependency_graph_string() 获取完整依赖图字符串。测试断言结果中包含 digraph G，验证其输出符合 DOT 图格式；同时断言结果中包含 "a" -> "b"，验证依赖图中的实际边关系能够被正确序列化输出。该测试说明该 API 能够将 PackageExporter 内部依赖图转换为可读、可调试的字符串表示。 4. 对 get_unique_id API 的验证 唯一标识生成验证 test_get_unique_id：连续三次调用 get_unique_id()，并分别断言返回值为 "0"、"1"、"2"。该测试验证了 API 能够在同一个 PackageExporter 实例内生成单调递增且不重复的字符串 ID，说明其可用于包内临时资源、模块名或自定义打包逻辑中的唯一命名需求。同时，连续调用场景也验证了内部计数状态能够被正确维护。 5. 对 register_intern_hook API 的验证 Hook 注册与触发验证 test_register_intern_hook：定义 intern_hook 回调函数，并通过 register_intern_hook 注册到 PackageExporter 中。随后调用 save_source_string("foo", "VALUE = 1", dependencies=False) 保存源码模块，触发模块 intern 流程。测试最终断言 interned_modules 等于 ["foo"]，说明当模块被打包进 package 时，已注册的 intern hook 能够被正确调用，并且能够接收到正确的模块名参数。 Hook 移除机制验证 test_register_intern_hook_remove：注册 intern hook 后，立即调用返回句柄的 remove() 方法移除该 hook，再保存 foo 模块。测试断言 interned_modules 为空列表，说明被移除的 hook 不会继续触发。该测试进一步覆盖了 register_intern_hook 返回句柄的有效性，以及 hook 注册后可撤销的边界行为，避免回调残留或误触发。 6. 对 close API 的验证 包写入闭环验证 test_close：先通过 save_source_string("foo", "VALUE = 3", dependencies=False) 向 package 中写入源码模块，再调用 close() 完成导出收尾。随后重置 BytesIO 指针，并使用 PackageImporter 从内存 package 中重新导入 foo 模块，断言 foo.VALUE 等于 3。该测试验证了 close() 能够正确完成 package 的最终写入、归档结构封装和资源收尾，使导出的内容能够被后续 PackageImporter 正常加载。 重复关闭异常路径验证 test_close_twice_raises：创建 PackageExporter 后先执行一次 close() 完成关闭，再次调用 close() 时断言抛出异常。该测试验证 close() 关闭状态管理符合预期，PackageExporter 在完成导出后不会允许重复关闭或重复写入，从而避免资源状态异常、归档结构重复收尾等问题。 7. 测试完整性与隔离性保障 该测试文件使用 BytesIO 作为内存 package 载体，避免依赖外部文件系统，保证测试过程轻量、独立、可重复。每个测试用例均重新创建 PackageExporter 实例，分别构造独立的依赖图、hook 列表或 package 内容，避免不同 API 测试之间发生状态污染。部分测试使用 with PackageExporter(buffer) as exporter 的上下文管理方式，覆盖自动 close 场景；test_close 显式调用 close()，覆盖手动关闭场景；test_add_dependency_nonexistent_module_raises 和 test_close_twice_raises 分别覆盖依赖解析失败与重复关闭两个异常分支。由于这些 API 主要属于 torch.package 的 Python 层打包、依赖管理和导出流程，不涉及实际张量计算或 NPU 算子执行，因此无需额外构造 NPU 张量，也无需额外进行张量迁移适配。 三、NPU 适配 torch.package.PackageExporter.add_dependency、torch.package.PackageExporter.all_paths、torch.package.PackageExporter.close、torch.package.PackageExporter.dependency_graph_string、torch.package.PackageExporter.get_unique_id 和 torch.package.PackageExporter.register_intern_hook 均属于 torch.package 模块中的 Python 层打包、依赖管理、调试分析和 Hook 扩展类 API，不涉及张量计算、算子执行或设备调度逻辑，因此无需针对昇腾 NPU 做额外适配，具体分析如下： 1. 纯 Python 层打包流程 API，无硬件相关计算逻辑 - add_dependency API：主要用于手动向 PackageExporter 的依赖图中添加模块依赖，并根据 extern、intern、mock、deny 等规则处理模块归属，核心逻辑是 Python 模块依赖分析和打包规则匹配，不涉及 Tensor 运算或 NPU 算子调用；新增的不存在模块用例验证的是打包阶段异常检查，也不涉及设备逻辑。 - all_paths API：仅用于查询 PackageExporter 内部依赖图中两个模块之间的依赖路径，返回 DOT 格式字符串，属于依赖图调试分析能力，不涉及任何设备侧计算。 - dependency_graph_string API：用于将当前依赖图字符串化输出，便于观察模块之间的依赖关系，本质是读取并序列化 Python 层依赖图结构，与 NPU 硬件无关。 - get_unique_id API：仅用于在当前 PackageExporter 实例内生成唯一字符串 ID，属于轻量级命名辅助工具，不涉及依赖扫描、文件执行、张量创建或设备迁移。 - register_intern_hook API：用于注册模块 intern 过程中的 Python 回调函数，核心逻辑是 hook 注册、触发和移除，不依赖任何底层硬件能力。 - close API：用于完成 package 的最终写入和资源收尾，将已保存的源码、对象或资源写入目标 package 中，属于文件/字节流归档写出逻辑；新增的重复 close 用例验证的是 Python 对象关闭状态管理，也不涉及 NPU 计算图或算子执行。 2. 无底层算子 / 内核 / NPU Runtime 依赖 - 这 6 个 API 的核心功能集中在 PackageExporter 的模块依赖管理、依赖图维护、包内容写入、唯一 ID 生成以及 hook 机制上，均运行在 Python 解释器和 PyTorch 打包框架层面。 - 测试过程中使用的 BytesIO、PackageExporter、PackageImporter、dependency_graph 等对象均属于 Python 层对象或 PyTorch package 管理结构，不会调用 torch_npu 的算子、NPU kernel、NPU 内存管理接口或设备通信接口。 - 测试用例即使在 torch-npu 迁移环境下执行，也仅验证 torch.package 的打包、导入和依赖图逻辑，不触发任何 NPU 设备侧行为。 3. 核心逻辑与硬件设备解耦 - 依赖管理解耦：add_dependency、all_paths 和 dependency_graph_string 操作的是模块依赖图，依赖关系来自 Python import 规则和 PackageExporter 的打包策略，与 CPU/GPU/NPU 设备类型无关。 - 打包写入解耦：close API 负责将 package 内容写入内存 buffer 或文件系统，其正确性取决于归档结构和资源写入完整性，而不是底层计算设备。 - Hook 机制解耦：register_intern_hook 触发的是 Python 回调函数，测试关注 hook 是否被正确注册、调用和移除，不涉及任何硬件执行路径。 - 唯一标识生成解耦：get_unique_id 仅维护 PackageExporter 内部计数状态并返回字符串 ID，不包含设备判断、张量分配或算子派发逻辑。 4. 无需构造 NPU 张量的原因 - 本测试文件覆盖的 6 个 API 均不以 Tensor 作为输入，也不返回 Tensor 结果。 - 测试逻辑主要包括模块依赖声明、异常依赖关闭检查、依赖图边关系查询、字符串输出校验、hook 调用验证、package 写入与重新导入验证、重复关闭异常验证。 - 因此，按照“涉及张量的用例尽可能运行在 NPU 上”的原则，本测试文件不存在需要迁移到 NPU 的张量对象，也无需额外添加 .npu() 或 .to(device_type) 操作。 - 若强行构造 NPU 张量，反而会引入与被测 API 无关的设备依赖，降低测试的针对性和最小化原则。 综上，torch.package.PackageExporter.add_dependency、all_paths、close、dependency_graph_string、get_unique_id 和 register_intern_hook 均属于硬件无关的 Python 层 package 导出与依赖管理 API。其功能正确性主要取决于 PackageExporter 内部依赖图、打包规则、hook 机制、异常状态管理和归档写入逻辑，不依赖昇腾 NPU 的算子、内存或运行时能力。因此在 torch-npu 适配中无需修改 API 本身，也无需构造 NPU 张量，可直接复用 PyTorch 社区逻辑进行验证。 # 【资料变更】 > 不涉及 已检查文档，https://gitcode.com/Ascend/pytorch/tree/v2.7.1/docs/zh/native_apis 下面各个版本均已记录这些 API 支持情况，因此不需要提交 PR 修改资料。 # 【接口变更】 > 不涉及 # 【功能验证】 > 说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤 > 新增/变更内容是否已新增/适配 UT 测试用例看护，并补充测试自验证截图 在 2.7.1、2.9.0、2.10.0、2.11.0、2.12.0 版本上执行该用例，均通过，日志如下： ` root@c18d5a0da657:/workspace/pytorch29/test/package# python -m unittest -v test_package_exporter_additional_api test_add_dependency (test_package_exporter_additional_api.TestPackageExporterAdditionalAPI.test_add_dependency) ... ok test_add_dependency_nonexistent_module_raises (test_package_exporter_additional_api.TestPackageExporterAdditionalAPI.test_add_dependency_nonexistent_module_raises) ... ok test_all_paths (test_package_exporter_additional_api.TestPackageExporterAdditionalAPI.test_all_paths) ... ok test_close (test_package_exporter_additional_api.TestPackageExporter See merge request: Ascend/pytorch!37841 | 2 个月前 |