Junming Cao | MindSpore源码阅读系列(一)：本地编译API文档并导入Dash

前言

我前几天报名参加了第四届中国软件开源创新大赛的代码评注组。代码评注组的比赛形式是让参赛者阅读指定开源软件的源码，并根据自己的理解撰写技术博客。大赛提供了三种可选择阅读的开源软件：MindSpore、OpenGauss、OpenHarmony。OpenGauss和OpenHarmony就是大名鼎鼎的高斯数据库和鸿蒙操作系统，而MindSpore当然也不同凡响，是华为于2020年推出的面向全场景的最佳昇(sheng)腾匹配的AI框架。我最近在做深度学习性能缺陷的研究，对各种深度学习系统的实现比较感兴趣，所以选择进行MindSpore的源码阅读与评注。

MindSpore让我感兴趣的点

我希望有一些比较具体的目标，这样更有针对性。粗略浏览了一下官网的文档介绍，我发现了如下让我感兴趣的点：

MindSpore是华为AI全栈的重要组件，它号称是最佳昇腾匹配的AI框架。那它底层针对异构计算架构(CANN)、昇腾处理器具体做了哪些定制优化？
MindSpore主打全场景，而且还有MindRE(全场景运行时)，支持端、边、云不同场景下的灵活部署。这种灵活性是如何实现的？计算资源受限的情况下，对模型的裁剪、压缩等技术相比于Tensorflow有何优劣？
MindSpore的自动微分不同于基于静态图和动态图的转换，而是基于源码的转换。一方面它可以像动态图一样轻松构建与调试模型，一方面可以对神经网络进行静态编译与优化。它具体是如何实现的？相比于Tensorflow 2.0的默认Eager执行，Pytorch最近推出的torchscript，它在易用性、执行效率方面有何区别？
MindSpore有一个独立的MindArmour库，它参考最新的深度学习安全与软工研究，为模型提供各种安全防护能力。我对其中的NAD算法，fuzz testing尤其感兴趣。
MindSpore提供了详细的调试网络的文档。其中Dump功能可以在Graph模式下调试，同时可以使用Callback自定义调试信息，能否利用这些功能静态或动态分析计算图，从而自动检测与修复缺陷？
华为AI全栈中还包括全流程开发IDE MindStudio，它提供了一些AI应用开发特定的补全与分析功能。我对它提供的调优分析功能很感兴趣。在检测MindSpore或Tensorflow应用的性能问题时，它相比于Tensorflow profiler，效果如何？除了单纯的profiling找bottleneck外，它实现了哪些智能分析技术，可以自动定位到性能缺陷的roor cause？

在后续的阅读学习过程中，我将尝试找出这些问题的答案并进行分享。开始阅读源码之前，我还要进行一些准备工作，首先是将文档进行本地编译。

为什么要本地编译API文档

相比于在线查询，将文档离线编译有如下两点好处：

方便离线查看。当API文档需要科学上网访问，或网络环境不好时，离线查看能省却很多麻烦。
可以导入API文档管理工具。强烈建议不太了解API文档管理工具的同学了解一下，绝对是解放记忆负担，提高生产力的神器。Mac平台的Dash是让我离不开Mac的重要原因之一，如果有同学知道Windows、Linux平台类似的API文档管理工具，欢迎分享。

Dash使用简介：

下载安装后打开设置，搜索需要安装的API库，并点击下载。Dash支持数十种编程语言的标准库文档，与数百个常见第三方库文档。其中Main Docsets是官方提供的，User Contributed则有一些用户自定义，然后提供给社区的。

在搜索框里搜索模块名/类名/方法名/字段名，可以提前选中某个库，也可以针对所有库搜索。

点击指定的搜索结果，会跳到对应的API页面。API页面都是经过Dash索引过的，一般会在左侧生成方便的目录。

常见的深度学习库，如Tensorflow、Pytorch、Keras、MXNET等都在Dash中有用户贡献的现成文档可以下载使用，但是MindSpore却没有。因此想要在Dash中搜索MindSpore文档，就必须对MindSpore文档进行本地编译为sphinx格式后，使用doc2dash导入。下面将依次介绍本地编译MindSpore Python API文档和将文档导入Dash的步骤。

