API说明 ======================== .. image:: https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg :target: https://atomgit.com/mindspore/docs/blob/master/docs/msadapter/docs/source_zh_cn/api.rst :alt: 查看源文件 .. toctree:: :maxdepth: 1 :hidden: note/pytorch_api_supporting_torch note/pytorch_api_supporting_torch_nn note/pytorch_api_supporting_nn_functional note/pytorch_api_supporting_tensor note/pytorch_api_supporting_optim MSAdapter是一款MindSpore生态适配工具，在不改变用户原有使用习惯下，将PyTorch/JAX等三方框架代码快速迁移到MindSpore生态上，帮助用户高效使用昇腾算力。当前MSAdapter适配PyTorch版本2.1.0。 文档中对API的支持程度分为三类，Stable、Beta、Not Support： - **Stable**：经过测试验证的API，与PyTorch原生API行为一致。 - **Beta**：核心功能已经完成，还未进行测试的API，且可能存在入参与PyTorch原生API不完全一致的情况。 - **Not Support**：当前还未实现的API。 使用限制 -------------- Out参数使用限制 ^^^^^^^^^^^^^^^^^^^^^^ 为更好地兼容PyTorch，我们的部分API设计中支持了out形式的输出参数。关于out参数的使用，有以下限制： **反向传播限制**： 在PyTorch中，指定out参数后，相关操作通常不支持反向传播（即不会自动进行梯度计算），这是由于底层实现无法追踪到out张量的梯度信息。我们的实现也遵循这一行为，即当使用out参数时，不支持自动的反向传播计算。另外，在PyTorch中同时传入out参数和requires_grad=True的张量时会报错，MSAdapter当前不报错，请注意。 **Shape 要求**： 与PyTorch能够自动调整out参数的张量shape不同，MSAdapter的out参数不支持自动resize。在使用out参数时，用户必须显式地传入与运算结果shape完全一致的张量。例如，如果函数的输出shape为 [2, 3, 4]，则传入的out张量也必须为 [2, 3, 4]，否则会报错。请务必确保所传入的out张量shape正确匹配，MSAdapter不会对传入的out参数自动调用resize。 暂不支持Complex64/Complex128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 以下展示Complex64的示例代码，Complex128数据类型的报错也类似： .. code-block:: import torch dtype = torch.complex64 size = (3, 3) tensor_ones = torch.ones(size, dtype=dtype) print("tensor_ones=", tensor_ones) 报错信息如下： .. code-block:: tensor_ones= Traceback (most recent call last): File "/path/to/your/torch/test_complex64.py", line 6, in print("tensor_ones=", tensor_ones) RuntimeError: aclnnInplaceOneGetWorkspaceSize call failed, please check! ---------------------------------------------------- - Ascend Error Message: ---------------------------------------------------- EZ1001: [PID: 1219868] 2025-05-28-10:15:15.550.981 self not implemented for DT_COMPLEX64, should be in dtype support list [DT_FLOAT,DT_FLOAT16,DT_INT8,DT_INT16,DT_INT32,DT_INT64,DT_UINT8,DT_BOOL,DT_DOUBLE,DT_BFLOAT16,].[THREAD:1220127] ---------------------------------------------------- - C++ Call Stack: (For framework developers) ---------------------------------------------------- 暂不支持动态Profiling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 示例代码： .. code-block:: import torch from torch.profiler import profile, record_function, ProfilerActivity with profile(activities=[ProfilerActivity.CPU], record_shapes=True) as prof: # 训练代码 for i in range(10): # 模拟训练步骤 pass 报错信息如下： .. code-block:: Traceback (most recent call last): File "/path/to/your/demo.py", line 102, in with profile(activities=[ProfilerActivity.CPU], record_shapes=True) as prof: File "/path/to/your/torch/profiler/profiler.py", line 54, in __init__ profiler_level = experimental_config._profiler_level, AttributeError: 'NoneType' object has no attribute '_profiler_level' Dataloader中的pin_memory参数仅支持设置为False ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 示例代码： .. code-block:: from torch.utils.data import DataLoader from torchvision import datasets from torchvision.transforms import ToTensor training_data = datasets.FashionMNIST(root="data", train=True, download=True, transform=ToTensor()) train_dataloader = DataLoader(training_data, batch_size=64, pin_memory=True) for batch, (X, y) in enumerate(train_dataloader): X, y = X.cuda(), y.cuda() 报错信息如下： .. code-block:: Traceback (most recent call last): File "/path/to/your/torch/utils/data/_utils/pin_memory.py", line 98, in pin_memory clone[i] = pin_memory(item, device) File "/path/to/your/torch/utils/data/_utils/pin_memory.py", line 64, in pin_memory return data.pin_memory(device) TypeError: pin_memory() takes 1 positional argument but 2 were given MindSpore导出的ckpt文件无法被直接加载到PyTorch模型中 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 示例代码： .. code-block:: import torch from torch import nn import mindspore as ms class NeuralNetwork(nn.Module): def __init__(self): super().__init__() self.linear = nn.Linear(28*28, 512) def forward(self, x): logits = self.linear(x) return logits class myNN(ms.nn.Cell): def __init__(self): super().__init__() self.linear = nn.Linear(28*28, 512) def construct(self, x): logits = self.linear(x) return logits model = myNN() ms.save_checkpoint(model, "./net.ckpt") model2 = NeuralNetwork() model.load_state_dict(torch.load("./net.ckpt")) 报错信息如下： .. code-block:: Traceback (most recent call last): File "/path/to/your/demo.py", line 99, in model.load_state_dict(torch.load("./mynn.ckpt")) File "/path/to/your/torch/serialization.py", line 1020, in load return _legacy_load(opened_file, pickle_module, **pickle_load_args) File "/path/to/your/torch/serialization.py", line 1118, in _legacy_load magic_number = pickle_module.load(f, **pickle_load_args) EOFError: Ran out of input 不支持MindSpore与MS-Adapter混合运行 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ import torch后，mindspore的部分行为会变更为torch的行为，从而产生不可预期的错误。 示例代码： .. code-block:: from mindspore import Tensor a = Tensor([2, 2]) print(f'before import torch: a.shape={a.shape}') import torch print(f'after import torch: a.shape={a.shape}') 执行结果如下，可以看到，import torch后，原本的mindspore.Tensor.shape行为发生了改变。 .. code-block:: before import torch: a.shape=(2,) after import torch: a.shape=torch.Size([2]) 不支持混合运行的MindSpore接口详见下表： .. list-table:: :widths: 20 80 :header-rows: 1 * - 模块 - 受影响接口 * - mindspore.Tensor/mindspore.StubTensor - is_shared, softmax, type\_, retain_grad, shape, to_dense, _base, data, numel, nelement, repeat, cuda, npu, cpu, size, dim, clone, log_softmax, narrow, view, __or__, device, __and__, __xor__, __iter__, __reduce_ex__, expand, detach, T, transpose, mean, clamp, is_cuda, is_cpu, repeat_interleave, is_sparse, requires_grad, requires_grad\_, unsqueeze, __pow__, float, backward, split, norm, record_stream, data_ptr, pin_memory, grad, __imul__, reshape, squeeze, element_size, exponential\_ 不支持非PyTorch API官方使用方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PyTorch通过pybind重载的场景下，当*号前存在key=value的默认值时，参数可以显式通过size=[1,2]的形式传参。 MSAdapter目前不支持此类传参方式，并且这类传参方式与PyTorch官方使用不符。 以torch.randint为例 .. code-block:: label = torch.randint(0, 10, size=[1, 2], dtype=torch.float) # PyTorch可运行，但是MSAdapter报错；非PyTorch官网使用方式 label = torch.randint(0, 10, [1, 2], dtype=torch.float) # PyTorch，MSAdapter均可运行；遵照PyTorch官网使用方式 用户需要按照PyTorch官方的方法使用参数，MSAdapter已和PyTorch官网的用法对齐。 PyTorch模块支持情况 ----------------------- 用户可以参考下列表格查看各模块API支持情况。 .. list-table:: PyTorch 模块支持情况 :widths: 40 30 :header-rows: 1 * - 模块名 - 支持情况 * - torch - 部分支持 * - torch.nn - 部分支持 * - torch.nn.functional - 部分支持 * - torch.Tensor - 部分支持 * - Tensor Attributes - 不支持 * - torch.amp - 不支持 * - torch.autograd - 不支持 * - torch.library - 不支持 * - torch.cpu - 不支持 * - torch.cuda - 不支持 * - torch.mps - 不支持 * - torch.backends - 不支持 * - torch.export - 不支持 * - torch.distributed - 不支持 * - torch.distributed.algorithms.join - 不支持 * - torch.distributed.elastic - 不支持 * - torch.distributed.fsdp - 不支持 * - torch.distributed.optim - 不支持 * - torch.distributed.tensor.parallel - 不支持 * - torch.distributed.checkpoint - 不支持 * - torch.distributions - 不支持 * - torch.compiler - 不支持 * - torch.fft - 不支持 * - torch.func - 不支持 * - torch.futures - 不支持 * - torch.fx - 不支持 * - torch.hub - 不支持 * - torch.jit - 不支持 * - torch.linalg - 不支持 * - torch.monitor - 不支持 * - torch.signal - 不支持 * - torch.special - 不支持 * - torch.overrides - 不支持 * - torch.package - 不支持 * - torch.profiler - 不支持 * - torch.nn.init - 不支持 * - torch.onnx - 不支持 * - torch.optim - 部分支持 * - torch.random - 不支持 * - torch.masked - 不支持 * - torch.nested - 不支持 * - torch.sparse - 不支持 * - torch.Storage - 不支持 * - torch.testing - 不支持 * - torch.utils - 不支持 * - torch.utils.benchmark - 不支持 * - torch.utils.bottleneck - 不支持 * - torch.utils.checkpoint - 不支持 * - torch.utils.cpp_extension - 不支持 * - torch.utils.data - 不支持 * - torch.utils.jit - 不支持 * - torch.utils.dlpack - 不支持 * - torch.utils.mobile_optimizer - 不支持 * - torch.utils.model_zoo - 不支持 * - torch.utils.tensorboard - 不支持 * - torch.__config__ - 不支持 * - torch._logging - 不支持