分布式训练算子标准.md

分布式训练算子接口

6.1 接口列表

类别	名称
分布式训练函数	创建初始通信器，根据进程号数组创建通信器，复制通信器，销毁通信器，查询进程数量，查询当前进程的进程号，查询异步操作的完成状态，等待异步操作完成，发送，接收，广播，全局规约，规约，全局聚集，聚集，分散，规约分散，所有对所有，屏障，异步发送，异步接收，异步广播，异步全局规约，异步规约，异步全局聚集，异步聚集，异步分散，异步规约分散，异步所有对所有，异步屏障

6.2 接口功能和参数

---

6.2.1 SGD优化器

6.2.1.1 功能描述

创建初始通信器。参与分布式训练的多个进程在开始训练前调用此函数，传入通信库类型、进程数量、当前进程的进程号、根进程标识等参数。函数将根据当前进程的进程号是否等于零来判断当前进程是否为根进程；如果当前进程为根进程，则根据根进程标识的内容来监听TCP/UDP端口、打开共享文件系统中指定的文件等等，并等待其余进程的通信请求；如果当前进程不是根进程，则根据根进程标识的内容来与根进程通信，并进一步与其余进程通信。

6.2.1.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信库类型	输入	必选	后端通信库类型，例如NCCL、GLOO、MPI等等
进程数量	输入	必选	参与通信的进程数量
进程号	输入	必选	当前进程的进程号
根进程标识	输入	必选	根进程的统一资源标识符。根进程以外的进程通过该标识符与根进程通信，并进一步获取与其他进程通信所需的信息。该标识符的形式可以是TCP/UDP端口，共享文件系统中的文件等等。
通信器	输出	必选	所创建的通信器

6.2.1.3 接口返回值

没有错误：操作成功。
通信库类型不存在：表示通信库类型不存在。
根进程标识格式错误：表示根进程标志的格式不合法。
根进程标识错误：表示无法根据根进程标志与根进程通信。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.1.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.1.5 接口示例

---

6.2.2 根据进程号数组创建通信器

6.2.2.1 功能描述

基于已有通信器，根据所传入的进程号数组，创建新通信器。新通信器中各进程的进程号等于该进程在进程号数组中的索引。原通信器中的所有进程都必须调用该函数，包括那些不会加入新通信器的进程。

6.2.2.2 接口参数

参数名	参数类型	可选/必选	参数说明
原通信器	输入	必选	原通信器
进程号数组	输入	必选	新通信器中将包含的进程号的数组
进程号数组长度	输入	必选	进程号数组的长度
新通信器	输出	必选	所创建的新通信器

6.2.2.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.2.4 引用说明

接口设计参考了PyTorch、MindSpore的接口。

6.2.2.5 接口示例

---

6.2.3 复制通信器

6.2.3.1 功能描述

复制已有通信器。该函数可用在不同的程序模块中复制通信器，避免模块间互相影响。

6.2.3.2 接口参数

参数名	参数类型	可选/必选	参数说明
原通信器	输入	必选	原通信器
新通信器	输出	必选	所创建的新通信器

6.2.3.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.3.4 引用说明

接口设计参考了MPI的接口。

6.2.3.5 接口示例

---

6.2.4 销毁通信器

6.2.4.1 功能描述

销毁已有通信器。

6.2.4.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	要销毁的通信器

6.2.4.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
其他内部错误：内部调用操作出错。

6.2.4.4 引用说明

接口设计参考了MPI、MindSpore的接口。

6.2.4.5 接口示例

---

6.2.5 查询进程数量

6.2.5.1 功能描述

查询进程数量。

6.2.5.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	要查询的通信器
进程数量	输出	必选	所查询的通信器中进程的数量

6.2.5.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.5.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.5.5 接口示例

---

6.2.6 查询当前进程的进程号

6.2.6.1 功能描述

查询当前进程的进程号。

6.2.6.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	要查询的通信器
当前进程的进程号	输出	必选	当前进程的进程号

6.2.6.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.6.4 引用说明

接口设计参考了MindSpore、MPI的接口。

6.2.6.5 接口示例

---

6.2.7 查询异步操作的完成状态

