MSAdapter
简体中文
MSAdapter是一款MindSpore生态适配工具,在不改变用户原有使用习惯下,将PyTorch/JAX等三方框架代码快速迁移到MindSpore生态上,帮助用户高效使用昇腾算力。
简介
msadapter是将PyTorch训练脚本高效迁移至MindSpore框架执行的工具,其目的是在不改变原有PyTorch用户的使用习惯情况下,使得PyTorch代码能在昇腾上获得高效性能。
- PyTorch接口支持: msadapter目前支持大部分PyTorch常用接口适配。用户接口使用方式不变,基于MindSpore动态图或静态图模式下执行在昇腾算力平台上。可以在torch接口支持列表中查看接口支持情况。
版本说明
| 分支名 | 发布时间 | 配套MindSpore版本 | mindspeed | mindspeed-llm | mindspeed-mm | megatron |
|---|---|---|---|---|---|---|
| v0.5.0 | 2025-09-30 | 2.7.1 | 2.2.0_core_r0.12.1 | 2.2.0 | 2.2.0 | core_v0.12.1 |
| v0.6.0 | 2025-12-30 | 2.7.2 | 2.3.0_core_r0.12.1 | 2.3.0 | 2.3.0 | core_v0.12.1 |
| v0.7.0 | 2026-01-30 | 2.8.0 | 2.3.0_core_r0.12.1 | 2.3.0 | 2.3.0 | core_v0.12.1 |
| v0.8.0 | 2026-03-30 | 2.9.0 | 2.3.0_core_r0.12.1 | 2.3.0 | 2.3.0 | core_v0.12.1 |
- MindSpore版本推荐从MindSpore官网获取。
文档
有关安装指南、教程和API的更多详细信息,请参阅教程文档。
msadapter入门指南
安装
首先查看版本说明选择所需的msadapter和MindSpore版本。
安装MindSpore
请根据MindSpore官网安装指南进行安装。
安装msadapter
方式一:使用源码, 环境变量切换
export PYTHONPATH=${MindSpeed_Core_MS_PATH}/msadapter/:$PYTHONPATH
export PYTHONPATH=${MindSpeed_Core_MS_PATH}/msadapter/msa_thirdparty:$PYTHONPATH
方式二:安装包
步骤一:源码下载
git clone https://gitee.com/mindspore/msadapter.git
步骤二:构建
cd msadapter
bash scripts/build.sh
构建完成后,msadapter目录下会新增一个build文件夹与一个dist文件夹。
步骤三:安装
pip install ${MindSpeed_Core_MS_PATH}/msadapter/dist/*.whl
export PYTHONPATH=/*/site-packages/msa_thirdparty:$PYTHONPATH
# /*/site-packages 指python环境下的安装包路径,可以使用pip show msadapter获取。
脚本中控制是否使用msadapter的代码
msadapter.enable_torch_proxy(True)
msadapter.enable_torch_proxy(False)
使用msadapter
通过环境变量使能msadapter,脚本使用PyTorch
import torch
from torch import nn
from torch.nn import functional as F
net = nn.Linear(10, 1)
脚本使用PyTorch,最开始的位置引用msadapter
import msadapter # 改为mindspore后端执行
import torch
from torch import nn
from torch.nn import functional as F
net = nn.Linear(10, 1)
脚本直接使用msadapter
import msadapter
from msadapter import nn
from msadapter.nn import functional as F
net = nn.Linear(10, 1)
多卡场景下启动方式:
需要使用msrun启动,不支持使用torchrun启动。
- msrun和torchrun入参不同, 参数样例:
NPUS_PER_NODE=8
MASTER_ADDR=localhost
MASTER_PORT=6099
NNODES=2
NODE_RANK=0
WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))
DISTRIBUTED_ARGS="
--node_rank $NODE_RANK \
--master_addr $MASTER_ADDR \
--master_port $MASTER_PORT
--worker_num $WORLD_SIZE \
--local_worker_num $NPUS_PER_NODE \
--log_dir=msrun_log \ # 分卡日志路径存储路径
--join=True \ # True代表显示屏打日志
"
msrun $DISTRIBUTED_ARGS pretrain_gpt.py
安装好msadapter后, 你可以按照以下方式使用它:
直接import torch即可将PyTorch代码适配到msadapter,在NPU设备上运行PyTorch代码
import msadapter
import torch
from torch import nn
from torch.utils.data import DataLoader
from torchvision import datasets
from torchvision.transforms import ToTensor
# 1.Working with data
# Download training data from open datasets.
training_data = datasets.FashionMNIST(root="data", train=True, download=True, transform=ToTensor())
# Download test data from open datasets.
test_data = datasets.FashionMNIST(root="data", train=False, download=True, transform=ToTensor())
# 2.Creating Models
class NeuralNetwork(nn.Module):
def __init__(self):
super().__init__()
self.flatten = nn.Flatten()
self.linear_relu_stack = nn.Sequential(
nn.Linear(28*28, 512),
nn.ReLU(),
nn.Linear(512, 512),
nn.ReLU(),
nn.Linear(512, 10)
)
def forward(self, x):
x = self.flatten(x)
logits = self.linear_relu_stack(x)
return logits
if __name__ == '__main__':
train_dataloader = DataLoader(training_data, batch_size=64)
test_dataloader = DataLoader(test_data, batch_size=64)
# 3.create Models
model = NeuralNetwork()
classes = [
"T-shirt/top",
"Trouser",
"Pullover",
"Dress",
"Coat",
"Sandal",
"Shirt",
"Sneaker",
"Bag",
"Ankle boot",
]
# 4.Predict
model.eval()
x, y = test_data[0][0], test_data[0][1]
with torch.no_grad():
pred = model(x)
predicted, actual = classes[pred[0].argmax(0)], classes[y]
print(f'Predicted: "{predicted}", Actual: "{actual}"')
安装完msadapter后,代码执行时torch同名的导入模块会自动被转换为msadapter相应的模块(目前支持torch、torchvision、torch_npu、torchair等相关模块的自动转换),接下来执行主入口的.py文件即可。更多的使用方式可以参考使用指南
限制
目前MSAdapter的使用存在如下限制:
暂不支持Complex64/Complex128
示例代码:
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
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 | |
| expand | |
| split | |
| norm | |
| record_stream | |
| data_ptr | |
| pin_memory | |
| grad | |
| grad | |
| __imul__ | |
| reshape | |
| squeeze | |
| element_size | |
| exponential_ |
许可证
Metadata
Release files for msadapter 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| msadapter-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for msadapter-0.8.0-py3-none-any.whl |
Release files / msadapter-0.8.0-py3-none-any.whl
| Download URL | msadapter-0.8.0-py3-none-any.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
007f245fac49b753e78f48ffc884458c61e5d346c81a3161bf89901c9fd72b92
|
|
BLAKE2b-256 checksum How to use checksums |
374d40390db7a825ac046c1c4e946743dd82bcfbde383ba173337998ce991871
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Security for msadapter 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.