Merge pull request #1808 from heavengate/video_doc

Video doc

README.md

@@ -36,6 +36,7 @@ PaddlePaddle 提供了丰富的计算单元，使得用户可以采用模块化
 [Attention模型](./fluid/PaddleCV/ocr_recognition)|场景文字识别模型|使用attention 识别图片中单行英文字符|[Recurrent Models of Visual Attention](https://arxiv.org/abs/1406.6247)
 [Metric Learning](https://github.com/PaddlePaddle/models/tree/develop/fluid/PaddleCV/metric_learning)|度量学习模型|能够用于分析对象时间的关联、比较关系，可应用于辅助分类、聚类问题，也广泛用于图像检索、人脸识别等领域|-
 [TSN](./fluid/PaddleCV/video_classification)|视频分类模型|基于长范围时间结构建模，结合了稀疏时间采样策略和视频级监督来保证使用整段视频时学习得有效和高效|[Temporal Segment Networks: Towards Good Practices for Deep Action Recognition](https://arxiv.org/abs/1608.00859)
+[视频模型库](./fluid/PaddleCV/video)|视频模型库|给开发者提供基于PaddlePaddle的便捷、高效的使用深度学习算法解决视频理解、视频编辑、视频生成等一系列模型||
 [caffe2fluid](./fluid/PaddleCV/caffe2fluid)|将Caffe模型转换为Paddle Fluid配置和模型文件工具|-|-
 
 ## PaddleNLP

fluid/PaddleCV/video/README.md

-# VideoClassification
-Video Classification
 
-To run train:
-    bash ./scripts/train/train_${model_name}.sh
-To run test:
-    bash ./scripts/test/test_${model_name}.sh
+## 简介
+本教程期望给开发者提供基于PaddlePaddle的便捷、高效的使用深度学习算法解决视频理解、视频编辑、视频生成等一系列模型。目前包含视频分类模型，后续会不断的扩展到其他更多场景。
+
+目前视频分类模型包括:
+
+| 模型 | 类别  | 描述 |
+| :--------------- | :--------: | :------------: |
+| [Attention Cluster](./models/attention_cluster/README.md) [[论文](https://arxiv.org/abs/1711.09550)] | 视频分类| CVPR'18提出的视频多模态特征注意力聚簇融合方法 |
+| [Attention LSTM](./models/attention_lstm/README.md) [[论文](https://arxiv.org/abs/1503.08909)] | 视频分类| 常用模型，速度快精度高 |
+| [NeXtVLAD](./models/nextvlad/README.md) [[论文](https://arxiv.org/abs/1811.05014)] | 视频分类| 2nd-Youtube-8M最优单模型 |
+| [StNet](./models/stnet/README.md) [[论文](https://arxiv.org/abs/1811.01549)] | 视频分类| AAAI'19提出的视频联合时空建模方法 |
+| [TSN](./models/tsn/README.md) [[论文](https://arxiv.org/abs/1608.00859)] | 视频分类| ECCV'16提出的基于2D-CNN经典解决方案 |
+
+## 安装
+
+在当前模型库运行样例代码需要PadddlePaddle Fluid v.1.2.0或以上的版本。如果你的运行环境中的PaddlePaddle低于此版本，请根据[安装文档](http://www.paddlepaddle.org/documentation/docs/zh/1.3/beginners_guide/install/index_cn.html)中的说明来更新PaddlePaddle。
+
+## 数据准备
+
+视频模型库使用Youtube-8M和Kinetics数据集, 具体使用方法请参考[数据说明](./dataset/README.md)
+
+## 快速使用
+
+视频模型库提供通用的train/test/infer框架，通过`train.py/test.py/infer.py`指定模型名、模型配置参数等可一键式进行训练和预测。
+
+以StNet模型为例：
+
+单卡训练：
+
+``` bash
+export CUDA_VISIBLE_DEVICES=0
+python train.py --model-name=STNET
+        --config=./configs/stnet.txt
+        --save-dir=checkpoints
+```
+
+多卡训练：
+
+``` bash
+export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
+python train.py --model-name=STNET
+        --config=./configs/stnet.txt
+        --save-dir=checkpoints
+```
+
+视频模型库同时提供了快速训练脚本，脚本位于`scripts/train`目录下，可通过如下命令启动训练:
+
+``` bash
+bash scripts/train/train_stnet.sh
+```
+
+- 请根据`CUDA_VISIBLE_DEVICES`指定卡数修改`config`文件中的`num_gpus`和`batch_size`配置。
+
+## Model Zoo
+
+- 基于Youtube-8M数据集模型：
+
+| 模型 | Batch Size | 环境配置 | cuDNN版本 | GAP | 下载链接 |
+| :-------: | :---: | :---------: | :-----: | :----: | :----------: |
+| Attention Cluster | 2048 | 8卡P40 | 7.1 | 0.84 | [model](https://paddlemodels.bj.bcebos.com/video_classification/attention_cluster_youtube8m.tar.gz) |
+| Attention LSTM | 1024 | 8卡P40 | 7.1 | 0.86 | [model](https://paddlemodels.bj.bcebos.com/video_classification/attention_lstm_youtube8m.tar.gz) |
+| NeXtVLAD | 160 | 4卡P40 | 7.1 | 0.87 | [model](https://paddlemodels.bj.bcebos.com/video_classification/nextvlad_youtube8m.tar.gz) |
+
+- 基于Kinetics数据集模型：
+
+| 模型 | Batch Size | 环境配置 | cuDNN版本 | Top-1 | 下载链接 |
+| :-------: | :---: | :---------: | :----: | :----: | :----------: |
+| StNet | 128 | 8卡P40 | 5.1 | 0.69 | [model](https://paddlemodels.bj.bcebos.com/video_classification/stnet_kinetics.tar.gz) |
+| TSN | 256 | 8卡P40 | 7.1 | 0.67 | [model](https://paddlemodels.bj.bcebos.com/video_classification/tsn_kinetics.tar.gz) |
+
+## 版本更新
+
+- 3/2019: 新增模型库，发布Attention Cluster，Attention LSTM，NeXtVLAD，StNet，TSN五个视频分类模型。
+

fluid/PaddleCV/video/dataset/README.md

+# 数据使用说明
+
+- [Youtube-8M](#Youtube-8M数据集)
+- [Kinetics](#Kinetics数据集)
+
+## Youtube-8M数据集
+这里用到的是YouTube-8M 2018年更新之后的数据集。使用官方数据集，并将TFRecord文件转化为pickle文件以便PaddlePaddle使用。Youtube-8M数据集官方提供了frame-level和video-level的特征，这里只需使用到frame-level的特征。
+
+### 数据下载
+请使用Youtube-8M官方链接分别下载[训练集](http://us.data.yt8m.org/2/frame/train/index.html)和[验证集](http://us.data.yt8m.org/2/frame/validate/index.html)。每个链接里各提供了3844个文件的下载地址，用户也可以使用官方提供的[下载脚本](https://research.google.com/youtube8m/download.html)下载数据。数据下载完成后，将会得到3844个训练数据文件和3844个验证数据文件（TFRecord格式）。
+假设存放视频模型代码库的主目录为: Code\_Root，进入dataset/youtube8m目录
+
+    cd dataset/youtube8m
+
+在youtube8m下新建目录tf/train和tf/val
+
+    mkdir tf && cd tf
+
+    mkdir train && mkdir val
+
+并分别将下载的train和validate数据存放在其中。
+
+### 数据格式转化
+
+为了适用于PaddlePaddle训练，需要离线将下载好的TFRecord文件格式转成了pickle格式，转换脚本请使用[dataset/youtube8m/tf2pkl.py](./youtube8m/tf2pkl.py)。
+
+在dataset/youtube8m 目录下新建目录pkl/train和pkl/val
+
+    cd dataset/youtube8m
+
+    mkdir pkl && cd pkl
+
+    mkdir train && mkdir val
+
+
+转化文件格式(TFRecord -> pkl)，进入dataset/youtube8m目录，运行脚本
+
+    python tf2pkl.py ./tf/train ./pkl/train
+
+和
+
+    python tf2pkl.py ./tf/val ./pkl/val
+
+分别将train和validate数据集转化为pkl文件。tf2pkl.py文件运行时需要两个参数，分别是数据源tf文件存放路径和转化后的pkl文件存放路径。
+
+备注：由于TFRecord文件的读取需要用到Tensorflow，用户要先安装Tensorflow，或者在安装有Tensorflow的环境中转化完数据，再拷贝到dataset/youtube8m/pkl目录下。为了避免和PaddlePaddle环境冲突，建议先在其他地方转化完成再将数据拷贝过来。
+
+### 生成文件列表
+
+进入dataset/youtube8m目录
+
+    ls $Code_Root/dataset/youtube8m/pkl/train/* > train.list
+
+    ls $Code_Root/dataset/youtube8m/pkl/val/* > val.list
+
+在dataset/youtube8m目录下将生成两个文件，train.list和val.list，每一行分别保存了一个pkl文件的绝对路径。
+
+## Kinetics数据集
+
+Kinetics数据集是DeepMind公开的大规模视频动作识别数据集，有Kinetics400与Kinetics600两个版本。这里使用Kinetics400数据集，具体的数据预处理过程如下。
+
+### mp4视频下载
+在Code\_Root目录下创建文件夹
+
+    cd $Code_Root/dataset && mkdir kinetics
+
+    cd kinetics && mkdir data_k400 && cd data_k400
+
+    mkdir train_mp4 && mkdir val_mp4
+
+ActivityNet官方提供了Kinetics的下载工具，具体参考其[官方repo ](https://github.com/activitynet/ActivityNet/tree/master/Crawler/Kinetics)即可下载Kinetics400的mp4视频集合。将kinetics400的训练与验证集合分别下载到dataset/kinetics/data\_k400/train\_mp4与dataset/kinetics/data\_k400/val\_mp4。
+
+### mp4文件预处理
+
+为提高数据读取速度，提前将mp4文件解帧并打pickle包，dataloader从视频的pkl文件中读取数据（该方法耗费更多存储空间）。pkl文件里打包的内容为(video-id,[frame1, frame2,...,frameN],label)。
+
+在 dataset/kinetics/data\_k400目录下创建目录train\_pkl和val\_pkl
+
+    cd $Code_Root/dataset/kinetics/data_k400
+
+    mkdir train_pkl && mkdir val_pkl
+
+进入$Code\_Root/dataset/kinetics目录，使用video2pkl.py脚本进行数据转化。首先需要下载[train](https://github.com/activitynet/ActivityNet/tree/master/Crawler/Kinetics/data/kinetics-400_train.csv)和[validation](https://github.com/activitynet/ActivityNet/tree/master/Crawler/Kinetics/data/kinetics-400_val.csv)数据集的文件列表。
+
+首先生成预处理需要的数据集标签文件
+
+    python generate_label.py kinetics-400_train.csv kinetics400_label.txt
+
+然后执行如下程序：
+
+    python video2pkl.py kinetics-400_train.csv $Source_dir $Target_dir  8 #以8个进程为例
+
+- 该脚本依赖`ffmpeg`库，请预先安装`ffmpeg`
+
+对于train数据，
+
+    Source_dir = $Code_Root/dataset/kinetics/data_k400/train_mp4
+
+    Target_dir = $Code_Root/dataset/kinetics/data_k400/train_pkl
+
+对于val数据，
+
+    Source_dir = $Code_Root/dataset/kinetics/data_k400/val_mp4
+
+    Target_dir = $Code_Root/dataset/kinetics/data_k400/val_pkl
+
+这样即可将mp4文件解码并保存为pkl文件。
+
+### 生成训练和验证集list
+
+    cd $Code_Root/dataset/kinetics
+
+    ls $Code_Root/dataset/kinetics/data_k400/train_pkl /* > train.list
+
+    ls $Code_Root/dataset/kinetics/data_k400/val_pkl /* > val.list
+
+
+即可生成相应的文件列表，train.list和val.list的每一行表示一个pkl文件的绝对路径。
+

fluid/PaddleCV/video/dataset/kinetics/README.md

-1. download kinetics-400_train.csv and kinetics-400_val.csv
-2. ffmpeg is required to decode mp4
-3. transfer mp4 video to pkl file, with each pkl stores [video_id, images, label]
-   python generate_label.py kinetics-400_train.csv kinetics400_label.txt # generate label file
-   python video2pkl.py kinetics-400_train.csv $Source_dir $Target_dir $NUM_THREADS

fluid/PaddleCV/video/dataset/youtube8m/README.md

-1. Tensorflow is required to process tfrecords
-2. python tf2pkl.py $Source_dir $Target_dir

fluid/PaddleCV/video/models/attention_cluster/README.md

+# Attention Cluster 视频分类模型
+
+---
+## 目录
+
+- [模型简介](#模型简介)
+- [数据准备](#数据准备)
+- [模型训练](#模型训练)
+- [模型评估](#模型评估)
+- [模型推断](#模型推断)
+- [参考论文](#参考论文)
+
+
+## 模型简介
+
+Attention Cluster模型为ActivityNet Kinetics Challenge 2017中最佳序列模型。该模型通过带Shifting Opeation的Attention Clusters处理已抽取好的RGB、Flow、Audio数据，Attention Cluster结构如下图所示。
+
+<p align="center">
+<img src="../../images/attention_cluster.png" height=300 width=400 hspace='10'/> <br />
+Multimodal Attention Cluster with Shifting Operation
+</p>
+
+详细内容请参考[Attention Clusters: Purely Attention Based Local Feature Integration for Video Classification](https://arxiv.org/abs/1711.09550)
+
+## 数据准备
+
+Attention Cluster模型使用2nd-Youtube-8M数据集, 数据下载及准备请参考[数据说明](../../dataset/README.md)
+
+## 模型训练
+
+数据准备完毕后，可以通过如下两种方式启动训练：
+
+    python train.py --model-name=AttentionCluster 
+            --config=./configs/attention_cluster.txt
+            --save-dir=checkpoints 
+            --log-interval=10 
+            --valid-interval=1
+
+    bash scripts/train/train_attention_cluster.sh
+
+- 可下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_cluster_youtube8m.tar.gz)通过`--resume`指定权重存放路径进行finetune等开发
+
+**数据读取器说明：** 模型读取Youtube-8M数据集中已抽取好的`rgb`和`audio`数据，对于每个视频的数据，均匀采样100帧，该值由配置文件中的`seg_num`参数指定。
+
+**模型设置：** 模型主要可配置参数为`cluster_nums`和`seg_num`参数，当配置`cluster_nums`为32, `seg_num`为100时，在Nvidia Tesla P40上单卡可跑`batch_size=256`。
+
+**训练策略：**
+
+*  采用Adam优化器，初始learning\_rate=0.001。
+*  训练过程中不使用权重衰减。
+*  参数主要使用MSRA初始化
+
+## 模型评估
+
+可通过如下两种方式进行模型评估:
+
+    python test.py --model-name=AttentionCluster 
+            --config=configs/attention_cluster.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS
+
+    bash scripts/test/test_attention_cluster.sh
+
+- 使用`scripts/test/test_attention_cluster.sh`进行评估时，需要修改脚本中的`--weights`参数指定需要评估的权重。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_cluster_youtube8m.tar.gz)进行评估
+
+当取如下参数时:
+
+| 参数 | 取值 |
+| :---------: | :----: |
+| cluster\_nums | 32 |
+| seg\_num | 100 |
+| batch\_size | 2048 |
+| nums\_gpu | 7 |
+
+在2nd-YouTube-8M数据集下评估精度如下:
+
+
+| 精度指标 | 模型精度 |
+| :---------: | :----: |
+| Hit@1 | 0.87 |
+| PERR | 0.78 |
+| GAP | 0.84 |
+
+## 模型推断
+
+可通过如下命令进行模型推断：
+
+    python infer.py --model-name=attention_cluster 
+            --config=configs/attention_cluster.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS 
+            --filelist=$FILELIST
+
+- 模型推断结果存储于`AttentionCluster_infer_result`中，通过`pickle`格式存储。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_cluster_youtube8m.tar.gz)进行推断
+
+## 参考论文
+
+- [Attention Clusters: Purely Attention Based Local Feature Integration for Video Classification](https://arxiv.org/abs/1711.09550), Xiang Long, Chuang Gan, Gerard de Melo, Jiajun Wu, Xiao Liu, Shilei Wen
+

fluid/PaddleCV/video/models/attention_lstm/README.md

+# AttentionLSTM视频分类模型
+
+---
+## 内容
+
+- [模型简介](#简介)
+- [数据准备](#数据准备)
+- [模型训练](#模型训练)
+- [模型评估](#模型评估)
+- [模型推断](#模型推断)
+- [参考论文](#参考论文)
+
+## 模型简介
+
+递归神经网络（RNN）常用于序列数据的处理，可建模视频连续多帧的时序信息，在视频分类领域为基础常用方法。该模型采用了双向长短记忆网络（LSTM），将视频的所有帧特征依次编码。与传统方法直接采用LSTM最后一个时刻的输出不同，该模型增加了一个Attention层，每个时刻的隐状态输出都有一个自适应权重，然后线性加权得到最终特征向量。论文中实现的是两层LSTM结构，而本代码实现的是带Attention的双向LSTM，Attention层可参考论文[AttentionCluster](https://arxiv.org/abs/1711.09550)。
+
+详细内容请参考[Beyond Short Snippets: Deep Networks for Video Classification](https://arxiv.org/abs/1503.08909)。
+
+## 数据准备
+
+AttentionLSTM模型使用2nd-Youtube-8M数据集，关于数据部分请参考[数据说明](../../dataset/README.md)
+
+## 模型训练
+
+### 随机初始化开始训练
+
+数据准备完毕后，可以通过如下两种方式启动训练：
+
+    python train.py --model-name=AttentionLSTM
+            --config=./configs/attention_lstm.txt
+            --save-dir=checkpoints 
+            --log-interval=10 
+            --valid-interval=1
+
+    bash scripts/train/train_attention_lstm.sh
+
+- AttentionLSTM模型使用8卡Nvidia Tesla P40来训练的，总的batch size数是1024。
+
+### 使用预训练模型做finetune
+请先将提供的[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_lstm_youtube8m.tar.gz)下载到本地，并在上述脚本文件中添加`--resume`为所保存的预模型存放路径。
+
+## 模型评估
+可通过如下两种方式进行模型评估:
+
+    python test.py --model-name=AttentionLSTM
+            --config=configs/attention_lstm.txt
+            --log-interval=1
+            --weights=$PATH_TO_WEIGHTS
+
+    bash scripts/test/test_attention_lstm.sh
+
+- 使用`scripts/test/test_attention_LSTM.sh`进行评估时，需要修改脚本中的`--weights`参数指定需要评估的权重。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_lstm_youtube8m.tar.gz)进行评估
+
+模型参数列表如下：
+
+| 参数 | 取值 |
+| :---------: | :----: |
+| embedding\_size | 512 |
+| lstm\_size | 1024 |
+| drop\_rate | 0.5 |
+
+
+计算指标列表如下：
+
+| 精度指标 | 模型精度 |
+| :---------: | :----: |
+| Hit@1 | 0.8885 |
+| PERR | 0.8012 |
+| GAP | 0.8594 |
+
+
+## 模型推断
+
+可通过如下命令进行模型推断：
+
+    python infer.py --model-name=attention_lstm
+            --config=configs/attention_lstm.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS 
+            --filelist=$FILELIST
+
+- 模型推断结果存储于`AttentionLSTM_infer_result`中，通过`pickle`格式存储。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/attention_lstm_youtube8m.tar.gz)进行推断
+
+## 参考论文
+
+- [Beyond Short Snippets: Deep Networks for Video Classification](https://arxiv.org/abs/1503.08909) Joe Yue-Hei Ng, Matthew Hausknecht, Sudheendra Vijayanarasimhan, Oriol Vinyals, Rajat Monga, George Toderici
+
+- [Attention Clusters: Purely Attention Based Local Feature Integration for Video Classification](https://arxiv.org/abs/1711.09550), Xiang Long, Chuang Gan, Gerard de Melo, Jiajun Wu, Xiao Liu, Shilei Wen
+

fluid/PaddleCV/video/models/nextvlad/README.md

+# NeXtVLAD视频分类模型
+
+---
+## 目录
+
+- [算法介绍](#模型简介)
+- [数据准备](#数据准备)
+- [模型训练](#模型训练)
+- [模型评估](#模型评估)
+- [模型推断](#模型推断)
+- [参考论文](#参考论文)
+
+
+## 算法介绍
+NeXtVLAD模型是第二届Youtube-8M视频理解竞赛中效果最好的单模型，在参数量小于80M的情况下，能得到高于0.87的GAP指标。该模型提供了一种将桢级别的视频特征转化并压缩成特征向量，以适用于大尺寸视频文件的分类的方法。其基本出发点是在NetVLAD模型的基础上，将高维度的特征先进行分组，通过引入attention机制聚合提取时间维度的信息，这样既可以获得较高的准确率，又可以使用更少的参数量。详细内容请参考[NeXtVLAD: An Efficient Neural Network to Aggregate Frame-level Features for Large-scale Video Classification](https://arxiv.org/abs/1811.05014)。
+
+这里实现了论文中的单模型结构，使用2nd-Youtube-8M的train数据集作为训练集，在val数据集上做测试。
+
+## 数据准备
+
+NeXtVLAD模型使用2nd-Youtube-8M数据集, 数据下载及准备请参考[数据说明](../../dataset/README.md)
+
+## 模型训练
+
+### 随机初始化开始训练
+在video目录下运行如下脚本即可
+
+    bash ./scripts/train/train_nextvlad.sh
+
+### 使用预训练模型做finetune
+
+请先将提供的预训练模型[model](https://paddlemodels.bj.bcebos.com/video_classification/nextvlad_youtube8m.tar.gz)下载到本地，并在上述脚本文件中添加--resume为所保存的预模型存放路径。
+
+使用4卡Nvidia Tesla P40，总的batch size数是160。
+
+### 训练策略
+
+*  使用Adam优化器，初始learning\_rate=0.0002
+*  每2,000,000个样本做一次学习率衰减，learning\_rate\_decay = 0.8
+*  正则化使用l2\_weight\_decay = 1e-5
+
+## 模型评估
+
+用户可以下载的预训练模型参数，或者使用自己训练好的模型参数，请在./scripts/test/test\_nextvald.sh
+文件中修改--weights参数为保存模型参数的目录。运行
+
+    bash ./scripts/test/test_nextvlad.sh
+
+由于youtube-8m提供的数据中test数据集是没有ground truth标签的，所以这里使用validation数据集来做测试。
+
+模型参数列表如下：
+
+| 参数 | 取值 |
+| :---------: | :----: |
+| cluster\_size | 128 |
+| hidden\_size | 2048 |
+| groups | 8 |
+| expansion | 2 |
+| drop\_rate | 0.5 |
+| gating\_reduction | 8 |
+
+计算指标列表如下：
+
+| 精度指标 | 模型精度 |
+| :---------: | :----: |
+| Hit@1 | 0.8960 |
+| PERR | 0.8132 |
+| GAP | 0.8709 |
+
+## 模型推断
+
+用户可以下载的预训练模型参数，或者使用自己训练好的模型参数，请在./scripts/infer/infer\_nextvald.sh
+文件中修改--weights参数为保存模型参数的目录，运行如下脚本
+
+    bash ./scripts/infer/infer_nextvald.sh
+
+推断结果会保存在NEXTVLAD\_infer\_result文件中，通过pickle格式存储。
+
+## 参考论文
+
+- [NeXtVLAD: An Efficient Neural Network to Aggregate Frame-level Features for Large-scale Video Classification](https://arxiv.org/abs/1811.05014), Rongcheng Lin, Jing Xiao, Jianping Fan
+

fluid/PaddleCV/video/models/stnet/README.md

+# StNet 视频分类模型
+
+---
+## 目录
+
+- [模型简介](#模型简介)
+- [数据准备](#数据准备)
+- [模型训练](#模型训练)
+- [模型评估](#模型评估)
+- [模型推断](#模型推断)
+- [参考论文](#参考论文)
+
+
+## 模型简介
+
+StNet模型框架为ActivityNet Kinetics Challenge 2018中夺冠的基础网络框架，本次开源的是基于ResNet50实现的StNet模型，基于其他backbone网络的框架用户可以依样配置。该模型提出“super-image"的概念，在super-image上进行2D卷积，建模视频中局部时空相关性。另外通过temporal modeling block建模视频的全局时空依赖，最后用一个temporal Xception block对抽取的特征序列进行长时序建模。StNet主体网络结构如下图所示：
+
+<p align="center">
+<img src="../../images/StNet.png" height=300 width=500 hspace='10'/> <br />
+StNet Framework Overview
+</p>
+
+详细内容请参考AAAI'2019年论文[StNet:Local and Global Spatial-Temporal Modeling for Human Action Recognition](https://arxiv.org/abs/1811.01549)
+
+## 数据准备
+
+StNet的训练数据采用由DeepMind公布的Kinetics-400动作识别数据集。数据下载及准备请参考[数据说明](../../dataset/README.md)
+
+## 模型训练
+
+数据准备完毕后，可以通过如下两种方式启动训练：
+
+    python train.py --model-name=STNET
+            --config=./configs/stnet.txt
+            --save-dir=checkpoints 
+            --log-interval=10 
+            --valid-interval=1
+
+    bash scripts/train/train_stnet.sh
+
+- 可下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/stnet_kinetics.tar.gz)通过`--resume`指定权重存放路径进行finetune等开发
+
+**数据读取器说明：** 模型读取Kinetics-400数据集中的`mp4`数据，每条数据抽取`seg_num`段，每段抽取`seg_len`帧图像，对每帧图像做随机增强后，缩放至`target_size`。
+
+**训练策略：**
+
+*  采用Momentum优化算法训练，momentum=0.9
+*  权重衰减系数为1e-4
+*  学习率在训练的总epoch数的1/3和2/3时分别做0.1的衰减
+
+**备注：**
+
+* 在训练StNet模型时使用PaddlePaddle Fluid 1.3 + cudnn5.1。使用cudnn7.0以上版本时batchnorm计算moving mean和moving average会出现异常，此问题还在修复中。建议用户安装PaddlePaddle时指定cudnn版本,
+
+     pip install paddlepaddle\_gpu==1.3.0.post85
+
+或者在PaddlePaddle的whl包[下载页面](http://paddlepaddle.org/documentation/docs/zh/1.3/beginners_guide/install/Tables.html/#permalink-4--whl-release)选择下载cuda8.0\_cudnn5\_avx\_mkl对应的whl包安装。
+关于安装PaddlePaddle的详细操作请参考[安装文档](http://www.paddlepaddle.org/documentation/docs/zh/1.3/beginners_guide/install/index_cn.html)。
+
+
+## 模型评估
+
+可通过如下两种方式进行模型评估:
+
+    python test.py --model-name=STNET
+            --config=configs/stnet.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS
+
+    bash scripts/test/test__stnet.sh
+
+- 使用`scripts/test/test_stnet.sh`进行评估时，需要修改脚本中的`--weights`参数指定需要评估的权重。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/stnet_kinetics.tar.gz)进行评估
+
+当取如下参数时:
+
+| 参数 | 取值 |
+| :---------: | :----: |
+| seg\_num | 25 |
+| seglen | 5 |
+| target\_size | 256 |
+
+在Kinetics400的validation数据集下评估精度如下:
+
+| 精度指标 | 模型精度 |
+| :---------: | :----: |
+| TOP\_1 | 0.69 |
+
+
+## 模型推断
+
+可通过如下命令进行模型推断：
+
+    python infer.py --model-name=stnet
+            --config=configs/stnet.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS 
+            --filelist=$FILELIST
+
+- 模型推断结果存储于`STNET_infer_result`中，通过`pickle`格式存储。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/stnet_kinetics.tar.gz)进行推断
+
+
+## 参考论文
+
+[StNet:Local and Global Spatial-Temporal Modeling for Human Action Recognition](https://arxiv.org/abs/1811.01549), Dongliang He, Zhichao Zhou, Chuang Gan, Fu Li, Xiao Liu, Yandong Li, Limin Wang, Shilei Wen
+

fluid/PaddleCV/video/models/tsn/README.md

+# TSN 视频分类模型
+
+---
+## 内容
+
+- [模型简介](#模型简介)
+- [数据准备](#数据准备)
+- [模型训练](#模型训练)
+- [模型评估](#模型评估)
+- [模型推断](#模型推断)
+- [参考论文](#参考论文)
+
+
+## 模型简介
+
+Temporal Segment Network (TSN) 是视频分类领域经典的基于2D-CNN的解决方案。该方法主要解决视频的长时间行为判断问题，通过稀疏采样视频帧的方式代替稠密采样，既能捕获视频全局信息，也能去除冗余，降低计算量。最终将每帧特征平均融合后得到视频的整体特征，并用于分类。本代码实现的模型为基于单路RGB图像的TSN网络结构，Backbone采用ResNet-50结构。
+
+详细内容请参考ECCV 2016年论文[StNet:Local and Global Spatial-Temporal Modeling for Human Action Recognition](https://arxiv.org/abs/1608.00859)
+
+## 数据准备
+
+TSN的训练数据采用由DeepMind公布的Kinetics-400动作识别数据集。数据下载及准备请参考[数据说明](../../dataset/README.md)
+
+## 模型训练
+
+数据准备完毕后，可以通过如下两种方式启动训练：
+
+    python train.py --model-name=TSN
+            --config=./configs/tsn.txt
+            --save-dir=checkpoints 
+            --log-interval=10 
+            --valid-interval=1
+
+    bash scripts/train/train_tsn.sh
+
+- 可下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/tsn_kinetics.tar.gz)通过`--resume`指定权重存放路径进行finetune等开发
+
+**数据读取器说明：** 模型读取Kinetics-400数据集中的`mp4`数据，每条数据抽取`seg_num`段，每段抽取1帧图像，对每帧图像做随机增强后，缩放至`target_size`。
+
+**训练策略：**
+
+*  采用Momentum优化算法训练，momentum=0.9
+*  权重衰减系数为1e-4
+*  学习率在训练的总epoch数的1/3和2/3时分别做0.1的衰减
+
+## 模型评估
+
+可通过如下两种方式进行模型评估:
+
+    python test.py --model-name=TSN
+            --config=configs/tsn.txt
+            --log-interval=1
+            --weights=$PATH_TO_WEIGHTS
+
+    bash scripts/test/test_tsn.sh
+
+- 使用`scripts/test/test_tsn.sh`进行评估时，需要修改脚本中的`--weights`参数指定需要评估的权重。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/tsn_kinetics.tar.gz)进行评估
+
+当取如下参数时，在Kinetics400的validation数据集下评估精度如下:
+
+| seg\_num | target\_size | Top-1 |
+| :------: | :----------: | :----: |
+| 3 | 224 | 0.66 |
+| 7 | 224 | 0.67 |
+
+## 模型推断
+
+可通过如下命令进行模型推断：
+
+    python infer.py --model-name=TSN
+            --config=configs/tsn.txt
+            --log-interval=1 
+            --weights=$PATH_TO_WEIGHTS 
+            --filelist=$FILELIST
+
+- 模型推断结果存储于`TSN_infer_result`中，通过`pickle`格式存储。
+
+- 若未指定`--weights`参数，脚本会下载已发布模型[model](https://paddlemodels.bj.bcebos.com/video_classification/tsn_kinetics.tar.gz)进行推断
+
+## 参考论文
+
+- [StNet:Local and Global Spatial-Temporal Modeling for Human Action Recognition](https://arxiv.org/abs/1608.00859), Limin Wang, Yuanjun Xiong, Zhe Wang, Yu Qiao, Dahua Lin, Xiaoou Tang, Luc Van Gool
+