6.2.7.1 功能描述

查询异步操作的完成状态。

6.2.7.2 接口参数

参数名	参数类型	可选/必选	参数说明
异步操作	输入	必选	要查询的异步操作
完成状态	输出	必选	所查询的异步操作的状态

6.2.7.3 接口返回值

没有错误：操作成功。 其他内部错误：内部调用操作出错。

6.2.7.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.7.5 接口示例

---

6.2.8 等待异步操作完成

6.2.8.1 功能描述

等待异步操作完成。

6.2.8.2 接口参数

参数名	参数类型	可选/必选	参数说明
异步操作	输入	必选	要等待的异步操作

6.2.8.3 接口返回值

没有错误：操作成功。
其他内部错误：内部调用操作出错。

6.2.8.4 引用说明

接口设计参考了PyTorch、飞桨、MPI的接口。

6.2.8.5 接口示例

---

6.2.9 发送

6.2.9.1 功能描述

点对点通信中的发送操作。

6.2.9.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
目标进程号	输入	必选	接收进程的进程号
标签	输入	必选	附带的数据匹配标签值，必须为非负整数

6.2.9.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.9.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.9.5 接口示例

---

6.2.10 接收

6.2.10.1 功能描述

点对点通信中的接收操作。

6.2.10.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
源进程号	输入	必选	发送进程的进程号
标签	输入	必选	附带的数据匹配标签值，等于0时表示接收带有任何标签的数据，等于非零值时表示仅接收带有相同标签的数据
接收张量	输出	必选	表示接收到的张量，发送进程的该参数会被忽略

6.2.10.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.10.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.10.5 接口示例

---

6.2.11 广播

6.2.11.1 功能描述

集合通信中的广播操作。

6.2.11.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
源进程号	输入	必选	发送进程的进程号
输出张量	输出	必选	表示接收到的张量

6.2.11.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.11.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.11.5 接口示例

---

6.2.12 全局规约

6.2.12.1 功能描述

集合通信中的全局规约操作。

6.2.12.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约的张量
规约类型	输入	必选	进行规约时使用的操作类型
输出张量	输出	必选	规约后得到的张量

6.2.12.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.12.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.12.5 接口示例

---

6.2.13 规约

6.2.13.1 功能描述

集合通信中的规约操作。

6.2.13.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约的张量
规约类型	输入	必选	进行规约时使用的操作类型
目标进程号	输入	必选	接收结果的进程的进程号
输出张量	输出	必选	规约后得到的张量

6.2.13.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.13.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI的接口。

6.2.13.5 接口示例

---

6.2.14 全局聚集

6.2.14.1 功能描述

集合通信中的全局聚集操作。

6.2.14.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行聚集的张量
输出张量	输出	必选	聚集得到的张量

6.2.14.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.14.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.14.5 接口示例

---

6.2.15 聚集

6.2.15.1 功能描述

集合通信中的聚集操作。

6.2.15.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行聚集的张量
目标进程号	输入	必选	接收结果的进程号
输出张量	输出	必选	聚集得到的张量

6.2.15.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.15.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI的接口。

6.2.15.5 接口示例

---

6.2.16 分散

6.2.16.1 功能描述

集合通信中的分散操作。

6.2.16.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行分散的张量
源进程号	输入	必选	分发张量的进程的进程号
输出张量	输出	必选	分发后各进程接收到的张量

6.2.16.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.16.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.16.5 接口示例

---

6.2.17 规约分散

6.2.17.1 功能描述

集合通信中的规约分散操作。

6.2.17.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约分散的张量
规约类型	输入	必选	进行规约时使用的操作类型
输出张量	输出	必选	规约分散后得到的张量

6.2.17.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.17.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.17.5 接口示例

---

6.2.18 所有对所有

6.2.18.1 功能描述

集合通信中的所有对所有操作。

6.2.18.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
输出张量	输出	必选	接收到的张量

6.2.18.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.18.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.18.5 接口示例

---

6.2.19 屏障

6.2.19.1 功能描述

屏障操作，用于进程同步。

6.2.19.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器

6.2.19.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
其他内部错误：内部调用操作出错。

