#58 接口开发指南

MSAdapter的主要功能是提供兼容PyTorch和MindSpore的接口。在接口兼容开发过程中，大概有如下步骤： 环境准备：MindSpore2.0.0.dev20221107、PyTorch1.12 #### 1. 接口功能兼容梳理 MSAdapter的接口和PyTorch对标，从功能上映射到MindSpore对应的接口。由于两个框架的接口实现方式存在差异，所以首先需要梳理两者的差异，例如：  **需要注意的是，接口对标前请选定正确的版本：[MindSpore2.0.0官网](https://www.mindspore.cn/docs/zh-CN/master/index.html)和[PyTorch1.12官网](https://pytorch.org/docs/1.12/)** #### 2. 功能开发 根据接口分类在对应的目录下修改/新建py文件，功能开发时原则上要对标接口的所有功能，包含参数个数、功能、取值类型和范围、默认值、返回值类型和个数、精度等。开发过程中的一些规范和注意事项如下： * 接口注释的示例中用法鼓励改成如下方式，尽量只修改import，保留原有用法。 > import ms_adapter.pytorch as torch > import ms_adapter.pytorch.nn as nn > m = nn.ReLU() > input = torch.randn(2) > output = m(input) * 接口兼容对标实现时，尽量用同等级接口做映射，例如nn接口也用nn下接口映射，如果由于功能上无法对标再考虑functional类的接口组合使用。可同步需求给MS框架。 * 调用MindSpore的对外接口和方法(API)，如功能上必须使用内部方法，需经评审讨论。 * 如果接口中存在不需要兼容，或者暂时不支持的参数或属性，统一调用unsupportedattr()方法，方便后续统一整改处理。 * 功能代码里不要用assert（测试代码除外），不支持的功能需要拦截报错。 * 接口功能实现要通用：Pynative(优先)/Graph模式下功能正确；Ascend(主要)/GPU/CPU硬件平台。 * 接口功能代码中不能有依赖pytorch等其他第三方的实现。 *（持续补充）* #### 3. 新增测试用例 新增接口开发后，需要同步添加测试用例来看护已实现功能，这样可以保证其他人合入代码时不会影响自己代码功能： * 在/MSAdapter/src/branch/master/testing/ut/对应目录下增加接口的测试用例文件。 * 测试代码如果需要ms和pytorch进行结果比较，先执行pytorch代码，后执行ms代码；相反的话在GPU后端可能导致CUPTI占用问题影响性能数据正确性。 * 代码一定要自验通过，尽量以可验证的方式进行看护，不要直接print；优先以graph模式验证，如果graph模式有问题，以pynative模式验证，同时反馈graph模式问题。 * 注意：ut测试用例运行时间必须尽量短，受设备资源限制，太久的用例不适合作为门禁用例看护。 #### 4. 代码合入 合并请求创建完成后，会自动触发CI门禁检查，包含ut基本用例测试和代码规范检查，确保合入的代码不会影响主仓上面已有功能。如果门禁检查成功，可以找相关审核人员合入代码；反之，则需要修复错误，修复代码合入后重新门禁检查。 为提高代码提交的效率，建议先在本地执行门禁检查："bash run.sh". 其中，run.sh包含如下三个步骤操作： * python setup.py install ---安装 * bash ./testing/ut/runtest.sh ---运行所有UT门槛用例 * bash ./pylint_check.sh ---运行pylint代码检查 在开发过程中也可以根据需求单独执行上述任一项。