From fb23f2fcaafedd54dbe7d6f627d4e9b245a4de66 Mon Sep 17 00:00:00 2001 From: zhengwei Date: Sun, 3 Aug 2025 20:56:37 +0800 Subject: [PATCH 1/2] update mint description --- docs/mindspore/source_zh_cn/features/mint.md | 163 +++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 docs/mindspore/source_zh_cn/features/mint.md diff --git a/docs/mindspore/source_zh_cn/features/mint.md b/docs/mindspore/source_zh_cn/features/mint.md new file mode 100644 index 0000000000..4cf6f9f62b --- /dev/null +++ b/docs/mindspore/source_zh_cn/features/mint.md @@ -0,0 +1,163 @@ +# what is mint? + +[![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/features/mint.md) + +## 介绍 +随着CANN推出aclnn类算子，mindspore存量的ops nn等API要进行适配优化，为了不影响原有API的行为同时保证兼容性，我们为此创建一个新的API目录来做这件事，新目录的名字mint的想法来自于linux is not unix。在mindspore.mint下，提供张量创建、计算、神经网络、通信等常用pytorch-like API。本文主要介绍mint类API支持范围和入参区别等。 + +- [张量创建](###张量创建) +- [随机采样](###随机采样) +- [数学计算](###数学计算) +- [神经网络](###神经网络) +- [通信类](###通信类) + +### 张量创建 + +以empty这个API看下主要差异点 + +| torch.empty | mindspore.mint.empty | 说明 | +|:---: | :---: | :---:| +| `*size` (int...) | `*size` (int...) | 必选 | +| `dtype` | `dtype` | 可选 | +| `device` | `device` | 可选 | +| `layout` | 无 | 可选 | +`requires_grad` | 无 | 可选 | +| `pin_memory` | 无 | 可选 | +|`memory_format` | 无 | 可选 | +| `out` | 无 | 可选 | + +#### 当前不支持的参数说明 +- `layout`: 创建torch tensor时，一般默认layout是stride，即dense tensor。mindspore创建tensor时，默认是dense tensor，与torch 无差异。开发者无需设置。 +- `memory_format`: tensor的内存排布，默认都是NCHW格式。torch 提供channel_last格式即NHWC，在一些场景中，这样会有性能提升，但是泛化性和兼容性需要开发者实际测试和验证。 +- `requires_grad`: 由于框架自动微分求导机制不同，mindspore没有在tensor的属性设置此参数。但是在parameter类是提供了此参数。 +- `pin_memory`: 返回的tensor被分配到pinned memory，差异来自与GPU和NPU设备内存的优化和管理机制不同。 NPU的内存优化和管理是由框架完成，GPU设备提供的是显示管理，即开发者进行操作。 +- `out`: 指定输出张量，用于原地操作和内存优化。当提供 `out` 参数时，操作结果会直接写入到指定的张量中，而不是创建新的张量。当前不支持 + +**代码示例**： +```diff +- import torch ++ import mindspore + +- x = torch.empty(2, 3, dtype=torch.float32) ++ x = mindspore.mint.empty(2, 3, dtype=mindspore.float32) +``` + +总结：tensor相关可选参数涉及框架实现机制不同，我们也会根据开发者反馈不断完善，如tensor storage能力已规划。 + +### 随机采样: random sampling +以bernoulli举例 + +| torch.bernoulli | mindspore.mint.bernoulli | 说明 | +|:---: | :---: | :---:| +| `input` (Tensor...) | `input` (Tensor...) | 必选 | +| `generator` | `generator`| 可选 | +| `out` | 无 | 可选 | + +out参数差异参考张量创建 + +**代码示例**： +```diff +- import torch ++ import mindspore.mint + +- a = torch.ones(3, 3) ++ a = mindspore.mint.ones(3, 3) + +- torch.bernoulli(a) ++ mindspore.mint.bernoulli(a) +``` + +### 数学计算 +基础计算类当前均已支持，以mul举例 +| torch.mul | mindspore.mint.mul | 说明 | +|:---: | :---: | :---:| +| `*size` (Tensor...) | `*size` (Tensor...) | 必选 | +| `other` | `other`| 可选 | +| `out` | 无 | 可选 | + +计算类ops当前不支持的参数与tensor creation是类似的，这与tensor实现机制相关。例如out + +**代码示例**： +```diff +- import torch ++ import mindspore.mint + +- a = torch.randn(3) ++ a = mindspore.mint.randn(3) + +- torch.mul(a,50) ++ mindspore.mint.mul(a,50) +``` + +### neural netowrk + +常用nn类，例如conv2d，参数均一致。 + +| torch.conv2d | mindspore.mint.conv2d | 说明 | +|:---: | :---: | :---:| +| `in_channels` (int) | `in_channels` (int) | 必选 | +| `out_channels`(int) | `out_channels`(int) | 必选 | +| `kernel_size` (int or tuple) | `kernel_size` (int or tuple) | 必选 | +| `stride` (int or tuple) | `stride` (int or tuple) | 可选 | +| `padding`(int,tuple or str) | `padding`(int,tuple or str) | 可选 | +| `padding_mode` (str) | `padding_mode` (str) | 可选 | +| `dilation`(int or tuple) | `dilation`(int or tuple) | 可选 | +| `groups` (int) | `groups` (int) | 可选 | +| `bias`(bool) | `bias`(bool) | 可选 | + + +**代码示例**： +```diff +- import torch ++ import mindspore + +in_channels = 16 +out_channels = 33 +kernel_size = (3, 5) +stride = (2, 1) +padding = (4, 2) +dilation = (3, 1) + +- input = torch.rand(20,16,50,100) ++ input = mindspore.mint.rand(20,16,50,100) + +- model = torch.conv2d(16,33,(3,5),stride=(2, 1), padding=(4, 2), dilation=(3, 1)) ++ model = mindspore.mint.conv2d(16,33,(3,5),stride=(2, 1), padding=(4, 2), dilation=(3, 1)) + +output = model(input) +``` +包含inplace参数的，当前未全部支持，例如 + +| API | Args | +| :--- | :--- | +| torch.nn.functional_dropout2d | input, p=0.5, training=True, inplace=False | +| mindspore.mint.nn.functional_dropout2d | input, p=0.5, training=True + +#### torch废弃的参数，不支持，例如 + +| torch.nn.MSELoss | 是否废弃 | mindspore.nn.MSELoss | 说明 | +|:---: | :--- | :---: | :---:| +| `size_average` | yes | N.A | 不支持 | +| `reduce` | yes | N.A | 不支持 | +| `reduction` | no | `reduction` | 支持 | + +### 通信类：distribute + +常用all_gather/all_reduce/all_to_all等均已支持，参数也保持一致，例如 + +| torch.distributed.all_gather | mindspore.mint.distributed.all_gather | 说明 | +|:---: | :---: | :---:| +| `tensor_list` (list[Tensor]) | `tensor_list` (list(Tensor)) | 必选 | +| `tensor`(Tensor) | `tensor`(Tensor) | 可选 | +| `group`(ProcessGroup) | `group` (ProcessGroup) | 可选 | +| `async_op` (bool) | `async_op` (bool) | 可选 | + + +| torch.distributed.all_reduce | mindspore.mint.distributed.all_reduce | 说明 | +|:---: | :---: | :---:| +| `tensor` (Tensor) | `Tensor` (Tensor) | 必选 | +| `op` | `op` | 可选 | +| `group`(ProcessGroup) | `group` (ProcessGroup) | 可选 | +| `async_op` (bool) | `async_op` (bool) | 可选 | + +更多API对比情况请查阅[mint_api_mapping](https://www.mindspore.cn/docs/zh-CN/master/features/note/api_mapping/mint_api.html) -- Gitee From 0a6e0dbdb034c1b78da0d35176ba5c9b8a6885a7 Mon Sep 17 00:00:00 2001 From: zhengwei Date: Mon, 4 Aug 2025 19:03:21 +0800 Subject: [PATCH 2/2] modify typo --- docs/mindspore/source_zh_cn/features/mint.md | 35 ++++++++++---------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/mindspore/source_zh_cn/features/mint.md b/docs/mindspore/source_zh_cn/features/mint.md index 4cf6f9f62b..8a953252dd 100644 --- a/docs/mindspore/source_zh_cn/features/mint.md +++ b/docs/mindspore/source_zh_cn/features/mint.md @@ -3,13 +3,8 @@ [![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source.svg)](https://gitee.com/mindspore/docs/blob/master/docs/mindspore/source_zh_cn/features/mint.md) ## 介绍 -随着CANN推出aclnn类算子，mindspore存量的ops nn等API要进行适配优化，为了不影响原有API的行为同时保证兼容性，我们为此创建一个新的API目录来做这件事，新目录的名字mint的想法来自于linux is not unix。在mindspore.mint下，提供张量创建、计算、神经网络、通信等常用pytorch-like API。本文主要介绍mint类API支持范围和入参区别等。 -- [张量创建](###张量创建) -- [随机采样](###随机采样) -- [数学计算](###数学计算) -- [神经网络](###神经网络) -- [通信类](###通信类) +随着cann推出aclnn类算子，mindspore存量的ops nn等API要进行适配优化，为了不影响原有API的行为同时保证兼容性，我们为此创建一个新的API目录来做这件事，新目录的名字mint的想法来自于linux is not unix。在mindspore.mint下，提供张量创建、计算、神经网络、通信等常用pytorch-like API。本文主要介绍mint类API支持范围和入参区别等。 ### 张量创建 @@ -27,13 +22,15 @@ | `out` | 无 | 可选 | #### 当前不支持的参数说明 + - `layout`: 创建torch tensor时，一般默认layout是stride，即dense tensor。mindspore创建tensor时，默认是dense tensor，与torch 无差异。开发者无需设置。 -- `memory_format`: tensor的内存排布，默认都是NCHW格式。torch 提供channel_last格式即NHWC，在一些场景中，这样会有性能提升，但是泛化性和兼容性需要开发者实际测试和验证。 -- `requires_grad`: 由于框架自动微分求导机制不同，mindspore没有在tensor的属性设置此参数。但是在parameter类是提供了此参数。 -- `pin_memory`: 返回的tensor被分配到pinned memory，差异来自与GPU和NPU设备内存的优化和管理机制不同。 NPU的内存优化和管理是由框架完成，GPU设备提供的是显示管理，即开发者进行操作。 -- `out`: 指定输出张量，用于原地操作和内存优化。当提供 `out` 参数时，操作结果会直接写入到指定的张量中，而不是创建新的张量。当前不支持 +- `memory_format`: tensor的内存排布，默认都是NCHW格式。torch 提供channel_last格式即NHWC，在一些场景中，这样会有性能提升，但是泛化性和兼容性需要开发者实际测试和验证。使用mindspore开发，可不设置此参数。 +- `requires_grad`: 由于框架自动微分求导机制不同，mindspore在tensor的属性中没有设置此参数。对于是否需要计算梯度，常用的parameter类提供了此参数。如果无需计算梯度，可参考[mindspore.ops.stop_gradient](https://www.mindspore.cn/docs/zh-CN/master/api_python/ops/mindspore.ops.stop_gradient.html) +- `pin_memory`: 返回的tensor被分配到pinned memory，我们已经规划支持此功能。计划在2.7.1版本推出。 +- `out`: 指定输出张量，用于原地操作和内存优化。当提供 `out` 参数时，操作结果会直接写入到指定的张量中，而不是创建新的张量。当前未规划支持此参数。 + +**代码示例**: -**代码示例**： ```diff - import torch + import mindspore @@ -55,7 +52,7 @@ out参数差异参考张量创建 -**代码示例**： +**代码示例**: ```diff - import torch + import mindspore.mint @@ -68,6 +65,7 @@ out参数差异参考张量创建 ``` ### 数学计算 + 基础计算类当前均已支持，以mul举例 | torch.mul | mindspore.mint.mul | 说明 | |:---: | :---: | :---:| @@ -77,7 +75,8 @@ out参数差异参考张量创建 计算类ops当前不支持的参数与tensor creation是类似的，这与tensor实现机制相关。例如out -**代码示例**： +**代码示例**: + ```diff - import torch + import mindspore.mint @@ -89,7 +88,7 @@ out参数差异参考张量创建 + mindspore.mint.mul(a,50) ``` -### neural netowrk +### 神经网络 常用nn类，例如conv2d，参数均一致。 @@ -106,7 +105,8 @@ out参数差异参考张量创建 | `bias`(bool) | `bias`(bool) | 可选 | -**代码示例**： +**代码示例**: + ```diff - import torch + import mindspore @@ -126,6 +126,7 @@ dilation = (3, 1) output = model(input) ``` + 包含inplace参数的，当前未全部支持，例如 | API | Args | @@ -141,7 +142,7 @@ output = model(input) | `reduce` | yes | N.A | 不支持 | | `reduction` | no | `reduction` | 支持 | -### 通信类：distribute +### 通信类 常用all_gather/all_reduce/all_to_all等均已支持，参数也保持一致，例如 @@ -160,4 +161,4 @@ output = model(input) | `group`(ProcessGroup) | `group` (ProcessGroup) | 可选 | | `async_op` (bool) | `async_op` (bool) | 可选 | -更多API对比情况请查阅[mint_api_mapping](https://www.mindspore.cn/docs/zh-CN/master/features/note/api_mapping/mint_api.html) +更多API对比情况请查阅[mint_api_mapping](https://www.mindspore.cn/docs/zh-CN/master/features/note/api_mapping/mint_api.html) \ No newline at end of file -- Gitee