MindSpore文档本地编译

安装MindSpore

由于MindSpore Docs的编译依赖于MindSpore，MindSporeHub，MindArmour，MindSporeServing，因此要先安装这些库。这里介绍最常用的GPU版本MindSpore的安装，需要注意GPU版本的MindSpore目前只支持Ubuntu系统。因为GPU版本安装起来比较麻烦，因此直接安装Docker镜像。

Docker使用GPU，需要首先安装nvidia-container-toolkit:

# Acquire version of operating system version
DISTRIBUTION=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$DISTRIBUTION/nvidia-docker.list | tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit nvidia-docker2
sudo systemctl restart docker

编辑文件daemon.json配置容器运行时，让Docker可以使用nvidia-container-runtime:

vim /etc/docker/daemon.json
#添加如下字段：
{
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

重启Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

拉取MindSpore的docker image，然后run:

docker pull swr.cn-south-1.myhuaweicloud.com/mindspore/mindspore-gpu:1.2.0
docker run -it -v /dev/shm:/dev/shm --runtime=nvidia --privileged=true swr.cn-south-1.myhuaweicloud.com/mindspore/mindspore-gpu:1.2.0 /bin/bash/

进入docker中，安装MindSporeHub，MindArmour，和MindSporeServing：

wget https://ms-release.obs.cn-north-4.myhuaweicloud.com/1.2.0/Hub/any/mindspore_hub-1.2.0-py3-none-any.whl
wget https://ms-release.obs.cn-north-4.myhuaweicloud.com/1.2.0/Serving/ubuntu_x86/mindspore_serving-1.2.0-cp37-cp37m-linux_x86_64.whl
pip install mindspore_hub-1.2.0-py3-none-any.whl
pip install https://ms-release.obs.cn-north-4.myhuaweicloud.com/1.2.0/MindArmour/x86_64/mindarmour-1.2.0-cp37-cp37m-linux_x86_64.whl --trusted-host ms-release.obs.cn-north-4.myhuaweicloud.com -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install mindspore_serving-1.2.0-cp37-cp37m-linux_x86_64.whl

编译MindSpore Docs

在docker中执行以下命令：

git pull https://gitee.com/mindspore/docs.git
cd docs/docs/api_python
pip install -r requirements
make html

却报错：

/bin/sh: sphinx-build: command not found

经过~~一番艰难的~~排查发现是pip安装的sphinx二进制文件没有加到Path中，因此执行：

echo 'export PATH=$PATH:/usr/local/python-3.7.5/bin/' >> ~/.bashrc
source ~/.bashrc
make html

这样就编译成功啦，生成的文档输出在./build_en/html目录下

将文档导入Dash

这一步建议在Mac环境下执行，因为doc2dash依赖的sphinx版本与MindSpore docs不一致，直接在上面的docker里安装并运行doc2dash，会报错。

首先将上一步输出的html文件夹拷贝到mac里，并且在mac里执行以下命令:

pip install doc2dash
doc2dash -n MindSpore -A html/

这样就将MindSpore的文档安装到Dash中啦！

后面我计划将编译完成的MindSpore文档提交给Dash社区，这样其他同学就能直接在Dash偏好设置界面搜索到MindSpore，然后直接下载安装了。

下期预告

计划下期还是源码阅读的准备工作，主要包括：

MindSpore中哪些模块/包是Python实现的，哪些是C++实现的，它是如何使用Cmake进行Python与C++的混合编译的？
修改MindSpore源码后，如何编译并安装到本机，然后能够被自己的代码使用。
运行样例代码或MindSpore提供的测试用例，在Python及C++中如何设置断点执行，查看程序运行状态。

最后吐槽一下MindSpore没有mac版(连windows都有MindSpore CPU版了)，这样就没法将源码安装到笔记本上查看源码了。虽然现在能通过VS Code远程连服务器查看，而且最新的pylance language server的性能飞起，但是网络状况不好的时候就没办法了。