@@ -3,3 +3,3 @@
 
-MSAdapter是MindSpore适配PyTorch接口的工具,其目的是在不改变原有PyTorch用户的使用习惯情况下,使得PyTorch代码能在昇腾上获得高效性能，用户只需要将PyTorch源代码中import torch替换为import ms_adapter.pytorch即可实现模型能支持昇腾上训练。
+MSAdapter是一款针对MindSpore适配PyTorch接口的实用工具，旨在不改变原生PyTorch用户的编程使用习惯下，使得PyTorch风格代码能在昇腾硬件上获得高效性能。理想情况下，用户只需要将PyTorch源代码中`import torch`替换为`import ms_adapter.pytorch`即可实现模型在昇腾硬件上的训练。
 

@@ -11,2 +8,3 @@
+## 2.基础使用指南
 
-在昇腾平台使用MindSpore不需要将模型或者数据给到GPU，遇到torch.cuda或者to gpu、cpu的操作都可以删除。如：
+用户期望要将现有PyTroch风格利用MSAdapter移植至MindSpore时，当前通常需要以下三个步骤:

@@ -57,2 +24,3 @@
+**Step2: 替换网络训练脚本**
 
-对于简单的模型训练可以调用MindSpore的原生接口，如mindspore.Model.train或者ms.nn.WithLossCell和ms.nn.TrainOneStepCell单步训练方式。具体使用如下：
+由于框架差异导致，当前网络训练流程仍无法完全自动适配（自动适配特性开发中，敬请期待！），用户暂时需要自己根据以下用例修改对应训练脚本；

@@ -78,1 +60,4 @@
+# 反向梯度定义
+grad_fn = ms.ops.value_and_grad(forward_fn, None, optimizer.parameters, has_aux=True)
+
 # 单步训练

@@ -86,0 +75,4 @@
+        print("------>epoch:{}, loss:{:.6f}".format(i, res.asnumpy()))
+```
+
+通过以上修改您的网络就可以基于MindSpore运行了，如果想要运用分布式式训练、图模式加速、数据下沉和混合精度等更高阶的训练方式可以参考[第三章](3.高阶使用指南)；

@@ -86,0 +79,4 @@
+
+**Step3: 少量手动调整适配**
+
+理想情况下，执行上述两个步骤之后，您的脚本已经可以在昇腾等MindSpore支持的硬件平台执行了，但是由于框架架构的差异，我们识别到仍有部分接口暂时无法完全对标，针对这类接口我们正在积极优化中，您可以暂时参考[第四章]()进行规避处理（不影响网络的正常执行训练）。如果您有遇到新的问题或无法对标的内容欢迎通过[ISSUE](https://openi.pcl.ac.cn/OpenI/MSAdapter/issues) 和我们反馈交流。

@@ -86,0 +87,4 @@
+
+### 3.1 使用静态图Graph模式加速训练
+
+目前MSAdapte默认支持MindSpore的PYNATIVE模式训练，请参考[静态图](https://www.mindspore.cn/tutorials/zh-CN/r2.0.0-alpha/advanced/compute_graph.html)使用教程调用GRAPH训练模式：

@@ -86,0 +94,4 @@
+```
+
+注意，部分网络中GRAPH模式训练无法一件切换，可能需要对代码进行相应调整，当前主要体现在inplace类型操作和MindSpore原生框架用法限制，具体细节可参考MindSpore官网资料；
+

@@ -86,0 +101,4 @@
+
+### 3.3 使用分布式训练
+
+请参考[快速入门分布式并行训练](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.0.0-alpha/parallel/parallel_training_quickstart.html)使用教程选择合适的分布式训练方式。推荐使用OpenMPI训练方式，类似pytorch的分布式数据并行DistributedDataParallel（DDP）的分布式训练方式：

@@ -122,3 +168,2 @@
-## 3.性能提升方法
 
-### 3.1 使用Graph模式
+## 4.临时规避问题汇总

@@ -127,2 +171,3 @@
+### 4.1 数据处理部分
 
-### 3.3 使用分布式训练
+MSAdapter的数据处理接口除了DataLoader中pin_memory=True不生效外，均PyTorch几乎完全对齐。仅需将数据处理相关导入包修改为从ms_adapter导入,示例如下

@@ -129,0 +185,4 @@
+
+```
+
+如果遇到数据处理接口未完全适配的场景，可以暂时使用torch原生的数据处理流程，将生成的数据torch张量转为adapter支持的张量对象，请参考[convert_tensor 工具使用教程](https://openi.pcl.ac.cn/OpenI/MSAdapterModelZoo/src/branch/master/tools#user-content-convert-tensor)实现；

@@ -129,0 +210,4 @@
+        return x
+```
+
+自定义module写法和torch原生写法一致，但需要注意下述问题：

@@ -129,0 +215,4 @@
+1. 自定义module时可能出现变量名已被使用场景，如`self.phase`，需要用户自行变更变量名;
+2. 自定义反向传播函数差异，反向函数需要满足MindSpore自定义反向函数格式要求，请参考[自定义Cell反向](https://www.mindspore.cn/tutorials/zh-CN/r2.0.0-alpha/advanced/modules/layer.html#%E8%87%AA%E5%AE%9A%E4%B9%89cell%E5%8F%8D%E5%90%91)，以下是适配案例：
+
+```pytorch

@@ -129,0 +292,4 @@
+由于框架架构差异导致有些接口功能暂时无法对标，但并不影响实际功能，可以先将相关代码删除，如：
+
+1. orch.cuda模块的相关操作;
+2. 对于torch.no_grad等梯度操作;

@@ -129,0 +302,4 @@
+
+### 4.4 其他
+
+1. 网络中如果调用了mindspore原生接口，则需要调用`ms_adapter.pytorch.cast_to_adapter_tensor`接口将tensor转换为adapter tensor后方可继续调用torch接口。除网络训练部分，不推荐新手混用MSAdapter接口和MindSpore接口;

@@ -68,1 +50,4 @@
+```python
+import mindspore as ms
+net = model().to(config_args.device)
 criterion = nn.CrossEntropyLoss()

@@ -66,2 +53,3 @@
+import ms_adapter.pytorch.nn as nn
 
-model = LeNet()
+net = model().to(config_args.device)