API说明

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数据类型的报错也类似：

import torch

dtype = torch.complex64
size = (3, 3)
tensor_ones = torch.ones(size, dtype=dtype)
print("tensor_ones=", tensor_ones)

报错信息如下：

tensor_ones= Traceback (most recent call last):
File "/path/to/your/torch/test_complex64.py", line 6, in <module>
    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

示例代码：

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

报错信息如下：

Traceback (most recent call last):
    File "/path/to/your/demo.py", line 102, in <module>
        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

示例代码：

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()

报错信息如下：

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模型中

示例代码：

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"))

报错信息如下：

Traceback (most recent call last):
    File "/path/to/your/demo.py", line 99, in <module>
        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的行为，从而产生不可预期的错误。 示例代码：

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行为发生了改变。

before import torch: a.shape=(2,)
after import torch: a.shape=torch.Size([2])

不支持混合运行的MindSpore接口详见下表：

模块

受影响接口

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为例

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支持情况。

PyTorch 模块支持情况

模块名	支持情况
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	不支持