Skip to content

F
FluidDoc

PaddlePaddle / FluidDoc

通知 10
Star 2
Fork 0
F
FluidDoc
未验证 提交 2be25c70 编写于 作者: L lujun 提交者： GitHub
浏览文件
操作

Merge pull request #3 from PaddlePaddle/develop 

merge to local
上级 3524ea61 997c89cd
展开全部 显示空白变更内容
内联 并排
Showing with 14089 addition and 13369 deletion
README.md
浏览文件 @ 2be25c70
# Introduction # Introduction
Fluiddoc consolidates all the documentations related to Paddle. It supplies the contents to PaddlePaddle.org via CI. FluidDoc consolidates all the documentations related to Paddle. It supplies the contents to PaddlePaddle.org via CI.
FluidDoc包含了所有PaddlePaddle相关的文档，它通过CI系统为PaddlePaddle.org提供文档内容
# Architecture # Architecture
FluidDoc submodules Paddle, Book, Models, Mobile and Anakin under `external` folder. All submodules should be put under `external` as standard practice. FluidDoc submodules Paddle, Book, Models, Mobile and Anakin under `external` folder. All submodules should be put under `external` as standard practice.
Fluiddoc then uses them as references to load up the documents. The FluidDoc constructs the whole doc-tree under the `FluidDoc/doc/fluid` folder. The entry point is `FluidDoc/doc/fluid/index_cn.rst` and `FluidDoc/doc/fluid/index_en.rst` FluidDoc将Paddle, Book, Models, Mobile and Anakin作为子模块，并放置在 `external` 目录下。按照标准做法，所有的子模块应当置于`external` 目录下
FluidDoc then uses them as references to load up the documents. The FluidDoc constructs the whole doc-tree under the `FluidDoc/doc/fluid` folder. The entry point is `FluidDoc/doc/fluid/index_cn.rst` and `FluidDoc/doc/fluid/index_en.rst`
FluidDoc通过引用这些子模块来加载这些Repo中的文档。FluidDoc在 `FluidDoc/doc/fluid` 目录下构建了文档的整体树形结构。可以分别在 `FluidDoc/doc/fluid/index_cn.rst` 和 `FluidDoc/doc/fluid/index_en.rst` 查看。
When a release branch is pushed to Github, Travis-CI will start automatically to compile documents and deploy documents to the server. When a release branch is pushed to Github, Travis-CI will start automatically to compile documents and deploy documents to the server.
当一个新发布的分支被push到了Github上，Travis-CI 将会自动启动编译文档并把文档部署到服务器
## Note: ## Note:
FluidDoc needs Paddle python module to compile API documents. Unfortunately, compiling Paddle python module takes longer time Travis CI permits. Usually Travis CI will fail due because of timeout. That's why there three jobs on Travis, two of them are to build libraries. Once the libraries are cached on the Travis, next build will be a lot faster. FluidDoc needs Paddle python module to compile API documents. Unfortunately, compiling Paddle python module takes longer time Travis CI permits. Usually Travis CI will fail due because of timeout. That's why there three jobs on Travis, two of them are to build libraries. Once the libraries are cached on the Travis, next build will be a lot faster.
## 注意：
FluidDoc 需要Paddle Repo的python模块去编译生成API文档。但由于Paddle的python模块过于庞大，超过了Travis CI允许的最大时长，通常Travis CI将会因为超时问题失败。这是Travis上有三项作业的原因，其中两项用于构建库。当Travis缓存了这些库以后，下一次的构建将会变得非常的快。
## Preview with PPO ## Preview with PPO
To preview documents constructured by FluidDoc. Please follow the [regular preview step](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md), but replace the path to paddle with the path to FluidDoc To preview documents constructured by FluidDoc. Please follow the [regular preview step](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md), but replace the path to paddle with the path to FluidDoc
`./runserver --paddle <path_to_FluidDoc_dir>` `./runserver --paddle <path_to_FluidDoc_dir>`
## 通过PaddlePaddle.org预览文档
为了预览FluidDoc的文档，请按照[常规预览步骤](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md)，但请在这一步将 paddle 的路径替换为 Fluid 的路径
`./runserver --paddle <path_to_FluidDoc_dir>`
# Publish New release # Publish New release
1. Checkout a new release branch. The branch name should follow `release/<version>` 1. Checkout a new release branch. The branch name should follow `release/<version>`
1. Update the documentations on the submodules or within FluidDoc 1. Update the documentations on the submodules or within FluidDoc
1. Make sure all the submodules are ready for release. Paddle, book, model, mobile and Anakin should all have stable commits. Note: Paddle repo should update the API RST files accordinly if Paddle changes the included module/classes. 1. Make sure all the submodules are ready for release. Paddle, book, model, mobile and Anakin should all have stable commits. Note: Paddle repo should update the API RST files accordinly if Paddle changes the included module/classes.
1. Update the submodules under `external` folder and commit the changes. 1. Update the submodules under `external` folder and commit the changes.
1. Git push the branch to Github, Travis CI will start several builds to publish the documents to the PaddlePaddle.org server 1. Git push the branch to Github, Travis CI will start several builds to publish the documents to the PaddlePaddle.org server
1. Please notify the PaddlePaddle.org team that the release content is ready. PaddlePaddl.org team should enable the version and update the default version to the latest one. PaddlePaddle.org should also update the search index accordingly (Until the search server is up) 1. Please notify the PaddlePaddle.org team that the release content is ready. PaddlePaddle.org team should enable the version and update the default version to the latest one. PaddlePaddle.org should also update the search index accordingly (Until the search server is up)
## 发布新的分支
1. 创建一个新的分支，此分支的名字应遵循`release/<version>`
1. 在FluidDoc和子模块中更新文档
1. 确认所有的子模块中处于发布就绪的状态。Paddle, book, model, mobile and Anakin 应全部有稳定的commit
请注意：如果Paddle Repo更改了module/classes，涉及API文档的RST文件应当也被更新
1. 在 `external` 中更新文件然后commit文档变更
1. 将这个分支push到Github，Travis CI将会启动几项构建工作以把文档发布到PaddlePaddle.org的服务器
1. 请告知PaddlePaddle.org团队，发布的内容已经就绪。PaddlePaddle.org团队将使版本生效并更新默认的版本到最新版。PaddlePaddle.org也应当更新相应的搜索引擎文件
doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst
浏览文件 @ 2be25c70
...@@ -71,7 +71,6 @@ WITH_MKL ON/OFF ...@@ -71,7 +71,6 @@ WITH_MKL ON/OFF
│   │   ├── paddle_analysis_config.h │   │   ├── paddle_analysis_config.h
│   │   ├── paddle_api.h │   │   ├── paddle_api.h
│   │   ├── paddle_inference_api.h │   │   ├── paddle_inference_api.h
│   │   ├── paddle_inference_pass.h
│   │   └── paddle_pass_builder.h │   │   └── paddle_pass_builder.h
│   └── lib │   └── lib
│   ├── libpaddle_fluid.a │   ├── libpaddle_fluid.a
......
doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md
浏览文件 @ 2be25c70
...@@ -26,14 +26,16 @@ NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习 ...@@ -26,14 +26,16 @@ NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习
cd /Paddle cd /Paddle
mkdir build mkdir build
cd build cd build
# TENSORRT_ROOT为TRT的路径，默认为 /usr，根据自己需求进行改动
# MKL 可以根据自己的需求自行打开
cmake .. \ cmake .. \
-DWITH_FLUID_ONLY=ON \ -DWITH_FLUID_ONLY=ON \
-DWITH_CONTRIB=OFF \
-DWITH_MKL=OFF \ -DWITH_MKL=OFF \
-DWITH_MKLDNN=OFF \ -DWITH_MKLDNN=OFF \
-DWITH_TESTING=ON \
-DCMAKE_BUILD_TYPE=Release \ -DCMAKE_BUILD_TYPE=Release \
-DWITH_PYTHON=OFF -DWITH_PYTHON=OFF \
-DTENSORRT_ROOT=/usr \
-DON_INFER=ON
# 编译 # 编译
make -j make -j
...@@ -41,6 +43,22 @@ NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习 ...@@ -41,6 +43,22 @@ NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习
make inference_lib_dist -j make inference_lib_dist -j
``` ```
编译后的库的目录如下：
```
fluid_inference_install_dir
├── paddle
│
├── CMakeCache.txt
├── version.txt
├── third_party
├── boost
├── install
└── engine3
```
`fluid_inference_install_dir`下， paddle目录包含了预测库的头文件和预测库的lib， version.txt 中包含了lib的版本和配置信息，third_party 中包含了预测库依赖的第三方库
## Paddle TensorRT使用 ## Paddle TensorRT使用
[`paddle_inference_api.h`]('https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/inference/api/paddle_inference_api.h') 定义了使用TensorRT的所有接口。 [`paddle_inference_api.h`]('https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/inference/api/paddle_inference_api.h') 定义了使用TensorRT的所有接口。
...@@ -97,11 +115,52 @@ void RunTensorRT(int batch_size, std::string model_dirname) { ...@@ -97,11 +115,52 @@ void RunTensorRT(int batch_size, std::string model_dirname) {
int main() { int main() {
// 模型下载地址 http://paddle-inference-dist.cdn.bcebos.com/tensorrt_test/mobilenet.tar.gz // 模型下载地址 http://paddle-inference-dist.cdn.bcebos.com/tensorrt_test/mobilenet.tar.gz
paddle::RunTensorRT(1, “./mobilenet"); paddle::RunTensorRT(1, "./mobilenet");
return 0; return 0;
} }
``` ```
编译过程可以参照[这里](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/fluid/inference/api/demo_ci)。
## 样例编译
1. 下载样例
```
wget http://paddle-inference-dist.cdn.bcebos.com/tensorrt_test/paddle_trt_samples.tar.gz
```
解压后的目录如下：
```
sample
├── CMakeLists.txt
├── mobilenet_test.cc
├── thread_mobilenet_test.cc
├── mobilenetv1
│ ├── model
│ └── params
└── run_impl.sh
```
- `mobilenet_test.cc` 为单线程的程序文件
- `thread_mobilenet_test.cc` 为多线程的程序文件
- `mobilenetv1` 为模型文件
在这里假设预测库的路径为 ``BASE_DIR/fluid_inference_install_dir/`` ，样例所在的目录为 ``SAMPLE_BASE_DIR/sample``
2. 编译样例
```shell
cd SAMPLE_BASE_DIR/sample
# sh run_impl.sh {预测库的地址} {测试脚本的名字} {模型目录}
sh run_impl.sh BASE_DIR/fluid_inference_install_dir/ mobilenet_test SAMPLE_BASE_DIR/sample/mobilenetv1
```
3. 编译多线程的样例
```shell
cd SAMPLE_BASE_DIR/sample
# sh run_impl.sh {预测库的地址} {测试脚本的名字} {模型目录}
sh run_impl.sh BASE_DIR/fluid_inference_install_dir/ thread_mobilenet_test SAMPLE_BASE_DIR/sample/mobilenetv1
```
## 子图运行原理 ## 子图运行原理
PaddlePaddle采用子图的形式对TensorRT进行集成，当模型加载后，神经网络可以表示为由变量和运算节点组成的计算图。Paddle TensorRT实现的功能是能够对整个图进行扫描，发现图中可以使用TensorRT优化的子图，并使用TensorRT节点替换它们。在模型的推断期间，如果遇到TensorRT节点，Paddle会调用TensoRT库对该节点进行优化，其他的节点调用Paddle的原生实现。TensorRT在推断期间能够进行Op的横向和纵向融合，过滤掉冗余的Op，并对特定平台下的特定的Op选择合适的kenel等进行优化，能够加快模型的预测速度。 PaddlePaddle采用子图的形式对TensorRT进行集成，当模型加载后，神经网络可以表示为由变量和运算节点组成的计算图。Paddle TensorRT实现的功能是能够对整个图进行扫描，发现图中可以使用TensorRT优化的子图，并使用TensorRT节点替换它们。在模型的推断期间，如果遇到TensorRT节点，Paddle会调用TensoRT库对该节点进行优化，其他的节点调用Paddle的原生实现。TensorRT在推断期间能够进行Op的横向和纵向融合，过滤掉冗余的Op，并对特定平台下的特定的Op选择合适的kenel等进行优化，能够加快模型的预测速度。
......
doc/fluid/advanced_usage/development/local_dev_guide.md 0 → 100644
浏览文件 @ 2be25c70
# Guide of local development
You will learn how to develop programs in local environment under the guidelines of this document.
## Requirements of coding
- Please refer to the coding comment format of [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
- Make sure that option of builder `WITH_STYLE_CHECK` is on and the build could pass through the code style check.
- Unit test is needed for all codes.
- Pass through all unit tests.
- Please follow [regulations of submitting codes](#regulations of submitting codes).
The following guidiance tells you how to submit code.
## [Fork](https://help.github.com/articles/fork-a-repo/)
Transfer to the home page of Github [PaddlePaddle](https://github.com/PaddlePaddle/Paddle) ,and then click button `Fork` to generate the git under your own file directory,such as <https://github.com/USERNAME/Paddle>。
## Clone
Clone remote git to local:
```bash
➜ git clone https://github.com/USERNAME/Paddle
➜ cd Paddle
```
## Create local branch
At present [Git stream branch model](http://nvie.com/posts/a-successful-git-branching-model/) is applied to Paddle to undergo task of development,test,release and maintenance.Please refer to [branch regulation of Paddle](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/design/releasing_process.md#paddle-分支规范) about details。
All development tasks of feature and bug fix should be finished in a new branch which is extended from `develop` branch.
Create and switch to a new branch with command `git checkout -b`.
```bash
➜ git checkout -b my-cool-stuff
```
It is worth noting that before the checkout, you need to keep the current branch directory clean, otherwise the untracked file will be brought to the new branch, which can be viewed by `git status` .
## Use `pre-commit` hook
Paddle developers use the [pre-commit](http://pre-commit.com/) tool to manage Git pre-commit hooks. It helps us format the source code (C++, Python) and automatically check some basic things before committing (such as having only one EOL per file, not adding large files in Git, etc.).
The `pre-commit` test is part of the unit test in Travis-CI. A PR that does not satisfy the hook cannot be submitted to Paddle. Install `pre-commit` first and then run it in current directory：
```bash
➜ pip install pre-commit
➜ pre-commit install
```
Paddle modify the format of C/C++ source code with `clang-format` .Make sure the version of `clang-format` is above 3.8.
Note：There are differences between the installation of `yapf` with `pip install pre-commit` and that with `conda install -c conda-forge pre-commit` . Paddle developers use `pip install pre-commit` 。
## Start development
I delete a line of README.md and create a new file in the case.
View the current state via `git status` , which will prompt some changes to the current directory, and you can also view the file's specific changes via `git diff` .
```bash
➜ git status
On branch test
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: README.md
Untracked files:
(use "git add <file>..." to include in what will be committed)
test
no changes added to commit (use "git add" and/or "git commit -a")
```
## Build and test
It needs a variety of development tools to build PaddlePaddle source code and generate documentation. For convenience, our standard development procedure is to put these tools together into a Docker image,called *development mirror* , usually named as `paddle:latest-dev` or `paddle:[version tag]-dev`,such as `paddle:0.11.0-dev` . Then all that need `cmake && make` ,such as IDE configuration,are replaced by `docker run paddle:latest-dev` .
You need to bulid this development mirror under the root directory of source code directory tree
```bash
➜ docker build -t paddle:latest-dev .
```
Then you can start building PaddlePaddle source code with this development mirror.For example,to build a Paddleddle which are not dependent on GPU but in support of AVX commands and including unit test,you can:
```bash
➜ docker run -v $(pwd):/paddle -e "WITH_GPU=OFF" -e "WITH_AVX=ON" -e "WITH_TESTING=ON" paddle:latest-dev
```
If you want to build PaddlePaddle based on Python3,you can:
```bash
➜ docker run -v $(pwd):/paddle -e "PY_VERSION=3.5" -e "WITH_FLUID_ONLY=ON" -e "WITH_GPU=OFF" -e "WITH_AVX=ON" -e "WITH_TESTING=ON" paddle:latest-dev
```
Except for the build of PaddlePaddle as `./build/libpaddle.so` and the output of `./build/paddle.deb` file, there is an output of `build/Dockerfile`. What we need to do is to package the PaddlePaddle as a *produce mirror*（ `paddle:prod` ）with following commands.
```bash
➜ docker build -t paddle:prod -f build/Dockerfile .
```
Run all unit tests with following commands:
```bash
➜ docker run -it -v $(pwd):/paddle paddle:latest-dev bash -c "cd /paddle/build && ctest"
```
Please refer to [Installation and run with Docker](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/v2/build_and_install/docker_install_cn.rst) about more information of construction and test.
## Commit
Next we cancel the modification of README.md,and submit new added test file.
```bash
➜ git checkout -- README.md
➜ git status
On branch test
Untracked files:
(use "git add <file>..." to include in what will be committed)
test
nothing added to commit but untracked files present (use "git add" to track)
➜ git add test
```
It's required that the commit message is also given on every Git commit, through which other developers will be notified of what changes have been made. Type `git commit` to realize it.
```bash
➜ git commit
CRLF end-lines remover...............................(no files to check)Skipped
yapf.................................................(no files to check)Skipped
Check for added large files..............................................Passed
Check for merge conflicts................................................Passed
Check for broken symlinks................................................Passed
Detect Private Key...................................(no files to check)Skipped
Fix End of Files.....................................(no files to check)Skipped
clang-formater.......................................(no files to check)Skipped
[my-cool-stuff c703c041] add test file
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 233
```
<b> <font color="red">Attention needs to be paid：you need to add commit message to trigger CI test.The command is as follows:</font> </b>
```bash
# Touch CI single test of develop branch
➜ git commit -m "test=develop"
# Touch CI single test of release/1.1 branch
➜ git commit -m "test=release/1.1"
```
## Keep the latest local repository
It needs to keep up with the latest code of original repository(<https://github.com/PaddlePaddle/Paddle>）before Pull Request.
Check the name of current remote repository with `git remote`.
```bash
➜ git remote
origin
➜ git remote -v
origin https://github.com/USERNAME/Paddle (fetch)
origin https://github.com/USERNAME/Paddle (push)
```
origin is the name of remote repository that we clone,which is also the Paddle under your own account. Next we create a remote host of an original Paddle and name it upstream.
```bash
➜ git remote add upstream https://github.com/PaddlePaddle/Paddle
➜ git remote
origin
upstream
```
Get the latest code of upstream and update current branch.
```bash
➜ git fetch upstream
➜ git pull upstream develop
```
## Push to remote repository
Push local modification to GitHub(https://github.com/USERNAME/Paddle).
```bash
# submit it to remote git the branch my-cool-stuff of origin
➜ git push origin my-cool-stuff
```
doc/fluid/advanced_usage/development/submit_pr_guide.md 0 → 100644
浏览文件 @ 2be25c70
# Guide of submitting PR to Github
## Create an Issue and finish Pull Request
Create an Issue to describe your problem and keep its number.
Switch to the branch you have created and click `New pull request`。
<img width="295" alt="screen shot 2017-04-26 at 9 09 28 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436054/a6d98c66-2ac4-11e7-9cb1-18dd13150230.png">
Switch to targeted branch:
<img width="750" alt="screen shot 2017-04-26 at 9 11 52 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436139/f83b1e6c-2ac4-11e7-8c0e-add499023c46.png">
A note of `resolve #Issue number` in PR description results in automatic close of corresponding Issue after the merge of PR.More details can be viewed [here](https://help.github.com/articles/closing-issues-via-commit-messages/)。
Then please wait for review.If there is any need to make a modification,you can update corresponding branch in origin following the steps above.
## Sign CLA and pass unit tests
### Sign CLA
For the first time to submit Pull Request,you need to sign CLA(Contributor License Agreement) to ensure merge of your code.Specific steps are listed as follows:
- Please check the Check in PR to find license/cla and click detail on the right to change into CLA website.
<div align="center">
<img src="https://github.com/PaddlePaddle/FluidDoc/blob/release/1.1/doc/fluid/advanced_usage/development/contribute_to_paddle/img/cla_unsigned.png?raw=true" height="330" width="400">
</div>
- Please click “Sign in with GitHub to agree” in CLA website.It will change into your Pull Request page after the click.
<div align="center">
<img src="https://github.com/PaddlePaddle/FluidDoc/blob/release/1.1/doc/fluid/advanced_usage/development/contribute_to_paddle/img/sign_cla.png?raw=true" height="330" width="400">
</div>
### Pass unit tests
Every new commit in your Pull Request will trigger CI unit tests,so please make sure that necessary comments have been included in your commit message.Please refer to [commit](local_dev_guide.html#permalink-8--commit-)
Please note the procedure of CI unit tests in your Pull Request which will be finished in several hours.
You only need to focus on CI projects associated with your submitted branch.For example,there is no need to check whether release/1.1 pass test or not if you submit code to develop branch.
Green ticks after all tests means that your commit has passed all unit tests.
Red cross after the tests means your commit hasn't passed certain unit test.Please click detail to view bug details and make a screenshot of bug,then add it as a comment in your Pull Request.Our stuff will help you check it.
## Delete remote branch
We can delete branches of remote repository in PR page after your PR is successfully merged into master repository.
<img width="775" alt="screen shot 2017-04-26 at 9 18 24 pm" src="https://cloud.githubusercontent.com/assets/11692045/25436457/e4cdd472-2ac5-11e7-9272-badc76c4a23e.png">
We can also delete the branch of remote repository with `git push origin :the_branch_name`,such as:
```bash
➜ git push origin :my-cool-stuff
```
## Delete local branch
Finally,we delete local branch
```bash
# Switch to develop branch
➜ git checkout develop
# delete my-cool-stuff branch
➜ git branch -D my-cool-stuff
```
And now we finish a full process of code contribution
## Certain regulations about submitting code
In order that reviewers focus on code in the code review,please follow these rules every time you submit your code:
1）Make sure that unit tests in Travis-CI pass through successfully.If it fails,it means problems have been found in submitted code which will not be reviewed by reviewer.
2）Before the submit of PUll Request:
- Please note the number of commit:
Reason：It will bother reviewers a lot if a dozen of commits are submitted after modification of only one file and only a few modifications are updated in every commit.Reviewers have to check commit one by one to figure out the modification.And sometimes it needs to take the overlap among commits into consideration.
Suggestion：Keep commit concise as much as possible at every submit.You can make a supplyment to the previous commit with `git commit --amend`.About several commits having been pushed to remote repository,you can refer to [squash commits after push](http://stackoverflow.com/questions/5667884/how-to-squash-commits-in-git-after-they-have-been-pushed)。
- Pay attention to the name of every commit:It would be better to abstract the content of present commit and be not too arbitrary.
3）If you have tackled with problems of an Issue,please add `fix #issue_number` to the *first* comment area of PULL Request.Then the corresponding Issue will be closed automatically after the merge of PULL Request.Keywords are including:close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.Please select appropriate word.Please refer to [Closing issues via commit messages](https://help.github.com/articles/closing-issues-via-commit-messages) for more details.
In addition,please follow the following regulations in response to the suggestion of reviewers:
1）A reply to every comment of reviewers（It's a fundamental complimentary conduct in open source community.An expression of appreciation is a need for help from others):
- If you adopt the suggestion of reviewer and make a modification accordingly, it's courteous to reply with a simple `Done` .
- Please clarify your reason to the disagreenment
2）If there are many suggestions
- Please show general modification
- Please follow [start a review](https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/) to give your reply,instead of directly replying for that every comment will result in sending an email causing email disaster.
doc/fluid/api/api_guides/high_low_level_api.md 已删除 100644 → 0
浏览文件 @ 3524ea61
## High/Low-level API简介
PaddlePaddle Fluid目前有2套API接口：
- Low-level（底层） API：
- 灵活性强并且已经相对成熟，使用它训练的模型，能直接支持C++预测上线。
- 提供了大量的模型作为使用示例，包括[Book](https://github.com/PaddlePaddle/book)中的全部章节，以及[models](https://github.com/PaddlePaddle/models)中的所有章节。
- 适用人群：对深度学习有一定了解，需要自定义网络进行训练/预测/上线部署的用户。
- High-level（高层）API：
- 使用简单
- 尚未成熟，接口暂时在[paddle.fluid.contrib](https://github.com/PaddlePaddle/Paddle/tree/develop/python/paddle/fluid/contrib)下面。
- 适用人群：想通过Book课程进行深度学习基础知识学习的初级用户。
doc/fluid/api/api_guides/index.rst 已删除 100755 → 0
浏览文件 @ 3524ea61
===========
API使用指南
===========
.. toctree::
:titlesonly:
high_low_level_api.md
low_level/layers/index.rst
low_level/executor.rst
low_level/optimizer.rst
low_level/metrics.rst
low_level/model_save_reader.rst
low_level/inference.rst
low_level/distributed/index.rst
doc/fluid/api/api_guides/low_level/cluster/cluster_train_data_cn.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_cluster_train_data:
####################
分布式训练reader准备
####################
一个数据并行的分布式训练任务通常会含有多个训练进程，每个训练进程处理整个数据集中的一部分，根据当前进程的唯一序号(trainer_id)以及训练进程总数(trainers)可以决定当前训练进程应该读取哪一部分数据。
实现 cluster_reader 来读取分布式训练数据集
----------------------------------------
比较通用的方法，可以实现一个 cluster_reader, 根据训练进程数量以及进程序号决定读取哪些 example:
.. code-block:: python
def cluster_reader(reader, trainers, trainer_id):
def reader_creator():
for idx, data in enumerate(reader()):
if idx % trainers == trainer_id:
yield data
return reader
trainers = int(os.getenv("PADDLE_TRAINERS", "1"))
trainer_id = int(os.getenv("PADDLE_TRAINER_ID", "0"))
train_reader = cluster_reader(paddle.dataset.mnist.train(), trainers, trainer_id)
上述代码中，`trainers` 和 `trainer_id` 分别是训练进程总数和当前训练进程的序号，可以通过环境变量或者参数的方式传递给 Python 程序。
预先切分训练文件
-----------------
由于使用 `cluster_reader` 依然会读取全量数据，对于训练进程比较多的任务，会造成IO资源的浪费、影响训练性能。另一种方法是可以将训练数据切分成多个小文件，每个进程处理其中的一部分文件,
例如在 Linux 系统中可以使用 `split <http://man7.org/linux/man-pages/man1/split.1.html>`_ 命令将训练数据切分成多个小文件：
.. code-block:: bash
$ split -d -a 4 -d -l 100 housing.data cluster/housing.data.
$ find ./cluster
cluster/
cluster/housing.data.0002
cluster/housing.data.0003
cluster/housing.data.0004
cluster/housing.data.0000
cluster/housing.data.0001
cluster/housing.data.0005
数据切分好以后, 可以实现一个 file_dispatcher 函数，根据训练进程数量以及序号决定需要读取哪些文件：
.. code-block:: python
def file_dispatcher(files_pattern, trainers, trainer_id):
file_list = glob.glob(files_pattern)
ret_list = []
for idx, f in enumerate(file_list):
if (idx + trainers) % trainers == trainer_id:
ret_list.append(f)
return ret_list
trainers = int(os.getenv("PADDLE_TRAINERS", "1"))
trainer_id = int(os.getenv("PADDLE_TRAINER_ID", "0"))
files_pattern = "cluster/housing.data.*"
my_files = file_dispatcher(files_pattern, triners, trainer_id)
在上述例子中，`files_pattern` 是训练文件的 `glob 表达式 <https://docs.python.org/2.7/library/glob.html>`_，一般可以用通配符来表示。
doc/fluid/api/api_guides/low_level/distributed/async_training.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_async_training:
############
分布式异步训练
############
Fluid支持数据并行的分布式异步训练，API使用 :code:`DistributedTranspiler` 将单机网络配置转换成可以多机执行的
:code:`pserver` 端程序和 :code:`trainer` 端程序。用户在不同的节点执行相同的一段代码，根据环境变量或启动参数，
可以执行对应的 :code:`pserver` 或 :code:`trainer` 角色。Fluid异步训练只支持pserver模式，异步训练和 `同步训练 <../distributed/sync_training.html>`_ 的主要差异在于：异步训练每个trainer的梯度是单独更新到参数上的，
而同步训练是所有trainer的梯度合并之后统一更新到参数上，因此，同步训练和异步训练的超参数需要分别调节。
pserver模式分布式异步训练
======================
API详细使用方法参考 :ref: `api_fluid_DistributeTranspiler` ，简单示例用法：
.. code-block:: python
config = fluid.DistributedTranspilerConfig()
# 配置策略config
config.slice_var_up = False
t = fluid.DistributedTranspiler(config=config)
t.transpile(trainer_id,
program=main_program,
pservers="192.168.0.1:6174,192.168.0.2:6174",
trainers=1,
sync_mode=False)
以上参数说明请参考`同步训练 <../distributed/sync_training.html>`_
需要注意的是：进行异步训练时，请修改 :code:`sync_mode` 的值
- :code:`sync_mode` ： 是否是同步训练模式，默认为True，不传此参数也默认是同步训练模式，设置为False则为异步训练
doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_cpu_training_best_practice:
##################
分布式CPU训练最佳实践
##################
提高CPU分布式训练的训练速度，主要要从两个方面来考虑：
1）提高训练速度，主要是提高CPU的使用率；2）提高通信速度，主要是减少通信传输的数据量。
提高CPU的使用率
=============
提高CPU使用率主要依赖 :code:`ParallelExecutor`，可以充分利用多个CPU的计算能力来加速计算。
API详细使用方法参考 :ref:`api_fluid_ParallelExecutor` ，简单实例用法：
.. code-block:: python
# 配置执行策略，主要是设置线程数
exec_strategy = fluid.ExecutionStrategy()
exec_strategy.num_threads = 8
# 配置构图策略，对于CPU训练而言，应该使用Reduce模式进行训练
build_strategy = fluid.BuildStrategy()
if int(os.getenv("CPU_NUM")) > 1:
build_strategy.reduce_strategy = fluid.BuildStrategy.ReduceStrategy.Reduce
pe = fluid.ParallelExecutor(
use_cuda=False,
loss_name=avg_cost.name,
main_program=main_program,
build_strategy=build_strategy,
exec_strategy=exec_strategy)
以上参数中：
- :code:`num_threads` ： 模型训练使用的线程数，最好和训练所在机器的物理CPU核数接近
- :code:`reduce_strategy` ： 对于CPU训练而言，应该选择 fluid.BuildStrategy.ReduceStrategy.Reduce
通用环境变量配置：
- :code:`CPU_NUM` ：模型副本replica的个数，最好和num_threads一致
提高通信速度
==========
要减少通信数据量，提高通信速度，主要是使用稀疏更新 ，目前支持 `稀疏更新 <../distributed/sparse_update.html>`_ 的主要是 :ref:`api_fluid_layers_embedding` 。
.. code-block:: python
data = fluid.layers.data(name='ids', shape=[1], dtype='int64')
fc = fluid.layers.embedding(input=data, size=[dict_size, 16], is_sparse=True)
以上参数中：
- :code:`is_sparse` ： 配置embedding使用稀疏更新，如果embedding的dict_size很大，而每次数据data很少，建议使用sparse更新方式。
doc/fluid/api/api_guides/low_level/distributed/index.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
=============
分布式训练
=============
.. toctree::
:maxdepth: 1
async_training.rst
cpu_train_best_practice.rst
large_scale_sparse_feature_training.rst
doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_large_scale_sparse_feature_training:
###################
大规模稀疏特征模型训练
###################
模型配置和训练
=============
embedding被广泛应用在各种网络结构中，尤其是文本处理相关的模型。在某些场景，例如推荐系统或者搜索引擎中，
embedding的feature id可能会非常多，当feature id达到一定数量时，embedding参数会变得很大，
会带来两个问题：
1）单机内存由于无法存放如此巨大的embedding参数，导致无法训练；
2）普通的训练模式每一轮迭代都需要同步完整的参数，参数太大会让通信变得非常慢，进而影响训练速度。
Fluid支持千亿量级超大规模稀疏特征embedding的训练，embedding参数只会保存在parameter server上，通过
参数prefetch和梯度稀疏更新的方法，大大减少通信量，提高通信速度。
该功能只对分布式训练有效，单机无法使用。
需要配合 `稀疏更新 <../distributed/sparse_update.html>`_ 一起使用。
使用方法：在配置embedding的时候，加上参数 :code:`is_distributed=True` 以及 :code:`is_sparse=True` 即可。
参数 :code:`dict_size` 定义数据中总的id的数量，id可以是int64范围内的任意值，只要总id个数小于等于dict_size就可以支持。
所以配置之前需要预估一下数据中总的feature id的数量。
.. code-block:: python
emb = fluid.layers.embedding(
is_distributed=True,
input=input,
size=[dict_size, embedding_width],
is_sparse=True,
is_distributed=True)
模型存储和预测
=============
当特征数量达到千亿的时候，参数量很大，单机已经无法存下，所以模型的存储和加载都和普通模式不同：
1）普通模式下，参数是在trainer端保存和加载的；
2）分布式模式下，参数的保存和加载，都是在pserver端进行，每个pserver只保存和加载该pserver自身对应部分的参数
doc/fluid/api/api_guides/low_level/distributed/sync_training.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_sync_training:
############
分布式同步训练
############
Fluid支持数据并行的分布式同步训练，API使用 :code:`DistributedTranspiler` 将单机网络配置转换成可以多机执行的
:code:`pserver` 端程序和 :code:`trainer` 端程序。用户在不同的节点执行相同的一段代码，根据环境变量或启动参数，
可以执行对应的 :code:`pserver` 或 :code:`trainer` 角色。Fluid分布式同步训练同时支持pserver模式和NCCL2模式，
在API使用上有差别，需要注意。
pserver模式分布式训练
===================
API详细使用方法参考 :ref:`DistributeTranspiler` ，简单实例用法：
.. code-block:: python
config = fluid.DistributedTranspilerConfig()
# 配置策略config
config.slice_var_up = False
t = fluid.DistributedTranspiler(config=config)
t.transpile(trainer_id,
program=main_program,
pservers="192.168.0.1:6174,192.168.0.2:6174",
trainers=1,
sync_mode=True)
以上参数中：
- :code:`trainer_id` ： trainer节点的id，从0到n-1，n为当前训练任务中trainer节点的个数
- :code:`program` ： 被转换的 :code:`program` 默认使用 :code:`fluid.default_main_program()`
- :code:`pservers` ： 当前训练任务中pserver节点的IP端口列表
- :code:`trainers` ： int类型，当前训练任务中trainer节点的个数。注意：
* pserver模式下，trainer节点个数可以和pserver节点个数不一致，比如使用20个pserver和50个trainer。在实际训练任务中，您可以通过调整pserver节点和trainer节点个数找到最佳性能
* NCCL2模式中，此项参数是字符串，指定trainer节点的IP端口列表
- :code:`sync_mode` ： 是否是同步训练模式，默认为True，不传此参数也默认是同步训练模式
其中，支持的config包括：
- :code:`slice_var_up` ： 配置是否切分一个参数到多个pserver上进行优化，默认开启。此选项适用于模型参数个数少，但需要使用大量节点的场景，有利于提升pserver端计算并行度
- :code:`split_method` ： 配置transpiler分配参数（或参数的切片）到多个pserver的方式，默认为"RoundRobin"，也可以使用"HashName"
- :code:`min_block_size` ： 如果配置了参数切分，指定最小Tensor的切分大小，防止RPC请求包过小，默认为8192，一般情况不需要调整此项参数
- :code:`enable_dc_asgd` ： 是否开启 :code:`DC-ASGD` 此选项在异步训练中生效，启用异步训练补偿算法
- :code:`mode` : 可以选择"pserver"或"nccl2"，指定使用pserver模式或NCCL2模式分布式训练
- :code:`print_log` ： 是否开启transpiler debug日志，此项为开发调试使用
通用环境变量配置：
- :code:`FLAGS_rpc_send_thread_num` ：int，指定RPC通信发送时线程的个数
- :code:`FLAGS_rpc_get_thread_num` ： int，指定RPC通信接受时线程的个数
- :code:`FLAGS_rpc_prefetch_thread_num` ： int，分布式lookup table执行RPC通信时，prefetch线程的个数
- :code:`FLAGS_rpc_deadline` ： int，RPC通信最长等待时间，单位为毫秒，默认180000
NCCL2模式分布式训练
=================
基于NCCL2 (Collective Communication) 的多机同步训练模式，仅支持在GPU集群下进行。
此部分详细API说明可以参考 :ref:`DistributeTranspiler` 。
注意：NCCL2模式下，集群不需要启动pserver，只需要启动多个trainer节点即可。
使用以下代码，将当前 :code:`Program` 转化成适用于NCCL2分布式计算的Fluid :code:`Program` ：
.. code-block:: python
config = fluid.DistributeTranspilerConfig()
config.mode = "nccl2"
t = fluid.DistributedTranspiler(config=config)
t.transpile(trainer_id,
program=main_program,
startup_program=startup_program,
trainers="192.168.0.1:6174,192.168.0.2:6174",
current_endpoint="192.168.0.1:6174")
其中：
- :code:`trainer_id` : trainer节点的id，从0到n-1，n为当前训练任务中trainer节点的个数
- :code:`program` 和 :code:`startup_program` : 分别为Fluid 模型的主配置program和初始化startup_program
- :code:`trainers` : 字符串类型，指定当前任务所有trainer的IP和端口号，仅用于NCCL2初始化（pserver模式中，此参数为int，指定trainer节点的个数）
- :code:`current_endpoint` : 当前任务的当前节点的IP和端口号
doc/fluid/api/api_guides/low_level/executor.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_executor:
##########
执行引擎
##########
:code:`Executor` 即 :code:`执行器` 。PaddlePaddle Fluid中有两种执行器可以选择。
:code:`Executor` 实现了一个简易的执行器，所有Operator会被顺序执行。用户可以使用
Python脚本驱动 :code:`Executor` 执行。默认情况下 :code:`Executor` 是单线程的，如果
想使用数据并行，请参考另一个执行器， :ref:`api_guide_parallel_executor` 。
:code:`Executor` 的代码逻辑非常简单。建议用户在调试过程中，先使用
:code:`Executor` 跑通模型，再切换到多设备计算，甚至多机计算。
:code:`Executor` 在构造的时候接受一个 :code:`Place`， 它们可以是 :ref:`api_fluid_CPUPlace`
或 :ref:`api_fluid_CUDAPlace` 。 :code:`Executor` 在执行的时候可以选择执行的
:ref:`api_guide_low_level_program` 。
简单的使用方法，请参考 `quick_start_fit_a_line <http://paddlepaddle.org/documentation/docs/zh/1.1/beginners_guide/quick_start/fit_a_line/README.cn.html>`_ , API Reference 请参考
:ref:`api_fluid_Executor` 。
doc/fluid/api/api_guides/low_level/inference.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_inference:
#########
预测引擎
#########
预测引擎提供了存储预测模型 :ref:`api_fluid_io_save_inference_model` 和加载预测模型 :ref:`api_fluid_io_load_inference_model` 两个接口。
预测模型的存储格式
=================
预测模型的存储格式有两种，由上述两个接口中的 :code:`model_filename` 和 :code:`params_filename` 变量控制：
- 参数保存到各个独立的文件，如设置 :code:`model_filename` 为 :code:`None` 、:code:`params_filename` 为 :code:`None`
.. code-block:: bash
ls recognize_digits_conv.inference.model/*
__model__ conv2d_1.w_0 conv2d_2.w_0 fc_1.w_0 conv2d_1.b_0 conv2d_2.b_0 fc_1.b_0
- 参数保存到同一个文件，如设置 :code:`model_filename` 为 :code:`None` 、:code:`params_filename` 为 :code:`__params__`
.. code-block:: bash
ls recognize_digits_conv.inference.model/*
__model__ __params__
存储预测模型
===========
.. code-block:: python
exe = fluid.Executor(fluid.CPUPlace())
path = "./infer_model"
fluid.io.save_inference_model(dirname=path, feeded_var_names=['img'],
target_vars=[predict_var], executor=exe)
在这个示例中，:code:`fluid.io.save_inference_model` 接口对默认的 :code:`fluid.Program` 进行裁剪，只保留预测 :code:`predict_var` 所需部分。
裁剪后的 :code:`program` 会保存在 :code:`./infer_model/__model__` 下，参数会保存到 :code:`./infer_model` 下的各个独立文件。
加载预测模型
===========
.. code-block:: python
exe = fluid.Executor(fluid.CPUPlace())
path = "./infer_model"
[inference_program, feed_target_names, fetch_targets] =
fluid.io.load_inference_model(dirname=path, executor=exe)
results = exe.run(inference_program,
feed={feed_target_names[0]: tensor_img},
fetch_list=fetch_targets)
在这个示例中，首先调用 :code:`fluid.io.load_inference_model` 接口，获得预测的 :code:`program` 、输入数据的 :code:`variable` 名称和输出结果的 :code:`variable` ;
然后调用 :code:`executor` 执行预测的 :code:`program` 获得预测结果。
doc/fluid/api/api_guides/low_level/layers/activations.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_activations:
####
激活函数
####
激活函数将非线性的特性引入到神经网络当中。
PaddlePaddle Fluid 对大部分的激活函数进行了支持，其中有:
:ref:`api_fluid_layers_relu`, :ref:`api_fluid_layers_tanh`, :ref:`api_fluid_layers_sigmoid`, :ref:`api_fluid_layers_elu`, :ref:`api_fluid_layers_relu6`, :ref:`api_fluid_layers_pow`, :ref:`api_fluid_layers_stanh`, :ref:`api_fluid_layers_hard_sigmoid`, :ref:`api_fluid_layers_swish`, :ref:`api_fluid_layers_prelu`, :ref:`api_fluid_layers_brelu`, :ref:`api_fluid_layers_leaky_relu`, :ref:`api_fluid_layers_soft_relu`, :ref:`api_fluid_layers_thresholded_relu`, :ref:`api_fluid_layers_maxout`, :ref:`api_fluid_layers_logsigmoid`, :ref:`api_fluid_layers_hard_shrink`, :ref:`api_fluid_layers_softsign`, :ref:`api_fluid_layers_softplus`, :ref:`api_fluid_layers_tanh_shrink`, :ref:`api_fluid_layers_softshrink`, :ref:`api_fluid_layers_exp`。
**Fluid提供了两种使用激活函数的方式：**
- 如果一个层的接口提供了 :code:`act` 变量（默认值为None），我们可以通过该变量指定该层的激活函数类型。该方式支持常见的激活函数: :code:`relu`, :code:`tanh`, :code:`sigmoid`, :code:`identity`。
.. code-block:: python
conv2d = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3, act="relu")
- Fluid为每个Activation提供了接口，我们可以显式的对它们进行调用。
.. code-block:: python
conv2d = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3)
relu1 = fluid.layers.relu(conv2d)
doc/fluid/api/api_guides/low_level/layers/control_flow.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. api_guide_control_flow:
######
控制流
######
在程序语言中，控制流(control flow)决定了语句的执行顺序，常见的控制流包括顺序执行、分支和循环等。PaddlePaddle Fluid继承了这一概念，提供了多种控制流API, 以控制深度学习模型在训练或者预测过程中的执行逻辑。
IfElse
======
条件分支，允许对同一个batch的输入，根据给定的条件，分别选择 :code:`true_block` 或 :code:`false_block` 中的逻辑进行执行，执行完成之后再将两个分支的输出合并为同一个输出。通常，条件表达式可由 :ref:`api_fluid_layers_less_than`, :ref:`api_fluid_layers_equal` 等逻辑比较 API 产生。
请参考 :ref:`api_fluid_layers_IfElse`
Switch
======
多分支选择结构，如同程序语言中常见的 :code:`switch-case` 声明, 其根据输入表达式的取值不同，选择不同的分支执行。具体来说，Fluid 所定义的 :code:`Switch` 控制流有如下特性：
* case的条件是个bool类型的值，即在Program中是一个张量类型的Variable；
* 依次检查逐个case，选择第一个满足条件的case执行，完成执行后即退出所属的block；
* 如果所有case均不满足条件，会选择默认的case进行执行。
请参考 :ref:`api_fluid_layers_Switch`
While
=====
While 循环，当条件判断为真时，循环执行 :code:`While` 控制流所属 :code:`block` 内的逻辑，条件判断为假时退出循环。与之相关的API有
* :ref:`api_fluid_layers_increment` ：累加API，通常用于对循环次数进行计数；
* :ref:`api_fluid_layers_array_read` ：从 :code:`LOD_TENSOR_ARRAY` 中指定的位置读入Variable，进行计算；
* :ref:`api_fluid_layers_array_write` ：将 Variable 写回到 :code:`LOD_TENSOR_ARRAY` 指定的位置，存储计算结果。
请参考 :ref:`api_fluid_layers_While`
DynamicRNN
==========
即动态RNN，可处理一个batch不等长的序列数据，其接受 :code:`lod_level=1` 的 Variable 作为输入，在 :code:`DynamicRNN` 的 :code:`block` 内，用户需自定义RNN的单步计算逻辑。在每一个时间步，用户可将需记忆的状态写入到 :code:`DynamicRNN` 的 :code:`memory` 中，并将需要的输出写出到其 :code:`output` 中。
:ref:`api_fluid_layers_sequence_last_step` 可获取 :code:`DynamicRNN` 最后一个时间步的输出。
请参考 :ref:`api_fluid_layers_DynamicRNN`
StaticRNN
=========
即静态RNN，只能处理固定长度的序列数据，接受 :code:`lod_level=0` 的 Variable 作为输入。与 :code:`DynamicRNN` 类似，在RNN的每单个时间步，用户需自定义计算逻辑，并可将状态和输出写出。
请参考 :ref:`api_fluid_layers_StaticRNN`
doc/fluid/api/api_guides/low_level/layers/conv.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_conv:
#####
卷积
#####
卷积有两组输入：特征图和卷积核，依据输入特征和卷积核的形状、Layout不同、计算方式的不同，在Fluid里，有针对变长序列特征的一维卷积，有针对定长图像特征的二维(2D Conv)、三维卷积(3D Conv)，同时也有卷积计算的逆向过程，下面先介绍Fluid里的2D/3D卷积，再来介绍序列卷积。
2D/3D卷积
==============
1. 卷积输入参数：
---------------------
卷积需要依据滑动步长(stride)、填充长度(padding)、卷积核窗口大小(filter size)、分组数(groups)、扩张系数(dilation rate)来决定如何计算。groups最早在 `AlexNet <https://www.nvidia.cn/content/tesla/pdf/machine-learning/imagenet-classification-with-deep-convolutional-nn.pdf>`_ 中引入, 可以理解为将原始的卷积分为独立若干组卷积计算。
**注意**: 同cuDNN的方式，Fluid目前只支持在特征图上下填充相同的长度，左右也是。
- 输入输出Layout:
2D卷积输入特征的Layout为[N, C, H, W]或[N, H, W, C], N即batch size，C是通道数，H、W是特征的高度和宽度，输出特征和输入特征的Layout一致。(相应的3D卷积输入特征的Layout为[N, C, D, H, W]或[N, D, H, W, C]，但**注意**，Fluid的卷积当前只支持[N, C, H, W]，[N, C, D, H, W]。)
- 卷积核的Layout:
Fluid中2D卷积的卷积核(也称权重)的Layout为[C_o, C_in / groups, f_h, f_w]，C_o、C_in表示输出、输入通道数，f_h、f_w表示卷积核窗口的高度和宽度，按行序存储。(相应的2D卷积的卷积核Layout为[C_o, C_in / groups, f_d, f_h, d_w]，同样按行序存储。)
- 深度可分离卷积(depthwise separable convolution):
在深度可分离卷积中包括depthwise convolution和pointwise convolution两组，这两个卷积的接口和上述普通卷积接口相同。前者可以通过给普通卷积设置groups来做，后者通过设置卷积核filters的大小为1x1，深度可分离卷积减少参数的同时减少了计算量。
对于depthwise convolution，可以设置groups等于输入通道数，此时，2D卷积的卷积核形状为[C_o, 1, f_h, f_w]。
对于pointwise convolution，卷积核的形状为[C_o, C_in, 1, 1]。
**注意**：Fluid针对depthwise convolution的GPU计算做了高度优化，您可以通过在 :code:`fluid.layers.conv2d`接口设置 :code:`use_cudnn=False`来使用Fluid自身优化的CUDA程序。
- 空洞卷积(dilated convolution):
空洞卷积相比普通卷积而言，卷积核在特征图上取值时不在连续，而是间隔的，这个间隔数称作dilation，等于1时，即为普通卷积，空洞卷积相比普通卷积的感受野更大。
- API汇总:
- :ref:`api_fluid_layers_conv2d`
- :ref:`api_fluid_layers_conv3d`
- :ref:`api_fluid_layers_conv2d_transpose`
- :ref:`api_fluid_layers_conv3d_transpose`
1D序列卷积
==============
Fluid可以表示变长的序列结构，这里的变长是指不同样本的时间步(step)数不一样，通常是一个2D的Tensor和一个能够区分的样本长度的辅助结构来表示。假定，2D的Tensor的形状是shape，shape[0]是所有样本的总时间步数，shape[1]是序列特征的大小。
基于此数据结构的卷积在Fluid里称作序列卷积，也表示一维卷积。同图像卷积，序列卷积的输入参数有卷积核大小、填充大小、滑动步长，但与2D卷积不同的是，这些参数个数都为1。**注意**，目前仅支持stride为1的情况，输出序列的时间步数和输入序列相同。
假如：输入序列形状为(T, N)， T即该序列的时间步数，N是序列特征大小；卷积核的上下文步长为K，输出序列长度为M，则卷积核权重形状为(K * N, M），输出序列形状为(T, M)。
另外，参考DeepSpeech，Fluid实现了行卷积row convolution, 或称
`look ahead convolution <http://www.cs.cmu.edu/~dyogatam/papers/wang+etal.iclrworkshop2016.pdf>`_ ，
该卷积相比上述普通序列卷积可以减少参数。
- API汇总:
- :ref:`api_fluid_layers_sequence_conv`
- :ref:`api_fluid_layers_row_conv`
doc/fluid/api/api_guides/low_level/layers/data_feeder.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_data_feeder:
使用DataFeeder传入训练/预测数据
###################################
Fluid提供 :code:`DataFeeder` 类，将numpy array等数据转换为 :code:`LoDTensor` 类型传入训练/预测网络。
用户创建 :code:`DataFeeder` 对象的方式为：
.. code-block:: python
import paddle.fluid as fluid
image = fluid.layers.data(name='image', shape=[-1, 3, 224, 224], dtype='float32')
label = fluid.layers.data(name='label', shape=[-1, 1], dtype='int64')
place = fluid.CUDAPlace(0) if fluid.core.is_compiled_with_cuda() else fluid.CPUPlace()
feeder = fluid.DataFeeder(feed_list=[image, label], place=place)
其中，:code:`feed_list` 参数为变量列表，这些变量由 :code:`fluid.layers.data()` 创建，
:code:`place` 参数表示应将Python端传入的numpy array等数据转换为GPU端或是CPU端的 :code:`LoDTensor` 。
创建 :code:`DataFeeder` 对象后，用户可调用其 :code:`feed(iterable)` 方法将用户传入的
:code:`iterable` 数据转换为 :code:`LoDTensor`。
:code:`iterable` 应为Python List或Tuple类型对象，且 :code:`iterable` 的每个元素均为长度为N的
Python List或Tuple类型对象，其中N为创建 :code:`DataFeeder` 对象时传入的 :code:`feed_list` 变量个数。
:code:`iterable` 的具体格式为：
.. code-block:: python
iterable = [
(image_1, label_1),
(image_2, label_2),
...
(image_n, label_n)
]
其中，:code:`image_i` 与 :code:`label_i` 均为numpy array类型数据。若传入数据的维度为[1]，如 :code:`label_i`,
则可传入Python int、float等类型数据。 :code:`image_i` 与 :code:`label_i` 的数据类型和维度不必
与 :code:`fluid.layers.data()` 创建时指定的 :code:`dtype` 和 :code:`shape` 完全一致，:code:`DataFeeder` 内部
会完成数据类型和维度的转换。若 :code:`feed_list` 中的变量的 :code:`lod_level` 不为零，则Fluid会将经过维度转换后的
:code:`iterable` 中每行数据的第0维作为返回结果的 :code:`LoD`。
具体使用方法请参见 :ref:`api_fluid_DataFeeder` 。
\ No newline at end of file
doc/fluid/api/api_guides/low_level/layers/data_in_out.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_data_in_out:
数据输入输出
###############
数据输入
-------------
Fluid支持两种数据输入方式，包括：
1. Python Reader: 纯Python的Reader。用户在Python端定义 :code:`fluid.layers.data` 层构建网络，并通过
:code:`executor.run(feed=...)` 的方式读入数据。数据读取和模型训练/预测的过程是同步进行的。
2. PyReader: 高效灵活的C++ Reader接口。PyReader内部维护容量为 :code:`capacity` 的队列（队列容量由
:code:`fluid.layers.py_reader` 接口中的 :code:`capacity` 参数设置），Python端调用队列的 :code:`push`
方法送入训练/预测数据，C++端的训练/预测程序调用队列的 :code:`pop` 方法取出Python端送入的数据。PyReader可与
:code:`double_buffer` 配合使用，实现数据读取和训练/预测的异步执行。
具体使用方法请参考 :ref:`api_fluid_layers_py_reader`。
数据输出
------------
Fluid支持在训练/预测阶段获取当前batch的数据。
用户可通过 :code:`executor.run(fetch_list=[...], return_numpy=...)` 的方式
fetch期望的输出变量，通过设置 :code:`return_numpy` 参数设置是否将输出数据转为numpy array。
若 :code:`return_numpy` 为 :code:`False` ，则返回 :code:`LoDTensor` 类型数据。
具体使用方式请参考相关API文档 :ref:`api_fluid_executor_Executor` 和
:ref:`api_fluid_ParallelExecutor`。
\ No newline at end of file
doc/fluid/api/api_guides/low_level/layers/detection.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_detection:
图像检测
#########
PaddlePaddle Fluid在图像检测任务中实现了多个特有的操作。以下分模型介绍各个api：
通用操作
-------------
图像检测中的一些通用操作，是对检测框的一系列操作，其中包括：
* 对检测框的编码，解码（box_coder）：实现两种框之间编码和解码的转换。例如训练阶段对先验框和真实框进行编码得到训练目标值。API Reference 请参考 :ref:`api_fluid_layers_box_coder`
* 比较两个检测框并进行匹配：
* iou_similarity：计算两组框的IOU值。API Reference 请参考 :ref:`api_fluid_layers_iou_similarity`
* bipartite_match：通过贪心二分匹配算法得到每一列中距离最大的一行。API Reference 请参考 :ref:`api_fluid_layers_bipartite_match`
* 根据检测框和标签得到分类和回归目标值（target_assign）：通过匹配索引和非匹配索引得到目标值和对应权重。API Reference 请参考 :ref:`api_fluid_layers_target_assign`
Faster RCNN
-------------
`Faster RCNN <https://arxiv.org/abs/1506.01497>`_ 是典型的两阶段目标检测器，相较于传统提取区域的方法，Faster RCNN中RPN网络通过共享卷积层参数大幅提高提取区域的效率，并提出高质量的候选区域。RPN网络需要对输入anchor和真实值进行比较生成初选候选框，并对初选候选框分配分类和回归值，>需要如下四个特有api：
* rpn_target_assign：通过anchor和真实框为anchor分配RPN网络的分类和回归目标值。API Reference 请参考 :ref:`api_fluid_layers_rpn_target_assign`
* anchor_generator：为每个位置生成一系列anchor。API Reference 请参考 :ref:`api_fluid_layers_anchor_generator`
* generate_proposal_labels: 通过generate_proposals得到的候选框和真实框得到RCNN部分的分类和回归的目标值。API Reference 请参考 :ref:`api_fluid_layers_generate_proposal_labels`
* generate_proposals: 对RPN网络输出box解码并筛选得到新的候选框。API Reference 请参考 :ref:`api_fluid_layers_generate_proposals`
SSD
----------------
`SSD <https://arxiv.org/abs/1512.02325>`_ 全称Single Shot MultiBox Detector，是目标检测领域较新且效果较好的检测算法之一，具有检测速度快且检测精度高的特点。与两阶段的检测方法不同，单阶段目标检测并不进行区域推荐，而是直接从特征图回归出目标的边界框和分类概率。SSD网络对六个尺度特>征图计算损失，进行预测，需要如下五种特有api：
* Prior Box：根据不同参数为每个输入位置生成一系列候选框。API Reference 请参考 :ref:`api_fluid_layers_prior_box`
* multi_box_head ：得到不同prior box的位置和置信度。API Reference 请参考 :ref:`api_fluid_layers_multi_box_head`
* detection_output：对prioir box解码，通过多分类NMS得到检测结果。API Reference 请参考 :ref:`api_fluid_layers_detection_output`
* ssd_loss：通过位置偏移预测值，置信度，检测框位置和真实框位置和标签计算损失。API Reference 请参考 :ref:`api_fluid_layers_ssd_loss`
* detection map: 利用mAP评估SSD网络模型。API Reference 请参考 :ref:`api_fluid_layers_detection_map`
OCR
---------
场景文字识别是在图像背景复杂、分辨率低下、字体多样、分布随意等情况下，将图像信息转化为文字序列的过程，可认为是一种特别的翻译过程：将图像输入翻译为自然语言输出。OCR任务中需要对检测框进行不规则变换，其中需要如下两个api：
* roi_perspective_transform：对输入roi做透视变换。API Reference 请参考 :ref:`api_fluid_layers_roi_perspective_transform`
* polygon_box_transform：对不规则检测框进行坐标变换。API Reference 请参考 :ref:`api_fluid_layers_polygon_box_transform`
doc/fluid/api/api_guides/low_level/layers/index.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
=============
神经网络层
=============
.. toctree::
:maxdepth: 1
conv.rst
pooling.rst
detection.rst
sequence.rst
math.rst
activations.rst
loss_function.rst
data_in_out.rst
control_flow.rst
sparse_update.rst
doc/fluid/api/api_guides/low_level/layers/learning_rate_scheduler.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_learning_rate_scheduler:
############
学习率调度器
############
当我们使用诸如梯度下降法等方式来训练模型时，一般会兼顾训练速度和损失(loss)来选择相对合适的学习率。但若在训练过程中一直使用一个学习率，训练集的损失下降到一定程度后便不再继续下降，而是在一定范围内震荡。其震荡原理如下图所示，即当损失函数收敛到局部极小值附近时，会由于学习率过大导致更新步幅过大，每步参数更新会反复越过极小值而出现震荡。
.. image:: ../../../../images/learning_rate_scheduler.png
:scale: 80 %
:align: center
学习率调度器定义了常用的学习率衰减策略来动态生成学习率，学习率衰减函数以epoch或step为参数，返回一个随训练逐渐减小的学习率，从而兼顾降低训练时间和在局部极小值能更好寻优两个方面。
下面介绍学习率调度器中相关的Api：
======
* :code:`noam_decay`: 诺姆衰减，相关算法请参考 `《Attention Is All You Need》 <https://arxiv.org/pdf/1706.03762.pdf>`_ 。
相关API Reference请参考 :ref:`api_fluid_layers_noam_decay`
* :code:`exponential_decay`: 指数衰减，即每次将当前学习率乘以给定的衰减率得到下一个学习率。
相关API Reference请参考 :ref:`api_fluid_layers_exponential_decay`
* :code:`natural_exp_decay`: 自然指数衰减，即每次将当前学习率乘以给定的衰减率的自然指数得到下一个学习率。
相关API Reference请参考 :ref:`api_fluid_layers_natural_exp_decay`
* :code:`inverse_time_decay`: 逆时间衰减，即得到的学习率与当前衰减次数成反比。
相关API Reference请参考 :ref:`api_fluid_layers_inverse_time_decay`
* :code:`polynomial_decay`: 多项式衰减，即得到的学习率为初始学习率和给定最终学习之间由多项式计算权重定比分点的插值。
相关API Reference请参考 :ref:`api_fluid_layers_polynomial_decay`
* :code:`piecewise_decay`: 分段衰减，即由给定step数分段呈阶梯状衰减，每段内学习率相同。
相关API Reference请参考 :ref:`api_fluid_layers_piecewise_decay`
* :code:`append_LARS`: 通过Layer-wise Adaptive Rate Scaling算法获得学习率，相关算法请参考 `《Train Feedfoward Neural Network with Layer-wise Adaptive Rate via Approximating Back-matching Propagation》 <https://arxiv.org/abs/1802.09750>`_ 。
相关API Reference请参考 :ref:`api_fluid_layers_append_LARS`
doc/fluid/api/api_guides/low_level/layers/loss_function.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_loss_function:
#######
损失函数
#######
损失函数定义了拟合结果和真实结果之间的差异，作为优化的目标直接关系模型训练的好坏，很多研究工作的内容也集中在损失函数的设计优化上。
Paddle Fluid 中提供了面向多种任务的多种类型的损失函数，以下列出了一些 Paddle Fluid 中包含的较为常用的损失函数。
回归
====
平方误差损失（squared error loss）使用预测值和真实值之间误差的平方作为样本损失，是回归问题中最为基本的损失函数。
API Reference 请参考 :ref:`api_fluid_layers_square_error_cost`。
平滑 L1 损失（smooth_l1 loss）是一种分段的损失函数，较平方误差损失其对异常点相对不敏感，因而更为鲁棒。
API Reference 请参考 :ref:`api_fluid_layers_smooth_l1`。
分类
====
`交叉熵（cross entropy） <https://en.wikipedia.org/wiki/Cross_entropy>`_ 是分类问题中使用最为广泛的损失函数，Paddle Fluid 中提供了接受归一化概率值和非归一化分值输入的两种交叉熵损失函数的接口，并支持 soft label 和 hard label 两种样本类别标签。
API Reference 请参考 :ref:`api_fluid_layers_cross_entropy` 和 :ref:`api_fluid_layers_softmax_with_cross_entropy`。
多标签分类
---------
对于多标签分类问题，如一篇文章同属于政治、科技等多个类别的情况，需要将各类别作为独立的二分类问题计算损失，Paddle Fluid 中为此提供了 sigmoid_cross_entropy_with_logits 损失函数，
API Reference 请参考 :ref:`api_fluid_layers_sigmoid_cross_entropy_with_logits`。
大规模分类
---------
对于大规模分类问题，通常需要特殊的方法及相应的损失函数以加速训练，常用的方法有 `噪声对比估计（Noise-contrastive estimation，NCE） <http://proceedings.mlr.press/v9/gutmann10a/gutmann10a.pdf>`_ 和 `层级 sigmoid <http://www.iro.umontreal.ca/~lisa/pointeurs/hierarchical-nnlm-aistats05.pdf>`_ 。
* 噪声对比估计通过将多分类问题转化为学习分类器来判别数据来自真实分布和噪声分布的二分类问题，基于二分类来进行极大似然估计，避免在全类别空间计算归一化因子从而降低了计算复杂度。
* 层级 sigmoid 通过二叉树进行层级的二分类来实现多分类，每个样本的损失对应了编码路径上各节点二分类交叉熵的和，避免了归一化因子的计算从而降低了计算复杂度。
这两种方法对应的损失函数在 Paddle Fluid 中均有提供，API Reference 请参考 :ref:`api_fluid_layers_nce` 和 :ref:`api_fluid_layers_hsigmoid`。
序列分类
-------
序列分类可以分为以下三种：
* 序列分类（Sequence Classification）问题，整个序列对应一个预测标签，如文本分类。这种即是普通的分类问题，可以使用 cross entropy 作为损失函数。
* 序列片段分类（Segment Classification）问题，序列中的各个片段对应有自己的类别标签，如命名实体识别。对于这种序列标注问题，`（线性链）条件随机场（Conditional Random Field，CRF） <http://www.cs.columbia.edu/~mcollins/fb.pdf>`_ 是一种常用的模型方法，其使用句子级别的似然概率，序列中不同位置的标签不再是条件独立，能够有效解决标记偏置问题。Paddle Fluid 中提供了 CRF 对应损失函数的支持，API Reference 请参考 :ref:`api_fluid_layers_linear_chain_crf`。
* 时序分类（Temporal Classification）问题，需要对未分割的序列进行标注，如语音识别。对于这种时序分类问题，`CTC（Connectionist Temporal Classification） <http://people.idsia.ch/~santiago/papers/icml2006.pdf>`_ 损失函数不需要对齐输入数据及标签，可以进行端到端的训练，Paddle Fluid 提供了 warpctc 的接口来计算相应的损失，API Reference 请参考 :ref:`api_fluid_layers_warpctc`。
排序
====
`排序问题 <https://en.wikipedia.org/wiki/Learning_to_rank>`_ 可以使用 Pointwise、Pairwise 和 Listwise 的学习方法，不同的方法需要使用不同的损失函数：
* Pointwise 的方法通过近似为回归问题解决排序问题，可以使用回归问题的损失函数。
* Pairwise 的方法需要特殊设计的损失函数，其通过近似为分类问题解决排序问题，使用两篇文档与 query 的相关性得分以偏序作为二分类标签来计算损失。Paddle Fluid 中提供了两种常用的 Pairwise 方法的损失函数，API Reference 请参考 :ref:`api_fluid_layers_rank_loss` 和 :ref:`api_fluid_layers_margin_rank_loss`。
更多
====
对于一些较为复杂的损失函数，可以尝试使用其他损失函数组合实现；Paddle Fluid 中提供的用于图像分割任务的 :ref:`api_fluid_layers_dice_loss` 即是使用其他 OP 组合（计算各像素位置似然概率的均值）而成；多目标损失函数也可看作这样的情况，如 Faster RCNN 就使用 cross entropy 和 smooth_l1 loss 的加权和作为损失函数。
**注意**，在定义损失函数之后为能够使用 :ref:`api_guide_optimizer` 进行优化，通常需要使用 :ref:`api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。
\ No newline at end of file
doc/fluid/api/api_guides/low_level/layers/math.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_math:
数学操作
#########
Paddle提供了丰富的数学操作，以下列出的数学操作都是对目标张量进行逐元素的操作。其中，如果二元操作的两个输入有不同形状，会先进行 :code:`broadcast`. 部分数学操作还支持数学操作符，比如： :code:`+`, :code:`-`, :code:`*`, :code:`/` 等。数学操作符不仅支持张量，还支持标量。
一元操作
==================
exp
------------------
对输入 :code:`Tensor` 逐元素做 :code:`exp` 操作。
API Reference 请参考 :ref:`api_fluid_layers_exp`
tanh
------------------
对输入 :code:`Tensor` 逐元素取正切。
API Reference 请参考 :ref:`api_fluid_layers_tanh`
sqrt
------------------
对输入 :code:`Tensor` 逐元素取平方根。
API Reference 请参考 :ref:`api_fluid_layers_sqrt`
abs
------------------
对输入 :code:`Tensor` 逐元素取绝对值。
API Reference 请参考 :ref:`api_fluid_layers_abs`
ceil
------------------
对输入 :code:`Tensor` 逐元素向上取整。
API Reference 请参考 :ref:`api_fluid_layers_ceil`
floor
------------------
对输入 :code:`Tensor` 逐元素向下取整。
API Reference 请参考 :ref:`api_fluid_layers_floor`
sin
------------------
对输入 :code:`Tensor` 逐元素取正玄。
API Reference 请参考 :ref:`api_fluid_layers_sin`
cos
------------------
对输入 :code:`Tensor` 逐元素取余玄。
API Reference 请参考 :ref:`api_fluid_layers_cos`
round
------------------
对输入 :code:`Tensor` 逐元素四舍五入取整。
API Reference 请参考 :ref:`api_fluid_layers_round`
square
------------------
对输入 :code:`Tensor` 逐元素取平方。
API Reference 请参考 :ref:`api_fluid_layers_square`
reciprocal
------------------
对输入 :code:`Tensor` 逐元素取倒数。
API Reference 请参考 :ref:`api_fluid_layers_reciprocal`
reduce
------------------
对输入 :code:`Tensor` 在指定的若干轴上做reduce操作，包括：min, max, sum, mean, product
API Reference 请参考:
:ref:`api_fluid_layers_reduce_min`
:ref:`api_fluid_layers_reduce_max`
:ref:`api_fluid_layers_reduce_sum`
:ref:`api_fluid_layers_reduce_mean`
:ref:`api_fluid_layers_reduce_prod`
二元操作
==================
elementwise_add
------------------
对两个 :code:`Tensor` 逐元素相加，对应的数学操作符为 :code:`+`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_add`
elementwise_sub
------------------
对两个 :code:`Tensor` 逐元素相减，对应数学操作符 :code:`-`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_sub`
elementwise_mul
------------------
对两个 :code:`Tensor` 逐元素相乘， 对应数学操作符 :code:`*`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_mul`
elementwise_div
------------------
对两个 :code:`Tensor` 逐元素相除， 对应数学操作符 :code:`/` 或 :code:`//`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_div`
elementwise_pow
------------------
对两个 :code:`Tensor` 逐元素做次幂操作， 对应数学操作符 :code:`**`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_pow`
equal
------------------
对两个 :code:`Tensor` 逐元素判断是否相等， 对应数学操作符 :code:`==`
API Reference 请参考 :ref:`api_fluid_layers_equal`
not_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否不等， 对应数学操作符 :code:`!=`
API Reference 请参考 :ref:`api_fluid_layers_elementwise_not_equal`
less_than
------------------
对两个 :code:`Tensor` 逐元素判断是否满足小于关系， 对应数学操作符 :code:`<`
API Reference 请参考 :ref:`api_fluid_layers_less_than`
less_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否满足小于或等于关系， 对应数学操作符 :code:`<=`
API Reference 请参考 :ref:`api_fluid_layers_less_equal`
greater_than
------------------
对两个 :code:`Tensor` 逐元素判断是否满足大于关系， 对应数学操作符 :code:`>`
API Reference 请参考 :ref:`api_fluid_layers_greater_than`
greater_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否满足大于或等于关系， 对应数学操作符 :code:`>=`
API Reference 请参考 :ref:`api_fluid_layers_greater_equal`
sum
------------------
对两个 :code:`Tensor` 逐元素相加。
API Reference 请参考 :ref:`api_fluid_layers_sum`
min
------------------
对两个 :code:`Tensor` 逐元素进行 :code:`min(x, y)` 操作。
API Reference 请参考 :ref:`api_fluid_layers_min`
max
------------------
对两个 :code:`Tensor` 逐元素进行 :code:`max(x, y)` 操作。
API Reference 请参考 :ref:`api_fluid_layers_max`
matmul
------------------
对两个 :code:`Tensor` 进行矩阵乘操作。
API Reference 请参考 :ref:`api_fluid_layers_matmul`
doc/fluid/api/api_guides/low_level/layers/pooling.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_pool:
#####
池化
#####
池化的作用是对输入特征做下采样和降低过拟合。降低过拟合是减小输出大小的结果，它同样也减少了后续层中的参数的数量。
池化通常只需要将前一层的特征图作为输入，此外需要一些参数来确定池化具体的操作。在PaddlePaddle中我们同样通过设定池化的大小，方式，步长，是否是全局池化，是否使用cudnn，是否使用ceil函数计算输出等参数来选择具体池化的方式。
PaddlePaddle中有针对定长图像特征的二维(pool2d)、三维卷积(pool3d)，RoI池化(roi_pool)，以及针对序列的序列池化(sequence_pool)，同时也有池化计算的反向过程，下面先介绍2D/3D池化，以及RoI池化，再来介绍序列池化。
--------------
1. pool2d/pool3d
------------------------
- ``input`` : 池化操作接收任何符合layout是：\ ``N（batch size）* C(channel size) * H(height) * W(width)``\ 格式的\ ``Tensor``\ 类型作为输入。
- ``pool_size``\ : 用来确定池化\ ``filter``\ 的大小，即将多大范围内的数据池化为一个值。
- ``num_channels``\ : 用来确定输入的\ ``channel``\ 数量，如果未设置参数或设置为\ ``None``\ ，其实际值将自动设置为输入的\ ``channel``\ 数量。
- ``pooling_type``\ : 接收\ ``avg``\ 和\ ``max``\ 2种类型之一作为pooling的方式，默认值为\ ``max``\ 。其中\ ``max``\ 意为最大池化，即计算池化\ ``filter``\ 区域内的数据的最大值作为输出；而\ ``avg``\ 意为平均池化，即计算池化\ ``filter``\ 区域内的数据的平均值作为输出。
- ``pool_stride``\ : 意为池化的\ ``filter``\ 在输入特征图上移动的步长。
- ``pool_padding``\ : 用来确定池化中\ ``padding``\ 的大小，\ ``padding``\ 的使用是为了对于特征图边缘的特征进行池化，选择不同的\ ``pool_padding``\ 大小确定了在特征图边缘增加多大区域的补零。从而决定边缘特征被池化的程度。
- ``global_pooling``\ : 意为是否使用全局池化，全局池化是指使用和特征图大小相同的\ ``filter``\ 来进行池化，同样这个过程也可以使用平均池化或者最大池化来做为池化的方式，全局池化通常会用来替换全连接层以大量减少参数防止过拟合。
- ``use_cudnn``\ : 选项可以来选择是否使用cudnn来优化计算池化速度。
- ``ceil_mode``\ : 是否使用ceil函数计算输出高度和宽度。\ ``ceil mode``\ 意为天花板模式，是指会把特征图中不足\ ``filter size``\ 的边给保留下来，单独另算，或者也可以理解为在原来的数据上补充了值为-NAN的边。而floor模式则是直接把不足\ ``filter size``\ 的边给舍弃了。具体计算公式如下：
- 非\ ``ceil_mode``\ 下:\ ``输出大小 = (输入大小 - filter size + 2 * padding) / stride（步长） + 1``
- ``ceil_mode``\ 下:\ ``输出大小 = (输入大小 - filter size + 2 * padding + stride - 1) / stride + 1``
api汇总：
- :ref:`api_fluid_layers_pool2d`
- :ref:`api_fluid_layers_pool3d`
2. roi_pool
------------------
``roi_pool``\ 一般用于检测网络中，将输入特征图依据候选框池化到特定的大小。
- ``rois``\ : 接收\ ``LoDTensor``\ 类型来表示需要池化的 Regions of Interest，关于RoI的解释请参考\ `论文 <https://arxiv.org/abs/1506.01497>`__
- ``pooled_height`` 和 ``pooled_width``\ : 这里可以接受非正方的池化窗口大小
- ``spatial_scale``\ : 用作设定缩放RoI和原图缩放的比例，注意，这里的设定需要用户自行计算RoI和原图的实际缩放比例。
api汇总：
- :ref:`api_fluid_layers_roi_pool`
3. sequence_pool
--------------------
``sequence_pool``\ 是一个用作对于不等长序列进行池化的接口，它将每一个实例的全部时间步的特征进行池化，它同样支持
``average``, ``sum``, ``sqrt`` 和\ ``max``\ 4种类型之一作为pooling的方式。 其中:
- ``average``\ 是对于每一个时间步内的数据求和后分别取平均值做为池化的结果。
- ``sum``\ 则是对每一个时间步内的数据分别求和作为池化的结果。
- ``sqrt``\ 则是对每一个时间步内的数据分别求和再分别取平方根作为池化的结果。
- ``max``\ 则是对每一个时间步内的数据分别求取最大值作为池化的结果。
api汇总：
- :ref:`api_fluid_layers_sequence_pool`
\ No newline at end of file
doc/fluid/api/api_guides/low_level/layers/sequence.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_sequence:
########
序列
########
在深度学习领域许多问题涉及到对 `序列（sequence） <https://en.wikipedia.org/wiki/Sequence>`_ 的处理。
从Wiki上的释义可知，序列可以表征多种物理意义，但在深度学习中，最常见的仍然是"时间序列"——一个序列包含多个时间步的信息。
在Paddle Fluid中，我们将序列表示为 :ref:`api_fluid_LoDTensor` 。
因为一般进行神经网络计算时都是一个batch一个batch地计算，所以我们用一个LoDTensor来存储一个mini batch的序列。
一个LoDTensor的第0维包含该mini batch中所有序列的所有时间步，并且用LoD来记录各个序列的长度，区分不同序列。
而在运算时，还需要根据LoD信息将LoDTensor中一个mini batch的第0维拆开成多个序列。（具体请参考上述LoD相关的文档。）
所以，对这类LoDTensor第0维的操作不能简单地使用一般的layer来进行，针对这一维的操作必须要结合LoD的信息。
(例如，你不能用 :code:`layers.reshape` 来对一个序列的第0维进行reshape)。
为了实行各类针对序列的操作，我们设计了一系列序列相关的API，专门用于正确处理序列相关的操作。
实践中，由于一个LoDTensor包括一个mini batch的序列，同一个mini batch中不同的序列通常属于多个sample，它们彼此之间不会也不应该发生相互作用。
因此，若一个layer以两个（或多个）LoDTensor为输入（或者以一个list的LoDTensor为输入），每一个LoDTensor代表一个mini batch的序列，则第一个LoDTensor中的第一个序列只会和第二个LoDTensor中的第一个序列发生计算，
第一个LoDTensor中的第二个序列只会和第二个LoDTensor中的第二个序列发生计算，第一个LoDTensor中的第i个序列只会和第二个LoDTensor中第i个序列发生计算，依此类推。
**总而言之，一个LoDTensor存储一个mini batch的多个序列，其中的序列个数为batch size；多个LoDTensor间发生计算时，每个LoDTensor中的第i个序列只会和其他LoDTensor中第i个序列发生计算。理解这一点对于理解接下来序列相关的操作会至关重要。**
1. sequence_softmax
-------------------
这个layer以一个mini batch的序列为输入，在每个序列内做softmax操作。其输出为一个mini batch相同shape的序列，但在序列内是经softmax归一化过的。
这个layer往往用于在每个sequence内做softmax归一化。
API Reference 请参考 :ref:`api_fluid_layers_sequence_softmax`
2. sequence_concat
------------------
这个layer以一个list为输入，该list中可以含有多个LoDTensor，每个LoDTensor为一个mini batch的序列。
该layer会将每个batch中第i个序列在时间维度上拼接成一个新序列，作为返回的batch中的第i个序列。
理所当然地，list中每个LoDTensor的序列必须有相同的batch size。
API Reference 请参考 :ref:`api_fluid_layers_sequence_concat`
3. sequence_first_step
----------------------
这个layer以一个LoDTensor作为输入，会取出每个序列中的第一个元素（即第一个时间步的元素），并作为返回值。
API Reference 请参考 :ref:`api_fluid_layers_sequence_first_step`
4. sequence_last_step
---------------------
同 :code:`sequence_first_step` ，除了本layer是取每个序列中最后一个元素（即最后一个时间步）作为返回值。
API Reference 请参考 :ref:`api_fluid_layers_sequence_last_step`
5. sequence_expand
------------------
这个layer有两个LoDTensor的序列作为输入，并按照第二个LoDTensor中序列的LoD信息来扩展第一个batch中的序列。
通常用来将只有一个时间步的序列（例如 :code:`sequence_first_step` 的返回结果）延展成有多个时间步的序列，以此方便与有多个时间步的序列进行运算。
API Reference 请参考 :ref:`api_fluid_layers_sequence_expand`
6. sequence_expand_as
---------------------
这个layer需要两个LoDTensor的序列作为输入，然后将第一个Tensor序列中的每一个序列延展成和第二个Tensor中对应序列等长的序列。
不同于 :code:`sequence_expand` ，这个layer会将第一个LoDTensor中的序列严格延展为和第二个LoDTensor中的序列等长。
如果无法延展成等长的（例如第二个batch中的序列长度不是第一个batch中序列长度的整数倍），则会报错。
API Reference 请参考 :ref:`api_fluid_layers_sequence_expand_as`
7. sequence_enumerate
---------------------
这个layer需要一个LoDTensor的序列作为输入，同时需要指定一个 :code:`win_size` 的长度。这个layer将依次取所有序列中长度为 :code:`win_size` 的子序列，并组合成新的序列。
API Reference 请参考 :ref:`api_fluid_layers_sequence_enumerate`
8. sequence_reshape
-------------------
这个layer需要一个LoDTensor的序列作为输入，同时需要指定一个 :code:`new_dim` 作为新的序列的维度。
该layer会将mini batch内每个序列reshape为new_dim给定的维度。注意，每个序列的长度会改变（因此LoD信息也会变），以适应新的形状。
API Reference 请参考 :ref:`api_fluid_layers_sequence_reshape`
9. sequence_scatter
-------------------
这个layer可以将一个序列的数据scatter到另一个tensor上。这个layer有三个input，一个要被scatter的目标tensor :code:`input`；
一个是序列的数据 :code:`update` ，一个是目标tensor的上坐标 :code:`index` 。Output为scatter后的tensor，形状和 :code:`input` 相同。
API Reference 请参考 :ref:`api_fluid_layers_sequence_scatter`
10. sequence_pad
----------------
这个layer可以将不等长的序列补齐成等长序列。使用这个layer需要提供一个 :code:`PadValue` 和一个 :code:`padded_length`。
前者是用来补齐序列的元素，可以是一个数也可以是一个tensor；后者是序列补齐的目标长度。
这个layer会返回补齐后的序列，以及一个记录补齐前各个序列长度的tensor :code:`Length`。
API Reference 请参考 :ref:`api_fluid_layers_sequence_pad`
11. sequence_mask
-----------------
这个layer会根据 :code:`input` 生成一个mask，:code:`input` 是一个记录了每个序列长度的tensor。
此外这个layer还需要一个参数 :code:`maxlen` 用于指定序列中最长的序列长度。
通常这个layer用于生成一个mask，将被pad后的序列中pad的部分过滤掉。
:code:`input` 的长度tensor通常可以直接用 :code:`sequence_pad` 返回的 :code:`Length`。
API Reference 请参考 :ref:`api_fluid_layers_sequence_mask`
doc/fluid/api/api_guides/low_level/layers/sparse_update.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_sparse_update:
#####
稀疏更新
#####
Fluid的 :ref:`api_fluid_layers_embedding` 层在单机训练和分布式训练时，均可以支持“稀疏更新”，即梯度以sparse tensor 结构存储，只保存梯度不为0的行。
在分布式训练中，对于较大的embedding层，开启稀疏更新有助于减少通信数据量，提升训练速度。
在paddle内部，我们用lookup_table来实现embedding。下边这张图说明了embedding在正向和反向计算的过程：
如图所示：一个Tensor中有两行不为0，正向计算的过程中，我们使用ids存储不为0的行，并使用对应的两行数据来进行计算；反向更新的过程也只更新这两行。
.. image:: ../../../../images/lookup_table_training.png
:scale: 50 %
embedding使用例子:
---------------------
API详细使用方法参考 :ref:`api_fluid_layers_embedding` ，以下是一个简单的例子：
.. code-block:: python
DICT_SIZE = 10000 * 10
EMBED_SIZE = 64
IS_SPARSE = False
def word_emb(word, dict_size=DICT_SIZE, embed_size=EMBED_SIZE):
embed = fluid.layers.embedding(
input=word,
size=[dict_size, embed_size],
dtype='float32',
param_attr=fluid.ParamAttr(
initializer=fluid.initializer.Normal(scale=1/math.sqrt(dict_size))),
is_sparse=IS_SPARSE,
is_distributed=False)
return embed
以上参数中：
- :code:`is_sparse` ： 反向计算的时候梯度是否为sparse tensor。如果不设置，梯度是一个 `LodTensor <https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md>`_ 。默认为False。
- :code:`is_distributed` ： 标志是否是用在分布式的场景下。一般大规模稀疏更新（embedding的第0维维度很大，比如几百万以上）才需要设置。具体可以参考大规模稀疏的API guide :ref:`api_guide_async_training` 。默认为False。
- API汇总:
- :ref:`api_fluid_layers_embedding`
doc/fluid/api/api_guides/low_level/layers/tensor.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_tensor:
########
张量
########
Fluid 中使用两种数据结构来承载数据，分别是 `Tensor 和 LoD_Tensor <../../../../user_guides/howto/prepare_data/lod_tensor.html>`_ 。 其中 LoD-Tensor 是 Fluid 的特有概念，它在 Tensor 基础上附加了序列信息。框架中可传输的数据包括：输入、输出、网络中的可学习参数，全部统一使用 LoD-Tensor 表示，Tensor 可以看作是一种特殊的 LoD-Tensor。
下面介绍这两种数据的相关操作。
Tensor
=======
1. create_tensor
---------------------
Tensor用于在框架中承载数据，使用 :code:`create_tensor` 可以创建一个指定数据类型的Lod-Tensor变量，
API reference 请参考： :ref:`api_fluid_layers_create_tensor`
2. create_parameter
---------------------
神经网络的训练过程是一个对参数的学习过程，Fluid 使用 :code:`create_parameter` 创建一个可学习的参数。该参数的值可以被operator改变。
API reference 请参考：:ref:`api_fluid_layers_create_parameter`
3. create_global_var
---------------------
Fluid 使用 :code:`create_global_var` 创建一个全局tensor，通过此 API 可以指定被创建 Tensor 变量的数据类型、形状和值。
API reference 请参考：:ref:`api_fluid_layers_create_global_var`
4. cast
---------------
Fluid 使用 :code:`cast` 将数据转换为指定类型。
API reference 请参考：:ref:`api_fluid_layers_cast`
5. concat
----------------
Fluid 使用 :code:`concat` 将输入数据沿指定维度连接。
API reference 请参考：:ref:`api_fluid_layers_concat`
6. sums
----------------
Fluid 使用 :code:`sums` 执行对输入数据的加和。
API reference 请参考：:ref:`api_fluid_layers_sums`
7. fill_constant_batch_size_like
---------------------------------
Fluid 使用 :code:`fill_constant_batch_size_like` 创建一个具有特定形状、类型和 batch_size 的 Tensor。并且该Tensor的初始值可以被指定为任意常数。其中 batch_size 信息由该tensor的 :code:`input_dim_idx` 和 :code:`output_dim_idx` 确定。
API reference 请参考：:ref:`api_fluid_layers_fill_constant_batch_size_like`
8. fill_constant
-----------------
Fluid 使用 :code:`fill_constant` 创建一个具有特定形状和类型的 Tensor。可以通过 :code:`value` 设置该变量的初始值。
API reference 请参考： :ref:`api_fluid_layers_fill_constant`
9. assign
---------------
Fluid 使用 :code:`assign` 复制一个变量。
API reference 请参考：:ref:`api_fluid_layers_assign`
10. argmin
--------------
Fluid 使用 :code:`argmin` 计算输入 Tensor 指定轴上最小元素的索引。
API reference 请参考：:ref:`api_fluid_layers_assign`
11. argmax
-----------
Fluid 使用 :code:`argmax` 计算输入 Tensor 指定轴上最大元素的索引。
API reference 请参考：:ref:`api_fluid_layers_argmax`
12. argsort
------------
Fluid 使用 :code:`argsort` 对输入 Tensor 在指定轴上进行排序，并返回排序后的数据变量及其对应的索引值。
API reference 请参考： :ref:`api_fluid_layers_argsort`
13. ones
-------------
Fluid 使用 :code:`ones` 创建一个指定大小和数据类型的Tensor，且初始值为1。
API reference 请参考： :ref:`api_fluid_layers_ones`
14. zeros
---------------
Fluid 使用 :code:`zeros` 创建一个指定大小和数据类型的Tensor，且初始值为0。
API reference 请参考： :ref:`api_fluid_layers_zeros`
15. reverse
-------------------
Fluid 使用 :code:`reverse` 沿指定轴反转 Tensor。
API reference 请参考： :ref:`api_fluid_layers_reverse`
LoD-Tensor
============
LoD-Tensor非常适用于序列数据，相关知识可以参考阅读 `LoD_Tensor <../../../../user_guides/howto/prepare_data/lod_tensor.html>`_ 。
1. create_lod_tensor
-----------------------
Fluid 使用 :code:`create_lod_tensor` 基于numpy数组、列表或现有 LoD_Tensor 创建拥有新的层级信息的 LoD_Tensor。
API reference 请参考： :ref:`api_fluid_create_lod_tensor`
2. create_random_int_lodtensor
----------------------------------
Fluid 使用 :code:`create_random_int_lodtensor` 创建一个由随机整数组成的 LoD_Tensor。
API reference 请参考： :ref:`api_fluid_create_random_int_lodtensor`
3. reorder_lod_tensor_by_rank
---------------------------------
Fluid 使用 :code:`reorder_lod_tensor_by_rank` 对输入 LoD_Tensor 的序列信息按指定顺序重拍。
API reference 请参考：:ref:`api_fluid_layers_reorder_lod_tensor_by_rank`
\ No newline at end of file
doc/fluid/api/api_guides/low_level/memory_optimize.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_memory_optimize:
#####
显存优化
#####
显存优化是通过分析、复用 :code:`Program` 中 :code:`Varaible` 使用的显存，从而降低 :code:`Program` 执行时显存消耗的方法。用户可以通过Python脚本调用 :code:`memory_optimize` 接口进行显存优化，显存优化的执行策略如下：
- 首先根据 :code:`Program` 中 :code:`Operator` 之间的关系对 :code:`Variable` 的最后存活时间进行分析，得到每个 :code:`Variable` 的最后存活时间;
- 其次根据每个 :code:`Variable` 的最后存活时间，我们将到达存活时间、不再存活的 :code:`Variable` 所占用的显存提供给后来的 :code:`Variable` 使用。
.. code-block:: python
z = fluid.layers.sum([x, y])
m = fluid.layers.matmul(y, z)
在这个示例中，:code:`x` 的存活时间到 :code:`fluid.layers.sum` 操作为止，所以它的显存可以被 :code:`m` 复用。
针对特定部分禁用显存优化
===========
:code:`memory_optimize` 支持针对特定部分禁用显存优化，用户可以通过传入 :code:`Variable` 名字的集合来指定哪些 :code:`Variable` 所使用的显存不会被复用;
与此同时，:code:`memory_optimize` 能够针对网络的反向部分禁用显存优化，用户可以通过传入 :code:`skip_grads` 参数来开启这个功能。
.. code-block:: python
fluid.memory_optimize(fluid.default_main_program(),
skip_opt_set=("fc"), skip_grads=True)
在这个示例中，:code:`fluid.memory_optimize` 接口对默认的 :code:`Program` 进行了 :code:`Variable` 最后存活时间的分析，并跳过了名字为 :code:`fc` 的 :code:`Variable` 以及网络反向部分的所有 :code:`Variable` 。
这部分 :code:`Variable` 的显存都不会被别的 :code:`Varaible` 再次使用。
指定显存优化等级
===========
:code:`memory_optimize` 支持打印显存复用的信息以方便用户进行调试，用户可以通过指定 :code:`print_log=True` 来开启显存复用的调试信息;
:code:`memory_optimize` 支持两种显存优化的等级，:code:`0` 或者 :code:`1` :
- 优化等级为 :code:`0` 时： :code:`memory_optimize` 在分析完 :code:`Variable` 的最后生存时间后，会判断 :code:`Variable` 的 :code:`shape` ，只有 :code:`shape` 相同的 :code:`Variable` 才会进行显存复用；
- 优化等级为 :code:`1` 时： :code:`memory_optimize` 会尽可能地进行显存复用，在分析完 :code:`Variable` 的最后生存时间后，即使是 :code:`shape` 不同的 :code:`Variable` 也会进行最大程度的显存复用。
.. code-block:: python
fluid.memory_optimize(fluid.default_main_program(),
level=0, print_log=True)
在这个示例中，:code:`fluid.memory_optimize` 接口对默认的 :code:`Program` 进行了 :code:`Variable` 最后存活时间的分析。
只有 :code:`shape` 完全相同的 :code:`Variable` 才会进行显存复用，并且在分析结束后，会打印出所有显存复用相关的调试信息。
doc/fluid/api/api_guides/low_level/metrics.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_metrics:
评价指标
#########
在神经网络训练过程中或者训练完成后，需要评价模型的训练效果。评价的方法一般是计算全体预测值和全体真值(label)之间的距离，不同类型的任务会使用不同的评价方法，或者综合使用多个评价方法。在具体的任务中，可以选用一种或者多种评价方法。下面对常用的评价方法按照任务类型做介绍。
分类任务评价
------------------
分类任务中最常用的是二分类，而多分类任务也可以转化为多个二分类任务的组合，二分类任务常用的评价指标有准确率、正确率、召回率、AUC和平均准确度。
- 准确率: :code:`Precision` ，用来衡量二分类中召回真值和召回值的比例。
API Reference 请参考 :ref:`api_fluid_metrics_Precision`
- 正确率: :code:`Accuracy` ，用来衡量二分类中召回真值和总样本数的比例。需要注意的是，准确率和正确率的定义是不同的，可以类比于误差分析中的 :code:`Variance` 和 :code:`Bias` 。
API Reference 请参考 :ref:`api_fluid_metrics_Accuracy`
- 召回率: :code:`Recall` ，用来衡量二分类中召回值和总样本数的比例。准确率和召回率的选取相互制约，实际模型中需要进行权衡，可以参考文档 `Precision_and_recall <https://en.wikipedia.org/wiki/Precision_and_recall>`_ 。
API Reference 请参考 :ref:`api_fluid_metrics_Recall`
- AUC: :code:`Area Under Curve`， 适用于二分类的分类模型评估，用来计算 `ROC曲线的累积面积 <https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve>`_。:code:`Auc` 通过python计算实现，如果关注性能，可以使用 :code:`fluid.layers.auc` 代替。
API Reference 请参考 :ref:`api_fluid_metrics_Auc`
- 平均准确度: :code:`Average Precision` ，常用在Faster R-CNN和SSD等物体检测任务中。在不同召回条件下，计算了准确率的平均值，具体可以参考文档 `Average-precision <https://sanchom.wordpress.com/tag/average-precision/>`_ 和 `SSD: Single Shot MultiBox Detector <https://arxiv.org/abs/1512.02325>`_。
API Reference 请参考 :ref:`api_fluid_metrics_DetectionMAP`
序列标注任务评价
------------------
序列标注任务中，token的分组称为语块(chunk)，模型会同时将输入的token分组和分类，常用的评估方法是语块评估方法。
- 语块评估方法: :code:`ChunkEvaluator` ，接收 :code:`chunk_eval` 接口的输出，累积每一个minibatch的语块统计值，最后计算准确率、召回率和F1值。:code:`ChunkEvaluator` 支持IOB, IOE, IOBES和IO四种标注模式。可以参考文档 `Chunking with Support Vector Machines <https://aclanthology.info/pdf/N/N01/N01-1025.pdf>`_ 。
API Reference 请参考 :ref:`api_fluid_metrics_ChunkEvaluator`
生成任务评价
------------------
生成任务会依据输入直接产生输出。对应NLP任务中(比如语音识别)，则生成新字符串。评估生成字符串和目标字符串之间距离的方法也有多种，比如多分类评估方法，而另外一种常用的方法叫做编辑距离。
- 编辑距离: :code:`EditDistance` ，用来衡量两个字符串的相似度。可以参考文档 `Edit_distance <https://en.wikipedia.org/wiki/Edit_distance>`_。
API Reference 请参考 :ref:`api_fluid_metrics_EditDistance`
doc/fluid/api/api_guides/low_level/model_save_reader.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_model_save_reader:
#########
模型保存与加载
#########
模型的保存与加载主要涉及到如下八个API：
:code:`fluid.io.save_vars`、:code:`fluid.io.save_params`、:code:`fluid.io.save_persistables`、:code:`fluid.io.save_inference_model`、:code:`fluid.io.load_vars`、:code:`fluid.io.load_params`、:code:`fluid.io.load_persistables` 和 :code:`fluid.io.load_inference_model`。
变量、持久性变量和参数
====================
在 :code:`Paddle` 中，算子(:code:`Operator`)的每一个输入和输出都是一个变量（:code:`Variable`），而参数（:code:`Parameter`）是变量（:code:`Variable`）的子类。持久性变量（:code:`Persistables`）是一种在每次迭代结束后均不会被删除的变量。参数是一种持久性变量，其在每次迭代后都会被优化器（:ref:`api_guide_optimizer`）更新。训练神经网络本质上就是在更新参数。
模型保存API介绍
====================
- :code:`fluid.io.save_vars`：通过执行器（:ref:`api_guide_executor`）保存变量到指定的目录中。保存变量的方式有两种：
1）通过接口中的 :code:`vars` 指定需要保存的变量列表。
2）将一个已经存在的程序（:code:`Program`）赋值给接口中的 :code:`main_program`，然后这个程序中的所有变量都将被保存下来。
第一种保存方式的优先级要高于第二种。
API Reference 请参考 :ref:`api_fluid_io_save_vars`。
- :code:`fluid.io.save_params`：通过接口中的 :code:`main_program` 指定好程序（:code:`Program`），该接口会将所指定程序中的全部参数（:code:`Parameter`）过滤出来，并将它们保存到 :code:`dirname` 指定的文件夹或 :code:`filename` 指定的文件中。
API Reference 请参考 :ref:`api_fluid_io_save_params`。
- :code:`fluid.io.save_persistables`：通过接口中的 :code:`main_program` 指定好程序（:code:`Program`），该接口会将所指定程序中的全部持久性变量（:code:`persistable==True`）过滤出来，并将它们保存到 :code:`dirname` 指定的文件夹或 :code:`filename` 指定的文件中。
API Reference 请参考 :ref:`api_fluid_io_save_persistables`。
- :code:`fluid.io.save_inference_model`：请参考 :ref:`api_guide_inference`。
模型加载API介绍
====================
- :code:`fluid.io.load_vars`：通过执行器（:code:`Executor`）加载指定目录中的变量。加载变量的方式有两种：
1）通过接口中的 :code:`vars` 指定需要加载的变量列表。
2）将一个已经存在的程序（:code:`Program`）赋值给接口中的 :code:`main_program`，然后这个程序中的所有变量都将被加载。
第一种加载方式的优先级要高于第二种。
API Reference 请参考 :ref:`api_fluid_io_load_vars`。
- :code:`fluid.io.load_params`：该接口从 :code:`main_program` 指定的程序中过滤出全部参数（:code:`Parameter`），并试图从 :code:`dirname` 指定的文件夹或 :code:`filename` 指定的文件中加载这些参数。
API Reference 请参考 :ref:`api_fluid_io_load_params`。
- :code:`fluid.io.load_persistables`：该接口从 :code:`main_program` 指定的程序中过滤出全部持久性变量（:code:`persistable==True`），并试图从 :code:`dirname` 指定的文件夹或 :code:`filename` 指定的文件中加载这些持久性变量。
API Reference 请参考 :ref:`api_fluid_io_load_persistables`。
- :code:`fluid.io.load_inference_model`：请参考 :ref:`api_guide_inference`。
doc/fluid/api/api_guides/low_level/nets.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_nets:
###########
复杂网络
###########
在处理复杂功能时，我们通常需要写大量的代码来构建复杂的 `神经网络 <https://zh.wikipedia.org/wiki/人工神经网络>`_ 。
因此，为了方便用户更加容易地搭建复杂网络模型，我们提供了一些比较常用的基本函数模块，以此来简化用户的代码量，从而降低开发成本。
这些模块通常是由细粒度的函数根据一定的逻辑拼接组合而成，实现代码请参考 `nets.py <https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/fluid/nets.py>`_ 。
1.simple_img_conv_pool
----------------------
:code:`simple_img_conv_pool` 是由 :ref:`api_fluid_layers_conv2d` 与 :ref:`api_fluid_layers_pool2d` 串联而成。
该模块在图像分类模型中广泛使用，比如应用在 `MNIST <https://en.wikipedia.org/wiki/MNIST_database>`_ 数字分类的问题。
API Reference 请参考 :ref:`api_fluid_nets_simple_img_conv_pool`
2.img_conv_group
----------------
:code:`img_conv_group` 是由 :ref:`api_fluid_layers_conv2d` , :ref:`api_fluid_layers_batch_norm`, :ref:`api_fluid_layers_dropout` 和 :ref:`api_fluid_layers_pool2d` 组成。
该模块可以实现多个 :ref:`api_fluid_layers_conv2d` , :ref:`api_fluid_layers_batch_norm` 和 :ref:`api_fluid_layers_dropout` 的串联单元与一个 :ref:`api_fluid_layers_pool2d` 的组合。
其中， :ref:`api_fluid_layers_conv2d` , :ref:`api_fluid_layers_batch_norm` 和 :ref:`api_fluid_layers_dropout` 的数量都可以分别控制，从而得到多样的组合。
该模块广泛使用在比较复杂的图像分类任务中，比如 `VGG <https://arxiv.org/pdf/1409.1556.pdf>`_ 。
API Reference 请参考 :ref:`api_fluid_nets_img_conv_group`
3.sequence_conv_pool
--------------------
:code:`sequence_conv_pool` 是由 :ref:`api_fluid_layers_sequence_conv` 与 :ref:`api_fluid_layers_sequence_pool` 串联而成。
该模块在 `自然语言处理 <https://zh.wikipedia.org/wiki/自然语言处理>`_ 以及 `语音识别 <https://zh.wikipedia.org/wiki/语音识别>`_ 等领域均有广泛应用，
比如 `文本分类模型 <https://github.com/PaddlePaddle/models/blob/develop/fluid/PaddleNLP/text_classification/nets.py>`_ ,
`TagSpace <https://github.com/PaddlePaddle/models/blob/develop/fluid/PaddleRec/tagspace/train.py>`_ 以及 `Multi-view Simnet <https://github.com/PaddlePaddle/models/blob/develop/fluid/PaddleRec/multiview_simnet/nets.py>`_ 等模型。
API Reference 请参考 :ref:`api_fluid_nets_sequence_conv_pool`
4.glu
-----
:code:`glu` 全称 Gated Linear Units， 来源于论文 `Language Modeling with Gated Convolutional Networks <https://arxiv.org/pdf/1612.08083.pdf>`_ ，由 :ref:`api_fluid_layers_split` ， :ref:`api_fluid_layers_sigmoid` 和 :ref:`api_fluid_layers_elementwise_mul` 组成。
它会把输入数据均分为2等份，并对第二部分求 `Sigmoid <https://en.wikipedia.org/wiki/Sigmoid_function>`_ , 然后再与第一部分数据求点乘得到输出。
API Reference 请参考 :ref:`api_fluid_nets_glu`
5.scaled_dot_product_attention
------------------------------
:code:`scaled_dot_product_attention` 来源于论文 `Attention Is All You Need <https://arxiv.org/pdf/1706.03762.pdf>`_ ，主要是由 :ref:`api_fluid_layers_fc` 和 :ref:`api_fluid_layers_softmax` 组成。
对于输入数据 :code:`Queries` , :code:`Key` 和 :code:`Values` 按照如下公式求出 :code:`Attention` 。
.. math::
Attention(Q, K, V)= softmax(QK^\mathrm{T})V
该模块广泛使用在 `机器翻译 <https://zh.wikipedia.org/zh/机器翻译>`_ 的模型中，比如 `Transformer <https://github.com/PaddlePaddle/models/tree/develop/fluid/PaddleNLP/neural_machine_translation/transformer>`_ 。
API Reference 请参考 :ref:`api_fluid_nets_scaled_dot_product_attention`
doc/fluid/api/api_guides/low_level/optimizer.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_optimizer:
###########
优化器
###########
神经网络最终是一个 `最优化问题 <https://en.wikipedia.org/wiki/Optimization_problem>`_ ，
在经过 `前向计算和反向传播 <https://zh.wikipedia.org/zh-hans/反向传播算法>`_ 后，
:code:`Optimizer` 使用反向传播梯度，优化神经网络中的参数。
1.SGD/SGDOptimizer
------------------
:code:`SGD` 是实现 `随机梯度下降 <https://arxiv.org/pdf/1609.04747.pdf>`_ 的一个 :code:`Optimizer` 子类，是 `梯度下降 <https://zh.wikipedia.org/zh-hans/梯度下降法>`_ 大类中的一种方法。
当需要训练大量样本的时候，往往选择 :code:`SGD` 来使损失函数更快的收敛。
API Reference 请参考 :ref:`api_fluid_optimizer_SGDOptimizer`
2.Momentum/MomentumOptimizer
----------------------------
:code:`Momentum` 优化器在 :code:`SGD` 基础上引入动量，减少了随机梯度下降过程中存在的噪声问题。
用户在使用时可以将 :code:`ues_nesterov` 参数设置为False或True，分别对应传统 `Momentum(论文4.1节)
<https://arxiv.org/pdf/1609.04747.pdf>`_ 算法和 `Nesterov accelerated gradient(论文4.2节)
<https://arxiv.org/pdf/1609.04747.pdf>`_ 算法。
API Reference 请参考 :ref:`api_fluid_optimizer_MomentumOptimizer`
3. Adagrad/AdagradOptimizer
---------------------------
`Adagrad <http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf>`_ 优化器可以针对不同参数样本数不平均的问题，自适应地为各个参数分配不同的学习率。
API Reference 请参考 :ref:`api_fluid_optimizer_AdagradOptimizer`
4.RMSPropOptimizer
------------------
`RMSProp优化器 <http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf>`_ ，是一种自适应调整学习率的方法，
主要解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。
API Reference 请参考 :ref:`api_fluid_optimizer_RMSPropOptimizer`
5.Adam/AdamOptimizer
--------------------
`Adam <https://arxiv.org/abs/1412.6980>`_ 的优化器是一种自适应调整学习率的方法，
适用于大多非 `凸优化 <https://zh.wikipedia.org/zh/凸優化>`_ 、大数据集和高维空间的场景。在实际应用中，:code:`Adam` 是最为常用的一种优化方法。
API Reference 请参考 :ref:`api_fluid_optimizer_AdamOptimizer`
6.Adamax/AdamaxOptimizer
------------------------
`Adamax <https://arxiv.org/abs/1412.6980>`_ 是 :code:`Adam` 算法的一个变体，对学习率的上限提供了一个更简单的范围，使学习率的边界范围更简单。
API Reference 请参考 :ref:`api_fluid_optimizer_AdamaxOptimizer`
7.DecayedAdagrad/ DecayedAdagradOptimizer
-------------------------------------------
`DecayedAdagrad <http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf>`_ 优化器，可以看做是引入了衰减速率的 :code:`Adagrad` 算法，解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。
API Reference 请参考 :ref:`api_fluid_optimizer_DecayedAdagrad`
8. Ftrl/FtrlOptimizer
----------------------
`FtrlOptimizer <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_ 优化器结合了 `FOBOS算法 <https://stanford.edu/~jduchi/projects/DuchiSi09b.pdf>`_ 的高精度与 `RDA算法
<http://www1.se.cuhk.edu.hk/~sqma/SEEM5121_Spring2015/dual-averaging.pdf>`_ 的稀疏性，是目前效果非常好的一种 `Online Learning <https://en.wikipedia.org/wiki/Online_machine_learning>`_ 算法。
API Reference 请参考 :ref:`api_fluid_optimizer_FtrlOptimizer`
9.ModelAverage
-----------------
:code:`ModelAverage` 优化器，在训练中通过窗口来累计历史 parameter，在预测时使用取平均值后的paramet，整体提高预测的精度。
API Reference 请参考 :ref:`api_fluid_optimizer_ModelAverage`
doc/fluid/api/api_guides/low_level/parallel_executor.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. _api_guide_parallel_executor:
#####
数据并行执行引擎
#####
:code:`ParallelExecutor` 是以数据并行的方式在多个节点上分别执行 :code:`Program` 的执行器。用户可以通过Python脚本驱动 :code:`ParallelExecutor` 执行， :code:`ParallelExecutor` 的执行过程：
- 首先根据 :code:`Program` 、 :code:`GPU` 卡的数目（或者 :code:`CPU` 的核数）以及 :ref:`api_fluid_BuildStrategy` 构建 :code:`SSA Graph` 和一个线程池;
- 执行过程中，根据Op的输入是否Ready决定是否执行该Op，这样可以使没有相互依赖的多个Op可在线程池中并行执行；
:code:`ParallelExecutor` 在构造时需要指定当前 :code:`Program` 的设备类型， :code:`GPU` 或者 :code:`CPU` ：
* 使用 :code:`GPU` 执行： :code:`ParallelExecutor` 会自动检测当前机器可以使用 :code:`GPU` 的个数，并在每个 :code:`GPU` 上分别执行 :code:`Program` ，用户也可以通过设置 :code:`CUDA_VISIBLE_DEVICES` 环境变量来指定执行器可使用的 :code:`GPU` ；
* 使用 :code:`CPU` 多线程执行：:code:`ParallelExecutor` 会自动检测当前机器可利用的 :code:`CPU` 核数，并将 :code:`CPU` 核数作为执行器中线程的个数，每个线程分别执行 :code:`Program` ，用户也可以通过设置 :code:`CPU_NUM` 环境变量来指定当前训练使用的线程个数。
:code:`ParallelExecutor` 支持模型训练和模型预测：
* 模型训练： :code:`ParallelExecutor` 在执行过程中对多个节点上的参数梯度进行聚合，然后进行参数的更新；
* 模型预测： :code:`ParallelExecutor` 在执行过程中各个节点独立运行当前的 :code:`Program` ；
:code:`ParallelExecutor` 在模型训练时支持两种模式的梯度聚合, :code:`AllReduce` 和 :code:`Reduce` ：
* :code:`AllReduce` 模式下， :code:`ParallelExecutor` 调用AllReduce操作使多个节点上参数梯度完全相等，然后各个节点独立进行参数的更新；
* :code:`Reduce` 模式下， :code:`ParallelExecutor` 会预先将所有参数的更新分派到不同的节点上，在执行过程中 :code:`ParallelExecutor` 调用Reduce操作将参数梯度在预先指定的节点上进行聚合，并进行参数更新，最后调用Broadcast操作将更新后的参数发送到其他节点。
这两种模式通过 :code:`build_strategy` 来指定，使用方法，请参考 :ref:`api_fluid_BuildStrategy` 。
**注意** ：如果在Reduce模式下使用 :code:`CPU` 多线程执行 :code:`Program` ， :code:`Program` 的参数在多个线程间是共享的，在某些模型上，Reduce模式可以大幅节省内存。
由于模型的执行速度与模型结构和执行器的执行策略相关， :code:`ParallelExecutor` 允许用户修改执行器的相关参数，如：线程池大小（ :code:`num_threads` ）、多少次迭代之后清理一次临时变量 :code:`num_iteration_per_drop_scope` 等，更多信息请参考 :ref:`api_fluid_ExecutionStrategy` >。
- 相关API汇总:
- :ref:`api_fluid_ParallelExecutor`
- :ref:`api_fluid_BuildStrategy`
- :ref:`api_fluid_ExecutionStrategy`
\ No newline at end of file
doc/fluid/api/api_guides/low_level/parameter.rst 已删除 100755 → 0
浏览文件 @ 3524ea61
.. _api_guide_parameter:
#########
模型参数
#########
模型参数为模型中的weight和bias统称，在fluid中对应fluid.Parameter类，继承自fluid.Variable，是一种可持久化的variable。模型的训练就是不断学习更新模型参数的过程。模型参数相关的属性可以通过 :ref:`api_fluid_param_attr_ParamAttr` 来配置，可配置内容有：
- 初始化方式
- 正则化
- 梯度剪切
- 模型平均
初始化方式
=================
fluid通过设置 :code:`ParamAttr` 的 :code:`initializer` 属性为单个parameter设置初始化方式。
示例如下：
.. code-block:: python
param_attrs = fluid.ParamAttr(name="fc_weight",
initializer=fluid.initializer.ConstantInitializer(1.0))
y_predict = fluid.layers.fc(input=x, size=10, param_attr=param_attrs)
以下为fluid支持的初始化方式：
1. BilinearInitializer
-----------------------
线性初始化方法。用该方法初始化的反卷积操作可当做线性插值操作使用。
可用别名：Bilinear
API请参考：:ref:`api_fluid_initializer_BilinearInitializer`
2. ConstantInitializer
----------------------
常数初始化方式，将parameter初始化为指定的数值。
可用别名：Constant
API请参考：:ref:`api_fluid_initializer_ConstantInitializer`
3. MSRAInitializer
------------------
该初始化方法参考论文: https://arxiv.org/abs/1502.01852
可用别名：MSRA
API请参考：:ref:`api_fluid_initializer_MSRAInitializer`
4. NormalInitializer
---------------------
随机高斯分布初始化方法。
可用别名：Normal
API请参考：:ref:`api_fluid_initializer_NormalInitializer`
5. TruncatedNormalInitializer
-----------------------------
随机截断高斯分布初始化方法。
可用别名：TruncatedNormal
API请参考：:ref:`api_fluid_initializer_TruncatedNormalInitializer`
6. UniformInitializer
--------------------
随机均匀分布初始化方式。
可用别名：Uniform
API请参考：:ref:`api_fluid_initializer_UniformInitializer`
7. XavierInitializer
--------------------
该初始化方式参考论文: http://proceedings.mlr.press/v9/glorot10a/glorot10a.pdf
可用别名：Xavier
API请参考：:ref:`api_fluid_initializer_XavierInitializer`
正则化方式
=============
fluid通过设置 :code:`ParamAttr` 的 :code:`regularizer` 属性为单个parameter设置正则化。
.. code-block:: python
param_attrs = fluid.ParamAttr(name="fc_weight",
regularizer=fluid.regularizer.L1DecayRegularizer(0.1))
y_predict = fluid.layers.fc(input=x, size=10, param_attr=param_attrs)
以下为fluid支持的正则化方式：
- :ref:`api_fluid_regularizer_L1DecayRegularizer` (别名：L1Decay)
- :ref:`api_fluid_regularizer_L2DecayRegularizer` (别名：L2Decay)
Clipping
==========
fluid通过设置 :code:`ParamAttr` 的 :code:`gradient_clip` 属性为单个parameter设置clipping方式。
.. code-block:: python
param_attrs = fluid.ParamAttr(name="fc_weight",
regularizer=fluid.regularizer.L1DecayRegularizer(0.1))
y_predict = fluid.layers.fc(input=x, size=10, param_attr=param_attrs)
以下为fluid支持的clipping方式：
1. ErrorClipByValue
-------------------
用来将一个tensor的值clipping到指定范围。
API请参考：:ref:`api_fluid_clip_ErrorClipByValue`
2. GradientClipByGlobalNorm
---------------------------
用来将多个Tensor的global-norm限制在 :code:`clip_norm` 以内。
API请参考：:ref:`api_fluid_clip_GradientClipByGlobalNorm`
3. GradientClipByNorm
---------------------
将Tensor的l2-norm限制在 :code:`max_norm` 以内。如果Tensor的l2-norm超过了 :code:`max_norm` ，
会将计算出一个 :code:`scale` ，该Tensor的所有值乘上计算出来的 :code:`scale` .
API请参考：:ref:`api_fluid_clip_GradientClipByNorm`
4. GradientClipByValue
----------------------
将parameter对应的gradient的值限制在[min, max]范围内。
API请参考：:ref:`api_fluid_clip_GradientClipByValue`
模型平均
========
fluid通过 :code:`ParamAttr` 的 :code:`do_model_average` 属性设置单个parameter是否进行平均优化。
示例如下：
.. code-block:: python
param_attrs = fluid.ParamAttr(name="fc_weight",
do_model_average=true)
y_predict = fluid.layers.fc(input=x, size=10, param_attr=param_attrs)
在miniBatch训练过程中，每个batch过后，都会更新一次parameters，模型平均做的就是平均最近k次更新产生的parameters。
平均后的parameters只是被用来进行测试和预测，其并不参与实际的训练过程。
具体API请参考：:ref:`api_fluid_optimizer_ModelAverage`
doc/fluid/api/data/data_reader.rst
浏览文件 @ 2be25c70
===================== =====================
Data Reader Interface Data Reader
===================== =====================
......
doc/fluid/api/data/dataset.rst
浏览文件 @ 2be25c70
Dataset dataset
======= =======
.. automodule:: paddle.dataset .. automodule:: paddle.dataset
......
doc/fluid/api/index_cn.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
=============
API Reference
=============
.. toctree::
:maxdepth: 1
fluid.rst
average.rst
backward.rst
clip.rst
data.rst
data_feeder.rst
executor.rst
initializer.rst
io.rst
layers.rst
metrics.rst
nets.rst
optimizer.rst
param_attr.rst
profiler.rst
recordio_writer.rst
regularizer.rst
transpiler.rst
doc/fluid/api/index_en.rst
浏览文件 @ 2be25c70
...@@ -18,9 +18,10 @@ API Reference ...@@ -18,9 +18,10 @@ API Reference
metrics.rst metrics.rst
nets.rst nets.rst
optimizer.rst optimizer.rst
param_attr.rst
profiler.rst profiler.rst
recordio_writer.rst recordio_writer.rst
regularizer.rst regularizer.rst
transpiler.rst transpiler.rst
data/dataset.rst
data/data_reader.rst
doc/fluid/api/param_attr.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
!DO NOT EDIT THIS FILE MANUALLY!
================
fluid.param_attr
================
.. _api_fluid_param_attr_ParamAttr:
ParamAttr
---------
.. autoclass:: paddle.fluid.param_attr.ParamAttr
:members:
:noindex:
.. _api_fluid_param_attr_WeightNormParamAttr:
WeightNormParamAttr
-------------------
.. autoclass:: paddle.fluid.param_attr.WeightNormParamAttr
:members:
:noindex:
doc/fluid/api_cn/api_guides/low_level/backward.rst 0 → 100644
浏览文件 @ 2be25c70
.. _api_guide_backward:
########
反向传播
########
神经网络对模型的表达能力依赖于优化算法，优化是一个不断计算梯度并调整可学习参数的过程，Fluid中的优化算法可参考 :ref:`api_guide_optimizer` 。
在网络的训练过程中，梯度计算分为两个步骤：前向计算与 `反向传播 <https://en.wikipedia.org/wiki/Backpropagation>`_ 。
- 前向计算会根据您搭建的网络结构，将输入单元的状态传递到输出单元。
- 反向传播借助 `链式法则 <https://en.wikipedia.org/wiki/Chain_rule>`_ ，计算两个或两个以上复合函数的导数，将输出单元的梯度反向传播回输入单元，根据计算出的梯度，调整网络的可学习参数。
详细实现过程可以参考阅读 `反向传导算法 <http://deeplearning.stanford.edu/wiki/index.php/%E5%8F%8D%E5%90%91%E4%BC%A0%E5%AF%BC%E7%AE%97%E6%B3%95>`_ 。
在Fluid中，我们并不推荐直接调用 :code:`fluid` 中反向传播相关API，因为这是一个极底层的API，请考虑使用 :ref:`api_guide_optimizer` 中的相关API替代。当您使用优化相关API时，Fluid会自动为您计算复杂的反向传播过程。
如想自己实现，您也可以使用 :ref:`cn_api_fluid_backward_append_backward` 中的 :code:`callback` 自
定义Operator的梯度计算形式。更多用法，请参考：
* :ref:`cn_api_fluid_backward_append_backward`
doc/fluid/api_cn/api_guides/low_level/executor.rst
浏览文件 @ 2be25c70
...@@ -7,14 +7,14 @@ ...@@ -7,14 +7,14 @@
:code:`Executor` 即 :code:`执行器` 。PaddlePaddle Fluid中有两种执行器可以选择。 :code:`Executor` 即 :code:`执行器` 。PaddlePaddle Fluid中有两种执行器可以选择。
:code:`Executor` 实现了一个简易的执行器，所有Operator会被顺序执行。用户可以使用 :code:`Executor` 实现了一个简易的执行器，所有Operator会被顺序执行。用户可以使用
Python脚本驱动 :code:`Executor` 执行。默认情况下 :code:`Executor` 是单线程的，如果 Python脚本驱动 :code:`Executor` 执行。默认情况下 :code:`Executor` 是单线程的，如果
想使用数据并行，请参考另一个执行器， :ref:`cn_api_guide_parallel_executor` 。 想使用数据并行，请参考另一个执行器， :ref:`api_guide_parallel_executor` 。
:code:`Executor` 的代码逻辑非常简单。建议用户在调试过程中，先使用 :code:`Executor` 的代码逻辑非常简单。建议用户在调试过程中，先使用
:code:`Executor` 跑通模型，再切换到多设备计算，甚至多机计算。 :code:`Executor` 跑通模型，再切换到多设备计算，甚至多机计算。
:code:`Executor` 在构造的时候接受一个 :code:`Place`， 它们可以是 :ref:`cn_api_fluid_CPUPlace` :code:`Executor` 在构造的时候接受一个 :code:`Place`， 它们可以是 :ref:`cn_api_fluid_CPUPlace`
或 :ref:`cn_api_fluid_CUDAPlace` 。 :code:`Executor` 在执行的时候可以选择执行的 或 :ref:`cn_api_fluid_CUDAPlace` 。 :code:`Executor` 在执行的时候可以选择执行的
:ref:`cn_api_guide_low_level_program` 。 :ref:`api_guide_low_level_program` 。
简单的使用方法，请参考 `quick_start_fit_a_line <http://paddlepaddle.org/documentation/docs/zh/1.1/beginners_guide/quick_start/fit_a_line/README.cn.html>`_ , API Reference 请参考 简单的使用方法，请参考 `quick_start_fit_a_line <http://paddlepaddle.org/documentation/docs/zh/1.1/beginners_guide/quick_start/fit_a_line/README.cn.html>`_ , API Reference 请参考
:ref:`cn_api_fluid_Executor` 。 :ref:`cn_api_fluid_Executor` 。
doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst
浏览文件 @ 2be25c70
.. api_guide_control_flow: .. _api_guide_control_flow:
###### ######
控制流 控制流
......
doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst
浏览文件 @ 2be25c70
...@@ -57,4 +57,4 @@ API Reference 请参考 :ref:`cn_api_fluid_layers_sigmoid_cross_entropy_with_log ...@@ -57,4 +57,4 @@ API Reference 请参考 :ref:`cn_api_fluid_layers_sigmoid_cross_entropy_with_log
对于一些较为复杂的损失函数，可以尝试使用其他损失函数组合实现；Paddle Fluid 中提供的用于图像分割任务的 :ref:`cn_api_fluid_layers_dice_loss` 即是使用其他 OP 组合（计算各像素位置似然概率的均值）而成；多目标损失函数也可看作这样的情况，如 Faster RCNN 就使用 cross entropy 和 smooth_l1 loss 的加权和作为损失函数。 对于一些较为复杂的损失函数，可以尝试使用其他损失函数组合实现；Paddle Fluid 中提供的用于图像分割任务的 :ref:`cn_api_fluid_layers_dice_loss` 即是使用其他 OP 组合（计算各像素位置似然概率的均值）而成；多目标损失函数也可看作这样的情况，如 Faster RCNN 就使用 cross entropy 和 smooth_l1 loss 的加权和作为损失函数。
**注意**，在定义损失函数之后为能够使用 :ref:`cn_api_guide_optimizer` 进行优化，通常需要使用 :ref:`cn_api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。 **注意**，在定义损失函数之后为能够使用 :ref:`api_guide_optimizer` 进行优化，通常需要使用 :ref:`cn_api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。
\ No newline at end of file \ No newline at end of file
doc/fluid/api_cn/api_guides/low_level/layers/math.rst
浏览文件 @ 2be25c70
...@@ -147,12 +147,6 @@ equal ...@@ -147,12 +147,6 @@ equal
API Reference 请参考 :ref:`cn_api_fluid_layers_equal` API Reference 请参考 :ref:`cn_api_fluid_layers_equal`
not_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否不等， 对应数学操作符 :code:`!=`
API Reference 请参考 :ref:`cn_api_fluid_layers_elementwise_not_equal`
less_than less_than
------------------ ------------------
...@@ -161,26 +155,7 @@ less_than ...@@ -161,26 +155,7 @@ less_than
API Reference 请参考 :ref:`cn_api_fluid_layers_less_than` API Reference 请参考 :ref:`cn_api_fluid_layers_less_than`
less_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否满足小于或等于关系， 对应数学操作符 :code:`<=`
API Reference 请参考 :ref:`cn_api_fluid_layers_less_equal`
greater_than
------------------
对两个 :code:`Tensor` 逐元素判断是否满足大于关系， 对应数学操作符 :code:`>`
API Reference 请参考 :ref:`cn_api_fluid_layers_greater_than`
greater_equal
------------------
对两个 :code:`Tensor` 逐元素判断是否满足大于或等于关系， 对应数学操作符 :code:`>=`
API Reference 请参考 :ref:`cn_api_fluid_layers_greater_equal`
sum sum
------------------ ------------------
...@@ -189,19 +164,19 @@ sum ...@@ -189,19 +164,19 @@ sum
API Reference 请参考 :ref:`cn_api_fluid_layers_sum` API Reference 请参考 :ref:`cn_api_fluid_layers_sum`
min elementwise_min
------------------ ------------------
对两个 :code:`Tensor` 逐元素进行 :code:`min(x, y)` 操作。 对两个 :code:`Tensor` 逐元素进行 :code:`min(x, y)` 操作。
API Reference 请参考 :ref:`cn_api_fluid_layers_min` API Reference 请参考 :ref:`cn_api_fluid_layers_elementwise_min`
max elementwise_max
------------------ ------------------
对两个 :code:`Tensor` 逐元素进行 :code:`max(x, y)` 操作。 对两个 :code:`Tensor` 逐元素进行 :code:`max(x, y)` 操作。
API Reference 请参考 :ref:`cn_api_fluid_layers_max` API Reference 请参考 :ref:`cn_api_fluid_layers_elementwise_max`
matmul matmul
------------------ ------------------
......
doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst
浏览文件 @ 2be25c70
...@@ -39,7 +39,7 @@ API详细使用方法参考 :ref:`cn_api_fluid_layers_embedding` ，以下是一 ...@@ -39,7 +39,7 @@ API详细使用方法参考 :ref:`cn_api_fluid_layers_embedding` ，以下是一
- :code:`is_sparse` ： 反向计算的时候梯度是否为sparse tensor。如果不设置，梯度是一个 `LodTensor <https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md>`_ 。默认为False。 - :code:`is_sparse` ： 反向计算的时候梯度是否为sparse tensor。如果不设置，梯度是一个 `LodTensor <https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md>`_ 。默认为False。
- :code:`is_distributed` ： 标志是否是用在分布式的场景下。一般大规模稀疏更新（embedding的第0维维度很大，比如几百万以上）才需要设置。具体可以参考大规模稀疏的API guide :ref:`cn_api_guide_async_training` 。默认为False。 - :code:`is_distributed` ： 标志是否是用在分布式的场景下。一般大规模稀疏更新（embedding的第0维维度很大，比如几百万以上）才需要设置。具体可以参考大规模稀疏的API guide :ref:`api_guide_async_training` 。默认为False。
- API汇总: - API汇总:
- :ref:`cn_api_fluid_layers_embedding` - :ref:`cn_api_fluid_layers_embedding`
doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst
浏览文件 @ 2be25c70
...@@ -10,12 +10,12 @@ ...@@ -10,12 +10,12 @@
变量、持久性变量和参数 变量、持久性变量和参数
==================== ====================
在 :code:`Paddle` 中，算子(:code:`Operator`)的每一个输入和输出都是一个变量（:code:`Variable`），而参数（:code:`Parameter`）是变量（:code:`Variable`）的子类。持久性变量（:code:`Persistables`）是一种在每次迭代结束后均不会被删除的变量。参数是一种持久性变量，其在每次迭代后都会被优化器（:ref:`cn_api_guide_optimizer`）更新。训练神经网络本质上就是在更新参数。 在 :code:`Paddle` 中，算子(:code:`Operator`)的每一个输入和输出都是一个变量（:code:`Variable`），而参数（:code:`Parameter`）是变量（:code:`Variable`）的子类。持久性变量（:code:`Persistables`）是一种在每次迭代结束后均不会被删除的变量。参数是一种持久性变量，其在每次迭代后都会被优化器（:ref:`api_guide_optimizer`）更新。训练神经网络本质上就是在更新参数。
模型保存API介绍 模型保存API介绍
==================== ====================
- :code:`fluid.io.save_vars`：通过执行器（:ref:`cn_api_guide_executor`）保存变量到指定的目录中。保存变量的方式有两种： - :code:`fluid.io.save_vars`：通过执行器（:ref:`api_guide_executor`）保存变量到指定的目录中。保存变量的方式有两种：
1）通过接口中的 :code:`vars` 指定需要保存的变量列表。 1）通过接口中的 :code:`vars` 指定需要保存的变量列表。
...@@ -33,7 +33,7 @@ ...@@ -33,7 +33,7 @@
API Reference 请参考 :ref:`cn_api_fluid_io_save_persistables`。 API Reference 请参考 :ref:`cn_api_fluid_io_save_persistables`。
- :code:`fluid.io.save_inference_model`：请参考 :ref:`cn_api_guide_inference`。 - :code:`fluid.io.save_inference_model`：请参考 :ref:`api_guide_inference`。
模型加载API介绍 模型加载API介绍
==================== ====================
...@@ -56,4 +56,4 @@ ...@@ -56,4 +56,4 @@
API Reference 请参考 :ref:`cn_api_fluid_io_load_persistables`。 API Reference 请参考 :ref:`cn_api_fluid_io_load_persistables`。
- :code:`fluid.io.load_inference_model`：请参考 :ref:`cn_api_guide_inference`。 - :code:`fluid.io.load_inference_model`：请参考 :ref:`api_guide_inference`。
doc/fluid/api_cn/api_guides/low_level/program.rst 0 → 100644
浏览文件 @ 2be25c70
.. _api_guide_Program:
###############################
Program/Block/Operator/Variable
###############################
==================
Program
==================
:code:`Fluid` 中使用类似于编程语言的抽象语法树的形式描述用户的神经网络配置，用户对计算的描述都将写入一段Program。Fluid 中的 Program 替代了传统框架中模型的概念，通过对顺序执行、条件选择和循环执行三种执行结构的支持，做到对任意复杂模型的描述。书写 :code:`Program` 的过程非常接近于写一段通用程序，如果您已经具有一定的编程经验，会很自然地将自己的知识迁移过来。
总得来说：
* 一个模型是一个 Fluid :code:`Program` ,一个模型可以含有多于一个 :code:`Program` ；
* :code:`Program` 由嵌套的 :code:`Block` 构成，:code:`Block` 的概念可以类比到 C++ 或是 Java 中的一对大括号，或是 Python 语言中的一个缩进块；
* :code:`Block` 中的计算由顺序执行、条件选择或者循环执行三种方式组合，构成复杂的计算逻辑；
* :code:`Block` 中包含对计算和计算对象的描述。计算的描述称之为 Operator；计算作用的对象（或者说 Operator 的输入和输出）被统一为 Tensor，在Fluid中，Tensor 用层级为0的 `LoD-Tensor <http://paddlepaddle.org/documentation/docs/zh/1.2/user_guides/howto/prepare_data/lod_tensor.html#permalink-4-lod-tensor>`_ 表示。
=========
Block
=========
:code:`Block` 是高级语言中变量作用域的概念，在编程语言中，Block是一对大括号，其中包含局部变量定义和一系列指令或操作符。编程语言中的控制流结构 :code:`if-else` 和 :code:`for` 在深度学习中可以被等效为：
+----------------------+-------------------------+
| 编程语言 | Fluid |
+======================+=========================+
| for, while loop | RNN,WhileOP |
+----------------------+-------------------------+
| if-else, switch | IfElseOp, SwitchOp |
+----------------------+-------------------------+
| 顺序执行 | 一系列 layers |
+----------------------+-------------------------+
如上文所说，Fluid 中的 :code:`Block` 描述了一组以顺序、选择或是循环执行的 Operator 以及 Operator 操作的对象：Tensor。
=============
Operator
=============
在 Fluid 中，所有对数据的操作都由 :code:`Operator` 表示，为了便于用户使用，在 Python 端，Fluid 中的 :code:`Operator` 被一步封装入 :code:`paddle.fluid.layers` ， :code:`paddle.fluid.nets` 等模块。
这是因为一些常见的对 Tensor 的操作可能是由更多基础操作构成，为了提高使用的便利性，框架内部对基础 Operator 进行了一些封装，包括创建 Operator 依赖可学习参数，可学习参数的初始化细节等，减少用户重复开发的成本。
更多内容可参考阅读 `Fluid设计思想 <../../../advanced_usage/design_idea/fluid_design_idea.html>`_
=========
Variable
=========
Fluid 中的 :code:`Variable` 可以包含任何类型的值———在大多数情况下是一个 LoD-Tensor。
模型中所有的可学习参数都以 :code:`Variable` 的形式保留在内存空间中，您在绝大多数情况下都不需要自己来创建网络中的可学习参数， Fluid 为几乎常见的神经网络基本计算模块都提供了封装。以最简单的全连接模型为例，调用 :code:`fluid.layers.fc` 会直接为全连接层创建连接权值( W )和偏置（ bias ）两个可学习参数，无需显示地调用 :code:`variable` 相关接口创建可学习参数。
=========
相关API
=========
* 用户配置的单个神经网络叫做 :ref:`cn_api_fluid_Program` 。值得注意的是，训练神经网
络时，用户经常需要配置和操作多个 :code:`Program` 。比如参数初始化的
:code:`Program` ， 训练用的 :code:`Program` ，测试用的
:code:`Program` 等等。
* 用户还可以使用 :ref:`cn_api_fluid_program_guard` 配合 :code:`with` 语句，修改配置好的 :ref:`cn_api_fluid_default_startup_program` 和 :ref:`cn_api_fluid_default_main_program` 。
* 在Fluid中，Block内部执行顺序由控制流决定，如 :ref:`cn_api_fluid_layers_IfElse` , :ref:`cn_api_fluid_layers_While`, :ref:`cn_api_fluid_layers_Switch` 等，更多内容可参考： :ref:`api_guide_control_flow`
doc/fluid/api_cn/fluid_cn.rst
浏览文件 @ 2be25c70
...@@ -9,7 +9,7 @@ ...@@ -9,7 +9,7 @@
AsyncExecutor AsyncExecutor
------------------------------- -------------------------------
.. py:function:: paddle.fluid.AsyncExecutor(place=None) .. py:class:: paddle.fluid.AsyncExecutor(place=None)
Python中的异步执行器。AsyncExecutor利用多核处理器和数据排队的强大功能，使数据读取和融合解耦，每个线程并行运行。 Python中的异步执行器。AsyncExecutor利用多核处理器和数据排队的强大功能，使数据读取和融合解耦，每个线程并行运行。
...@@ -122,8 +122,9 @@ str类型。在 ``ParallelExecutor`` 中，存在三种定义 *loss@grad* 的方 ...@@ -122,8 +122,9 @@ str类型。在 ``ParallelExecutor`` 中，存在三种定义 *loss@grad* 的方
str类型。在 ``ParallelExecutor`` 中，存在两种减少策略（reduce strategy），即 ``AllReduce`` 和 ``Reduce`` 。如果你需要在所有执行场所上独立地进行参数优化，可以使用 ``AllReduce`` 。反之，如果使用 ``Reduce`` 策略，所有参数的优化将均匀地分配给不同的执行场所，随之将优化后的参数广播给其他执行场所。在一些模型中， ``Reduce`` 策略执行速度更快一些。默认值为 ``AllReduce`` 。 str类型。在 ``ParallelExecutor`` 中，存在两种减少策略（reduce strategy），即 ``AllReduce`` 和 ``Reduce`` 。如果你需要在所有执行场所上独立地进行参数优化，可以使用 ``AllReduce`` 。反之，如果使用 ``Reduce`` 策略，所有参数的优化将均匀地分配给不同的执行场所，随之将优化后的参数广播给其他执行场所。在一些模型中， ``Reduce`` 策略执行速度更快一些。默认值为 ``AllReduce`` 。
.. py:attribute:: remove_unnecessary_lock
BOOL类型。如果设置为True, GPU操作中的一些锁将被释放，ParallelExecutor将运行得更快，默认为 False。
...@@ -270,7 +271,7 @@ CUDAPlace ...@@ -270,7 +271,7 @@ CUDAPlace
DataFeedDesc DataFeedDesc
------------------------------- -------------------------------
.. py:function:: paddle.fluid.DataFeedDesc(proto_file) .. py:class:: paddle.fluid.DataFeedDesc(proto_file)
数据描述符，描述输入训练数据格式。 数据描述符，描述输入训练数据格式。
...@@ -324,7 +325,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 ...@@ -324,7 +325,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含
- **proto_file** (string) - 包含数据feed中描述的磁盘文件 - **proto_file** (string) - 包含数据feed中描述的磁盘文件
.. py:method:: set_batch_size(self, batch_size) .. py:method:: set_batch_size(batch_size)
设置batch size，训练期间有效 设置batch size，训练期间有效
...@@ -339,7 +340,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 ...@@ -339,7 +340,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含
data_feed = fluid.DataFeedDesc('data.proto') data_feed = fluid.DataFeedDesc('data.proto')
data_feed.set_batch_size(128) data_feed.set_batch_size(128)
.. py:method:: set_dense_slots(self, dense_slots_name) .. py:method:: set_dense_slots(dense_slots_name)
指定slot经过设置后将变成密集的slot，仅在训练期间有效。 指定slot经过设置后将变成密集的slot，仅在训练期间有效。
...@@ -360,7 +361,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 ...@@ -360,7 +361,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含
默认情况下，所有slot都是稀疏的 默认情况下，所有slot都是稀疏的
.. py:method:: set_use_slots(self, use_slots_name) .. py:method:: set_use_slots(use_slots_name)
设置一个特定的slot是否用于训练。一个数据集包含了很多特征，通过这个函数可以选择哪些特征将用于指定的模型。 设置一个特定的slot是否用于训练。一个数据集包含了很多特征，通过这个函数可以选择哪些特征将用于指定的模型。
...@@ -380,7 +381,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 ...@@ -380,7 +381,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含
默认值不用于所有slot 默认值不用于所有slot
.. py:method:: desc(self) .. py:method:: desc()
返回此DataFeedDesc的protobuf信息 返回此DataFeedDesc的protobuf信息
...@@ -1163,8 +1164,8 @@ ParallelExecutor ...@@ -1163,8 +1164,8 @@ ParallelExecutor
- ``TypeError`` - 如果feed参数是list类型，但是它里面的元素不是dict类型时，弹出此异常 - ``TypeError`` - 如果feed参数是list类型，但是它里面的元素不是dict类型时，弹出此异常
.. note:: .. note::
1.如果feed参数为dict类型，那么传入 ``ParallelExecutor`` 的数据量 *必须* 大于可用的执行场所数目。否则，C++端将会抛出异常。应额外注意核对数据集的最后一个batch是否比可用执行场所数目大。 1. 如果feed参数为dict类型，那么传入 ``ParallelExecutor`` 的数据量 *必须* 大于可用的CPU核数或GPU卡数。否则，C++端将会抛出异常。应额外注意核对数据集的最后一个batch是否比可用的CPU核数或GPU卡数大。
2.如果可用执行场所大于一个，则为每个变量最后获取的结果都是list类型，且这个list中的每个元素都是各个可用执行场所的变量 2. 如果可用的CPU核数或GPU卡数大于一个，则为每个变量最后获取的结果都是list类型，且这个list中的每个元素都是各CPU核或GPU卡上的变量
**代码示例** **代码示例**
...@@ -1231,10 +1232,10 @@ ParamAttr ...@@ -1231,10 +1232,10 @@ ParamAttr
Program Program
------------------------------- -------------------------------
.. py:function:: paddle.fluid.Program .. py:class:: paddle.fluid.Program
创建python program， 在paddleFluid内部会被转换为ProgramDesc描述语言，是被用来创建c++ Program。Program像容器一样也是一种独立的程序语言。Program包括至少一个块（Block），控制流比如conditional_block包括while_op，该Program将会含有嵌套块（nested block）。详情请参阅framework.proto。 创建python program， 在paddleFluid内部会被转换为ProgramDesc描述语言，用来创建一段 c++ 程序。Program像容器一样，是一种自包含的程序语言。Program中包括至少一个块（Block），当 block 中存在条件选择的控制流op（例如 while_op）时，该Program将会含有嵌套块（nested block）。详情请参阅framework.proto。
注意：默认情况下，paddleFluid内部默认含有 ``default_startup_program`` 和 ``default_main_program`` ，它们将共享参数。 ``default_startup_program`` 只运行一次来初始化参数， ``default_main_program`` 在每个mini batch中运行并调整权重。 注意：默认情况下，paddleFluid内部默认含有 ``default_startup_program`` 和 ``default_main_program`` ，它们将共享参数。 ``default_startup_program`` 只运行一次来初始化参数， ``default_main_program`` 在每个mini batch中运行并调整权重。
......
doc/fluid/api_cn/index_cn.rst
浏览文件 @ 2be25c70
...@@ -18,7 +18,6 @@ API ...@@ -18,7 +18,6 @@ API
metrics_cn.rst metrics_cn.rst
nets_cn.rst nets_cn.rst
optimizer_cn.rst optimizer_cn.rst
param_attr_cn.rst
profiler_cn.rst profiler_cn.rst
regularizer_cn.rst regularizer_cn.rst
transpiler_cn.rst transpiler_cn.rst
doc/fluid/api_cn/initializer_cn.rst
浏览文件 @ 2be25c70
...@@ -285,7 +285,7 @@ UniformInitializer ...@@ -285,7 +285,7 @@ UniformInitializer
参数： 参数：
- **low** (float) - 下界 - **low** (float) - 下界
- **high** (float) - 上界 - **high** (float) - 上界
- **seed** (float) - 随机种子 - **seed** (int) - 随机种子
**代码示例** **代码示例**
......
doc/fluid/api_cn/layers_cn.rst
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/api_cn/metrics_cn.rst
浏览文件 @ 2be25c70
...@@ -196,7 +196,7 @@ CompositeMetric ...@@ -196,7 +196,7 @@ CompositeMetric
DetectionMAP DetectionMAP
------------------------------- -------------------------------
.. py:class:: paddle.fluid.metrics.DetectionMAP(name=None) .. py:class:: paddle.fluid.metrics.DetectionMAP(input, gt_label, gt_box, gt_difficult=None, class_num=None, background_label=0, overlap_threshold=0.5, evaluate_difficult=True, ap_version='integral')
计算 detection 平均精度（mAP）。 mAP是衡量object detectors精度的指标，比如 Faster R-CNN,SSD等。它不同于召回率，它是最大精度的平均值。 请从以下文章中获取更多信息： 计算 detection 平均精度（mAP）。 mAP是衡量object detectors精度的指标，比如 Faster R-CNN,SSD等。它不同于召回率，它是最大精度的平均值。 请从以下文章中获取更多信息：
...@@ -246,7 +246,7 @@ https://arxiv.org/abs/1512.02325 ...@@ -246,7 +246,7 @@ https://arxiv.org/abs/1512.02325
返回：当前 mini-batch 的 mAP 变量，和跨 mini-batch 的 mAP 累加和 返回：当前 mini-batch 的 mAP 变量，和跨 mini-batch 的 mAP 累加和
.. py:methord:: reset(executor, reset_program=None) .. py:method:: reset(executor, reset_program=None)
在指定 batch 的每一 pass/user 开始时重置度量状态。 在指定 batch 的每一 pass/user 开始时重置度量状态。
...@@ -380,7 +380,7 @@ Recall ...@@ -380,7 +380,7 @@ Recall
.. py:class:: paddle.fluid.metrics.Recall(name=None) .. py:class:: paddle.fluid.metrics.Recall(name=None)
召回率（也称为敏感度）是度量有多个正例被分为正例 召回率（也称为敏感度）是指得到的相关实例数占相关实例总数的比重
https://en.wikipedia.org/wiki/Precision_and_recall https://en.wikipedia.org/wiki/Precision_and_recall
......
doc/fluid/api_cn/nets_cn.rst
浏览文件 @ 2be25c70
...@@ -159,7 +159,7 @@ attention运算机制可以被视为将查询和一组键值对映射到输出 ...@@ -159,7 +159,7 @@ attention运算机制可以被视为将查询和一组键值对映射到输出
sequence_conv_pool sequence_conv_pool
------------------------------- -------------------------------
.. py:function:: paddle.fluid.nets.sequence_conv_pool(input, num_filters, filter_size, param_attr=None, act='sigmoid', pool_type='max') .. py:function:: paddle.fluid.nets.sequence_conv_pool(input, num_filters, filter_size, param_attr=None, act='sigmoid', pool_type='max', bias_attr=None)
sequence_conv_pool由序列卷积和池化组成 sequence_conv_pool由序列卷积和池化组成
......
doc/fluid/api_cn/optimizer_cn.rst
浏览文件 @ 2be25c70
...@@ -262,7 +262,7 @@ FtrlOptimizer ...@@ -262,7 +262,7 @@ FtrlOptimizer
FTRL (Follow The Regularized Leader) Optimizer. FTRL (Follow The Regularized Leader) Optimizer.
TFRTL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_) FTRL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_)
.. math:: .. math::
...@@ -439,9 +439,10 @@ MomentumOptimizer ...@@ -439,9 +439,10 @@ MomentumOptimizer
.. math:: .. math::
& velocity = mu * velocity + gradient\\ & velocity = mu * velocity + gradient\\
& if (use\_nesterov):\ & if (use\_nesterov):\\
\&\quad param = param - (gradient + mu * velocity) * learning\_rate\\ &\quad param = param - (gradient + mu * velocity) * learning\_rate\\
& else:\\&\quad param = param - learning\_rate * velocity & else:\\&\quad param = param - learning\_rate * velocity
参数： 参数：
- **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量 - **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量
- **momentum** (float) - 动量因子 - **momentum** (float) - 动量因子
...@@ -469,7 +470,7 @@ RMSPropOptimizer ...@@ -469,7 +470,7 @@ RMSPropOptimizer
.. py:class:: paddle.fluid.optimizer.RMSPropOptimizer(learning_rate, rho=0.95, epsilon=1e-06, momentum=0.0, centered=False, regularization=None, name=None) .. py:class:: paddle.fluid.optimizer.RMSPropOptimizer(learning_rate, rho=0.95, epsilon=1e-06, momentum=0.0, centered=False, regularization=None, name=None)
均方根平均传播（RMSProp）法是一种未发表的,自适应学习率的方法。原始slides提出了RMSProp：[http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf]中的第29张slide。等式如下所示： 均方根传播（RMSProp）法是一种未发表的,自适应学习率的方法。原演示幻灯片中提出了RMSProp：[http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf]中的第29张。等式如下所示：
.. math:: .. math::
r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\
...@@ -493,11 +494,11 @@ RMSPropOptimizer ...@@ -493,11 +494,11 @@ RMSPropOptimizer
其中， :math:`ρ` 是超参数，典型值为0.9,0.95等。 :math:`beta` 是动量术语。 :math:`epsilon` 是一个平滑项，用于避免除零，通常设置在1e-4到1e-8的范围内。 其中， :math:`ρ` 是超参数，典型值为0.9,0.95等。 :math:`beta` 是动量术语。 :math:`epsilon` 是一个平滑项，用于避免除零，通常设置在1e-4到1e-8的范围内。
参数： 参数：
- **learning_rate** （float） - 全球学习率。 - **learning_rate** （float） - 全局学习率。
- **rho** （float） - rho是等式中的 :math:`rho` ，默认设置为0.95。 - **rho** （float） - rho是等式中的 :math:`rho` ，默认设置为0.95。
- **epsilon** （float） - 等式中的epsilon是平滑项，避免被零除，默认设置为1e-6。 - **epsilon** （float） - 等式中的epsilon是平滑项，避免被零除，默认设置为1e-6。
- **momentum** （float） - 方程中的β是动量项，默认设置为0.0。 - **momentum** （float） - 方程中的β是动量项，默认设置为0.0。
- **centered** （bool） - 如果为True，则通过梯度估计方差对梯度进行归一化；如果false，则由未centered的第二个moment归一化。将此设置为True有助于培训，但在计算和内存方面稍微昂贵一些。默认为False。 - **centered** （bool） - 如果为True，则通过梯度的估计方差,对梯度进行归一化；如果False，则由未centered的第二个moment归一化。将此设置为True有助于模型训练，但会消耗额外计算和内存资源。默认为False。
- **regularization** - 正则器项，如 ``fluid.regularizer.L2DecayRegularizer`` 。 - **regularization** - 正则器项，如 ``fluid.regularizer.L2DecayRegularizer`` 。
- **name** - 可选的名称前缀。 - **name** - 可选的名称前缀。
......
doc/fluid/api_cn/param_attr_cn.rst 已删除 100644 → 0
浏览文件 @ 3524ea61
#################
fluid.param_attr
#################
.. _cn_api_fluid_param_attr_ParamAttr:
ParamAttr
-------------------------------
.. py:class:: paddle.fluid.param_attr.ParamAttr(name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False)
该类代表了参数的各种属性。 为了使神经网络训练过程更加流畅，用户可以根据需要调整参数属性。比如learning rate（学习率）, regularization（正则化）, trainable（可训练性）, do_model_average(平均化模型)和参数初始化方法.
参数:
- **name** (str) – 参数名。默认为None。
- **initializer** (Initializer) – 初始化该参数的方法。 默认为None
- **learning_rate** (float) – 参数的学习率。计算方法为 global_lr*parameter_lr∗scheduler_factor。 默认为1.0
- **regularizer** (WeightDecayRegularizer) – 正则因子. 默认为None
- **trainable** (bool) – 该参数是否可训练。默认为True
- **gradient_clip** (BaseGradientClipAttr) – 减少参数梯度的方法。默认为None
- **do_model_average** (bool) – 该参数是否服从模型平均值。默认为False
**代码示例**
.. code-block:: python
w_param_attrs = fluid.ParamAttr(name="fc_weight",
learning_rate=0.5,
regularizer=fluid.L2Decay(1.0),
trainable=True)
y_predict = fluid.layers.fc(input=x, size=10, param_attr=w_param_attrs)
.. _cn_api_fluid_param_attr_WeightNormParamAttr:
WeightNormParamAttr
-------------------------------
.. py:class:: paddle.fluid.param_attr.WeightNormParamAttr(dim=None, name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False)
权重归一化。权范数是神经网络中权向量的再参数化，它将权向量的长度与其方向解耦。该paper对权值归一化的实现进行了讨论： `Weight Normalization: A Simple Reparameterization to Accelerate Training of Deep Neural Networks <https://arxiv.org/pdf/1602.07868.pdf>`_
参数:
- **dim** (list) – 参数维度. Default None.
- **name** (str) – 参数名称. Default None.
- **initializer** (Initializer) – 初始化参数的方法. Default None.
- **learning_rate** (float) – 参数的学习率. 优化的参数学习率为 :math:`global\_lr*parameter\_lr*scheduler\_factor` . Default 1.0
- **regularizer** (WeightDecayRegularizer) – 正则化因子. Default None.
- **trainable** (bool) – 参数是否可训练. Default True.
- **gradient_clip** (BaseGradientClipAttr) – 修剪这个参数的梯度的方法. Default None.
- **do_model_average** (bool) – 这个参数是否应该做模型平均. Default False.
**代码示例**
.. code-block:: python
data = fluid.layers.data(name="data", shape=[3, 32, 32], dtype="float32")
fc = fluid.layers.fc(input=data,
size=1000,
param_attr=WeightNormParamAttr(
dim=None,
name='weight_norm_param'))
doc/fluid/api_cn/profiler_cn.rst
浏览文件 @ 2be25c70
...@@ -171,10 +171,10 @@ start_profiler ...@@ -171,10 +171,10 @@ start_profiler
stop_profiler stop_profiler
------------------------------- -------------------------------
.. py:function::paddle.fluid.profiler.stop_profiler(sorted_key=None, profile_path='/tmp/profile') .. py:function:: paddle.fluid.profiler.stop_profiler(sorted_key=None, profile_path='/tmp/profile')
停止 profiler， 用户可以使用 ``fluid.profiler.start_profiler`` 和 ``fluid.profiler.stop_profiler`` 插入代码 停止 profiler， 用户可以使用 ``fluid.profiler.start_profiler`` 和 ``fluid.profiler.stop_profiler`` 插入代码
不能使用 fluid.profiler.profiler`` 不能使用 ``fluid.profiler.profiler``
参数: 参数:
- **sorted_key** (string) – 如果为None，prfile的结果将按照事件的第一次结束时间顺序打印。否则，结果将按标志排序。标志取值为"call"、"total"、"max"、"min" "ave"之一，根据调用着的数量进行排序。total表示按总执行时间排序，max 表示按最大执行时间排序。min 表示按最小执行时间排序。ave表示按平均执行时间排序。 - **sorted_key** (string) – 如果为None，prfile的结果将按照事件的第一次结束时间顺序打印。否则，结果将按标志排序。标志取值为"call"、"total"、"max"、"min" "ave"之一，根据调用着的数量进行排序。total表示按总执行时间排序，max 表示按最大执行时间排序。min 表示按最小执行时间排序。ave表示按平均执行时间排序。
......
doc/fluid/api_cn/transpiler_cn.rst
浏览文件 @ 2be25c70
...@@ -150,7 +150,7 @@ DistributeTranspilerConfig ...@@ -150,7 +150,7 @@ DistributeTranspilerConfig
最小数据块的大小 最小数据块的大小
注意: 根据：https：//github.com/PaddlePaddle/Paddle/issues/8638#issuecomment-369912156, 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看slice_variable函数。 注意: 根据：https://github.com/PaddlePaddle/Paddle/issues/8638#issuecomment-369912156 , 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看slice_variable函数。
......
doc/fluid/beginners_guide/install/FAQ_en.md 0 → 100644
浏览文件 @ 2be25c70
***
<a name="FAQ_en"></a>
# **FAQ**
- How to compile python2.7 as a shared library under CentOS6?
> Use the following instructions:
./configure --prefix=/usr/local/python2.7 --enable-shared
make && make install
- Ubuntu18.04 under libidn11 can not be found?
> Use the following instructions:
apt install libidn11
- When Ubuntu compiles, a lot of code segments are not recognized?
> This may be caused by a mismatch in the cmake version. Please use the following command in the gcc installation directory:
apt install gcc-4.8 g++-4.8
cp gcc gcc.bak
cp g++ g++.bak
rm gcc
rm g++
ln -s gcc-4.8 gcc
ln -s g++-4.8 g++
- Encountered paddlepaddle*.whl is not a supported wheel on this platform?
> The main reason for this problem is that there is no paddlepaddle installation package that matches the current system. Please check if the Python version is 2.7 series. In addition, the latest pip official source installation package defaults to the manylinux1 standard, you need to use the latest pip (>9.0.0) to install. You can update your pip by following these instructions:
pip install --upgrade pip
or
python -c "import pip; print(pip.pep425tags.get_supported())"
> If the system supports linux_x86_64 and the installation package is manylinux1_x86_64, you need to upgrade the pip version to the latest; if the system supports manylinux1_x86_64 and the installation package (local) is linux_x86_64, you can rename this whl package to manylinux1_x86_64 and install it again.
- Is there a problem with Docker compilation?
> Please refer to [Issue12079](https://github.com/PaddlePaddle/Paddle/issues/12079) on GitHub.
- What is Docker?
> If you haven't heard of Docker, you can think of it as a virtualenv-like system, but it virtualises more than the Python runtime environment.
- Is Docker still a virtual machine?
> Someone uses a virtual machine to analogize to Docker. It should be emphasized that Docker does not virtualize any hardware. The compiler tools running in the Docker container are actually run directly on the native CPU and operating system. The performance is the same as installing the compiler on the machine.
- Why use Docker?
> Installing the tools and configurations in a Docker image standardizes the build environment. This way, if you encounter problems, others can reproduce the problem to help. In addition, for developers accustomed to using Windows and MacOS, there is no need to configure a cross-compilation environment using Docker.
- Can I choose not to use Docker?
> Of course you can. You can install development tools to the machine in the same way that you install them into Docker image. This document describes the Docker-based development process because it is easier than the other methods.
- How hard is it to learn Docker?
> It's not difficult to understand Docker. It takes about ten minutes to read this [article](https://zhuanlan.zhihu.com/p/19902938).
This can save you an hour of installing and configuring various development tools, as well as the need for new installations when switching machines. Don't forget that PaddlePaddle updates may lead to the need for new development tools. Not to mention the benefits of simplifying the recurrence of problems.
- Can I use an IDE?
> Of course, because the source code is on the machine. By default, the IDE calls a program like make to compile the source code. We only need to configure the IDE to call the Docker command to compile the source code.
Many PaddlePaddle developers use Emacs. They add two lines to their `~/.emacs` configuration file.
`global-set-key "\C-cc" 'compile`
`setq compile-command "docker run --rm -it -v $(git rev-parse --show- Toplevel): /paddle paddle:dev"`
You can start the compilation by pressing `Ctrl-C` and` c`.
- Can I compile in parallel?
> Yes. Our Docker image runs a [Bash script](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/paddle/scripts/paddle_build.sh). This script calls `make -j$(nproc)` to start as many processes as the CPU cores to compile in parallel.
- Docker needs sudo?
> If you develop with your own computer, you will naturally have admin privileges (sudo). If you are developing from a public computer, you need to ask the administrator to install and configure Docker. In addition, the PaddlePaddle project is working hard to support other container technologies that don't require sudo, such as rkt.
- Is compiling slow on Windows/MacOS?
> Docker runs on both Windows and MacOS. However, it is actually running on a Linux virtual machine. It may be necessary to pay attention to allocate more CPU and memory to this virtual machine to ensure efficient compilation. Please refer to [issue627](https://github.com/PaddlePaddle/Paddle/issues/627) for details.
- Not enough disk?
> In the example in this article, the `--rm` parameter is used in the `docker run`command to ensure that containers after the end of the run are not retained on disk. You can use the `docker ps -a` command to see containers that are stopped but not deleted. The `docker build` command sometimes produces some intermediate results, an image with no name, and it also occupies the disk. You can refer to this [article](https://zaiste.net/removing_docker_containers/) to clean up this content.
- Can't I open `http://localhost:8888/` when using the book under DockerToolbox?
> You need to replace localhost with virtual machine ip. Generally type this in the browser: `http://192.168.99.100:8888/`
- After the pip install gpu version of PaddlePaddle runing, the SegmentFault appears as follows:
@ 0x7f6c8d214436 paddle::platform::EnforceNotMet::EnforceNotMet()
@ 0x7f6c8dfed666 paddle::platform::GetCUDADeviceCount()
@ 0x7f6c8d2b93b6 paddle::framework::InitDevices()
> The main reason for this problem is that your graphics card driver is lower than the corresponding CUDA version. Please ensure that your graphics card driver supports the CUDA version used.
- `Fatal Python error: PyThreadState_Get: no current thread running` error occurs when importing paddle.fluid after installing PaddlePaddle on MacOS.
- For Python2.7.x (install by brew): Please use `export LD_LIBRARY_PATH=/usr/local/Cellar/python@2/2.7.15_1/Frameworks/Python.framework/Versions/2.7 && export DYLD_LIBRARY_PATH=/usr/ Local/Cellar/python@2/2.7.15_1/Frameworks/Python.framework/Versions/2.7`
- For Python2.7.x (install by Python.org): Please use `export LD_LIBRARY_PATH=/Library/Frameworks/Python.framework/Versions/2.7 && export DYLD_LIBRARY_PATH=/Library/Frameworks/Python.framework/Versions/2.7`
- For Python3.5.x (install by Python.org): Please use `export LD_LIBRARY_PATH=/Library/Frameworks/Python.framework/Versions/3.5/ && export DYLD_LIBRARY_PATH=/Library/Frameworks/Python.framework/Versions/3.5 /`
- Use customized openblas under MACOS. See issue for details:
>[ISSUE 13217](https://github.com/PaddlePaddle/Paddle/issues/13721)
- Swig has been installed but there is still a problem that swig can't find. See issue for details:
>[ISSUE 13759](https://github.com/PaddlePaddle/Paddle/issues/13759)
- The question "target pattern contain no '%'." appears. See issue for details:
>[ISSUE 13806](https://github.com/PaddlePaddle/Paddle/issues/13806)
doc/fluid/beginners_guide/install/Tables.md
浏览文件 @ 2be25c70
...@@ -363,7 +363,8 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。 ...@@ -363,7 +363,8 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。
<a name="ciwhls-release"></a> <a name="ciwhls-release"></a>
</br></br> </br></br>
## **多版本whl包列表-v1.2**
## **多版本whl包列表-Release**
<p align="center"> <p align="center">
<table> <table>
......
doc/fluid/beginners_guide/install/Tables_en.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/beginners_guide/install/compile/compile_CentOS.md
浏览文件 @ 2be25c70
...@@ -80,7 +80,7 @@ ...@@ -80,7 +80,7 @@
`cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` `cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release`
> 我们目前不支持CentOS下GPU版本PaddlePaddle的编译 > 我们目前不支持CentOS下使用Docker编译GPU版本的PaddlePaddle
9. 执行编译： 9. 执行编译：
...@@ -171,9 +171,9 @@ ...@@ -171,9 +171,9 @@
- `cd Paddle` - `cd Paddle`
8. 切换到较稳定release分支下进行编译(从1.2.0分支开始支持python3.6及3.7版本)： 8. 切换到较稳定release分支下进行编译(从1.2分支开始支持python3.6及3.7版本)：
`git checkout release/1.2.0` `git checkout release/1.2`
9. 并且请创建并进入一个叫build的目录下： 9. 并且请创建并进入一个叫build的目录下：
......
doc/fluid/beginners_guide/install/compile/compile_CentOS_en.md 0 → 100644
浏览文件 @ 2be25c70
***
# **Compile under CentOS from Source Code**
This instruction will show you how to compile PaddlePaddle on a 64-bit desktop or laptop and CentOS. The Centos systems we support must meet the following requirements:
* CentOS 7 / 6 (this involves whether the related tools can be installed normally)
## Determine which version to compile
* **Only PaddlePaddle for CPU is supported.**
## Choose a compilation method
We provide two compilation methods under the CentOS system:
* Docker source code compilation (the CentOS 6 / 7 GPU version is not supported) (this image already contains python2.7, python3.6, python3.7 environment)
* Direct native source code compilation (does not support all versions of CentOS 6 and GPU versions of CentOS 7)
We recommend using **Docker for compilation** because we are installing both the tools and the configuration in a Docker image. This way, if you encounter problems, others can reproduce the problem to help. In addition, for developers accustomed to using Windows and MacOS, there is no need to configure a cross-compilation environment using Docker. It should be emphasized that Docker does not virtualize any hardware. The compiler tools running in the Docker container are actually running directly on the native CPU and operating system. The performance is the same as installing the compiler on the machine.
Also for those who can't install Docker for a variety of reasons, we also provide a way to **compile directly from sources**, but since the situation on host machine is more complicated, we only support specific systems.
### ***Compile with Docker***
In order to better use Docker and avoid problems, we recommend using **the highest version of Docker**. For details on **installing and using Docker**, please refer to the [official Docker documentation](https://docs.docker.com/install/).
Once you have **properly installed Docker**, you can start **compiling PaddlePaddle with Docker**:
1. First select the path where you want to store PaddlePaddle, then use the following command to clone PaddlePaddle's source code from github to a folder named Paddle in the local current directory:
`git clone https://github.com/PaddlePaddle/Paddle.git`
2. Go to the Paddle directory: `cd Paddle`
3. Take advantage of the image we provided (with this command you don't have to download the image in advance):
`docker run --name paddle-test -v $PWD:/paddle --network=host -it` `hub.baidubce.com/paddlepaddle/paddle:latest-dev /bin/bash`
> `--name paddle-test` names the Docker container you created as paddle-test, `-v $PWD:/paddle` mounts the current directory to the /paddle directory in the Docker container (the PWD variable in Linux will expand to the current [Absolute path](https://baike.baidu.com/item/%E7%BB%9D%E5%AF%B9%E8%B7%AF%E5%BE%84/481185)), `-it` keeps interacting with the host, `hub.baidubce.com/paddlepaddle/paddle` creates a Docker container with an image called `hub.baidubce.com/paddlepaddle/paddle:latest-dev`, /bin/bash enters the container After starting the `/bin/bash` command.
4. After entering Docker, go to the paddle directory: `cd paddle`
5. Switch to a more stable version to compile:
`git checkout v1.1`
6. Create and enter the /paddle/build path:
`mkdir -p /paddle/build && cd /paddle/build`
7. Use the following command to install the dependencies: (For Python3: Please select the pip for the python version you wish to use, such as pip3.5, pip3.6)
For Python2: pip install protobuf==3.1.0
For Python3: pip3.5 install protobuf==3.1.0
> Install protobuf 3.1.0
`apt install patchelf`
> Installing patchelf, PatchELF is a small and useful program for modifying the dynamic linker and RPATH of ELF executables.
8. Execute cmake:
> For details on the compilation options, see the [compilation options table](../Tables.html/#Compile).
* For users who need to compile the **CPU version PaddlePaddle**:
`cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release`
> We currently do not support the compilation of the GPU version PaddlePaddle under CentOS.
9. Execute compilation:
`make -j$(nproc)`
> Use multicore compilation
10. After compiling successfully, go to the `/paddle/build/python/dist` directory and find the generated `.whl` package: `cd /paddle/build/python/dist`
11. Install the compiled `.whl` package on the current machine or target machine: (For Python3: Please select the pip corresponding to the python version you wish to use, such as pip3.5, pip3.6)
For Python2: pip install (whl package name)
For Python3: pip3.5 install (whl package name)
Now that you have successfully installed PaddlePaddle using Docker, you only need to run PaddlePaddle after entering the Docker container. For more Docker usage, please refer to the [official Docker documentation](https://docs.docker.com/).
> Notes: In order to reduce the size, `vim` is not installed in PaddlePaddle Docker image by default. You can edit the code in the container after executing `apt-get install -y vim` in the container.
Congratulations, you have now completed the process of compiling PaddlePaddle using Docker.
<br/><br/>
### *Local compilation*
**Please strictly follow the order of the following instructions**
1. Check that your computer and operating system meet the compilation standards we support: `uname -m && cat /etc/*release`
2. Update the source of `yum`: `yum update`, and add the necessary yum source: `yum install -y epel-release`, and install openCV in advance
3. Install the necessary tools `bzip2` and `make`: `yum install -y bzip2 `, `yum install -y make`
4. We support compiling and installing with virtualenv. First, create a virtual environment called `paddle-venv` with the following command:
* a. Install Python-dev:
For Python2: yum install python-devel
For Python3: (Please refer to the official Python installation process)
* b. Install pip:
For Python2: yum install python-pip (please have a pip version of 9.0.1 and above)
For Python3: (Please refer to the official Python installation process, and ensure that the pip3 version 9.0.1 and above, please note that in python3.6 and above, pip3 does not necessarily correspond to the python version, such as python3.7 default only Pip3.7)
* c. (Only For Python3) set Python3 related environment variables, here is python3.5 version example, please replace with the version you use (3.6, 3.7):
1. First find the path to the Python lib using ``` find `dirname $(dirname
$(which python3))` -name "libpython3.so"``` . If it is 3.6 or 3.7, change `python3` to `python3.6` or `python3.7`, then replace [python-lib-path] in the following steps with the file path found.
2. Set PYTHON_LIBRARIES: `export PYTHON_LIBRARY=[python-lib-path]`.
3. Secondly, use ```find `dirname $(dirname
$(which python3))`/include -name "python3.5m"``` to find the path to Python Include, please pay attention to the python version, then replace the following [python-include-path] to the file path found.
4. Set PYTHON_INCLUDE_DIR: `export PYTHON_INCLUDE_DIRS=[python-include-path]`
5. Set the system environment variable path: `export PATH=[python-lib-path]:$PATH `(here replace the last two levels content of [python-lib-path] with /bin/)
* d. Install the virtual environment `virtualenv` and `virtualenvwrapper` and create a virtual environment called `paddle-venv`: (please note the pip3 commands corresponding to the python version, such as pip3.6, pip3.7)
1. `pip install virtualenv` or `pip3 install virtualenv`
2. `Pip install virtualenvwrapper` or `pip3 install virtualenvwrapper`
3. Find `virtualenvwrapper.sh`: `find / -name virtualenvwrapper.sh` (please find the corresponding Python version of `virtualenvwrapper.sh`)
4. See the installation method in `virtualenvwrapper.sh`: `cat vitualenvwrapper.sh`
5. Install `virtualwrapper`
6. Create a virtual environment called `paddle-venv`: `mkvirtualenv paddle-venv`
5. Enter the virtual environment: `workon paddle-venv`
6. Before **executing the compilation**, please confirm that the related dependencies mentioned in the [compile dependency table](../Tables.html/#third_party) are installed in the virtual environment:
* Here is the installation method for `patchELF`. Other dependencies can be installed using `yum install` or `pip install`/`pip3 install` followed by the name and version:
`yum install patchelf`
> Users who can't use apt installation can refer to patchElF [github official documentation](https://gist.github.com/ruario/80fefd174b3395d34c14).
7. Put the PaddlePaddle source cloned in the Paddle folder in the current directory and go to the Paddle directory:
- `git clone https://github.com/PaddlePaddle/Paddle.git`
- `cd Paddle`
8. Switch to a more stable release branch for compilation (support for Python 3.6 and 3.7 is added from the 1.2 branch):
- `git checkout release/1.2.0`
9. And please create and enter a directory called build:
- `mkdir build && cd build`
10. Execute cmake:
> For details on the compilation options, see the [compilation options table](../Tables.html/#Compile).
* For users who need to compile the **CPU version PaddlePaddle**:
For Python2: cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release
For Python3: cmake .. -DPY_VERSION=3.5 -DPYTHON_INCLUDE_DIR=${PYTHON_INCLUDE_DIRS} \
-DPYTHON_LIBRARY=${PYTHON_LIBRARY} -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release
> If you encounter `Could NOT find PROTOBUF (missing: PROTOBUF_LIBRARY PROTOBUF_INCLUDE_DIR)`, you can re-execute the cmake command.
> Please note that the PY_VERSION parameter is replaced with the python version you need.
11. Compile with the following command:
`make -j$(nproc)`
12. After compiling successfully, go to the `/paddle/build/python/dist `directory and find the generated `.whl` package: `cd /paddle/build/python/dist`
13. Install the compiled `.whl` package on the current machine or target machine:
`Pip install (whl package name) `or `pip3 install (whl package name)`
Congratulations, now you have completed the process of compiling PaddlePaddle natively.
<br/><br/>
### ***Verify installation***
After the installation is complete, you can use `python` to enter the Python interpreter and then use `import paddle.fluid` to verify that the installation was successful.
<br/><br/>
### ***How to uninstall***
Please use the following command to uninstall PaddlePaddle (users who use Docker to install PaddlePaddle should use the following command in the container containing PaddlePaddle. Please use the corresponding version of pip):
* ***CPU version of PaddlePaddle***: `pip uninstall paddlepaddle` or `pip3 uninstall paddlepaddle`
doc/fluid/beginners_guide/install/compile/compile_MacOS.md
浏览文件 @ 2be25c70
...@@ -177,9 +177,9 @@ ...@@ -177,9 +177,9 @@
- `cd Paddle` - `cd Paddle`
7. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2.0分支开始支持) 7. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2分支开始支持)
`git checkout release/1.0.0` `git checkout release/1.2`
8. 并且请创建并进入一个叫build的目录下： 8. 并且请创建并进入一个叫build的目录下：
......
doc/fluid/beginners_guide/install/compile/compile_MacOS_en.md 0 → 100644
浏览文件 @ 2be25c70
***
# **Compile under MacOS from Source Code**
This instruction will show you how to compile PaddlePaddle on *64-bit desktops or laptops* and MacOS systems. The MacOS systems we support need to meet the following requirements:
* MacOS 10.12/10.13/10.14 (this involves whether the related tools can be installed normally)
## Determine which version to compile
* **Only PaddlePaddle for CPU is supported.**
## Choose a compilation method
Under the MacOS 10.12/10.13/10.14 system we offer 2 ways to compile:
* Docker source compilation (this image already contains python2.7, python3.6, python3.7 environment)
* Direct source code compilation
We recommend **using Docker for compilation** because we are installing both the tools and the configuration in a Docker image. This way, if you encounter problems, others can reproduce the problem to help. In addition, for developers accustomed to using Windows and MacOS, there is no need to configure a cross-compilation environment using Docker. It should be emphasized that Docker does not virtualize any hardware. The compiler tools running in the Docker container are actually running directly on the native CPU and operating system. The performance is the same as installing the compiler on the machine.
Also for those who can't install Docker for a variety of reasons, we also provide a way to **compile directly from local sources**, but since the situation on this machine is more complicated, we only support specific systems.
<br/><br/>
### ***Compile with Docker***
In order to better use Docker and avoid problems, we recommend using **the highest version of Docker**. For details on **installing and using Docker**, please refer to the [official Docker documentation](https://docs.docker.com/install/).
> Please note that running Docker on MacOS requires logging in with your dockerID, otherwise an Authenticate Failed error will occur.
Once you have **properly installed Docker**, you can start **compiling PaddlePaddle with Docker**:
1. Enter the terminal of the Mac
2. Please select the path where you want to store PaddlePaddle, and then use the following command to clone PaddlePaddle's source code from github to a folder named Paddle in the local current directory:
`git clone https://github.com/PaddlePaddle/Paddle.git`
3. Go to the Paddle directory: `cd Paddle`
4. Take advantage of the image we provided (with this command you don't have to download the image in advance):
`docker run --name paddle-test -v $PWD:/paddle --network=host -it` `hub.baidubce.com/paddlepaddle/paddle:latest-dev /bin/bash`
> --name paddle-test Name the Docker container you created as paddle-test, -v $PWD:/paddle mount the current directory to the /paddle directory in the Docker container (the PWD variable in Linux will expand to the current path's [Absolute path](https://baike.baidu.com/item/绝对路径/481185)), -it keeps interacting with the host, `hub.baidubce.com/paddlepaddle/paddle:latest-dev` creates a Docker container with a mirror named `hub.baidubce.com/paddlepaddle/paddle:latest-dev`, /bin /bash starts the /bin/bash command after entering the container.
5. After entering Docker, go to the paddle directory: `cd paddle`
6. Switch to a more stable version to compile:
`git checkout v1.1`
7. Create and enter the /paddle/build path:
`mkdir -p /paddle/build && cd /paddle/build`
8. Use the following command to install the dependencies: (For Python3: Please select the pip for the python version you wish to use, such as pip3.5, pip3.6)
For Python2: pip install protobuf==3.1.0
For Python3: pip3.5 install protobuf==3.1.0
> Install protobuf 3.1.0.
`apt install patchelf`
> Installing patchelf, PatchELF is a small and useful program for modifying the dynamic linker and RPATH of ELF executables.
9. Execute cmake:
> For details on the compilation options, see the [compilation options table](../Tables.html/#Compile).
* For users who need to compile the **CPU version PaddlePaddle**:
`cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release`
> We currently do not support the compilation of the GPU version PaddlePaddle under CentOS.
10. Execute compilation:
`make -j$(nproc)`
> Use multicore compilation
11. After compiling successfully, go to the `/paddle/build/python/dist `directory and find the generated `.whl` package: `cd /paddle/build/python/dist`
12. Install the compiled `.whl` package on the current machine or target machine: (For Python3: Please select the pip corresponding to the python version you wish to use, such as pip3.5, pip3.6)
For Python2: pip install (whl package name)
For Python3: pip3.5 install (whl package name)
Now that you have successfully installed PaddlePaddle using Docker, you only need to run PaddlePaddle after entering the Docker container. For more Docker usage, please refer to the [official Docker documentation](https://docs.docker.com/).
> Note: In order to reduce the size, `vim` is not installed in PaddlePaddle Docker image by default. You can edit the code in the container after executing `apt-get install -y vim` in the container.
Congratulations, you have now completed the process of compiling PaddlePaddle using Docker.
<br/><br/>
### ***Native compilation***
**Please strictly follow the order of the following instructions**
1. Check that your computer and operating system meet our supported compilation standards: `uname -m` and view the system version `about this Mac`. And install openCV in advance.
2. Install python and pip:
> **Please do not use the Python initially given by MacOS**, we strongly recommend that you use [Homebrew](https://brew.sh/) to install python (for Python3 please use python [official download](https://www.python.org/downloads/mac-osx/) python3.5.x, python3.6.x, python3.7.x), pip and other dependencies, This will greatly reduce the difficulty of installing and compiling.
For python2: brew install python@2
For python3: Install using Python official website
> Please note that when you have multiple pythons installed on your mac, make sure that the python you are using is the python you wish to use.
3. (Only For Python2) Set Python-related environment variables:
- Use `find / -name libpython2.7.dylib` to find your current python `libpython2.7.dylib` path and use `export LD_LIBRARY_PATH=[libpython2.7.dylib path] && export DYLD_LIBRARY_PATH=[libpython2.7.dylib to the top two directories of the directory]`
4. (Only For Python3) Set Python-related environment variables:
- a. First use
```find `dirname $(dirname
$(which python3))` -name "libpython3.*.dylib"```
to find the path to Pythonlib (the first one it prompts is the dylib path for the python you need to use), then (below [python-lib-path] is replaced by finding the file path)
- b. Set PYTHON_LIBRARIES: `export PYTHON_LIBRARY=[python-lib-path]`
- c. Secondly use the path to find PythonInclude (usually find the above directory of [python-lib-path] as the include of the same directory, then find the path of python3.x or python2.x in the directory), then (the [python-include-path] in the following commands should be replaced by the path found here)
- d. Set PYTHON_INCLUDE_DIR: `export PYTHON_INCLUDE_DIRS=[python-include-path]`
- e. Set the system environment variable path: `export PATH=[python-bin-path]:$PATH` (here [python-bin-path] is the result of replacing the last two levels of [python-lib-path] with the path after /bin/ )
- f. Set the dynamic library link: `export LD_LIBRARY_PATH=[python-ld-path]` and `export DYLD_LIBRARY_PATH=[python-ld-path]` (here [python-ld-path] is the [python-bin-path]'s parent directory )
- g. (Optional) If you are compiling PaddlePaddle on MacOS 10.14, make sure you have the [appropriate version](http://developer.apple.com/download) of Xcode installed.
5. Before **compilation**, please confirm that the relevant dependencies mentioned in the [compilation dependency table](h../Tables.html/#third_party) are installed in your environment, otherwise we strongly recommend using `Homebrew` to install related dependencies.
> Under MacOS, if you have not modified or installed the dependencies mentioned in the "Compile Dependency Table", you only need to use `pip` to install `numpy`, `protobuf`, `wheel`, use `homebrew` to install `wget`, `swig`,then install `cmake`.
- a. Here is a special description of the installation of **CMake**:
Since we are using CMake3.4 please follow the steps below:
1. Download the CMake image from the [official CMake website](https://cmake.org/files/v3.4/cmake-3.4.3-Darwin-x86_64.dmg) and install it.
2. Enter `sudo "/Applications/CMake.app/Contents/bin/cmake-gui" –install` in the console
- b. If you do not want to use the system default blas and want to use your own installed OPENBLAS please read [FAQ](../FAQ.html/#OPENBLAS)
6. Put the PaddlePaddle source cloned in the Paddle folder in the current directory and go to the Paddle directory:
- `git clone https://github.com/PaddlePaddle/Paddle.git`
- `cd Paddle`
7. Switch to a more stable release branch to compile: (Note that python 3.6, python 3.7 version are supported from the 1.2 branch)
`git checkout release/1.2`
8. And please create and enter a directory called build:
`mkdir build && cd build`
9. Execute cmake:
> For details on the compilation options, see the [compilation options table](../Tables.html/#Compile).
* For users who need to compile the **CPU version PaddlePaddle**:
For Python2: cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release
For Python3: cmake .. -DPY_VERSION=3.5 -DPYTHON_INCLUDE_DIR=${PYTHON_INCLUDE_DIRS} \-DPYTHON_LIBRARY=${PYTHON_LIBRARY} -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release
> ``-DPY_VERSION=3.5`` Please change to the Python version of the installation environment.
10. Compile with the following command:
`make -j4`
11. After compiling successfully, go to the `/paddle/build/python/dist `directory and find the generated `.whl` package: `cd /paddle/build/python/dist`
12. Install the compiled `.whl` package on the current machine or target machine:
`pip install (whl package name)` or `pip3 install (whl package name)`
> If you have multiple python environments and pips installed on your computer, please see the [FAQ](../Tables.html/#MACPRO).
Congratulations, now you have completed the process of compiling PaddlePaddle using this machine.
<br/><br/>
### ***Verify installation***
After the installation is complete, you can use `python` to enter the Python interpreter and then use `import paddle.fluid` to verify that the installation was successful.
<br/><br/>
### ***How to uninstall***
Please use the following command to uninstall PaddlePaddle (users who use Docker to install PaddlePaddle should use the following command in the container containing PaddlePaddle. Please use the corresponding version of pip):
* ***CPU version of PaddlePaddle***: `pip uninstall paddlepaddle` or `pip3 uninstall paddlepaddle`
doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md
浏览文件 @ 2be25c70
...@@ -54,9 +54,9 @@ ...@@ -54,9 +54,9 @@
4. 进入Docker后进入paddle目录下：`cd paddle` 4. 进入Docker后进入paddle目录下：`cd paddle`
5. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2.0分支开始支持) 5. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2分支开始支持)
`git checkout release/1.2.0` `git checkout release/1.2`
6. 创建并进入/paddle/build路径下： 6. 创建并进入/paddle/build路径下：
......
doc/fluid/beginners_guide/install/compile/fromsource_en.rst 0 → 100644
浏览文件 @ 2be25c70
==============================
**Compile From Source Code**
==============================
You can also choose to compile and install PaddlePaddle in the way of source code compilation. However, due to the diversity of the native environment, complicated problems may occur when compiling the source code, which may cause your installation to fail. In order to ensure your smooth installation, it is recommended that you prefer the normal installation method.
.. toctree::
compile_Ubuntu_en.md
compile_CentOS_en.md
compile_MacOS_en.md
compile_Windows_en.md
doc/fluid/beginners_guide/install/index_cn.rst
浏览文件 @ 2be25c70
========== ==========
安装说明 安装说明
========== ==========
本说明将指导您在64位台式机或笔记本电脑上, 使用Python2.7或者Python3.5编译和安装PaddlePaddle，目前PaddlePaddle支持以下环境： 本说明将指导您在64位台式机或笔记本电脑上编译和安装PaddlePaddle
PaddlePaddle目前支持的Python版本包括：Python 2.7-3.7
PaddlePaddle目前支持以下环境：
* *Ubuntu 14.04 /16.04 /18.04* * *Ubuntu 14.04 /16.04 /18.04*
* *CentOS 7 / 6* * *CentOS 7 / 6*
......
doc/fluid/beginners_guide/install/install_CentOS_en.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/beginners_guide/install/install_MacOS_en.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/beginners_guide/install/install_Ubuntu_en.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/beginners_guide/install/install_Windows_en.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
doc/fluid/user_guides/howto/prepare_data/reader_cn.md 0 → 100644
浏览文件 @ 2be25c70
此差异已折叠。
Paddle @ 3f687765
比较 81b66db9...3f687765
Subproject commit 81b66db96c1b9c16535bf86e6167da911891e9fb Subproject commit 3f687765e6a0e00428588f776d74d5cb114ee227
book @ 64c82c57
比较 ef293450...64c82c57
Subproject commit ef2934505b87eeb516eed7d083900ec88a62fb20 Subproject commit 64c82c575ff842eaf02c62e61ec6cce78ecc0f42
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或