p83571920
/
mindspore
forked from mindspore-Ecosystem/mindspore
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

!10582 [ModelZoo]Add gnn readme for CN 

From: @zhan_ke
Reviewed-by: 
Signed-off-by:
This commit is contained in:
mindspore-ci-bot 2020-12-31 10:35:22 +08:00 committed by Gitee
parent 37726406ff 76d58aa5c0
commit 882a582eb4
3 changed files with 637 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

243
model_zoo/official/gnn/bgcf/README_CN.md Normal file
View File

@ -0,0 +1,243 @@
# 目录
<!-- TOC -->
- [目录](#目录)
- [贝叶斯图协同过滤](#贝叶斯图协同过滤)
- [模型架构](#模型架构)
- [数据集](#数据集)
- [特性](#特性)
- [混合精度](#混合精度)
- [环境要求](#环境要求)
- [快速入门](#快速入门)
- [脚本说明](#脚本说明)
- [脚本及样例代码](#脚本及样例代码)
- [脚本参数](#脚本参数)
- [训练过程](#训练过程)
- [训练](#训练)
- [评估过程](#评估过程)
- [评估](#评估)
- [模型描述](#模型描述)
- [性能](#性能)
- [随机情况说明](#随机情况说明)
- [ModelZoo主页](#modelzoo主页)
<!-- /TOC -->
# 贝叶斯图协同过滤
贝叶斯图协同过滤（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)。

202
model_zoo/official/gnn/gat/README_CN.md Normal file
View File

@ -0,0 +1,202 @@
# 目录
<!-- TOC -->
- [目录](#目录)
- [图注意力网络描述](#图注意力网络描述)
- [模型架构](#模型架构)
- [数据集](#数据集)
- [特性](#特性)
- [混合精度](#混合精度)
- [环境要求](#环境要求)
- [快速入门](#快速入门)
- [脚本说明](#脚本说明)
- [脚本及样例代码](#脚本及样例代码)
- [脚本参数](#脚本参数)
- [训练过程](#训练过程)
- [训练](#训练)
- [模型描述](#模型描述)
- [性能](#性能)
- [随机情况说明](#随机情况说明)
- [ModelZoo主页](#modelzoo主页)
<!-- /TOC -->
# 图注意力网络描述
图注意力网络（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 |
| 脚本 | <https://gitee.com/mindspore/mindspore/tree/master/model_zoo/official/gnn/gat> |
# 随机情况说明
GAT模型中有很多的dropout操作，如果想关闭dropout，可以在src/config.py中将attn_dropout和feature_dropout设置为0。注：该操作会导致准确率降低到80%左右。
# ModelZoo主页
请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。

192
model_zoo/official/gnn/gcn/README_CN.md Normal file
View File

@ -0,0 +1,192 @@
# 目录
<!-- TOC -->
- [目录](#目录)
- [图卷积网络描述](#图卷积网络描述)
- [模型架构](#模型架构)
- [数据集](#数据集)
- [环境要求](#环境要求)
- [快速入门](#快速入门)
- [用法](#用法)
- [启动](#启动)
- [脚本说明](#脚本说明)
- [脚本及样例代码](#脚本及样例代码)
- [脚本参数](#脚本参数)
- [培训、评估、测试过程](#培训评估测试过程)
- [用法](#用法-1)
- [启动](#启动-1)
- [结果](#结果)
- [模型描述](#模型描述)
- [性能](#性能)
- [随机情况说明](#随机情况说明)
- [ModelZoo主页](#modelzoo主页)
<!-- /TOC -->
# 图卷积网络描述
图卷积网络（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 |
| 脚本 | <https://gitee.com/mindspore/mindspore/tree/master/model_zoo/official/gnn/gcn> |
# 随机情况说明
以下两种随机情况：
- 根据入参--seed在train.py中设置种子。
- 随机失活操作。
train.py已经设置了一些种子，避免权重初始化的随机性。若需关闭随机失活，将src/config.py中相应的dropout_prob参数设置为0。
# ModelZoo主页
请浏览官网[主页](https://gitee.com/mindspore/mindspore/tree/master/model_zoo)。