diff --git a/model_zoo/official/gnn/bgcf/README_CN.md b/model_zoo/official/gnn/bgcf/README_CN.md new file mode 100644 index 0000000000..e5b88fda40 --- /dev/null +++ b/model_zoo/official/gnn/bgcf/README_CN.md @@ -0,0 +1,243 @@ +# 目录 + + + +- [目录](#目录) +- [贝叶斯图协同过滤](#贝叶斯图协同过滤) +- [模型架构](#模型架构) +- [数据集](#数据集) +- [特性](#特性) + - [混合精度](#混合精度) +- [环境要求](#环境要求) +- [快速入门](#快速入门) +- [脚本说明](#脚本说明) + - [脚本及样例代码](#脚本及样例代码) + - [脚本参数](#脚本参数) + - [训练过程](#训练过程) + - [训练](#训练) + - [评估过程](#评估过程) + - [评估](#评估) +- [模型描述](#模型描述) + - [性能](#性能) +- [随机情况说明](#随机情况说明) +- [ModelZoo主页](#modelzoo主页) + + + +# 贝叶斯图协同过滤 + +贝叶斯图协同过滤（BGCF）是Sun J、Guo W、Zhang D等人于2020年提出的。通过结合用户与物品交互图中的不确定性，显示了Amazon推荐数据集的优异性能。使用MindSpore中的Amazon-Beauty数据集对BGCF进行训练。更重要的是，这是BGCF的第一个开源版本。 + +[论文](https://dl.acm.org/doi/pdf/10.1145/3394486.3403254): Sun J, Guo W, Zhang D, et al.A Framework for Recommending Accurate and Diverse Items Using Bayesian Graph Convolutional Neural Networks[C]//Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining.2020: 2030-2039. + +# 模型架构 + +BGCF包含两个主要模块。首先是抽样，它生成基于节点复制的样本图。另一个为聚合节点的邻居采样，节点包含平均聚合器和注意力聚合器。 + +# 数据集 + +- 数据集大小： + + 所用数据集的统计信息摘要如下： + + | | Amazon-Beauty | + | ------------------ | -----------------------:| + | 任务 | 推荐 | + | # 用户 | 7068 (1图) | + | # 物品 | 3570 | + | # 交互 | 79506 | + | # 训练数据 | 60818 | + | # 测试数据 | 18688 | + | # 密度 | 0.315% | + +- 数据准备 + - 将数据集放到任意路径，文件夹应该包含如下文件（以Amazon-Beauty数据集为例）： + + ```text + . + └─data + ├─ratings_Beauty.csv + ``` + + - 为Amazon-Beauty生成MindRecord格式的数据集 + + ```builddoutcfg + cd ./scripts + # SRC_PATH是您下载的数据集文件路径 + sh run_process_data_ascend.sh [SRC_PATH] + ``` + + - 启动 + + ```text + # 为Amazon-Beauty生成MindRecord格式的数据集 + sh ./run_process_data_ascend.sh ./data + +# 特性 + +## 混合精度 + +为了充分利用Ascend芯片强大的运算能力，加快训练过程，此处采用混合训练方法。MindSpore能够处理FP32输入和FP16操作符。在BGCF示例中，除损失计算部分外，模型设置为FP16模式。 + +# 环境要求 + +- 硬件（Ascend） +- 框架 + - [MindSpore](https://www.mindspore.cn/install) +- 如需查看详情，请参见如下资源： + - [MindSpore教程](https://www.mindspore.cn/tutorial/training/zh-CN/master/index.html) + - [MindSpore Python API](https://www.mindspore.cn/doc/api_python/zh-CN/master/index.html) + +# 快速入门 + +通过官方网站安装MindSpore，并正确生成数据集后，您可以按照如下步骤进行训练和评估： + +- Ascend处理器环境运行 + + ```text + + # 使用Amazon-Beauty数据集运行训练示例 + sh run_train_ascend.sh + + # 使用Amazon-Beauty数据集运行评估示例 + sh run_eval_ascend.sh + + ``` + +# 脚本说明 + +## 脚本及样例代码 + +```shell + +└─bgcf + ├─README.md + ├─scripts + | ├─run_eval_ascend.sh # 启动评估 + | ├─run_process_data_ascend.sh # 生成MindRecord格式的数据集 + | └─run_train_ascend.sh # 启动训练 + | + ├─src + | ├─bgcf.py # BGCF模型 + | ├─callback.py # 回调函数 + | ├─config.py # 训练配置 + | ├─dataset.py # 数据预处理 + | ├─metrics.py # 推荐指标 + | └─utils.py # 训练BGCF的工具 + | + ├─eval.py # 评估网络 + └─train.py # 训练网络 + +``` + +## 脚本参数 + +在config.py中可以同时配置训练参数和评估参数。 + +- BGCF数据集配置 + + ```python + + "learning_rate": 0.001, # 学习率 + "num_epochs": 600, # 训练轮次 + "num_neg": 10, # 负采样率 + "raw_neighs": 40, # 原图采样邻居个数 + "gnew_neighs": 20, # 样本图采样邻居个数 + "input_dim": 64, # 用户与物品嵌入维度 + "l2_coeff": 0.03 # l2系数 + "neighbor_dropout": [0.0, 0.2, 0.3]# 不同汇聚层dropout率 + "num_graphs":5 # 样例图个数 + + ``` + + 在config.py中以获取更多配置。 + +## 训练过程 + +### 训练 + +- Ascend处理器环境运行 + + ```python + + sh run_train_ascend.sh + + ``` + + 训练结果将保存在脚本路径下，文件夹名称以“train”开头。您可在日志中找到结果，如下所示。 + + ```python + + Epoch 001 iter 12 loss 34696.242 + Epoch 002 iter 12 loss 34275.508 + Epoch 003 iter 12 loss 30620.635 + Epoch 004 iter 12 loss 21628.908 + + ... + Epoch 597 iter 12 loss 3662.3152 + Epoch 598 iter 12 loss 3640.7612 + Epoch 599 iter 12 loss 3654.9087 + Epoch 600 iter 12 loss 3632.4585 + ... + + ``` + +## 评估过程 + +### 评估 + +- Ascend评估 + + ```python + + sh run_eval_ascend.sh + + ``` + + 评估结果将保存在脚本路径下，文件夹名称以“eval”开头。您可在日志中找到结果，如下所示。 + + ```python + + epoch:020, recall_@10:0.07345, recall_@20:0.11193, ndcg_@10:0.05293, ndcg_@20:0.06613, + sedp_@10:0.01393, sedp_@20:0.01126, nov_@10:6.95106, nov_@20:7.22280 + epoch:040, recall_@10:0.07410, recall_@20:0.11537, ndcg_@10:0.05387, ndcg_@20:0.06801, + sedp_@10:0.01445, sedp_@20:0.01168, nov_@10:7.34799, nov_@20:7.58883 + epoch:060, recall_@10:0.07654, recall_@20:0.11987, ndcg_@10:0.05530, ndcg_@20:0.07015, + sedp_@10:0.01474, sedp_@20:0.01206, nov_@10:7.46553, nov_@20:7.69436 + + ... + epoch:560, recall_@10:0.09825, recall_@20:0.14877, ndcg_@10:0.07176, ndcg_@20:0.08883, + sedp_@10:0.01882, sedp_@20:0.01501, nov_@10:7.58045, nov_@20:7.79586 + epoch:580, recall_@10:0.09917, recall_@20:0.14970, ndcg_@10:0.07337, ndcg_@20:0.09037, + sedp_@10:0.01896, sedp_@20:0.01504, nov_@10:7.57995, nov_@20:7.79439 + epoch:600, recall_@10:0.09926, recall_@20:0.15080, ndcg_@10:0.07283, ndcg_@20:0.09016, + sedp_@10:0.01890, sedp_@20:0.01517, nov_@10:7.58277, nov_@20:7.80038 + ... + + ``` + +# 模型描述 + +## 性能 + +| 参数 | BGCF | +| ------------------------------------ | ----------------------------------------- | +| 资源 | Ascend 910 | +| 上传日期 | 09/23/2020(月/日/年) | +| MindSpore版本 | 1.0.0 | +| 数据集 | Amazon-Beauty | +| 训练参数 | epoch=600 | +| 优化器 | Adam | +| 损失函数 | BPR loss | +| Recall@20 | 0.1534 | +| NDCG@20 | 0.0912 | +| 训练成本 | 25min | +| 脚本 | [bgcf脚本](https://gitee.com/mindspore/mindspore/tree/master/model_zoo/official/gnn/bgcf) | + +# 随机情况说明 + +BGCF模型中有很多的dropout操作，如果想关闭dropout，可以在src/config.py中将neighbor_dropout设置为[0.0, 0.0, 0.0] 。 + +# ModelZoo主页 + +请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。 diff --git a/model_zoo/official/gnn/gat/README_CN.md b/model_zoo/official/gnn/gat/README_CN.md new file mode 100644 index 0000000000..0499c4a5fa --- /dev/null +++ b/model_zoo/official/gnn/gat/README_CN.md @@ -0,0 +1,202 @@ +# 目录 + + + +- [目录](#目录) +- [图注意力网络描述](#图注意力网络描述) +- [模型架构](#模型架构) +- [数据集](#数据集) +- [特性](#特性) + - [混合精度](#混合精度) +- [环境要求](#环境要求) +- [快速入门](#快速入门) +- [脚本说明](#脚本说明) + - [脚本及样例代码](#脚本及样例代码) + - [脚本参数](#脚本参数) + - [训练过程](#训练过程) + - [训练](#训练) +- [模型描述](#模型描述) + - [性能](#性能) +- [随机情况说明](#随机情况说明) +- [ModelZoo主页](#modelzoo主页) + + + +# 图注意力网络描述 + +图注意力网络（GAT）由Petar Veličković等人于2017年提出。GAT通过利用掩蔽自注意层来克服现有基于图的方法的缺点，在Cora等传感数据集和PPI等感应数据集上都达到了最先进的性能。以下是用MindSpore的Cora数据集训练GAT的例子。 + +[论文](https://arxiv.org/abs/1710.10903): Veličković, P., Cucurull, G., Casanova, A., Romero, A., Lio, P., & Bengio, Y. (2017).Graph attention networks. arXiv preprint arXiv:1710.10903. + +# 模型架构 + +请注意节点更新函数是级联还是平均，取决于注意力层是否为网络输出层。 + +# 数据集 + +- 数据集大小： + + 所用数据集汇总如下： + + | | Cora | Citeseer | + | ------------------ | -------------: | -------------: | + | 任务 | Transductive | Transductive | + | # 节点 | 2708 (1图) | 3327 (1图) | + | # 边 | 5429 | 4732 | + | # 特性/节点 | 1433 | 3703 | + | # 类 | 7 | 6 | + | # 训练节点 | 140 | 120 | + | # 验证节点 | 500 | 500 | + | # 测试节点 | 1000 | 1000 | + +- 数据准备 + - 将数据集放到任意路径，文件夹应该包含如下文件（以Cora数据集为例）： + + ```text + . + └─data + ├─ind.cora.allx + ├─ind.cora.ally + ├─ind.cora.graph + ├─ind.cora.test.index + ├─ind.cora.tx + ├─ind.cora.ty + ├─ind.cora.x + └─ind.cora.y + ``` + + - 为Cora或Citeseer生成MindRecord格式的数据集 + + ```buildoutcfg + cd ./scripts + # SRC_PATH为下载的数据集文件路径，DATASET_NAME为Cora或Citeseer + sh run_process_data_ascend.sh [SRC_PATH] [DATASET_NAME] + ``` + + - 启动 + + ```text + # 为Cora生成MindRecord格式的数据集 + ./run_process_data_ascend.sh ./data cora + # 为Citeseer生成MindRecord格式的数据集 + ./run_process_data_ascend.sh ./data citeseer + ``` + +# 特性 + +## 混合精度 + +为了充分利用Ascend芯片强大的运算能力，加快训练过程，此处采用混合训练方法。MindSpore能够处理FP32输入和FP16操作符。在GAT示例中，除损失计算部分外，模型设置为FP16模式。 + +# 环境要求 + +- 硬件（Ascend） +- 框架 + - [MindSpore](https://www.mindspore.cn/install) +- 如需查看详情，请参见如下资源： + - [MindSpore教程](https://www.mindspore.cn/tutorial/training/zh-CN/master/index.html) + - [MindSpore Python API](https://www.mindspore.cn/doc/api_python/zh-CN/master/index.html) + +# 快速入门 + +通过官方网站安装MindSpore，并正确生成数据集后，您可以按照如下步骤进行训练和评估： + +- Ascend处理器环境运行 + + ```text + # 使用Cora数据集运行训练示例，DATASET_NAME为cora + sh run_train_ascend.sh [DATASET_NAME] + ``` + +# 脚本说明 + +## 脚本及样例代码 + +```shell +. +└─gat + ├─README.md + ├─scripts + | ├─run_process_data_ascend.sh # 生成MindRecord格式的数据集 + | └─run_train_ascend.sh # 启动训练 + | + ├─src + | ├─config.py # 训练配置 + | ├─dataset.py # 数据预处理 + | ├─gat.py # GAT模型 + | └─utils.py # 训练gat的工具 + | + └─train.py # 训练网络 +``` + +## 脚本参数 + +在config.py中可以同时配置训练参数和评估参数。 + +- 配置GAT和Cora数据集 + + ```python + "learning_rate": 0.005, # 学习率 + "num_epochs": 200, # 训练轮次 + "hid_units": [8], # 每层注意头隐藏单元 + "n_heads": [8, 1], # 每层头数 + "early_stopping": 100, # 早停忍耐轮次数 + "l2_coeff": 0.0005 # l2系数 + "attn_dropout": 0.6 # 注意力层dropout系数 + "feature_dropout":0.6 # 特征层dropout系数 + ``` + +## 训练过程 + +### 训练 + +- Ascend处理器环境运行 + + ```python + sh run_train_ascend.sh [DATASET_NAME] + ``` + + 训练结果将保存在脚本路径下，文件夹名称以“train”开头。您可在日志中找到结果 + ，如下所示。 + + ```python + Epoch:0, train loss=1.98498 train acc=0.17143 | val loss=1.97946 val acc=0.27200 + Epoch:1, train loss=1.98345 train acc=0.15000 | val loss=1.97233 val acc=0.32600 + Epoch:2, train loss=1.96968 train acc=0.21429 | val loss=1.96747 val acc=0.37400 + Epoch:3, train loss=1.97061 train acc=0.20714 | val loss=1.96410 val acc=0.47600 + Epoch:4, train loss=1.96864 train acc=0.13571 | val loss=1.96066 val acc=0.59600 + ... + Epoch:195, train loss=1.45111 train_acc=0.56429 | val_loss=1.44325 val_acc=0.81200 + Epoch:196, train loss=1.52476 train_acc=0.52143 | val_loss=1.43871 val_acc=0.81200 + Epoch:197, train loss=1.35807 train_acc=0.62857 | val_loss=1.43364 val_acc=0.81400 + Epoch:198, train loss=1.47566 train_acc=0.51429 | val_loss=1.42948 val_acc=0.81000 + Epoch:199, train loss=1.56411 train_acc=0.55000 | val_loss=1.42632 val_acc=0.80600 + Test loss=1.5366285, test acc=0.84199995 + ... + ``` + +# 模型描述 + +## 性能 + +| 参数 | GAT | +| ------------------------------------ | ----------------------------------------- | +| 资源 | Ascend 910 | +| 上传日期 | 2020-06-16 | +| MindSpore版本 | 0.5.0-beta | +| 数据集 | Cora/Citeseer | +| 训练参数 | epoch=200 | +| 优化器 | Adam | +| 损失函数 | Softmax交叉熵 | +| 准确率 | 83.0/72.5 | +| 速度 | 0.195s/epoch | +| 总时长 | 39s | +| 脚本 | | + +# 随机情况说明 + +GAT模型中有很多的dropout操作，如果想关闭dropout，可以在src/config.py中将attn_dropout和feature_dropout设置为0。注：该操作会导致准确率降低到80%左右。 + +# ModelZoo主页 + +请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。 diff --git a/model_zoo/official/gnn/gcn/README_CN.md b/model_zoo/official/gnn/gcn/README_CN.md new file mode 100644 index 0000000000..1b5035bc2a --- /dev/null +++ b/model_zoo/official/gnn/gcn/README_CN.md @@ -0,0 +1,192 @@ +# 目录 + + + +- [目录](#目录) +- [图卷积网络描述](#图卷积网络描述) +- [模型架构](#模型架构) +- [数据集](#数据集) +- [环境要求](#环境要求) +- [快速入门](#快速入门) + - [用法](#用法) + - [启动](#启动) +- [脚本说明](#脚本说明) + - [脚本及样例代码](#脚本及样例代码) + - [脚本参数](#脚本参数) + - [培训、评估、测试过程](#培训评估测试过程) + - [用法](#用法-1) + - [启动](#启动-1) + - [结果](#结果) +- [模型描述](#模型描述) + - [性能](#性能) +- [随机情况说明](#随机情况说明) +- [ModelZoo主页](#modelzoo主页) + + + +# 图卷积网络描述 + +图卷积网络（GCN）于2016年提出，旨在对图结构数据进行半监督学习。它提出了一种基于卷积神经网络有效变体的可扩展方法，可直接在图上操作。该模型在图边缘的数量上线性缩放，并学习隐藏层表示，这些表示编码了局部图结构和节点特征。 + +[论文](https://arxiv.org/abs/1609.02907): Thomas N. Kipf, Max Welling.2016.Semi-Supervised Classification with Graph Convolutional Networks.In ICLR 2016. + +# 模型架构 + +GCN包含两个图卷积层。每一层以节点特征和邻接矩阵为输入，通过聚合相邻特征来更新节点特征。 + +# 数据集 + +| 数据集 | 类型 | 节点 | 边 | 类 | 特征 | 标签率 | +| ------- | ---------------:|-----:| ----:| ------:|--------:| ---------:| +| Cora | Citation network | 2708 | 5429 | 7 | 1433 | 0.052 | +| Citeseer| Citation network | 3327 | 4732 | 6 | 3703 | 0.036 | + +# 环境要求 + +- 硬件（Ascend处理器） + - 准备Ascend或GPU处理器搭建硬件环境。如需试用昇腾处理器，请发送[申请表](https://obs-9be7.obs.cn-east-2.myhuaweicloud.com/file/other/Ascend%20Model%20Zoo%E4%BD%93%E9%AA%8C%E8%B5%84%E6%BA%90%E7%94%B3%E8%AF%B7%E8%A1%A8.docx)至ascend@huawei，审核通过即可获得资源。 +- 框架 + - [MindSpore](https://gitee.com/mindspore/mindspore) +- 如需查看详情，请参见如下资源： + - [MindSpore教程](https://www.mindspore.cn/tutorial/training/zh-CN/master/index.html) + - [MindSpore Python API](https://www.mindspore.cn/doc/api_python/zh-CN/master/index.html) + +# 快速入门 + +- 安装[MindSpore](https://www.mindspore.cn/install) + +- 从github下载/kimiyoung/planetoid提供的数据集Cora或Citeseer + +- 将数据集放到任意路径，文件夹应该包含如下文件（以Cora数据集为例）： + +```text +. +└─data + ├─ind.cora.allx + ├─ind.cora.ally + ├─ind.cora.graph + ├─ind.cora.test.index + ├─ind.cora.tx + ├─ind.cora.ty + ├─ind.cora.x + └─ind.cora.y +``` + +- 为Cora或Citeseer生成MindRecord格式的数据集 + +## 用法 + +```buildoutcfg +cd ./scripts +# SRC_PATH为下载的数据集文件路径，DATASET_NAME为Cora或Citeseer +sh run_process_data.sh [SRC_PATH] [DATASET_NAME] +``` + +## 启动 + +```text +# 为Cora生成MindRecord格式的数据集 +sh run_process_data.sh ./data cora +# 为Citeseer生成MindRecord格式的数据集 +sh run_process_data.sh ./data citeseer +``` + +# 脚本说明 + +## 脚本及样例代码 + +```shell +. +└─gcn + ├─README.md + ├─scripts + | ├─run_process_data.sh # 生成MindRecord格式的数据集 + | └─run_train.sh # 启动训练，目前只支持Ascend后端 + | + ├─src + | ├─config.py # 参数配置 + | ├─dataset.py # 数据预处理 + | ├─gcn.py # GCN骨干 + | └─metrics.py # 损失和准确率 + | + └─train.py # 训练网络，每个训练轮次后评估验证结果收敛后，训练停止，然后进行测试。 +``` + +## 脚本参数 + +训练参数可以在config.py中配置。 + +```text +"learning_rate": 0.01, # 学习率 +"epochs": 200, # 训练轮次 +"hidden1": 16, # 第一图卷积层隐藏大小 +"dropout": 0.5, # 第一图卷积层dropout率 +"weight_decay": 5e-4, # 第一图卷积层参数的权重衰减 +"early_stopping": 10, # 早停容限 +``` + +## 培训、评估、测试过程 + +### 用法 + +```text +# 使用Cora或Citeseer数据集进行训练，DATASET_NAME为Cora或Citeseer +sh run_train.sh [DATASET_NAME] +``` + +### 启动 + +```bash +sh run_train.sh cora +``` + +### 结果 + +训练结果将保存在脚本路径下，文件夹名称以“train”开头。您可在日志中找到如下结果： + +```text +Epoch:0001 train_loss= 1.95373 train_acc= 0.09286 val_loss= 1.95075 val_acc= 0.20200 time= 7.25737 +Epoch:0002 train_loss= 1.94812 train_acc= 0.32857 val_loss= 1.94717 val_acc= 0.34000 time= 0.00438 +Epoch:0003 train_loss= 1.94249 train_acc= 0.47857 val_loss= 1.94337 val_acc= 0.43000 time= 0.00428 +Epoch:0004 train_loss= 1.93550 train_acc= 0.55000 val_loss= 1.93957 val_acc= 0.46400 time= 0.00421 +Epoch:0005 train_loss= 1.92617 train_acc= 0.67143 val_loss= 1.93558 val_acc= 0.45400 time= 0.00430 +... +Epoch:0196 train_loss= 0.60326 train_acc= 0.97857 val_loss= 1.05155 val_acc= 0.78200 time= 0.00418 +Epoch:0197 train_loss= 0.60377 train_acc= 0.97143 val_loss= 1.04940 val_acc= 0.78000 time= 0.00418 +Epoch:0198 train_loss= 0.60680 train_acc= 0.95000 val_loss= 1.04847 val_acc= 0.78000 time= 0.00414 +Epoch:0199 train_loss= 0.61920 train_acc= 0.96429 val_loss= 1.04797 val_acc= 0.78400 time= 0.00413 +Epoch:0200 train_loss= 0.57948 train_acc= 0.96429 val_loss= 1.04753 val_acc= 0.78600 time= 0.00415 +Optimization Finished! +Test set results: cost= 1.00983 accuracy= 0.81300 time= 0.39083 +... +``` + +# 模型描述 + +## 性能 + +| 参数 | GCN | +| -------------------------- | -------------------------------------------------------------- | +| 资源 | Ascend 910 | +| 上传日期 | 2020-06-09 | +| MindSpore版本 | 0.5.0-beta | +| 数据集 | Cora/Citeseer | +| 训练参数 | epoch=200 | +| 优化器 | Adam | +| 损失函数 | Softmax交叉熵 | +| 准确率 | 81.5/70.3 | +| 参数(B) | 92160/59344 | +| 脚本 | | + +# 随机情况说明 + +以下两种随机情况： + +- 根据入参--seed在train.py中设置种子。 +- 随机失活操作。 + +train.py已经设置了一些种子，避免权重初始化的随机性。若需关闭随机失活，将src/config.py中相应的dropout_prob参数设置为0。 + +# ModelZoo主页 + +请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。