diff --git a/README.md b/README.md index dc02d7c7b39d036321a80218ddaa0cd8cacc92b8..4c8f0718aa2a8fd67c222364c01535ca7a3b4417 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,52 @@ # 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 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. +当一个新发布的分支被push到了Github上，Travis-CI 将会自动启动编译文档并把文档部署到服务器 + ## 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 需要Paddle Repo的python模块去编译生成API文档。但由于Paddle的python模块过于庞大，超过了Travis CI允许的最大时长，通常Travis CI将会因为超时问题失败。这是Travis上有三项作业的原因，其中两项用于构建库。当Travis缓存了这些库以后，下一次的构建将会变得非常的快。 + ## 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 `./runserver --paddle ` +## 通过PaddlePaddle.org预览文档 + +为了预览FluidDoc的文档，请按照[常规预览步骤](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md)，但请在这一步将 paddle 的路径替换为 Fluid 的路径 +`./runserver --paddle ` + + # Publish New release 1. Checkout a new release branch. The branch name should follow `release/` 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. 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. 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/` +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也应当更新相应的搜索引擎文件 + diff --git a/doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst b/doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst index 6dad245b5b0b7baa8dd2b69f368a2328cba62f0c..5c10484a7e9c52738bf2b915a8cd0a746b4bd17c 100644 --- a/doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst +++ b/doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst @@ -71,7 +71,6 @@ WITH_MKL ON/OFF │   │   ├── paddle_analysis_config.h │   │   ├── paddle_api.h │   │   ├── paddle_inference_api.h - │   │   ├── paddle_inference_pass.h │   │   └── paddle_pass_builder.h │   └── lib │   ├── libpaddle_fluid.a diff --git a/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md b/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md index 8a98954bfc8445ae38373e6dad151da25c87e0b1..462633cb1740633e6d0f6a7ee6d157c1067a1e35 100644 --- a/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md +++ b/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md @@ -26,20 +26,38 @@ NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习 cd /Paddle mkdir build cd build + # TENSORRT_ROOT为TRT的路径，默认为 /usr，根据自己需求进行改动 + # MKL 可以根据自己的需求自行打开 cmake .. \ -DWITH_FLUID_ONLY=ON \ - -DWITH_CONTRIB=OFF \ -DWITH_MKL=OFF \ -DWITH_MKLDNN=OFF \ - -DWITH_TESTING=ON \ -DCMAKE_BUILD_TYPE=Release \ - -DWITH_PYTHON=OFF + -DWITH_PYTHON=OFF \ + -DTENSORRT_ROOT=/usr \ + -DON_INFER=ON # 编译 make -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使用 @@ -97,11 +115,52 @@ void RunTensorRT(int batch_size, std::string model_dirname) { int main() { // 模型下载地址 http://paddle-inference-dist.cdn.bcebos.com/tensorrt_test/mobilenet.tar.gz - paddle::RunTensorRT(1, “./mobilenet"); + paddle::RunTensorRT(1, "./mobilenet"); 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等进行优化，能够加快模型的预测速度。 diff --git a/doc/fluid/advanced_usage/development/local_dev_guide.md b/doc/fluid/advanced_usage/development/local_dev_guide.md new file mode 100644 index 0000000000000000000000000000000000000000..02e223f7d0882f96959bd39680fc866748725daa --- /dev/null +++ b/doc/fluid/advanced_usage/development/local_dev_guide.md @@ -0,0 +1,193 @@ +# 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 。 + +## 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 ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + modified: README.md +Untracked files: + (use "git add ..." 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 ..." 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 +``` + + Attention needs to be paid：you need to add commit message to trigger CI test.The command is as follows: + +```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(）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 +``` diff --git a/doc/fluid/advanced_usage/development/submit_pr_guide.md b/doc/fluid/advanced_usage/development/submit_pr_guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d71d92e3632d323e95fa45342c822183ab844e45 --- /dev/null +++ b/doc/fluid/advanced_usage/development/submit_pr_guide.md @@ -0,0 +1,110 @@ +# 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`。 + +screen shot 2017-04-26 at 9 09 28 pm + +Switch to targeted branch: + +screen shot 2017-04-26 at 9 11 52 pm + +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. + +
+ + + +
+ +- Please click “Sign in with GitHub to agree” in CLA website.It will change into your Pull Request page after the click. + +
+ + + +
+ + +### 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. + +screen shot 2017-04-26 at 9 18 24 pm + +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. diff --git a/doc/fluid/api/api_guides/high_low_level_api.md b/doc/fluid/api/api_guides/high_low_level_api.md deleted file mode 100644 index d95a2f89eb6913ed0b23ce7eaf0613ec44529356..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/high_low_level_api.md +++ /dev/null @@ -1,15 +0,0 @@ -## 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课程进行深度学习基础知识学习的初级用户。 diff --git a/doc/fluid/api/api_guides/index.rst b/doc/fluid/api/api_guides/index.rst deleted file mode 100755 index fe96d6e912b872d92c3e36f7b464de496d27d098..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -=========== -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 diff --git a/doc/fluid/api/api_guides/low_level/cluster/cluster_train_data_cn.rst b/doc/fluid/api/api_guides/low_level/cluster/cluster_train_data_cn.rst deleted file mode 100644 index c4c7e22958bd337b54658e632c37f421b0b66536..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/cluster/cluster_train_data_cn.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _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 `_ 命令将训练数据切分成多个小文件： - - .. 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 表达式 `_，一般可以用通配符来表示。 diff --git a/doc/fluid/api/api_guides/low_level/distributed/async_training.rst b/doc/fluid/api/api_guides/low_level/distributed/async_training.rst deleted file mode 100644 index a36fd2cd185c36d50b5437fb109a28dd686f43c0..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/distributed/async_training.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _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则为异步训练 diff --git a/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst b/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst deleted file mode 100644 index b6b5102636f27141911c232d05317b1f9b8a1bed..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _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更新方式。 diff --git a/doc/fluid/api/api_guides/low_level/distributed/index.rst b/doc/fluid/api/api_guides/low_level/distributed/index.rst deleted file mode 100644 index 5a570461e867b36aaee2f0795883aff900994ac3..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/distributed/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -============= -分布式训练 -============= - -.. toctree:: - :maxdepth: 1 - - async_training.rst - cpu_train_best_practice.rst - large_scale_sparse_feature_training.rst - diff --git a/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst b/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst deleted file mode 100644 index 7b2994f15a9de769507a4c16586b4c0df6cbf0ae..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _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自身对应部分的参数 diff --git a/doc/fluid/api/api_guides/low_level/distributed/sync_training.rst b/doc/fluid/api/api_guides/low_level/distributed/sync_training.rst deleted file mode 100644 index b64c37ac8e52fdf5b7e4c149c55d37f73fcbe36f..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/distributed/sync_training.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _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和端口号 diff --git a/doc/fluid/api/api_guides/low_level/executor.rst b/doc/fluid/api/api_guides/low_level/executor.rst deleted file mode 100644 index 5617d14c143e17f59042eff2509eda024adefd40..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/executor.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _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 `_ , API Reference 请参考 -:ref:`api_fluid_Executor` 。 diff --git a/doc/fluid/api/api_guides/low_level/inference.rst b/doc/fluid/api/api_guides/low_level/inference.rst deleted file mode 100644 index 2a61fb307534ec5b5bbc4b89219be9fc31961430..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/inference.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _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` 获得预测结果。 diff --git a/doc/fluid/api/api_guides/low_level/layers/activations.rst b/doc/fluid/api/api_guides/low_level/layers/activations.rst deleted file mode 100644 index 615e364d525b483adcdcad89272a06fc5ade70e7..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/activations.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _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) diff --git a/doc/fluid/api/api_guides/low_level/layers/control_flow.rst b/doc/fluid/api/api_guides/low_level/layers/control_flow.rst deleted file mode 100644 index c2192b498cb335c29e1e56dedc1c248cada47198..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/control_flow.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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` diff --git a/doc/fluid/api/api_guides/low_level/layers/conv.rst b/doc/fluid/api/api_guides/low_level/layers/conv.rst deleted file mode 100644 index 018c3d56ef96f6101f43b82b5e68ced24ce4942c..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/conv.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _api_guide_conv: - -##### -卷积 -##### - -卷积有两组输入：特征图和卷积核，依据输入特征和卷积核的形状、Layout不同、计算方式的不同，在Fluid里，有针对变长序列特征的一维卷积，有针对定长图像特征的二维(2D Conv)、三维卷积(3D Conv)，同时也有卷积计算的逆向过程，下面先介绍Fluid里的2D/3D卷积，再来介绍序列卷积。 - - -2D/3D卷积 -============== - -1. 卷积输入参数： ---------------------- - -卷积需要依据滑动步长(stride)、填充长度(padding)、卷积核窗口大小(filter size)、分组数(groups)、扩张系数(dilation rate)来决定如何计算。groups最早在 `AlexNet `_ 中引入, 可以理解为将原始的卷积分为独立若干组卷积计算。 - - **注意**: 同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 `_ ， -该卷积相比上述普通序列卷积可以减少参数。 - - -- API汇总: - - :ref:`api_fluid_layers_sequence_conv` - - :ref:`api_fluid_layers_row_conv` diff --git a/doc/fluid/api/api_guides/low_level/layers/data_feeder.rst b/doc/fluid/api/api_guides/low_level/layers/data_feeder.rst deleted file mode 100644 index 770116dfb99fcef42184393f77a23d3a61134cc8..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/data_feeder.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _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 diff --git a/doc/fluid/api/api_guides/low_level/layers/data_in_out.rst b/doc/fluid/api/api_guides/low_level/layers/data_in_out.rst deleted file mode 100644 index 9d0a2521ee23615ce614ec4066f16b3a2b3533bf..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/data_in_out.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _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 diff --git a/doc/fluid/api/api_guides/low_level/layers/detection.rst b/doc/fluid/api/api_guides/low_level/layers/detection.rst deleted file mode 100644 index f277c27ceaa5e1c5649f5212d377442e3fd73860..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/detection.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _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 `_ 是典型的两阶段目标检测器，相较于传统提取区域的方法，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 `_ 全称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` - - diff --git a/doc/fluid/api/api_guides/low_level/layers/index.rst b/doc/fluid/api/api_guides/low_level/layers/index.rst deleted file mode 100644 index df9f56a9754b0f771ec922e4c08c5c5c7c70316f..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -============= -神经网络层 -============= - -.. 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 - diff --git a/doc/fluid/api/api_guides/low_level/layers/learning_rate_scheduler.rst b/doc/fluid/api/api_guides/low_level/layers/learning_rate_scheduler.rst deleted file mode 100644 index c617c44958a2f597f4ba3c20f182c6c5dd3e9ad3..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/learning_rate_scheduler.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _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》 `_ 。 - 相关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》 `_ 。 - 相关API Reference请参考 :ref:`api_fluid_layers_append_LARS` - diff --git a/doc/fluid/api/api_guides/low_level/layers/loss_function.rst b/doc/fluid/api/api_guides/low_level/layers/loss_function.rst deleted file mode 100644 index 5802fc4b934183572279f2d5d0d260eda5346710..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/loss_function.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _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） `_ 是分类问题中使用最为广泛的损失函数，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） `_ 和 `层级 sigmoid `_ 。 - -* 噪声对比估计通过将多分类问题转化为学习分类器来判别数据来自真实分布和噪声分布的二分类问题，基于二分类来进行极大似然估计，避免在全类别空间计算归一化因子从而降低了计算复杂度。 -* 层级 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） `_ 是一种常用的模型方法，其使用句子级别的似然概率，序列中不同位置的标签不再是条件独立，能够有效解决标记偏置问题。Paddle Fluid 中提供了 CRF 对应损失函数的支持，API Reference 请参考 :ref:`api_fluid_layers_linear_chain_crf`。 -* 时序分类（Temporal Classification）问题，需要对未分割的序列进行标注，如语音识别。对于这种时序分类问题，`CTC（Connectionist Temporal Classification） `_ 损失函数不需要对齐输入数据及标签，可以进行端到端的训练，Paddle Fluid 提供了 warpctc 的接口来计算相应的损失，API Reference 请参考 :ref:`api_fluid_layers_warpctc`。 - -排序 -==== - -`排序问题 `_ 可以使用 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 diff --git a/doc/fluid/api/api_guides/low_level/layers/math.rst b/doc/fluid/api/api_guides/low_level/layers/math.rst deleted file mode 100644 index 6ae121ccd5540b3f9f7a9df5f9815de1889c06df..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/math.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. _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` diff --git a/doc/fluid/api/api_guides/low_level/layers/pooling.rst b/doc/fluid/api/api_guides/low_level/layers/pooling.rst deleted file mode 100644 index de4a1bd82cc144b6237d4ec171576d93b1d8aaf9..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/pooling.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _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的解释请参考\ `论文 `__ - -- ``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 diff --git a/doc/fluid/api/api_guides/low_level/layers/sequence.rst b/doc/fluid/api/api_guides/low_level/layers/sequence.rst deleted file mode 100644 index 455e8e9b51c4196a2adc450a0f14e87512381480..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/sequence.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _api_guide_sequence: - -######## -序列 -######## - -在深度学习领域许多问题涉及到对 `序列（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` - diff --git a/doc/fluid/api/api_guides/low_level/layers/sparse_update.rst b/doc/fluid/api/api_guides/low_level/layers/sparse_update.rst deleted file mode 100644 index ae49a70c2bc7c3dac330deacef9637e888884ee6..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/sparse_update.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _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 `_ 。默认为False。 - -- :code:`is_distributed` ： 标志是否是用在分布式的场景下。一般大规模稀疏更新（embedding的第0维维度很大，比如几百万以上）才需要设置。具体可以参考大规模稀疏的API guide :ref:`api_guide_async_training` 。默认为False。 - -- API汇总: - - :ref:`api_fluid_layers_embedding` diff --git a/doc/fluid/api/api_guides/low_level/layers/tensor.rst b/doc/fluid/api/api_guides/low_level/layers/tensor.rst deleted file mode 100644 index a0549fcb84fe537820b935a311071c78d32f8733..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/layers/tensor.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. _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 diff --git a/doc/fluid/api/api_guides/low_level/memory_optimize.rst b/doc/fluid/api/api_guides/low_level/memory_optimize.rst deleted file mode 100644 index f820d2e48327ef623bc841df3aa314cf2148d9e9..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/memory_optimize.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _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` 才会进行显存复用，并且在分析结束后，会打印出所有显存复用相关的调试信息。 diff --git a/doc/fluid/api/api_guides/low_level/metrics.rst b/doc/fluid/api/api_guides/low_level/metrics.rst deleted file mode 100644 index 90531d61635a7f35dd2101e554bdbaaa0fe31a17..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/metrics.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _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 `_ 。 - - API Reference 请参考 :ref:`api_fluid_metrics_Recall` - -- AUC: :code:`Area Under Curve`， 适用于二分类的分类模型评估，用来计算 `ROC曲线的累积面积 `_。:code:`Auc` 通过python计算实现，如果关注性能，可以使用 :code:`fluid.layers.auc` 代替。 - - API Reference 请参考 :ref:`api_fluid_metrics_Auc` - -- 平均准确度: :code:`Average Precision` ，常用在Faster R-CNN和SSD等物体检测任务中。在不同召回条件下，计算了准确率的平均值，具体可以参考文档 `Average-precision `_ 和 `SSD: Single Shot MultiBox Detector `_。 - - 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 `_ 。 - - API Reference 请参考 :ref:`api_fluid_metrics_ChunkEvaluator` - - -生成任务评价 ------------------- -生成任务会依据输入直接产生输出。对应NLP任务中(比如语音识别)，则生成新字符串。评估生成字符串和目标字符串之间距离的方法也有多种，比如多分类评估方法，而另外一种常用的方法叫做编辑距离。 - -- 编辑距离: :code:`EditDistance` ，用来衡量两个字符串的相似度。可以参考文档 `Edit_distance `_。 - - API Reference 请参考 :ref:`api_fluid_metrics_EditDistance` - diff --git a/doc/fluid/api/api_guides/low_level/model_save_reader.rst b/doc/fluid/api/api_guides/low_level/model_save_reader.rst deleted file mode 100644 index 8edae985082970cc94c867bc7802e7714af90670..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/model_save_reader.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _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`。 diff --git a/doc/fluid/api/api_guides/low_level/nets.rst b/doc/fluid/api/api_guides/low_level/nets.rst deleted file mode 100644 index 38c1b24a785e18ae3929d450c30d81584ce302f9..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/nets.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _api_guide_nets: - -########### -复杂网络 -########### - -在处理复杂功能时，我们通常需要写大量的代码来构建复杂的 `神经网络 `_ 。 -因此，为了方便用户更加容易地搭建复杂网络模型，我们提供了一些比较常用的基本函数模块，以此来简化用户的代码量，从而降低开发成本。 -这些模块通常是由细粒度的函数根据一定的逻辑拼接组合而成，实现代码请参考 `nets.py `_ 。 - -1.simple_img_conv_pool ----------------------- - -:code:`simple_img_conv_pool` 是由 :ref:`api_fluid_layers_conv2d` 与 :ref:`api_fluid_layers_pool2d` 串联而成。 -该模块在图像分类模型中广泛使用，比如应用在 `MNIST `_ 数字分类的问题。 - -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 `_ 。 - -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` 串联而成。 -该模块在 `自然语言处理 `_ 以及 `语音识别 `_ 等领域均有广泛应用， -比如 `文本分类模型 `_ , -`TagSpace `_ 以及 `Multi-view Simnet `_ 等模型。 - -API Reference 请参考 :ref:`api_fluid_nets_sequence_conv_pool` - - -4.glu ------ -:code:`glu` 全称 Gated Linear Units， 来源于论文 `Language Modeling with Gated Convolutional Networks `_ ，由 :ref:`api_fluid_layers_split` ， :ref:`api_fluid_layers_sigmoid` 和 :ref:`api_fluid_layers_elementwise_mul` 组成。 -它会把输入数据均分为2等份，并对第二部分求 `Sigmoid `_ , 然后再与第一部分数据求点乘得到输出。 - -API Reference 请参考 :ref:`api_fluid_nets_glu` - - -5.scaled_dot_product_attention ------------------------------- -:code:`scaled_dot_product_attention` 来源于论文 `Attention Is All You Need `_ ，主要是由 :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 - -该模块广泛使用在 `机器翻译 `_ 的模型中，比如 `Transformer `_ 。 - -API Reference 请参考 :ref:`api_fluid_nets_scaled_dot_product_attention` - diff --git a/doc/fluid/api/api_guides/low_level/optimizer.rst b/doc/fluid/api/api_guides/low_level/optimizer.rst deleted file mode 100644 index e068bd4801081e129ca24a9208699f1f0d5bf927..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/optimizer.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _api_guide_optimizer: - -########### -优化器 -########### - -神经网络最终是一个 `最优化问题 `_ ， -在经过 `前向计算和反向传播 `_ 后， -:code:`Optimizer` 使用反向传播梯度，优化神经网络中的参数。 - -1.SGD/SGDOptimizer ------------------- - -:code:`SGD` 是实现 `随机梯度下降 `_ 的一个 :code:`Optimizer` 子类，是 `梯度下降 `_ 大类中的一种方法。 -当需要训练大量样本的时候，往往选择 :code:`SGD` 来使损失函数更快的收敛。 - -API Reference 请参考 :ref:`api_fluid_optimizer_SGDOptimizer` - - -2.Momentum/MomentumOptimizer ----------------------------- - -:code:`Momentum` 优化器在 :code:`SGD` 基础上引入动量，减少了随机梯度下降过程中存在的噪声问题。 -用户在使用时可以将 :code:`ues_nesterov` 参数设置为False或True，分别对应传统 `Momentum(论文4.1节) -`_ 算法和 `Nesterov accelerated gradient(论文4.2节) -`_ 算法。 - -API Reference 请参考 :ref:`api_fluid_optimizer_MomentumOptimizer` - - -3. Adagrad/AdagradOptimizer ---------------------------- -`Adagrad `_ 优化器可以针对不同参数样本数不平均的问题，自适应地为各个参数分配不同的学习率。 - -API Reference 请参考 :ref:`api_fluid_optimizer_AdagradOptimizer` - - -4.RMSPropOptimizer ------------------- -`RMSProp优化器 `_ ，是一种自适应调整学习率的方法， -主要解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。 - -API Reference 请参考 :ref:`api_fluid_optimizer_RMSPropOptimizer` - - - -5.Adam/AdamOptimizer --------------------- -`Adam `_ 的优化器是一种自适应调整学习率的方法， -适用于大多非 `凸优化 `_ 、大数据集和高维空间的场景。在实际应用中，:code:`Adam` 是最为常用的一种优化方法。 - -API Reference 请参考 :ref:`api_fluid_optimizer_AdamOptimizer` - - - -6.Adamax/AdamaxOptimizer ------------------------- - -`Adamax `_ 是 :code:`Adam` 算法的一个变体，对学习率的上限提供了一个更简单的范围，使学习率的边界范围更简单。 - -API Reference 请参考 :ref:`api_fluid_optimizer_AdamaxOptimizer` - - - -7.DecayedAdagrad/ DecayedAdagradOptimizer -------------------------------------------- - -`DecayedAdagrad `_ 优化器，可以看做是引入了衰减速率的 :code:`Adagrad` 算法，解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。 - -API Reference 请参考 :ref:`api_fluid_optimizer_DecayedAdagrad` - - - - -8. Ftrl/FtrlOptimizer ----------------------- - -`FtrlOptimizer `_ 优化器结合了 `FOBOS算法 `_ 的高精度与 `RDA算法 -`_ 的稀疏性，是目前效果非常好的一种 `Online Learning `_ 算法。 - -API Reference 请参考 :ref:`api_fluid_optimizer_FtrlOptimizer` - - - -9.ModelAverage ------------------ - -:code:`ModelAverage` 优化器，在训练中通过窗口来累计历史 parameter，在预测时使用取平均值后的paramet，整体提高预测的精度。 - -API Reference 请参考 :ref:`api_fluid_optimizer_ModelAverage` - - diff --git a/doc/fluid/api/api_guides/low_level/parallel_executor.rst b/doc/fluid/api/api_guides/low_level/parallel_executor.rst deleted file mode 100644 index f269bc02ccb0c95581ce3656bda1e0c6e17f8128..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/parallel_executor.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _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 diff --git a/doc/fluid/api/api_guides/low_level/parameter.rst b/doc/fluid/api/api_guides/low_level/parameter.rst deleted file mode 100755 index b485fa4743e00866804917aed039b64eaddc0d01..0000000000000000000000000000000000000000 --- a/doc/fluid/api/api_guides/low_level/parameter.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. _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` diff --git a/doc/fluid/api/data/data_reader.rst b/doc/fluid/api/data/data_reader.rst index 1a35d0bbc8f9d751f49c7e1fc26feb1bcb3ae7f0..ac227a505ecc8d4a3f88252196d62298d5239ac2 100644 --- a/doc/fluid/api/data/data_reader.rst +++ b/doc/fluid/api/data/data_reader.rst @@ -1,5 +1,5 @@ ===================== -Data Reader Interface +Data Reader ===================== diff --git a/doc/fluid/api/data/dataset.rst b/doc/fluid/api/data/dataset.rst index e7c8be4452bf55e0967d750c2e624e8e316e9330..6a26f7ddc10c5f26a94cd80886fd9e3d5e4a1253 100644 --- a/doc/fluid/api/data/dataset.rst +++ b/doc/fluid/api/data/dataset.rst @@ -1,4 +1,4 @@ -Dataset +dataset ======= .. automodule:: paddle.dataset diff --git a/doc/fluid/api/index_cn.rst b/doc/fluid/api/index_cn.rst deleted file mode 100644 index 39a2028d32cfec3a1d90058a1ada5fe1fd7b44e4..0000000000000000000000000000000000000000 --- a/doc/fluid/api/index_cn.rst +++ /dev/null @@ -1,26 +0,0 @@ -============= -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 - diff --git a/doc/fluid/api/index_en.rst b/doc/fluid/api/index_en.rst index 39a2028d32cfec3a1d90058a1ada5fe1fd7b44e4..88f460f608a3a38bb2e2aea5bae6ca2ca32642e9 100644 --- a/doc/fluid/api/index_en.rst +++ b/doc/fluid/api/index_en.rst @@ -18,9 +18,10 @@ API Reference metrics.rst nets.rst optimizer.rst - param_attr.rst profiler.rst recordio_writer.rst regularizer.rst transpiler.rst + data/dataset.rst + data/data_reader.rst diff --git a/doc/fluid/api/param_attr.rst b/doc/fluid/api/param_attr.rst deleted file mode 100644 index 33035bbc7ca5c8d000adeaf1cb79806a3ea64604..0000000000000000000000000000000000000000 --- a/doc/fluid/api/param_attr.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. 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: - diff --git a/doc/fluid/api_cn/api_guides/low_level/backward.rst b/doc/fluid/api_cn/api_guides/low_level/backward.rst new file mode 100644 index 0000000000000000000000000000000000000000..1b5fd9728948be6b40414698050e2ae8df41ddb8 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/backward.rst @@ -0,0 +1,23 @@ +.. _api_guide_backward: + + +######## +反向传播 +######## + +神经网络对模型的表达能力依赖于优化算法，优化是一个不断计算梯度并调整可学习参数的过程，Fluid中的优化算法可参考 :ref:`api_guide_optimizer` 。 + +在网络的训练过程中，梯度计算分为两个步骤：前向计算与 `反向传播 `_ 。 + +- 前向计算会根据您搭建的网络结构，将输入单元的状态传递到输出单元。 + +- 反向传播借助 `链式法则 `_ ，计算两个或两个以上复合函数的导数，将输出单元的梯度反向传播回输入单元，根据计算出的梯度，调整网络的可学习参数。 + +详细实现过程可以参考阅读 `反向传导算法 `_ 。 + +在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` diff --git a/doc/fluid/api_cn/api_guides/low_level/executor.rst b/doc/fluid/api_cn/api_guides/low_level/executor.rst index 8599a759828dc41db5aa3f6a6106e7d2542926f5..4801e8b25ca0a231722a626b1ec4c5dc9ea5c510 100644 --- a/doc/fluid/api_cn/api_guides/low_level/executor.rst +++ b/doc/fluid/api_cn/api_guides/low_level/executor.rst @@ -7,14 +7,14 @@ :code:`Executor` 即 :code:`执行器` 。PaddlePaddle Fluid中有两种执行器可以选择。 :code:`Executor` 实现了一个简易的执行器，所有Operator会被顺序执行。用户可以使用 Python脚本驱动 :code:`Executor` 执行。默认情况下 :code:`Executor` 是单线程的，如果 -想使用数据并行，请参考另一个执行器， :ref:`cn_api_guide_parallel_executor` 。 +想使用数据并行，请参考另一个执行器， :ref:`api_guide_parallel_executor` 。 :code:`Executor` 的代码逻辑非常简单。建议用户在调试过程中，先使用 :code:`Executor` 跑通模型，再切换到多设备计算，甚至多机计算。 :code:`Executor` 在构造的时候接受一个 :code:`Place`， 它们可以是 :ref:`cn_api_fluid_CPUPlace` 或 :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 `_ , API Reference 请参考 :ref:`cn_api_fluid_Executor` 。 diff --git a/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst b/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst index 3bb1b424b450f3f637b16920591626d53d4b5a89..6587f6edc388ff8cb5db98287454ad7e0a0d3e30 100644 --- a/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst +++ b/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst @@ -1,4 +1,4 @@ -.. api_guide_control_flow: +.. _api_guide_control_flow: ###### 控制流 diff --git a/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst b/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst index 453a6d559b2e825cd92e52de883e7ad481a9ef71..6b4d22e1bf4055d803b1cbdb59c3b654de48d496 100644 --- a/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst +++ b/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst @@ -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 的加权和作为损失函数。 -**注意**，在定义损失函数之后为能够使用 :ref:`cn_api_guide_optimizer` 进行优化，通常需要使用 :ref:`cn_api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。 \ No newline at end of file +**注意**，在定义损失函数之后为能够使用 :ref:`api_guide_optimizer` 进行优化，通常需要使用 :ref:`cn_api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。 \ No newline at end of file diff --git a/doc/fluid/api_cn/api_guides/low_level/layers/math.rst b/doc/fluid/api_cn/api_guides/low_level/layers/math.rst index 7244b7228213b01e661a442b9f015b471ebca5c1..1379077d24d89d4dbce267ee5a864dae3deb6b97 100644 --- a/doc/fluid/api_cn/api_guides/low_level/layers/math.rst +++ b/doc/fluid/api_cn/api_guides/low_level/layers/math.rst @@ -147,12 +147,6 @@ 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 ------------------ @@ -161,26 +155,7 @@ 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 ------------------ @@ -189,19 +164,19 @@ sum API Reference 请参考 :ref:`cn_api_fluid_layers_sum` -min +elementwise_min ------------------ 对两个 :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)` 操作。 -API Reference 请参考 :ref:`cn_api_fluid_layers_max` +API Reference 请参考 :ref:`cn_api_fluid_layers_elementwise_max` matmul ------------------ diff --git a/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst b/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst index a25e4beabb691f597fa3e7fc45e8ca07f1742c1e..138bfca4cb0c5c1a11ae5de93699dc9ffc294ecd 100644 --- a/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst +++ b/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst @@ -39,7 +39,7 @@ API详细使用方法参考 :ref:`cn_api_fluid_layers_embedding` ，以下是一 - :code:`is_sparse` ： 反向计算的时候梯度是否为sparse tensor。如果不设置，梯度是一个 `LodTensor `_ 。默认为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汇总: - :ref:`cn_api_fluid_layers_embedding` diff --git a/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst b/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst index b0ed7ef10a8b580e6e685e539769d9113c0c8f41..d14e19b48e678faafd5c88bf108053dcd0ebb894 100644 --- a/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst +++ b/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst @@ -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介绍 ==================== -- :code:`fluid.io.save_vars`：通过执行器（:ref:`cn_api_guide_executor`）保存变量到指定的目录中。保存变量的方式有两种： +- :code:`fluid.io.save_vars`：通过执行器（:ref:`api_guide_executor`）保存变量到指定的目录中。保存变量的方式有两种： 1）通过接口中的 :code:`vars` 指定需要保存的变量列表。 @@ -33,7 +33,7 @@ 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介绍 ==================== @@ -56,4 +56,4 @@ 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`。 diff --git a/doc/fluid/api_cn/api_guides/low_level/program.rst b/doc/fluid/api_cn/api_guides/low_level/program.rst new file mode 100644 index 0000000000000000000000000000000000000000..cbc307597a84fcf645169426a2e64f03f606b493 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/program.rst @@ -0,0 +1,81 @@ +.. _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 `_ 表示。 + + + + +========= +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` diff --git a/doc/fluid/api_cn/fluid_cn.rst b/doc/fluid/api_cn/fluid_cn.rst index 2bf0c08ad190f856d1f05f0417f5fd189fa3b3c9..a358254fc61ccc9bdcacded392dbec9498d010c6 100644 --- a/doc/fluid/api_cn/fluid_cn.rst +++ b/doc/fluid/api_cn/fluid_cn.rst @@ -9,7 +9,7 @@ AsyncExecutor ------------------------------- -.. py:function:: paddle.fluid.AsyncExecutor(place=None) +.. py:class:: paddle.fluid.AsyncExecutor(place=None) Python中的异步执行器。AsyncExecutor利用多核处理器和数据排队的强大功能，使数据读取和融合解耦，每个线程并行运行。 @@ -122,8 +122,9 @@ str类型。在 ``ParallelExecutor`` 中，存在三种定义 *loss@grad* 的方 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 DataFeedDesc ------------------------------- -.. py:function:: paddle.fluid.DataFeedDesc(proto_file) +.. py:class:: paddle.fluid.DataFeedDesc(proto_file) 数据描述符，描述输入训练数据格式。 @@ -324,7 +325,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 - **proto_file** (string) - 包含数据feed中描述的磁盘文件 -.. py:method:: set_batch_size(self, batch_size) +.. py:method:: set_batch_size(batch_size) 设置batch size，训练期间有效 @@ -339,7 +340,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 data_feed = fluid.DataFeedDesc('data.proto') 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，仅在训练期间有效。 @@ -360,7 +361,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 默认情况下，所有slot都是稀疏的 -.. py:method:: set_use_slots(self, use_slots_name) +.. py:method:: set_use_slots(use_slots_name) 设置一个特定的slot是否用于训练。一个数据集包含了很多特征，通过这个函数可以选择哪些特征将用于指定的模型。 @@ -380,7 +381,7 @@ DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含 默认值不用于所有slot -.. py:method:: desc(self) +.. py:method:: desc() 返回此DataFeedDesc的protobuf信息 @@ -1163,8 +1164,8 @@ ParallelExecutor - ``TypeError`` - 如果feed参数是list类型，但是它里面的元素不是dict类型时，弹出此异常 .. note:: - 1.如果feed参数为dict类型，那么传入 ``ParallelExecutor`` 的数据量 *必须* 大于可用的执行场所数目。否则，C++端将会抛出异常。应额外注意核对数据集的最后一个batch是否比可用执行场所数目大。 - 2.如果可用执行场所大于一个，则为每个变量最后获取的结果都是list类型，且这个list中的每个元素都是各个可用执行场所的变量 + 1. 如果feed参数为dict类型，那么传入 ``ParallelExecutor`` 的数据量 *必须* 大于可用的CPU核数或GPU卡数。否则，C++端将会抛出异常。应额外注意核对数据集的最后一个batch是否比可用的CPU核数或GPU卡数大。 + 2. 如果可用的CPU核数或GPU卡数大于一个，则为每个变量最后获取的结果都是list类型，且这个list中的每个元素都是各CPU核或GPU卡上的变量 **代码示例** @@ -1231,10 +1232,10 @@ ParamAttr 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中运行并调整权重。 diff --git a/doc/fluid/api_cn/index_cn.rst b/doc/fluid/api_cn/index_cn.rst index 21c1ac5510e8533f6acc78f749acf53fad1c31e4..9febfaf1bbb0065a6be3ebb3f37b3f8a81fbb9bb 100644 --- a/doc/fluid/api_cn/index_cn.rst +++ b/doc/fluid/api_cn/index_cn.rst @@ -18,7 +18,6 @@ API metrics_cn.rst nets_cn.rst optimizer_cn.rst - param_attr_cn.rst profiler_cn.rst regularizer_cn.rst transpiler_cn.rst diff --git a/doc/fluid/api_cn/initializer_cn.rst b/doc/fluid/api_cn/initializer_cn.rst index adc5d45fc9de2ab8457d1a729c826454f83aa716..98bd68c54b6837b147fc734a2921966b46df19a0 100644 --- a/doc/fluid/api_cn/initializer_cn.rst +++ b/doc/fluid/api_cn/initializer_cn.rst @@ -285,7 +285,7 @@ UniformInitializer 参数： - **low** (float) - 下界 - **high** (float) - 上界 - - **seed** (float) - 随机种子 + - **seed** (int) - 随机种子 **代码示例** diff --git a/doc/fluid/api_cn/layers_cn.rst b/doc/fluid/api_cn/layers_cn.rst index b365c380c32cbc966fca9fd6d2b9866e26995566..fc55e9a99f6ebf385851b1d520bcebf213479ac1 100644 --- a/doc/fluid/api_cn/layers_cn.rst +++ b/doc/fluid/api_cn/layers_cn.rst @@ -1,11119 +1,11193 @@ -################### -fluid.layers -################### - - -============ - control_flow -============ - - -.. _cn_api_fluid_layers_array_length: - -array_length -------------------------------- - -.. py:function:: paddle.fluid.layers.array_length(array) - -**得到输入LoDTensorArray的长度** - -此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。 - -相关API: - - :ref:`cn_api_fluid_layers_array_read` - - :ref:`cn_api_fluid_layers_array_write` - - :ref:`cn_api_fluid_layers_While` - -参数： - - **array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度 - -返回：输入数组LoDTensorArray的长度 - -返回类型：变量（Variable） - -**代码示例**: - -.. code-block:: python - - tmp = fluid.layers.zeros(shape=[10], dtype='int32') - i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) - arr = fluid.layers.array_write(tmp, i=i) - arr_len = fluid.layers.array_length(arr) - - - - - - - - - -.. _cn_api_fluid_layers_array_read: - -array_read -------------------------------- - -.. py:function:: paddle.fluid.layers.array_read(array,i) - -此函数用于读取数据，数据以LOD_TENSOR_ARRAY数组的形式读入 - -:: - - - Given: - array = [0.6,0.1,0.3,0.1] - And: - I=2 - Then: - output = 0.3 - -参数： - - **array** (Variable|list)-输入张量，存储要读的数据 - - **i** (Variable|list)-输入数组中数据的索引 - -返回：张量类型的变量，已有数据写入 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - tmp = fluid.layers.zeros(shape=[10],dtype='int32') - i = fluid.layers.fill_constant(shape=[1],dtype='int64',value=10) - arr = layers.array_read(tmp,i=i) - - - - - - - - - -.. _cn_api_fluid_layers_array_write: - -array_write -------------------------------- - -.. py:function:: paddle.fluid.layers.array_write(x, i, array=None) - - -该函数将给定的输入变量（即 ``x`` ）写入一个作为输出的 ``LOD_TENSOR_ARRAY`` 变量的某一指定位置中， -这一位置由数组下标(即 ``i`` )指明。 如果 ``LOD_TENSOR_ARRAY`` (即 ``array`` )未指定（即为None值）， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回。 - -参数: - - **x** (Variable|list) – 待从中读取数据的输入张量(tensor) - - **i** (Variable|list) – 输出结果 ``LOD_TENSOR_ARRAY`` 的下标, 该下标指向输入张量 ``x`` 写入输出数组的位置 - - **array** (Variable|list) – 会被输入张量 ``x`` 写入的输出结果 ``LOD_TENSOR_ARRAY`` 。如果该项值为None， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回 - -返回: 输入张量 ``x`` 所写入的输出结果 ``LOD_TENSOR_ARRAY`` - -返回类型: 变量（Variable） - -**代码示例** - -.. code-block:: python - - tmp = fluid.layers.zeros(shape=[10], dtype='int32') - i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) - arr = layers.array_write(tmp, i=i) - - - - - - - - - - - -.. _cn_api_fluid_layers_create_array: - -create_array -------------------------------- - -.. py:function:: paddle.fluid.layers.create_array(dtype) - - -创建LoDTensorArray数组。它主要用于实现RNN与array_write, array_read和While。 - -参数: - - **dtype** (int |float) — lod_tensor_array中存储元素的数据类型。 - -返回: lod_tensor_array， 元素数据类型为dtype。 - -返回类型: Variable。 - - -**代码示例** - -.. code-block:: python - - data = fluid.layers.create_array(dtype='float32') - - - - - - - - - - - -.. _cn_api_fluid_layers_DynamicRNN: - -DynamicRNN -------------------------------- - -.. py:class:: paddle.fluid.layers.DynamicRNN(name=None) - - -动态RNN可以处理一批序列数据,每个样本序列的长度可以不同。这个API自动批量处理它们。 - -必须设置输入lod，请参考 ``lod_tensor`` - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - data = fluid.layers.data(name='sentence', dtype='int64', lod_level=1) - embedding = fluid.layers.embedding(input=data, size=[65535, 32], - is_sparse=True) - - drnn = fluid.layers.DynamicRNN() - with drnn.block(): - word = drnn.step_input(embedding) - prev = drnn.memory(shape=[200]) - hidden = fluid.layers.fc(input=[word, prev], size=200, act='relu') - drnn.update_memory(prev, hidden) # set prev to hidden - drnn.output(hidden) - - # last是的最后一时间步，也是编码（encoding）得出的最终结果 - last = fluid.layers.sequence_last_step(drnn()) - - -动态RNN将按照timesteps展开开序列。用户需要在with block中定义如何处理处理每个timestep。 - -memory用于缓存分段数据。memory的初始值可以是零，也可以是其他变量。 - -动态RNN可以将多个变量标记为其输出。使用drnn()获得输出序列。 - -.. note:: - 目前不支持在DynamicRNN中任何层上配置 is_sparse = True - -.. py:method:: step_input(x) - - 将序列标记为动态RNN输入。 - -参数: - - **x** (Variable) - 输入序列 - - -返回:当前的输入序列中的timestep。 - -.. py:method:: static_input(x) - -将变量标记为RNN输入。输入不会分散到timestep中。 - -参数: - - **x** (Variable) - 输入序列 - -返回:可以访问的RNN的输入变量,。 - -.. py:method:: block(*args, **kwds) - -用户在RNN中定义operators的block。有关详细信息，请参阅class ``docstring`` 。 - -.. py:method:: memory(init=None, shape=None, value=0.0, need_reorder=False, dtype='float32') - -为动态rnn创建一个memory 变量。 - -如果 ``init`` 不是None， ``memory`` 将由这个变量初始化。参数 ``need_reorder`` 用于将memory重新排序作为输入变量。当memory初始化依赖于输入样本时，应该将其设置为true。 - -**例如** - -.. code-block:: python - - import paddle.fluid as fluid - sentence = fluid.layers.data( - name='sentence', dtype='float32', shape=[32]) - boot_memory = fluid.layers.data( - name='boot', dtype='float32', shape=[10]) - - drnn = fluid.layers.DynamicRNN() - with drnn.block(): - word = drnn.step_input(sentence) - memory = drnn.memory(init=boot_memory, need_reorder=True) - hidden = fluid.layers.fc( - input=[word, memory], size=10, act='tanh') - drnn.update_memory(ex_mem=memory, new_mem=hidden) - drnn.output(hidden) - - rnn_output = drnn() - - - -否则，如果已经设置 ``shape`` 、 ``value`` 、 ``dtype`` ，memory将被 ``value`` 初始化 - -.. code-block:: python - - import paddle.fluid as fluid - - sentence = fluid.layers.data( - name='sentence', dtype='float32', shape=[32]) - - drnn = fluid.layers.DynamicRNN() - with drnn.block(): - word = drnn.step_input(sentence) - memory = drnn.memory(shape=[10], dtype='float32', value=0) - hidden = fluid.layers.fc( - input=[word, memory], size=10, act='tanh') - drnn.update_memory(ex_mem=memory, new_mem=hidden) - drnn.output(hidden) - rnn_output = drnn() - - -参数： - - **init** (Variable|None) – 初始化的Variable - - **shape** (list|tuple) – memory shape. 注意形状不包含batch的大小 - - **value** (float) – 初始化的值 - - **need_reorder** (bool) – memory初始化依赖于输入样本时设置为True - - **dtype** (str|numpy.dtype) – 初始化memory的数据类型 - -返回：memory Variable - - -.. py:method:: update_memory(ex_mem, new_mem) - -将内存从 ``ex_mem`` 更新到 ``new_mem`` 。注意， ``ex_mem`` 和 ``new_mem`` 的 ``shape`` 和数据类型必须相同。 - -参数： - - **ex_mem** （memory Variable）- memory 变量（Variable） - - **new_mem** （memory Variable）- RNN块中生成的平坦变量（plain variable） - -返回：None - - -.. py:method:: output(*outputs) - -标记RNN输出变量。 - -参数: - - **\*outputs** - 输出变量。 - -返回:None - - - - - - - - - - -.. _cn_api_fluid_layers_equal: - -equal -------------------------------- - -.. py:function:: paddle.fluid.layers.equal(x,y,cond=None,**ignored) - -**equal** -该层返回 :math:`x==y` 按逐元素运算而得的真值。 - -参数： - - **x** (Variable)-equal的第一个操作数 - - **y** (Variable)-equal的第二个操作数 - - **cond** (Variable|None)-输出变量（可选），用来存储equal的结果 - -返回：张量类型的变量，存储equal的输出结果 - -返回类型：变量（Variable） - -**代码示例**: - -.. code-block:: python - - less = fluid.layers.equal(x=label,y=limit) - - - - - - - - - -.. _cn_api_fluid_layers_IfElse: - -IfElse -------------------------------- - -.. py:function:: paddle.fluid.layers.IfElse(cond, name=None) - -if-else控制流。 - -参数： - - **cond** (Variable)-用于比较的条件 - - **Name** (str,默认为空（None）)-该层名称 - -**代码示例**： - -.. code-block:: python - - limit = fluid.layers.fill_constant_batch_size_like( - input=label, dtype='int64', shape=[1], value=5.0) - cond = fluid.layers.less_than(x=label, y=limit) - ie = fluid.layers.IfElse(cond) - with ie.true_block(): - true_image = ie.input(image) - hidden = fluid.layers.fc(input=true_image, size=100, act='tanh') - prob = fluid.layers.fc(input=hidden, size=10, act='softmax') - ie.output(prob) - - with ie.false_block(): - false_image = ie.input(image) - hidden = fluid.layers.fc( - input=false_image, size=200, act='tanh') - prob = fluid.layers.fc(input=hidden, size=10, act='softmax') - ie.output(prob) - prob = ie() - - - - - - - - - -.. _cn_api_fluid_layers_increment: - -increment -------------------------------- - -.. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True) - - -该函数为输入 ``x`` 增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。 - -.. note:: - ``x`` 中元素个数必须为1 - -参数: - - **x** (Variable|list) – 含有输入值的张量(tensor) - - **value** (float) – 需要增加在 ``x`` 变量上的值 - - **in_place** (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本 - -返回： 每个元素增加后的对象 - -返回类型：变量(variable) - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[1], dtype='float32', - append_batch_size=False) - data = fluid.layers.increment(x=data, value=3.0, in_place=True) - - - - - - - - - - - -.. _cn_api_fluid_layers_is_empty: - -is_empty -------------------------------- - -.. py:function:: paddle.fluid.layers.is_empty(x, cond=None, **ignored) - -测试变量是否为空 - -参数： - - **x** (Variable)-测试的变量 - - **cond** (Variable|None)-输出参数。返回给定x的测试结果，默认为空（None） - -返回：布尔类型的标量。如果变量x为空则值为真 - -返回类型：变量（Variable） - -抛出异常：``TypeError``-如果input不是变量或cond类型不是变量 - -**代码示例**： - -.. code-block:: python - - res = fluid.layers.is_empty(x=input) - # or: - fluid.layers.is_empty(x=input, cond=res) - - - - - - - - - -.. _cn_api_fluid_layers_less_than: - -less_than -------------------------------- - -.. py:function:: paddle.fluid.layers.less_than(x, y, force_cpu=None, cond=None, **ignored) - - -该函数按元素出现顺序依次在X,Y上操作，并返回 ``Out`` ，它们三个都是n维tensor（张量）。 -其中，X、Y可以是任何类型的tensor，Out张量的各个元素可以通过 :math:`Out=X`_ - -.. math:: - - PE(pos, 2i) &= \sin{(pos / 10000^{2i / P})}\\ - PE(pos, 2i + 1) &= \cos{(pos / 10000^{2i / P})}\\ - Out(:, pos, i) &= \alpha * input(:, pos, i) + \beta * PE(pos, i) - -其中: - - PE(pos, 2i): 偶数位置上数字的增量 - - PE(pos, 2i + 1): 奇数位置上数字的增量 - -返回： Variable: 具有位置编码的三维形状张量[N×M×P] - -**代码示例：** - -.. code-block:: python - - position_tensor = fluid.layers.add_position_encoding(input=tensor) - - - - - - - - - - - -.. _cn_api_fluid_layers_affine_channel: - -affine_channel -------------------------------- - -.. py:function:: paddle.fluid.layers.affine_channel(x, scale=None, bias=None, data_layout='NCHW', name=None) - -对输入的每个 channel 应用单独的仿射变换。用于将空间批处理范数替换为其等价的固定变换。 - -输入也可以是二维张量，并在二维应用仿射变换。 - -参数： - - **x** (Variable):特征图输入可以是一个具有NCHW阶或NHWC阶的4D张量。它也可以是二维张量和应用于第二维度的仿射变换。 - - **scale** (Variable): 形状为(C)的一维输入，第C个元素为输入的第C通道仿射变换的尺度因子。 - - **bias** (Variable):形状为(C)的一维输入，第C个元素是输入的第C个通道的仿射变换的偏置。 - - **data_layout** (string, default NCHW): NCHW 或 NHWC，如果输入是一个2D张量，可以忽略该参数 - - **name** (str, default None): 此层的名称 - -返回： out (Variable): 与x具有相同形状和数据布局的张量。 - - - - - - - - - -.. _cn_api_fluid_layers_affine_grid: - -affine_grid -------------------------------- - -.. py:function:: paddle.fluid.layers.affine_grid(theta, out_shape, name=None) - -它使用仿射变换的参数生成(x,y)坐标的网格，这些参数对应于一组点，在这些点上，输入特征映射应该被采样以生成转换后的输出特征映射。 - - - -.. code-block:: text - - * 例 1: - 给定: - theta = [[[x_11, x_12, x_13] - [x_14, x_15, x_16]] - [[x_21, x_22, x_23] - [x_24, x_25, x_26]]] - out_shape = [2, 3, 5, 5] - - Step 1: - - 根据out_shape生成标准化坐标 - - 归一化坐标的值在-1和1之间 - - 归一化坐标的形状为[2,H, W]，如下所示: - - C = [[[-1. -1. -1. -1. -1. ] - [-0.5 -0.5 -0.5 -0.5 -0.5] - [ 0. 0. 0. 0. 0. ] - [ 0.5 0.5 0.5 0.5 0.5] - [ 1. 1. 1. 1. 1. ]] - [[-1. -0.5 0. 0.5 1. ] - [-1. -0.5 0. 0.5 1. ] - [-1. -0.5 0. 0.5 1. ] - [-1. -0.5 0. 0.5 1. ] - [-1. -0.5 0. 0.5 1. ]]] - - C[0]是高轴坐标，C[1]是宽轴坐标。 - - Step2: - - 将C转换并重组成形为[H * W, 2]的张量,并追加到最后一个维度 - - 我们得到: - - C_ = [[-1. -1. 1. ] - [-0.5 -1. 1. ] - [ 0. -1. 1. ] - [ 0.5 -1. 1. ] - [ 1. -1. 1. ] - [-1. -0.5 1. ] - [-0.5 -0.5 1. ] - [ 0. -0.5 1. ] - [ 0.5 -0.5 1. ] - [ 1. -0.5 1. ] - [-1. 0. 1. ] - [-0.5 0. 1. ] - [ 0. 0. 1. ] - [ 0.5 0. 1. ] - [ 1. 0. 1. ] - [-1. 0.5 1. ] - [-0.5 0.5 1. ] - [ 0. 0.5 1. ] - [ 0.5 0.5 1. ] - [ 1. 0.5 1. ] - [-1. 1. 1. ] - [-0.5 1. 1. ] - [ 0. 1. 1. ] - [ 0.5 1. 1. ] - [ 1. 1. 1. ]] - Step3: - 按下列公式计算输出 -.. math:: - - Output[i] = C\_ * Theta[i]^T - -参数： - - **theta** (Variable)： 一类具有形状为[N, 2, 3]的仿射变换参数 - - **out_shape** (Variable | list | tuple)：具有格式[N, C, H, W]的目标输出的shape，out_shape可以是变量、列表或元组。 - - **name** (str|None): 此层的名称(可选)。如果没有设置，将自动命名。 - -返回： Variable: 形为[N, H, W, 2]的输出。 - -抛出异常： ValueError: 如果输入了不支持的参数类型 - -**代码示例：** - -.. code-block:: python - - theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") - out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") - data = fluid.layers.affine_grid(theta, out_shape) - # or - data = fluid.layers.affine_grid(theta, [5, 3, 28, 28]) - - - - - - - - - -.. _cn_api_fluid_layers_autoincreased_step_counter: - -autoincreased_step_counter -------------------------------- - -.. py:function:: paddle.fluid.layers.autoincreased_step_counter(counter_name=None, begin=1, step=1) - -创建一个自增变量，每个mini-batch返回主函数运行次数，变量自动加1，默认初始值为1. - -参数： - - **counter_name** (str)-计数名称，默认为 ``@STEP_COUNTER@`` - - **begin** (int)-开始计数 - - **step** (int)-执行之间增加的步数 - -返回：全局运行步数 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - global_step = fluid.layers.autoincreased_step_counter( - counter_name='@LR_DECAY_COUNTER@', begin=begin, step=1) - - - - - - - - - -.. _cn_api_fluid_layers_batch_norm: - -batch_norm -------------------------------- - -.. py:function:: paddle.fluid.layers.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False, fuse_with_relu=False) - -批正则化层（Batch Normalization Layer） - -可用作conv2d和全链接操作的正则化函数。该层需要的数据格式如下： - -1.NHWC[batch,in_height,in_width,in_channels] -2.NCHW[batch,in_channels,in_height,in_width] - -更多详情请参考 : `Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ - -``input`` 是mini-batch的输入特征。 - -.. math:: - \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mini-batch-mean \\ - \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// mini-batch-variance \\ - \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ - y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift - -参数： - - **input** (Variable) - 输入变量，为LoDTensor - - **act** （string，默认None）- 激活函数类型，linear|relu|prelu|... - - **is_test** （bool,默认False） - 用于训练 - - **momentum** （float，默认0.9）- （暂无说明，待更新） - - **epsilon** （float，默认1e-05）- （暂无说明，待更新） - - **param_attr** （ParamAttr|None） - batch_norm参数范围的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为param_attr。如果没有设置param_attr的初始化函数，参数初始化为Xavier。默认：None - - **bias_attr** （ParamAttr|None） - batch_norm bias参数的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为bias_attr。如果没有设置bias_attr的初始化函数，参数初始化为0。默认：None - - **data_layout** （string,默认NCHW) - NCHW|NHWC - - **in_place** （bool，默认False）- 得出batch norm可复用记忆的输入和输出 - - **name** （string，默认None）- 该层名称（可选）。若设为None，则自动为该层命名 - - **moving_mean_name** （string，默认None）- moving_mean的名称，存储全局Mean - - **moving_variance_name** （string，默认None）- moving_variance的名称，存储全局变量 - - **do_model_average_for_mean_and_var** （bool，默认False）- 是否为mean和variance做模型均值 - - **fuse_with_relo** （bool）- 如果为True，batch norm后该操作符执行relu - -返回： 张量，在输入中运用批正则后的结果 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - hidden1 = fluid.layers.fc(input=x, size=200, param_attr='fc1.w') - hidden2 = fluid.layers.batch_norm(input=hidden1) - - - - - - - - - - - -.. _cn_api_fluid_layers_beam_search: - -beam_search -------------------------------- - -.. py:function:: paddle.fluid.layers.beam_search(pre_ids, pre_scores, ids, scores, beam_size, end_id, level=0, name=None) - -在机器翻译任务中，束搜索(Beam search)是选择候选词的一种经典算法 - -更多细节参考 `Beam Search `_ - -该层对束在一时间步中进行搜索。根据候选词使用于源句子所得的 ``scores`` , 从候选词 ``ids`` 中选择当前步骤的 top-K （最佳K）候选词的id，其中 ``K`` 是 ``beam_size`` ， ``ids`` ， ``scores`` 是计算单元的预测结果。 另外， ``pre_id`` 和 ``pre_scores`` 是上一步中 ``beam_search`` 的输出，用于特殊处理结束边界。 - -注意，传入的 ``scores`` 应该是累积分数，并且，在计算累积分数之前应该使用额外的 operators 进行长度惩罚，也建议在计算前查找top-K，然后使用top-K候选项。 - -有关完全波束搜索用法演示，请参阅以下示例： - - fluid/tests/book/test_machine_translation.py - - - -参数: - - **pre_ids** （Variable） - LodTensor变量，它是上一步 ``beam_search`` 的输出。在第一步中。它应该是LodTensor，shape为 :math:`(batch\_size，1)` ， :math:`lod [[0,1，...，batch\_size]，[0,1，...，batch\_size]]` - - **pre_scores** （Variable） - LodTensor变量，它是上一步中beam_search的输出 - - **ids** （Variable） - 包含候选ID的LodTensor变量。shpae为 :math:`（batch\_size×beam\_ize，K）` ，其中 ``K`` 应该是 ``beam_size`` - - **scores** （Variable） - 与 ``ids`` 及其shape对应的累积分数的LodTensor变量, 与 ``ids`` 的shape相同。 - - **beam_size** （int） - 束搜索中的束宽度。 - - **end_id** （int） - 结束标记的id。 - - **level** （int，default 0） - **可忽略，当前不能更改** 。它表示lod的源级别，解释如下。 ``ids`` 的 lod 级别应为2.第一级是源级别， 描述每个源句子（beam）的前缀（分支）的数量，第二级是描述这些候选者属于前缀的句子级别的方式。链接前缀和所选候选者的路径信息保存在lod中。 - - **name** （str | None） - 该层的名称（可选）。如果设置为None，则自动命名该层。 - -返回：LodTensor pair ， 包含所选的ID和相应的分数 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - # 假设 `probs` 包含计算神经元所得的预测结果 - # `pre_ids` 和 `pre_scores` 为beam_search之前时间步的输出 - topk_scores, topk_indices = layers.topk(probs, k=beam_size) - accu_scores = layers.elementwise_add( - x=layers.log(x=topk_scores)), - y=layers.reshape( - pre_scores, shape=[-1]), - axis=0) - selected_ids, selected_scores = layers.beam_search( - pre_ids=pre_ids, - pre_scores=pre_scores, - ids=topk_indices, - scores=accu_scores, - beam_size=beam_size, - end_id=end_id) - - - - - - - - - - - -.. _cn_api_fluid_layers_beam_search_decode: - -beam_search_decode -------------------------------- - -.. py:function:: paddle.fluid.layers.beam_search_decode(ids, scores, beam_size, end_id, name=None) - -束搜索层（Beam Search Decode Layer）通过回溯LoDTensorArray ids，为每个源语句构建完整假设，LoDTensorArray ``ids`` 的lod可用于恢复束搜索树中的路径。请参阅下面的demo中的束搜索使用示例： - - :: - - fluid/tests/book/test_machine_translation.py - -参数: - - **id** (Variable) - LodTensorArray，包含所有回溯步骤重中所需的ids。 - - **score** (Variable) - LodTensorArra，包含所有回溯步骤对应的score。 - - **beam_size** (int) - 束搜索中波束的宽度。 - - **end_id** (int) - 结束token的id。 - - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回： LodTensor 对（pair）， 由生成的id序列和相应的score序列组成。两个LodTensor的shape和lod是相同的。lod的level=2，这两个level分别表示每个源句有多少个假设，每个假设有多少个id。 - -返回类型: 变量（variable） - - -**代码示例** - -.. code-block:: python - - # 假设 `ids` 和 `scores` 为 LodTensorArray变量，它们保留了 - # 选择出的所有时间步的id和score - finished_ids, finished_scores = layers.beam_search_decode( - ids, scores, beam_size=5, end_id=0) - - - - - - - - - -.. _cn_api_fluid_layers_bilinear_tensor_product: - -bilinear_tensor_product -------------------------------- - -.. py:function:: paddle.fluid.layers.bilinear_tensor_product(x, y, size, act=None, name=None, param_attr=None, bias_attr=None) - -该层对两个输入执行双线性张量积。 - -例如: - -.. math:: - out{i} = x * W_{i} * {y^\mathrm{T}}, i=0,1,...,size-1 - -在这个公式中： - - :math:`x`: 第一个输入，包含M个元素，形状为[batch_size, M] - - :math:`y`: 第二个输入，包含N个元素，形状为[batch_size, N] - - :math:`W_{i}`: 第i个被学习的权重，形状是[M, N] - - :math:`out_{i}`: out的第i个元素，形状是[batch_size, size] - - :math:`y^\mathrm{T}`: :math:`y_{2}` 的转置 - -参数： - - **x** (Variable): 2-D 输入张量，形状为 [batch_size, M] - - **y** (Variable): 2-D 输入张量，形状为 [batch_size, N] - - **size** (int): 此层的维度， - - **act** (str, default None): 应用到该层输出的激活函数 - - **name** (str, default None): 该层的名称 - - **param_attr** (ParamAttr, default None): 可学习参数/权重（w） 的参数属性 - - **bias_attr** (ParamAttr, default None): 偏差的参数属性，如果设置为False，则不会向输出单元添加偏差。如果设置为零，偏差初始化为零。默认值:None - -返回： Variable: 一个形为[batch_size, size]的2-D张量 - -**代码示例：** - -.. code-block:: python - - tensor = bilinear_tensor_product(x=layer1, y=layer2, size=1000) - - - - - - - - - - -.. _cn_api_fluid_layers_brelu: - -brelu -------------------------------- - -.. py:function:: paddle.fluid.layers.brelu(x, t_min=0.0, t_max=24.0, name=None) - - -BRelu 激活函数 - -.. math:: out=max(min(x,tmin),tmax) - -参数: - - **x** (Variable) - BReluoperator的输入 - - **t_min** (FLOAT|0.0) - BRelu的最小值 - - **t_max** (FLOAT|24.0) - BRelu的最大值 - - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 - - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[2,3,16,16], dtype=”float32”) - y = fluid.layers.brelu(x, t_min=1.0, t_max=20.0) - - - - - - -.. _cn_api_fluid_layers_chunk_eval: - -chunk_eval -------------------------------- - -.. py:function:: paddle.fluid.layers.chunk_eval(input, label, chunk_scheme, num_chunk_types, excluded_chunk_types=None) - -块估计（Chunk Evaluator） - -该功能计算并输出块检测（chunk detection）的准确率、召回率和F1值。 - -chunking的一些基础请参考 `Chunking with Support Vector Machines `_ - -ChunkEvalOp计算块检测（chunk detection）的准确率、召回率和F1值，并支持IOB，IOE，IOBES和IO标注方案。以下是这些标注方案的命名实体（NER）标注例子： - -:: - - - ====== ====== ====== ===== == ============ ===== ===== ===== == ========= - Li Ming works at Agricultural Bank of China in Beijing. - ====== ====== ====== ===== == ============ ===== ===== ===== == ========= - IO I-PER I-PER O O I-ORG I-ORG I-ORG I-ORG O I-LOC - IOB B-PER I-PER O O B-ORG I-ORG I-ORG I-ORG O B-LOC - IOE I-PER E-PER O O I-ORG I-ORG I-ORG E-ORG O E-LOC - IOBES B-PER E-PER O O I-ORG I-ORG I-ORG E-ORG O S-LOC - ====== ====== ====== ===== == ============ ===== ===== ===== == ========= - -有三种块类别（命名实体类型），包括PER（人名），ORG（机构名）和LOC（地名），标签形式为标注类型（tag type）-块类型（chunk type）。 - -由于计算实际上用的是标签id而不是标签，需要额外注意将标签映射到相应的id，这样CheckEvalOp才可运行。关键在于id必须在列出的等式中有效。 - -:: - - - tag_type = label % num_tag_type - chunk_type = label / num_tag_type - -num_tag_type是标注规则中的标签类型数，num_chunk_type是块类型数，tag_type从下面的表格中获取值。 - -:: - - - Scheme Begin Inside End Single - plain 0 - - - - IOB 0 1 - - - IOE - 0 1 - - IOBES 0 1 2 3 - -仍以NER为例，假设标注规则是IOB块类型为ORG，PER和LOC。为了满足以上等式，标签图如下： - -:: - - - B-ORG 0 - I-ORG 1 - B-PER 2 - I-PER 3 - B-LOC 4 - I-LOC 5 - O 6 - -不难证明等式的块类型数为3，IOB规则中的标签类型数为2.例如I-LOC的标签id为5，I-LOC的标签类型id为1，I-LOC的块类型id为2，与等式的结果一致。 - -参数： - - **input** (Variable) - 网络的输出预测 - - **label** (Variable) - 测试数据集的标签 - - **chunk_scheme** (str) - 标注规则，表示如何解码块。必须数IOB，IOE，IOBES或者plain。详情见描述 - - **num_chunk_types** (int) - 块类型数。详情见描述 - - **excluded_chunk_types** (list) - 列表包含块类型id，表示不在计数内的块类型。详情见描述 - -返回：元组（tuple），包含precision, recall, f1_score, num_infer_chunks, num_label_chunks, num_correct_chunks - -返回类型：tuple（元组） - -**代码示例**： - -.. code-block:: python: - - crf = fluid.layers.linear_chain_crf( - input=hidden, label=label, param_attr=ParamAttr(name="crfw")) - crf_decode = fluid.layers.crf_decoding( - input=hidden, param_attr=ParamAttr(name="crfw")) - fluid.layers.chunk_eval( - input=crf_decode, - label=label, - chunk_scheme="IOB", - num_chunk_types=(label_dict_len - 1) / 2) - - - - - - - - - -.. _cn_api_fluid_layers_clip: - -clip -------------------------------- - -.. py:function:: paddle.fluid.layers.clip(x, min, max, name=None) - -clip算子 - -clip运算符限制给定输入的值在一个区间内。间隔使用参数"min"和"max"来指定：公式为 - -.. math:: - Out=min(max(X,min),max) - -参数： - - **x** （Variable）- （Tensor）clip运算的输入，维数必须在[1,9]之间。 - - **min** （FLOAT）- （float）最小值，小于该值的元素由min代替。 - - **max** （FLOAT）- （float）最大值，大于该值的元素由max替换。 - - **name** （basestring | None）- 输出的名称。 - -返回： （Tensor）clip操作后的输出和输入（X）具有形状（shape） - -返回类型： 输出（Variable）。 - -**代码示例：** - -.. code-block:: python - - input = fluid.layers.data( - name='data', shape=[1], dtype='float32') - reward = fluid.layers.clip(x=input, min=-1.0, max=1.0) - - - - - - -.. _cn_api_fluid_layers_clip_by_norm: - -clip_by_norm -------------------------------- - -.. py:function:: paddle.fluid.layers.clip_by_norm(x, max_norm, name=None) - -ClipByNorm算子 - -此运算符将输入 ``X`` 的L2范数限制在 ``max_norm`` 内。如果 ``X`` 的L2范数小于或等于 ``max_norm`` ，则输出（Out）将与 ``X`` 相同。如果X的L2范数大于 ``max_norm`` ，则 ``X`` 将被线性缩放，使得输出（Out）的L2范数等于 ``max_norm`` ，如下面的公式所示： - -.. math:: - Out = \frac{max\_norm * X}{norm(X)} - -其中， :math:`norm（X）` 代表 ``x`` 的L2范数。 - - -参数： - - **x** (Variable)- (Tensor) clip_by_norm运算的输入，维数必须在[1,9]之间。 - - **max_norm** (float)- 最大范数值。 - - **name** (basestring | None)- 输出的名称。 - -返回： (Tensor)clip_by_norm操作后的输出和输入(X)具有形状(shape). - -返回类型： Variable - -**代码示例：** - -.. code-block:: python - - input = fluid.layers.data( - name='data', shape=[1], dtype='float32') - reward = fluid.layers.clip_by_norm(x=input, max_norm=1.0) - - - - - - - - -.. _cn_api_fluid_layers_conv2d: - -conv2d -------------------------------- - -.. py:function:: paddle.fluid.layers.conv2d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) - -卷积二维层（convolution2D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、dilations、一组参数计算输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 `_ 。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。 - -对每个输入X，有等式： - -.. math:: - - Out = \sigma \left ( W * X + b \right ) - -其中： - - :math:`X` ：输入值，NCHW格式的张量（Tensor） - - :math:`W` ：滤波器值，MCHW格式的张量（Tensor） - - :math:`*` ： 卷积操作 - - :math:`b` ：Bias值，二维张量（Tensor），shape为[M,1] - - :math:`\sigma` ：激活函数 - - :math:`Out` ：输出值，*Out*和**X**的shape可能不同 - -**示例** - -- 输入： - - 输入shape：:math:`( N,C_{in},H_{in},W_{in} )` - - 滤波器shape： :math:`( C_{out},C_{in},H_{f},W_{f} )` - -- 输出： - - 输出shape： :math:`( N,C_{out},H_{out},W_{out} )` - -其中 - -.. math:: - - H_{out} = \frac{\left ( H_{in}+2*paddings[0]-\left ( dilations[0]*\left ( H_{f}-1 \right )+1 \right ) \right )}{strides[0]}+1 - - W_{out} = \frac{\left ( H_{in}+2*paddings[1]-\left ( dilations[1]*\left ( W_{f}-1 \right )+1 \right ) \right )}{strides[1]}+1 - -参数： - - **input** (Variable) - 格式为[N,C,H,W]格式的输入图像 - - **num_fliters** (int) - 滤波器数。和输出图像通道相同 - - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size，filter_size_W）。否则，滤波器为square - - **stride** (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含两个整型数，（stride_H,stride_W）。否则，stride_H = stride_W = stride。默认：stride = 1 - - **padding** (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含两个整型数，（padding_H,padding_W)。否则，padding_H = padding_W = padding。默认：padding = 0 - - **dilation** (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数，（dilation_H,dilation_W）。否则，dilation_H = dilation_W = dilation。默认：dilation = 1 - - **groups** (int) - 卷积二维层（Conv2D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1 - - **param_attr** (ParamAttr|None) - conv2d的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)` ，并且std为 :math:`\frac{2.0}{filter\_elem\_num}^{0.5}` 。默认为None - - **bias_attr** (ParamAttr|bool|None) - conv2d bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None - - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True - - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回：张量，存储卷积和非线性激活结果 - -返回类型：变量（Variable） - -抛出异常: - - ``ValueError`` - 如果输入shape和filter_size，stride,padding和group不匹配。 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') - conv2d = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3, act="relu") - - - - - - - - - - - -.. _cn_api_fluid_layers_conv2d_transpose: - -conv2d_transpose -------------------------------- - -.. py:function:: paddle.fluid.layers.conv2d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) - -2-D卷积转置层（Convlution2D transpose layer） - -该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充（padding）来计算输出。输入(Input)和输出(Output)为NCHW格式，其中 ``N`` 为batch大小， ``C`` 为通道数（channel），``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别都包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为 ``None``，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数。 - -.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf - -输入 :math:`X` 和输出 :math:`Out` 函数关系如下： - -.. math:: - Out=\sigma (W*X+b)\\ - -其中： - - :math:`X` : 输入张量，具有 ``NCHW`` 格式 - - - :math:`W` : 滤波器张量，，具有 ``NCHW`` 格式 - - - :math:`*` : 卷积操作 - - - :math:`b` : 偏置（bias），二维张量，shape为 ``[m,1]`` - - - :math:`σ` : 激活函数 - - - :math:`Out` : 输出值，Out和 ``X`` 的 ``shape`` 可能不一样 - -**样例**： - -输入： - -.. math:: - - 输入张量的shape : （N，C_{in}， H_{in}， W_{in}) - - 滤波器（filter）shape ： （C_{in}, C_{out}, H_f, W_f) - -输出： - -.. math:: - 输出张量的 shape ： （N，C_{out}, H_{out}, W_{out}) - -其中 - -.. math:: - - & H'_{out} = (H_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(H_f-1)+1\\ - & W'_{out} = (W_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(W_f-1)+1 \\ - & H_{out}\in[H'_{out},H'_{out} + strides[0])\\ - & W_{out}\in[W'_{out},W'_{out} + strides[1])\\ - - - -参数: - - **input** （Variable）- 输入张量，格式为[N, C, H, W] - - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（ channel ）相同 - - **output_size** (int|tuple|None) - 输出图片的大小。如果output_size是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果output_size=None,则内部会使用filter_size、padding和stride来计算output_size。如果output_size和filter_size是同时指定的，那么它们应满足上面的公式。 - - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果filter_size=None，则内部会计算输出大小。 - - **padding** (int|tuple) - 填充大小。如果padding是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。 - - **stride** (int|tuple) - 步长大小。如果stride是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 - - **dilation** (int|元组) - 膨胀大小。如果dilation是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation_W。默认:dilation= 1。 - - **groups** (int) - Conv2d转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。 - - **param_attr** (ParamAttr|None) - conv2d_transfer中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv2d_transfer使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。 - - **bias_attr** (ParamAttr|bool|None) - conv2d_tran_bias中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv2d_transfer使用ParamAttrs作为，bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。 - - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。 - - **act** (str) - 激活函数类型，如果设置为None，则不使用激活函数。默认值:None。 - - **name** (str|None) - 该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。 - - -返回： 存储卷积转置结果的张量。 - -返回类型: 变量（variable） - -抛出异常: - - ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') - conv2d_transpose = fluid.layers.conv2d_transpose(input=data, num_filters=2, filter_size=3) - - - - - - - - - - - -.. _cn_api_fluid_layers_conv3d: - -conv3d -------------------------------- - -.. py:function:: paddle.fluid.layers.conv3d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) - -卷积三维层（convolution3D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀（dilations）、组数参数计算得到输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积三维（Convlution3D）和卷积二维（Convlution2D）相似，但多了一维深度（depth）。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。 - -对每个输入X，有等式： - -.. math:: - - - Out = \sigma \left ( W * X + b \right ) - -其中： - - :math:`X` ：输入值，NCHW格式的张量（Tensor） - - :math:`W` ：滤波器值，MCHW格式的张量（Tensor） - - :math:`*` ： 卷积操作 - - :math:`b` ：Bias值，二维张量（Tensor），形为[M,1] - - :math:`\sigma` ：激活函数 - - :math:`Out` ：输出值, 和 :math:`X` 的形状可能不同 - -**示例** - -- 输入： - 输入shape： :math:`( N,C_{in},H_{in},W_{in} )` - - 滤波器shape： :math:`( C_{out},C_{in},H_{f},W_{f} )` -- 输出： - 输出shape： :math:`( N,C_{out},H_{out},W_{out} )` - -其中 - -.. math:: - - - D_{out} = \frac{\left ( D_{in}+2*paddings[0]-\left ( dilations[0]*\left ( D_{f}-1 \right )+1 \right ) \right )}{strides[0]}+1 - - H_{out} = \frac{\left ( H_{in}+2*paddings[1]-\left ( dilations[1]*\left ( H_{f}-1 \right )+1 \right ) \right )}{strides[1]}+1 - - W_{out} = \frac{\left ( W_{in}+2*paddings[2]-\left ( dilations[2]*\left ( W_{f}-1 \right )+1 \right ) \right )}{strides[2]}+1 - -参数： - - **input** (Variable) - 格式为[N,C,H,W]格式的输入图像 - - **num_fliters** (int) - 滤波器数。和输出图像通道相同 - - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size，filter_size_W）。否则，滤波器为square - - **stride** (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含两个整型数，（stride_H,stride_W）。否则，stride_H = stride_W = stride。默认：stride = 1 - - **padding** (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含两个整型数，（padding_H,padding_W)。否则，padding_H = padding_W = padding。默认：padding = 0 - - **dilation** (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数，（dilation_H,dilation_W）。否则，dilation_H = dilation_W = dilation。默认：dilation = 1 - - **groups** (int) - 卷积二维层（Conv2D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1 - - **param_attr** (ParamAttr|None) - conv2d的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)`，并且std为 :math:`\left ( \frac{2.0}{filter\_elem\_num} \right )^{0.5}` 。默认为None - - **bias_attr** (ParamAttr|bool|None) - conv2d bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None - - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True - - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回：张量，存储卷积和非线性激活结果 - -返回类型：变量（Variable） - -抛出异常： - - ``ValueError`` - 如果 ``input`` 的形和 ``filter_size`` ， ``stride`` , ``padding`` 和 ``group`` 不匹配。 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32') - conv3d = fluid.layers.conv3d(input=data, num_filters=2, filter_size=3, act="relu") - - - - - - - - - -.. _cn_api_fluid_layers_conv3d_transpose: - -conv3d_transpose -------------------------------- - -.. py:function:: paddle.fluid.layers.conv3d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) - -3-D卷积转置层（Convlution3D transpose layer) - -该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充来计算输出。输入(Input)和输出(Output)为NCDHW格式。其中 ``N`` 为batch大小， ``C`` 为通道数（channel）, ``D`` 为特征深度, ``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为None，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数 - -.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf - -输入X和输出Out函数关系X，有等式如下： - -.. math:: - \\Out=\sigma (W*X+b)\\ - -其中： - - :math:`X` : 输入张量，具有 ``NCDHW`` 格式 - - - :math:`W` : 滤波器张量，，具有 ``NCDHW`` 格式 - - - :math:`*` : 卷积操作 - - - :math:`b` : 偏置（bias），二维张量，shape为[m,1] - - - :math:`σ` : 激活函数 - - - :math:`Out` : 输出值， ``Out`` 和 ``X`` 的 shape可能不一样 - - -**样例** - -输入: - -.. math:: - - Input shape: (N,C_{in},D_{in},H_{in},W_{in}) - - Filter shape: (C_{in},C_{out},D_f,H_f,W_f) - - - -输出: - -.. math:: - - Output shape: (N,C_{out},D_{out},H_{out},W_{out}) - - -其中： - -.. math:: - - - - D_{out}=(D_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(D_f-1)+1 - - H_{out}=(H_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(H_f-1)+1 - - W_{out}=(W_{in}-1)*strides[2]-2*paddings[2]+dilations[2]*(W_f-1)+1 - - - -参数: - - **input** （Variable）- 输入张量，格式为[N, C, D, H, W] - - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（channel）相同 - - **output_size** (int|tuple|None) - 输出图片的大小。如果 ``output_size`` 是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果 ``output_size=None`` ,则内部会使用filter_size、padding和stride来计算output_size。如果 ``output_size`` 和 ``filter_size`` 是同时指定的，那么它们应满足上面的公式。 - - **filter_size** (int|tuple|None) - 滤波器大小。如果 ``filter_size`` 是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果 ``filter_size=None`` ，则内部会计算输出大小。 - - **padding** (int|tuple) - 填充大小。如果 ``padding`` 是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。 - - **stride** (int|tuple) - 步长大小。如果 ``stride`` 是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 - - **dilation** (int|元组) - 膨胀大小。如果 ``dilation`` 是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation_W。默认:dilation= 1。 - - **groups** (int) - Conv2d转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。 - - **param_attr** (ParamAttr|None) - conv2d_transfer中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv2d_transfer使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。 - - **bias_attr** (ParamAttr|bool|None) - conv2d_tran_bias中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv2d_transfer使用ParamAttrs作为，bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。 - - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。 - - **act** (str) - 激活函数类型，如果设置为None，则不使用激活函数。默认值:None。 - - **name** (str|None) - 该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。 - - -返回： 存储卷积转置结果的张量。 - -返回类型: 变量（variable） - -抛出异常: - - ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError - - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32') - conv3d_transpose = fluid.layers.conv3d_transpose(input=data, num_filters=2, filter_size=3) - - - - - - - - - - -.. _cn_api_fluid_layers_cos_sim: - -cos_sim -------------------------------- - -.. py:function:: paddle.fluid.layers.cos_sim(X, Y) - -余弦相似度运算符（Cosine Similarity Operator） - -.. math:: - - Out = \frac{X^{T}*Y}{\sqrt{X^{T}*X}*\sqrt{Y^{T}*Y}} - -输入X和Y必须具有相同的shape，除非输入Y的第一维为1(不同于输入X)，在计算它们的余弦相似度之前，Y的第一维会被broadcasted，以匹配输入X的shape。 - -输入X和Y都携带或者都不携带LoD(Level of Detail)信息。但输出仅采用输入X的LoD信息。 - -参数： - - **X** (Variable) - cos_sim操作函数的一个输入 - - **Y** (Variable) - cos_sim操作函数的第二个输入 - -返回：cosine(X,Y)的输出 - -返回类型：变量（Variable) - - - - - - - - - -.. _cn_api_fluid_layers_crf_decoding: - -crf_decoding -------------------------------- - -.. py:function:: paddle.fluid.layers.crf_decoding(input, param_attr, label=None) - -该函数读取由 ``linear_chain_crf`` 学习的emission feature weights（发射状态特征的权重）和 transition feature weights(转移特征的权重)。 -本函数实现了Viterbi算法，可以动态地寻找隐藏状态最可能的序列，该序列也被称为Viterbi路径（Viterbi path），从而得出的标注(tags)序列。 - -这个运算的结果会随着 ``Label`` 参数的有无而改变： - - 1. ``Label`` 非None的情况，在实际训练中时常发生。此时本函数会协同 ``chunk_eval`` 工作。本函数会返回一行形为[N X 1]的向量，其中值为0的部分代表该label不适合作为对应结点的标注，值为1的部分则反之。此类型的输出可以直接作为 ``chunk_eval`` 算子的输入 - - 2. 当没有 ``Label`` 时，该函数会执行标准decoding过程 - -（没有 ``Label`` 时）该运算返回一个形为 [N X 1]的向量，其中元素取值范围为 0 ~ 最大标注个数-1，分别为预测出的标注（tag）所在的索引。 - -参数： - - **input** (Variable)(LoDTensor，默认类型为 LoDTensor) — 一个形为 [N x D] 的LoDTensor，其中 N 是mini-batch的大小，D是标注（tag) 的总数。 该输入是 ``linear_chain_crf`` 的 unscaled emission weight matrix （未标准化的发射权重矩阵） - - **param_attr** (ParamAttr) — 参与训练的参数的属性 - - **label** (Variable)(LoDTensor，默认类型为 LoDTensor) — 形为[N x 1]的正确标注（ground truth）。 该项可选择传入。 有关该参数的更多信息，请详见上述描述 - -返回：(LoDTensor, LoDTensor)decoding结果。具体内容根据 ``Label`` 参数是否提供而定。请参照函数介绍来详细了解。 - -返回类型： Variable - - -**代码示例** - -.. code-block:: python - - crf_decode = layers.crf_decoding( - input=hidden, param_attr=ParamAttr(name="crfw")) - - - - - - - - - - - - -.. _cn_api_fluid_layers_crop: - -crop -------------------------------- - -.. py:function:: paddle.fluid.layers.crop(x, shape=None, offsets=None, name=None) - -根据偏移量（offsets）和形状（shape），裁剪输入张量。 - -**样例**： - -:: - - * Case 1: - Given - X = [[0, 1, 2, 0, 0] - [0, 3, 4, 0, 0] - [0, 0, 0, 0, 0]], - and - shape = [2, 2], - offsets = [0, 1], - output is: - Out = [[1, 2], - [3, 4]]. - * Case 2: - Given - X = [[0, 1, 2, 5, 0] - [0, 3, 4, 6, 0] - [0, 0, 0, 0, 0]], - and shape is tensor - shape = [[0, 0, 0] - [0, 0, 0]] - and - offsets = [0, 1], - - output is: - Out = [[1, 2, 5], - [3, 4, 6]]. - - -参数: - - **x** (Variable): 输入张量。 - - **shape** (Variable|list/tuple of integer) - 输出张量的形状由参数shape指定，它可以是一个变量/整数的列表/整数元组。如果是张量变量，它的秩必须与x相同。该方式适可用于每次迭代时候需要改变输出形状的情况。如果是整数列表/tupe，则其长度必须与x的秩相同 - - **offsets** (Variable|list/tuple of integer|None) - 指定每个维度上的裁剪的偏移量。它可以是一个Variable，或者一个整数list/tupe。如果是一个tensor variable，它的rank必须与x相同，这种方法适用于每次迭代的偏移量（offset）都可能改变的情况。如果是一个整数list/tupe，则长度必须与x的rank的相同，如果shape=None，则每个维度的偏移量为0。 - - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: 裁剪张量。 - -返回类型: 变量（Variable） - -抛出异常: 如果形状不是列表、元组或变量，抛出ValueError - - -**代码示例**: - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3, 5], dtype="float32") - y = fluid.layers.data(name="y", shape=[2, 3], dtype="float32") - crop = fluid.layers.crop(x, shape=y) - - - ## or - z = fluid.layers.data(name="z", shape=[3, 5], dtype="float32") - crop = fluid.layers.crop(z, shape=[2, 3]) - - - - - - - - - - -.. _cn_api_fluid_layers_cross_entropy: - -cross_entropy -------------------------------- - -.. py:function:: paddle.fluid.layers.cross_entropy(input, label, soft_label=False, ignore_index=-100) - -该函数定义了输入和标签之间的cross entropy(交叉熵)层。该函数支持standard cross-entropy computation（标准交叉熵损失计算） -以及soft-label cross-entropy computation（软标签交叉熵损失计算） - - 1. One-hot cross-entropy算法 - - soft_label = False, Label[i, 0] 指明样本i的类别所具的索引: - .. math:: - \\Y[i]=-log(X[i,Label[i]])\\ - - 2. Soft-label cross-entropy算法 - - soft_label = True, Label[i, j] 表明样本i对应类别j的soft label(软标签): - .. math:: - \\Y[i]= \sum_{j}-Label[i,j]*log(X[i,j])\\ - - **请确保采用此算法时识别为各软标签的概率总和为1** - - 3. One-hot cross-entropy with vecterized label（使用向量化标签的One-hot）算法 - - 作为 *2* 的特殊情况，当软类标签内部只有一个非零概率元素，且它的值为1，那么 *2* 算法降级为一种仅有one-hot标签的one-hot交叉熵 - - - - - -参数： - - **input** (Variable|list) – 一个形为[N x D]的二维tensor，其中N是batch大小，D是类别（class）数目。 这是由之前的operator计算出的概率，绝大多数情况下是由softmax operator得出的结果 - - **label** (Variable|list) – 一个二维tensor组成的正确标记的数据集(ground truth)。 当 ``soft_label`` 为False时，label为形为[N x 1]的tensor。 ``soft_label`` 为True时, label是形为 [N x D]的 tensor - - **soft_label** (bool) – 标志位，指明是否需要把给定的标签列表认定为软标签。默认为False。 - - **ignore_index** (int) – 指定一个被无视的目标值，并且这个值不影响输入梯度变化。仅在 ``soft_label`` 为False时生效。 默认值: -100 - -返回： 一个形为[N x 1]的二维tensor，承载了交叉熵损失 - -弹出异常： ``ValueError`` - - 1. 当 ``input`` 的第一维和 ``label`` 的第一维不相等时，弹出异常 - 2. 当 ``soft_label`` 值为True， 且 ``input`` 的第二维和 ``label`` 的第二维不相等时，弹出异常 - 3. 当 ``soft_label`` 值为False，且 ``label`` 的第二维不是1时，弹出异常 - - - -**代码示例** - -.. code-block:: python - - predict = fluid.layers.fc(input=net, size=classdim, act='softmax') - cost = fluid.layers.cross_entropy(input=predict, label=label) - - - - - - - - - - - - - -.. _cn_api_fluid_layers_ctc_greedy_decoder: - -ctc_greedy_decoder -------------------------------- - -.. py:function:: paddle.fluid.layers.ctc_greedy_decoder(input, blank, name=None) - -此op用于贪婪策略解码序列，步骤如下: - 1. 获取输入中的每一行的最大值索引，也就是numpy.argmax(input, axis=0)。 - 2. 对于step1结果中的每个序列，在两个空格之间合并重复部分（即合并重复的上一步中的到的索引值）并删除所有空格。 - - -简单举一个例子， - -:: - - 已知： - - input.data = [[0.6, 0.1, 0.3, 0.1], - [0.3, 0.2, 0.4, 0.1], - [0.1, 0.5, 0.1, 0.3], - [0.5, 0.1, 0.3, 0.1], - - [0.5, 0.1, 0.3, 0.1], - [0.2, 0.2, 0.2, 0.4], - [0.2, 0.2, 0.1, 0.5], - [0.5, 0.1, 0.3, 0.1]] - - input.lod = [[4, 4]] - - 计算过程： - - 1. 将argmax的运算结果应用于输入的第一个序列，即 input.data[0:4] 。 - 则得出的结果为[[0], [2], [1], [0]] - 2. 合并重复的索引值部分，删除空格，即为0的值。 - 则第一个输入序列对应的输出为：[[2], [1]] - - 最后 - - output.data = [[2], - [1], - [3]] - - output.lod = [[2, 1]] - - -参数: - - **input** (Variable) — (LoDTensor)，变长序列的概率，它是一个具有LoD信息的二维张量。它的形状是[Lp, num_classes + 1]，其中Lp是所有输入序列长度的和，num_classes是真正的类别。(不包括空白标签)。 - - **blank** (int) — Connectionist Temporal Classification (CTC) loss空白标签索引, 属于半开区间[0,num_classes + 1）。 - - **name** (str) — 此层的名称。可选。 - -返回： CTC贪婪解码结果是一个形为(Lp,1)的二维张量，其中Lp是所有输出序列的长度之和。如果结果中的所有序列都为空，则输出LoDTensor 为[-1]，其中LoD[[]] 形为[1,1]。 - -返回类型： 变量（Variable） - - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[8], dtype='float32') - - cost = fluid.layers.ctc_greedy_decoder(input=x, blank=0) - - - - - - - - - - - -.. _cn_api_fluid_layers_dice_loss: - -dice_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.dice_loss(input, label, epsilon=1e-05) - -dice_loss是比较两批数据相似度，通常用于二值图像分割，即标签为二值。 - -dice_loss定义为: - -.. math:: - dice\_loss &= 1- \frac{2 * intersection\_area}{total\_rea}\\ - &= \frac{(total\_area−intersection\_area)−intersection\_area}{total\_area}\\ - &= \frac{union\_area−intersection\_area}{total\_area} - -参数: - - **input** (Variable) - rank>=2的预测。第一个维度是batch大小，最后一个维度是类编号。 - - **label** （Variable）- 与输入tensor rank相同的正确的标注数据（groud truth）。第一个维度是batch大小，最后一个维度是1。 - - **epsilon** (float) - 将会加到分子和分母上。如果输入和标签都为空，则确保dice为1。默认值:0.00001 - -返回: dice_loss shape为[1]。 - -返回类型: dice_loss(Variable) - -**代码示例** - -.. code-block:: python - - predictions = fluid.layers.softmax(x) - loss = fluid.layers.dice_loss(input=predictions, label=label, 2) - - - - - - - - - - - -.. _cn_api_fluid_layers_dropout: - -dropout -------------------------------- - -.. py:function:: Paddle.fluid.layers.dropout(x,dropout_prob,is_test=False,seed=None,name=None,dropout_implementation='downgrade_in_infer') - -dropout操作 - -丢弃或者保持x的每个元素独立。Dropout是一种正则化技术，通过在训练过程中阻止神经元节点间的联合适应性来减少过拟合。根据给定的丢弃概率dropout操作符随机将一些神经元输出设置为0，其他的仍保持不变。 - -参数： - - **x** (Variable)-输入张量 - - **dropout_prob** (float)-设置为0的单元的概率 - - **is_test** (bool)-显示是否进行测试用语的标记 - - **seed** (int)-Python整型，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。 - - **name** (str|None)-该层名称（可选）。如果设置为None,则自动为该层命名 - - **dropout_implementation** (string) - [‘downgrade_in_infer’(defauld)|’upscale_in_train’] - 其中: - 1.downgrade_in_infer(default), 在预测时减小输出结果 - - train: out = input * mask - - inference: out = input * dropout_prob - - (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ) - - 2.upscale_in_train, 增加训练时的结果 - - train: out = input * mask / ( 1.0 - dropout_prob ) - - inference: out = input - - (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ） - -dropout操作符可以从程序中移除，程序变得高效。 - -返回：带有x维的张量 - -返回类型：变量 - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32") - droped = fluid.layers.dropout(x, dropout_prob=0.5) - - - - - - - - - -.. _cn_api_fluid_layers_dynamic_gru: - -dynamic_gru -------------------------------- - -.. py:function:: paddle.fluid.layers.dynamic_gru(input, size, param_attr=None, bias_attr=None, is_reverse=False, gate_activation='sigmoid', candidate_activation='tanh', h_0=None) - - - -**实现了Gated Recurrent Unit层。** - -详细理论介绍，请参照 `Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling`_。 - -.. _Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling: https://arxiv.org/abs/1412.3555 - - -公式如下： - -.. math:: - u_{t}=act_g(W_{ux}x_{t}+W_{uh}h_{t-1}+b_{u}) -.. math:: - r_{t}=act_g(W_{rx}x_{t}+W_{rh}h_{t-1}+b_{r}) -.. math:: - \widetilde{h_{t}}=act_{c}(W_{cx}x_{t}+W_{ch}(r_{t}\odot h_{t-1})+b_c) -.. math:: - h_t=(1-u_t)\odot h_{t-1}+u_t\odot \widetilde{h_t} - -其中， :math:`\odot` 为按元素将向量相乘。 :math:`act_g` 是更新门（update gate）和重置门（reset gate）的激励函数(activation)， 常为 :math:`sigmoid` 函数。 :math:`act_c` 是candidate hidden state(候选隐藏状态)的激励函数，常为 :math:`tanh` 。 - -注意 :math:`W_{ux}x_{t},W_{rx}x_{t},W_{cx}x_{t}` 这些在 input :math:`x_t` 上的操作不包括在该运算中。用户可以选择性地在GRU层之前使用FC层来进行这一操作。 - - - -参数: - - **input** (Variable) – dynamic_gru层的输入, 支持variable time length input sequence（可变时长输入序列）。 本变量底层的tensor是一个(T×3D)矩阵， 其中T是该mini-batch中总时间步数， D是隐藏状态的规模（hidden size）。 - - **size** (int) – GRU cell的维度 - - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重矩阵的参数属性。 - 注意： - - 该矩阵为一个（T X 3D）矩阵。其中D为隐藏状态的规模（hidden size） - - 该矩阵的所有元素由两部分组成。一是update gate和reset gate的权重，形为（D X 2D)，二是候选隐藏状态（candidate hidden state）的权重，形为 (D X D) - 如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一，则会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果param_attr未被初始化（即其构造函数未被设置），Xavier会负责初始化它。 默认值为None。 - - **bias_attr** (ParamAttr|bool|None) - GRU层bias的参数属性。该（1 X 3D）形的bias变量将会连结（concatenate）在update gate（更新门）、reset gate（重置门）、candidate calculations（候选隐藏状态计算）后。如果值为False，将没有bias会应用到上述三个过程中。如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一， ``dynamic_gru`` 会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果bias_attr未被初始化（即其构造函数未被设置），则它会被初始化为0。默认值为None。 - - **is_reverse** (bool) –是否计算反GRU(reversed GRU)，默认为False - - **gate_activation** (str) – update gate 和 reset gate的激励函数（activation）。 可选择[“sigmoid”, “tanh”, “relu”, “identity”]其一, 默认为 “sigmoid” - - **candidate_activation** (str) – candidate hidden state（候选隐藏状态）计算所需的激励函数（activation）。 可从[“sigmoid”, “tanh”, “relu”, “identity”]中选择, 默认为 “tanh” - - **h_0** (Variable) – 该函数参数为初始隐藏状态。若未赋值，则默认为0。它是一个 (N x D) tensor, 其中 N 为输入mini-batch的总时间步数， D 为 隐藏状态规模(hidden size) - - -返回： GRU的隐藏状态(hidden state)。形为（T X D），序列长度和输入相同。 - -返回类型: 变量（variable） - - -**代码示例** - -.. code-block:: python - - dict_dim, emb_dim = 128, 64 - data = fluid.layers.data(name='sequence', shape=[1], - dtype='int32', lod_level=1) - emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim]) - hidden_dim = 512 - x = fluid.layers.fc(input=emb, size=hidden_dim * 3) - hidden = fluid.layers.dynamic_gru(input=x, size=hidden_dim) - - - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_dynamic_lstm: - -dynamic_lstm -------------------------------- - -.. py:function:: paddle.fluid.layers.dynamic_lstm(input, size, h_0=None, c_0=None, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', dtype='float32', name=None) - -LSTM，即Long-Short Term Memory(长短期记忆)运算。 - -默认实现方式为diagonal/peephole连接(https://arxiv.org/pdf/1402.1128.pdf)，公式如下： - - -.. math:: - i_t=\sigma (W_{ix}x_{t}+W_{ih}h_{t-1}+W_{ic}c_{t-1}+b_i) -.. math:: - f_t=\sigma (W_{fx}x_{t}+W_{fh}h_{t-1}+W_{fc}c_{t-1}+b_f) -.. math:: - \widetilde{c_t}=act_g(W_{ct}x_{t}+W_{ch}h_{t-1}+b_{c}) -.. math:: - o_t=\sigma (W_{ox}x_{t}+W_{oh}h_{t-1}+W_{oc}c_{t}+b_o) -.. math:: - c_t=f_t\odot c_{t-1}+i_t\odot \widetilde{c_t} -.. math:: - h_t=o_t\odot act_h(c_t) - -W 代表了权重矩阵(weight matrix)，例如 :math:`W_{xi}` 是从输入门（input gate）到输入的权重矩阵, :math:`W_{ic}` ，:math:`W_{fc}` ， :math:`W_{oc}` 是对角权重矩阵(diagonal weight matrix)，用于peephole连接。在此实现方式中，我们使用向量来代表这些对角权重矩阵。 - -其中： - - :math:`b` 表示bias向量（ :math:`b_i` 是输入门的bias向量） - - :math:`σ` 是非线性激励函数（non-linear activations），比如逻辑sigmoid函数 - - :math:`i` ，:math:`f` ，:math:`o` 和 :math:`c` 分别为输入门(input gate)，遗忘门(forget gate)，输出门（output gate）,以及神经元激励向量（cell activation vector）这些向量和神经元输出激励向量（cell output activation vector） :math:`h` 有相同的大小。 - - :math:`⊙` 意为按元素将两向量相乘 - - :math:`act_g` , :math:`act_h` 分别为神经元(cell)输入、输出的激励函数(activation)。常常使用tanh函数。 - - :math:`\widetilde{c_t}` 也被称为候选隐藏状态(candidate hidden state)。可根据当前输入和之前的隐藏状态计算而得 - -将 ``use_peepholes`` 设为False来禁用 peephole 连接方法。 公式等详细信息请参考 http://www.bioinf.jku.at/publications/older/2604.pdf 。 - -注意， :math:`W_{xi}x_t, W_{xf}x_t, W_{xc}x_t,W_{xo}x_t` 这些在输入 :math:`x_t` 上的操作不包括在此运算中。用户可以在LSTM operator之前选择使用全连接运算。 - - - - -参数: - - **input** (Variable) (LoDTensor) - LodTensor类型，支持variable time length input sequence（时长可变的输入序列）。 该LoDTensor中底层的tensor是一个形为(T X 4D)的矩阵，其中T为此mini-batch上的总共时间步数。D为隐藏层的大小、规模(hidden size) - - **size** (int) – 4 * 隐藏层大小 - - **h_0** (Variable) – 最初的隐藏状态（hidden state），可选项。默认值为0。它是一个(N x D)张量，其中N是batch大小，D是隐藏层大小。 - - **c_0** (Variable) – 最初的神经元状态（cell state）， 可选项。 默认值0。它是一个(N x D)张量, 其中N是batch大小。h_0和c_0仅可以同时为None，不能只其中一个为None。 - - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重的参数属性。 - 注意： - - Weights = :math:`\{W_{ch}, W_{ih}, W_{fh}, W_{oh} \}` - - 形为(D x 4D), 其中D是hidden size（隐藏层规模） - - 如果它被设为None或者 ``ParamAttr`` 属性之一, dynamic_lstm会创建 ``ParamAttr`` 对象作为param_attr。如果没有对param_attr初始化（即构造函数没有被设置）， Xavier会负责初始化参数。默认为None。 - - **bias_attr** (ParamAttr|None) – 可学习的bias权重的属性, 包含两部分，input-hidden bias weights（输入隐藏层的bias权重）和 peephole connections weights（peephole连接权重）。如果 ``use_peepholes`` 值为 ``True`` ， 则意为使用peephole连接的权重。 - 另外： - - use_peepholes = False - Biases = :math:`\{ b_c,b_i,b_f,b_o \}` - 形为(1 x 4D)。 - - use_peepholes = True - Biases = :math:`\{ b_c,b_i,b_f,b_o,W_{ic},W_{fc},W_{oc} \}` - 形为 (1 x 7D)。 - - 如果它被设为None或 ``ParamAttr`` 的属性之一， ``dynamic_lstm`` 会创建一个 ``ParamAttr`` 对象作为bias_attr。 如果没有对bias_attr初始化（即构造函数没有被设置），bias会被初始化为0。默认值为None。 - - **use_peepholes** (bool) – （默认: True） 是否使用diagonal/peephole连接方式 - - **is_reverse** (bool) – （默认: False） 是否计算反LSTM(reversed LSTM) - - **gate_activation** (str) – （默认: "sigmoid"）应用于input gate（输入门），forget gate（遗忘门）和 output gate（输出门）的激励函数（activation），默认为sigmoid - - **cell_activation** (str) – （默认: tanh）用于神经元输出的激励函数(activation), 默认为tanh - - **candidate_activation** (str) – （默认: tanh）candidate hidden state（候选隐藏状态）的激励函数(activation), 默认为tanh - - **dtype** (str) – 即 Data type（数据类型）。 可以选择 [“float32”, “float64”]，默认为“float32” - - **name** (str|None) – 该层的命名，可选项。如果值为None, 将会自动对该层命名 - -返回：隐藏状态（hidden state），LSTM的神经元状态。两者都是（T x D）形，且LoD保持与输入一致 - -返回类型: 元组（tuple） - - -**代码示例** - -.. code-block:: python - - hidden_dim = 512 - forward_proj = fluid.layers.fc(input=input_seq, size=hidden_dim * 4, - bias_attr=False) - forward, _ = fluid.layers.dynamic_lstm( - input=forward_proj, size=hidden_dim * 4, use_peepholes=False) - - - - - - - - - - - - - -.. _cn_api_fluid_layers_dynamic_lstmp: - -dynamic_lstmp -------------------------------- -.. py:function:: paddle.fluid.layers.dynamic_lstmp(input, size, proj_size, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', proj_activation='tanh', dtype='float32', name=None) - -动态LSTMP层(Dynamic LSTMP Layer) - -LSTMP层(具有循环映射的LSTM)在LSTM层后有一个分离的映射层，从原始隐藏状态映射到较低维的状态，用来减少参数总数，减少LSTM计算复杂度，特别是输出单元相对较大的情况下。 `Long Short-Term Memory Recurrent Neural Network Architectures for Large Scale Acoustic Modeling `_ - -公式如下： - -.. math:: - - i_t & = \sigma(W_{ix}x_{t} + W_{ir}r_{t-1} + W_{ic}c_{t-1} + b_i)\\ - f_t & = \sigma(W_{fx}x_{t} + W_{fr}r_{t-1} + W_{fc}c_{t-1} + b_f)\\ - \tilde{c_t} & = act_g(W_{cx}x_t + W_{cr}r_{t-1} + b_c)\\ - o_t & = \sigma(W_{ox}x_{t} + W_{or}r_{t-1} + W_{oc}c_t + b_o)\\ - c_t & = f_t \odot c_{t-1} + i_t \odot \tilde{c_t}\\ - h_t & = o_t \odot act_h(c_t)\\ - r_t & = \overline{act_h}(W_{rh}h_t)\\ - - -在以上公式中： - - :math:`W` : 代表权重矩阵（例如 :math:`W_{xi}` 是输入门道输入的权重矩阵） - - :math:`W_{ic}` , :math:`W_{fc}` , :math:`W_{oc}` : peephole connections的对角权重矩阵。在我们的实现中，外面用向量代表这些对角权重矩阵 - - :math:`b` : 代表偏差向量（例如 :math:`b_{i}` 是输入偏差向量） - - :math:`\delta` : 激活函数，比如逻辑回归函数 - - :math:`i,f,o` 和 :math:`c` :分别代表输入门，遗忘门,输出门和cell激活函数向量，四者的大小和cell输出激活函数向量 :math:`h` 的四者大小相等 - - :math:`h` : 隐藏状态 - - :math:`r` : 隐藏状态的循环映射 - - :math:`\tilde{c_t}` : 候选隐藏状态 - - :math:`\odot` : 向量的元素状态生成 - - :math:`act_g` 和 :math:`act_h` : cell输入和cell输出激活函数，通常使用 :math:`tanh` - - :math:`\overline{act_h}` : 映射输出的激活函数，通常用 :math:`identity` 或等同的 :math:`act_h` - -将 ``use_peepholes`` 设置为False，断开窥视孔连接（peephole connection）。在此省略公式，详情请参照论文 `LONG SHORT-TERM MEMORY `_ 。 - -注意输入 :math:`x_{t}` 中的 :math:`W_{xi}x_{t},W_{xf}x_{t},W_{xc}x_{t},W_{xo}x_{t}` 不在此操作符中。用户选择在LSTMP层之前使用全链接层。 - -参数： - - **input** (Variable) - dynamic_lstmp层的输入，支持输入序列长度为变量的倍数。该变量的张量为一个矩阵，维度为（T X 4D），T为mini-batch的总时间步长，D是隐藏大小。 - - **size** (int) - 4*隐藏状态大小（hidden size） - - **proj_size** (int) - 投影输出的大小 - - **param_attr** (ParamAttr|None) - 可学习hidden-hidden权重和投影权重的参数属性。 - 说明: - - Hidden-hidden （隐藏状态到隐藏状态）权重 = :math:`\{ W_{ch},W_{ih},W_{fh},W_{oh} \}` - - hidden-hidden权重的权重矩阵为（P*4D），P是投影大小，D是隐藏大小。 - - 投影（Projection）权重 = :math:`\{ W_{rh} \}` - - 投影权重的shape为（D\*P） - - 如果设为None或者ParamAttr的一个属性，dynamic_lstm将创建ParamAttr为param_attr。如果param_attr的初始函数未设置，参数则初始化为Xavier。默认:None。 - - **bias_attr** (ParamAttr|None) - 可学习bias权重的bias属性，包含输入隐藏的bias权重和窥视孔连接权重（peephole connection）,前提是use_peepholes设为True。 - - 说明: - 1.use_peepholes = False - - Biases = { :math:`b_{c},b_{i},b_{f},b_{o}`}. - - 维度为（1*4D） - - 2.use_peepholes = True - - Biases = { :math:`b_{c},b_{i},b_{f},b_{o},W_{ic},W_{fc},W_{oc}`} - - 维度为（1*7D） - - 如果设置为None或者ParamAttr的一个属性，dynamic_lstm将创建ParamAttr为bias_attr。bias_attr的初始函数未设置，bias则初始化为0.默认：None。 - - - **use_peepholes** (bool) - 是否开启诊断/窥视孔链接，默认为True。 - - **is_reverse** (bool) - 是否计算反向LSTM，默认为False。 - - **gate_activation** (bool) - 输入门（input gate）、遗忘门（forget gate）和输出门（output gate）的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“sigmoid”。 - - **cell_activation** (str) - cell输出的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 - - **candidate_activation** (str) - 候选隐藏状态（candidate hidden state）的激活状态。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 - - **proj_activation** (str) - 投影输出的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 - - **dtype** (str) - 数据类型。Choices = [“float32”，“float64”]，默认“float32”。 - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 - -返回：含有两个输出变量的元组，隐藏状态（hidden state）的投影和LSTMP的cell状态。投影的shape为（T*P），cell state的shape为（T*D），两者的LoD和输入相同。 - -返回类型：元组(tuple) - -**代码示例**： - -.. code-block:: python - - dict_dim, emb_dim = 128, 64 - data = fluid.layers.data(name='sequence', shape=[1], - dtype='int32', lod_level=1) - emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim]) - hidden_dim, proj_dim = 512, 256 - fc_out = fluid.layers.fc(input=emb, size=hidden_dim * 4, - act=None, bias_attr=None) - proj_out, _ = fluid.layers.dynamic_lstmp(input=fc_out, - size=hidden_dim * 4, - proj_size=proj_dim, - use_peepholes=False, - is_reverse=True, - cell_activation="tanh", - proj_activation="tanh") - - - - - - - - - - - -.. _cn_api_fluid_layers_edit_distance: - - -edit_distance -------------------------------- - -.. py:function:: Paddle.fluid.layers.edit_distance(input,label,normalized=True,ignored_tokens=None) - -编辑距离运算符 - -计算一批给定字符串及其参照字符串间的编辑距离。编辑距离也称Levenshtein距离，通过计算从一个字符串变成另一个字符串所需的最少操作步骤来衡量两个字符串的相异度。这里的操作包括插入、删除和替换。 - -比如给定假设字符串A=“kitten”和参照字符串B=“sitting”，从A变换成B编辑距离为3，至少需要两次替换和一次插入： - -“kitten”->“sitten”->“sittn”->“sitting” - -输入为LoDTensor,包含假设字符串（带有表示批尺寸的总数）和分离信息（具体为LoD信息）。并且批尺寸大小的参照字符串和输入LoDTensor的顺序保持一致。 - -输出包含批尺寸大小的结果，代表一对字符串中每个字符串的编辑距离。如果Attr(normalized)为真，编辑距离则处以参照字符串的长度。 - -参数： - - **input** (Variable)-假设字符串的索引 - - **label** (Variable)-参照字符串的索引 - - **normalized** (bool,默认为True)-表示是否用参照字符串的长度进行归一化 - - **ignored_tokens** (list,默认为None)-计算编辑距离前需要移除的token - - **name** (str)-该层名称，可选 - -返回：[batch_size,1]中序列到序列到编辑距离 - -返回类型：变量 - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[1], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='float32') - cost = fluid.layers.edit_distance(input=x,label=y) - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_add: - -elementwise_add -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_add(x, y, axis=-1, act=None, name=None) - -逐元素相加算子 - -等式为： - -.. math:: - Out = X + Y - -- :math:`X` ：任意维度的张量（Tensor）. -- :math:`Y` ：一个维度必须小于等于X维度的张量（Tensor）。 -对于这个运算算子有2种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2: - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），则 ``axis`` 为 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾部尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。 - -参数： - - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 - - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由 ``MKLDNN`` 使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_div: - -elementwise_div -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_div(x, y, axis=-1, act=None, name=None) - -逐元素相除算子 - -等式是： - -.. math:: - Out = X / Y - -- :math:`X` ：任何尺寸的张量（Tensor）。 -- :math:`Y` ：尺寸必须小于或等于X尺寸的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。 - -参数： - - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 - - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_max: - -elementwise_max -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_max(x, y, axis=-1, act=None, name=None) -最大元素算子 - -等式是： - -.. math:: - Out = max(X, Y) - -- :math:`X` ：任何尺寸的张量（Tensor）。 -- :math:`Y` ：尺寸必须小于或等于X尺寸的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 - - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_min: - -elementwise_min -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_min(x, y, axis=-1, act=None, name=None) - -最小元素算子 - -等式是： - -.. math:: - Out = min(X, Y) - -- :math:`X` ：任何维数的张量（Tensor）。 -- :math:`Y` ：维数必须小于或等于X维数的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 - - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_mul: - -elementwise_mul -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_mul(x, y, axis=-1, act=None, name=None) - -逐元素相乘算子 - -等式是： - -.. math:: - Out = X \odot Y - -- **X** ：任何尺寸的张量（Tensor）。 -- **Y** ：尺寸必须小于或等于X尺寸的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** - （Tensor），元素op的第一个输入张量（Tensor）。 - - **y** - （Tensor），元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_pow: - -elementwise_pow -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_pow(x, y, axis=-1, act=None, name=None) - -逐元素幂运算算子 - -等式是： - -.. math:: - Out = X ^ Y - -- :math:`X` ：任何维数的张量（Tensor）。 -- :math:`Y` ：维数必须小于或等于X维数的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 - - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_elementwise_sub: - -elementwise_sub -------------------------------- - -.. py:function:: paddle.fluid.layers.elementwise_sub(x, y, axis=-1, act=None, name=None) - -逐元素相减算子 - -等式是： - -.. math:: - Out = X - Y - -- **X** ：任何尺寸的张量（Tensor）。 -- **Y** ：尺寸必须小于或等于**X**尺寸的张量（Tensor）。 - -此运算算子有两种情况： - 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 - 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 - -对于情况2： - 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 - 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 - 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 - -例如： - -.. code-block:: python - - shape(X) = (2, 3, 4, 5), shape(Y) = (,) - shape(X) = (2, 3, 4, 5), shape(Y) = (5,) - shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 - shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 - shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 - shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 - -输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** - （Tensor），元素op的第一个输入张量（Tensor）。 - - **y** - （Tensor），元素op的第二个输入张量（Tensor）。 - - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 - - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 - - **act** （basestring | None）- 激活应用于输出。 - - **name** （basestring | None）- 输出的名称。 - -返回： 元素运算的输出。 - - - - - - - - - -.. _cn_api_fluid_layers_elu: - -elu -------------------------------- - -.. py:function:: paddle.fluid.layers.elu(x, alpha=1.0, name=None) - -ELU激活层（ELU Activation Operator） - -根据 https://arxiv.org/abs/1511.07289 对输入张量中每个元素应用以下计算。 - -.. math:: - \\out=max(0,x)+min(0,α∗(ex−1))\\ - -参数: - - x(Variable)- ELU operator的输入 - - alpha(FAOAT|1.0)- ELU的alpha值 - - name (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: ELU操作符的输出 - -返回类型: 输出(Variable) - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.elu(x, alpha=0.2) - - - - - - - -.. _cn_api_fluid_layers_embedding: - -embedding -------------------------------- - -.. py:function:: paddle.fluid.layers.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') - -嵌入层(Embedding Layer) - -该层用于查找由输入提供的id在查找表中的嵌入矩阵。查找的结果是input里每个ID对应的嵌入矩阵。 -所有的输入变量都作为局部变量传入LayerHelper构造器 - -参数： - - **input** (Variable)-包含IDs的张量 - - **size** (tuple|list)-查找表参数的维度。应当有两个参数，一个代表嵌入矩阵字典的大小，一个代表每个嵌入向量的大小。 - - **is_sparse** (bool)-代表是否用稀疏更新的标志 - - **is_distributed** (bool)-是否从远程参数服务端运行查找表 - - **padding_idx** (int|long|None)-如果为 ``None`` ，对查找结果无影响。如果padding_idx不为空，表示一旦查找表中找到input中对应的 ``padding_idz``，则用0填充输出结果。如果 :math:`padding_{i}dx<0` ,在查找表中使用的 ``padding_idx`` 值为 :math:`size[0]+dim` 。 - - **param_attr** (ParamAttr)-该层参数 - - **dtype** (np.dtype|core.VarDesc.VarType|str)-数据类型：float32,float_16,int等。 - -返回：张量，存储已有输入的嵌入矩阵。 - -返回类型：变量(Variable) - -**代码示例**: - -.. code-block:: python - - dict_size = len(dataset.ids) - data = fluid.layers.data(name='ids', shape=[32, 32], dtype='float32') - fc = fluid.layers.embedding(input=data, size=[dict_size, 16]) - - - - - - - - - -.. _cn_api_fluid_layers_expand: - -expand -------------------------------- - -.. py:function:: paddle.fluid.layers.expand(x, expand_times, name=None) - -expand运算会按给定的次数对输入各维度进行复制（tile）运算。 您应该通过提供属性 ``expand_times`` 来为每个维度设置次数。 X的秩应该在[1,6]中。请注意， ``expand_times`` 的大小必须与X的秩相同。以下是一个用例： - -:: - - 输入(X) 是一个形状为[2, 3, 1]的三维张量（Tensor）: - - [ - [[1], [2], [3]], - [[4], [5], [6]] - ] - - 属性(expand_times): [1, 2, 2] - - 输出(Out) 是一个形状为[2, 6, 2]的三维张量（Tensor）: - - [ - [[1, 1], [2, 2], [3, 3], [1, 1], [2, 2], [3, 3]], - [[4, 4], [5, 5], [6, 6], [4, 4], [5, 5], [6, 6]] - ] - -参数: - - **x** (Variable)- 一个秩在[1, 6]范围中的张量（Tensor）. - - **expand_times** (list|tuple) - 每一个维度要扩展的次数. - -返回： expand变量是LoDTensor。expand运算后，输出（Out）的每个维度的大小等于输入（X）的相应维度的大小乘以 ``expand_times`` 给出的相应值。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[10], dtype='float32') - out = fluid.layers.expand(x=x, expand_times=[1, 2, 2]) - - - - - - - - - - -.. _cn_api_fluid_layers_fc: - -fc -------------------------------- - -.. py:function:: paddle.fluid.layers.fc(input, size, num_flatten_dims=1, param_attr=None, bias_attr=None, act=None, is_test=False, name=None) - - -**全连接层** - -该函数在神经网络中建立一个全连接层。 它可以同时将多个tensor作为自己的输入，并为每个输入的tensor创立一个变量，称为“权”（weights），等价于一个从每个输入单元到每个输出单元的全连接权矩阵。FC层用每个tensor和它对应的权相乘得到输出tensor。如果有多个输入tensor，那么多个乘法运算将会加在一起得出最终结果。如果 ``bias_attr`` 非空，则会新创建一个偏向变量（bias variable），并把它加入到输出结果的运算中。最后，如果 ``act`` 非空，它也会加入最终输出的计算中。 - -这个过程可以通过如下公式表现： - -.. math:: - - \\Out=Act(\sum^{N-1}_{i=0}X_iW_i+b) \\ - - -上述等式中： - - :math:`N` ：输入tensor的数目 - - :math:`X_i` : 输入的tensor - - :math:`W` ：该层创立的权 - - :math:`b` ：该层创立的bias参数 - - :math:`Act` : activation function(激励函数) - - :math:`Out` : 输出tensor - - -参数: - - **input** (Variable|list of Variable) – 该层的输入tensor(s)（张量），其维度至少是2 - - **size** (int) – 该层输出单元的数目 - - **num_flatten_dims** (int, default 1) – fc层可以接受一个维度大于2的tensor。此时， 它首先会被扁平化(flattened)为一个二维矩阵。 参数``num_flatten_dims`` 决定了输入tensor的flattened方式: 前 ``num_flatten_dims`` (包含边界，从1开始数) 个维度会被扁平化为最终矩阵的第一维 (维度即为矩阵的高), 剩下的 rank(X) - num_flatten_dims 维被扁平化为最终矩阵的第二维 (即矩阵的宽)。 例如， 假设X是一个五维tensor，其形可描述为(2, 3, 4, 5, 6), 且num_flatten_dims = 3。那么扁平化的矩阵形状将会如此： (2 x 3 x 4, 5 x 6) = (24, 30) - - **param_attr** (ParamAttr|list of ParamAttr, default None) – 该层可学习的参数/权的参数属性 - - **bias_attr** (ParamAttr|list of ParamAttr, default None) – 该层bias变量的参数属性。如果值为False， 则bias变量不参与输出单元运算。 如果值为None，bias变量被初始化为0。默认为 None。 - - **act** (str, default None) – 应用于输出的Activation（激励函数） - - **is_test** (bool) – 表明当前执行是否处于测试阶段的标志 - - **name** (str, default None) – 该层的命名 - - -返回：转换结果 - -返回类型: Variable - -弹出异常：``ValueError`` - 如果输入tensor的维度小于2 - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name="data", shape=[32, 32], dtype="float32") - fc = fluid.layers.fc(input=data, size=1000, act="tanh") - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_flatten: - -flatten -------------------------------- - -将输入张量压扁成二维矩阵 - -例如： - -.. code-block:: text - - Case 1: - - 给定 - X.shape = (3, 100, 100, 4) - 且 - axis = 2 - 得到: - Out.shape = (3 * 100, 4 * 100) - - Case 2: - - 给定 - X.shape = (3, 100, 100, 4) - 且 - axis = 0 - 得到: - Out.shape = (1, 3 * 100 * 100 * 4) - -参数： - - **x** (Variable): 一个秩>=axis 的张量 - - **axis** (int)：指出应该将哪些输入维度(唯一的) flatten 到输出的外部维度。axis的值必须在[0,R]范围内，其中R是输入张量的秩。当 axis= 0 时，输出张量的形状为(1，(d_0 X d_1…)，其中输入张量的形状为(d_0, d_1，…)d_n)。 - - **name** (str|None)：此层的名称(可选)。如果没有设置，层将自动命名。 - -返回：Variable: 一个二维张量，它包含输入张量的内容，输入维数将沿给定轴flatten到输出的外部维度，剩余的输入维数flatten到输出的内部维数。 - -抛出异常： - - ValueError: 如果 x 不是一个变量 - - ValueError: 如果axis的范围不在 [0, rank(x)] - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[4, 4, 3], dtype="float32") - out = fluid.layers.flatten(x=x, axis=2) - - - - - - - - - - -.. _cn_api_fluid_layers_gather: - -gather -------------------------------- - -.. py:function:: paddle.fluid.layers.gather(input, index) - -收集层（gather layer） - -根据索引index获取X的最外层维度的条目，并将它们串连在一起。 - -.. math:: - Out=X[Index] - -:: - - X = [[1, 2], - [3, 4], - [5, 6]] - - Index = [1, 2] - - Then: - - Out = [[3, 4], - [5, 6]] - - -参数: - - **input** (Variable) - input 的rank >= 1。 - - **index** (Variable) - index的rank = 1。 - -返回： output (Variable) - -**代码示例** - -.. code-block:: python - - output = fluid.layers.gather(x, index) - - - - - - - - - -.. _cn_api_fluid_layers_gaussian_random: - -gaussian_random -------------------------------- - -.. py:function:: paddle.fluid.layers.gaussian_random(shape, mean=0.0, std=1.0, seed=0, dtype='float32') - -gaussian_random算子。 - -用于使用高斯随机生成器初始化张量（Tensor）。 - -参数： - - **shape** （tuple | list）- （vector ）随机张量的维数 - - **mean** （Float）- （默认值0.0）随机张量的均值 - - **std** （Float）- （默认值为1.0）随机张量的std - - **seed** （Int）- （默认值为 0）生成器随机生成种子。0表示使用系统范围的种子。注意如果seed不为0，则此运算符每次将始终生成相同的随机数 - - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出的数据类型。 - -返回： 输出高斯随机运算矩阵 - -返回类型： 输出（Variable） - - - - - - - - - - -.. _cn_api_fluid_layers_gaussian_random_batch_size_like: - -gaussian_random_batch_size_like -------------------------------- - -.. py:function:: paddle.fluid.layers.gaussian_random_batch_size_like(input, shape, input_dim_idx=0, output_dim_idx=0, mean=0.0, std=1.0, seed=0, dtype='float32') - -用于使用高斯随机发生器初始化张量。分布的defalut均值为0.并且分布的defalut标准差（std）为1.用户可以通过输入参数设置mean和std。 - -参数： - - **input** （Variable）- 其input_dim_idx'th维度指定batch_size的张量（Tensor）。 - - **shape** （元组|列表）- 输出的形状。 - - **input_dim_idx** （Int）- 默认值0.输入批量大小维度的索引。 - - **output_dim_idx** （Int）- 默认值0.输出批量大小维度的索引。 - - **mean** （Float）- （默认值0.0）高斯分布的平均值（或中心值）。 - - **std** （Float）- （默认值 1.0）高斯分布的标准差（std或spread）。 - - **seed** （Int）- （默认为0）用于随机数引擎的随机种子。0表示使用系统生成的种子。请注意，如果seed不为0，则此运算符将始终每次生成相同的随机数。 - - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出数据的类型为float32，float_16，int等。 - -返回： 指定形状的张量将使用指定值填充。 - -返回类型： 输出（Variable）。 - - - - - - - - - - -.. _cn_api_fluid_layers_get_tensor_from_selected_rows: - -get_tensor_from_selected_rows -------------------------------- - -.. py:function:: paddle.fluid.layers.get_tensor_from_selected_rows(x, name=None) - -:code:`Get Tensor From Selected Rows` 用于从选中行（Selected Rows）中获取张量 - -参数： - - **x** (Variable) - 输入，类型是SelectedRows - - **name** (basestring|None) - 输出的名称 - -返回： 输出类型为LoDTensor - -返回类型： out(Variable) - - - - - - - - - - - -.. _cn_api_fluid_layers_grid_sampler: - -grid_sampler -------------------------------- - -.. py:function:: paddle.fluid.layers.grid_sampler(x, grid, name=None) - -该操作使用基于flow field网格的双线性插值对输入X进行采样，通常由affine_grid生成。 - -形状为(N、H、W、2)的网格是由两个形状均为(N、H、W)的坐标(grid_x grid_y)连接而成的。 - -其中，grid_x是输入数据x的第四个维度(宽度维度)的索引，grid_y是第三维度(高维)的索引，最终得到4个最接近的角点的双线性插值值。 - -step 1： - - 得到(x, y)网格坐标，缩放到[0,h -1/W-1] - - grid_x = 0.5 * (grid[:, :, :, 0] + 1) * (W - 1) grid_y = 0.5 * (grid[:, :, :, 1] + 1) * (H - 1) - -step 2： - - 在每个[H, W]区域用网格(X, y)作为输入数据X的索引，并将双线性插值点值由4个最近的点表示。 - -.. code-block:: text - - wn ------- y_n ------- en - | | | - | d_n | - | | | - x_w --d_w-- grid--d_e-- x_e - | | | - | d_s | - | | | - ws ------- y_s ------- wn - - x_w = floor(x) // west side x coord - x_e = x_w + 1 // east side x coord - y_n = floor(y) // north side y coord - y_s = y_s + 1 // south side y coord - d_w = grid_x - x_w // distance to west side - d_e = x_e - grid_x // distance to east side - d_n = grid_y - y_n // distance to north side - d_s = y_s - grid_y // distance to south side - wn = X[:, :, y_n, x_w] // north-west point value - en = X[:, :, y_n, x_e] // north-east point value - ws = X[:, :, y_s, x_w] // south-east point value - es = X[:, :, y_s, x_w] // north-east point value - - - output = wn * d_e * d_s + en * d_w * d_s - + ws * d_e * d_n + es * d_w * d_n - -参数： - - **x** (Variable): 输入数据，形状为[N, C, H, W] - - **grid** (Variable): 输入网格张量，形状为[N, H, W, 2] - - **name** (str, default None): 该层的名称 - -返回： **out** (Variable): 输入X基于输入网格的bilnear插值计算结果，形状为[N, C, H, W] - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[3, 10, 32, 32], dtype='float32') - theta = fluid.layers.data(name='theta', shape=[3, 2, 3], dtype='float32') - grid = fluid.layers.affine_grid(input=theta, size=[3, 10, 32, 32]}) - out = fluid.layers.grid_sampler(x=x, grid=grid) - - - - - - - - - - -.. _cn_api_fluid_layers_group_norm: - -group_norm -------------------------------- - -.. py:function:: paddle.fluid.layers.group_norm(input, groups, epsilon=1e-05, param_attr=None, bias_attr=None, act=None, data_layout='NCHW', name=None) - -参考论文： `Group Normalization `_ - -参数： - - **input** (Variable)：输入张量变量 - - **groups** (int)：从 channel 中分离出来的 group 的数目 - - **epsilon** (float)：为防止方差除零，增加一个很小的值 - - **param_attr** (ParamAttr|None)：可学习标度的参数属性 :math:`g`,如果设置为False，则不会向输出单元添加标度。如果设置为0，偏差初始化为1。默认值:None - - **bias_attr** (ParamAttr|None)：可学习偏置的参数属性 :math:`b ` , 如果设置为False，则不会向输出单元添加偏置量。如果设置为零，偏置初始化为零。默认值:None。 - - **act** (str):将激活应用于输出的 group normalizaiton - - **data_layout** (string|NCHW): 只支持NCHW。 - - **name** (str):这一层的名称（可选） - -返回： Variable: 一个张量变量，它是对输入进行 group normalization 后的结果。 - -**代码示例：** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[8, 32, 32], - dtype='float32') - x = fluid.layers.group_norm(input=data, groups=4) - - - - - - - - - - -.. _cn_api_fluid_layers_gru_unit: - -gru_unit -------------------------------- - -.. py:function:: paddle.fluid.layers.gru_unit(input, hidden, size, param_attr=None, bias_attr=None, activation='tanh', gate_activation='sigmoid') - -GRU单元层。GRU执行步骤基于如下等式： - -.. math:: - u_t=actGate(xu_t+W_{u}h_{t-1}+b_u) -.. math:: - r_t=actGate(xr_t+W_{r}h_{t-1}+b_r) -.. math:: - m_t=actNode(xm_t+W_{c}dot(r_t,h_{t-1})+b_m) -.. math:: - h_t=dot((1-u_t),m_t)+dot(u_t,h_{t-1}) - -GRU单元的输入包括 :math:`z_t` ， :math:`h_{t-1}` 。在上述等式中， :math:`z_t` 会被分割成三部分： :math:`xu_t` 、 :math:`xr_t` 和 :math:`xm_t` 。 -这意味着要为一批输入实现一个全GRU层，我们需要采用一个全连接层，才能得到 :math:`z_t=W_{fc}x_t` 。 -:math:`u_t` 和 :math:`r_t` 分别代表了GRU神经元的update gates（更新门）和reset gates(重置门)。 -和LSTM不同，GRU少了一个门（它没有LSTM的forget gate）。但是它有一个叫做中间候选隐藏状态（intermediate candidate hidden output）的输出， -记为 :math:`m_t` 。 该层有三个输出： :math:`h_t, dot(r_t,h_{t-1})` 以及 :math:`u_t，r_t，m_t` 的连结(concatenation)。 - - - - -参数: - - **input** (Variable) – 经FC层变换后的当前步骤的输入值 - - **hidden** (Variable) – 从上一步而来的gru unit 隐藏状态值(hidden value) - - **size** (integer) – 输入数据的维度 - - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重矩阵的参数属性。 - 注意： - - 该权重矩阵形为 :math:`(T×3D)` ， :math:`D` 是隐藏状态的规模（hidden size） - - 该权重矩阵的所有元素由两部分组成， 一是update gate和reset gate的权重，形为 :math:`(D×2D)` ；二是候选隐藏状态（candidate hidden state）的权重矩阵，形为 :math:`(D×D)` - 如果该函数参数值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 param_attr。如果param_attr没有被初始化，那么会由Xavier来初始化它。默认值为None - - **bias_attr** (ParamAttr|bool|None) - GRU的bias变量的参数属性。形为 :math:`(1x3D)` 的bias连结（concatenate）在update gates（更新门），reset gates(重置门)以及candidate calculations（候选隐藏状态计算）中的bias。如果值为False，那么上述三者将没有bias参与运算。若值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 bias_attr。如果bias_attr没有被初始化，那它会被默认初始化为0。默认值为None。 - - **activation** (string) – 神经元 “actNode” 的激励函数（activation）类型。默认类型为‘tanh’ - - **gate_activation** (string) – 门 “actGate” 的激励函数（activation）类型。 默认类型为 ‘sigmoid’ - - -返回： hidden value（隐藏状态的值），reset-hidden value(重置隐藏状态值)，gate values(门值) - -返回类型: 元组（tuple） - - -**代码示例** - -.. code-block:: python - - # 假设我们现在有x_t_data和size=10的之前的隐藏层 - x_t = fluid.layers.fc(input=x_t_data, size=30) - hidden_val, r_h_val, gate_val = fluid.layers.gru_unit(input=x_t, - hidden = prev_hidden) - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_hard_sigmoid: - -hard_sigmoid -------------------------------- - -.. py:function:: paddle.fluid.layers.hard_sigmoid(x, slope=0.2, offset=0.5, name=None) - -HardSigmoid激活算子。 - -sigmoid的分段线性逼近(https://arxiv.org/abs/1603.00391)，比sigmoid快得多。 - -.. math:: - - \\out=\max(0,\min(1,slope∗x+shift))\\ - -斜率是正数。偏移量可正可负的。斜率和位移的默认值是根据上面的参考设置的。建议使用默认值。 - -参数： - - **x** (Variable) - HardSigmoid operator的输入 - - **slope** (FLOAT|0.2) -斜率 - - **offset** (FLOAT|0.5) - 偏移量 - - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 - - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.hard_sigmoid(x, slope=0.3, offset=0.8) - - - - - - -.. _cn_api_fluid_layers_hash: - -hash -------------------------------- - -.. py:function:: paddle.fluid.layers.hash(input, hash_size, num_hash=1, name=None) - -将输入 hash 到一个整数，该数的值小于给定的 hash size - -我们使用的哈希算法是 xxHash - `Extremely fast hash algorithm `_ - -提供一简单的例子： - -.. code-block:: text - - 给出： - - # shape [2, 2] - input.data = [ - [[1], [2]], - [[3], [4]], - ] - - input.lod = [[0, 2]] - - hash_size = 10000 - - num_hash = 4 - - 然后: - - 哈希操作将这个二维input的所有数字作为哈希算法每次的输入。 - - 每个输入都将被哈希4次，最终得到一个长度为4的数组。 - - 数组中的每个值的范围从0到9999。 - - - - # shape [2, 4] - output.data = [ - [[9662], [9217], [1129], [8487]], - [[8310], [1327], [1654], [4567]], - ] - - output.lod = [[0, 2]] - -参数： - - **input** (Variable) - 输入变量是一个 one-hot 词。输入变量的维数必须是2。 - - **hash_size** (int) - 哈希算法的空间大小。输出值将保持在 :math:`[0, hash\_size - 1]` 范围内。 - - **num_hash** (int) - 哈希次数，默认为1。 - - **name** (str, default None) - 该层的名称 - -返回：哈希的结果变量，是一个lodtensor。 - -返回类型： Variable - -**代码示例：** - -.. code-block:: python - - word_dict = paddle.dataset.imdb.word_dict() - x = fluid.layers.data(shape[1], dtype='int32', lod_level=1) - out = fluid.layers.hash(input=x, num_hash=4, hash_size=1000) - - - - - - - - - -.. _cn_api_fluid_layers_hsigmoid: - -hsigmoid -------------------------------- - -.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None, path_table=None, path_code=None, is_custom=False, is_sparse=False) - -层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完全二叉树，也可以使用 ``is_custom`` 参数来传入自定义的树结构来实现层次化。 - -树中每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。 - -hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。 - -使用默认树结构，请参考 `Hierarchical Probabilistic Neural Network Language Model `_ 。 - -若要使用自定义树结构，请设置 ``is_custom`` 值为True。但在此之前，请完成以下几步部署： - -1.使用自定义词典来建立二叉树，每个叶结点都应该是词典中的单词 - -2.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径** 的映射，称之为路径表 ``path_table`` 参数 - -3.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径的编码(code)** 的映射。 编码code是指每次二分类的标签，1为真，0为假 - -4.现在我们的每个单词都已经有自己的路径和路径编码，当对于同一批输入进行操作时，你可以同时传入一批路径和路径编码进行运算。 - -参数: - - **input** (Variable) - 输入张量，shape为 ``[N×D]`` ,其中 ``N`` 是minibatch的大小，D是特征大小。 - - **label** (Variable) - 训练数据的标签。该tensor的shape为 ``[N×1]`` - - **num_classes** (int) - 类别的数量不能少于2。若使用默认树结构，该参数必须用户设置。当 ``is_custom=False`` 时，该项绝不能为None。反之，如果 ``is_custom=True`` ，它取值应为非叶节点的个数，来指明二分类实用的类别数目。 - - **param_attr** (ParamAttr|None) - 可学习参数/ hsigmoid权重的参数属性。如果将其设置为ParamAttr的一个属性或None，则将ParamAttr设置为param_attr。如果没有设置param_attr的初始化器，那么使用用Xavier初始化。默认值:没None。 - - **bias_attr** (ParamAttr|bool|None) - hsigmoid偏置的参数属性。如果设置为False，则不会向输出添加偏置。如果将其设置ParamAttr的一个属性或None，则将ParamAttr设置为bias_attr。如果没有设置bias_attr的初始化器，偏置将初始化为零。默认值:None。 - - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名。默认值:None。 - - **path_table** (Variable|None) – 存储每一批样本从词到根节点的路径。路径应为从叶至根方向。 ``path_table`` 和 ``path_code`` 应具有相同的形, 对于每个样本 i ，path_table[i]为一个类似np.array的结构，该数组内的每个元素都是其双亲结点权重矩阵的索引 - - **path_code** (Variable|None) – 存储每批样本的路径编码，仍然是按从叶至根方向。各样本路径编码批都由其各祖先结点的路径编码组成 - - **is_custom** (bool|False) – 使用用户自定义二叉树取代默认二叉树结构，如果该项为真， 请务必设置 ``path_table`` , ``path_code`` , ``num_classes`` , 否则就需要设置 num_classes - - **is_sparse** (bool|False) – 使用稀疏更新方式，而非密集更新。如果为真， W的梯度和输入梯度将会变得稀疏 - -返回: (LoDTensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1] - -返回类型: Out - - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[2], dtype='float32') - y = fluid.layers.data(name='y', shape=[1], dtype='int64') - out = fluid.layers.hsigmoid(input=x, label=y, num_classes=6) - - - - - - - - - - -.. _cn_api_fluid_layers_im2sequence: - -im2sequence -------------------------------- - -.. py:function:: paddle.fluid.layers.im2sequence(input, filter_size=1, stride=1, padding=0, input_image_size=None, out_stride=1, name=None) - -从输入张量中提取图像张量，与im2col相似，shape={input.batch_size * output_height * output_width, filter_size_H * filter_size_W * input.通道}。这个op使用filter / kernel扫描图像并将这些图像转换成序列。一个图片展开后的timestep的个数为output_height * output_width，其中output_height和output_width由下式计算: - - -.. math:: - output\_size=1+\frac{(2∗padding+img\_size−block\_size+stride-1}{stride} - -每个timestep的维度为 :math:`block\_y * block\_x * input.channels` 。 - -参数: - - **input** （Variable）- 输入张量，格式为[N, C, H, W] - - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个tuple，它必须包含两个整数(filter_size_H, filter_size_W)。否则，过滤器将是一个方阵。 - - **stride** (int|tuple) - 步长大小。如果stride是一个元组，它必须包含两个整数(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 - - **padding** (int|tuple) - 填充大小。如果padding是一个元组，它可以包含两个整数(padding_H, padding_W)，这意味着padding_up = padding_down = padding_H和padding_left = padding_right = padding_W。或者它可以使用(padding_up, padding_left, padding_down, padding_right)来指示四个方向的填充。否则，标量填充意味着padding_up = padding_down = padding_left = padding_right = padding Default: padding = 0。 - - **input_image_size** (Variable) - 输入包含图像的实际大小。它的维度为[batchsize，2]。该参数可有可无，是用于batch推理。 - - **out_stride** (int|tuple) - 通过CNN缩放图像。它可有可无，只有当input_image_size不为空时才有效。如果out_stride是tuple，它必须包含(out_stride_H, out_stride_W)，否则，out_stride_H = out_stride_W = out_stride。 - - **name** (int) - 该layer的名称，可以忽略。 - -返回： LoDTensor shaoe为{batch_size * output_height * output_width, filter_size_H * filter_size_W * input.channels}。如果将输出看作一个矩阵，这个矩阵的每一行都是一个序列的step。 - -返回类型: output - -:: - - Given: - - x = [[[[ 6. 2. 1.] - [ 8. 3. 5.] - [ 0. 2. 6.]] - - [[ 2. 4. 4.] - [ 6. 3. 0.] - [ 6. 4. 7.]]] - - [[[ 6. 7. 1.] - [ 5. 7. 9.] - [ 2. 4. 8.]] - - [[ 1. 2. 1.] - [ 1. 3. 5.] - [ 9. 0. 8.]]]] - - x.dims = {2, 2, 3, 3} - - And: - - filter = [2, 2] - stride = [1, 1] - padding = [0, 0] - - Then: - - output.data = [[ 6. 2. 8. 3. 2. 4. 6. 3.] - [ 2. 1. 3. 5. 4. 4. 3. 0.] - [ 8. 3. 0. 2. 6. 3. 6. 4.] - [ 3. 5. 2. 6. 3. 0. 4. 7.] - [ 6. 7. 5. 7. 1. 2. 1. 3.] - [ 7. 1. 7. 9. 2. 1. 3. 5.] - [ 5. 7. 2. 4. 1. 3. 9. 0.] - [ 7. 9. 4. 8. 3. 5. 0. 8.]] - - output.dims = {8, 8} - - output.lod = [[4, 4]] - - -**代码示例** - -.. code-block:: python - - output = fluid.layers.im2sequence( - input=layer, stride=[1, 1], filter_size=[2, 2]) - - - - - - - - - - -.. _cn_api_fluid_layers_image_resize: - -image_resize -------------------------------- - -.. py:function:: paddle.fluid.layers.image_resize(input, out_shape=None, scale=None, name=None, resample='BILINEAR') - -调整一批图片的大小 - -输入张量的shape为(num_batch, channels, in_h, in_w)，并且调整大小只适用于最后两个维度(高度和宽度)。 - -支持重新取样方法: - - BILINEAR：双线性插值 - NEAREST：最近邻插值 - -参数: - - **input** (Variable) - 图片调整层的输入张量，这是一个shape=4的张量(num_batch, channels, in_h, in_w) - - **out_shape** (list|tuple|Variable|None) - 图片调整层的输出，shape为(out_h, out_w)。默认值:None - - **scale** (float|None)-输入的高度或宽度的乘数因子 。 out_shape和scale至少要设置一个。out_shape的优先级高于scale。默认值:None - - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 - - **resample** (str) - 重采样方法。目前只支持“双线性”。默认值:双线性插值 - - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`actual_shape` 而不是 :code:`out_shape` 。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值:None - - -返回： 4维tensor，shape为 (num_batches, channls, out_h, out_w). - -返回类型: 变量（variable） - -抛出异常： - - :code:`TypeError` - out_shape应该是一个列表、元组或变量。 - - :code:`TypeError` - actual_shape应该是变量或None - - :code:`ValueError` - image_resize的"resample"只能是"BILINEAR"或"NEAREST"。 - - :code:`ValueError` - out_shape 和 scale 不能为 None - - :code:`ValueError` - out_shape 的长度必须为 2 - -**代码示例** - -.. code-block:: python - - out = fluid.layers.image_resize(input, out_shape=[12, 12], resample="NEAREST") - - - - - - - - - - - - -.. _cn_api_fluid_layers_image_resize_short: - -image_resize_short -------------------------------- - -.. py:function:: paddle.fluid.layers.image_resize_short(input, out_short_len, resample='BILINEAR') - -调整一批图片的大小。输入图像的短边将被调整为给定的out_short_len 。输入图像的长边按比例调整大小，最终图像的长宽比保持不变。 - -参数: - - **input** (Variable) - 图像调整图层的输入张量，这是一个4维的形状张量(num_batch, channels, in_h, in_w)。 - - **out_short_len** (int) - 输出图像的短边长度。 - - **resample** (str) - resample方法，默认为双线性插值。 - -返回： 4维张量，shape为(num_batch, channls, out_h, out_w) - -返回类型: 变量（variable） - - - - - - - - - - - -.. _cn_api_fluid_layers_l2_normalize: - -l2_normalize -------------------------------- - -.. py:function:: paddle.fluid.layers.l2_normalize(x,axis,epsilon=1e-12,name=None) - -L2正则（L2 normalize Layer） - -该层用欧几里得距离之和对维轴的x归一化。对于1-D张量（系数矩阵的维度固定为0），该层计算公式如下： - -.. math:: - - y=\frac{x}{\sqrt{\sum x^{2}+epsion}} - -对于x多维的情况，该函数分别对维度轴上的每个1-D切片单独归一化 - -参数： - - **x** (Variable|list)- l2正则层（l2_normalize layer）的输入 - - **axis** (int)-运用归一化的轴。如果轴小于0，归一化的维是rank(X)+axis。-1是最后维 - - **epsilon** (float)-epsilon用于避免分母为0，默认值为1e-10 - - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名 - - 返回：输出张量，同x的维度一致 - - 返回类型：变量 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data(name="data", - shape=(3, 17, 13), - dtype="float32") - normed = fluid.layers.l2_normalize(x=data, axis=1) - - - - - - - - - -.. _cn_api_fluid_layers_label_smooth: - -label_smooth -------------------------------- - -.. py:function:: paddle.fluid.layers.label_smooth(label, prior_dist=None, epsilon=0.1, dtype='float32', name=None) - -标签平滑是一种对分类器层进行正则化的机制，称为标签平滑正则化(LSR)。 - - -由于直接优化正确标签的对数似然可能会导致过拟合，降低模型的适应能力，因此提出了标签平滑的方法来降低模型置信度。 -标签平滑使用标签 :math:`y` 自身和一些固定模式随机分布变量 :math:`\mu` 。对 :math:`k` 标签，我们有： - -.. math:: - \tilde{y_k} = (1 - \epsilon) * y_k + \epsilon * \mu_k, - -其中 :math:`1-\epsilon` 和 :math:`\epsilon` 分别是权重， :math:`\tilde{y_k}` 是平滑后的标签。 通常μ 使用均匀分布 - - -查看更多关于标签平滑的细节 https://arxiv.org/abs/1512.00567 - -参数： - - **label** （Variable） - 包含标签数据的输入变量。 标签数据应使用 one-hot 表示。 - - **prior_dist** （Variable） - 用于平滑标签的先验分布。 如果未提供，则使用均匀分布。 prior_dist的shape应为 :math:`(1，class\_num)` 。 - - **epsilon** （float） - 用于混合原始真实分布和固定分布的权重。 - - **dtype** （np.dtype | core.VarDesc.VarType | str） - 数据类型：float32，float_64，int等。 - - **name** （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名图层。 - -返回：张量变量, 包含平滑后的标签 - -返回类型: Variable - -**代码示例** - -.. code-block:: python - - label = layers.data(name="label", shape=[1], dtype="float32") - one_hot_label = layers.one_hot(input=label, depth=10) - smooth_label = layers.label_smooth( - label=one_hot_label, epsilon=0.1, dtype="float32") - - - - - - - - - -.. _cn_api_fluid_layers_layer_norm: - -layer_norm -------------------------------- - -.. py:function:: paddle.fluid.layers.layer_norm(input, scale=True, shift=True, begin_norm_axis=1, epsilon=1e-05, param_attr=None, bias_attr=None, act=None, name=None) - -假设特征向量存在于维度 ``begin_norm_axis ... rank (input）`` 上，计算大小为 ``H`` 的特征向量a在该维度上的矩统计量，然后使用相应的统计量对每个特征向量进行归一化。 之后，如果设置了 ``scale`` 和 ``shift`` ，则在标准化的张量上应用可学习的增益和偏差以进行缩放和移位。 - -请参考 `Layer Normalization `_ - -公式如下 - -.. math:: - \\\mu=\frac{1}{H}\sum_{i=1}^{H}a_i\\ -.. math:: - \\\sigma=\sqrt{\frac{1}{H}\sum_i^H{(a_i-\mu)^2}}\\ -.. math:: - \\h=f(\frac{g}{\sigma}(a-\mu) + b)\\ - -- :math:`\alpha` : 该层神经元输入总和的向量表示 -- :math:`H` : 层中隐藏的神经元个数 -- :math:`g` : 可训练的缩放因子参数 -- :math:`b` : 可训练的bias参数 - - -参数: - - **input** （Variable） - 输入张量变量。 - - **scale** （bool） - 是否在归一化后学习自适应增益g。默认为True。 - - **shift** （bool） - 是否在归一化后学习自适应偏差b。默认为True。 - - **begin_norm_axis** （int） - ``begin_norm_axis`` 到 ``rank（input）`` 的维度执行规范化。默认1。 - - **epsilon** （float） - 添加到方差的很小的值，以防止除零。默认1e-05。 - - **param_attr** （ParamAttr | None） - 可学习增益g的参数属性。如果 ``scale`` 为False，则省略 ``param_attr`` 。如果 ``scale`` 为True且 ``param_attr`` 为None，则默认 ``ParamAttr`` 将作为比例。如果添加了 ``param_attr``， 则将其初始化为1。默认None。 - - **bias_attr** （ParamAttr | None） - 可学习偏差的参数属性b。如果 ``shift`` 为False，则省略 ``bias_attr`` 。如果 ``shift`` 为True且 ``param_attr`` 为None，则默认 ``ParamAttr`` 将作为偏差。如果添加了 ``bias_attr`` ，则将其初始化为0。默认None。 - - **act** （str） - 激活函数。默认 None - - **name** （str） - 该层的名称， 可选的。默认为None，将自动生成唯一名称。 - -返回： 标准化后的结果 - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 32, 32], - dtype='float32') - x = fluid.layers.layer_norm(input=data, begin_norm_axis=1) - - - - - - - - - -.. _cn_api_fluid_layers_leaky_relu: - -leaky_relu -------------------------------- - -.. py:function:: paddle.fluid.layers.leaky_relu(x, alpha=0.02, name=None) - -LeakyRelu 激活函数 - -.. math:: out=max(x,α∗x) - -参数: - - **x** (Variable) - LeakyRelu Operator的输入 - - **alpha** (FLOAT|0.02) - 负斜率，值很小。 - - **name** (str|None) - 此层的名称(可选)。如果设置为None，该层将被自动命名。 - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[2,3,16,16], dtype="float32") - y = fluid.layers.leaky_relu(x, alpha=0.01) - - - - - - - -.. _cn_api_fluid_layers_linear_chain_crf: - -linear_chain_crf -------------------------------- - -.. py:function:: paddle.fluid.layers.linear_chain_crf(input, label, param_attr=None) - -线性链条件随机场（Linear Chain CRF） - -条件随机场定义间接概率图，节点代表随机变量，边代表两个变量之间的依赖。CRF学习条件概率 :math:`P\left ( Y|X \right )` ， :math:`X = \left ( x_{1},x_{2},...,x_{n} \right )` 是结构性输入，:math:`Y = \left ( y_{1},y_{2},...,y_{n} \right )` 为输入标签。 - -线性链条件随机场（Linear Chain CRF)是特殊的条件随机场（CRF），有利于序列标注任务。序列标注任务不为输入设定许多条件依赖。唯一的限制是输入和输出必须是线性序列。因此类似CRF的图是一个简单的链或者线，也就是线性链随机场（linear chain CRF）。 - -该操作符实现了线性链条件随机场（linear chain CRF）的前向——反向算法。详情请参照 http://www.cs.columbia.edu/~mcollins/fb.pdf 和 http://cseweb.ucsd.edu/~elkan/250Bwinter2012/loglinearCRFs.pdf。 - -公式： - - 1.这里x代表Emission - - 2.Transition的第一维度值，代表起始权重，这里用a表示 - - 3.Transition的下一维值，代表末尾权重，这里用b表示 - - 4.Transition剩下的值，代表转移权重，这里用w表示 - - 5.Label用s表示 - - 长度为L的序列s的概率定义如下： - -.. math:: - - P(s) = (1/Z)exp(a_{s_{1}}+b_{s_{L}}+sum_{L}^{l=1}x_{s+{l}}+sum_{L}^{l=2}w_{s_{l-1},s_{l}}) - -其中Z是正则化值，所有可能序列的P(s)之和为1，x是线性链条件随机场（linear chain CRF）的发射（emission）特征权重。 - -线性链条件随机场最终输出mini-batch每个训练样本的条件概率的对数 - -**注意：** - - 1.条件随机场（CRF）的特征函数由发射特征(emission feature）和转移特征（transition feature）组成。发射特征（emission feature）权重在调用函数前计算，而不在函数里计算。 - - 2.由于该函数对所有可能序列的进行全局正则化，发射特征（emission feature）权重应是未缩放的。因此如果该函数带有发射特征（emission feature），并且发射特征是任意非线性激活函数的输出，则请勿调用该函数。 - - 3.Emission的第二维度必须和标记数字（tag number）相同 - -参数： - - **input** (Variable，LoDTensor，默认float类型LoDTensor) - 一个二维LoDTensor，shape为[N*D]，N是mini-batch的大小，D是总标记数。线性链条件随机场的未缩放发射权重矩阵 - - **input** (Tensor，默认float类型LoDTensor) - 一个二维张量，shape为[(D+2)*D]。linear_chain_crf操作符的可学习参数。更多详情见operator注释 - - **label** (Variable，LoDTensor，默认int64类型LoDTensor） - shape为[N*10的LoDTensor，N是mini-batch的总元素数 - - **param_attr** (ParamAttr) - 可学习参数的属性 - -返回： - output(Variable，Tensor，默认float类型Tensor)：shape为[N*D]的二维张量。Emission的指数。这是前向计算中的中间计算结果，在后向计算中还会复用 - - output(Variable，Tensor，默认float类型Tensor)：shape为[(D+2)*D]的二维张量。Transition的指数。这是前向计算中的中间计算结果，在后向计算中还会复用 - - output(Variable,Tensor，默认float类型Tensor)：mini-batch每个训练样本的条件概率的对数。这是一个shape为[S*1]的二维张量，S是mini-batch的序列数。注：S等同于mini-batch的序列数。输出不再是LoDTensor - -返回类型：output（Variable） - - - - - - - - - - - - -.. _cn_api_fluid_layers_lod_reset: - -lod_reset -------------------------------- - -.. py:function:: paddle.fluid.layers.lod_reset(x, y=None, target_lod=None) - - -设定x的LoD为y或者target_lod。如果提供y，首先将y.lod指定为目标LoD,否则y.data将指定为目标LoD。如果未提供y，目标LoD则指定为target_lod。如果目标LoD指定为Y.data或target_lod，只提供一层LoD。 - -:: - - - * 例1: - - 给定一级LoDTensor x: - x.lod = [[ 2, 3, 1 ]] - x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - x.dims = [6, 1] - - target_lod: [4, 2] - - 得到一级LoDTensor: - out.lod = [[4, 2]] - out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - out.dims = [6, 1] - - * 例2: - - 给定一级LoDTensor x: - x.lod = [[2, 3, 1]] - x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - x.dims = [6, 1] - - y是张量（Tensor）: - y.data = [[2, 4]] - y.dims = [1, 3] - - 得到一级LoDTensor: - out.lod = [[2, 4]] - out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - out.dims = [6, 1] - - * 例3: - - 给定一级LoDTensor x: - x.lod = [[2, 3, 1]] - x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - x.dims = [6, 1] - - y是二级LoDTensor: - y.lod = [[2, 2], [2, 2, 1, 1]] - y.data = [[1.1], [2.1], [3.1], [4.1], [5.1], [6.1]] - y.dims = [6, 1] - - 得到一个二级LoDTensor: - out.lod = [[2, 2], [2, 2, 1, 1]] - out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] - out.dims = [6, 1] - -参数： - - **x** (Variable)-输入变量，可以为Tensor或者LodTensor - - **y** (Variable|None)-若提供，输出的LoD则衍生自y - - **target_lod** (list|tuple|None)-一层LoD，y未提供时作为目标LoD - -返回：输出变量，该层指定为LoD - -返回类型：变量 - -提示：抛出异常 - 如果y和target_lod都为空 - -**代码示例**： - -.. code-block:: python - - x = layers.data(name='x', shape=[10]) - y = layers.data(name='y', shape=[10, 20], lod_level=2) - out = layers.lod_reset(x=x, y=y) - - - - - - - - - -.. _cn_api_fluid_layers_log: - -log -------------------------------- - -.. py:function:: paddle.fluid.layers.log(x, name=None) - - -给定输入张量，计算其每个元素的自然对数 - -.. math:: - \\Out=ln(x)\\ - - -参数: - - **x** (Variable) – 输入张量 - - **name** (str|None, default None) – 该layer的名称，如果为None，自动命名 - -返回：给定输入张量计算自然对数 - -返回类型: 变量（variable） - - -**代码示例** - -.. code-block:: python - - output = fluid.layers.log(x) - - - - - - - - - - - -.. _cn_api_fluid_layers_log_loss: - -log_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.log_loss(input, label, epsilon=0.0001, name=None) - -**负log loss层** - -该层对输入的预测结果和目的标签进行计算，返回负log loss损失值。 - -.. math:: - - Out = -label * \log{(input + \epsilon)} - (1 - label) * \log{(1 - input + \epsilon)} - - -参数: - - **input** (Variable|list) – 形为[N x 1]的二维张量, 其中N为batch大小。 该输入是由先前运算得来的概率集。 - - **label** (Variable|list) – 形为[N x 1]的二维张量，承载着正确标记的数据， 其中N为batch大小。 - - **epsilon** (float) – epsilon - - **name** (string) – log_loss层的名称 - -返回： 形为[N x 1]的二维张量，承载着负log_loss值 - -返回类型: 变量（Variable） - - -**代码示例** - -.. code-block:: python - - prob = fluid.layers.sigmoid(net) - cost = fluid.layers.log_loss(input=prob, label=label) - - - - - - - - - - - -.. _cn_api_fluid_layers_logical_and: - -logical_and -------------------------------- - -.. py:function:: paddle.fluid.layers.logical_and(x, y, out=None, name=None) - -logical_and算子 - -它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： - -.. math:: - Out = X \&\& Y - -参数： - - **x** （Variable）- （LoDTensor）logical_and运算符的左操作数 - - **y** （Variable）- （LoDTensor）logical_and运算符的右操作数 - - **out** （Tensor）- 输出逻辑运算的张量。 - - **name** （basestring | None）- 输出的名称。 - -返回： (LoDTensor)n-dim bool张量。每个元素的计算公式： :math:`Out = X \&\& Y` - -返回类型： 输出（Variable）。 - - -**代码示例：** - -.. code-block:: python - - left = fluid.layers.data( - name='left', shape=[1], dtype='int32') - right = fluid.layers.data( - name='right', shape=[1], dtype='int32') - result = fluid.layers.logical_and(x=left, y=right) - - - - - - - - - -.. _cn_api_fluid_layers_logical_not: - -logical_not -------------------------------- - -.. py:function:: paddle.fluid.layers.logical_not(x, out=None, name=None) - -logical_not算子 - -它在X上以元素方式操作，并返回Out。X和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： - -.. math:: - Out = !X - -参数： - - **x** （Variable）- （LoDTensor）logical_not运算符的操作数 - - **out** （Tensor）- 输出逻辑运算的张量。 - - **name** （basestring | None）- 输出的名称。 - -返回： (LoDTensor)n维布尔张量。 - -返回类型： 输出（Variable）。 - - -**代码示例：** - -.. code-block:: python - - left = fluid.layers.data( - name='left', shape=[1], dtype='int32') - result = fluid.layers.logical_not(x=left) - - - - - - - -.. _cn_api_fluid_layers_logical_or: - -logical_or -------------------------------- - -.. py:function:: paddle.fluid.layers.logical_or(x, y, out=None, name=None) - -logical_or算子 - -它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： - -.. math:: - Out = X || Y - -参数： - - **x** （Variable）- （LoDTensor）logical_or运算符的左操作数 - - **y** （Variable）- （LoDTensor）logical_or运算符的右操作数 - - **out** （Tensor）- 输出逻辑运算的张量。 - - **name** （basestring | None）- 输出的名称。 - -返回： (LoDTensor)n维布尔张量。每个元素的计算公式： :math:`Out = X || Y` - -返回类型： 输出（Variable）。 - - - -**代码示例：** - -.. code-block:: python - - left = fluid.layers.data( - name='left', shape=[1], dtype='int32') - right = fluid.layers.data( - name='right', shape=[1], dtype='int32') - result = fluid.layers.logical_or(x=left, y=right) - - - - - - -.. _cn_api_fluid_layers_logical_xor: - -logical_xor -------------------------------- - -.. py:function:: paddle.fluid.layers.logical_xor(x, y, out=None, name=None) - -logical_xor算子 - -它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： - -.. math:: - Out = (X || Y) \&\& !(X \&\& Y) - -参数： - - **x** （Variable）- （LoDTensor）logical_xor运算符的左操作数 - - **y** （Variable）- （LoDTensor）logical_xor运算符的右操作数 - - **out** （Tensor）- 输出逻辑运算的张量。 - - **name** （basestring | None）- 输出的名称。 - -返回： (LoDTensor)n维布尔张量。 - -返回类型： 输出（Variable）。 - - - -**代码示例：** - -.. code-block:: python - - left = fluid.layers.data( - name='left', shape=[1], dtype='int32') - right = fluid.layers.data( - name='right', shape=[1], dtype='int32') - result = fluid.layers.logical_xor(x=left, y=right) - - - - - - -.. _cn_api_fluid_layers_lrn: - -lrn -------------------------------- - -.. py:function:: paddle.fluid.layers.lrn(input, n=5, k=1.0, alpha=0.0001, beta=0.75, name=None) - -局部响应正则层（Local Response Normalization Layer） - -该层对局部输入区域正则化，执行一种侧向抑制（lateral inhibition）。 - -公式如下： - -.. math:: - - Output(i,x,y) = Input(i,x,y)/\left ( k+\alpha \sum_{j=max(0,c-n/2)}^{min(C,c+n/2)}(Input(j,x,y))^2 \right )^\beta - -在以上公式中： - - :math:`n` ：累加的通道数 - - :math:`k` ：位移（避免除数为0） - - :math:`\alpha` ： 缩放参数 - - :math:`\beta` ： 指数参数 - -参考 : `ImageNet Classification with Deep Convolutional Neural Networks `_ - -参数： - - **input** （Variable）- 该层输入张量，输入张量维度必须为4 - - **n** (int，默认5） - 累加哦的通道数 - - **k** （float，默认1.0）- 位移（通常为正数，避免除数为0） - - **alpha** （float，默认1e-4）- 缩放参数 - - **beta** （float，默认0.75）- 指数 - - **name** （str，默认None）- 操作符名 - -抛出异常: - - ``ValueError`` - 如果输入张量的阶不为4 - -返回：张量，存储转置结果 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data( - name="data", shape=[3, 112, 112], dtype="float32") - lrn = fluid.layers.lrn(input=data) - - - - - - - - - - - -.. _cn_api_fluid_layers_lstm: - -lstm -------------------------------- - -.. py:function:: paddle.fluid.layers.lstm(input, init_h, init_c, max_len, hidden_size, num_layers, dropout_prob=0.0, is_bidirec=False, is_test=False, name=None, default_initializer=None, seed=-1) - -如果您的设备是GPU，本op将使用cudnn LSTM实现 - -一个没有 peephole 连接的四门长短期记忆网络。在前向传播中，给定迭代的输出ht和单元输出ct可由递归输入ht-1、单元输入ct-1和上一层输入xt计算，给定矩阵W、R和bias bW, bR由下式计算: - -.. math:: - - i_t = \sigma(W_{ix}x_{t} + W_{ih}h_{t-1} + bx_i + bh_i)\\ - f_t = \sigma(W_{fx}x_{t} + W_{fh}h_{t-1} + bx_f + bh_f)\\ - o_t = \sigma(W_{ox}x_{t} + W_{oh}h_{t-1} + bx_o + bh_o)\\ - \tilde{c_t} = tanh(W_{cx}x_t + W_{ch}h_{t-1} + bx_c + bh_c)\\ - c_t = f_t \odot c_{t-1} + i_t \odot \tilde{c_t}\\ - h_t = o_t \odot tanh(c_t) - -公式中： - - W 项表示权重矩阵(e.g. :math:`W_{ix}` 是从输入门到输入的权重矩阵) - - b 项表示偏差向量( :math:`b_{xi}` 和 :math:`b_{hi}` 是输入门的偏差向量) - - sigmoid 是 logistic sigmoid 函数 - - i、f、o、c 分别为输入门、遗忘门、输出门和激活向量，它们的大小与 cell 输出激活向量h相同。 - - :math:`\odot` 是向量的元素乘积 - - tanh是激活函数 - - :math:`\tilde{c_t}` 也称为候选隐藏状态，它是根据当前输入和之前的隐藏状态来计算的 - - sigmoid的计算公式为：sigmoid(x) = 1 / (1 + e^-x) - - \*表示点乘，X表示矩阵乘 - -参数： - - **input** (Variable) - LSTM 输入张量，形状必须为(seq_len x，batch_size，x，input_size) - - **init_h** (Variable) – LSTM的初始隐藏状态，是一个有形状的张量(num_layers，x，batch_size，x，hidden_size)如果is_bidirec = True，形状应该是(num_layers*2，x， batch_size， x， hidden_size) - - **init_c** (Variable) - LSTM的初始状态。这是一个有形状的张量(num_layers， x， batch_size， x， hidden_size)如果is_bidirec = True，形状应该是(num_layers*2， x， batch_size， x， hidden_size) - - **max_len** (int) – LSTM的最大长度。输入张量的第一个 dim 不能大于max_len - - **hidden_size** (int) - LSTM的隐藏大小 - - **num_layers** (int) – LSTM的总层数 - - **dropout_prob** (float|0.0) – dropout prob，dropout 只在 rnn 层之间工作，而不是在时间步骤之间。dropout 不作用于最后的 rnn 层的 rnn 输出中 - - **is_bidirec** (bool) – 是否是双向的 - - **is_test** (bool) – 是否在测试阶段 - - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 - - **default_initializer** (Initialize|None) – 在哪里使用初始化器初始化权重，如果没有设置，将进行默认初始化。 - - **seed** (int) – LSTM中dropout的Seed，如果是-1,dropout将使用随机Seed - -返回： - - LSTM hidden的结果：形状(seq_len x batch_size x hidden_size)如果is_bidirec设置为True,形状为(seq_len x batch_sze hidden_size * 2) - - last_h(Tensor): LSTM最后一步的隐藏状态，形状为(num_layers x batch_size x hidden_size)；如果is_bidirec设置为True，形状为(num_layers*2 x batch_size x hidden_size) - - last_c(Tensor)： LSTM最后一步的cell状态，形状为(num_layers x batch_size x hidden_size)；如果is_bidirec设置为True，形状为(num_layers*2 x batch_size x hidden_size) - -**代码示例：** - -.. code-block:: python - - input = embedding - batch_size = 20 - max_len = 100 - dropout_prob = 0.2 - input_size = 100 - hidden_size = 150 - num_layers = 1 - init_hidden1 = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0, stop_grad=False) - init_cell1 = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0, stop_grad=False) - - rnn_out, last_h, last_c = layers.lstm( input, init_h, init_c, max_len, dropout_prob, input_size, hidden_size, num_layers) - - - - - - - - - - - - -.. _cn_api_fluid_layers_lstm_unit: - -lstm_unit -------------------------------- - -.. py:function:: paddle.fluid.layers.lstm_unit(x_t, hidden_t_prev, cell_t_prev, forget_bias=0.0, param_attr=None, bias_attr=None, name=None) - -Lstm unit layer - -lstm步的等式： - -.. math:: - - i_{t} &= \sigma \left ( W_{x_{i}}x_{t}+W_{h_{i}}h_{t-1}+b_{i} \right ) \\ - f_{t} &= \sigma \left ( W_{x_{f}}x_{t}+W_{h_{f}}h_{t-1}+b_{f} \right ) \\ - c_{t} &= f_{t}c_{t-1}+i_{t}tanh\left ( W_{x_{c}}x_{t} +W_{h_{c}}h_{t-1}+b_{c}\right ) \\ - o_{t} &= \sigma \left ( W_{x_{o}}x_{t}+W_{h_{o}}h_{t-1}+b_{o} \right ) \\ - h_{t} &= o_{t}tanh \left ( c_{t} \right ) - -lstm单元的输入包括 :math:`x_{t}` ， :math:`h_{t-1}` 和 :math:`c_{t-1}` 。:math:`h_{t-1}` 和 :math:`c_{t-1}` 的第二维应当相同。在此实现过程中，线性转换和非线性转换分离。以 :math:`i_{t}` 为例。线性转换运用到fc层，等式为： - -.. math:: - - L_{i_{t}} = W_{x_{i}}x_{t} + W_{h_{i}}h_{t-1} + b_{i} - -非线性转换运用到lstm_unit运算，方程如下： - -.. math:: - - i_{t} = \sigma \left ( L_{i_{t}} \right ) - -该层有 :math:`h_{t}` 和 :math:`o_{t}` 两个输出。 - -参数： - - **x_t** (Variable) - 当前步的输入值，二维张量，shape为 M x N ，M是批尺寸，N是输入尺寸 - - **hidden_t_prev** (Variable) - lstm单元的隐藏状态值，二维张量，shape为 M x S，M是批尺寸，N是lstm单元的大小 - - **cell_t_prev** (Variable) - lstm单元的cell值，二维张量，shape为 M x S ，M是批尺寸，N是lstm单元的大小 - - **forget_bias** (Variable) - lstm单元的遗忘bias - - **param_attr** (ParamAttr|None) - 可学习hidden-hidden权重的擦参数属性。如果设为None或者ParamAttr的一个属性，lstm_unit创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数初始化为Xavier。默认：None - - **bias_attr** (ParamAttr|None) - 可学习bias权重的bias属性。如果设为False，输出单元中则不添加bias。如果设为None或者ParamAttr的一个属性，lstm_unit创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认：None - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名 - -返回：lstm单元的hidden(隐藏状态)值和cell值 - -返回类型：tuple（元组） - -抛出异常: - - ``ValueError`` - ``x_t``，``hidden_t_prev`` 和 ``cell_t_prev`` 的阶不为2，或者 ``x_t`` ，``hidden_t_prev`` 和 ``cell_t_prev`` 的第一维不一致，或者 ``hidden_t_prev`` 和 ``cell_t_prev`` 的第二维不一致 - -**代码示例**： - -.. code-block:: python - - x_t = fluid.layers.fc(input=x_t_data, size=10) - prev_hidden = fluid.layers.fc(input=prev_hidden_data, size=30) - prev_cell = fluid.layers.fc(input=prev_cell_data, size=30) - hidden_value, cell_value = fluid.layers.lstm_unit(x_t=x_t, - hidden_t_prev=prev_hidden, - cell_t_prev=prev_cell) - - - - - - - - - - - -.. _cn_api_fluid_layers_margin_rank_loss: - -margin_rank_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.margin_rank_loss(label, left, right, margin=0.1, name=None) - -margin rank loss（差距排序损失）层。在排序问题中，它可以比较传进来的 ``left`` 得分和 ``right`` 得分。 - -可用如下等式定义： - -.. math:: - rank\_loss = max(0, -label * (left - right) + margin) - - -参数: - - **label** (Variable) – 表明是否左元素排名要高于右元素 - - **left** (Variable) – 左元素排序得分 - - **right** (Variable) – 右元素排序得分 - - **margin** (float) – 指定固定的得分差 - - **name** (str|None) – 可选项，该层的命名。如果为None, 该层将会被自动命名 - -返回： 排序损失 - -返回类型: 变量（Variable） - -抛出异常: - - ``ValueError`` - ``label`` , ``left`` , ``right`` 有一者不为Variable类型时，抛出此异常 - -**代码示例** - -.. code-block:: python - - label = fluid.layers.data(name="label", shape=[4, 1], dtype="float32") - left = fluid.layers.data(name="left", shape=[4, 1], dtype="float32") - right = fluid.layers.data(name="right", shape=[4, 1], dtype="float32") - out = fluid.layers.margin_rank_loss(label, left, right) - - - - - - - - - - - -.. _cn_api_fluid_layers_matmul: - - - -matmul -------------------------------- - -.. py:function:: paddle.fluid.layers.matmul(x, y, transpose_x=False, transpose_y=False, alpha=1.0, name=None) - -对两个张量进行矩阵相乘 - -当前输入的张量可以为任意阶，但当任意一个输入的阶数大于3时，两个输入的阶必须相等。 -实际的操作取决于x,y的维度和 ``transpose_x`` , ``transpose_y`` 的标记值。具体如下： - -- 如果transpose值为真，则对应 ``tensor`` 的最后两位将被转置。如：x是一个shape=[D]的一阶张量，那么x在非转置形式中为[1,D]，在转置形式中为[D,1],而y则相反，在非转置形式中作为[D,1]，在转置形式中作为[1,D]。 - -- 转置后，这两个`tensors`将为 2-D 或 n-D ,并依据下列规则进行矩阵相乘： - - 如果两个都是2-D，则同普通矩阵一样进行矩阵相乘 - - 如果任意一个是n-D，则将其视为驻留在最后两个维度的矩阵堆栈，并在两个张量上应用支持广播的批处理矩阵乘法。 - -**注意，如果原始张量x或y的秩为1且没有转置，则在矩阵乘法之后，前置或附加维度1将被移除。** - - -参数： - - **x** (Variable)-输入变量，类型为Tensor或LoDTensor - - **y** (Variable)-输入变量，类型为Tensor或LoDTensor - - **transpose_x** (bool)-相乘前是否转置x - - **transeptse_y** (bool)-相乘前是否转置y - - **alpha** (float)-输出比例。默认为1.0 - - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名 - -返回：张量乘积变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - # 以下是解释输入和输出维度的示例 - # x: [B, ..., M, K], y: [B, ..., K, N] - fluid.layers.matmul(x, y) # out: [B, ..., M, N] - - # x: [B, M, K], y: [B, K, N] - fluid.layers.matmul(x, y) # out: [B, M, N] - - # x: [B, M, K], y: [K, N] - fluid.layers.matmul(x, y) # out: [B, M, N] - - # x: [M, K], y: [K, N] - fluid.layers.matmul(x, y) # out: [M, N] - - # x: [B, M, K], y: [K] - fluid.layers.matmul(x, y) # out: [B, M] - - # x: [K], y: [K] - fluid.layers.matmul(x, y) # out: [1] - - # x: [M], y: [N] - fluid.layers.matmul(x, y, True, True) # out: [M, N] - - - - - - - - - -.. _cn_api_fluid_layers_maxout: - -maxout -------------------------------- - -.. py:function:: paddle.fluid.layers.maxout(x, groups, name=None) - -假设输入形状为(N, Ci, H, W)，输出形状为(N, Co, H, W)，则 :math:`Co=Ci/groups` 运算公式如下: - -.. math:: - - y_{si+j} &= \max_k x_{gsi + sk + j} \\ - g &= groups \\ - s &= \frac{input.size}{num_channels} \\ - 0 &\le i < \frac{num_channels}{groups} \\ - 0 &\le j < s \\ - 0 &\le k < groups - - -请参阅论文: - - Maxout Networks: http://www.jmlr.org/proceedings/papers/v28/goodfellow13.pdf - - Multi-digit Number Recognition from Street View Imagery using Deep Convolutional Neural Networks: https://arxiv.org/pdf/1312.6082v4.pdf - -参数： - - **x** (Variable) - (tensor) maxout算子的输入张量。输入张量的格式为NCHW。其中N为 batch size ，C为通道数，H和W为feature的高和宽 - - **groups** （INT）- 指定输入张量将被分成多少组“通道维数”。输出通道的数量以组为单位。 - - **name** (basestring|None) - 输出的名称 - -返回：Tensor，maxout算子的输出张量。输出张量的格式也是NCHW。其中N为 batch size，C为通道数，H和W为特征的高和宽。 - -返回类型：out（variable） - - - - - - - - - - -.. _cn_api_fluid_layers_mean: - -mean -------------------------------- - -.. py:function:: paddle.fluid.layers.mean(x, name=None) - -mean算子计算X中所有元素的平均值 - -参数： - - **x** (Variable)- (Tensor) 均值运算的输入。 - - **name** (basestring | None)- 输出的名称。 - -返回： 均值运算输出张量（Tensor） - -返回类型： Variable - - - - - - - - - - -.. _cn_api_fluid_layers_mean_iou: - -mean_iou -------------------------------- - -.. py:function:: paddle.fluid.layers.mean_iou(input, label, num_functiones) - -均值IOU（Mean Intersection-Over-Union）是语义图像分割中的常用的评价指标之一，它首先计算每个语义类的IOU，然后计算类之间的平均值。定义如下: - - .. math:: IOU = \frac{true_positi}{true_positive+false_positive+false_negative} - -在一个混淆矩阵中累积得到预测值，然后从中计算均值-IOU。 - -参数: - - **input** (Variable) - 类型为int32或int64的语义标签的预测结果张量。 - - **label** (Variable) - int32或int64类型的真实label张量。它的shape应该与输入相同。 - - **num_classes** (int) - 标签可能的类别数目。 - -返回: 张量，shape为[1]， 代表均值IOU。out_wrong(变量):张量，shape为[num_classes]。每个类别中错误的个数。out_correct(变量):张量，shape为[num_classes]。每个类别中的正确个数。 - -返回类型: mean_iou(Variable) - -**代码示例**: - -.. code-block:: python - - iou, wrongs, corrects = fluid.layers.mean_iou(predict, label, num_classes) - - - - - - - - - -.. _cn_api_fluid_layers_merge_selected_rows: - -merge_selected_rows -------------------------------- - -.. py:function:: paddle.fluid.layers.merge_selected_rows(x, name=None) - -**实现合并选中行（row）操作** - -该运算用于合并（值相加）输入张量中重复的行。输出行没有重复的行，并且按值从小到大顺序重新对行排序。 - -:: - - 例如： - - 输入: - X.rows = [0, 5, 5, 4, 19] - X.height = 20 - X.value = [[1, 1] [2, 2] [3, 3] [4, 4] [6, 6]] - - - 输出： - Out.row is [0, 4, 5, 19] - Out.height is 20 - Out.value is: [[1, 1] [4, 4] [5, 5] [6, 6]] - - - -参数: - - x (Variable) – 输入类型为SelectedRows, 选中行有可能重复 - - name (basestring|None) – 输出变量的命名 - -返回: 输出类型为SelectedRows，并且选中行不会重复 - -返回类型: 变量（Variable） - - - - - - - - - - - -.. _cn_api_fluid_layers_mul: - -mul -------------------------------- - -.. py:function:: paddle.fluid.layers.mul(x, y, x_num_col_dims=1, y_num_col_dims=1, name=None) - -mul算子 -此运算是用于对输入X和Y执行矩阵乘法。 -等式是： - -.. math:: - Out = X * Y - -输入X和Y都可以携带LoD（详细程度）信息。但输出仅与输入X共享LoD信息。 - -参数： - - **x** (Variable)- (Tensor) 乘法运算的第一个输入张量。 - - **y** (Variable)- (Tensor) 乘法运算的第二个输入张量。 - - **x_num_col_dims** （int）- 默认值1， 可以将具有两个以上维度的张量作为输入。如果输入X是具有多于两个维度的张量，则输入X将先展平为二维矩阵。展平规则是：前 ``num_col_dims`` 将被展平成最终矩阵的第一个维度（矩阵的高度），其余的 rank(X) - num_col_dims 维度被展平成最终矩阵的第二个维度（矩阵的宽度）。结果是展平矩阵的高度等于X的前 ``x_num_col_dims`` 维数的乘积，展平矩阵的宽度等于X的最后一个秩（x）- ``num_col_dims`` 个剩余维度的维数的乘积。例如，假设X是一个五维张量，形状为（2,3,4,5,6）。 则扁平化后的张量具有的形即为 （2x3x4,5x6）=（24,30）。 - - **y_num_col_dims** （int）- 默认值1， 可以将具有两个以上维度的张量作为输入。如果输入Y是具有多于两个维度的张量，则Y将首先展平为二维矩阵。 ``y_num_col_dims`` 属性确定Y的展平方式。有关更多详细信息，请参阅 ``x_num_col_dims`` 的注释。 - - **name** (basestring | None)- 输出的名称。 - -返回： 乘法运算输出张量（Tensor）. - -返回类型： 输出(Variable)。 - - - - - - - - - - -.. _cn_api_fluid_layers_multiplex: - -multiplex -------------------------------- - -.. py:function:: paddle.fluid.layers.multiplex(inputs, index) - -引用给定的索引变量，该层从输入变量中选择行构造Multiplex变量。 - -假设有 :math:`m` 个输入变量，:math:`I_{i}` 代表第i个输入变量，而且 :math:`i` is in :math:`[0,m)` 。 - -所有输入变量都是具有相同形状的张量 :math:`[d_0,d_1, ... ,d_R]` 。 - -请注意，输入张量的秩应至少为2。每个输入变量将被视为形状为 :math:`[M，N]` 的二维矩阵，其中 :math:`M` 表示 :math:`d0` ，N表示 :math:`d_1 * d_2 * ... * d_R` 。 - -设 :math:`I_{i}[j]` 为第i个输入变量的第j行。 给定的索引变量是具有形状[M，1]的2-D张量。 设 :math:`ID[i]` 为索引变量的第i个索引值。 然后输出变量将是一个形状为 :math:`[d_0,d_1, ... ,d_R]` 的张量。 - -如果将输出张量视为具有形状[M，N]的2-D矩阵,并且令O[i]为矩阵的第i行，则O[i]等于 :math:`I_{ID}[i][i]` - -- Ids: 索引张量 -- X[0 : N - 1]: 输出的候选张量度(N >= 2). -- 对于从 0 到 batchSize-1 的每个索引i，输出是第（Ids [i]） 张量的第i行 - -对于第i行的输出张量： - -.. math:: - \\y[i]=x_k[i]\\ - -其中 :math:`y` 为输出张量， :math:`x_k` 为第k个输入张量，并且 :math:`k=Ids[i]` 。 - -参数: - - **inputs** （list） - 要从中收集的变量列表。所有变量的形状相同，秩至少为2 - - **index** （Variable） - Tensor ，索引变量为二维张量，形状[M, 1]，其中M为批大小。 - -返回：multiplex 张量 - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - x1 = fluid.layers.data(name='x1', shape=[4], dtype='float32') - x2 = fluid.layers.data(name='x2', shape=[4], dtype='float32') - index = fluid.layers.data(name='index', shape=[1], dtype='int32') - out = fluid.layers.multiplex(inputs=[x1, x2], index=index) - - - - - - - - - - -.. _cn_api_fluid_layers_nce: - -nce -------------------------------- - -.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None, sampler='uniform', custom_dist=None, seed=0, is_sparse=False) - -计算并返回噪音对比估计（ noise-contrastive estimation training loss）。 -`请参考 See Noise-contrastive estimation: A new estimation principle for unnormalized statistical models -`_ -该operator默认使用均匀分布进行抽样。 - -参数: - - **input** (Variable) - 输入变量 - - **label** (Variable) - 标签 - - **num_total_classes** (int) - 所有样本中的类别的总数 - - **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0 - - **param_attr** (ParamAttr|None) - :math:`可学习参数/nce权重` 的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None - - **bias_attr** (ParamAttr|bool|None) - nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None - - **num_neg_samples** (int) - 负样例的数量。默认值是10 - - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名 - - **sampler** (str) – 取样器，用于从负类别中进行取样。可以是 ‘uniform’, ‘log_uniform’ 或 ‘custom_dist’。 默认 ‘uniform’ - - **custom_dist** (float[]) – 一个 float[] 并且它的长度为 ``num_total_classes`` 。 如果取样器类别为‘custom_dist’，则使用此参数。 custom_dist[i] 是第i个类别被取样的概率。默认为 None - - **seed** (int) – 取样器使用的seed。默认为0 - - **is_sparse** (bool) – 标志位，指明是否使用稀疏更新, :math:`weight@GRAD` 和 :math:`bias@GRAD` 会变为 SelectedRows - -返回： nce loss - -返回类型: 变量（Variable） - - -**代码示例** - -.. code-block:: python - - window_size = 5 - words = [] - for i in xrange(window_size): - words.append(layers.data( - name='word_{0}'.format(i), shape=[1], dtype='int64')) - - dict_size = 10000 - label_word = int(window_size / 2) + 1 - - embs = [] - for i in xrange(window_size): - if i == label_word: - continue - - emb = layers.embedding(input=words[i], size=[dict_size, 32], - param_attr='emb.w', is_sparse=True) - embs.append(emb) - - embs = layers.concat(input=embs, axis=1) - loss = layers.nce(input=embs, label=words[label_word], - num_total_classes=dict_size, param_attr='nce.w', - bias_attr='nce.b') - - #使用custom distribution - dist = fluid.layers.assign(input=np.array([0.05,0.5,0.1,0.3,0.05]).astype("float32")) - loss = layers.nce(input=embs, label=words[label_word], - num_total_classes=5, param_attr='nce.w', - bias_attr='nce.b', - num_neg_samples=3, - sampler="custom_dist", - custom_dist=dist) - - - - - - - - - - -.. _cn_api_fluid_layers_one_hot: - -one_hot -------------------------------- - -.. py:function:: paddle.fluid.layers.one_hot(input, depth) - -该层创建输入指数的one-hot表示 - -参数： - - **input** (Variable)-输入指数，最后维度必须为1 - - **depth** (scalar)-整数，定义one-hot维度的深度 - -返回：输入的one-hot表示 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - label = layers.data(name="label", shape=[1], dtype="float32") - one_hot_label = layers.one_hot(input=label, depth=10) - - - - - - - - - -.. _cn_api_fluid_layers_pad: - -pad -------------------------------- - -.. py:function:: paddle.fluid.layers.pad(x, paddings, pad_value=0.0, name=None) - -在张量上加上一个由 ``pad_value`` 给出的常数值，填充宽度由 ``paddings`` 指定。 -其中，维度 ``i`` 中 ``x`` 内容前填充的值个数用 ``paddings[i]`` 表示，维度 ``i`` 中 ``x`` 内容后填充的值个数用 ``paddings[i+1]`` 表示。 - -一个例子: - -:: - - Given: - - x = [[1, 2], [3, 4]] - - paddings = [0, 1, 1, 2] - - pad_value = 0 - - Return: - - out = [[0, 1, 2, 0, 0] - [0, 3, 4, 0, 0] - [0, 0, 0, 0, 0]] - - -参数: - - **x** (Variable) — —输入张量变量。 - - **paddings** (list) — 一个整数列表。按顺序填充在每个维度上填充元素。 ``padding`` 长度必须是 ``rank(x)×2`` - - **pad_value** (float) — 用来填充的常量值。 - - **name** (str|None) — 这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回： 填充后的张量变量 - -返回类型： 变量（Variable） - - -**代码示例** - -.. code-block:: python - - out = fluid.layers.pad( - x=x, paddings=[0, 1, 1, 2], pad_value=0.) - - - - - - - - - - -.. _cn_api_fluid_layers_pad2d: - -pad2d -------------------------------- - -.. py:function:: paddle.fluid.layers.pad2d(input, paddings=[0, 0, 0, 0], mode='constant', pad_value=0.0, data_format='NCHW', name=None) - -依照 paddings 和 mode 属性对图像进行2维 ``pad``,如果mode是 ``reflection``，则paddings[0]和paddings[1]必须不大于height-1。宽度维数具有相同的条件。 - -例如： - -.. code-block:: text - - 假设X是输入图像: - - X = [[1, 2, 3], - [4, 5, 6]] - - Case 0: - paddings = [0, 1, 2, 3], - mode = 'constant' - pad_value = 0 - Out = [[0, 0, 1, 2, 3, 0, 0, 0] - [0, 0, 4, 5, 6, 0, 0, 0] - [0, 0, 0, 0, 0, 0, 0, 0]] - - Case 1: - paddings = [0, 1, 2, 1], - mode = 'reflect' - Out = [[3, 2, 1, 2, 3, 2] - [6, 5, 4, 5, 6, 5] - [3, 2, 1, 2, 3, 2]] - - Case 2: - paddings = [0, 1, 2, 1], - mode = 'edge' - Out = [[1, 1, 1, 2, 3, 3] - [4, 4, 4, 5, 6, 6] - [4, 4, 4, 5, 6, 6]] - -参数： - - **input** (Variable) - 具有[N, C, H, W]格式或[N, H, W, C]格式的输入图像。 - - **paddings** (tuple|list) - 填充区域的大小。如果填充是一个元组，它必须包含四个整数， - (padding_top、padding_bottom、padding_left、padding_right)。默认:padding =[0,0,0,0]。 - - **mode** (str) - 三种模式:constant(默认)、reflect、edge。默认值:常数 - - **pad_value** (float32) - 以常量模式填充填充区域的值。默认值:0 - - **data_format** (str) - 可选字符串，选项有: ``NHWC`` , ``NCHW``。指定输入数据的数据格式。默认值:``NCHW`` - - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 - -返回： tensor变量，按照 padding值 和 mode 进行填充 - -返回类型：variable - -**代码示例：** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') - result = fluid.layers.pad2d(input=data, padding=[1,2,3,4], mode='reflect') - - - - - - - - - - - -.. _cn_api_fluid_layers_pad_constant_like: - -pad_constant_like -------------------------------- - -.. py:function:: paddle.fluid.layers.pad_constant_like(x, y, pad_value=0.0, name=None) - -使用 ``pad_value`` 填充 ``Y`` ，填充到每个axis（轴）值的数量由X和Y的形不同而指定。（（0，shape_x_0 - shape_y_0），...（0，shape_x_n - shape_y_n ））是每个axis唯一pad宽度。输入应该是k维张量（k> 0且k <7）。 - -**实例如下** - -:: - - Given: - X = [[[[ 0, 1, 2], - [ 3, 4, 5]], - [[ 6, 7, 8], - [ 9, 10, 11]], - [[12, 13, 14], - [15, 16, 17]]], - [[[18, 19, 20], - [21, 22, 23]], - [[24, 25, 26], - [27, 28, 29]], - [[30, 31, 32], - [33, 34, 35]]]] - X.shape = (2, 3, 2, 3) - - Y = [[[[35, 36, 37]], - [[38, 39, 40]], - [[41, 42, 43]]]] - Y.shape = (1, 3, 1, 3) - -参数： - - **x** （Variable）- 输入Tensor变量。 - - **y** （Variable）- 输出Tensor变量。 - - **pad_value** (float) - 用于填充的常量值。 - - **name** （str | None） - 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回：填充张量（Tensor）变量 - -返回类型： 变量（Variable） - -**示例代码** - -.. code-block:: python - - # x是秩为4的tensor, x.shape = (2, 3, 2, 3)。 - # y是秩为4的tensor, y.shape = (1, 3, 1, 3)。 - out = fluid.layers.pad_constant_like(x=x, y=y, pad_value=0.) - # out是秩为4的tensor, out.shape = [2, 3 ,2 , 3]。 - - - - - - - - - - - -.. _cn_api_fluid_layers_pool2d: - -pool2d -------------------------------- - -.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True) - -pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。 - -输入X和输出Out是NCHW格式，N为batch尺寸，C是通道数，H是特征高度，W是特征宽度。 - -参数（ksize,strides,paddings）含有两个元素。这两个元素分别代表高度和宽度。输入X的大小和输出Out的大小可能不一致。 - -例如： - -输入： - X shape：:math:`\left ( N,C,H_{in},W_{in} \right )` - -输出： - Out shape：:math:`\left ( N,C,H_{out},W_{out} \right )` - -如果 ``ceil_mode`` = false： - -.. math:: - H_{out} = \frac{(H_{in} - ksize[0] + 2 * paddings[0])}{strides[0]} + 1 - -.. math:: - W_{out} = \frac{(W_{in} - ksize[1] + 2 * paddings[1])}{strides[1]} + 1 - -如果 ``ceil_mode`` = true： - -.. math:: - H_{out} = \frac{(H_{in} - ksize[0] + 2 * paddings[0] + strides[0] - 1)}{strides[0]} + 1 - -.. math:: - W_{out} = \frac{(W_{in} - ksize[1] + 2 * paddings[1] + strides[1] - 1)}{strides[1]} + 1 - -如果 ``exclusive`` = true: - -.. math:: - hstart &= i * strides[0] - paddings[0] \\ - hend &= hstart + ksize[0] \\ - wstart &= j * strides[1] - paddings[1] \\ - wend &= wstart + ksize[1] \\ - Output(i ,j) &= \frac{sum(Input[hstart:hend, wstart:wend])}{ksize[0] * ksize[1]} - -如果 ``exclusive`` = false: - -.. math:: - hstart &= max(0, i * strides[0] - paddings[0])\\ - hend &= min(H, hstart + ksize[0]) \\ - wstart &= max(0, j * strides[1] - paddings[1]) \\ - wend & = min(W, wstart + ksize[1]) \\ - Output(i ,j) & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} - - - -参数： - - **input** (Variable) - 池化操作的输入张量。输入张量格式为NCHW，N为批尺寸，C是通道数，H是特征高度，W是特征宽度 - - **pool_size** (int|list|tuple) - 池化窗口的大小。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。 - - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling - - **pool_stride** (int|list|tuple) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。 - - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。 - - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true， ``pool_size`` 和 ``pool_padding`` 将被忽略。 - - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn - - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数 - - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。 - - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 - -返回：池化结果 - -返回类型：变量（Variable） - -抛出异常： - - ``ValueError`` - 如果 ``pool_type`` 既不是“max”也不是“avg” - - ``ValueError`` - 如果 ``global_pooling`` 为False并且‘pool_size’为-1 - - ``ValueError`` - 如果 ``use_cudnn`` 不是bool值 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data( - name='data', shape=[3, 32, 32], dtype='float32') - conv2d = fluid.layers.pool2d( - input=data, - pool_size=2, - pool_type='max', - pool_stride=1, - global_pooling=False) - - - - - - - - - -.. _cn_api_fluid_layers_pool3d: - -pool3d -------------------------------- - -.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None， exclusive=True) - -函数使用上述输入参数的池化配置，为三维空间添加池化操作 - -参数： - - **input** (Vairable) - 池化运算的输入张量。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。 - - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 - - **pool_type** (str) - 池化类型， "max" 对应max-pooling, "avg" 对应average-pooling。 - - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 - - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 - - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略。 - - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效。 - - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。 - - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。 - - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 - -返回：pool3d层的输出 - -返回类型：变量（Variable） - - - - - - - - - - - - -.. _cn_api_fluid_layers_pow: - -pow -------------------------------- - -.. py:function:: paddle.fluid.layers.pow(x, factor=1.0, name=None) - -指数激活算子（Pow Activation Operator.） - -参数 - - **x** (Variable) - Pow operator的输入 - - **factor** (FLOAT|1.0) - Pow的指数因子 - - **name** (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: 输出Pow操作符 - -返回类型: 输出(Variable) - - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.pow(x, factor=2.0) - - - - - - -.. _cn_api_fluid_layers_prelu: - -prelu -------------------------------- - -.. py:function:: paddle.fluid.layers.prelu(x, mode, param_attr=None, name=None) - -等式： - -.. math:: - y = max(0, x) + \alpha min(0, x) - -参数： - - **x** （Variable）- 输入为Tensor。 - - **param_attr** (ParamAttr|None) - 可学习权重 :math:`[\alpha]` 的参数属性。 - - **mode** （string）- 权重共享的模式all：所有元素共享相同的权重通道：通道中的元素共享相同的权重元素：每个元素都有一个权重 - - **name** （str | None）- 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 输出Tensor与输入shape相同。 - -返回类型： 变量（Variable） - - - - - - - - - - - -.. _cn_api_fluid_layers_random_crop: - -random_crop -------------------------------- - -.. py:function:: paddle.fluid.layers.random_crop(x, shape, seed=None) - -该operator对batch中每个实例进行随机裁剪。这意味着每个实例的裁剪位置不同，裁剪位置由均匀分布随机生成器决定。所有裁剪的实例都具有相同的shape，由参数shape决定。 - -参数: - - **x(Variable)** - 一组随机裁剪的实例 - - **shape(int)** - 裁剪实例的形状 - - **seed(int|变量|None)** - 默认情况下，随机种子从randint(-65536,-65536)中取得 - -返回: 裁剪后的batch - -**代码示例**: - -.. code-block:: python - - img = fluid.layers.data("img", [3, 256, 256]) - cropped_img = fluid.layers.random_crop(img, shape=[3, 224, 224]) - - - - - - - - - - -.. _cn_api_fluid_layers_rank_loss: - -rank_loss -------------------------------- - - -.. py:function:: paddle.fluid.layers.rank_loss(label, left, right, name=None) - -`RankNet `_ 是一个成对的 -排序模型，训练样本由一对文档组成：A和B。标签P表示a的排名是否高于B: - -P 的取值可为： {0, 1} 或 {0, 0.5, 1}, 其中，0.5表示输入的两文档排序相同。 - -排序的损失函数有三个输入:left(o_i)、right(o_j) 和 label (P\_{i,j})。输入分别表示RankNet对文档A、B的输出得分和标签p的值。由下式计算输入的排序损失C\_{i,j}: - -.. math:: - - C_{i,j} &= -\tilde{P_{ij}} * o_{i,j} + \log(1 + e^{o_{i,j}}) \\ - o_{i,j} &= o_i - o_j \\ - \tilde{P_{i,j}} &= \left \{0, 0.5, 1 \right \} \ or \ \left \{0, 1 \right \} - -排序损失层的输入为batch_size (batch_size >= 1) - -参数： - - **label** (Variable)：A的排名是否高于B - - **left** (Variable)：RankNet对doc A的输出分数 - - **right** (Variable): RankNet对doc B的输出分数 - - **name** (str|None)：此层的名称(可选)。如果没有设置，层将自动命名。 - -返回：variable：形为[N, H, W, 2]的输出 - -抛出异常：ValueError: 如果参数为不支持的类型 - - -**代码示例** - -.. code-block:: python - - theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") - out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") - data = fluid.layers.affine_grid(theta, out_shape) - - # or - data = fluid.layers.affine_grid(theta, [5, 3, 28, 28]) - - - - - - - - - - -.. _cn_api_fluid_layers_reduce_max: - -reduce_max -------------------------------- - -.. py:function:: paddle.fluid.layers.reduce_max(input, dim=None, keep_dim=False, name=None) - -计算给定维度上张量（Tensor）元素最大值。 - -参数： - - **input** （Variable）：输入变量为Tensor或LoDTensor。 - - **dim** （list | int | None）：函数运算的维度。如果为None，则计算所有元素的平均值并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 - - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 - - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 运算、减少维度之后的Tensor变量。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 - fluid.layers.reduce_max(x) # [0.9] - fluid.layers.reduce_max(x, dim=0) # [0.2, 0.3, 0.6, 0.9] - fluid.layers.reduce_max(x, dim=-1) # [0.9, 0.7] - fluid.layers.reduce_max(x, dim=1, keep_dim=True) # [[0.9], [0.7]] - - # x是一个shape为[2, 2, 2]的Tensor，元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 - fluid.layers.reduce_max(x, dim=[1, 2]) # [4.0, 8.0] - fluid.layers.reduce_max(x, dim=[0, 1]) # [7.0, 8.0] - - - - - - - - - - -.. _cn_api_fluid_layers_reduce_mean: - -reduce_mean -------------------------------- - -.. py:function:: paddle.fluid.layers.reduce_mean(input, dim=None, keep_dim=False, name=None) - -计算给定维度上张量（Tensor）元素平均值。 - -参数： - - **input** （Variable）：输入变量为Tensor或LoDTensor。 - - **dim** （list | int | None）：函数运算的维度。如果为None，则对输入的所有元素求平均值并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 - - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 - - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 运算、减少维度之后的Tensor变量。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_mean(x) # [0.4375] - fluid.layers.reduce_mean(x, dim=0) # [0.15, 0.25, 0.55, 0.8] - fluid.layers.reduce_mean(x, dim=-1) # [0.475, 0.4] - fluid.layers.reduce_mean( - x, dim=1, keep_dim=True) # [[0.475], [0.4]] - - # x 是一个shape为[2, 2, 2]的Tensor元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 - fluid.layers.reduce_mean(x, dim=[1, 2]) # [2.5, 6.5] - fluid.layers.reduce_mean(x, dim=[0, 1]) # [4.0, 5.0] - - - - - - - - - - -.. _cn_api_fluid_layers_reduce_min: - -reduce_min -------------------------------- - -.. py:function:: paddle.fluid.layers.reduce_min(input, dim=None, keep_dim=False, name=None) - -计算给定维度上张量元素的最小值。 - -参数： - - **input** （Variable）：输入变量为Tensor或LoDTensor。 - - **dim** （list | int | None）：函数运算的维度。如果为None，则对输入的所有元素做差并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 - - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 - - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 运算、减少维度之后的Tensor变量。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_min(x) # [0.1] - fluid.layers.reduce_min(x, dim=0) # [0.1, 0.2, 0.5, 0.7] - fluid.layers.reduce_min(x, dim=-1) # [0.2, 0.1] - fluid.layers.reduce_min(x, dim=1, keep_dim=True) # [[0.2], [0.1]] - - # x 是一个shape为[2, 2, 2]的Tensor元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 - fluid.layers.reduce_min(x, dim=[1, 2]) # [1.0, 5.0] - fluid.layers.reduce_min(x, dim=[0, 1]) # [1.0, 2.0] - - - - - - - - - - -.. _cn_api_fluid_layers_reduce_prod: - -reduce_prod -------------------------------- - -.. py:function:: paddle.fluid.layers.reduce_prod(input, dim=None, keep_dim=False, name=None) - -计算给定维度上张量（Tensor）元素乘积。 - -参数： - - **input** （Variable）：输入变量为Tensor或LoDTensor。 - - **dim** （list | int | None）：函数运算的维度。如果为None，则将输入的所有元素相乘并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 - - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 - - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 运算、减少维度之后的Tensor变量。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_prod(x) # [0.0002268] - fluid.layers.reduce_prod(x, dim=0) # [0.02, 0.06, 0.3, 0.63] - fluid.layers.reduce_prod(x, dim=-1) # [0.027, 0.0084] - fluid.layers.reduce_prod(x, dim=1, - keep_dim=True) # [[0.027], [0.0084]] - - # x 是一个shape为[2, 2, 2]的Tensor元素如下: - # [[[1.0, 2.0], [3.0, 4.0]], - # [[5.0, 6.0], [7.0, 8.0]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_prod(x, dim=[1, 2]) # [24.0, 1680.0] - fluid.layers.reduce_prod(x, dim=[0, 1]) # [105.0, 384.0] - - - - - - - - - - -.. _cn_api_fluid_layers_reduce_sum: - -reduce_sum -------------------------------- - -.. py:function:: paddle.fluid.layers.reduce_sum(input, dim=None, keep_dim=False, name=None) - -计算给定维度上张量（Tensor）元素之和。 - -参数： - - **input** （Variable）- 输入变量为Tensor或LoDTensor。 - - **dim** （list | int | None）- 求和运算的维度。如果为None，则对输入的所有元素求和并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 - - **keep_dim** （bool | False）- 是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 - - **name** （str | None）- 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 - -返回： 运算、减少维度之后的Tensor变量。 - -返回类型： 变量（Variable） - -**代码示例** - -.. code-block:: python - - # x是一个Tensor，元素如下: - # [[0.2, 0.3, 0.5, 0.9] - # [0.1, 0.2, 0.6, 0.7]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_sum(x) # [3.5] - fluid.layers.reduce_sum(x, dim=0) # [0.3, 0.5, 1.1, 1.6] - fluid.layers.reduce_sum(x, dim=-1) # [1.9, 1.6] - fluid.layers.reduce_sum(x, dim=1, keep_dim=True) # [[1.9], [1.6]] - - # x 是一个shape为[2, 2, 2]的Tensor元素如下: - # [[[1, 2], [3, 4]], - # [[5, 6], [7, 8]]] - # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 - fluid.layers.reduce_sum(x, dim=[1, 2]) # [10, 26] - fluid.layers.reduce_sum(x, dim=[0, 1]) # [16, 20] - - - - - - - - - - -.. _cn_api_fluid_layers_relu: - -relu -------------------------------- - -.. py:function:: paddle.fluid.layers.relu(x, name=None) - -Relu接受一个输入数据(张量)，输出一个张量。将线性函数y = max(0, x)应用到张量中的每个元素上。 - -.. math:: - \\Out=\max(0,x)\\ - - -参数: - - **x** (Variable):输入张量。 - - **name** (str|None，默认None) :如果设置为None，该层将自动命名。 - -返回: 与输入形状相同的输出张量。 - -返回类型: 变量（Variable） - -**代码示例**: - -.. code-block:: python - - output = fluid.layers.relu(x) - - - - - - - - - - -.. _cn_api_fluid_layers_relu6: - -relu6 -------------------------------- - -.. py:function:: paddle.fluid.layers.relu6(x, threshold=6.0, name=None) - -relu6激活算子（Relu6 Activation Operator） - -.. math:: - - \\out=min(max(0, x), 6)\\ - - -参数: - - **x** (Variable) - Relu6 operator的输入 - - **threshold** (FLOAT|6.0) - Relu6的阈值 - - **name** (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: Relu6操作符的输出 - -返回类型: 输出(Variable) - - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.relu6(x, threshold=6.0) - - - - - - - -.. _cn_api_fluid_layers_reshape: - -reshape -------------------------------- - -.. py:function:: paddle.fluid.layers.reshape(x, shape, actual_shape=None, act=None, inplace=False, name=None) - -保持输入张量数据不变的情况下，改变张量的形状。 - -目标形状可由 ``shape`` 或 ``actual_shape`` 给出。``shape`` 是一个整数列表，而 ``actual_shape`` 是一个张量变量。 -当两个属性同时被指定时，``actual_shape`` 的优先级高于 ``shape`` ，但在编译时仍然应该正确地设置 ``shape`` 以保证形状推断。 - -在指定目标shape时存在一些技巧： - -.. code-block:: text - - 1. -1表示这个维度的值是从x的元素总数和剩余维度推断出来的。因此，有且只有一个维度可以被设置为-1。 - 2. 0表示实际的维数是从x的对应维数中复制出来的，因此shape中0的索引值不能超过秩(x)。 - - -这里有一些例子来解释它们： - -.. code-block:: text - - 1. 给定一个形状为[2,4,6]的三维张量x，目标形状为[6,8]， ``reshape`` 将x变换为形状为[6,8]的二维张量，且x的数据保持不变。 - 2. 给定一个形状为[2,4,6]的三维张量x，指定的目标形状为[2,3,-1,2]， ``reshape``将x变换为形状为[2,3,4,2]的4- d张量，不改变x的数据。在这种情况下，目标形状的一个维度被设置为-1，这个维度的值是从x的元素总数和剩余维度推断出来的。 - 3. 给定一个形状为[2,4,6]的三维张量x，目标形状为[- 1,0,3,2]，整形算子将x变换为形状为[2,4,3,2]的四维张量，使x的数据保持不变。在这种情况下，0意味着实际的维值将从x的对应维数中复制,-1位置的维度由x的元素总数和剩余维度计算得来。 - -参数： - - **x** (variable) - 输入张量 - - **shape** (list) - 新的形状。新形状最多只能有一个维度为-1。 - - **actual_shape** (variable) - 一个可选的输入。如果提供，则根据 ``actual_shape`` 进行 reshape，而不是指定 ``shape`` 。也就是说，actual_shape具有比shape更高的优先级。 - - **act** (str) - 对reshpe后的tensor变量执行非线性激活 - - **inplace** (bool) - 如果在多个操作符中使用x，则 ``inplace`` 必须设置为False。如果该标志设置为True，则重用输入x进行reshape，这将改变张量变量x的形状，并可能在多个操作符中使用x时造成错误。如果为False，则保留形状x，并创建一个新的输出张量变量，该张量变量的数据是从输入x复制的，但经过了重构。 - - **name** (str) - 可选变量，此层的名称 - -返回：如果 ``act`` 为 ``None``,返回reshape后的tensor变量。如果 ``inplace`` 为 ``False`` ,将返回一个新的Tensor变量，否则，将改变x自身。如果 ``act`` 不是 ``None`` ，则返回激活的张量变量。 - -抛出异常：``TypeError`` - 如果 actual_shape 既不是变量也不是None - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data( - name='data', shape=[2, 4, 6], dtype='float32') - reshaped = fluid.layers.reshape( - x=data, shape=[-1, 0, 3, 2], inplace=True) - - - - - - - - - - -.. _cn_api_fluid_layers_resize_bilinear: - -resize_bilinear -------------------------------- - -.. py:function:: paddle.fluid.layers.resize_bilinear(input, out_shape=None, scale=None, name=None) - -根据指定的out_shape执行双线性插值调整输入大小，输出形状按优先级由actual_shape、out_shape和scale指定。 - -双线性插值是对线性插值的扩展,即二维变量方向上(如h方向和w方向)插值。关键思想是先在一个方向上执行线性插值，然后再在另一个方向上执行线性插值。 - - `详情请参阅维基百科 https://en.wikipedia.org/wiki/Bilinear_interpolation `_ - -参数: - - **input** (Variable) - 双线性插值的输入张量，是一个shpae为(N x C x h x w)的4d张量。 - - **out_shape** (Variable) - 一维张量，包含两个数。第一个数是高度，第二个数是宽度。 - - **scale** (float|None) - 用于输入高度或宽度的乘数因子。out_shape和scale至少要设置一个。out_shape的优先级高于scale。默认值:None。 - - **name** (str|None) - 输出变量名。 - - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`actual_shape` 而不是 :code:`out_shape` 。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值:None - -返回： 输出的维度是(N x C x out_h x out_w) - - -**代码示例：** - -.. code-block:: python - - out = fluid.layers.resize_bilinear(input, out_shape=[12, 12]) - - - - - - - - -.. _cn_api_fluid_layers_resize_nearest: - -resize_nearest -------------------------------- - -.. py:function:: paddle.fluid.layers.resize_nearest(input, out_shape=None, scale=None, name=None, actual_shape=None) - -该层对输入进行放缩，在第三维（高度方向）和第四维（宽度方向）进行最邻近插值（nearest neighbor interpolation）操作。 -输出形状按优先级顺序依据 ``actual_shape`` , ``out_shape`` 和 ``scale`` 而定。 - -最邻近插值的详细介绍请参照： `Wiki Nearest-neighbor interpolation `_ - - - -参数: - - **input** (Variable) – 插值运算的输入张量, 是一个形为 (N,C,H,W) 的四维张量 - - **out_shape** (Variable) – 一维张量，包含两个指明输出大小的数字 。 第一个代表了高度，第二个代表了宽度 - - **scale** (float|None) – 输入高、宽的乘法器。 ``out_shape`` 和 ``scale`` 二者至少设置其一。 ``out_shape`` 具有比 ``scale`` 更高的优先级。 默认: None - - **name** (str|None) – 输出变量的命名 - - **actual_shape** (Variable) – 可选输入， 动态设置输出张量的形状。 如果提供该值， 图片放缩会依据此形状进行， 而非依据 ``out_shape`` 和 ``scale`` 。 即为， ``actual_shape`` 具有最高的优先级。 如果想动态指明输出形状，推荐使用 ``actual_shape`` 取代 ``out_shape`` 。 当使用 ``actual_shape`` 来指明输出形状， ``out_shape`` 和 ``scale`` 也应该进行设置, 否则在图形生成阶段将会报错。默认: None - -返回：插值运算的输出张量，是一个形为 (N,C,H,W) 的四维张量 - -**代码示例** - -.. code-block:: python - - out = fluid.layers.resize_nearest(input, out_shape=[12, 12]) - - - - - - - - - - -.. _cn_api_fluid_layers_roi_align: - -roi_align -------------------------------- - -.. py:function:: paddle.fluid.layers.roi_align(input, rois, pooled_height=1, pooled_width=1, spatial_scale=1.0, sampling_ratio=-1, name=None) - -**实现RoIAlign操作。** - -Region of Interests align(直译：有意义、有价值选区对齐) 用于实现双线性插值，它可以将不均匀大小的输入 -变为固定大小的特征图(feature map)。 - -该运算通过 ``pooled_width`` 和 ``pooled_height`` 将每个推荐区域划分为等大小分块。位置保持不变。 - -在每个RoI框中，四个常取样位置会通过双线性插值直接计算。输出为这四个位置的平均值从而解决不对齐问题。 - -参数: - - **input** (Variable) – (Tensor) 该运算的的输入张量，形为(N,C,H,W)。其中 N 为batch大小, C 为输入通道的个数, H 特征高度, W 特征宽度 - - **rois** (Variable) – 待池化的ROIs (Regions of Interest) - - **pooled_height** (integer) – (默认为1), 池化后的输出高度 - - **pooled_width** (integer) – (默认为1), 池化后的输出宽度 - - **spatial_scale** (float) – (默认为1.0),乘法性质空间标尺因子，池化时，将RoI坐标变换至运算采用的标度 - - **sampling_ratio** (intger) – (默认为-1),插值格中采样点的数目。 如果它 <=0, 它们将自适应 ``roi_width`` 和 ``pooled_w`` , 在高度上也是同样的道理。 - -返回：一个形为 (num_rois, channels, pooled_h, pooled_w) 的四维张量 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - align_out = fluid.layers.roi_align(input=x, - rois=rois, - pooled_height=7, - pooled_width=7, - spatial_scale=0.5, - sampling_ratio=-1) - - - - - - - - - - - -.. _cn_api_fluid_layers_roi_pool: - -roi_pool -------------------------------- - -.. py:function:: paddle.fluid.layers.roi_pool(input, rois, pooled_height=1, pooled_width=1, spatial_scale=1.0) - - -roi池化是对非均匀大小的输入执行最大池化，以获得固定大小的特征映射(例如7*7)。 - -该operator有三个步骤: - - 1. 用pooled_width和pooled_height将每个区域划分为大小相等的部分 - 2. 在每个部分中找到最大的值 - 3. 将这些最大值复制到输出缓冲区 - -Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverflow.com/questions/43430056/what-is-roi-layer-in-fast-rcnn - -参数: - - **input** (Variable) - 张量，ROIPoolOp的输入。输入张量的格式是NCHW。其中N为batch大小，C为输入通道数，H为特征高度，W为特征宽度 - - **roi** (Variable) - roi区域。 - - **pooled_height** (integer) - (int，默认1)，池化输出的高度。默认:1 - - **pooled_width** (integer) - (int，默认1) 池化输出的宽度。默认:1 - - **spatial_scale** (float) - (float，默认1.0)，用于将ROI coords从输入规模转换为池化时使用的规模。默认1.0 - -返回: (张量)，ROIPoolOp的输出是一个shape为(num_rois, channel, pooled_h, pooled_w)的4d张量。 - -返回类型: 变量（Variable） - - -**代码示例** - -.. code-block:: python - - pool_out = fluid.layers。roi_pool(输入=x, rois=rois, 7,7,1.0) - - - - - - - - - - -.. _cn_api_fluid_layers_row_conv: - -row_conv -------------------------------- - -.. py:function:: paddle.fluid.layers.row_conv(input, future_context_size, param_attr=None, act=None) - -行卷积（Row-convolution operator）称为超前卷积（lookahead convolution）。下面关于DeepSpeech2的paper中介绍了这个operator - - ``_ - -双向的RNN在深度语音模型中很有用，它通过对整个序列执行正向和反向传递来学习序列的表示。然而，与单向RNNs不同的是，在线部署和低延迟设置中，双向RNNs具有难度。超前卷积将来自未来子序列的信息以一种高效的方式进行计算，以改进单向递归神经网络。 row convolution operator 与一维序列卷积不同，计算方法如下: - -给定输入序列长度为 :math:`t` 的输入序列 :math:`in` 和输入维度 :math:`d` ，以及一个大小为 :math:`context x d` 的滤波器 :math:`W` ，输出序列卷积为: - -.. math:: - out_i = \sum_{j=i}^{i+context} in_{j} · W_{i-j} - -公式中： - - :math:`out_i` : 第i行输出变量 shaoe为[1, D]. - - :math:`context` ： 未来上下文（feature context）大小 - - :math:`in_j` : 第j行输出变量,形为[1，D] - - :math:`W_{i-j}` : 第(i-j)行参数，其形状为[1,D]。 - -`详细请参考设计文档 https://github.com/PaddlePaddle/Paddle/issues/2228#issuecomment-303903645 `_ . - -参数: - - **input** (Variable) -- 输入是一个LodTensor，它支持可变时间长度的输入序列。这个LodTensor的内部张量是一个具有形状(T x N)的矩阵，其中T是这个mini batch中的总的timestep，N是输入数据维数。 - - **future_context_size** (int) -- 未来上下文大小。请注意，卷积核的shape是[future_context_size + 1, D]。 - - **param_attr** (ParamAttr) -- 参数的属性，包括名称、初始化器等。 - - **act** (str) -- 非线性激活函数。 - -返回: 输出(Out)是一个LodTensor，它支持可变时间长度的输入序列。这个LodTensor的内部量是一个形状为 T x N 的矩阵，和X的 shape 一样。 - - -**代码示例** - -.. code-block:: python - - import paddle.fluid as fluid - - x = fluid.layers.data(name='x', shape=[16], - dtype='float32', lod_level=1) - out = fluid.layers.row_conv(input=x, future_context_size=2) - - - - - - - - - - -.. _cn_api_fluid_layers_sampling_id: - -sampling_id -------------------------------- - -.. py:function:: paddle.fluid.layers.sampling_id(x, min=0.0, max=1.0, seed=0, dtype='float32') - -sampling_id算子。用于从输入的多项分布中对id进行采样的图层。为一个样本采样一个id。 - -参数： - - **x** （Variable）- softmax的输入张量（Tensor）。2-D形状[batch_size，input_feature_dimensions] - - **min** （Float）- 随机的最小值。（浮点数，默认为0.0） - - **max** （Float）- 随机的最大值。（float，默认1.0） - - **seed** （Float）- 用于随机数引擎的随机种子。0表示使用系统生成的种子。请注意，如果seed不为0，则此运算符将始终每次生成相同的随机数。（int，默认为0） - - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出数据的类型为float32，float_16，int等。 - -返回： Id采样的数据张量。 - -返回类型： 输出（Variable）。 - - - - - - - - - - - -.. _cn_api_fluid_layers_scale: - -scale -------------------------------- - -.. py:function:: paddle.fluid.layers.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None) - -缩放算子 - -对输入张量应用缩放和偏移加法。 - -if ``bias_after_scale`` = True: - -.. math:: - Out=scale*X+bias - -else: - -.. math:: - Out=scale*(X+bias) - -参数: - - **x** (Variable) - (Tensor) 要比例运算的输入张量（Tensor）。 - - **scale** (FLOAT) - 比例运算的比例因子。 - - **bias** (FLOAT) - 比例算子的偏差。 - - **bias_after_scale** (BOOLEAN) - 在缩放之后或之前添加bias。在某些情况下，对数值稳定性很有用。 - - **act** (basestring|None) - 应用于输出的激活函数。 - - **name** (basestring|None)- 输出的名称。 - -返回: 比例运算符的输出张量(Tensor) - -返回类型: 变量(Variable) - - - - - - - - - - -.. _cn_api_fluid_layers_scatter: - -scatter -------------------------------- - -.. py:function:: paddle.fluid.layers.scatter(input, index, updates, name=None) - - -通过更新输入在第一维度上指定索引位置处的元素来获得输出。 - -.. math:: - \\Out=XOut[Ids]=Updates\\ - - -参数： - - **input** （Variable） - 秩> = 1的源输入 - - **index** （Variable） - 秩= 1的索引输入。 它的dtype应该是int32或int64，因为它用作索引 - - **updates** （Variable） - scatter 要进行更新的变量 - - **name** （str | None） - 输出变量名称。 默认None - -返回：张量变量, 与输入张量的shape相同 - -返回类型：output（Variable） - -**代码示例** - -.. code-block:: python - - output = fluid.layers.scatter(input, index, updates) - - - - - - - - - - - -.. _cn_api_fluid_layers_selu: - -selu -------------------------------- - -.. py:function:: paddle.fluid.layers.selu(x, scale=None, alpha=None, name=None) - -**实现Selu运算** - -有如下等式： - -.. math:: - selu= \lambda* - \begin{cases} - x &\quad \text{ if } x>0 \\ - \alpha * e^x - \alpha &\quad \text{ if } x<=0 - \end{cases} - -输入 ``x`` 可以选择性携带LoD信息。输出和它共享此LoD信息(如果有)。 - -参数: - - **x** (Variable) – 输入张量 - - **scale** (float, None) – 如果标度没有设置，其默认值为 1.0507009873554804934193349852946。 详情请见： `Self-Normalizing Neural Networks `_ - - **alpha** (float, None) – 如果没有设置改参数, 其默认值为 1.6732632423543772848170429916717。 详情请见： `Self-Normalizing Neural Networks `_ - - **name** (str|None, default None) – 该层命名，若为None则自动为其命名 - -返回：一个形和输入张量相同的输出张量 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - output = fluid.layers.selu(x) - - - - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_concat: - -sequence_concat -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_concat(input, name=None) - -sequence_concat操作通过序列信息连接LoD张量（Tensor）。例如：X1的LoD = [0,3,7]，X2的LoD = [0,7,9]，结果的LoD为[0，（3 + 7），（7 + 9）]，即[0,10,16]。 - -参数: - - **input** (list) – List of Variables to be concatenated. - - **name** (str|None) – A name for this layer(optional). If set None, the layer will be named automatically. - -返回: 连接好的输出变量。 - -返回类型: 变量（Variable） - - -**代码示例** - -.. code-block:: python - - out = fluid.layers.sequence_concat(input=[seq1, seq2, seq3]) - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_conv: - -sequence_conv -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_conv(input, num_filters, filter_size=3, filter_stride=1, padding=None, bias_attr=None, param_attr=None, act=None, name=None) - -该函数的输入参数中给出了滤波器和步长，通过利用输入以及滤波器和步长的常规配置来为sequence_conv创建操作符。 - -参数： - - **input** (Variable) - (LoD张量）输入X是LoD张量，支持可变的时间量的长度输入序列。该LoDTensor的标记张量是一个维度为（T,N)的矩阵，其中T是mini-batch的总时间步数，N是input_hidden_size - - **num_filters** (int) - 滤波器的数量 - - **filter_size** (int) - 滤波器大小（H和W) - - **filter_stride** (int) - 滤波器的步长 - - **padding** (bool) - 若为真，添加填充 - - **bias_attr** (ParamAttr|bool|None) - sequence_conv偏离率参数属性。若设为False,输出单元则不加入偏离率。若设为None或ParamAttr的一个属性，sequence_conv将创建一个ParamAttr作为bias_attr。如果未设置bias_attr的初始化函数，则将bias初始化为0.默认:None - - **param_attr** (ParamAttr|None) - 可学习参数/sequence_conv的权重参数属性。若设置为None或ParamAttr的一个属性，sequence_conv将创建ParamAttr作为param_attr。 - 若未设置param_attr的初始化函数，则用Xavier初始化参数。默认:None - -返回：sequence_conv的输出 - -返回类型：变量（Variable） - - - - - - - - - -.. _cn_api_fluid_layers_sequence_enumerate: - -sequence_enumerate -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_enumerate(input, win_size, pad_value=0, name=None) - -为输入索引序列生成一个新序列，该序列枚举输入长度为 ``win_size`` 的所有子序列。 输入序列和枚举序列第一维上维度相同，第二维是 ``win_size`` ，在生成中如果需要，通过设置 ``pad_value`` 填充。 - -**例子：** - -:: - - 输入： - X.lod = [[0, 3, 5]] X.data = [[1], [2], [3], [4], [5]] X.dims = [5, 1] - 属性： - win_size = 2 pad_value = 0 - 输出： - Out.lod = [[0, 3, 5]] Out.data = [[1, 2], [2, 3], [3, 0], [4, 5], [5, 0]] Out.dims = [5, 2] - -参数: - - **input** （Variable）- 作为索引序列的输入变量。 - - **win_size** （int）- 枚举所有子序列的窗口大小。 - - **pad_value** （int）- 填充值，默认为0。 - -返回: 枚举序列变量是LoD张量（LoDTensor）。 - -返回类型: Variable - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(shape[30, 1], dtype='int32', lod_level=1) - out = fluid.layers.sequence_enumerate(input=x, win_size=3, pad_value=0) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_expand: - -sequence_expand -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_expand(x, y, ref_level=-1, name=None) - -序列扩张层（Sequence Expand Layer) - -将根据指定 y 的 level lod 展开输入变量x，请注意 x 的 lod level 最多为1，而 x 的秩最少为2。当 x 的秩大于2时，它就被看作是一个二维张量。下面的例子将解释 sequence_expand 是如何工作的: - -:: - - - * 例1 - x is a LoDTensor: - x.lod = [[2, 2]] - x.data = [[a], [b], [c], [d]] - x.dims = [4, 1] - - y is a LoDTensor: - y.lod = [[2, 2], - [3, 3, 1, 1]] - - ref_level: 0 - - then output is a 1-level LoDTensor: - out.lod = [[2, 2, 2, 2]] - out.data = [[a], [b], [a], [b], [c], [d], [c], [d]] - out.dims = [8, 1] - - * 例2 - x is a Tensor: - x.data = [[a], [b], [c]] - x.dims = [3, 1] - - y is a LoDTensor: - y.lod = [[2, 0, 3]] - - ref_level: -1 - - then output is a Tensor: - out.data = [[a], [a], [c], [c], [c]] - out.dims = [5, 1] - -参数： - - **x** (Variable) - 输入变量，张量或LoDTensor - - **y** (Variable) - 输入变量，为LoDTensor - - **ref_level** (int) - x表示的y的Lod层。若设为-1，表示lod的最后一层 - - **name** (str|None) - 该层名称（可选）。如果设为空，则自动为该层命名 - -返回：扩展变量，LoDTensor - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[10], dtype='float32') - y = fluid.layers.data(name='y', shape=[10, 20], - dtype='float32', lod_level=1) - out = layers.sequence_expand(x=x, y=y, ref_level=0) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_expand_as: - -sequence_expand_as -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_expand_as(x, y, name=None) - -Sequence Expand As Layer - -这一层将根据y的第0级lod展开输入变量x。当前实现要求输入（Y）的lod层数必须为1，输入（X）的第一维应当和输入（Y）的第0层lod的大小相同，不考虑输入（X）的lod。 - -以下示例解释sequence_expand如何工作： - -:: - - * 例1: - 给定一维LoDTensor input(X) - X.data = [[a], [b], [c], [d]] - X.dims = [4, 1] - 和 input(Y) - Y.lod = [[0, 3, 6, 7, 8]] - ref_level: 0 - 得到1级 LoDTensor - Out.lod = [[0, 3, 6, 7, 8]] - Out.data = [[a], [a], [a], [b], [b], [b], [c], [d]] - Out.dims = [8, 1] - -参数： - - **x** (Variable) - 输入变量，类型为Tensor或LoDTensor - - **y** (Variable) - 输入变量，为LoDTensor - - **name** (str|None) - 该层名称（可选）。如果设为空，则自动为该层命名 - -返回：扩展变量，LoDTensor - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[10], dtype='float32') - y = fluid.layers.data(name='y', shape=[10, 20], - dtype='float32', lod_level=1) - out = layers.sequence_expand_as(x=x, y=y) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_first_step: - -sequence_first_step -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_first_step(input) - -该功能获取序列的第一步 - -:: - - x是1-level LoDTensor: - - x.lod = [[2, 3, 2]] - - x.data = [1, 3, 2, 4, 6, 5, 1] - - x.dims = [7, 1] - - 输出为张量: - - out.dim = [3, 1] - with condition len(x.lod[-1]) == out.dims[0] - out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) - -参数：**input** (variable)-输入变量，为LoDTensor - -返回：序列第一步，为张量 - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[7, 1], - dtype='float32', lod_level=1) - x_first_step = fluid.layers.sequence_first_step(input=x) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_last_step: - -sequence_last_step -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_last_step(input) - -该API可以获取序列的最后一步 - -:: - - x是level-1的LoDTensor: - - x.lod = [[2, 3, 2]] - - x.data = [1, 3, 2, 4, 6, 5, 1] - - x.dims = [7, 1] - - 输出为Tensor: - - out.dim = [3, 1] - - 且 len(x.lod[-1]) == out.dims[0] - - out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) - -参数：**input** (variable)-输入变量，为LoDTensor - -返回：序列的最后一步，为张量 - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[7, 1], - dtype='float32', lod_level=1) - x_last_step = fluid.layers.sequence_last_step(input=x) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_mask: - -sequence_mask -------------------------------- - -该层根据输入 ``x`` 和 ```maxlen`` 输出一个掩码，数据类型为dtype。 - -假设x是一个形状为[d_1, d_2，…]的张量。， y是一个形为[d_1, d_2，… ，d_n, maxlen]的掩码，其中: - -.. math:: - - y(i_1, i_2,..., i_n, j) = (j < x(i_1, i_2,..., i_n)) - -参数： - - **x** (Variable) - sequence_mask层的输入张量，其元素是小于maxlen的整数。 - - **maxlen** (int|None) - 序列的最大长度。如果maxlen为空，则用max(x)替换。 - - **dtype** (np.dtype|core.VarDesc.VarType|str) - 输出的数据类型 - - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 - -返回： sequence mask 的输出 - -返回类型： Variable - - - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_pad: - -sequence_pad -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None,name=None) - -序列填充操作符（Sequence Pad Operator） - -这个操作符将同一batch中的序列填充到一个一致的长度。长度由属性padded_length指定。填充的新元素的值具体由输入 ``PadValue`` 指定，并会添加到每一个序列的末尾，使得他们最终的长度保持一致。 - -以下的例子更清晰地解释此操作符的工作原理： - -:: - - 例1: - - 给定 1-level LoDTensor - - input(X): - X.lod = [[0,2,5]] - X.data = [a,b,c,d,e] - input(PadValue): - PadValue.data = [0] - - 'padded_length'=4 - - 得到LoDTensor: - Out.data = [[a,b,0,0],[c,d,e,0]] - Length.data = [[2],[3]] - -:: - - 例2: - - 给定 1-level LoDTensor - - input(X): - X.lod = [[0,2,5]] - X.data = [[a1,a2],[b1,b2],[c1,c2],[d1,d2],[e1,e2]] - input(PadValue): - PadValue.data = [0] - - 'padded_length' = -1,表示用最长输入序列的长度(此例中为3) - - 得到LoDTensor: - Out.data = [[[a1,a2],[b1,b2],[0,0]],[[c1,c2],[d1,d2],[e1,e2]]] - Length.data = [[2],[3]] - - -:: - - 例3: - - 给定 1-level LoDTensor - - input(X): - X.lod = [[0,2,5]] - X.data = [[a1,a2],[b1,b2],[c1,c2],[d1,d2],[e1,e2]] - input(PadValue): - PadValue.data = [p1,p2] - - 'padded_length' = -1,表示用最长输入序列的长度（此例中为3） - - 得到LoDTensor: - Out.data = [[[a1,a2],[b1,b2],[p1,p2]],[[c1,c2],[d1,d2],[e1,e2]]] - Length.data = [[2],[3]] - - -参数： - - **x** (Vairable) - 输入变量，应包含lod信息 - - **pad_value** (Variable) - 变量，存有放入填充步的值。可以是标量或tensor,维度和序列的时间步长相等。如果是标量,则自动广播到时间步长的维度 - - **maxlen** (int,默认None) - 填充序列的长度。可以为空或者任意正整数。当为空时，以序列中最长序列的长度为准，其他所有序列填充至该长度。当是某个特定的正整数，最大长度必须大于最长初始序列的长度 - - **name** (str|None) – 该层的命名(可选项)。 如果为 None, 则自动命名 - -返回：填充序列批（batch）和填充前的初始长度。所有输出序列的长度相等 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - import numpy - - x = fluid.layers.data(name='y', shape=[10, 5], - dtype='float32', lod_level=1) - pad_value = fluid.layers.assign( - input=numpy.array([0.0], dtype=numpy.float32)) - out = fluid.layers.sequence_pad(x=x, pad_value=pad_value) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_pool: - -sequence_pool -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type, is_test=False) - -该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的pool_type将特征运用到输入到首部。 - -支持四种pool_type: - -- **average**: :math:`Out[i] = \frac{\sum_{i}X_{i}}{N}` -- **sum**: :math:`Out[i] = \sum _{j}X_{ij}` -- **sqrt**: :math:`Out[i] = \frac{ \sum _{j}X_{ij}}{\sqrt{len(\sqrt{X_{i}})}}` -- **max**: :math:`Out[i] = max(X_{i})` - -:: - - - x是一级LoDTensor: - x.lod = [[2, 3, 2]] - x.data = [1, 3, 2, 4, 6, 5, 1] - x.dims = [7, 1] - 输出为张量（Tensor）： - out.dim = [3, 1] - with condition len(x.lod[-1]) == out.dims[0] - 对于不同的pool_type： - average: out.data = [2, 4, 3], where 2=(1+3)/2, 4=(2+4+6)/3, 3=(5+1)/2 - sum : out.data = [4, 12, 6], where 4=1+3, 12=2+4+6, 6=5+1 - sqrt : out.data = [2.82, 6.93, 4.24], where 2.82=(1+3)/sqrt(2), - 6.93=(2+4+6)/sqrt(3), 4.24=(5+1)/sqrt(2) - max : out.data = [3, 6, 5], where 3=max(1,3), 6=max(2,4,6), 5=max(5,1) - last : out.data = [3, 6, 1], where 3=last(1,3), 6=last(2,4,6), 1=last(5,1) - first : out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) - -参数： - - **input** (variable) - 输入变量，为LoDTensor - - **pool_type** (string) - 池化类型。支持average,sum,sqrt和max - - **is_test** (bool, 默认为 False) - 用于区分训练模式和测试评分模式 - -返回：sequence pooling 变量，类型为张量（Tensor) - -**代码示例**: - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[7, 1], - dtype='float32', lod_level=1) - avg_x = fluid.layers.sequence_pool(input=x, pool_type='average') - sum_x = fluid.layers.sequence_pool(input=x, pool_type='sum') - sqrt_x = fluid.layers.sequence_pool(input=x, pool_type='sqrt') - max_x = fluid.layers.sequence_pool(input=x, pool_type='max') - last_x = fluid.layers.sequence_pool(input=x, pool_type='last') - first_x = fluid.layers.sequence_pool(input=x, pool_type='first') - - - - - - - - - -.. _cn_api_fluid_layers_sequence_reshape: - -sequence_reshape -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_reshape(input, new_dim) - -Sequence Reshape Layer -该层重排输入序列。用户设置新维度。每一个序列的的长度通过原始长度、原始维度和新的维度计算得出。以下实例帮助解释该层的功能 - -.. code-block:: python - - x是一个LoDTensor: - x.lod = [[0, 2, 6]] - x.data = [[1, 2], [3, 4], - [5, 6], [7, 8], - [9, 10], [11, 12]] - x.dims = [6, 2] - 设置 new_dim = 4 - 输出为LoDTensor: - out.lod = [[0, 1, 3]] - - out.data = [[1, 2, 3, 4], - [5, 6, 7, 8], - [9, 10, 11, 12]] - out.dims = [3, 4] - -目前仅提供1-level LoDTensor，请确保(原长度*原维数)可以除以新的维数，每个序列没有余数。 - -参数： - - **input** (Variable)-一个2-D LoDTensor,模型为[N,M]，维度为M - - **new_dim** (int)-新维度，输入LoDTensor重新塑造后的新维度 - -返回：根据新维度重新塑造的LoDTensor - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(shape=[5, 20], dtype='float32', lod_level=1) - x_reshaped = fluid.layers.sequence_reshape(input=x, new_dim=10) - - - - - - - - - -.. _cn_api_fluid_layers_sequence_reverse: - -sequence_reverse -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_reverse(x, name=None) - -**实现SequenceReverse（序列倒序）运算** - -在第0维上将输入 ``x`` 的各序列倒序。 - -:: - - 假设 ``x`` 是一个形为 (5,4) 的LoDTensor， lod信息为 [[0, 2, 5]]，其中， - - - X.data() = [ [1, 2, 3, 4], [5, 6, 7, 8], # 索引为0，长度为2的序列 - - [9, 10, 11, 12], [13, 14, 15, 16], [17, 18, 19, 20] # 索引为1长度为3的序列 - -输出 ``Y`` 与 ``x`` 具有同样的维数和LoD信息。 于是有： - -:: - - Y.data() = [ [5, 6, 7, 8], [1, 2, 3, 4], # 索引为0，长度为2的逆序列 - [17, 18, 19, 20], [13, 14, 15, 16], [9, 10, 11, 12] # 索引为1，长度为3的逆序列 - -该运算在建立反dynamic RNN 网络中十分有用。 - -目前仅支持LoD层次(LoD level)为1的张量倒序。 - -参数: - - **x** (Variable) – 输入张量 - - **name** (basestring|None) – 输出变量的命名 - -返回：输出LoD张量 - -返回类型：Variable - - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_scatter: - -sequence_scatter -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_scatter(input, index, updates, name=None) - -序列散射层 - -这个operator将更新张量X，它使用Ids的LoD信息来选择要更新的行，并使用Ids中的值作为列来更新X的每一行。 - -**样例**: - -:: - - 输入： - input.data = [[1.0, 1.0, 1.0, 1.0, 1.0, 1.0], - [1.0, 1.0, 1.0, 1.0, 1.0, 1.0], [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]] - input.dims = [3, 6] - - index.data = [[0], [1], [2], [5], [4], [3], [2], [1], [3], [2], [5], [4]] index.lod = [[0, 3, 8, 12]] - - updates.data = [[0.3], [0.3], [0.4], [0.1], [0.2], [0.3], [0.4], [0.0], [0.2], [0.3], [0.1], [0.4]] updates.lod = [[ 0, 3, 8, 12]] - - - 输出： - out.data = [[1.3, 1.3, 1.4, 1.0, 1.0, 1.0], - [1.0, 1.0, 1.4, 1.3, 1.2, 1.1], [1.0, 1.0, 1.3, 1.2, 1.4, 1.1]] - out.dims = X.dims = [3, 6] - - -参数： - - **input** (Variable) - input 秩（rank） >= 1。 - - **index** (Variable) - index 秩（rank）=1。由于用于索引dtype应该是int32或int64。 - - **updates** (Variable) - input需要被更新的值。 - - **name** (str|None) - 输出变量名。默认：None。 - -返回： 输出张量维度应该和输入张量相同 - -返回类型：output (Variable) - - -**代码示例**: - -.. code-block:: python - - output = fluid.layers.sequence_scatter(input, index, updates) - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_slice: - -sequence_slice -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_slice(input, offset, length, name=None) - -**实现Sequence Slice(序列切片)运算** - -该层从给定序列中截取子序列。截取依据为所给的开始 ``offset`` （偏移量） 和子序列长 ``length`` 。 - -仅支持序列数据，LoD level（LoD层次为1） -:: - 输入变量： - - input.data = [[a1, a2], [b1, b2], [c1, c2], [d1, d2], [e1, e2]], - input.lod = [[3, 2]], - input.dims = (5, 2), - - 以及 offset.data = [[0], [1]] and length.data = [[2], [1]], - - 则输出变量为： - - out.data = [[a1, a2], [b1, b2], [e1, e2]], - out.lod = [[2, 1]], - out.dims = (3, 2). - -.. note:: - ``input`` ， ``offset`` ， ``length`` 的第一维大小应相同。 - ``offset`` 从0开始。 - -参数: - - **input** (Variable) – 输入变量 ，承载着完整的序列 - - **offset** (Variable) – 对每个序列切片的起始索引 - - **length** (Variable) – 每个子序列的长度 - - **name** (str|None) – 该层的命名，可选项。 如果None, 则自动命名该层 - -返回：输出目标子序列 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - import numpy as np - seqs = fluid.layers.data(name='x', shape=[10, 5], - dtype='float32', lod_level=1) - offset = fluid.layers.assign(input=np.array([[0, 1]]).astype("int32")) - length = fluid.layers.assign(input=np.array([[2, 1]]).astype("int32")) - subseqs = fluid.layers.sequence_slice(input=seqs, offset=offset, - length=length) - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_softmax: - -sequence_softmax -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_softmax(input, use_cudnn=False, name=None) - -该函数计算每一个序列所有时间步中的softmax激活函数。每个时间步的维度应为1。 - -输入张量的形状可为 :math:`[N，1]` 或者 :math:`[N]` , :math:`N` 是所有序列长度之和。 - -对mini-batch的第i序列： - -.. math:: - - Out\left ( X[lod[i]:lod[i+1]],: \right ) = \frac{exp(X[lod[i]:lod[i+1],:])}{\sum (exp(X[lod[i]:lod[i+1],:]))} - -例如，对有3个序列（可变长度）的mini-batch，每个包含2，3，2时间步，其lod为[0,2,5,7]，则在 :math:`X[0:2,:],X[2:5,:],X[5:7,:]` 中进行softmax运算，并且 :math:`N` 的结果为7. - -参数： - - **input** (Variable) - 输入变量，为LoDTensor - - **use_cudnn** (bool) - 是否用cudnn核，仅当下载cudnn库才有效。默认：False - - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。默认：None - -返回：sequence_softmax的输出 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[7, 1], - dtype='float32', lod_level=1) - x_sequence_softmax = fluid.layers.sequence_softmax(input=x) - - - - - - - - - - -.. _cn_api_fluid_layers_sequence_unpad: - -sequence_unpad -------------------------------- - -.. py:function:: paddle.fluid.layers.sequence_unpad(x, length, name=None) - -**实现Sequence Unpad(去除序列填充值)运算** - -该层从给定序列中删除padding（填充值），并且将该序列转变为未填充时的原序列作为该层的输出，并且实际长度可以在输出的LoD信息中取得。 - -:: - - 示例： - - 给定输入变量 ``x`` : - x.data = [[ 1.0, 2.0, 3.0, 4.0, 5.0], - [ 6.0, 7.0, 8.0, 9.0, 10.0], - [11.0, 12.0, 13.0, 14.0, 15.0]], - - 其中包含 3 个被填充到长度为5的序列，实际长度由输入变量 ``length`` 指明： - - length.data = [[2], [3], [4]], - - 则去填充（unpad）后的输出变量为： - - out.data = [[1.0, 2.0, 6.0, 7.0, 8.0, 11.0, 12.0, 13.0, 14.0]] - out.lod = [[2, 3, 4]] - - - -参数: - - **x** (Variable) – 输入变量，承载着多个填充后等长的序列 - - **length** (Variable) – 变量，指明去填充后各个序列所具有的实际长度 - - **name** (str|None) – 可选项，该层名称。 若为 None, 将自动命名该层 - -返回：变量，承载着去填充处理后的序列 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[10, 5], dtype='float32') - len = fluid.layers.data(name='length', shape=[1], dtype='int64') - out = fluid.layers.sequence_unpad(x=x, length=len) - - - - - - - - - - - - -.. _cn_api_fluid_layers_shape: - -shape -------------------------------- - -.. py:function:: paddle.fluid.layers.shape(input) - -shape算子 - -获得输入张量的形状。现在只支持输入CPU的Tensor。 - -参数： - - **input** （Variable）- （Tensor），输入张量。 - -返回： (Tensor），输入张量的形状，形状的数据类型是int32，它将与输入张量（Tensor）在同一设备上。 - -返回类型： 输出（Variable）。 - - - - - - - - - - - -.. _cn_api_fluid_layers_sigmoid_cross_entropy_with_logits: - -sigmoid_cross_entropy_with_logits -------------------------------- - -.. py:function:: paddle.fluid.layers.sigmoid_cross_entropy_with_logits(x, label, name=None) - -在类别不相互独立的分类任务中，该函数可以衡量按元素顺序的可能性误差。可以这么认为，为单一数据点预测标签，它们之间不是完全互斥的关系。例如，一篇新闻文章可以同时关于政治，科技，体育或者同时不包含这些内容。 - -逻辑loss可通过下式计算： - -.. math:: - loss = -Labels * log(sigma(X)) - (1 - Labels) * log(1 - sigma(X)) - -已知: - -.. math:: - sigma(X) = \frac{1}{1 + exp(-X)} - -代入最开始的式子， - -.. math:: - loss = X - X * Labels + log(1 + exp(-X)) - -为了计算稳定性，防止 :math:`exp(-X)` 溢出，当 :math:`X<0` 时，loss将采用以下公式计算: - -.. math:: - loss = max(X, 0) - X * Labels + log(1 + exp(-|X|)) - -输入 ``X`` 和 ``label`` 都可以携带LoD信息。当输出仅采用输入 ``X`` 的LoD。 - - - -参数: - - **x** (Variable) - (Tensor, 默认 Tensor)，形为 N x D 的二维张量，N为batch大小，D为类别数目。该输入是一个由先前运算得出的logit组成的张量。logit是未标准化(unscaled)的log概率， 公式为 :math:`log(\frac{p}{1-p})` - - **label** (Variable) - (Tensor, 默认 Tensor) 具有和X相同类型，相同形状的二维张量。该输入张量代表了每个logit的可能标签 - - **name** (basestring|None) - 输出的名称 - -返回： (Tensor, 默认Tensor), 形为 N x D 的二维张量，其值代表了按元素的逻辑loss - -返回类型: Variable - - - - - - - - - - - - -.. _cn_api_fluid_layers_similarity_focus: - -similarity_focus -------------------------------- - -.. py:function:: paddle.fluid.layers.similarity_focus(input, axis, indexes, name=None) - -**实现SimilarityFocus(相似度聚焦)运算** - -通过以下三种方式，该层生成一个和输入 ``input`` 同形的mask（掩码）： - -1. 根据 ``axis`` 和 ``indexes`` 提取一个三维张量，第一维为batch大小。 - 例如，如果 ``axis=1, indexes=[a]`` , 将得到矩阵 T=X[:, a, :, :] 。 - 该例中，如果输入X的形为 (BatchSize, A, B, C) ，则输出张量T的形为 (BatchSize, B, C) 。 -2. 对于每一个索引，在输出T中找到最大值。所以同一行、同一列最多只有一个数字，这意味着如果在第i行，第j列中找到最大值，那么在相应行、列中的其他数值都将被忽略。然后再在剩余的数值中找到下一个最大值。显然，将会产生 min（B,C）个数字，并把三维相似聚焦掩码张量相应位置的元素置为1，其余则置为0。对每个索引按元素进行or运算。 -3. 将这个三维相似度聚焦mask调整、适配于输入 ``input`` 的形状 - -请参照 `Similarity Focus Layer `_ 。 - -:: - - 例如 : - - 给定四维张量 x 形为 (BatchSize, C, A, B), 其中C 为通道Channel数目， - 特征图（feature map）的形为（A,B）： - - x.shape = (2, 3, 2, 2) - x.data = [[[[0.8, 0.1], - [0.4, 0.5]], - - [[0.9, 0.7], - [0.9, 0.9]], - - [[0.8, 0.9], - [0.1, 0.2]]], - - - [[[0.2, 0.5], - [0.3, 0.4]], - - [[0.9, 0.7], - [0.8, 0.4]], - - [[0.0, 0.2], - [0.4, 0.7]]]] - - 给定轴: 1 (即channel轴) - 给定索引: [0] - - 于是我们得到一个与输入同形的四维输出张量： - out.shape = (2, 3, 2, 2) - out.data = [[[[1.0, 0.0], - [0.0, 1.0]], - - [[1.0, 0.0], - [0.0, 1.0]], - - [[1.0, 0.0], - [0.0, 1.0]]], - - [[[0.0, 1.0], - [1.0, 0.0]], - - [[0.0, 1.0], - [1.0, 0.0]], - - [[0.0, 1.0], - [1.0, 0.0]]]] - - - -参数: - - **input** (Variable) – 输入张量(默认类型为float)。应为一个四维张量，形为[BatchSize, A, B, C] - - **axis** (int) – 指明要选择的轴。 可能取值为 1, 2 或 3. - - **indexes** (list) – 指明选择维度的索引列表 - -返回：一个和输入张量同形、同类型的张量变量 - -返回类型：Variable - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data( - name='data', shape=[2, 3, 2, 2], dtype='float32') - x = fluid.layers.layer_norm(input=data, axis=1, indexes=[0]) - - - - - - - - - - - - -.. _cn_api_fluid_layers_slice: - -slice -------------------------------- - -.. py:function:: paddle.fluid.layers.slice(input, axes, starts, ends) - -slice算子。 - -沿多个轴生成输入张量的切片。与numpy类似： https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html Slice使用 ``axes`` 、 ``starts`` 和 ``ends`` 属性来指定轴列表中每个轴的起点和终点维度，它使用此信息来对输入数据张量切片。如果向 ``starts`` 或 ``ends`` 传递负值，则表示该维度结束之前的元素数目。如果传递给 ``starts`` 或 ``end`` 的值大于n（此维度中的元素数目），则表示n。对于未知大小维度的末尾进行切片，则建议传入 ``INT_MAX`` 。如果省略轴，则将它们设置为[0，...，ndim-1]。以下示例将解释切片如何工作： - -:: - - 案例1：给定：data=[[1,2,3,4],[5,6,7,8],] - axes=[0,1] - starts=[1,0] - ends=[2,3] - 则： - result=[[5,6,7],] - - 案例2：给定： - data=[[1,2,3,4],[5,6,7,8],] - starts=[0,1] - ends=[-1,1000] - 则： - result=[[2,3,4],] - -参数： - - **input** （Variable）- 提取切片的数据张量（Tensor）。 - - **axes** （List）- （list ）开始和结束的轴适用于。它是可选的。如果不存在，将被视为[0,1，...，len（starts）- 1]。 - - **starts** （List）- （list ）在轴上开始相应轴的索引。 - - **ends** （List）- （list ）在轴上结束相应轴的索引。 - -返回： 切片数据张量（Tensor）. - -返回类型： 输出（Variable）。 - - - - - - - - - - -.. _cn_api_fluid_layers_smooth_l1: - -smooth_l1 -------------------------------- - -.. py:function:: paddle.fluid.layers.smooth_l1(x, y, inside_weight=None, outside_weight=None, sigma=None) - -该layer计算变量x1和y 的smooth L1 loss，它以x和y的第一维大小作为批处理大小。对于每个实例，按元素计算smooth L1 loss，然后计算所有loss。输出变量的形状是[batch_size, 1] - - -参数: - - **x** (Variable) - rank至少为2的张量。输入x的smmoth L1 loss 的op，shape为[batch_size, dim1，…],dimN]。 - - **y** (Variable) - rank至少为2的张量。与 ``x`` 形状一致的的smooth L1 loss op目标值。 - - **inside_weight** (Variable|None) - rank至少为2的张量。这个输入是可选的，与x的形状应该相同。如果给定， ``(x - y)`` 的结果将乘以这个张量元素。 - - **outside_weight** (变量|None) - 一个rank至少为2的张量。这个输入是可选的，它的形状应该与 ``x`` 相同。如果给定，那么 smooth L1 loss 就会乘以这个张量元素。 - - **sigma** (float|None) - smooth L1 loss layer的超参数。标量，默认值为1.0。 - -返回： smooth L1 loss, shape为 [batch_size, 1] - -返回类型: Variable - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[128], dtype='float32') - label = fluid.layers.data( - name='label', shape=[100], dtype='float32') - fc = fluid.layers.fc(input=data, size=100) - out = fluid.layers.smooth_l1(x=fc, y=label) - - - - - - - - - - -.. _cn_api_fluid_layers_soft_relu: - -soft_relu -------------------------------- - -.. py:function:: paddle.fluid.layers.soft_relu(x, threshold=40.0, name=None) - -SoftRelu 激活函数 - -.. math:: out=ln(1+exp(max(min(x,threshold),threshold)) - -参数: - - **x** (variable) - SoftRelu operator的输入 - - **threshold** (FLOAT|40.0) - SoftRelu的阈值 - - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name=”x”, shape=[2,3,16,16], dtype=”float32”) - y = fluid.layers.soft_relu(x, threshold=20.0) - - - - - - - - -.. _cn_api_fluid_layers_softmax: - -softmax -------------------------------- - -.. py:function:: paddle.fluid.layers.softmax(input, use_cudnn=True, name=None) - -softmax操作符的输入是任意阶的张量，输出张量和输入张量的维度相同。 - -首先逻辑上将输入张量压平至二维矩阵。矩阵的第二维（行数）和输入张量的最后一维相同。第一维（列数） -是输入张量除最后一维之外的所有维的产物。对矩阵的每一行来说,softmax操作将K维(K是矩阵的宽度,也就是输入张量的维度)任意实际值，压缩成K维取值为[0,1]之间的向量，压缩后k个值的和为1。 - - -softmax操作符计算k维向量输入中所有其他维的指数和指数值的累加和。维的指数比例和所有其他维的指数值之和作为softmax操作符的输出。 - -对矩阵中的每行i和每列j有： - -.. math:: - - Out[i,j] = \frac{exp(X[i,j])}{\sum{j}_exp(X[i,j])} - -参数： - - **input** (Variable) - 输入变量 - - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效 - - **name** (str|None) - 该层名称（可选）。若为空，则自动为该层命名。默认：None - -返回： softmax输出 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - fc = fluid.layers.fc(input=x, size=10) - softmax = fluid.layers.softmax(input=fc) - - - - - - - - - -.. _cn_api_fluid_layers_softmax_with_cross_entropy: - -softmax_with_cross_entropy -------------------------------- - -.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100, numeric_stable_mode=False, return_softmax=False) - -使用softmax的交叉熵在输出层已被广泛使用。该函数计算输入张量每一行的softmax标准化值，而后计算交叉熵。通过此种方式，可以得到更具数字稳定性的梯度值。 - -因为该运算是在内部进行logit上的softmax运算，所以它需要未标准化（unscaled）的logit。该运算不应该对softmax运算的输出进行操作，否则会得出错误结果。 - -当 ``soft_label`` 为 ``False`` 时，该运算接受互斥的硬标签，batch中的每一个样本都以为1的概率分类到一个类别中，并且仅有一个标签。 - -涉及到的等式如下: - -1.硬标签，即 one-hot label, 每个样本仅可分到一个类别 - -.. math:: - loss_j = -\text{logit}_{label_j} +\log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right), j = 1,..., K - -2.软标签，每个样本可能被分配至多个类别中 - -.. math:: - loss_j = -\sum_{i=0}^{K}\text{label}_i\left(\text{logit}_i - \log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right)\right), j = 1,...,K - -3.如果 ``numeric_stable_mode`` 为真，在通过softmax和标签计算交叉熵损失前， softmax 首先经由下式计算得出： - -.. math:: - max_j &= \max_{i=0}^{K}{\text{logit}_i} \\ - log\_max\_sum_j &= \log\sum_{i=0}^{K}\exp(logit_i - max_j)\\ - softmax_j &= \exp(logit_j - max_j - {log\_max\_sum}_j) - - -参数: - - **logits** (Variable) - 未标准化(unscaled)的log概率,一个形为 N X K 的二维张量。 N是batch大小，K是类别总数 - - **label** (Variable) - 2-D 张量，代表了正确标注（ground truth）, 如果 ``soft_label`` 为 False，则该参数是一个形为 N X 1 的Tensor 。如果 ``soft_label`` 为 True，它是 Tensor ，形为 N X K - - **soft_label** (bool) - 是否将输入标签当作软标签。默认为False - - **ignore_index** (int) - 指明要无视的目标值，使之不对输入梯度有贡献。仅在 ``soft_label`` 为False时有效，默认为-100 - - **numeric_stable_mode** (bool) – 标志位，指明是否使用一个具有更佳数学稳定性的算法。仅在 ``soft_label`` 为 False的GPU模式下生效. 若 ``soft_label`` 为 True 或者执行场所为CPU, 算法一直具有数学稳定性。 注意使用稳定算法时速度可能会变慢。默认为 False - - **return_softmax** (bool) – 标志位，指明是否额外返回一个softmax值， 同时返回交叉熵计算结果。默认为False - -返回: - - 如果 ``return_softmax`` 为 False， 则返回交叉熵，一个形为[N x 1]的二维张量 - - 如果 ``return_softmax`` 为 True，则返回元组 (loss, softmax) ，其中交叉熵loss为形为[N x 1]的二维张量，softmax为[N x K]的二维张量 - -返回类型:变量或者两个变量组成的元组 - - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name='data', shape=[128], dtype='float32') - label = fluid.layers.data(name='label', shape=[1], dtype='int64') - fc = fluid.layers.fc(input=data, size=100) - out = fluid.layers.softmax_with_cross_entropy( - logits=fc, label=label) - - - - - - - - - - -.. _cn_api_fluid_layers_space_to_depth: - -space_to_depth -------------------------------- - -.. py:function:: paddle.fluid.layers.space_to_depth(x, blocksize, name=None) - -给该函数一个 ``blocksize`` 值，可以对形为[batch, channel, height, width]的输入LoD张量进行space_to_depth（广度至深度）运算。 - -该运算对成块的空间数据进行重组，形成深度。确切地说，该运算输出一个输入LoD张量的拷贝，其高度，宽度维度上的值移动至通道维度上。 - -``blocksize`` 参数指明了数据块大小。 - -重组时，依据 ``blocksize`` , 生成形为 :math:`[batch, channel * blocksize * blocksize, height/blocksize, width/blocksize]` 的输出： - -该运算适用于在卷积间重放缩激励函数，并保持所有的数据。 - - - 在各位置上，不重叠的，大小为 :math:`block\_size * block\_size` 的块重组入深度depth - - 输出张量的深度为 :math:`block\_size * block\_size * input\_channel` - - 输入各个块中的Y,X坐标变为输出张量通道索引的高序部位 - - channel可以被blocksize的平方整除 - - 高度，宽度可以被blocksize整除 - -参数: - - **x** (variable) – 输入LoD张量 - - **blocksize** (variable) – 在每个特征图上选择元素时采用的块大小，应该 > 2 - -返回：输出LoD tensor - -返回类型：Variable - -抛出异常： - - ``TypeError`` - ``blocksize`` 必须是long类型 - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data( - name='data', shape=[1, 4, 2, 2], dtype='float32') - space_to_depthed = fluid.layers.space_to_depth( - x=data, blocksize=2) - - - - - - - - - - -.. _cn_api_fluid_layers_split: - -split -------------------------------- - -.. py:function:: paddle.fluid.layers.split(input,num_or_sections,dim=-1,name=None) - -将输入张量分解成多个子张量 - -参数： - - **input** (Variable)-输入变量，类型为Tensor或者LoDTensor - - **num_or_sections** (int|list)-如果num_or_sections是整数，则表示张量平均划分为的相同大小子张量的数量。如果num_or_sections是一列整数，列表的长度代表子张量的数量，整数依次代表子张量的dim维度的大小 - - **dim** (int)-将要划分的维。如果dim<0,划分的维为rank(input)+dim - - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名 - -返回：一列分割张量 - -返回类型：列表(Variable) - -**代码示例**： - -.. code-block:: python - - # x是维为[3,9,5]的张量： - x0, x1, x2 = fluid.layers.split(x, num_or_sections=3, dim=1) - x0.shape # [3, 3, 5] - x1.shape # [3, 3, 5] - x2.shape # [3, 3, 5] - x0, x1, x2 = fluid.layers.split( - x, num_or_sections=[2, 3, 4], dim=1) - x0.shape # [3, 2, 5] - x1.shape # [3, 3, 5] - x2.shape # [3, 4, 5] - - - - - - - - - -.. _cn_api_fluid_layers_square_error_cost: - -square_error_cost -------------------------------- - -.. py:function:: paddle.fluid.layers.square_error_cost(input,label) - -方差估计层（Square error cost layer） - -该层接受输入预测值和目标值，并返回方差估计 - -对于预测值X和目标值Y，公式为： - -.. math:: - - Out = (X-Y)^{2} - -在以上等式中： - - **X** : 输入预测值，张量（Tensor) - - **Y** : 输入目标值，张量（Tensor） - - **Out** : 输出值，维度和X的相同 - -参数： - - **input** (Variable) - 输入张量（Tensor），带有预测值 - - **label** (Variable) - 标签张量（Tensor），带有目标值 - -返回：张量变量，存储输入张量和标签张量的方差 - -返回类型：变量（Variable） - -**代码示例**： - - .. code-block:: python - - y = layers.data(name='y', shape=[1], dtype='float32') - y_predict = layers.data(name='y_predict', shape=[1], dtype='float32') - cost = layers.square_error_cost(input=y_predict, label=y) - - - - - - - - - -.. _cn_api_fluid_layers_squeeze: - -squeeze -------------------------------- - -.. py:function:: paddle.fluid.layers.squeeze(input, axes, name=None) - -向张量维度中移除单维输入。传入用于压缩的轴。如果未提供轴，所有的单一维度将从维中移除。如果选择的轴的形状条目不等于1，则报错。 - -:: - - - 例如： - - 例1： - 给定 - X.shape = (1,3,1,5) - axes = [0] - 得到 - Out.shape = (3,1,5) - 例2： - 给定 - X.shape = (1,3,1,5) - axes = [] - 得到 - Out.shape = (3,5) - -参数： - - **input** (Variable)-将要压缩的输入变量 - - **axes** (list)-一列整数，代表压缩的维 - - **name** (str|None)-该层名称 - -返回：输出压缩的变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = layers.data(name='x', shape=[5, 1, 10]) - y = layers.sequeeze(input=x, axes=[1]) - - - - - - - - - -.. _cn_api_fluid_layers_stack: - -stack -------------------------------- - -.. py:function:: paddle.fluid.layers.stack(x, axis=0) - -实现了stack层。 - -沿 ``axis`` 轴，该层对输入 ``x`` 进行stack运算。 - -输入 x 可以是单个变量, 或是多个变量组成的列表或元组。如果 x 是一个列表或元组, 那么这些变量必须同形。 假设每个输入的形都为 :math:`[d_0,d_1,...,d_{n−1}]` , 则输出变量的形为 :math:`[d_0,d_1,...,d_{axis}=len(x),...,d_{n−1}]` 。 如果 ``axis`` < 0, 则将其取代为 :math:`axis+rank(x[0])+1` 。 如果 ``axis`` 为 None, 则认为它是 0。 - -参数: - - **x** (Variable|list(Variable)|tuple(Variable)) – 输入变量 - - **axis** (int|None) – 对输入进行stack运算所在的轴 - -返回: 经stack运算后的变量 - -返回类型: Variable - - - - - - - - - - - -.. _cn_api_fluid_layers_stanh: - -stanh -------------------------------- - -.. py:function:: paddle.fluid.layers.stanh(x, scale_a=0.6666666666666666, scale_b=1.7159, name=None) - -STanh 激活算子（STanh Activation Operator.） - -.. math:: - \\out=b*\frac{e^{a*x}-e^{-a*x}}{e^{a*x}+e^{-a*x}}\\ - -参数： - - **x** (Variable) - STanh operator的输入 - - **scale_a** (FLOAT|2.0 / 3.0) - 输入的a的缩放参数 - - **scale_b** (FLOAT|1.7159) - b的缩放参数 - - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: STanh操作符的输出 - -返回类型: 输出(Variable) - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.stanh(x, scale_a=0.67, scale_b=1.72) - - - - - - - -.. _cn_api_fluid_layers_sum: - -sum -------------------------------- - -.. py:function:: paddle.fluid.layers.sum(x) - -sum算子。 - -该运算符对输入张量求和。所有输入都可以携带LoD（详细程度）信息，但是输出仅与第一个输入共享LoD信息。 - -参数： - - **x** （Variable）- （vector ）sum运算符的输入张量（Tensor）。 - -返回: (Tensor）求和算子的输出张量。 - -返回类型： Variable - - - - - - - - - - -.. _cn_api_fluid_layers_swish: - -swish -------------------------------- - -.. py:function:: paddle.fluid.layers.swish(x, beta=1.0, name=None) - -Swish 激活函数 - -.. math:: - \\out = \frac{x}{e^(1+betax)}\\ - -参数： - - **x** (Variable) - Swishoperator的输入 - - **beta** (浮点|1.0) - Swish operator 的常量beta - - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 - -返回: Swish operator 的输出 - -返回类型: output(Variable) - - -**代码示例：** - -.. code-block:: python - - x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") - y = fluid.layers.swish(x, beta=2.0) - - - - - - - - - -.. _cn_api_fluid_layers_topk: - -topk -------------------------------- -.. py:function:: paddle.fluid.layers.topk(input, k, name=None) - -这个运算符用于查找最后一维的前k个最大项，返回它们的值和索引。 - -如果输入是（1-D Tensor），则找到向量的前k最大项，并以向量的形式输出前k最大项的值和索引。values[j]是输入中第j最大项，其索引为indices[j]。 -如果输入是更高阶的张量，则该operator会基于最后一维计算前k项 - -例如： - -.. code-block:: text - - - 如果: - input = [[5, 4, 2, 3], - [9, 7, 10, 25], - [6, 2, 10, 1]] - k = 2 - - 则: - 第一个输入: - values = [[5, 4], - [10, 25], - [6, 10]] - - 第二个输入: - indices = [[0, 1], - [2, 3], - [0, 2]] - -参数： - - **input** (Variable)-输入变量可以是一个向量或者更高阶的张量 - - **k** (int)-在输入最后一纬中寻找的前项数目 - - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名。默认为空 - -返回：含有两个元素的元组。元素都是变量。第一个元素是最后维切片的前k项。第二个元素是输入最后维里值索引 - -返回类型：元组[变量] - -提示：抛出异常-如果k<1或者k不小于输入的最后维 - -**代码示例**： - -.. code-block:: python - - top5_values, top5_indices = layers.topk(input, k=5) - - - - - - - - - -.. _cn_api_fluid_layers_transpose: - -transpose -------------------------------- - -.. py:function:: paddle.fluid.layers.transpose(x,perm,name=None) - -根据perm对输入矩阵维度进行重排。 - -返回张量（tensor）的第i维对应输入维度矩阵的perm[i]。 - -参数： - - **x** (Variable) - 输入张量（Tensor) - - **perm** (list) - 输入维度矩阵的转置 - - **name** (str) - 该层名称（可选） - -返回： 转置后的张量（Tensor） - -返回类型：变量（Variable） - -**代码示例**: - -.. code-block:: python - - # 请使用 append_batch_size=False 来避免 - # 在数据张量中添加多余的batch大小维度 - x = fluid.layers.data(name='x', shape=[5, 10, 15], - dtype='float32', append_batch_size=False) - x_transposed = layers.transpose(x, perm=[1, 0, 2]) - - - - - - - - - -.. _cn_api_fluid_layers_uniform_random_batch_size_like: - -uniform_random_batch_size_like -------------------------------- - -.. py:function:: paddle.fluid.layers.uniform_random_batch_size_like(input, shape, dtype='float32', input_dim_idx=0, output_dim_idx=0, min=-1.0, max=1.0, seed=0) - -uniform_random_batch_size_like算子。 - -此运算符使用与输入张量（Tensor）相同的batch_size初始化张量（Tensor），并使用从均匀分布中采样的随机值。 - -参数： - - **input** （Variable）- 其input_dim_idx'th维度指定batch_size的张量（Tensor）。 - - **shape** （元组|列表）- 输出的形状。 - - **input_dim_idx** （Int）- 默认值0.输入批量大小维度的索引。 - - **output_dim_idx** （Int）- 默认值0.输出批量大小维度的索引。 - - **min** （Float）- （默认 1.0）均匀随机的最小值。 - - **max** （Float）- （默认 1.0）均匀随机的最大值。 - - **seed** （Int）- （int，default 0）用于生成样本的随机种子。0表示使用系统生成的种子。注意如果seed不为0，则此运算符将始终每次生成相同的随机数。 - - **dtype** （np.dtype | core.VarDesc.VarType | str） - 数据类型：float32，float_16，int等。 - -返回: 指定形状的张量（Tensor）将使用指定值填充。 - -返回类型: Variable - - - - - - - - - -.. _cn_api_fluid_layers_unsqueeze: - -unsqueeze -------------------------------- - -.. py:function:: paddle.fluid.layers.unsqueeze(input, axes, name=None) - -向张量shape中插入单维函数。获取一个必需axes值，用来插入维度列表。输出张量显示轴的维度索引值。 - -比如： - 给定一个张量，例如维度为[3,4,5]的张量，轴为[0,4]的未压缩张量，维度为[1,3,4,5,1] - -参数： - - **input** (Variable)- 未压缩的输入变量 - - **axes** (list)- 一列整数，代表要插入的维数 - - **name** (str|None) - 该层名称 - -返回：输出未压缩变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - x = layers.data(name='x', shape=[5, 10]) - y = layers.unsequeeze(input=x, axes=[1]) - - - - - - - - - - -.. _cn_api_fluid_layers_unstack: - -unstack -------------------------------- - -.. py:function:: paddle.fluid.layers.unstack(x, axis=0, num=None) - -实现了unstack层。 - -沿 ``axis`` 轴，该层对输入 ``x`` 进行unstack运算。 - -如果 ``axis`` <0，则将其以 :math:`axis+rank(x)` 代之。 - -如果 ``num`` 为 None，则它可以从 ``x.shape[axis]`` 中推断而来。 - -如果 ``x.shape[axis]`` <= 0或者Unknown, 则抛出异常 ``ValueError`` 。 - -参数: - - **x** (Variable|list(Variable)|tuple(Variable)) – 输入变量 - - **axis** (int|None) – 对输入进行unstack运算所在的轴 - - **num** (int|None) - 输出变量的数目 - -返回: 经unstack运算后的变量 - -返回类型: Variable - - - - - - - - - - - -.. _cn_api_fluid_layers_warpctc: - -warpctc -------------------------------- - -.. py:function:: paddle.fluid.layers.warpctc(input, label, blank=0, norm_by_times=False, use_cudnn=False)) - -该操作符集成了 `开源Warp-CTC库 `_ ，计算基于神经网络的时序类分类（CTC）损失。原生softmax激活函数集成到Wrap-CTC库中，操作符也可称作含CTC的softmax，将输入张量每一行的值正则化。 - -参数： - - **input** （Variable） - 变长序列的非尺度化概率，是一个含LoD信息的二维张量。shape为[Lp，num_classes+1]，Lp是所有输出序列长度之和，num_classes是实际类别数。（不包括空白标签） - - **label** (Variable） - 变长序列中正确标记的数据，是一个含LoD信息的二维张量。shape为[Lg，1]，Lg是所有标签长度之和 - - **blank** （int，默认0） - 基于神经网络的时序类分类（CTC）损失的空白标签索引，在半开区间间隔内[0，num_classes+1] - - **norm_by_times** （bool，默认false） - 是否利用时间步长（即序列长度）的数量对梯度进行正则化。如果warpctc层后面跟着mean_op则无需对梯度正则化。 - - **use_cudnn** (bool, 默认false) - 是否使用cudnn - -返回：基于神经网络的时序类分类（CTC）损失，是一个shape为[batch_size，1]的二维张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - label = fluid.layers.data(shape=[11, 8], dtype='float32', lod_level=1) - predict = fluid.layers.data(shape=[11, 1], dtype='float32') - cost = fluid.layers.warpctc(input=predict, label=label) - - - - - - - - - - - -============ - ops -============ - - -.. _cn_api_fluid_layers_abs: - -abs -------------------------------- - -.. py:function:: paddle.fluid.layers.abs(x, name=None) - - -参数: - - **x** - abs运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - - -返回： Abs运算符的输出。 - - - - - - - - - - - -.. _cn_api_fluid_layers_ceil: - -ceil -------------------------------- - -.. py:function:: paddle.fluid.layers.ceil(x, name=None) - - -参数: - - **x** - Ceil运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Ceil运算符的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_cos: - -cos -------------------------------- - -.. py:function:: paddle.fluid.layers.cos(x, name=None) - - - -参数: - - **x** - cos运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Cos运算符的输出 - - - - - - - - - - -.. _cn_api_fluid_layers_cumsum: - -cumsum -------------------------------- - -.. py:function:: paddle.fluid.layers.cumsum(x,axis=None,exclusive=None,reverse=None - -沿给定轴的元素的累加和。默认结果的第一个元素和输入的第一个元素一致。如果exlusive为真，结果的第一个元素则为0。 - -参数： - - **x** -累加操作符的输入 - - **axis** (INT)-需要累加的维。-1代表最后一维。[默认 -1]。 - - **exclusive** (BOOLEAN)-是否执行exclusive累加。[默认false]。 - - **reverse** (BOOLEAN)-若为true,则以相反顺序执行累加。[默认 false]。 - -返回：累加器的输出 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data(name="input", shape=[32, 784]) - result = fluid.layers.cumsum(data, axis=0) - - - - - - - - - -.. _cn_api_fluid_layers_exp: - -exp -------------------------------- - -.. py:function:: paddle.fluid.layers.exp(x, name=None) - - -参数: - - **x** - Exp运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Exp算子的输出 - - - - - - - - - - -.. _cn_api_fluid_layers_floor: - -floor -------------------------------- - -.. py:function:: paddle.fluid.layers.floor(x, name=None) - - - -参数: - - **x** - Floor运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Floor运算符的输出。 - - - - - - - - - - - -.. _cn_api_fluid_layers_hard_shrink: - -hard_shrink -------------------------------- - -.. py:function:: paddle.fluid.layers.hard_shrink(x,threshold=None) - -HardShrink激活函数(HardShrink activation operator) - - -.. math:: - - out = \begin{cases} - x, \text{if } x > \lambda \\ - x, \text{if } x < -\lambda \\ - 0, \text{otherwise} - \end{cases} - -参数： - - **x** - HardShrink激活函数的输入 - - **threshold** (FLOAT)-HardShrink激活函数的threshold值。[默认：0.5] - -返回：HardShrink激活函数的输出 - -**代码示例**： - - .. code-block:: python - - data = fluid.layers.data(name="input", shape=[784]) - result = fluid.layers.hard_shrink(x=data, threshold=0.3) - - - - - - - - - -.. _cn_api_fluid_layers_logsigmoid: - -logsigmoid -------------------------------- - -.. py:function:: paddle.fluid.layers.logsigmoid(x, name=None) - - - -参数: - - **x** - LogSigmoid运算符的输入 - - **use_mkldnn** (bool) - （默认为False）仅在 ``mkldnn`` 内核中使用 - -返回： LogSigmoid运算符的输出 - - - - - - - - - - -.. _cn_api_fluid_layers_reciprocal: - -reciprocal -------------------------------- - -.. py:function:: paddle.fluid.layers.reciprocal(x, name=None) - - -参数: - - **x** - Ceil运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Reciprocal运算符的输出。 - - - - - - - - - - - - - -.. _cn_api_fluid_layers_round: - -round -------------------------------- - -.. py:function:: paddle.fluid.layers.round(x, name=None) - - -参数: - - **x** - Ceil运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Round运算符的输出。 - - - - - - - - - - -.. _cn_api_fluid_layers_sigmoid: - -sigmoid -------------------------------- - -.. py:function:: paddle.fluid.layers.sigmoid(x, name=None) - - - -参数: - - **x** - Sigmoid运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - - -返回： Sigmoid运算输出. - - - - - - - - - - -.. _cn_api_fluid_layers_sin: - -sin -------------------------------- - -.. py:function:: paddle.fluid.layers.sin(x, name=None) - - -参数: - - **x** - sin运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Sin运算符的输出。 - - - - - - - - - - - -.. _cn_api_fluid_layers_softplus: - -softplus -------------------------------- - -.. py:function:: paddle.fluid.layers.softplus(x,name=None) - -参数： - - **x** : Softplus操作符的输入 - - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 - -返回：Softplus操作后的结果 - - - - - - - - - -.. _cn_api_fluid_layers_softshrink: - -softshrink -------------------------------- - -.. py:function:: paddle.fluid.layers.softshrink(x, name=None) - -Softshrink激活算子 - -.. math:: - out = \begin{cases} - x - \lambda, \text{if } x > \lambda \\ - x + \lambda, \text{if } x < -\lambda \\ - 0, \text{otherwise} - \end{cases} - -参数： - - **x** - Softshrink算子的输入 - - **lambda** （FLOAT）- 非负偏移量。 - -返回： Softshrink运算符的输出 - - - - - - - - - - -.. _cn_api_fluid_layers_softsign: - -softsign -------------------------------- - -.. py:function:: Paddle.fluid.layers.softsign(x,name=None) - -参数： - - **x** : Softsign操作符的输入 - - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 - -返回：Softsign操作后的结果 - - - - - - - - - -.. _cn_api_fluid_layers_sqrt: - -sqrt -------------------------------- - -.. py:function:: paddle.fluid.layers.sqrt(x, name=None) - - -参数: - - **x** - Sqrt运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： Sqrt算子的输出。 - - - - - - - - - - - -.. _cn_api_fluid_layers_square: - -square -------------------------------- - -.. py:function:: paddle.fluid.layers.square(x,name=None) - -参数: - - **x** : 平方操作符的输入 - - **use_mkldnn** (bool, 默认false) 仅在mkldnn核中使用 - -返回：平方后的结果 - - - - - - - - - -.. _cn_api_fluid_layers_tanh: - -tanh -------------------------------- - -.. py:function:: paddle.fluid.layers.tanh(x, name=None) - - - -参数: - - **x** - Tanh运算符的输入 - - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 - - -返回： Tanh算子的输出。 - - - - - - - - - - - -.. _cn_api_fluid_layers_tanh_shrink: - -tanh_shrink -------------------------------- - -.. py:function:: paddle.fluid.layers.tanh_shrink(x, name=None) - - -参数: - - **x** - TanhShrink运算符的输入 - - **use_mkldnn** (bool)- （默认为false）仅在 ``mkldnn`` 内核中使用 - -返回： tanh_shrink算子的输出 - - - - - - - - - -.. _cn_api_fluid_layers_thresholded_relu: - -thresholded_relu -------------------------------- - -.. py:function:: paddle.fluid.layers.thresholded_relu(x,threshold=None) - - ThresholdedRelu激活函数 - - .. math:: - - out = \left\{\begin{matrix} - x, if&x > threshold\\ - 0, &otherwise - \end{matrix}\right. - -参数： - - **x** -ThresholdedRelu激活函数的输入 - - **threshold** (FLOAT)-激活函数threshold的位置。[默认1.0]。 - - 返回：ThresholdedRelu激活函数的输出 - - **代码示例**： - - .. code-block:: python - - data = fluid.layers.data(name="input", shape=[1]) - result = fluid.layers.thresholded_relu(data, threshold=0.4) - - - - - - - - - -.. _cn_api_fluid_layers_uniform_random: - -uniform_random -------------------------------- - -.. py:function:: Paddle.fluid.layers.uniform_random(shape,dtype=None,min=None,max=None,seed=None) -该操作符初始化一个张量，该张量的值是从正太分布中抽样的随机值 - -参数： - - **shape** (LONGS)-输出张量的维 - - **min** (FLOAT)-均匀随机分布的最小值。[默认 -1.0] - - **max** (FLOAT)-均匀随机分布的最大值。[默认 1.0] - - **seed** (INT)-随机种子，用于生成样本。0表示使用系统生成的种子。注意如果种子不为0，该操作符每次都生成同样的随机数。[默认 0] - - **dtype** (INT)-输出张量数据类型。[默认5(FP32)] - -返回：正态随机操作符的输出张量 - -**代码示例**： - -.. code-block:: python - - result = fluid.layers.uniform_random(shape=[32, 784]) - - - - - - - - - - - -============ - tensor -============ - - -.. _cn_api_fluid_layers_argmax: - -argmax -------------------------------- - -.. py:function:: paddle.fluid.layers argmin(x,axis=0) - - **argmax** - - 该功能计算输入张量元素中最大元素的索引，张量的元素在提供的轴上。 - - 参数： - - **x** (Variable)-用于计算最大元素索引的输入 - - **axis** (int)-用于计算索引的轴 - - 返回：存储在输出中的张量 - - 返回类型：变量（Variable） - - **代码示例**： - - .. code-block:: python - - out = fluid.layers.argmax(x=in, axis=0) - out = fluid.layers.argmax(x=in, axis=-1) - - - - - - - - - -.. _cn_api_fluid_layers_argmin: - -argmin -------------------------------- - -.. py:function:: paddle.fluid.layers argmin(x,axis=0) - - **argmin** - - 该功能计算输入张量元素中最小元素的索引，张量元素在提供的轴上。 - - 参数： - - **x** (Variable)-计算最小元素索引的输入 - - **axis** (int)-计算索引的轴 - - 返回：存储在输出中的张量 - - 返回类型：变量（Variable） - - **代码示例**： - - .. code-block:: python - - out = fluid.layers.argmin(x=in, axis=0) - out = fluid.layers.argmin(x=in, axis=-1) - - - - - - - - - -.. _cn_api_fluid_layers_argsort: - -argsort -------------------------------- - -.. py:function:: paddle.fluid.layers argsort(input,axis=-1,name=None) - -对给定轴上的输入变量进行排序，输出排序好的数据和相应的索引，其维度和输入相同 - -.. code-block:: text - - 例如： - 给定 input 并指定 axis=-1 - - input = [[0.15849551, 0.45865775, 0.8563702 ], - [0.12070083, 0.28766365, 0.18776911]], - - 执行argsort操作后，得到排序数据： - - out = [[0.15849551, 0.45865775, 0.8563702 ], - [0.12070083, 0.18776911, 0.28766365]], - - 根据指定axis排序后的数据indices变为: - - indices = [[0, 1, 2], - [0, 2, 1]] - -参数： - - **input** (Variable)-用于排序的输入变量 - - **axis** (int)-含有用于排序输入变量的轴。当axis<0,实际的轴为axis+rank(input)。默认为-1，即最后一维。 - - **name** (str|None)-（可选）该层名称。如果设为空，则自动为该层命名。 - -返回：含有已排序的数据和索引 - -返回类型：元组 - -**代码示例**： - -.. code-block:: python - - input = fluid.layers.data(data=[2, 3]) - out, indices = fluid.layers.argsort(input, axis=0) - - - - - - - - - -.. _cn_api_fluid_layers_assign: - -assign -------------------------------- - -.. py:function:: paddle.fluid.layers.assign(input,output=None) - -**Assign** - -该功能将输入变量复制到输出变量 - -参数： - - **input** (Variable|numpy.ndarray)-源变量 - - **output** (Variable|None)-目标变量 - -返回：作为输出的目标变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - out = fluid.layers.create_tensor(dtype='float32') - hidden = fluid.layers.fc(input=data, size=10) - fluid.layers.assign(hidden, out) - - - - - - - - - -.. _cn_api_fluid_layers_cast: - -cast -------------------------------- - -.. py:function:: paddle.fluid.layers.cast(x,dtype) - -该层传入变量x,并用x.dtype将x转换成dtype类型，作为输出。 - -参数： - - **x** (Variable)-转换函数的输入变量 - - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出变量的数据类型 - -返回：转换后的输出变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.data(name='x', shape=[13], dtype='float32') - result = fluid.layers.cast(x=data, dtype='float64') - - - - - - - - - -.. _cn_api_fluid_layers_concat: - -concat -------------------------------- - -.. py:function:: paddle.fluid.layers.concat(input,axis=0,name=None) - -**Concat** - -这个函数将输入连接在前面提到的轴上，并将其作为输出返回。 - -参数： - - **input** (list)-将要联结的张量列表 - - **axis** (int)-数据类型为整型的轴，其上的张量将被联结 - - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名。 - -返回：输出的联结变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - out = fluid.layers.concat(input=[Efirst, Esecond, Ethird, Efourth]) - - - - - - - - - -.. _cn_api_fluid_layers_create_global_var: - -create_global_var -------------------------------- - -.. py:function:: paddle.fluid.layers.create_global_var(shape,value,dtype,persistable=False,force_cpu=False,name=None) - -在全局块中创建一个新的带有值的张量。 - -参数： - - **shape** (list[int])-变量的维度 - - **value** (float)-变量的值。填充新创建的变量 - - **dtype** (string)-变量的数据类型 - - **persistable** (bool)-如果是永久变量。默认：False - - **force_cpu** (bool)-将该变量压入CPU。默认：False - - **name** (str|None)-变量名。如果设为空，则自动创建变量名。默认：None. - -返回：创建的变量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - var = fluid.create_global_var(shape=[2,3], value=1.0, dtype='float32', - persistable=True, force_cpu=True, name='new_var') - - - - - - - - - -.. _cn_api_fluid_layers_create_parameter: - -create_parameter -------------------------------- - -.. py:function:: paddle.fluid.layers.create_parameter(shape,dtype,name=None,attr=None,is_bias=False,default_initializer=None) - -创建一个参数。该参数是一个可学习的变量，拥有梯度并且可优化。 - -注：这是一个低级别的API。如果您希望自己创建新的op，这个API将非常有用，无需使用layers。 - -参数： - - **shape** (list[int])-参数的维度 - - **dtype** (string)-参数的元素类型 - - **attr** (ParamAttr)-参数的属性 - - **is_bias** (bool)-当default_initializer为空，该值会对选择哪个默认初始化程序产生影响。如果is_bias为真，则使用initializer.Constant(0.0)，否则使用Xavier()。 - - **default_initializer** (Initializer)-参数的初始化程序 - -返回：创建的参数 - -**代码示例**： - -.. code-block:: python - - W = fluid.layers.create_parameter(shape=[784, 200], dtype='float32') - data = fluid.layers.data(name="img", shape=[64, 784], append_batch_size=False) - hidden = fluid.layers.matmul(x=data, y=W) - - - - - - - - - -.. _cn_api_fluid_layers_create_tensor: - -create_tensor -------------------------------- - -.. py:function:: paddle.fluid.layers.create_tensor(dtype,name=None,persistable=False) - -创建一个变量，存储数据类型为dtype的LoDTensor。 - -参数： - - **dtype** (string)-“float32”|“int32”|..., 创建张量的数据类型。 - - **name** (string)-创建张量的名称。如果未设置，则随机取一个唯一的名称。 - - **persistable** (bool)-为创建张量设置的永久标记 - -返回：存储在创建张量中的张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - tensor = fluid.layers.create_tensor(dtype='float32') - - - - - - - - - - -.. _cn_api_fluid_layers_fill_constant: - -fill_constant -------------------------------- - -.. py:function:: paddle.fluid.layers fill_constant(shape,dtype,value,force_cpu=False,out=None) - -**fill_constant** - -该功能创建一个张量，具体含有shape,dtype和batch尺寸。并用值中提供的常量初始化该张量。 - -创建张量的属性stop_gradient设为True。 - -参数： - - **shape** (tuple|list|None)-输出张量的维 - - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 - - **value** (float)-用于初始化输出张量的常量值 - - **out** (Variable)-输出张量 - - **force_cpu** (True|False)-若设为true,数据必须在CPU上 - -返回：存储在输出中的张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.fill_constant(shape=[1], value=0, dtype='int64') - - - - - - - - - -.. _cn_api_fluid_layers_fill_constant_batch_size_like: - -fill_constant_batch_size_like -------------------------------- - -.. py:function:: paddle.fluid.layers.fill_constant_batch_size_like(input,shape,dtype,value,input_dim_idx=0,output_dim_idx=0) - -该功能创建一个张量，具体含有shape,dtype和batch尺寸。并用值中提供的常量初始化该张量。该批尺寸从输入张量中获取。它还将stop_gradient设置为True. - -参数： - - **input** (Variable)-张量，其input_dim_idx个维具体指示batch_size - - **shape** (INTS)-输出的维 - - **dtype** (INT)-可以为numpy.dtype。输出数据类型。默认为float32 - - **value** (FLOAT)-默认为0.将要被填充的值 - - **input_dim_idx** (INT)-默认为0.输入批尺寸维的索引 - - **output_dim_idx** (INT)-默认为0.输出批尺寸维的索引 - -返回：具体维的张量填充有具体值 - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.fill_constant_batch_size_like( - input=like, shape=[1], value=0, dtype='int64') - - - - - - - - - - -.. _cn_api_fluid_layers_has_inf: - -has_inf -------------------------------- - -.. py:function:: paddle.fluid.layers.has_inf(x) - -测试x是否包括一个无穷数 - -参数： - - **x(variable)** - 用于被检查的Tensor/LoDTensor - -返回： - tensor变量存储输出值，包含一个bool型数值 - - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_has_nan: - -has_nan -------------------------------- - -.. py:function:: paddle.fluid.layers.has_nan(x) - -测试x是否包含NAN - -参数： - - **x(variable)** - 用于被检查的Tensor/LoDTensor - -返回： - tensor变量存储输出值，包含一个bool型数值 - - - - - - - - - -.. _cn_api_fluid_layers_isfinite: - -isfinite -------------------------------- - -.. py:function:: paddle.fluid.layers.isfinite(x) - -测试x是否包含无穷大/NAN值，如果所有元素都是有穷数，返回Ture,否则返回False - -参数： - - **x(variable)** - 用于被检查的Tensor/LoDTensor - -返回: - Variable: tensor变量存储输出值，包含一个bool型数值 - - - - - - - - - - -.. _cn_api_fluid_layers_ones: - -ones -------------------------------- - -.. py:function:: paddle.fluid.layers.ones(shape,dtype,force_cpu=False) - -**ones** - -该功能创建一个张量，有具体的维度和dtype，初始值为1。 - -也将stop_gradient设置为True。 - -参数： - - **shape** (tuple|list|None)-输出张量的维 - - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 - -返回：存储在输出中的张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.ones(shape=[1], dtype='int64') - - - - - - - - - -.. _cn_api_fluid_layers_reverse: - -reverse -------------------------------- - -.. py:function:: paddle.fluid.layers.reverse(x,axis) - -**reverse** - -该功能将给定轴上的输入‘x’逆序 - -参数： - - **x** (Variable)-预逆序到输入 - - **axis** (int|tuple|list)-其上元素逆序排列的轴。 - -返回：逆序的张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - out = fluid.layers.reverse(x=in, axis=0) - # or: - out = fluid.layers.reverse(x=in, axis=[0,1]) - - - - - - - - - -.. _cn_api_fluid_layers_sums: - -sums -------------------------------- - -.. py:function:: paddle.fluid.layers.sums(input,out=None) - -该函数对输入进行求和，并返回求和结果作为输出。 - -参数： - - **input** (Variable|list)-输入张量，有需要求和的元素 - - **out** (Variable|None)-输出参数。求和结果。默认：None - -返回：输入的求和。和参数'out'等同 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - tmp = fluid.layers.zeros(shape=[10], dtype='int32') - i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) - a0 = layers.array_read(array=tmp, i=i) - i = layers.increment(x=i) - a1 = layers.array_read(array=tmp, i=i) - mean_a0 = layers.mean(a0) - mean_a1 = layers.mean(a1) - a_sum = layers.sums(input=[mean_a0, mean_a1]) - - - - - - - - - -.. _cn_api_fluid_layers_tensor_array_to_tensor: - -tensor_array_to_tensor -------------------------------- - -.. py:function:: paddle.fluid.layers.tensor_array_to_tensor(input, axis=1, name=None) - -此函数在指定轴上连接LodTensorArray中的元素，并将其作为输出返回。 - - -简单示例如下： - -.. code-block:: text - - Given: - input.data = {[[0.6, 0.1, 0.3], - [0.5, 0.3, 0.2]], - [[1.3], - [1.8]], - [[2.3, 2.1], - [2.5, 2.4]]} - - axis = 1 - - Then: - output.data = [[0.6, 0.1, 0.3, 1.3, 2.3, 2.1], - [0.5, 0.3, 0.2, 1.8, 2.5, 2.4]] - output_index.data = [3, 1, 2] - -参数： - - **input** (list) - 输入的LodTensorArray - - **axis** (int) - 整数轴，tensor将会和它连接在一起 - - **name** (str|None) - 该layer的名字，可选。如果设置为none，layer将会被自动命名 - -返回： - Variable: 连接的输出变量,输入LodTensorArray沿指定axis连接。 - -**代码示例：** - -.. code-block:: python - - output, output_index = fluid.layers.tensor_array_to_tensor(input=tensor_array) - - - - - - - - - - - -.. _cn_api_fluid_layers_zeros: - -zeros -------------------------------- - -.. py:function:: paddle.fluid.layers.zeros(shape,dtype,force_cpu=False) - -**zeros** - -该功能创建一个张量，含有具体的维度和dtype，初始值为0. - -也将stop_gradient设置为True。 - -参数： - - **shape** (tuple|list|None)-输出张量的维 - - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 - - **force_cpu** (bool,default False)-是否将输出保留在CPU上 - -返回：存储在输出中的张量 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - data = fluid.layers.zeros(shape=[1], dtype='int64') - - - - - - - - - - - -============ - learning_rate_scheduler -============ - - -.. _cn_api_fluid_layers_append_LARS: - -append_LARS -------------------------------- - -.. py:function:: paddle.fluid.layers.append_LARS(params_grads,learning_rate,weight_decay) - -对每一层的学习率运用LARS(LAYER-WISE ADAPTIVE RATE SCALING) - - - -参数： - - **learning_rate** -变量学习率。LARS的全局学习率。 - - **weight_decay** -Python float类型数 - -返回： 衰减的学习率 - -**代码示例** : - -.. code-block:: python - - learning_rate*=local_gw_ratio * sqrt(sumsq(param)) - / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param))) - - - - - - - -.. _cn_api_fluid_layers_exponential_decay: - -exponential_decay -------------------------------- - -.. py:function:: paddle.fluid.layers exponential_decay(learning_rate,decay_steps,decay_rate,staircase=False) - -在学习率上运用指数衰减。 -训练模型时，在训练过程中通常推荐降低学习率。每次 ``decay_steps`` 步骤中用 ``decay_rate`` 衰减学习率。 - -.. code-block:: text - - if staircase == True: - decayed_learning_rate = learning_rate * decay_rate ^ floor(global_step / decay_steps) - else: - decayed_learning_rate = learning_rate * decay_rate ^ (global_step / decay_steps) - -参数： - - **learning_rate** (Variable|float)-初始学习率 - - **decay_steps** (int)-见以上衰减运算 - - **decay_rate** (float)-衰减率。见以上衰减运算 - - **staircase** (Boolean)-若为True,按离散区间衰减学习率。默认：False - -返回：衰减的学习率 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - base_lr = 0.1 - sgd_optimizer = fluid.optimizer.SGD( - learning_rate=fluid.layers.exponential_decay( - learning_rate=base_lr, - decay_steps=10000, - decay_rate=0.5, - staircase=True)) - sgd_optimizer.minimize(avg_cost) - - - - - - - - - -.. _cn_api_fluid_layers_inverse_time_decay: - -inverse_time_decay -------------------------------- - -.. py:function:: paddle.fluid.layers.inverse_time_decay(learning_rate, decay_steps, decay_rate, staircase=False) - -在初始学习率上运用逆时衰减。 - -训练模型时，在训练过程中通常推荐降低学习率。通过执行该函数，将对初始学习率运用逆向衰减函数。 - -.. code-block:: python - - if staircase == True: - decayed_learning_rate = learning_rate / (1 + decay_rate * floor(global_step / decay_step)) - else: - decayed_learning_rate = learning_rate / (1 + decay_rate * global_step / decay_step) - -参数： - - **learning_rate** (Variable|float)-初始学习率 - - **decay_steps** (int)-见以上衰减运算 - - **decay_rate** (float)-衰减率。见以上衰减运算 - - **staircase** (Boolean)-若为True，按间隔区间衰减学习率。默认：False - - 返回：衰减的学习率 - - 返回类型：变量（Variable） - -**示例代码：** - -.. code-block:: python - - base_lr = 0.1 - sgd_optimizer = fluid.optimizer.SGD( - learning_rate=fluid.layers.inverse_time_decay( - learning_rate=base_lr, - decay_steps=10000, - decay_rate=0.5, - staircase=True)) - sgd_optimizer.minimize(avg_cost) - - - - - - - - - -.. _cn_api_fluid_layers_natural_exp_decay: - -natural_exp_decay -------------------------------- - -.. py:function:: paddle.fluid.layers.natural_exp_decay(learning_rate, decay_steps, decay_rate, staircase=False) - -将自然指数衰减运用到初始学习率上。 - -.. code-block:: python - - if not staircase: - decayed_learning_rate = learning_rate * exp(- decay_rate * (global_step / decay_steps)) - else: - decayed_learning_rate = learning_rate * exp(- decay_rate * (global_step / decay_steps)) - -参数： - - **learning_rate** - 标量float32值或变量。是训练过程中的初始学习率。 - - **decay_steps** - Python int32数 - - **decay_rate** - Python float数 - - **staircase** - Boolean.若设为true，每个decay_steps衰减学习率 - -返回：衰减的学习率 - - - - - - - - - -.. _cn_api_fluid_layers_noam_decay: - -noam_decay -------------------------------- - -.. py:function:: paddle.fluid.layers noam_decay(d_model,warmup_steps) - -Noam衰减方法。noam衰减的numpy实现如下。 - -.. code-block:: python - - import numpy as np - lr_value = np.power(d_model, -0.5) * np.min([ - np.power(current_steps, -0.5), - np.power(warmup_steps, -1.5) * current_steps]) - -请参照 attention is all you need。 - -参数： - - **d_model** (Variable)-模型的输入和输出维度 - - **warmup_steps** (Variable)-超参数 - -返回：衰减的学习率 - - - - - - - - - -.. _cn_api_fluid_layers_piecewise_decay: - -piecewise_decay -------------------------------- - -.. py:function:: paddle.fluid.layers.piecewise_decay(boundaries,values) - -对初始学习率进行分段衰减。 - -该算法可用如下代码描述。 - -.. code-block:: text - - boundaries = [10000, 20000] - values = [1.0, 0.5, 0.1] - if step < 10000: - learning_rate = 1.0 - elif 10000 <= step < 20000: - learning_rate = 0.5 - else: - learning_rate = 0.1 - -参数： - - **boundaries** -一列代表步数的数字 - - **values** -一列学习率的值，从不同的步边界中挑选 - -返回：衰减的学习率 - - - - - - - - - -.. _cn_api_fluid_layers_polynomial_decay: - -polynomial_decay -------------------------------- - -.. py:function:: paddle.fluid.layers.polynomial_decay(learning_rate,decay_steps,end_learning_rate=0.0001,power=1.0,cycle=False) - -对初始学习率使用多项式衰减 - -.. code-block:: text - - if cycle: - decay_steps = decay_steps * ceil(global_step / decay_steps) - else: - global_step = min(global_step, decay_steps) - decayed_learning_rate = (learning_rate - end_learning_rate) * - (1 - global_step / decay_steps) ^ power + end_learning_rate - -参数： - - **learning_rate** (Variable|float32)-标量float32值或变量。是训练过程中的初始学习率。 - - **decay_steps** (int32)-Python int32数 - - **end_learning_rate** (float)-Python float数 - - **power** (float)-Python float数 - - **cycle** (bool)-若设为true，每decay_steps衰减学习率 - -返回：衰减的学习率 - -返回类型：变量（Variable） - - - - - - - - - - - -============ - detection -============ - - -.. _cn_api_fluid_layers_anchor_generator: - -anchor_generator -------------------------------- - -.. py:function:: paddle.fluid.layers.anchor_generator(input, anchor_sizes=None, aspect_ratios=None, variance=[0.1, 0.1, 0.2, 0.2], stride=None, offset=0.5, name=None) - -**Anchor generator operator** - -为快速RCNN算法生成锚，输入的每一位产生N个锚，N=size(anchor_sizes)*size(aspect_ratios)。生成锚的顺序首先是aspect_ratios循环，然后是anchor_sizes循环。 - -参数： - - **input** (Variable) - 输入特征图，格式为NCHW - - **anchor_sizes** (list|tuple|float) - 生成锚的锚大小 - - **in absolute pixels** 等[64.,128.,256.,512.](给定)-实例，锚大小为64意味该锚的面积等于64*2 - - **aspect_ratios** (list|tuple|float) - 生成锚的高宽比，例如[0.5,1.0,2.0] - - **variance** (list|tuple) - 变量，在框回归delta中使用。默认：[0.1,0.1,0.2,0.2] - - **stride** (list|tuple) - 锚在宽度和高度方向上的步长，比如[16.0,16.0] - - **offset** (float) - 先验框的中心位移。默认：0.5 - - **name** (str) - 先验框操作符名称。默认：None - -:: - - - 输出anchor，布局[H,W,num_anchors,4] - H是输入的高度，W是输入的宽度，num_priors是输入每位的框数 - 每个anchor格式（非正式格式）为(xmin,ymin,xmax,ymax) - -:: - - - 变量(Variable):锚的扩展变量 - 布局为[H,W,num_priors,4]。H是输入的高度，W是输入的宽度，num_priors是输入每位的框数 - 每个变量的格式为(xcenter,ycenter)。 - -返回类型：anchor（Variable) - -**代码示例**： - -.. code-block:: python - - anchor, var = anchor_generator( - input=conv1, - anchor_sizes=[64, 128, 256, 512], - aspect_ratios=[0.5, 1.0, 2.0], - variance=[0.1, 0.1, 0.2, 0.2], - stride=[16.0, 16.0], - offset=0.5) - - - - - - - - - -.. _cn_api_fluid_layers_bipartite_match: - -bipartite_match -------------------------------- - -.. py:function:: paddle.fluid.layers.bipartite_match(dist_matrix, match_type=None, dist_threshold=None, name=None) - -该算子实现了贪心二分匹配算法，该算法用于根据输入距离矩阵获得与最大距离的匹配。对于输入二维矩阵，二分匹配算法可以找到每一行的匹配列（匹配意味着最大距离），也可以找到每列的匹配行。此运算符仅计算列到行的匹配索引。对于每个实例，匹配索引的数量是输入距离矩阵的列号。 - -它有两个输出，匹配的索引和距离。简单的描述是该算法将最佳（最大距离）行实体与列实体匹配，并且匹配的索引在ColToRowMatchIndices的每一行中不重复。如果列实体与任何行实体不匹配，则ColToRowMatchIndices设置为-1。 - -注意：输入距离矩阵可以是LoDTensor（带有LoD）或Tensor。如果LoDTensor带有LoD，则ColToRowMatchIndices的高度是批量大小。如果是Tensor，则ColToRowMatchIndices的高度为1。 - -注意：此API是一个非常低级别的API。它由 ``ssd_loss`` 层使用。请考虑使用 ``ssd_loss`` 。 - -参数： - - **dist_matrix** （变量）- 该输入是具有形状[K，M]的2-D LoDTensor。它是由每行和每列来表示实体之间的成对距离矩阵。例如，假设一个实体是具有形状[K]的A，另一个实体是具有形状[M]的B. dist_matrix [i] [j]是A[i]和B[j]之间的距离。距离越大，匹配越好。 - - 注意：此张量可以包含LoD信息以表示一批输入。该批次的一个实例可以包含不同数量的实体。 - - - **match_type** （string | None）- 匹配方法的类型，应为'bipartite'或'per_prediction'。[默认'二分']。 - - **dist_threshold** （float | None）- 如果match_type为'per_prediction'，则此阈值用于根据最大距离确定额外匹配的bbox，默认值为0.5。 - -返回： 返回一个包含两个元素的元组。第一个是匹配的索引（matched_indices），第二个是匹配的距离（matched_distance）。 - - **matched_indices** 是一个2-D Tensor，int类型的形状为[N，M]。 N是批量大小。如果match_indices[i][j]为-1，则表示B[j]与第i个实例中的任何实体都不匹配。否则，这意味着在第i个实例中B[j]与行match_indices[i][j]匹配。第i个实例的行号保存在match_indices[i][j]中。 - - **matched_distance** 是一个2-D Tensor，浮点型的形状为[N，M]。 N是批量大小。如果match_indices[i][j]为-1，则match_distance[i][j]也为-1.0。否则，假设match_distance[i][j]=d，并且每个实例的行偏移称为LoD。然后match_distance[i][j]=dist_matrix[d]+ LoD[i]][j]。 - -返回类型： 元组(tuple) - -**代码示例** - -.. code-block:: python - - x = fluid.layers.data(name='x', shape=[4], dtype='float32') - y = fluid.layers.data(name='y', shape=[4], dtype='float32') - iou = fluid.layers.iou_similarity(x=x, y=y) - matched_indices, matched_dist = fluid.layers.bipartite_match(iou) - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_box_coder: - -box_coder -------------------------------- - -.. py:function:: paddle.fluid.layers.box_coder(prior_box, prior_box_var, target_box, code_type='encode_center_size', box_normalized=True, name=None) - -Bounding Box Coder - -编码/解码带有先验框信息的目标边界框 - -编码规则描述如下： - -.. math:: - - ox &= (tx - px)/pw/pxv - - oy &= (ty - py)/ph/pyv - - ow &= log(abs(tw/pw))/pwv - - oh &= log(abs(th/ph))/phv - -解码规则描述如下： - -.. math:: - - ox &= (pw * pxv * tx * + px ) - tw/2 - - oy &= (ph * pyv * ty * + py ) - th/2 - - ow &= exp(pwv * tw ) * pw + tw/2 - - oh &= exp(phv * th ) * ph + th/2 - -其中tx，ty，tw，th分别表示目标框的中心坐标、宽度和高度。同样地，px，py，pw，ph表示先验框地中心坐标、宽度和高度。pxv，pyv，pwv，phv表示先验框变量，ox，oy，ow，oh表示编码/解码坐标、宽度和高度。 - -参数： - - **prior_box** (Variable) - 张量，默认float类型的张量。先验框是二维张量，维度为[M,4]，存储M个框，每个框代表[xmin，ymin，xmax，ymax]，[xmin，ymin]是先验框的左顶点坐标，如果输入数图像特征图，则接近坐标原点。[xmax,ymax]是先验框的右底点坐标 - - **prior_box_var** (Variable) - 张量，默认float类型的张量。先验框是二维张量，维度为[M,4]，存储M组变量。PriorBoxVar默认将每个元素置为1 - - **target_box** (Variable) - LoDTensor或者Tensor，当code_type为‘encode_center_size’，输入可以是二维LoDTensor，维度为[N,4]。当code_type为‘decode_center_size’输入可以为三维张量，维度为[N,M,4]。每个框代表[xmin,ymin,xmax,ymax]，[xmin,ymin]是先验框的左顶点坐标，如果输入数图像特征图，则接近坐标原点。[xmax,ymax]是先验框的右底点坐标。该张量包含LoD信息，代表一批输入。批的一个实例可以包含不同的实体数。 - - **code_type** (string，默认encode_center_size) - 编码类型用目标框 - - **box_normalized** (boolean，默认true) - 是否将先验框作为正则框 - -返回：（LoDTensor 或者 Tensor） - - - ``code_type`` 为 ``‘encode_center_size’`` 时，形为[N,M,4]的输出张量代表N目标框的结果，目标框用M先验框和变量编码。 - - ``code_type`` 为 ``‘decode_center_size’`` 时，N代表batch大小，M代表解码框数 - -返回类型：output_box（Variable） - - - - - - - - - - - -.. _cn_api_fluid_layers_density_prior_box: - -density_prior_box -------------------------------- - -.. py:function:: paddle.fluid.layers.density_prior_box(input, image, densities=None, fixed_sizes=None, fixed_ratios=None, variance=[0.1, 0.1, 0.2, 0.2], clip=False, steps=[0.0, 0.0], offset=0.5, flatten_to_2d=False, name=None) - - -**Density Prior Box Operator** - -为SSD算法(Single Shot MultiBox Detector)生成density prior box。 -每个input的位置产生N个prior box，其中，N通过densities, fixed_sizes and fixed_ratios -的量来决定。在每个input位置附近的box center格点，通过此op生成。格点坐标由densities决定， -density prior box的量由fixed_sizes and fixed_ratios决定。显然地，fixed_sizes -和densities相等。对于densities中的densities_i： - -.. math:: - - N\_density\_prior\_box =sum(N\_fixed\_ratios * {densities\_i}^2) - - -参数： - - **input** (Variable) - 输入变量，格式为NCHW - - **image** (Variable) - PriorBoxOp的输入图像数据，格式为NCHW - - **densities** (list|tuple|None) - 被生成的density prior boxes的densities，此属性应该是一个整数列表或数组。默认值为None - - **fixed_sizes** (list|tuple|None) - 被生成的density prior boxes的固定大小，此属性应该为和 :attr:`densities` 有同样长度的列表或数组。默认值为None - - **fixed_ratios** (list|tuple|None) - 被生成的density prior boxes的固定长度，如果该属性未被设置，同时 :attr:`densities` 和 :attr:`fix_sizes` 被设置，则 :attr:`aspect_ratios` 被用于生成 density prior boxes - - **variance** (list|tuple) - 将被用于density prior boxes编码的方差，默认值为:[0.1, 0.1, 0.2, 0.2] - - **clip(bool)** - 是否clip超出范围的box。默认值：False - - **step** (list|turple) - Prior boxes在宽度和高度的步长，如果step[0] == 0.0/step[1] == 0.0, input的the density prior boxes的高度/宽度的步长将被自动计算。默认值：Default: [0., 0.] - - **offset** (float) - Prior boxes中心补偿值，默认为：0.5 - - **flatten_to_2d** (bool) - 是否将output prior boxes和方差 ``flatten`` 至2维形状，第二个dim为4。默认值：False - - **name(str)** - density prior box op的名字，默认值: None - -返回： - tuple: 有两个变量的数组 (boxes, variances) - - boxes: PriorBox的输出density prior boxes - - 当flatten_to_2d为False时，形式为[H, W, num_priors, 4] - - 当flatten_to_2d为True时，形式为[H * W * num_priors, 4] - - H是输入的高度，W是输入的宽度 - - num_priors是输入中每个位置的总box count - - variances: PriorBox的expanded variance - - 当flatten_to_2d为False时，形式为[H, W, num_priors, 4] - - 当flatten_to_2d为True时，形式为[H * W * num_priors, 4] - - H是输入的高度，W是输入的宽度 - - num_priors是输入中每个位置的总box count - -**代码示例**: - -.. code-block:: python - - box, var = fluid.layers.density_prior_box( - input=conv1, - image=images, - densities=[4, 2, 1], - fixed_sizes=[32.0, 64.0, 128.0], - fixed_ratios=[1.], - clip=True, - flatten_to_2d=True) - - - - - - - - - - - -.. _cn_api_fluid_layers_detection_map: - -detection_map -------------------------------- - -.. py:function:: paddle.fluid.layers.detection_map(detect_res, label, function_num, background_label=0, overlap_threshold=0.3, evaluate_difficult=True, has_state=None, input_states=None, out_states=None, ap_version='integral') - -检测mAP评估运算符。一般步骤如下：首先，根据检测输入和标签计算TP（true positive）和FP（false positive），然后计算mAP评估值。支持'11 point'和积分mAP算法。请从以下文章中获取更多信息： - - https://sanchom.wordpress.com/tag/average-precision/ - - https://arxiv.org/abs/1512.02325 - -参数： - - **detect_res** （LoDTensor）- 用具有形状[M，6]的2-D LoDTensor来表示检测。每行有6个值：[label，confidence，xmin，ymin，xmax，ymax]，M是此小批量中检测结果的总数。对于每个实例，第一维中的偏移称为LoD，偏移量为N+1，如果LoD[i+1]-LoD[i]== 0，则表示没有检测到数据。 - - **label** （LoDTensor）- 2-D LoDTensor用来带有标签的真实数据。每行有6个值：[label，xmin，ymin，xmax，ymax，is_difficult]或5个值：[label，xmin，ymin，xmax，ymax]，其中N是此小批量中真实数据的总数。对于每个实例，第一维中的偏移称为LoD，偏移量为N + 1，如果LoD [i + 1] - LoD [i] == 0，则表示没有真实数据。 - - **class_num** （int）- 类的数目。 - - **background_label** （int，defalut：0）- background标签的索引，background标签将被忽略。如果设置为-1，则将考虑所有类别。 - - **overlap_threshold** （float）- 检测输出和真实数据下限的重叠阈值。 - - **evaluate_difficult** （bool，默认为true）- 通过切换来控制是否对difficult-data进行评估。 - - **has_state** （Tensor ）- 是shape[1]的张量，0表示忽略输入状态，包括PosCount，TruePos，FalsePos。 - - **input_states** - 如果不是None，它包含3个元素： - - 1、pos_count（Tensor）是一个shape为[Ncls，1]的张量，存储每类的输入正例的数量，Ncls是输入分类的数量。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。当输入（PosCount）为空时，不执行累积计算，仅计算当前小批量的结果。 - - 2、true_pos（LoDTensor）是一个shape为[Ntp，2]的2-D LoDTensor，存储每个类输入的正实例。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。 - - 3、false_pos（LoDTensor）是一个shape为[Nfp，2]的2-D LoDTensor，存储每个类输入的负实例。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。 - - - **out_states** - 如果不是None，它包含3个元素： - - 1、accum_pos_count（Tensor）是一个shape为[Ncls，1]的Tensor，存储每个类的实例数。它结合了输入（PosCount）和从输入中的（Detection）和（label）计算的正例数。 - - 2、accum_true_pos（LoDTensor）是一个shape为[Ntp'，2]的LoDTensor，存储每个类的正实例。它结合了输入（TruePos）和从输入中（Detection）和（label）计算的正实例数。 。 - - 3、accum_false_pos（LoDTensor）是一个shape为[Nfp'，2]的LoDTensor，存储每个类的负实例。它结合了输入（FalsePos）和从输入中（Detection）和（label）计算的负实例数。 - - - **ap_version** （string，默认'integral'）- AP算法类型，'integral'或'11 point'。 - -返回： 具有形状[1]的（Tensor），存储mAP的检测评估结果。 - -**代码示例** - -.. code-block:: python - - detect_res = fluid.layers.data( - name='detect_res', - shape=[10, 6], - append_batch_size=False, - dtype='float32') - label = fluid.layers.data( - name='label', - shape=[10, 6], - append_batch_size=False, - dtype='float32') - map_out = fluid.layers.detection_map(detect_res, label, 21) - - - - - - - - - - - -.. _cn_api_fluid_layers_detection_output: - -detection_output -------------------------------- - -.. py:function:: paddle.fluid.layers.detection_output(loc, scores, prior_box, prior_box_var, background_label=0, nms_threshold=0.3, nms_top_k=400, keep_top_k=200, score_threshold=0.01, nms_eta=1.0) - -Detection Output Layer for Single Shot Multibox Detector(SSD) - -该操作符用于获得检测结果，执行步骤如下： - - 1.根据先验框解码输入边界框（bounding box）预测 - - 2.通过运用多类非最大压缩(NMS)获得最终检测结果 - -请注意，该操作符不将最终输出边界框剪切至图像窗口。 - -参数： - - **loc** (Variable) - 一个三维张量（Tensor），维度为[N,M,4]，代表M个bounding bboxes的预测位置。N是批尺寸，每个边界框（boungding box）有四个坐标值，布局为[xmin,ymin,xmax,ymax] - - **scores** (Variable) - 一个三维张量（Tensor），维度为[N,M,C]，代表预测置信预测。N是批尺寸，C是类别数，M是边界框数。对每类一共M个分数，对应M个边界框 - - **prior_box** (Variable) - 一个二维张量（Tensor),维度为[M,4]，存储M个框，每个框代表[xmin,ymin,xmax,ymax]，[xmin,ymin]是anchor box的左上坐标，如果输入是图像特征图，靠近坐标系统的原点。[xmax,ymax]是anchor box的右下坐标 - - **prior_box_var** (Variable) - 一个二维张量（Tensor），维度为[M,4]，存有M变量群 - - **background_label** (float) - 背景标签索引，背景标签将会忽略。若设为-1，将考虑所有类别 - - **nms_threshold** (int) - 用于NMS的临界值（threshold） - - **nms_top_k** (int) - 基于score_threshold过滤检测后，根据置信数维持的最大检测数 - - **keep_top_k** (int) - NMS步后，每一图像要维持的总bbox数 - - **score_threshold** (float) - 临界函数（Threshold），用来过滤带有低置信数的边界框（bounding box）。若未提供，则考虑所有框 - - **nms_eta** (float) - 适应NMS的参数 - -返回： - 检测输出一个LoDTensor，维度为[No,6]。每行有6个值：[label,confidence,xmin,ymin,xmax,ymax]。No是该mini-batch的总检测数。对每个实例，第一维偏移称为LoD，偏移数为N+1，N是批尺寸。第i个图像有LoD[i+1]-LoD[i]检测结果。如果为0，第i个图像无检测结果。如果所有图像都没有检测结果，LoD所有元素都为0，并且输出张量只包含一个值-1。 - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - pb = layers.data(name='prior_box', shape=[10, 4], - append_batch_size=False, dtype='float32') - pbv = layers.data(name='prior_box_var', shape=[10, 4], - append_batch_size=False, dtype='float32') - loc = layers.data(name='target_box', shape=[2, 21, 4], - append_batch_size=False, dtype='float32') - scores = layers.data(name='scores', shape=[2, 21, 10], - append_batch_size=False, dtype='float32') - nmsed_outs = fluid.layers.detection_output(scores=scores, - loc=loc, - prior_box=pb, - prior_box_var=pbv) - - - - - - - - - - - -.. _cn_api_fluid_layers_generate_proposal_labels: - -generate_proposal_labels -------------------------------- - -.. py:function:: paddle.fluid.layers.generate_proposal_labels(rpn_rois, gt_functiones, is_crowd, gt_boxes, im_info, batch_size_per_im=256, fg_fraction=0.25, fg_thresh=0.25, bg_thresh_hi=0.5, bg_thresh_lo=0.0, bbox_reg_weights=[0.1, 0.1, 0.2, 0.2], function_nums=None, use_random=True) - -**该函数可以应用于 Faster-RCNN 网络，生成建议标签。** - -该函数可以根据 ``GenerateProposals`` 的输出结果，即bounding boxes（区域框），groundtruth（正确标记数据）来对foreground boxes和background boxes进行采样，并计算loss值。 - -RpnRois 是RPN的输出box， 并由 ``GenerateProposals`` 来进一步处理, 这些box将与groundtruth boxes合并， 并根据 ``batch_size_per_im`` 和 ``fg_fraction`` 进行采样。 - -如果一个实例具有大于 ``fg_thresh`` (前景重叠阀值)的正确标记重叠，那么它会被认定为一个前景样本。 -如果一个实例具有的正确标记重叠大于 ``bg_thresh_lo`` 且小于 ``bg_thresh_hi`` (详见参数说明)，那么它将被认定为一个背景样本。 -在所有前景、背景框（即Rois regions of interest 直译：有意义的区域）被选择后，我们接着采用随机采样的方法来确保前景框数量不多于 batch_size_per_im * fg_fraction 。 - -对Rois中的每个box, 我们给它分配类标签和回归目标(box label)。最后 ``bboxInsideWeights`` 和 ``BboxOutsideWeights`` 用来指明是否它将影响训练loss值。 - -参数: - - **rpn_rois** (Variable) – 形为[N, 4]的二维LoDTensor。 N 为 ``GenerateProposals`` 的输出结果, 其中各元素为 :math:`[x_{min}, y_{min}, x_{max}, y_{max}]` 格式的边界框 - - **gt_classes** (Variable) – 形为[M, 1]的二维LoDTensor。 M 为正确标记数据数目, 其中各元素为正确标记数据的类别标签 - - **is_crowd** (Variable) – 形为[M, 1]的二维LoDTensor。M 为正确标记数据数目, 其中各元素为一个标志位，表明一个正确标记数据是不是crowd - - **gt_boxes** (Variable) – 形为[M, 4]的二维LoDTensor。M 为正确标记数据数目, 其中各元素为 :math:`[x_{min}, y_{min}, x_{max}, y_{max}]` 格式的边界框 - - **im_info** (Variable) – 形为[B, 3]的二维LoDTensor。B 为输入图片的数目, 各元素由 im_height, im_width, im_scale 组成. - - **batch_size_per_im** (int) – 每张图片的Rois batch数目 - - **fg_fraction** (float) – Foreground前景在 ``batch_size_per_im`` 中所占比例 - - **fg_thresh** (float) – 前景重叠阀值，用于选择foreground前景样本 - - **bg_thresh_hi** (float) – 背景重叠阀值的上界，用于筛选背景样本 - - **bg_thresh_lo** (float) – 背景重叠阀值的下界，用于筛选背景样本O - - **bbox_reg_weights** (list|tuple) – Box 回归权重 - - **class_nums** (int) – 种类数目 - - **use_random** (bool) – 是否使用随机采样来选择foreground（前景）和background（背景） boxes（框） - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_generate_proposals: - -generate_proposals -------------------------------- - -.. py:function:: paddle.fluid.layers.generate_proposals(scores, bbox_deltas, im_info, anchors, variances, pre_nms_top_n=6000, post_nms_top_n=1000, nms_thresh=0.5, min_size=0.1, eta=1.0, name=None) - -生成proposal的Faster-RCNN - -该操作根据每个框为foreground（前景）对象的概率，并且通过锚（anchors）来计算这些框，进而提出RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。 - -为了生成 ``proposals`` ，此操作执行以下步骤： - - 1、转置和调整bbox_deltas的分数和大小为（H * W * A，1）和（H * W * A，4）。 - - 2、计算方框位置作为 ``proposals`` 候选框。 - - 3、剪辑框图像。 - - 4、删除小面积的预测框。 - - 5、应用NMS以获得最终 ``proposals`` 作为输出。 - -参数： - - **scores** (Variable)- 是一个shape为[N，A，H，W]的4-D张量，表示每个框成为object的概率。N是批量大小，A是anchor数，H和W是feature map的高度和宽度。 - - **bbox_deltas** （Variable）- 是一个shape为[N，4 * A，H，W]的4-D张量，表示预测框位置和anchor位置之间的差异。 - - **im_info** （Variable）- 是一个shape为[N，3]的2-D张量，表示N个批次原始图像的信息。信息包含原始图像大小和 ``feature map`` 的大小之间高度，宽度和比例。 - - **anchors** （Variable）- 是一个shape为[H，W，A，4]的4-D Tensor。H和W是 ``feature map`` 的高度和宽度， - - **num_anchors** - 是每个位置的框的数量。每个anchor都是以非标准化格式（xmin，ymin，xmax，ymax）定义的。 - - **variances** （Variable）- anchor的方差，shape为[H，W，num_priors，4]。每个方差都是（xcenter，ycenter，w，h）这样的格式。 - - **pre_nms_top_n** （float）- 每个图在NMS之前要保留的总框数。默认为6000。 - - **post_nms_top_n** （float）- 每个图在NMS后要保留的总框数。默认为1000。 - - **nms_thresh** （float）- NMS中的阈值，默认为0.5。 - - **min_size** （float）- 删除高度或宽度小于min_size的预测框。默认为0.1。 - - **eta** （float）- 在自适应NMS中应用，如果自适应阈值> 0.5，则在每次迭代中使用adaptive_threshold = adaptive_treshold * eta。 - - - - - - - - - - - -.. _cn_api_fluid_layers_iou_similarity: - -iou_similarity -------------------------------- - -.. py:function:: paddle.fluid.layers.iou_similarity(x, y, name=None) - -**IOU Similarity Operator** - -计算两个框列表的intersection-over-union(IOU)。框列表‘X’应为LoDTensor，‘Y’是普通张量，X成批输入的所有实例共享‘Y’中的框。给定框A和框B，IOU的运算如下： - -.. math:: - IOU(A, B) = \frac{area(A\cap B)}{area(A)+area(B)-area(A\cap B)} - -参数： - - **x** (Variable,默认LoDTensor,float类型) - 框列表X是二维LoDTensor，shape为[N,4],存有N个框，每个框代表[xmin,ymin,xmax,ymax],X的shape为[N,4]。如果输入是图像特征图,[xmin,ymin]市框的左上角坐标，接近坐标轴的原点。[xmax,ymax]是框的右下角坐标。张量可以包含代表一批输入的LoD信息。该批的一个实例能容纳不同的项数 - - **y** (Variable,张量，默认float类型的张量) - 框列表Y存有M个框，每个框代表[xmin,ymin,xmax,ymax],X的shape为[N,4]。如果输入是图像特征图,[xmin,ymin]市框的左上角坐标，接近坐标轴的原点。[xmax,ymax]是框的右下角坐标。张量可以包含代表一批输入的LoD信息。 - -返回：iou_similarity操作符的输出，shape为[N,M]的张量，代表一对iou分数 - -返回类型：out(Variable) - - - - - - - - - -.. _cn_api_fluid_layers_multi_box_head: - -multi_box_head -------------------------------- - -.. py:function:: paddle.fluid.layers.multi_box_head(inputs, image, base_size, num_functiones, aspect_ratios, min_ratio=None, max_ratio=None, min_sizes=None, max_sizes=None, steps=None, step_w=None, step_h=None, offset=0.5, variance=[0.1, 0.1, 0.2, 0.2], flip=True, clip=False, kernel_size=1, pad=0, stride=1, name=None, min_max_aspect_ratios_order=False) - -生成SSD（Single Shot MultiBox Detector）算法的候选框。有关此算法的详细信息，请参阅SSD论文 `SSD：Single Shot MultiBox Detector `_ 的2.2节。 - -参数： - - **inputs** （list | tuple）- 输入变量列表，所有变量的格式为NCHW。 - - **image** （Variable）- PriorBoxOp的输入图像数据，布局为NCHW。 - - **base_size** （int）- base_size用于根据 ``min_ratio`` 和 ``max_ratio`` 来获取 ``min_size`` 和 ``max_size`` 。 - - **num_classes** （int）- 类的数量。 - - **aspect_ratios** （list | tuple）- 生成候选框的宽高比。 ``input`` 和 ``aspect_ratios`` 的长度必须相等。 - - **min_ratio** （int）- 生成候选框的最小比率。 - - **max_ratio** （int）- 生成候选框的最大比率。 - - **min_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``min_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 - - **max_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``max_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 - - **steps** （list | tuple）- 如果step_w和step_h相同，则step_w和step_h可以被steps替换。 - - **step_w** （list | tuple）- 候选框跨越宽度。如果step_w [i] == 0.0，将自动计算输跨越入[i]宽度。默认值：无。 - - **step_h** （list | tuple）- 候选框跨越高度，如果step_h [i] == 0.0，将自动计算跨越输入[i]高度。默认值：无。 - - **offset** （float）- 候选框中心偏移。默认值：0.5 - - **variance** （list | tuple）- 在候选框编码的方差。默认值：[0.1,0.1,0.2,0.2]。 - - **flip** （bool）- 是否翻转宽高比。默认值：false。 - - **clip** （bool）- 是否剪切超出边界的框。默认值：False。 - - **kernel_size** （int）- conv2d的内核大小。默认值：1。 - - **pad** （int | list | tuple）- conv2d的填充。默认值：0。 - - **stride** （int | list | tuple）- conv2d的步长。默认值：1， - - **name** （str）- 候选框的名称。默认值：无。 - - **min_max_aspect_ratios_order** （bool）- 如果设置为True，则输出候选框的顺序为[min，max，aspect_ratios]，这与Caffe一致。请注意，此顺序会影响卷积层后面的权重顺序，但不会影响最终检测结果。默认值：False。 - -返回：一个带有四个变量的元组，（mbox_loc，mbox_conf，boxes, variances）: - - - **mbox_loc** ：预测框的输入位置。布局为[N，H * W * Priors，4]。其中 ``Priors`` 是每个输位置的预测框数。 - - - **mbox_conf** ：预测框对输入的置信度。布局为[N，H * W * Priors，C]。其中 ``Priors`` 是每个输入位置的预测框数，C是类的数量。 - - - **boxes** ： ``PriorBox`` 的输出候选框。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总盒数。 - - - **variances** ： ``PriorBox`` 的方差。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总窗口数。 - -返回类型：元组（tuple） - -**代码示例** - -.. code-block:: python - - mbox_locs, mbox_confs, box, var = fluid.layers.multi_box_head( - inputs=[conv1, conv2, conv3, conv4, conv5, conv5], - image=images, - num_classes=21, - min_ratio=20, - max_ratio=90, - aspect_ratios=[[2.], [2., 3.], [2., 3.], [2., 3.], [2.], [2.]], - base_size=300, - offset=0.5, - flip=True, - clip=True) - - - - - - - - - - -.. _cn_api_fluid_layers_polygon_box_transform: - -polygon_box_transform -------------------------------- - -.. py:function:: paddle.fluid.layers.polygon_box_transform(input, name=None) - -PolygonBoxTransform 算子。 - -该算子用于将偏移坐标转变为真正的坐标。 - -输入是检测网络的最终几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数字 :math:`(x_i, y_i)` ，所以何输出包含 2*n 个通道。 - -参数： - - **input** （Variable） - shape 为[batch_size，geometry_channels，height，width]的张量 - -返回：与输入 shpae 相同 - -返回类型：output（Variable） - - - - - - - - - - - -.. _cn_api_fluid_layers_prior_box: - -prior_box -------------------------------- -.. py:function:: paddle.fluid.layers.prior_box(input,image,min_sizes=None,aspect_ratios=[1.0],variance=[0.1,0.1,0.2,0.2],flip=False,clip=False,steps=[0.0,0.0],offset=0.5,name=None,min_max_aspect_ratios_order=False) - -**Prior Box Operator** - -为SSD(Single Shot MultiBox Detector)算法生成先验框。输入的每个位产生N个先验框，N由min_sizes,max_sizes和aspect_ratios的数目决定，先验框的尺寸在(min_size,max_size)之间，该尺寸根据aspect_ratios在序列中生成。 - -参数： - - **input** (Variable)-输入变量，格式为NCHW - - **image** (Variable)-PriorBoxOp的输入图像数据，布局为NCHW - - **min_sizes** (list|tuple|float值)-生成的先验框的最小尺寸 - - **max_sizes** (list|tuple|None)-生成的先验框的最大尺寸。默认：None - - **aspect_ratios** (list|tuple|float值)-生成的先验框的纵横比。默认：[1.] - - **variance** (list|tuple)-先验框中的变量，会被解码。默认：[0.1,0.1,0.2,0.2] - - **flip** (bool)-是否忽略纵横比。默认：False。 - - **clip** (bool)-是否修建溢界框。默认：False。 - - **step** (list|tuple)-先验框在width和height上的步长。如果step[0] == 0.0/step[1] == 0.0，则自动计算先验框在宽度和高度上的步长。默认：[0.,0.] - - **offset** (float)-先验框中心位移。默认：0.5 - - **name** (str)-先验框操作符名称。默认：None - - **min_max_aspect_ratios_order** (bool)-若设为True,先验框的输出以[min,max,aspect_ratios]的顺序，和Caffe保持一致。请注意，该顺序会影响后面卷基层的权重顺序，但不影响最后的检测结果。默认：False。 - -返回： - 含有两个变量的元组(boxes,variances) - boxes:PriorBox的输出先验框。布局是[H,W,num_priors,4]。H是输入的高度，W是输入的宽度，num_priors是输入每位的总框数 - variances:PriorBox的扩展变量。布局上[H,W,num_priors,4]。H是输入的高度，W是输入的宽度，num_priors是输入每位的总框数 - -返回类型：元组 - -**代码示例**： - -.. code-block:: python - - box, var = fluid.layers.prior_box( - input=conv1, - image=images, - min_sizes=[100.], - flip=True, - clip=True) - - - - - - - - - - - -.. _cn_api_fluid_layers_roi_perspective_transform: - -roi_perspective_transform -------------------------------- - -.. py:function:: paddle.fluid.layers.roi_perspective_transform(input, rois, transformed_height, transformed_width, spatial_scale=1.0) - -**ROI perspective transform操作符** - -参数： - - **input** (Variable) - ROI Perspective TransformOp的输入。输入张量的形式为NCHW。N是批尺寸，C是输入通道数，H是特征高度，W是特征宽度 - - **rois** (Variable) - 用来处理的ROIs，应该是shape的二维LoDTensor(num_rois,8)。给定[[x1,y1,x2,y2,x3,y3,x4,y4],...],(x1,y1)是左上角坐标，(x2,y2)是右上角坐标，(x3,y3)是右下角坐标，(x4,y4)是左下角坐标 - - **transformed_height** - 输出的宽度 - - **spatial_scale** (float) - 空间尺度因子，用于缩放ROI坐标，默认：1.0。 - -返回： - ``ROIPerspectiveTransformOp`` 的输出，带有shape的四维张量(num_rois,channels,transformed_h,transformed_w) - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - out = fluid.layers.roi_perspective_transform(input, rois, 7, 7, 1.0) - - - - - - - - - - - - - - - - - -.. _cn_api_fluid_layers_rpn_target_assign: - -rpn_target_assign -------------------------------- - -.. py:function:: paddle.fluid.layers.rpn_target_assign(bbox_pred, cls_logits, anchor_box, anchor_var, gt_boxes, is_crowd, im_info, rpn_batch_size_per_im=256, rpn_straddle_thresh=0.0, rpn_fg_fraction=0.5, rpn_positive_overlap=0.7, rpn_negative_overlap=0.3, use_random=True) - -在Faster-RCNN检测中为区域检测网络（RPN）分配目标层。 - -对于给定anchors和真实框之间的IoU重叠，该层可以为每个anchors做分类和回归，这些target labels用于训练RPN。classification targets是二进制的类标签（是或不是对象）。根据Faster-RCNN的论文，positive labels有两种anchors： - -(i) anchor/anchors与真实框具有最高IoU重叠； - -(ii) 具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。 - -请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。 - -参数： - - **bbox_pred** （Variable）- 是一个shape为[N，M，4]的3-D Tensor，表示M个边界框的预测位置。N是批量大小，每个边界框有四个坐标值，即[xmin，ymin，xmax，ymax]。 - - **cls_logits** （Variable）- 是一个shape为[N，M，1]的3-D Tensor，表示预测的置信度。N是批量大小，1是frontground和background的sigmoid，M是边界框的数量。 - - **anchor_box** （Variable）- 是一个shape为[M，4]的2-D Tensor，它拥有M个框，每个框可表示为[xmin，ymin，xmax，ymax]，[xmin，ymin]是anchor框的左上部坐标，如果输入是图像特征图，则它们接近坐标系的原点。 [xmax，ymax]是anchor框的右下部坐标。 - - **anchor_var** （Variable）- 是一个shape为[M，4]的2-D Tensor，它拥有anchor的expand方差。 - - **gt_boxes** （Variable）- 真实边界框是一个shape为[Ng，4]的2D LoDTensor，Ng是小批量输入的真实框（bbox）总数。 - - **is_crowd** （Variable）- 1-D LoDTensor，表示（groud-truth）是密集的。 - - **im_info** （Variable）- 是一个形为[N，3]的2-D LoDTensor。N是batch大小，第二维上的3维分别代表高度，宽度和规模(scale) - - **rpn_batch_size_per_im** （int）- 每个图像中RPN示例总数。 - - **rpn_straddle_thresh** （float）- 通过straddle_thresh像素删除出现在图像外部的RPN anchor。 - - **rpn_fg_fraction** （float）- 为foreground（即class> 0）RoI小批量而标记的目标分数，第0类是background。 - - **rpn_positive_overlap** （float）- 对于一个正例的（anchor, gt box）对，是允许anchors和所有真实框之间最小重叠的。 - - **rpn_negative_overlap** （float）- 对于一个反例的（anchor, gt box）对，是允许anchors和所有真实框之间最大重叠的。 - -返回: - -返回元组 (predicted_scores, predicted_location, target_label, target_bbox, bbox_inside_weight) : - - **predicted_scores** 和 **predicted_location** 是RPN的预测结果。 **target_label** 和 **target_bbox** 分别是真实准确数据(ground-truth)。 - - **predicted_location** 是一个形为[F，4]的2D Tensor， **target_bbox** 的形与 **predicted_location** 相同，F是foreground anchors的数量。 - - **predicted_scores** 是一个shape为[F + B，1]的2D Tensor， **target_label** 的形与 **predict_scores** 的形相同，B是background anchors的数量，F和B取决于此算子的输入。 - - **Bbox_inside_weight** 标志着predicted_loction是否为fake_fg（假前景），其形为[F,4]。 - -返回类型： 元组(tuple) - - -**代码示例** - -.. code-block:: python - - bbox_pred = layers.data(name=’bbox_pred’, shape=[100, 4], - append_batch_size=False, dtype=’float32’) - cls_logits = layers.data(name=’cls_logits’, shape=[100, 1], - append_batch_size=False, dtype=’float32’) - anchor_box = layers.data(name=’anchor_box’, shape=[20, 4], - append_batch_size=False, dtype=’float32’) - gt_boxes = layers.data(name=’gt_boxes’, shape=[10, 4], - append_batch_size=False, dtype=’float32’) - loc_pred, score_pred, loc_target, score_target, bbox_inside_weight= - fluid.layers.rpn_target_assign(bbox_pred=bbox_pred, - cls_logits=cls_logits, anchor_box=anchor_box, gt_boxes=gt_boxes) - - - - - - - - - - - -.. _cn_api_fluid_layers_ssd_loss: - -ssd_loss -------------------------------- - -.. py:function:: paddle.fluid.layers.ssd_loss(location, confidence, gt_box, gt_label, prior_box, prior_box_var=None, background_label=0, overlap_threshold=0.5, neg_pos_ratio=3.0, neg_overlap=0.5, loc_loss_weight=1.0, conf_loss_weight=1.0, match_type='per_prediction', mining_type='max_negative', normalize=True, sample_size=None) - -用于SSD的对象检测算法的多窗口损失层 - -该层用于计算SSD的损失，给定位置偏移预测，置信度预测，候选框和真实框标签，以及实例挖掘的类型。通过执行以下步骤，返回的损失是本地化损失（或回归损失）和置信度损失（或分类损失）的加权和： - -1、通过二分匹配算法查找匹配的边界框。 - - 1.1、计算真实框与先验框之间的IOU相似度。 - - 1.2、通过二分匹配算法计算匹配的边界框。 - -2、计算难分样本的置信度 - - 2.1、根据匹配的索引获取目标标签。 - - 2.2、计算置信度损失。 - -3、应用实例挖掘来获取负示例索引并更新匹配的索引。 - -4、分配分类和回归目标 - - 4.1、根据前面的框编码bbox。 - - 4.2、分配回归目标。 - - 4.3、分配分类目标。 - -5、计算总体客观损失。 - - 5.1计算置信度损失。 - - 5.1计算本地化损失。 - - 5.3计算总体加权损失。 - -参数： - - **location** （Variable）- 位置预测是具有形状[N，Np，4]的3D张量，N是批量大小，Np是每个实例的预测总数。 4是坐标值的数量，布局是[xmin，ymin，xmax，ymax]。 - - **confidence** (Variable) - 置信度预测是具有形状[N，Np，C]，N和Np的3D张量，它们与位置相同，C是类号。 - - **gt_box** （Variable）- 真实框（bbox）是具有形状[Ng，4]的2D LoDTensor，Ng是小批量输入的真实框（bbox）的总数。 - - **gt_label** （Variable）- ground-truth标签是具有形状[Ng，1]的2D LoDTensor。 - - **prior_box** （Variable）- 候选框是具有形状[Np，4]的2D张量。 - - **prior_box_var** （Variable）- 候选框的方差是具有形状[Np，4]的2D张量。 - - **background_label** （int）- background标签的索引，默认为0。 - - **overlap_threshold** （float）- 当找到匹配的盒子，如果 ``match_type`` 为'per_prediction'，请使用 ``overlap_threshold`` 确定额外匹配的bbox。默认为0.5。 - - **neg_pos_ratio** （float）- 负框与正框的比率，仅在 ``mining_type`` 为'max_negative'时使用，3.0由defalut使用。 - - **neg_overlap** （float）- 不匹配预测的负重叠上限。仅当mining_type为'max_negative'时使用，默认为0.5。 - - **loc_loss_weight** （float）- 本地化丢失的权重，默认为1.0。 - - **conf_loss_weight** （float）- 置信度损失的权重，默认为1.0。 - - **match_type** （str）- 训练期间匹配方法的类型应为'bipartite'或'per_prediction'，'per_prediction'由defalut提供。 - - **mining_type** （str）- 硬示例挖掘类型应该是'hard_example'或'max_negative'，现在只支持max_negative。 - - **normalize** （bool）- 是否通过输出位置的总数将SSD丢失标准化，默认为True。 - - **sample_size** （int）- 负框的最大样本大小，仅在 ``mining_type`` 为'hard_example'时使用。 - -返回： 具有形状[N * Np，1]，N和Np的定位损失和置信度损失的加权和与它们在位置上的相同。 - -抛出异常： ``ValueError`` - 如果 ``mining_type`` 是'hard_example'，现在只支持 ``max_negative`` 的挖掘类型。 - -**代码示例** - -.. code-block:: python - - pb = fluid.layers.data( - name='prior_box', - shape=[10, 4], - append_batch_size=False, - dtype='float32') - pbv = fluid.layers.data( - name='prior_box_var', - shape=[10, 4], - append_batch_size=False, - dtype='float32') - loc = fluid.layers.data(name='target_box', shape=[10, 4], dtype='float32') - scores = fluid.layers.data(name='scores', shape=[10, 21], dtype='float32') - gt_box = fluid.layers.data( - name='gt_box', shape=[4], lod_level=1, dtype='float32') - gt_label = fluid.layers.data( - name='gt_label', shape=[1], lod_level=1, dtype='float32') - loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv) - - - - - - - - - - -.. _cn_api_fluid_layers_target_assign: - -target_assign -------------------------------- - -.. py:function:: paddle.fluid.layers.target_assign(input, matched_indices, negative_indices=None, mismatch_value=None, name=None) - -对于给定的目标边界框（bounding box）和标签（label），该操作符对每个预测赋予分类和逻辑回归目标函数以及预测权重。权重具体表示哪个预测无需贡献训练误差。 - -对于每个实例，根据 ``match_indices`` 和 ``negative_indices`` 赋予输入 ``out`` 和 ``out_weight``。将定输入中每个实例的行偏移称为lod，该操作符执行分类或回归目标函数，执行步骤如下： - -1.根据match_indices分配所有输入 - -.. code-block:: text - - If id = match_indices[i][j] > 0, - - out[i][j][0 : K] = X[lod[i] + id][j % P][0 : K] - out_weight[i][j] = 1. - - Otherwise, - - out[j][j][0 : K] = {mismatch_value, mismatch_value, ...} - out_weight[i][j] = 0. - -2.如果提供neg_indices，根据neg_indices分配out_weight： - -假设neg_indices中每个实例的行偏移称为neg_lod，该实例中第i个实例和neg_indices的每个id如下： - -.. code-block:: text - - out[i][id][0 : K] = {mismatch_value, mismatch_value, ...} - out_weight[i][id] = 1.0 - -参数： - - **inputs** (Variable) - 输入为三维LoDTensor，维度为[M,P,K] - - **matched_indices** (Variable) - 张量（Tensor），整型，输入匹配索引为二维张量（Tensor），类型为整型32位，维度为[N,P]，如果MatchIndices[i][j]为-1，在第i个实例中第j列项不匹配任何行项。 - - **negative_indices** (Variable) - 输入负例索引，可选输入，维度为[Neg,1]，类型为整型32，Neg为负例索引的总数 - - **mismatch_value** (float32) - 为未匹配的位置填充值 - -返回：返回一个元组（out,out_weight）。out是三维张量，维度为[N,P,K],N和P与neg_indices中的N和P一致，K和输入X中的K一致。如果match_indices[i][j]存在，out_weight是输出权重，维度为[N,P,1]。 - -返回类型：元组（tuple） - -**代码示例**： - -.. code-block:: python - - matched_indices, matched_dist = fluid.layers.bipartite_match(iou) - gt = layers.data( - name='gt', shape=[1, 1], dtype='int32', lod_level=1) - trg, trg_weight = layers.target_assign( - gt, matched_indices, mismatch_value=0) - - - - - - - - - - - -============ - metric_op -============ - - -.. _cn_api_fluid_layers_accuracy: - -accuracy -------------------------------- - -.. py:function:: paddle.fluid.layers.accuracy(input, label, k=1, correct=None, total=None) - -accuracy layer。 参考 https://en.wikipedia.org/wiki/Precision_and_recall - -使用输入和标签计算准确率。 每个类别中top k 中正确预测的个数。注意：准确率的 dtype 由输入决定。 输入和标签 dtype 可以不同。 - -参数： - - **input** (Variable)-该层的输入，即网络的预测。支持 Carry LoD。 - - **label** (Variable)-数据集的标签。 - - **k** (int) - 每个类别的 top k - - **correct** (Variable)-正确的预测个数。 - - **total** (Variable)-总共的样本数。 - -返回: 正确率 - -返回类型: 变量（Variable） - -**代码示例** - -.. code-block:: python - - data = fluid.layers.data(name="data", shape=[-1, 32, 32], dtype="float32") - label = fluid.layers.data(name="data", shape=[-1,1], dtype="int32") - predict = fluid.layers.fc(input=data, size=10) - acc = fluid.layers.accuracy(input=predict, label=label, k=5) - - - - - - - - - - - - -.. _cn_api_fluid_layers_auc: - -auc -------------------------------- - -.. py:function:: paddle.fluid.layers.auc(input, label, curve='ROC', num_thresholds=4095, topk=1, slide_steps=1) - -**Area Under the Curve(AUC) Layer** - -该层根据前向输出和标签计算AUC，在二分类(binary classification)估计中广泛使用。 - -注：如果输入标注包含一种值，只有0或1两种情况，数据类型则强制转换成布尔值。相关定义可以在这里: https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 找到 - -有两种可能的曲线： - -1. ROC:受试者工作特征曲线 - -2. PR:准确率召回率曲线 - -参数： - - **input** (Variable) - 浮点二维变量，值的范围为[0,1]。每一行降序排列。输入应为topk的输出。该变量显示了每个标签的概率。 - - **label** (Variable) - 二维整型变量，表示训练数据的标注。批尺寸的高度和宽度始终为1. - - **curve** (str) - 曲线类型，可以为 ``ROC`` 或 ``PR``，默认 ``ROC``。 - - **num_thresholds** (int) - 将roc曲线离散化时使用的临界值数。默认200 - - **topk** (int) - 只有预测输出的topk数才被用于auc - - **slide_steps** - 计算批auc时，不仅用当前步也用先前步。slide_steps=1，表示用当前步；slide_steps = 3表示用当前步和前两步；slide_steps = 0，则用所有步 - -返回：代表当前AUC的scalar - -返回类型：变量（Variable） - -**代码示例**： - -.. code-block:: python - - # network为二分类模型, label为ground truth（正确标记） - prediction = network(image, is_infer=True) - auc_out=fluid.layers.auc(input=prediction, label=label) - - - - - - - - - - - +################### +fluid.layers +################### + + +============ + control_flow +============ + + +.. _cn_api_fluid_layers_array_length: + +array_length +------------------------------- + +.. py:function:: paddle.fluid.layers.array_length(array) + +**得到输入LoDTensorArray的长度** + +此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。 + +相关API: + - :ref:`cn_api_fluid_layers_array_read` + - :ref:`cn_api_fluid_layers_array_write` + - :ref:`cn_api_fluid_layers_While` + +参数： + - **array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度 + +返回：输入数组LoDTensorArray的长度 + +返回类型：变量（Variable） + +**代码示例**: + +.. code-block:: python + + tmp = fluid.layers.zeros(shape=[10], dtype='int32') + i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) + arr = fluid.layers.array_write(tmp, i=i) + arr_len = fluid.layers.array_length(arr) + + + + + + + + + +.. _cn_api_fluid_layers_array_read: + +array_read +------------------------------- + +.. py:function:: paddle.fluid.layers.array_read(array,i) + +此函数用于读取数据，数据以LOD_TENSOR_ARRAY数组的形式读入 + +:: + + + Given: + array = [0.6,0.1,0.3,0.1] + And: + I=2 + Then: + output = 0.3 + +参数： + - **array** (Variable|list)-输入张量，存储要读的数据 + - **i** (Variable|list)-输入数组中数据的索引 + +返回：张量类型的变量，已有数据写入 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + tmp = fluid.layers.zeros(shape=[10],dtype='int32') + i = fluid.layers.fill_constant(shape=[1],dtype='int64',value=10) + arr = layers.array_read(tmp,i=i) + + + + + + + + + +.. _cn_api_fluid_layers_array_write: + +array_write +------------------------------- + +.. py:function:: paddle.fluid.layers.array_write(x, i, array=None) + + +该函数将给定的输入变量（即 ``x`` ）写入一个作为输出的 ``LOD_TENSOR_ARRAY`` 变量的某一指定位置中， +这一位置由数组下标(即 ``i`` )指明。 如果 ``LOD_TENSOR_ARRAY`` (即 ``array`` )未指定（即为None值）， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回。 + +参数: + - **x** (Variable|list) – 待从中读取数据的输入张量(tensor) + - **i** (Variable|list) – 输出结果 ``LOD_TENSOR_ARRAY`` 的下标, 该下标指向输入张量 ``x`` 写入输出数组的位置 + - **array** (Variable|list) – 会被输入张量 ``x`` 写入的输出结果 ``LOD_TENSOR_ARRAY`` 。如果该项值为None， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回 + +返回: 输入张量 ``x`` 所写入的输出结果 ``LOD_TENSOR_ARRAY`` + +返回类型: 变量（Variable） + +**代码示例** + +.. code-block:: python + + tmp = fluid.layers.zeros(shape=[10], dtype='int32') + i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) + arr = layers.array_write(tmp, i=i) + + + + + + + + + + + +.. _cn_api_fluid_layers_create_array: + +create_array +------------------------------- + +.. py:function:: paddle.fluid.layers.create_array(dtype) + + +创建LoDTensorArray数组。它主要用于实现RNN与array_write, array_read和While。 + +参数: + - **dtype** (int |float) — lod_tensor_array中存储元素的数据类型。 + +返回: lod_tensor_array， 元素数据类型为dtype。 + +返回类型: Variable。 + + +**代码示例** + +.. code-block:: python + + data = fluid.layers.create_array(dtype='float32') + + + + + + + + + + + +.. _cn_api_fluid_layers_DynamicRNN: + +DynamicRNN +------------------------------- + +.. py:class:: paddle.fluid.layers.DynamicRNN(name=None) + + +动态RNN可以处理一批序列数据,每个样本序列的长度可以不同。这个API自动批量处理它们。 + +必须设置输入lod，请参考 ``lod_tensor`` + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + data = fluid.layers.data(name='sentence', dtype='int64', lod_level=1) + embedding = fluid.layers.embedding(input=data, size=[65535, 32], + is_sparse=True) + + drnn = fluid.layers.DynamicRNN() + with drnn.block(): + word = drnn.step_input(embedding) + prev = drnn.memory(shape=[200]) + hidden = fluid.layers.fc(input=[word, prev], size=200, act='relu') + drnn.update_memory(prev, hidden) # set prev to hidden + drnn.output(hidden) + + # last是的最后一时间步，也是编码（encoding）得出的最终结果 + last = fluid.layers.sequence_last_step(drnn()) + + +动态RNN将按照timesteps展开开序列。用户需要在with block中定义如何处理处理每个timestep。 + +memory用于缓存分段数据。memory的初始值可以是零，也可以是其他变量。 + +动态RNN可以将多个变量标记为其输出。使用drnn()获得输出序列。 + +.. note:: + 目前不支持在DynamicRNN中任何层上配置 is_sparse = True + +.. py:method:: step_input(x) + + 将序列标记为动态RNN输入。 + +参数: + - **x** (Variable) - 输入序列 + + +返回:当前的输入序列中的timestep。 + +.. py:method:: static_input(x) + +将变量标记为RNN输入。输入不会分散到timestep中。 + +参数: + - **x** (Variable) - 输入序列 + +返回:可以访问的RNN的输入变量,。 + +.. py:method:: block(*args, **kwds) + +用户在RNN中定义operators的block。有关详细信息，请参阅class ``docstring`` 。 + +.. py:method:: memory(init=None, shape=None, value=0.0, need_reorder=False, dtype='float32') + +为动态rnn创建一个memory 变量。 + +如果 ``init`` 不是None， ``memory`` 将由这个变量初始化。参数 ``need_reorder`` 用于将memory重新排序作为输入变量。当memory初始化依赖于输入样本时，应该将其设置为true。 + +**例如** + +.. code-block:: python + + import paddle.fluid as fluid + sentence = fluid.layers.data( + name='sentence', dtype='float32', shape=[32]) + boot_memory = fluid.layers.data( + name='boot', dtype='float32', shape=[10]) + + drnn = fluid.layers.DynamicRNN() + with drnn.block(): + word = drnn.step_input(sentence) + memory = drnn.memory(init=boot_memory, need_reorder=True) + hidden = fluid.layers.fc( + input=[word, memory], size=10, act='tanh') + drnn.update_memory(ex_mem=memory, new_mem=hidden) + drnn.output(hidden) + + rnn_output = drnn() + + + +否则，如果已经设置 ``shape`` 、 ``value`` 、 ``dtype`` ，memory将被 ``value`` 初始化 + +.. code-block:: python + + import paddle.fluid as fluid + + sentence = fluid.layers.data( + name='sentence', dtype='float32', shape=[32]) + + drnn = fluid.layers.DynamicRNN() + with drnn.block(): + word = drnn.step_input(sentence) + memory = drnn.memory(shape=[10], dtype='float32', value=0) + hidden = fluid.layers.fc( + input=[word, memory], size=10, act='tanh') + drnn.update_memory(ex_mem=memory, new_mem=hidden) + drnn.output(hidden) + rnn_output = drnn() + + +参数： + - **init** (Variable|None) – 初始化的Variable + - **shape** (list|tuple) – memory shape. 注意形状不包含batch的大小 + - **value** (float) – 初始化的值 + - **need_reorder** (bool) – memory初始化依赖于输入样本时设置为True + - **dtype** (str|numpy.dtype) – 初始化memory的数据类型 + +返回：memory Variable + + +.. py:method:: update_memory(ex_mem, new_mem) + +将内存从 ``ex_mem`` 更新到 ``new_mem`` 。注意， ``ex_mem`` 和 ``new_mem`` 的 ``shape`` 和数据类型必须相同。 + +参数： + - **ex_mem** （memory Variable）- memory 变量（Variable） + - **new_mem** （memory Variable）- RNN块中生成的平坦变量（plain variable） + +返回：None + + +.. py:method:: output(*outputs) + +标记RNN输出变量。 + +参数: + - **\*outputs** - 输出变量。 + +返回:None + + + + + + + + + + +.. _cn_api_fluid_layers_equal: + +equal +------------------------------- + +.. py:function:: paddle.fluid.layers.equal(x,y,cond=None,**ignored) + +**equal** +该层返回 :math:`x==y` 按逐元素运算而得的真值。 + +参数： + - **x** (Variable)-equal的第一个操作数 + - **y** (Variable)-equal的第二个操作数 + - **cond** (Variable|None)-输出变量（可选），用来存储equal的结果 + +返回：张量类型的变量，存储equal的输出结果 + +返回类型：变量（Variable） + +**代码示例**: + +.. code-block:: python + + less = fluid.layers.equal(x=label,y=limit) + + + + + + + + + +.. _cn_api_fluid_layers_IfElse: + +IfElse +------------------------------- + +.. py:class:: paddle.fluid.layers.IfElse(cond, name=None) + +if-else控制流。 + +参数： + - **cond** (Variable)-用于比较的条件 + - **Name** (str,默认为空（None）)-该层名称 + +**代码示例**： + +.. code-block:: python + + limit = fluid.layers.fill_constant_batch_size_like( + input=label, dtype='int64', shape=[1], value=5.0) + cond = fluid.layers.less_than(x=label, y=limit) + ie = fluid.layers.IfElse(cond) + with ie.true_block(): + true_image = ie.input(image) + hidden = fluid.layers.fc(input=true_image, size=100, act='tanh') + prob = fluid.layers.fc(input=hidden, size=10, act='softmax') + ie.output(prob) + + with ie.false_block(): + false_image = ie.input(image) + hidden = fluid.layers.fc( + input=false_image, size=200, act='tanh') + prob = fluid.layers.fc(input=hidden, size=10, act='softmax') + ie.output(prob) + prob = ie() + + + + + + + + + +.. _cn_api_fluid_layers_increment: + +increment +------------------------------- + +.. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True) + + +该函数为输入 ``x`` 增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。 + +.. note:: + ``x`` 中元素个数必须为1 + +参数: + - **x** (Variable|list) – 含有输入值的张量(tensor) + - **value** (float) – 需要增加在 ``x`` 变量上的值 + - **in_place** (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本 + +返回： 每个元素增加后的对象 + +返回类型：变量(variable) + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[1], dtype='float32', + append_batch_size=False) + data = fluid.layers.increment(x=data, value=3.0, in_place=True) + + + + + + + + + + + +.. _cn_api_fluid_layers_is_empty: + +is_empty +------------------------------- + +.. py:function:: paddle.fluid.layers.is_empty(x, cond=None, **ignored) + +测试变量是否为空 + +参数： + - **x** (Variable)-测试的变量 + - **cond** (Variable|None)-输出参数。返回给定x的测试结果，默认为空（None） + +返回：布尔类型的标量。如果变量x为空则值为真 + +返回类型：变量（Variable） + +抛出异常：``TypeError``-如果input不是变量或cond类型不是变量 + +**代码示例**： + +.. code-block:: python + + res = fluid.layers.is_empty(x=input) + # or: + fluid.layers.is_empty(x=input, cond=res) + + + + + + + + + +.. _cn_api_fluid_layers_less_than: + +less_than +------------------------------- + +.. py:function:: paddle.fluid.layers.less_than(x, y, force_cpu=None, cond=None, **ignored) + + +该函数按元素出现顺序依次在X,Y上操作，并返回 ``Out`` ，它们三个都是n维tensor（张量）。 +其中，X、Y可以是任何类型的tensor，Out张量的各个元素可以通过 :math:`Out=X`_ + +.. math:: + + PE(pos, 2i) &= \sin{(pos / 10000^{2i / P})}\\ + PE(pos, 2i + 1) &= \cos{(pos / 10000^{2i / P})}\\ + Out(:, pos, i) &= \alpha * input(:, pos, i) + \beta * PE(pos, i) + +其中: + - PE(pos, 2i): 偶数位置上数字的增量 + - PE(pos, 2i + 1): 奇数位置上数字的增量 + +返回： Variable: 具有位置编码的三维形状张量[N×M×P] + +**代码示例：** + +.. code-block:: python + + position_tensor = fluid.layers.add_position_encoding(input=tensor) + + + + + + + + + + + +.. _cn_api_fluid_layers_affine_channel: + +affine_channel +------------------------------- + +.. py:function:: paddle.fluid.layers.affine_channel(x, scale=None, bias=None, data_layout='NCHW', name=None) + +对输入的每个 channel 应用单独的仿射变换。用于将空间批处理范数替换为其等价的固定变换。 + +输入也可以是二维张量，并在二维应用仿射变换。 + +参数： + - **x** (Variable):特征图输入可以是一个具有NCHW阶或NHWC阶的4D张量。它也可以是二维张量和应用于第二维度的仿射变换。 + - **scale** (Variable): 形状为(C)的一维输入，第C个元素为输入的第C通道仿射变换的尺度因子。 + - **bias** (Variable):形状为(C)的一维输入，第C个元素是输入的第C个通道的仿射变换的偏置。 + - **data_layout** (string, default NCHW): NCHW 或 NHWC，如果输入是一个2D张量，可以忽略该参数 + - **name** (str, default None): 此层的名称 + +返回： out (Variable): 与x具有相同形状和数据布局的张量。 + + + + + + + + + +.. _cn_api_fluid_layers_affine_grid: + +affine_grid +------------------------------- + +.. py:function:: paddle.fluid.layers.affine_grid(theta, out_shape, name=None) + +它使用仿射变换的参数生成(x,y)坐标的网格，这些参数对应于一组点，在这些点上，输入特征映射应该被采样以生成转换后的输出特征映射。 + + + +.. code-block:: text + + * 例 1: + 给定: + theta = [[[x_11, x_12, x_13] + [x_14, x_15, x_16]] + [[x_21, x_22, x_23] + [x_24, x_25, x_26]]] + out_shape = [2, 3, 5, 5] + + Step 1: + + 根据out_shape生成标准化坐标 + + 归一化坐标的值在-1和1之间 + + 归一化坐标的形状为[2,H, W]，如下所示: + + C = [[[-1. -1. -1. -1. -1. ] + [-0.5 -0.5 -0.5 -0.5 -0.5] + [ 0. 0. 0. 0. 0. ] + [ 0.5 0.5 0.5 0.5 0.5] + [ 1. 1. 1. 1. 1. ]] + [[-1. -0.5 0. 0.5 1. ] + [-1. -0.5 0. 0.5 1. ] + [-1. -0.5 0. 0.5 1. ] + [-1. -0.5 0. 0.5 1. ] + [-1. -0.5 0. 0.5 1. ]]] + + C[0]是高轴坐标，C[1]是宽轴坐标。 + + Step2: + + 将C转换并重组成形为[H * W, 2]的张量,并追加到最后一个维度 + + 我们得到: + + C_ = [[-1. -1. 1. ] + [-0.5 -1. 1. ] + [ 0. -1. 1. ] + [ 0.5 -1. 1. ] + [ 1. -1. 1. ] + [-1. -0.5 1. ] + [-0.5 -0.5 1. ] + [ 0. -0.5 1. ] + [ 0.5 -0.5 1. ] + [ 1. -0.5 1. ] + [-1. 0. 1. ] + [-0.5 0. 1. ] + [ 0. 0. 1. ] + [ 0.5 0. 1. ] + [ 1. 0. 1. ] + [-1. 0.5 1. ] + [-0.5 0.5 1. ] + [ 0. 0.5 1. ] + [ 0.5 0.5 1. ] + [ 1. 0.5 1. ] + [-1. 1. 1. ] + [-0.5 1. 1. ] + [ 0. 1. 1. ] + [ 0.5 1. 1. ] + [ 1. 1. 1. ]] + Step3: + 按下列公式计算输出 +.. math:: + + Output[i] = C\_ * Theta[i]^T + +参数： + - **theta** (Variable)： 一类具有形状为[N, 2, 3]的仿射变换参数 + - **out_shape** (Variable | list | tuple)：具有格式[N, C, H, W]的目标输出的shape，out_shape可以是变量、列表或元组。 + - **name** (str|None): 此层的名称(可选)。如果没有设置，将自动命名。 + +返回： Variable: 形为[N, H, W, 2]的输出。 + +抛出异常： ValueError: 如果输入了不支持的参数类型 + +**代码示例：** + +.. code-block:: python + + theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") + out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") + data = fluid.layers.affine_grid(theta, out_shape) + # or + data = fluid.layers.affine_grid(theta, [5, 3, 28, 28]) + + + + + + + + + +.. _cn_api_fluid_layers_autoincreased_step_counter: + +autoincreased_step_counter +------------------------------- + +.. py:function:: paddle.fluid.layers.autoincreased_step_counter(counter_name=None, begin=1, step=1) + +创建一个自增变量，每个mini-batch返回主函数运行次数，变量自动加1，默认初始值为1. + +参数： + - **counter_name** (str)-计数名称，默认为 ``@STEP_COUNTER@`` + - **begin** (int)-开始计数 + - **step** (int)-执行之间增加的步数 + +返回：全局运行步数 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + global_step = fluid.layers.autoincreased_step_counter( + counter_name='@LR_DECAY_COUNTER@', begin=begin, step=1) + + + + + + + + + +.. _cn_api_fluid_layers_batch_norm: + +batch_norm +------------------------------- + +.. py:function:: paddle.fluid.layers.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False, fuse_with_relu=False) + +批正则化层（Batch Normalization Layer） + +可用作conv2d和全链接操作的正则化函数。该层需要的数据格式如下： + +1.NHWC[batch,in_height,in_width,in_channels] +2.NCHW[batch,in_channels,in_height,in_width] + +更多详情请参考 : `Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ + +``input`` 是mini-batch的输入特征。 + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mini-batch-mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// mini-batch-variance \\ + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift + +参数： + - **input** (Variable) - 输入变量，为LoDTensor + - **act** （string，默认None）- 激活函数类型，linear|relu|prelu|... + - **is_test** （bool,默认False） - 标志位，是否用于测试或训练 + - **momentum** （float，默认0.9）- （暂无说明，待更新） + - **epsilon** （float，默认1e-05）- （暂无说明，待更新） + - **param_attr** （ParamAttr|None） - batch_norm参数范围的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为param_attr。如果没有设置param_attr的初始化函数，参数初始化为Xavier。默认：None + - **bias_attr** （ParamAttr|None） - batch_norm bias参数的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为bias_attr。如果没有设置bias_attr的初始化函数，参数初始化为0。默认：None + - **data_layout** （string,默认NCHW) - NCHW|NHWC + - **in_place** （bool，默认False）- 得出batch norm可复用记忆的输入和输出 + - **name** （string，默认None）- 该层名称（可选）。若设为None，则自动为该层命名 + - **moving_mean_name** （string，默认None）- moving_mean的名称，存储全局Mean + - **moving_variance_name** （string，默认None）- moving_variance的名称，存储全局变量 + - **do_model_average_for_mean_and_var** （bool，默认False）- 是否为mean和variance做模型均值 + - **fuse_with_relu** （bool）- 如果为True，batch norm后该操作符执行relu + +返回： 张量，在输入中运用批正则后的结果 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + hidden1 = fluid.layers.fc(input=x, size=200, param_attr='fc1.w') + hidden2 = fluid.layers.batch_norm(input=hidden1) + + + + + + + + + + + +.. _cn_api_fluid_layers_beam_search: + +beam_search +------------------------------- + +.. py:function:: paddle.fluid.layers.beam_search(pre_ids, pre_scores, ids, scores, beam_size, end_id, level=0, name=None) + +在机器翻译任务中，束搜索(Beam search)是选择候选词的一种经典算法 + +更多细节参考 `Beam Search `_ + +该层对束在一时间步中进行搜索。根据候选词使用于源句子所得的 ``scores`` , 从候选词 ``ids`` 中选择当前步骤的 top-K （最佳K）候选词的id，其中 ``K`` 是 ``beam_size`` ， ``ids`` ， ``scores`` 是计算单元的预测结果。 另外， ``pre_id`` 和 ``pre_scores`` 是上一步中 ``beam_search`` 的输出，用于特殊处理结束边界。 + +注意，传入的 ``scores`` 应该是累积分数，并且，在计算累积分数之前应该使用额外的 operators 进行长度惩罚，也建议在计算前查找top-K，然后使用top-K候选项。 + +有关完全波束搜索用法演示，请参阅以下示例： + + fluid/tests/book/test_machine_translation.py + + + +参数: + - **pre_ids** （Variable） - LodTensor变量，它是上一步 ``beam_search`` 的输出。在第一步中。它应该是LodTensor，shape为 :math:`(batch\_size，1)` ， :math:`lod [[0,1，...，batch\_size]，[0,1，...，batch\_size]]` + - **pre_scores** （Variable） - LodTensor变量，它是上一步中beam_search的输出 + - **ids** （Variable） - 包含候选ID的LodTensor变量。shpae为 :math:`（batch\_size×beam\_ize，K）` ，其中 ``K`` 应该是 ``beam_size`` + - **scores** （Variable） - 与 ``ids`` 及其shape对应的累积分数的LodTensor变量, 与 ``ids`` 的shape相同。 + - **beam_size** （int） - 束搜索中的束宽度。 + - **end_id** （int） - 结束标记的id。 + - **level** （int，default 0） - **可忽略，当前不能更改** 。它表示lod的源级别，解释如下。 ``ids`` 的 lod 级别应为2.第一级是源级别， 描述每个源句子（beam）的前缀（分支）的数量，第二级是描述这些候选者属于前缀的句子级别的方式。链接前缀和所选候选者的路径信息保存在lod中。 + - **name** （str | None） - 该层的名称（可选）。如果设置为None，则自动命名该层。 + +返回：LodTensor pair ， 包含所选的ID和相应的分数 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + # 假设 `probs` 包含计算神经元所得的预测结果 + # `pre_ids` 和 `pre_scores` 为beam_search之前时间步的输出 + topk_scores, topk_indices = layers.topk(probs, k=beam_size) + accu_scores = layers.elementwise_add( + x=layers.log(x=topk_scores)), + y=layers.reshape( + pre_scores, shape=[-1]), + axis=0) + selected_ids, selected_scores = layers.beam_search( + pre_ids=pre_ids, + pre_scores=pre_scores, + ids=topk_indices, + scores=accu_scores, + beam_size=beam_size, + end_id=end_id) + + + + + + + + + + + +.. _cn_api_fluid_layers_beam_search_decode: + +beam_search_decode +------------------------------- + +.. py:function:: paddle.fluid.layers.beam_search_decode(ids, scores, beam_size, end_id, name=None) + +束搜索层（Beam Search Decode Layer）通过回溯LoDTensorArray ids，为每个源语句构建完整假设，LoDTensorArray ``ids`` 的lod可用于恢复束搜索树中的路径。请参阅下面的demo中的束搜索使用示例： + + :: + + fluid/tests/book/test_machine_translation.py + +参数: + - **id** (Variable) - LodTensorArray，包含所有回溯步骤重中所需的ids。 + - **score** (Variable) - LodTensorArra，包含所有回溯步骤对应的score。 + - **beam_size** (int) - 束搜索中波束的宽度。 + - **end_id** (int) - 结束token的id。 + - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回： LodTensor 对（pair）， 由生成的id序列和相应的score序列组成。两个LodTensor的shape和lod是相同的。lod的level=2，这两个level分别表示每个源句有多少个假设，每个假设有多少个id。 + +返回类型: 变量（variable） + + +**代码示例** + +.. code-block:: python + + # 假设 `ids` 和 `scores` 为 LodTensorArray变量，它们保留了 + # 选择出的所有时间步的id和score + finished_ids, finished_scores = layers.beam_search_decode( + ids, scores, beam_size=5, end_id=0) + + + + + + + + + +.. _cn_api_fluid_layers_bilinear_tensor_product: + +bilinear_tensor_product +------------------------------- + +.. py:function:: paddle.fluid.layers.bilinear_tensor_product(x, y, size, act=None, name=None, param_attr=None, bias_attr=None) + +该层对两个输入执行双线性张量积。 + +例如: + +.. math:: + out_{i} = x * W_{i} * {y^\mathrm{T}}, i=0,1,...,size-1 + +在这个公式中： + - :math:`x`: 第一个输入，包含M个元素，形状为[batch_size, M] + - :math:`y`: 第二个输入，包含N个元素，形状为[batch_size, N] + - :math:`W_{i}`: 第i个被学习的权重，形状是[M, N] + - :math:`out_{i}`: out的第i个元素，形状是[batch_size, size] + - :math:`y^\mathrm{T}`: :math:`y_{2}` 的转置 + +参数： + - **x** (Variable): 2-D 输入张量，形状为 [batch_size, M] + - **y** (Variable): 2-D 输入张量，形状为 [batch_size, N] + - **size** (int): 此层的维度， + - **act** (str, default None): 应用到该层输出的激活函数 + - **name** (str, default None): 该层的名称 + - **param_attr** (ParamAttr, default None): 可学习参数/权重（w） 的参数属性 + - **bias_attr** (ParamAttr, default None): 偏差的参数属性，如果设置为False，则不会向输出单元添加偏差。如果设置为零，偏差初始化为零。默认值:None + +返回： Variable: 一个形为[batch_size, size]的2-D张量 + +**代码示例：** + +.. code-block:: python + + tensor = bilinear_tensor_product(x=layer1, y=layer2, size=1000) + + + + + + + + + + +.. _cn_api_fluid_layers_brelu: + +brelu +------------------------------- + +.. py:function:: paddle.fluid.layers.brelu(x, t_min=0.0, t_max=24.0, name=None) + + +BRelu 激活函数 + +.. math:: out=max(min(x,tmin),tmax) + +参数: + - **x** (Variable) - BReluoperator的输入 + - **t_min** (FLOAT|0.0) - BRelu的最小值 + - **t_max** (FLOAT|24.0) - BRelu的最大值 + - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 + + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[2,3,16,16], dtype=”float32”) + y = fluid.layers.brelu(x, t_min=1.0, t_max=20.0) + + + + + + +.. _cn_api_fluid_layers_chunk_eval: + +chunk_eval +------------------------------- + +.. py:function:: paddle.fluid.layers.chunk_eval(input, label, chunk_scheme, num_chunk_types, excluded_chunk_types=None) + +块估计（Chunk Evaluator） + +该功能计算并输出块检测（chunk detection）的准确率、召回率和F1值。 + +chunking的一些基础请参考 `Chunking with Support Vector Machines `_ + +ChunkEvalOp计算块检测（chunk detection）的准确率、召回率和F1值，并支持IOB，IOE，IOBES和IO标注方案。以下是这些标注方案的命名实体（NER）标注例子： + +:: + + + ====== ====== ====== ===== == ============ ===== ===== ===== == ========= + Li Ming works at Agricultural Bank of China in Beijing. + ====== ====== ====== ===== == ============ ===== ===== ===== == ========= + IO I-PER I-PER O O I-ORG I-ORG I-ORG I-ORG O I-LOC + IOB B-PER I-PER O O B-ORG I-ORG I-ORG I-ORG O B-LOC + IOE I-PER E-PER O O I-ORG I-ORG I-ORG E-ORG O E-LOC + IOBES B-PER E-PER O O I-ORG I-ORG I-ORG E-ORG O S-LOC + ====== ====== ====== ===== == ============ ===== ===== ===== == ========= + +有三种块类别（命名实体类型），包括PER（人名），ORG（机构名）和LOC（地名），标签形式为标注类型（tag type）-块类型（chunk type）。 + +由于计算实际上用的是标签id而不是标签，需要额外注意将标签映射到相应的id，这样CheckEvalOp才可运行。关键在于id必须在列出的等式中有效。 + +:: + + + tag_type = label % num_tag_type + chunk_type = label / num_tag_type + +num_tag_type是标注规则中的标签类型数，num_chunk_type是块类型数，tag_type从下面的表格中获取值。 + +:: + + + Scheme Begin Inside End Single + plain 0 - - - + IOB 0 1 - - + IOE - 0 1 - + IOBES 0 1 2 3 + +仍以NER为例，假设标注规则是IOB块类型为ORG，PER和LOC。为了满足以上等式，标签图如下： + +:: + + + B-ORG 0 + I-ORG 1 + B-PER 2 + I-PER 3 + B-LOC 4 + I-LOC 5 + O 6 + +不难证明等式的块类型数为3，IOB规则中的标签类型数为2.例如I-LOC的标签id为5，I-LOC的标签类型id为1，I-LOC的块类型id为2，与等式的结果一致。 + +参数： + - **input** (Variable) - 网络的输出预测 + - **label** (Variable) - 测试数据集的标签 + - **chunk_scheme** (str) - 标注规则，表示如何解码块。必须数IOB，IOE，IOBES或者plain。详情见描述 + - **num_chunk_types** (int) - 块类型数。详情见描述 + - **excluded_chunk_types** (list) - 列表包含块类型id，表示不在计数内的块类型。详情见描述 + +返回：元组（tuple），包含precision, recall, f1_score, num_infer_chunks, num_label_chunks, num_correct_chunks + +返回类型：tuple（元组） + +**代码示例**： + +.. code-block:: python: + + crf = fluid.layers.linear_chain_crf( + input=hidden, label=label, param_attr=ParamAttr(name="crfw")) + crf_decode = fluid.layers.crf_decoding( + input=hidden, param_attr=ParamAttr(name="crfw")) + fluid.layers.chunk_eval( + input=crf_decode, + label=label, + chunk_scheme="IOB", + num_chunk_types=(label_dict_len - 1) / 2) + + + + + + + + + +.. _cn_api_fluid_layers_clip: + +clip +------------------------------- + +.. py:function:: paddle.fluid.layers.clip(x, min, max, name=None) + +clip算子 + +clip运算符限制给定输入的值在一个区间内。间隔使用参数"min"和"max"来指定：公式为 + +.. math:: + Out=min(max(X,min),max) + +参数： + - **x** （Variable）- （Tensor）clip运算的输入，维数必须在[1,9]之间。 + - **min** （FLOAT）- （float）最小值，小于该值的元素由min代替。 + - **max** （FLOAT）- （float）最大值，大于该值的元素由max替换。 + - **name** （basestring | None）- 输出的名称。 + +返回： （Tensor）clip操作后的输出和输入（X）具有形状（shape） + +返回类型： 输出（Variable）。 + +**代码示例：** + +.. code-block:: python + + input = fluid.layers.data( + name='data', shape=[1], dtype='float32') + reward = fluid.layers.clip(x=input, min=-1.0, max=1.0) + + + + + + +.. _cn_api_fluid_layers_clip_by_norm: + +clip_by_norm +------------------------------- + +.. py:function:: paddle.fluid.layers.clip_by_norm(x, max_norm, name=None) + +ClipByNorm算子 + +此运算符将输入 ``X`` 的L2范数限制在 ``max_norm`` 内。如果 ``X`` 的L2范数小于或等于 ``max_norm`` ，则输出（Out）将与 ``X`` 相同。如果X的L2范数大于 ``max_norm`` ，则 ``X`` 将被线性缩放，使得输出（Out）的L2范数等于 ``max_norm`` ，如下面的公式所示： + +.. math:: + Out = \frac{max\_norm * X}{norm(X)} + +其中， :math:`norm（X）` 代表 ``x`` 的L2范数。 + + +参数： + - **x** (Variable)- (Tensor) clip_by_norm运算的输入，维数必须在[1,9]之间。 + - **max_norm** (float)- 最大范数值。 + - **name** (basestring | None)- 输出的名称。 + +返回： (Tensor)clip_by_norm操作后的输出和输入(X)具有形状(shape). + +返回类型： Variable + +**代码示例：** + +.. code-block:: python + + input = fluid.layers.data( + name='data', shape=[1], dtype='float32') + reward = fluid.layers.clip_by_norm(x=input, max_norm=1.0) + + + + + + + + +.. _cn_api_fluid_layers_conv2d: + +conv2d +------------------------------- + +.. py:function:: paddle.fluid.layers.conv2d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) + +卷积二维层（convolution2D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、dilations、一组参数计算输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 `_ 。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。 + +对每个输入X，有等式： + +.. math:: + + Out = \sigma \left ( W * X + b \right ) + +其中： + - :math:`X` ：输入值，NCHW格式的张量（Tensor） + - :math:`W` ：滤波器值，MCHW格式的张量（Tensor） + - :math:`*` ： 卷积操作 + - :math:`b` ：Bias值，二维张量（Tensor），shape为[M,1] + - :math:`\sigma` ：激活函数 + - :math:`Out` ：输出值，*Out*和**X**的shape可能不同 + +**示例** + +- 输入： + + 输入shape：:math:`( N,C_{in},H_{in},W_{in} )` + + 滤波器shape： :math:`( C_{out},C_{in},H_{f},W_{f} )` + +- 输出： + + 输出shape： :math:`( N,C_{out},H_{out},W_{out} )` + +其中 + +.. math:: + + H_{out} = \frac{\left ( H_{in}+2*paddings[0]-\left ( dilations[0]*\left ( H_{f}-1 \right )+1 \right ) \right )}{strides[0]}+1 + + W_{out} = \frac{\left ( H_{in}+2*paddings[1]-\left ( dilations[1]*\left ( W_{f}-1 \right )+1 \right ) \right )}{strides[1]}+1 + +参数： + - **input** (Variable) - 格式为[N,C,H,W]格式的输入图像 + - **num_fliters** (int) - 滤波器数。和输出图像通道相同 + - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size，filter_size_W）。否则，滤波器为square + - **stride** (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含两个整型数，（stride_H,stride_W）。否则，stride_H = stride_W = stride。默认：stride = 1 + - **padding** (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含两个整型数，（padding_H,padding_W)。否则，padding_H = padding_W = padding。默认：padding = 0 + - **dilation** (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数，（dilation_H,dilation_W）。否则，dilation_H = dilation_W = dilation。默认：dilation = 1 + - **groups** (int) - 卷积二维层（Conv2D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1 + - **param_attr** (ParamAttr|None) - conv2d的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)` ，并且std为 :math:`\frac{2.0}{filter\_elem\_num}^{0.5}` 。默认为None + - **bias_attr** (ParamAttr|bool|None) - conv2d bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None + - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True + - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None + - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 + +返回：张量，存储卷积和非线性激活结果 + +返回类型：变量（Variable） + +抛出异常: + - ``ValueError`` - 如果输入shape和filter_size，stride,padding和group不匹配。 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') + conv2d = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3, act="relu") + + + + + + + + + + + +.. _cn_api_fluid_layers_conv2d_transpose: + +conv2d_transpose +------------------------------- + +.. py:function:: paddle.fluid.layers.conv2d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) + +2-D卷积转置层（Convlution2D transpose layer） + +该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充（padding）来计算输出。输入(Input)和输出(Output)为NCHW格式，其中 ``N`` 为batch大小， ``C`` 为通道数（channel），``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别都包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为 ``None``，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数。 + +.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf + +输入 :math:`X` 和输出 :math:`Out` 函数关系如下： + +.. math:: + Out=\sigma (W*X+b)\\ + +其中： + - :math:`X` : 输入张量，具有 ``NCHW`` 格式 + + - :math:`W` : 滤波器张量，具有 ``NCHW`` 格式 + + - :math:`*` : 卷积操作 + + - :math:`b` : 偏置（bias），二维张量，shape为 ``[m,1]`` + + - :math:`σ` : 激活函数 + + - :math:`Out` : 输出值，Out和 ``X`` 的 ``shape`` 可能不一样 + +**样例**： + +输入： + +.. math:: + + 输入张量的shape : （N，C_{in}， H_{in}， W_{in}) + + 滤波器（filter）shape ： （C_{in}, C_{out}, H_f, W_f) + +输出： + +.. math:: + 输出张量的 shape ： （N，C_{out}, H_{out}, W_{out}) + +其中 + +.. math:: + + & H'_{out} = (H_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(H_f-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(W_f-1)+1 \\ + & H_{out}\in[H'_{out},H'_{out} + strides[0])\\ + & W_{out}\in[W'_{out},W'_{out} + strides[1])\\ + + + +参数: + - **input** （Variable）- 输入张量，格式为[N, C, H, W] + - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（ channel ）相同 + - **output_size** (int|tuple|None) - 输出图片的大小。如果output_size是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果output_size=None,则内部会使用filter_size、padding和stride来计算output_size。如果output_size和filter_size是同时指定的，那么它们应满足上面的公式。 + - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果filter_size=None，则内部会计算输出大小。 + - **padding** (int|tuple) - 填充大小。如果padding是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。 + - **stride** (int|tuple) - 步长大小。如果stride是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 + - **dilation** (int|元组) - 膨胀大小。如果dilation是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation_W。默认:dilation= 1。 + - **groups** (int) - Conv2d转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。 + - **param_attr** (ParamAttr|None) - conv2d_transfer中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv2d_transfer使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。 + - **bias_attr** (ParamAttr|bool|None) - conv2d_tran_bias中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv2d_transfer使用ParamAttrs作为，bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。 + - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。 + - **act** (str) - 激活函数类型，如果设置为None，则不使用激活函数。默认值:None。 + - **name** (str|None) - 该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。 + + +返回： 存储卷积转置结果的张量。 + +返回类型: 变量（variable） + +抛出异常: + - ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') + conv2d_transpose = fluid.layers.conv2d_transpose(input=data, num_filters=2, filter_size=3) + + + + + + + + + + + +.. _cn_api_fluid_layers_conv3d: + +conv3d +------------------------------- + +.. py:function:: paddle.fluid.layers.conv3d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) + +卷积三维层（convolution3D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀（dilations）、组数参数计算得到输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积三维（Convlution3D）和卷积二维（Convlution2D）相似，但多了一维深度（depth）。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。 + +对每个输入X，有等式： + +.. math:: + + + Out = \sigma \left ( W * X + b \right ) + +其中： + - :math:`X` ：输入值，NCHW格式的张量（Tensor） + - :math:`W` ：滤波器值，MCHW格式的张量（Tensor） + - :math:`*` ： 卷积操作 + - :math:`b` ：Bias值，二维张量（Tensor），形为[M,1] + - :math:`\sigma` ：激活函数 + - :math:`Out` ：输出值, 和 :math:`X` 的形状可能不同 + +**示例** + +- 输入： + 输入shape： :math:`( N,C_{in},H_{in},W_{in} )` + + 滤波器shape： :math:`( C_{out},C_{in},H_{f},W_{f} )` +- 输出： + 输出shape： :math:`( N,C_{out},H_{out},W_{out} )` + +其中 + +.. math:: + + + D_{out} = \frac{\left ( D_{in}+2*paddings[0]-\left ( dilations[0]*\left ( D_{f}-1 \right )+1 \right ) \right )}{strides[0]}+1 + + H_{out} = \frac{\left ( H_{in}+2*paddings[1]-\left ( dilations[1]*\left ( H_{f}-1 \right )+1 \right ) \right )}{strides[1]}+1 + + W_{out} = \frac{\left ( W_{in}+2*paddings[2]-\left ( dilations[2]*\left ( W_{f}-1 \right )+1 \right ) \right )}{strides[2]}+1 + +参数： + - **input** (Variable) - 格式为[N,C,H,W]格式的输入图像 + - **num_fliters** (int) - 滤波器数。和输出图像通道相同 + - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size，filter_size_W）。否则，滤波器为square + - **stride** (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含两个整型数，（stride_H,stride_W）。否则，stride_H = stride_W = stride。默认：stride = 1 + - **padding** (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含两个整型数，（padding_H,padding_W)。否则，padding_H = padding_W = padding。默认：padding = 0 + - **dilation** (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数，（dilation_H,dilation_W）。否则，dilation_H = dilation_W = dilation。默认：dilation = 1 + - **groups** (int) - 卷积二维层（Conv2D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1 + - **param_attr** (ParamAttr|None) - conv2d的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)`，并且std为 :math:`\left ( \frac{2.0}{filter\_elem\_num} \right )^{0.5}` 。默认为None + - **bias_attr** (ParamAttr|bool|None) - conv2d bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None + - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True + - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None + - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 + +返回：张量，存储卷积和非线性激活结果 + +返回类型：变量（Variable） + +抛出异常： + - ``ValueError`` - 如果 ``input`` 的形和 ``filter_size`` ， ``stride`` , ``padding`` 和 ``group`` 不匹配。 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32') + conv3d = fluid.layers.conv3d(input=data, num_filters=2, filter_size=3, act="relu") + + + + + + + + + +.. _cn_api_fluid_layers_conv3d_transpose: + +conv3d_transpose +------------------------------- + +.. py:function:: paddle.fluid.layers.conv3d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None) + +3-D卷积转置层（Convlution3D transpose layer) + +该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充来计算输出。输入(Input)和输出(Output)为NCDHW格式。其中 ``N`` 为batch大小， ``C`` 为通道数（channel）, ``D`` 为特征深度, ``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为None，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数 + +.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf + +输入X和输出Out函数关系X，有等式如下： + +.. math:: + \\Out=\sigma (W*X+b)\\ + +其中： + - :math:`X` : 输入张量，具有 ``NCDHW`` 格式 + + - :math:`W` : 滤波器张量，，具有 ``NCDHW`` 格式 + + - :math:`*` : 卷积操作 + + - :math:`b` : 偏置（bias），二维张量，shape为[m,1] + + - :math:`σ` : 激活函数 + + - :math:`Out` : 输出值， ``Out`` 和 ``X`` 的 shape可能不一样 + + +**样例** + +输入: + +.. math:: + + Input shape: (N,C_{in},D_{in},H_{in},W_{in}) + + Filter shape: (C_{in},C_{out},D_f,H_f,W_f) + + + +输出: + +.. math:: + + Output shape: (N,C_{out},D_{out},H_{out},W_{out}) + + +其中： + +.. math:: + + + + D_{out}=(D_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(D_f-1)+1 + + H_{out}=(H_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(H_f-1)+1 + + W_{out}=(W_{in}-1)*strides[2]-2*paddings[2]+dilations[2]*(W_f-1)+1 + + + +参数: + - **input** （Variable）- 输入张量，格式为[N, C, D, H, W] + - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（channel）相同 + - **output_size** (int|tuple|None) - 输出图片的大小。如果 ``output_size`` 是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果 ``output_size=None`` ,则内部会使用filter_size、padding和stride来计算output_size。如果 ``output_size`` 和 ``filter_size`` 是同时指定的，那么它们应满足上面的公式。 + - **filter_size** (int|tuple|None) - 滤波器大小。如果 ``filter_size`` 是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果 ``filter_size=None`` ，则内部会计算输出大小。 + - **padding** (int|tuple) - 填充大小。如果 ``padding`` 是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。 + - **stride** (int|tuple) - 步长大小。如果 ``stride`` 是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 + - **dilation** (int|元组) - 膨胀大小。如果 ``dilation`` 是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation_W。默认:dilation= 1。 + - **groups** (int) - Conv2d转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。 + - **param_attr** (ParamAttr|None) - conv2d_transfer中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv2d_transfer使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。 + - **bias_attr** (ParamAttr|bool|None) - conv2d_tran_bias中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv2d_transfer使用ParamAttrs作为，bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。 + - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。 + - **act** (str) - 激活函数类型，如果设置为None，则不使用激活函数。默认值:None。 + - **name** (str|None) - 该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。 + + +返回： 存储卷积转置结果的张量。 + +返回类型: 变量（variable） + +抛出异常: + - ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError + + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32') + conv3d_transpose = fluid.layers.conv3d_transpose(input=data, num_filters=2, filter_size=3) + + + + + + + + + + +.. _cn_api_fluid_layers_cos_sim: + +cos_sim +------------------------------- + +.. py:function:: paddle.fluid.layers.cos_sim(X, Y) + +余弦相似度运算符（Cosine Similarity Operator） + +.. math:: + + Out = \frac{X^{T}*Y}{\sqrt{X^{T}*X}*\sqrt{Y^{T}*Y}} + +输入X和Y必须具有相同的shape，除非输入Y的第一维为1(不同于输入X)，在计算它们的余弦相似度之前，Y的第一维会被broadcasted，以匹配输入X的shape。 + +输入X和Y都携带或者都不携带LoD(Level of Detail)信息。但输出仅采用输入X的LoD信息。 + +参数： + - **X** (Variable) - cos_sim操作函数的一个输入 + - **Y** (Variable) - cos_sim操作函数的第二个输入 + +返回：cosine(X,Y)的输出 + +返回类型：变量（Variable) + + + + + + + + + +.. _cn_api_fluid_layers_crf_decoding: + +crf_decoding +------------------------------- + +.. py:function:: paddle.fluid.layers.crf_decoding(input, param_attr, label=None) + +该函数读取由 ``linear_chain_crf`` 学习的emission feature weights（发射状态特征的权重）和 transition feature weights(转移特征的权重)。 +本函数实现了Viterbi算法，可以动态地寻找隐藏状态最可能的序列，该序列也被称为Viterbi路径（Viterbi path），从而得出的标注(tags)序列。 + +这个运算的结果会随着 ``Label`` 参数的有无而改变： + + 1. ``Label`` 非None的情况，在实际训练中时常发生。此时本函数会协同 ``chunk_eval`` 工作。本函数会返回一行形为[N X 1]的向量，其中值为0的部分代表该label不适合作为对应结点的标注，值为1的部分则反之。此类型的输出可以直接作为 ``chunk_eval`` 算子的输入 + + 2. 当没有 ``Label`` 时，该函数会执行标准decoding过程 + +（没有 ``Label`` 时）该运算返回一个形为 [N X 1]的向量，其中元素取值范围为 0 ~ 最大标注个数-1，分别为预测出的标注（tag）所在的索引。 + +参数： + - **input** (Variable)(LoDTensor，默认类型为 LoDTensor) — 一个形为 [N x D] 的LoDTensor，其中 N 是mini-batch的大小，D是标注（tag) 的总数。 该输入是 ``linear_chain_crf`` 的 unscaled emission weight matrix （未标准化的发射权重矩阵） + - **param_attr** (ParamAttr) — 参与训练的参数的属性 + - **label** (Variable)(LoDTensor，默认类型为 LoDTensor) — 形为[N x 1]的正确标注（ground truth）。 该项可选择传入。 有关该参数的更多信息，请详见上述描述 + +返回：(LoDTensor, LoDTensor)decoding结果。具体内容根据 ``Label`` 参数是否提供而定。请参照函数介绍来详细了解。 + +返回类型： Variable + + +**代码示例** + +.. code-block:: python + + crf_decode = layers.crf_decoding( + input=hidden, param_attr=ParamAttr(name="crfw")) + + + + + + + + + + + + +.. _cn_api_fluid_layers_crop: + +crop +------------------------------- + +.. py:function:: paddle.fluid.layers.crop(x, shape=None, offsets=None, name=None) + +根据偏移量（offsets）和形状（shape），裁剪输入张量。 + +**样例**： + +:: + + * Case 1: + Given + X = [[0, 1, 2, 0, 0] + [0, 3, 4, 0, 0] + [0, 0, 0, 0, 0]], + and + shape = [2, 2], + offsets = [0, 1], + output is: + Out = [[1, 2], + [3, 4]]. + * Case 2: + Given + X = [[0, 1, 2, 5, 0] + [0, 3, 4, 6, 0] + [0, 0, 0, 0, 0]], + and shape is tensor + shape = [[0, 0, 0] + [0, 0, 0]] + and + offsets = [0, 1], + + output is: + Out = [[1, 2, 5], + [3, 4, 6]]. + + +参数: + - **x** (Variable): 输入张量。 + - **shape** (Variable|list/tuple of integer) - 输出张量的形状由参数shape指定，它可以是一个变量/整数的列表/整数元组。如果是张量变量，它的秩必须与x相同。该方式适可用于每次迭代时候需要改变输出形状的情况。如果是整数列表/tupe，则其长度必须与x的秩相同 + - **offsets** (Variable|list/tuple of integer|None) - 指定每个维度上的裁剪的偏移量。它可以是一个Variable，或者一个整数list/tupe。如果是一个tensor variable，它的rank必须与x相同，这种方法适用于每次迭代的偏移量（offset）都可能改变的情况。如果是一个整数list/tupe，则长度必须与x的rank的相同，如果shape=None，则每个维度的偏移量为0。 + - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: 裁剪张量。 + +返回类型: 变量（Variable） + +抛出异常: 如果形状不是列表、元组或变量，抛出ValueError + + +**代码示例**: + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3, 5], dtype="float32") + y = fluid.layers.data(name="y", shape=[2, 3], dtype="float32") + crop = fluid.layers.crop(x, shape=y) + + + ## or + z = fluid.layers.data(name="z", shape=[3, 5], dtype="float32") + crop = fluid.layers.crop(z, shape=[2, 3]) + + + + + + + + + + +.. _cn_api_fluid_layers_cross_entropy: + +cross_entropy +------------------------------- + +.. py:function:: paddle.fluid.layers.cross_entropy(input, label, soft_label=False, ignore_index=-100) + +该函数定义了输入和标签之间的cross entropy(交叉熵)层。该函数支持standard cross-entropy computation（标准交叉熵损失计算） +以及soft-label cross-entropy computation（软标签交叉熵损失计算） + + 1. One-hot cross-entropy算法 + + soft_label = False, Label[i, 0] 指明样本i的类别所具的索引: + .. math:: + \\Y[i]=-log(X[i,Label[i]])\\ + + 2. Soft-label cross-entropy算法 + + soft_label = True, Label[i, j] 表明样本i对应类别j的soft label(软标签): + .. math:: + \\Y[i]= \sum_{j}-Label[i,j]*log(X[i,j])\\ + + **请确保采用此算法时识别为各软标签的概率总和为1** + + 3. One-hot cross-entropy with vecterized label（使用向量化标签的One-hot）算法 + + 作为 *2* 的特殊情况，当软类标签内部只有一个非零概率元素，且它的值为1，那么 *2* 算法降级为一种仅有one-hot标签的one-hot交叉熵 + + + + + +参数： + - **input** (Variable|list) – 一个形为[N x D]的二维tensor，其中N是batch大小，D是类别（class）数目。 这是由之前的operator计算出的概率，绝大多数情况下是由softmax operator得出的结果 + - **label** (Variable|list) – 一个二维tensor组成的正确标记的数据集(ground truth)。 当 ``soft_label`` 为False时，label为形为[N x 1]的tensor。 ``soft_label`` 为True时, label是形为 [N x D]的 tensor + - **soft_label** (bool) – 标志位，指明是否需要把给定的标签列表认定为软标签。默认为False。 + - **ignore_index** (int) – 指定一个被无视的目标值，并且这个值不影响输入梯度变化。仅在 ``soft_label`` 为False时生效。 默认值: -100 + +返回： 一个形为[N x 1]的二维tensor，承载了交叉熵损失 + +弹出异常： ``ValueError`` + + 1. 当 ``input`` 的第一维和 ``label`` 的第一维不相等时，弹出异常 + 2. 当 ``soft_label`` 值为True， 且 ``input`` 的第二维和 ``label`` 的第二维不相等时，弹出异常 + 3. 当 ``soft_label`` 值为False，且 ``label`` 的第二维不是1时，弹出异常 + + + +**代码示例** + +.. code-block:: python + + predict = fluid.layers.fc(input=net, size=classdim, act='softmax') + cost = fluid.layers.cross_entropy(input=predict, label=label) + + + + + + + + + + + + + +.. _cn_api_fluid_layers_ctc_greedy_decoder: + +ctc_greedy_decoder +------------------------------- + +.. py:function:: paddle.fluid.layers.ctc_greedy_decoder(input, blank, name=None) + +此op用于贪婪策略解码序列，步骤如下: + 1. 获取输入中的每一行的最大值索引，也就是numpy.argmax(input, axis=0)。 + 2. 对于step1结果中的每个序列，在两个空格之间合并重复部分（即合并重复的上一步中的到的索引值）并删除所有空格。 + + +简单举一个例子， + +:: + + 已知： + + input.data = [[0.6, 0.1, 0.3, 0.1], + [0.3, 0.2, 0.4, 0.1], + [0.1, 0.5, 0.1, 0.3], + [0.5, 0.1, 0.3, 0.1], + + [0.5, 0.1, 0.3, 0.1], + [0.2, 0.2, 0.2, 0.4], + [0.2, 0.2, 0.1, 0.5], + [0.5, 0.1, 0.3, 0.1]] + + input.lod = [[4, 4]] + + 计算过程： + + 1. 将argmax的运算结果应用于输入的第一个序列，即 input.data[0:4] 。 + 则得出的结果为[[0], [2], [1], [0]] + 2. 合并重复的索引值部分，删除空格，即为0的值。 + 则第一个输入序列对应的输出为：[[2], [1]] + + 最后 + + output.data = [[2], + [1], + [3]] + + output.lod = [[2, 1]] + + +参数: + - **input** (Variable) — (LoDTensor)，变长序列的概率，它是一个具有LoD信息的二维张量。它的形状是[Lp, num_classes + 1]，其中Lp是所有输入序列长度的和，num_classes是真正的类别。(不包括空白标签)。 + - **blank** (int) — Connectionist Temporal Classification (CTC) loss空白标签索引, 属于半开区间[0,num_classes + 1）。 + - **name** (str) — 此层的名称。可选。 + +返回： CTC贪婪解码结果是一个形为(Lp,1)的二维张量，其中Lp是所有输出序列的长度之和。如果结果中的所有序列都为空，则输出LoDTensor 为[-1]，其中LoD[[]] 形为[1,1]。 + +返回类型： 变量（Variable） + + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[8], dtype='float32') + + cost = fluid.layers.ctc_greedy_decoder(input=x, blank=0) + + + + + + + + + + + +.. _cn_api_fluid_layers_dice_loss: + +dice_loss +------------------------------- + +.. py:function:: paddle.fluid.layers.dice_loss(input, label, epsilon=1e-05) + +dice_loss是比较两批数据相似度，通常用于二值图像分割，即标签为二值。 + +dice_loss定义为: + +.. math:: + dice\_loss &= 1- \frac{2 * intersection\_area}{total\_rea}\\ + &= \frac{(total\_area−intersection\_area)−intersection\_area}{total\_area}\\ + &= \frac{union\_area−intersection\_area}{total\_area} + +参数: + - **input** (Variable) - rank>=2的预测。第一个维度是batch大小，最后一个维度是类编号。 + - **label** （Variable）- 与输入tensor rank相同的正确的标注数据（groud truth）。第一个维度是batch大小，最后一个维度是1。 + - **epsilon** (float) - 将会加到分子和分母上。如果输入和标签都为空，则确保dice为1。默认值:0.00001 + +返回: dice_loss shape为[1]。 + +返回类型: dice_loss(Variable) + +**代码示例** + +.. code-block:: python + + predictions = fluid.layers.softmax(x) + loss = fluid.layers.dice_loss(input=predictions, label=label, 2) + + + + + + + + + + + +.. _cn_api_fluid_layers_dropout: + +dropout +------------------------------- + +.. py:function:: Paddle.fluid.layers.dropout(x,dropout_prob,is_test=False,seed=None,name=None,dropout_implementation='downgrade_in_infer') + +dropout操作 + +丢弃或者保持x的每个元素独立。Dropout是一种正则化技术，通过在训练过程中阻止神经元节点间的联合适应性来减少过拟合。根据给定的丢弃概率dropout操作符随机将一些神经元输出设置为0，其他的仍保持不变。 + +参数： + - **x** (Variable)-输入张量 + - **dropout_prob** (float)-设置为0的单元的概率 + - **is_test** (bool)-显示是否进行测试用语的标记 + - **seed** (int)-Python整型，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。 + - **name** (str|None)-该层名称（可选）。如果设置为None,则自动为该层命名 + - **dropout_implementation** (string) - [‘downgrade_in_infer’(defauld)|’upscale_in_train’] + 其中: + 1.downgrade_in_infer(default), 在预测时减小输出结果 + + train: out = input * mask + + inference: out = input * dropout_prob + + (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ) + + 2.upscale_in_train, 增加训练时的结果 + + train: out = input * mask / ( 1.0 - dropout_prob ) + + inference: out = input + + (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ） + +dropout操作符可以从程序中移除，程序变得高效。 + +返回：与输入X，shape相同的张量 + +返回类型：变量 + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32") + droped = fluid.layers.dropout(x, dropout_prob=0.5) + + + + + + + + + +.. _cn_api_fluid_layers_dynamic_gru: + +dynamic_gru +------------------------------- + +.. py:function:: paddle.fluid.layers.dynamic_gru(input, size, param_attr=None, bias_attr=None, is_reverse=False, gate_activation='sigmoid', candidate_activation='tanh', h_0=None) + + + +**实现了Gated Recurrent Unit层。** + +详细理论介绍，请参照 `Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling`_。 + +.. _Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling: https://arxiv.org/abs/1412.3555 + + +公式如下： + +.. math:: + u_{t}=act_g(W_{ux}x_{t}+W_{uh}h_{t-1}+b_{u}) +.. math:: + r_{t}=act_g(W_{rx}x_{t}+W_{rh}h_{t-1}+b_{r}) +.. math:: + \widetilde{h_{t}}=act_{c}(W_{cx}x_{t}+W_{ch}(r_{t}\odot h_{t-1})+b_c) +.. math:: + h_t=(1-u_t)\odot h_{t-1}+u_t\odot \widetilde{h_t} + +其中， :math:`\odot` 为按元素将向量相乘。 :math:`act_g` 是更新门（update gate）和重置门（reset gate）的激励函数(activation)， 常为 :math:`sigmoid` 函数。 :math:`act_c` 是candidate hidden state(候选隐藏状态)的激励函数，常为 :math:`tanh` 。 + +注意 :math:`W_{ux}x_{t},W_{rx}x_{t},W_{cx}x_{t}` 这些在 input :math:`x_t` 上的操作不包括在该运算中。用户可以选择性地在GRU层之前使用FC层来进行这一操作。 + + + +参数: + - **input** (Variable) – dynamic_gru层的输入, 支持variable time length input sequence（可变时长输入序列）。 本变量底层的tensor是一个(T×3D)矩阵， 其中T是该mini-batch中总时间步数， D是隐藏状态的规模（hidden size）。 + - **size** (int) – GRU cell的维度 + - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重矩阵的参数属性。 + 注意： + - 该矩阵为一个（T X 3D）矩阵。其中D为隐藏状态的规模（hidden size） + - 该矩阵的所有元素由两部分组成。一是update gate和reset gate的权重，形为（D X 2D)，二是候选隐藏状态（candidate hidden state）的权重，形为 (D X D) + 如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一，则会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果param_attr未被初始化（即其构造函数未被设置），Xavier会负责初始化它。 默认值为None。 + - **bias_attr** (ParamAttr|bool|None) - GRU层bias的参数属性。该（1 X 3D）形的bias变量将会连结（concatenate）在update gate（更新门）、reset gate（重置门）、candidate calculations（候选隐藏状态计算）后。如果值为False，将没有bias会应用到上述三个过程中。如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一， ``dynamic_gru`` 会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果bias_attr未被初始化（即其构造函数未被设置），则它会被初始化为0。默认值为None。 + - **is_reverse** (bool) –是否计算反GRU(reversed GRU)，默认为False + - **gate_activation** (str) – update gate 和 reset gate的激励函数（activation）。 可选择[“sigmoid”, “tanh”, “relu”, “identity”]其一, 默认为 “sigmoid” + - **candidate_activation** (str) – candidate hidden state（候选隐藏状态）计算所需的激励函数（activation）。 可从[“sigmoid”, “tanh”, “relu”, “identity”]中选择, 默认为 “tanh” + - **h_0** (Variable) – 该函数参数为初始隐藏状态。若未赋值，则默认为0。它是一个 (N x D) tensor, 其中 N 为输入mini-batch的总时间步数， D 为 隐藏状态规模(hidden size) + + +返回： GRU的隐藏状态(hidden state)。形为（T X D），序列长度和输入相同。 + +返回类型: 变量（variable） + + +**代码示例** + +.. code-block:: python + + dict_dim, emb_dim = 128, 64 + data = fluid.layers.data(name='sequence', shape=[1], + dtype='int32', lod_level=1) + emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim]) + hidden_dim = 512 + x = fluid.layers.fc(input=emb, size=hidden_dim * 3) + hidden = fluid.layers.dynamic_gru(input=x, size=hidden_dim) + + + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_dynamic_lstm: + +dynamic_lstm +------------------------------- + +.. py:function:: paddle.fluid.layers.dynamic_lstm(input, size, h_0=None, c_0=None, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', dtype='float32', name=None) + +LSTM，即Long-Short Term Memory(长短期记忆)运算。 + +默认实现方式为diagonal/peephole连接(https://arxiv.org/pdf/1402.1128.pdf)，公式如下： + + +.. math:: + i_t=\sigma (W_{ix}x_{t}+W_{ih}h_{t-1}+W_{ic}c_{t-1}+b_i) +.. math:: + f_t=\sigma (W_{fx}x_{t}+W_{fh}h_{t-1}+W_{fc}c_{t-1}+b_f) +.. math:: + \widetilde{c_t}=act_g(W_{ct}x_{t}+W_{ch}h_{t-1}+b_{c}) +.. math:: + o_t=\sigma (W_{ox}x_{t}+W_{oh}h_{t-1}+W_{oc}c_{t}+b_o) +.. math:: + c_t=f_t\odot c_{t-1}+i_t\odot \widetilde{c_t} +.. math:: + h_t=o_t\odot act_h(c_t) + +W 代表了权重矩阵(weight matrix)，例如 :math:`W_{xi}` 是从输入门（input gate）到输入的权重矩阵, :math:`W_{ic}` ，:math:`W_{fc}` ， :math:`W_{oc}` 是对角权重矩阵(diagonal weight matrix)，用于peephole连接。在此实现方式中，我们使用向量来代表这些对角权重矩阵。 + +其中： + - :math:`b` 表示bias向量（ :math:`b_i` 是输入门的bias向量） + - :math:`σ` 是非线性激励函数（non-linear activations），比如逻辑sigmoid函数 + - :math:`i` ，:math:`f` ，:math:`o` 和 :math:`c` 分别为输入门(input gate)，遗忘门(forget gate)，输出门（output gate）,以及神经元激励向量（cell activation vector）这些向量和神经元输出激励向量（cell output activation vector） :math:`h` 有相同的大小。 + - :math:`⊙` 意为按元素将两向量相乘 + - :math:`act_g` , :math:`act_h` 分别为神经元(cell)输入、输出的激励函数(activation)。常常使用tanh函数。 + - :math:`\widetilde{c_t}` 也被称为候选隐藏状态(candidate hidden state)。可根据当前输入和之前的隐藏状态计算而得 + +将 ``use_peepholes`` 设为False来禁用 peephole 连接方法。 公式等详细信息请参考 http://www.bioinf.jku.at/publications/older/2604.pdf 。 + +注意， :math:`W_{xi}x_t, W_{xf}x_t, W_{xc}x_t,W_{xo}x_t` 这些在输入 :math:`x_t` 上的操作不包括在此运算中。用户可以在LSTM operator之前选择使用全连接运算。 + + + + +参数: + - **input** (Variable) (LoDTensor) - LodTensor类型，支持variable time length input sequence（时长可变的输入序列）。 该LoDTensor中底层的tensor是一个形为(T X 4D)的矩阵，其中T为此mini-batch上的总共时间步数。D为隐藏层的大小、规模(hidden size) + - **size** (int) – 4 * 隐藏层大小 + - **h_0** (Variable) – 最初的隐藏状态（hidden state），可选项。默认值为0。它是一个(N x D)张量，其中N是batch大小，D是隐藏层大小。 + - **c_0** (Variable) – 最初的神经元状态（cell state）， 可选项。 默认值0。它是一个(N x D)张量, 其中N是batch大小。h_0和c_0仅可以同时为None，不能只其中一个为None。 + - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重的参数属性。 + 注意： + - Weights = :math:`\{W_{ch}, W_{ih}, W_{fh}, W_{oh} \}` + - 形为(D x 4D), 其中D是hidden size（隐藏层规模） + + 如果它被设为None或者 ``ParamAttr`` 属性之一, dynamic_lstm会创建 ``ParamAttr`` 对象作为param_attr。如果没有对param_attr初始化（即构造函数没有被设置）， Xavier会负责初始化参数。默认为None。 + - **bias_attr** (ParamAttr|None) – 可学习的bias权重的属性, 包含两部分，input-hidden bias weights（输入隐藏层的bias权重）和 peephole connections weights（peephole连接权重）。如果 ``use_peepholes`` 值为 ``True`` ， 则意为使用peephole连接的权重。 + 另外： + - use_peepholes = False - Biases = :math:`\{ b_c,b_i,b_f,b_o \}` - 形为(1 x 4D)。 + - use_peepholes = True - Biases = :math:`\{ b_c,b_i,b_f,b_o,W_{ic},W_{fc},W_{oc} \}` - 形为 (1 x 7D)。 + + 如果它被设为None或 ``ParamAttr`` 的属性之一， ``dynamic_lstm`` 会创建一个 ``ParamAttr`` 对象作为bias_attr。 如果没有对bias_attr初始化（即构造函数没有被设置），bias会被初始化为0。默认值为None。 + - **use_peepholes** (bool) – （默认: True） 是否使用diagonal/peephole连接方式 + - **is_reverse** (bool) – （默认: False） 是否计算反LSTM(reversed LSTM) + - **gate_activation** (str) – （默认: "sigmoid"）应用于input gate（输入门），forget gate（遗忘门）和 output gate（输出门）的激励函数（activation），默认为sigmoid + - **cell_activation** (str) – （默认: tanh）用于神经元输出的激励函数(activation), 默认为tanh + - **candidate_activation** (str) – （默认: tanh）candidate hidden state（候选隐藏状态）的激励函数(activation), 默认为tanh + - **dtype** (str) – 即 Data type（数据类型）。 可以选择 [“float32”, “float64”]，默认为“float32” + - **name** (str|None) – 该层的命名，可选项。如果值为None, 将会自动对该层命名 + +返回：隐藏状态（hidden state），LSTM的神经元状态。两者都是（T x D）形，且LoD保持与输入一致 + +返回类型: 元组（tuple） + + +**代码示例** + +.. code-block:: python + + hidden_dim = 512 + forward_proj = fluid.layers.fc(input=input_seq, size=hidden_dim * 4, + bias_attr=False) + forward, _ = fluid.layers.dynamic_lstm( + input=forward_proj, size=hidden_dim * 4, use_peepholes=False) + + + + + + + + + + + + + +.. _cn_api_fluid_layers_dynamic_lstmp: + +dynamic_lstmp +------------------------------- +.. py:function:: paddle.fluid.layers.dynamic_lstmp(input, size, proj_size, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', proj_activation='tanh', dtype='float32', name=None) + +动态LSTMP层(Dynamic LSTMP Layer) + +LSTMP层(具有循环映射的LSTM)在LSTM层后有一个分离的映射层，从原始隐藏状态映射到较低维的状态，用来减少参数总数，减少LSTM计算复杂度，特别是输出单元相对较大的情况下。 `Long Short-Term Memory Recurrent Neural Network Architectures for Large Scale Acoustic Modeling `_ + +公式如下： + +.. math:: + + i_t & = \sigma(W_{ix}x_{t} + W_{ir}r_{t-1} + W_{ic}c_{t-1} + b_i)\\ + f_t & = \sigma(W_{fx}x_{t} + W_{fr}r_{t-1} + W_{fc}c_{t-1} + b_f)\\ + \tilde{c_t} & = act_g(W_{cx}x_t + W_{cr}r_{t-1} + b_c)\\ + o_t & = \sigma(W_{ox}x_{t} + W_{or}r_{t-1} + W_{oc}c_t + b_o)\\ + c_t & = f_t \odot c_{t-1} + i_t \odot \tilde{c_t}\\ + h_t & = o_t \odot act_h(c_t)\\ + r_t & = \overline{act_h}(W_{rh}h_t)\\ + + +在以上公式中： + - :math:`W` : 代表权重矩阵（例如 :math:`W_{xi}` 是输入门道输入的权重矩阵） + - :math:`W_{ic}` , :math:`W_{fc}` , :math:`W_{oc}` : peephole connections的对角权重矩阵。在我们的实现中，外面用向量代表这些对角权重矩阵 + - :math:`b` : 代表偏差向量（例如 :math:`b_{i}` 是输入偏差向量） + - :math:`\delta` : 激活函数，比如逻辑回归函数 + - :math:`i,f,o` 和 :math:`c` :分别代表输入门，遗忘门,输出门和cell激活函数向量，四者的大小和cell输出激活函数向量 :math:`h` 的四者大小相等 + - :math:`h` : 隐藏状态 + - :math:`r` : 隐藏状态的循环映射 + - :math:`\tilde{c_t}` : 候选隐藏状态 + - :math:`\odot` : 向量的元素状态生成 + - :math:`act_g` 和 :math:`act_h` : cell输入和cell输出激活函数，通常使用 :math:`tanh` + - :math:`\overline{act_h}` : 映射输出的激活函数，通常用 :math:`identity` 或等同的 :math:`act_h` + +将 ``use_peepholes`` 设置为False，断开窥视孔连接（peephole connection）。在此省略公式，详情请参照论文 `LONG SHORT-TERM MEMORY `_ 。 + +注意输入 :math:`x_{t}` 中的 :math:`W_{xi}x_{t},W_{xf}x_{t},W_{xc}x_{t},W_{xo}x_{t}` 不在此操作符中。用户选择在LSTMP层之前使用全链接层。 + +参数： + - **input** (Variable) - dynamic_lstmp层的输入，支持输入序列长度为变量的倍数。该变量的张量为一个矩阵，维度为（T X 4D），T为mini-batch的总时间步长，D是隐藏大小。 + - **size** (int) - 4*隐藏状态大小（hidden size） + - **proj_size** (int) - 投影输出的大小 + - **param_attr** (ParamAttr|None) - 可学习hidden-hidden权重和投影权重的参数属性。 + 说明: + - Hidden-hidden （隐藏状态到隐藏状态）权重 = :math:`\{ W_{ch},W_{ih},W_{fh},W_{oh} \}` + - hidden-hidden权重的权重矩阵为（P*4D），P是投影大小，D是隐藏大小。 + - 投影（Projection）权重 = :math:`\{ W_{rh} \}` + - 投影权重的shape为（D\*P） + + 如果设为None或者ParamAttr的一个属性，dynamic_lstm将创建ParamAttr为param_attr。如果param_attr的初始函数未设置，参数则初始化为Xavier。默认:None。 + - **bias_attr** (ParamAttr|None) - 可学习bias权重的bias属性，包含输入隐藏的bias权重和窥视孔连接权重（peephole connection）,前提是use_peepholes设为True。 + + 说明: + 1.use_peepholes = False + - Biases = { :math:`b_{c},b_{i},b_{f},b_{o}`}. + - 维度为（1*4D） + + 2.use_peepholes = True + - Biases = { :math:`b_{c},b_{i},b_{f},b_{o},W_{ic},W_{fc},W_{oc}`} + - 维度为（1*7D） + + 如果设置为None或者ParamAttr的一个属性，dynamic_lstm将创建ParamAttr为bias_attr。bias_attr的初始函数未设置，bias则初始化为0.默认：None。 + + - **use_peepholes** (bool) - 是否开启诊断/窥视孔链接，默认为True。 + - **is_reverse** (bool) - 是否计算反向LSTM，默认为False。 + - **gate_activation** (bool) - 输入门（input gate）、遗忘门（forget gate）和输出门（output gate）的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“sigmoid”。 + - **cell_activation** (str) - cell输出的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 + - **candidate_activation** (str) - 候选隐藏状态（candidate hidden state）的激活状态。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 + - **proj_activation** (str) - 投影输出的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。 + - **dtype** (str) - 数据类型。Choices = [“float32”，“float64”]，默认“float32”。 + - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。 + +返回：含有两个输出变量的元组，隐藏状态（hidden state）的投影和LSTMP的cell状态。投影的shape为（T*P），cell state的shape为（T*D），两者的LoD和输入相同。 + +返回类型：元组(tuple) + +**代码示例**： + +.. code-block:: python + + dict_dim, emb_dim = 128, 64 + data = fluid.layers.data(name='sequence', shape=[1], + dtype='int32', lod_level=1) + emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim]) + hidden_dim, proj_dim = 512, 256 + fc_out = fluid.layers.fc(input=emb, size=hidden_dim * 4, + act=None, bias_attr=None) + proj_out, _ = fluid.layers.dynamic_lstmp(input=fc_out, + size=hidden_dim * 4, + proj_size=proj_dim, + use_peepholes=False, + is_reverse=True, + cell_activation="tanh", + proj_activation="tanh") + + + + + + + + + + + +.. _cn_api_fluid_layers_edit_distance: + + +edit_distance +------------------------------- + +.. py:function:: Paddle.fluid.layers.edit_distance(input,label,normalized=True,ignored_tokens=None) + +编辑距离运算符 + +计算一批给定字符串及其参照字符串间的编辑距离。编辑距离也称Levenshtein距离，通过计算从一个字符串变成另一个字符串所需的最少操作步骤来衡量两个字符串的相异度。这里的操作包括插入、删除和替换。 + +比如给定假设字符串A=“kitten”和参照字符串B=“sitting”，从A变换成B编辑距离为3，至少需要两次替换和一次插入： + +“kitten”->“sitten”->“sittn”->“sitting” + +输入为LoDTensor,包含假设字符串（带有表示批尺寸的总数）和分离信息（具体为LoD信息）。并且批尺寸大小的参照字符串和输入LoDTensor的顺序保持一致。 + +输出包含批尺寸大小的结果，代表一对字符串中每个字符串的编辑距离。如果Attr(normalized)为真，编辑距离则处以参照字符串的长度。 + +参数： + - **input** (Variable)-假设字符串的索引 + - **label** (Variable)-参照字符串的索引 + - **normalized** (bool,默认为True)-表示是否用参照字符串的长度进行归一化 + - **ignored_tokens** (list,默认为None)-计算编辑距离前需要移除的token + - **name** (str)-该层名称，可选 + +返回：[batch_size,1]中序列到序列到编辑距离 + +返回类型：变量 + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[1], dtype='float32') + y = fluid.layers.data(name='y', shape=[1], dtype='float32') + cost = fluid.layers.edit_distance(input=x,label=y) + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_add: + +elementwise_add +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_add(x, y, axis=-1, act=None, name=None) + +逐元素相加算子 + +等式为： + +.. math:: + Out = X + Y + +- :math:`X` ：任意维度的张量（Tensor）. +- :math:`Y` ：一个维度必须小于等于X维度的张量（Tensor）。 +对于这个运算算子有2种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2: + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），则 ``axis`` 为 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾部尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。 + +参数： + - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 + - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由 ``MKLDNN`` 使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_div: + +elementwise_div +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_div(x, y, axis=-1, act=None, name=None) + +逐元素相除算子 + +等式是： + +.. math:: + Out = X / Y + +- :math:`X` ：任何尺寸的张量（Tensor）。 +- :math:`Y` ：尺寸必须小于或等于X尺寸的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。 + +参数： + - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 + - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_max: + +elementwise_max +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_max(x, y, axis=-1, act=None, name=None) +最大元素算子 + +等式是： + +.. math:: + Out = max(X, Y) + +- :math:`X` ：任何尺寸的张量（Tensor）。 +- :math:`Y` ：尺寸必须小于或等于X尺寸的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 + - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_min: + +elementwise_min +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_min(x, y, axis=-1, act=None, name=None) + +最小元素算子 + +等式是： + +.. math:: + Out = min(X, Y) + +- :math:`X` ：任何维数的张量（Tensor）。 +- :math:`Y` ：维数必须小于或等于X维数的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 + - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_mul: + +elementwise_mul +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_mul(x, y, axis=-1, act=None, name=None) + +逐元素相乘算子 + +等式是： + +.. math:: + Out = X \odot Y + +- **X** ：任何尺寸的张量（Tensor）。 +- **Y** ：尺寸必须小于或等于X尺寸的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** - （Tensor），元素op的第一个输入张量（Tensor）。 + - **y** - （Tensor），元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_pow: + +elementwise_pow +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_pow(x, y, axis=-1, act=None, name=None) + +逐元素幂运算算子 + +等式是： + +.. math:: + Out = X ^ Y + +- :math:`X` ：任何维数的张量（Tensor）。 +- :math:`Y` ：维数必须小于或等于X维数的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** （Tensor）- 元素op的第一个输入张量（Tensor）。 + - **y** （Tensor）- 元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_elementwise_sub: + +elementwise_sub +------------------------------- + +.. py:function:: paddle.fluid.layers.elementwise_sub(x, y, axis=-1, act=None, name=None) + +逐元素相减算子 + +等式是： + +.. math:: + Out = X - Y + +- **X** ：任何尺寸的张量（Tensor）。 +- **Y** ：尺寸必须小于或等于**X**尺寸的张量（Tensor）。 + +此运算算子有两种情况： + 1. :math:`Y` 的形状（shape）与 :math:`X` 相同。 + 2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。 + +对于情况2： + 1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。 + 2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。 + 3. 考虑到子序列， :math:`Y` 的大小为1的尾随尺寸将被忽略，例如shape（Y）=（2,1）=>（2）。 + +例如： + +.. code-block:: python + + shape(X) = (2, 3, 4, 5), shape(Y) = (,) + shape(X) = (2, 3, 4, 5), shape(Y) = (5,) + shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2 + shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1 + shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0 + shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0 + +输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** - （Tensor），元素op的第一个输入张量（Tensor）。 + - **y** - （Tensor），元素op的第二个输入张量（Tensor）。 + - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。 + - **use_mkldnn** （BOOLEAN）- （bool，默认为false）。由MKLDNN使用。 + - **act** （basestring | None）- 激活应用于输出。 + - **name** （basestring | None）- 输出的名称。 + +返回： 元素运算的输出。 + + + + + + + + + +.. _cn_api_fluid_layers_elu: + +elu +------------------------------- + +.. py:function:: paddle.fluid.layers.elu(x, alpha=1.0, name=None) + +ELU激活层（ELU Activation Operator） + +根据 https://arxiv.org/abs/1511.07289 对输入张量中每个元素应用以下计算。 + +.. math:: + \\out=max(0,x)+min(0,α∗(ex−1))\\ + +参数: + - x(Variable)- ELU operator的输入 + - alpha(FAOAT|1.0)- ELU的alpha值 + - name (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: ELU操作符的输出 + +返回类型: 输出(Variable) + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.elu(x, alpha=0.2) + + + + + + + +.. _cn_api_fluid_layers_embedding: + +embedding +------------------------------- + +.. py:function:: paddle.fluid.layers.embedding(input, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32') + +嵌入层(Embedding Layer) + +该层用于查找由输入提供的id在查找表中的嵌入矩阵。查找的结果是input里每个ID对应的嵌入矩阵。 +所有的输入变量都作为局部变量传入LayerHelper构造器 + +参数： + - **input** (Variable)-包含IDs的张量 + - **size** (tuple|list)-查找表参数的维度。应当有两个参数，一个代表嵌入矩阵字典的大小，一个代表每个嵌入向量的大小。 + - **is_sparse** (bool)-代表是否用稀疏更新的标志 + - **is_distributed** (bool)-是否从远程参数服务端运行查找表 + - **padding_idx** (int|long|None)-如果为 ``None`` ，对查找结果无影响。如果padding_idx不为空，表示一旦查找表中找到input中对应的 ``padding_idz``，则用0填充输出结果。如果 :math:`padding_{i}dx<0` ,在查找表中使用的 ``padding_idx`` 值为 :math:`size[0]+dim` 。 + - **param_attr** (ParamAttr)-该层参数 + - **dtype** (np.dtype|core.VarDesc.VarType|str)-数据类型：float32,float_16,int等。 + +返回：张量，存储已有输入的嵌入矩阵。 + +返回类型：变量(Variable) + +**代码示例**: + +.. code-block:: python + + dict_size = len(dataset.ids) + data = fluid.layers.data(name='ids', shape=[32, 32], dtype='float32') + fc = fluid.layers.embedding(input=data, size=[dict_size, 16]) + + + + + + + + + +.. _cn_api_fluid_layers_expand: + +expand +------------------------------- + +.. py:function:: paddle.fluid.layers.expand(x, expand_times, name=None) + +expand运算会按给定的次数对输入各维度进行复制（tile）运算。 您应该通过提供属性 ``expand_times`` 来为每个维度设置次数。 X的秩应该在[1,6]中。请注意， ``expand_times`` 的大小必须与X的秩相同。以下是一个用例： + +:: + + 输入(X) 是一个形状为[2, 3, 1]的三维张量（Tensor）: + + [ + [[1], [2], [3]], + [[4], [5], [6]] + ] + + 属性(expand_times): [1, 2, 2] + + 输出(Out) 是一个形状为[2, 6, 2]的三维张量（Tensor）: + + [ + [[1, 1], [2, 2], [3, 3], [1, 1], [2, 2], [3, 3]], + [[4, 4], [5, 5], [6, 6], [4, 4], [5, 5], [6, 6]] + ] + +参数: + - **x** (Variable)- 一个秩在[1, 6]范围中的张量（Tensor）. + - **expand_times** (list|tuple) - 每一个维度要扩展的次数. + +返回： expand变量是LoDTensor。expand运算后，输出（Out）的每个维度的大小等于输入（X）的相应维度的大小乘以 ``expand_times`` 给出的相应值。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[10], dtype='float32') + out = fluid.layers.expand(x=x, expand_times=[1, 2, 2]) + + + + + + + + + + +.. _cn_api_fluid_layers_fc: + +fc +------------------------------- + +.. py:function:: paddle.fluid.layers.fc(input, size, num_flatten_dims=1, param_attr=None, bias_attr=None, act=None, is_test=False, name=None) + + +**全连接层** + +该函数在神经网络中建立一个全连接层。 它可以同时将多个tensor作为自己的输入，并为每个输入的tensor创立一个变量，称为“权”（weights），等价于一个从每个输入单元到每个输出单元的全连接权矩阵。FC层用每个tensor和它对应的权相乘得到输出tensor。如果有多个输入tensor，那么多个乘法运算将会加在一起得出最终结果。如果 ``bias_attr`` 非空，则会新创建一个偏向变量（bias variable），并把它加入到输出结果的运算中。最后，如果 ``act`` 非空，它也会加入最终输出的计算中。 + +这个过程可以通过如下公式表现： + +.. math:: + + \\Out=Act(\sum^{N-1}_{i=0}X_iW_i+b) \\ + + +上述等式中： + - :math:`N` ：输入tensor的数目 + - :math:`X_i` : 输入的tensor + - :math:`W` ：该层创立的权 + - :math:`b` ：该层创立的bias参数 + - :math:`Act` : activation function(激励函数) + - :math:`Out` : 输出tensor + + +参数: + - **input** (Variable|list of Variable) – 该层的输入tensor(s)（张量），其维度至少是2 + - **size** (int) – 该层输出单元的数目 + - **num_flatten_dims** (int, default 1) – fc层可以接受一个维度大于2的tensor。此时， 它首先会被扁平化(flattened)为一个二维矩阵。 参数``num_flatten_dims`` 决定了输入tensor的flattened方式: 前 ``num_flatten_dims`` (包含边界，从1开始数) 个维度会被扁平化为最终矩阵的第一维 (维度即为矩阵的高), 剩下的 rank(X) - num_flatten_dims 维被扁平化为最终矩阵的第二维 (即矩阵的宽)。 例如， 假设X是一个五维tensor，其形可描述为(2, 3, 4, 5, 6), 且num_flatten_dims = 3。那么扁平化的矩阵形状将会如此： (2 x 3 x 4, 5 x 6) = (24, 30) + - **param_attr** (ParamAttr|list of ParamAttr, default None) – 该层可学习的参数/权的参数属性 + - **bias_attr** (ParamAttr|list of ParamAttr, default None) – 该层bias变量的参数属性。如果值为False， 则bias变量不参与输出单元运算。 如果值为None，bias变量被初始化为0。默认为 None。 + - **act** (str, default None) – 应用于输出的Activation（激励函数） + - **is_test** (bool) – 表明当前执行是否处于测试阶段的标志 + - **name** (str, default None) – 该层的命名 + + +返回：转换结果 + +返回类型: Variable + +弹出异常：``ValueError`` - 如果输入tensor的维度小于2 + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name="data", shape=[32, 32], dtype="float32") + fc = fluid.layers.fc(input=data, size=1000, act="tanh") + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_flatten: + +flatten +------------------------------- + +.. py:function:: paddle.fluid.layers.flatten(x, axis=1, name=None) + +将输入张量压扁成二维矩阵 + +例如： + +.. code-block:: text + + Case 1: + + 给定 + X.shape = (3, 100, 100, 4) + 且 + axis = 2 + 得到: + Out.shape = (3 * 100, 4 * 100) + + Case 2: + + 给定 + X.shape = (3, 100, 100, 4) + 且 + axis = 0 + 得到: + Out.shape = (1, 3 * 100 * 100 * 4) + +参数： + - **x** (Variable): 一个秩>=axis 的张量 + - **axis** (int)：指出应该将哪些输入维度(唯一的) flatten 到输出的外部维度。axis的值必须在[0,R]范围内，其中R是输入张量的秩。当 axis= 0 时，输出张量的形状为(1，(d_0 X d_1…)，其中输入张量的形状为(d_0, d_1，…)d_n)。 + - **name** (str|None)：此层的名称(可选)。如果没有设置，层将自动命名。 + +返回：Variable: 一个二维张量，它包含输入张量的内容，输入维数将沿给定轴flatten到输出的外部维度，剩余的输入维数flatten到输出的内部维数。 + +抛出异常： + - ValueError: 如果 x 不是一个变量 + - ValueError: 如果axis的范围不在 [0, rank(x)] + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[4, 4, 3], dtype="float32") + out = fluid.layers.flatten(x=x, axis=2) + + + + + + + + + + +.. _cn_api_fluid_layers_gather: + +gather +------------------------------- + +.. py:function:: paddle.fluid.layers.gather(input, index) + +收集层（gather layer） + +根据索引index获取X的最外层维度的条目，并将它们串连在一起。 + +.. math:: + Out=X[Index] + +:: + + X = [[1, 2], + [3, 4], + [5, 6]] + + Index = [1, 2] + + Then: + + Out = [[3, 4], + [5, 6]] + + +参数: + - **input** (Variable) - input 的rank >= 1。 + - **index** (Variable) - index的rank = 1。 + +返回： output (Variable) + +**代码示例** + +.. code-block:: python + + output = fluid.layers.gather(x, index) + + + + + + + + + +.. _cn_api_fluid_layers_gaussian_random: + +gaussian_random +------------------------------- + +.. py:function:: paddle.fluid.layers.gaussian_random(shape, mean=0.0, std=1.0, seed=0, dtype='float32') + +gaussian_random算子。 + +用于使用高斯随机生成器初始化张量（Tensor）。 + +参数： + - **shape** （tuple | list）- （vector ）随机张量的维数 + - **mean** （Float）- （默认值0.0）随机张量的均值 + - **std** （Float）- （默认值为1.0）随机张量的std + - **seed** （Int）- （默认值为 0）生成器随机生成种子。0表示使用系统范围的种子。注意如果seed不为0，则此运算符每次将始终生成相同的随机数 + - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出的数据类型。 + +返回： 输出高斯随机运算矩阵 + +返回类型： 输出（Variable） + +**代码示例：** + +.. code-block:: python + + out = layers.gaussian_random(shape=[20, 30]) + + + + + + + + +.. _cn_api_fluid_layers_gaussian_random_batch_size_like: + +gaussian_random_batch_size_like +------------------------------- + +.. py:function:: paddle.fluid.layers.gaussian_random_batch_size_like(input, shape, input_dim_idx=0, output_dim_idx=0, mean=0.0, std=1.0, seed=0, dtype='float32') + +用于使用高斯随机发生器初始化张量。分布的defalut均值为0.并且分布的defalut标准差（std）为1.用户可以通过输入参数设置mean和std。 + +参数： + - **input** （Variable）- 其input_dim_idx'th维度指定batch_size的张量（Tensor）。 + - **shape** （元组|列表）- 输出的形状。 + - **input_dim_idx** （Int）- 默认值0.输入批量大小维度的索引。 + - **output_dim_idx** （Int）- 默认值0.输出批量大小维度的索引。 + - **mean** （Float）- （默认值0.0）高斯分布的平均值（或中心值）。 + - **std** （Float）- （默认值 1.0）高斯分布的标准差（std或spread）。 + - **seed** （Int）- （默认为0）用于随机数引擎的随机种子。0表示使用系统生成的种子。请注意，如果seed不为0，则此运算符将始终每次生成相同的随机数。 + - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出数据的类型为float32，float_16，int等。 + +返回： 指定形状的张量将使用指定值填充。 + +返回类型： 输出（Variable）。 + + + +**代码示例：** + +.. code-block:: python + + input = layers.data(name="input", shape=[13, 11], dtype='float32') + + out = layers.gaussian_random_batch_size_like( + input, shape=[-1, 11], mean=1.0, std=2.0) + + + + + + +.. _cn_api_fluid_layers_get_tensor_from_selected_rows: + +get_tensor_from_selected_rows +------------------------------- + +.. py:function:: paddle.fluid.layers.get_tensor_from_selected_rows(x, name=None) + +:code:`Get Tensor From Selected Rows` 用于从选中行（Selected Rows）中获取张量 + +参数： + - **x** (Variable) - 输入，类型是SelectedRows + - **name** (basestring|None) - 输出的名称 + +返回： 输出类型为LoDTensor + +返回类型： out(Variable) + + + + + + + + + + + +.. _cn_api_fluid_layers_grid_sampler: + +grid_sampler +------------------------------- + +.. py:function:: paddle.fluid.layers.grid_sampler(x, grid, name=None) + +该操作使用基于flow field网格的双线性插值对输入X进行采样，通常由affine_grid生成。 + +形状为(N、H、W、2)的网格是由两个形状均为(N、H、W)的坐标(grid_x grid_y)连接而成的。 + +其中，grid_x是输入数据x的第四个维度(宽度维度)的索引，grid_y是第三维度(高维)的索引，最终得到4个最接近的角点的双线性插值值。 + +step 1： + + 得到(x, y)网格坐标，缩放到[0,h -1/W-1] + + grid_x = 0.5 * (grid[:, :, :, 0] + 1) * (W - 1) grid_y = 0.5 * (grid[:, :, :, 1] + 1) * (H - 1) + +step 2： + + 在每个[H, W]区域用网格(X, y)作为输入数据X的索引，并将双线性插值点值由4个最近的点表示。 + +.. code-block:: text + + wn ------- y_n ------- en + | | | + | d_n | + | | | + x_w --d_w-- grid--d_e-- x_e + | | | + | d_s | + | | | + ws ------- y_s ------- wn + + x_w = floor(x) // west side x coord + x_e = x_w + 1 // east side x coord + y_n = floor(y) // north side y coord + y_s = y_s + 1 // south side y coord + d_w = grid_x - x_w // distance to west side + d_e = x_e - grid_x // distance to east side + d_n = grid_y - y_n // distance to north side + d_s = y_s - grid_y // distance to south side + wn = X[:, :, y_n, x_w] // north-west point value + en = X[:, :, y_n, x_e] // north-east point value + ws = X[:, :, y_s, x_w] // south-east point value + es = X[:, :, y_s, x_w] // north-east point value + + + output = wn * d_e * d_s + en * d_w * d_s + + ws * d_e * d_n + es * d_w * d_n + +参数： + - **x** (Variable): 输入数据，形状为[N, C, H, W] + - **grid** (Variable): 输入网格张量，形状为[N, H, W, 2] + - **name** (str, default None): 该层的名称 + +返回： **out** (Variable): 输入X基于输入网格的bilnear插值计算结果，形状为[N, C, H, W] + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[3, 10, 32, 32], dtype='float32') + theta = fluid.layers.data(name='theta', shape=[3, 2, 3], dtype='float32') + grid = fluid.layers.affine_grid(input=theta, size=[3, 10, 32, 32]}) + out = fluid.layers.grid_sampler(x=x, grid=grid) + + + + + + + + + + +.. _cn_api_fluid_layers_group_norm: + +group_norm +------------------------------- + +.. py:function:: paddle.fluid.layers.group_norm(input, groups, epsilon=1e-05, param_attr=None, bias_attr=None, act=None, data_layout='NCHW', name=None) + +参考论文： `Group Normalization `_ + +参数： + - **input** (Variable)：输入张量变量 + - **groups** (int)：从 channel 中分离出来的 group 的数目 + - **epsilon** (float)：为防止方差除零，增加一个很小的值 + - **param_attr** (ParamAttr|None)：可学习标度的参数属性 :math:`g`,如果设置为False，则不会向输出单元添加标度。如果设置为0，偏差初始化为1。默认值:None + - **bias_attr** (ParamAttr|None)：可学习偏置的参数属性 :math:`b ` , 如果设置为False，则不会向输出单元添加偏置量。如果设置为零，偏置初始化为零。默认值:None。 + - **act** (str):将激活应用于输出的 group normalizaiton + - **data_layout** (string|NCHW): 只支持NCHW。 + - **name** (str):这一层的名称（可选） + +返回： Variable: 一个张量变量，它是对输入进行 group normalization 后的结果。 + +**代码示例：** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[8, 32, 32], + dtype='float32') + x = fluid.layers.group_norm(input=data, groups=4) + + + + + + + + + + +.. _cn_api_fluid_layers_gru_unit: + +gru_unit +------------------------------- + +.. py:function:: paddle.fluid.layers.gru_unit(input, hidden, size, param_attr=None, bias_attr=None, activation='tanh', gate_activation='sigmoid') + +GRU单元层。GRU执行步骤基于如下等式： + +.. math:: + u_t=actGate(xu_t+W_{u}h_{t-1}+b_u) +.. math:: + r_t=actGate(xr_t+W_{r}h_{t-1}+b_r) +.. math:: + m_t=actNode(xm_t+W_{c}dot(r_t,h_{t-1})+b_m) +.. math:: + h_t=dot((1-u_t),m_t)+dot(u_t,h_{t-1}) + +GRU单元的输入包括 :math:`z_t` ， :math:`h_{t-1}` 。在上述等式中， :math:`z_t` 会被分割成三部分： :math:`xu_t` 、 :math:`xr_t` 和 :math:`xm_t` 。 +这意味着要为一批输入实现一个全GRU层，我们需要采用一个全连接层，才能得到 :math:`z_t=W_{fc}x_t` 。 +:math:`u_t` 和 :math:`r_t` 分别代表了GRU神经元的update gates（更新门）和reset gates(重置门)。 +和LSTM不同，GRU少了一个门（它没有LSTM的forget gate）。但是它有一个叫做中间候选隐藏状态（intermediate candidate hidden output）的输出， +记为 :math:`m_t` 。 该层有三个输出： :math:`h_t, dot(r_t,h_{t-1})` 以及 :math:`u_t，r_t，m_t` 的连结(concatenation)。 + + + + +参数: + - **input** (Variable) – 经FC层变换后的当前步骤的输入值 + - **hidden** (Variable) – 从上一步而来的gru unit 隐藏状态值(hidden value) + - **size** (integer) – 输入数据的维度 + - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重矩阵的参数属性。 + 注意： + - 该权重矩阵形为 :math:`(T×3D)` ， :math:`D` 是隐藏状态的规模（hidden size） + - 该权重矩阵的所有元素由两部分组成， 一是update gate和reset gate的权重，形为 :math:`(D×2D)` ；二是候选隐藏状态（candidate hidden state）的权重矩阵，形为 :math:`(D×D)` + 如果该函数参数值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 param_attr。如果param_attr没有被初始化，那么会由Xavier来初始化它。默认值为None + - **bias_attr** (ParamAttr|bool|None) - GRU的bias变量的参数属性。形为 :math:`(1x3D)` 的bias连结（concatenate）在update gates（更新门），reset gates(重置门)以及candidate calculations（候选隐藏状态计算）中的bias。如果值为False，那么上述三者将没有bias参与运算。若值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 bias_attr。如果bias_attr没有被初始化，那它会被默认初始化为0。默认值为None。 + - **activation** (string) – 神经元 “actNode” 的激励函数（activation）类型。默认类型为‘tanh’ + - **gate_activation** (string) – 门 “actGate” 的激励函数（activation）类型。 默认类型为 ‘sigmoid’ + + +返回： hidden value（隐藏状态的值），reset-hidden value(重置隐藏状态值)，gate values(门值) + +返回类型: 元组（tuple） + + +**代码示例** + +.. code-block:: python + + # 假设我们现在有x_t_data和size=10的之前的隐藏层 + x_t = fluid.layers.fc(input=x_t_data, size=30) + hidden_val, r_h_val, gate_val = fluid.layers.gru_unit(input=x_t, + hidden = prev_hidden) + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_hard_sigmoid: + +hard_sigmoid +------------------------------- + +.. py:function:: paddle.fluid.layers.hard_sigmoid(x, slope=0.2, offset=0.5, name=None) + +HardSigmoid激活算子。 + +sigmoid的分段线性逼近(https://arxiv.org/abs/1603.00391)，比sigmoid快得多。 + +.. math:: + + \\out=\max(0,\min(1,slope∗x+shift))\\ + +斜率是正数。偏移量可正可负的。斜率和位移的默认值是根据上面的参考设置的。建议使用默认值。 + +参数： + - **x** (Variable) - HardSigmoid operator的输入 + - **slope** (FLOAT|0.2) -斜率 + - **offset** (FLOAT|0.5) - 偏移量 + - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 + + +**代码示例：** + + +.. code-block:: python + + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.hard_sigmoid(x, slope=0.3, offset=0.8) + + + + + + +.. _cn_api_fluid_layers_hash: + +hash +------------------------------- + +.. py:function:: paddle.fluid.layers.hash(input, hash_size, num_hash=1, name=None) + +将输入 hash 到一个整数，该数的值小于给定的 hash size + +我们使用的哈希算法是 xxHash - `Extremely fast hash algorithm `_ + +提供一简单的例子： + +.. code-block:: text + + 给出： + + # shape [2, 2] + input.data = [ + [[1], [2]], + [[3], [4]], + ] + + input.lod = [[0, 2]] + + hash_size = 10000 + + num_hash = 4 + + 然后: + + 哈希操作将这个二维input的所有数字作为哈希算法每次的输入。 + + 每个输入都将被哈希4次，最终得到一个长度为4的数组。 + + 数组中的每个值的范围从0到9999。 + + + + # shape [2, 4] + output.data = [ + [[9662], [9217], [1129], [8487]], + [[8310], [1327], [1654], [4567]], + ] + + output.lod = [[0, 2]] + +参数： + - **input** (Variable) - 输入变量是一个 one-hot 词。输入变量的维数必须是2。 + - **hash_size** (int) - 哈希算法的空间大小。输出值将保持在 :math:`[0, hash\_size - 1]` 范围内。 + - **num_hash** (int) - 哈希次数，默认为1。 + - **name** (str, default None) - 该层的名称 + +返回：哈希的结果变量，是一个lodtensor。 + +返回类型： Variable + +**代码示例：** + +.. code-block:: python + + word_dict = paddle.dataset.imdb.word_dict() + x = fluid.layers.data(shape[1], dtype='int32', lod_level=1) + out = fluid.layers.hash(input=x, num_hash=4, hash_size=1000) + + + + + + + + + +.. _cn_api_fluid_layers_hsigmoid: + +hsigmoid +------------------------------- + +.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None, path_table=None, path_code=None, is_custom=False, is_sparse=False) + +层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完全二叉树，也可以使用 ``is_custom`` 参数来传入自定义的树结构来实现层次化。 + +树中每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。 + +hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。 + +使用默认树结构，请参考 `Hierarchical Probabilistic Neural Network Language Model `_ 。 + +若要使用自定义树结构，请设置 ``is_custom`` 值为True。但在此之前，请完成以下几步部署： + +1.使用自定义词典来建立二叉树，每个叶结点都应该是词典中的单词 + +2.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径** 的映射，称之为路径表 ``path_table`` 参数 + +3.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径的编码(code)** 的映射。 编码code是指每次二分类的标签，1为真，0为假 + +4.现在我们的每个单词都已经有自己的路径和路径编码，当对于同一批输入进行操作时，你可以同时传入一批路径和路径编码进行运算。 + +参数: + - **input** (Variable) - 输入张量，shape为 ``[N×D]`` ,其中 ``N`` 是minibatch的大小，D是特征大小。 + - **label** (Variable) - 训练数据的标签。该tensor的shape为 ``[N×1]`` + - **num_classes** (int) - 类别的数量不能少于2。若使用默认树结构，该参数必须用户设置。当 ``is_custom=False`` 时，该项绝不能为None。反之，如果 ``is_custom=True`` ，它取值应为非叶节点的个数，来指明二分类实用的类别数目。 + - **param_attr** (ParamAttr|None) - 可学习参数/ hsigmoid权重的参数属性。如果将其设置为ParamAttr的一个属性或None，则将ParamAttr设置为param_attr。如果没有设置param_attr的初始化器，那么使用用Xavier初始化。默认值:没None。 + - **bias_attr** (ParamAttr|bool|None) - hsigmoid偏置的参数属性。如果设置为False，则不会向输出添加偏置。如果将其设置ParamAttr的一个属性或None，则将ParamAttr设置为bias_attr。如果没有设置bias_attr的初始化器，偏置将初始化为零。默认值:None。 + - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名。默认值:None。 + - **path_table** (Variable|None) – 存储每一批样本从词到根节点的路径。路径应为从叶至根方向。 ``path_table`` 和 ``path_code`` 应具有相同的形, 对于每个样本 i ，path_table[i]为一个类似np.array的结构，该数组内的每个元素都是其双亲结点权重矩阵的索引 + - **path_code** (Variable|None) – 存储每批样本的路径编码，仍然是按从叶至根方向。各样本路径编码批都由其各祖先结点的路径编码组成 + - **is_custom** (bool|False) – 使用用户自定义二叉树取代默认二叉树结构，如果该项为真， 请务必设置 ``path_table`` , ``path_code`` , ``num_classes`` , 否则就需要设置 num_classes + - **is_sparse** (bool|False) – 使用稀疏更新方式，而非密集更新。如果为真， W的梯度和输入梯度将会变得稀疏 + +返回: (LoDTensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1] + +返回类型: Out + + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[2], dtype='float32') + y = fluid.layers.data(name='y', shape=[1], dtype='int64') + out = fluid.layers.hsigmoid(input=x, label=y, num_classes=6) + + + + + + + + + + +.. _cn_api_fluid_layers_im2sequence: + +im2sequence +------------------------------- + +.. py:function:: paddle.fluid.layers.im2sequence(input, filter_size=1, stride=1, padding=0, input_image_size=None, out_stride=1, name=None) + +从输入张量中提取图像张量，与im2col相似，shape={input.batch_size * output_height * output_width, filter_size_H * filter_size_W * input.通道}。这个op使用filter / kernel扫描图像并将这些图像转换成序列。一个图片展开后的timestep的个数为output_height * output_width，其中output_height和output_width由下式计算: + + +.. math:: + output\_size=1+\frac{(2∗padding+img\_size−block\_size+stride-1}{stride} + +每个timestep的维度为 :math:`block\_y * block\_x * input.channels` 。 + +参数: + - **input** （Variable）- 输入张量，格式为[N, C, H, W] + - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个tuple，它必须包含两个整数(filter_size_H, filter_size_W)。否则，过滤器将是一个方阵。 + - **stride** (int|tuple) - 步长大小。如果stride是一个元组，它必须包含两个整数(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。 + - **padding** (int|tuple) - 填充大小。如果padding是一个元组，它可以包含两个整数(padding_H, padding_W)，这意味着padding_up = padding_down = padding_H和padding_left = padding_right = padding_W。或者它可以使用(padding_up, padding_left, padding_down, padding_right)来指示四个方向的填充。否则，标量填充意味着padding_up = padding_down = padding_left = padding_right = padding Default: padding = 0。 + - **input_image_size** (Variable) - 输入包含图像的实际大小。它的维度为[batchsize，2]。该参数可有可无，是用于batch推理。 + - **out_stride** (int|tuple) - 通过CNN缩放图像。它可有可无，只有当input_image_size不为空时才有效。如果out_stride是tuple，它必须包含(out_stride_H, out_stride_W)，否则，out_stride_H = out_stride_W = out_stride。 + - **name** (int) - 该layer的名称，可以忽略。 + +返回： LoDTensor shaoe为{batch_size * output_height * output_width, filter_size_H * filter_size_W * input.channels}。如果将输出看作一个矩阵，这个矩阵的每一行都是一个序列的step。 + +返回类型: output + +:: + + Given: + + x = [[[[ 6. 2. 1.] + [ 8. 3. 5.] + [ 0. 2. 6.]] + + [[ 2. 4. 4.] + [ 6. 3. 0.] + [ 6. 4. 7.]]] + + [[[ 6. 7. 1.] + [ 5. 7. 9.] + [ 2. 4. 8.]] + + [[ 1. 2. 1.] + [ 1. 3. 5.] + [ 9. 0. 8.]]]] + + x.dims = {2, 2, 3, 3} + + And: + + filter = [2, 2] + stride = [1, 1] + padding = [0, 0] + + Then: + + output.data = [[ 6. 2. 8. 3. 2. 4. 6. 3.] + [ 2. 1. 3. 5. 4. 4. 3. 0.] + [ 8. 3. 0. 2. 6. 3. 6. 4.] + [ 3. 5. 2. 6. 3. 0. 4. 7.] + [ 6. 7. 5. 7. 1. 2. 1. 3.] + [ 7. 1. 7. 9. 2. 1. 3. 5.] + [ 5. 7. 2. 4. 1. 3. 9. 0.] + [ 7. 9. 4. 8. 3. 5. 0. 8.]] + + output.dims = {8, 8} + + output.lod = [[4, 4]] + + +**代码示例** + +.. code-block:: python + + output = fluid.layers.im2sequence( + input=layer, stride=[1, 1], filter_size=[2, 2]) + + + + + + + + + + +.. _cn_api_fluid_layers_image_resize: + +image_resize +------------------------------- + +.. py:function:: paddle.fluid.layers.image_resize(input, out_shape=None, scale=None, name=None, resample='BILINEAR', actual_shape=None) + +调整一批图片的大小 + +输入张量的shape为(num_batch, channels, in_h, in_w)，并且调整大小只适用于最后两个维度(高度和宽度)。 + +支持重新取样方法: + + BILINEAR：双线性插值 + + NEAREST：最近邻插值 + +参数: + - **input** (Variable) - 图片调整层的输入张量，这是一个shape=4的张量(num_batch, channels, in_h, in_w) + - **out_shape** (list|tuple|Variable|None) - 图片调整层的输出，shape为(out_h, out_w)。默认值:None + - **scale** (float|None)-输入的高度或宽度的乘数因子 。 out_shape和scale至少要设置一个。out_shape的优先级高于scale。默认值:None + - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 + - **resample** (str) - 重采样方法。目前只支持“双线性”。默认值:双线性插值 + - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`actual_shape` 而不是 :code:`out_shape` 。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值:None + + +返回： 4维tensor，shape为 (num_batches, channls, out_h, out_w). + +返回类型: 变量（variable） + +抛出异常： + - :code:`TypeError` - out_shape应该是一个列表、元组或变量。 + - :code:`TypeError` - actual_shape应该是变量或None + - :code:`ValueError` - image_resize的"resample"只能是"BILINEAR"或"NEAREST"。 + - :code:`ValueError` - out_shape 和 scale 不能为 None + - :code:`ValueError` - out_shape 的长度必须为 2 + +**代码示例** + +.. code-block:: python + + out = fluid.layers.image_resize(input, out_shape=[12, 12], resample="NEAREST") + + + + + + + + + + + + +.. _cn_api_fluid_layers_image_resize_short: + +image_resize_short +------------------------------- + +.. py:function:: paddle.fluid.layers.image_resize_short(input, out_short_len, resample='BILINEAR') + +调整一批图片的大小。输入图像的短边将被调整为给定的out_short_len 。输入图像的长边按比例调整大小，最终图像的长宽比保持不变。 + +参数: + - **input** (Variable) - 图像调整图层的输入张量，这是一个4维的形状张量(num_batch, channels, in_h, in_w)。 + - **out_short_len** (int) - 输出图像的短边长度。 + - **resample** (str) - resample方法，默认为双线性插值。 + +返回： 4维张量，shape为(num_batch, channls, out_h, out_w) + +返回类型: 变量（variable） + + + + + + + + + + + +.. _cn_api_fluid_layers_l2_normalize: + +l2_normalize +------------------------------- + +.. py:function:: paddle.fluid.layers.l2_normalize(x,axis,epsilon=1e-12,name=None) + +L2正则（L2 normalize Layer） + +该层用欧几里得距离之和对维轴的x归一化。对于1-D张量（系数矩阵的维度固定为0），该层计算公式如下： + +.. math:: + + y=\frac{x}{\sqrt{\sum x^{2}+epsion}} + +对于x多维的情况，该函数分别对维度轴上的每个1-D切片单独归一化 + +参数： + - **x** (Variable|list)- l2正则层（l2_normalize layer）的输入 + - **axis** (int)-运用归一化的轴。如果轴小于0，归一化的维是rank(X)+axis。-1是最后维 + - **epsilon** (float)-epsilon用于避免分母为0，默认值为1e-10 + - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名 + + 返回：输出张量，同x的维度一致 + + 返回类型：变量 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name="data", + shape=(3, 17, 13), + dtype="float32") + normed = fluid.layers.l2_normalize(x=data, axis=1) + + + + + + + + + +.. _cn_api_fluid_layers_label_smooth: + +label_smooth +------------------------------- + +.. py:function:: paddle.fluid.layers.label_smooth(label, prior_dist=None, epsilon=0.1, dtype='float32', name=None) + +标签平滑是一种对分类器层进行正则化的机制，称为标签平滑正则化(LSR)。 + + +由于直接优化正确标签的对数似然可能会导致过拟合，降低模型的适应能力，因此提出了标签平滑的方法来降低模型置信度。 +标签平滑使用标签 :math:`y` 自身和一些固定模式随机分布变量 :math:`\mu` 。对 :math:`k` 标签，我们有： + +.. math:: + \tilde{y_k} = (1 - \epsilon) * y_k + \epsilon * \mu_k, + +其中 :math:`1-\epsilon` 和 :math:`\epsilon` 分别是权重， :math:`\tilde{y_k}` 是平滑后的标签。 通常μ 使用均匀分布 + + +查看更多关于标签平滑的细节 https://arxiv.org/abs/1512.00567 + +参数： + - **label** （Variable） - 包含标签数据的输入变量。 标签数据应使用 one-hot 表示。 + - **prior_dist** （Variable） - 用于平滑标签的先验分布。 如果未提供，则使用均匀分布。 prior_dist的shape应为 :math:`(1，class\_num)` 。 + - **epsilon** （float） - 用于混合原始真实分布和固定分布的权重。 + - **dtype** （np.dtype | core.VarDesc.VarType | str） - 数据类型：float32，float_64，int等。 + - **name** （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名图层。 + +返回：张量变量, 包含平滑后的标签 + +返回类型: Variable + +**代码示例** + +.. code-block:: python + + label = layers.data(name="label", shape=[1], dtype="float32") + one_hot_label = layers.one_hot(input=label, depth=10) + smooth_label = layers.label_smooth( + label=one_hot_label, epsilon=0.1, dtype="float32") + + + + + + + + + +.. _cn_api_fluid_layers_layer_norm: + +layer_norm +------------------------------- + +.. py:function:: paddle.fluid.layers.layer_norm(input, scale=True, shift=True, begin_norm_axis=1, epsilon=1e-05, param_attr=None, bias_attr=None, act=None, name=None) + +假设特征向量存在于维度 ``begin_norm_axis ... rank (input）`` 上，计算大小为 ``H`` 的特征向量a在该维度上的矩统计量，然后使用相应的统计量对每个特征向量进行归一化。 之后，如果设置了 ``scale`` 和 ``shift`` ，则在标准化的张量上应用可学习的增益和偏差以进行缩放和移位。 + +请参考 `Layer Normalization `_ + +公式如下 + +.. math:: + \\\mu=\frac{1}{H}\sum_{i=1}^{H}a_i\\ +.. math:: + \\\sigma=\sqrt{\frac{1}{H}\sum_i^H{(a_i-\mu)^2}}\\ +.. math:: + \\h=f(\frac{g}{\sigma}(a-\mu) + b)\\ + +- :math:`\alpha` : 该层神经元输入总和的向量表示 +- :math:`H` : 层中隐藏的神经元个数 +- :math:`g` : 可训练的缩放因子参数 +- :math:`b` : 可训练的bias参数 + + +参数: + - **input** （Variable） - 输入张量变量。 + - **scale** （bool） - 是否在归一化后学习自适应增益g。默认为True。 + - **shift** （bool） - 是否在归一化后学习自适应偏差b。默认为True。 + - **begin_norm_axis** （int） - ``begin_norm_axis`` 到 ``rank（input）`` 的维度执行规范化。默认1。 + - **epsilon** （float） - 添加到方差的很小的值，以防止除零。默认1e-05。 + - **param_attr** （ParamAttr | None） - 可学习增益g的参数属性。如果 ``scale`` 为False，则省略 ``param_attr`` 。如果 ``scale`` 为True且 ``param_attr`` 为None，则默认 ``ParamAttr`` 将作为比例。如果添加了 ``param_attr``， 则将其初始化为1。默认None。 + - **bias_attr** （ParamAttr | None） - 可学习偏差的参数属性b。如果 ``shift`` 为False，则省略 ``bias_attr`` 。如果 ``shift`` 为True且 ``param_attr`` 为None，则默认 ``ParamAttr`` 将作为偏差。如果添加了 ``bias_attr`` ，则将其初始化为0。默认None。 + - **act** （str） - 激活函数。默认 None + - **name** （str） - 该层的名称， 可选的。默认为None，将自动生成唯一名称。 + +返回： 标准化后的结果 + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 32, 32], + dtype='float32') + x = fluid.layers.layer_norm(input=data, begin_norm_axis=1) + + + + + + + + + +.. _cn_api_fluid_layers_leaky_relu: + +leaky_relu +------------------------------- + +.. py:function:: paddle.fluid.layers.leaky_relu(x, alpha=0.02, name=None) + +LeakyRelu 激活函数 + +.. math:: out=max(x,α∗x) + +参数: + - **x** (Variable) - LeakyRelu Operator的输入 + - **alpha** (FLOAT|0.02) - 负斜率，值很小。 + - **name** (str|None) - 此层的名称(可选)。如果设置为None，该层将被自动命名。 + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[2,3,16,16], dtype="float32") + y = fluid.layers.leaky_relu(x, alpha=0.01) + + + + + + + +.. _cn_api_fluid_layers_linear_chain_crf: + +linear_chain_crf +------------------------------- + +.. py:function:: paddle.fluid.layers.linear_chain_crf(input, label, param_attr=None) + +线性链条件随机场（Linear Chain CRF） + +条件随机场定义间接概率图，节点代表随机变量，边代表两个变量之间的依赖。CRF学习条件概率 :math:`P\left ( Y|X \right )` ， :math:`X = \left ( x_{1},x_{2},...,x_{n} \right )` 是结构性输入，:math:`Y = \left ( y_{1},y_{2},...,y_{n} \right )` 为输入标签。 + +线性链条件随机场（Linear Chain CRF)是特殊的条件随机场（CRF），有利于序列标注任务。序列标注任务不为输入设定许多条件依赖。唯一的限制是输入和输出必须是线性序列。因此类似CRF的图是一个简单的链或者线，也就是线性链随机场（linear chain CRF）。 + +该操作符实现了线性链条件随机场（linear chain CRF）的前向——反向算法。详情请参照 http://www.cs.columbia.edu/~mcollins/fb.pdf 和 http://cseweb.ucsd.edu/~elkan/250Bwinter2012/loglinearCRFs.pdf。 + + +长度为L的序列s的概率定义如下： + +.. math:: + + P(s) = (1/Z) exp(a_{s_1} + b_{s_L} + sum_{l=1}^L x_{s_l} + sum_{l=2}^L w_{s_{l-1},s_l}) + + +其中Z是正则化值，所有可能序列的P(s)之和为1，x是线性链条件随机场（linear chain CRF）的发射（emission）特征权重。 + +线性链条件随机场最终输出mini-batch每个训练样本的条件概率的对数 + + + 1.这里 :math:`x` 代表Emission + + 2.Transition的第一维度值，代表起始权重，这里用 :math:`a` 表示 + + 3.Transition的下一维值，代表末尾权重，这里用 :math:`b` 表示 + + 4.Transition剩下的值，代表转移权重，这里用 :math:`w` 表示 + + 5.Label用 :math:`s` 表示 + + + + +**注意：** + + 1.条件随机场（CRF）的特征函数由发射特征(emission feature）和转移特征（transition feature）组成。发射特征（emission feature）权重在调用函数前计算，而不在函数里计算。 + + 2.由于该函数对所有可能序列的进行全局正则化，发射特征（emission feature）权重应是未缩放的。因此如果该函数带有发射特征（emission feature），并且发射特征是任意非线性激活函数的输出，则请勿调用该函数。 + + 3.Emission的第二维度必须和标记数字（tag number）相同 + +参数： + - **input** (Variable，LoDTensor，默认float类型LoDTensor) - 一个二维LoDTensor，shape为[N*D]，N是mini-batch的大小，D是总标记数。线性链条件随机场的未缩放发射权重矩阵 + - **input** (Tensor，默认float类型LoDTensor) - 一个二维张量，shape为[(D+2)*D]。linear_chain_crf操作符的可学习参数。更多详情见operator注释 + - **label** (Variable，LoDTensor，默认int64类型LoDTensor） - shape为[N*10的LoDTensor，N是mini-batch的总元素数 + - **param_attr** (ParamAttr) - 可学习参数的属性 + +返回： + output(Variable，Tensor，默认float类型Tensor)：shape为[N*D]的二维张量。Emission的指数。这是前向计算中的中间计算结果，在后向计算中还会复用 + + output(Variable，Tensor，默认float类型Tensor)：shape为[(D+2)*D]的二维张量。Transition的指数。这是前向计算中的中间计算结果，在后向计算中还会复用 + + output(Variable,Tensor，默认float类型Tensor)：mini-batch每个训练样本的条件概率的对数。这是一个shape为[S*1]的二维张量，S是mini-batch的序列数。注：S等同于mini-batch的序列数。输出不再是LoDTensor + +返回类型：output（Variable） + + + + + + + + + + + + +.. _cn_api_fluid_layers_lod_reset: + +lod_reset +------------------------------- + +.. py:function:: paddle.fluid.layers.lod_reset(x, y=None, target_lod=None) + + +设定x的LoD为y或者target_lod。如果提供y，首先将y.lod指定为目标LoD,否则y.data将指定为目标LoD。如果未提供y，目标LoD则指定为target_lod。如果目标LoD指定为Y.data或target_lod，只提供一层LoD。 + +:: + + + * 例1: + + 给定一级LoDTensor x: + x.lod = [[ 2, 3, 1 ]] + x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + x.dims = [6, 1] + + target_lod: [4, 2] + + 得到一级LoDTensor: + out.lod = [[4, 2]] + out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + out.dims = [6, 1] + + * 例2: + + 给定一级LoDTensor x: + x.lod = [[2, 3, 1]] + x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + x.dims = [6, 1] + + y是张量（Tensor）: + y.data = [[2, 4]] + y.dims = [1, 3] + + 得到一级LoDTensor: + out.lod = [[2, 4]] + out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + out.dims = [6, 1] + + * 例3: + + 给定一级LoDTensor x: + x.lod = [[2, 3, 1]] + x.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + x.dims = [6, 1] + + y是二级LoDTensor: + y.lod = [[2, 2], [2, 2, 1, 1]] + y.data = [[1.1], [2.1], [3.1], [4.1], [5.1], [6.1]] + y.dims = [6, 1] + + 得到一个二级LoDTensor: + out.lod = [[2, 2], [2, 2, 1, 1]] + out.data = [[1.0], [2.0], [3.0], [4.0], [5.0], [6.0]] + out.dims = [6, 1] + +参数： + - **x** (Variable)-输入变量，可以为Tensor或者LodTensor + - **y** (Variable|None)-若提供，输出的LoD则衍生自y + - **target_lod** (list|tuple|None)-一层LoD，y未提供时作为目标LoD + +返回：输出变量，该层指定为LoD + +返回类型：变量 + +抛出异常：``TypeError`` - 如果y和target_lod都为空 + +**代码示例**： + +.. code-block:: python + + x = layers.data(name='x', shape=[10]) + y = layers.data(name='y', shape=[10, 20], lod_level=2) + out = layers.lod_reset(x=x, y=y) + + + + + + + + + +.. _cn_api_fluid_layers_log: + +log +------------------------------- + +.. py:function:: paddle.fluid.layers.log(x, name=None) + + +给定输入张量，计算其每个元素的自然对数 + +.. math:: + \\Out=ln(x)\\ + + +参数: + - **x** (Variable) – 输入张量 + - **name** (str|None, default None) – 该layer的名称，如果为None，自动命名 + +返回：给定输入张量计算自然对数 + +返回类型: 变量（variable） + + +**代码示例** + +.. code-block:: python + + output = fluid.layers.log(x) + + + + + + + + + + + +.. _cn_api_fluid_layers_log_loss: + +log_loss +------------------------------- + +.. py:function:: paddle.fluid.layers.log_loss(input, label, epsilon=0.0001, name=None) + +**负log loss层** + +该层对输入的预测结果和目的标签进行计算，返回负log loss损失值。 + +.. math:: + + Out = -label * \log{(input + \epsilon)} - (1 - label) * \log{(1 - input + \epsilon)} + + +参数: + - **input** (Variable|list) – 形为[N x 1]的二维张量, 其中N为batch大小。 该输入是由先前运算得来的概率集。 + - **label** (Variable|list) – 形为[N x 1]的二维张量，承载着正确标记的数据， 其中N为batch大小。 + - **epsilon** (float) – epsilon + - **name** (string) – log_loss层的名称 + +返回： 形为[N x 1]的二维张量，承载着负log_loss值 + +返回类型: 变量（Variable） + + +**代码示例** + +.. code-block:: python + + prob = fluid.layers.sigmoid(net) + cost = fluid.layers.log_loss(input=prob, label=label) + + + + + + + + + + + +.. _cn_api_fluid_layers_logical_and: + +logical_and +------------------------------- + +.. py:function:: paddle.fluid.layers.logical_and(x, y, out=None, name=None) + +logical_and算子 + +它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： + +.. math:: + Out = X \&\& Y + +参数： + - **x** （Variable）- （LoDTensor）logical_and运算符的左操作数 + - **y** （Variable）- （LoDTensor）logical_and运算符的右操作数 + - **out** （Tensor）- 输出逻辑运算的张量。 + - **name** （basestring | None）- 输出的名称。 + +返回： (LoDTensor)n-dim bool张量。每个元素的计算公式： :math:`Out = X \&\& Y` + +返回类型： 输出（Variable）。 + + +**代码示例：** + +.. code-block:: python + + left = fluid.layers.data( + name='left', shape=[1], dtype='int32') + right = fluid.layers.data( + name='right', shape=[1], dtype='int32') + result = fluid.layers.logical_and(x=left, y=right) + + + + + + + + + +.. _cn_api_fluid_layers_logical_not: + +logical_not +------------------------------- + +.. py:function:: paddle.fluid.layers.logical_not(x, out=None, name=None) + +logical_not算子 + +它在X上以元素方式操作，并返回Out。X和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： + +.. math:: + Out = !X + +参数： + - **x** （Variable）- （LoDTensor）logical_not运算符的操作数 + - **out** （Tensor）- 输出逻辑运算的张量。 + - **name** （basestring | None）- 输出的名称。 + +返回： (LoDTensor)n维布尔张量。 + +返回类型： 输出（Variable）。 + + +**代码示例：** + +.. code-block:: python + + left = fluid.layers.data( + name='left', shape=[1], dtype='int32') + result = fluid.layers.logical_not(x=left) + + + + + + + +.. _cn_api_fluid_layers_logical_or: + +logical_or +------------------------------- + +.. py:function:: paddle.fluid.layers.logical_or(x, y, out=None, name=None) + +logical_or算子 + +它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： + +.. math:: + Out = X || Y + +参数： + - **x** （Variable）- （LoDTensor）logical_or运算符的左操作数 + - **y** （Variable）- （LoDTensor）logical_or运算符的右操作数 + - **out** （Tensor）- 输出逻辑运算的张量。 + - **name** （basestring | None）- 输出的名称。 + +返回： (LoDTensor)n维布尔张量。每个元素的计算公式： :math:`Out = X || Y` + +返回类型： 输出（Variable）。 + + + +**代码示例：** + +.. code-block:: python + + + left = fluid.layers.data( + name='left', shape=[1], dtype='int32') + right = fluid.layers.data( + name='right', shape=[1], dtype='int32') + result = fluid.layers.logical_or(x=left, y=right) + + + + + + +.. _cn_api_fluid_layers_logical_xor: + +logical_xor +------------------------------- + +.. py:function:: paddle.fluid.layers.logical_xor(x, y, out=None, name=None) + +logical_xor算子 + +它在X和Y上以元素方式操作，并返回Out。X、Y和Out是N维布尔张量（Tensor）。Out的每个元素的计算公式为： + +.. math:: + Out = (X || Y) \&\& !(X \&\& Y) + +参数： + - **x** （Variable）- （LoDTensor）logical_xor运算符的左操作数 + - **y** （Variable）- （LoDTensor）logical_xor运算符的右操作数 + - **out** （Tensor）- 输出逻辑运算的张量。 + - **name** （basestring | None）- 输出的名称。 + +返回： (LoDTensor)n维布尔张量。 + +返回类型： 输出（Variable）。 + + + +**代码示例：** + +.. code-block:: python + + left = fluid.layers.data( + name='left', shape=[1], dtype='int32') + right = fluid.layers.data( + name='right', shape=[1], dtype='int32') + result = fluid.layers.logical_xor(x=left, y=right) + + + + + + +.. _cn_api_fluid_layers_lrn: + +lrn +------------------------------- + +.. py:function:: paddle.fluid.layers.lrn(input, n=5, k=1.0, alpha=0.0001, beta=0.75, name=None) + +局部响应正则层（Local Response Normalization Layer） + +该层对局部输入区域正则化，执行一种侧向抑制（lateral inhibition）。 + +公式如下： + +.. math:: + + Output(i,x,y) = Input(i,x,y)/\left ( k+\alpha \sum_{j=max(0,c-n/2)}^{min(C,c+n/2)}(Input(j,x,y))^2 \right )^\beta + +在以上公式中： + - :math:`n` ：累加的通道数 + - :math:`k` ：位移（避免除数为0） + - :math:`\alpha` ： 缩放参数 + - :math:`\beta` ： 指数参数 + +参考 : `ImageNet Classification with Deep Convolutional Neural Networks `_ + +参数： + - **input** （Variable）- 该层输入张量，输入张量维度必须为4 + - **n** (int，默认5） - 累加哦的通道数 + - **k** （float，默认1.0）- 位移（通常为正数，避免除数为0） + - **alpha** （float，默认1e-4）- 缩放参数 + - **beta** （float，默认0.75）- 指数 + - **name** （str，默认None）- 操作符名 + +抛出异常: + - ``ValueError`` - 如果输入张量的阶不为4 + +返回：张量，存储转置结果 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data( + name="data", shape=[3, 112, 112], dtype="float32") + lrn = fluid.layers.lrn(input=data) + + + + + + + + + + + +.. _cn_api_fluid_layers_lstm: + +lstm +------------------------------- + +.. py:function:: paddle.fluid.layers.lstm(input, init_h, init_c, max_len, hidden_size, num_layers, dropout_prob=0.0, is_bidirec=False, is_test=False, name=None, default_initializer=None, seed=-1) + +如果您的设备是GPU，本op将使用cudnn LSTM实现 + +一个没有 peephole 连接的四门长短期记忆网络。在前向传播中，给定迭代的输出ht和单元输出ct可由递归输入ht-1、单元输入ct-1和上一层输入xt计算，给定矩阵W、R和bias bW, bR由下式计算: + +.. math:: + + i_t = \sigma(W_{ix}x_{t} + W_{ih}h_{t-1} + bx_i + bh_i)\\ + f_t = \sigma(W_{fx}x_{t} + W_{fh}h_{t-1} + bx_f + bh_f)\\ + o_t = \sigma(W_{ox}x_{t} + W_{oh}h_{t-1} + bx_o + bh_o)\\ + \tilde{c_t} = tanh(W_{cx}x_t + W_{ch}h_{t-1} + bx_c + bh_c)\\ + c_t = f_t \odot c_{t-1} + i_t \odot \tilde{c_t}\\ + h_t = o_t \odot tanh(c_t) + +公式中： + - W 项表示权重矩阵(e.g. :math:`W_{ix}` 是从输入门到输入的权重矩阵) + - b 项表示偏差向量( :math:`b_{xi}` 和 :math:`b_{hi}` 是输入门的偏差向量) + - sigmoid 是 logistic sigmoid 函数 + - i、f、o、c 分别为输入门、遗忘门、输出门和激活向量，它们的大小与 cell 输出激活向量h相同。 + - :math:`\odot` 是向量的元素乘积 + - tanh是激活函数 + - :math:`\tilde{c_t}` 也称为候选隐藏状态，它是根据当前输入和之前的隐藏状态来计算的 + - sigmoid的计算公式为：sigmoid(x) = 1 / (1 + e^-x) + - \*表示点乘，X表示矩阵乘 + +参数： + - **input** (Variable) - LSTM 输入张量，形状必须为(seq_len x，batch_size，x，input_size) + - **init_h** (Variable) – LSTM的初始隐藏状态，是一个有形状的张量(num_layers，x，batch_size，x，hidden_size)如果is_bidirec = True，形状应该是(num_layers*2，x， batch_size， x， hidden_size) + - **init_c** (Variable) - LSTM的初始状态。这是一个有形状的张量(num_layers， x， batch_size， x， hidden_size)如果is_bidirec = True，形状应该是(num_layers*2， x， batch_size， x， hidden_size) + - **max_len** (int) – LSTM的最大长度。输入张量的第一个 dim 不能大于max_len + - **hidden_size** (int) - LSTM的隐藏大小 + - **num_layers** (int) – LSTM的总层数 + - **dropout_prob** (float|0.0) – dropout prob，dropout 只在 rnn 层之间工作，而不是在时间步骤之间。dropout 不作用于最后的 rnn 层的 rnn 输出中 + - **is_bidirec** (bool) – 是否是双向的 + - **is_test** (bool) – 是否在测试阶段 + - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 + - **default_initializer** (Initialize|None) – 在哪里使用初始化器初始化权重，如果没有设置，将进行默认初始化。 + - **seed** (int) – LSTM中dropout的Seed，如果是-1,dropout将使用随机Seed + +返回： + - LSTM hidden的结果：形状(seq_len x batch_size x hidden_size)如果is_bidirec设置为True,形状为(seq_len x batch_sze hidden_size * 2) + - last_h(Tensor): LSTM最后一步的隐藏状态，形状为(num_layers x batch_size x hidden_size)；如果is_bidirec设置为True，形状为(num_layers*2 x batch_size x hidden_size) + - last_c(Tensor)： LSTM最后一步的cell状态，形状为(num_layers x batch_size x hidden_size)；如果is_bidirec设置为True，形状为(num_layers*2 x batch_size x hidden_size) + +**代码示例：** + +.. code-block:: python + + input = embedding + batch_size = 20 + max_len = 100 + dropout_prob = 0.2 + input_size = 100 + hidden_size = 150 + num_layers = 1 + init_hidden1 = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0, stop_grad=False) + init_cell1 = layers.fill_constant( [num_layers, batch_size, hidden_size], 'float32', 0.0, stop_grad=False) + + rnn_out, last_h, last_c = layers.lstm( input, init_h, init_c, max_len, dropout_prob, input_size, hidden_size, num_layers) + + + + + + + + + + + + +.. _cn_api_fluid_layers_lstm_unit: + +lstm_unit +------------------------------- + +.. py:function:: paddle.fluid.layers.lstm_unit(x_t, hidden_t_prev, cell_t_prev, forget_bias=0.0, param_attr=None, bias_attr=None, name=None) + +Lstm unit layer + +lstm步的等式： + +.. math:: + + i_{t} &= \sigma \left ( W_{x_{i}}x_{t}+W_{h_{i}}h_{t-1}+b_{i} \right ) \\ + f_{t} &= \sigma \left ( W_{x_{f}}x_{t}+W_{h_{f}}h_{t-1}+b_{f} \right ) \\ + c_{t} &= f_{t}c_{t-1}+i_{t}tanh\left ( W_{x_{c}}x_{t} +W_{h_{c}}h_{t-1}+b_{c}\right ) \\ + o_{t} &= \sigma \left ( W_{x_{o}}x_{t}+W_{h_{o}}h_{t-1}+b_{o} \right ) \\ + h_{t} &= o_{t}tanh \left ( c_{t} \right ) + +lstm单元的输入包括 :math:`x_{t}` ， :math:`h_{t-1}` 和 :math:`c_{t-1}` 。:math:`h_{t-1}` 和 :math:`c_{t-1}` 的第二维应当相同。在此实现过程中，线性转换和非线性转换分离。以 :math:`i_{t}` 为例。线性转换运用到fc层，等式为： + +.. math:: + + L_{i_{t}} = W_{x_{i}}x_{t} + W_{h_{i}}h_{t-1} + b_{i} + +非线性转换运用到lstm_unit运算，方程如下： + +.. math:: + + i_{t} = \sigma \left ( L_{i_{t}} \right ) + +该层有 :math:`h_{t}` 和 :math:`o_{t}` 两个输出。 + +参数： + - **x_t** (Variable) - 当前步的输入值，二维张量，shape为 M x N ，M是批尺寸，N是输入尺寸 + - **hidden_t_prev** (Variable) - lstm单元的隐藏状态值，二维张量，shape为 M x S，M是批尺寸，N是lstm单元的大小 + - **cell_t_prev** (Variable) - lstm单元的cell值，二维张量，shape为 M x S ，M是批尺寸，N是lstm单元的大小 + - **forget_bias** (Variable) - lstm单元的遗忘bias + - **param_attr** (ParamAttr|None) - 可学习hidden-hidden权重的擦参数属性。如果设为None或者ParamAttr的一个属性，lstm_unit创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数初始化为Xavier。默认：None + - **bias_attr** (ParamAttr|None) - 可学习bias权重的bias属性。如果设为False，输出单元中则不添加bias。如果设为None或者ParamAttr的一个属性，lstm_unit创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认：None + - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名 + +返回：lstm单元的hidden(隐藏状态)值和cell值 + +返回类型：tuple（元组） + +抛出异常: + - ``ValueError`` - ``x_t``，``hidden_t_prev`` 和 ``cell_t_prev`` 的阶不为2，或者 ``x_t`` ，``hidden_t_prev`` 和 ``cell_t_prev`` 的第一维不一致，或者 ``hidden_t_prev`` 和 ``cell_t_prev`` 的第二维不一致 + +**代码示例**： + +.. code-block:: python + + x_t = fluid.layers.fc(input=x_t_data, size=10) + prev_hidden = fluid.layers.fc(input=prev_hidden_data, size=30) + prev_cell = fluid.layers.fc(input=prev_cell_data, size=30) + hidden_value, cell_value = fluid.layers.lstm_unit(x_t=x_t, + hidden_t_prev=prev_hidden, + cell_t_prev=prev_cell) + + + + + + + + + + + +.. _cn_api_fluid_layers_margin_rank_loss: + +margin_rank_loss +------------------------------- + +.. py:function:: paddle.fluid.layers.margin_rank_loss(label, left, right, margin=0.1, name=None) + +margin rank loss（差距排序损失）层。在排序问题中，它可以比较传进来的 ``left`` 得分和 ``right`` 得分。 + +可用如下等式定义： + +.. math:: + rank\_loss = max(0, -label * (left - right) + margin) + + +参数: + - **label** (Variable) – 表明是否左元素排名要高于右元素 + - **left** (Variable) – 左元素排序得分 + - **right** (Variable) – 右元素排序得分 + - **margin** (float) – 指定固定的得分差 + - **name** (str|None) – 可选项，该层的命名。如果为None, 该层将会被自动命名 + +返回： 排序损失 + +返回类型: 变量（Variable） + +抛出异常: + - ``ValueError`` - ``label`` , ``left`` , ``right`` 有一者不为Variable类型时，抛出此异常 + +**代码示例** + +.. code-block:: python + + label = fluid.layers.data(name="label", shape=[4, 1], dtype="float32") + left = fluid.layers.data(name="left", shape=[4, 1], dtype="float32") + right = fluid.layers.data(name="right", shape=[4, 1], dtype="float32") + out = fluid.layers.margin_rank_loss(label, left, right) + + + + + + + + + + + +.. _cn_api_fluid_layers_matmul: + + + +matmul +------------------------------- + +.. py:function:: paddle.fluid.layers.matmul(x, y, transpose_x=False, transpose_y=False, alpha=1.0, name=None) + +对两个张量进行矩阵相乘 + +当前输入的张量可以为任意阶，但当任意一个输入的阶数大于3时，两个输入的阶必须相等。 +实际的操作取决于x,y的维度和 ``transpose_x`` , ``transpose_y`` 的标记值。具体如下： + +- 如果transpose值为真，则对应 ``tensor`` 的最后两维将被转置。如：x是一个shape=[D]的一阶张量，那么x在非转置形式中为[1,D]，在转置形式中为[D,1],而y则相反，在非转置形式中作为[D,1]，在转置形式中作为[1,D]。 + +- 转置后，这两个`tensors`将为 2-D 或 n-D ,并依据下列规则进行矩阵相乘： + - 如果两个都是2-D，则同普通矩阵一样进行矩阵相乘 + - 如果任意一个是n-D，则将其视为驻留在最后两个维度的矩阵堆栈，并在两个张量上应用支持广播的批处理矩阵乘法。 + +**注意，如果原始张量x或y的秩为1且没有转置，则在矩阵乘法之后，前置或附加维度1将被移除。** + + +参数： + - **x** (Variable)-输入变量，类型为Tensor或LoDTensor + - **y** (Variable)-输入变量，类型为Tensor或LoDTensor + - **transpose_x** (bool)-相乘前是否转置x + - **transpose_y** (bool)-相乘前是否转置y + - **alpha** (float)-输出比例。默认为1.0 + - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名 + +返回：张量乘积变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + # 以下是解释输入和输出维度的示例 + # x: [B, ..., M, K], y: [B, ..., K, N] + fluid.layers.matmul(x, y) # out: [B, ..., M, N] + + # x: [B, M, K], y: [B, K, N] + fluid.layers.matmul(x, y) # out: [B, M, N] + + # x: [B, M, K], y: [K, N] + fluid.layers.matmul(x, y) # out: [B, M, N] + + # x: [M, K], y: [K, N] + fluid.layers.matmul(x, y) # out: [M, N] + + # x: [B, M, K], y: [K] + fluid.layers.matmul(x, y) # out: [B, M] + + # x: [K], y: [K] + fluid.layers.matmul(x, y) # out: [1] + + # x: [M], y: [N] + fluid.layers.matmul(x, y, True, True) # out: [M, N] + + + + + + + + + +.. _cn_api_fluid_layers_maxout: + +maxout +------------------------------- + +.. py:function:: paddle.fluid.layers.maxout(x, groups, name=None) + +假设输入形状为(N, Ci, H, W)，输出形状为(N, Co, H, W)，则 :math:`Co=Ci/groups` 运算公式如下: + +.. math:: + + y_{si+j} &= \max_k x_{gsi + sk + j} \\ + g &= groups \\ + s &= \frac{input.size}{num\_channels} \\ + 0 \le &i < \frac{num\_channels}{groups} \\ + 0 \le &j < s \\ + 0 \le &k < groups + + +请参阅论文: + - Maxout Networks: http://www.jmlr.org/proceedings/papers/v28/goodfellow13.pdf + - Multi-digit Number Recognition from Street View Imagery using Deep Convolutional Neural Networks: https://arxiv.org/pdf/1312.6082v4.pdf + +参数： + - **x** (Variable) - (tensor) maxout算子的输入张量。输入张量的格式为NCHW。其中N为 batch size ，C为通道数，H和W为feature的高和宽 + - **groups** （INT）- 指定输入张量将被分成多少组“通道维数”。输出通道的数量以组为单位。 + - **name** (basestring|None) - 输出的名称 + +返回：Tensor，maxout算子的输出张量。输出张量的格式也是NCHW。其中N为 batch size，C为通道数，H和W为特征的高和宽。 + +返回类型：out（variable） + + + + + + + + + + +.. _cn_api_fluid_layers_mean: + +mean +------------------------------- + +.. py:function:: paddle.fluid.layers.mean(x, name=None) + +mean算子计算X中所有元素的平均值 + +参数： + - **x** (Variable)- (Tensor) 均值运算的输入。 + - **name** (basestring | None)- 输出的名称。 + +返回： 均值运算输出张量（Tensor） + +返回类型： Variable + + + + + + + + + + +.. _cn_api_fluid_layers_mean_iou: + +mean_iou +------------------------------- + +.. py:function:: paddle.fluid.layers.mean_iou(input, label, num_functiones) + +均值IOU（Mean Intersection-Over-Union）是语义图像分割中的常用的评价指标之一，它首先计算每个语义类的IOU，然后计算类之间的平均值。定义如下: + + .. math:: IOU = \frac{true_{positive}}{true_{positive}+false_{positive}+false_{negative}} + +在一个混淆矩阵中累积得到预测值，然后从中计算均值-IOU。 + +参数: + - **input** (Variable) - 类型为int32或int64的语义标签的预测结果张量。 + - **label** (Variable) - int32或int64类型的真实label张量。它的shape应该与输入相同。 + - **num_classes** (int) - 标签可能的类别数目。 + +返回: 张量，shape为[1]， 代表均值IOU。out_wrong(变量):张量，shape为[num_classes]。每个类别中错误的个数。out_correct(变量):张量，shape为[num_classes]。每个类别中的正确个数。 + +返回类型: mean_iou(Variable) + +**代码示例**: + +.. code-block:: python + + iou, wrongs, corrects = fluid.layers.mean_iou(predict, label, num_classes) + + + + + + + + + +.. _cn_api_fluid_layers_merge_selected_rows: + +merge_selected_rows +------------------------------- + +.. py:function:: paddle.fluid.layers.merge_selected_rows(x, name=None) + +**实现合并选中行（row）操作** + +该运算用于合并（值相加）输入张量中重复的行。输出行没有重复的行，并且按值从小到大顺序重新对行排序。 + +:: + + 例如： + + 输入: + X.rows = [0, 5, 5, 4, 19] + X.height = 20 + X.value = [[1, 1] [2, 2] [3, 3] [4, 4] [6, 6]] + + + 输出： + Out.row is [0, 4, 5, 19] + Out.height is 20 + Out.value is: [[1, 1] [4, 4] [5, 5] [6, 6]] + + + +参数: + - x (Variable) – 输入类型为SelectedRows, 选中行有可能重复 + - name (basestring|None) – 输出变量的命名 + +返回: 输出类型为SelectedRows，并且选中行不会重复 + +返回类型: 变量（Variable） + + + + + + + + + + + +.. _cn_api_fluid_layers_mul: + +mul +------------------------------- + +.. py:function:: paddle.fluid.layers.mul(x, y, x_num_col_dims=1, y_num_col_dims=1, name=None) + +mul算子 +此运算是用于对输入X和Y执行矩阵乘法。 +等式是： + +.. math:: + Out = X * Y + +输入X和Y都可以携带LoD（详细程度）信息。但输出仅与输入X共享LoD信息。 + +参数： + - **x** (Variable)- (Tensor) 乘法运算的第一个输入张量。 + - **y** (Variable)- (Tensor) 乘法运算的第二个输入张量。 + - **x_num_col_dims** （int）- 默认值1， 可以将具有两个以上维度的张量作为输入。如果输入X是具有多于两个维度的张量，则输入X将先展平为二维矩阵。展平规则是：前 ``num_col_dims`` 将被展平成最终矩阵的第一个维度（矩阵的高度），其余的 rank(X) - num_col_dims 维度被展平成最终矩阵的第二个维度（矩阵的宽度）。结果是展平矩阵的高度等于X的前 ``x_num_col_dims`` 维数的乘积，展平矩阵的宽度等于X的最后一个秩（x）- ``num_col_dims`` 个剩余维度的维数的乘积。例如，假设X是一个五维张量，形状为（2,3,4,5,6）。 则扁平化后的张量具有的形即为 （2x3x4,5x6）=（24,30）。 + - **y_num_col_dims** （int）- 默认值1， 可以将具有两个以上维度的张量作为输入。如果输入Y是具有多于两个维度的张量，则Y将首先展平为二维矩阵。 ``y_num_col_dims`` 属性确定Y的展平方式。有关更多详细信息，请参阅 ``x_num_col_dims`` 的注释。 + - **name** (basestring | None)- 输出的名称。 + +返回： 乘法运算输出张量（Tensor）. + +返回类型： 输出(Variable)。 + + + + + + + + + + +.. _cn_api_fluid_layers_multiplex: + +multiplex +------------------------------- + +.. py:function:: paddle.fluid.layers.multiplex(inputs, index) + +引用给定的索引变量，该层从输入变量中选择行构造Multiplex变量。 + +假设有 :math:`m` 个输入变量，:math:`I_{i}` 代表第i个输入变量，而且 :math:`i` is in :math:`[0,m)` 。 + +所有输入变量都是具有相同形状的张量 :math:`[d_0,d_1, ... ,d_R]` 。 + +请注意，输入张量的秩应至少为2。每个输入变量将被视为形状为 :math:`[M，N]` 的二维矩阵，其中 :math:`M` 表示 :math:`d0` ，N表示 :math:`d_1 * d_2 * ... * d_R` 。 + +设 :math:`I_{i}[j]` 为第i个输入变量的第j行。 给定的索引变量是具有形状[M，1]的2-D张量。 设 :math:`ID[i]` 为索引变量的第i个索引值。 然后输出变量将是一个形状为 :math:`[d_0,d_1, ... ,d_R]` 的张量。 + +如果将输出张量视为具有形状[M，N]的2-D矩阵,并且令O[i]为矩阵的第i行，则O[i]等于 :math:`I_{ID}[i][i]` + +- Ids: 索引张量 +- X[0 : N - 1]: 输出的候选张量度(N >= 2). +- 对于从 0 到 batchSize-1 的每个索引i，输出是第（Ids [i]） 张量的第i行 + +对于第i行的输出张量： + +.. math:: + \\y[i]=x_k[i]\\ + +其中 :math:`y` 为输出张量， :math:`x_k` 为第k个输入张量，并且 :math:`k=Ids[i]` 。 + +参数: + - **inputs** （list） - 要从中收集的变量列表。所有变量的形状相同，秩至少为2 + - **index** （Variable） - Tensor ，索引变量为二维张量，形状[M, 1]，其中M为批大小。 + +返回：multiplex 张量 + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + + x1 = fluid.layers.data(name='x1', shape=[4], dtype='float32') + x2 = fluid.layers.data(name='x2', shape=[4], dtype='float32') + index = fluid.layers.data(name='index', shape=[1], dtype='int32') + out = fluid.layers.multiplex(inputs=[x1, x2], index=index) + + + + + + + + + + +.. _cn_api_fluid_layers_nce: + +nce +------------------------------- + +.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None, sampler='uniform', custom_dist=None, seed=0, is_sparse=False) + +计算并返回噪音对比估计（ noise-contrastive estimation training loss）。 +`请参考 See Noise-contrastive estimation: A new estimation principle for unnormalized statistical models +`_ +该operator默认使用均匀分布进行抽样。 + +参数: + - **input** (Variable) - 输入变量 + - **label** (Variable) - 标签 + - **num_total_classes** (int) - 所有样本中的类别的总数 + - **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0 + - **param_attr** (ParamAttr|None) - :math:`可学习参数/nce权重` 的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None + - **bias_attr** (ParamAttr|bool|None) - nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None + - **num_neg_samples** (int) - 负样例的数量。默认值是10 + - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名 + - **sampler** (str) – 取样器，用于从负类别中进行取样。可以是 ‘uniform’, ‘log_uniform’ 或 ‘custom_dist’。 默认 ‘uniform’ + - **custom_dist** (float[]) – 一个 float[] 并且它的长度为 ``num_total_classes`` 。 如果取样器类别为‘custom_dist’，则使用此参数。 custom_dist[i] 是第i个类别被取样的概率。默认为 None + - **seed** (int) – 取样器使用的seed。默认为0 + - **is_sparse** (bool) – 标志位，指明是否使用稀疏更新, :math:`weight@GRAD` 和 :math:`bias@GRAD` 会变为 SelectedRows + +返回： nce loss + +返回类型: 变量（Variable） + + +**代码示例** + +.. code-block:: python + + window_size = 5 + words = [] + for i in xrange(window_size): + words.append(layers.data( + name='word_{0}'.format(i), shape=[1], dtype='int64')) + + dict_size = 10000 + label_word = int(window_size / 2) + 1 + + embs = [] + for i in xrange(window_size): + if i == label_word: + continue + + emb = layers.embedding(input=words[i], size=[dict_size, 32], + param_attr='emb.w', is_sparse=True) + embs.append(emb) + + embs = layers.concat(input=embs, axis=1) + loss = layers.nce(input=embs, label=words[label_word], + num_total_classes=dict_size, param_attr='nce.w', + bias_attr='nce.b') + + #使用custom distribution + dist = fluid.layers.assign(input=np.array([0.05,0.5,0.1,0.3,0.05]).astype("float32")) + loss = layers.nce(input=embs, label=words[label_word], + num_total_classes=5, param_attr='nce.w', + bias_attr='nce.b', + num_neg_samples=3, + sampler="custom_dist", + custom_dist=dist) + + + + + + + + + + +.. _cn_api_fluid_layers_one_hot: + +one_hot +------------------------------- + +.. py:function:: paddle.fluid.layers.one_hot(input, depth) + +该层创建输入指数的one-hot表示 + +参数： + - **input** (Variable)-输入指数，最后维度必须为1 + - **depth** (scalar)-整数，定义one-hot维度的深度 + +返回：输入的one-hot表示 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + label = layers.data(name="label", shape=[1], dtype="float32") + one_hot_label = layers.one_hot(input=label, depth=10) + + + + + + + + + +.. _cn_api_fluid_layers_pad: + +pad +------------------------------- + +.. py:function:: paddle.fluid.layers.pad(x, paddings, pad_value=0.0, name=None) + +在张量上加上一个由 ``pad_value`` 给出的常数值，填充宽度由 ``paddings`` 指定。 +其中，维度 ``i`` 中 ``x`` 内容前填充的值个数用 ``paddings[i]`` 表示，维度 ``i`` 中 ``x`` 内容后填充的值个数用 ``paddings[i+1]`` 表示。 + +一个例子: + +:: + + Given: + + x = [[1, 2], [3, 4]] + + paddings = [0, 1, 1, 2] + + pad_value = 0 + + Return: + + out = [[0, 1, 2, 0, 0] + [0, 3, 4, 0, 0] + [0, 0, 0, 0, 0]] + + +参数: + - **x** (Variable) — —输入张量变量。 + - **paddings** (list) — 一个整数列表。按顺序填充在每个维度上填充元素。 ``padding`` 长度必须是 ``rank(x)×2`` + - **pad_value** (float) — 用来填充的常量值。 + - **name** (str|None) — 这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回： 填充后的张量变量 + +返回类型： 变量（Variable） + + +**代码示例** + +.. code-block:: python + + out = fluid.layers.pad( + x=x, paddings=[0, 1, 1, 2], pad_value=0.) + + + + + + + + + + +.. _cn_api_fluid_layers_pad2d: + +pad2d +------------------------------- + +.. py:function:: paddle.fluid.layers.pad2d(input, paddings=[0, 0, 0, 0], mode='constant', pad_value=0.0, data_format='NCHW', name=None) + +依照 paddings 和 mode 属性对图像进行2维 ``pad``,如果mode是 ``reflection``，则paddings[0]和paddings[1]必须不大于height-1。宽度维数具有相同的条件。 + +例如： + +.. code-block:: text + + 假设X是输入图像: + + X = [[1, 2, 3], + [4, 5, 6]] + + Case 0: + paddings = [0, 1, 2, 3], + mode = 'constant' + pad_value = 0 + Out = [[0, 0, 1, 2, 3, 0, 0, 0] + [0, 0, 4, 5, 6, 0, 0, 0] + [0, 0, 0, 0, 0, 0, 0, 0]] + + Case 1: + paddings = [0, 1, 2, 1], + mode = 'reflect' + Out = [[3, 2, 1, 2, 3, 2] + [6, 5, 4, 5, 6, 5] + [3, 2, 1, 2, 3, 2]] + + Case 2: + paddings = [0, 1, 2, 1], + mode = 'edge' + Out = [[1, 1, 1, 2, 3, 3] + [4, 4, 4, 5, 6, 6] + [4, 4, 4, 5, 6, 6]] + +参数： + - **input** (Variable) - 具有[N, C, H, W]格式或[N, H, W, C]格式的输入图像。 + - **paddings** (tuple|list) - 填充区域的大小。如果填充是一个元组，它必须包含四个整数， + (padding_top、padding_bottom、padding_left、padding_right)。默认:padding =[0,0,0,0]。 + - **mode** (str) - 三种模式:constant(默认)、reflect、edge。默认值:常数 + - **pad_value** (float32) - 以常量模式填充填充区域的值。默认值:0 + - **data_format** (str) - 可选字符串，选项有: ``NHWC`` , ``NCHW``。指定输入数据的数据格式。默认值:``NCHW`` + - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 + +返回： tensor变量，按照 padding值 和 mode 进行填充 + +返回类型：variable + +**代码示例：** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') + result = fluid.layers.pad2d(input=data, padding=[1,2,3,4], mode='reflect') + + + + + + + + + + + +.. _cn_api_fluid_layers_pad_constant_like: + +pad_constant_like +------------------------------- + +.. py:function:: paddle.fluid.layers.pad_constant_like(x, y, pad_value=0.0, name=None) + +使用 ``pad_value`` 填充 ``Y`` ，填充到每个axis（轴）值的数量由X和Y的形不同而指定。（（0，shape_x_0 - shape_y_0），...（0，shape_x_n - shape_y_n ））是每个axis唯一pad宽度。输入应该是k维张量（k> 0且k <7）。 + +**实例如下** + +:: + + Given: + X = [[[[ 0, 1, 2], + [ 3, 4, 5]], + [[ 6, 7, 8], + [ 9, 10, 11]], + [[12, 13, 14], + [15, 16, 17]]], + [[[18, 19, 20], + [21, 22, 23]], + [[24, 25, 26], + [27, 28, 29]], + [[30, 31, 32], + [33, 34, 35]]]] + X.shape = (2, 3, 2, 3) + + Y = [[[[35, 36, 37]], + [[38, 39, 40]], + [[41, 42, 43]]]] + Y.shape = (1, 3, 1, 3) + +参数： + - **x** （Variable）- 输入Tensor变量。 + - **y** （Variable）- 输出Tensor变量。 + - **pad_value** (float) - 用于填充的常量值。 + - **name** （str | None） - 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回：填充张量（Tensor）变量 + +返回类型： 变量（Variable） + +**示例代码** + +.. code-block:: python + + # x是秩为4的tensor, x.shape = (2, 3, 2, 3)。 + # y是秩为4的tensor, y.shape = (1, 3, 1, 3)。 + out = fluid.layers.pad_constant_like(x=x, y=y, pad_value=0.) + # out是秩为4的tensor, out.shape = [2, 3 ,2 , 3]。 + + + + + + + + + + + +.. _cn_api_fluid_layers_pool2d: + +pool2d +------------------------------- + +.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True) + +pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。 + +输入X和输出Out是NCHW格式，N为batch尺寸，C是通道数，H是特征高度，W是特征宽度。 + +参数（ksize,strides,paddings）含有两个元素。这两个元素分别代表高度和宽度。输入X的大小和输出Out的大小可能不一致。 + +例如： + +输入： + X shape：:math:`\left ( N,C,H_{in},W_{in} \right )` + +输出： + Out shape：:math:`\left ( N,C,H_{out},W_{out} \right )` + +如果 ``ceil_mode`` = false： + +.. math:: + H_{out} = \frac{(H_{in} - ksize[0] + 2 * paddings[0])}{strides[0]} + 1 + +.. math:: + W_{out} = \frac{(W_{in} - ksize[1] + 2 * paddings[1])}{strides[1]} + 1 + +如果 ``ceil_mode`` = true： + +.. math:: + H_{out} = \frac{(H_{in} - ksize[0] + 2 * paddings[0] + strides[0] - 1)}{strides[0]} + 1 + +.. math:: + W_{out} = \frac{(W_{in} - ksize[1] + 2 * paddings[1] + strides[1] - 1)}{strides[1]} + 1 + +如果 ``exclusive`` = true: + +.. math:: + hstart &= i * strides[0] - paddings[0] \\ + hend &= hstart + ksize[0] \\ + wstart &= j * strides[1] - paddings[1] \\ + wend &= wstart + ksize[1] \\ + Output(i ,j) &= \frac{sum(Input[hstart:hend, wstart:wend])}{ksize[0] * ksize[1]} + +如果 ``exclusive`` = false: + +.. math:: + hstart &= max(0, i * strides[0] - paddings[0])\\ + hend &= min(H, hstart + ksize[0]) \\ + wstart &= max(0, j * strides[1] - paddings[1]) \\ + wend & = min(W, wstart + ksize[1]) \\ + Output(i ,j) & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} + + + +参数： + - **input** (Variable) - 池化操作的输入张量。输入张量格式为NCHW，N为批尺寸，C是通道数，H是特征高度，W是特征宽度 + - **pool_size** (int|list|tuple) - 池化窗口的大小。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。 + - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling + - **pool_stride** (int|list|tuple) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。 + - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。 + - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true， ``pool_size`` 和 ``pool_padding`` 将被忽略。 + - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn + - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数 + - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。 + - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 + +返回：池化结果 + +返回类型：变量（Variable） + +抛出异常： + - ``ValueError`` - 如果 ``pool_type`` 既不是“max”也不是“avg” + - ``ValueError`` - 如果 ``global_pooling`` 为False并且‘pool_size’为-1 + - ``ValueError`` - 如果 ``use_cudnn`` 不是bool值 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data( + name='data', shape=[3, 32, 32], dtype='float32') + conv2d = fluid.layers.pool2d( + input=data, + pool_size=2, + pool_type='max', + pool_stride=1, + global_pooling=False) + + + + + + + + + +.. _cn_api_fluid_layers_pool3d: + +pool3d +------------------------------- + +.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None， exclusive=True) + +函数使用上述输入参数的池化配置，为三维空间添加池化操作 + +参数： + - **input** (Vairable) - 池化运算的输入张量。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。 + - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **pool_type** (str) - 池化类型， "max" 对应max-pooling, "avg" 对应average-pooling。 + - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略。 + - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效。 + - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。 + - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。 + - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 + +返回：pool3d层的输出 + +返回类型：变量（Variable） + + + + + + + + + + + + +.. _cn_api_fluid_layers_pow: + +pow +------------------------------- + +.. py:function:: paddle.fluid.layers.pow(x, factor=1.0, name=None) + +指数激活算子（Pow Activation Operator.） + +.. math:: + + out = x^{factor} + +参数 + - **x** (Variable) - Pow operator的输入 + - **factor** (FLOAT|1.0) - Pow的指数因子 + - **name** (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: 输出Pow操作符 + +返回类型: 输出(Variable) + + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.pow(x, factor=2.0) + + + + + + +.. _cn_api_fluid_layers_prelu: + +prelu +------------------------------- + +.. py:function:: paddle.fluid.layers.prelu(x, mode, param_attr=None, name=None) + +等式： + +.. math:: + y = max(0, x) + \alpha min(0, x) + +参数： + - **x** （Variable）- 输入为Tensor。 + - **param_attr** (ParamAttr|None) - 可学习权重 :math:`[\alpha]` 的参数属性。 + - **mode** （string）- 权重共享的模式all：所有元素共享相同的权重通道：通道中的元素共享相同的权重元素：每个元素都有一个权重 + - **name** （str | None）- 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 输出Tensor与输入shape相同。 + +返回类型： 变量（Variable） + + + + + + + + + + + +.. _cn_api_fluid_layers_random_crop: + +random_crop +------------------------------- + +.. py:function:: paddle.fluid.layers.random_crop(x, shape, seed=None) + +该operator对batch中每个实例进行随机裁剪。这意味着每个实例的裁剪位置不同，裁剪位置由均匀分布随机生成器决定。所有裁剪的实例都具有相同的shape，由参数shape决定。 + +参数: + - **x(Variable)** - 一组随机裁剪的实例 + - **shape(int)** - 裁剪实例的形状 + - **seed(int|变量|None)** - 默认情况下，随机种子从randint(-65536,-65536)中取得 + +返回: 裁剪后的batch + +**代码示例**: + +.. code-block:: python + + img = fluid.layers.data("img", [3, 256, 256]) + cropped_img = fluid.layers.random_crop(img, shape=[3, 224, 224]) + + + + + + + + + + +.. _cn_api_fluid_layers_rank_loss: + +rank_loss +------------------------------- + + +.. py:function:: paddle.fluid.layers.rank_loss(label, left, right, name=None) + +`RankNet `_ 是一个成对的 +排序模型，训练样本由一对文档组成：A和B。标签P表示a的排名是否高于B: + +P 的取值可为： {0, 1} 或 {0, 0.5, 1}, 其中，0.5表示输入的两文档排序相同。 + +排序的损失函数有三个输入:left(o_i)、right(o_j) 和 label (P\_{i,j})。输入分别表示RankNet对文档A、B的输出得分和标签p的值。由下式计算输入的排序损失C\_{i,j}: + +.. math:: + + C_{i,j} &= -\tilde{P_{ij}} * o_{i,j} + \log(1 + e^{o_{i,j}}) \\ + o_{i,j} &= o_i - o_j \\ + \tilde{P_{i,j}} &= \left \{0, 0.5, 1 \right \} \ or \ \left \{0, 1 \right \} + +排序损失层的输入为batch_size (batch_size >= 1) + +参数： + - **label** (Variable)：A的排名是否高于B + - **left** (Variable)：RankNet对doc A的输出分数 + - **right** (Variable): RankNet对doc B的输出分数 + - **name** (str|None)：此层的名称(可选)。如果没有设置，层将自动命名。 + +返回：variable：形为[N, H, W, 2]的输出 + +抛出异常：ValueError: 如果参数为不支持的类型 + + +**代码示例** + +.. code-block:: python + + theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") + out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") + data = fluid.layers.affine_grid(theta, out_shape) + + # or + data = fluid.layers.affine_grid(theta, [5, 3, 28, 28]) + + + + + + + + + + +.. _cn_api_fluid_layers_reduce_max: + +reduce_max +------------------------------- + +.. py:function:: paddle.fluid.layers.reduce_max(input, dim=None, keep_dim=False, name=None) + +计算给定维度上张量（Tensor）元素最大值。 + +参数： + - **input** （Variable）：输入变量为Tensor或LoDTensor。 + - **dim** （list | int | None）：函数运算的维度。如果为None，则计算所有元素的平均值并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 + - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 + - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 运算、减少维度之后的Tensor变量。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + # x是一个Tensor，元素如下: + # [[0.2, 0.3, 0.5, 0.9] + # [0.1, 0.2, 0.6, 0.7]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 + fluid.layers.reduce_max(x) # [0.9] + fluid.layers.reduce_max(x, dim=0) # [0.2, 0.3, 0.6, 0.9] + fluid.layers.reduce_max(x, dim=-1) # [0.9, 0.7] + fluid.layers.reduce_max(x, dim=1, keep_dim=True) # [[0.9], [0.7]] + + # x是一个shape为[2, 2, 2]的Tensor，元素如下: + # [[[1.0, 2.0], [3.0, 4.0]], + # [[5.0, 6.0], [7.0, 8.0]]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 + fluid.layers.reduce_max(x, dim=[1, 2]) # [4.0, 8.0] + fluid.layers.reduce_max(x, dim=[0, 1]) # [7.0, 8.0] + + + + + + + + + + +.. _cn_api_fluid_layers_reduce_mean: + +reduce_mean +------------------------------- + +.. py:function:: paddle.fluid.layers.reduce_mean(input, dim=None, keep_dim=False, name=None) + +计算给定维度上张量（Tensor）元素平均值。 + +参数： + - **input** （Variable）：输入变量为Tensor或LoDTensor。 + - **dim** （list | int | None）：函数运算的维度。如果为None，则对输入的所有元素求平均值并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 + - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 + - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 运算、减少维度之后的Tensor变量。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + # x是一个Tensor，元素如下: + # [[0.2, 0.3, 0.5, 0.9] + # [0.1, 0.2, 0.6, 0.7]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_mean(x) # [0.4375] + fluid.layers.reduce_mean(x, dim=0) # [0.15, 0.25, 0.55, 0.8] + fluid.layers.reduce_mean(x, dim=-1) # [0.475, 0.4] + fluid.layers.reduce_mean( + x, dim=1, keep_dim=True) # [[0.475], [0.4]] + + # x 是一个shape为[2, 2, 2]的Tensor元素如下: + # [[[1.0, 2.0], [3.0, 4.0]], + # [[5.0, 6.0], [7.0, 8.0]]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 + fluid.layers.reduce_mean(x, dim=[1, 2]) # [2.5, 6.5] + fluid.layers.reduce_mean(x, dim=[0, 1]) # [4.0, 5.0] + + + + + + + + + + +.. _cn_api_fluid_layers_reduce_min: + +reduce_min +------------------------------- + +.. py:function:: paddle.fluid.layers.reduce_min(input, dim=None, keep_dim=False, name=None) + +计算给定维度上张量元素的最小值。 + +参数： + - **input** （Variable）：输入变量为Tensor或LoDTensor。 + - **dim** （list | int | None）：函数运算的维度。如果为None，则对输入的所有元素做差并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 + - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 + - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 运算、减少维度之后的Tensor变量。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + # x是一个Tensor，元素如下: + # [[0.2, 0.3, 0.5, 0.9] + # [0.1, 0.2, 0.6, 0.7]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_min(x) # [0.1] + fluid.layers.reduce_min(x, dim=0) # [0.1, 0.2, 0.5, 0.7] + fluid.layers.reduce_min(x, dim=-1) # [0.2, 0.1] + fluid.layers.reduce_min(x, dim=1, keep_dim=True) # [[0.2], [0.1]] + + # x 是一个shape为[2, 2, 2]的Tensor元素如下: + # [[[1.0, 2.0], [3.0, 4.0]], + # [[5.0, 6.0], [7.0, 8.0]]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。。 + fluid.layers.reduce_min(x, dim=[1, 2]) # [1.0, 5.0] + fluid.layers.reduce_min(x, dim=[0, 1]) # [1.0, 2.0] + + + + + + + + + + +.. _cn_api_fluid_layers_reduce_prod: + +reduce_prod +------------------------------- + +.. py:function:: paddle.fluid.layers.reduce_prod(input, dim=None, keep_dim=False, name=None) + +计算给定维度上张量（Tensor）元素乘积。 + +参数： + - **input** （Variable）：输入变量为Tensor或LoDTensor。 + - **dim** （list | int | None）：函数运算的维度。如果为None，则将输入的所有元素相乘并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 + - **keep_dim** （bool | False）：是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 + - **name** （str | None）：这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 运算、减少维度之后的Tensor变量。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + # x是一个Tensor，元素如下: + # [[0.2, 0.3, 0.5, 0.9] + # [0.1, 0.2, 0.6, 0.7]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_prod(x) # [0.0002268] + fluid.layers.reduce_prod(x, dim=0) # [0.02, 0.06, 0.3, 0.63] + fluid.layers.reduce_prod(x, dim=-1) # [0.027, 0.0084] + fluid.layers.reduce_prod(x, dim=1, + keep_dim=True) # [[0.027], [0.0084]] + + # x 是一个shape为[2, 2, 2]的Tensor元素如下: + # [[[1.0, 2.0], [3.0, 4.0]], + # [[5.0, 6.0], [7.0, 8.0]]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_prod(x, dim=[1, 2]) # [24.0, 1680.0] + fluid.layers.reduce_prod(x, dim=[0, 1]) # [105.0, 384.0] + + + + + + + + + + +.. _cn_api_fluid_layers_reduce_sum: + +reduce_sum +------------------------------- + +.. py:function:: paddle.fluid.layers.reduce_sum(input, dim=None, keep_dim=False, name=None) + +计算给定维度上张量（Tensor）元素之和。 + +参数： + - **input** （Variable）- 输入变量为Tensor或LoDTensor。 + - **dim** （list | int | None）- 求和运算的维度。如果为None，则对输入的所有元素求和并返回单个元素的Tensor变量，否则必须在 :math:`[−rank(input),rank(input)]` 范围内。如果 :math:`dim [i] <0` ，则维度将减小为 :math:`rank+dim[i]` 。 + - **keep_dim** （bool | False）- 是否在输出Tensor中保留减小的维度。除非 ``keep_dim`` 为true，否则结果张量将比输入少一个维度。 + - **name** （str | None）- 这一层的名称（可选）。如果设置为None，则将自动命名这一层。 + +返回： 运算、减少维度之后的Tensor变量。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + # x是一个Tensor，元素如下: + # [[0.2, 0.3, 0.5, 0.9] + # [0.1, 0.2, 0.6, 0.7]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_sum(x) # [3.5] + fluid.layers.reduce_sum(x, dim=0) # [0.3, 0.5, 1.1, 1.6] + fluid.layers.reduce_sum(x, dim=-1) # [1.9, 1.6] + fluid.layers.reduce_sum(x, dim=1, keep_dim=True) # [[1.9], [1.6]] + + # x 是一个shape为[2, 2, 2]的Tensor元素如下: + # [[[1, 2], [3, 4]], + # [[5, 6], [7, 8]]] + # 接下来的示例中，我们在每处函数调用后面都标注出了它的结果张量。 + fluid.layers.reduce_sum(x, dim=[1, 2]) # [10, 26] + fluid.layers.reduce_sum(x, dim=[0, 1]) # [16, 20] + + + + + + + + + + +.. _cn_api_fluid_layers_relu: + +relu +------------------------------- + +.. py:function:: paddle.fluid.layers.relu(x, name=None) + +Relu接受一个输入数据(张量)，输出一个张量。将线性函数y = max(0, x)应用到张量中的每个元素上。 + +.. math:: + \\Out=\max(0,x)\\ + + +参数: + - **x** (Variable):输入张量。 + - **name** (str|None，默认None) :如果设置为None，该层将自动命名。 + +返回: 与输入形状相同的输出张量。 + +返回类型: 变量（Variable） + +**代码示例**: + +.. code-block:: python + + output = fluid.layers.relu(x) + + + + + + + + + + +.. _cn_api_fluid_layers_relu6: + +relu6 +------------------------------- + +.. py:function:: paddle.fluid.layers.relu6(x, threshold=6.0, name=None) + +relu6激活算子（Relu6 Activation Operator） + +.. math:: + + \\out=min(max(0, x), 6)\\ + + +参数: + - **x** (Variable) - Relu6 operator的输入 + - **threshold** (FLOAT|6.0) - Relu6的阈值 + - **name** (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: Relu6操作符的输出 + +返回类型: 输出(Variable) + + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.relu6(x, threshold=6.0) + + + + + + + +.. _cn_api_fluid_layers_reshape: + +reshape +------------------------------- + +.. py:function:: paddle.fluid.layers.reshape(x, shape, actual_shape=None, act=None, inplace=False, name=None) + +保持输入张量数据不变的情况下，改变张量的形状。 + +目标形状可由 ``shape`` 或 ``actual_shape`` 给出。``shape`` 是一个整数列表，而 ``actual_shape`` 是一个张量变量。 +当两个属性同时被指定时，``actual_shape`` 的优先级高于 ``shape`` ，但在编译时仍然应该正确地设置 ``shape`` 以保证形状推断。 + +在指定目标shape时存在一些技巧： + +.. code-block:: text + + 1. -1表示这个维度的值是从x的元素总数和剩余维度推断出来的。因此，有且只有一个维度可以被设置为-1。 + 2. 0表示实际的维数是从x的对应维数中复制出来的，因此shape中0的索引值不能超过秩(x)。 + + +这里有一些例子来解释它们： + +.. code-block:: text + + 1. 给定一个形状为[2,4,6]的三维张量x，目标形状为[6,8]， ``reshape`` 将x变换为形状为[6,8]的二维张量，且x的数据保持不变。 + 2. 给定一个形状为[2,4,6]的三维张量x，指定的目标形状为[2,3,-1,2]， ``reshape``将x变换为形状为[2,3,4,2]的4- d张量，不改变x的数据。在这种情况下，目标形状的一个维度被设置为-1，这个维度的值是从x的元素总数和剩余维度推断出来的。 + 3. 给定一个形状为[2,4,6]的三维张量x，目标形状为[- 1,0,3,2]，整形算子将x变换为形状为[2,4,3,2]的四维张量，使x的数据保持不变。在这种情况下，0意味着实际的维值将从x的对应维数中复制,-1位置的维度由x的元素总数和剩余维度计算得来。 + +参数： + - **x** (variable) - 输入张量 + - **shape** (list) - 新的形状。新形状最多只能有一个维度为-1。 + - **actual_shape** (variable) - 一个可选的输入。如果提供，则根据 ``actual_shape`` 进行 reshape，而不是指定 ``shape`` 。也就是说，actual_shape具有比shape更高的优先级。 + - **act** (str) - 对reshpe后的tensor变量执行非线性激活 + - **inplace** (bool) - 如果在多个操作符中使用x，则 ``inplace`` 必须设置为False。如果该标志设置为True，则重用输入x进行reshape，这将改变张量变量x的形状，并可能在多个操作符中使用x时造成错误。如果为False，则保留形状x，并创建一个新的输出张量变量，该张量变量的数据是从输入x复制的，但经过了重构。 + - **name** (str) - 可选变量，此层的名称 + +返回：如果 ``act`` 为 ``None``,返回reshape后的tensor变量。如果 ``inplace`` 为 ``False`` ,将返回一个新的Tensor变量，否则，将改变x自身。如果 ``act`` 不是 ``None`` ，则返回激活的张量变量。 + +抛出异常：``TypeError`` - 如果 actual_shape 既不是变量也不是None + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data( + name='data', shape=[2, 4, 6], dtype='float32') + reshaped = fluid.layers.reshape( + x=data, shape=[-1, 0, 3, 2], inplace=True) + + + + + + + + + + +.. _cn_api_fluid_layers_resize_bilinear: + +resize_bilinear +------------------------------- + +.. py:function:: paddle.fluid.layers.resize_bilinear(input, out_shape=None, scale=None, name=None, actual_shape=None) + + +根据指定的out_shape执行双线性插值调整输入大小，输出形状按优先级由actual_shape、out_shape和scale指定。 + +双线性插值是对线性插值的扩展,即二维变量方向上(如h方向和w方向)插值。关键思想是先在一个方向上执行线性插值，然后再在另一个方向上执行线性插值。 + + `详情请参阅维基百科 https://en.wikipedia.org/wiki/Bilinear_interpolation `_ + +参数: + - **input** (Variable) - 双线性插值的输入张量，是一个shpae为(N x C x h x w)的4d张量。 + - **out_shape** (Variable) - 一维张量，包含两个数。第一个数是高度，第二个数是宽度。 + - **scale** (float|None) - 用于输入高度或宽度的乘数因子。out_shape和scale至少要设置一个。out_shape的优先级高于scale。默认值:None。 + - **name** (str|None) - 输出变量名。 + - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`actual_shape` 而不是 :code:`out_shape` 。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值:None + +返回： 输出的维度是(N x C x out_h x out_w) + + +**代码示例：** + +.. code-block:: python + + out = fluid.layers.resize_bilinear(input, out_shape=[12, 12]) + + + + + + + + +.. _cn_api_fluid_layers_resize_nearest: + +resize_nearest +------------------------------- + +.. py:function:: paddle.fluid.layers.resize_nearest(input, out_shape=None, scale=None, name=None, actual_shape=None) + +该层对输入进行放缩，在第三维（高度方向）和第四维（宽度方向）进行最邻近插值（nearest neighbor interpolation）操作。 +输出形状按优先级顺序依据 ``actual_shape`` , ``out_shape`` 和 ``scale`` 而定。 + +最邻近插值的详细介绍请参照： `Wiki Nearest-neighbor interpolation `_ + + + +参数: + - **input** (Variable) – 插值运算的输入张量, 是一个形为 (N,C,H,W) 的四维张量 + - **out_shape** (Variable) – 一维张量，包含两个指明输出大小的数字 。 第一个代表了高度，第二个代表了宽度 + - **scale** (float|None) – 输入高、宽的乘法器。 ``out_shape`` 和 ``scale`` 二者至少设置其一。 ``out_shape`` 具有比 ``scale`` 更高的优先级。 默认: None + - **name** (str|None) – 输出变量的命名 + - **actual_shape** (Variable) – 可选输入， 动态设置输出张量的形状。 如果提供该值， 图片放缩会依据此形状进行， 而非依据 ``out_shape`` 和 ``scale`` 。 即为， ``actual_shape`` 具有最高的优先级。 如果想动态指明输出形状，推荐使用 ``actual_shape`` 取代 ``out_shape`` 。 当使用 ``actual_shape`` 来指明输出形状， ``out_shape`` 和 ``scale`` 也应该进行设置, 否则在图形生成阶段将会报错。默认: None + +返回：插值运算的输出张量，是一个形为 (N,C,H,W) 的四维张量 + +**代码示例** + +.. code-block:: python + + out = fluid.layers.resize_nearest(input, out_shape=[12, 12]) + + + + + + + + + + +.. _cn_api_fluid_layers_roi_align: + +roi_align +------------------------------- + +.. py:function:: paddle.fluid.layers.roi_align(input, rois, pooled_height=1, pooled_width=1, spatial_scale=1.0, sampling_ratio=-1, name=None) + +**实现RoIAlign操作。** + +Region of Interests align(直译：有意义、有价值选区对齐) 用于实现双线性插值，它可以将不均匀大小的输入 +变为固定大小的特征图(feature map)。 + +该运算通过 ``pooled_width`` 和 ``pooled_height`` 将每个推荐区域划分为等大小分块。位置保持不变。 + +在每个RoI框中，四个常取样位置会通过双线性插值直接计算。输出为这四个位置的平均值从而解决不对齐问题。 + +参数: + - **input** (Variable) – (Tensor) 该运算的的输入张量，形为(N,C,H,W)。其中 N 为batch大小, C 为输入通道的个数, H 特征高度, W 特征宽度 + - **rois** (Variable) – 待池化的ROIs (Regions of Interest) + - **pooled_height** (integer) – (默认为1), 池化后的输出高度 + - **pooled_width** (integer) – (默认为1), 池化后的输出宽度 + - **spatial_scale** (float) – (默认为1.0),乘法性质空间标尺因子，池化时，将RoI坐标变换至运算采用的标度 + - **sampling_ratio** (intger) – (默认为-1),插值格中采样点的数目。 如果它 <=0, 它们将自适应 ``roi_width`` 和 ``pooled_w`` , 在高度上也是同样的道理。 + +返回：一个形为 (num_rois, channels, pooled_h, pooled_w) 的四维张量 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + align_out = fluid.layers.roi_align(input=x, + rois=rois, + pooled_height=7, + pooled_width=7, + spatial_scale=0.5, + sampling_ratio=-1) + + + + + + + + + + + +.. _cn_api_fluid_layers_roi_pool: + +roi_pool +------------------------------- + +.. py:function:: paddle.fluid.layers.roi_pool(input, rois, pooled_height=1, pooled_width=1, spatial_scale=1.0) + + +roi池化是对非均匀大小的输入执行最大池化，以获得固定大小的特征映射(例如7*7)。 + +该operator有三个步骤: + + 1. 用pooled_width和pooled_height将每个区域划分为大小相等的部分 + 2. 在每个部分中找到最大的值 + 3. 将这些最大值复制到输出缓冲区 + +Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverflow.com/questions/43430056/what-is-roi-layer-in-fast-rcnn + +参数: + - **input** (Variable) - 张量，ROIPoolOp的输入。输入张量的格式是NCHW。其中N为batch大小，C为输入通道数，H为特征高度，W为特征宽度 + - **roi** (Variable) - roi区域。 + - **pooled_height** (integer) - (int，默认1)，池化输出的高度。默认:1 + - **pooled_width** (integer) - (int，默认1) 池化输出的宽度。默认:1 + - **spatial_scale** (float) - (float，默认1.0)，用于将ROI coords从输入规模转换为池化时使用的规模。默认1.0 + +返回: (张量)，ROIPoolOp的输出是一个shape为(num_rois, channel, pooled_h, pooled_w)的4d张量。 + +返回类型: 变量（Variable） + + +**代码示例** + +.. code-block:: python + + pool_out = fluid.layers。roi_pool(输入=x, rois=rois, 7,7,1.0) + + + + + + + + + + +.. _cn_api_fluid_layers_row_conv: + +row_conv +------------------------------- + +.. py:function:: paddle.fluid.layers.row_conv(input, future_context_size, param_attr=None, act=None) + +行卷积（Row-convolution operator）称为超前卷积（lookahead convolution）。下面关于DeepSpeech2的paper中介绍了这个operator + + ``_ + +双向的RNN在深度语音模型中很有用，它通过对整个序列执行正向和反向传递来学习序列的表示。然而，与单向RNNs不同的是，在线部署和低延迟设置中，双向RNNs具有难度。超前卷积将来自未来子序列的信息以一种高效的方式进行计算，以改进单向递归神经网络。 row convolution operator 与一维序列卷积不同，计算方法如下: + +给定输入序列长度为 :math:`t` 的输入序列 :math:`in` 和输入维度 :math:`d` ，以及一个大小为 :math:`context x d` 的滤波器 :math:`W` ，输出序列卷积为: + +.. math:: + out_i = \sum_{j=i}^{i+context} in_{j} · W_{i-j} + +公式中： + - :math:`out_i` : 第i行输出变量 shaoe为[1, D]. + - :math:`context` ： 未来上下文（feature context）大小 + - :math:`in_j` : 第j行输出变量,形为[1，D] + - :math:`W_{i-j}` : 第(i-j)行参数，其形状为[1,D]。 + +`详细请参考设计文档 https://github.com/PaddlePaddle/Paddle/issues/2228#issuecomment-303903645 `_ . + +参数: + - **input** (Variable) -- 输入是一个LodTensor，它支持可变时间长度的输入序列。这个LodTensor的内部张量是一个具有形状(T x N)的矩阵，其中T是这个mini batch中的总的timestep，N是输入数据维数。 + - **future_context_size** (int) -- 未来上下文大小。请注意，卷积核的shape是[future_context_size + 1, D]。 + - **param_attr** (ParamAttr) -- 参数的属性，包括名称、初始化器等。 + - **act** (str) -- 非线性激活函数。 + +返回: 输出(Out)是一个LodTensor，它支持可变时间长度的输入序列。这个LodTensor的内部量是一个形状为 T x N 的矩阵，和X的 shape 一样。 + + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + + x = fluid.layers.data(name='x', shape=[16], + dtype='float32', lod_level=1) + out = fluid.layers.row_conv(input=x, future_context_size=2) + + + + + + + + + + +.. _cn_api_fluid_layers_sampling_id: + +sampling_id +------------------------------- + +.. py:function:: paddle.fluid.layers.sampling_id(x, min=0.0, max=1.0, seed=0, dtype='float32') + +sampling_id算子。用于从输入的多项分布中对id进行采样的图层。为一个样本采样一个id。 + +参数： + - **x** （Variable）- softmax的输入张量（Tensor）。2-D形状[batch_size，input_feature_dimensions] + - **min** （Float）- 随机的最小值。（浮点数，默认为0.0） + - **max** （Float）- 随机的最大值。（float，默认1.0） + - **seed** （Float）- 用于随机数引擎的随机种子。0表示使用系统生成的种子。请注意，如果seed不为0，则此运算符将始终每次生成相同的随机数。（int，默认为0） + - **dtype** （np.dtype | core.VarDesc.VarType | str）- 输出数据的类型为float32，float_16，int等。 + +返回： Id采样的数据张量。 + +返回类型： 输出（Variable）。 + + +**代码示例：** + +.. code-block:: python + + x = layers.data( + name="X", + shape=[13, 11], + dtype='float32', + append_batch_size=False) + + out = layers.sampling_id(x) + + + + + + + + +.. _cn_api_fluid_layers_scale: + +scale +------------------------------- + +.. py:function:: paddle.fluid.layers.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None) + +缩放算子 + +对输入张量应用缩放和偏移加法。 + +if ``bias_after_scale`` = True: + +.. math:: + Out=scale*X+bias + +else: + +.. math:: + Out=scale*(X+bias) + +参数: + - **x** (Variable) - (Tensor) 要比例运算的输入张量（Tensor）。 + - **scale** (FLOAT) - 比例运算的比例因子。 + - **bias** (FLOAT) - 比例算子的偏差。 + - **bias_after_scale** (BOOLEAN) - 在缩放之后或之前添加bias。在某些情况下，对数值稳定性很有用。 + - **act** (basestring|None) - 应用于输出的激活函数。 + - **name** (basestring|None)- 输出的名称。 + +返回: 比例运算符的输出张量(Tensor) + +返回类型: 变量(Variable) + + + + + + + + + + +.. _cn_api_fluid_layers_scatter: + +scatter +------------------------------- + +.. py:function:: paddle.fluid.layers.scatter(input, index, updates, name=None) + + +通过更新输入在第一维度上指定索引位置处的元素来获得输出。 + +.. math:: + \\Out=XOut[Ids]=Updates\\ + + +参数： + - **input** （Variable） - 秩> = 1的源输入 + - **index** （Variable） - 秩= 1的索引输入。 它的dtype应该是int32或int64，因为它用作索引 + - **updates** （Variable） - scatter 要进行更新的变量 + - **name** （str | None） - 输出变量名称。 默认None + +返回：张量变量, 与输入张量的shape相同 + +返回类型：output（Variable） + +**代码示例** + +.. code-block:: python + + output = fluid.layers.scatter(input, index, updates) + + + + + + + + + + + +.. _cn_api_fluid_layers_selu: + +selu +------------------------------- + +.. py:function:: paddle.fluid.layers.selu(x, scale=None, alpha=None, name=None) + +**实现Selu运算** + +有如下等式： + +.. math:: + selu= \lambda* + \begin{cases} + x &\quad \text{ if } x>0 \\ + \alpha * e^x - \alpha &\quad \text{ if } x<=0 + \end{cases} + +输入 ``x`` 可以选择性携带LoD信息。输出和它共享此LoD信息(如果有)。 + +参数: + - **x** (Variable) – 输入张量 + - **scale** (float, None) – 如果标度没有设置，其默认值为 1.0507009873554804934193349852946。 详情请见： `Self-Normalizing Neural Networks `_ + - **alpha** (float, None) – 如果没有设置改参数, 其默认值为 1.6732632423543772848170429916717。 详情请见： `Self-Normalizing Neural Networks `_ + - **name** (str|None, default None) – 该层命名，若为None则自动为其命名 + +返回：一个形和输入张量相同的输出张量 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + output = fluid.layers.selu(x) + + + + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_concat: + +sequence_concat +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_concat(input, name=None) + +sequence_concat操作通过序列信息连接LoD张量（Tensor）。例如：X1的LoD = [0,3,7]，X2的LoD = [0,7,9]，结果的LoD为[0，（3 + 7），（7 + 9）]，即[0,10,16]。 + +参数: + - **input** (list) – 要连接变量的列表 + - **name** (str|None) – 此层的名称(可选)。如果没有设置，该层将被自动命名。 + +返回: 连接好的输出变量。 + +返回类型: 变量（Variable） + + +**代码示例** + +.. code-block:: python + + out = fluid.layers.sequence_concat(input=[seq1, seq2, seq3]) + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_conv: + +sequence_conv +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_conv(input, num_filters, filter_size=3, filter_stride=1, padding=None, bias_attr=None, param_attr=None, act=None, name=None) + +该函数的输入参数中给出了滤波器和步长，通过利用输入以及滤波器和步长的常规配置来为sequence_conv创建操作符。 + +参数： + - **input** (Variable) - (LoD张量）输入X是LoD张量，支持可变的时间量的长度输入序列。该LoDTensor的标记张量是一个维度为（T,N)的矩阵，其中T是mini-batch的总时间步数，N是input_hidden_size + - **num_filters** (int) - 滤波器的数量 + - **filter_size** (int) - 滤波器大小（H和W) + - **filter_stride** (int) - 滤波器的步长 + - **padding** (bool) - 若为真，添加填充 + - **bias_attr** (ParamAttr|bool|None) - sequence_conv偏离率参数属性。若设为False,输出单元则不加入偏离率。若设为None或ParamAttr的一个属性，sequence_conv将创建一个ParamAttr作为bias_attr。如果未设置bias_attr的初始化函数，则将bias初始化为0.默认:None + - **param_attr** (ParamAttr|None) - 可学习参数/sequence_conv的权重参数属性。若设置为None或ParamAttr的一个属性，sequence_conv将创建ParamAttr作为param_attr。 + 若未设置param_attr的初始化函数，则用Xavier初始化参数。默认:None + +返回：sequence_conv的输出 + +返回类型：变量（Variable） + + + + + + + + + +.. _cn_api_fluid_layers_sequence_enumerate: + +sequence_enumerate +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_enumerate(input, win_size, pad_value=0, name=None) + +为输入索引序列生成一个新序列，该序列枚举输入长度为 ``win_size`` 的所有子序列。 输入序列和枚举序列第一维上维度相同，第二维是 ``win_size`` ，在生成中如果需要，通过设置 ``pad_value`` 填充。 + +**例子：** + +:: + + 输入： + X.lod = [[0, 3, 5]] X.data = [[1], [2], [3], [4], [5]] X.dims = [5, 1] + 属性： + win_size = 2 pad_value = 0 + 输出： + Out.lod = [[0, 3, 5]] Out.data = [[1, 2], [2, 3], [3, 0], [4, 5], [5, 0]] Out.dims = [5, 2] + +参数: + - **input** （Variable）- 作为索引序列的输入变量。 + - **win_size** （int）- 枚举所有子序列的窗口大小。 + - **pad_value** （int）- 填充值，默认为0。 + +返回: 枚举序列变量是LoD张量（LoDTensor）。 + +返回类型: Variable + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(shape[30, 1], dtype='int32', lod_level=1) + out = fluid.layers.sequence_enumerate(input=x, win_size=3, pad_value=0) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_expand: + +sequence_expand +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_expand(x, y, ref_level=-1, name=None) + +序列扩张层（Sequence Expand Layer) + +将根据指定 y 的 level lod 展开输入变量x，请注意 x 的 lod level 最多为1，而 x 的秩最少为2。当 x 的秩大于2时，它就被看作是一个二维张量。下面的例子将解释 sequence_expand 是如何工作的: + +:: + + + * 例1 + x is a LoDTensor: + x.lod = [[2, 2]] + x.data = [[a], [b], [c], [d]] + x.dims = [4, 1] + + y is a LoDTensor: + y.lod = [[2, 2], + [3, 3, 1, 1]] + + ref_level: 0 + + then output is a 1-level LoDTensor: + out.lod = [[2, 2, 2, 2]] + out.data = [[a], [b], [a], [b], [c], [d], [c], [d]] + out.dims = [8, 1] + + * 例2 + x is a Tensor: + x.data = [[a], [b], [c]] + x.dims = [3, 1] + + y is a LoDTensor: + y.lod = [[2, 0, 3]] + + ref_level: -1 + + then output is a Tensor: + out.data = [[a], [a], [c], [c], [c]] + out.dims = [5, 1] + +参数： + - **x** (Variable) - 输入变量，张量或LoDTensor + - **y** (Variable) - 输入变量，为LoDTensor + - **ref_level** (int) - x表示的y的Lod层。若设为-1，表示lod的最后一层 + - **name** (str|None) - 该层名称（可选）。如果设为空，则自动为该层命名 + +返回：扩展变量，LoDTensor + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[10], dtype='float32') + y = fluid.layers.data(name='y', shape=[10, 20], + dtype='float32', lod_level=1) + out = layers.sequence_expand(x=x, y=y, ref_level=0) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_expand_as: + +sequence_expand_as +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_expand_as(x, y, name=None) + +Sequence Expand As Layer + +这一层将根据y的第0级lod扩展输入变量x。当前实现要求输入（Y）的lod层数必须为1，输入（X）的第一维应当和输入（Y）的第0层lod的大小相同，不考虑输入（X）的lod。 + +以下示例解释sequence_expand如何工作： + +:: + + * 例1: + 给定一维LoDTensor input(X) + X.data = [[a], [b], [c], [d]] + X.dims = [4, 1] + 和 input(Y) + Y.lod = [[0, 3, 6, 7, 8]] + ref_level: 0 + 得到1级 LoDTensor + Out.lod = [[0, 3, 6, 7, 8]] + Out.data = [[a], [a], [a], [b], [b], [b], [c], [d]] + Out.dims = [8, 1] + + *例2 + + 给定一个 input(X)： + X.data = [[a, b], [c, d], [e, f]] + X.dims = [3, 2] + + 和 input(Y): + Y.lod = [[0, 2, 3, 6]] + ref_level: 0 + + 得到输出张量： + + Out.lod = [[0, 2, 3, 6]] + Out.data = [[a, b], [a, b] [c, d], [e, f], [e, f], [e, f]] + Out.dims = [6, 2] + + +参数： + - **x** (Variable) - 输入变量，类型为Tensor或LoDTensor + - **y** (Variable) - 输入变量，为LoDTensor + - **name** (str|None) - 该层名称（可选）。如果设为空，则自动为该层命名 + +返回：扩展变量，LoDTensor + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[10], dtype='float32') + y = fluid.layers.data(name='y', shape=[10, 20], + dtype='float32', lod_level=1) + out = layers.sequence_expand_as(x=x, y=y) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_first_step: + +sequence_first_step +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_first_step(input) + +该功能获取序列的第一步 + +:: + + x是1-level LoDTensor: + + x.lod = [[2, 3, 2]] + + x.data = [1, 3, 2, 4, 6, 5, 1] + + x.dims = [7, 1] + + 输出为张量: + + out.dim = [3, 1] + with condition len(x.lod[-1]) == out.dims[0] + out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) + +参数：**input** (variable)-输入变量，为LoDTensor + +返回：序列第一步，为张量 + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[7, 1], + dtype='float32', lod_level=1) + x_first_step = fluid.layers.sequence_first_step(input=x) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_last_step: + +sequence_last_step +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_last_step(input) + +该API可以获取序列的最后一步 + +:: + + x是level-1的LoDTensor: + + x.lod = [[2, 3, 2]] + + x.data = [1, 3, 2, 4, 6, 5, 1] + + x.dims = [7, 1] + + 输出为Tensor: + + out.dim = [3, 1] + + 且 len(x.lod[-1]) == out.dims[0] + + out.data = [3, 6, 1], where 3=last(1,3), 6=last(2,4,6), 1=last(5,1) + +参数：**input** (variable)-输入变量，为LoDTensor + +返回：序列的最后一步，为张量 + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[7, 1], + dtype='float32', lod_level=1) + x_last_step = fluid.layers.sequence_last_step(input=x) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_mask: + +sequence_mask +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_mask(x, maxlen=None, dtype='int64', name=None) + +该层根据输入 ``x`` 和 ``maxlen`` 输出一个掩码，数据类型为dtype。 + +假设x是一个形状为[d_1, d_2，…, d_n]的张量。， y是一个形为[d_1, d_2，… ，d_n, maxlen]的掩码，其中: + +.. math:: + + y(i_1, i_2,..., i_n, j) = (j < x(i_1, i_2,..., i_n)) + +参数： + - **x** (Variable) - sequence_mask层的输入张量，其元素是小于maxlen的整数。 + - **maxlen** (int|None) - 序列的最大长度。如果maxlen为空，则用max(x)替换。 + - **dtype** (np.dtype|core.VarDesc.VarType|str) - 输出的数据类型 + - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 + +返回： sequence mask 的输出 + +返回类型： Variable + + + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_pad: + +sequence_pad +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None,name=None) + +序列填充操作符（Sequence Pad Operator） + +这个操作符将同一batch中的序列填充到一个一致的长度。长度由属性padded_length指定。填充的新元素的值具体由输入 ``PadValue`` 指定，并会添加到每一个序列的末尾，使得他们最终的长度保持一致。 + +以下的例子更清晰地解释此操作符的工作原理： + +:: + + 例1: + + 给定 1-level LoDTensor + + input(X): + X.lod = [[0,2,5]] + X.data = [a,b,c,d,e] + input(PadValue): + PadValue.data = [0] + + 'padded_length'=4 + + 得到LoDTensor: + Out.data = [[a,b,0,0],[c,d,e,0]] + Length.data = [[2],[3]] + +:: + + 例2: + + 给定 1-level LoDTensor + + input(X): + X.lod = [[0,2,5]] + X.data = [[a1,a2],[b1,b2],[c1,c2],[d1,d2],[e1,e2]] + input(PadValue): + PadValue.data = [0] + + 'padded_length' = -1,表示用最长输入序列的长度(此例中为3) + + 得到LoDTensor: + Out.data = [[[a1,a2],[b1,b2],[0,0]],[[c1,c2],[d1,d2],[e1,e2]]] + Length.data = [[2],[3]] + + +:: + + 例3: + + 给定 1-level LoDTensor + + input(X): + X.lod = [[0,2,5]] + X.data = [[a1,a2],[b1,b2],[c1,c2],[d1,d2],[e1,e2]] + input(PadValue): + PadValue.data = [p1,p2] + + 'padded_length' = -1,表示用最长输入序列的长度（此例中为3） + + 得到LoDTensor: + Out.data = [[[a1,a2],[b1,b2],[p1,p2]],[[c1,c2],[d1,d2],[e1,e2]]] + Length.data = [[2],[3]] + + +参数： + - **x** (Vairable) - 输入变量，应包含lod信息 + - **pad_value** (Variable) - 变量，存有放入填充步的值。可以是标量或tensor,维度和序列的时间步长相等。如果是标量,则自动广播到时间步长的维度 + - **maxlen** (int,默认None) - 填充序列的长度。可以为空或者任意正整数。当为空时，以序列中最长序列的长度为准，其他所有序列填充至该长度。当是某个特定的正整数，最大长度必须大于最长初始序列的长度 + - **name** (str|None) – 该层的命名(可选项)。 如果为 None, 则自动命名 + +返回：填充序列批（batch）和填充前的初始长度。所有输出序列的长度相等 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + import numpy + + x = fluid.layers.data(name='y', shape=[10, 5], + dtype='float32', lod_level=1) + pad_value = fluid.layers.assign( + input=numpy.array([0.0], dtype=numpy.float32)) + out = fluid.layers.sequence_pad(x=x, pad_value=pad_value) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_pool: + +sequence_pool +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type, is_test=False) + +该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的pool_type将特征运用到输入到首部。 + +支持四种pool_type: + +- **average**: :math:`Out[i] = \frac{\sum_{i}X_{i}}{N}` +- **sum**: :math:`Out[i] = \sum _{j}X_{ij}` +- **sqrt**: :math:`Out[i] = \frac{ \sum _{j}X_{ij}}{\sqrt{len(\sqrt{X_{i}})}}` +- **max**: :math:`Out[i] = max(X_{i})` + +:: + + + x是一级LoDTensor: + x.lod = [[2, 3, 2]] + x.data = [1, 3, 2, 4, 6, 5, 1] + x.dims = [7, 1] + 输出为张量（Tensor）： + out.dim = [3, 1] + with condition len(x.lod[-1]) == out.dims[0] + 对于不同的pool_type： + average: out.data = [2, 4, 3], where 2=(1+3)/2, 4=(2+4+6)/3, 3=(5+1)/2 + sum : out.data = [4, 12, 6], where 4=1+3, 12=2+4+6, 6=5+1 + sqrt : out.data = [2.82, 6.93, 4.24], where 2.82=(1+3)/sqrt(2), + 6.93=(2+4+6)/sqrt(3), 4.24=(5+1)/sqrt(2) + max : out.data = [3, 6, 5], where 3=max(1,3), 6=max(2,4,6), 5=max(5,1) + last : out.data = [3, 6, 1], where 3=last(1,3), 6=last(2,4,6), 1=last(5,1) + first : out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) + +参数： + - **input** (variable) - 输入变量，为LoDTensor + - **pool_type** (string) - 池化类型。支持average,sum,sqrt和max + - **is_test** (bool, 默认为 False) - 用于区分训练模式和测试评分模式 + +返回：sequence pooling 变量，类型为张量（Tensor) + +**代码示例**: + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[7, 1], + dtype='float32', lod_level=1) + avg_x = fluid.layers.sequence_pool(input=x, pool_type='average') + sum_x = fluid.layers.sequence_pool(input=x, pool_type='sum') + sqrt_x = fluid.layers.sequence_pool(input=x, pool_type='sqrt') + max_x = fluid.layers.sequence_pool(input=x, pool_type='max') + last_x = fluid.layers.sequence_pool(input=x, pool_type='last') + first_x = fluid.layers.sequence_pool(input=x, pool_type='first') + + + + + + + + + +.. _cn_api_fluid_layers_sequence_reshape: + +sequence_reshape +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_reshape(input, new_dim) + +Sequence Reshape Layer +该层重排输入序列。用户设置新维度。每一个序列的的长度通过原始长度、原始维度和新的维度计算得出。以下实例帮助解释该层的功能 + +.. code-block:: python + + x是一个LoDTensor: + x.lod = [[0, 2, 6]] + x.data = [[1, 2], [3, 4], + [5, 6], [7, 8], + [9, 10], [11, 12]] + x.dims = [6, 2] + 设置 new_dim = 4 + 输出为LoDTensor: + out.lod = [[0, 1, 3]] + + out.data = [[1, 2, 3, 4], + [5, 6, 7, 8], + [9, 10, 11, 12]] + out.dims = [3, 4] + +目前仅提供1-level LoDTensor，请确保(原长度*原维数)可以除以新的维数，每个序列没有余数。 + +参数： + - **input** (Variable)-一个2-D LoDTensor,模型为[N,M]，维度为M + - **new_dim** (int)-新维度，输入LoDTensor重新塑造后的新维度 + +返回：根据新维度重新塑造的LoDTensor + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(shape=[5, 20], dtype='float32', lod_level=1) + x_reshaped = fluid.layers.sequence_reshape(input=x, new_dim=10) + + + + + + + + + +.. _cn_api_fluid_layers_sequence_reverse: + +sequence_reverse +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_reverse(x, name=None) + +**实现SequenceReverse（序列倒序）运算** + +在第0维上将输入 ``x`` 的各序列倒序。 + +:: + + 假设 ``x`` 是一个形为 (5,4) 的LoDTensor， lod信息为 [[0, 2, 5]]，其中， + + + X.data() = [ [1, 2, 3, 4], [5, 6, 7, 8], # 索引为0，长度为2的序列 + + [9, 10, 11, 12], [13, 14, 15, 16], [17, 18, 19, 20] # 索引为1长度为3的序列 + +输出 ``Y`` 与 ``x`` 具有同样的维数和LoD信息。 于是有： + +:: + + Y.data() = [ [5, 6, 7, 8], [1, 2, 3, 4], # 索引为0，长度为2的逆序列 + [17, 18, 19, 20], [13, 14, 15, 16], [9, 10, 11, 12] # 索引为1，长度为3的逆序列 + +该运算在建立反dynamic RNN 网络中十分有用。 + +目前仅支持LoD层次(LoD level)为1的张量倒序。 + +参数: + - **x** (Variable) – 输入张量 + - **name** (basestring|None) – 输出变量的命名 + +返回：输出LoD张量 + +返回类型：Variable + + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_scatter: + +sequence_scatter +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_scatter(input, index, updates, name=None) + +序列散射层 + +这个operator将更新张量X，它使用Ids的LoD信息来选择要更新的行，并使用Ids中的值作为列来更新X的每一行。 + +**样例**: + +:: + + 输入： + input.data = [[1.0, 1.0, 1.0, 1.0, 1.0, 1.0], + [1.0, 1.0, 1.0, 1.0, 1.0, 1.0], [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]] + input.dims = [3, 6] + + index.data = [[0], [1], [2], [5], [4], [3], [2], [1], [3], [2], [5], [4]] index.lod = [[0, 3, 8, 12]] + + updates.data = [[0.3], [0.3], [0.4], [0.1], [0.2], [0.3], [0.4], [0.0], [0.2], [0.3], [0.1], [0.4]] updates.lod = [[ 0, 3, 8, 12]] + + + 输出： + out.data = [[1.3, 1.3, 1.4, 1.0, 1.0, 1.0], + [1.0, 1.0, 1.4, 1.3, 1.2, 1.1], [1.0, 1.0, 1.3, 1.2, 1.4, 1.1]] + out.dims = X.dims = [3, 6] + + +参数： + - **input** (Variable) - input 秩（rank） >= 1。 + - **index** (Variable) - LoD Tensor， index 是 sequence scatter op 的输入索引，该函数的input将依据index进行更新。 秩（rank）=1。由于用于索引dtype应该是int32或int64。 + - **updates** (Variable) - 一个 LoD Tensor , update 的值将被 sactter 到输入x。update 的 LoD信息必须与index一致。 + - **name** (str|None) - 输出变量名。默认：None。 + +返回： 输出张量维度应该和输入张量相同 + +返回类型：output (Variable) + + +**代码示例**: + +.. code-block:: python + + output = fluid.layers.sequence_scatter(input, index, updates) + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_slice: + +sequence_slice +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_slice(input, offset, length, name=None) + +**实现Sequence Slice(序列切片)运算** + +该层从给定序列中截取子序列。截取依据为所给的开始 ``offset`` （偏移量） 和子序列长 ``length`` 。 + +仅支持序列数据，LoD level（LoD层次为1） +:: + 输入变量： + + input.data = [[a1, a2], [b1, b2], [c1, c2], [d1, d2], [e1, e2]], + input.lod = [[3, 2]], + input.dims = (5, 2), + + 以及 offset.data = [[0], [1]] and length.data = [[2], [1]], + + 则输出变量为： + + out.data = [[a1, a2], [b1, b2], [e1, e2]], + out.lod = [[2, 1]], + out.dims = (3, 2). + +.. note:: + ``input`` ， ``offset`` ， ``length`` 的第一维大小应相同。 + ``offset`` 从0开始。 + +参数: + - **input** (Variable) – 输入变量 ，承载着完整的序列 + - **offset** (Variable) – 对每个序列切片的起始索引 + - **length** (Variable) – 每个子序列的长度 + - **name** (str|None) – 该层的命名，可选项。 如果None, 则自动命名该层 + +返回：输出目标子序列 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + import numpy as np + seqs = fluid.layers.data(name='x', shape=[10, 5], + dtype='float32', lod_level=1) + offset = fluid.layers.assign(input=np.array([[0, 1]]).astype("int32")) + length = fluid.layers.assign(input=np.array([[2, 1]]).astype("int32")) + subseqs = fluid.layers.sequence_slice(input=seqs, offset=offset, + length=length) + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_softmax: + +sequence_softmax +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_softmax(input, use_cudnn=False, name=None) + +该函数计算每一个序列所有时间步中的softmax激活函数。每个时间步的维度应为1。 + +输入张量的形状可为 :math:`[N，1]` 或者 :math:`[N]` , :math:`N` 是所有序列长度之和。 + +对mini-batch的第i序列： + +.. math:: + + Out\left ( X[lod[i]:lod[i+1]],: \right ) = \frac{exp(X[lod[i]:lod[i+1],:])}{\sum (exp(X[lod[i]:lod[i+1],:]))} + +例如，对有3个序列（可变长度）的mini-batch，每个包含2，3，2时间步，其lod为[0,2,5,7]，则在 :math:`X[0:2,:],X[2:5,:],X[5:7,:]` 中进行softmax运算，并且 :math:`N` 的结果为7. + +参数： + - **input** (Variable) - 输入变量，为LoDTensor + - **use_cudnn** (bool) - 是否用cudnn核，仅当下载cudnn库才有效。默认：False + - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。默认：None + +返回：sequence_softmax的输出 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[7, 1], + dtype='float32', lod_level=1) + x_sequence_softmax = fluid.layers.sequence_softmax(input=x) + + + + + + + + + + +.. _cn_api_fluid_layers_sequence_unpad: + +sequence_unpad +------------------------------- + +.. py:function:: paddle.fluid.layers.sequence_unpad(x, length, name=None) + +**实现Sequence Unpad(去除序列填充值)运算** + +该层从给定序列中删除padding（填充值），并且将该序列转变为未填充时的原序列作为该层的输出，并且实际长度可以在输出的LoD信息中取得。 + +:: + + 示例： + + 给定输入变量 ``x`` : + x.data = [[ 1.0, 2.0, 3.0, 4.0, 5.0], + [ 6.0, 7.0, 8.0, 9.0, 10.0], + [11.0, 12.0, 13.0, 14.0, 15.0]], + + 其中包含 3 个被填充到长度为5的序列，实际长度由输入变量 ``length`` 指明： + + length.data = [[2], [3], [4]], + + 则去填充（unpad）后的输出变量为： + + out.data = [[1.0, 2.0, 6.0, 7.0, 8.0, 11.0, 12.0, 13.0, 14.0]] + out.lod = [[2, 3, 4]] + + + +参数: + - **x** (Variable) – 输入变量，承载着多个填充后等长的序列 + - **length** (Variable) – 变量，指明去填充后各个序列所具有的实际长度 + - **name** (str|None) – 可选项，该层名称。 若为 None, 将自动命名该层 + +返回：变量，承载着去填充处理后的序列 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[10, 5], dtype='float32') + len = fluid.layers.data(name='length', shape=[1], dtype='int64') + out = fluid.layers.sequence_unpad(x=x, length=len) + + + + + + + + + + + + +.. _cn_api_fluid_layers_shape: + +shape +------------------------------- + +.. py:function:: paddle.fluid.layers.shape(input) + +shape算子 + +获得输入张量的形状。现在只支持输入CPU的Tensor。 + +参数： + - **input** （Variable）- （Tensor），输入张量。 + +返回： (Tensor），输入张量的形状，形状的数据类型是int32，它将与输入张量（Tensor）在同一设备上。 + +返回类型： 输出（Variable）。 + + +**代码示例：** + +.. code-block:: python + + input = layers.data( + name="input", shape=[3, 100, 100], dtype="float32") + out = layers.shape(input) + + + + + + + + +.. _cn_api_fluid_layers_sigmoid_cross_entropy_with_logits: + +sigmoid_cross_entropy_with_logits +------------------------------- + +.. py:function:: paddle.fluid.layers.sigmoid_cross_entropy_with_logits(x, label, name=None) + +在类别不相互独立的分类任务中，该函数可以衡量按元素顺序的可能性误差。可以这么认为，为单一数据点预测标签，它们之间不是完全互斥的关系。例如，一篇新闻文章可以同时关于政治，科技，体育或者同时不包含这些内容。 + +逻辑loss可通过下式计算： + +.. math:: + loss = -Labels * log(sigma(X)) - (1 - Labels) * log(1 - sigma(X)) + +已知: + +.. math:: + sigma(X) = \frac{1}{1 + exp(-X)} + +代入最开始的式子， + +.. math:: + loss = X - X * Labels + log(1 + exp(-X)) + +为了计算稳定性，防止 :math:`exp(-X)` 溢出，当 :math:`X<0` 时，loss将采用以下公式计算: + +.. math:: + loss = max(X, 0) - X * Labels + log(1 + exp(-|X|)) + +输入 ``X`` 和 ``label`` 都可以携带LoD信息。当输出仅采用输入 ``X`` 的LoD。 + + + +参数: + - **x** (Variable) - (Tensor, 默认 Tensor)，形为 N x D 的二维张量，N为batch大小，D为类别数目。该输入是一个由先前运算得出的logit组成的张量。logit是未标准化(unscaled)的log概率， 公式为 :math:`log(\frac{p}{1-p})` + - **label** (Variable) - (Tensor, 默认 Tensor) 具有和X相同类型，相同形状的二维张量。该输入张量代表了每个logit的可能标签 + - **name** (basestring|None) - 输出的名称 + +返回： (Tensor, 默认Tensor), 形为 N x D 的二维张量，其值代表了按元素的逻辑loss + +返回类型: Variable + + + + + + + + + + + + +.. _cn_api_fluid_layers_similarity_focus: + +similarity_focus +------------------------------- + +.. py:function:: paddle.fluid.layers.similarity_focus(input, axis, indexes, name=None) + +**实现SimilarityFocus(相似度聚焦)运算** + +通过以下三种方式，该层生成一个和输入 ``input`` 同形的mask（掩码）： + +1. 根据 ``axis`` 和 ``indexes`` 提取一个三维张量，第一维为batch大小。 + 例如，如果 ``axis=1, indexes=[a]`` , 将得到矩阵 T=X[:, a, :, :] 。 + 该例中，如果输入X的形为 (BatchSize, A, B, C) ，则输出张量T的形为 (BatchSize, B, C) 。 +2. 对于每一个索引，在输出T中找到最大值。所以同一行、同一列最多只有一个数字，这意味着如果在第i行，第j列中找到最大值，那么在相应行、列中的其他数值都将被忽略。然后再在剩余的数值中找到下一个最大值。显然，将会产生 min（B,C）个数字，并把三维相似聚焦掩码张量相应位置的元素置为1，其余则置为0。对每个索引按元素进行or运算。 +3. 将这个三维相似度聚焦mask调整、适配于输入 ``input`` 的形状 + +请参照 `Similarity Focus Layer `_ 。 + +:: + + 例如 : + + 给定四维张量 x 形为 (BatchSize, C, A, B), 其中C 为通道Channel数目， + 特征图（feature map）的形为（A,B）： + + x.shape = (2, 3, 2, 2) + x.data = [[[[0.8, 0.1], + [0.4, 0.5]], + + [[0.9, 0.7], + [0.9, 0.9]], + + [[0.8, 0.9], + [0.1, 0.2]]], + + + [[[0.2, 0.5], + [0.3, 0.4]], + + [[0.9, 0.7], + [0.8, 0.4]], + + [[0.0, 0.2], + [0.4, 0.7]]]] + + 给定轴: 1 (即channel轴) + 给定索引: [0] + + 于是我们得到一个与输入同形的四维输出张量： + out.shape = (2, 3, 2, 2) + out.data = [[[[1.0, 0.0], + [0.0, 1.0]], + + [[1.0, 0.0], + [0.0, 1.0]], + + [[1.0, 0.0], + [0.0, 1.0]]], + + [[[0.0, 1.0], + [1.0, 0.0]], + + [[0.0, 1.0], + [1.0, 0.0]], + + [[0.0, 1.0], + [1.0, 0.0]]]] + + + +参数: + - **input** (Variable) – 输入张量(默认类型为float)。应为一个四维张量，形为[BatchSize, A, B, C] + - **axis** (int) – 指明要选择的轴。 可能取值为 1, 2 或 3. + - **indexes** (list) – 指明选择维度的索引列表 + +返回：一个和输入张量同形、同类型的张量变量 + +返回类型：Variable + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data( + name='data', shape=[2, 3, 2, 2], dtype='float32') + x = fluid.layers.layer_norm(input=data, axis=1, indexes=[0]) + + + + + + + + + + + + +.. _cn_api_fluid_layers_slice: + +slice +------------------------------- + +.. py:function:: paddle.fluid.layers.slice(input, axes, starts, ends) + +slice算子。 + +沿多个轴生成输入张量的切片。与numpy类似： https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html Slice使用 ``axes`` 、 ``starts`` 和 ``ends`` 属性来指定轴列表中每个轴的起点和终点维度，它使用此信息来对输入数据张量切片。如果向 ``starts`` 或 ``ends`` 传递负值，则表示该维度结束之前的元素数目。如果传递给 ``starts`` 或 ``end`` 的值大于n（此维度中的元素数目），则表示n。对于未知大小维度的末尾进行切片，则建议传入 ``INT_MAX`` 。如果省略轴，则将它们设置为[0，...，ndim-1]。以下示例将解释切片如何工作： + +:: + + 案例1：给定：data=[[1,2,3,4],[5,6,7,8],] + axes=[0,1] + starts=[1,0] + ends=[2,3] + 则： + result=[[5,6,7],] + + 案例2：给定： + data=[[1,2,3,4],[5,6,7,8],] + starts=[0,1] + ends=[-1,1000] + 则： + result=[[2,3,4],] + +参数： + - **input** （Variable）- 提取切片的数据张量（Tensor）。 + - **axes** （List）- （list ）开始和结束的轴适用于。它是可选的。如果不存在，将被视为[0,1，...，len（starts）- 1]。 + - **starts** （List）- （list ）在轴上开始相应轴的索引。 + - **ends** （List）- （list ）在轴上结束相应轴的索引。 + +返回： 切片数据张量（Tensor）. + +返回类型： 输出（Variable）。 + + +**代码示例：** + +.. code-block:: python + + starts = [1, 0, 2] + ends = [3, 3, 4] + axes = [0, 1, 2] + + input = layers.data( + name="input", shape=[3, 4, 5, 6], dtype='float32') + + out = layers.slice(input, axes=axes, starts=starts, ends=ends) + + + + + + + +.. _cn_api_fluid_layers_smooth_l1: + +smooth_l1 +------------------------------- + +.. py:function:: paddle.fluid.layers.smooth_l1(x, y, inside_weight=None, outside_weight=None, sigma=None) + +该layer计算变量 ``x`` 和 ``y`` 的smooth L1 loss，它以 ``x`` 和 ``y`` 的第一维大小作为批处理大小。对于每个实例，按元素计算smooth L1 loss，然后计算所有loss。输出变量的形状是[batch_size, 1] + + +参数: + - **x** (Variable) - rank至少为2的张量。输入x的smmoth L1 loss 的op，shape为[batch_size, dim1，…],dimN]。 + - **y** (Variable) - rank至少为2的张量。与 ``x`` 形状一致的的smooth L1 loss op目标值。 + - **inside_weight** (Variable|None) - rank至少为2的张量。这个输入是可选的，与x的形状应该相同。如果给定， ``(x - y)`` 的结果将乘以这个张量元素。 + - **outside_weight** (变量|None) - 一个rank至少为2的张量。这个输入是可选的，它的形状应该与 ``x`` 相同。如果给定，那么 smooth L1 loss 就会乘以这个张量元素。 + - **sigma** (float|None) - smooth L1 loss layer的超参数。标量，默认值为1.0。 + +返回： smooth L1 loss, shape为 [batch_size, 1] + +返回类型: Variable + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[128], dtype='float32') + label = fluid.layers.data( + name='label', shape=[100], dtype='float32') + fc = fluid.layers.fc(input=data, size=100) + out = fluid.layers.smooth_l1(x=fc, y=label) + + + + + + + + + + +.. _cn_api_fluid_layers_soft_relu: + +soft_relu +------------------------------- + +.. py:function:: paddle.fluid.layers.soft_relu(x, threshold=40.0, name=None) + +SoftRelu 激活函数 + +.. math:: out=ln(1+exp(max(min(x,threshold),threshold)) + +参数: + - **x** (variable) - SoftRelu operator的输入 + - **threshold** (FLOAT|40.0) - SoftRelu的阈值 + - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名 + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name=”x”, shape=[2,3,16,16], dtype=”float32”) + y = fluid.layers.soft_relu(x, threshold=20.0) + + + + + + + + +.. _cn_api_fluid_layers_softmax: + +softmax +------------------------------- + +.. py:function:: paddle.fluid.layers.softmax(input, use_cudnn=True, name=None) + +softmax操作符的输入是任意阶的张量，输出张量和输入张量的维度相同。 + +首先逻辑上将输入张量压平至二维矩阵。矩阵的第二维（行数）和输入张量的最后一维相同。第一维（列数） +是输入张量除最后一维之外的所有维的产物。对矩阵的每一行来说,softmax操作将K维(K是矩阵的宽度,也就是输入张量的维度)任意实际值，压缩成K维取值为[0,1]之间的向量，压缩后k个值的和为1。 + + +softmax操作符计算k维向量输入中所有其他维的指数和指数值的累加和。维的指数比例和所有其他维的指数值之和作为softmax操作符的输出。 + +对矩阵中的每行i和每列j有： + +.. math:: + + Out[i,j] = \frac{exp(X[i,j])}{\sum_j exp(X[i,j])} + +参数： + - **input** (Variable) - 输入变量 + - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效 + - **name** (str|None) - 该层名称（可选）。若为空，则自动为该层命名。默认：None + +返回： softmax输出 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + fc = fluid.layers.fc(input=x, size=10) + softmax = fluid.layers.softmax(input=fc) + + + + + + + + + +.. _cn_api_fluid_layers_softmax_with_cross_entropy: + +softmax_with_cross_entropy +------------------------------- + +.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100, numeric_stable_mode=False, return_softmax=False) + +使用softmax的交叉熵在输出层已被广泛使用。该函数计算输入张量每一行的softmax标准化值，而后计算交叉熵。通过此种方式，可以得到更具数字稳定性的梯度值。 + +因为该运算是在内部进行logit上的softmax运算，所以它需要未标准化（unscaled）的logit。该运算不应该对softmax运算的输出进行操作，否则会得出错误结果。 + +当 ``soft_label`` 为 ``False`` 时，该运算接受互斥的硬标签，batch中的每一个样本都以为1的概率分类到一个类别中，并且仅有一个标签。 + +涉及到的等式如下: + +1.硬标签，即 one-hot label, 每个样本仅可分到一个类别 + +.. math:: + loss_j = -\text{logit}_{label_j} +\log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right), j = 1,..., K + +2.软标签，每个样本可能被分配至多个类别中 + +.. math:: + loss_j = -\sum_{i=0}^{K}\text{label}_i\left(\text{logit}_i - \log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right)\right), j = 1,...,K + +3.如果 ``numeric_stable_mode`` 为真，在通过softmax和标签计算交叉熵损失前， softmax 首先经由下式计算得出： + +.. math:: + max_j &= \max_{i=0}^{K}{\text{logit}_i} \\ + log\_max\_sum_j &= \log\sum_{i=0}^{K}\exp(logit_i - max_j)\\ + softmax_j &= \exp(logit_j - max_j - {log\_max\_sum}_j) + + +参数: + - **logits** (Variable) - 未标准化(unscaled)的log概率,一个形为 N X K 的二维张量。 N是batch大小，K是类别总数 + - **label** (Variable) - 2-D 张量，代表了正确标注（ground truth）, 如果 ``soft_label`` 为 False，则该参数是一个形为 N X 1 的Tensor 。如果 ``soft_label`` 为 True，它是 Tensor ，形为 N X K + - **soft_label** (bool) - 是否将输入标签当作软标签。默认为False + - **ignore_index** (int) - 指明要无视的目标值，使之不对输入梯度有贡献。仅在 ``soft_label`` 为False时有效，默认为-100 + - **numeric_stable_mode** (bool) – 标志位，指明是否使用一个具有更佳数学稳定性的算法。仅在 ``soft_label`` 为 False的GPU模式下生效. 若 ``soft_label`` 为 True 或者执行场所为CPU, 算法一直具有数学稳定性。 注意使用稳定算法时速度可能会变慢。默认为 False + - **return_softmax** (bool) – 标志位，指明是否额外返回一个softmax值， 同时返回交叉熵计算结果。默认为False + +返回: + - 如果 ``return_softmax`` 为 False， 则返回交叉熵，一个形为[N x 1]的二维张量 + - 如果 ``return_softmax`` 为 True，则返回元组 (loss, softmax) ，其中交叉熵loss为形为[N x 1]的二维张量，softmax为[N x K]的二维张量 + +返回类型:变量或者两个变量组成的元组 + + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[128], dtype='float32') + label = fluid.layers.data(name='label', shape=[1], dtype='int64') + fc = fluid.layers.fc(input=data, size=100) + out = fluid.layers.softmax_with_cross_entropy( + logits=fc, label=label) + + + + + + + + + + +.. _cn_api_fluid_layers_space_to_depth: + +space_to_depth +------------------------------- + +.. py:function:: paddle.fluid.layers.space_to_depth(x, blocksize, name=None) + +给该函数一个 ``blocksize`` 值，可以对形为[batch, channel, height, width]的输入LoD张量进行space_to_depth（广度至深度）运算。 + +该运算对成块的空间数据进行重组，形成深度。确切地说，该运算输出一个输入LoD张量的拷贝，其高度，宽度维度上的值移动至通道维度上。 + +``blocksize`` 参数指明了数据块大小。 + +重组时，依据 ``blocksize`` , 生成形为 :math:`[batch, channel * blocksize * blocksize, height/blocksize, width/blocksize]` 的输出： + +该运算适用于在卷积间重放缩激励函数，并保持所有的数据。 + + - 在各位置上，不重叠的，大小为 :math:`block\_size * block\_size` 的块重组入深度depth + - 输出张量的深度为 :math:`block\_size * block\_size * input\_channel` + - 输入各个块中的Y,X坐标变为输出张量通道索引的高序部位 + - channel可以被blocksize的平方整除 + - 高度，宽度可以被blocksize整除 + +参数: + - **x** (variable) – 输入LoD张量 + - **blocksize** (variable) – 在每个特征图上选择元素时采用的块大小，应该 > 2 + +返回：输出LoD tensor + +返回类型：Variable + +抛出异常： + - ``TypeError`` - ``blocksize`` 必须是long类型 + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data( + name='data', shape=[1, 4, 2, 2], dtype='float32') + space_to_depthed = fluid.layers.space_to_depth( + x=data, blocksize=2) + + + + + + + + + + +.. _cn_api_fluid_layers_split: + +split +------------------------------- + +.. py:function:: paddle.fluid.layers.split(input,num_or_sections,dim=-1,name=None) + +将输入张量分解成多个子张量 + +参数： + - **input** (Variable)-输入变量，类型为Tensor或者LoDTensor + - **num_or_sections** (int|list)-如果num_or_sections是整数，则表示张量平均划分为的相同大小子张量的数量。如果num_or_sections是一列整数，列表的长度代表子张量的数量，整数依次代表子张量的dim维度的大小 + - **dim** (int)-将要划分的维。如果dim<0,划分的维为rank(input)+dim + - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名 + +返回：一列分割张量 + +返回类型：列表(Variable) + +**代码示例**： + +.. code-block:: python + + # x是维为[3,9,5]的张量： + x0, x1, x2 = fluid.layers.split(x, num_or_sections=3, dim=1) + x0.shape # [3, 3, 5] + x1.shape # [3, 3, 5] + x2.shape # [3, 3, 5] + x0, x1, x2 = fluid.layers.split( + x, num_or_sections=[2, 3, 4], dim=1) + x0.shape # [3, 2, 5] + x1.shape # [3, 3, 5] + x2.shape # [3, 4, 5] + + + + + + + + + +.. _cn_api_fluid_layers_square_error_cost: + +square_error_cost +------------------------------- + +.. py:function:: paddle.fluid.layers.square_error_cost(input,label) + +方差估计层（Square error cost layer） + +该层接受输入预测值和目标值，并返回方差估计 + +对于预测值X和目标值Y，公式为： + +.. math:: + + Out = (X-Y)^{2} + +在以上等式中： + - **X** : 输入预测值，张量（Tensor) + - **Y** : 输入目标值，张量（Tensor） + - **Out** : 输出值，维度和X的相同 + +参数： + - **input** (Variable) - 输入张量（Tensor），带有预测值 + - **label** (Variable) - 标签张量（Tensor），带有目标值 + +返回：张量变量，存储输入张量和标签张量的方差 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + y = layers.data(name='y', shape=[1], dtype='float32') + y_predict = layers.data(name='y_predict', shape=[1], dtype='float32') + cost = layers.square_error_cost(input=y_predict, label=y) + + + + + + + + + +.. _cn_api_fluid_layers_squeeze: + +squeeze +------------------------------- + +.. py:function:: paddle.fluid.layers.squeeze(input, axes, name=None) + +向张量维度中移除单维输入。传入用于压缩的轴。如果未提供轴，所有的单一维度将从维中移除。如果选择的轴的形状条目不等于1，则报错。 + +:: + + + 例如： + + 例1： + 给定 + X.shape = (1,3,1,5) + axes = [0] + 得到 + Out.shape = (3,1,5) + 例2： + 给定 + X.shape = (1,3,1,5) + axes = [] + 得到 + Out.shape = (3,5) + +参数： + - **input** (Variable)-将要压缩的输入变量 + - **axes** (list)-一列整数，代表压缩的维 + - **name** (str|None)-该层名称 + +返回：输出压缩的变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = layers.data(name='x', shape=[5, 1, 10]) + y = layers.sequeeze(input=x, axes=[1]) + + + + + + + + + +.. _cn_api_fluid_layers_stack: + +stack +------------------------------- + +.. py:function:: paddle.fluid.layers.stack(x, axis=0) + +实现了stack层。 + +沿 ``axis`` 轴，该层对输入 ``x`` 进行stack运算。 + +输入 x 可以是单个变量, 或是多个变量组成的列表或元组。如果 x 是一个列表或元组, 那么这些变量必须同形。 假设每个输入的形都为 :math:`[d_0,d_1,...,d_{n−1}]` , 则输出变量的形为 :math:`[d_0,d_1,...,d_{axis}=len(x),...,d_{n−1}]` 。 如果 ``axis`` < 0, 则将其取代为 :math:`axis+rank(x[0])+1` 。 如果 ``axis`` 为 None, 则认为它是 0。 + +参数: + - **x** (Variable|list(Variable)|tuple(Variable)) – 输入变量 + - **axis** (int|None) – 对输入进行stack运算所在的轴 + +返回: 经stack运算后的变量 + +返回类型: Variable + + + + + + + + + + + +.. _cn_api_fluid_layers_stanh: + +stanh +------------------------------- + +.. py:function:: paddle.fluid.layers.stanh(x, scale_a=0.6666666666666666, scale_b=1.7159, name=None) + +STanh 激活算子（STanh Activation Operator.） + +.. math:: + \\out=b*\frac{e^{a*x}-e^{-a*x}}{e^{a*x}+e^{-a*x}}\\ + +参数： + - **x** (Variable) - STanh operator的输入 + - **scale_a** (FLOAT|2.0 / 3.0) - 输入的a的缩放参数 + - **scale_b** (FLOAT|1.7159) - b的缩放参数 + - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: STanh操作符的输出 + +返回类型: 输出(Variable) + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.stanh(x, scale_a=0.67, scale_b=1.72) + + + + + + + +.. _cn_api_fluid_layers_sum: + +sum +------------------------------- + +.. py:function:: paddle.fluid.layers.sum(x) + +sum算子。 + +该运算符对输入张量求和。所有输入都可以携带LoD（详细程度）信息，但是输出仅与第一个输入共享LoD信息。 + +参数： + - **x** （Variable）- （vector ）sum运算符的输入张量（Tensor）。 + +返回: (Tensor）求和算子的输出张量。 + +返回类型： Variable + + +**代码示例：** + +.. code-block:: python + + input = layers.data(name="input", shape=[13, 11], dtype='float32') + out = layers.sum(input) + + + + + + + +.. _cn_api_fluid_layers_swish: + +swish +------------------------------- + +.. py:function:: paddle.fluid.layers.swish(x, beta=1.0, name=None) + +Swish 激活函数 + +.. math:: + out = \frac{x}{1 + e^{- beta x}} + +参数： + - **x** (Variable) - Swish operator 的输入 + - **beta** (浮点|1.0) - Swish operator 的常量beta + - **name** (str|None) - 这个层的名称(可选)。如果设置为None，该层将被自动命名。 + +返回: Swish operator 的输出 + +返回类型: output(Variable) + + +**代码示例：** + +.. code-block:: python + + x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32") + y = fluid.layers.swish(x, beta=2.0) + + + + + + + + + +.. _cn_api_fluid_layers_topk: + +topk +------------------------------- +.. py:function:: paddle.fluid.layers.topk(input, k, name=None) + +这个运算符用于查找最后一维的前k个最大项，返回它们的值和索引。 + +如果输入是（1-D Tensor），则找到向量的前k最大项，并以向量的形式输出前k最大项的值和索引。values[j]是输入中第j最大项，其索引为indices[j]。 +如果输入是更高阶的张量，则该operator会基于最后一维计算前k项 + +例如： + +.. code-block:: text + + + 如果: + input = [[5, 4, 2, 3], + [9, 7, 10, 25], + [6, 2, 10, 1]] + k = 2 + + 则: + 第一个输入: + values = [[5, 4], + [10, 25], + [6, 10]] + + 第二个输入: + indices = [[0, 1], + [2, 3], + [0, 2]] + +参数： + - **input** (Variable)-输入变量可以是一个向量或者更高阶的张量 + - **k** (int)-在输入最后一纬中寻找的前项数目 + - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名。默认为空 + +返回：含有两个元素的元组。元素都是变量。第一个元素是最后维切片的前k项。第二个元素是输入最后维里值索引 + +返回类型：元组[变量] + +抛出异常: ``ValueError`` - 如果k<1或者k不小于输入的最后维 + +**代码示例**： + +.. code-block:: python + + top5_values, top5_indices = layers.topk(input, k=5) + + + + + + + + + +.. _cn_api_fluid_layers_transpose: + +transpose +------------------------------- + +.. py:function:: paddle.fluid.layers.transpose(x,perm,name=None) + +根据perm对输入矩阵维度进行重排。 + +返回张量（tensor）的第i维对应输入维度矩阵的perm[i]。 + +参数： + - **x** (Variable) - 输入张量（Tensor) + - **perm** (list) - 输入维度矩阵的转置 + - **name** (str) - 该层名称（可选） + +返回： 转置后的张量（Tensor） + +返回类型：变量（Variable） + +**代码示例**: + +.. code-block:: python + + # 请使用 append_batch_size=False 来避免 + # 在数据张量中添加多余的batch大小维度 + x = fluid.layers.data(name='x', shape=[5, 10, 15], + dtype='float32', append_batch_size=False) + x_transposed = layers.transpose(x, perm=[1, 0, 2]) + + + + + + + + + +.. _cn_api_fluid_layers_uniform_random_batch_size_like: + +uniform_random_batch_size_like +------------------------------- + +.. py:function:: paddle.fluid.layers.uniform_random_batch_size_like(input, shape, dtype='float32', input_dim_idx=0, output_dim_idx=0, min=-1.0, max=1.0, seed=0) + +uniform_random_batch_size_like算子。 + +此运算符使用与输入张量（Tensor）相同的batch_size初始化张量（Tensor），并使用从均匀分布中采样的随机值。 + +参数： + - **input** （Variable）- 其input_dim_idx'th维度指定batch_size的张量（Tensor）。 + - **shape** （元组|列表）- 输出的形状。 + - **input_dim_idx** （Int）- 默认值0.输入批量大小维度的索引。 + - **output_dim_idx** （Int）- 默认值0.输出批量大小维度的索引。 + - **min** （Float）- （默认 1.0）均匀随机的最小值。 + - **max** （Float）- （默认 1.0）均匀随机的最大值。 + - **seed** （Int）- （int，default 0）用于生成样本的随机种子。0表示使用系统生成的种子。注意如果seed不为0，则此运算符将始终每次生成相同的随机数。 + - **dtype** （np.dtype | core.VarDesc.VarType | str） - 数据类型：float32，float_16，int等。 + +返回: 指定形状的张量（Tensor）将使用指定值填充。 + +返回类型: Variable + + +**代码示例：** + +.. code-block:: python + + + input = layers.data(name="input", shape=[13, 11], dtype='float32') + out = layers.uniform_random_batch_size_like(input, [-1, 11]) + + + + + +.. _cn_api_fluid_layers_unsqueeze: + +unsqueeze +------------------------------- + +.. py:function:: paddle.fluid.layers.unsqueeze(input, axes, name=None) + +向张量shape中插入单维函数。获取一个必需axes值，用来插入维度列表。输出张量显示轴的维度索引值。 + +比如： + 给定一个张量，例如维度为[3,4,5]的张量，轴为[0,4]的未压缩张量，维度为[1,3,4,5,1] + +参数： + - **input** (Variable)- 未压缩的输入变量 + - **axes** (list)- 一列整数，代表要插入的维数 + - **name** (str|None) - 该层名称 + +返回：输出未压缩变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + x = layers.data(name='x', shape=[5, 10]) + y = layers.unsequeeze(input=x, axes=[1]) + + + + + + + + + + +.. _cn_api_fluid_layers_unstack: + +unstack +------------------------------- + +.. py:function:: paddle.fluid.layers.unstack(x, axis=0, num=None) + +实现了unstack层。 + +沿 ``axis`` 轴，该层对输入 ``x`` 进行unstack运算。 + +如果 ``axis`` <0，则将其以 :math:`axis+rank(x)` 代之。 + +如果 ``num`` 为 None，则它可以从 ``x.shape[axis]`` 中推断而来。 + +如果 ``x.shape[axis]`` <= 0或者Unknown, 则抛出异常 ``ValueError`` 。 + +参数: + - **x** (Variable|list(Variable)|tuple(Variable)) – 输入变量 + - **axis** (int|None) – 对输入进行unstack运算所在的轴 + - **num** (int|None) - 输出变量的数目 + +返回: 经unstack运算后的变量 + +返回类型: list(Variable) + + + + + + + + + + + +.. _cn_api_fluid_layers_warpctc: + +warpctc +------------------------------- + +.. py:function:: paddle.fluid.layers.warpctc(input, label, blank=0, norm_by_times=False, use_cudnn=False)) + +该操作符集成了 `开源Warp-CTC库 `_ ，计算基于神经网络的时序类分类（CTC）损失。原生softmax激活函数集成到Wrap-CTC库中，操作符也可称作含CTC的softmax，将输入张量每一行的值正则化。 + +参数： + - **input** （Variable） - 变长序列的非尺度化概率，是一个含LoD信息的二维张量。shape为[Lp，num_classes+1]，Lp是所有输出序列长度之和，num_classes是实际类别数。（不包括空白标签） + - **label** (Variable） - 变长序列中正确标记的数据，是一个含LoD信息的二维张量。shape为[Lg，1]，Lg是所有标签长度之和 + - **blank** （int，默认0） - 基于神经网络的时序类分类（CTC）损失的空白标签索引，在半开区间间隔内[0，num_classes+1] + - **norm_by_times** （bool，默认false） - 是否利用时间步长（即序列长度）的数量对梯度进行正则化。如果warpctc层后面跟着mean_op则无需对梯度正则化。 + - **use_cudnn** (bool, 默认false) - 是否使用cudnn + +返回：基于神经网络的时序类分类（CTC）损失，是一个shape为[batch_size，1]的二维张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + label = fluid.layers.data(shape=[11, 8], dtype='float32', lod_level=1) + predict = fluid.layers.data(shape=[11, 1], dtype='float32') + cost = fluid.layers.warpctc(input=predict, label=label) + + + + + + + + + + + +============ + ops +============ + + +.. _cn_api_fluid_layers_abs: + +abs +------------------------------- + +.. py:function:: paddle.fluid.layers.abs(x, name=None) + + +参数: + - **x** - abs运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Abs运算符的输出。 + + + + + + + + + + + +.. _cn_api_fluid_layers_ceil: + +ceil +------------------------------- + +.. py:function:: paddle.fluid.layers.ceil(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Ceil运算符的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_cos: + +cos +------------------------------- + +.. py:function:: paddle.fluid.layers.cos(x, name=None) + + + +参数: + - **x** - cos运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Cos运算符的输出 + + + + + + + + + + +.. _cn_api_fluid_layers_cumsum: + +cumsum +------------------------------- + +.. py:function:: paddle.fluid.layers.cumsum(x,axis=None,exclusive=None,reverse=None + +沿给定轴的元素的累加和。默认结果的第一个元素和输入的第一个元素一致。如果exlusive为真，结果的第一个元素则为0。 + +参数： + - **x** -累加操作符的输入 + - **axis** (INT)-需要累加的维。-1代表最后一维。[默认 -1]。 + - **exclusive** (BOOLEAN)-是否执行exclusive累加。[默认false]。 + - **reverse** (BOOLEAN)-若为true,则以相反顺序执行累加。[默认 false]。 + +返回：累加器的输出 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name="input", shape=[32, 784]) + result = fluid.layers.cumsum(data, axis=0) + + + + + + + + + +.. _cn_api_fluid_layers_exp: + +exp +------------------------------- + +.. py:function:: paddle.fluid.layers.exp(x, name=None) + + +参数: + - **x** - Exp运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Exp算子的输出 + + + + + + + + + + +.. _cn_api_fluid_layers_floor: + +floor +------------------------------- + +.. py:function:: paddle.fluid.layers.floor(x, name=None) + + + +参数: + - **x** - Floor运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Floor运算符的输出。 + + + + + + + + + + + +.. _cn_api_fluid_layers_hard_shrink: + +hard_shrink +------------------------------- + +.. py:function:: paddle.fluid.layers.hard_shrink(x,threshold=None) + +HardShrink激活函数(HardShrink activation operator) + + +.. math:: + + out = \begin{cases} + x, \text{if } x > \lambda \\ + x, \text{if } x < -\lambda \\ + 0, \text{otherwise} + \end{cases} + +参数： + - **x** - HardShrink激活函数的输入 + - **threshold** (FLOAT)-HardShrink激活函数的threshold值。[默认：0.5] + +返回：HardShrink激活函数的输出 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name="input", shape=[784]) + result = fluid.layers.hard_shrink(x=data, threshold=0.3) + + + + + + + + + +.. _cn_api_fluid_layers_logsigmoid: + +logsigmoid +------------------------------- + +.. py:function:: paddle.fluid.layers.logsigmoid(x, name=None) + + + +参数: + - **x** - LogSigmoid运算符的输入 + - **use_mkldnn** (bool) - （默认为False）仅在 ``mkldnn`` 内核中使用 + +返回： LogSigmoid运算符的输出 + + + + + + + + + + +.. _cn_api_fluid_layers_reciprocal: + +reciprocal +------------------------------- + +.. py:function:: paddle.fluid.layers.reciprocal(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Reciprocal运算符的输出。 + + + + + + + + + + + + + +.. _cn_api_fluid_layers_round: + +round +------------------------------- + +.. py:function:: paddle.fluid.layers.round(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Round运算符的输出。 + + + + + + + + + + +.. _cn_api_fluid_layers_sigmoid: + +sigmoid +------------------------------- + +.. py:function:: paddle.fluid.layers.sigmoid(x, name=None) + + + +参数: + - **x** - Sigmoid运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Sigmoid运算输出. + + + + + + + + + + +.. _cn_api_fluid_layers_sin: + +sin +------------------------------- + +.. py:function:: paddle.fluid.layers.sin(x, name=None) + + +参数: + - **x** - sin运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Sin运算符的输出。 + + + + + + + + + + + +.. _cn_api_fluid_layers_softplus: + +softplus +------------------------------- + +.. py:function:: paddle.fluid.layers.softplus(x,name=None) + +参数： + - **x** : Softplus操作符的输入 + - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 + +返回：Softplus操作后的结果 + + + + + + + + + +.. _cn_api_fluid_layers_softshrink: + +softshrink +------------------------------- + +.. py:function:: paddle.fluid.layers.softshrink(x, name=None) + +Softshrink激活算子 + +.. math:: + out = \begin{cases} + x - \lambda, \text{if } x > \lambda \\ + x + \lambda, \text{if } x < -\lambda \\ + 0, \text{otherwise} + \end{cases} + +参数： + - **x** - Softshrink算子的输入 + - **lambda** （FLOAT）- 非负偏移量。 + +返回： Softshrink运算符的输出 + + + + + + + + + + +.. _cn_api_fluid_layers_softsign: + +softsign +------------------------------- + +.. py:function:: Paddle.fluid.layers.softsign(x,name=None) + +参数： + - **x** : Softsign操作符的输入 + - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 + +返回：Softsign操作后的结果 + + + + + + + + + +.. _cn_api_fluid_layers_sqrt: + +sqrt +------------------------------- + +.. py:function:: paddle.fluid.layers.sqrt(x, name=None) + + +参数: + - **x** - Sqrt运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Sqrt算子的输出。 + + + + + + + + + + + +.. _cn_api_fluid_layers_square: + +square +------------------------------- + +.. py:function:: paddle.fluid.layers.square(x,name=None) + +参数: + - **x** : 平方操作符的输入 + - **use_mkldnn** (bool, 默认false) 仅在mkldnn核中使用 + +返回：平方后的结果 + + + + + + + + + +.. _cn_api_fluid_layers_tanh: + +tanh +------------------------------- + +.. py:function:: paddle.fluid.layers.tanh(x, name=None) + + + +参数: + - **x** - Tanh运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Tanh算子的输出。 + + + + + + + + + + + +.. _cn_api_fluid_layers_tanh_shrink: + +tanh_shrink +------------------------------- + +.. py:function:: paddle.fluid.layers.tanh_shrink(x, name=None) + + +参数: + - **x** - TanhShrink运算符的输入 + - **use_mkldnn** (bool)- （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： tanh_shrink算子的输出 + + + + + + + + + +.. _cn_api_fluid_layers_thresholded_relu: + +thresholded_relu +------------------------------- + +.. py:function:: paddle.fluid.layers.thresholded_relu(x,threshold=None) + +ThresholdedRelu激活函数 + +.. math:: + + out = \left\{\begin{matrix} + x, if&x > threshold\\ + 0, &otherwise + \end{matrix}\right. + +参数： +- **x** -ThresholdedRelu激活函数的输入 +- **threshold** (FLOAT)-激活函数threshold的位置。[默认1.0]。 + +返回：ThresholdedRelu激活函数的输出 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name="input", shape=[1]) + result = fluid.layers.thresholded_relu(data, threshold=0.4) + + + + + + + + + +.. _cn_api_fluid_layers_uniform_random: + +uniform_random +------------------------------- + +.. py:function:: Paddle.fluid.layers.uniform_random(shape,dtype=None,min=None,max=None,seed=None) +该操作符初始化一个张量，该张量的值是从均匀分布中抽样的随机值 + +参数： + - **shape** (LONGS)-输出张量的维 + - **min** (FLOAT)-均匀随机分布的最小值。[默认 -1.0] + - **max** (FLOAT)-均匀随机分布的最大值。[默认 1.0] + - **seed** (INT)-随机种子，用于生成样本。0表示使用系统生成的种子。注意如果种子不为0，该操作符每次都生成同样的随机数。[默认 0] + - **dtype** (INT)-输出张量数据类型。[默认5(FP32)] + +返回：正态随机操作符的输出张量 + +**代码示例**： + +.. code-block:: python + + result = fluid.layers.uniform_random(shape=[32, 784]) + + + + + + + + + + + +============ + tensor +============ + + +.. _cn_api_fluid_layers_argmax: + +argmax +------------------------------- + +.. py:function:: paddle.fluid.layers.argmin(x,axis=0) + +**argmax** + +该功能计算输入张量元素中最大元素的索引，张量的元素在提供的轴上。 + +参数： + - **x** (Variable)-用于计算最大元素索引的输入 + - **axis** (int)-用于计算索引的轴 + +返回：存储在输出中的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.argmax(x=in, axis=0) + out = fluid.layers.argmax(x=in, axis=-1) + + + + + + + + + +.. _cn_api_fluid_layers_argmin: + +argmin +------------------------------- + +.. py:function:: paddle.fluid.layers.argmin(x,axis=0) + +**argmin** + +该功能计算输入张量元素中最小元素的索引，张量元素在提供的轴上。 + +参数： + - **x** (Variable)-计算最小元素索引的输入 + - **axis** (int)-计算索引的轴 + +返回：存储在输出中的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.argmin(x=in, axis=0) + out = fluid.layers.argmin(x=in, axis=-1) + + + + + + + + + +.. _cn_api_fluid_layers_argsort: + +argsort +------------------------------- + +.. py:function:: paddle.fluid.layers.argsort(input,axis=-1,name=None) + +对输入变量沿给定轴进行排序，输出排序好的数据和相应的索引，其维度和输入相同 + +.. code-block:: text + + 例如： + 给定 input 并指定 axis=-1 + + input = [[0.15849551, 0.45865775, 0.8563702 ], + [0.12070083, 0.28766365, 0.18776911]], + + 执行argsort操作后，得到排序数据： + + out = [[0.15849551, 0.45865775, 0.8563702 ], + [0.12070083, 0.18776911, 0.28766365]], + + 根据指定axis排序后的数据indices变为: + + indices = [[0, 1, 2], + [0, 2, 1]] + +参数： + - **input** (Variable)-用于排序的输入变量 + - **axis** (int)- 沿该参数指定的轴对输入进行排序。当axis<0,实际的轴为axis+rank(input)。默认为-1，即最后一维。 + - **name** (str|None)-（可选）该层名称。如果设为空，则自动为该层命名。 + +返回：一组已排序的数据变量和索引 + +返回类型：元组 + +**代码示例**： + +.. code-block:: python + + input = fluid.layers.data(data=[2, 3]) + out, indices = fluid.layers.argsort(input, axis=0) + + + + + + + + + +.. _cn_api_fluid_layers_assign: + +assign +------------------------------- + +.. py:function:: paddle.fluid.layers.assign(input,output=None) + +**Assign** + +该功能将输入变量复制到输出变量 + +参数： + - **input** (Variable|numpy.ndarray)-源变量 + - **output** (Variable|None)-目标变量 + +返回：作为输出的目标变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.create_tensor(dtype='float32') + hidden = fluid.layers.fc(input=data, size=10) + fluid.layers.assign(hidden, out) + + + + + + + + + +.. _cn_api_fluid_layers_cast: + +cast +------------------------------- + +.. py:function:: paddle.fluid.layers.cast(x,dtype) + +该层传入变量x,并用x.dtype将x转换成dtype类型，作为输出。 + +参数： + - **x** (Variable)-转换函数的输入变量 + - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出变量的数据类型 + +返回：转换后的输出变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name='x', shape=[13], dtype='float32') + result = fluid.layers.cast(x=data, dtype='float64') + + + + + + + + + +.. _cn_api_fluid_layers_concat: + +concat +------------------------------- + +.. py:function:: paddle.fluid.layers.concat(input,axis=0,name=None) + +**Concat** + +这个函数将输入连接在前面提到的轴上，并将其作为输出返回。 + +参数： + - **input** (list)-将要联结的张量列表 + - **axis** (int)-数据类型为整型的轴，其上的张量将被联结 + - **name** (str|None)-该层名称（可选）。如果设为空，则自动为该层命名。 + +返回：输出的联结变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.concat(input=[Efirst, Esecond, Ethird, Efourth]) + + + + + + + + + +.. _cn_api_fluid_layers_create_global_var: + +create_global_var +------------------------------- + +.. py:function:: paddle.fluid.layers.create_global_var(shape,value,dtype,persistable=False,force_cpu=False,name=None) + +在全局块中创建一个新的带有 ``value`` 的张量。 + +参数： + - **shape** (list[int])-变量的维度 + - **value** (float)-变量的值。填充新创建的变量 + - **dtype** (string)-变量的数据类型 + - **persistable** (bool)-如果是永久变量。默认：False + - **force_cpu** (bool)-将该变量压入CPU。默认：False + - **name** (str|None)-变量名。如果设为空，则自动创建变量名。默认：None. + +返回：创建的变量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + var = fluid.create_global_var(shape=[2,3], value=1.0, dtype='float32', + persistable=True, force_cpu=True, name='new_var') + + + + + + + + + +.. _cn_api_fluid_layers_create_parameter: + +create_parameter +------------------------------- + +.. py:function:: paddle.fluid.layers.create_parameter(shape,dtype,name=None,attr=None,is_bias=False,default_initializer=None) + +创建一个参数。该参数是一个可学习的变量，拥有梯度并且可优化。 + +注：这是一个低级别的API。如果您希望自己创建新的op，这个API将非常有用，无需使用layers。 + +参数： + - **shape** (list[int])-参数的维度 + - **dtype** (string)-参数的元素类型 + - **attr** (ParamAttr)-参数的属性 + - **is_bias** (bool)-当default_initializer为空，该值会对选择哪个默认初始化程序产生影响。如果is_bias为真，则使用initializer.Constant(0.0)，否则使用Xavier()。 + - **default_initializer** (Initializer)-参数的初始化程序 + +返回：创建的参数 + +**代码示例**： + +.. code-block:: python + + W = fluid.layers.create_parameter(shape=[784, 200], dtype='float32') + data = fluid.layers.data(name="img", shape=[64, 784], append_batch_size=False) + hidden = fluid.layers.matmul(x=data, y=W) + + + + + + + + + +.. _cn_api_fluid_layers_create_tensor: + +create_tensor +------------------------------- + +.. py:function:: paddle.fluid.layers.create_tensor(dtype,name=None,persistable=False) + +创建一个变量，存储数据类型为dtype的LoDTensor。 + +参数： + - **dtype** (string)-“float32”|“int32”|..., 创建张量的数据类型。 + - **name** (string)-创建张量的名称。如果未设置，则随机取一个唯一的名称。 + - **persistable** (bool)-是否将创建的张量设置为 persistable + +返回：一个张量，存储着创建的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + tensor = fluid.layers.create_tensor(dtype='float32') + + + + + + + + + + +.. _cn_api_fluid_layers_fill_constant: + +fill_constant +------------------------------- + +.. py:function:: paddle.fluid.layers.fill_constant(shape,dtype,value,force_cpu=False,out=None) + +**fill_constant** + +该功能创建一个张量，含有具体的shape,dtype和batch尺寸。并用 ``value`` 中提供的常量初始化该张量。 + +创建张量的属性stop_gradient设为True。 + +参数： + - **shape** (tuple|list|None)-输出张量的形状 + - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 + - **value** (float)-用于初始化输出张量的常量值 + - **out** (Variable)-输出张量 + - **force_cpu** (True|False)-若设为true,数据必须在CPU上 + +返回：存储着输出的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.fill_constant(shape=[1], value=0, dtype='int64') + + + + + + + + + +.. _cn_api_fluid_layers_fill_constant_batch_size_like: + +fill_constant_batch_size_like +------------------------------- + +.. py:function:: paddle.fluid.layers.fill_constant_batch_size_like(input,shape,dtype,value,input_dim_idx=0,output_dim_idx=0) + +该功能创建一个张量，含有具体的shape,dtype和batch尺寸。并用 ``Value`` 中提供的常量初始化该张量。该批尺寸从输入张量中获取。它还将stop_gradient设置为True. + +参数： + - **input** (Variable)-张量，其input_dim_idx个维具体指示batch_size + - **shape** (INTS)-输出的形状 + - **dtype** (INT)-可以为numpy.dtype。输出数据类型。默认为float32 + - **value** (FLOAT)-默认为0.将要被填充的值 + - **input_dim_idx** (INT)-默认为0.输入批尺寸维的索引 + - **output_dim_idx** (INT)-默认为0.输出批尺寸维的索引 + +返回：具有特定形状和值的张量 + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.fill_constant_batch_size_like( + input=like, shape=[1], value=0, dtype='int64') + + + + + + + + + + +.. _cn_api_fluid_layers_has_inf: + +has_inf +------------------------------- + +.. py:function:: paddle.fluid.layers.has_inf(x) + +测试x是否包括一个无穷数 + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回： + tensor变量存储输出值，包含一个bool型数值 + +返回类型：Variable + + + + + + + + + + + + + +.. _cn_api_fluid_layers_has_nan: + +has_nan +------------------------------- + +.. py:function:: paddle.fluid.layers.has_nan(x) + +测试x是否包含NAN + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回： + tensor变量存储输出值，包含一个bool型数值 + +返回类型：Variable + + + + + + + +.. _cn_api_fluid_layers_isfinite: + +isfinite +------------------------------- + +.. py:function:: paddle.fluid.layers.isfinite(x) + +测试x是否包含无穷大/NAN值，如果所有元素都是有穷数，返回Ture,否则返回False + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回: + Variable: tensor变量存储输出值，包含一个bool型数值 + +返回类型：Variable + + + + + + + + +.. _cn_api_fluid_layers_ones: + +ones +------------------------------- + +.. py:function:: paddle.fluid.layers.ones(shape,dtype,force_cpu=False) + +**ones** + +该功能创建一个张量，有具体的维度和dtype，初始值为1。 + +也将stop_gradient设置为True。 + +参数： + - **shape** (tuple|list|None)-输出张量的维 + - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 + +返回：存储在输出中的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.ones(shape=[1], dtype='int64') + + + + + + + + + +.. _cn_api_fluid_layers_reverse: + +reverse +------------------------------- + +.. py:function:: paddle.fluid.layers.reverse(x,axis) + +**reverse** + +该功能将给定轴上的输入‘x’逆序 + +参数： + - **x** (Variable)-预逆序的输入 + - **axis** (int|tuple|list) - 元素逆序排列的轴。如果该参数是一个元组或列表，则对该参数中每个元素值所指定的轴上进行逆序运算。 + +返回：逆序的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.reverse(x=in, axis=0) + # or: + out = fluid.layers.reverse(x=in, axis=[0,1]) + + + + + + + + + +.. _cn_api_fluid_layers_sums: + +sums +------------------------------- + +.. py:function:: paddle.fluid.layers.sums(input,out=None) + +该函数对输入进行求和，并返回求和结果作为输出。 + +参数： + - **input** (Variable|list)-输入张量，有需要求和的元素 + - **out** (Variable|None)-输出参数。求和结果。默认：None + +返回：输入的求和。和参数'out'等同 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + tmp = fluid.layers.zeros(shape=[10], dtype='int32') + i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10) + a0 = layers.array_read(array=tmp, i=i) + i = layers.increment(x=i) + a1 = layers.array_read(array=tmp, i=i) + mean_a0 = layers.mean(a0) + mean_a1 = layers.mean(a1) + a_sum = layers.sums(input=[mean_a0, mean_a1]) + + + + + + + + + +.. _cn_api_fluid_layers_tensor_array_to_tensor: + +tensor_array_to_tensor +------------------------------- + +.. py:function:: paddle.fluid.layers.tensor_array_to_tensor(input, axis=1, name=None) + +此函数在指定轴上连接LodTensorArray中的元素，并将其作为输出返回。 + + +简单示例如下： + +.. code-block:: text + + Given: + input.data = {[[0.6, 0.1, 0.3], + [0.5, 0.3, 0.2]], + [[1.3], + [1.8]], + [[2.3, 2.1], + [2.5, 2.4]]} + + axis = 1 + + Then: + output.data = [[0.6, 0.1, 0.3, 1.3, 2.3, 2.1], + [0.5, 0.3, 0.2, 1.8, 2.5, 2.4]] + output_index.data = [3, 1, 2] + +参数： + - **input** (list) - 输入的LodTensorArray + - **axis** (int) - 整数轴，tensor将会和它连接在一起 + - **name** (str|None) - 该layer的名字，可选。如果设置为none，layer将会被自动命名 + +返回： + Variable: 连接的输出变量,输入LodTensorArray沿指定axis连接。 + +返回类型： Variable + +**代码示例：** + +.. code-block:: python + + output, output_index = fluid.layers.tensor_array_to_tensor(input=tensor_array) + + + + + + + + + + + +.. _cn_api_fluid_layers_zeros: + +zeros +------------------------------- + +.. py:function:: paddle.fluid.layers.zeros(shape,dtype,force_cpu=False) + +**zeros** + +该功能创建一个张量，含有具体的维度和dtype，初始值为0. + +也将stop_gradient设置为True。 + +参数： + - **shape** (tuple|list|None)-输出张量的维 + - **dtype** (np.dtype|core.VarDesc.VarType|str)-输出张量的数据类型 + - **force_cpu** (bool,default False)-是否将输出保留在CPU上 + +返回：存储在输出中的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.zeros(shape=[1], dtype='int64') + + + + + + + + + + + +============ + learning_rate_scheduler +============ + + +.. _cn_api_fluid_layers_append_LARS: + +append_LARS +------------------------------- + +.. py:function:: paddle.fluid.layers.append_LARS(params_grads,learning_rate,weight_decay) + +对每一层的学习率运用LARS(LAYER-WISE ADAPTIVE RATE SCALING) + + + +参数： + - **learning_rate** -变量学习率。LARS的全局学习率。 + - **weight_decay** -Python float类型数 + +返回： 衰减的学习率 + +**代码示例** : + +.. code-block:: python + + learning_rate*=local_gw_ratio * sqrt(sumsq(param)) + / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param))) + + + + + + + +.. _cn_api_fluid_layers_exponential_decay: + +exponential_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.exponential_decay(learning_rate,decay_steps,decay_rate,staircase=False) + +在学习率上运用指数衰减。 +训练模型时，在训练过程中通常推荐降低学习率。每次 ``decay_steps`` 步骤中用 ``decay_rate`` 衰减学习率。 + +.. code-block:: text + + if staircase == True: + decayed_learning_rate = learning_rate * decay_rate ^ floor(global_step / decay_steps) + else: + decayed_learning_rate = learning_rate * decay_rate ^ (global_step / decay_steps) + +参数： + - **learning_rate** (Variable|float)-初始学习率 + - **decay_steps** (int)-见以上衰减运算 + - **decay_rate** (float)-衰减率。见以上衰减运算 + - **staircase** (Boolean)-若为True,按离散区间衰减学习率。默认：False + +返回：衰减的学习率 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + base_lr = 0.1 + sgd_optimizer = fluid.optimizer.SGD( + learning_rate=fluid.layers.exponential_decay( + learning_rate=base_lr, + decay_steps=10000, + decay_rate=0.5, + staircase=True)) + sgd_optimizer.minimize(avg_cost) + + + + + + + + + +.. _cn_api_fluid_layers_inverse_time_decay: + +inverse_time_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.inverse_time_decay(learning_rate, decay_steps, decay_rate, staircase=False) + +在初始学习率上运用逆时衰减。 + +训练模型时，在训练过程中通常推荐降低学习率。通过执行该函数，将对初始学习率运用逆向衰减函数。 + +.. code-block:: python + + if staircase == True: + decayed_learning_rate = learning_rate / (1 + decay_rate * floor(global_step / decay_step)) + else: + decayed_learning_rate = learning_rate / (1 + decay_rate * global_step / decay_step) + +参数： + - **learning_rate** (Variable|float)-初始学习率 + - **decay_steps** (int)-见以上衰减运算 + - **decay_rate** (float)-衰减率。见以上衰减运算 + - **staircase** (Boolean)-若为True，按间隔区间衰减学习率。默认：False + +返回：衰减的学习率 + +返回类型：变量（Variable） + +**示例代码：** + +.. code-block:: python + + base_lr = 0.1 + sgd_optimizer = fluid.optimizer.SGD( + learning_rate=fluid.layers.inverse_time_decay( + learning_rate=base_lr, + decay_steps=10000, + decay_rate=0.5, + staircase=True)) + sgd_optimizer.minimize(avg_cost) + + + + + + + + + +.. _cn_api_fluid_layers_natural_exp_decay: + +natural_exp_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.natural_exp_decay(learning_rate, decay_steps, decay_rate, staircase=False) + +将自然指数衰减运用到初始学习率上。 + +.. code-block:: python + + if not staircase: + decayed_learning_rate = learning_rate * exp(- decay_rate * (global_step / decay_steps)) + else: + decayed_learning_rate = learning_rate * exp(- decay_rate * (global_step / decay_steps)) + +参数： + - **learning_rate** - 标量float32值或变量。是训练过程中的初始学习率。 + - **decay_steps** - Python int32数 + - **decay_rate** - Python float数 + - **staircase** - Boolean.若设为true，每个decay_steps衰减学习率 + +返回：衰减的学习率 + + + + + + + + + +.. _cn_api_fluid_layers_noam_decay: + +noam_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.noam_decay(d_model,warmup_steps) + +Noam衰减方法。noam衰减的numpy实现如下。 + +.. code-block:: python + + import numpy as np + lr_value = np.power(d_model, -0.5) * np.min([ + np.power(current_steps, -0.5), + np.power(warmup_steps, -1.5) * current_steps]) + +请参照 `attention is all you need `_ + +参数： + - **d_model** (Variable)-模型的输入和输出维度 + - **warmup_steps** (Variable)-超参数 + +返回：衰减的学习率 + + + + + + + + + +.. _cn_api_fluid_layers_piecewise_decay: + +piecewise_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.piecewise_decay(boundaries,values) + +对初始学习率进行分段衰减。 + +该算法可用如下代码描述。 + +.. code-block:: text + + boundaries = [10000, 20000] + values = [1.0, 0.5, 0.1] + if step < 10000: + learning_rate = 1.0 + elif 10000 <= step < 20000: + learning_rate = 0.5 + else: + learning_rate = 0.1 + +参数： + - **boundaries** -一列代表步数的数字 + - **values** -一列学习率的值，从不同的步边界中挑选 + +返回：衰减的学习率 + + + + + + + + + +.. _cn_api_fluid_layers_polynomial_decay: + +polynomial_decay +------------------------------- + +.. py:function:: paddle.fluid.layers.polynomial_decay(learning_rate,decay_steps,end_learning_rate=0.0001,power=1.0,cycle=False) + +对初始学习率使用多项式衰减 + +.. code-block:: text + + if cycle: + decay_steps = decay_steps * ceil(global_step / decay_steps) + else: + global_step = min(global_step, decay_steps) + decayed_learning_rate = (learning_rate - end_learning_rate) * + (1 - global_step / decay_steps) ^ power + end_learning_rate + +参数： + - **learning_rate** (Variable|float32)-标量float32值或变量。是训练过程中的初始学习率。 + - **decay_steps** (int32)-Python int32数 + - **end_learning_rate** (float)-Python float数 + - **power** (float)-Python float数 + - **cycle** (bool)-若设为true，每decay_steps衰减学习率 + +返回：衰减的学习率 + +返回类型：变量（Variable） + + + + + + + + + + + +============ + detection +============ + + +.. _cn_api_fluid_layers_anchor_generator: + +anchor_generator +------------------------------- + +.. py:function:: paddle.fluid.layers.anchor_generator(input, anchor_sizes=None, aspect_ratios=None, variance=[0.1, 0.1, 0.2, 0.2], stride=None, offset=0.5, name=None) + +**Anchor generator operator** + +为快速RCNN算法生成锚，输入的每一位产生N个锚，N=size(anchor_sizes)*size(aspect_ratios)。生成锚的顺序首先是aspect_ratios循环，然后是anchor_sizes循环。 + +参数： + - **input** (Variable) - 输入特征图，格式为NCHW + - **anchor_sizes** (list|tuple|float) - 生成锚的锚大小，以绝对像素的形式表示，例如：[64.,128.,256.,512.]若锚的大小为64，则意味着这个锚的面积等于64**2。 + - **aspect_ratios** (list|tuple|float) - 生成锚的高宽比，例如[0.5,1.0,2.0] + - **variance** (list|tuple) - 变量，在框回归delta中使用。默认：[0.1,0.1,0.2,0.2] + - **stride** (list|tuple) - 锚在宽度和高度方向上的步长，比如[16.0,16.0] + - **offset** (float) - 先验框的中心位移。默认：0.5 + - **name** (str) - 先验框操作符名称。默认：None + +返回： + - Anchors(Varibale): 输出anchor，布局[H,W,num_anchors,4] , ``H`` 是输入的高度， ``W`` 是输入的宽度， ``num_priors`` 是输入每位的框数,每个anchor格式（未归一化）为(xmin,ymin,xmax,ymax) + + - Variances(Variable): 锚的扩展变量布局为 [H,W,num_priors,4]。 ``H`` 是输入的高度， ``W`` 是输入的宽度， ``num_priors`` 是输入每个位置的框数,每个变量的格式为(xcenter,ycenter,w,h)。 + +返回类型：anchor（Variable) + +**代码示例**： + +.. code-block:: python + + anchor, var = anchor_generator( + input=conv1, + anchor_sizes=[64, 128, 256, 512], + aspect_ratios=[0.5, 1.0, 2.0], + variance=[0.1, 0.1, 0.2, 0.2], + stride=[16.0, 16.0], + offset=0.5) + + + + + + + + + +.. _cn_api_fluid_layers_bipartite_match: + +bipartite_match +------------------------------- + +.. py:function:: paddle.fluid.layers.bipartite_match(dist_matrix, match_type=None, dist_threshold=None, name=None) + +该算子实现了贪心二分匹配算法，该算法用于根据输入距离矩阵获得与最大距离的匹配。对于输入二维矩阵，二分匹配算法可以找到每一行的匹配列（匹配意味着最大距离），也可以找到每列的匹配行。此运算符仅计算列到行的匹配索引。对于每个实例，匹配索引的数量是输入距离矩阵的列号。 + +它有两个输出，匹配的索引和距离。简单的描述是该算法将最佳（最大距离）行实体与列实体匹配，并且匹配的索引在ColToRowMatchIndices的每一行中不重复。如果列实体与任何行实体不匹配，则ColToRowMatchIndices设置为-1。 + +注意：输入距离矩阵可以是LoDTensor（带有LoD）或Tensor。如果LoDTensor带有LoD，则ColToRowMatchIndices的高度是批量大小。如果是Tensor，则ColToRowMatchIndices的高度为1。 + +注意：此API是一个非常低级别的API。它由 ``ssd_loss`` 层使用。请考虑使用 ``ssd_loss`` 。 + +参数： + - **dist_matrix** （变量）- 该输入是具有形状[K，M]的2-D LoDTensor。它是由每行和每列来表示实体之间的成对距离矩阵。例如，假设一个实体是具有形状[K]的A，另一个实体是具有形状[M]的B. dist_matrix [i] [j]是A[i]和B[j]之间的距离。距离越大，匹配越好。 + + 注意：此张量可以包含LoD信息以表示一批输入。该批次的一个实例可以包含不同数量的实体。 + + - **match_type** （string | None）- 匹配方法的类型，应为'bipartite'或'per_prediction'。[默认'二分']。 + - **dist_threshold** （float | None）- 如果match_type为'per_prediction'，则此阈值用于根据最大距离确定额外匹配的bbox，默认值为0.5。 + +返回： 返回一个包含两个元素的元组。第一个是匹配的索引（matched_indices），第二个是匹配的距离（matched_distance）。 + + **matched_indices** 是一个2-D Tensor，int类型的形状为[N，M]。 N是批量大小。如果match_indices[i][j]为-1，则表示B[j]与第i个实例中的任何实体都不匹配。否则，这意味着在第i个实例中B[j]与行match_indices[i][j]匹配。第i个实例的行号保存在match_indices[i][j]中。 + + **matched_distance** 是一个2-D Tensor，浮点型的形状为[N，M]。 N是批量大小。如果match_indices[i][j]为-1，则match_distance[i][j]也为-1.0。否则，假设match_distance[i][j]=d，并且每个实例的行偏移称为LoD。然后match_distance[i][j]=dist_matrix[d]+ LoD[i]][j]。 + +返回类型： 元组(tuple) + +**代码示例** + +.. code-block:: python + + x = fluid.layers.data(name='x', shape=[4], dtype='float32') + y = fluid.layers.data(name='y', shape=[4], dtype='float32') + iou = fluid.layers.iou_similarity(x=x, y=y) + matched_indices, matched_dist = fluid.layers.bipartite_match(iou) + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_box_coder: + +box_coder +------------------------------- + +.. py:function:: paddle.fluid.layers.box_coder(prior_box, prior_box_var, target_box, code_type='encode_center_size', box_normalized=True, name=None) + +Bounding Box Coder + +编码/解码带有先验框信息的目标边界框 + +编码规则描述如下： + +.. math:: + + ox &= (tx - px)/pw/pxv + + oy &= (ty - py)/ph/pyv + + ow &= log(abs(tw/pw))/pwv + + oh &= log(abs(th/ph))/phv + +解码规则描述如下： + +.. math:: + + ox &= (pw * pxv * tx * + px ) - tw/2 + + oy &= (ph * pyv * ty * + py ) - th/2 + + ow &= exp(pwv * tw ) * pw + tw/2 + + oh &= exp(phv * th ) * ph + th/2 + +其中tx，ty，tw，th分别表示目标框的中心坐标、宽度和高度。同样地，px，py，pw，ph表示先验框地中心坐标、宽度和高度。pxv，pyv，pwv，phv表示先验框变量，ox，oy，ow，oh表示编码/解码坐标、宽度和高度。 + +参数： + - **prior_box** (Variable) - 张量，默认float类型的张量。先验框是二维张量，维度为[M,4]，存储M个框，每个框代表[xmin，ymin，xmax，ymax]，[xmin，ymin]是先验框的左顶点坐标，如果输入数图像特征图，则接近坐标原点。[xmax,ymax]是先验框的右底点坐标 + - **prior_box_var** (Variable) - 张量，默认float类型的张量。先验框是二维张量，维度为[M,4]，存储M组变量。PriorBoxVar默认将每个元素置为1 + - **target_box** (Variable) - LoDTensor或者Tensor，当code_type为‘encode_center_size’，输入可以是二维LoDTensor，维度为[N,4]。当code_type为‘decode_center_size’输入可以为三维张量，维度为[N,M,4]。每个框代表[xmin,ymin,xmax,ymax]，[xmin,ymin]是先验框的左顶点坐标，如果输入数图像特征图，则接近坐标原点。[xmax,ymax]是先验框的右底点坐标。该张量包含LoD信息，代表一批输入。批的一个实例可以包含不同的实体数。 + - **code_type** (string，默认encode_center_size) - 编码类型用目标框 + - **box_normalized** (boolean，默认true) - 是否将先验框作为正则框 + +返回：（LoDTensor 或者 Tensor） + + - ``code_type`` 为 ``‘encode_center_size’`` 时，形为[N,M,4]的输出张量代表N目标框的结果，目标框用M先验框和变量编码。 + - ``code_type`` 为 ``‘decode_center_size’`` 时，N代表batch大小，M代表解码框数 + +返回类型：output_box（Variable） + + + + + + + + + + + +.. _cn_api_fluid_layers_density_prior_box: + +density_prior_box +------------------------------- + +.. py:function:: paddle.fluid.layers.density_prior_box(input, image, densities=None, fixed_sizes=None, fixed_ratios=None, variance=[0.1, 0.1, 0.2, 0.2], clip=False, steps=[0.0, 0.0], offset=0.5, flatten_to_2d=False, name=None) + + +**Density Prior Box Operator** + +为SSD算法(Single Shot MultiBox Detector)生成density prior box。 +每个input的位置产生N个prior box，其中，N通过densities, fixed_sizes and fixed_ratios +的量来决定。在每个input位置附近的box center格点，通过此op生成。格点坐标由densities决定， +density prior box的量由fixed_sizes and fixed_ratios决定。显然地，fixed_sizes +和densities相等。对于densities中的densities_i： + +.. math:: + + N\_density\_prior\_box =sum(N\_fixed\_ratios * {densities\_i}^2) + + +参数： + - **input** (Variable) - 输入变量，格式为NCHW + - **image** (Variable) - PriorBoxOp的输入图像数据，格式为NCHW + - **densities** (list|tuple|None) - 被生成的density prior boxes的densities，此属性应该是一个整数列表或数组。默认值为None + - **fixed_sizes** (list|tuple|None) - 被生成的density prior boxes的固定大小，此属性应该为和 :attr:`densities` 有同样长度的列表或数组。默认值为None + - **fixed_ratios** (list|tuple|None) - 被生成的density prior boxes的固定长度，如果该属性未被设置，同时 :attr:`densities` 和 :attr:`fix_sizes` 被设置，则 :attr:`aspect_ratios` 被用于生成 density prior boxes + - **variance** (list|tuple) - 将被用于density prior boxes编码的方差，默认值为:[0.1, 0.1, 0.2, 0.2] + - **clip(bool)** - 是否clip超出范围的box。默认值：False + - **step** (list|turple) - Prior boxes在宽度和高度的步长，如果step[0] == 0.0/step[1] == 0.0, input的the density prior boxes的高度/宽度的步长将被自动计算。默认值：Default: [0., 0.] + - **offset** (float) - Prior boxes中心补偿值，默认为：0.5 + - **flatten_to_2d** (bool) - 是否将output prior boxes和方差 ``flatten`` 至2维形状，第二个dim为4。默认值：False + - **name(str)** - density prior box op的名字，默认值: None + +返回： + tuple: 有两个变量的数组 (boxes, variances) + + boxes: PriorBox的输出density prior boxes + + 当flatten_to_2d为False时，形式为[H, W, num_priors, 4] + + 当flatten_to_2d为True时，形式为[H * W * num_priors, 4] + + H是输入的高度，W是输入的宽度 + + num_priors是输入中每个位置的总box count + + variances: PriorBox的expanded variance + + 当flatten_to_2d为False时，形式为[H, W, num_priors, 4] + + 当flatten_to_2d为True时，形式为[H * W * num_priors, 4] + + H是输入的高度，W是输入的宽度 + + num_priors是输入中每个位置的总box count + +**代码示例**: + +.. code-block:: python + + box, var = fluid.layers.density_prior_box( + input=conv1, + image=images, + densities=[4, 2, 1], + fixed_sizes=[32.0, 64.0, 128.0], + fixed_ratios=[1.], + clip=True, + flatten_to_2d=True) + + + + + + + + + + + +.. _cn_api_fluid_layers_detection_map: + +detection_map +------------------------------- + +.. py:function:: paddle.fluid.layers.detection_map(detect_res, label, function_num, background_label=0, overlap_threshold=0.3, evaluate_difficult=True, has_state=None, input_states=None, out_states=None, ap_version='integral') + +检测mAP评估运算符。一般步骤如下：首先，根据检测输入和标签计算TP（true positive）和FP（false positive），然后计算mAP评估值。支持'11 point'和积分mAP算法。请从以下文章中获取更多信息： + + https://sanchom.wordpress.com/tag/average-precision/ + + https://arxiv.org/abs/1512.02325 + +参数： + - **detect_res** （LoDTensor）- 用具有形状[M，6]的2-D LoDTensor来表示检测。每行有6个值：[label，confidence，xmin，ymin，xmax，ymax]，M是此小批量中检测结果的总数。对于每个实例，第一维中的偏移称为LoD，偏移量为N+1，如果LoD[i+1]-LoD[i]== 0，则表示没有检测到数据。 + - **label** （LoDTensor）- 2-D LoDTensor用来带有标签的真实数据。每行有6个值：[label，xmin，ymin，xmax，ymax，is_difficult]或5个值：[label，xmin，ymin，xmax，ymax]，其中N是此小批量中真实数据的总数。对于每个实例，第一维中的偏移称为LoD，偏移量为N + 1，如果LoD [i + 1] - LoD [i] == 0，则表示没有真实数据。 + - **class_num** （int）- 类的数目。 + - **background_label** （int，defalut：0）- background标签的索引，background标签将被忽略。如果设置为-1，则将考虑所有类别。 + - **overlap_threshold** （float）- 检测输出和真实数据下限的重叠阈值。 + - **evaluate_difficult** （bool，默认为true）- 通过切换来控制是否对difficult-data进行评估。 + - **has_state** （Tensor ）- 是shape[1]的张量，0表示忽略输入状态，包括PosCount，TruePos，FalsePos。 + - **input_states** - 如果不是None，它包含3个元素： + + 1、pos_count（Tensor）是一个shape为[Ncls，1]的张量，存储每类的输入正例的数量，Ncls是输入分类的数量。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。当输入（PosCount）为空时，不执行累积计算，仅计算当前小批量的结果。 + + 2、true_pos（LoDTensor）是一个shape为[Ntp，2]的2-D LoDTensor，存储每个类输入的正实例。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。 + + 3、false_pos（LoDTensor）是一个shape为[Nfp，2]的2-D LoDTensor，存储每个类输入的负实例。此输入用于在执行多个小批量累积计算时传递最初小批量生成的AccumPosCount。 + + - **out_states** - 如果不是None，它包含3个元素： + + 1、accum_pos_count（Tensor）是一个shape为[Ncls，1]的Tensor，存储每个类的实例数。它结合了输入（PosCount）和从输入中的（Detection）和（label）计算的正例数。 + + 2、accum_true_pos（LoDTensor）是一个shape为[Ntp'，2]的LoDTensor，存储每个类的正实例。它结合了输入（TruePos）和从输入中（Detection）和（label）计算的正实例数。 。 + + 3、accum_false_pos（LoDTensor）是一个shape为[Nfp'，2]的LoDTensor，存储每个类的负实例。它结合了输入（FalsePos）和从输入中（Detection）和（label）计算的负实例数。 + + - **ap_version** （string，默认'integral'）- AP算法类型，'integral'或'11 point'。 + +返回： 具有形状[1]的（Tensor），存储mAP的检测评估结果。 + +**代码示例** + +.. code-block:: python + + detect_res = fluid.layers.data( + name='detect_res', + shape=[10, 6], + append_batch_size=False, + dtype='float32') + label = fluid.layers.data( + name='label', + shape=[10, 6], + append_batch_size=False, + dtype='float32') + map_out = fluid.layers.detection_map(detect_res, label, 21) + + + + + + + + + + + +.. _cn_api_fluid_layers_detection_output: + +detection_output +------------------------------- + +.. py:function:: paddle.fluid.layers.detection_output(loc, scores, prior_box, prior_box_var, background_label=0, nms_threshold=0.3, nms_top_k=400, keep_top_k=200, score_threshold=0.01, nms_eta=1.0) + +Detection Output Layer for Single Shot Multibox Detector(SSD) + +该操作符用于获得检测结果，执行步骤如下： + + 1.根据先验框解码输入边界框（bounding box）预测 + + 2.通过运用多类非最大压缩(NMS)获得最终检测结果 + +请注意，该操作符不将最终输出边界框剪切至图像窗口。 + +参数： + - **loc** (Variable) - 一个三维张量（Tensor），维度为[N,M,4]，代表M个bounding bboxes的预测位置。N是批尺寸，每个边界框（boungding box）有四个坐标值，布局为[xmin,ymin,xmax,ymax] + - **scores** (Variable) - 一个三维张量（Tensor），维度为[N,M,C]，代表预测置信预测。N是批尺寸，C是类别数，M是边界框数。对每类一共M个分数，对应M个边界框 + - **prior_box** (Variable) - 一个二维张量（Tensor),维度为[M,4]，存储M个框，每个框代表[xmin,ymin,xmax,ymax]，[xmin,ymin]是anchor box的左上坐标，如果输入是图像特征图，靠近坐标系统的原点。[xmax,ymax]是anchor box的右下坐标 + - **prior_box_var** (Variable) - 一个二维张量（Tensor），维度为[M,4]，存有M变量群 + - **background_label** (float) - 背景标签索引，背景标签将会忽略。若设为-1，将考虑所有类别 + - **nms_threshold** (int) - 用于NMS的临界值（threshold） + - **nms_top_k** (int) - 基于score_threshold过滤检测后，根据置信数维持的最大检测数 + - **keep_top_k** (int) - NMS步后，每一图像要维持的总bbox数 + - **score_threshold** (float) - 临界函数（Threshold），用来过滤带有低置信数的边界框（bounding box）。若未提供，则考虑所有框 + - **nms_eta** (float) - 适应NMS的参数 + +返回： + 检测输出一个LoDTensor，维度为[No,6]。每行有6个值：[label,confidence,xmin,ymin,xmax,ymax]。No是该mini-batch的总检测数。对每个实例，第一维偏移称为LoD，偏移数为N+1，N是批尺寸。第i个图像有LoD[i+1]-LoD[i]检测结果。如果为0，第i个图像无检测结果。如果所有图像都没有检测结果，LoD所有元素都为0，并且输出张量只包含一个值-1。 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + pb = layers.data(name='prior_box', shape=[10, 4], + append_batch_size=False, dtype='float32') + pbv = layers.data(name='prior_box_var', shape=[10, 4], + append_batch_size=False, dtype='float32') + loc = layers.data(name='target_box', shape=[2, 21, 4], + append_batch_size=False, dtype='float32') + scores = layers.data(name='scores', shape=[2, 21, 10], + append_batch_size=False, dtype='float32') + nmsed_outs = fluid.layers.detection_output(scores=scores, + loc=loc, + prior_box=pb, + prior_box_var=pbv) + + + + + + + + + + + +.. _cn_api_fluid_layers_generate_proposal_labels: + +generate_proposal_labels +------------------------------- + +.. py:function:: paddle.fluid.layers.generate_proposal_labels(rpn_rois, gt_functiones, is_crowd, gt_boxes, im_info, batch_size_per_im=256, fg_fraction=0.25, fg_thresh=0.25, bg_thresh_hi=0.5, bg_thresh_lo=0.0, bbox_reg_weights=[0.1, 0.1, 0.2, 0.2], function_nums=None, use_random=True) + +**该函数可以应用于 Faster-RCNN 网络，生成建议标签。** + +该函数可以根据 ``GenerateProposals`` 的输出结果，即bounding boxes（区域框），groundtruth（正确标记数据）来对foreground boxes和background boxes进行采样，并计算loss值。 + +RpnRois 是RPN的输出box， 并由 ``GenerateProposals`` 来进一步处理, 这些box将与groundtruth boxes合并， 并根据 ``batch_size_per_im`` 和 ``fg_fraction`` 进行采样。 + +如果一个实例具有大于 ``fg_thresh`` (前景重叠阀值)的正确标记重叠，那么它会被认定为一个前景样本。 +如果一个实例具有的正确标记重叠大于 ``bg_thresh_lo`` 且小于 ``bg_thresh_hi`` (详见参数说明)，那么它将被认定为一个背景样本。 +在所有前景、背景框（即Rois regions of interest 直译：有意义的区域）被选择后，我们接着采用随机采样的方法来确保前景框数量不多于 batch_size_per_im * fg_fraction 。 + +对Rois中的每个box, 我们给它分配类标签和回归目标(box label)。最后 ``bboxInsideWeights`` 和 ``BboxOutsideWeights`` 用来指明是否它将影响训练loss值。 + +参数: + - **rpn_rois** (Variable) – 形为[N, 4]的二维LoDTensor。 N 为 ``GenerateProposals`` 的输出结果, 其中各元素为 :math:`[x_{min}, y_{min}, x_{max}, y_{max}]` 格式的边界框 + - **gt_classes** (Variable) – 形为[M, 1]的二维LoDTensor。 M 为正确标记数据数目, 其中各元素为正确标记数据的类别标签 + - **is_crowd** (Variable) – 形为[M, 1]的二维LoDTensor。M 为正确标记数据数目, 其中各元素为一个标志位，表明一个正确标记数据是不是crowd + - **gt_boxes** (Variable) – 形为[M, 4]的二维LoDTensor。M 为正确标记数据数目, 其中各元素为 :math:`[x_{min}, y_{min}, x_{max}, y_{max}]` 格式的边界框 + - **im_info** (Variable) – 形为[B, 3]的二维LoDTensor。B 为输入图片的数目, 各元素由 im_height, im_width, im_scale 组成. + - **batch_size_per_im** (int) – 每张图片的Rois batch数目 + - **fg_fraction** (float) – Foreground前景在 ``batch_size_per_im`` 中所占比例 + - **fg_thresh** (float) – 前景重叠阀值，用于选择foreground前景样本 + - **bg_thresh_hi** (float) – 背景重叠阀值的上界，用于筛选背景样本 + - **bg_thresh_lo** (float) – 背景重叠阀值的下界，用于筛选背景样本O + - **bbox_reg_weights** (list|tuple) – Box 回归权重 + - **class_nums** (int) – 种类数目 + - **use_random** (bool) – 是否使用随机采样来选择foreground（前景）和background（背景） boxes（框） + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_generate_proposals: + +generate_proposals +------------------------------- + +.. py:function:: paddle.fluid.layers.generate_proposals(scores, bbox_deltas, im_info, anchors, variances, pre_nms_top_n=6000, post_nms_top_n=1000, nms_thresh=0.5, min_size=0.1, eta=1.0, name=None) + +生成proposal的Faster-RCNN + +该操作根据每个框为foreground（前景）对象的概率，并且通过锚（anchors）来计算这些框，进而提出RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。 + +为了生成 ``proposals`` ，此操作执行以下步骤： + + 1、转置和调整bbox_deltas的分数和大小为（H * W * A，1）和（H * W * A，4）。 + + 2、计算方框位置作为 ``proposals`` 候选框。 + + 3、剪辑框图像。 + + 4、删除小面积的预测框。 + + 5、应用NMS以获得最终 ``proposals`` 作为输出。 + +参数： + - **scores** (Variable)- 是一个shape为[N，A，H，W]的4-D张量，表示每个框成为object的概率。N是批量大小，A是anchor数，H和W是feature map的高度和宽度。 + - **bbox_deltas** （Variable）- 是一个shape为[N，4 * A，H，W]的4-D张量，表示预测框位置和anchor位置之间的差异。 + - **im_info** （Variable）- 是一个shape为[N，3]的2-D张量，表示N个批次原始图像的信息。信息包含原始图像大小和 ``feature map`` 的大小之间高度，宽度和比例。 + - **anchors** （Variable）- 是一个shape为[H，W，A，4]的4-D Tensor。H和W是 ``feature map`` 的高度和宽度， + - **num_anchors** - 是每个位置的框的数量。每个anchor都是以非标准化格式（xmin，ymin，xmax，ymax）定义的。 + - **variances** （Variable）- anchor的方差，shape为[H，W，num_priors，4]。每个方差都是（xcenter，ycenter，w，h）这样的格式。 + - **pre_nms_top_n** （float）- 每个图在NMS之前要保留的总框数。默认为6000。 + - **post_nms_top_n** （float）- 每个图在NMS后要保留的总框数。默认为1000。 + - **nms_thresh** （float）- NMS中的阈值，默认为0.5。 + - **min_size** （float）- 删除高度或宽度小于min_size的预测框。默认为0.1。 + - **eta** （float）- 在自适应NMS中应用，如果自适应阈值> 0.5，则在每次迭代中使用adaptive_threshold = adaptive_treshold * eta。 + + + + + + + + + + + +.. _cn_api_fluid_layers_iou_similarity: + +iou_similarity +------------------------------- + +.. py:function:: paddle.fluid.layers.iou_similarity(x, y, name=None) + +**IOU Similarity Operator** + +计算两个框列表的intersection-over-union(IOU)。框列表‘X’应为LoDTensor，‘Y’是普通张量，X成批输入的所有实例共享‘Y’中的框。给定框A和框B，IOU的运算如下： + +.. math:: + IOU(A, B) = \frac{area(A\cap B)}{area(A)+area(B)-area(A\cap B)} + +参数： + - **x** (Variable,默认LoDTensor,float类型) - 框列表X是二维LoDTensor，shape为[N,4],存有N个框，每个框代表[xmin,ymin,xmax,ymax],X的shape为[N,4]。如果输入是图像特征图,[xmin,ymin]市框的左上角坐标，接近坐标轴的原点。[xmax,ymax]是框的右下角坐标。张量可以包含代表一批输入的LoD信息。该批的一个实例能容纳不同的项数 + - **y** (Variable,张量，默认float类型的张量) - 框列表Y存有M个框，每个框代表[xmin,ymin,xmax,ymax],X的shape为[N,4]。如果输入是图像特征图,[xmin,ymin]市框的左上角坐标，接近坐标轴的原点。[xmax,ymax]是框的右下角坐标。张量可以包含代表一批输入的LoD信息。 + +返回：iou_similarity操作符的输出，shape为[N,M]的张量，代表一对iou分数 + +返回类型：out(Variable) + + + + + + + + + +.. _cn_api_fluid_layers_multi_box_head: + +multi_box_head +------------------------------- + +.. py:function:: paddle.fluid.layers.multi_box_head(inputs, image, base_size, num_functiones, aspect_ratios, min_ratio=None, max_ratio=None, min_sizes=None, max_sizes=None, steps=None, step_w=None, step_h=None, offset=0.5, variance=[0.1, 0.1, 0.2, 0.2], flip=True, clip=False, kernel_size=1, pad=0, stride=1, name=None, min_max_aspect_ratios_order=False) + +生成SSD（Single Shot MultiBox Detector）算法的候选框。有关此算法的详细信息，请参阅SSD论文 `SSD：Single Shot MultiBox Detector `_ 的2.2节。 + +参数： + - **inputs** （list | tuple）- 输入变量列表，所有变量的格式为NCHW。 + - **image** （Variable）- PriorBoxOp的输入图像数据，布局为NCHW。 + - **base_size** （int）- base_size用于根据 ``min_ratio`` 和 ``max_ratio`` 来获取 ``min_size`` 和 ``max_size`` 。 + - **num_classes** （int）- 类的数量。 + - **aspect_ratios** （list | tuple）- 生成候选框的宽高比。 ``input`` 和 ``aspect_ratios`` 的长度必须相等。 + - **min_ratio** （int）- 生成候选框的最小比率。 + - **max_ratio** （int）- 生成候选框的最大比率。 + - **min_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``min_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 + - **max_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``max_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 + - **steps** （list | tuple）- 如果step_w和step_h相同，则step_w和step_h可以被steps替换。 + - **step_w** （list | tuple）- 候选框跨越宽度。如果step_w [i] == 0.0，将自动计算输跨越入[i]宽度。默认值：无。 + - **step_h** （list | tuple）- 候选框跨越高度，如果step_h [i] == 0.0，将自动计算跨越输入[i]高度。默认值：无。 + - **offset** （float）- 候选框中心偏移。默认值：0.5 + - **variance** （list | tuple）- 在候选框编码的方差。默认值：[0.1,0.1,0.2,0.2]。 + - **flip** （bool）- 是否翻转宽高比。默认值：false。 + - **clip** （bool）- 是否剪切超出边界的框。默认值：False。 + - **kernel_size** （int）- conv2d的内核大小。默认值：1。 + - **pad** （int | list | tuple）- conv2d的填充。默认值：0。 + - **stride** （int | list | tuple）- conv2d的步长。默认值：1， + - **name** （str）- 候选框的名称。默认值：无。 + - **min_max_aspect_ratios_order** （bool）- 如果设置为True，则输出候选框的顺序为[min，max，aspect_ratios]，这与Caffe一致。请注意，此顺序会影响卷积层后面的权重顺序，但不会影响最终检测结果。默认值：False。 + +返回：一个带有四个变量的元组，（mbox_loc，mbox_conf，boxes, variances）: + + - **mbox_loc** ：预测框的输入位置。布局为[N，H * W * Priors，4]。其中 ``Priors`` 是每个输位置的预测框数。 + + - **mbox_conf** ：预测框对输入的置信度。布局为[N，H * W * Priors，C]。其中 ``Priors`` 是每个输入位置的预测框数，C是类的数量。 + + - **boxes** ： ``PriorBox`` 的输出候选框。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总盒数。 + + - **variances** ： ``PriorBox`` 的方差。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总窗口数。 + +返回类型：元组（tuple） + +**代码示例** + +.. code-block:: python + + mbox_locs, mbox_confs, box, var = fluid.layers.multi_box_head( + inputs=[conv1, conv2, conv3, conv4, conv5, conv5], + image=images, + num_classes=21, + min_ratio=20, + max_ratio=90, + aspect_ratios=[[2.], [2., 3.], [2., 3.], [2., 3.], [2.], [2.]], + base_size=300, + offset=0.5, + flip=True, + clip=True) + + + + + + + + + + +.. _cn_api_fluid_layers_polygon_box_transform: + +polygon_box_transform +------------------------------- + +.. py:function:: paddle.fluid.layers.polygon_box_transform(input, name=None) + +PolygonBoxTransform 算子。 + +该算子用于将偏移坐标转变为真正的坐标。 + +输入是检测网络的最终几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数字 :math:`(x_i, y_i)` ，所以何输出包含 2*n 个通道。 + +参数： + - **input** （Variable） - shape 为[batch_size，geometry_channels，height，width]的张量 + +返回：与输入 shpae 相同 + +返回类型：output（Variable） + + + + + + + + + + + +.. _cn_api_fluid_layers_prior_box: + +prior_box +------------------------------- +.. py:function:: paddle.fluid.layers.prior_box(input,image,min_sizes=None,aspect_ratios=[1.0],variance=[0.1,0.1,0.2,0.2],flip=False,clip=False,steps=[0.0,0.0],offset=0.5,name=None,min_max_aspect_ratios_order=False) + +**Prior Box Operator** + +为SSD(Single Shot MultiBox Detector)算法生成先验框。输入的每个位产生N个先验框，N由min_sizes,max_sizes和aspect_ratios的数目决定，先验框的尺寸在(min_size,max_size)之间，该尺寸根据aspect_ratios在序列中生成。 + +参数： + - **input** (Variable)-输入变量，格式为NCHW + - **image** (Variable)-PriorBoxOp的输入图像数据，布局为NCHW + - **min_sizes** (list|tuple|float值)-生成的先验框的最小尺寸 + - **max_sizes** (list|tuple|None)-生成的先验框的最大尺寸。默认：None + - **aspect_ratios** (list|tuple|float值)-生成的先验框的纵横比。默认：[1.] + - **variance** (list|tuple)-先验框中的变量，会被解码。默认：[0.1,0.1,0.2,0.2] + - **flip** (bool)-是否忽略纵横比。默认：False。 + - **clip** (bool)-是否修建溢界框。默认：False。 + - **step** (list|tuple)-先验框在width和height上的步长。如果step[0] == 0.0/step[1] == 0.0，则自动计算先验框在宽度和高度上的步长。默认：[0.,0.] + - **offset** (float)-先验框中心位移。默认：0.5 + - **name** (str)-先验框操作符名称。默认：None + - **min_max_aspect_ratios_order** (bool)-若设为True,先验框的输出以[min,max,aspect_ratios]的顺序，和Caffe保持一致。请注意，该顺序会影响后面卷基层的权重顺序，但不影响最后的检测结果。默认：False。 + +返回： + 含有两个变量的元组(boxes,variances) + boxes:PriorBox的输出先验框。布局是[H,W,num_priors,4]。H是输入的高度，W是输入的宽度，num_priors是输入每位的总框数 + variances:PriorBox的扩展变量。布局上[H,W,num_priors,4]。H是输入的高度，W是输入的宽度，num_priors是输入每位的总框数 + +返回类型：元组 + +**代码示例**： + +.. code-block:: python + + box, var = fluid.layers.prior_box( + input=conv1, + image=images, + min_sizes=[100.], + flip=True, + clip=True) + + + + + + + + + + + +.. _cn_api_fluid_layers_roi_perspective_transform: + +roi_perspective_transform +------------------------------- + +.. py:function:: paddle.fluid.layers.roi_perspective_transform(input, rois, transformed_height, transformed_width, spatial_scale=1.0) + +**ROI perspective transform操作符** + +参数： + - **input** (Variable) - ROI Perspective TransformOp的输入。输入张量的形式为NCHW。N是批尺寸，C是输入通道数，H是特征高度，W是特征宽度 + - **rois** (Variable) - 用来处理的ROIs，应该是shape的二维LoDTensor(num_rois,8)。给定[[x1,y1,x2,y2,x3,y3,x4,y4],...],(x1,y1)是左上角坐标，(x2,y2)是右上角坐标，(x3,y3)是右下角坐标，(x4,y4)是左下角坐标 + - **transformed_height** - 输出的宽度 + - **spatial_scale** (float) - 空间尺度因子，用于缩放ROI坐标，默认：1.0。 + +返回： + ``ROIPerspectiveTransformOp`` 的输出，它是一个4维张量，形为 (num_rois,channels,transformed_h,transformed_w) + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + out = fluid.layers.roi_perspective_transform(input, rois, 7, 7, 1.0) + + + + + + + + + + + + + + + + + +.. _cn_api_fluid_layers_rpn_target_assign: + +rpn_target_assign +------------------------------- + +.. py:function:: paddle.fluid.layers.rpn_target_assign(bbox_pred, cls_logits, anchor_box, anchor_var, gt_boxes, is_crowd, im_info, rpn_batch_size_per_im=256, rpn_straddle_thresh=0.0, rpn_fg_fraction=0.5, rpn_positive_overlap=0.7, rpn_negative_overlap=0.3, use_random=True) + +在Faster-RCNN检测中为区域检测网络（RPN）分配目标层。 + +对于给定anchors和真实框之间的IoU重叠，该层可以为每个anchors做分类和回归，这些target labels用于训练RPN。classification targets是二进制的类标签（是或不是对象）。根据Faster-RCNN的论文，positive labels有两种anchors： + +(i) anchor/anchors与真实框具有最高IoU重叠； + +(ii) 具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。 + +请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。 + +参数： + - **bbox_pred** （Variable）- 是一个shape为[N，M，4]的3-D Tensor，表示M个边界框的预测位置。N是批量大小，每个边界框有四个坐标值，即[xmin，ymin，xmax，ymax]。 + - **cls_logits** （Variable）- 是一个shape为[N，M，1]的3-D Tensor，表示预测的置信度。N是批量大小，1是frontground和background的sigmoid，M是边界框的数量。 + - **anchor_box** （Variable）- 是一个shape为[M，4]的2-D Tensor，它拥有M个框，每个框可表示为[xmin，ymin，xmax，ymax]，[xmin，ymin]是anchor框的左上部坐标，如果输入是图像特征图，则它们接近坐标系的原点。 [xmax，ymax]是anchor框的右下部坐标。 + - **anchor_var** （Variable）- 是一个shape为[M，4]的2-D Tensor，它拥有anchor的expand方差。 + - **gt_boxes** （Variable）- 真实边界框是一个shape为[Ng，4]的2D LoDTensor，Ng是小批量输入的真实框（bbox）总数。 + - **is_crowd** （Variable）- 1-D LoDTensor，表示（groud-truth）是密集的。 + - **im_info** （Variable）- 是一个形为[N，3]的2-D LoDTensor。N是batch大小，第二维上的3维分别代表高度，宽度和规模(scale) + - **rpn_batch_size_per_im** （int）- 每个图像中RPN示例总数。 + - **rpn_straddle_thresh** （float）- 通过straddle_thresh像素删除出现在图像外部的RPN anchor。 + - **rpn_fg_fraction** （float）- 为foreground（即class> 0）RoI小批量而标记的目标分数，第0类是background。 + - **rpn_positive_overlap** （float）- 对于一个正例的（anchor, gt box）对，是允许anchors和所有真实框之间最小重叠的。 + - **rpn_negative_overlap** （float）- 对于一个反例的（anchor, gt box）对，是允许anchors和所有真实框之间最大重叠的。 + +返回: + +返回元组 (predicted_scores, predicted_location, target_label, target_bbox, bbox_inside_weight) : + - **predicted_scores** 和 **predicted_location** 是RPN的预测结果。 **target_label** 和 **target_bbox** 分别是真实准确数据(ground-truth)。 + - **predicted_location** 是一个形为[F，4]的2D Tensor， **target_bbox** 的形与 **predicted_location** 相同，F是foreground anchors的数量。 + - **predicted_scores** 是一个shape为[F + B，1]的2D Tensor， **target_label** 的形与 **predict_scores** 的形相同，B是background anchors的数量，F和B取决于此算子的输入。 + - **Bbox_inside_weight** 标志着predicted_loction是否为fake_fg（假前景），其形为[F,4]。 + +返回类型： 元组(tuple) + + +**代码示例** + +.. code-block:: python + + bbox_pred = layers.data(name=’bbox_pred’, shape=[100, 4], + append_batch_size=False, dtype=’float32’) + cls_logits = layers.data(name=’cls_logits’, shape=[100, 1], + append_batch_size=False, dtype=’float32’) + anchor_box = layers.data(name=’anchor_box’, shape=[20, 4], + append_batch_size=False, dtype=’float32’) + gt_boxes = layers.data(name=’gt_boxes’, shape=[10, 4], + append_batch_size=False, dtype=’float32’) + loc_pred, score_pred, loc_target, score_target, bbox_inside_weight= + fluid.layers.rpn_target_assign(bbox_pred=bbox_pred, + cls_logits=cls_logits, anchor_box=anchor_box, gt_boxes=gt_boxes) + + + + + + + + + + + +.. _cn_api_fluid_layers_ssd_loss: + +ssd_loss +------------------------------- + +.. py:function:: paddle.fluid.layers.ssd_loss(location, confidence, gt_box, gt_label, prior_box, prior_box_var=None, background_label=0, overlap_threshold=0.5, neg_pos_ratio=3.0, neg_overlap=0.5, loc_loss_weight=1.0, conf_loss_weight=1.0, match_type='per_prediction', mining_type='max_negative', normalize=True, sample_size=None) + +用于SSD的对象检测算法的多窗口损失层 + +该层用于计算SSD的损失，给定位置偏移预测，置信度预测，候选框和真实框标签，以及实例挖掘的类型。通过执行以下步骤，返回的损失是本地化损失（或回归损失）和置信度损失（或分类损失）的加权和： + +1、通过二分匹配算法查找匹配的边界框。 + + 1.1、计算真实框与先验框之间的IOU相似度。 + + 1.2、通过二分匹配算法计算匹配的边界框。 + +2、计算难分样本的置信度 + + 2.1、根据匹配的索引获取目标标签。 + + 2.2、计算置信度损失。 + +3、应用实例挖掘来获取负示例索引并更新匹配的索引。 + +4、分配分类和回归目标 + + 4.1、根据前面的框编码bbox。 + + 4.2、分配回归目标。 + + 4.3、分配分类目标。 + +5、计算总体客观损失。 + + 5.1计算置信度损失。 + + 5.1计算本地化损失。 + + 5.3计算总体加权损失。 + +参数： + - **location** （Variable）- 位置预测是具有形状[N，Np，4]的3D张量，N是批量大小，Np是每个实例的预测总数。 4是坐标值的数量，布局是[xmin，ymin，xmax，ymax]。 + - **confidence** (Variable) - 置信度预测是具有形状[N，Np，C]，N和Np的3D张量，它们与位置相同，C是类号。 + - **gt_box** （Variable）- 真实框（bbox）是具有形状[Ng，4]的2D LoDTensor，Ng是小批量输入的真实框（bbox）的总数。 + - **gt_label** （Variable）- ground-truth标签是具有形状[Ng，1]的2D LoDTensor。 + - **prior_box** （Variable）- 候选框是具有形状[Np，4]的2D张量。 + - **prior_box_var** （Variable）- 候选框的方差是具有形状[Np，4]的2D张量。 + - **background_label** （int）- background标签的索引，默认为0。 + - **overlap_threshold** （float）- 当找到匹配的盒子，如果 ``match_type`` 为'per_prediction'，请使用 ``overlap_threshold`` 确定额外匹配的bbox。默认为0.5。 + - **neg_pos_ratio** （float）- 负框与正框的比率，仅在 ``mining_type`` 为'max_negative'时使用，3.0由defalut使用。 + - **neg_overlap** （float）- 不匹配预测的负重叠上限。仅当mining_type为'max_negative'时使用，默认为0.5。 + - **loc_loss_weight** （float）- 本地化丢失的权重，默认为1.0。 + - **conf_loss_weight** （float）- 置信度损失的权重，默认为1.0。 + - **match_type** （str）- 训练期间匹配方法的类型应为'bipartite'或'per_prediction'，'per_prediction'由defalut提供。 + - **mining_type** （str）- 硬示例挖掘类型应该是'hard_example'或'max_negative'，现在只支持max_negative。 + - **normalize** （bool）- 是否通过输出位置的总数将SSD丢失标准化，默认为True。 + - **sample_size** （int）- 负框的最大样本大小，仅在 ``mining_type`` 为'hard_example'时使用。 + +返回： 具有形状[N * Np，1]，N和Np的定位损失和置信度损失的加权和与它们在位置上的相同。 + +抛出异常： ``ValueError`` - 如果 ``mining_type`` 是'hard_example'，现在只支持 ``max_negative`` 的挖掘类型。 + +**代码示例** + +.. code-block:: python + + pb = fluid.layers.data( + name='prior_box', + shape=[10, 4], + append_batch_size=False, + dtype='float32') + pbv = fluid.layers.data( + name='prior_box_var', + shape=[10, 4], + append_batch_size=False, + dtype='float32') + loc = fluid.layers.data(name='target_box', shape=[10, 4], dtype='float32') + scores = fluid.layers.data(name='scores', shape=[10, 21], dtype='float32') + gt_box = fluid.layers.data( + name='gt_box', shape=[4], lod_level=1, dtype='float32') + gt_label = fluid.layers.data( + name='gt_label', shape=[1], lod_level=1, dtype='float32') + loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv) + + + + + + + + + + +.. _cn_api_fluid_layers_target_assign: + +target_assign +------------------------------- + +.. py:function:: paddle.fluid.layers.target_assign(input, matched_indices, negative_indices=None, mismatch_value=None, name=None) + +对于给定的目标边界框（bounding box）和标签（label），该操作符对每个预测赋予分类和逻辑回归目标函数以及预测权重。权重具体表示哪个预测无需贡献训练误差。 + +对于每个实例，根据 ``match_indices`` 和 ``negative_indices`` 赋予输入 ``out`` 和 ``out_weight``。将定输入中每个实例的行偏移称为lod，该操作符执行分类或回归目标函数，执行步骤如下： + +1.根据match_indices分配所有输入 + +.. code-block:: text + + If id = match_indices[i][j] > 0, + + out[i][j][0 : K] = X[lod[i] + id][j % P][0 : K] + out_weight[i][j] = 1. + + Otherwise, + + out[j][j][0 : K] = {mismatch_value, mismatch_value, ...} + out_weight[i][j] = 0. + +2.如果提供neg_indices，根据neg_indices分配out_weight： + +假设neg_indices中每个实例的行偏移称为neg_lod，该实例中第i个实例和neg_indices的每个id如下： + +.. code-block:: text + + out[i][id][0 : K] = {mismatch_value, mismatch_value, ...} + out_weight[i][id] = 1.0 + +参数： + - **inputs** (Variable) - 输入为三维LoDTensor，维度为[M,P,K] + - **matched_indices** (Variable) - 张量（Tensor），整型，输入匹配索引为二维张量（Tensor），类型为整型32位，维度为[N,P]，如果MatchIndices[i][j]为-1，在第i个实例中第j列项不匹配任何行项。 + - **negative_indices** (Variable) - 输入负例索引，可选输入，维度为[Neg,1]，类型为整型32，Neg为负例索引的总数 + - **mismatch_value** (float32) - 为未匹配的位置填充值 + +返回：返回一个元组（out,out_weight）。out是三维张量，维度为[N,P,K],N和P与neg_indices中的N和P一致，K和输入X中的K一致。如果match_indices[i][j]存在，out_weight是输出权重，维度为[N,P,1]。 + +返回类型：元组（tuple） + +**代码示例**： + +.. code-block:: python + + matched_indices, matched_dist = fluid.layers.bipartite_match(iou) + gt = layers.data( + name='gt', shape=[1, 1], dtype='int32', lod_level=1) + trg, trg_weight = layers.target_assign( + gt, matched_indices, mismatch_value=0) + + + + + + + + + + + +============ + metric_op +============ + + +.. _cn_api_fluid_layers_accuracy: + +accuracy +------------------------------- + +.. py:function:: paddle.fluid.layers.accuracy(input, label, k=1, correct=None, total=None) + +accuracy layer。 参考 https://en.wikipedia.org/wiki/Precision_and_recall + +使用输入和标签计算准确率。 每个类别中top k 中正确预测的个数。注意：准确率的 dtype 由输入决定。 输入和标签 dtype 可以不同。 + +参数： + - **input** (Variable)-该层的输入，即网络的预测。支持 Carry LoD。 + - **label** (Variable)-数据集的标签。 + - **k** (int) - 每个类别的 top k + - **correct** (Variable)-正确的预测个数。 + - **total** (Variable)-总共的样本数。 + +返回: 正确率 + +返回类型: 变量（Variable） + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name="data", shape=[-1, 32, 32], dtype="float32") + label = fluid.layers.data(name="data", shape=[-1,1], dtype="int32") + predict = fluid.layers.fc(input=data, size=10) + acc = fluid.layers.accuracy(input=predict, label=label, k=5) + + + + + + + + + + + + +.. _cn_api_fluid_layers_auc: + +auc +------------------------------- + +.. py:function:: paddle.fluid.layers.auc(input, label, curve='ROC', num_thresholds=4095, topk=1, slide_steps=1) + +**Area Under the Curve(AUC) Layer** + +该层根据前向输出和标签计算AUC，在二分类(binary classification)估计中广泛使用。 + +注：如果输入标注包含一种值，只有0或1两种情况，数据类型则强制转换成布尔值。相关定义可以在这里: https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 找到 + +有两种可能的曲线： + +1. ROC:受试者工作特征曲线 + +2. PR:准确率召回率曲线 + +参数： + - **input** (Variable) - 浮点二维变量，值的范围为[0,1]。每一行降序排列。输入应为topk的输出。该变量显示了每个标签的概率。 + - **label** (Variable) - 二维整型变量，表示训练数据的标注。批尺寸的高度和宽度始终为1. + - **curve** (str) - 曲线类型，可以为 ``ROC`` 或 ``PR``，默认 ``ROC``。 + - **num_thresholds** (int) - 将roc曲线离散化时使用的临界值数。默认200 + - **topk** (int) - 只有预测输出的topk数才被用于auc + - **slide_steps** - 计算批auc时，不仅用当前步也用先前步。slide_steps=1，表示用当前步；slide_steps = 3表示用当前步和前两步；slide_steps = 0，则用所有步 + +返回：代表当前AUC的scalar + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + # network为二分类模型, label为ground truth（正确标记） + prediction = network(image, is_infer=True) + auc_out=fluid.layers.auc(input=prediction, label=label) + + + + + + + + + + + diff --git a/doc/fluid/api_cn/metrics_cn.rst b/doc/fluid/api_cn/metrics_cn.rst index 64cdf50d68befc74509729785ec34aeb836b5ec9..21670356c2d492ae4892b8bda75346dd802ceee7 100644 --- a/doc/fluid/api_cn/metrics_cn.rst +++ b/doc/fluid/api_cn/metrics_cn.rst @@ -196,7 +196,7 @@ CompositeMetric 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等。它不同于召回率，它是最大精度的平均值。 请从以下文章中获取更多信息： @@ -246,7 +246,7 @@ https://arxiv.org/abs/1512.02325 返回：当前 mini-batch 的 mAP 变量，和跨 mini-batch 的 mAP 累加和 -.. py:methord:: reset(executor, reset_program=None) +.. py:method:: reset(executor, reset_program=None) 在指定 batch 的每一 pass/user 开始时重置度量状态。 @@ -380,7 +380,7 @@ Recall .. py:class:: paddle.fluid.metrics.Recall(name=None) -召回率（也称为敏感度）是度量有多个正例被分为正例 +召回率（也称为敏感度）是指得到的相关实例数占相关实例总数的比重 https://en.wikipedia.org/wiki/Precision_and_recall diff --git a/doc/fluid/api_cn/nets_cn.rst b/doc/fluid/api_cn/nets_cn.rst index 8f95a142ae90466c4e5fc2ee9f02767d9d9c6923..96584a54a6e8f6838299239cc4ff7bed3029e2af 100644 --- a/doc/fluid/api_cn/nets_cn.rst +++ b/doc/fluid/api_cn/nets_cn.rst @@ -159,7 +159,7 @@ attention运算机制可以被视为将查询和一组键值对映射到输出 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由序列卷积和池化组成 diff --git a/doc/fluid/api_cn/optimizer_cn.rst b/doc/fluid/api_cn/optimizer_cn.rst index 29b6ad5489a5d7fe8be643cb253d1966c3ecb71e..a67e42d1268e3ebd53d3b6361d2b2d70326a8f5a 100644 --- a/doc/fluid/api_cn/optimizer_cn.rst +++ b/doc/fluid/api_cn/optimizer_cn.rst @@ -262,7 +262,7 @@ FtrlOptimizer FTRL (Follow The Regularized Leader) Optimizer. -TFRTL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf `_) +FTRL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf `_) .. math:: @@ -439,9 +439,10 @@ MomentumOptimizer .. math:: & velocity = mu * velocity + gradient\\ - & if (use\_nesterov):\ - \&\quad param = param - (gradient + mu * velocity) * learning\_rate\\ + & if (use\_nesterov):\\ + &\quad param = param - (gradient + mu * velocity) * learning\_rate\\ & else:\\&\quad param = param - learning\_rate * velocity + 参数： - **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量 - **momentum** (float) - 动量因子 @@ -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) -均方根平均传播（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:: r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ @@ -493,11 +494,11 @@ RMSPropOptimizer 其中， :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。 - **epsilon** （float） - 等式中的epsilon是平滑项，避免被零除，默认设置为1e-6。 - **momentum** （float） - 方程中的β是动量项，默认设置为0.0。 - - **centered** （bool） - 如果为True，则通过梯度估计方差对梯度进行归一化；如果false，则由未centered的第二个moment归一化。将此设置为True有助于培训，但在计算和内存方面稍微昂贵一些。默认为False。 + - **centered** （bool） - 如果为True，则通过梯度的估计方差,对梯度进行归一化；如果False，则由未centered的第二个moment归一化。将此设置为True有助于模型训练，但会消耗额外计算和内存资源。默认为False。 - **regularization** - 正则器项，如 ``fluid.regularizer.L2DecayRegularizer`` 。 - **name** - 可选的名称前缀。 diff --git a/doc/fluid/api_cn/param_attr_cn.rst b/doc/fluid/api_cn/param_attr_cn.rst deleted file mode 100644 index 1e32d1f8a9eadbd29baad35be9219abd3203bfe7..0000000000000000000000000000000000000000 --- a/doc/fluid/api_cn/param_attr_cn.rst +++ /dev/null @@ -1,90 +0,0 @@ -################# - 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 `_ - -参数: - - **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')) - - - - - - - - - - - - - diff --git a/doc/fluid/api_cn/profiler_cn.rst b/doc/fluid/api_cn/profiler_cn.rst index 52442b2da2662df462ccb6a3b0484ff02e72a40c..bc617ba59a7b9379c8fb2ea69a59c8b0c6b76782 100644 --- a/doc/fluid/api_cn/profiler_cn.rst +++ b/doc/fluid/api_cn/profiler_cn.rst @@ -171,10 +171,10 @@ start_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`` 插入代码 -不能使用 fluid.profiler.profiler`` +不能使用 ``fluid.profiler.profiler`` 参数: - **sorted_key** (string) – 如果为None，prfile的结果将按照事件的第一次结束时间顺序打印。否则，结果将按标志排序。标志取值为"call"、"total"、"max"、"min" "ave"之一，根据调用着的数量进行排序。total表示按总执行时间排序，max 表示按最大执行时间排序。min 表示按最小执行时间排序。ave表示按平均执行时间排序。 diff --git a/doc/fluid/api_cn/transpiler_cn.rst b/doc/fluid/api_cn/transpiler_cn.rst index 1e48c4f6036807ac90e9892aa118ad92a00acf21..6eb8b9fc19410a198072162be759e80f608e83e5 100644 --- a/doc/fluid/api_cn/transpiler_cn.rst +++ b/doc/fluid/api_cn/transpiler_cn.rst @@ -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函数。 diff --git a/doc/fluid/beginners_guide/install/FAQ_en.md b/doc/fluid/beginners_guide/install/FAQ_en.md new file mode 100644 index 0000000000000000000000000000000000000000..b3218c85ee647e3daf7b08c80c23ed9b10ed3c02 --- /dev/null +++ b/doc/fluid/beginners_guide/install/FAQ_en.md @@ -0,0 +1,130 @@ +*** + + +# **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) diff --git a/doc/fluid/beginners_guide/install/Tables.md b/doc/fluid/beginners_guide/install/Tables.md index 86ff0bd6ee36e75b62cb657fd2ff02439f819a9f..6ef975c29dfb3ff2bcf19599fc5cd056668366ac 100644 --- a/doc/fluid/beginners_guide/install/Tables.md +++ b/doc/fluid/beginners_guide/install/Tables.md @@ -363,7 +363,8 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。

-## **多版本whl包列表-v1.2** + +## **多版本whl包列表-Release**

diff --git a/doc/fluid/beginners_guide/install/Tables_en.md b/doc/fluid/beginners_guide/install/Tables_en.md new file mode 100644 index 0000000000000000000000000000000000000000..9041a2deb66a56e03fdf15a3eb0350e87b0cd50b --- /dev/null +++ b/doc/fluid/beginners_guide/install/Tables_en.md @@ -0,0 +1,665 @@ +*** +# APPENDIX + + +## Compile Dependency Table + +

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Dependency package name Version Description Installation command
CMake 3.4
GCC 4.8 / 5.4 recommends using devtools2 for CentOS
Python 2.7.x. depends on libpython2.7.so apt install python-dev or yum install python-devel
SWIG at least 2.0 apt install swig or yum install swig
wget any apt install wget or yum install wget
openblas any
pip at least 9.0.1 apt install python-pip or yum install Python-pip
numpy >=1.12.0 pip install numpy==1.14.0
protobuf 3.1.0 pip install protobuf==3.1.0
wheel any pip install wheel
patchELF any apt install patchelf or read github patchELF official documentation
go >=1.8 optional
+

+ + +*** + +

+## **Compile Option Table** + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Option Description Default
WITH_GPU Whether to support GPU ON
WITH_C_API Whether to compile CAPI OFF
WITH_DOUBLE Whether to use double precision floating point numeber OFF
WITH_DSO whether to load CUDA dynamic libraries dynamically at runtime, instead of statically loading CUDA dynamic libraries. ON
WITH_AVX whether to compile PaddlePaddle binaries file containing the AVX instruction set ON
WITH_PYTHON Whether the PYTHON interpreter is embedded ON
WITH_STYLE_CHECK Whether to perform code style checking at compile time ON
WITH_TESTING Whether to turn on unit test OFF
WITH_DOC Whether to compile Chinese and English documents OFF
WITH_SWIG_PY Whether to compile PYTHON's SWIG interface, which can be used for predicting and customizing training Auto
WITH_GOLANG Whether to compile the fault-tolerant parameter server of the go language OFF
WITH_MKL Whether to use the MKL math library, if not,using OpenBLAS ON
WITH_SYSTEM_BLAS Whether to use the system's BLAS OFF
WITH_DISTRIBUTE Whether to Compile with distributed version OFF
WITH_MKL Whether to uses the MKL math library, if not, using OpenBLAS ON
WITH_RDMA Whether to compile the relevant parts that supports RDMA OFF
WITH_BRPC_RDMA Whether to use BRPC RDMA as RPC protocol OFF
ON_INFER Whether to turn on prediction optimization OFF
DWITH_ANAKIN Whether to Compile ANAKIN OFF
+

+ + +**BLAS** + +PaddlePaddle supports two BLAS libraries, [MKL](https://software.intel.com/en-us/mkl) and [OpenBlAS](http://www.openblas.net/). MKL is used by default. If you use MKL and the machine contains the AVX2 instruction set, you will also download the MKL-DNN math library, for details please refer to [here](https://github.com/PaddlePaddle/Paddle/tree/develop/doc/design/mkldnn#cmake). + +If you close MKL, OpenBLAS will be used as the BLAS library. + +**CUDA/cuDNN** + +PaddlePaddle automatically finds the CUDA and cuDNN libraries installed in the system for compilation and execution at compile time/runtime. Use the parameter `-DCUDA_ARCH_NAME=Auto` to specify to enable automatic detection of the SM architecture and speed up compilation. + +PaddlePaddle can be compiled and run using any version after cuDNN v5.1, but try to keep the same version of cuDNN in the compiling and running processes. We recommend using the latest version of cuDNN. + +**Configure Compile Options** + +PaddePaddle implements references to various BLAS/CUDA/cuDNN libraries by specifying paths at compile time. When cmake compiles, it first searches the system paths ( `/usr/liby` and `/usr/local/lib` ) for these libraries, and also reads the relevant path variables for searching. Can be set by using the `-D` command, for example: + +> `Cmake .. -DWITH_GPU=ON -DWITH_TESTING=OFF -DCUDNN_ROOT=/opt/cudnnv5` + +**Note**: The settings introduced here for these compilation options are only valid for the first cmake. If you want to reset it later, it is recommended to clean up the entire build directory ( rm -rf ) and then specify it. + + +*** +

+## **Installation Package List** + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Version Number Release Discription
paddlepaddle==[version code] such as paddlepaddle==1.0.1 (download version 1.0.1 which only supports CPU PaddlePaddle) Only support the corresponding version of the CPU PaddlePaddle, please refer to Pypi for the specific version.
paddlepaddle-gpu==1.0.1 Using version 1.0.1 compiled with CUDA 9.0 and cuDNN 7
paddlepaddle-gpu==1.0.1.post87 Using version 1.0.1 compiled with CUDA 8.0 and cuDNN 7
paddlepaddle-gpu==1.0.1.post85 Using version 1.0.1 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==1.0.0 Using version 1.0.0 compiled with CUDA 9.0 and cuDNN 7
paddlepaddle-gpu==1.0.0.post87 Using version 1.0.0 compiled with CUDA 8.0 and cuDNN 7
paddlepaddle-gpu==1.0.0.post85 Using version 1.0.0 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==0.15.0 Using version 0.15.0 compiled with CUDA 9.0 and cuDNN 7
paddlepaddle-gpu==0.15.0.post87 Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 7
paddlepaddle-gpu==0.15.0.post85 Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==0.14.0 Using version 0.15.0 compiled with CUDA 9.0 and cuDNN 7
paddlepaddle-gpu==0.14.0.post87 Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 7
paddlepaddle-gpu==0.14.0.post85 Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==0.13.0 Using version 0.13.0 compiled with CUDA 9.0 and cuDNN 7
paddlepaddle-gpu==0.12.0 Using version 0.12.0 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==0.11.0.post87 Using version 0.11.0 compiled with CUDA 8.0 and cuDNN 7
paddlepaddle-gpu==0.11.0.post85 Using version 0.11.0 compiled with CUDA 8.0 and cuDNN 5
paddlepaddle-gpu==0.11.0 Using version 0.11.0 compiled with CUDA 7.5 and cuDNN 5
+

+ + + +You can find various distributions of PaddlePaddle-gpu in [the Release History](https://pypi.org/project/paddlepaddle-gpu/#history). + +*** +

+## Installation Mirrors and Introduction + +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Version Number Release Description
hub.baidubce.com/paddlepaddle/paddle:latest The latest pre-installed image of the PaddlePaddle CPU version
hub.baidubce.com/paddlepaddle/paddle:latest-dev The latest PaddlePaddle development environment
hub.baidubce.com/paddlepaddle/paddle:[Version] Replace version with a specific version, preinstalled PaddlePaddle image in historical version
hub.baidubce.com/paddlepaddle/paddle:latest-gpu The latest pre-installed image of the PaddlePaddle GPU version
+

+ + + +You can find the docker image for each release of PaddlePaddle in the [DockerHub](https://hub.docker.com/r/paddlepaddle/paddle/tags/). + +*** + +

+ +## **Multi-version whl package list - Release** + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Release Instruction cp27-cp27mu cp27-cp27m cp35-cp35m cp36-cp36m cp37-cp37m
cpu-noavx-mkl + paddlepaddle-1.2.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle-1.2.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle-1.2.0-cp37-cp37m-linux_x86_64.whl
cpu_avx_mkl + paddlepaddle-1.2.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle-1.2.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle-1.2.0-cp37-cp37m-linux_x86_64.whl
cpu_avx_openblas + paddlepaddle-1.2.0-cp27-cp27mu-linux_x86_64.whl paddlepaddle-1.2.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle-1.2.0-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn5_avx_mkl paddlepaddle_gpu-1.2.0-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn7_noavx_mkl paddlepaddle_gpu-1.2.0-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn7_avx_mkl paddlepaddle_gpu-1.2.0.post87-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-1.2.0.post87-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-1.2.0.post87-cp35-cp35m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0.post87-cp36-cp36m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0.post87-cp37-cp37m-linux_x86_64.whl
cuda9.0_cudnn7_avx_mkl paddlepaddle_gpu-1.2.0-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-1.2.0-cp35-cp35m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp36-cp36m-linux_x86_64.whl + paddlepaddle_gpu-1.2.0-cp37-cp37m-linux_x86_64.whl
+

+ + +

+ + + + +## **Multi-version whl package list - dev** + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Release Instruction cp27-cp27mu cp27-cp27m cp35-cp35m cp36-cp36m cp37-cp37m
cpu-noavx-mkl + paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl + paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl + paddlepaddle-latest-cp35-cp35m-linux_x86_64.whl + paddlepaddle-latest-cp36-cp36m-linux_x86_64.whl + paddlepaddle-latest-cp37-cp37m-linux_x86_64.whl
cpu_avx_mkl + paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl + paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl + paddlepaddle-latest-cp35-cp35m-linux_x86_64.whl + paddlepaddle-latest-cp36-cp36m-linux_x86_64.whl + paddlepaddle-latest-cp37-cp37m-linux_x86_64.whl
cpu_avx_openblas + paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl + paddlepaddle-latest-cp35-cp35m-linux_x86_64.whl + paddlepaddle-latest-cp36-cp36m-linux_x86_64.whl + paddlepaddle-latest-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn5_avx_mkl paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-latest-cp35-cp35m-linux_x86_64.whl paddlepaddle_gpu-latest-cp36-cp36m-linux_x86_64.whl paddlepaddle_gpu-latest-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn7_noavx_mkl paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-latest-cp35-cp35m-linux_x86_64.whl + paddlepaddle_gpu-latest-cp36-cp36m-linux_x86_64.whl + paddlepaddle_gpu-latest-cp37-cp37m-linux_x86_64.whl
cuda8.0_cudnn7_avx_mkl paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-latest-cp35-cp35m-linux_x86_64.whl paddlepaddle_gpu-latest-cp36-cp36m-linux_x86_64.whl paddlepaddle_gpu-latest-cp37-cp37m-linux_x86_64.whl
cuda9.0_cudnn7_avx_mkl paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl paddlepaddle_gpu-latest-cp35-cp35m-linux_x86_64.whl paddlepaddle_gpu-latest-cp36-cp36m-linux_x86_64.whl paddlepaddle_gpu-latest-cp37-cp37m-linux_x86_64.whl
+

+ + +

+ +## Execute the PaddlePaddle training program in Docker + +*** + +Suppose you have written a PaddlePaddle program in the current directory (such as /home/work): `train.py` ( refer to [PaddlePaddleBook](http://www.paddlepaddle.org/docs/develop/book/01.fit_a_line/index.cn.html) to write), you can start the training with the following command: + + + cd /home/work + docker run -it -v $PWD:/work hub.baidubce.com/paddlepaddle/paddle /work/train.py + + +In the above commands, the `-it` parameter indicates that the container has been run interactively; `-v $PWD:/work` specifies that the current path (the absolute path where the PWD variable in Linux will expand to the current path) is mounted to the `:/work` directory inside the container: `Hub.baidubce.com/paddlepaddle/paddle` specifies the container to be used; finally `/work/train.py` is the command executed inside the container, ie. the training program. + +Of course, you can also enter into the Docker container and execute or debug your code interactively: + + + docker run -it -v $PWD:/work hub.baidubce.com/paddlepaddle/paddle /bin/bash + cd /work + python train.py + + +**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` **(which installs vim for you) in the container.** + +

+ +## Start PaddlePaddle Book tutorial with Docker + +*** + +Use Docker to quickly launch a local Jupyter Notebook containing the PaddlePaddle official Book tutorial, which can be viewed on the web. PaddlePaddle Book is an interactive Jupyter Notebook for users and developers. If you want to learn more about deep learning, PaddlePaddle Book is definitely your best choice. You can read tutorials or create and share interactive documents with code, formulas, charts, and text. + +We provide a Docker image that can run the PaddlePaddle Book directly, running directly: + +`docker run -p 8888:8888 hub.baidubce.com/paddlepaddle/book` + +Domestic users can use the following image source to speed up access: + +`docker run -p 8888:8888 hub.baidubce.com/paddlepaddle/book` + +Then enter the following URL in your browser: + +`http://localhost:8888/` + +It's that simple and bon voyage! For further questions, please refer to the [FAQ](#FAQ). + + +

+## Perform GPU training using Docker + +*** + +In order to ensure that the GPU driver works properly in the image, we recommend using [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) to run the image. Don't forget to install the latest GPU drivers on your physical machine in advance. + +`Nvidia-docker run -it -v $PWD:/work hub.baidubce.com/paddlepaddle/paddle:latest-gpu /bin/bash` + +**Note: If you don't have nvidia-docker installed, you can try the following to mount the CUDA library and Linux devices into the Docker container:** + + + export CUDA_SO="$(\ls /usr/lib64/libcuda* | xargs -I{} echo '-v {}:{}') \ + $(\ls /usr/lib64/libnvidia* | xargs -I{} echo '-v {}:{}')" + export DEVICES=$(\ls /dev/nvidia* | xargs -I{} echo '--device {}:{}') + docker run ${CUDA_SO} \ + ${DEVICES} -it hub.baidubce.com/paddlepaddle/paddle:latest-gpu + + + +**About AVX:** + +AVX is a set of CPU instructions that speeds up the calculation of PaddlePaddle. The latest PaddlePaddle Docker image is enabled by default for AVX compilation, so if your computer does not support AVX, you need to [compile](/build_from_source_cn.html) PaddlePaddle to no-avx version separately. + +The following instructions can check if the Linux computer supports AVX: + +`if cat /proc/cpuinfo | grep -i avx; then echo Yes; else echo No; fi` + +If the output is No, you need to choose a mirror that uses no-AVX. + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/fluid/beginners_guide/install/compile/compile_CentOS.md b/doc/fluid/beginners_guide/install/compile/compile_CentOS.md index b7da31bbe54f0628500456c7c129b7edf9a2eaeb..6226e54f92d6f739e6afc52c24b58d82cf2b10cd 100644 --- a/doc/fluid/beginners_guide/install/compile/compile_CentOS.md +++ b/doc/fluid/beginners_guide/install/compile/compile_CentOS.md @@ -80,7 +80,7 @@ `cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` - > 我们目前不支持CentOS下GPU版本PaddlePaddle的编译 + > 我们目前不支持CentOS下使用Docker编译GPU版本的PaddlePaddle 9. 执行编译： @@ -171,9 +171,9 @@ - `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的目录下： diff --git a/doc/fluid/beginners_guide/install/compile/compile_CentOS_en.md b/doc/fluid/beginners_guide/install/compile/compile_CentOS_en.md new file mode 100644 index 0000000000000000000000000000000000000000..9cecda894b2569535053d4bd9124f6769bd9934e --- /dev/null +++ b/doc/fluid/beginners_guide/install/compile/compile_CentOS_en.md @@ -0,0 +1,212 @@ +*** +# **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. + + + +

+### *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. + +

+### ***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. + +

+### ***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` diff --git a/doc/fluid/beginners_guide/install/compile/compile_MacOS.md b/doc/fluid/beginners_guide/install/compile/compile_MacOS.md index 4d3d422d465f6e9f7de942864bac26107ce87ebb..06268c43beba803218e53eeecac3c5e0a12158d5 100644 --- a/doc/fluid/beginners_guide/install/compile/compile_MacOS.md +++ b/doc/fluid/beginners_guide/install/compile/compile_MacOS.md @@ -177,9 +177,9 @@ - `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的目录下： diff --git a/doc/fluid/beginners_guide/install/compile/compile_MacOS_en.md b/doc/fluid/beginners_guide/install/compile/compile_MacOS_en.md new file mode 100644 index 0000000000000000000000000000000000000000..51ea6d3cae3330a8dd3536e9108189c9c5cdcd0a --- /dev/null +++ b/doc/fluid/beginners_guide/install/compile/compile_MacOS_en.md @@ -0,0 +1,207 @@ +*** +# **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. + +

+### ***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. + + +

+### ***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. + +

+### ***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. + +

+### ***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` diff --git a/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md b/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md index 8cc80b40c1843b849163df6b6176cff537622db7..a69caba9ad2fc076a408822ae8eb9d4c67344227 100644 --- a/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md +++ b/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md @@ -54,9 +54,9 @@ 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路径下： diff --git a/doc/fluid/beginners_guide/install/compile/compile_Ubuntu_en.md b/doc/fluid/beginners_guide/install/compile/compile_Ubuntu_en.md new file mode 100644 index 0000000000000000000000000000000000000000..073e4973112ba3b22782ede4640318dddb2068d8 --- /dev/null +++ b/doc/fluid/beginners_guide/install/compile/compile_Ubuntu_en.md @@ -0,0 +1,213 @@ +*** +# **Compile under Ubuntu from Source Code** + +This instruction describes how to compile PaddlePaddle on *64-bit desktops or laptops* and Ubuntu systems. The Ubuntu systems we support must meet the following requirements: + +* Ubuntu 14.04/16.04/18.04 (this involves whether the related tools can be installed successfully) + +## Determine which version to compile + +* **CPU version of PaddlePaddle**, if your system does not have an NVIDIA® GPU, you must install this version. This version is easier than the GPU version. So even if you have a GPU on your computer, we recommend that you first install the CPU version of PaddlePaddle to check if your local environment is suitable. + +* **GPU version of PaddlePaddle**, in order to make the PaddlePaddle program run more quickly, we usually use the GPU to accelerate the PaddlePaddle program, but the GPU version of PaddlePaddle needs to have the NVIDIA® GPU that meets the following conditions (see NVIDIA for the specific installation process and configuration). Official documentation: [For CUDA](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/), For [cuDNN](https://docs.nvidia.com/deeplearning/sdk/cudnn-install/)) + + * *CUDA Toolkit 9.0 with cuDNN v7* + * *CUDA Toolkit 8.0 with cuDNN v7* + * *Hardware devices with GPU compute capability exceeding 1.0* + +## Choose a compilation method + +Under Ubuntu's system we offer 2 ways to compile: + +* Docker source compilation (this image already contains python2.7, python3.6, python3.7 environment) + +* Direct native source code compilation (does not support GPU version under ubuntu18.04) + +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. 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 running directly on the native CPU and operating system. The performance is the same as installing the compiler on the machine. + +We also provide methods that can be **compiled from local source code**, but since the situation on host machine is more complicated, we only provide support for 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/). + +> Please note that to install and use the PaddlePaddle version that supports GPU, you must first install nvidia-docker + +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 path's [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: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. + +4. After entering Docker, go to the paddle directory: `cd paddle` + +5. 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.0` + +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 the meaning of the specific compiling options, [compilation options table](../Tables.html/#Compile) is your resort. Please note that the parameter `-DPY_VERSION` is the python version used in your current environment. + + * For users who need to compile the **CPU version PaddlePaddle**: + + `cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` + + * For users who need to compile the **GPU version PaddlePaddle**: + + `cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` + +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/). + +> 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. + + +

+### ***Local compilation*** + +**Please strictly follow the following instructions step by step** + +1. Check that your computer and operating system meet the compilation standards we support: `uname -m && cat /etc/*release` + +2. Update the source of `apt`: `apt update`, and install openCV in advance. + +3. We support compiling and installing with virtualenv. First, create a virtual environment called `paddle-venv` with the following command: + + * a. Install Python-dev: (Please install python3.x-dev that matches the current environment python version) + + For Python2: apt install python-dev + For Python3: apt install python3.5-dev + + * b. Install pip: (Please ensure that pip version is 9.0.1 and above ): (Please note that the version corresponding to python3 is modified) + + For Python2: apt install python-pip + For Python3: apt-get udpate && apt-get install -y software-properties-common && add-apt-repository ppa:deadsnakes/ppa && apt install curl && curl https://bootstrap.pypa.io/get-pip. Py -o - | python3.5 && easy_install pip + + + * c. Install the virtual environment `virtualenv` and `virtualenvwrapper` and create a virtual environment called `paddle-venv` (please note the python version) : + + 1. `apt install virtualenv` or `pip install virtualenv` or `pip3 install virtualenv` + 2. `apt install virtualenvwrapper` or `pip install virtualenvwrapper` or `pip3 install virtualenvwrapper` + 3. Find `virtualenvwrapper.sh`: `find / -name virtualenvwrapper.sh` + 4. (Only for Python3) Set the interpreter path for the virtual environment: `export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3.5` + 5. See the installation method in `virtualenvwrapper.sh`: `cat virtualenvwrapper.sh` + 6. Install `virtualwrapper` according to the installation method in `virtualenvwrapper.sh` + 7. Create a virtual environment called `paddle-venv`: `mkvirtualenv paddle-venv` + +4. Enter the virtual environment: `workon paddle-venv` + +5. 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 `apt install` or `pip install` followed by the name and version: + + `apt install patchelf` + + > Users who can't use apt installation can refer to patchElF [github official documentation](https://gist.github.com/ruario/80fefd174b3395d34c14). + +6. Clone the PaddlePaddle source code 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, replacing the brackets and their contents with **the target branch name**: + + - `git checkout [name of target branch]` + +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 of PaddlePaddle**: (For Python3: Please configure the correct python version for the PY_VERSION parameter) + + For Python2: cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release + For Python3: cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release + + + * For users who need to compile **GPU version of PaddlePaddle**: (*only support ubuntu16.04/14.04*) + + 1. Please make sure that you have installed nccl2 correctly, or install nccl2 according to the following instructions (here is ubuntu 16.04, CUDA9, ncDNN7 nccl2 installation instructions), for more information on the installation information please refer to the [NVIDIA official website](https://developer.nvidia.com/nccl/nccl-download): + + i. `wget http: / /developer.download.nvidia.com/compute/machine-learning/repos/ubuntu1604/x86_64/nvidia-machine-learning-repo-ubuntu1604_1.0.0-1_amd64.deb ` + + ii. `dpkg -i nvidia-machine-learning-repo-ubuntu1604_1 .0.0-1_amd64.deb` + + iii. `sudo apt-get install -y libnccl2=2.2.13-1+cuda9.0 libnccl-dev=2.2.13-1+cuda9.0` + + 2. If you have already installed `nccl2` correctly, you can start cmake: *(For Python3: Please configure the correct python version for the PY_VERSION parameter)* + + For Python2: cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release + For Python3: cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -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 -j$(nproc)` + +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)` + +Congratulations, now you have completed the process of compiling PaddlePaddle natively. + +

+### ***Verify installation*** + +After the installation is complete, you can use `python` or `python3` to enter the Python interpreter and then use `import paddle.fluid` to verify that the installation was successful. + +

+### ***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` + +- ***GPU version of PaddlePaddle***: `pip uninstall paddlepaddle-gpu` or `pip3 uninstall paddlepaddle-gpu` diff --git a/doc/fluid/beginners_guide/install/compile/compile_Windows_en.md b/doc/fluid/beginners_guide/install/compile/compile_Windows_en.md new file mode 100644 index 0000000000000000000000000000000000000000..86c84ade026c34282443be4b20c3580302cf6a81 --- /dev/null +++ b/doc/fluid/beginners_guide/install/compile/compile_Windows_en.md @@ -0,0 +1,104 @@ +*** +# **Compile under Windows from Source Code** + +This instruction will show you how to compile PaddlePaddle on a *64-bit desktop or laptop* and Windows 10. The Windows systems we support must meet the following requirements: + +* Windows 10 Family Edition / Professional Edition / Enterprise Edition +* Visual Studio 2015 Update3 + +## Determine which version to compile + +* **Only PaddlePaddle for CPU is supported.** + +## Choose a compilation method + +We provide one compilation method under the Windows system: + +* Direct source code compilation + +Since the situation on host machine is more complicated, we only support specific systems. + +Please note: The current version does not support NCCL, distributed, AVX, warpctc and MKL related functions. + + +### ***Local compilation*** + +**Please strictly follow the following instructions step by step** + +1. Check that your computer and operating system meet our supported compilation standards + + * Windows 10 Family Edition / Professional Edition / Enterprise Edition + + * Visual Studio 2015 Update3 + +2. Install the necessary tools i.e. cmake, git and python : + + > Cmake requires version 3.0 and above, which can be downloaded from the official website and added to the environment variable. [Download here](https://cmake.org/download/). + + > Git can be downloaded on the official website and added to the environment variable. [Download here](https://gitforwindows.org/). + + > Python requires version 2.7 and above, and ensure that modules such as numpy, protobuf, wheel are installed. [Download here](https://www.python.org/download/releases/2.7/). + + + * To Install numpy package you can use command `pip install numpy` or command `pip3 install numpy` + + * To Install protobuf package you can use command `pip install protobuf` or command `pip3 install protobuf` + + * To Install Wheel package you can use command `pip install wheel` or `pip3 install wheel` + + +3. Clone the PaddlePaddle source in the Paddle folder in the current directory and go to the Paddle directory: + + - `git clone https://github.com/PaddlePaddle/Paddle.git` + - `cd Paddle` + +4. Switch to a more stable release branch for compilation (supports 1.2.x and above): + + - `git checkout release/x.x.x` + +5. Create a directory called build and enter it: + + - `mkdir build` + - `cd build` + +6. Execute cmake: + + > For details on the compilation options, see [the compilation options list](../Tables.html/#Compile). + + * For users who need to compile **the CPU version PaddlePaddle**: + + For Python2:`cmake .. -G "Visual Studio 14 2015 Win64" -DPYTHON_INCLUDE_DIR = $ {PYTHON_INCLUDE_DIRS} + -DPYTHON_LIBRARY = $ {PYTHON_LIBRARY} + -DPYTHON_EXECUTABLE = $ {PYTHON_EXECUTABLE} -DWITH_FLUID_ONLY = ON -DWITH_GPU = OFF -DWITH_TESTING = OFF -DCMAKE_BUILD_TYPE =Release` + + + For Python3: `cmake .. -G "Visual Studio 14 2015 Win64" -DPY_VERSION = 3.5 -DPYTHON_INCLUDE_DIR = $ {PYTHON_INCLUDE_DIRS} + -DPYTHON_LIBRARY = $ {PYTHON_LIBRARY} + -DPYTHON_EXECUTABLE = $ {PYTHON_EXECUTABLE} -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. + +7. Some third-party dependencies (openblas, snappystream) currently require users to provide pre-compiled versions, or download pre-compiled files from `https://github.com/wopeizl/Paddle_deps` and place the entire `third_party` folder in the `build` directory. + +8. Use Blend for Visual Studio 2015 to open `paddle.sln` file, select the platform `x64`, configure with `Release`, then begin to compile + +9. Having compiled successfully, go to the `\paddle\build\python\dist`directory and find the generated `.whl` package: + + `cd \paddle\build\python\dist` + +10. 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. + + +### ***Verify installation*** + +After the installation is complete, you can use: `python` to enter the Python interpreter and then use `import paddle.fluid`. If there is no error prompted, the installation is successful. + +### ***How to uninstall*** + +Please use the following command to uninstall PaddlePaddle: + +* ***CPU version of PaddlePaddle*** : `pip uninstall paddlepaddle` or `pip3 uninstall paddlepaddle` diff --git a/doc/fluid/beginners_guide/install/compile/fromsource_en.rst b/doc/fluid/beginners_guide/install/compile/fromsource_en.rst new file mode 100644 index 0000000000000000000000000000000000000000..970a0abcb59f687fb78ac976be60b4ce4a963f7b --- /dev/null +++ b/doc/fluid/beginners_guide/install/compile/fromsource_en.rst @@ -0,0 +1,13 @@ +============================== +**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 diff --git a/doc/fluid/beginners_guide/install/index_cn.rst b/doc/fluid/beginners_guide/install/index_cn.rst index 5b7e02ba766cd95a1ce443c7a9e41d53dd816628..adfc8adba6b48caab297a25bc01e81fe7ba69876 100644 --- a/doc/fluid/beginners_guide/install/index_cn.rst +++ b/doc/fluid/beginners_guide/install/index_cn.rst @@ -1,7 +1,11 @@ ========== 安装说明 ========== -本说明将指导您在64位台式机或笔记本电脑上, 使用Python2.7或者Python3.5编译和安装PaddlePaddle，目前PaddlePaddle支持以下环境： +本说明将指导您在64位台式机或笔记本电脑上编译和安装PaddlePaddle + +PaddlePaddle目前支持的Python版本包括：Python 2.7-3.7 + +PaddlePaddle目前支持以下环境： * *Ubuntu 14.04 /16.04 /18.04* * *CentOS 7 / 6* diff --git a/doc/fluid/beginners_guide/install/install_CentOS.md b/doc/fluid/beginners_guide/install/install_CentOS.md index de020cd4b9b8f7718581b4ef0448a4f3d6acef9e..6a1a56369600fe38862337ab05b12887b9a4fd69 100644 --- a/doc/fluid/beginners_guide/install/install_CentOS.md +++ b/doc/fluid/beginners_guide/install/install_CentOS.md @@ -6,7 +6,7 @@ -请注意：在其他系统上的尝试可能会导致安装失败。请确保您的环境满足以上条件，我们默认提供的安装同时需要您的计算机处理器支持AVX指令集，否则请选择[多版本whl包安装列表](Tables.html/#ciwhls)中`no_avx`的版本。 +请注意：在其他系统上的尝试可能会导致安装失败。请确保您的环境满足以上条件，我们默认提供的安装同时需要您的计算机处理器支持AVX指令集，否则请选择[[最新Release安装包列表](./Tables.html/#ciwhls-release)中`no_avx`的版本。 CentOS系统下您可以使用`cat /proc/cpuinfo | grep avx`来检测您的处理器是否支持AVX指令集 @@ -48,17 +48,6 @@ CentOS系统下您可以使用`cat /proc/cpuinfo | grep avx`来检测您的处

### ***使用pip安装PaddlePaddle*** -您可以直接粘贴以下命令到命令行来安装PaddlePaddle(适用于CentOS7安装CPU-ONLY的版本)，如果出现问题，您可以参照后面的解释对命令作出适应您系统的更改： - -Python2.7： - - yum update && yum install -y epel-release && yum install -y python-devel python-pip && pip install paddlepaddle - - -Python3.5、3.6、3.7: (由于在CentOS下安装Python3的方法较为复杂，我们提供默认您已经正确安装python3.5+以及pip3之后的安装命令） - - yum update && yum install -y epel-release && pip3 install paddlepaddle - 首先，我们使用以下指令来**检测本机的环境**是否适合安装PaddlePaddle： @@ -101,7 +90,7 @@ Python3.5、3.6、3.7: (由于在CentOS下安装Python3的方法较为复杂， * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` - > `版本号`参见[安装包列表](./Tables.html/#whls)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[多版本whl包列表](./Tables.html/#ciwhls)或者我们的[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 + > `版本号`参见[最新Release安装包列表](./Tables.html/#whls)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[[最新dev安装包列表](./Tables.html/#ciwhls)或者我们的[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 diff --git a/doc/fluid/beginners_guide/install/install_CentOS_en.md b/doc/fluid/beginners_guide/install/install_CentOS_en.md new file mode 100644 index 0000000000000000000000000000000000000000..c4ec953ccae21aadfa4bb064f10acce85ca5a068 --- /dev/null +++ b/doc/fluid/beginners_guide/install/install_CentOS_en.md @@ -0,0 +1,148 @@ +*** + +# **Install under CentOS** + +This note will show you how to install PaddlePaddle on a *64-bit desktop or laptop* and CentOS. The CentOS system we support needs to meet the following requirements: + +Please note: Attempts on other systems may cause the installation to fail. Please ensure that your environment meets the conditions. The installation we provide by default requires your computer processor to support the AVX instruction set. Otherwise, please select the version of `no_avx` in [the latest Release installation package list](./Tables.html/#ciwhls-release). + +Under CentOS you can use `cat /proc/cpuinfo | grep avx` to check if your processor supports the AVX instruction set. + +* CentOS 6 / 7 + +## Determine which version to install + +* Only PaddlePaddle for CPU is supported. If your computer does not have an NVIDIA® GPU, you can only install this version. If your computer has a GPU, it is recommended that you install the CPU version of PaddlePaddle first to check if your local environment is suitable. + +* PaddlePaddle with GPU support, in order to make the PaddlePaddle program run more quickly, we accelerate the PaddlePaddle program through the GPU, but the GPU version of PaddlePaddle needs to have the NVIDIA® GPU that meets the following conditions (see the NVIDIA official for the specific installation process and configuration). Documentation: [For CUDA](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/), [For cuDNN](https://docs.nvidia.com/deeplearning/sdk/cudnn-install/)) + + * *CUDA Toolkit 9.0 with cuDNN v7* + * *CUDA Toolkit 8.0 with cuDNN v7* + * *Hardware devices with GPU compute capability exceeding 1.0* + + +## Choose an installation method + +We offer 4 installation methods under the CentOS system: + +* Pip installation +* Docker installation (the GPU version is not supported) (the version of python in the image is 2.7) +* Source code compilation and installation (all versions of CentOS 6 and GPU version of CentOS 7 are not supported) +* Docker source compilation and installation (not supported for GPU version) (Python version 2.7, 3.5, 3.6, 3.7 in image) + +**With pip installation** (the easiest way to install), we offer you a pip installation method, but it depends more on your native environment and may have some issues related to your local environment. + +**Use Docker for installation** (the safest way to install), because we are installing the tools and configuration in a Docker image so that if something goes wrong, others can reproduce the problem for 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 run directly on the native CPU and operating system. The performance is the same as installing the compiler on the machine. + +Compile and install from [**source**](#ct_source) and [**use Docker**](#ct_docker). This is a process of compiling the PaddlePaddle source code into a binary file and then installing the binary file. Compared with the binary form of PaddlePaddle that has been successfully tested and compiled for you, this manual compilation is more complicated, and we will answer you in detail at the end of this tutorial. + + +

+## ***Install PaddlePaddle using pip*** + +First, we use the following commands to check if **the environment of this machine** is suitable for installing PaddlePaddle: + +`Uname -m && cat /etc/*release` + +> The above command will display the operating system and processing bits of the machine. Please make sure your computer is consistent with the requirements of this tutorial. + +Second, your computer needs to meet the following requirements: + +* Python2.7.x (devel), Pip >= 9.0.1 + + > CentOS6 needs to compile Python 2.7 into a [shared library](./FAQ.html/#FAQ). + +* Python3.5+.x (devel), Pip3 >= 9.0.1 + + > You may have installed pip on your CentOS. Please use pip -V to confirm that we recommend using pip 9.0.1 or higher to install. + + Update the source of yum: `yum update` and install the extension source to install pip: `yum install -y epel-release` + + Use the following command to install or upgrade Python and pip to the required version: + + + - For Python2: `sudo yum install python-devel python-pip` + - For Python3: (Please refer to the official Python installation, and pay attention to whether the python3 version is consistent with the python version corresponding to the pip3 command. If there are multiple python3 versions, please specify the pip version such as pip3.7, or add soft link from pip3 to the python version you use. ) + + + + + > Even if you already have `Python` in your environment, you need to install the `python develop` package. + +Here's how to install PaddlePaddle: + +1. Use pip install to install PaddlePaddle: + + * For users who need **the CPU version PaddlePaddle**: `pip install paddlepaddle` or `pip3 install paddlepaddle` + + * For users who need **the GPU version PaddlePaddle**: `pip install paddlepaddle-gpu` or `pip3 install paddlepaddle-gpu` + + > 1 . In order to prevent problem "nccl.h cannot be found", please first install nccl2 according to the instructions of [NVIDIA official website](https://developer.nvidia.com/nccl/nccl-download). + + > 2 . If you do not specify the pypi package version number, we will by default provide you with a version of PaddlePaddle that supports Cuda 9/cuDNN v7. + + * For users with `Cannot uninstall 'six'.` problems, the probable reason is the existing Python installation issues in your system. In this case, use `pip install paddlepaddle --ignore-installed six`(CPU) or `pip install paddlepaddle-gpu -- Ignore-installed six` (GPU) to resolve. + + * For users with **other requirements**: `pip install paddlepaddle==[version number]` or `pip3 install paddlepaddle==[version number]` + + > For `the version number`, please refer to [the latest Release installation package list](./Tables.html/#whls). If you need to obtain and install **the latest PaddlePaddle development branch**, you can download and install the latest whl installation package and c-api development package from [the latest dev installation package list](./Tables.html/#ciwhls) or our [CI system](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview). To log in, click on "Log in as guest". + +Now you have completed the process of installing PaddlePaddle via `pip install`. + + +

+## *Install using 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 to install and use the PaddlePaddle version that supports GPU, you must first install [nvidia-docker](https://github.com/NVIDIA/nvidia-docker). + +Once you have **properly installed Docker**, you can start **installing PaddlePaddle with Docker**. + +1. Use the following command to pull the image we pre-installed for PaddlePaddle: + + * For users who need a **CPU version of PaddlePaddle**, use the following command to pull the image we pre-installed for your *PaddlePaddle For CPU*: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle: 1.2` + + * You can also pull any of our Docker images by following the instructions below: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` + + > (Please replace [tag] with the contents of [the mirror table](./Tables.html/#dockers)) + + +2. Use the following command to build from the already pulled image and enter the Docker container: + + `Docker run --name [Name of container] -it -v $PWD:/paddle /bin/bash` + + > In the above command, --name [Name of container] sets the name of the Docker; the -it parameter indicates that the container is running interactively with the host machine; -v $PWD:/paddle specifies the current path (the PWD variable in Linux will expand to [The absolute path](https://baike.baidu.com/item/%E7%BB%9D%E5%AF%B9%E8%B7%AF%E5%BE%84/481185) of the current path ) which is mounted to the /paddle directory inside the container; `` specifies the name of the image to use, if you need to use our image please use `hub.baidubce.com/paddlepaddle/paddle:[tag]`. Note: The meaning of the tag is the same as the second step. /bin/bash is the command to be executed in Docker. + +3. (Optional: When you need to enter the Docker container a second time) re-enter the PaddlePaddle container with the following command: + + `Docker start [Name of container]` + + > start the container created previously + + `Docker attach [Name of container]` + + > Enter the started container in the last step. + +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. + + +

+## ***Verify installation*** + +After the installation is complete, you can use `python` or `python3` to enter the Python interpreter and then use `import paddle.fluid` to verify that the installation was successful. + +

+## ***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` + +* ***GPU version of PaddlePaddle***: `pip uninstall paddlepaddle-gpu` or `pip3 uninstall paddlepaddle-gpu` diff --git a/doc/fluid/beginners_guide/install/install_MacOS.md b/doc/fluid/beginners_guide/install/install_MacOS.md index d0464e0b77e70e2056501b1f81a1b3fcf6d56702..50280990a093860f89a54bb53d57b28c8b4ee800 100644 --- a/doc/fluid/beginners_guide/install/install_MacOS.md +++ b/doc/fluid/beginners_guide/install/install_MacOS.md @@ -59,7 +59,7 @@ * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` - > `版本号`参见[安装包列表](./Tables.html/#whls)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 + > `版本号`参见[最新Release安装包列表](./Tables.html/#ciwhls-release)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 diff --git a/doc/fluid/beginners_guide/install/install_MacOS_en.md b/doc/fluid/beginners_guide/install/install_MacOS_en.md new file mode 100644 index 0000000000000000000000000000000000000000..0e4e5cc6f9076f24be29008c8c4389f57bd5b152 --- /dev/null +++ b/doc/fluid/beginners_guide/install/install_MacOS_en.md @@ -0,0 +1,124 @@ +*** +# **Install under MacOS** + +This instruction will show you how to install PaddlePaddle on a *64-bit desktop or laptop* and MacOS system. The MacOS system we support must meet the following requirements. + +Please note: Attempts on other systems may cause the installation to fail. + +* MacOS 10.11/10.12/10.13/10.14 + +## Determine which version to install + +* Only PaddlePaddle for CPU is supported. + + + +## Choose an installation method + +Under the MacOS system we offer 3 installation methods: + +* Pip installation (not supported for GPU version) (distributed architecture is not supported under python3) +* Docker installation (the GPU version is not supported) (the version of python in the image is 2.7) +* Docker source compilation and installation (not supported for GPU version) (Python version 2.7, 3.5, 3.6, 3.7 in image) + +**With pip installation** (the easiest way to install), we offer you a pip installation method, but it depends more on your local environment and may have some issues related to your local environment. + +**Use Docker for installation** (the safest way to install), because we have installed the tools and configuration in a Docker image so that if something goes wrong, others can reproduce the problem for 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 local CPU and operating system. The performance is the same as installing the compiler on the machine. + + +

+### ***Install using pip*** + +Due to the large difference in Python situation in MacOS, we do not provide quick installation commands. Please follow the steps below to install. + +First, **check whether your computer and operating system** meet our supported compilation standards or not by `uname -m` and view the system version `About This Mac` in the Apple menu. + +Second, your computer needs to meet the following requirements: + +> **Please do not use the Python originally provided by MacOS**. For **Python 2**, we recommend Python2.7.15 provided by [Homebrew](https://brew.sh/) or [Python.org](https://www.python.org/ftp/python/2.7.15/python-2.7.15-macosx10.9.pkg). For Python3, please use python3.5.x, Python3.6.x or python3.7.x provided by [Python.org](https://www.python.org/downloads/mac-osx/). + + + For python2: brew install python@2 or use Python officially downloaded python2.7.15 + For python3: Use python3.5.x, python3.6.x or python3.7.x downloaded from Python official site + + +* Python2.7.x, Pip >= 9.0.1 + +* Python3.5.x, Pip3 >= 9.0.1 + +* Python3.6.x, Pip3 >= 9.0.1 + +* Python3.7.x, Pip3 >= 9.0.1 + + > Note: You may have installed pip on your MacOS. Please use pip -V to confirm that its version is the recommended pip 9.0.1 or higher. + + +Here's how to install PaddlePaddle: + +1. Use pip install to install PaddlePaddle: + + * For users who need **the CPU version PaddlePaddle**: `pip install paddlepaddle` or `pip3 install paddlepaddle` + + * For users with **other requirements**: `pip install paddlepaddle==[version number]` or `pip3 install paddlepaddle==[version number]` + + > For `the version number`, please refer to [the latest Release installation package list](./Tables.html/#ciwhls-release). If you need to obtain and install **the latest PaddlePaddle development branch**, you can download the latest whl installation package and c-api development package from [the CI system](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) and install it. To log in, click on "Log in as guest". + + + +Now you have completed the process of installing PaddlePaddle via `pip install`. + + +

+### ***Install using 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. + + +If Docker is **properly installed**, you can start **using Docker to install PaddlePaddle**. + +1. Use the following command to pull the image we pre-installed for PaddlePaddle: + + * For users who need **the CPU version of PaddlePaddle**, use the following command to pull the image we pre-installed for your *PaddlePaddle For CPU*: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle: 1.2` + + * You can also pull any of our Docker images by following the instructions below: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` + + > (Please replace [tag] with the contents of [the mirror table](./Tables.html/#dockers)) + +2. Use the following command to build from the already pulled image and enter the Docker container: + + `Docker run --name [Name of container] -it -v $PWD:/paddle /bin/bash` + + > In the above command, --name [Name of container] sets the name of the Docker; the -it parameter indicates that the container is running interactively with the host machine; -v $PWD:/paddle specifies the current path (the PWD variable in Linux will expand to [The absolute path](https://baike.baidu.com/item/绝对路径/481185) ) of the current path is mounted to the /paddle directory inside the container; `` specifies the name of the image to use, if you need to use our image please use `hub.baidubce.com/paddlepaddle/paddle:[tag]`. Note: The meaning of tag is the same as the second step; /bin/bash is the command to be executed in Docker. + +3. (Optional: When you need to enter the Docker container a second time) re-enter the PaddlePaddle container with the following command: + + `Docker start [Name of container]` + + > start the container created previously. + + `Docker attach [Name of container]` + + > Enter the started container. + +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. + + +

+## ***Verify installation*** + +After the installation is complete, you can use `python` or `python3` to enter the python interpreter and then use `import paddle.fluid` to verify that the installation was successful. + +

+## ***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` diff --git a/doc/fluid/beginners_guide/install/install_Ubuntu.md b/doc/fluid/beginners_guide/install/install_Ubuntu.md index 7dcd78870f305e31c089ccf1633164c17a72fd82..8dc394687662c34e03d290aedc5cac6cce05326f 100644 --- a/doc/fluid/beginners_guide/install/install_Ubuntu.md +++ b/doc/fluid/beginners_guide/install/install_Ubuntu.md @@ -6,7 +6,7 @@ -请注意：在其他系统上的尝试可能会导致安装失败。请确保您的环境满足以上条件，我们默认提供的安装同时需要您的计算机处理器支持AVX指令集，否则请选择[多版本whl包安装列表](Tables.html/#ciwhls)中`no_avx`的版本。 +请注意：在其他系统上的尝试可能会导致安装失败。请确保您的环境满足以上条件，我们默认提供的安装同时需要您的计算机处理器支持AVX指令集，否则请选择[最新Release安装包列表](./Tables.html/#ciwhls-release)中`no_avx`的版本。 Ubuntu系统下您可以使用`cat /proc/cpuinfo | grep avx`来检测您的处理器是否支持AVX指令集 @@ -47,25 +47,7 @@ Ubuntu系统下您可以使用`cat /proc/cpuinfo | grep avx`来检测您的处

### ***使用pip安装*** -#### ****直接安装**** -您可以直接粘贴以下命令到命令行来安装PaddlePaddle(适用于ubuntu16.04及以上安装CPU-ONLY的版本)，如果出现问题，您可以参照后面的解释对命令作出适应您系统的更改： - -Python2.7： - - apt update && apt install -y python-dev python-pip && pip install paddlepaddle - -Python3.5（该指令适用于本机未安装python2的用户，否则，请卸载python2之后再使用本指令）： - - apt-get udpate && apt-get install -y software-properties-common && add-apt-repository ppa:deadsnakes/ppa && apt-get install -y curl python3.5 python3.5-dev wget vim git && curl https://bootstrap.pypa.io/get-pip.py -o - | python3.5 && easy_install pip && pip3 install paddlepaddle - -Python3.6、Python3.7：（由于版本相对较新，在不同Ubuntu版本上安装差异较大，不一一描述其安装过程，执行以下命令前，我们认为您已经准备好python3.6或3.7的环境，并安装了对应版本的python3-dev以及pip3） - - apt update && pip3 install paddlepaddle - -
- -#### ****分步安装**** 首先，我们使用以下指令来**检测本机的环境**是否适合安装PaddlePaddle： uname -m && cat /etc/*release @@ -108,7 +90,7 @@ Python3.6、Python3.7：（由于版本相对较新，在不同Ubuntu版本上 * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` - > `版本号`参见[安装包列表](./Tables.html/#whls)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[多版本whl包列表](./Tables.html/#ciwhls)或者我们的[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 + > `版本号`参见[最新Release安装包列表](./Tables.html/#whls)或者您如果需要获取并安装**最新的PaddlePaddle开发分支**，可以从[最新dev安装包列表](./Tables.html/#ciwhls)或者我们的[CI系统](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview) 中下载最新的whl安装包和c-api开发包并安装。如需登录，请点击“Log in as guest”。 diff --git a/doc/fluid/beginners_guide/install/install_Ubuntu_en.md b/doc/fluid/beginners_guide/install/install_Ubuntu_en.md new file mode 100644 index 0000000000000000000000000000000000000000..912926230be797b7c81a28a679cec7b17207987d --- /dev/null +++ b/doc/fluid/beginners_guide/install/install_Ubuntu_en.md @@ -0,0 +1,159 @@ +*** + +# **Install under Ubuntu** + +This instruction describes how to install PaddlePaddle on a *64-bit desktop or laptop and Ubuntu system. The Ubuntu systems we support must meet the following requirements: + +Please note: Attempts on other systems may cause the installation to fail. Please ensure that your environment meets the conditions. The installation we provide by default requires your computer processor to support the AVX instruction set. Otherwise, please select the version of `no_avx` in the [latest Release installation package list](./Tables.html/#ciwhls-release). + +Under Ubuntu, you can use `cat /proc/cpuinfo | grep avx` to check if your processor supports the AVX instruction set. + +* Ubuntu 14.04 /16.04 /18.04 + +## Determine which version to install + +* PaddlePaddle for CPU is supported. If your computer does not have an NVIDIA® GPU, you can only install this version. If your computer has a GPU, it is also recommended that you install the CPU version of PaddlePaddle first to check if your local environment is suitable. + +* PaddlePaddle for GPU is supported. In order to make the PaddlePaddle program run more quickly, we accelerate the PaddlePaddle program through the GPU, but the GPU version of the PaddlePaddle needs to have the NVIDIA® GPU that meets the following conditions (see the NVIDIA official documentation for the specific installation process and configuration: [For CUDA](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/), [For cuDNN](https://docs.nvidia.com/deeplearning/sdk/cudnn-install/)) + + * *CUDA Toolkit 9.0 with cuDNN v7* + * *CUDA Toolkit 8.0 with cuDNN v7* + * *Hardware devices with GPU computing power exceeding 1.0* + + + +## Choose an installation method + +Under the Ubuntu system, we offer 4 installation methods: + +* Pip installation +* Docker installation (the version of python in the image is 2.7) +* Source code compilation and installation +* Docker source code compilation and installation (the python version in the image is 2.7, 3.5, 3.6, 3.7) + + +**With pip installation** (the easiest way to install), we offer you a pip installation method, but it depends more on your native environment and may have some issues related to your local environment. + +**Use Docker for installation** (the safest way to install), because we have installed the tools and configuration in a Docker image so that if something goes wrong, others can reproduce the problem for 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. + +Compile and install from [**source**](#ubt_source) and [**use Docker**](#ubt_docker). This is a process of compiling the PaddlePaddle source code into a binary file and then installing the binary file. Compared to the binary PaddlePaddle that has been successfully tested and compiled for you, the manual compilation is more complicated, we will answer you in detail at the end of the description. + +

+### ***Install using pip*** + + +First, we use the following commands to **check if the environment of this machine** is suitable for installing PaddlePaddle: + + uname -m && cat /etc/*release + +>The above command will display the operating system and processing bits of the machine. Please make sure your computer is consistent with the requirements of this tutorial. + +Second, your computer needs to meet any of the following requirements: + +* Python2.7.x (dev), Pip >= 9.0.1 +* Python3.5+.x (dev), Pip3 >= 9.0.1 + +>You may have installed pip on your Ubuntu. Please use pip -V or pip3 -V to confirm its version is the recommended pip 9.0.1 or higher. + + Update apt source: `apt update` + +Use the following command to install or upgrade Python and pip to the required version: (pip and dev installation in python3.6, python3.7 differs greatly across different Ubuntu versions, thus the steps are omitted here) + + - For python2: `sudo apt install python-dev python-pip` + + - For python3.5: `sudo apt install python3.5-dev and curl https://bootstrap.pypa.io/get-pip.py -o - | python3.5 && easy_install pip` + + - For python3.6, python3.7: We assumed that python3.6 (3.7) and the corresponding versions of dev and pip3 are properly installed by yourself. + + +>Even if you already have Python 2 or Python 3 in your environment, you need to install Python-dev or Python 3.5 (3.6, 3.7) -dev. + +Now let's install PaddlePaddle: + + + +1. Use pip install to install PaddlePaddle + + + * For users who need **the CPU version PaddlePaddle**: `pip install paddlepaddle` or `pip3 install paddlepaddle` + + * For users who need **the GPU version PaddlePaddle**: `pip install paddlepaddle-gpu` or `pip3 install paddlepaddle-gpu` + + > 1.In order to prevent problem "nccl.h cannot be found", please first install nccl2 according to the following command (here is ubuntu 16.04, CUDA9, ncDNN v7 nccl2 installation instructions), for more information about the installation information, please refer to [the NVIDIA official website](https://developer.nvidia.com/nccl/nccl-download): + + i. `Wget http://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu1604/x86_64/nvidia-machine-learning-repo-ubuntu1604_1.0.0-1_amd64.deb` + ii. `dpkg -i nvidia-machine- Learning-repo-ubuntu1604_1.0.0-1_amd64.deb` + iii. `sudo apt-get install -y libnccl2=2.2.13-1+cuda9.0 libnccl-dev=2.2.13-1+cuda9.0` + + > 2.If you do not specify the pypi package version number, we will by default provide you with a version of PaddlePaddle that supports Cuda 9/cuDNN v7. + + * For users with `Cannot uninstall 'six'.` problems, the probable reason is the existing Python installation issues in your system. In this case, use `pip install paddlepaddle --ignore-installed six`(CPU) or `pip install paddlepaddle-gpu -- Ignore-installed six` (GPU) to resolve. + + * For users with **other requirements**: `pip install paddlepaddle==[version number]` or `pip3 install paddlepaddle==[version number]` + + > For `the version number`, please refer to [the latest Release installation package list](./Tables.html/#whls). If you need to obtain and install **the latest PaddlePaddle development branch**, you can download and install the latest whl installation package and c-api development package from [the latest dev installation package list](./Tables.html/#ciwhls) or our [CI system](https://paddleci.ngrok.io/project.html?projectId=Manylinux1&tab=projectOverview). To log in, click on "Log in as guest". + + +Now you have completed the process of installing PaddlePaddle using `pip install`. + + +

+### ***Install using 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 to install and use the PaddlePaddle version that supports GPU, you must first install [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) + +If Docker is **properly installed**, you can start **installing PaddlePaddle using Docker**. + +1. Use the following command to pull the image we pre-installed for PaddlePaddle: + + * For users who need **a CPU version of PaddlePaddle**, use the following command to pull the image we pre-installed for your *PaddlePaddle For CPU*: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle: 1.2` + + * For users who need **a GPU version of PaddlePaddle**, use the following command to pull the image we pre-installed for your *PaddlePaddle For GPU*: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle:1.2-gpu-cuda9.0-cudnn7` + + * You can also pull any of our Docker images by following the instructions below: + + `Docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` + + > (Please replace [tag] with the contents of [the mirror table](https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/beginners_guide/install/Tables.html/#dockers)) + +2. Use the following command to build from the already pulled image and enter the Docker container: + + `Docker run --name [Name of container] -it -v $PWD:/paddle /bin/bash` + + > In the above command, --name [Name of container] sets the name of the Docker; the `-it` parameter indicates that the container is running interactively with the host machine; -v $PWD:/paddle specifies the current path (the PWD variable in Linux will expand to The absolute path of the current path) is mounted to the /paddle directory inside the container; `` specifies the name of the image to use, if you need to use our image please use `hub.baidubce.com/paddlepaddle/paddle:[tag]`. Note: The meaning of tag is the same as the second step; /bin/bash is the command to be executed in Docker. + +3. (Optional: When you need to enter the Docker container a second time) re-enter the PaddlePaddle container with the following command: + + `Docker start [Name of container]` + + > start the container created previously. + + `Docker attach [Name of container]` + + > Enter the started container. + +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. + +

+## ***Verify installation*** + +After the installation is complete, you can use `python` or `python3` to enter the python interpreter and then use `import paddle.fluid` to verify that the installation was successful. + + + +

+## ***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` + +- ***GPU version of PaddlePaddle***: `pip uninstall paddlepaddle-gpu` or `pip3 uninstall paddlepaddle-gpu` diff --git a/doc/fluid/beginners_guide/install/install_Windows.md b/doc/fluid/beginners_guide/install/install_Windows.md index 2cea71fabf3a811219c7dbe399f107c2c17ba204..7ab3863f1752203abcf7c869d56113158ee417ad 100644 --- a/doc/fluid/beginners_guide/install/install_Windows.md +++ b/doc/fluid/beginners_guide/install/install_Windows.md @@ -27,10 +27,10 @@ Windows系统下可使用`cpu-z`这类软件来检测您的处理器是否支持 * 首先，**检查您的计算机和操作系统**是否满足以下要求： For python2: 使用Python官方下载的python2.7.15 - For python3: 使用Python官方下载的python3.5.x + For python3: 使用Python官方下载的python3.5.x, python3.6.x 或 python3.7.x -* Python2.7.x，pip >= 9.0.1 -* Python3.5.x，pip3 >= 9.0.1 +* Python2.7.x ：pip >= 9.0.1 +* Python3.5.x, python3.6.x 或 python3.7.x ：pip3 >= 9.0.1 下面将说明如何安装PaddlePaddle： diff --git a/doc/fluid/beginners_guide/install/install_Windows_en.md b/doc/fluid/beginners_guide/install/install_Windows_en.md new file mode 100644 index 0000000000000000000000000000000000000000..75f0a30711e3fbe55372c48c5ea88dc1c029e86e --- /dev/null +++ b/doc/fluid/beginners_guide/install/install_Windows_en.md @@ -0,0 +1,52 @@ +*** + +# **Install under Windows** + +This instruction will show you how to install PaddlePaddle on a 64-bit desktop or laptop and Windows. The Windows systems we support must meet the following requirements. + + +Please note: Attempts on other systems may cause the installation to fail. Please ensure that your environment meets the conditions. The installation we provide by default requires your computer processor to support the AVX instruction set. Otherwise, please select the version of `no_avx` in [the multi-version whl package installation list](Tables.html/#ciwhls): + +Windows can use software such as `cpu-z` to detect whether your processor supports the AVX instruction set. + +The current version does not support NCCL, distributed, AVX, warpctc and MKL related functions. + +* *Windows 7/8 and Windows 10 Professional/Enterprise Edition* + +## Determine which version to install + +* Under Windows, we currently only offer PaddlePaddle that supports CPU. + +## Choose an installation method + +### ***Install using pip*** + +We do not provide a quick installation command, please install according to the following steps： + +* First, **check that your computer and operating system** meet the following requirements: + + For python2: Python2.7.15 downloaded from official Python + For python3: Use python3.5.x, python3.6.x or python3.7.x downloaded from official Python + +* Python2.7.x :pip >= 9.0.1 +* Python3.5.x, python3.6.x or python3.7.x :pip3 >= 9.0.1 + +Here's how to install PaddlePaddle: + +* Use pip install to install PaddlePaddle: + + ** paddlepaddle's dependency package `recordio` may not be installed with `pip`'s default source, you can use `easy_install recordio` to install. ** + + ** For users who need **the CPU version PaddlePaddle**: `pip install paddlepaddle` or `pip3 install paddlepaddle`. ** + +Now you have completed the process of installing PaddlePaddle via `pip install`. + +## ***Verify installation*** + +After completing the installation, you can use `python` or `python3` to enter the python interpreter and then use `import paddle.fluid` to verify that the installation was successful. + +## ***How to uninstall*** + +Use the following command to uninstall PaddlePaddle (users who use Docker to install PaddlePaddle, please use the following command in the container containing PaddlePaddle): + +* ***CPU version of PaddlePaddle***: `pip uninstallpaddlepaddle `or `pip3 uninstall paddlepaddle` diff --git a/doc/fluid/beginners_guide/programming_guide/programming_guide.md b/doc/fluid/beginners_guide/programming_guide/programming_guide.md index 204cd195815e71ccdbafb12e88fc3da5bd178804..14fbe554ee53fa1fc080340043fafd8655539b53 100644 --- a/doc/fluid/beginners_guide/programming_guide/programming_guide.md +++ b/doc/fluid/beginners_guide/programming_guide/programming_guide.md @@ -62,10 +62,10 @@ a = fluid.layers.data(name="a",shape=[3,4],dtype='int64') #若图片的宽度和高度在运行时可变，将宽度和高度定义为None。 #shape的三个维度含义分别是：channel、图片的宽度、图片的高度 -b = fluid.layers.data(name="image",shape=[3,None,None],dtpye="float32") +b = fluid.layers.data(name="image",shape=[3,None,None],dtype="float32") ``` -其中，dtpye=“int64”表示有符号64位整数数据类型，更多Fluid目前支持的数据类型请查看：[Fluid目前支持的数据类型](../../user_guides/howto/prepare_data/feeding_data.html#fluid)。 +其中，dtype=“int64”表示有符号64位整数数据类型，更多Fluid目前支持的数据类型请查看：[Fluid目前支持的数据类型](../../user_guides/howto/prepare_data/feeding_data.html#fluid)。 **3. 常量 Tensor** @@ -384,6 +384,9 @@ outs = exe.run( #定义损失函数 cost = fluid.layers.square_error_cost(input=y_predict,label=y) avg_cost = fluid.layers.mean(cost) + #定义优化方法 + sgd_optimizer = fluid.optimizer.SGD(learning_rate=0.01) + sgd_optimizer.minimize(avg_cost) #参数初始化 cpu = fluid.core.CPUPlace() exe = fluid.Executor(cpu) diff --git a/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst b/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst index b4ba14ffbc616c65be71860f5dc482ace61f06b8..ea75d12de164a784d978d86a8b2bc07f91e40eeb 100644 --- a/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst +++ b/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst @@ -42,7 +42,7 @@ LoD 索引 让我们来看另一个2-level LoD-Tensor的例子：假设存在一个mini-batch中包含3个句子、1个句子和2个句子的文章，每个句子都由不同数量的单词组成，则这个mini-batch的样式可以看作： -.. code-block :: text +.. code-block:: text 3 1 2 @@ -52,7 +52,7 @@ LoD 索引 表示的LoD信息为： -.. code-block :: text +.. code-block:: text [[3，1，2]/*level=0*/，[3，2，4，1，2，3]/*level=1*/] @@ -61,7 +61,7 @@ LoD 索引 在视觉任务中，时常需要处理视频和图像这些元素是高维的对象，假设现存的一个nimi-batch包含3个视频，分别有3个，1个和2个帧，每个帧都具有相同大小：640x480，则这个mini-batch可以被表示为： -.. code-block :: text +.. code-block:: text 3 1 2 口口口 口 口口 @@ -73,14 +73,14 @@ LoD 索引 在传统的情况下，比如有N个固定大小的图像的mini-batch，LoD-Tensor表示为: -.. code-block :: text +.. code-block:: text 1 1 1 1 1 口口口口 ... 口 在这种情况下，我们不会因为索引值都为1而忽略信息，仅仅把LoD-Tensor看作是一个普通的张量: -.. code-block :: text +.. code-block:: text 口口口口 ... 口 @@ -95,13 +95,13 @@ LoDTensor的偏移表示 在上述例子中，您可以计算基本元素的长度： -.. code-block :: text +.. code-block:: text 3 2 4 1 2 3 将其转换为偏移表示： -.. code-block :: text +.. code-block:: text 0 3 5 9 10 12 15 = = = = = = @@ -111,13 +111,13 @@ LoDTensor的偏移表示 类似的，LoD的顶层长度 -.. code-block :: text +.. code-block:: text 3 1 2 可以被转化成偏移形式： -.. code-block :: text +.. code-block:: text 0 3 4 6 = = = @@ -125,7 +125,7 @@ LoDTensor的偏移表示 因此该LoD-Tensor的偏移表示为： -.. code-block :: text +.. code-block:: text 0 3 4 6 3 5 9 10 12 15 @@ -139,7 +139,7 @@ LoD-Tensor 以上文提到的一个2-level LoD-Tensor为例： -.. code-block :: text +.. code-block:: text 3 1 2 3 2 4 1 2 3 @@ -153,14 +153,27 @@ LoD-Tensor recursive_seq_lens 是一个双层嵌套列表，也就是列表的列表，最外层列表的size表示嵌套的层数，也就是lod-level的大小；内部的每个列表，对应表示每个lod-level下，每个元素的大小。 -.. code-block :: text +.. code-block:: python + #创建lod-tensor + import paddle.fluid as fluid + import numpy as np + + a = fluid.create_lod_tensor(np.array([[1],[1],[1], + [1],[1], + [1],[1],[1],[1], + [1], + [1],[1], + [1],[1],[1]]).astype('int64') , + [[3,1,2] , [3,2,4,1,2,3]], + fluid.CPUPlace()) + #查看lod-tensor嵌套层数 - print len(recursive_seq_lengths) + print len(a.recursive_sequence_lengths()) # output：2 #查看最基础元素个数 - print sum(recursive_seq_lengths[-1]) + print sum(a.recursive_sequence_lengths()[-1]) # output:15 (3+2+4+1+2+3=15) 代码示例 @@ -173,29 +186,14 @@ recursive_seq_lens 是一个双层嵌套列表，也就是列表的列表，最 - 学习如何打印LoDTensor内容 -**创建LoD-Tensor** - -Fluid中可以通过 :code:`fluid.create_lod_tensor()` 创建一个LoD-Tensor，使用说明请参考 :ref:`api_fluid_layers_sequence-expand` 。需要注意的是，这个API只能支持int64的数据，如果您希望处理float32的数据，推荐您使用下述方式创建lod_tensor： - -使用fluid.LoDTensor()创建一个LoD-Tensor，并为其指定数据、运算场所和LoD值： - -.. code-block :: python - import paddle.fluid as fluid - import numpy as np - - def create_lod_tensor(data, lod, place): - res = fluid.LoDTensor() - res.set(data, place) - res.set_lod(lod) - return res - + **定义计算过程** -layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充，关于 :code:`fluid.layers.sequence_expand` 的功能说明，请先阅读 :ref:`api_fluid_layers_sequence-expand` 。 +layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充，关于 :code:`fluid.layers.sequence_expand` 的功能说明，请先阅读 :ref:`api_fluid_layers_sequence_expand` 。 序列扩充代码实现： -.. code-block :: python +.. code-block:: python x = fluid.layers.data(name='x', shape=[1], dtype='float32', lod_level=0) y = fluid.layers.data(name='y', shape=[1], dtype='float32', lod_level=1) @@ -205,7 +203,7 @@ layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充， **创建Executor** -.. code-block :: python +.. code-block:: python place = fluid.CPUPlace() exe = fluid.Executor(place) @@ -213,47 +211,24 @@ layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充， **准备数据** -这里我们使用偏移量的方法表示Tensor的LoD索引： -假使x_d 为一个LoDTensor： - -.. code-block :: shell - - x.lod = [[0,1,4]] - x.data = [[1],[2],[3],[4]] - x.dims = [4,1] - -y_d 也为一个LoDTensor： - -.. code-block :: shell - - y.lod = [[0, 1, 4], - [0, 2, 3, 5, 6]] - -其中，输出值只与 y 的LoD值有关，y_d 的 data 值在这里并不参与计算，维度上与LoD[-1]一致即可。 +这里我们调用 :code:`fluid.create_lod_tensor` 创建 :code:`sequence_expand` 的输入数据，通过定义 y_d 的 LoD 值，对 x_d 进行扩充。其中，输出值只与 y_d 的 LoD 值有关，y_d 的 data 值在这里并不参与计算，维度上与LoD[-1]一致即可。 -预期输出结果为： - -.. code-block :: shell - - #预期输出lod的原始长度 - out.lod = [ [1, 3, 3, 3]] - #预期输出结果 - out.data = [ [1],[2],[3],[4],[2],[3],[4],[2],[3],[4]] +:code:`fluid.create_lod_tensor()` 的使用说明请参考 :ref:`api_fluid_create_lod_tensor` 。 实现代码如下： -.. code-block :: python +.. code-block:: python + + x_d = fluid.create_lod_tensor(np.array([[1.1],[2.2],[3.3],[4.4]]).astype('float32'), [[1,3]], place) + y_d = fluid.create_lod_tensor(np.array([[1.1],[1.1],[1.1],[1.1],[1.1],[1.1]]).astype('float32'), [[1,3], [2,1,2,1]],place) - x_d = create_lod_tensor(np.array([[1], [2],[3],[4]]), [[0,1,4]], place) - y_d = create_lod_tensor(np.array([[1],[1],[1],[1],[1],[1]]), [[0,1,4], [0,2,3,5,6]], place) **执行运算** -在Fluid中，LoD>1的Tensor与其他类型数据一样，使用feed定义数据传入顺序。此外，由于输出results是带有LoD信息的Tensor，需在exe.run( )中添加 :code: `return_numpy=False`参数，获得LoD-Tensor的输出结果。 +在Fluid中，LoD>1的Tensor与其他类型的数据一样，使用 :code:`feed` 定义数据传入顺序。此外，由于输出results是带有LoD信息的Tensor，需在exe.run( )中添加 :code:`return_numpy=False` 参数，获得LoD-Tensor的输出结果。 -.. code-block :: python +.. code-block:: python - feeder = fluid.DataFeeder(place=place, feed_list=[x, y]) results = exe.run(fluid.default_main_program(), feed={'x':x_d, 'y': y_d }, fetch_list=[out],return_numpy=False) @@ -262,17 +237,63 @@ y_d 也为一个LoDTensor： 由于LoDTensor的特殊属性，无法直接print查看内容，常用操作时将LoD-Tensor作为网络的输出fetch出来，然后执行 numpy.array(lod_tensor), 就能转成numpy array： -.. code-block :: python +.. code-block:: python np.array(results[0]) 输出结果为： -.. code-block :: python +.. code-block:: text + + array([[1.1],[2.2],[3.3],[4.4],[2.2],[3.3],[4.4],[2.2],[3.3],[4.4]]) + +**查看序列长度** + +可以通过查看序列长度得到 LoDTensor 的递归序列长度： + +.. code-block:: python + + results[0].recursive_sequence_lengths() + +输出结果为： - array([[1],[2],[3],[4],[2],[3],[4],[2],[3],[4]]) +.. code-block:: text + + [[1L, 3L, 3L, 3L]] + +**完整代码** + +您可以运行下列完整代码，观察输出结果： + +.. code-block:: python + + #加载库 + import paddle + import paddle.fluid as fluid + import numpy as np + #定义前向计算 + x = fluid.layers.data(name='x', shape=[1], dtype='float32', lod_level=0) + y = fluid.layers.data(name='y', shape=[1], dtype='float32', lod_level=1) + out = fluid.layers.sequence_expand(x=x, y=y, ref_level=0) + #定义运算场所 + place = fluid.CPUPlace() + #创建执行器 + exe = fluid.Executor(place) + exe.run(fluid.default_startup_program()) + #创建LoDTensor + x_d = fluid.create_lod_tensor(np.array([[1.1], [2.2],[3.3],[4.4]]).astype('float32'), [[1,3]], place) + y_d = fluid.create_lod_tensor(np.array([[1.1],[1.1],[1.1],[1.1],[1.1],[1.1]]).astype('float32'), [[1,3], [1,2,1,2]], place) + #开始计算 + results = exe.run(fluid.default_main_program(), + feed={'x':x_d, 'y': y_d }, + fetch_list=[out],return_numpy=False) + #输出执行结果 + print("The data of the result: {}.".format(np.array(results[0]))) + #输出 result 的序列长度 + print("The recursive sequence lengths of the result: {}.".format(results[0].recursive_sequence_lengths())) + #输出 result 的 LoD + print("The LoD of the result: {}.".format(results[0].lod())) -可以看到与准备数据一节中的预期结果一致。 总结 ======== diff --git a/doc/fluid/user_guides/howto/prepare_data/index.rst b/doc/fluid/user_guides/howto/prepare_data/index.rst index 338035b8c136a4d586b3dadf0978c280eb7812cc..3dcc2fe17902e978d377c4ebdc3b148c37326632 100644 --- a/doc/fluid/user_guides/howto/prepare_data/index.rst +++ b/doc/fluid/user_guides/howto/prepare_data/index.rst @@ -44,7 +44,7 @@ Python Reader支持组batch、shuffle等高级功能，具体请参考： .. toctree:: :maxdepth: 1 - reader.md + reader_cn.md py_reader接口异步方式 ##################### diff --git a/doc/fluid/user_guides/howto/prepare_data/reader.md b/doc/fluid/user_guides/howto/prepare_data/reader.md index aa50e4d26166536eaf8044d527debd8ad46060f6..fab10bdd4473d3f1cb0cbc9dcddd60ff863e3412 100644 --- a/doc/fluid/user_guides/howto/prepare_data/reader.md +++ b/doc/fluid/user_guides/howto/prepare_data/reader.md @@ -21,7 +21,7 @@ and also provide a function which can convert a reader to a batch reader, freque iterable = data_reader() ``` -The item produced from the iterable should be a **single** entry of data and **not** a mini batch. The entry of data could be a single item or a tuple of items. Item should be of one of the [supported types](http://www.paddlepaddle.org/doc/ui/data_provider/pydataprovider2.html?highlight=dense_vector#input-types) (e.g., numpy 1d array of float32, int, list of int etc.) +The item produced from the iterable should be a **single** entry of data and **not** a mini batch. The entry of data could be a single item or a tuple of items. Item should be of one of the supported types (e.g., numpy 1d array of float32, int, list of int etc.) An example implementation for single item data reader creator is as follows: @@ -164,7 +164,7 @@ reader = paddle.reader.shuffle(paddle.dataset.mnist.train(), 512) ### Why does a reader return only a single entry, and not a mini batch? -Returning a single entry makes reusing existing data readers much easier (for example, if an existing reader returns 3 entries instead if a single entry, the training code will be more complicated because it need to handle cases like a batch size 2). +Returning a single entry makes reusing existing data readers much easier (for example, if an existing reader returns 3 entries instead of a single entry, the training code will be more complicated because it needs to handle cases like a batch size 2). We provide a function: `paddle.batch` to turn (a single entry) reader into a batch reader. diff --git a/doc/fluid/user_guides/howto/prepare_data/reader_cn.md b/doc/fluid/user_guides/howto/prepare_data/reader_cn.md new file mode 100644 index 0000000000000000000000000000000000000000..f4e3178a85d4f7c3944c0d3c204a35ad3d1bb010 --- /dev/null +++ b/doc/fluid/user_guides/howto/prepare_data/reader_cn.md @@ -0,0 +1,203 @@ +```eval_rst +.. _user_guide_reader: +``` + +# Python Reader +在模型训练和预测阶段，PaddlePaddle程序需要读取训练或预测数据。为了帮助用户编写数据读取的代码，我们提供了如下接口： + +- *reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个数据项。 +- *reader creator*: 接受一个或多个reader作为参数、返回一个新reader的函数。 +- *reader decorator*: 一个函数，接受一个或多个reader，并返回一个reader。 +- *batch reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个batch大小的数据项。 + +此外，还提供了将reader转换为batch reader的函数，会频繁用到reader creator和reader decorator。 + +## Data Reader 接口 +Data reader不一定要求为读取和遍历数据项的函数。它可以是返回iterable对象（即可以用于`for x in iterable`的任意对象）的任意不带参数的函数： + +``` +iterable = data_reader() +``` + +Iterable对象应产生单项或tuple形式的数据，而不是一个mini batch的数据。产生的数据项应在[支持的类型](./feeding_data.html#fluid) 中，例如float32,int类型的numpy一维矩阵，int类型的列表等。 + +以下是实现单项数据reader creator的示例： + +```python +def reader_creator_random_image(width, height): + def reader(): + while True: + yield numpy.random.uniform(-1, 1, size=width*height) + return reader +``` + +以下是实现多项数据reader creator的示例： + +```python +def reader_creator_random_image_and_label(width, height, label): + def reader(): + while True: + yield numpy.random.uniform(-1, 1, size=width*height), label + return reader +``` + +## Batch Reader 接口 +*Batch reader*可以是返回iterable对象（即可以用于`for x in iterable`的任意对象）的任意不带参数的函数。Iterable的输出应为一个batch（list）的数据项。list中的每个数据项均为一个tuple元组。 + +这里是一些有效输出： + +```python +# 三个数据项组成一个mini batch。每个数据项有三列，每列数据项为1。 +[(1, 1, 1), +(2, 2, 2), +(3, 3, 3)] + +# 三个数据项组成一个mini batch。每个数据项是一个列表（单列）。 +[([1,1,1],), +([2,2,2],), +([3,3,3],)] +``` + +请注意列表里的每个项必须为tuple，下面是一个无效输出： +```python + # 错误, [1,1,1]需在一个tuple内: ([1,1,1],). + # 否则产生歧义，[1,1,1]是否表示数据[1, 1, 1]整体作为单一列。 + # 或者数据的三列，每一列为1。 +[[1,1,1], +[2,2,2], +[3,3,3]] +``` + +很容易将reader转换成batch reader： + +```python +mnist_train = paddle.dataset.mnist.train() +mnist_train_batch_reader = paddle.batch(mnist_train, 128) +``` + +也可以直接创建一个自定义batch reader： + +```python +def custom_batch_reader(): + while True: + batch = [] + for i in xrange(128): + batch.append((numpy.random.uniform(-1, 1, 28*28),)) # note that it's a tuple being appended. + yield batch + +mnist_random_image_batch_reader = custom_batch_reader +``` + +## 使用 +以下是我们如何用PaddlePaddle的reader： + +batch reader是从数据项到数据层（data layer）的映射，batch_size和总pass数通过以下方式传给`paddle.train`： + +```python +# 创建两个数据层： +image_layer = paddle.layer.data("image", ...) +label_layer = paddle.layer.data("label", ...) + +# ... +batch_reader = paddle.batch(paddle.dataset.mnist.train(), 128) +paddle.train(batch_reader, {"image":0, "label":1}, 128, 10, ...) +``` + +## Data Reader装饰器 +*Data reader decorator*接收一个或多个reader对象作为参数，返回一个新的reader对象。它类似于[python decorator](https://wiki.python.org/moin/PythonDecorators) ，但在语法上不需要写`@`。 + +我们对data reader接口有严格限制（无参数并返回单个数据项），data reader可灵活地搭配data reader decorators使用。以下是一些示例： + +### 预取回数据（缓存数据） +由于读数据需要一些时间，而没有数据无法进行训练，因此一般而言数据预读取会是一个很好的方法。 + +用`paddle.reader.buffered`预读取数据： + +```python +buffered_reader = paddle.reader.buffered(paddle.dataset.mnist.train(), 100) +``` + +`buffered_reader`将尝试缓存（预读取）`100`个数据项。 + +### 组成多个Data Reader +例如，如果我们想用实际图像源(也就是复用mnist数据集),和随机图像源作为[Generative Adversarial Networks](https://arxiv.org/abs/1406.2661)的输入。 + +我们可以参照如下： + +```python +def reader_creator_random_image(width, height): + def reader(): + while True: + yield numpy.random.uniform(-1, 1, size=width*height) + return reader + +def reader_creator_bool(t): + def reader: + while True: + yield t + return reader + +true_reader = reader_creator_bool(True) +false_reader = reader_creator_bool(False) + +reader = paddle.reader.compose(paddle.dataset.mnist.train(), data_reader_creator_random_image(20, 20), true_reader, false_reader) +# 跳过1因为paddle.dataset.mnist.train()为每个数据项生成两个项。 +# 并且这里我们暂时不考虑第二项。 +paddle.train(paddle.batch(reader, 128), {"true_image":0, "fake_image": 2, "true_label": 3, "false_label": 4}, ...) +``` + +### 随机排序 +给定大小为`n`的随机排序缓存， `paddle.reader.shuffle`返回一个data reader ，缓存`n`个数据项，并在读取一个数据项前进行随机排序。 + +示例： +```python +reader = paddle.reader.shuffle(paddle.dataset.mnist.train(), 512) +``` + +## Q & A + +### 为什么一个reader只返回单项而不是mini batch？ + +返回单项，可以更容易地复用已有的data reader，例如如果一个已有的reader返回3项而不是一个单项，这样训练代码会更复杂，因为需要处理像batch_size为2这样的例子。 + +我们提供一个函数来将一个单项reader转换成一个batch reader。 + +### 为什么需要一个batch raeder，在训练过程中给出reader和batch_size参数这样不足够吗？ + +在大多数情况下，在训练方法中给出reader和batch_size参数是足够的。但有时用户想自定义mini batch里数据项的顺序，或者动态改变batch_size。在这些情况下用batch reader会非常高效有用。 + +### 为什么用字典而不是列表进行映射？ + +使用字典(`{"image":0, "label":1}`)而不是列表`["image", "label"]`)有利于用户易于复用数据项，例如使用`{"image_a":0, "image_b":0, "label":1}`，或者甚至跳过数据项，例如使用`{"image_a":0, "label":2}`。 + + +### 如何创建一个自定义data reader？ +```python +def image_reader_creator(image_path, label_path, n): + def reader(): + f = open(image_path) + l = open(label_path) + images = numpy.fromfile( + f, 'ubyte', count=n * 28 * 28).reshape((n, 28 * 28)).astype('float32') + images = images / 255.0 * 2.0 - 1.0 + labels = numpy.fromfile(l, 'ubyte', count=n).astype("int") + for i in xrange(n): + yield images[i, :], labels[i] # a single entry of data is created each time + f.close() + l.close() + return reader + +# images_reader_creator创建一个reader +reader = image_reader_creator("/path/to/image_file", "/path/to/label_file", 1024) +paddle.train(paddle.batch(reader, 128), {"image":0, "label":1}, ...) +``` + +### `paddle.train`实现原理 +实现`paddle.train`的示例如下： + +```python +def train(batch_reader, mapping, batch_size, total_pass): + for pass_idx in range(total_pass): + for mini_batch in batch_reader(): # this loop will never end in online learning. + do_forward_backward(mini_batch, mapping) +``` diff --git a/external/Paddle b/external/Paddle index 81b66db96c1b9c16535bf86e6167da911891e9fb..3f687765e6a0e00428588f776d74d5cb114ee227 160000 --- a/external/Paddle +++ b/external/Paddle @@ -1 +1 @@ -Subproject commit 81b66db96c1b9c16535bf86e6167da911891e9fb +Subproject commit 3f687765e6a0e00428588f776d74d5cb114ee227 diff --git a/external/book b/external/book index ef2934505b87eeb516eed7d083900ec88a62fb20..64c82c575ff842eaf02c62e61ec6cce78ecc0f42 160000 --- a/external/book +++ b/external/book @@ -1 +1 @@ -Subproject commit ef2934505b87eeb516eed7d083900ec88a62fb20 +Subproject commit 64c82c575ff842eaf02c62e61ec6cce78ecc0f42