6.2.19.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.19.5 接口示例

---

6.2.20 异步发送

6.2.20.1 功能描述

点对点通信中的异步发送操作。

6.2.20.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
目标进程号	输入	必选	接收进程的进程号
标签	输入	必选	附带的数据匹配标签值，必须为非负整数
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.20.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.20.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.20.5 接口示例

---

6.2.21 异步接收

6.2.21.1 功能描述

点对点通信中的异步接收操作。

6.2.21.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
源进程号	输入	必选	发送进程的进程号
标签	输入	必选	附带的数据匹配标签值，等于0时表示接收带有任何标签的数据，等于非零值时表示仅接收带有相同标签的数据
接收张量	输出	表示接收到的张量，发送进程的该参数会被忽略
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.21.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.21.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.21.5 接口示例

---

6.2.22 异步广播

6.2.22.1 功能描述

集合通信中的异步广播操作。

6.2.22.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
源进程号	输入	必选	发送进程的进程号
输出张量	输出	必选	表示接收到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.22.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.22.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.22.5 接口示例

---

6.2.23 异步全局规约

6.2.23.1 功能描述

集合通信中的异步全局规约操作。

6.2.23.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约的张量
规约类型	输入	必选	进行规约时使用的操作类型
输出张量	输出	必选	规约后得到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.23.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.23.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.23.5 接口示例

---

6.2.24 异步规约

6.2.24.1 功能描述

集合通信中的异步规约操作。

6.2.24.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约的张量
规约类型	输入	必选	进行规约时使用的操作类型
目标进程号	输入	必选	接收结果的进程的进程号
输出张量	输出	必选	规约后得到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.24.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.24.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI的接口。

6.2.24.5 接口示例

---

6.2.25 异步全局聚集

6.2.25.1 功能描述

集合通信中的异步全局聚集操作。

6.2.25.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行聚集的张量
输出张量	输出	必选	聚集得到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.25.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.25.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.25.5 接口示例

---

6.2.26 异步聚集

6.2.26.1 功能描述

集合通信中的异步聚集操作。

6.2.26.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行聚集的张量
目标进程号	输入	必选	接收结果的进程号
输出张量	输出	必选	聚集得到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.26.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
目标进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.26.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI的接口。

6.2.26.5 接口示例

---

6.2.27 异步分散

6.2.27.1 功能描述

集合通信中的异步分散操作。

6.2.27.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行分散的张量
源进程号	输入	必选	分发张量的进程的进程号
输出张量	输出	必选	分发后各进程接收到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.27.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
源进程号不存在：表示进程号不存在于通信器中。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.27.4 引用说明

接口设计参考了PyTorch、MPI的接口。

6.2.27.5 接口示例

---

6.2.28 异步规约分散

6.2.28.1 功能描述

集合通信中的异步规约分散操作。

6.2.28.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要进行规约分散的张量
规约类型	输入	必选	进行规约时使用的操作类型
输出张量	输出	必选	规约分散后得到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.28.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.28.4 引用说明

接口设计参考了PyTorch、MPI、MindSpore的接口。

6.2.28.5 接口示例

---

6.2.29 异步所有对所有

6.2.29.1 功能描述

集合通信中的异步所有对所有操作。

6.2.29.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
输入张量	输入	必选	需要发送的张量
输出张量	输出	必选	接收到的张量
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.29.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
非法参数：表示其他参数不合法。
其他内部错误：内部调用操作出错。

6.2.29.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.29.5 接口示例

---

6.2.30 异步屏障

6.2.30.1 功能描述

异步屏障操作，用于进程同步。

6.2.30.2 接口参数

参数名	参数类型	可选/必选	参数说明
通信器	输入	必选	所使用的通信器
异步操作	输出	必选	本次的异步操作，用于后续查询操作的完成状态，或者等待操作完成等。

6.2.30.3 接口返回值

没有错误：操作成功。
通信器不存在：表示通信器不存在。
其他内部错误：内部调用操作出错。

6.2.30.4 引用说明

接口设计参考了TensorFlow、PyTorch、MPI、MindSpore的接口。

6.2.30.5 接口示例

---