From 8755edded1624a25413919a84bdb8ba7ee79614d Mon Sep 17 00:00:00 2001 From: Cheerego <35982308+shanyi15@users.noreply.github.com> Date: Fri, 7 Dec 2018 10:24:56 +0800 Subject: [PATCH] Update v1.2 Doc (#448) * add_api_cn (#437) * add gpu benchmark page (#436) * add gpu benchmark * fix comments * add chinese link in gen_doc.py (#439) * modified gen_doc.py * Update gen_doc.py * update gen_doc.py * Update mobile doc (#440) * update_en_structure * update_Paddle_commitid * delete_DS * update_mobile_doc * Update book commit (#438) * update_en_structure * update_Paddle_commitid * delete_DS * update_book_commit_id * update_api_rst * Adjust structure of advanced usage (#442) * adjust_structure_of_advanced_usage * Update paddle_gpu_benchmark.md * adjust_toctree_hidden * fix_api_guide * Update index.rst * fix deadlinkes (#443) * add_toctree (#445) * adjust_beginners_structure (#446) * adjust_beginners_structure * Update index.rst * update install_doc for python3 (#418) * update install_doc for python3 * update python3.5+ info,test=develop * fix review, test=develop * fix_pic (#447) --- .../{ => anakin}/anakin_arm_benchmark.md | 0 .../deploy/{ => anakin}/anakin_example.md | 0 .../{ => anakin}/anakin_gpu_benchmark.md | 0 .../{ => anakin}/anakin_parser_design.md | 0 .../deploy/{ => anakin}/anakin_run_on_arm.md | 0 .../deploy/{ => anakin}/anakin_tutorial.md | 0 .../{ => anakin}/convert_paddle_to_anakin.md | 0 .../{ => anakin}/how_to_add_anakin_op.md | 0 .../how_to_support_new_device_in_anakin.md | 0 .../{index_anakin.rst => anakin/index_cn.rst} | 0 .../deploy/{ => anakin}/install_anakin.md | 0 .../deploy/{ => anakin}/run_anakin_on_arm.md | 0 doc/fluid/advanced_usage/deploy/index_cn.rst | 13 + .../advanced_usage/deploy/index_mobile.rst | 8 - .../inference/build_and_install_lib_cn.rst | 0 .../deploy}/inference/image/image1.png | Bin .../deploy}/inference/image/image2.png | Bin .../deploy}/inference/image/image3.png | Bin .../deploy}/inference/image/image4.png | Bin .../deploy}/inference/image/image5.png | Bin .../deploy}/inference/image/image6.png | Bin .../deploy}/inference/image/image7.png | Bin .../deploy}/inference/image/image8.png | Bin .../deploy}/inference/image/image9.png | Bin .../inference/image/model_graph_original.png | Bin .../inference/image/model_graph_trt.png | Bin .../deploy/inference/index_cn.rst} | 5 +- .../deploy}/inference/native_infer.md | 2 +- .../deploy/inference/paddle_gpu_benchmark.md | 48 + .../inference/paddle_tensorrt_infer.md | 2 +- .../inference/windows_cpp_inference.md | 2 +- .../advanced_usage/deploy/mobile/index_cn.rst | 15 + .../deploy/{ => mobile}/mobile_build.md | 2 +- .../deploy/{ => mobile}/mobile_readme.md | 17 +- .../design_idea/fluid_design_idea.md | 8 +- .../design_idea/image/executor_design.png | Bin .../design_idea/image/fluid_process.png | Bin .../contribute_to_paddle/index_cn.rst | 6 +- .../advanced_usage/development/new_op.md | 1 - .../development/new_op/index_cn.rst | 13 + .../development/new_op/new_op_cn.md | 1 + .../development/{ => new_op}/op_notes.md | 8 +- .../development/profiling/index.rst | 10 - .../development/profiling/index_cn.rst | 21 + doc/fluid/advanced_usage/index.rst | 41 +- doc/fluid/api/average.rst | 2 + doc/fluid/api/backward.rst | 2 + doc/fluid/api/clip.rst | 8 + doc/fluid/api/data_feeder.rst | 2 + doc/fluid/api/executor.rst | 14 +- doc/fluid/api/fluid.rst | 66 +- doc/fluid/api/gen_doc.py | 5 + doc/fluid/api/index_cn.rst | 1 - doc/fluid/api/initializer.rst | 32 + doc/fluid/api/io.rst | 16 + doc/fluid/api/layers.rst | 488 + doc/fluid/api/metrics.rst | 18 + doc/fluid/api/nets.rst | 10 + doc/fluid/api/optimizer.rst | 38 + doc/fluid/api/profiler.rst | 10 + doc/fluid/api/recordio_writer.rst | 4 + doc/fluid/api/regularizer.rst | 8 + doc/fluid/api/transpiler.rst | 12 + .../api_cn/api_guides/high_low_level_api.md | 15 + doc/fluid/api_cn/api_guides/index.rst | 18 + .../low_level/distributed/async_training.rst | 33 + .../distributed/cluster_train_data_cn.rst | 64 + .../distributed/cpu_train_best_practice.rst | 58 + .../low_level/distributed/index.rst | 14 + .../large_scale_sparse_feature_training.rst | 42 + .../low_level/distributed/sync_training.rst | 83 + .../api_cn/api_guides/low_level/executor.rst | 20 + .../api_cn/api_guides/low_level/inference.rst | 55 + .../low_level/layers/activations.rst | 28 + .../low_level/layers/control_flow.rst | 53 + .../api_guides/low_level/layers/conv.rst | 64 + .../low_level/layers/data_feeder.rst | 44 + .../low_level/layers/data_in_out.rst | 33 + .../api_guides/low_level/layers/detection.rst | 63 + .../api_guides/low_level/layers/index.rst | 21 + .../layers/learning_rate_scheduler.rst | 40 + .../low_level/layers/loss_function.rst | 60 + .../api_guides/low_level/layers/math.rst | 211 + .../api_guides/low_level/layers/pooling.rst | 80 + .../api_guides/low_level/layers/sequence.rst | 112 + .../low_level/layers/sparse_update.rst | 45 + .../api_guides/low_level/layers/tensor.rst | 149 + .../api_guides/low_level/memory_optimize.rst | 49 + .../api_cn/api_guides/low_level/metrics.rst | 51 + .../low_level/model_save_reader.rst | 59 + .../api_cn/api_guides/low_level/nets.rst | 61 + .../api_cn/api_guides/low_level/optimizer.rst | 92 + .../low_level/parallel_executor.rst | 37 + .../api_cn/api_guides/low_level/parameter.rst | 167 + doc/fluid/api_cn/average_cn.rst | 69 + doc/fluid/api_cn/backward_cn.rst | 90 + doc/fluid/api_cn/clip_cn.rst | 156 + doc/fluid/api_cn/data_feeder_cn.rst | 121 + doc/fluid/api_cn/executor_cn.rst | 111 + doc/fluid/api_cn/fluid_cn.rst | 1550 +++ doc/fluid/api_cn/gen_index.py | 21 + doc/fluid/api_cn/index_cn.rst | 25 + doc/fluid/api_cn/initializer_cn.rst | 355 + doc/fluid/api_cn/io_cn.rst | 345 + doc/fluid/api_cn/layers_cn.rst | 10326 ++++++++++++++++ doc/fluid/api_cn/metrics_cn.rst | 372 + doc/fluid/api_cn/net_cn.rst | 244 + doc/fluid/api_cn/optimizer_cn.rst | 442 + doc/fluid/api_cn/param_attr_cn.rst | 79 + doc/fluid/api_cn/profiler_cn.rst | 196 + doc/fluid/api_cn/regularizer_cn.rst | 72 + doc/fluid/api_cn/transpliter_cn.rst | 244 + doc/fluid/beginners_guide/basics/index.rst | 77 +- doc/fluid/beginners_guide/index.rst | 17 +- .../install/compile/compile_CentOS.md | 35 +- .../install/compile/compile_MacOS.md | 8 +- .../install/compile/compile_Ubuntu.md | 43 +- .../install/compile/fromsource.rst | 4 +- .../install/{Start.rst => index_cn.rst} | 29 +- .../beginners_guide/install/install_CentOS.md | 23 +- .../beginners_guide/install/install_MacOS.md | 12 +- .../beginners_guide/install/install_Ubuntu.md | 39 +- doc/fluid/dev/new_op_cn.md | 2 +- doc/fluid/index_cn.rst | 2 +- .../howto/basic_concept/index_cn.rst | 12 + .../lod_tensor.rst} | 297 +- .../howto/evaluation_and_debugging/index.rst | 2 +- .../user_guides/howto/prepare_data/index.rst | 17 +- .../user_guides/howto/training/index.rst | 2 +- .../user_guides/howto/training/multi_node.rst | 2 +- doc/fluid/user_guides/index.rst | 19 +- external/book | 2 +- 132 files changed, 17949 insertions(+), 393 deletions(-) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_arm_benchmark.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_example.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_gpu_benchmark.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_parser_design.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_run_on_arm.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/anakin_tutorial.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/convert_paddle_to_anakin.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/how_to_add_anakin_op.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/how_to_support_new_device_in_anakin.md (100%) rename doc/fluid/advanced_usage/deploy/{index_anakin.rst => anakin/index_cn.rst} (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/install_anakin.md (100%) rename doc/fluid/advanced_usage/deploy/{ => anakin}/run_anakin_on_arm.md (100%) create mode 100644 doc/fluid/advanced_usage/deploy/index_cn.rst delete mode 100644 doc/fluid/advanced_usage/deploy/index_mobile.rst rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/build_and_install_lib_cn.rst (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image1.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image2.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image3.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image4.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image5.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image6.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image7.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image8.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/image9.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/model_graph_original.png (100%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/image/model_graph_trt.png (100%) rename doc/fluid/{user_guides/howto/inference/index.rst => advanced_usage/deploy/inference/index_cn.rst} (78%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/native_infer.md (99%) create mode 100644 doc/fluid/advanced_usage/deploy/inference/paddle_gpu_benchmark.md rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/paddle_tensorrt_infer.md (99%) rename doc/fluid/{user_guides/howto => advanced_usage/deploy}/inference/windows_cpp_inference.md (98%) create mode 100644 doc/fluid/advanced_usage/deploy/mobile/index_cn.rst rename doc/fluid/advanced_usage/deploy/{ => mobile}/mobile_build.md (95%) rename doc/fluid/advanced_usage/deploy/{ => mobile}/mobile_readme.md (84%) rename doc/fluid/{user_guides => advanced_usage}/design_idea/fluid_design_idea.md (98%) rename doc/fluid/{user_guides => advanced_usage}/design_idea/image/executor_design.png (100%) rename doc/fluid/{user_guides => advanced_usage}/design_idea/image/fluid_process.png (100%) delete mode 120000 doc/fluid/advanced_usage/development/new_op.md create mode 100644 doc/fluid/advanced_usage/development/new_op/index_cn.rst create mode 120000 doc/fluid/advanced_usage/development/new_op/new_op_cn.md rename doc/fluid/advanced_usage/development/{ => new_op}/op_notes.md (98%) delete mode 100644 doc/fluid/advanced_usage/development/profiling/index.rst create mode 100644 doc/fluid/advanced_usage/development/profiling/index_cn.rst create mode 100644 doc/fluid/api_cn/api_guides/high_low_level_api.md create mode 100755 doc/fluid/api_cn/api_guides/index.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/async_training.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/cluster_train_data_cn.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/cpu_train_best_practice.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/index.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/distributed/sync_training.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/executor.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/inference.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/activations.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/conv.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/data_feeder.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/data_in_out.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/detection.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/index.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/learning_rate_scheduler.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/math.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/pooling.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/sequence.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/layers/tensor.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/memory_optimize.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/metrics.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/nets.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/optimizer.rst create mode 100644 doc/fluid/api_cn/api_guides/low_level/parallel_executor.rst create mode 100755 doc/fluid/api_cn/api_guides/low_level/parameter.rst create mode 100644 doc/fluid/api_cn/average_cn.rst create mode 100644 doc/fluid/api_cn/backward_cn.rst create mode 100644 doc/fluid/api_cn/clip_cn.rst create mode 100644 doc/fluid/api_cn/data_feeder_cn.rst create mode 100644 doc/fluid/api_cn/executor_cn.rst create mode 100644 doc/fluid/api_cn/fluid_cn.rst create mode 100644 doc/fluid/api_cn/gen_index.py create mode 100644 doc/fluid/api_cn/index_cn.rst create mode 100644 doc/fluid/api_cn/initializer_cn.rst create mode 100644 doc/fluid/api_cn/io_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn.rst create mode 100644 doc/fluid/api_cn/metrics_cn.rst create mode 100644 doc/fluid/api_cn/net_cn.rst create mode 100644 doc/fluid/api_cn/optimizer_cn.rst create mode 100644 doc/fluid/api_cn/param_attr_cn.rst create mode 100644 doc/fluid/api_cn/profiler_cn.rst create mode 100644 doc/fluid/api_cn/regularizer_cn.rst create mode 100644 doc/fluid/api_cn/transpliter_cn.rst rename doc/fluid/beginners_guide/install/{Start.rst => index_cn.rst} (66%) create mode 100644 doc/fluid/user_guides/howto/basic_concept/index_cn.rst rename doc/fluid/user_guides/howto/{prepare_data/lod_tensor.md => basic_concept/lod_tensor.rst} (56%) diff --git a/doc/fluid/advanced_usage/deploy/anakin_arm_benchmark.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_arm_benchmark.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_arm_benchmark.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_arm_benchmark.md diff --git a/doc/fluid/advanced_usage/deploy/anakin_example.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_example.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_example.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_example.md diff --git a/doc/fluid/advanced_usage/deploy/anakin_gpu_benchmark.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_gpu_benchmark.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_gpu_benchmark.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_gpu_benchmark.md diff --git a/doc/fluid/advanced_usage/deploy/anakin_parser_design.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_parser_design.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_parser_design.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_parser_design.md diff --git a/doc/fluid/advanced_usage/deploy/anakin_run_on_arm.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_run_on_arm.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_run_on_arm.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_run_on_arm.md diff --git a/doc/fluid/advanced_usage/deploy/anakin_tutorial.md b/doc/fluid/advanced_usage/deploy/anakin/anakin_tutorial.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/anakin_tutorial.md rename to doc/fluid/advanced_usage/deploy/anakin/anakin_tutorial.md diff --git a/doc/fluid/advanced_usage/deploy/convert_paddle_to_anakin.md b/doc/fluid/advanced_usage/deploy/anakin/convert_paddle_to_anakin.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/convert_paddle_to_anakin.md rename to doc/fluid/advanced_usage/deploy/anakin/convert_paddle_to_anakin.md diff --git a/doc/fluid/advanced_usage/deploy/how_to_add_anakin_op.md b/doc/fluid/advanced_usage/deploy/anakin/how_to_add_anakin_op.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/how_to_add_anakin_op.md rename to doc/fluid/advanced_usage/deploy/anakin/how_to_add_anakin_op.md diff --git a/doc/fluid/advanced_usage/deploy/how_to_support_new_device_in_anakin.md b/doc/fluid/advanced_usage/deploy/anakin/how_to_support_new_device_in_anakin.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/how_to_support_new_device_in_anakin.md rename to doc/fluid/advanced_usage/deploy/anakin/how_to_support_new_device_in_anakin.md diff --git a/doc/fluid/advanced_usage/deploy/index_anakin.rst b/doc/fluid/advanced_usage/deploy/anakin/index_cn.rst similarity index 100% rename from doc/fluid/advanced_usage/deploy/index_anakin.rst rename to doc/fluid/advanced_usage/deploy/anakin/index_cn.rst diff --git a/doc/fluid/advanced_usage/deploy/install_anakin.md b/doc/fluid/advanced_usage/deploy/anakin/install_anakin.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/install_anakin.md rename to doc/fluid/advanced_usage/deploy/anakin/install_anakin.md diff --git a/doc/fluid/advanced_usage/deploy/run_anakin_on_arm.md b/doc/fluid/advanced_usage/deploy/anakin/run_anakin_on_arm.md similarity index 100% rename from doc/fluid/advanced_usage/deploy/run_anakin_on_arm.md rename to doc/fluid/advanced_usage/deploy/anakin/run_anakin_on_arm.md diff --git a/doc/fluid/advanced_usage/deploy/index_cn.rst b/doc/fluid/advanced_usage/deploy/index_cn.rst new file mode 100644 index 0000000000000..6be367358338d --- /dev/null +++ b/doc/fluid/advanced_usage/deploy/index_cn.rst @@ -0,0 +1,13 @@ +######## +预测部署 +######## + +- `原生预测引擎 `_ ：介绍了支持模型部署上线的Fluid C++ API + +- `移动端部署 `_：介绍了 PaddlePaddle组织下的嵌入式平台深度学习框架Paddle-Mobile + +.. toctree:: + :hidden: + + inference/index_cn.rst + mobile/index_cn.rst diff --git a/doc/fluid/advanced_usage/deploy/index_mobile.rst b/doc/fluid/advanced_usage/deploy/index_mobile.rst deleted file mode 100644 index c7a338d9be2b5..0000000000000 --- a/doc/fluid/advanced_usage/deploy/index_mobile.rst +++ /dev/null @@ -1,8 +0,0 @@ -移动端部署 -########## - -.. toctree:: - :maxdepth: 2 - - mobile_readme.md - mobile_build.md diff --git a/doc/fluid/user_guides/howto/inference/build_and_install_lib_cn.rst b/doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst similarity index 100% rename from doc/fluid/user_guides/howto/inference/build_and_install_lib_cn.rst rename to doc/fluid/advanced_usage/deploy/inference/build_and_install_lib_cn.rst diff --git a/doc/fluid/user_guides/howto/inference/image/image1.png b/doc/fluid/advanced_usage/deploy/inference/image/image1.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image1.png rename to doc/fluid/advanced_usage/deploy/inference/image/image1.png diff --git a/doc/fluid/user_guides/howto/inference/image/image2.png b/doc/fluid/advanced_usage/deploy/inference/image/image2.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image2.png rename to doc/fluid/advanced_usage/deploy/inference/image/image2.png diff --git a/doc/fluid/user_guides/howto/inference/image/image3.png b/doc/fluid/advanced_usage/deploy/inference/image/image3.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image3.png rename to doc/fluid/advanced_usage/deploy/inference/image/image3.png diff --git a/doc/fluid/user_guides/howto/inference/image/image4.png b/doc/fluid/advanced_usage/deploy/inference/image/image4.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image4.png rename to doc/fluid/advanced_usage/deploy/inference/image/image4.png diff --git a/doc/fluid/user_guides/howto/inference/image/image5.png b/doc/fluid/advanced_usage/deploy/inference/image/image5.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image5.png rename to doc/fluid/advanced_usage/deploy/inference/image/image5.png diff --git a/doc/fluid/user_guides/howto/inference/image/image6.png b/doc/fluid/advanced_usage/deploy/inference/image/image6.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image6.png rename to doc/fluid/advanced_usage/deploy/inference/image/image6.png diff --git a/doc/fluid/user_guides/howto/inference/image/image7.png b/doc/fluid/advanced_usage/deploy/inference/image/image7.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image7.png rename to doc/fluid/advanced_usage/deploy/inference/image/image7.png diff --git a/doc/fluid/user_guides/howto/inference/image/image8.png b/doc/fluid/advanced_usage/deploy/inference/image/image8.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image8.png rename to doc/fluid/advanced_usage/deploy/inference/image/image8.png diff --git a/doc/fluid/user_guides/howto/inference/image/image9.png b/doc/fluid/advanced_usage/deploy/inference/image/image9.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/image9.png rename to doc/fluid/advanced_usage/deploy/inference/image/image9.png diff --git a/doc/fluid/user_guides/howto/inference/image/model_graph_original.png b/doc/fluid/advanced_usage/deploy/inference/image/model_graph_original.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/model_graph_original.png rename to doc/fluid/advanced_usage/deploy/inference/image/model_graph_original.png diff --git a/doc/fluid/user_guides/howto/inference/image/model_graph_trt.png b/doc/fluid/advanced_usage/deploy/inference/image/model_graph_trt.png similarity index 100% rename from doc/fluid/user_guides/howto/inference/image/model_graph_trt.png rename to doc/fluid/advanced_usage/deploy/inference/image/model_graph_trt.png diff --git a/doc/fluid/user_guides/howto/inference/index.rst b/doc/fluid/advanced_usage/deploy/inference/index_cn.rst similarity index 78% rename from doc/fluid/user_guides/howto/inference/index.rst rename to doc/fluid/advanced_usage/deploy/inference/index_cn.rst index 1e572b2d4df70..7f7a0a1020613 100644 --- a/doc/fluid/user_guides/howto/inference/index.rst +++ b/doc/fluid/advanced_usage/deploy/inference/index_cn.rst @@ -1,13 +1,14 @@ ############ -预测部署 +原生预测引擎 ############ PaddlePaddle Fluid 提供了 C++ API 来支持模型的部署上线 .. toctree:: - :maxdepth: 2 + :hidden: build_and_install_lib_cn.rst native_infer.md paddle_tensorrt_infer.md + paddle_gpu_benchmark.md windows_cpp_inference.md diff --git a/doc/fluid/user_guides/howto/inference/native_infer.md b/doc/fluid/advanced_usage/deploy/inference/native_infer.md similarity index 99% rename from doc/fluid/user_guides/howto/inference/native_infer.md rename to doc/fluid/advanced_usage/deploy/inference/native_infer.md index fc3a3879c0b4e..3317ac283360c 100644 --- a/doc/fluid/user_guides/howto/inference/native_infer.md +++ b/doc/fluid/advanced_usage/deploy/inference/native_infer.md @@ -1,4 +1,4 @@ -# Paddle 预测 API +# C++ 预测 API介绍 为了更简单方便的预测部署，Fluid 提供了一套高层 API 用来隐藏底层不同的优化实现。 diff --git a/doc/fluid/advanced_usage/deploy/inference/paddle_gpu_benchmark.md b/doc/fluid/advanced_usage/deploy/inference/paddle_gpu_benchmark.md new file mode 100644 index 0000000000000..c5b746290f7d4 --- /dev/null +++ b/doc/fluid/advanced_usage/deploy/inference/paddle_gpu_benchmark.md @@ -0,0 +1,48 @@ +# TensorRT库性能测试 + +## 测试环境 +- CPU:Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz GPU:Tesla P4 +- TensorRT4.0, CUDA8.0, CUDNNV7 +- 测试模型 ResNet50，MobileNet，ResNet101, Inception V3. + +## 测试对象 +**PaddlePaddle, Pytorch, Tensorflow** + +- 在测试中，PaddlePaddle使用子图优化的方式集成了TensorRT, 模型[地址](https://github.com/PaddlePaddle/models/tree/develop/fluid/PaddleCV/image_classification/models)。 +- Pytorch使用了原生的实现, 模型[地址1](https://github.com/pytorch/vision/tree/master/torchvision/models)、[地址2](https://github.com/marvis/pytorch-mobilenet)。 +- 对TensorFlow测试包括了对TF的原生的测试，和对TF—TRT的测试，**对TF—TRT的测试并没有达到预期的效果，后期会对其进行补充**， 模型[地址](https://github.com/tensorflow/models)。 + + +### ResNet50 + +|batch_size|PaddlePaddle(ms)|Pytorch(ms)|TensorFlow(ms)| +|---|---|---|---| +|1|4.64117 |16.3|10.878| +|5|6.90622| 22.9 |20.62| +|10|7.9758 |40.6|34.36| + +### MobileNet +|batch_size|PaddlePaddle(ms)|Pytorch(ms)|TensorFlow(ms)| +|---|---|---|---| +|1| 1.7541 | 7.8 |2.72| +|5| 3.04666 | 7.8 |3.19| +|10|4.19478 | 14.47 |4.25| + +### ResNet101 +|batch_size|PaddlePaddle(ms)|Pytorch(ms)|TensorFlow(ms)| +|---|---|---|---| +|1|8.95767| 22.48 |18.78| +|5|12.9811 | 33.88 |34.84| +|10|14.1463| 61.97 |57.94| + + +### Inception v3 +|batch_size|PaddlePaddle(ms)|Pytorch(ms)|TensorFlow(ms)| +|---|---|---|---| +|1|15.1613 | 24.2 |19.1| +|5|18.5373 | 34.8 |27.2| +|10|19.2781| 54.8 |36.7| + + + + diff --git a/doc/fluid/user_guides/howto/inference/paddle_tensorrt_infer.md b/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md similarity index 99% rename from doc/fluid/user_guides/howto/inference/paddle_tensorrt_infer.md rename to doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md index 2803e4578a048..8a98954bfc844 100644 --- a/doc/fluid/user_guides/howto/inference/paddle_tensorrt_infer.md +++ b/doc/fluid/advanced_usage/deploy/inference/paddle_tensorrt_infer.md @@ -1,4 +1,4 @@ -# 使用Paddle TensorRT预测 +# 使用TensorRT库预测 NVIDIA TensorRT 是一个高性能的深度学习预测库，可为深度学习推理应用程序提供低延迟和高吞吐量。Paddle 1.0 采用了子图的形式对TensorRT进行了初步集成，即我们可以使用该模块来提升Paddle模型的预测性能。该模块依旧在持续开发中，目前已支持的模型有：AlexNet, MobileNet, ResNet50, VGG19, ResNext, Se-ReNext, GoogleNet, DPN, ICNET, MobileNet-SSD等。在这篇文档中，我们将会对Paddle-TensorRT库的获取、使用和原理进行介绍。 diff --git a/doc/fluid/user_guides/howto/inference/windows_cpp_inference.md b/doc/fluid/advanced_usage/deploy/inference/windows_cpp_inference.md similarity index 98% rename from doc/fluid/user_guides/howto/inference/windows_cpp_inference.md rename to doc/fluid/advanced_usage/deploy/inference/windows_cpp_inference.md index f2642b46221c7..b6a5a2168be98 100644 --- a/doc/fluid/user_guides/howto/inference/windows_cpp_inference.md +++ b/doc/fluid/advanced_usage/deploy/inference/windows_cpp_inference.md @@ -1,4 +1,4 @@ -Windows环境模型预测使用说明 +Windows环境模型预测 =========================== 环境部署 diff --git a/doc/fluid/advanced_usage/deploy/mobile/index_cn.rst b/doc/fluid/advanced_usage/deploy/mobile/index_cn.rst new file mode 100644 index 0000000000000..4e9fc9e91ad6a --- /dev/null +++ b/doc/fluid/advanced_usage/deploy/mobile/index_cn.rst @@ -0,0 +1,15 @@ +########## +移动端部署 +########## + +本模块介绍了 PaddlePaddle 组织下的嵌入式平台深度学习框架——Paddle-Mobile，包括： + +* `项目简介 `_：简要介绍了 Paddle-Mobile 的应用效果，特点以及使用说明 + +* `环境搭建 `_：分别介绍如何在Docker和非Docker下搭建环境 + +.. toctree:: + :hidden: + + mobile_readme.md + mobile_build.md diff --git a/doc/fluid/advanced_usage/deploy/mobile_build.md b/doc/fluid/advanced_usage/deploy/mobile/mobile_build.md similarity index 95% rename from doc/fluid/advanced_usage/deploy/mobile_build.md rename to doc/fluid/advanced_usage/deploy/mobile/mobile_build.md index e51593164987d..8f538d04c790a 100644 --- a/doc/fluid/advanced_usage/deploy/mobile_build.md +++ b/doc/fluid/advanced_usage/deploy/mobile/mobile_build.md @@ -1,7 +1,7 @@ # 环境搭建 ## 使用 docker ### 1. 安装 docker -安装 docker 的方式，参考官方文档 [https://docs.docker.com/install/](https://docs.docker.com/install/) +安装 docker 的方式，参考 [官方文档](https://docs.docker.com/install/) ### 2. 使用 docker 搭建构建环境 首先进入 paddle-mobile 的目录下，执行 `docker build` 以 Linux/Mac 为例 (windows 建议在 'Docker Quickstart Terminal' 中执行) diff --git a/doc/fluid/advanced_usage/deploy/mobile_readme.md b/doc/fluid/advanced_usage/deploy/mobile/mobile_readme.md similarity index 84% rename from doc/fluid/advanced_usage/deploy/mobile_readme.md rename to doc/fluid/advanced_usage/deploy/mobile/mobile_readme.md index 10fde9c70b16e..7f4144ac32792 100644 --- a/doc/fluid/advanced_usage/deploy/mobile_readme.md +++ b/doc/fluid/advanced_usage/deploy/mobile/mobile_readme.md @@ -33,13 +33,11 @@ 开发文档主要是关于编译、运行等问题。作为开发者，它可以和贡献文档共同结合使用 -[iOS](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_ios.md) - -[Android](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_android.md) - -[FPGA](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_fpga.md) - -[ARM_LINUX](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_arm_linux.md) +* [iOS](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_ios.md) +* [Android_CPU](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_android.md) +* [Android_GPU](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_android_GPU.md) +* [FPGA](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_fpga.md) +* [ARM_LINUX](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/doc/development_arm_linux.md) ### 贡献代码 @@ -71,10 +69,6 @@ ONNX全称为“Open Neural Network Exchange”，即“开放的神经网络切 [下载链接](http://mms-graph.bj.bcebos.com/paddle-mobile%2FmodelsAndImages.zip) -如下gif是简单搜索app的线上主体检测应用效果 - -![ezgif-1-050a733dfb](http://otkwwi4x8.bkt.clouddn.com/2018-07-05-ezgif-1-050a733dfb.gif) - ## 问题解决 欢迎提出或解决我们的问题，有疑问可以发[Issue](https://github.com/PaddlePaddle/paddle-mobile/issues) @@ -85,3 +79,4 @@ Paddle-Mobile 提供相对宽松的Apache-2.0开源协议 [Apache-2.0 license](L ## 旧版 Mobile-Deep-Learning 原MDL(Mobile-Deep-Learning)工程被迁移到了这里 [Mobile-Deep-Learning](https://github.com/allonli/mobile-deep-learning) + diff --git a/doc/fluid/user_guides/design_idea/fluid_design_idea.md b/doc/fluid/advanced_usage/design_idea/fluid_design_idea.md similarity index 98% rename from doc/fluid/user_guides/design_idea/fluid_design_idea.md rename to doc/fluid/advanced_usage/design_idea/fluid_design_idea.md index 4b469ca3ac4b7..9fbcd8ac62433 100644 --- a/doc/fluid/user_guides/design_idea/fluid_design_idea.md +++ b/doc/fluid/advanced_usage/design_idea/fluid_design_idea.md @@ -1,4 +1,4 @@ -# Fluid设计思想 +# 设计思想 ## 简介 @@ -17,7 +17,7 @@ Fluid使用一种编译器式的执行流程，分为编译时和运行时两个 本地训练任务执行流程图如下所示：

- +

1. 编译时，用户编写一段python程序，通过调用 Fluid 提供的算子，向一段 Program 中添加变量（Tensor）以及对变量的操作（Operators 或者 Layers）。用户只需要描述核心的前向计算，不需要关心反向计算、分布式下以及异构设备下如何计算。 @@ -153,7 +153,7 @@ Executor 在运行时将接受一个`ProgramDesc`、一个`block_id`和一个`Sc 完成的编译执行的具体过程如下图所示：

- +

1. Executor 为每一个block创建一个Scope，Block是可嵌套的，因此Scope也是可嵌套的 @@ -359,5 +359,5 @@ Fluid使用Executor.run来运行一段Program。 [6.099215 ]], dtype=float32), array([1.6935859], dtype=float32)] ``` -至此您已经了解了Fluid 内部的执行流程的核心概念，更多框架使用细节请参考[使用指南](../../user_guides/index.html)相关内容，[模型库](../../user_guides/models/index.html +至此您已经了解了Fluid 内部的执行流程的核心概念，更多框架使用细节请参考[使用指南](../../user_guides/index.html)相关内容，[模型库](../../user_guides/models/index_cn.html )中也为您提供了丰富的模型示例以供参考。 diff --git a/doc/fluid/user_guides/design_idea/image/executor_design.png b/doc/fluid/advanced_usage/design_idea/image/executor_design.png similarity index 100% rename from doc/fluid/user_guides/design_idea/image/executor_design.png rename to doc/fluid/advanced_usage/design_idea/image/executor_design.png diff --git a/doc/fluid/user_guides/design_idea/image/fluid_process.png b/doc/fluid/advanced_usage/design_idea/image/fluid_process.png similarity index 100% rename from doc/fluid/user_guides/design_idea/image/fluid_process.png rename to doc/fluid/advanced_usage/design_idea/image/fluid_process.png diff --git a/doc/fluid/advanced_usage/development/contribute_to_paddle/index_cn.rst b/doc/fluid/advanced_usage/development/contribute_to_paddle/index_cn.rst index a46fd00e66bbd..a2cb0b18d9f3e 100644 --- a/doc/fluid/advanced_usage/development/contribute_to_paddle/index_cn.rst +++ b/doc/fluid/advanced_usage/development/contribute_to_paddle/index_cn.rst @@ -1,9 +1,9 @@ -######## +############ 如何贡献代码 -######## +############ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 local_dev_guide.md submit_pr_guide.md diff --git a/doc/fluid/advanced_usage/development/new_op.md b/doc/fluid/advanced_usage/development/new_op.md deleted file mode 120000 index a2b0044b01385..0000000000000 --- a/doc/fluid/advanced_usage/development/new_op.md +++ /dev/null @@ -1 +0,0 @@ -../../dev/new_op_cn.md \ No newline at end of file diff --git a/doc/fluid/advanced_usage/development/new_op/index_cn.rst b/doc/fluid/advanced_usage/development/new_op/index_cn.rst new file mode 100644 index 0000000000000..5b9a20b57bb24 --- /dev/null +++ b/doc/fluid/advanced_usage/development/new_op/index_cn.rst @@ -0,0 +1,13 @@ +############# +新增operator +############# + +- `如何写新的operator <../../../advanced_usage/development/new_op.html>`_ ：介绍如何在 Fluid 中添加新的 Operator + +- `op相关的一些注意事项 <../../../advanced_usage/development/op_notes.html>`_ ：介绍op相关的一些注意事项 + +.. toctree:: + :hidden: + + new_op_cn.md + op_notes.md diff --git a/doc/fluid/advanced_usage/development/new_op/new_op_cn.md b/doc/fluid/advanced_usage/development/new_op/new_op_cn.md new file mode 120000 index 0000000000000..dce0348585b8c --- /dev/null +++ b/doc/fluid/advanced_usage/development/new_op/new_op_cn.md @@ -0,0 +1 @@ +../../../dev/new_op_cn.md \ No newline at end of file diff --git a/doc/fluid/advanced_usage/development/op_notes.md b/doc/fluid/advanced_usage/development/new_op/op_notes.md similarity index 98% rename from doc/fluid/advanced_usage/development/op_notes.md rename to doc/fluid/advanced_usage/development/new_op/op_notes.md index 09c8bc0085220..03e4f2ad0223a 100644 --- a/doc/fluid/advanced_usage/development/op_notes.md +++ b/doc/fluid/advanced_usage/development/new_op/op_notes.md @@ -1,4 +1,4 @@ -# Op相关的一些注意事项 +# op相关的一些注意事项 ## Fluid中Op的构建逻辑 ### 1.Fluid中Op的构建逻辑 @@ -9,7 +9,7 @@ Op的核心方法是Run，Run方法需要两方面的资源：数据资源和计 Fluid框架的设计理念是可以在多种设备及第三方库上运行，有些Op的实现可能会因为设备或者第三方库的不同而不同。为此，Fluid引入了OpKernel的方式，即一个Op可以有多个OpKernel，这类Op继承自`OperatorWithKernel`，这类Op的代表是conv，conv_op的OpKerne有：`GemmConvKernel`、`CUDNNConvOpKernel`、`ConvMKLDNNOpKernel`，且每个OpKernel都有double和float两种数据类型。不需要OpKernel的代表有`WhileOp`等。 Operator继承关系图： -![op_inheritance_relation_diagram](../pics/op_inheritance_relation_diagram.png) +![op_inheritance_relation_diagram](../../pics/op_inheritance_relation_diagram.png) 进一步了解可参考：[multi_devices](https://github.com/PaddlePaddle/FluidDoc/tree/develop/doc/fluid/design/multi_devices)，[scope](https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/design/concepts/scope.md)，[Developer's_Guide_to_Paddle_Fluid](https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/getstarted/Developer's_Guide_to_Paddle_Fluid.md) @@ -92,7 +92,7 @@ Operator继承关系图： 5. 框架没有提供默认的op_infer_var_type方法，用户需要根据实际情况添加op_infer_var_shape。严格来说每个Op都应该注册一个InferVarType，op_infer_var_type根据输入的Var的type和dtype推断输出Var的type和dtype。**注意：**在Python端的LayerHelper中create_variable_for_type_inference操作返回的Variable里面是LoDTensor，C++端的InferVarType可以修改`Variable`的type和dtype。 -更多内容请参考: [如何写新的Op](./new_op.html) +更多内容请参考: [如何写新的Op](../new_op.html) ## 写Op注意事项 ### 1.Op可以支持输入输出类型 @@ -183,4 +183,4 @@ def fc(input, act=None, is_test=False, name=None) -``` \ No newline at end of file +``` diff --git a/doc/fluid/advanced_usage/development/profiling/index.rst b/doc/fluid/advanced_usage/development/profiling/index.rst deleted file mode 100644 index 1d2eedc439d94..0000000000000 --- a/doc/fluid/advanced_usage/development/profiling/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -########## -性能调优 -########## -.. toctree:: - - benchmark.rst - cpu_profiling_cn.md - gpu_profiling_cn.rst - host_memory_profiling_cn.md - timeline_cn.md diff --git a/doc/fluid/advanced_usage/development/profiling/index_cn.rst b/doc/fluid/advanced_usage/development/profiling/index_cn.rst new file mode 100644 index 0000000000000..7baf05134332e --- /dev/null +++ b/doc/fluid/advanced_usage/development/profiling/index_cn.rst @@ -0,0 +1,21 @@ +########## +性能调优 +########## + +本模块介绍 Fluid 使用过程中的调优方法，包括： + +- `如何进行基准测试 `_：介绍如何选择基准模型，从而验证模型的精度和性能 +- `CPU性能调优 `_：介绍如何使用 cProfile 包、yep库、Google perftools 进行性能分析与调优 +- `GPU性能调优 `_：介绍如何使用 Fluid 内置的定时工具、nvprof 或 nvvp 进行性能分析和调优 +- `堆内存分析和优化 `_：介绍如何使用 gperftool 进行堆内存分析和优化，以解决内存泄漏的问题 +- `Timeline工具简介 `_ ：介绍如何使用 Timeline 工具进行性能分析和调优 + + +.. toctree:: + :hidden: + + benchmark.rst + cpu_profiling_cn.md + gpu_profiling_cn.rst + host_memory_profiling_cn.md + timeline_cn.md diff --git a/doc/fluid/advanced_usage/index.rst b/doc/fluid/advanced_usage/index.rst index 817cd76330167..795547fbd5b1e 100644 --- a/doc/fluid/advanced_usage/index.rst +++ b/doc/fluid/advanced_usage/index.rst @@ -2,51 +2,30 @@ 进阶使用 ######## -===================== - 概览 -===================== .. todo:: 如果您非常熟悉 Fluid，期望获得更高效的模型或者定义自己的Operator，请阅读： - - `移动端部署 <../advanced_usage/deploy/index_mobile.html>`_：介绍了 PaddlePaddle 组织下的嵌入式平台深度学习框架——Paddle-Mobile，包括： + - `Fluid 设计思想 <../advanced_usage/design_idea/fluid_design_idea.html>`_：介绍 Fluid 底层的设计思想，帮助您更好的理解框架运作过程 - - `简介 <../advanced_usage/deploy/mobile_readme.html>`_：简要介绍了 Paddle-Mobile 的应用效果，特点以及使用说明 - - `环境搭建 <../advanced_usage/deploy/mobile_build.html>`_：从使用 Docker 和不使用 Docker 两种方法下分别介绍如何搭建环境 - - `ios开发文档 <../advanced_usage/deploy/mobile_dev.html>`_：介绍如何在 ios 系统下运用 Paddle-Mobile 进行开发 + - `预测部署 <../advanced_usage/deploy/index_cn.html>`_ ：介绍如何应用训练好的模型进行预测 - - `Anakin预测引擎 <../advanced_usage/deploy/index_anakin.html>`_：介绍如何使用 Anakin 在不同硬件平台实现深度学习的高速预测 - - - `如何写新的Operator <../advanced_usage/development/new_op.html>`_ ：介绍如何在 Fluid 中添加新的 Operator - - - `Op相关的一些注意事项 <../advanced_usage/development/op_notes.html>`_ ：介绍Op相关的一些注意事项 - - - `性能调优 <../advanced_usage/development/profiling/index.html>`_ ：介绍 Fluid 使用过程中的调优方法，包括： - - - `如何进行基准测试 <../advanced_usage/development/profiling/benchmark.html>`_：介绍如何选择基准模型，从而验证模型的精度和性能 - - `CPU性能调优 <../advanced_usage/development/profiling/cpu_profiling_cn.html>`_：介绍如何使用 cProfile 包、yep库、Google perftools 进行性能分析与调优 - - `GPU性能调优 <../advanced_usage/development/profiling/gpu_profiling_cn.html>`_：介绍如何使用 Fluid 内置的定时工具、nvprof 或 nvvp 进行性能分析和调优 - - `堆内存分析和优化 <../advanced_usage/development/profiling/host_memory_profiling_cn.html>`_：介绍如何使用 gperftool 进行堆内存分析和优化，以解决内存泄漏的问题 - - `Timeline工具简介 <../advanced_usage/development/profiling/timeline_cn.html>`_ ：介绍如何使用 Timeline 工具进行性能分析和调优 + - `新增operator <../advanced_usage/development/new_op/index_cn.html>`_ ：介绍新增operator的方法及注意事项 + - `性能调优 <../advanced_usage/development/profiling/index.html>`_ ：介绍 Fluid 使用过程中的调优方法 非常欢迎您为我们的开源社区做出贡献，关于如何贡献您的代码或文档，请阅读： - - `如何贡献代码 <../advanced_usage/development/contribute_to_paddle.html>`_：介绍如何向 PaddlePaddle 开源社区贡献代码 + - `如何贡献代码 <../advanced_usage/development/contribute_to_paddle/index_cn.html>`_：介绍如何向 PaddlePaddle 开源社区贡献代码 - `如何贡献文档 <../advanced_usage/development/write_docs_cn.html>`_：介绍如何向 PaddlePaddle 开源社区贡献文档 -===================== - 目录 -===================== - .. toctree:: - :maxdepth: 2 + :hidden: - deploy/index_mobile.rst - deploy/index_anakin.rst + design_idea/fluid_design_idea.md + deploy/index_cn.rst + development/new_op/index_cn.rst + development/profiling/index_cn.rst development/contribute_to_paddle/index_cn.rst development/write_docs_cn.md - development/new_op.md - development/op_notes.md - development/profiling/index.rst diff --git a/doc/fluid/api/average.rst b/doc/fluid/api/average.rst index 496f5b2987544..b91bfcfb6e36e 100644 --- a/doc/fluid/api/average.rst +++ b/doc/fluid/api/average.rst @@ -14,3 +14,5 @@ WeightedAverage :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_average_WeightedAverage` + diff --git a/doc/fluid/api/backward.rst b/doc/fluid/api/backward.rst index 0076394543c2f..b18a0d796240a 100644 --- a/doc/fluid/api/backward.rst +++ b/doc/fluid/api/backward.rst @@ -13,3 +13,5 @@ append_backward .. autofunction:: paddle.fluid.backward.append_backward :noindex: +Read Chinese Version: :ref:`cn_api_fluid_backward_append_backward` + diff --git a/doc/fluid/api/clip.rst b/doc/fluid/api/clip.rst index 8597d40ca4e6a..7c26323414d7f 100644 --- a/doc/fluid/api/clip.rst +++ b/doc/fluid/api/clip.rst @@ -14,6 +14,8 @@ ErrorClipByValue :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_clip_ErrorClipByValue` + .. _api_fluid_clip_GradientClipByGlobalNorm: GradientClipByGlobalNorm @@ -23,6 +25,8 @@ GradientClipByGlobalNorm :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` + .. _api_fluid_clip_GradientClipByNorm: GradientClipByNorm @@ -32,6 +36,8 @@ GradientClipByNorm :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_clip_GradientClipByNorm` + .. _api_fluid_clip_GradientClipByValue: GradientClipByValue @@ -41,3 +47,5 @@ GradientClipByValue :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_clip_GradientClipByValue` + diff --git a/doc/fluid/api/data_feeder.rst b/doc/fluid/api/data_feeder.rst index 11d2890f5b344..6ea67e62ffceb 100644 --- a/doc/fluid/api/data_feeder.rst +++ b/doc/fluid/api/data_feeder.rst @@ -14,3 +14,5 @@ DataFeeder :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_data_feeder_DataFeeder` + diff --git a/doc/fluid/api/executor.rst b/doc/fluid/api/executor.rst index eab798b3d6866..143f9794c85d3 100644 --- a/doc/fluid/api/executor.rst +++ b/doc/fluid/api/executor.rst @@ -5,14 +5,6 @@ fluid.executor ============== -.. _api_fluid_executor__switch_scope: - -_switch_scope -------------- - -.. autofunction:: paddle.fluid.executor._switch_scope - :noindex: - .. _api_fluid_executor_Executor: Executor @@ -22,6 +14,8 @@ Executor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_executor_Executor` + .. _api_fluid_executor_global_scope: global_scope @@ -30,6 +24,8 @@ global_scope .. autofunction:: paddle.fluid.executor.global_scope :noindex: +Read Chinese Version: :ref:`cn_api_fluid_executor_global_scope` + .. _api_fluid_executor_scope_guard: scope_guard @@ -38,3 +34,5 @@ scope_guard .. autofunction:: paddle.fluid.executor.scope_guard :noindex: +Read Chinese Version: :ref:`cn_api_fluid_executor_scope_guard` + diff --git a/doc/fluid/api/fluid.rst b/doc/fluid/api/fluid.rst index e3651ee2a0d42..fc5aaa802270f 100644 --- a/doc/fluid/api/fluid.rst +++ b/doc/fluid/api/fluid.rst @@ -5,14 +5,6 @@ fluid ===== -.. _api_fluid__switch_scope: - -_switch_scope -------------- - -.. autofunction:: paddle.fluid._switch_scope - :noindex: - .. _api_fluid_AsyncExecutor: AsyncExecutor @@ -22,6 +14,8 @@ AsyncExecutor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_AsyncExecutor` + .. _api_fluid_BuildStrategy: BuildStrategy @@ -31,6 +25,8 @@ BuildStrategy :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_BuildStrategy` + .. _api_fluid_CPUPlace: CPUPlace @@ -40,6 +36,8 @@ CPUPlace :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_CPUPlace` + .. _api_fluid_create_lod_tensor: create_lod_tensor @@ -48,6 +46,8 @@ create_lod_tensor .. autofunction:: paddle.fluid.create_lod_tensor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_create_lod_tensor` + .. _api_fluid_create_random_int_lodtensor: create_random_int_lodtensor @@ -56,6 +56,8 @@ create_random_int_lodtensor .. autofunction:: paddle.fluid.create_random_int_lodtensor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_create_random_int_lodtensor` + .. _api_fluid_CUDAPinnedPlace: CUDAPinnedPlace @@ -65,6 +67,8 @@ CUDAPinnedPlace :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_CUDAPinnedPlace` + .. _api_fluid_CUDAPlace: CUDAPlace @@ -74,6 +78,8 @@ CUDAPlace :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_CUDAPlace` + .. _api_fluid_DataFeedDesc: DataFeedDesc @@ -83,6 +89,8 @@ DataFeedDesc :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_DataFeedDesc` + .. _api_fluid_DataFeeder: DataFeeder @@ -92,6 +100,8 @@ DataFeeder :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_DataFeeder` + .. _api_fluid_default_main_program: default_main_program @@ -100,6 +110,8 @@ default_main_program .. autofunction:: paddle.fluid.default_main_program :noindex: +Read Chinese Version: :ref:`cn_api_fluid_default_main_program` + .. _api_fluid_default_startup_program: default_startup_program @@ -108,6 +120,8 @@ default_startup_program .. autofunction:: paddle.fluid.default_startup_program :noindex: +Read Chinese Version: :ref:`cn_api_fluid_default_startup_program` + .. _api_fluid_DistributeTranspiler: DistributeTranspiler @@ -117,6 +131,8 @@ DistributeTranspiler :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_DistributeTranspiler` + .. _api_fluid_DistributeTranspilerConfig: DistributeTranspilerConfig @@ -126,6 +142,8 @@ DistributeTranspilerConfig :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_DistributeTranspilerConfig` + .. _api_fluid_ExecutionStrategy: ExecutionStrategy @@ -135,6 +153,8 @@ ExecutionStrategy :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_ExecutionStrategy` + .. _api_fluid_Executor: Executor @@ -144,6 +164,8 @@ Executor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_Executor` + .. _api_fluid_global_scope: global_scope @@ -152,6 +174,8 @@ global_scope .. autofunction:: paddle.fluid.global_scope :noindex: +Read Chinese Version: :ref:`cn_api_fluid_global_scope` + .. _api_fluid_LoDTensor: LoDTensor @@ -161,6 +185,8 @@ LoDTensor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_LoDTensor` + .. _api_fluid_LoDTensorArray: LoDTensorArray @@ -170,6 +196,8 @@ LoDTensorArray :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_LoDTensorArray` + .. _api_fluid_memory_optimize: memory_optimize @@ -178,6 +206,8 @@ memory_optimize .. autofunction:: paddle.fluid.memory_optimize :noindex: +Read Chinese Version: :ref:`cn_api_fluid_memory_optimize` + .. _api_fluid_name_scope: name_scope @@ -186,6 +216,8 @@ name_scope .. autofunction:: paddle.fluid.name_scope :noindex: +Read Chinese Version: :ref:`cn_api_fluid_name_scope` + .. _api_fluid_ParallelExecutor: ParallelExecutor @@ -195,6 +227,8 @@ ParallelExecutor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_ParallelExecutor` + .. _api_fluid_ParamAttr: ParamAttr @@ -204,6 +238,8 @@ ParamAttr :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_ParamAttr` + .. _api_fluid_Program: Program @@ -213,6 +249,8 @@ Program :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_Program` + .. _api_fluid_program_guard: program_guard @@ -221,6 +259,8 @@ program_guard .. autofunction:: paddle.fluid.program_guard :noindex: +Read Chinese Version: :ref:`cn_api_fluid_program_guard` + .. _api_fluid_release_memory: release_memory @@ -229,6 +269,8 @@ release_memory .. autofunction:: paddle.fluid.release_memory :noindex: +Read Chinese Version: :ref:`cn_api_fluid_release_memory` + .. _api_fluid_Scope: Scope @@ -238,6 +280,8 @@ Scope :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_Scope` + .. _api_fluid_scope_guard: scope_guard @@ -246,6 +290,8 @@ scope_guard .. autofunction:: paddle.fluid.scope_guard :noindex: +Read Chinese Version: :ref:`cn_api_fluid_scope_guard` + .. _api_fluid_Tensor: Tensor @@ -255,6 +301,8 @@ Tensor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_Tensor` + .. _api_fluid_WeightNormParamAttr: WeightNormParamAttr @@ -264,3 +312,5 @@ WeightNormParamAttr :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_WeightNormParamAttr` + diff --git a/doc/fluid/api/gen_doc.py b/doc/fluid/api/gen_doc.py index 2b9979a9f1a62..3c910360a3daa 100644 --- a/doc/fluid/api/gen_doc.py +++ b/doc/fluid/api/gen_doc.py @@ -86,6 +86,7 @@ def print_class(self, name): :noindex: '''.format(self.module_name, name)) + self._print_cn_ref(name) def print_method(self, name): self._print_ref_(name) @@ -94,6 +95,7 @@ def print_method(self, name): :noindex: '''.format(self.module_name, name)) + self._print_cn_ref(name) def _print_header_(self, name, dot, is_title): dot_line = dot * len(name) @@ -109,6 +111,9 @@ def _print_header_(self, name, dot, is_title): def _print_ref_(self, name): self.stream.write(".. _api_{0}_{1}:\n\n".format("_".join( self.module_name.split(".")), name)) + def _print_cn_ref(self, name): + self.stream.write("Read Chinese Version: :ref:`cn_api_{0}_{1}`\n\n".format("_".join( + self.module_name.split(".")),name)) def main(): diff --git a/doc/fluid/api/index_cn.rst b/doc/fluid/api/index_cn.rst index dcda7e97f51d5..39a2028d32cfe 100644 --- a/doc/fluid/api/index_cn.rst +++ b/doc/fluid/api/index_cn.rst @@ -5,7 +5,6 @@ API Reference .. toctree:: :maxdepth: 1 - api_guides/index.rst fluid.rst average.rst backward.rst diff --git a/doc/fluid/api/initializer.rst b/doc/fluid/api/initializer.rst index ce2036675581b..8a149e3bf5b7a 100644 --- a/doc/fluid/api/initializer.rst +++ b/doc/fluid/api/initializer.rst @@ -14,6 +14,8 @@ Bilinear :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_Bilinear` + .. _api_fluid_initializer_BilinearInitializer: BilinearInitializer @@ -23,6 +25,8 @@ BilinearInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_BilinearInitializer` + .. _api_fluid_initializer_Constant: Constant @@ -32,6 +36,8 @@ Constant :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_Constant` + .. _api_fluid_initializer_ConstantInitializer: ConstantInitializer @@ -41,6 +47,8 @@ ConstantInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_ConstantInitializer` + .. _api_fluid_initializer_force_init_on_cpu: force_init_on_cpu @@ -49,6 +57,8 @@ force_init_on_cpu .. autofunction:: paddle.fluid.initializer.force_init_on_cpu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_force_init_on_cpu` + .. _api_fluid_initializer_init_on_cpu: init_on_cpu @@ -57,6 +67,8 @@ init_on_cpu .. autofunction:: paddle.fluid.initializer.init_on_cpu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_init_on_cpu` + .. _api_fluid_initializer_MSRA: MSRA @@ -66,6 +78,8 @@ MSRA :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_MSRA` + .. _api_fluid_initializer_MSRAInitializer: MSRAInitializer @@ -75,6 +89,8 @@ MSRAInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_MSRAInitializer` + .. _api_fluid_initializer_Normal: Normal @@ -84,6 +100,8 @@ Normal :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_Normal` + .. _api_fluid_initializer_NormalInitializer: NormalInitializer @@ -93,6 +111,8 @@ NormalInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_NormalInitializer` + .. _api_fluid_initializer_TruncatedNormal: TruncatedNormal @@ -102,6 +122,8 @@ TruncatedNormal :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_TruncatedNormal` + .. _api_fluid_initializer_TruncatedNormalInitializer: TruncatedNormalInitializer @@ -111,6 +133,8 @@ TruncatedNormalInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_TruncatedNormalInitializer` + .. _api_fluid_initializer_Uniform: Uniform @@ -120,6 +144,8 @@ Uniform :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_Uniform` + .. _api_fluid_initializer_UniformInitializer: UniformInitializer @@ -129,6 +155,8 @@ UniformInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_UniformInitializer` + .. _api_fluid_initializer_Xavier: Xavier @@ -138,6 +166,8 @@ Xavier :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_Xavier` + .. _api_fluid_initializer_XavierInitializer: XavierInitializer @@ -147,3 +177,5 @@ XavierInitializer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_initializer_XavierInitializer` + diff --git a/doc/fluid/api/io.rst b/doc/fluid/api/io.rst index b3dc7f83ca7c6..922af9a23ea7b 100644 --- a/doc/fluid/api/io.rst +++ b/doc/fluid/api/io.rst @@ -13,6 +13,8 @@ load_inference_model .. autofunction:: paddle.fluid.io.load_inference_model :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_load_inference_model` + .. _api_fluid_io_load_params: load_params @@ -21,6 +23,8 @@ load_params .. autofunction:: paddle.fluid.io.load_params :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_load_params` + .. _api_fluid_io_load_persistables: load_persistables @@ -29,6 +33,8 @@ load_persistables .. autofunction:: paddle.fluid.io.load_persistables :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_load_persistables` + .. _api_fluid_io_load_vars: load_vars @@ -37,6 +43,8 @@ load_vars .. autofunction:: paddle.fluid.io.load_vars :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_load_vars` + .. _api_fluid_io_save_inference_model: save_inference_model @@ -45,6 +53,8 @@ save_inference_model .. autofunction:: paddle.fluid.io.save_inference_model :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_save_inference_model` + .. _api_fluid_io_save_params: save_params @@ -53,6 +63,8 @@ save_params .. autofunction:: paddle.fluid.io.save_params :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_save_params` + .. _api_fluid_io_save_persistables: save_persistables @@ -61,6 +73,8 @@ save_persistables .. autofunction:: paddle.fluid.io.save_persistables :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_save_persistables` + .. _api_fluid_io_save_vars: save_vars @@ -69,3 +83,5 @@ save_vars .. autofunction:: paddle.fluid.io.save_vars :noindex: +Read Chinese Version: :ref:`cn_api_fluid_io_save_vars` + diff --git a/doc/fluid/api/layers.rst b/doc/fluid/api/layers.rst index d9808904a8543..96a8c5d017165 100644 --- a/doc/fluid/api/layers.rst +++ b/doc/fluid/api/layers.rst @@ -16,6 +16,8 @@ array_length .. autofunction:: paddle.fluid.layers.array_length :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_array_length` + .. _api_fluid_layers_array_read: array_read @@ -24,6 +26,8 @@ array_read .. autofunction:: paddle.fluid.layers.array_read :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_array_read` + .. _api_fluid_layers_array_write: array_write @@ -32,6 +36,8 @@ array_write .. autofunction:: paddle.fluid.layers.array_write :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_array_write` + .. _api_fluid_layers_create_array: create_array @@ -40,6 +46,8 @@ create_array .. autofunction:: paddle.fluid.layers.create_array :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_create_array` + .. _api_fluid_layers_DynamicRNN: DynamicRNN @@ -49,6 +57,8 @@ DynamicRNN :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_DynamicRNN` + .. _api_fluid_layers_equal: equal @@ -57,6 +67,8 @@ equal .. autofunction:: paddle.fluid.layers.equal :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_equal` + .. _api_fluid_layers_IfElse: IfElse @@ -66,6 +78,8 @@ IfElse :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_IfElse` + .. _api_fluid_layers_increment: increment @@ -74,6 +88,8 @@ increment .. autofunction:: paddle.fluid.layers.increment :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_increment` + .. _api_fluid_layers_is_empty: is_empty @@ -82,6 +98,8 @@ is_empty .. autofunction:: paddle.fluid.layers.is_empty :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_is_empty` + .. _api_fluid_layers_less_than: less_than @@ -90,6 +108,8 @@ less_than .. autofunction:: paddle.fluid.layers.less_than :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_less_than` + .. _api_fluid_layers_Print: Print @@ -98,6 +118,8 @@ Print .. autofunction:: paddle.fluid.layers.Print :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_Print` + .. _api_fluid_layers_reorder_lod_tensor_by_rank: reorder_lod_tensor_by_rank @@ -106,6 +128,8 @@ reorder_lod_tensor_by_rank .. autofunction:: paddle.fluid.layers.reorder_lod_tensor_by_rank :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reorder_lod_tensor_by_rank` + .. _api_fluid_layers_StaticRNN: StaticRNN @@ -115,6 +139,8 @@ StaticRNN :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_StaticRNN` + .. _api_fluid_layers_Switch: Switch @@ -124,6 +150,8 @@ Switch :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_Switch` + .. _api_fluid_layers_While: While @@ -133,6 +161,8 @@ While :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_While` + device ====== @@ -147,6 +177,8 @@ batch .. autofunction:: paddle.fluid.layers.batch :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_batch` + .. _api_fluid_layers_create_py_reader_by_data: create_py_reader_by_data @@ -155,6 +187,8 @@ create_py_reader_by_data .. autofunction:: paddle.fluid.layers.create_py_reader_by_data :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_create_py_reader_by_data` + .. _api_fluid_layers_data: data @@ -163,6 +197,8 @@ data .. autofunction:: paddle.fluid.layers.data :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_data` + .. _api_fluid_layers_double_buffer: double_buffer @@ -171,6 +207,8 @@ double_buffer .. autofunction:: paddle.fluid.layers.double_buffer :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_double_buffer` + .. _api_fluid_layers_load: load @@ -179,6 +217,8 @@ load .. autofunction:: paddle.fluid.layers.load :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_load` + .. _api_fluid_layers_open_files: open_files @@ -187,6 +227,8 @@ open_files .. autofunction:: paddle.fluid.layers.open_files :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_open_files` + .. _api_fluid_layers_Preprocessor: Preprocessor @@ -196,6 +238,8 @@ Preprocessor :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_Preprocessor` + .. _api_fluid_layers_py_reader: py_reader @@ -204,6 +248,8 @@ py_reader .. autofunction:: paddle.fluid.layers.py_reader :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_py_reader` + .. _api_fluid_layers_random_data_generator: random_data_generator @@ -212,6 +258,8 @@ random_data_generator .. autofunction:: paddle.fluid.layers.random_data_generator :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_random_data_generator` + .. _api_fluid_layers_read_file: read_file @@ -220,6 +268,8 @@ read_file .. autofunction:: paddle.fluid.layers.read_file :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_read_file` + .. _api_fluid_layers_shuffle: shuffle @@ -228,6 +278,8 @@ shuffle .. autofunction:: paddle.fluid.layers.shuffle :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_shuffle` + nn == @@ -239,6 +291,8 @@ add_position_encoding .. autofunction:: paddle.fluid.layers.add_position_encoding :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_add_position_encoding` + .. _api_fluid_layers_affine_channel: affine_channel @@ -247,6 +301,8 @@ affine_channel .. autofunction:: paddle.fluid.layers.affine_channel :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_affine_channel` + .. _api_fluid_layers_affine_grid: affine_grid @@ -255,6 +311,8 @@ affine_grid .. autofunction:: paddle.fluid.layers.affine_grid :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_affine_grid` + .. _api_fluid_layers_autoincreased_step_counter: autoincreased_step_counter @@ -263,6 +321,8 @@ autoincreased_step_counter .. autofunction:: paddle.fluid.layers.autoincreased_step_counter :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_autoincreased_step_counter` + .. _api_fluid_layers_batch_norm: batch_norm @@ -271,6 +331,8 @@ batch_norm .. autofunction:: paddle.fluid.layers.batch_norm :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_batch_norm` + .. _api_fluid_layers_beam_search: beam_search @@ -279,6 +341,8 @@ beam_search .. autofunction:: paddle.fluid.layers.beam_search :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_beam_search` + .. _api_fluid_layers_beam_search_decode: beam_search_decode @@ -287,6 +351,8 @@ beam_search_decode .. autofunction:: paddle.fluid.layers.beam_search_decode :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_beam_search_decode` + .. _api_fluid_layers_bilinear_tensor_product: bilinear_tensor_product @@ -295,6 +361,8 @@ bilinear_tensor_product .. autofunction:: paddle.fluid.layers.bilinear_tensor_product :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_bilinear_tensor_product` + .. _api_fluid_layers_brelu: brelu @@ -303,6 +371,8 @@ brelu .. autofunction:: paddle.fluid.layers.brelu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_brelu` + .. _api_fluid_layers_chunk_eval: chunk_eval @@ -311,6 +381,8 @@ chunk_eval .. autofunction:: paddle.fluid.layers.chunk_eval :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_chunk_eval` + .. _api_fluid_layers_clip: clip @@ -319,6 +391,8 @@ clip .. autofunction:: paddle.fluid.layers.clip :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_clip` + .. _api_fluid_layers_clip_by_norm: clip_by_norm @@ -327,6 +401,8 @@ clip_by_norm .. autofunction:: paddle.fluid.layers.clip_by_norm :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_clip_by_norm` + .. _api_fluid_layers_conv2d: conv2d @@ -335,6 +411,8 @@ conv2d .. autofunction:: paddle.fluid.layers.conv2d :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_conv2d` + .. _api_fluid_layers_conv2d_transpose: conv2d_transpose @@ -343,6 +421,8 @@ conv2d_transpose .. autofunction:: paddle.fluid.layers.conv2d_transpose :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_conv2d_transpose` + .. _api_fluid_layers_conv3d: conv3d @@ -351,6 +431,8 @@ conv3d .. autofunction:: paddle.fluid.layers.conv3d :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_conv3d` + .. _api_fluid_layers_conv3d_transpose: conv3d_transpose @@ -359,6 +441,8 @@ conv3d_transpose .. autofunction:: paddle.fluid.layers.conv3d_transpose :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_conv3d_transpose` + .. _api_fluid_layers_cos_sim: cos_sim @@ -367,6 +451,8 @@ cos_sim .. autofunction:: paddle.fluid.layers.cos_sim :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_cos_sim` + .. _api_fluid_layers_crf_decoding: crf_decoding @@ -375,6 +461,8 @@ crf_decoding .. autofunction:: paddle.fluid.layers.crf_decoding :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_crf_decoding` + .. _api_fluid_layers_crop: crop @@ -383,6 +471,8 @@ crop .. autofunction:: paddle.fluid.layers.crop :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_crop` + .. _api_fluid_layers_cross_entropy: cross_entropy @@ -391,6 +481,8 @@ cross_entropy .. autofunction:: paddle.fluid.layers.cross_entropy :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_cross_entropy` + .. _api_fluid_layers_ctc_greedy_decoder: ctc_greedy_decoder @@ -399,6 +491,8 @@ ctc_greedy_decoder .. autofunction:: paddle.fluid.layers.ctc_greedy_decoder :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_ctc_greedy_decoder` + .. _api_fluid_layers_dice_loss: dice_loss @@ -407,6 +501,8 @@ dice_loss .. autofunction:: paddle.fluid.layers.dice_loss :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_dice_loss` + .. _api_fluid_layers_dropout: dropout @@ -415,6 +511,8 @@ dropout .. autofunction:: paddle.fluid.layers.dropout :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_dropout` + .. _api_fluid_layers_dynamic_gru: dynamic_gru @@ -423,6 +521,8 @@ dynamic_gru .. autofunction:: paddle.fluid.layers.dynamic_gru :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_dynamic_gru` + .. _api_fluid_layers_dynamic_lstm: dynamic_lstm @@ -431,6 +531,8 @@ dynamic_lstm .. autofunction:: paddle.fluid.layers.dynamic_lstm :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_dynamic_lstm` + .. _api_fluid_layers_dynamic_lstmp: dynamic_lstmp @@ -439,6 +541,8 @@ dynamic_lstmp .. autofunction:: paddle.fluid.layers.dynamic_lstmp :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_dynamic_lstmp` + .. _api_fluid_layers_edit_distance: edit_distance @@ -447,6 +551,8 @@ edit_distance .. autofunction:: paddle.fluid.layers.edit_distance :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_edit_distance` + .. _api_fluid_layers_elementwise_add: elementwise_add @@ -455,6 +561,8 @@ elementwise_add .. autofunction:: paddle.fluid.layers.elementwise_add :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_add` + .. _api_fluid_layers_elementwise_div: elementwise_div @@ -463,6 +571,8 @@ elementwise_div .. autofunction:: paddle.fluid.layers.elementwise_div :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_div` + .. _api_fluid_layers_elementwise_max: elementwise_max @@ -471,6 +581,8 @@ elementwise_max .. autofunction:: paddle.fluid.layers.elementwise_max :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_max` + .. _api_fluid_layers_elementwise_min: elementwise_min @@ -479,6 +591,8 @@ elementwise_min .. autofunction:: paddle.fluid.layers.elementwise_min :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_min` + .. _api_fluid_layers_elementwise_mul: elementwise_mul @@ -487,6 +601,8 @@ elementwise_mul .. autofunction:: paddle.fluid.layers.elementwise_mul :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_mul` + .. _api_fluid_layers_elementwise_pow: elementwise_pow @@ -495,6 +611,8 @@ elementwise_pow .. autofunction:: paddle.fluid.layers.elementwise_pow :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_pow` + .. _api_fluid_layers_elementwise_sub: elementwise_sub @@ -503,6 +621,8 @@ elementwise_sub .. autofunction:: paddle.fluid.layers.elementwise_sub :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elementwise_sub` + .. _api_fluid_layers_elu: elu @@ -511,6 +631,8 @@ elu .. autofunction:: paddle.fluid.layers.elu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_elu` + .. _api_fluid_layers_embedding: embedding @@ -519,6 +641,8 @@ embedding .. autofunction:: paddle.fluid.layers.embedding :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_embedding` + .. _api_fluid_layers_expand: expand @@ -527,6 +651,8 @@ expand .. autofunction:: paddle.fluid.layers.expand :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_expand` + .. _api_fluid_layers_fc: fc @@ -535,6 +661,8 @@ fc .. autofunction:: paddle.fluid.layers.fc :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_fc` + .. _api_fluid_layers_flatten: flatten @@ -543,6 +671,8 @@ flatten .. autofunction:: paddle.fluid.layers.flatten :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_flatten` + .. _api_fluid_layers_gather: gather @@ -551,6 +681,8 @@ gather .. autofunction:: paddle.fluid.layers.gather :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_gather` + .. _api_fluid_layers_gaussian_random: gaussian_random @@ -559,6 +691,8 @@ gaussian_random .. autofunction:: paddle.fluid.layers.gaussian_random :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_gaussian_random` + .. _api_fluid_layers_gaussian_random_batch_size_like: gaussian_random_batch_size_like @@ -567,6 +701,18 @@ gaussian_random_batch_size_like .. autofunction:: paddle.fluid.layers.gaussian_random_batch_size_like :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_gaussian_random_batch_size_like` + +.. _api_fluid_layers_get_tensor_from_selected_rows: + +get_tensor_from_selected_rows +----------------------------- + +.. autofunction:: paddle.fluid.layers.get_tensor_from_selected_rows + :noindex: + +Read Chinese Version: :ref:`cn_api_fluid_layers_get_tensor_from_selected_rows` + .. _api_fluid_layers_grid_sampler: grid_sampler @@ -575,6 +721,8 @@ grid_sampler .. autofunction:: paddle.fluid.layers.grid_sampler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_grid_sampler` + .. _api_fluid_layers_group_norm: group_norm @@ -583,6 +731,8 @@ group_norm .. autofunction:: paddle.fluid.layers.group_norm :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_group_norm` + .. _api_fluid_layers_gru_unit: gru_unit @@ -591,6 +741,8 @@ gru_unit .. autofunction:: paddle.fluid.layers.gru_unit :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_gru_unit` + .. _api_fluid_layers_hard_sigmoid: hard_sigmoid @@ -599,6 +751,8 @@ hard_sigmoid .. autofunction:: paddle.fluid.layers.hard_sigmoid :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_hard_sigmoid` + .. _api_fluid_layers_hash: hash @@ -607,6 +761,8 @@ hash .. autofunction:: paddle.fluid.layers.hash :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_hash` + .. _api_fluid_layers_hsigmoid: hsigmoid @@ -615,6 +771,8 @@ hsigmoid .. autofunction:: paddle.fluid.layers.hsigmoid :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_hsigmoid` + .. _api_fluid_layers_im2sequence: im2sequence @@ -623,6 +781,8 @@ im2sequence .. autofunction:: paddle.fluid.layers.im2sequence :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_im2sequence` + .. _api_fluid_layers_image_resize: image_resize @@ -631,6 +791,8 @@ image_resize .. autofunction:: paddle.fluid.layers.image_resize :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_image_resize` + .. _api_fluid_layers_image_resize_short: image_resize_short @@ -639,6 +801,8 @@ image_resize_short .. autofunction:: paddle.fluid.layers.image_resize_short :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_image_resize_short` + .. _api_fluid_layers_l2_normalize: l2_normalize @@ -647,6 +811,8 @@ l2_normalize .. autofunction:: paddle.fluid.layers.l2_normalize :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_l2_normalize` + .. _api_fluid_layers_label_smooth: label_smooth @@ -655,6 +821,8 @@ label_smooth .. autofunction:: paddle.fluid.layers.label_smooth :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_label_smooth` + .. _api_fluid_layers_layer_norm: layer_norm @@ -663,6 +831,8 @@ layer_norm .. autofunction:: paddle.fluid.layers.layer_norm :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_layer_norm` + .. _api_fluid_layers_leaky_relu: leaky_relu @@ -671,6 +841,8 @@ leaky_relu .. autofunction:: paddle.fluid.layers.leaky_relu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_leaky_relu` + .. _api_fluid_layers_linear_chain_crf: linear_chain_crf @@ -679,6 +851,8 @@ linear_chain_crf .. autofunction:: paddle.fluid.layers.linear_chain_crf :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_linear_chain_crf` + .. _api_fluid_layers_lod_reset: lod_reset @@ -687,6 +861,8 @@ lod_reset .. autofunction:: paddle.fluid.layers.lod_reset :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_lod_reset` + .. _api_fluid_layers_log: log @@ -695,6 +871,8 @@ log .. autofunction:: paddle.fluid.layers.log :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_log` + .. _api_fluid_layers_log_loss: log_loss @@ -703,6 +881,8 @@ log_loss .. autofunction:: paddle.fluid.layers.log_loss :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_log_loss` + .. _api_fluid_layers_logical_and: logical_and @@ -711,6 +891,8 @@ logical_and .. autofunction:: paddle.fluid.layers.logical_and :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_logical_and` + .. _api_fluid_layers_logical_not: logical_not @@ -719,6 +901,8 @@ logical_not .. autofunction:: paddle.fluid.layers.logical_not :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_logical_not` + .. _api_fluid_layers_logical_or: logical_or @@ -727,6 +911,8 @@ logical_or .. autofunction:: paddle.fluid.layers.logical_or :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_logical_or` + .. _api_fluid_layers_logical_xor: logical_xor @@ -735,6 +921,8 @@ logical_xor .. autofunction:: paddle.fluid.layers.logical_xor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_logical_xor` + .. _api_fluid_layers_lrn: lrn @@ -743,6 +931,18 @@ lrn .. autofunction:: paddle.fluid.layers.lrn :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_lrn` + +.. _api_fluid_layers_lstm: + +lstm +---- + +.. autofunction:: paddle.fluid.layers.lstm + :noindex: + +Read Chinese Version: :ref:`cn_api_fluid_layers_lstm` + .. _api_fluid_layers_lstm_unit: lstm_unit @@ -751,6 +951,8 @@ lstm_unit .. autofunction:: paddle.fluid.layers.lstm_unit :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_lstm_unit` + .. _api_fluid_layers_margin_rank_loss: margin_rank_loss @@ -759,6 +961,8 @@ margin_rank_loss .. autofunction:: paddle.fluid.layers.margin_rank_loss :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_margin_rank_loss` + .. _api_fluid_layers_matmul: matmul @@ -767,6 +971,8 @@ matmul .. autofunction:: paddle.fluid.layers.matmul :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_matmul` + .. _api_fluid_layers_maxout: maxout @@ -775,6 +981,8 @@ maxout .. autofunction:: paddle.fluid.layers.maxout :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_maxout` + .. _api_fluid_layers_mean: mean @@ -783,6 +991,8 @@ mean .. autofunction:: paddle.fluid.layers.mean :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_mean` + .. _api_fluid_layers_mean_iou: mean_iou @@ -791,6 +1001,18 @@ mean_iou .. autofunction:: paddle.fluid.layers.mean_iou :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_mean_iou` + +.. _api_fluid_layers_merge_selected_rows: + +merge_selected_rows +------------------- + +.. autofunction:: paddle.fluid.layers.merge_selected_rows + :noindex: + +Read Chinese Version: :ref:`cn_api_fluid_layers_merge_selected_rows` + .. _api_fluid_layers_mul: mul @@ -799,6 +1021,8 @@ mul .. autofunction:: paddle.fluid.layers.mul :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_mul` + .. _api_fluid_layers_multiplex: multiplex @@ -807,6 +1031,8 @@ multiplex .. autofunction:: paddle.fluid.layers.multiplex :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_multiplex` + .. _api_fluid_layers_nce: nce @@ -815,6 +1041,8 @@ nce .. autofunction:: paddle.fluid.layers.nce :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_nce` + .. _api_fluid_layers_one_hot: one_hot @@ -823,6 +1051,8 @@ one_hot .. autofunction:: paddle.fluid.layers.one_hot :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_one_hot` + .. _api_fluid_layers_pad: pad @@ -831,6 +1061,8 @@ pad .. autofunction:: paddle.fluid.layers.pad :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pad` + .. _api_fluid_layers_pad2d: pad2d @@ -839,6 +1071,8 @@ pad2d .. autofunction:: paddle.fluid.layers.pad2d :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pad2d` + .. _api_fluid_layers_pad_constant_like: pad_constant_like @@ -847,6 +1081,8 @@ pad_constant_like .. autofunction:: paddle.fluid.layers.pad_constant_like :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pad_constant_like` + .. _api_fluid_layers_pool2d: pool2d @@ -855,6 +1091,8 @@ pool2d .. autofunction:: paddle.fluid.layers.pool2d :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pool2d` + .. _api_fluid_layers_pool3d: pool3d @@ -863,6 +1101,8 @@ pool3d .. autofunction:: paddle.fluid.layers.pool3d :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pool3d` + .. _api_fluid_layers_pow: pow @@ -871,6 +1111,8 @@ pow .. autofunction:: paddle.fluid.layers.pow :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_pow` + .. _api_fluid_layers_prelu: prelu @@ -879,6 +1121,8 @@ prelu .. autofunction:: paddle.fluid.layers.prelu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_prelu` + .. _api_fluid_layers_random_crop: random_crop @@ -887,6 +1131,8 @@ random_crop .. autofunction:: paddle.fluid.layers.random_crop :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_random_crop` + .. _api_fluid_layers_rank_loss: rank_loss @@ -895,6 +1141,8 @@ rank_loss .. autofunction:: paddle.fluid.layers.rank_loss :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_rank_loss` + .. _api_fluid_layers_reduce_max: reduce_max @@ -903,6 +1151,8 @@ reduce_max .. autofunction:: paddle.fluid.layers.reduce_max :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reduce_max` + .. _api_fluid_layers_reduce_mean: reduce_mean @@ -911,6 +1161,8 @@ reduce_mean .. autofunction:: paddle.fluid.layers.reduce_mean :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reduce_mean` + .. _api_fluid_layers_reduce_min: reduce_min @@ -919,6 +1171,8 @@ reduce_min .. autofunction:: paddle.fluid.layers.reduce_min :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reduce_min` + .. _api_fluid_layers_reduce_prod: reduce_prod @@ -927,6 +1181,8 @@ reduce_prod .. autofunction:: paddle.fluid.layers.reduce_prod :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reduce_prod` + .. _api_fluid_layers_reduce_sum: reduce_sum @@ -935,6 +1191,8 @@ reduce_sum .. autofunction:: paddle.fluid.layers.reduce_sum :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reduce_sum` + .. _api_fluid_layers_relu: relu @@ -943,6 +1201,8 @@ relu .. autofunction:: paddle.fluid.layers.relu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_relu` + .. _api_fluid_layers_relu6: relu6 @@ -951,6 +1211,8 @@ relu6 .. autofunction:: paddle.fluid.layers.relu6 :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_relu6` + .. _api_fluid_layers_reshape: reshape @@ -959,6 +1221,8 @@ reshape .. autofunction:: paddle.fluid.layers.reshape :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reshape` + .. _api_fluid_layers_resize_bilinear: resize_bilinear @@ -967,6 +1231,8 @@ resize_bilinear .. autofunction:: paddle.fluid.layers.resize_bilinear :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_resize_bilinear` + .. _api_fluid_layers_resize_nearest: resize_nearest @@ -975,6 +1241,8 @@ resize_nearest .. autofunction:: paddle.fluid.layers.resize_nearest :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_resize_nearest` + .. _api_fluid_layers_roi_align: roi_align @@ -983,6 +1251,8 @@ roi_align .. autofunction:: paddle.fluid.layers.roi_align :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_roi_align` + .. _api_fluid_layers_roi_pool: roi_pool @@ -991,6 +1261,8 @@ roi_pool .. autofunction:: paddle.fluid.layers.roi_pool :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_roi_pool` + .. _api_fluid_layers_row_conv: row_conv @@ -999,6 +1271,8 @@ row_conv .. autofunction:: paddle.fluid.layers.row_conv :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_row_conv` + .. _api_fluid_layers_sampling_id: sampling_id @@ -1007,6 +1281,8 @@ sampling_id .. autofunction:: paddle.fluid.layers.sampling_id :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sampling_id` + .. _api_fluid_layers_scale: scale @@ -1015,6 +1291,8 @@ scale .. autofunction:: paddle.fluid.layers.scale :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_scale` + .. _api_fluid_layers_scatter: scatter @@ -1023,6 +1301,8 @@ scatter .. autofunction:: paddle.fluid.layers.scatter :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_scatter` + .. _api_fluid_layers_selu: selu @@ -1031,6 +1311,8 @@ selu .. autofunction:: paddle.fluid.layers.selu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_selu` + .. _api_fluid_layers_sequence_concat: sequence_concat @@ -1039,6 +1321,8 @@ sequence_concat .. autofunction:: paddle.fluid.layers.sequence_concat :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_concat` + .. _api_fluid_layers_sequence_conv: sequence_conv @@ -1047,6 +1331,8 @@ sequence_conv .. autofunction:: paddle.fluid.layers.sequence_conv :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_conv` + .. _api_fluid_layers_sequence_enumerate: sequence_enumerate @@ -1055,6 +1341,8 @@ sequence_enumerate .. autofunction:: paddle.fluid.layers.sequence_enumerate :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_enumerate` + .. _api_fluid_layers_sequence_expand: sequence_expand @@ -1063,6 +1351,8 @@ sequence_expand .. autofunction:: paddle.fluid.layers.sequence_expand :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_expand` + .. _api_fluid_layers_sequence_expand_as: sequence_expand_as @@ -1071,6 +1361,8 @@ sequence_expand_as .. autofunction:: paddle.fluid.layers.sequence_expand_as :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_expand_as` + .. _api_fluid_layers_sequence_first_step: sequence_first_step @@ -1079,6 +1371,8 @@ sequence_first_step .. autofunction:: paddle.fluid.layers.sequence_first_step :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_first_step` + .. _api_fluid_layers_sequence_last_step: sequence_last_step @@ -1087,6 +1381,8 @@ sequence_last_step .. autofunction:: paddle.fluid.layers.sequence_last_step :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_last_step` + .. _api_fluid_layers_sequence_mask: sequence_mask @@ -1095,6 +1391,8 @@ sequence_mask .. autofunction:: paddle.fluid.layers.sequence_mask :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_mask` + .. _api_fluid_layers_sequence_pad: sequence_pad @@ -1103,6 +1401,8 @@ sequence_pad .. autofunction:: paddle.fluid.layers.sequence_pad :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_pad` + .. _api_fluid_layers_sequence_pool: sequence_pool @@ -1111,6 +1411,8 @@ sequence_pool .. autofunction:: paddle.fluid.layers.sequence_pool :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_pool` + .. _api_fluid_layers_sequence_reshape: sequence_reshape @@ -1119,6 +1421,8 @@ sequence_reshape .. autofunction:: paddle.fluid.layers.sequence_reshape :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_reshape` + .. _api_fluid_layers_sequence_reverse: sequence_reverse @@ -1127,6 +1431,8 @@ sequence_reverse .. autofunction:: paddle.fluid.layers.sequence_reverse :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_reverse` + .. _api_fluid_layers_sequence_scatter: sequence_scatter @@ -1135,6 +1441,8 @@ sequence_scatter .. autofunction:: paddle.fluid.layers.sequence_scatter :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_scatter` + .. _api_fluid_layers_sequence_slice: sequence_slice @@ -1143,6 +1451,8 @@ sequence_slice .. autofunction:: paddle.fluid.layers.sequence_slice :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_slice` + .. _api_fluid_layers_sequence_softmax: sequence_softmax @@ -1151,6 +1461,8 @@ sequence_softmax .. autofunction:: paddle.fluid.layers.sequence_softmax :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_softmax` + .. _api_fluid_layers_sequence_unpad: sequence_unpad @@ -1159,6 +1471,8 @@ sequence_unpad .. autofunction:: paddle.fluid.layers.sequence_unpad :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sequence_unpad` + .. _api_fluid_layers_shape: shape @@ -1167,6 +1481,8 @@ shape .. autofunction:: paddle.fluid.layers.shape :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_shape` + .. _api_fluid_layers_sigmoid_cross_entropy_with_logits: sigmoid_cross_entropy_with_logits @@ -1175,6 +1491,8 @@ sigmoid_cross_entropy_with_logits .. autofunction:: paddle.fluid.layers.sigmoid_cross_entropy_with_logits :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sigmoid_cross_entropy_with_logits` + .. _api_fluid_layers_similarity_focus: similarity_focus @@ -1183,6 +1501,8 @@ similarity_focus .. autofunction:: paddle.fluid.layers.similarity_focus :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_similarity_focus` + .. _api_fluid_layers_slice: slice @@ -1191,6 +1511,8 @@ slice .. autofunction:: paddle.fluid.layers.slice :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_slice` + .. _api_fluid_layers_smooth_l1: smooth_l1 @@ -1199,6 +1521,8 @@ smooth_l1 .. autofunction:: paddle.fluid.layers.smooth_l1 :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_smooth_l1` + .. _api_fluid_layers_soft_relu: soft_relu @@ -1207,6 +1531,8 @@ soft_relu .. autofunction:: paddle.fluid.layers.soft_relu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_soft_relu` + .. _api_fluid_layers_softmax: softmax @@ -1215,6 +1541,8 @@ softmax .. autofunction:: paddle.fluid.layers.softmax :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_softmax` + .. _api_fluid_layers_softmax_with_cross_entropy: softmax_with_cross_entropy @@ -1223,6 +1551,8 @@ softmax_with_cross_entropy .. autofunction:: paddle.fluid.layers.softmax_with_cross_entropy :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_softmax_with_cross_entropy` + .. _api_fluid_layers_space_to_depth: space_to_depth @@ -1231,6 +1561,8 @@ space_to_depth .. autofunction:: paddle.fluid.layers.space_to_depth :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_space_to_depth` + .. _api_fluid_layers_split: split @@ -1239,6 +1571,8 @@ split .. autofunction:: paddle.fluid.layers.split :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_split` + .. _api_fluid_layers_square_error_cost: square_error_cost @@ -1247,6 +1581,8 @@ square_error_cost .. autofunction:: paddle.fluid.layers.square_error_cost :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_square_error_cost` + .. _api_fluid_layers_squeeze: squeeze @@ -1255,6 +1591,8 @@ squeeze .. autofunction:: paddle.fluid.layers.squeeze :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_squeeze` + .. _api_fluid_layers_stack: stack @@ -1263,6 +1601,8 @@ stack .. autofunction:: paddle.fluid.layers.stack :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_stack` + .. _api_fluid_layers_stanh: stanh @@ -1271,6 +1611,8 @@ stanh .. autofunction:: paddle.fluid.layers.stanh :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_stanh` + .. _api_fluid_layers_sum: sum @@ -1279,6 +1621,8 @@ sum .. autofunction:: paddle.fluid.layers.sum :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sum` + .. _api_fluid_layers_swish: swish @@ -1287,6 +1631,8 @@ swish .. autofunction:: paddle.fluid.layers.swish :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_swish` + .. _api_fluid_layers_topk: topk @@ -1295,6 +1641,8 @@ topk .. autofunction:: paddle.fluid.layers.topk :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_topk` + .. _api_fluid_layers_transpose: transpose @@ -1303,6 +1651,8 @@ transpose .. autofunction:: paddle.fluid.layers.transpose :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_transpose` + .. _api_fluid_layers_uniform_random_batch_size_like: uniform_random_batch_size_like @@ -1311,6 +1661,8 @@ uniform_random_batch_size_like .. autofunction:: paddle.fluid.layers.uniform_random_batch_size_like :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_uniform_random_batch_size_like` + .. _api_fluid_layers_unsqueeze: unsqueeze @@ -1319,6 +1671,8 @@ unsqueeze .. autofunction:: paddle.fluid.layers.unsqueeze :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_unsqueeze` + .. _api_fluid_layers_unstack: unstack @@ -1327,6 +1681,8 @@ unstack .. autofunction:: paddle.fluid.layers.unstack :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_unstack` + .. _api_fluid_layers_warpctc: warpctc @@ -1335,6 +1691,8 @@ warpctc .. autofunction:: paddle.fluid.layers.warpctc :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_warpctc` + ops === @@ -1346,6 +1704,8 @@ abs .. autofunction:: paddle.fluid.layers.abs :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_abs` + .. _api_fluid_layers_ceil: ceil @@ -1354,6 +1714,8 @@ ceil .. autofunction:: paddle.fluid.layers.ceil :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_ceil` + .. _api_fluid_layers_cos: cos @@ -1362,6 +1724,8 @@ cos .. autofunction:: paddle.fluid.layers.cos :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_cos` + .. _api_fluid_layers_cumsum: cumsum @@ -1370,6 +1734,8 @@ cumsum .. autofunction:: paddle.fluid.layers.cumsum :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_cumsum` + .. _api_fluid_layers_exp: exp @@ -1378,6 +1744,8 @@ exp .. autofunction:: paddle.fluid.layers.exp :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_exp` + .. _api_fluid_layers_floor: floor @@ -1386,6 +1754,8 @@ floor .. autofunction:: paddle.fluid.layers.floor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_floor` + .. _api_fluid_layers_hard_shrink: hard_shrink @@ -1394,6 +1764,8 @@ hard_shrink .. autofunction:: paddle.fluid.layers.hard_shrink :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_hard_shrink` + .. _api_fluid_layers_logsigmoid: logsigmoid @@ -1402,6 +1774,8 @@ logsigmoid .. autofunction:: paddle.fluid.layers.logsigmoid :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_logsigmoid` + .. _api_fluid_layers_reciprocal: reciprocal @@ -1410,6 +1784,8 @@ reciprocal .. autofunction:: paddle.fluid.layers.reciprocal :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reciprocal` + .. _api_fluid_layers_round: round @@ -1418,6 +1794,8 @@ round .. autofunction:: paddle.fluid.layers.round :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_round` + .. _api_fluid_layers_sigmoid: sigmoid @@ -1426,6 +1804,8 @@ sigmoid .. autofunction:: paddle.fluid.layers.sigmoid :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sigmoid` + .. _api_fluid_layers_sin: sin @@ -1434,6 +1814,8 @@ sin .. autofunction:: paddle.fluid.layers.sin :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sin` + .. _api_fluid_layers_softplus: softplus @@ -1442,6 +1824,8 @@ softplus .. autofunction:: paddle.fluid.layers.softplus :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_softplus` + .. _api_fluid_layers_softshrink: softshrink @@ -1450,6 +1834,8 @@ softshrink .. autofunction:: paddle.fluid.layers.softshrink :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_softshrink` + .. _api_fluid_layers_softsign: softsign @@ -1458,6 +1844,8 @@ softsign .. autofunction:: paddle.fluid.layers.softsign :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_softsign` + .. _api_fluid_layers_sqrt: sqrt @@ -1466,6 +1854,8 @@ sqrt .. autofunction:: paddle.fluid.layers.sqrt :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sqrt` + .. _api_fluid_layers_square: square @@ -1474,6 +1864,8 @@ square .. autofunction:: paddle.fluid.layers.square :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_square` + .. _api_fluid_layers_tanh: tanh @@ -1482,6 +1874,8 @@ tanh .. autofunction:: paddle.fluid.layers.tanh :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_tanh` + .. _api_fluid_layers_tanh_shrink: tanh_shrink @@ -1490,6 +1884,8 @@ tanh_shrink .. autofunction:: paddle.fluid.layers.tanh_shrink :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_tanh_shrink` + .. _api_fluid_layers_thresholded_relu: thresholded_relu @@ -1498,6 +1894,8 @@ thresholded_relu .. autofunction:: paddle.fluid.layers.thresholded_relu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_thresholded_relu` + .. _api_fluid_layers_uniform_random: uniform_random @@ -1506,6 +1904,8 @@ uniform_random .. autofunction:: paddle.fluid.layers.uniform_random :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_uniform_random` + tensor ====== @@ -1517,6 +1917,8 @@ argmax .. autofunction:: paddle.fluid.layers.argmax :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_argmax` + .. _api_fluid_layers_argmin: argmin @@ -1525,6 +1927,8 @@ argmin .. autofunction:: paddle.fluid.layers.argmin :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_argmin` + .. _api_fluid_layers_argsort: argsort @@ -1533,6 +1937,8 @@ argsort .. autofunction:: paddle.fluid.layers.argsort :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_argsort` + .. _api_fluid_layers_assign: assign @@ -1541,6 +1947,8 @@ assign .. autofunction:: paddle.fluid.layers.assign :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_assign` + .. _api_fluid_layers_cast: cast @@ -1549,6 +1957,8 @@ cast .. autofunction:: paddle.fluid.layers.cast :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_cast` + .. _api_fluid_layers_concat: concat @@ -1557,6 +1967,8 @@ concat .. autofunction:: paddle.fluid.layers.concat :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_concat` + .. _api_fluid_layers_create_global_var: create_global_var @@ -1565,6 +1977,8 @@ create_global_var .. autofunction:: paddle.fluid.layers.create_global_var :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_create_global_var` + .. _api_fluid_layers_create_parameter: create_parameter @@ -1573,6 +1987,8 @@ create_parameter .. autofunction:: paddle.fluid.layers.create_parameter :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_create_parameter` + .. _api_fluid_layers_create_tensor: create_tensor @@ -1581,6 +1997,8 @@ create_tensor .. autofunction:: paddle.fluid.layers.create_tensor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_create_tensor` + .. _api_fluid_layers_fill_constant: fill_constant @@ -1589,6 +2007,8 @@ fill_constant .. autofunction:: paddle.fluid.layers.fill_constant :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_fill_constant` + .. _api_fluid_layers_fill_constant_batch_size_like: fill_constant_batch_size_like @@ -1597,6 +2017,8 @@ fill_constant_batch_size_like .. autofunction:: paddle.fluid.layers.fill_constant_batch_size_like :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_fill_constant_batch_size_like` + .. _api_fluid_layers_has_inf: has_inf @@ -1605,6 +2027,8 @@ has_inf .. autofunction:: paddle.fluid.layers.has_inf :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_has_inf` + .. _api_fluid_layers_has_nan: has_nan @@ -1613,6 +2037,8 @@ has_nan .. autofunction:: paddle.fluid.layers.has_nan :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_has_nan` + .. _api_fluid_layers_isfinite: isfinite @@ -1621,6 +2047,8 @@ isfinite .. autofunction:: paddle.fluid.layers.isfinite :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_isfinite` + .. _api_fluid_layers_ones: ones @@ -1629,6 +2057,8 @@ ones .. autofunction:: paddle.fluid.layers.ones :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_ones` + .. _api_fluid_layers_reverse: reverse @@ -1637,6 +2067,8 @@ reverse .. autofunction:: paddle.fluid.layers.reverse :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_reverse` + .. _api_fluid_layers_sums: sums @@ -1645,6 +2077,8 @@ sums .. autofunction:: paddle.fluid.layers.sums :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_sums` + .. _api_fluid_layers_tensor_array_to_tensor: tensor_array_to_tensor @@ -1653,6 +2087,8 @@ tensor_array_to_tensor .. autofunction:: paddle.fluid.layers.tensor_array_to_tensor :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_tensor_array_to_tensor` + .. _api_fluid_layers_zeros: zeros @@ -1661,6 +2097,8 @@ zeros .. autofunction:: paddle.fluid.layers.zeros :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_zeros` + learning_rate_scheduler ======================= @@ -1672,6 +2110,8 @@ append_LARS .. autofunction:: paddle.fluid.layers.append_LARS :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_append_LARS` + .. _api_fluid_layers_exponential_decay: exponential_decay @@ -1680,6 +2120,8 @@ exponential_decay .. autofunction:: paddle.fluid.layers.exponential_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_exponential_decay` + .. _api_fluid_layers_inverse_time_decay: inverse_time_decay @@ -1688,6 +2130,8 @@ inverse_time_decay .. autofunction:: paddle.fluid.layers.inverse_time_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_inverse_time_decay` + .. _api_fluid_layers_natural_exp_decay: natural_exp_decay @@ -1696,6 +2140,8 @@ natural_exp_decay .. autofunction:: paddle.fluid.layers.natural_exp_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_natural_exp_decay` + .. _api_fluid_layers_noam_decay: noam_decay @@ -1704,6 +2150,8 @@ noam_decay .. autofunction:: paddle.fluid.layers.noam_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_noam_decay` + .. _api_fluid_layers_piecewise_decay: piecewise_decay @@ -1712,6 +2160,8 @@ piecewise_decay .. autofunction:: paddle.fluid.layers.piecewise_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_piecewise_decay` + .. _api_fluid_layers_polynomial_decay: polynomial_decay @@ -1720,6 +2170,8 @@ polynomial_decay .. autofunction:: paddle.fluid.layers.polynomial_decay :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_polynomial_decay` + detection ========= @@ -1731,6 +2183,8 @@ anchor_generator .. autofunction:: paddle.fluid.layers.anchor_generator :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_anchor_generator` + .. _api_fluid_layers_bipartite_match: bipartite_match @@ -1739,6 +2193,8 @@ bipartite_match .. autofunction:: paddle.fluid.layers.bipartite_match :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_bipartite_match` + .. _api_fluid_layers_box_coder: box_coder @@ -1747,6 +2203,8 @@ box_coder .. autofunction:: paddle.fluid.layers.box_coder :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_box_coder` + .. _api_fluid_layers_density_prior_box: density_prior_box @@ -1755,6 +2213,8 @@ density_prior_box .. autofunction:: paddle.fluid.layers.density_prior_box :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_density_prior_box` + .. _api_fluid_layers_detection_map: detection_map @@ -1763,6 +2223,8 @@ detection_map .. autofunction:: paddle.fluid.layers.detection_map :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_detection_map` + .. _api_fluid_layers_detection_output: detection_output @@ -1771,6 +2233,8 @@ detection_output .. autofunction:: paddle.fluid.layers.detection_output :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_detection_output` + .. _api_fluid_layers_generate_proposal_labels: generate_proposal_labels @@ -1779,6 +2243,8 @@ generate_proposal_labels .. autofunction:: paddle.fluid.layers.generate_proposal_labels :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_generate_proposal_labels` + .. _api_fluid_layers_generate_proposals: generate_proposals @@ -1787,6 +2253,8 @@ generate_proposals .. autofunction:: paddle.fluid.layers.generate_proposals :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_generate_proposals` + .. _api_fluid_layers_iou_similarity: iou_similarity @@ -1795,6 +2263,8 @@ iou_similarity .. autofunction:: paddle.fluid.layers.iou_similarity :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_iou_similarity` + .. _api_fluid_layers_multi_box_head: multi_box_head @@ -1803,6 +2273,8 @@ multi_box_head .. autofunction:: paddle.fluid.layers.multi_box_head :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_multi_box_head` + .. _api_fluid_layers_polygon_box_transform: polygon_box_transform @@ -1811,6 +2283,8 @@ polygon_box_transform .. autofunction:: paddle.fluid.layers.polygon_box_transform :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_polygon_box_transform` + .. _api_fluid_layers_prior_box: prior_box @@ -1819,6 +2293,8 @@ prior_box .. autofunction:: paddle.fluid.layers.prior_box :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_prior_box` + .. _api_fluid_layers_roi_perspective_transform: roi_perspective_transform @@ -1827,6 +2303,8 @@ roi_perspective_transform .. autofunction:: paddle.fluid.layers.roi_perspective_transform :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_roi_perspective_transform` + .. _api_fluid_layers_rpn_target_assign: rpn_target_assign @@ -1835,6 +2313,8 @@ rpn_target_assign .. autofunction:: paddle.fluid.layers.rpn_target_assign :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_rpn_target_assign` + .. _api_fluid_layers_ssd_loss: ssd_loss @@ -1843,6 +2323,8 @@ ssd_loss .. autofunction:: paddle.fluid.layers.ssd_loss :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_ssd_loss` + .. _api_fluid_layers_target_assign: target_assign @@ -1851,6 +2333,8 @@ target_assign .. autofunction:: paddle.fluid.layers.target_assign :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_target_assign` + metric_op ========= @@ -1862,6 +2346,8 @@ accuracy .. autofunction:: paddle.fluid.layers.accuracy :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_accuracy` + .. _api_fluid_layers_auc: auc @@ -1870,3 +2356,5 @@ auc .. autofunction:: paddle.fluid.layers.auc :noindex: +Read Chinese Version: :ref:`cn_api_fluid_layers_auc` + diff --git a/doc/fluid/api/metrics.rst b/doc/fluid/api/metrics.rst index 5b5f7bc3b4155..8d0a603475ffb 100644 --- a/doc/fluid/api/metrics.rst +++ b/doc/fluid/api/metrics.rst @@ -14,6 +14,8 @@ Accuracy :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_Accuracy` + .. _api_fluid_metrics_Auc: Auc @@ -23,6 +25,8 @@ Auc :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_Auc` + .. _api_fluid_metrics_ChunkEvaluator: ChunkEvaluator @@ -32,6 +36,8 @@ ChunkEvaluator :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_ChunkEvaluator` + .. _api_fluid_metrics_CompositeMetric: CompositeMetric @@ -41,6 +47,8 @@ CompositeMetric :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_CompositeMetric` + .. _api_fluid_metrics_DetectionMAP: DetectionMAP @@ -50,6 +58,8 @@ DetectionMAP :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_DetectionMAP` + .. _api_fluid_metrics_EditDistance: EditDistance @@ -59,6 +69,8 @@ EditDistance :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_EditDistance` + .. _api_fluid_metrics_MetricBase: MetricBase @@ -68,6 +80,8 @@ MetricBase :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_MetricBase` + .. _api_fluid_metrics_Precision: Precision @@ -77,6 +91,8 @@ Precision :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_Precision` + .. _api_fluid_metrics_Recall: Recall @@ -86,3 +102,5 @@ Recall :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_metrics_Recall` + diff --git a/doc/fluid/api/nets.rst b/doc/fluid/api/nets.rst index f3792e6294696..4e0dcabee3b7d 100644 --- a/doc/fluid/api/nets.rst +++ b/doc/fluid/api/nets.rst @@ -13,6 +13,8 @@ glu .. autofunction:: paddle.fluid.nets.glu :noindex: +Read Chinese Version: :ref:`cn_api_fluid_nets_glu` + .. _api_fluid_nets_img_conv_group: img_conv_group @@ -21,6 +23,8 @@ img_conv_group .. autofunction:: paddle.fluid.nets.img_conv_group :noindex: +Read Chinese Version: :ref:`cn_api_fluid_nets_img_conv_group` + .. _api_fluid_nets_scaled_dot_product_attention: scaled_dot_product_attention @@ -29,6 +33,8 @@ scaled_dot_product_attention .. autofunction:: paddle.fluid.nets.scaled_dot_product_attention :noindex: +Read Chinese Version: :ref:`cn_api_fluid_nets_scaled_dot_product_attention` + .. _api_fluid_nets_sequence_conv_pool: sequence_conv_pool @@ -37,6 +43,8 @@ sequence_conv_pool .. autofunction:: paddle.fluid.nets.sequence_conv_pool :noindex: +Read Chinese Version: :ref:`cn_api_fluid_nets_sequence_conv_pool` + .. _api_fluid_nets_simple_img_conv_pool: simple_img_conv_pool @@ -45,3 +53,5 @@ simple_img_conv_pool .. autofunction:: paddle.fluid.nets.simple_img_conv_pool :noindex: +Read Chinese Version: :ref:`cn_api_fluid_nets_simple_img_conv_pool` + diff --git a/doc/fluid/api/optimizer.rst b/doc/fluid/api/optimizer.rst index 6c81c501dc03d..6fb2140ece1ed 100644 --- a/doc/fluid/api/optimizer.rst +++ b/doc/fluid/api/optimizer.rst @@ -14,6 +14,8 @@ Adadelta :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Adadelta` + .. _api_fluid_optimizer_Adagrad: Adagrad @@ -23,6 +25,8 @@ Adagrad :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Adagrad` + .. _api_fluid_optimizer_AdagradOptimizer: AdagradOptimizer @@ -32,6 +36,8 @@ AdagradOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_AdagradOptimizer` + .. _api_fluid_optimizer_Adam: Adam @@ -41,6 +47,8 @@ Adam :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Adam` + .. _api_fluid_optimizer_Adamax: Adamax @@ -50,6 +58,8 @@ Adamax :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Adamax` + .. _api_fluid_optimizer_AdamaxOptimizer: AdamaxOptimizer @@ -59,6 +69,8 @@ AdamaxOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` + .. _api_fluid_optimizer_AdamOptimizer: AdamOptimizer @@ -68,6 +80,8 @@ AdamOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_AdamOptimizer` + .. _api_fluid_optimizer_DecayedAdagrad: DecayedAdagrad @@ -77,6 +91,8 @@ DecayedAdagrad :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_DecayedAdagrad` + .. _api_fluid_optimizer_DecayedAdagradOptimizer: DecayedAdagradOptimizer @@ -86,6 +102,8 @@ DecayedAdagradOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` + .. _api_fluid_optimizer_Ftrl: Ftrl @@ -95,6 +113,8 @@ Ftrl :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Ftrl` + .. _api_fluid_optimizer_FtrlOptimizer: FtrlOptimizer @@ -104,6 +124,8 @@ FtrlOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_FtrlOptimizer` + .. _api_fluid_optimizer_LarsMomentum: LarsMomentum @@ -113,6 +135,8 @@ LarsMomentum :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_LarsMomentum` + .. _api_fluid_optimizer_LarsMomentumOptimizer: LarsMomentumOptimizer @@ -122,6 +146,8 @@ LarsMomentumOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` + .. _api_fluid_optimizer_ModelAverage: ModelAverage @@ -131,6 +157,8 @@ ModelAverage :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_ModelAverage` + .. _api_fluid_optimizer_Momentum: Momentum @@ -140,6 +168,8 @@ Momentum :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_Momentum` + .. _api_fluid_optimizer_MomentumOptimizer: MomentumOptimizer @@ -149,6 +179,8 @@ MomentumOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_MomentumOptimizer` + .. _api_fluid_optimizer_RMSPropOptimizer: RMSPropOptimizer @@ -158,6 +190,8 @@ RMSPropOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_RMSPropOptimizer` + .. _api_fluid_optimizer_SGD: SGD @@ -167,6 +201,8 @@ SGD :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_SGD` + .. _api_fluid_optimizer_SGDOptimizer: SGDOptimizer @@ -176,3 +212,5 @@ SGDOptimizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_optimizer_SGDOptimizer` + diff --git a/doc/fluid/api/profiler.rst b/doc/fluid/api/profiler.rst index cff8e8c2428f8..19feb25bf760b 100644 --- a/doc/fluid/api/profiler.rst +++ b/doc/fluid/api/profiler.rst @@ -13,6 +13,8 @@ cuda_profiler .. autofunction:: paddle.fluid.profiler.cuda_profiler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_profiler_cuda_profiler` + .. _api_fluid_profiler_profiler: profiler @@ -21,6 +23,8 @@ profiler .. autofunction:: paddle.fluid.profiler.profiler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_profiler_profiler` + .. _api_fluid_profiler_reset_profiler: reset_profiler @@ -29,6 +33,8 @@ reset_profiler .. autofunction:: paddle.fluid.profiler.reset_profiler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_profiler_reset_profiler` + .. _api_fluid_profiler_start_profiler: start_profiler @@ -37,6 +43,8 @@ start_profiler .. autofunction:: paddle.fluid.profiler.start_profiler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_profiler_start_profiler` + .. _api_fluid_profiler_stop_profiler: stop_profiler @@ -45,3 +53,5 @@ stop_profiler .. autofunction:: paddle.fluid.profiler.stop_profiler :noindex: +Read Chinese Version: :ref:`cn_api_fluid_profiler_stop_profiler` + diff --git a/doc/fluid/api/recordio_writer.rst b/doc/fluid/api/recordio_writer.rst index f0c12fd115478..9d7848f406912 100644 --- a/doc/fluid/api/recordio_writer.rst +++ b/doc/fluid/api/recordio_writer.rst @@ -13,6 +13,8 @@ convert_reader_to_recordio_file .. autofunction:: paddle.fluid.recordio_writer.convert_reader_to_recordio_file :noindex: +Read Chinese Version: :ref:`cn_api_fluid_recordio_writer_convert_reader_to_recordio_file` + .. _api_fluid_recordio_writer_convert_reader_to_recordio_files: convert_reader_to_recordio_files @@ -21,3 +23,5 @@ convert_reader_to_recordio_files .. autofunction:: paddle.fluid.recordio_writer.convert_reader_to_recordio_files :noindex: +Read Chinese Version: :ref:`cn_api_fluid_recordio_writer_convert_reader_to_recordio_files` + diff --git a/doc/fluid/api/regularizer.rst b/doc/fluid/api/regularizer.rst index dcf69eba8a8db..b505ff506b8e2 100644 --- a/doc/fluid/api/regularizer.rst +++ b/doc/fluid/api/regularizer.rst @@ -14,6 +14,8 @@ L1Decay :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_regularizer_L1Decay` + .. _api_fluid_regularizer_L1DecayRegularizer: L1DecayRegularizer @@ -23,6 +25,8 @@ L1DecayRegularizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_regularizer_L1DecayRegularizer` + .. _api_fluid_regularizer_L2Decay: L2Decay @@ -32,6 +36,8 @@ L2Decay :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_regularizer_L2Decay` + .. _api_fluid_regularizer_L2DecayRegularizer: L2DecayRegularizer @@ -41,3 +47,5 @@ L2DecayRegularizer :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_regularizer_L2DecayRegularizer` + diff --git a/doc/fluid/api/transpiler.rst b/doc/fluid/api/transpiler.rst index 7764f60deda2f..e647933278fb2 100644 --- a/doc/fluid/api/transpiler.rst +++ b/doc/fluid/api/transpiler.rst @@ -14,6 +14,8 @@ DistributeTranspiler :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_DistributeTranspiler` + .. _api_fluid_transpiler_DistributeTranspilerConfig: DistributeTranspilerConfig @@ -23,6 +25,8 @@ DistributeTranspilerConfig :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_DistributeTranspilerConfig` + .. _api_fluid_transpiler_HashName: HashName @@ -32,6 +36,8 @@ HashName :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_HashName` + .. _api_fluid_transpiler_memory_optimize: memory_optimize @@ -40,6 +46,8 @@ memory_optimize .. autofunction:: paddle.fluid.transpiler.memory_optimize :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_memory_optimize` + .. _api_fluid_transpiler_release_memory: release_memory @@ -48,6 +56,8 @@ release_memory .. autofunction:: paddle.fluid.transpiler.release_memory :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_release_memory` + .. _api_fluid_transpiler_RoundRobin: RoundRobin @@ -57,3 +67,5 @@ RoundRobin :members: :noindex: +Read Chinese Version: :ref:`cn_api_fluid_transpiler_RoundRobin` + diff --git a/doc/fluid/api_cn/api_guides/high_low_level_api.md b/doc/fluid/api_cn/api_guides/high_low_level_api.md new file mode 100644 index 0000000000000..8ce2695737c45 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/high_low_level_api.md @@ -0,0 +1,15 @@ +## High/Low-level API简介 + +Paddle目前有2套API接口： + +- Low-level（底层） API： + + - 灵活性强并且已经相对成熟，使用它训练的模型，能直接支持C++预测上线。 + - 提供了大量的模型作为使用示例，包括[Book](https://github.com/PaddlePaddle/book)中的第7和8章，以及[models](https://github.com/PaddlePaddle/models)中的所有章节。 + - 适用人群：对深度学习有一定了解，需要自定义网络进行训练/预测/上线部署的用户。 + +- High-level（高层）API： + + - 使用简单，[Book](https://github.com/PaddlePaddle/book)中前六章提供了示例。 + - 尚未成熟，接口暂时在[paddle.fluid.contrib](https://github.com/PaddlePaddle/Paddle/tree/develop/python/paddle/fluid/contrib)下面。 + - 适用人群：想通过Book课程进行深度学习基础知识学习的初级用户。 diff --git a/doc/fluid/api_cn/api_guides/index.rst b/doc/fluid/api_cn/api_guides/index.rst new file mode 100755 index 0000000000000..fbbad453b24a0 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/index.rst @@ -0,0 +1,18 @@ +=========== +API使用指南 +=========== + +.. toctree:: + :hidden: + + 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 + low_level/memory_optimize.rst + low_level/nets.rst + low_level/parallel_executor.rst diff --git a/doc/fluid/api_cn/api_guides/low_level/distributed/async_training.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/async_training.rst new file mode 100644 index 0000000000000..a36fd2cd185c3 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/async_training.rst @@ -0,0 +1,33 @@ +.. _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_cn/api_guides/low_level/distributed/cluster_train_data_cn.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/cluster_train_data_cn.rst new file mode 100644 index 0000000000000..c4c7e22958bd3 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/cluster_train_data_cn.rst @@ -0,0 +1,64 @@ +.. _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_cn/api_guides/low_level/distributed/cpu_train_best_practice.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/cpu_train_best_practice.rst new file mode 100644 index 0000000000000..b6b5102636f27 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/cpu_train_best_practice.rst @@ -0,0 +1,58 @@ +.. _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_cn/api_guides/low_level/distributed/index.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/index.rst new file mode 100644 index 0000000000000..d689921f14759 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/index.rst @@ -0,0 +1,14 @@ +============= +分布式训练 +============= + +.. toctree:: + :maxdepth: 1 + + sync_training.rst + async_training.rst + cpu_train_best_practice.rst + large_scale_sparse_feature_training.rst + cluster_train_data_cn.rst + + diff --git a/doc/fluid/api_cn/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst new file mode 100644 index 0000000000000..7b2994f15a9de --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst @@ -0,0 +1,42 @@ +.. _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_cn/api_guides/low_level/distributed/sync_training.rst b/doc/fluid/api_cn/api_guides/low_level/distributed/sync_training.rst new file mode 100644 index 0000000000000..b64c37ac8e52f --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/distributed/sync_training.rst @@ -0,0 +1,83 @@ +.. _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_cn/api_guides/low_level/executor.rst b/doc/fluid/api_cn/api_guides/low_level/executor.rst new file mode 100644 index 0000000000000..5617d14c143e1 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/executor.rst @@ -0,0 +1,20 @@ +.. _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_cn/api_guides/low_level/inference.rst b/doc/fluid/api_cn/api_guides/low_level/inference.rst new file mode 100644 index 0000000000000..2a61fb307534e --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/inference.rst @@ -0,0 +1,55 @@ +.. _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_cn/api_guides/low_level/layers/activations.rst b/doc/fluid/api_cn/api_guides/low_level/layers/activations.rst new file mode 100644 index 0000000000000..615e364d525b4 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/activations.rst @@ -0,0 +1,28 @@ +.. _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_cn/api_guides/low_level/layers/control_flow.rst b/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst new file mode 100644 index 0000000000000..c2192b498cb33 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/control_flow.rst @@ -0,0 +1,53 @@ +.. 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_cn/api_guides/low_level/layers/conv.rst b/doc/fluid/api_cn/api_guides/low_level/layers/conv.rst new file mode 100644 index 0000000000000..018c3d56ef96f --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/conv.rst @@ -0,0 +1,64 @@ +.. _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_cn/api_guides/low_level/layers/data_feeder.rst b/doc/fluid/api_cn/api_guides/low_level/layers/data_feeder.rst new file mode 100644 index 0000000000000..770116dfb99fc --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/data_feeder.rst @@ -0,0 +1,44 @@ +.. _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_cn/api_guides/low_level/layers/data_in_out.rst b/doc/fluid/api_cn/api_guides/low_level/layers/data_in_out.rst new file mode 100644 index 0000000000000..9d0a2521ee236 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/data_in_out.rst @@ -0,0 +1,33 @@ +.. _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_cn/api_guides/low_level/layers/detection.rst b/doc/fluid/api_cn/api_guides/low_level/layers/detection.rst new file mode 100644 index 0000000000000..f277c27ceaa5e --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/detection.rst @@ -0,0 +1,63 @@ +.. _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_cn/api_guides/low_level/layers/index.rst b/doc/fluid/api_cn/api_guides/low_level/layers/index.rst new file mode 100644 index 0000000000000..78bf1fa1f2f0a --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/index.rst @@ -0,0 +1,21 @@ +============= +神经网络层 +============= + +.. 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 + data_feeder.rst + learning_rate_scheduler.rst + tensor.rst + diff --git a/doc/fluid/api_cn/api_guides/low_level/layers/learning_rate_scheduler.rst b/doc/fluid/api_cn/api_guides/low_level/layers/learning_rate_scheduler.rst new file mode 100644 index 0000000000000..c617c44958a2f --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/learning_rate_scheduler.rst @@ -0,0 +1,40 @@ +.. _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_cn/api_guides/low_level/layers/loss_function.rst b/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst new file mode 100644 index 0000000000000..5802fc4b93418 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/loss_function.rst @@ -0,0 +1,60 @@ +.. _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_cn/api_guides/low_level/layers/math.rst b/doc/fluid/api_cn/api_guides/low_level/layers/math.rst new file mode 100644 index 0000000000000..6ae121ccd5540 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/math.rst @@ -0,0 +1,211 @@ +.. _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_cn/api_guides/low_level/layers/pooling.rst b/doc/fluid/api_cn/api_guides/low_level/layers/pooling.rst new file mode 100644 index 0000000000000..de4a1bd82cc14 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/pooling.rst @@ -0,0 +1,80 @@ +.. _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_cn/api_guides/low_level/layers/sequence.rst b/doc/fluid/api_cn/api_guides/low_level/layers/sequence.rst new file mode 100644 index 0000000000000..455e8e9b51c41 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/sequence.rst @@ -0,0 +1,112 @@ +.. _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_cn/api_guides/low_level/layers/sparse_update.rst b/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst new file mode 100644 index 0000000000000..ae49a70c2bc7c --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/sparse_update.rst @@ -0,0 +1,45 @@ +.. _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_cn/api_guides/low_level/layers/tensor.rst b/doc/fluid/api_cn/api_guides/low_level/layers/tensor.rst new file mode 100644 index 0000000000000..a0549fcb84fe5 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/layers/tensor.rst @@ -0,0 +1,149 @@ +.. _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_cn/api_guides/low_level/memory_optimize.rst b/doc/fluid/api_cn/api_guides/low_level/memory_optimize.rst new file mode 100644 index 0000000000000..f820d2e48327e --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/memory_optimize.rst @@ -0,0 +1,49 @@ +.. _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_cn/api_guides/low_level/metrics.rst b/doc/fluid/api_cn/api_guides/low_level/metrics.rst new file mode 100644 index 0000000000000..90531d61635a7 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/metrics.rst @@ -0,0 +1,51 @@ +.. _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_cn/api_guides/low_level/model_save_reader.rst b/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst new file mode 100644 index 0000000000000..8edae98508297 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/model_save_reader.rst @@ -0,0 +1,59 @@ +.. _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_cn/api_guides/low_level/nets.rst b/doc/fluid/api_cn/api_guides/low_level/nets.rst new file mode 100644 index 0000000000000..38c1b24a785e1 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/nets.rst @@ -0,0 +1,61 @@ +.. _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_cn/api_guides/low_level/optimizer.rst b/doc/fluid/api_cn/api_guides/low_level/optimizer.rst new file mode 100644 index 0000000000000..e068bd4801081 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/optimizer.rst @@ -0,0 +1,92 @@ +.. _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_cn/api_guides/low_level/parallel_executor.rst b/doc/fluid/api_cn/api_guides/low_level/parallel_executor.rst new file mode 100644 index 0000000000000..f269bc02ccb0c --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/parallel_executor.rst @@ -0,0 +1,37 @@ +.. _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_cn/api_guides/low_level/parameter.rst b/doc/fluid/api_cn/api_guides/low_level/parameter.rst new file mode 100755 index 0000000000000..b485fa4743e00 --- /dev/null +++ b/doc/fluid/api_cn/api_guides/low_level/parameter.rst @@ -0,0 +1,167 @@ +.. _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_cn/average_cn.rst b/doc/fluid/api_cn/average_cn.rst new file mode 100644 index 0000000000000..cf55798fb6d56 --- /dev/null +++ b/doc/fluid/api_cn/average_cn.rst @@ -0,0 +1,69 @@ + +################# + fluid.average +################# + + + +.. _cn_api_fluid_average_WeightedAverage: + +WeightedAverage +>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.average.WeightedAverage + +计算加权平均值。 + +平均计算完全通过Python完成。它们不会改变Paddle的程序，也不会修改NN模型的配置。它们完全是Python函数的包装器。 + +**示例代码** + +.. code-block:: python + + avg = fluid.average.WeightedAverage() + avg.add(value=2.0, weight=1) + avg.add(value=4.0, weight=2) + avg.eval() + # 结果为 3.333333333. + # 因为 (2.0 * 1 + 4.0 * 2) / (1 + 2) = 3.333333333 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +英文版API文档: :ref:`api_fluid_average_WeightedAverage` + diff --git a/doc/fluid/api_cn/backward_cn.rst b/doc/fluid/api_cn/backward_cn.rst new file mode 100644 index 0000000000000..ad8cdd3c00ca9 --- /dev/null +++ b/doc/fluid/api_cn/backward_cn.rst @@ -0,0 +1,90 @@ + +################# + fluid.backward +################# + + + +.. _cn_api_fluid_backward_append_backward: + +append_backward +>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.backward.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None) + +将向 ``main_program`` 追加 ``backward`` 。 + +完整的神经网络训练由前向和反向传播组成。但是当我们配置网络时，我们只需要指定其前向部分。通过该功能，根据前向部分自动生成反向部分。 + +在大多数情况下，用户无需手动调用此功能。它将由优化程序的最小化函数自动调用。 + +参数： + - **loss** （Variable）- 网络的损失变量。 + - **parameter_list** （list [string] | None）- 优化器需要更新的参数名称。如果为None，则将更新所有参数。默认值：None。 + - **no_grad_set** （set | None）- ``block`` 0中变量的梯度应该被忽略。所有 ``block`` 中带有 ``step_gradient = True`` 的所有变量都将自动添加到此集合中。默认值：None。 + - **callbacks** （list [callable object] | None）- 回调用于在反向传播构建中执行一些自定义作业。每次将新的梯度运算符添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： ``block`` 和 ``context`` 。 ``block`` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度变量名，值是对应的原始变量。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度运算符的 ``op_desc`` 。 + +返回： 成对参数及其相应的梯度。键是参数，值是梯度变量。 + +返回类型： list[(Variable,Variable)] + +抛出： + - ``AssertionError`` - 如果loss不是Variable的实例。 + +**示例代码** + +.. code-block:: python + + # 网络配置 + # ... + avg_loss = fluid.layers.mean(loss) + param_grad_list = fluid.backward.append_backward(loss=avg_loss) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +英文版API文档: :ref:`api_fluid_backward_append_backward` + diff --git a/doc/fluid/api_cn/clip_cn.rst b/doc/fluid/api_cn/clip_cn.rst new file mode 100644 index 0000000000000..83e08a9948e5e --- /dev/null +++ b/doc/fluid/api_cn/clip_cn.rst @@ -0,0 +1,156 @@ + +################# + fluid.clip +################# + + + +.. _cn_api_fluid_clip_ErrorClipByValue: + +ErrorClipByValue +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.clip.ErrorClipByValue(max, min=None) + +将张量值的范围压缩到 [min, max]。 + + +给定一个张量 ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max`` 之间 + +- 任何小于最小值的值都被设置为最小值 + +- 任何大于max的值都被设置为max + +参数: + - **max** (foat) - 要修剪的最大值。 + - **min** (float) - 要修剪的最小值。如果用户没有设置，将被 ``framework`` 设置为 ``-max`` + +**代码示例** + +.. code-block:: python + + var = fluid.framework.Variable(..., error_clip=ErrorClipByValue(max=5.0), ...) + + + + +英文版API文档: :ref:`api_fluid_clip_ErrorClipByValue` + +.. _cn_api_fluid_clip_GradientClipByGlobalNorm: + +GradientClipByGlobalNorm +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.clip.GradientClipByGlobalNorm(clip_norm, group_name='default_group') + +通过多个张量的范数之和的比率来剪切（clip）多个张量。 + +给定一个张量列表 :math:`t\_list` 和一个剪切比率 ``clip_norm`` ，返回一个被剪切的张量列表list_clipped和 :math:`t\_list` 中所有张量的全局范数(global_norm)。 + +剪切过程如下： + +.. math:: + \\t\_list[i]=t\_list[i]∗\frac{clip\_norm}{max(global\_norm,clip\_norm)}\\ + +其中： + +.. math:: + \\global\_norm=\sqrt{\sum_{i=0}^{n-1}(l2norm(t\_list[i]))^2}\\ + + +如果 :math:`clip\_norm>global\_norm` ， :math:`t\_list` 中的张量保持不变，否则它们都会按照全局比率缩减。 + + +参数: + - **clip_norm** (float) - 范数最大值 + - **group_name** (str, optional) - 剪切的组名 + +**代码示例** + +.. code-block:: python + + p_g_clip = fluid.backward.append_backward(loss=avg_cost_clip) + + with fluid.program_guard(main_program=prog_clip): + fluid.clip.set_gradient_clip( + fluid.clip.GradientClipByGlobalNorm(clip_norm=2.0)) + p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip) + + + +英文版API文档: :ref:`api_fluid_clip_GradientClipByGlobalNorm` + +.. _cn_api_fluid_clip_GradientClipByNorm: + +GradientClipByNorm +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.clip.GradientClipByNorm(clip_norm) + +将张量转换为L2范数不超过 ``clip_norm`` 的张量 + +该operator 限制了 输入张量 :math:`X` 的L2范数不会超过 :math:`max\_norm` 。如果 :math:`X` 的 ``L2`` 范数小于或等于 :math:`max\_norm` ,输出和 :math:`X` 一样，如果 :math:`X` 的L2范数大于 :math:`max\_norm` , :math:`X` 将被线性缩放到L2范数等于 :math:`max\_norm` ,如以下公式所示: + +.. math:: + \\Out = \frac{max\_norm∗X}{norm(X)}\\ + +其中 :math:`norm（X）` 代表 :math:`X` 的 L2 范数 + + +参数: + - **clip_norm** (float) - 二范数最大值 + + +**代码示例** + +.. code-block:: python + + w_param_attrs = ParamAttr(name=None, + initializer=UniformInitializer(low=-1.0, high=1.0, seed=0), + learning_rate=1.0, + regularizer=L1Decay(1.0), + trainable=True, + clip=GradientClipByNorm(clip_norm=2.0)) + y_predict = fluid.layers.fc(input=x, size=1, param_attr=w_param_attrs) + + + + +英文版API文档: :ref:`api_fluid_clip_GradientClipByNorm` + +.. _cn_api_fluid_clip_GradientClipByValue: + +GradientClipByValue +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.clip.GradientClipByValue(max, min=None) + +将梯度值(gradient values)的范围压缩到 [min, max]。 + + +给定一个张量 ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max`` 之间 + +- 任何小于最小值的值都被设置为最小值 + +- 任何大于max的值都被设置为max + +参数: + - **max** (foat) - 要修剪的最大值。 + - **min** (float，optional) - 要修剪的最小值。如果用户没有设置，将被 ``framework`` 设置为 ``-max`` 。 + +**代码示例** + +.. code-block:: python + + w_param_attrs = ParamAttr(name=None, + initializer=UniformInitializer(low=-1.0, high=1.0, seed=0), + learning_rate=1.0, + regularizer=L1Decay(1.0), + trainable=True, + clip=GradientClipByValue(-1.0, 1.0)) + y_predict = fluid.layers.fc(input=x, size=1, param_attr=w_param_attrs) + + + +英文版API文档: :ref:`api_fluid_clip_GradientClipByValue` + diff --git a/doc/fluid/api_cn/data_feeder_cn.rst b/doc/fluid/api_cn/data_feeder_cn.rst new file mode 100644 index 0000000000000..111242d54158f --- /dev/null +++ b/doc/fluid/api_cn/data_feeder_cn.rst @@ -0,0 +1,121 @@ + +################# +fluid.data_feeder +################# + + + +.. _cn_api_fluid_data_feeder_DataFeeder: + +DataFeeder +>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.data_feeder.DataFeeder(feed_list, place, program=None) + + + +``DataFeeder`` 负责将reader(读取器)返回的数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。 +reader通常返回一个minibatch条目列表。在列表中每一条目都是一个样本（sample）,它是由具有一至多个特征的列表或元组组成的。 + + +以下是简单用法： + +.. code-block:: python + + place = fluid.CPUPlace() + img = fluid.layers.data(name='image', shape=[1, 28, 28]) + label = fluid.layers.data(name='label', shape=[1], dtype='int64') + feeder = fluid.DataFeeder([img, label], fluid.CPUPlace()) + result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])]) + +在多GPU模型训练时，如果需要提前分别向各GPU输入数据，可以使用 ``decorate_reader`` 函数。 + +.. code-block:: python + + place=fluid.CUDAPlace(0) + feeder = fluid.DataFeeder(place=place, feed_list=[data, label]) + reader = feeder.decorate_reader( + paddle.batch(flowers.train(), batch_size=16)) + + + +参数： + - **feed_list** (list) – 向模型输入的变量表或者变量表名 + - **place** (Place) – place表明是向GPU还是CPU中输入数据。如果想向GPU中输入数据, 请使用 ``fluid.CUDAPlace(i)`` (i 代表 the GPU id)；如果向CPU中输入数据, 请使用 ``fluid.CPUPlace()`` + - **program** (Program) – 需要向其中输入数据的Program。如果为None, 会默认使用 ``default_main_program()``。 缺省值为None + + +弹出异常: ``ValueError`` – 如果一些变量不在此 Program 中 + + +**代码示例** + +.. code-block:: python + + # ... + place = fluid.CPUPlace() + feed_list = [ + main_program.global_block().var(var_name) for var_name in feed_vars_name + ] # feed_vars_name 是一个由变量名组成的列表 + feeder = fluid.DataFeeder(feed_list, place) + for data in reader(): + outs = exe.run(program=main_program, + feed=feeder.feed(data)) + + +.. py:method:: feed(iterable) + + +根据feed_list（数据输入表）和iterable（可遍历的数据）提供的信息，将输入数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。 + +参数: + - **iterable** (list|tuple) – 要输入的数据 + +返回： 转换结果 + +返回类型: dict + + +.. py:method:: feed_parallel(iterable, num_places=None) + + +该方法获取的多个minibatch，并把每个minibatch提前输入进各个设备中。 + +参数: + - **iterable** (list|tuple) – 要输入的数据 + - **num_places** (int) – 设备数目。默认为None。 + +返回: 转换结果 + +返回类型: dict + +.. note:: + 设备（CPU或GPU）的数目必须等于minibatch的数目 + + + +.. py:method:: decorate_reader(reader, multi_devices, num_places=None, drop_last=True) + + + +将reader返回的输入数据batch转换为多个mini-batch，之后每个mini-batch都会被输入进各个设备（CPU或GPU）中。 + +参数： + - **reader** (fun) – 待输入的数据 + - **multi_devices** (bool) – 执行场所的数目，默认为None + - **num_places** (int) – 执行场所的数目，默认为None + - **drop_last** (bool) – 舍弃数目匹配不上的batch或设备 + +返回：转换结果 + +返回类型: dict + +弹出异常： ValueError – 如果 ``drop_last`` 值为False并且reader返回的minibatch数目与设备数目不相等时，产生此异常 + + + + + + +英文版API文档: :ref:`api_fluid_data_feeder_DataFeeder` + diff --git a/doc/fluid/api_cn/executor_cn.rst b/doc/fluid/api_cn/executor_cn.rst new file mode 100644 index 0000000000000..feeb1f28311b2 --- /dev/null +++ b/doc/fluid/api_cn/executor_cn.rst @@ -0,0 +1,111 @@ + +################# + fluid.executor +################# + + + +.. _cn_api_fluid_executor: + +Executor +>>>>>>>>>>>>>>>>>>>>> + + +.. py:class:: paddle.fluid.executor.Executor (place) + + + + +执行引擎（Executor）使用python脚本驱动，仅支持在单GPU环境下运行。多卡环境下请参考 ``ParallelExecutor`` 。 +Python Executor可以接收传入的program,并根据feed map(输入映射表)和fetch_list(结果获取表) +向program中添加feed operators(数据输入算子)和fetch operators（结果获取算子)。 +feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。 + +应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。 + +Executor将全局变量存储到全局作用域中，并为临时变量创建局部作用域。 +当每一mini-batch上的前向/反向运算完成后，局部作用域的内容将被废弃， +但全局作用域中的变量将在Executor的不同执行过程中一直存在。 + +program中所有的算子会按顺序执行。 + +参数: + - **place** (core.CPUPlace|core.CUDAPlace(n)) – 指明了 ``Executor`` 的执行场所 + + + +提示：你可以用Executor来调试基于并行GPU实现的复杂网络，他们有完全一样的参数也会产生相同的结果。 + + +.. py:method:: close() + + +关闭这个执行器(Executor)。调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上涉及到目前训练器的资源。 + +**示例代码** + +.. code-block:: python + + cpu = core.CPUPlace() + exe = Executor(cpu) + ... + exe.close() + + +.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True,use_program_cache=False) + + +调用该执行器对象的此方法可以执行program。通过feed map提供待学习数据，以及借助fetch_list得到相应的结果。 +Python执行器(Executor)可以接收传入的program,并根据输入映射表(feed map)和结果获取表(fetch_list) +向program中添加数据输入算子(feed operators)和结果获取算子（fetch operators)。 +feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。 + +应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。 + +参数： + - **program** (Program) – 需要执行的program,如果没有给定那么默认使用default_main_program + - **feed** (dict) – 前向输入的变量，数据,词典dict类型, 例如 {“image”: ImageData, “label”: LableData} + - **fetch_list** (list) – 用户想得到的变量或者命名的列表, run会根据这个列表给与结果 + - **feed_var_name** (str) – 前向算子(feed operator)变量的名称 + - **fetch_var_name** (str) – 结果获取算子(fetch operator)的输出变量名称 + - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。缺省为全局域 + - **return_numpy** (bool) – 如果为True,则将结果张量（fetched tensor）转化为numpy + - **use_program_cache** (bool) – 当program较上次比没有改动则将其置为True + +返回: 根据fetch_list来获取结果 + +返回类型: list(numpy.array) + + +**示例代码** + +.. code-block:: python + + + data = layers.data(name='X', shape=[1], dtype='float32') + hidden = layers.fc(input=data, size=10) + layers.assign(hidden, out) + loss = layers.mean(out) + adam = fluid.optimizer.Adam() + adam.minimize(loss) + + +.. code-block:: python + + + cpu = core.CPUPlace() + exe = Executor(cpu) + exe.run(default_startup_program()) + +.. code-block:: python + + x = numpy.random.random(size=(10, 1)).astype('float32') + outs = exe.run( + feed={'X': x}, + fetch_list=[loss.name]) + + + + +英文版API文档: :ref:`api_fluid_executor` + diff --git a/doc/fluid/api_cn/fluid_cn.rst b/doc/fluid/api_cn/fluid_cn.rst new file mode 100644 index 0000000000000..3ba5d33af4e15 --- /dev/null +++ b/doc/fluid/api_cn/fluid_cn.rst @@ -0,0 +1,1550 @@ + +################# +fluid +################# + + + +.. _cn_api_fluid_AsyncExecutor: + +AsyncExecutor +>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.AsyncExecutor(place=None) + +Python中的异步执行器。AsyncExecutor利用多核处理器和数据排队的强大功能，使数据读取和融合解耦，每个线程并行运行。 + +AsyncExecutor不是在python端读取数据，而是接受一个训练文件列表，该列表将在c++中检索，然后训练输入将被读取、解析并在c++代码中提供给训练网络。 + +AsyncExecutor正在积极开发，API可能在不久的将来会发生变化。 + +参数： + - **place** (fluid.CPUPlace|None) - 指示 executor 将在哪个设备上运行。目前仅支持CPU + +**代码示例：** + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + startup_program = fluid.default_startup_program() + main_program = fluid.default_main_program() + filelist = ["train_data/part-%d" % i for i in range(100)] + thread_num = len(filelist) / 4 + place = fluid.CPUPlace() + async_executor = fluid.AsyncExecutor(place) + async_executor.run_startup_program(startup_program) + epoch = 10 + for i in range(epoch): + async_executor.run(main_program, + data_feed, + filelist, + thread_num, + [acc], + debug=False) + +.. note:: + + 对于并行gpu调试复杂网络，您可以在executor上测试。他们有完全相同的参数，并可以得到相同的结果。 + + 目前仅支持CPU + + + +英文版API文档: :ref:`api_fluid_AsyncExecutor` + +.. _cn_api_fluid_BuildStrategy: + +BuildStrategy +>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.BuildStrategy + +``BuildStrategy`` 使用户更精准地控制 ``ParallelExecutor`` 中SSA图的建造方法。可通过设置 ``ParallelExecutor`` 中的 ``BuildStrategy`` 成员来实现此功能。 + +**代码示例** + +.. code-block:: python + + build_strategy = fluid.BuildStrategy() + build_strategy.reduce_strategy = fluid.BuildStrategy.ReduceStrategy.Reduce + + train_exe = fluid.ParallelExecutor(use_cuda=True, + loss_name=loss.name, + build_strategy=build_strategy) + + train_loss, = train_exe.run([loss.name], feed=feed_dict) + + + +.. py:attribute:: debug_graphviz_path + +str类型。它表明了以graphviz格式向文件中写入SSA图的路径，有利于调试。 默认值为""。 + + + +.. py:attribute:: fuse_elewise_add_act_ops + +bool类型。它表明了是否融合（fuse）elementwise_add_op和activation_op。这会使整体执行过程更快一些。默认为False。 + + + +.. py:attribute:: gradient_scale_strategy + +str类型。在 ``ParallelExecutor`` 中，存在三种定义 *loss@grad* 的方式，分别为 ``CoeffNumDevice``, ``One`` 与 ``Customized``。默认情况下， ``ParallelExecutor`` 根据设备数目来设置 *loss@grad* 。如果你想自定义 *loss@grad* ，你可以选择 ``Customized`` 方法。默认为 ``CoeffNumDevice`` 。 + + + +.. py:attribute:: reduce_strategy + +str类型。在 ``ParallelExecutor`` 中，存在两种减少策略（reduce strategy），即 ``AllReduce`` 和 ``Reduce`` 。如果你需要在所有执行场所上独立地进行参数优化，可以使用 ``AllReduce`` 。反之，如果使用 ``Reduce`` 策略，所有参数的优化将均匀地分配给不同的执行场所，随之将优化后的参数广播给其他执行场所。在一些模型中， ``Reduce`` 策略执行速度更快一些。默认值为 ``AllReduce`` 。 + + + + + + + + +英文版API文档: :ref:`api_fluid_BuildStrategy` + +.. _cn_api_fluid_CPUPlace: + +CPUPlace +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.CPUPlace + + + + +英文版API文档: :ref:`api_fluid_CPUPlace` + +.. _cn_api_fluid_create_lod_tensor: + + +create_lod_tensor +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.create_lod_tensor(data, recursive_seq_lens, place) + + +该函数从一个numpy数组，列表或者已经存在的lod tensor中创建一个lod tensor。 +通过一下几步实现: + 1. 检查length-based level of detail (LoD,长度为基准的细节层次)，或称recursive_sequence_lengths(递归序列长度)的正确性 + 2. 将recursive_sequence_lengths转化为offset-based LoD(偏移量为基准的LoD) + 3. 把提供的numpy数组，列表或者已经存在的lod tensor复制到CPU或GPU中(依据执行场所确定) + 4. 利用offset-based LoD来设置LoD +例如： + 假如我们想用LoD Tensor来承载一词序列的数据，其中每个词由一个整数来表示。现在，我们意图创建一个LoD Tensor来代表两个句子，其中一个句子有两个词，另外一个句子有三个。 + 那么数据可以是一个numpy数组，形状为（5,1）。同时， ``recursive_seq_lens`` 为 [[2, 3]]，表明各个句子的长度。这个长度为基准的 ``recursive_seq_lens`` 将在函数中会被转化为以偏移量为基准的 LoD [[0, 2, 5]]。 + +参数: + - **data** (numpy.ndarray|list|LoDTensor) – 容纳着待复制数据的一个numpy数组、列表或LoD Tensor + - **recursive_seq_lens** (list) – 一组列表的列表， 表明了由用户指明的length-based level of detail信息 + - **place** (Place) – CPU或GPU。 指明返回的新LoD Tensor存储地点 + +返回: 一个fluid LoDTensor对象，包含数据和 ``recursive_seq_lens`` 信息 + + + + + + + +英文版API文档: :ref:`api_fluid_create_lod_tensor` + +.. _cn_api_fluid_create_random_int_lodtensor: + + +create_random_int_lodtensor +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.create_random_int_lodtensor(recursive_seq_lens, base_shape, place, low, high) + + + +该函数创建一个存储多个随机整数的LoD Tensor。 + +该函数是经常在书中出现的案例，所以我们根据新的API： ``create_lod_tensor`` 更改它然后放在LoD Tensor板块里来简化代码。 + +该函数实现以下功能： + + 1. 根据用户输入的length-based ``recursive_seq_lens`` （基于长度的递归序列长）和在 ``basic_shape`` 中的基本元素形状计算LoDTensor的整体形状 + 2. 由此形状，建立numpy数组 + 3. 使用API： ``create_lod_tensor`` 建立LoDTensor + + +假如我们想用LoD Tensor来承载一词序列，其中每个词由一个整数来表示。现在，我们意图创建一个LoD Tensor来代表两个句子，其中一个句子有两个词，另外一个句子有三个。那么 ``base_shape`` 为[1], 输入的length-based ``recursive_seq_lens`` 是 [[2, 3]]。那么LoDTensor的整体形状应为[5, 1]，并且为两个句子存储5个词。 + +参数: + - **recursive_seq_lens** (list) – 一组列表的列表， 表明了由用户指明的length-based level of detail信息 + - **base_shape** (list) – LoDTensor所容纳的基本元素的形状 + - **place** (Place) – CPU或GPU。 指明返回的新LoD Tensor存储地点 + - **low** (int) – 随机数下限 + - **high** (int) – 随机数上限 + +返回: 一个fluid LoDTensor对象，包含数据和 ``recursive_seq_lens`` 信息 + + + + + + + + + +英文版API文档: :ref:`api_fluid_create_random_int_lodtensor` + +.. _cn_api_fluid_CUDAPinnedPlace: + +CUDAPinnedPlace +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.CUDAPinnedPlace + + + + + + + + +英文版API文档: :ref:`api_fluid_CUDAPinnedPlace` + +.. _cn_api_fluid_CUDAPlace: + +CUDAPlace +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.CUDAPlace + + + + +英文版API文档: :ref:`api_fluid_CUDAPlace` + +.. _cn_api_fluid_DataFeedDesc: + +DataFeedDesc +>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.DataFeedDesc(proto_file) + +数据描述符，描述输入训练数据格式。 + +这个类目前只用于AsyncExecutor(有关类AsyncExecutor的简要介绍，请参阅注释) + +DataFeedDesc应由来自磁盘的有效protobuf消息初始化: + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + +可以参考 :code:`paddle/fluid/framework/data_feed.proto` 查看我们如何定义message + +一段典型的message可能是这样的： + +.. code-block:: text + + name: "MultiSlotDataFeed" + batch_size: 2 + multi_slot_desc { + slots { + name: "words" + type: "uint64" + is_dense: false + is_used: true + } + slots { + name: "label" + type: "uint64" + is_dense: false + is_used: true + } + } + +但是，用户通常不应该关心消息格式;相反，我们鼓励他们在将原始日志文件转换为AsyncExecutor可以接受的训练文件的过程中，使用 :code:`Data Generator` 生成有效数据描述。 + +DataFeedDesc也可以在运行时更改。一旦你熟悉了每个字段的含义，您可以修改它以更好地满足您的需要。例如: + +.. code-block:: text + + data_feed.set_batch_size(128) + data_feed.set_dense_slots('wd') # The slot named 'wd' will be dense + data_feed.set_use_slots('wd') # The slot named 'wd' will be used + + #Finally, the content can be dumped out for debugging purpose: + + print(data_feed.desc()) + +参数： + - **proto_file** (string) - 包含数据feed中描述的磁盘文件 + + +.. py:method:: set_batch_size(self, batch_size) + +设置batch size，训练期间有效 + + +参数： + - batch_size：batch size + +**代码示例：** + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + data_feed.set_batch_size(128) + +.. py:method:: set_dense_slots(self, dense_slots_name) + +指定slot经过设置后将变成密集的slot，仅在训练期间有效。 + +密集slot的特征将被输入一个Tensor，而稀疏slot的特征将被输入一个lodTensor + + +参数： + - **dense_slots_name** : slot名称的列表，这些slot将被设置为密集的 + +**代码示例：** + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + data_feed.set_dense_slots(['words']) + +.. note:: + + 默认情况下，所有slot都是稀疏的 + +.. py:method:: set_use_slots(self, use_slots_name) + + +设置一个特定的slot是否用于训练。一个数据集包含了很多特征，通过这个函数可以选择哪些特征将用于指定的模型。 + +参数： + - **use_slots_name** :将在训练中使用的slot名列表 + +**代码示例：** + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + data_feed.set_use_slots(['words']) + +.. note:: + + 默认值不用于所有slot + + +.. py:method:: desc(self) + +返回此DataFeedDesc的protobuf信息 + +返回：一个message字符串 + +**代码示例：** + +.. code-block:: python + + data_feed = fluid.DataFeedDesc('data.proto') + print(data_feed.desc()) + + +英文版API文档: :ref:`api_fluid_DataFeedDesc` + +.. _cn_api_fluid_DataFeeder: + +DataFeeder +>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.DataFeeder(feed_list, place, program=None) + + + +``DataFeeder`` 负责将reader(读取器)返回的数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。 +reader通常返回一个minibatch条目列表。在列表中每一条目都是一个样本（sample）,它是由具有一至多个特征的列表或元组组成的。 + + +以下是简单用法： + +.. code-block:: python + + place = fluid.CPUPlace() + img = fluid.layers.data(name='image', shape=[1, 28, 28]) + label = fluid.layers.data(name='label', shape=[1], dtype='int64') + feeder = fluid.DataFeeder([img, label], fluid.CPUPlace()) + result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])]) + +在多GPU模型训练时，如果需要提前分别向各GPU输入数据，可以使用 ``decorate_reader`` 函数。 + +.. code-block:: python + + place=fluid.CUDAPlace(0) + feeder = fluid.DataFeeder(place=place, feed_list=[data, label]) + reader = feeder.decorate_reader( + paddle.batch(flowers.train(), batch_size=16)) + + + +参数： + - **feed_list** (list) – 向模型输入的变量表或者变量表名 + - **place** (Place) – place表明是向GPU还是CPU中输入数据。如果想向GPU中输入数据, 请使用 ``fluid.CUDAPlace(i)`` (i 代表 the GPU id)；如果向CPU中输入数据, 请使用 ``fluid.CPUPlace()`` + - **program** (Program) – 需要向其中输入数据的Program。如果为None, 会默认使用 ``default_main_program()``。 缺省值为None + + +弹出异常: ``ValueError`` – 如果一些变量不在此 Program 中 + + +**代码示例** + +.. code-block:: python + + # ... + place = fluid.CPUPlace() + feed_list = [ + main_program.global_block().var(var_name) for var_name in feed_vars_name + ] # feed_vars_name 是一个由变量名组成的列表 + feeder = fluid.DataFeeder(feed_list, place) + for data in reader(): + outs = exe.run(program=main_program, + feed=feeder.feed(data)) + + +.. py:method:: feed(iterable) + + +根据feed_list（数据输入表）和iterable（可遍历的数据）提供的信息，将输入数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。 + +参数: + - **iterable** (list|tuple) – 要输入的数据 + +返回： 转换结果 + +返回类型: dict + + +.. py:method:: feed_parallel(iterable, num_places=None) + + +该方法获取的多个minibatch，并把每个minibatch提前输入进各个设备中。 + +参数: + - **iterable** (list|tuple) – 要输入的数据 + - **num_places** (int) – 设备数目。默认为None。 + +返回: 转换结果 + +返回类型: dict + +**特别注意：** 设备（CPU或GPU）的数目必须等于minibatch的数目 + + + +.. py:method:: decorate_reader(reader, multi_devices, num_places=None, drop_last=True) + + + +将reader返回的输入数据batch转换为多个mini-batch，之后每个mini-batch都会被输入进各个设备（CPU或GPU）中。 + +参数： + - **reader** (fun) – 待输入的数据 + - **multi_devices** (bool) – 执行场所的数目，默认为None + - **num_places** (int) – 执行场所的数目，默认为None + - **drop_last** (bool) – 舍弃数目匹配不上的batch或设备 + +返回：转换结果 + +返回类型: dict + +弹出异常： ``ValueError`` – 如果 ``drop_last`` 值为False并且reader返回的minibatch数目与设备数目不相等时，产生此异常 + + + + + + + + +英文版API文档: :ref:`api_fluid_DataFeeder` + +.. _cn_api_fluid_default_main_program: + +default_main_program +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.default_main_program() + + + + + +此函数用于获取默认或全局main program(主程序)。该主程序用于训练和测试模型。 + +``fluid.layers`` 中的所有layer函数可以向 ``default_main_program`` 中添加operators（算子）和variables（变量）。 + +``default_main_program`` 是fluid的许多编程接口（API）的Program参数的缺省值。例如,当用户program没有传入的时候， +``Executor.run()`` 会默认执行 ``default_main_program`` 。 + + +返回： main program + +返回类型: Program + + + + + + + +英文版API文档: :ref:`api_fluid_default_main_program` + +.. _cn_api_fluid_default_startup_program: + + + + +default_startup_program +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.default_startup_program() + + + +该函数可以获取默认/全局 startup program (启动程序)。 + +``fluid.layers`` 中的layer函数会新建参数、readers(读取器)、NCCL句柄作为全局变量。 + +startup_program会使用内在的operators（算子）去初始化他们，并由layer函数将这些operators追加到startup program中。 + +该函数将返回默认的或当前的startup_program。用户可以使用 ``fluid.program_guard`` 去切换program。 + +返回: startup program + +返回类型: Program + + + + + + + +英文版API文档: :ref:`api_fluid_default_startup_program` + +.. _cn_api_fluid_DistributeTranspiler: + +DistributeTranspiler +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.DistributeTranspiler (config=None) + + +该类可以把fluid program转变为分布式数据并行计算程序（distributed data-parallelism programs）,可以有Pserver和NCCL2两种模式。 +当program在Pserver（全称：parameter server）模式下， ``main_program`` (主程序)转为使用一架远程parameter server(即pserver,参数服务器)来进行参数优化，并且优化图会被输入到一个pserver program中。 +在NCCL2模式下，transpiler会在 ``startup_program`` 中附加一个 ``NCCL_ID`` 广播算子（broadcasting operators）来实现在该集群中所有工作结点共享 ``NCCL_ID`` 。 +调用 ``transpile_nccl2`` 后， 你 **必须** 将 ``trainer_id`` , ``num_trainers`` 参数提供给 ``ParallelExecutor`` 来启动NCCL2分布式模式。 + + + + +**代码示例** + +.. code-block:: python + + #pserver模式下 + pserver_endpoints = "192.168.0.1:6174,192.168.0.2:6174" + trainer_endpoints = "192.168.0.1:6174,192.168.0.2:6174" + current_endpoint = "192.168.0.1:6174" + trainer_id = 0 + trainers = 4 + role = os.getenv("PADDLE_TRAINING_ROLE") + + t = fluid.DistributeTranspiler() + t.transpile( + trainer_id, pservers=pserver_endpoints, trainers=trainers) + if role == "PSERVER": + pserver_program = t.get_pserver_program(current_endpoint) + pserver_startup_program = t.get_startup_program(current_endpoint, + pserver_program) + elif role == "TRAINER": + trainer_program = t.get_trainer_program() + + # nccl2模式下 + config = fluid.DistributeTranspilerConfig() + config.mode = "nccl2" + t = fluid.DistributeTranspiler(config=config) + t.transpile(trainer_id, workers=workers, current_endpoint=curr_ep) + exe = fluid.ParallelExecutor( + use_cuda, + loss_name=loss_var.name, + num_trainers=len(trainers.split(",)), + trainer_id=trainer_id + ) + + + +.. py:method:: transpile(trainer_id, program=None, pservers='127.0.0.1:6174', trainers=1, sync_mode=True, startup_program=None, current_endpoint='127.0.0.1:6174') + +该方法可以运行该transpiler（转译器）。 + +参数: + - **trainer_id** (int) – 当前Trainer worker的id, 如果有n个Trainer worker, id 取值范围为0 ~ n-1 + - **program** (Program|None) – 待transpile（转译）的program, 缺省为 ``fluid.default_main_program()`` + - **pservers** (str) – 内容为Pserver列表的字符串，格式为：按逗号区分不同的Pserver，每个Pserver的格式为 *ip地址:端口号* + - **trainers** (int|str) – 在Pserver模式下，该参数指Trainer机的个数；在nccl2模式下，它是一个内容为Trainer终端列表的字符串 + - **sync_mode** (bool) – 是否做同步训练(synchronous training), 默认为True + - **startup_program** (Program|None) – 待transpile（转译）的startup_program，默认为 ``fluid.default_main_program()`` + - **current_endpoint** (str) – 当需要把program转译（transpile）至NCCL2模式下时，需要将当前endpoint（终端）传入该参数。Pserver模式不使用该参数 + +.. py:method:: get_trainer_program(wait_port=True) + + +该方法可以得到Trainer侧的program。 + +返回: Trainer侧的program + +返回类型: Program + + + +.. py:method:: get_pserver_program(endpoint) + + +该方法可以得到Pserver（参数服务器）侧的程序 + +参数: + - **endpoint** (str) – 当前Pserver终端 + +返回: 当前Pserver需要执行的program + +返回类型: Program + + +.. py:method:: get_pserver_programs(endpoint) + + +该方法可以得到Pserver侧用于分布式训练的 ``main_program`` 和 ``startup_program`` 。 + +参数: + - **endpoint** (str) – 当前Pserver终端 + +返回: (main_program, startup_program), “Program”类型的元组 + +返回类型: tuple + + +.. py:method:: get_startup_program(endpoint, pserver_program=None, startup_program=None) + + +**该函数已停止使用** +获取当前Pserver的startup_program，如果有多个被分散到不同blocks的变量，则修改operator的输入变量。 + +参数: + - **endpoint** (str) – 当前Pserver终端 + - **pserver_program** (Program) – 已停止使用。 先调用get_pserver_program + - **startup_program** (Program) – 已停止使用。应在初始化时传入startup_program + +返回: Pserver侧的startup_program + +返回类型: Program + + + + + +英文版API文档: :ref:`api_fluid_DistributeTranspiler` + +.. _cn_api_fluid_DistributeTranspilerConfig: + +DistributeTranspilerConfig +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.DistributeTranspilerConfig + + +.. py:attribute:: slice_var_up (bool) + +为多个Pserver（parameter server）将tensor切片, 默认为True。 + +.. py:attribute:: split_method (PSDispatcher) + +可使用 RoundRobin 或者 HashName。 + +注意: 尝试选择最佳方法来达到Pserver间负载均衡。 + +.. py:attribute:: min_block_size (int) + +最小数据块的大小 + +注意: 根据：`issuecomment-369912156 `_ , 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看 ``slice_variable`` 函数。 + + + +英文版API文档: :ref:`api_fluid_DistributeTranspilerConfig` + +.. _cn_api_fluid_ExecutionStrategy: + +ExecutionStrategy +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.ExecutionStrategy + +``ExecutionStrategy`` 允许用户更加精准地控制program在 ``ParallelExecutor`` 中的运行方式。可以通过在 ``ParallelExecutor`` 中设置本成员来实现。 + +**代码示例** + +.. code-block:: python + + exec_strategy = fluid.ExecutionStrategy() + exec_strategy.num_threads = 4 + + train_exe = fluid.ParallelExecutor(use_cuda=True, + loss_name=loss.name, + exec_strategy=exec_strategy) + + train_loss, = train_exe.run([loss.name], feed=feed_dict) + + + +.. py:attribute:: allow_op_delay + +这是一个bool类型成员，表示是否推迟communication operators(交流运算)的执行，这样做会使整体执行过程更快一些。但是在一些模型中，allow_op_delay会导致程序中断。默认为False。 + + + +.. py:attribute:: num_iteration_per_drop_scope + +int型成员。它表明了清空执行时产生的临时变量需要的程序执行重复次数。因为临时变量的形可能在两次重复过程中保持一致，所以它会使整体执行过程更快。默认值为100。 + +.. note:: + 1. 如果在调用 ``run`` 方法时获取结果数据，``ParallelExecutor`` 会在当前程序重复执行尾部清空临时变量 + + 2. 在一些NLP模型里，该成员会致使GPU内存不足。此时，你应减少 ``num_iteration_per_drop_scope`` 的值 + + + +.. py:attribute:: num_threads + +int型成员。它代表了线程池(thread pool)的大小。这些线程会被用来执行当前 ``ParallelExecutor`` 的program中的operator（算子，运算）。如果 :math:`num\_threads=1` ，则所有的operator将一个接一个地执行，但在不同的程序重复周期(iterations)中执行顺序可能不同。如果该成员没有被设置，则在 ``ParallelExecutor`` 中，它会依据设备类型(device type)、设备数目(device count)而设置为相应值。对GPU，:math:`num\_threads=device\_count∗4` ；对CPU， :math:`num\_threads=CPU\_NUM∗4` 。在 ``ParallelExecutor`` 中有关于 :math:`CPU\_NUM` 的详细解释。如果没有设置 :math:`CPU\_NUM` ， ``ParallelExecutor`` 可以通过调用 ``multiprocessing.cpu_count()`` 获取CPU数目(cpu count)。默认值为0。 + + + + + + + + +英文版API文档: :ref:`api_fluid_ExecutionStrategy` + +.. _cn_api_fluid_executor: + +Executor +>>>>>>>>>>>>>>>>>>>>> + + +.. py:class:: paddle.fluid.Executor (place) + + + + +执行引擎（Executor）使用python脚本驱动，仅支持在单GPU环境下运行。多卡环境下请参考 ``ParallelExecutor`` 。 +Python Executor可以接收传入的program,并根据feed map(输入映射表)和fetch_list(结果获取表) +向program中添加feed operators(数据输入算子)和fetch operators（结果获取算子)。 +feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。 + +应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。 + +Executor将全局变量存储到全局作用域中，并为临时变量创建局部作用域。 +当每一mini-batch上的前向/反向运算完成后，局部作用域的内容将被废弃， +但全局作用域中的变量将在Executor的不同执行过程中一直存在。 + +program中所有的算子会按顺序执行。 + +参数: + - **place** (core.CPUPlace|core.CUDAPlace(n)) – 指明了 ``Executor`` 的执行场所 + + + +提示：你可以用 ``Executor`` 来调试基于并行GPU实现的复杂网络，他们有完全一样的参数也会产生相同的结果。 + + +.. py:method:: close() + + +关闭这个执行器(Executor)。调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上涉及到目前训练器的资源。 + +**示例代码** + +.. code-block:: python + + cpu = core.CPUPlace() + exe = Executor(cpu) + ... + exe.close() + + +.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True,use_program_cache=False) + + +调用该执行器对象的此方法可以执行program。通过feed map提供待学习数据，以及借助fetch_list得到相应的结果。 +Python执行器(Executor)可以接收传入的program,并根据输入映射表(feed map)和结果获取表(fetch_list) +向program中添加数据输入算子(feed operators)和结果获取算子（fetch operators)。 +feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。 + +应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。 + +参数： + - **program** (Program) – 需要执行的program,如果没有给定那么默认使用default_main_program + - **feed** (dict) – 前向输入的变量，数据,词典dict类型, 例如 {“image”: ImageData, “label”: LableData} + - **fetch_list** (list) – 用户想得到的变量或者命名的列表, run会根据这个列表给与结果 + - **feed_var_name** (str) – 前向算子(feed operator)变量的名称 + - **fetch_var_name** (str) – 结果获取算子(fetch operator)的输出变量名称 + - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。缺省为全局域 + - **return_numpy** (bool) – 如果为True,则将结果张量（fetched tensor）转化为numpy + - **use_program_cache** (bool) – 当program较上次比没有改动则将其置为True + +返回: 根据fetch_list来获取结果 + +返回类型: list(numpy.array) + + +**示例代码** + +.. code-block:: python + + + data = layers.data(name='X', shape=[1], dtype='float32') + hidden = layers.fc(input=data, size=10) + layers.assign(hidden, out) + loss = layers.mean(out) + adam = fluid.optimizer.Adam() + adam.minimize(loss) + + +.. code-block:: python + + + cpu = core.CPUPlace() + exe = Executor(cpu) + exe.run(default_startup_program()) + +.. code-block:: python + + x = numpy.random.random(size=(10, 1)).astype('float32') + outs = exe.run( + feed={'X': x}, + fetch_list=[loss.name]) + + + + + + + + + +英文版API文档: :ref:`api_fluid_executor` + +.. _cn_api_fluid_fluid_Tensor: + +Tensor +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.Tensor + + ``LoDTensor`` 的别名 + + + + +英文版API文档: :ref:`api_fluid_fluid_Tensor` + +.. _cn_api_fluid_global_scope: + +global_scope +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.global_scope() + + +获取全局/默认作用域实例。很多api使用默认 ``global_scope`` ，例如 ``Executor.run`` 。 + +返回：全局/默认作用域实例 + +返回类型：Scope + + + +英文版API文档: :ref:`api_fluid_global_scope` + +.. _cn_api_fluid_LoDTensor: + +LoDTensor +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.LoDTensor + + +LoDTensor是一个具有LoD信息的张量(Tensor) + + ``np.array(lod_tensor)`` 可以将LoDTensor转换为numpy array。 ``lod_tensor.lod()`` 可以获得LoD信息。 +LoD是多层序列（Level of Details）的缩写，通常用于不同长度的序列。如果您不需要了解LoD信息，可以跳过下面的注解。 + +举例: + +X 为 LoDTensor，它包含两个序列。第一个长度是2，第二个长度是3。 + +从Lod中可以计算出X的第一维度为5， 因为5=2+3， 说明X中有5个序列。在X中的每个序列中的每个元素有2列，因此X的shape为[5,2]。 + +:: + + x.lod = [[2, 3]] + x.data = [[1, 2], [3, 4], // seq 1 + + [5, 6], [7, 8], [9, 10]] // seq 2 + + x.shape = [5, 2] + + +LoD可以有多个level(例如，一个段落可以有多个句子，一个句子可以有多个单词)。下面的例子中，Y为LoDTensor ，lod_level为2。表示有2个序列，第一个序列的长度是2(有2个子序列)，第二个序列的长度是1。第一序列的两个子序列长度分别为2和2。第二个序列的子序列的长度是3。 + + +:: + + y.lod = [[2 1], [2 2 3]] y.shape = [2+2+3, ...] + + +.. note:: + + 在上面的描述中，LoD是基于长度的。在paddle内部实现中，lod是基于偏移的。因此,在内部,y.lod表示为[[0,2,3]，[0,2,4,7]](基于长度的Lod表示为为[[2-0,3-2]，[2-0,4-2,7-4]])。 + + 可以将LoD理解为recursive_sequence_length（递归序列长度）。此时，LoD必须是基于长度的。由于历史原因。当LoD在API中被称为lod时，它可能是基于偏移的。用户应该注意。 + + + + +.. py:method:: has_valid_recursive_sequence_lengths(self: paddle.fluid.core.LoDTensor) → bool + +.. py:method:: lod(self: paddle.fluid.core.LoDTensor) → List[List[int]] + +.. py:method:: recursive_sequence_lengths(self: paddle.fluid.core.LoDTensor) → List[List[int]] + +.. py:method:: set_lod(self: paddle.fluid.core.LoDTensor, arg0: List[List[int]]) → None + +.. py:method:: set_recursive_sequence_lengths(self: paddle.fluid.core.LoDTensor, arg0: List[List[int]]) → None + + + + + + + +英文版API文档: :ref:`api_fluid_LoDTensor` + +.. _cn_api_fluid_LoDTensorArray: + +LoDTensorArray +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.LoDTensorArray + +.. py:method:: append(self: paddle.fluid.core.LoDTensorArray, arg0: paddle.fluid.core.LoDTensor) → None + + + + + +英文版API文档: :ref:`api_fluid_LoDTensorArray` + +.. _cn_api_fluid_memory_optimize: + +memory_optimize +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.memory_optimize(input_program, skip_opt_set=None, print_log=False, level=0, skip_grads=False) + + +通过重用var内存来优化内存。 + +注意:它不支持block中嵌套子block。 + +参数: + - **input_program** (str) – 输入Program。 + - **skip_opt_set** (set) – set中的vars将不被内存优化。 + - **print_log** (bool) – 是否打印debug日志。 + - **level** (int) 如果 level=0 并且shape是完全相等，则重用。 + +返回: None + + + + +英文版API文档: :ref:`api_fluid_memory_optimize` + +.. _cn_api_fluid_name_scope: + +name_scope +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.name_scope(*args, **kwds) + + +为operators生成层次名称前缀 + +注意： 这个函数只能用于调试和可视化。不要将其用于分析，比如graph/program转换。 + +参数： + - **prefix** (str) - 前缀 + +**示例代码** + +.. code-block:: python + + with name_scope("encoder"): + ... + with name_scope("decoder"): + ... + with name_scope("attention"): + ... + + + +英文版API文档: :ref:`api_fluid_name_scope` + +.. _cn_api_fluid_ParallelExecutor: + +ParallelExecutor +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.ParallelExecutor(use_cuda, loss_name=None, main_program=None, share_vars_from=None, exec_strategy=None, build_strategy=None, num_trainers=1, trainer_id=0, scope=None) + + + + +``ParallelExecutor`` 专门设计用来实现数据并行计算，着力于向不同结点(node)分配数据，并行地在不同结点中对数据进行操作。如果在GPU上使用该类运行程序，node则用来指代GPU， ``ParallelExecutor`` 也将自动获取在当前机器上可用的GPU资源。如果在CPU上进行操作，node则指代CPU，同时你也可以通过添加环境变量 ``CPU_NUM`` 来设置CPU设备的个数。例如，``CPU_NUM=4``。但是如果没有设置该环境变量，该类会调用 ``multiprocessing.cpu_count`` 来获取当前系统中CPU的个数。 + + + + +参数: + - **use_cuda** (bool) – 是否使用CUDA + - **loss_name** (str) – 在训练阶段，必须提供loss function名称。默认为None + - **main_program** (Program) – 需要执行的program。如果未提供， 那么将使用 ``default_main_program``。 默认为None + - **share_vars_from** (ParallelExecutor) – 如果提供了该参数， 则该 ``ParallelExecutor`` 与指定的 ``ParallelExecutor`` 共享变量。默 认为空 + - **exec_strategy** (ExecutionStrategy) – ``exec_strategy`` 用于调控program在 ``ParallelExecutor`` 中的执行方式，例如，执行该program需要的线程数, 释放在执行过程中产生的临时变量需要的重复(iterations)次数。 请参考 ``fluid.ExecutionStrategy`` 获取详细介绍。该参数默认为 None + - **build_strategy** (BuildStrategy) – 设置成员 ``build_strategy`` 可以控制在 ``ParallelExecutor`` 中搭建SSA Graph的方式，例如， ``reduce_strategy`` ， ``gradient_scale_strategy`` 。 请参考 ``fluid.BuildStrategy`` 获取详细介绍。 该参数默认为None + - **num_trainers** (int) – 如果该值大于1， NCCL将会通过多层级node的方式来初始化。每个node应有相同的GPU数目。 随之会启用分布式训练。该参数默认为1 + - **trainer_id** (int) – 必须与 ``num_trainers`` 参数同时使用。``trainer_id`` 是当前所在node的 “rank”（层级），从0开始计数。该参数默认为0 + - **scope** (Scope) – 指定执行program所在的作用域， 默认使用 ``fluid.global_scope()`` + +返回：初始化后的 ``ParallelExecutor`` 对象 + +返回类型: ParallelExecutor + +弹出异常：``TypeError`` - 如果提供的参数 ``share_vars_from`` 不是 ``ParallelExecutor`` 类型的，将会弹出此异常 + +**代码示例** + +.. code-block:: python + + train_exe = fluid.ParallelExecutor(use_cuda=True, loss_name=loss.name) + test_exe = fluid.ParallelExecutor(use_cuda=True, + main_program=test_program, + share_vars_from=train_exe) + + train_loss, = train_exe.run([loss.name], feed=feed_dict) + test_loss, = test_exe.run([loss.name], feed=feed_dict) + + + +.. py:method:: run(fetch_list, feed=None, feed_dict=None, return_numpy=True) + +使用 ``fetch_list`` 执行一个 ``ParallelExecutor`` 对象。 + +参数 ``feed`` 可以是 ``dict`` 或者 ``list`` 类型变量。如果该参数是 ``dict`` 类型，feed中的数据将会被分割(split)并分送给多个设备（CPU/GPU）。 +反之，如果它是 ``list`` ，则列表中的各个元素都会直接分别被拷贝到各设备中。 + +例如，如果 ``feed`` 是个 ``dict`` 类型变量，则有 + +.. code-block:: python + + exe = ParallelExecutor() + # 图像会被split到设备中。假设有两个设备，那么每个设备将会处理形为 (24, 1, 28, 28)的图像 + exe.run(feed={'image': numpy.random.random(size=(48, 1, 28, 28))}) + +如果 ``feed`` 是个 ``list`` 类型变量，则有 + +.. code-block:: python + + exe = ParallelExecutor() + # 各设备挨个处理列表中的每个元素 + # 第一个设备处理形为 (48, 1, 28, 28) 的图像 + # 第二个设备处理形为 (32, 1, 28, 28) 的图像 + # + # 使用 exe.device_count 得到设备数目 + exe.run(feed=[{"image": numpy.random.random(size=(48, 1, 28, 28))}, + {"image": numpy.random.random(size=(32, 1, 28, 28))}, + ]) + +参数： + - **fetch_list** (list) – 获取的变量名列表 + - **feed** (list|dict|None) – feed变量。 如果该参数是 ``dict`` 类型，feed中的数据将会被分割(split)并分送给多个设备（CPU/GPU）。反之，如果它是 ``list`` ，则列表中的各个元素都直接分别被拷贝到各设备中。默认为None + - **feed_dict** – 该参数已经停止使用。feed参数的别名, 为向后兼容而立。默认为None + - **return_numpy** (bool) – 是否将fetched tensor转换为numpy。默认为True + +返回： 获取的结果列表 + +返回类型：List + +弹出异常： + ``ValueError`` - 如果feed参数是list类型，但是它的长度不等于可用设备（执行场所）的数目，再或者给定的feed不是dict类型，弹出此异常 + + ``TypeError`` - 如果feed参数是list类型，但是它里面的元素不是dict类型时，弹出此异常 + +额外注意： + 1.如果feed参数为dict类型，那么传入 ``ParallelExecutor`` 的数据量 *必须* 大于可用的执行场所数目。否则，C++端将会弹出异常。应额外注意核对数据集的最后一个batch是否比可用执行场所数目大。 + + 2.如果可用执行场所大于一个，则为每个变量最后获取的结果都是list类型，且这个list中的每个元素都是各个可用执行场所的变量 + +**代码示例** + +.. code-block:: python + + pe = fluid.ParallelExecutor(use_cuda=use_cuda, + loss_name=avg_cost.name, + main_program=fluid.default_main_program()) + loss = pe.run(feed=feeder.feed(cur_batch), + fetch_list=[avg_cost.name])) + + + + + +英文版API文档: :ref:`api_fluid_ParallelExecutor` + +.. _cn_api_fluid_ParamAttr: + + +ParamAttr +>>>>>>>>>>>>>>>>>>>>>>>>> + + +.. py:class:: paddle.fluid.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) – 参数的学习率。计算方法为 :math:`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) + + + + + + + + + +英文版API文档: :ref:`api_fluid_ParamAttr` + +.. _cn_api_fluid_Program: + +Program +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.Program + + +创建python program， 在paddleFluid内部会被转换为ProgramDesc描述语言，是被用来创建c++ Program。Program像容器一样也是一种独立的程序语言。Program包括至少一个块（Block），控制流比如conditional_block包括while_op，该Program将会含有嵌套块（nested block）。详情请参阅framework.proto。 + +注意：默认情况下，paddleFluid内部默认含有 ``default_startup_program`` 和 ``default_main_program`` ，它们将共享参数。 ``default_startup_program`` 只运行一次来初始化参数， ``default_main_program`` 在每个mini batch中运行并调整权重。 + +返回： empty program + +**代码示例** + +.. code-block:: python + + main_program = fluid.Program() + startup_program = fluid.Program() + with fluid.program_guard(main_program=main_program, startup_program=startup_program): + fluid.layers.data(name="x", shape=[-1, 784], dtype='float32') + fluid.layers.data(name="y", shape=[-1, 1], dtype='int32') + fluid.layers.fc(name="fc", shape=[10], dtype='float32', act="relu") + + + +.. py:attribute:: op_role + +operator的角色，值只能是枚举变量{Forward, Backward, Optimize}。 + +注意：这是一个底层API。它仅用于 ``ParallelExecutor`` 复制或调度operator到设备。 + +例如，Forward operator应该在每个设备上执行。Backward operator在每个设备上执行，并将后向传播的参数梯度(使用 ``op_role_var`` 获得该变量)合并到一个设备上。Optimize operator只在一个设备上执行，并向其他设备广播新的参数， + + + +.. py:attribute:: set_op_role + +operator的角色，值只能是枚举变量{Forward, Backward, Optimize}。 + +注意：这是一个底层API。它仅用于 ``ParallelExecutor`` 复制或调度operator到设备上执行。 + +例如，Forward operator应该在每个设备上执行。Backward operato应该在每个设备上执行，并将后向传播的参数梯度(使用op_role_var获得该变量)合并到一个设备上。Optimize operator只在一个设备上执行，并向其他设备广播新的参数 + + + +.. py:attribute:: op_role_var + +``op_role`` 的辅助变量。 + +参考: ``Program.op_role`` 文档。 + +注意:这是一个底层API，用户不应该直接使用它。 + + + +.. py:attribute:: set_op_role_var + +``op_role`` 的辅助变量。 + +参考: ``Program.op_role`` 文档。 + +注意:这是一个底层API。用户不应该直接使用它。 + + + +.. py:method:: to_string(throw_on_error, with_details=False) + +用于debug + +参数： + - **throw_on_error** (bool): 没有设置任何必需的字段时，抛出值错误。 + - **with_details** (bool): 值为true时，打印更多关于变量和参数的信息，如trainable, optimize_attr等 + +返回：(str): debug 字符串 + +抛出异常： ``ValueError`` - 当 ``throw_on_error == true`` ，但没有设置任何必需的字段时，抛出 ``ValueError`` 。 + + + +.. py:method:: clone(for_test=False) + +创建一个新的、相同的Program。 + +有些operator，在训练和测试之间的行为是不同的，比如batch_norm。它们有一个属性is_test来控制行为。当for_test=True时，此方法将把它们的is_test属性更改为True。 + +- 克隆Program，该Program用于训练时，将 ``for_test`` 设置为False。 +- 克隆Program，该Program用于测试时，将 ``for_test`` 设置为True。 + +注意:此API不会删除任何操作符。请在backward和optimization之前使用clone(for_test=True)。 + +**代码示例** + +.. code-block:: python + + test_program = fluid.default_main_program().clone(for_test=True) + optimizer = fluid.optimizer.Momentum(learning_rate=0.01, momentum=0.9) + optimizer.minimize() + +参数： + - **for_test** (bool) – 取值为True时，clone方法内部会把operator的属性 ``is_test`` 设置为 True + +返回：一个新的、相同的Program + +返回类型:Program + +**代码示例** + +1.克隆一个Program，示例代码如下： + +.. code-block:: python + + train_program = fluid.Program() + startup_program = fluid.Program() + with fluid.program_guard(train_program, startup_program): + img = fluid.layers.data(name='image', shape=[784]) + hidden = fluid.layers.fc(input=img, size=200, act='relu') + hidden = fluid.layers.dropout(hidden, dropout_prob=0.5) + loss = fluid.layers.cross_entropy( + input=fluid.layers.fc(hidden, size=10, act='softmax'), + label=fluid.layers.data(name='label', shape=[1], dtype='int64')) + test_program = train_program.clone(for_test=True) + sgd = fluid.optimizer.SGD(learning_rate=1e-3) + with fluid.program_guard(train_program, startup_program): + sgd.minimize(loss) + +2.如果分别运行 train Program 和 test Program，则可以不使用clone。 + +.. code-block:: python + + import paddle.fluid as fluid + + def network(is_test): + img = fluid.layers.data(name='image', shape=[784]) + hidden = fluid.layers.fc(input=img, size=200, act='relu') + hidden = fluid.layers.dropout(hidden, dropout_prob=0.5, is_test=is_test) + loss = fluid.layers.cross_entropy( + input=fluid.layers.fc(hidden, size=10, act='softmax'), + label=fluid.layers.data(name='label', shape=[1], dtype='int64')) + return loss + + train_program = fluid.Program() + startup_program = fluid.Program() + test_program = fluid.Program() + + with fluid.program_guard(train_program, startup_program): + with fluid.unique_name.guard(): + loss = network(is_test=False) + sgd = fluid.optimizer.SGD(learning_rate=1e-3) + sgd.minimize(loss) + + # 不使用测试阶段的startup program + with fluid.program_guard(test_program, fluid.Program()): + with fluid.unique_name.guard(): + loss = network(is_test=True) + +上边两个代码片段生成的Program是一样的。 + +.. py:staticmethod:: parse_from_string(binary_str) + +反序列化protobuf，转换成program + +注意:在序列化和反序列化之后，所有关于参数的信息都会丢失。 + +参数: + - **binary_str_type** (str) – prootbuf二进制字符串 + +返回: 反序列化后的ProgramDesc + +返回类型：Program + +.. py:attribute:: num_blocks + +该program中的block的个数 + +.. py:attribute:: random_seed + + +程序中随机运算符的默认随机种子。0意味着从随机设备中获取随机种子。 + +注意：必须在operator被添加之前设置。 + +.. py:method:: global_block() + +获取该program的第一个block。 + +.. py:method:: block(index) + +返回该program中 ， ``index`` 指定的block。 ``index`` 类型为int + +返回：index对应的block + +返回类型：Block + +.. py:method:: current_block() + +获取当前block。当前block是用来添加operators。 + +.. py:method:: list_vars() + +获取当前program中所有变量。返回值是一个可迭代对象（iterable object)。 + +返回：generator 会yield每个Program中的变量 + +返回类型：iterable + + + + +英文版API文档: :ref:`api_fluid_Program` + +.. _cn_api_fluid_program_guard: + +program_guard +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.program_guard(*args, **kwds) + + + +该函数应配合使用python的“with”语句来改变全局主程序(main program)和启动程序(startup program)。 + +“with”语句块中的layer函数将在新的main program（主程序）中添加operators（算子）和variables（变量）。 + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + main_program = fluid.Program() + startup_program = fluid.Program() + with fluid.program_guard(main_program, startup_program): + data = fluid.layers.data(...) + hidden = fluid.layers.fc(...) + +需要注意的是，如果用户不需要构建自己的启动程序或者主程序，一个临时的program将会发挥作用。 + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + main_program = fluid.Program() + # 如果您不需要关心startup program,传入一个临时值即可 + with fluid.program_guard(main_program, fluid.Program()): + data = ... + + +参数： + - **main_program** (Program) – “with”语句中将使用的新的main program。 + - **startup_program** (Program) – “with”语句中将使用的新的startup program。若传入 ``None`` 则不改变当前的启动程序。 + + + + + + +英文版API文档: :ref:`api_fluid_program_guard` + +.. _cn_api_fluid_release_memory: + +release_memory +>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.release_memory(input_program, skip_opt_set=None) + + +该函数可以调整输入program，插入 ``delete_op`` 删除算子，提前删除不需要的变量。 +改动是在变量本身上进行的。 + +**提醒**: 该API还在试验阶段，会在后期版本中删除。不建议用户使用。 + +参数: + - **input_program** (Program) – 在此program中插入 ``delete_op`` + - **skip_opt_set** (set) – 在内存优化时跳过的变量的集合 + +返回: None + + + + + + + + + + +英文版API文档: :ref:`api_fluid_release_memory` + +.. _cn_api_fluid_Scope: + +Scope +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.scope(scope) + +.. py:method:: drop_kids(self: paddle.fluid.core.Scope) → None +.. py:method:: find_var(self: paddle.fluid.core.Scope, arg0: unicode) → paddle.fluid.core.Variable +.. py:method:: new_scope(self: paddle.fluid.core.Scope) → paddle.fluid.core.Scope +.. py:method:: var(self: paddle.fluid.core.Scope, arg0: unicode) → paddle.fluid.core.Variable + + + + +英文版API文档: :ref:`api_fluid_Scope` + +.. _cn_api_fluid_scope_guard: + +scope_guard +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.scope_guard(*args, **kwds)() + + +修改全局/默认作用域（scope）, 运行时中的所有变量都将分配给新的scope。 + +参数： + - **scope** - 新的全局/默认 scope。 + +**代码示例** + +.. code-block:: python + + import paddle.fluid as fluid + + new_scope = fluid.Scope() + with fluid.scope_guard(new_scope): + ... + + + + +英文版API文档: :ref:`api_fluid_scope_guard` + +.. _cn_api_fluid_switch_scope: + +_switch_scope +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid._switch_scope(scope) + + + + + +英文版API文档: :ref:`api_fluid_switch_scope` + +.. _cn_api_fluid_WeightNormParamAttr: + +WeightNormParamAttr +>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.WeightNormParamAttr(dim=None, name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False) + + +权重归一化。权重归一化是将权重向量的长度与其方向解耦。`Weight Normalization: A Simple Reparameterization to Accelerate Training of Deep Neural Networks `_ 这篇paper中讨论了权重归一化的实现 + +参数: + - **dim** (list) - 参数的名称。默认None。 + - **name** (str) - 参数的名称。默认None。 + - **initializer** （initializer) - 初始化参数的方法。默认None。 + - **learning_rate** (float) - 学习率。优化时学习速率 :math:`global\_lr∗parameter\_lr∗scheduler\_factor` 。默认1.0。 + - **regularizer** (WeightDecayRegularizer) - 正则化因子。默认None。 + - **trainable** (bool) - 参数是否可训练。默认True。 + - **gradient_clip** (BaseGradientClipAttr) - 梯度下降裁剪（Gradient Clipping）的方法。默认None。 + - **do_model_average** (bool) - 参数是否应该model average。默认False。 + +返回： empty program + +**代码示例** + +.. 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')) + + + + +英文版API文档: :ref:`api_fluid_WeightNormParamAttr` + diff --git a/doc/fluid/api_cn/gen_index.py b/doc/fluid/api_cn/gen_index.py new file mode 100644 index 0000000000000..692f9841bec8a --- /dev/null +++ b/doc/fluid/api_cn/gen_index.py @@ -0,0 +1,21 @@ +import os.path, time +import exceptions +import glob +import os +if __name__ == '__main__': + + file_object = open('index_cn.rst', 'w') + file_object.write('''============= +API Reference +============= + +.. toctree:: + :maxdepth: 1 + +''') + file_object.write(' api_guides/index.rst'+'\n') + file_object.write(' fluid_cn.rst'+'\n') + for file_name in sorted(glob.glob("*.rst")): + if file_name != ('index_cn.rst' and 'fluid_cn.rst'): + file_object.write(' '+file_name + "\n") + file_object.close( ) diff --git a/doc/fluid/api_cn/index_cn.rst b/doc/fluid/api_cn/index_cn.rst new file mode 100644 index 0000000000000..ce264c1d64577 --- /dev/null +++ b/doc/fluid/api_cn/index_cn.rst @@ -0,0 +1,25 @@ +============= +API Reference +============= + +.. toctree:: + :maxdepth: 1 + + api_guides/index.rst + fluid_cn.rst + average_cn.rst + backward_cn.rst + clip_cn.rst + data_feeder_cn.rst + executor_cn.rst + index_cn.rst + initializer_cn.rst + io_cn.rst + layers_cn.rst + metrics_cn.rst + net_cn.rst + optimizer_cn.rst + param_attr_cn.rst + profiler_cn.rst + regularizer_cn.rst + transpliter_cn.rst diff --git a/doc/fluid/api_cn/initializer_cn.rst b/doc/fluid/api_cn/initializer_cn.rst new file mode 100644 index 0000000000000..734198216ada8 --- /dev/null +++ b/doc/fluid/api_cn/initializer_cn.rst @@ -0,0 +1,355 @@ + +################# + fluid.initializer +################# + + +.. _cn_api_fluid_initializer_Bilinear: + +Bilinear +>>>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.Bilinear + + ``BilinearInitializer``的别名 + + +.. _cn_api_fluid_initializer_BilinearInitializer: + +BilinearInitializer +>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.BilinearInitializer + +该初始化函数用于转置卷积函数，进行上采样。用户通过任意整型因子放大shape为(B，C，H，W)的特征图。用法如下： + +**代码示例**: + +.. code-block:: python + + factor = 2 + w_attr = ParamAttr(learning_rate=0., regularizer=L2Decay(0.), + initializer=Bilinear()) + conv_up = fluid.layers.conv2d_transpose( + input, + num_filters=C, + output_size=None, + filter_size=2 * factor - factor % 2, + padding=ceil((factor - 1) / 2.), + stride=factor, + groups=C, + param_attr=w_attr, + bias_attr=False) + +num_filters = C和groups = C 表示这是按通道转置的卷积函数。滤波器shape为(C,1,K,K)，K为filter_size。该初始化函数为滤波器的每个通道设置(K,K)插值核。输出特征图的最终输出shape为(B,C,factor*H,factor*W)。注意学习率和权重衰减设为0，以便在训练过程中双线性插值的系数值保持不变 + + + +英文版API文档: :ref:`api_fluid_initializer_BilinearInitializer` + +.. _cn_api_fluid_initializer_Constant: + +Constant +>>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.Constant + + ``ConstantInitializer``的别名 + + +.. _cn_api_fluid_initializer_ConstantInitializer: + +ConstantInitializer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.ConstantInitializer(value=0.0, force_cpu=False) + +常量初始器 + +参数： + - **value** (float) - 用常量初始化变量 + +**代码示例** + +.. code-block:: python + + fc = fluid.layers.fc(input=x, size=10, + param_attr=fluid.initializer.Constant(value=2.0)) + + + +英文版API文档: :ref:`api_fluid_initializer_ConstantInitializer` + + + +.. _cn_api_fluid_initializer_force_init_on_cpu: + +force_init_on_cpu +>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.force_init_on_cpu() + +标志位，是否强制在CPU上进行变量初始化。 + +返回：状态，是否应强制在CPU上强制进行变量初始化 + +返回类型：bool + +**代码示例**： + +.. code-block:: python + + if force_init_on_cpu(): + create_op('force_cpu': force_init_on_cpu()) + + +英文版API文档: :ref:`api_fluid_initializer_force_init_on_cpu` + + + + + + + + +.. _cn_api_fluid_initializer_init_on_cpu: + +init_on_cpu +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.init_on_cpu(*args, **kwds) + +强制变量在 cpu 上初始化。 + +**代码示例** + +.. code-block:: python + + with init_on_cpu(): + step = layers.create_global_var() + + + +英文版API文档: :ref:`api_fluid_initializer_init_on_cpu` + + +.. _cn_api_fluid_initializer_MSRA: + +MSRA +>>>>>> + +.. py:function:: paddle.fluid.initializer.MSRA + + ``MSRAInitializer``的别名 + +.. _cn_api_fluid_initializer_MSRAInitializer: + +MSRAInitializer +>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.MSRAInitializer(uniform=True, fan_in=None, seed=0) + +实现MSRA初始化（a.k.a. Kaiming初始化） + +该类实现权重初始化方法，方法来自Kaiming He，Xiangyu Zhang，Shaoqing Ren 和 Jian Sun所写的论文: `Delving Deep into Rectifiers: Surpassing Human-Level Performance on ImageNet Classification `_ 。这是一个鲁棒性特别强的初始化方法，并且适应了非线性激活函数（rectifier nonlinearities）。 + +在均匀分布中，范围为[-x,x]，其中： + +.. math:: + + x = \sqrt{\frac{6.0}{fan\_in}} + +在正态分布中，均值为0，标准差为： + +.. math:: + + \sqrt{\frac{2.0}{fan\_in}} + +参数： + - **uniform** (bool) - 是否用均匀分布或正态分布 + - **fan_in** (float) - MSRAInitializer的fan_in。如果为None，fan_in沿伸自变量 + - **seed** (int) - 随机种子 + +.. note:: + + 在大多数情况下推荐设置fan_in为None + +**代码示例**： + +.. code-block:: python + + fc = fluid.layers.fc( + input=queries, size=10, + param_attr=fluid.initializer.MSRA(uniform=False)) + + + +英文版API文档: :ref:`api_fluid_initializer_MSRAInitializer` + + +.. _cn_api_fluid_initializer_Normal: + +Normal +>>>>>>>> + +.. py:function:: paddle.fluid.initializer.Normal + + ``NormalInitializer``的别名 + + +.. _cn_api_fluid_initializer_NormalInitializer: + +NormalInitializer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.NormalInitializer(loc=0.0, scale=1.0, seed=0) + +随机正态（高斯）分布初始化器 + +参数： + - **loc** （float） - 正态分布的平均值 + - **scale** （float） - 正态分布的标准差 + - **seed** （int） - 随机种子 + +**代码示例** + +.. code-block:: python + + fc = fluid.layers.fc(input=x, size=10, + param_attr=fluid.initializer.Normal(loc=0.0, scale=2.0) + + + + + +英文版API文档: :ref:`api_fluid_initializer_NormalInitializer` + +.. _cn_api_fluid_initializer_TruncatedNormal: + +TruncatedNormal +>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.TruncatedNormal + + ``TruncatedNormalInitializer``的别名 + + +.. _cn_api_fluid_initializer_TruncatedNormalInitializer: + +TruncatedNormalInitializer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.TruncatedNormalInitializer(loc=0.0, scale=1.0, seed=0) + +Random Truncated Normal（高斯）分布初始化器 + +参数： + - **loc** （float） - 正态分布的平均值 + - **scale** （float） - 正态分布的标准差 + - **seed** （int） - 随机种子 + +**代码示例** + +.. code-block:: python + + fc = fluid.layers.fc(input=x, size=10, + param_attr=fluid.initializer.TruncatedNormal(loc=0.0, scale=2.0)) + + + + + + +英文版API文档: :ref:`api_fluid_initializer_TruncatedNormalInitializer` + + +.. _cn_api_fluid_initializer_Uniform: + +Uniform +>>>>>>>>> + +.. _cn_api_fluid_initializer_UniformInitializer: + +.. py:class:: paddle.fluid.initializer.Uniform + + ``UniformInitializer``的别名 + + +UniformInitializer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0) + +随机均匀分布初始化器 + +参数： + - **low** (float) - 下界 + - **high** (float) - 上界 + - **seed** (float) - 随机种子 + +**代码示例** + +.. code-block:: python + + fc = fluid.layers.fc(input=x, size=10, + param_attr=fluid.initializer.Uniform(low=-0.5, high=0.5)) + + + + +英文版API文档: :ref:`api_fluid_initializer_UniformInitializer` + +.. _api_fluid_initializer_Xavier: + +Xavier +>>>>>>>>> + +.. py:function:: paddle.fluid.initializer.Xavier + + ``XavierInitializer``的别名 + +.. _cn_api_fluid_initializer_XavierInitializer: + +XavierInitializer +>>>>>>>>>>>>>>>>>>> +.. py:class:: paddle.fluid.initializer.XavierInitializer(uniform=True, fan_in=None, fan_out=None, seed=0) + +该类实现Xavier权重初始化方法（ Xavier weight initializer），Xavier权重初始化方法出自Xavier Glorot和Yoshua Bengio的论文 `Understanding the difficulty of training deep feedforward neural networks `_ + +该初始化函数用于保持所有层的梯度尺度几乎一致。 + +在均匀分布的情况下，取值范围为[-x,x]，其中： + +.. math:: + + x = \sqrt{\frac{6.0}{fan\_in+fan\_out}} + +正态分布的情况下，均值为0，标准差为： + +.. math:: + + x = \sqrt{\frac{2.0}{fan\_in+fan\_out}} + +参数： + - **uniform** (bool) - 是否用均匀分布或者正态分布 + - **fan_in** (float) - 用于Xavier初始化的fan_in。如果为None，fan_in沿伸自变量 + - **fan_out** (float) - 用于Xavier初始化的fan_out。如果为None，fan_out沿伸自变量 + - **seed** (int) - 随机种子 + +.. note:: + + 在大多数情况下推荐将fan_in和fan_out设置为None + +**代码示例**： + +.. code-block:: python + + fc = fluid.layers.fc( + input=queries, size=10, + param_attr=fluid.initializer.Xavier(uniform=False)) + + + + +英文版API文档: :ref:`api_fluid_initializer_XavierInitializer` + diff --git a/doc/fluid/api_cn/io_cn.rst b/doc/fluid/api_cn/io_cn.rst new file mode 100644 index 0000000000000..f7a579d03748e --- /dev/null +++ b/doc/fluid/api_cn/io_cn.rst @@ -0,0 +1,345 @@ + +################# + fluid.io +################# + + + +.. _cn_api_fluid_io_load_inference_model: + +load_inference_model +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.load_inference_model(dirname, executor, model_filename=None, params_filename=None, pserver_endpoints=None) + +从指定目录中加载 推理model(inference model) + +参数: + - **dirname** (str) – model的路径 + - **executor** (Executor) – 运行 inference model的 ``executor`` + - **model_filename** (str|None) – 推理 Program 的文件名称。如果设置为None，将使用默认的文件名为： ``__model__`` + - **params_filename** (str|None) – 加载所有相关参数的文件名称。如果设置为None，则参数将保存在单独的文件中。 + - **pserver_endpoints** (list|None) – 只有在分布式推理时需要用到。 当在训练时使用分布式 look up table , 需要这个参数. 该参数是 pserver endpoints 的列表 + +返回: 这个函数的返回有三个元素的元组(Program，feed_target_names, fetch_targets)。Program 是一个 ``Program`` ，它是推理 ``Program``。 ``feed_target_names`` 是一个str列表，它包含需要在推理 ``Program`` 中提供数据的变量的名称。` `fetch_targets`` 是一个 ``Variable`` 列表，从中我们可以得到推断结果。 + +返回类型：元组(tuple) + +抛出异常： + - ``ValueError`` – 如果 ``dirname`` 非法 + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + path = "./infer_model" + endpoints = ["127.0.0.1:2023","127.0.0.1:2024"] + [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) + # 在这个示例中，inference program 保存在 ./infer_model/__model__”中 + # 参数保存在./infer_mode 单独的若干文件中 + # 加载 inference program 后， executor 使用 fetch_targets 和 feed_target_names 执行Program， 得到推理结果 + + + +英文版API文档: :ref:`api_fluid_io_load_inference_model` + +.. _cn_api_fluid_io_load_params: + +load_params +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.load_params(executor, dirname, main_program=None, filename=None) + +该函数过滤掉 给定 ``main_program`` 中所有参数，然后将它们加载保存在到目录 ``dirname`` 中或文件中的参数。 + +``dirname`` 用于指定保存变量的目录。如果变量保存在指定目录的若干文件中，设置文件名 None; 如果所有变量保存在一个文件中，请使用filename来指定它 + +注意:有些变量不是参数，但它们对于训练是必要的。因此，您不能仅通过 ``save_params()`` 和 ``load_params()`` 保存并之后继续训练。可以使用 ``save_persistables()`` 和 ``load_persistables()`` 代替这两个函数 + +参数: + - **executor** (Executor) – 加载变量的 executor + - **dirname** (str) – 目录路径 + - **main_program** (Program|None) – 需要加载变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None + - **filename** (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None + +返回: None + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + prog = fluid.default_main_program() + fluid.io.load_params(executor=exe, dirname=param_path, + main_program=None) + + + +英文版API文档: :ref:`api_fluid_io_load_params` + +.. _cn_api_fluid_io_load_persistables: + +load_persistables +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.load_persistables(executor, dirname, main_program=None, filename=None) + +该函数过滤掉 给定 ``main_program`` 中所有参数，然后将它们加载保存在到目录 ``dirname`` 中或文件中的参数。 + +``dirname`` 用于指定保存变量的目录。如果变量保存在指定目录的若干文件中，设置文件名 None; 如果所有变量保存在一个文件中，请使用filename来指定它 + +参数: + - **executor** (Executor) – 加载变量的 executor + - **dirname** (str) – 目录路径 + - **main_program** (Program|None) – 需要加载变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None + - **filename** (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None + +返回: None + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + prog = fluid.default_main_program() + fluid.io.load_persistables(executor=exe, dirname=param_path, + main_program=None) + + + +英文版API文档: :ref:`api_fluid_io_load_persistables` + +.. _cn_api_fluid_io_load_vars: + +load_vars +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.load_vars(executor, dirname, main_program=None, vars=None, predicate=None, filename=None) + +``executor`` 从指定目录加载变量。 + +有两种方法来加载变量:方法一，``vars`` 为变量的列表。方法二，将已存在的 ``Program`` 赋值给 ``main_program`` ，然后将加载 ``Program`` 中的所有变量。第一种方法优先级更高。如果指定了 vars，那么忽略 ``main_program`` 和 ``predicate`` 。 + +``dirname`` 用于指定加载变量的目录。如果变量保存在指定目录的若干文件中，设置文件名 None; 如果所有变量保存在一个文件中，请使用 ``filename`` 来指定它 + +参数: + - **executor** (Executor) – 加载变量的 executor + - **dirname** (str) – 目录路径 + - **main_program** (Program|None) – 需要加载变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None + - **vars** (list[Variable]|None) – 要加载的变量的列表。 优先级高于main_program。默认值: None + - **predicate** (function|None) – 如果不等于None，当指定main_program， 那么只有 predicate(variable)==True 时，main_program中的变量会被加载。 + - **filename** (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None + +抛出异常： + - ``TypeError`` - 如果参数 ``main_program`` 为 None 或为一个非 ``Program`` 的实例 + +返回: None + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + + # 第一种使用方式 使用 main_program 指定变量 + def name_has_fc(var): + res = "fc" in var.name + return res + + prog = fluid.default_main_program() + fluid.io.load_vars(executor=exe, dirname=path, main_program=prog, + vars=None) + + + # The second usage: using `vars` to specify variables + var_list = [var_a, var_b, var_c] + fluid.io.load_vars(executor=exe, dirname=path, vars=var_list, + filename="vars_file") + # var_a, var_b and var_c will be loaded. And they are supposed to haven + # been saved in the same file named 'var_file' in the path "./my_paddle_model". + + + +英文版API文档: :ref:`api_fluid_io_load_vars` + +.. _cn_api_fluid_io_save_inference_model: + +save_inference_model +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.save_inference_model(dirname, feeded_var_names, target_vars, executor, main_program=None, model_filename=None, params_filename=None, export_for_deployment=True) + +修改指定的 ``main_program`` ，构建一个专门用于推理的 ``Program``，然后 ``executor`` 把它和所有相关参数保存到 ``dirname`` 中 + +``dirname`` 用于指定保存变量的目录。如果变量保存在指定目录的若干文件中，设置文件名 None; 如果所有变量保存在一个文件中，请使用filename来指定它 + +参数: + - **dirname** (str) – 保存推理model的路径 + - **feeded_var_names** (list[str]) – 推理（inference）需要 feed 的数据 + - **target_vars** (list[Variable]) – 保存推理（inference）结果的 Variables + - **executor** (Executor) – executor 保存 inference model + - **main_program** (Program|None) – 使用 ``main_program`` ，构建一个专门用于推理的 ``Program`` （inference model）. 如果为None, 使用 ``default main program`` 默认: None. + - **model_filename** (str|None) – 保存 推理P rogram 的文件名称。如果设置为None，将使用默认的文件名为： ``__model__`` + - **params_filename** (str|None) – 保存所有相关参数的文件名称。如果设置为None，则参数将保存在单独的文件中。 + - **export_for_deployment** (bool) – 如果为真，Program将被修改为只支持直接推理部署的Program。否则，将存储更多的信息，方便优化和再训练。目前只支持True。 + +返回: None + +抛出异常： + - ``ValueError`` – 如果 ``feed_var_names`` 不是字符串列表 + - ``ValueError`` – 如果 ``target_vars`` 不是 ``Variable`` 列表 + +**代码示例** + +.. 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) + + # 在这个示例中，函数将修改默认的主程序让它适合于推断‘predict_var’。修改的 + # 推理Program 将被保存在 ./infer_model/__model__”中。 + # 和参数将保存在文件夹下的单独文件中 ./infer_mode + + + + +英文版API文档: :ref:`api_fluid_io_save_inference_model` + +.. _cn_api_fluid_io_save_params: + +save_params +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.save_params(executor, dirname, main_program=None, filename=None) + +该函数过滤掉 给定 ``main_program`` 中所有参数，然后将它们保存到目录 ``dirname`` 中或文件中。 + +``dirname`` 用于指定保存变量的目录。如果想将变量保存到指定目录的若干文件中，设置文件名 None; 如果想将所有变量保存在一个文件中，请使用filename来指定它 + +注意:有些变量不是参数，但它们对于训练是必要的。因此，您不能仅通过 ``save_params()`` 和 ``load_params()`` 保存并之后继续训练。可以使用 ``save_persistables()`` 和 ``load_persistables()`` 代替这两个函数 + + +参数: + - **executor** (Executor) – 保存变量的 executor + - **dirname** (str) – 目录路径 + - **main_program** (Program|None) – 需要保存变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None + - **vars** (list[Variable]|None) – 要保存的所有变量的列表。 优先级高于main_program。默认值: None + - **filename** (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None + +返回: None + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + prog = fluid.default_main_program() + fluid.io.save_params(executor=exe, dirname=param_path, + main_program=None) + + + +英文版API文档: :ref:`api_fluid_io_save_params` + +.. _cn_api_fluid_io_save_persistables: + +save_persistables +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.save_persistables(executor, dirname, main_program=None, filename=None) + +该函数过滤掉 给定 ``main_program`` 中所有参数，然后将它们保存到目录 ``dirname`` 中或文件中。 + +``dirname`` 用于指定保存变量的目录。如果想将变量保存到指定目录的若干文件中，设置 ``filename=None`` ; 如果想将所有变量保存在一个文件中，请使用 ``filename`` 来指定它 + +参数: + - **executor** (Executor) – 保存变量的 executor + - **dirname** (str) – 目录路径 + - **main_program** (Program|None) – 需要保存变量的 Program。如果为 None，则使用 default_main_Program 。默认值: None + - **predicate** (function|None) – 如果不等于None，当指定main_program， 那么只有 predicate(variable)==True 时，main_program中的变量 + - **vars** (list[Variable]|None) – 要保存的所有变量的列表。 优先级高于main_program。默认值: None + - **filename** (str|None) – 保存变量的文件。如果想分开保存变量，设置 filename=None. 默认值: None + +返回: None + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + prog = fluid.default_main_program() + fluid.io.save_persistables(executor=exe, dirname=param_path, + main_program=None) + + + + +英文版API文档: :ref:`api_fluid_io_save_persistables` + + + +.. _cn_api_fluid_io_save_vars: + +save_vars +>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.io.save_vars(executor, dirname, main_program=None, vars=None, predicate=None, filename=None) + +通过 ``Executor`` ,此函数将变量保存到指定目录下。 + +有两种方法可以指定要保存的变量：第一种方法，在列表中列出变量并将其传给 ``vars`` 参数。第二种方法是，将现有程序分配给 ``main_program`` ，它会保存program中的所有变量。第一种方式具有更高的优先级。换句话说，如果分配了变量，则将忽略 ``main_program`` 和 ``predicate`` 。 + +``dirname`` 用于指定保存变量的文件夹。如果您希望将变量分别保存在文件夹目录的多个单独文件中，请设置 ``filename`` 为无；如果您希望将所有变量保存在单个文件中，请使用 ``filename`` 指定它。 + +参数： + - **executor** （Executor）- 为保存变量而运行的执行器。 + - **dirname** （str）- 目录路径。 + - **main_program** （Program | None）- 保存变量的程序。如果为None，将自动使用默认主程序。默认值：None。 + - **vars** （list [Variable] | None）- 包含要保存的所有变量的列表。它的优先级高于 ``main_program`` 。默认值：None。 + - **predicate** （function | None）- 如果它不是None，则只保存 ``main_program`` 中使 :math:`predicate(variable)== True` 的变量。它仅在我们使用 ``main_program`` 指定变量时才起作用（换句话说，vars为None）。默认值：None。 + - **filename** （str | None）- 保存所有变量的文件。如果您希望单独保存变量，请将其设置为None。默认值：None。 + +返回： None + +抛出异常： + - ``TypeError`` - 如果main_program不是Program的实例，也不是None。 + +**代码示例** + +.. code-block:: python + + exe = fluid.Executor(fluid.CPUPlace()) + param_path = "./my_paddle_model" + + # 第一种用法:用main_program来指定变量。 + def name_has_fc(var): + res = "fc" in var.name + return res + + prog = fluid.default_main_program() + fluid.io.save_vars(executor=exe, dirname=path, main_program=prog, + vars=None) + # 将main_program中名中包含“fc”的的所有变量保存。 + # 变量将分开保存。 + + + # 第二种用法: 用vars来指定变量。 + var_list = [var_a, var_b, var_c] + fluid.io.save_vars(executor=exe, dirname=path, vars=var_list, + filename="vars_file") + # var_a，var_b和var_c将被保存。 他们将使用同一文件，名为“var_file”，保存在路径“./my_paddle_model”下。 + + + +英文版API文档: :ref:`api_fluid_io_save_vars` + diff --git a/doc/fluid/api_cn/layers_cn.rst b/doc/fluid/api_cn/layers_cn.rst new file mode 100644 index 0000000000000..9a973ba86e43d --- /dev/null +++ b/doc/fluid/api_cn/layers_cn.rst @@ -0,0 +1,10326 @@ + +################### +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:`api_fluid_layers_array_read` + - :ref:`api_fluid_layers_array_write` + - :ref:`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) + + + +英文版API文档: :ref:`api_fluid_layers_array_length` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_array_read` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_array_write` + + + +.. _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') + + + + + +英文版API文档: :ref:`api_fluid_layers_create_array` + + + +.. _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()获得输出序列。 + +.. 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 + + + + +英文版API文档: :ref:`api_fluid_layers_DynamicRNN` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_equal` + + + +.. _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() + + + +英文版API文档: :ref:`api_fluid_layers_IfElse` + + + +.. _cn_api_fluid_layers_increment: + +increment +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True) + + +该函数为输入 ``x`` 中的每一个值增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。 + +参数: + - **x** (Variable|list) – 含有输入值的张量(tensor) + - **value** (float) – 需要增加在 ``x`` 变量上的值 + - **in_place** (bool) – 是否在 ``x`` 变量本身进行增加操作，而非返回其增加后的一个副本而本身不改变。默认为True, 即在其本身进行操作。 + +返回： 每个元素增加后的对象 + +返回类型：变量(variable) + +**代码示例** + +.. code-block:: python + + data = fluid.layers.data(name='data', shape=[32, 32], dtype='float32') + data = fluid.layers.increment(x=data, value=3.0, in_place=True) + + + + + +英文版API文档: :ref:`api_fluid_layers_increment` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_is_empty` + + + +.. _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>>>>>> + +.. py:function:: paddle.fluid.layers.Print(input, first_n=-1, message=None, summarize=-1, print_tensor_name=True, print_tensor_type=True, print_tensor_shape=True, print_tensor_lod=True, print_phase='both') + +**Print操作命令** + +该操作命令创建一个打印操作，打印正在访问的张量。 + +封装传入的张量，以便无论何时访问张量，都会打印信息message和张量的当前值。 + +参数： + - **input** (Variable)-将要打印的张量 + - **summarize** (int)-打印张量中的元素数目，如果值为-1则打印所有元素 + - **message** (str)-字符串类型消息，作为前缀打印 + - **first_n** (int)-只记录first_n次数 + - **print_tensor_name** (bool)-打印张量名称 + - **print_tensor_type** (bool)-打印张量类型 + - **print_tensor_shape** (bool)-打印张量维度 + - **print_tensor_lod** (bool)-打印张量lod + - **print_phase** (str)-打印的阶段，包括 ``forward`` , ``backward`` 和 ``both`` .若设置为 ``backward`` 或者 ``both`` ,则打印输入张量的梯度。 + +返回：输出张量，和输入张量同样的数据 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + value = some_layer(...) + Print(value, summarize=10, + message="The content of some_layer: ") + + + +英文版API文档: :ref:`api_fluid_layers_Print` + + + +.. _cn_api_fluid_layers_reorder_lod_tensor_by_rank: + +reorder_lod_tensor_by_rank +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.reorder_lod_tensor_by_rank(x, rank_table) + + +函数参数 ``X`` 是由多个序列(sequence)组成的的一个batch（数据批）。``rank_table`` 存储着batch中序列的重新排列规则。 +该operator（算子）根据 ``rank_table`` 中提供的规则信息来实现对 ``X`` 的重新排列。 + + +:: + + 例如: + + 假设在 RankTable 中存储的序列索引为 [3,0,2,1]， X 将会被这样被重新排列： + X 中的第四个序列（即索引为3的序列，后面以此类推）会变成排列后的batch中的第一个，紧接着就是原来batch中的第一个元素，第三个元素，和第二个元素。 + 简言之，若有原batch：X = [Seq0, Seq1, Seq2, Seq3] 且 RankTable 中的索引为 [3,0,2,1]，那么输出即为 Out = [Seq3, Seq0, Seq2, Seq1] ，它携带着新的LoD信息。 + 如果 X 的LoD信息是空的，这表明 X 不是序列型数据。这和由多个定长为1的序列组成的batch是相同的情况。此时，该函数将对 X 中的切片（slice） 在第一轴(axis)上按 rank_table 里的规则加以排列。 + 例如，现有 X = [Slice0, Slice1, Slice2, Slice3] ，并且它LoD信息为空，在 RankTable 索引为[3, 0, 2, 1]。则 Out = [Slice3, Slice0, Slice2, Slice1] ，并且不在其中追加LoD信息。 + +注意，该operator对 ``X`` 进行的排序所依据的 ``LoDRankTable`` 不一定是在 ``X`` 的基础上得出来的。它可以由 +其他不同的序列batch得出，并由该operator依据这个 ``LoDRankTable`` 来对 ``X`` 排序。 + +参数： + - **x** (LoDTensor)-待根据提供的 ``RankTable`` 进行排序的LoD tensor + - **rank_table** (LoDRankTable)- ``X`` 重新排序的依据规则表 + + +返回： 重新排列后的LoDTensor + +返回类型: LoDTensor + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_reorder_lod_tensor_by_rank` + + + +.. _cn_api_fluid_layers_StaticRNN: + +StaticRNN +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.layers.StaticRNN(name=None) + + +用于创建static RNN。RNN将有自己的参数，比如输入、输出、memory、状态和长度。 + +.. py:method:: memory(init=None, shape=None, batch_ref=None, init_value=0.0, init_batch_dim_idx=0, ref_batch_dim_idx=1) + +参数： + - **init** - boot memory，如果没有设置，则必须提供一个shape + - **shape** - boot memory的形状 + - **batch_ref** - batch引用 + - **init_value** - boot memory的初始化值 + - **init_batch_dim_idx** - init维度中的batch大小的索引 + - **ref_batch_dim_idx** - batch_ref维度中的batch大小的索引 + + + + + + +英文版API文档: :ref:`api_fluid_layers_StaticRNN` + + + +.. _cn_api_fluid_layers_Switch: + +Switch +>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.Switch (name=None) + +Switch类实现的功能十分类似if-elif-else。它可以在学习率调度器(learning rate scheduler)中调整学习率。 +:: + 语义上， + 1. switch控制流挨个检查cases + 2. 各个case的条件是一个布尔值(boolean)，它是一个标量(scalar)变量 + 3. 它将执行第一个匹配的case后面的分支，如果没有匹配的case，但若存在一个default case,则会执行default case后面的语句 + 4. 一旦匹配了一个case,它降会执行这个case所对应的分支，且仅此分支。 + +**代码示例** + +.. code-block:: python + + lr = fluid.layers.tensor.create_global_var( + shape=[1], + value=0.0, + dtype='float32', + persistable=True, + name="learning_rate") + one_var = tensor.fill_constant( + shape=[1], dtype='float32', value=1.0) + two_var = tensor.fill_constant( + shape=[1], dtype='float32', value=2.0) + + with fluid.layers.control_flow.Switch() as switch: + with switch.case(global_step == zero_var): + fluid.layers.tensor.assign(input=one_var, output=lr) + with switch.default(): + fluid.layers.tensor.assign(input=two_var, output=lr) + +.. py:method:: case(condition) + +为该condition（情况，条件）建立新的block（块）。 + + +.. py:method:: default() + +为该switch建立default case。 + + + + + + +英文版API文档: :ref:`api_fluid_layers_Switch` + + + +.. _cn_api_fluid_layers_While: + +While +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.While (cond, is_test=False, name=None) + + +该类用于实现while循环控制功能。 + + +参数： + - **cond** (Variable) – 用于比较的条件 + - **is_test** (bool) – 用于表明是不是在测试阶段执行 + - **name** (str) - 该层的命名 + +**代码示例** + +.. code-block:: python + + d0 = layers.data("d0", shape=[10], dtype='float32') + data_array = layers.array_write(x=d0, i=i) + array_len = layers.fill_constant(shape=[1],dtype='int64', value=3) + + cond = layers.less_than(x=i, y=array_len) + while_op = layers.While(cond=cond) + with while_op.block(): + d = layers.array_read(array=data_array, i=i) + i = layers.increment(x=i, in_place=True) + layers.array_write(result, i=i, array=d) + layers.less_than(x=i, y=array_len, cond=cond) + + + +英文版API文档: :ref:`api_fluid_layers_While` + + + + + +============ + io +============ + + +.. _cn_api_fluid_layers_batch: + +batch +>>>>>>> + +.. py:function:: paddle.fluid.layers.batch(reader, batch_size) + +该层是一个reader装饰器。接受一个reader变量并添加``batching``装饰。读取装饰的reader，输出数据自动组织成batch的形式。 + +参数： + - **reader** (Variable)-装饰有“batching”的reader变量 + - **batch_size** (int)-批尺寸 + +返回：装饰有``batching``的reader变量 + +返回类型：变量(Variable) + +**代码示例**： + +.. code-block:: python + + raw_reader = fluid.layers.io.open_files(filenames=['./data1.recordio', + './data2.recordio'], + shapes=[(3,224,224), (1)], + lod_levels=[0, 0], + dtypes=['float32', 'int64'], + thread_num=2, + buffer_size=2) + batch_reader = fluid.layers.batch(reader=raw_reader, batch_size=5) + + # 如果用raw_reader读取数据： + # data = fluid.layers.read_file(raw_reader) + # 只能得到数据实例。 + # + # 但如果用batch_reader读取数据： + # data = fluid.layers.read_file(batch_reader) + # 每5个相邻的实例自动连接成一个batch。因此get('data')得到的是一个batch数据而不是一个实例。 + + + +英文版API文档: :ref:`api_fluid_layers_batch` + + + +.. _cn_api_fluid_layers_create_py_reader_by_data: + +create_py_reader_by_data +>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.create_py_reader_by_data(capacity,feed_list,name=None,use_double_buffer=True) + +创建一个 Python reader用于在python中提供数据,该函数将返回一个 ``reader`` 变量。 + +它的工作方式与 ``py_reader`` 非常相似，除了它的输入是一个 feed_list 而不是 ``shapes``、 ``dtypes`` 和 ``lod_level`` + +参数： + - **capacity** (int) - 缓冲区容量由 :code:`py_reader` 维护 + - **feed_list** (list(Variable)) - 传输数据列表 + - **name** (basestring) - 前缀Python队列名称和 reader 名称。不定义时将自动生成名称。 + - **use_double_buffer** (bool) - 是否使用 double buffer + +返回： Variable: 一种reader，我们可以从中获得输入数据。 + +**代码示例：** + + :code:`py_reader` 的基本用法如下所示： + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.dataset.mnist as mnist + + image = fluid.layers.data(name='image', shape=[3,224,224], dtypes='float32') + label = fluid.layers.data(name='label', shape=[1], dtypes='int64') + reader = fluid.layers.create_py_reader_by_data(capacity=64, feed_list=[image, label]) + reader.decorate_paddle_reader( + paddle.reader.shuffle(paddle.batch(mnist.train()) + img, label = fluid.layers.read_file(reader) + loss = network(img, label) # some network definition + + fluid.Executor(fluid.CUDAPlace(0)).run(fluid.default_startup_program()) + + exe = fluid.ParallelExecutor(use_cuda=True, loss_name=loss.name) + for epoch_id in range(10): + reader.start() + try: + while True: + exe.run(fetch_list=[loss.name]) + except fluid.core.EOFException: + reader.reset() + + + + + +英文版API文档: :ref:`api_fluid_layers_create_py_reader_by_data` + + + +.. _cn_api_fluid_layers_data: + +data +>>>>> + +.. py:function:: paddle.fluid.layers.data(name, shape, append_batch_size=True, dtype='float32', lod_level=0, type=VarType.LOD_TENSOR, stop_gradient=True) + +数据层(Data Layer) + +该功能接受输入数据，判断是否需要以minibatch方式返回数据，然后使用辅助函数创建全局变量。该全局变量可由计算图中的所有operator访问。 + +这个函数的所有输入变量都作为本地变量传递给LayerHelper构造函数。 + +参数： + - **name** (str)-函数名或函数别名 + - **shape** (list)-声明维度的元组 + - **append_batch_size** (bool)- + + 1.如果为真，则在维度shape的开头插入-1 + “如果shape=[1],则输出shape为[-1,1].” + + 2.如果维度shape包含-1，比如shape=[-1,1], + “append_batch_size则为False（表示无效）” + + - **dtype** (int|float)-数据类型：float32,float_16,int等 + - **type** (VarType)-输出类型。默认为LOD_TENSOR + - **lod_level** (int)-LoD层。0表示输入数据不是一个序列 + - **stop_gradient** (bool)-布尔类型，提示是否应该停止计算梯度 + +返回：全局变量，可进行数据访问 + +返回类型：变量(Variable) + +**代码示例**： + +.. code-block:: python + + data = fluid.layers.data(name='x', shape=[784], dtype='float32') + + + + +英文版API文档: :ref:`api_fluid_layers_data` + + + +.. _cn_api_fluid_layers_double_buffer: + +double_buffer +>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.double_buffer(reader, place=None, name=None) + + +生成一个双缓冲队列reader. 数据将复制到具有双缓冲队列的位置（由place指定），如果 ``place=none`` 则将使用executor执行的位置。 + +参数: + - **reader** (Variable) – 需要wrap的reader + - **place** (Place) – 目标数据的位置. 默认是executor执行样本的位置. + - **name** (str) – Variable 的名字. 默认为None，不关心名称时也可以设置为None + + +返回： 双缓冲队列的reader + + +**代码示例** + +.. code-block:: python + + reader = fluid.layers.open_files(filenames=['somefile'], + shapes=[[-1, 784], [-1, 1]], + dtypes=['float32', 'int64']) + reader = fluid.layers.double_buffer(reader) + img, label = fluid.layers.read_file(reader) + + + + + + +英文版API文档: :ref:`api_fluid_layers_double_buffer` + + + +.. _cn_api_fluid_layers_load: + +load +>>>>> + +.. py:function:: paddle.fluid.layers.load(out, file_path, load_as_fp16=None) + +Load操作命令将从磁盘文件中加载LoDTensor/SelectedRows变量。 + +.. code-block:: python + + import paddle.fluid as fluid + tmp_tensor = fluid.layers.create_tensor(dtype='float32') + fluid.layers.load(tmp_tensor, "./tmp_tensor.bin") + +参数： + - **out** (Variable)-需要加载的LoDTensor或SelectedRows + - **file_path** (STRING)-预从“file_path”中加载的变量Variable + - **load_as_fp16** (BOOLEAN)-如果为真，张量首先进行加载然后类型转换成float16。如果为假，张量将直接加载，不需要进行数据类型转换。默认为false。 + +返回：None + + + +英文版API文档: :ref:`api_fluid_layers_load` + + + +.. _cn_api_fluid_layers_open_files: + +open_files +>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.open_files(filenames, shapes, lod_levels, dtypes, thread_num=None, buffer_size=None, pass_num=1, is_test=None) + +打开文件(Open files) + +该函数获取需要读取的文件列表，并返回Reader变量。通过Reader变量，我们可以从给定的文件中获取数据。所有文件必须有名称后缀来表示它们的格式，例如，``*.recordio``。 + +参数： + - **filenames** (list)-文件名列表 + - **shape** (list)-元组类型值列表，声明数据维度 + - **lod_levels** (list)-整形值列表，声明数据的lod层级 + - **dtypes** (list)-字符串类型值列表，声明数据类型 + - **thread_num** (None)-用于读文件的线程数。默认：min(len(filenames),cpu_number) + - **buffer_size** (None)-reader的缓冲区大小。默认：3*thread_num + - **pass_num** (int)-用于运行的传递数量 + - **is_test** (bool|None)-open_files是否用于测试。如果用于测试，生成的数据顺序和文件顺序一致。反之，无法保证每一epoch之间的数据顺序是一致的 + +返回：一个Reader变量，通过该变量获取文件数据 + +返回类型：变量(Variable) + +**代码示例**： + +.. code-block:: python + + reader = fluid.layers.io.open_files(filenames=['./data1.recordio', + './data2.recordio'], + shapes=[(3,224,224), (1)], + lod_levels=[0, 0], + dtypes=['float32', 'int64']) + + # 通过reader, 可使用''read_file''层获取数据: + image, label = fluid.layers.io.read_file(reader) + + + +英文版API文档: :ref:`api_fluid_layers_open_files` + + + +.. _cn_api_fluid_layers_Preprocessor: + +Preprocessor +>>>>>>>>>>>>> + +.. py:class:: class paddle.fluid.layers.Preprocessor(reader, name=None) + +reader变量中数据预处理块。 + +参数： + - **reader** (Variable)-reader变量 + - **name** (str,默认None)-reader的名称 + +**代码示例**: + +.. code-block:: python + + preprocessor = fluid.layers.io.Preprocessor(reader=reader) + with preprocessor.block(): + img, lbl = preprocessor.inputs() + img_out = img / 2 + lbl_out = lbl + 1 + preprocessor.outputs(img_out, lbl_out) + data_file = fluid.layers.io.double_buffer(preprocessor()) + + + +英文版API文档: :ref:`api_fluid_layers_Preprocessor` + + + +.. _cn_api_fluid_layers_py_reader: + +py_reader +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.py_reader(capacity, shapes, dtypes, lod_levels=None, name=None, use_double_buffer=True) + + +创建一个由在Python端提供数据的reader + +该layer返回一个Reader Variable。reader提供了 ``decorate_paddle_reader()`` 和 ``decorate_tensor_provider()`` 来设置Python generator，作为Python端的数据源。在c++端调用 ``Executor::Run()`` 时，来自generator的数据将被自动读取。与 ``DataFeeder.feed()`` 不同，数据读取进程和 ``Executor::Run()`` 进程可以使用 ``py_reader`` 并行运行。reader的 ``start()`` 方法应该在每次数据传递开始时调用，在传递结束和抛出 ``fluid.core.EOFException`` 后执行 ``reset()`` 方法。注意， ``Program.clone()`` 方法不能克隆 ``py_reader`` 。 + +参数: + - **capacity** (int) – ``py_reader`` 维护的缓冲区容量 + - **shapes** (list|tuple) –数据形状的元组或列表. + - **dtypes** (list|tuple) – ``shapes`` 对应元素的数据类型 + - **lod_levels** (list|tuple) – lod_level的整型列表或元组 + - **name** (basestring) – python 队列的前缀名称和Reader 名称。不会自动生成。 + - **use_double_buffer** (bool) – 是否使用双缓冲 + +返回: reader，从reader中可以获取feed的数据 + +返回类型: Variable + + + +**代码示例** + +1.py_reader 基本使用如下代码 + +.. code-block:: python + + import paddle.v2 + import paddle.fluid as fluid + import paddle.dataset.mnist as mnist + + reader = fluid.layers.py_reader(capacity=64, + shapes=[(-1,3,224,224), (-1,1)], + dtypes=['float32', 'int64']) + reader.decorate_paddle_reader( + paddle.v2.reader.shuffle(paddle.batch(mnist.train()) + + img, label = fluid.layers.read_file(reader) + loss = network(img, label) # 一些网络定义 + + fluid.Executor(fluid.CUDAPlace(0)).run(fluid.default_startup_program()) + + exe = fluid.ParallelExecutor(use_cuda=True, loss_name=loss.name) + for epoch_id in range(10): + reader.start() + try: + while True: + exe.run(fetch_list=[loss.name]) + except fluid.core.EOFException: + reader.reset() + + + + + +2.训练和测试应使用不同的名称创建两个不同的py_reader，例如： + +.. code-block:: python + + import paddle.v2 + import paddle.fluid as fluid + import paddle.dataset.mnist as mnist + + def network(reader): + img, label = fluid.layers.read_file(reader) + # 此处我们省略了一些网络定义 + return loss + + train_reader = fluid.layers.py_reader(capacity=64, + shapes=[(-1,3,224,224), (-1,1)], + dtypes=['float32', 'int64'], + name='train_reader') + train_reader.decorate_paddle_reader( + paddle.v2.reader.shuffle(paddle.batch(mnist.train()) + + test_reader = fluid.layers.py_reader(capacity=32, + shapes=[(-1,3,224,224), (-1,1)], + dtypes=['float32', 'int64'], + name='test_reader') + test_reader.decorate_paddle_reader(paddle.batch(mnist.test(), 512)) + + # 新建 train_main_prog 和 train_startup_prog + train_main_prog = fluid.Program() + train_startup_prog = fluid.Program() + with fluid.program_guard(train_main_prog, train_startup_prog): + # 使用 fluid.unique_name.guard() 实现与test program的参数共享 + with fluid.unique_name.guard(): + train_loss = network(train_reader) # 一些网络定义 + adam = fluid.optimizer.Adam(learning_rate=0.01) + adam.minimize(loss) + + # Create test_main_prog and test_startup_prog + test_main_prog = fluid.Program() + test_startup_prog = fluid.Program() + with fluid.program_guard(test_main_prog, test_startup_prog): + # 使用 fluid.unique_name.guard() 实现与train program的参数共享 + with fluid.unique_name.guard(): + test_loss = network(test_reader) + + fluid.Executor(fluid.CUDAPlace(0)).run(train_startup_prog) + fluid.Executor(fluid.CUDAPlace(0)).run(test_startup_prog) + + train_exe = fluid.ParallelExecutor(use_cuda=True, + loss_name=train_loss.name, main_program=train_main_prog) + test_exe = fluid.ParallelExecutor(use_cuda=True, + loss_name=test_loss.name, main_program=test_main_prog) + for epoch_id in range(10): + train_reader.start() + try: + while True: + train_exe.run(fetch_list=[train_loss.name]) + except fluid.core.EOFException: + train_reader.reset() + + test_reader.start() + try: + while True: + test_exe.run(fetch_list=[test_loss.name]) + except fluid.core.EOFException: + test_reader.reset() + + + + + + +英文版API文档: :ref:`api_fluid_layers_py_reader` + + + +.. _cn_api_fluid_layers_random_data_generator: + +random_data_generator +>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.random_data_generator(low, high, shapes, lod_levels, for_parallel=True) + +创建一个均匀分布随机数据生成器. + +该层返回一个Reader变量。该Reader变量不是用于打开文件读取数据，而是自生成float类型的均匀分布随机数。该变量可作为一个虚拟reader来测试网络，而不需要打开一个真实的文件。 + +参数： + - **low** (float)--数据均匀分布的下界 + - **high** (float)-数据均匀分布的上界 + - **shapes** (list)-元组数列表，声明数据维度 + - **lod_levels** (list)-整形数列表，声明数据 + - **for_parallel** (Bool)-若要运行一系列操作命令则将其设置为True + +返回：Reader变量，可从中获取随机数据 + +返回类型：变量(Variable) + +**代码示例**： + +.. code-block:: python + + reader = fluid.layers.random_data_generator( + low=0.0, + high=1.0, + shapes=[[3,224,224], [1]], + lod_levels=[0, 0]) + # 通过reader, 可以用'read_file'层获取数据: + image, label = fluid.layers.read_file(reader) + + + +英文版API文档: :ref:`api_fluid_layers_random_data_generator` + + + +.. _cn_api_fluid_layers_read_file: + +read_file +>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.read_file(reader) + +执行给定的reader变量并从中获取数据 + +reader也是变量。可以为由fluid.layers.open_files()生成的原始reader或者由fluid.layers.double_buffer()生成的装饰变量，等等。 + +参数： + **reader** (Variable)-将要执行的reader + +返回：从给定的reader中读取数据 + +**代码示例**： + +.. code-block:: python + + data_file = fluid.layers.open_files( + filenames=['mnist.recordio'], + shapes=[(-1, 748), (-1, 1)], + lod_levels=[0, 0], + dtypes=["float32", "int64"]) + data_file = fluid.layers.double_buffer( + fluid.layers.batch(data_file, batch_size=64)) + input, label = fluid.layers.read_file(data_file) + + + +英文版API文档: :ref:`api_fluid_layers_read_file` + + + +.. _cn_api_fluid_layers_shuffle: + +shuffle +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.shuffle(reader, buffer_size) + +使用python装饰器用shuffle 装饰 reader + +参数: + - **reader** (Variable) – 用shuffle装饰的reader + - **buffer_size** (int) – reader中buffer的大小 + +返回:用shuffle装饰后的reader + +返回类型:Variable + + + + +英文版API文档: :ref:`api_fluid_layers_shuffle` + + + + + +============ + nn +============ + + +.. _cn_api_fluid_layers_add_position_encoding: + +add_position_encoding +>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.add_position_encoding(input, alpha, beta, name=None) + +**添加位置编码层** + +接受形状为[N×M×P]的三维输入张量，并返回一个形为[N×M×P]的输出张量，且输出张量具有位置编码值。 + +可参考论文: `Attention Is All You Need `_ + +.. 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) + + + + + + +英文版API文档: :ref:`api_fluid_layers_add_position_encoding` + + + +.. _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具有相同形状和数据布局的张量。 + + + +英文版API文档: :ref:`api_fluid_layers_affine_channel` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_affine_grid` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_autoincreased_step_counter` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_batch_norm` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_beam_search` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_beam_search_decode` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_bilinear_tensor_product` + + + +.. _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，该层将被自动命名 + + + +英文版API文档: :ref:`api_fluid_layers_brelu` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_chunk_eval` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_clip` + + + +.. _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范数。 + +例如, + +.. code-block:: python + + data = fluid.layer.data( name=’data’, shape=[2, 4, 6], dtype=’float32’) + reshaped = fluid.layers.clip_by_norm( x=data, max_norm=0.5) + + +参数： + - **x** (Variable)- (Tensor) clip_by_norm运算的输入，维数必须在[1,9]之间。 + - **max_norm** (float)- 最大范数值。 + - **name** (basestring | None)- 输出的名称。 + +返回： (Tensor)clip_by_norm操作后的输出和输入(X)具有形状(shape). + +返回类型： Variable + + + + +英文版API文档: :ref:`api_fluid_layers_clip_by_norm` + + + +.. _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") + + + + + +英文版API文档: :ref:`api_fluid_layers_conv2d` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_conv2d_transpose` + + + +.. _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") + + + +英文版API文档: :ref:`api_fluid_layers_conv3d` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_conv3d_transpose` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_cos_sim` + + + +.. _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")) + + + + + + +英文版API文档: :ref:`api_fluid_layers_crf_decoding` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_crop` + + + +.. _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) + + + + + + + +英文版API文档: :ref:`api_fluid_layers_cross_entropy` + + + +.. _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结果中的每个序列，在两个空格之间合并重复token并删除所有空格。 + + +A simple example as below: + + :: + + Given: + + 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]] + + Then: + + 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贪婪解码结果。如果结果中的所有序列都为空，则LoDTensor 为[-1]，其中LoD[[]] dims[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) + + + + + +英文版API文档: :ref:`api_fluid_layers_ctc_greedy_decoder` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_dice_loss` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_dropout` + + + +.. _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, dim=hidden_dim) + + + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_dynamic_gru` + + + +.. _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) + + + + + + + +英文版API文档: :ref:`api_fluid_layers_dynamic_lstm` + + + +.. _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") + + + + + +英文版API文档: :ref:`api_fluid_layers_dynamic_lstmp` + + + +.. _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=[8], dtype='float32') + y = fluid.layers.data(name='y', shape=[7], dtype='float32') + cost = fluid.layers.edit_distance(input=x,label=y) + + + +英文版API文档: :ref:`api_fluid_layers_edit_distance` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_add` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_div` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_max` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_min` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_mul` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_pow` + + + +.. _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）- 输出的名称。 + +返回： 元素运算的输出。 + + + +英文版API文档: :ref:`api_fluid_layers_elementwise_sub` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_elu` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_embedding` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_expand` + + + +.. _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") + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_fc` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_flatten` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_gather` + + + +.. _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） + + + + +英文版API文档: :ref:`api_fluid_layers_gaussian_random` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_gaussian_random_batch_size_like` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_grid_sampler` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_group_norm` + + + +.. _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) + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_gru_unit` + + + +.. _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，该层将被自动命名。 + + + +英文版API文档: :ref:`api_fluid_layers_hard_sigmoid` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_hash` + + + +.. _cn_api_fluid_layers_hsigmoid: + +hsigmoid +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None) + +层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完整的二叉树，每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。 + +`请参考 Hierarchical Probabilistic Neural Network Language Model `_ + +参数: + - **input** (Variable) - 输入张量，shape为 ``[N×D]`` ,其中 ``N`` 是minibatch的大小，D是特征大小。 + - **label** (Variable) - 训练数据的标签。该tensor的shape为 ``[N×1]`` + - **num_classes** (int) - 类别的数量不能少于2 + - **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。 + + 返回: (Tensor) 层次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) + + + + +英文版API文档: :ref:`api_fluid_layers_hsigmoid` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_im2sequence` + + + +.. _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)，并且调整大小只适用于最后两个维度(高度和宽度)。 + +支持重新取样方法: 双线性插值 + +参数: + - **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) - 重采样方法。目前只支持“双线性”。默认值:双线性插值 + +返回： 4维tensor，shape为 (num_batches, channls, out_h, out_w). + +返回类型: 变量（variable） + + +**代码示例** + +.. code-block:: python + + out = fluid.layers.image_resize(input, out_shape=[12, 12]) + + + + + + +英文版API文档: :ref:`api_fluid_layers_image_resize` + + + +.. _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） + + + + + +英文版API文档: :ref:`api_fluid_layers_image_resize_short` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_l2_normalize` + + + +.. _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") + + + +英文版API文档: :ref:`api_fluid_layers_label_smooth` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_layer_norm` + + + +.. _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，该层将被自动命名。 + + + +英文版API文档: :ref:`api_fluid_layers_leaky_relu` + + + +.. _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） + + + + + + +英文版API文档: :ref:`api_fluid_layers_linear_chain_crf` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_lod_reset` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_log` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_log_loss` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_logical_and` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_logical_not` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_logical_or` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_logical_xor` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_lrn` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_lstm_unit` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_margin_rank_loss` + + + +.. _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] + + + +英文版API文档: :ref:`api_fluid_layers_matmul` + + + +.. _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） + + + + +英文版API文档: :ref:`api_fluid_layers_maxout` + + + +.. _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 + + + + +英文版API文档: :ref:`api_fluid_layers_mean` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_mean_iou` + + + +.. _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)。 + + + + +英文版API文档: :ref:`api_fluid_layers_mul` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_multiplex` + + + +.. _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) + +计算并返回噪音对比估计（ 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) - 可学习参数/ 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，该层将被自动命名 + +返回： 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') + + + + +英文版API文档: :ref:`api_fluid_layers_nce` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_one_hot` + + + +.. _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.) + + + + +英文版API文档: :ref:`api_fluid_layers_pad` + + + +.. _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') + + + + + +英文版API文档: :ref:`api_fluid_layers_pad2d` + + + +.. _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]。 + + + + + +英文版API文档: :ref:`api_fluid_layers_pad_constant_like` + + + +.. _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) + +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_{in},H_{in},W_{in} \right )` + +输出： + Out shape：:math:`\left ( N,C_{out},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) - 池化窗口的边长。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。 + - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling + - **pool_stride** (int) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。 + - **pool_padding** (int) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。 + - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true，ksize和填充（padding）则被忽略 + - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn + - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数 + - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。 + +返回：池化结果 + +返回类型：变量（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) + + + +英文版API文档: :ref:`api_fluid_layers_pool2d` + + + +.. _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) + +函数使用上述输入参数的池化配置，为三维空间添加池化操作 + +参数： + - **input** (Vairable) - 池化的输入张量。输入张量的格式为NCHW, N是批尺寸，C是通道数，N是特征高度，W是特征宽度。 + - **pool_size** (int) - 池化窗口的边长。所有对池化窗口都是正方形，边长为pool_size。 + - **pool_type** (str) - 池化类型，``ma``对应max-pooling,``avg``对应average-pooling。 + - **pool_stride** (int) - 跨越步长 + - **pool_padding** (int) - 填充大小 + - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true,ksize and paddings将被忽略。 + - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效 + - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。 + - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。 + +返回：pool3d层的输出 + +返回类型：变量（Variable） + + + + + + +英文版API文档: :ref:`api_fluid_layers_pool3d` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_pow` + + + +.. _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） + + + + + +英文版API文档: :ref:`api_fluid_layers_prelu` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_random_crop` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_rank_loss` + + + +.. _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] + + + + +英文版API文档: :ref:`api_fluid_layers_reduce_max` + + + +.. _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] + + + + +英文版API文档: :ref:`api_fluid_layers_reduce_mean` + + + +.. _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] + + + + +英文版API文档: :ref:`api_fluid_layers_reduce_min` + + + +.. _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] + + + + +英文版API文档: :ref:`api_fluid_layers_reduce_prod` + + + +.. _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] + + + + +英文版API文档: :ref:`api_fluid_layers_reduce_sum` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_relu` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_relu6` + + + +.. _cn_api_fluid_layers_reshape: + +reshape +>>>>>>>>>> + +保持输入张量数据不变的情况下，改变张量的形状。 + +目标形状可由 ``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) + + + + +英文版API文档: :ref:`api_fluid_layers_reshape` + + + +.. _cn_api_fluid_layers_resize_bilinear: + +resize_bilinear +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.resize_bilinear(input, out_shape=None, scale=None, name=None) + +双线性插值是对线性插值的扩展,即二维变量方向上(如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) - 输出变量名。 + +返回： 输出的维度是(N x C x out_h x out_w) + + + + + +英文版API文档: :ref:`api_fluid_layers_resize_bilinear` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_resize_nearest` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_roi_align` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_roi_pool` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_row_conv` + + + +.. _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）。 + + + + + +英文版API文档: :ref:`api_fluid_layers_sampling_id` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_scale` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_scatter` + + + +.. _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) + + + + + + + +英文版API文档: :ref:`api_fluid_layers_selu` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_concat` + + + +.. _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） + + + +英文版API文档: :ref:`api_fluid_layers_sequence_conv` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_enumerate` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_expand` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_expand_as` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_first_step` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_last_step` + + + +.. _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 + + + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_mask` + + + +.. _cn_api_fluid_layers_sequence_pad: + +sequence_pad +>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=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) - 填充序列的长度。可以为空或者任意正整数。当为空时，以序列中最长序列的长度为准，其他所有序列填充至该长度。当是某个特定的正整数，最大长度必须大于最长初始序列的长度 + +返回：填充序列批（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])) + out = fluid.layers.sequence_pad(x=x, pad_value=pad_value) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_pad` + + + +.. _cn_api_fluid_layers_sequence_pool: + +sequence_pool +>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type) + +该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的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 + +返回：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') + + + +英文版API文档: :ref:`api_fluid_layers_sequence_pool` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_sequence_reshape` + + + +.. _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 + + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_reverse` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_scatter` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_slice` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_softmax` + + + +.. _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) + + + + + + +英文版API文档: :ref:`api_fluid_layers_sequence_unpad` + + + +.. _cn_api_fluid_layers_shape: + +shape +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.shape(input) + +shape算子 + +获得输入张量的形状。现在只支持输入CPU的Tensor。 + +参数： + - **input** （Variable）- （Tensor），输入张量。 + +返回： (Tensor），输入张量的形状，形状的数据类型是int32，它将与输入张量（Tensor）在同一设备上。 + +返回类型： 输出（Variable）。 + + + + + +英文版API文档: :ref:`api_fluid_layers_shape` + + + +.. _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 + + + + + + +英文版API文档: :ref:`api_fluid_layers_sigmoid_cross_entropy_with_logits` + + + +.. _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]) + + + + + + +英文版API文档: :ref:`api_fluid_layers_similarity_focus` + + + +.. _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）。 + + + + +英文版API文档: :ref:`api_fluid_layers_slice` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_smooth_l1` + + + +.. _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，该层将被自动命名 + + + + +英文版API文档: :ref:`api_fluid_layers_soft_relu` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_softmax` + + + +.. _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) + +使用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 + + +参数: + - **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 + +返回： 交叉熵，一个形为[N x 1]的二维张量 + +返回类型: Variable + + +**代码示例** + +.. 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) + + + + +英文版API文档: :ref:`api_fluid_layers_softmax_with_cross_entropy` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_space_to_depth` + + + +.. _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] + + + +英文版API文档: :ref:`api_fluid_layers_split` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_square_error_cost` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_squeeze` + + + +.. _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 + + + + + +英文版API文档: :ref:`api_fluid_layers_stack` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_stanh` + + + +.. _cn_api_fluid_layers_sum: + +sum +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sum(x) + +sum算子。 + +该运算符对输入张量求和。所有输入都可以携带LoD（详细程度）信息，但是输出仅与第一个输入共享LoD信息。 + +参数： + - **x** （Variable）- （vector ）sum运算符的输入张量（Tensor）。 + +返回: (Tensor）求和算子的输出张量。 + +返回类型： Variable + + + + +英文版API文档: :ref:`api_fluid_layers_sum` + + + +.. _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) + + + + + + +英文版API文档: :ref:`api_fluid_layers_swish` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_topk` + + + +.. _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 + + x = fluid.layers.data(name='x', shape=[5, 10, 15], dtype='float32') + x_transposed = layers.transpose(x, perm=[1, 0, 2]) + + + +英文版API文档: :ref:`api_fluid_layers_transpose` + + + +.. _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 + + + +英文版API文档: :ref:`api_fluid_layers_uniform_random_batch_size_like` + + + +.. _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]) + + + + +英文版API文档: :ref:`api_fluid_layers_unsqueeze` + + + +.. _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 + + + + + +英文版API文档: :ref:`api_fluid_layers_unstack` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_warpctc` + + + + + +============ + ops +============ + + +.. _cn_api_fluid_layers_abs: + +abs +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.abs(x, name=None) + + +参数: + - **x** - abs运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Abs运算符的输出。 + + + + + +英文版API文档: :ref:`api_fluid_layers_abs` + + + +.. _cn_api_fluid_layers_ceil: + +ceil +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.ceil(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Ceil运算符的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_ceil` + + + +.. _cn_api_fluid_layers_cos: + +cos +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.cos(x, name=None) + + + +参数: + - **x** - cos运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Cos运算符的输出 + + + + +英文版API文档: :ref:`api_fluid_layers_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) + + + +英文版API文档: :ref:`api_fluid_layers_cumsum` + + + +.. _cn_api_fluid_layers_exp: + +exp +>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.exp(x, name=None) + + +参数: + - **x** - Exp运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Exp算子的输出 + + + + +英文版API文档: :ref:`api_fluid_layers_exp` + + + +.. _cn_api_fluid_layers_floor: + +floor +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.floor(x, name=None) + + + +参数: + - **x** - Floor运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Floor运算符的输出。 + + + + + +英文版API文档: :ref:`api_fluid_layers_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) + + + +英文版API文档: :ref:`api_fluid_layers_hard_shrink` + + + +.. _cn_api_fluid_layers_logsigmoid: + +logsigmoid +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.logsigmoid(x, name=None) + + + +参数: + - **x** - LogSigmoid运算符的输入 + - **use_mkldnn** (bool) - （默认为False）仅在 ``mkldnn`` 内核中使用 + +返回： LogSigmoid运算符的输出 + + + + +英文版API文档: :ref:`api_fluid_layers_logsigmoid` + + + +.. _cn_api_fluid_layers_reciprocal: + +reciprocal +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.reciprocal(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Reciprocal运算符的输出。 + + + + + + + +英文版API文档: :ref:`api_fluid_layers_reciprocal` + + + +.. _cn_api_fluid_layers_round: + +round +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.round(x, name=None) + + +参数: + - **x** - Ceil运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Round运算符的输出。 + + + + +英文版API文档: :ref:`api_fluid_layers_round` + + + +.. _cn_api_fluid_layers_sigmoid: + +sigmoid +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sigmoid(x, name=None) + + + +参数: + - **x** - Sigmoid运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Sigmoid运算输出. + + + + +英文版API文档: :ref:`api_fluid_layers_sigmoid` + + + +.. _cn_api_fluid_layers_sin: + +sin +>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sin(x, name=None) + + +参数: + - **x** - sin运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Sin运算符的输出。 + + + + + +英文版API文档: :ref:`api_fluid_layers_sin` + + + +.. _cn_api_fluid_layers_softplus: + +softplus +>>>>>>>>> + +.. py:function:: paddle.fluid.layers.softplus(x,name=None) + +参数： + - **x** : Softplus操作符的输入 + - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 + +返回：Softplus操作后的结果 + + + +英文版API文档: :ref:`api_fluid_layers_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运算符的输出 + + + + +英文版API文档: :ref:`api_fluid_layers_softshrink` + + + +.. _cn_api_fluid_layers_softsign: + +softsign +>>>>>>>>> + +.. py:function:: Paddle.fluid.layers.softsign(x,name=None) + +参数： + - **x** : Softsign操作符的输入 + - **use_mkldnn** (bool, 默认false) - 仅在mkldnn核中使用 + +返回：Softsign操作后的结果 + + + +英文版API文档: :ref:`api_fluid_layers_softsign` + + + +.. _cn_api_fluid_layers_sqrt: + +sqrt +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.sqrt(x, name=None) + + +参数: + - **x** - Sqrt运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + +返回： Sqrt算子的输出。 + + + + + +英文版API文档: :ref:`api_fluid_layers_sqrt` + + + +.. _cn_api_fluid_layers_square: + +square +>>>>>>> + +.. py:function:: paddle.fluid.layers.square(x,name=None) + +参数: + - **x** : 平方操作符的输入 + - **use_mkldnn** (bool, 默认false) 仅在mkldnn核中使用 + +返回：平方后的结果 + + + +英文版API文档: :ref:`api_fluid_layers_square` + + + +.. _cn_api_fluid_layers_tanh: + +tanh +>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.tanh(x, name=None) + + + +参数: + - **x** - Tanh运算符的输入 + - **use_mkldnn** (bool) - （默认为false）仅在 ``mkldnn`` 内核中使用 + + +返回： Tanh算子的输出。 + + + + + +英文版API文档: :ref:`api_fluid_layers_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算子的输出 + + + +英文版API文档: :ref:`api_fluid_layers_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) + + + +英文版API文档: :ref:`api_fluid_layers_thresholded_relu` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_uniform_random` + + + + + +============ + 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) + + + +英文版API文档: :ref:`api_fluid_layers_argmax` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_argmin` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_argsort` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_assign` + + + +.. _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') + + + +英文版API文档: :ref:`api_fluid_layers_cast` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_concat` + + + +.. _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') + + + +英文版API文档: :ref:`api_fluid_layers_create_global_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) + + + +英文版API文档: :ref:`api_fluid_layers_create_parameter` + + + +.. _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') + + +英文版API文档: :ref:`api_fluid_layers_create_tensor` + + + +.. _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') + + + +英文版API文档: :ref:`api_fluid_layers_fill_constant` + + + +.. _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') + + + + +英文版API文档: :ref:`api_fluid_layers_fill_constant_batch_size_like` + + + +.. _cn_api_fluid_layers_has_inf: + +has_inf +>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.has_inf(x) + +测试x是否包括一个无穷数 + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回： + tensor变量存储输出值，包含一个bool型数值 + + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_has_inf` + + + +.. _cn_api_fluid_layers_has_nan: + +has_nan +>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.has_nan(x) + +测试x是否包含NAN + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回： + tensor变量存储输出值，包含一个bool型数值 + + + +英文版API文档: :ref:`api_fluid_layers_has_nan` + + + +.. _cn_api_fluid_layers_isfinite: + +isfinite +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.layers.isfinite(x) + +测试x是否包含无穷大/NAN值，如果所有元素都是有穷数，返回Ture,否则返回False + +参数： + - **x(variable)** - 用于被检查的Tensor/LoDTensor + +返回: + Variable: tensor变量存储输出值，包含一个bool型数值 + + + + +英文版API文档: :ref:`api_fluid_layers_isfinite` + + + +.. _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') + + + +英文版API文档: :ref:`api_fluid_layers_ones` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_reverse` + + + +.. _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]) + + + +英文版API文档: :ref:`api_fluid_layers_sums` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_tensor_array_to_tensor` + + + +.. _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') + + + +英文版API文档: :ref:`api_fluid_layers_zeros` + + + + + +============ + 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) + +.. code-block python + + .. math:: + + learning_rate*=local_gw_ratio * sqrt(sumsq(param)) + / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param))) + +参数： + - **learning_rate** -变量学习率。LARS的全局学习率。 + - **weight_decay** -Python float类型数 + +返回： 衰减的学习率 + + + +英文版API文档: :ref:`api_fluid_layers_append_LARS` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_exponential_decay` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_inverse_time_decay` + + + +.. _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衰减学习率 + +返回：衰减的学习率 + + + +英文版API文档: :ref:`api_fluid_layers_natural_exp_decay` + + + +.. _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)-超参数 + +返回：衰减的学习率 + + + +英文版API文档: :ref:`api_fluid_layers_noam_decay` + + + +.. _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** -一列学习率的值，从不同的步边界中挑选 + +返回：衰减的学习率 + + + +英文版API文档: :ref:`api_fluid_layers_piecewise_decay` + + + +.. _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） + + + +英文版API文档: :ref:`api_fluid_layers_polynomial_decay` + + + + + +============ + 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) + + + +英文版API文档: :ref:`api_fluid_layers_anchor_generator` + + + +.. _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) + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_bipartite_match` + + + +.. _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） + + + + + +英文版API文档: :ref:`api_fluid_layers_box_coder` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_density_prior_box` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_detection_map` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_detection_output` + + + +.. _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（框） + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_generate_proposal_labels` + + + +.. _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。 + + + + +英文版API文档: :ref:`api_fluid_layers_generate_proposals` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_iou_similarity` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_multi_box_head` + + + +.. _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） + + + + + +英文版API文档: :ref:`api_fluid_layers_polygon_box_transform` + + + +.. _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) + + + + + +英文版API文档: :ref:`api_fluid_layers_prior_box` + + + +.. _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) + + + + + + + + + + + +英文版API文档: :ref:`api_fluid_layers_roi_perspective_transform` + + + +.. _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和所有真实框之间最大重叠的。 + +返回： 返回元组（predict_scores，predict_location，target_label，target_bbox）。predict_scores和predict_location是RPN的预测结果。 target_label和target_bbox分别是ground-truth。 predict_location是一个shape为[F，4]的2D Tensor， ``target_bbox`` 的shape与 ``predict_location`` 的shape相同，F是foreground anchors的数量。 ``predict_scores`` 是一个shape为[F + B，1]的2D Tensor， ``target_label`` 的shape与 ``predict_scores`` 的shape相同，B是background anchors的数量，F和B取决于此算子的输入。 + +返回类型： 元组(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 = + fluid.layers.rpn_target_assign(bbox_pred=bbox_pred, + cls_logits=cls_logits, anchor_box=anchor_box, gt_boxes=gt_boxes) + + + + + +英文版API文档: :ref:`api_fluid_layers_rpn_target_assign` + + + +.. _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) + + + + +英文版API文档: :ref:`api_fluid_layers_ssd_loss` + + + +.. _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) + + + +英文版API文档: :ref:`api_fluid_layers_target_assign` + + + + + +============ + 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) + + + + + + +英文版API文档: :ref:`api_fluid_layers_accuracy` + + + +.. _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 is a binary classification model and label the ground truth + prediction = network(image, is_infer=True) + auc_out=fluid.layers.auc(input=prediction, label=label) + + + + + +英文版API文档: :ref:`api_fluid_layers_auc` + + + diff --git a/doc/fluid/api_cn/metrics_cn.rst b/doc/fluid/api_cn/metrics_cn.rst new file mode 100644 index 0000000000000..4ba6a470bf02b --- /dev/null +++ b/doc/fluid/api_cn/metrics_cn.rst @@ -0,0 +1,372 @@ + +################# + fluid.metrics +################# + + + +.. _cn_api_fluid_merics_Auc: + +Auc +>>>> + +.. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095) + +Auc度量适用于二分类。参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。需要注意auc度量本身是用Python计算值。如果关心速度，请用fluid.layers.auc。 + +auc函数创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算AUC。对于离散化AUC曲线，临界值线性间隔设置以便计算召回率和准确率的值，用false positive率的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。 + +参数： + - **name** - 度量名 + - **curve** - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。 + +注：目前只用Python实现ROC曲线 + +**代码示例**： + +.. code-block:: python + + pred = fluid.layers.fc(input=data, size=1000, act="tanh") + metric = fluid.metrics.Auc() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, preds, labels]) + metric.update(preds, labels) + numpy_auc = metric.eval() + + + + + + + + + + +英文版API文档: :ref:`api_fluid_merics_Auc` + +.. _cn_api_fluid_merics_MetricBase: + +MetricBase +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.MetricBase(name) + +所有Metrics的基类。MetricBase为模型估计方法定义一组接口。Metrics累积连续的两个minibatch之间的度量状态，对每个minibatch用最新接口将当前minibatch值添加到全局状态。用eval函数来计算last reset()或者scratch on()中累积的度量值。如果需要定制一个新的metric，请继承自MetricBase和自定义实现类。 + +参数： + - **name** (str) - metric实例名。例如准确率（accuracy）。如果想区分一个模型里不同的metrics，则需要实例名。 + +.. py:method:: reset() + + reset()清除度量（metric）的状态（state）。默认情况下，状态（state）包含没有 ``_`` 前缀的metric。reset将这些状态设置为初始状态。如果不想使用隐式命名规则，请自定义reset接口。 + +.. py:method:: get_config() + +获取度量（metric)状态和当前状态。状态（state）包含没有 ``_`` 前缀的成员。 + +参数：**None** + +返回：metric对应到state的字典 + +返回类型：字典（dict） + + +.. py:method:: update(preds,labels) + +更新每个minibatch的度量状态（metric states），用户可通过Python或者C++操作符计算minibatch度量值（metric）。 + +参数： + - **preds** (numpy.array) - 当前minibatch的预测 + - **labels** (numpy.array) - 当前minibatch的标签，如果标签为one-hot或者soft-label，应该自定义相应的更新规则。 + +.. py:method:: eval() + +基于累积状态（accumulated states）评估当前度量（current metric）。 + +返回：metrics（Python中） + +返回类型：float|list(float)|numpy.array + + + +英文版API文档: :ref:`api_fluid_merics_MetricBase` + +.. _cn_api_fluid_metrics_Accuracy: + +Accuracy +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.Accuracy(name=None) + +累加mini-batch正确率，计算每次pass的平均准确率。https://en.wikipedia.org/wiki/Accuracy_and_precision + +参数: + - **name** — 度量标准的名称 + +**代码示例** + +.. code-block:: python + + labels = fluid.layers.data(name="data", shape=[1], dtype="int32") + data = fluid.layers.data(name="data", shape=[32, 32], dtype="int32") + pred = fluid.layers.fc(input=data, size=1000, act="tanh") + minibatch_accuracy = fluid.layers.accuracy(pred, label) + accuracy_evaluator = fluid.metrics.Accuracy() + for pass in range(PASSES): + accuracy_evaluator.reset() + for data in train_reader(): + batch_size = data[0] + loss = exe.run(fetch_list=[cost, minibatch_accuracy]) + accuracy_evaluator.update(value=minibatch_accuracy, weight=batch_size) + numpy_acc = accuracy_evaluator.eval() + + +.. py:method:: update(value, weight) + +更新mini batch的状态. + +参数： + - **value** (float|numpy.array) – 每个mini batch的正确率 + - **weight** (int|float) – batch 大小 + + + +英文版API文档: :ref:`api_fluid_metrics_Accuracy` + +.. _cn_api_fluid_metrics_ChunkEvaluator: + +ChunkEvaluator +>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.ChunkEvaluator(name=None) + +用mini-batch的chunk_eval累计counter numbers，用累积的counter numbers计算准确率、召回率和F1值。对于chunking的基础知识，请参考 .. _Chunking with Support Vector Machines: https://aclanthology.info/pdf/N/N01/N01-1025.pdf 。ChunkEvalEvaluator计算块检测（chunk detection）的准确率，召回率和F1值，支持IOB, IOE, IOBES和IO标注方案。 + +**代码示例**： + +.. code-block:: python + + labels = fluid.layers.data(name="data", shape=[1], dtype="int32") + data = fluid.layers.data(name="data", shape=[32, 32], dtype="int32") + pred = fluid.layers.fc(input=data, size=1000, act="tanh") + precision, recall, f1_score, num_infer_chunks, num_label_chunks, num_correct_chunks = layers.chunk_eval( + input=pred, + label=label) + metric = fluid.metrics.ChunkEvaluator() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, preds, labels]) + metric.update(num_infer_chunks, num_label_chunks, num_correct_chunks) + numpy_precision, numpy_recall, numpy_f1 = metric.eval() + +.. py:method:: update(num_infer_chunks, num_label_chunks, num_correct_chunks) + +基于layers.chunk_eval()输出更新状态（state)输出 + +参数: + - **num_infer_chunks** (int|numpy.array): 给定minibatch的Interface块数。 + - **num_label_chunks** (int|numpy.array): 给定minibatch的Label块数。 + - **num_correct_chunks** （int|numpy.array）: 给定minibatch的Interface和Label的块数 + + + +英文版API文档: :ref:`api_fluid_metrics_ChunkEvaluator` + +.. _cn_api_fluid_metrics_CompositeMetric: + +CompositeMetric +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.CompositeMetric(name=None) + +在一个实例中组合多个指标。例如，将F1、准确率、召回率合并为一个指标。 + +**代码示例** + +.. code-block:: python + + labels = fluid.layers.data(name="data", shape=[1], dtype="int32") + data = fluid.layers.data(name="data", shape=[32, 32], dtype="int32") + pred = fluid.layers.fc(input=data, size=1000, act="tanh") + comp = fluid.metrics.CompositeMetric() + acc = fluid.metrics.Precision() + recall = fluid.metrics.Recall() + comp.add_metric(acc) + comp.add_metric(recall) + for pass in range(PASSES): + comp.reset() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, preds, labels]) + comp.update(preds=preds, labels=labels) + numpy_acc, numpy_recall = comp.eval() + + +.. py:method:: add_metric(metric) + +向CompositeMetric添加一个度量指标 + +参数: + - **metric** – MetricBase的一个实例。 + + + +.. py:method:: update(preds, labels) + +更新序列中的每个指标。 + +参数: + - **preds** (numpy.array) - 当前mini batch的预测 + - **labels** (numpy.array) - 当前minibatch的label，如果标签是one-hot或soft-laebl 编码，应该自定义相应的更新规则。 + +.. py:method:: eval() + +按顺序评估每个指标。 + + +返回：Python中的度量值列表。 + +返回类型：list（float | numpy.array） + + + + +英文版API文档: :ref:`api_fluid_metrics_CompositeMetric` + +.. _cn_api_fluid_metrics_DetectionMAP: + +DetectionMAP +>>>>>>>>>>>> + +.. py:class:: class paddle.fluid.metrics.DetectionMAP(name=None) + +计算 detection 平均精度（mAP）。 mAP是衡量object detectors精度的指标，比如 Faster R-CNN,SSD等。它不同于召回率，它是最大精度的平均值。 请从以下文章中获取更多信息： + +https://sanchom.wordpress.com/tag/average-precision/ + +https://arxiv.org/abs/1512.02325 + +通常步骤如下： + +1. 根据detectors中的输入和label，计算 true positive 和 false positive +2. 计算map，支持 ‘11 point’ and ‘integral’ + + +**代码示例** + +.. code-block:: python + + pred = fluid.layers.fc(input=data, size=1000, act="tanh") + batch_map = layers.detection_map( + input, + label, + class_num, + background_label, + overlap_threshold=overlap_threshold, + evaluate_difficult=evaluate_difficult, + ap_version=ap_version) + + metric = fluid.metrics.DetectionMAP() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, batch_map]) + batch_size = data[0] + metric.update(value=batch_map, weight=batch_size) + numpy_map = metric.eval() + + + + + +英文版API文档: :ref:`api_fluid_metrics_DetectionMAP` + +.. _cn_api_fluid_metrics_EditDistance: + +EditDistance +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.EditDistance(name) + +编辑距离是通过计算将一个字符串转换为另一个字符串所需的最小操作数来量化两个字符串(例如单词)之间的差异的一种方法。参考 https://en.wikipedia.org/wiki/Edit_distance +从mini batch中累计编辑距离和序列号，计算所有batch的平均编辑距离和实例错误。 + +参数: + - **name** - 度量标准名称 + +**代码示例** + +.. code-block:: python + + distances, seq_num = fluid.layers.edit_distance(input, label) + distance_evaluator = fluid.metrics.EditDistance() + for epoch in PASS_NUM: + distance_evaluator.reset() + for data in batches: + loss = exe.run(fetch_list=[cost] + list(edit_distance_metrics)) + distance_evaluator.update(distances, seq_num) + distance, instance_error = distance_evaluator.eval() + +在上面的例子中：'distance'是一个pass中的编辑距离的平均值。 'instance_error'是一个pass中的实例的错误率。 + + + +英文版API文档: :ref:`api_fluid_metrics_EditDistance` + +.. _cn_api_fluid_metrics_Precision: + +Precision +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.Precision(name=None) + +Precision(也称为 positive predictive value,正预测值)是被预测为正样例中实际为正的比例。https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers +注:二分类中，Precision与Accuracy不同, + +.. math:: + Accuracy & = \frac{true \quad positive}{total \quad instances(所有样例)} \\\\ + Precision & = \frac{true \quad positive}{all \quad positive \quad instances(所有正样例)} + + +**代码示例** + +.. code-block:: python + + metric = fluid.metrics.Precision() + + for pass in range(PASSES): + metric.reset() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, preds, labels]) + metric.update(preds=preds, labels=labels) + numpy_precision = metric.eval() + + + +英文版API文档: :ref:`api_fluid_metrics_Precision` + +.. _cn_api_fluid_metrics_Recall: + +Recall +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.metrics.Recall(name=None) + +召回率（也称为敏感度）是度量有多个正例被分为正例 + +https://en.wikipedia.org/wiki/Precision_and_recall + +**代码示例** + +.. code-block:: python + + metric = fluid.metrics.Recall() + + for pass in range(PASSES): + metric.reset() + for data in train_reader(): + loss, preds, labels = exe.run(fetch_list=[cost, preds, labels]) + metric.update(preds=preds, labels=labels) + numpy_recall = metric.eval() + + + + +英文版API文档: :ref:`api_fluid_metrics_Recall` + diff --git a/doc/fluid/api_cn/net_cn.rst b/doc/fluid/api_cn/net_cn.rst new file mode 100644 index 0000000000000..847804737164d --- /dev/null +++ b/doc/fluid/api_cn/net_cn.rst @@ -0,0 +1,244 @@ + +################# + fluid.nets +################# + + + +.. _cn_api_fluid_nets_glu: + +glu +>>>> +.. py:function:: paddle.fluid.nets.glu(input, dim=-1) +T +he Gated Linear Units(GLU)由切分（split），sigmoid激活函数和按元素相乘组成。沿着给定维将input拆分成两个大小相同的部分，a和b，计算如下： + +.. math:: + + GLU(a,b) = a\bigotimes \sigma (b) + +参考论文: `Language Modeling with Gated Convolutional Networks `_ + +参数： + - **input** (Variable) - 输入变量，张量或者LoDTensor + - **dim** (int) - 拆分的维度。如果 :math:`dim<0`，拆分的维为 :math:`rank(input)+dim`。默认为-1 + +返回：变量 —— 变量的大小为输入的一半 + +返回类型：变量（Variable） + +**代码示例：** + +.. code-block:: python + + data = fluid.layers.data(name="words", shape=[3, 6, 9], dtype="float32") + output = fluid.nets.glu(input=data, dim=1) # shape of output: [3, 3, 9] + + + + + +英文版API文档: :ref:`api_fluid_nets_glu` + +.. _cn_api_fluid_nets_img_conv_group: + +img_conv_group +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.nets.img_conv_group(input, conv_num_filter, pool_size, conv_padding=1, conv_filter_size=3, conv_act=None, param_attr=None, conv_with_batchnorm=False, conv_batchnorm_drop_rate=0.0, pool_stride=1, pool_type='max', use_cudnn=True) + +Image Convolution Group由Convolution2d，BatchNorm，DropOut和Pool2d组成。根据输入参数，img_conv_group将使用Convolution2d，BatchNorm，DropOut对Input进行连续计算，并将最后一个结果传递给Pool2d。 + +参数： + - **input** （Variable） - 具有[N，C，H，W]格式的输入图像。 + - **conv_num_filter** （list | tuple） - 表示该组的过滤器数。 + - **pool_size** （int | list | tuple） - ``Pool2d Layer`` 池的大小。如果pool_size是列表或元组，则它必须包含两个整数（pool_size_H，pool_size_W）。否则，pool_size_H = pool_size_W = pool_size。 + - **conv_padding** （int | list | tuple） - Conv2d Layer的 ``padding`` 大小。如果 ``padding`` 是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有Conv2d图层的 ``conv_padding`` 都是相同的。默认1。 + - **conv_filter_size** （int | list | tuple） - 过滤器大小。如果filter_size是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有Conv2d图层的 ``conv_filter_size`` 都是相同的。默认3。 + - **conv_act** （str） - ``Conv2d Layer`` 的激活类型， ``BatchNorm`` 后面没有。默认值：无。 + - **param_attr** （ParamAttr） - Conv2d层的参数。默认值：无 + - **conv_with_batchnorm** （bool | list） - 表示在 ``Conv2d Layer`` 之后是否使用 ``BatchNorm`` 。如果 ``conv_with_batchnorm`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则， ``conv_with_batchnorm`` 指示是否所有Conv2d层都遵循 ``BatchNorm``。默认为False。 + - **conv_batchnorm_drop_rate** （float | list） - 表示 ``BatchNorm`` 之后的 ``Dropout Layer`` 的 ``rop_rate`` 。如果 ``conv_batchnorm_drop_rate`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有 ``Dropout Layers`` 的 ``drop_rate`` 都是 ``conv_batchnorm_drop_rate`` 。默认值为0.0。 + - **pool_stride** （int | list | tuple） - ``Pool2d`` 层的汇集步幅。如果 ``pool_stride`` 是列表或元组，则它必须包含两个整数（pooling_stride_H，pooling_stride_W）。否则，pooling_stride_H = pooling_stride_W = pool_stride。默认1。 + - **pool_type** （str） - 池化类型可以是最大池化的 ``max`` 和平均池化的 ``avg`` 。默认max。 + - **use_cudnn** （bool） - 是否使用cudnn内核，仅在安装cudnn库时才有效。默认值：True + +返回： 使用Convolution2d进行串行计算后的最终结果，BatchNorm，DropOut和Pool2d。 + +返回类型： 变量（Variable）。 + +**代码示例** + +.. code-block:: python + + img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32') + conv_pool = fluid.nets.img_conv_group(input=img, + num_channels=3, + conv_padding=1, + conv_num_filter=[3, 3], + conv_filter_size=3, + conv_act="relu", + pool_size=2, + pool_stride=2) + + + +英文版API文档: :ref:`api_fluid_nets_img_conv_group` + +.. _cn_api_fluid_nets_scaled_dot_product_attention: + +scaled_dot_product_attention +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.nets.scaled_dot_product_attention(queries, keys, values, num_heads=1, dropout_rate=0.0) + +点乘attention运算。 + +attention运算机制可以被视为将查询和一组键值对映射到输出。 将输出计算为值的加权和，其中分配给每个值的权重由查询的兼容性函数（此处的点积）与对应的密钥计算。 + +可以通过（batch）矩阵乘法实现点积attention运算，如下所示： + +.. math:: + Attention(Q, K, V)= softmax(QK^\mathrm{T})V + +请参阅 `Attention Is All You Need `_ + +参数： + - **queries** （Variable） - 输入变量，应为3-D Tensor。 + - **keys** （Variable） - 输入变量，应为3-D Tensor。 + - **values** （Variable） - 输入变量，应为3-D Tensor。 + - **num_heads** （int） - 计算缩放点积attention运算的head数。默认值：1。 + - **dropout_rate** （float） - 降低attention的dropout率。默认值：0.0。 + +返回： 通过multi-head来缩放点积attention运算的三维张量。 + +返回类型： 变量（Variable）。 + +抛出异常: + - ``ValueError`` - 如果输入查询键，值不是3-D Tensor会报错。 + +.. note:: + 当num_heads> 1时，分别学习三个线性投影，以将输入查询，键和值映射到查询'，键'和值'。 查询'，键'和值'与查询，键和值具有相同的形状。 + 当num_heads == 1时，scaled_dot_product_attention没有可学习的参数。 + +**代码示例** + +.. code-block:: python + + queries = fluid.layers.data(name="queries", + shape=[3, 5, 9], + dtype="float32", + append_batch_size=False) + queries.stop_gradient = False + keys = fluid.layers.data(name="keys", + shape=[3, 6, 9], + dtype="float32", + append_batch_size=False) + keys.stop_gradient = False + values = fluid.layers.data(name="values", + shape=[3, 6, 10], + dtype="float32", + append_batch_size=False) + values.stop_gradient = False + contexts = fluid.nets.scaled_dot_product_attention(queries, keys, values) + contexts.shape # [3, 5, 10] + + + + + +英文版API文档: :ref:`api_fluid_nets_scaled_dot_product_attention` + +.. _cn_api_fluid_nets_sequence_conv_pool: + +sequence_conv_pool +>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.nets.sequence_conv_pool(input, num_filters, filter_size, param_attr=None, act='sigmoid', pool_type='max') + +sequence_conv_pool由序列卷积和池化组成 + +参数： + - **input** (Variable) - sequence_conv的输入，支持变量时间长度输入序列。当前输入为shape为（T，N）的矩阵，T是mini-batch中的总时间步数，N是input_hidden_size + - **num_filters** （int）- 滤波器数 + - **filter_size** （int）- 滤波器大小 + - **param_attr** （ParamAttr) - Sequence_conv层的参数。默认：None + - **act** （str） - Sequence_conv层的激活函数类型。默认：sigmoid + - **pool_type** （str）- 池化类型。可以是max-pooling的max，average-pooling的average，sum-pooling的sum，sqrt-pooling的sqrt。默认max + +返回：序列卷积（Sequence Convolution）和池化（Pooling）的结果 + + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python + + input_dim = len(word_dict) + emb_dim = 128 + hid_dim = 512 + data = fluid.layers.data( ame="words", shape=[1], dtype="int64", lod_level=1) + emb = fluid.layers.embedding(input=data, size=[input_dim, emb_dim], is_sparse=True) + seq_conv = fluid.nets.sequence_conv_pool(input=emb, + num_filters=hid_dim, + filter_size=3, + act="tanh", + pool_type="sqrt") + + + + +英文版API文档: :ref:`api_fluid_nets_sequence_conv_pool` + +.. _cn_api_fluid_nets_simple_img_conv_pool: + +simple_img_conv_pool +>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.nets.simple_img_conv_pool(input, num_filters, filter_size, pool_size, pool_stride, pool_padding=0, pool_type='max', global_pooling=False, conv_stride=1, conv_padding=0, conv_dilation=1, conv_groups=1, param_attr=None, bias_attr=None, act=None, use_cudnn=True) + + ``simple_img_conv_pool`` 由一个Convolution2d和一个Pool2d组成。 + +参数： + - **input** （Variable） - 输入图像的格式为[N，C，H，W]。 + - **num_filters** （int） - ``filter`` 的数量。它与输出的通道相同。 + - **filter_size** （int | list | tuple） - 过滤器大小。如果 ``filter_size`` 是列表或元组，则它必须包含两个整数（filter_size_H，filter_size_W）。否则，filter_size_H = filter_size_W = filter_size。 + - **pool_size** （int | list | tuple） - Pool2d池化层大小。如果pool_size是列表或元组，则它必须包含两个整数（pool_size_H，pool_size_W）。否则，pool_size_H = pool_size_W = pool_size。 + - **pool_stride** （int | list | tuple） - Pool2d池化层步长。如果pool_stride是列表或元组，则它必须包含两个整数（pooling_stride_H，pooling_stride_W）。否则，pooling_stride_H = pooling_stride_W = pool_stride。 + - **pool_padding** （int | list | tuple） - Pool2d池化层的padding。如果pool_padding是列表或元组，则它必须包含两个整数（pool_padding_H，pool_padding_W）。否则，pool_padding_H = pool_padding_W = pool_padding。默认值为0。 + - **pool_type** （str） - 池化类型可以是 ``max-pooling`` 的 ``max`` 和平均池的 ``avg`` 。默认 ``max`` 。 + - **global_pooling** （bool）- 是否使用全局池。如果global_pooling = true，则忽略pool_size和pool_padding。默认为False + - **conv_stride** （int | list | tuple） - conv2d Layer的步长。如果stride是列表或元组，则它必须包含两个整数，（conv_stride_H，conv_stride_W）。否则，conv_stride_H = conv_stride_W = conv_stride。默认值：conv_stride = 1。 + - **conv_padding** （int | list | tuple） - conv2d Layer的padding大小。如果padding是列表或元组，则它必须包含两个整数（conv_padding_H，conv_padding_W）。否则，conv_padding_H = conv_padding_W = conv_padding。默认值：conv_padding = 0。 + - **conv_dilation** （int | list | tuple） - conv2d Layer的dilation大小。如果dilation是列表或元组，则它必须包含两个整数（conv_dilation_H，conv_dilation_W）。否则，conv_dilation_H = conv_dilation_W = conv_dilation。默认值：conv_dilation = 1。 + - **conv_groups** （int） - conv2d Layer的组数。根据Alex Krizhevsky的Deep 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的初始化程序，则将偏差初始化为零。默认值：None + - **act** （str） - conv2d的激活类型，如果设置为None，则不附加激活。默认值：无。 + - **use_cudnn** （bool） - 是否使用cudnn内核，仅在安装cudnn库时才有效。默认值：True。 + +返回： Convolution2d和Pool2d之后输入的结果。 + +返回类型： 变量（Variable） + +**示例代码** + +.. code-block:: python + + img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32') + conv_pool = fluid.nets.simple_img_conv_pool(input=img, + filter_size=5, + num_filters=20, + pool_size=2, + pool_stride=2, + act="relu") + + + + + + + +英文版API文档: :ref:`api_fluid_nets_simple_img_conv_pool` + diff --git a/doc/fluid/api_cn/optimizer_cn.rst b/doc/fluid/api_cn/optimizer_cn.rst new file mode 100644 index 0000000000000..4d900d82536d8 --- /dev/null +++ b/doc/fluid/api_cn/optimizer_cn.rst @@ -0,0 +1,442 @@ + +################# + fluid.optimizer +################# + + + +.. _cn_api_fluid_optimizer_AdagradOptimizer: + +AdagradOptimizer +>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.AdagradOptimizer(learning_rate, epsilon=1e-06, regularization=None, name=None) + +**Adaptive Gradient Algorithm(Adagrad)** + +更新如下： + +.. math:: + + moment\_out &= moment + grad * grad\\param\_out + &= param - \frac{learning\_rate * grad}{\sqrt{moment\_out} + \epsilon} + +原始论文（http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf）没有epsilon属性。在我们的实现中也作了如下更新： +http://cs231n.github.io/neural-networks-3/#ada 用于维持数值稳定性，避免除数为0的错误发生。 + +参数： + - **learning_rate** (float|Variable)-学习率，用于更新参数。作为数据参数，可以是一个浮点类型值或者有一个浮点类型值的变量 + - **epsilon** (float) - 维持数值稳定性的短浮点型值 + - **regularization** - 规则化函数，例如fluid.regularizer.L2DecayRegularizer + - **name** - 名称前缀（可选） + +**代码示例**： + +.. code-block:: python: + + optimizer = fluid.optimizer.Adagrad(learning_rate=0.2) + optimizer.minimize(cost) + +AdamOptimizer +>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer. AdamOptimizer(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, regularization=None, name=None) + +该函数实现了自适应矩估计优化器，介绍自Adam论文:https://arxiv.org/abs/1412.6980的第二节。Adam是一阶基于梯度下降的算法，基于自适应低阶矩估计。 +Adam更新如下： + +.. math:: + + t & = t + 1\\moment\_out & = {\beta}_1 * moment + (1 - {\beta}_1) * grad\\inf\_norm\_out & = max({\beta}_2 * inf\_norm + \epsilon, |grad|)\\learning\_rate & = \frac{learning\_rate}{1 - {\beta}_1^t}\\param\_out & = param - learning\_rate * \frac{moment\_out}{inf\_norm\_out} + +参数: + - **learning_rate** (float|Variable)-学习率，用于更新参数。作为数据参数，可以是一个浮点类型值或有一个浮点类型值的变量 + - **beta1** (float)-一阶矩估计的指数衰减率 + - **beta2** (float)-二阶矩估计的指数衰减率 + - **epsilon** (float)-保持数值稳定性的短浮点类型值 + - **regularization** - 规则化函数，例如''fluid.regularizer.L2DecayRegularizer + - **name** - 可选名称前缀 + +**代码示例**： + +.. code-block:: python: + + optimizer = fluid.optimizer.Adam(learning_rate=0.2) + optimizer.minimize(cost) + +.. note:: + + 目前，AdamaxOptimizer不支持稀疏参数优化 + + + +英文版API文档: :ref:`api_fluid_optimizer_AdagradOptimizer` + +.. _cn_api_fluid_optimizer_AdamaxOptimizer: + +AdamaxOptimizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.AdamaxOptimizer(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, regularization=None, name=None) + +我们参考Adam论文第7节中的Adamax优化: https://arxiv.org/abs/1412.6980 ， Adamax是基于无穷大范数的Adam算法的一个变种。 + + +Adamax 更新规则: + +.. math:: + \\t = t + 1 +.. math:: + moment\_out=\beta_1∗moment+(1−\beta_1)∗grad +.. math:: + inf\_norm\_out=\max{(\beta_2∗inf\_norm+ϵ, \left|grad\right|)} +.. math:: + learning\_rate=\frac{learning\_rate}{1-\beta_1^t} +.. math:: + param\_out=param−learning\_rate*\frac{moment\_out}{inf\_norm\_out}\\ + + +论文中没有 ``epsilon`` 参数。但是，为了数值稳定性， 防止除0错误， 增加了这个参数 + +参数: + - **learning_rate** (float|Variable) - 用于更新参数的学习率。可以是浮点值，也可以是具有一个浮点值作为数据元素的变量。 + - **beta1** (float) - 第1阶段估计的指数衰减率 + - **beta2** (float) - 第2阶段估计的指数衰减率。 + - **epsilon** (float) -非常小的浮点值，为了数值的稳定性质 + - **regularization** - 正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` + - **name** - 可选的名称前缀。 + +**代码示例** + +.. code-block:: python + + optimizer = fluid.optimizer.Adamax(learning_rate=0.2) + optimizer.minimize(cost) + +.. note:: + 目前 ``AdamaxOptimizer`` 不支持 sparse gradient + + + + +英文版API文档: :ref:`api_fluid_optimizer_AdamaxOptimizer` + +.. _cn_api_fluid_optimizer_DecayedAdagradOptimizer: + +DecayedAdagradOptimizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.DecayedAdagradOptimizer(learning_rate, decay=0.95, epsilon=1e-06, regularization=None, name=None) + +Decayed Adagrad Optimizer + +`原始论文 `_ + +原始论文： `http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf `_ 中没有 ``epsilon`` 参数。但是，为了数值稳定性， 防止除0错误， 增加了这个参数 + +.. math:: + moment\_out = decay*moment+(1-decay)*grad*grad +.. math:: + param\_out=param-\frac{learning\_rate*grad}{\sqrt{moment\_out+\epsilon }} + +参数: + - **learning_rate** (float|Variable) - 用于更新参数的学习率。可以是浮点值，也可以是具有一个浮点值作为数据元素的变量。 + - **decay** (float) – 衰减率 + - **regularization** - 一个正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` + - **epsilon** (float) - 非常小的浮点值，为了数值稳定性 + - **name** — 可选的名称前缀。 + + +**代码示例** + +.. code-block:: python + + optimizer = fluid.optimizer.DecayedAdagrad(learning_rate=0.2) + optimizer.minimize(cost) + +.. note:: + ``DecayedAdagradOptimizer`` 不支持 sparse gradient + + + + +英文版API文档: :ref:`api_fluid_optimizer_DecayedAdagradOptimizer` + +.. _cn_api_fluid_optimizer_FtrlOptimizer: + +FtrlOptimizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.FtrlOptimizer(learning_rate, l1=0.0, l2=0.0, lr_power=-0.5,regularization=None, name=None) + +FTRL (Follow The Regularized Leader) Optimizer. + +TFRTL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf `_) + + +.. math:: + &\qquad new\_accum=squared\_accum+grad^2\\\\ + &\qquad if(lr\_power==−0.5):\\ + &\qquad \qquad linear\_accum+=grad-\frac{\sqrt{new\_accum}-\sqrt{squared\_accum}}{learning\_rate*param}\\ + &\qquad else:\\ + &\qquad \qquad linear\_accum+=grad-\frac{new\_accum^{-lr\_power}-accum^{-lr\_power}}{learning\_rate*param}\\\\ + &\qquad x=l1*sign(linear\_accum)−linear\_accum\\\\ + &\qquad if(lr\_power==−0.5):\\ + &\qquad \qquad y=\frac{\sqrt{new\_accum}}{learning\_rate}+(2*l2)\\ + &\qquad \qquad pre\_shrink=\frac{x}{y}\\ + &\qquad \qquad param=(abs(linear\_accum)>l1).select(pre\_shrink,0.0)\\ + &\qquad else:\\ + &\qquad \qquad y=\frac{new\_accum^{-lr\_power}}{learning\_rate}+(2*l2)\\ + &\qquad \qquad pre\_shrink=\frac{x}{y}\\ + &\qquad \qquad param=(abs(linear\_accum)>l1).select(pre\_shrink,0.0)\\\\ + &\qquad squared\_accum+=grad^2 + + +参数: + - **learning_rate** (float|Variable)-全局学习率。 + - **l1** (float) + - **l2** (float) + - **lr_power** (float) + - **regularization** - 正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` + - **name** — 可选的名称前缀 + +抛出异常： + - ``ValueError`` - 如果 ``learning_rate`` , ``rho`` , ``epsilon`` , ``momentum`` 为 None. + +**代码示例** + +.. code-block:: python + + optimizer = fluid.optimizer.Ftrl(0.0001) + _, params_grads = optimizer.minimize(cost) + +.. note:: +目前, FtrlOptimizer 不支持 sparse gradient + + + + +英文版API文档: :ref:`api_fluid_optimizer_FtrlOptimizer` + +.. _cn_api_fluid_optimizer_LarsMomentum: + +LarsMomentum +>>>>>>>>>>>>>> + +:code:`fluid.optimizer.LarsMomentumOptimizer` 的别名 + + + + +英文版API文档: :ref:`api_fluid_optimizer_LarsMomentum` + +.. _cn_api_fluid_optimizer_LarsMomentumOptimizer: + +LarsMomentumOptimizer +>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.optimizer.LarsMomentumOptimizer(learning_rate, momentum, lars_coeff=0.001, lars_weight_decay=0.0005, regularization=None, name=None) + +LARS支持的Momentum优化器 + +公式作如下更新： + +.. math:: + + & local\_learning\_rate = learning\_rate * lars\_coeff * \ + \frac{||param||}{||gradient|| + lars\_weight\_decay * ||param||}\\ + & velocity = mu * velocity + local\_learning\_rate * (gradient + lars\_weight\_decay * param)\\ + & param = param - velocity + +参数： + - **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量 + - **momentum** (float) - 动量因子 + - **lars_coeff** (float) - 定义LARS本地学习率的权重 + - **lars_weight_decay** (float) - 使用LARS进行衰减的权重衰减系数 + - **regularization** - 正则化函数，例如 :code:`fluid.regularizer.L2DecayRegularizer` + - **name** - 名称前缀，可选 + +**代码示例：** + +.. code-block:: python + + optimizer = fluid.optimizer.LarsMomentum(learning_rate=0.2, momentum=0.1, lars_weight_decay=0.001) + optimizer.minimize(cost) + + + +英文版API文档: :ref:`api_fluid_optimizer_LarsMomentumOptimizer` + +.. _cn_api_fluid_optimizer_ModelAverage: + +ModelAverage +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.ModelAverage(average_window_rate, min_average_window=10000, max_average_window=10000, regularization=None, name=None) + +在滑动窗口中累积参数的平均值。平均结果将保存在临时变量中，通过调用 ``apply()`` 方法可应用于当前模型的参数变量。使用 ``restore()`` 方法恢复当前模型的参数值。 + +平均窗口的大小由 ``average_window_rate`` ， ``min_average_window`` ， ``max_average_window`` 以及当前更新次数决定。 + + +参数: + - **average_window_rate** – 窗口平均速率 + - **min_average_window** – 平均窗口大小的最小值 + - **max_average_window** – 平均窗口大小的最大值 + - **regularization** – 正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` + - **name** – 可选的名称前缀 + +**代码示例** + +.. code-block:: python + + optimizer = fluid.optimizer.Momentum() + optimizer.minimize(cost) + model_average = fluid.optimizer.ModelAverage(0.15, + min_average_window=10000, + max_average_window=20000) + for pass_id in range(args.pass_num): + for data in train_reader(): + exe.run(fluid.default_main_program()...) + + with model_average.apply(exe): + for data in test_reader(): + exe.run(inference_program...) + + +.. py:method:: apply(*args, **kwds) + +将平均值应用于当前模型的参数。 + +.. py:method:: restore(executor) + +恢复当前模型的参数值 + + + + +英文版API文档: :ref:`api_fluid_optimizer_ModelAverage` + +.. _cn_api_fluid_optimizer_MomentumOptimizer: + +MomentumOptimizer +>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.MomentumOptimizer(learning_rate, momentum, use_nesterov=False, regularization=None, name=None) + +含有速度状态的Simple Momentum 优化器 + +该优化器含有牛顿动量标志，公式更新如下： + +.. math:: + & velocity = mu * velocity + gradient\\ + & if (use\_nesterov):\ + \&\quad param = param - (gradient + mu * velocity) * learning\_rate\\ + & else:\\&\quad param = param - learning\_rate * velocity +参数： + - **learning_rate** (float|Variable) - 学习率，用于参数更新。作为数据参数，可以是浮点型值或含有一个浮点型值的变量 + - **momentum** (float) - 动量因子 + - **use_nesterov** (bool) - 赋能牛顿动量 + - **regularization** - 正则化函数，比如fluid.regularizer.L2DecayRegularizer + - **name** - 名称前缀（可选） + +**代码示例**： + +.. code-block:: python + + optimizer = fluid.optimizer.Momentum(learning_rate=0.2, momentum=0.1) + optimizer.minimize(cost) + + + +英文版API文档: :ref:`api_fluid_optimizer_MomentumOptimizer` + +.. _cn_api_fluid_optimizer_RMSPropOptimizer: + +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。等式如下所示： + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + w & = w - \frac{\eta} {\sqrt{r(w,t) + \epsilon}} \nabla Q_{i}(w) + +第一个等式计算每个权重平方梯度的移动平均值，然后将梯度除以 :math:`sqrtv（w，t）` 。 + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + v(w, t) & = \beta v(w, t-1) +\frac{\eta} {\sqrt{r(w,t) +\epsilon}} \nabla Q_{i}(w)\\ + w & = w - v(w, t) + +如果居中为真： + +.. math:: + r(w, t) & = \rho r(w, t-1) + (1 - \rho)(\nabla Q_{i}(w))^2\\ + g(w, t) & = \rho g(w, t-1) + (1 -\rho)\nabla Q_{i}(w)\\ + v(w, t) & = \beta v(w, t-1) + \frac{\eta} {\sqrt{r(w,t) - (g(w, t))^2 +\epsilon}} \nabla Q_{i}(w)\\ + w & = w - v(w, t) + +其中， :math:`ρ` 是超参数，典型值为0.9,0.95等。 :math:`beta` 是动量术语。 :math:`epsilon` 是一个平滑项，用于避免除零，通常设置在1e-4到1e-8的范围内。 + +参数： + - **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。 + - **regularization** - 正则器项，如 ``fluid.regularizer.L2DecayRegularizer`` 。 + - **name** - 可选的名称前缀。 + +抛出异常: + - ``ValueError`` -如果 ``learning_rate`` ， ``rho`` ， ``epsilon`` ， ``momentum`` 为None。 + +**示例代码** + +.. code-block:: python + + optimizer = fluid.optimizer.RMSProp(0.0001) + _, params_grads = optimizer.minimize(cost) + + + + + + + +英文版API文档: :ref:`api_fluid_optimizer_RMSPropOptimizer` + +.. _cn_api_fluid_optimizer_SGDOptimizer: + +SGDOptimizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.optimizer.SGDOptimizer(learning_rate, regularization=None, name=None) + +随机梯度下降算法的优化器 + +.. math:: + \\param\_out=param-learning\_rate*grad\\ + + +参数: + - **learning_rate** (float|Variable) - 用于更新参数的学习率。可以是浮点值，也可以是具有一个浮点值作为数据元素的变量。 + - **regularization** - 一个正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` + - **name** - 可选的名称前缀。 + + +**代码示例** + +.. code-block:: python + + sgd_optimizer = fluid.optimizer.SGD(learning_rate=0.2) + sgd_optimizer.minimize(cost) + + + + + +英文版API文档: :ref:`api_fluid_optimizer_SGDOptimizer` + diff --git a/doc/fluid/api_cn/param_attr_cn.rst b/doc/fluid/api_cn/param_attr_cn.rst new file mode 100644 index 0000000000000..5d1e151f0ad6e --- /dev/null +++ b/doc/fluid/api_cn/param_attr_cn.rst @@ -0,0 +1,79 @@ + +################# + fluid.param_attr +################# + + + +.. _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')) + + + + + +英文版API文档: :ref:`api_fluid_param_attr_WeightNormParamAttr` + +.. _cn_api_fluid_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) + + + +英文版API文档: :ref:`api_fluid_ParamAttr` + diff --git a/doc/fluid/api_cn/profiler_cn.rst b/doc/fluid/api_cn/profiler_cn.rst new file mode 100644 index 0000000000000..a88d5119bbb82 --- /dev/null +++ b/doc/fluid/api_cn/profiler_cn.rst @@ -0,0 +1,196 @@ + +################# + fluid.profiler +################# + + + +.. _cn_api_fluid_profiler_cuda_profiler: + +cuda_profiler +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.profiler.cuda_profiler(*args, **kwds) + + +CUDA分析器。通过CUDA运行时应用程序编程接口对CUDA程序进行性能分析。分析结果将以键-值对格式或逗号分隔的格式写入output_file。用户可以通过output_mode参数设置输出模式，并通过配置参数设置计数器/选项。默认配置是[' gpustarttimestamp '， ' gpustarttimestamp '， ' gridsize3d '， ' threadblocksize '， ' streamid '， ' enableonstart 0 '， ' conckerneltrace ']。然后，用户可使用 `NVIDIA Visual Profiler `_ 工具来加载这个输出文件以可视化结果。 + + +参数: + - **output_file** (string) – 输出文件名称, 输出结果将会写入该文件 + - **output_mode** (string) – 输出格式是有 key-value 键值对 和 逗号的分割的格式。格式应该是' kvp '或' csv ' + - **config** (list of string) – 参考“Compute Command Line Profiler User Guide” 查阅 profiler options 和 counter相关信息 + +抛出异常: + - ``ValueError`` - 如果 ``output_mode`` 不在 [‘kvp’, ‘csv’] 中 + + +**代码示例** + + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.profiler as profiler + + epoc = 8 + dshape = [4, 3, 28, 28] + data = fluid.layers.data(name='data', shape=[3, 28, 28], dtype='float32') + conv = fluid.layers.conv2d(data, 20, 3, stride=[1, 1], padding=[1, 1]) + + place = fluid.CUDAPlace(0) + exe = fluid.Executor(place) + exe.run(fluid.default_startup_program()) + + output_file = 'cuda_profiler.txt' + with profiler.cuda_profiler(output_file, 'csv') as nvprof: + for i in range(epoc): + input = np.random.random(dshape).astype('float32') + exe.run(fluid.default_main_program(), feed={'data': input}) + + # 之后可以使用 NVIDIA Visual Profile 可视化结果 + + + + + +英文版API文档: :ref:`api_fluid_profiler_cuda_profiler` + +.. _cn_api_fluid_profiler_profiler: + +profiler +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.profiler.profiler(*args, **kwds) + +profile interface 。与cuda_profiler不同，此profiler可用于分析CPU和GPU程序。默认情况下，它记录CPU和GPU kernel，如果想分析其他程序，可以参考教程来在c++代码中添加更多代码。 + + +如果 state== ' All '，在profile_path 中写入文件 profile proto 。该文件记录执行期间的时间顺序信息。然后用户可以看到这个文件的时间轴，请参考 `https://github.com/PaddlePaddle/Paddle/blob/develop/doc/fluid/howto/optimization/timeline.md `_ + +参数: + - **state** (string) – profiling state, 取值为 ‘CPU’ 或 ‘GPU’, profiler 使用 CPU timer 或GPU timer 进行 profiling. 虽然用户可能在开始时指定了执行位置(CPUPlace/CUDAPlace)，但是为了灵活性，profiler不会使用这个位置。 + - **sorted_key** (string) – 如果为None，prfile的结果将按照事件的第一次结束时间顺序打印。否则，结果将按标志排序。标志取值为“call”、“total”、“max”、“min” “ave”之一，根据调用着的数量进行排序。total表示按总执行时间排序，max 表示按最大执行时间排序。min 表示按最小执行时间排序。ave表示按平均执行时间排序。 + - **profile_path** (string) – 如果 state == ‘All’, 结果将写入文件 profile proto. + +抛出异常： + - ``ValueError`` – 如果state 取值不在 [‘CPU’, ‘GPU’, ‘All’]中. 如果 sorted_key 取值不在 [‘calls’, ‘total’, ‘max’, ‘min’, ‘ave’] + +**代码示例** + +.. code-block:: python + + import paddle.fluid.profiler as profiler + + with profiler.profiler('All', 'total', '/tmp/profile') as prof: + for pass_id in range(pass_num): + for batch_id, data in enumerate(train_reader()): + exe.run(fluid.default_main_program(), + feed=feeder.feed(data), + fetch_list=[], + use_program_cache=True) + # ... + + + +英文版API文档: :ref:`api_fluid_profiler_profiler` + +.. _cn_api_fluid_profiler_reset_profiler: + +reset_profiler +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.profiler.reset_profiler() + +清除之前的时间记录。此接口不适用于 ``fluid.profiler.cuda_profiler`` ，它只适用于 ``fluid.profiler.start_profiler`` , ``fluid.profiler.stop_profiler`` , ``fluid.profiler.profiler`` 。 + +**代码示例** + +.. code-block:: python + + import paddle.fluid.profiler as profiler + with profiler.profiler(state, 'total', '/tmp/profile'): + for iter in range(10): + if iter == 2: + profiler.reset_profiler() + # ... + + + + +英文版API文档: :ref:`api_fluid_profiler_reset_profiler` + +.. _cn_api_fluid_profiler_start_profiler: + +start_profiler +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.profiler.start_profiler(state) + +激活使用 profiler， 用户可以使用 ``fluid.profiler.start_profiler`` 和 ``fluid.profiler.stop_profiler`` 插入代码 +不能使用 ``fluid.profiler.profiler`` + + +如果 state== ' All '，在profile_path 中写入文件 profile proto 。该文件记录执行期间的时间顺序信息。然后用户可以看到这个文件的时间轴，请参考 `https://github.com/PaddlePaddle/Paddle/blob/develop/doc/fluid/howto/optimization/timeline.md `_ + +参数: + - **state** (string) – profiling state, 取值为 ‘CPU’ 或 ‘GPU’ 或 ‘All’, ‘CPU’ 代表只分析 cpu. ‘GPU’ 代表只分析 GPU . ‘All’ 会产生 timeline. + +抛出异常: + - ``ValueError`` – 如果state 取值不在 [‘CPU’, ‘GPU’, ‘All’]中 + +**代码示例** + +.. code-block:: python + + import paddle.fluid.profiler as profiler + + profiler.start_profiler('GPU') + for iter in range(10): + if iter == 2: + profiler.reset_profiler() + # except each iteration + profiler.stop_profiler('total', '/tmp/profile') + + # ... + + + + +英文版API文档: :ref:`api_fluid_profiler_start_profiler` + +.. _cn_api_fluid_profiler_stop_profiler: + +stop_profiler +>>>>>>>>>>>> + +.. 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`` + +参数: + - **sorted_key** (string) – 如果为None，prfile的结果将按照事件的第一次结束时间顺序打印。否则，结果将按标志排序。标志取值为“call”、“total”、“max”、“min” “ave”之一，根据调用着的数量进行排序。total表示按总执行时间排序，max 表示按最大执行时间排序。min 表示按最小执行时间排序。ave表示按平均执行时间排序。 + - **profile_path** (string) - 如果 state == ‘All’, 结果将写入文件 profile proto. + + +抛出异常: + - ``ValueError`` – 如果state 取值不在 [‘CPU’, ‘GPU’, ‘All’]中 + +**代码示例** + +.. code-block:: python + + import paddle.fluid.profiler as profiler + + profiler.start_profiler('GPU') + for iter in range(10): + if iter == 2: + profiler.reset_profiler() + # except each iteration + profiler.stop_profiler('total', '/tmp/profile') + + + +英文版API文档: :ref:`api_fluid_profiler_stop_profiler` + diff --git a/doc/fluid/api_cn/regularizer_cn.rst b/doc/fluid/api_cn/regularizer_cn.rst new file mode 100644 index 0000000000000..f1db193e19392 --- /dev/null +++ b/doc/fluid/api_cn/regularizer_cn.rst @@ -0,0 +1,72 @@ + +################# + fluid.regularizer +################# + + + +.. _cn_api_fluid_regularizer_L1DecayRegularizer: + +L1DecayRegularizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.regularizer.L1DecayRegularizer(regularization_coeff=0.0) + +实现 L1 权重衰减正则化。 + +L1正则将会稀疏化权重矩阵。 + + +.. math:: + \\L1WeightDecay=reg\_coeff∗sign(parameter)\\ + +参数: + - **regularization_coeff** (float) – 正则化系数 + +**代码示例** + +.. code-block:: python + + ioptimizer = fluid.optimizer.Adagrad( + learning_rate=1e-4, + regularization=fluid.regularizer.L1DecayRegularizer( + regularization_coeff=0.1)) + optimizer.minimize(avg_cost) + + + + + +英文版API文档: :ref:`api_fluid_regularizer_L1DecayRegularizer` + +.. _cn_api_fluid_regularizer_L2DecayRegularizer: + +L2DecayRegularizer +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.0) + +实现L2 权重衰减正则化。 + +较小的 L2 的有助于防止对训练数据的过度拟合。 + +.. math:: + \\L2WeightDecay=reg\_coeff*parameter\\ + +参数: + - **regularization_coeff** (float) – 正则化系数 + +**代码示例** + +.. code-block:: python + + optimizer = fluid.optimizer.Adagrad( + learning_rate=1e-4, + regularization=fluid.regularizer.L2DecayRegularizer( + regularization_coeff=0.1)) + optimizer.minimize(avg_cost) + + + +英文版API文档: :ref:`api_fluid_regularizer_L2DecayRegularizer` + diff --git a/doc/fluid/api_cn/transpliter_cn.rst b/doc/fluid/api_cn/transpliter_cn.rst new file mode 100644 index 0000000000000..4c1d5b810c7ef --- /dev/null +++ b/doc/fluid/api_cn/transpliter_cn.rst @@ -0,0 +1,244 @@ + +################# + fluid.transpiler +################# + + + + + + +.. _cn_api_fluid_DistributeTranspiler: + +DistributeTranspiler +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:class:: paddle.fluid.transpiler.DistributeTranspiler (config=None) + + +该类可以把fluid program转变为分布式数据并行计算程序（distributed data-parallelism programs）,可以有Pserver和NCCL2两种模式。 +当program在Pserver（全称：parameter server）模式下， ``main_program`` (主程序)转为使用一架远程parameter server(即pserver,参数服务器)来进行参数优化，并且优化图会被输入到一个pserver program中。 +在NCCL2模式下，transpiler会在 ``startup_program`` 中附加一个 ``NCCL_ID`` 广播算子（broadcasting operators）来实现在该集群中所有工作结点共享``NCCL_ID`` 。 +调用 ``transpile_nccl2`` 后， 你 **必须** 将 ``trainer_id`` , ``num_trainers`` 参数提供给 ``ParallelExecutor`` 来启动NCCL2分布式模式。 + + + + +**代码示例** + +.. code-block:: python + + # for pserver mode + pserver_endpoints = "192.168.0.1:6174,192.168.0.2:6174" + trainer_endpoints = "192.168.0.1:6174,192.168.0.2:6174" + current_endpoint = "192.168.0.1:6174" + trainer_id = 0 + trainers = 4 + role = os.getenv("PADDLE_TRAINING_ROLE") + + t = fluid.DistributeTranspiler() + t.transpile( + trainer_id, pservers=pserver_endpoints, trainers=trainers) + if role == "PSERVER": + pserver_program = t.get_pserver_program(current_endpoint) + pserver_startup_program = t.get_startup_program(current_endpoint, + pserver_program) + elif role == "TRAINER": + trainer_program = t.get_trainer_program() + + # for nccl2 mode + config = fluid.DistributeTranspilerConfig() + config.mode = "nccl2" + t = fluid.DistributeTranspiler(config=config) + t.transpile(trainer_id, workers=workers, current_endpoint=curr_ep) + exe = fluid.ParallelExecutor( + use_cuda, + loss_name=loss_var.name, + num_trainers=len(trainers.split(",)), + trainer_id=trainer_id + ) + + + +.. py:method:: transpile(trainer_id, program=None, pservers='127.0.0.1:6174', trainers=1, sync_mode=True, startup_program=None, current_endpoint='127.0.0.1:6174') + +该方法可以运行该transpiler（转译器）。 + +参数: + - **trainer_id** (int) – 当前Trainer worker的id, 如果有n个Trainer worker, id 取值范围为0 ~ n-1 + - **program** (Program|None) – 待transpile（转译）的program, 缺省为 ``fluid.default_main_program()`` + - **pservers** (str) – 内容为Pserver列表的字符串，格式为：按逗号区分不同的Pserver，每个Pserver的格式为 *ip地址:端口号* + - **trainers** (int|str) – 在Pserver模式下，该参数指Trainer机的个数；在nccl2模式下，它是一个内容为Trainer终端列表的字符串 + - **sync_mode** (bool) – 是否做同步训练(synchronous training), 默认为True + - **startup_program** (Program|None) – 待transpile（转译）的startup_program，默认为 ``fluid.default_main_program()`` + - **current_endpoint** (str) – 当需要把program转译（transpile）至NCCL2模式下时，需要将当前endpoint（终端）传入该参数。Pserver模式不使用该参数 + +.. py:method:: get_trainer_program(wait_port=True) + + +该方法可以得到Trainer侧的program。 + +返回: Trainer侧的program + +返回类型: Program + + + +.. py:method:: get_pserver_program(endpoint) + + +该方法可以得到Pserver（参数服务器）侧的程序 + +参数: + - **endpoint** (str) – 当前Pserver终端 + +返回: 当前Pserver需要执行的program + +返回类型: Program + + +.. py:method:: get_pserver_programs(endpoint) + + +该方法可以得到Pserver侧用于分布式训练的 ``main_program`` 和 ``startup_program`` 。 + +参数: + - **endpoint** (str) – 当前Pserver终端 + +返回: (main_program, startup_program), “Program”类型的元组 + +返回类型: tuple + + +.. py:method:: get_startup_program(endpoint, pserver_program=None, startup_program=None) + + +**该函数已停止使用** +获取当前Pserver的startup_program，如果有多个被分散到不同blocks的变量，则修改operator的输入变量。 + +参数: + - **endpoint** (str) – 当前Pserver终端 + - **pserver_program** (Program) – 已停止使用。 先调用get_pserver_program + - **startup_program** (Program) – 已停止使用。应在初始化时传入startup_program + +返回: Pserver侧的startup_program + +返回类型: Program + + + +英文版API文档: :ref:`api_fluid_DistributeTranspiler` + +.. _cn_api_fluid_transpiler_DistributeTranspilerConfig: + +DistributeTranspilerConfig +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.transpiler.DistributeTranspilerConfig + +.. py:method:: slice_var_up (bool) + +为Pserver将张量切片, 默认为True + +.. py:method:: split_method (PSDispatcher) + +可使用 RoundRobin 或者 HashName + +注意: 尝试选择最佳方法来达到负载均衡。 + + +.. py:attribute:: min_block_size (int) + +最小数据块的大小 + +注意: 根据：https：//github.com/PaddlePaddle/Paddle/issues/8638#issuecomment-369912156, 当数据块大小超过2MB时，我们可以有效地使用带宽。如果你想更改它，请详细查看slice_variable函数。 + + + +英文版API文档: :ref:`api_fluid_transpiler_DistributeTranspilerConfig` + +.. _cn_api_fluid_transpiler_HashName: + +HashName +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.transpiler.HashName(pserver_endpoints) + +使用 python ``Hash()`` 函数将变量名散列到多个pserver终端。 + +参数: + - **pserver_endpoints** (list) - endpoint （ip:port）的 list + + + + +英文版API文档: :ref:`api_fluid_transpiler_HashName` + +.. _cn_api_fluid_transpiler_memory_optimize: + +memory_optimize +>>>>>>>>>>>> + +.. py:function:: paddle.fluid.transpiler.memory_optimize(input_program, skip_opt_set=None, print_log=False, level=0, skip_grads=False) + +通过重用var内存来优化内存。 + +注意:它不支持block中嵌套子block。 + +参数: + - **input_program** (str) – 输入Program。 + - **skip_opt_set** (set) – set中的vars将不被内存优化。 + - **print_log** (bool) – 是否打印debug日志。 + - **level** (int) - 如果 level=0 并且shape是完全相等，则重用。 + +返回: None + +英文版API文档: :ref:`api_fluid_transpiler_memory_optimize` + + + + +.. _cn_api_fluid_transpiler_release_memory: + +release_memory +>>>>>>>>>>>>>>>>>>>>>>>>>>> + +.. py:function:: paddle.fluid.transpiler.release_memory(input_program, skip_opt_set=None) + + +该函数可以调整输入program，插入 ``delete_op`` 删除算子，提前删除不需要的变量。 +改动是在变量本身上进行的。 + +.. note:: + 该API还在试验阶段，会在后期版本中删除。不建议用户使用。 + +参数: + - **input_program** (Program) – 在此program中插入 ``delete_op`` + - **skip_opt_set** (set) – 在内存优化时跳过的变量的集合 + +返回: None + +英文版API文档: :ref:`api_fluid_transpiler_release_memory` + + + + +.. _cn_api_fluid_transpiler_RoundRobin: + +RoundRobin +>>>>>>>>>>>> + +.. py:class:: paddle.fluid.transpiler.RoundRobin(pserver_endpoints) + +使用 ``RondRobin`` 方法将变量分配给服务器端点。 + +`RondRobin `_ + +参数: + - **pserver_endpoints** (list) - endpoint （ip:port）的 list + + + + +英文版API文档: :ref:`api_fluid_transpiler_RoundRobin` + diff --git a/doc/fluid/beginners_guide/basics/index.rst b/doc/fluid/beginners_guide/basics/index.rst index f293320907005..5371748f3e873 100644 --- a/doc/fluid/beginners_guide/basics/index.rst +++ b/doc/fluid/beginners_guide/basics/index.rst @@ -1,12 +1,17 @@ ################ -深度学习基础知识 +深度学习基础 ################ -.. todo:: +本章由6篇文档组成，它们按照简单到难的顺序排列，将指导您如何使用PaddlePaddle完成基础的深度学习任务 + +本章文档涉及大量了深度学习基础知识，也介绍了如何使用PaddlePaddle实现这些内容，请参阅以下说明了解如何使用： + +内容简介 +====================== + +您现在在看的这本书是一本“交互式”电子书 —— 每一章都可以运行在一个Jupyter Notebook里。 - 概述 - .. toctree:: :titlesonly: @@ -16,3 +21,67 @@ understand_sentiment/index.md label_semantic_roles/index.md machine_translation/index.md + +我们把Jupyter、PaddlePaddle、以及各种被依赖的软件都打包进一个Docker image了。所以您不需要自己来安装各种软件，只需要安装Docker即可。对于各种Linux发行版，请参考 https://www.docker.com 。如果您使用 `Windows `_ 或者 `Mac `_，可以考虑 `给Docker更多内存和CPU资源 `_ 。 + +使用方法 +====================== + +本书默认使用CPU训练，若是要使用GPU训练，使用步骤会稍有变化,请参考下文“使用GPU训练” + +使用CPU训练 +>>>>>>>>>>>> + +只需要在命令行窗口里运行： + +.. code-block:: shell + + docker run -d -p 8888:8888 paddlepaddle/book + +即可从DockerHub.com下载和运行本书的Docker image。阅读和在线编辑本书请在浏览器里访问 http://localhost:8888 + +如果您访问DockerHub.com很慢，可以试试我们的另一个镜像docker.paddlepaddlehub.com： + +:: + + docker run -d -p 8888:8888 docker.paddlepaddlehub.com/book + + +使用GPU训练 +>>>>>>>>>>>>> + +为了保证GPU驱动能够在镜像里面正常运行，我们推荐使用 `nvidia-docker `_ 来运行镜像。请先安装nvidia-docker，之后请运行： + +:: + + nvidia-docker run -d -p 8888:8888 paddlepaddle/book:latest-gpu + + +或者使用国内的镜像请运行： + +:: + + nvidia-docker run -d -p 8888:8888 docker.paddlepaddlehub.com/book:latest-gpu + + +还需要将以下代码 + +.. code-block:: python + + use_cuda = False + + +改成： + +.. code-block:: python + + use_cuda = True + +贡献新章节 +============= + +您要是能贡献新的章节那就太好了！请发Pull Requests把您写的章节加入到 :code:`pending` 下面的一个子目录里。当这一章稳定下来，我们一起把您的目录挪到根目录。 + +为了写作、运行、调试，您需要安装Python 2.x和Go >1.5, 并可以用 `脚本程序 `_ 来生成新的Docker image。 + +**Please Note:** We also provide `English Readme `_ for PaddlePaddle book diff --git a/doc/fluid/beginners_guide/index.rst b/doc/fluid/beginners_guide/index.rst index 7b22cd8f72e75..a2c7d74254a7f 100644 --- a/doc/fluid/beginners_guide/index.rst +++ b/doc/fluid/beginners_guide/index.rst @@ -4,12 +4,7 @@ PaddlePaddle (PArallel Distributed Deep LEarning)是一个易用、高效、灵活、可扩展的深度学习框架 -您可参考我们的 `Github `_ 了解详情，也可阅读 `版本说明 <../release_note.html>`_ 了解新版本的特性 - - -========= - 概览 -========= +您可参考PaddlePaddle的 `Github `_ 了解详情，也可阅读 `版本说明 <../release_note.html>`_ 了解新版本的特性 当您第一次来到PaddlePaddle，请您首先阅读以下文档，了解安装方法： @@ -27,17 +22,13 @@ PaddlePaddle (PArallel Distributed Deep LEarning)是一个易用、高效、灵 - `快速入门 <../beginners_guide/quick_start/index.html>`_：提供线性回归和识别数字两个入门级模型，帮助您快速上手训练网络 - - `深度学习基础知识 <../beginners_guide/basics/index.html>`_：覆盖图像分类、个性化推荐、机器翻译等多个深度领域的基础知识，提供 Fluid 实现案例 - + - `深度学习基础 <../beginners_guide/basics/index.html>`_：覆盖图像分类、个性化推荐、机器翻译等多个深度领域的基础知识，提供 Fluid 实现案例 -========= - 目录 -========= .. toctree:: - :maxdepth: 2 + :hidden: - install/Start.rst + install/index_cn.rst quick_start/index.rst basics/index.rst basics/learning_materials.md diff --git a/doc/fluid/beginners_guide/install/compile/compile_CentOS.md b/doc/fluid/beginners_guide/install/compile/compile_CentOS.md index 6b4d01e8f5ce1..e9eed3e8e9d07 100644 --- a/doc/fluid/beginners_guide/install/compile/compile_CentOS.md +++ b/doc/fluid/beginners_guide/install/compile/compile_CentOS.md @@ -63,7 +63,7 @@ 7. 使用以下命令安装相关依赖： For Python2: pip install protobuf==3.1.0 - For Python3: pip install protobuf==3.1.0 + For Python3: pip3 install protobuf==3.1.0 > 安装protobuf 3.1.0。 @@ -127,48 +127,42 @@ * a. 安装Python-dev: For Python2: yum install python-devel - For Python3: (这里由于python3.5的编译安装过程较为复杂，请参照Python官方流程安装） + For Python3: (请参照Python官方流程安装） * b. 安装pip: For Python2: yum install python-pip (请保证拥有9.0.1及以上的pip版本) - For Python3: (这里由于pip3的编译安装过程较为复杂，请参照Python官方流程安装）(请保证拥有9.0.1及以上的pip3版本） + For Python3: (请参照Python官方流程安装, 并保证拥有9.0.1及以上的pip3版本，请注意，python3.6及以上版本环境下，pip3并不一定对应python版本，如python3.7下默认只有pip3.7） - - * c.（Only For Python3）设置Python3相关的环境变量： + * c.（Only For Python3）设置Python3相关的环境变量，这里以python3.5版本示例，请替换成您使用的版本（3.6、3.7）： 1. 首先使用``` find `dirname $(dirname - $(which python3))` -name "libpython3.so"```找到Pythonlib的路径，然后（下面[python-lib-path]替换为找到文件路径） + $(which python3))` -name "libpython3.so"```找到Python lib的路径，如果是3.6或3.7，请将`python3`改成`python3.6`或`python3.7`，然后将下面[python-lib-path]替换为找到文件路径 2. 设置PYTHON_LIBRARIES：`export PYTHON_LIBRARY=[python-lib-path]` 3. 其次使用```find `dirname $(dirname - $(which python3))`/include -name "python3.5m"```找到PythonInclude的路径，然后（下面[python-include-path]替换为找到文件路径） + $(which python3))`/include -name "python3.5m"```找到Python Include的路径，请注意python版本，然后将下面[python-include-path]替换为找到文件路径 4. 设置PYTHON_INCLUDE_DIR: `export PYTHON_INCLUDE_DIRS=[python-include-path]` 5. 设置系统环境变量路径：`export PATH=[python-lib-path]:$PATH` （这里将[python-lib-path]的最后两级目录替换为/bin/) - - - * d. 安装虚环境`virtualenv`以及`virtualenvwrapper`并创建名为`paddle-venv`的虚环境： + * d. 安装虚环境`virtualenv`以及`virtualenvwrapper`并创建名为`paddle-venv`的虚环境：(请注意对应python版本的pip3的命令，如pip3.6、pip3.7) 1. `pip install virtualenv` 或 `pip3 install virtualenv` 2. `pip install virtualenvwrapper` 或 `pip3 install virtualenvwrapper` - 3. 找到`virtualenvwrapper.sh`： `find / -name virtualenvwrapper.sh`（请找到对应Python版本的`virtualenvwrapper.sh` + 3. 找到`virtualenvwrapper.sh`： `find / -name virtualenvwrapper.sh`（请找到对应Python版本的`virtualenvwrapper.sh`） 4. 查看`virtualenvwrapper.sh`中的安装方法： `cat vitualenvwrapper.sh` 5. 安装`virtualwrapper` 6. 创建名为`paddle-venv`的虚环境： `mkvirtualenv paddle-venv` - 5. 进入虚环境：`workon paddle-venv` - 6. **执行编译前**请您确认在虚环境中安装有[编译依赖表](../Tables.html/#third_party)中提到的相关依赖： * 这里特别提供`patchELF`的安装方法，其他的依赖可以使用`yum install`或者`pip install`/`pip3 install` 后跟依赖名称和版本安装: - `yum install patchelf` - + `yum install patchelf` > 不能使用apt安装的用户请参见patchElF github[官方文档](https://gist.github.com/ruario/80fefd174b3395d34c14) 7. 将PaddlePaddle的源码clone在当下目录下的Paddle的文件夹中，并进入Padde目录下： @@ -177,9 +171,9 @@ - `cd Paddle` -8. 切换到较稳定release分支下进行编译： +8. 切换到较稳定release分支下进行编译(从1.2.0分支开始支持python3.6及3.7版本)： - `git checkout release/1.0.0` + `git checkout release/1.2.0` 9. 并且请创建并进入一个叫build的目录下： @@ -189,17 +183,14 @@ >具体编译选项含义请参见[编译选项表](../Tables.html/#Compile) - * 对于需要编译**CPU版本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 - - > 如果遇到`Could NOT find PROTOBUF (missing: PROTOBUF_LIBRARY PROTOBUF_INCLUDE_DIR)`可以重新执行一次cmake指令 - - + > 如果遇到`Could NOT find PROTOBUF (missing: PROTOBUF_LIBRARY PROTOBUF_INCLUDE_DIR)`可以重新执行一次cmake指令。 + > 请注意PY_VERSION参数更换为您需要的python版本 11. 使用以下命令来编译： diff --git a/doc/fluid/beginners_guide/install/compile/compile_MacOS.md b/doc/fluid/beginners_guide/install/compile/compile_MacOS.md index 0eca1bdd7fca8..28ee06180b65c 100644 --- a/doc/fluid/beginners_guide/install/compile/compile_MacOS.md +++ b/doc/fluid/beginners_guide/install/compile/compile_MacOS.md @@ -74,7 +74,7 @@ 8. 使用以下命令安装相关依赖： For Python2: pip install protobuf==3.1.0 - For Python3: pip install protobuf==3.1.0 + For Python3: pip3 install protobuf==3.1.0 > 安装protobuf 3.1.0。 @@ -128,7 +128,7 @@ 2. 安装python以及pip： - > **请不要使用MacOS中自带python**，我们强烈建议您使用[Homebrew](https://brew.sh)安装python(对于**Python3**请使用python[官方下载](https://www.python.org/downloads/mac-osx/)python3.5.x), pip以及其他的依赖，这会大大降低您安装编译的难度。 + > **请不要使用MacOS中自带python**，我们强烈建议您使用[Homebrew](https://brew.sh)安装python(对于**Python3**请使用python[官方下载](https://www.python.org/downloads/mac-osx/)python3.5.x、python3.6.x、python3.7.x), pip以及其他的依赖，这会大大降低您安装编译的难度。 For python2: brew install python@2 For python3: 使用Python官网安装 @@ -180,7 +180,7 @@ - `cd Paddle` -7. 切换到较稳定release分支下进行编译： +7. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2.0分支开始支持) `git checkout release/1.0.0` @@ -192,12 +192,12 @@ >具体编译选项含义请参见[编译选项表](../Tables.html/#Compile) - * 对于需要编译**CPU版本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`请修改为安装环境的Python版本 10. 使用以下命令来编译： diff --git a/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md b/doc/fluid/beginners_guide/install/compile/compile_Ubuntu.md index 71aebe61782b6..c72d60341aa62 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. 切换到较稳定版本下进行编译： +5. 切换到较稳定release分支下进行编译：(注意，python3.6、python3.7版本是从1.2.0分支开始支持) - `git checkout v1.1` + `git checkout release/1.2.0` 6. 创建并进入/paddle/build路径下： @@ -65,8 +65,7 @@ 7. 使用以下命令安装相关依赖： For Python2: pip install protobuf==3.1.0 - For Python3: pip install protobuf==3.1.0 - + For Python3: pip3 install protobuf==3.1.0 > 安装protobuf 3.1.0。 @@ -77,16 +76,15 @@ 8. 执行cmake： >具体编译选项含义请参见[编译选项表](../Tables.html/#Compile) - + >请注意修改参数`-DPY_VERSION`为您当前环境下使用的python版本 * 对于需要编译**CPU版本PaddlePaddle**的用户： - `cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` - + `cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` * 对于需要编译**GPU版本PaddlePaddle**的用户： - `cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` + `cmake .. -DPY_VERSION=3.5 -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -DWITH_TESTING=OFF -DCMAKE_BUILD_TYPE=Release` 9. 执行编译： @@ -114,32 +112,25 @@

### ***本机编译*** - **请严格按照以下指令顺序执行** - 1. 检查您的计算机和操作系统是否符合我们支持的编译标准： `uname -m && cat /etc/*release` 2. 更新`apt`的源： `apt update` -2. 我们支持使用virtualenv进行编译安装，首先请使用以下命令创建一个名为`paddle-venv`的虚环境： - - - * a. 安装Python-dev: +3. 我们支持使用virtualenv进行编译安装，首先请使用以下命令创建一个名为`paddle-venv`的虚环境： + * a. 安装Python-dev:（请安装与当前环境python版本匹配的python3.x-dev） For Python2: apt install python-dev For Python3: apt install python3.5-dev - - * b. 安装pip: (请保证拥有9.0.1及以上版本的pip): - + * b. 安装pip: (请保证拥有9.0.1及以上版本的pip):（请注意修改对应python3的版本） 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. 安装虚环境`virtualenv`以及`virtualenvwrapper`并创建名为`paddle-venv`的虚环境： + * c. 安装虚环境`virtualenv`以及`virtualenvwrapper`并创建名为`paddle-venv`的虚环境：(请注意修改python版本) 1. `apt install virtualenv` 或 `pip install virtualenv` 或 `pip3 install virtualenv` 2. `apt install virtualenvwrapper` 或 `pip install virtualenvwrapper` 或 `pip3 install virtualenvwrapper` @@ -149,11 +140,9 @@ 6. 按照`virtualenvwrapper.sh`中的安装方法安装`virtualwrapper` 7. 创建名为`paddle-venv`的虚环境： `mkvirtualenv paddle-venv` +4. 进入虚环境：`workon paddle-venv` -3. 进入虚环境：`workon paddle-venv` - - -4. **执行编译前**请您确认在虚环境中安装有[编译依赖表](../Tables.html/#third_party)中提到的相关依赖： +5. **执行编译前**请您确认在虚环境中安装有[编译依赖表](../Tables.html/#third_party)中提到的相关依赖： * 这里特别提供`patchELF`的安装方法，其他的依赖可以使用`apt install`或者`pip install` 后跟依赖名称和版本安装: @@ -179,13 +168,11 @@ >具体编译选项含义请参见[编译选项表](../Tables.html/#Compile) - - * 对于需要编译**CPU版本PaddlePaddle**的用户： + * 对于需要编译**CPU版本PaddlePaddle**的用户：(*For Python3: 请给PY_VERSION参数配置正确的python版本*) 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 - * 对于需要编译**GPU版本PaddlePaddle**的用户：(*仅支持ubuntu16.04/14.04*) 1. 请确保您已经正确安装nccl2，或者按照以下指令安装nccl2（这里提供的是ubuntu 16.04，CUDA9，cuDNN7下nccl2的安装指令），更多版本的安装信息请参考NVIDIA[官方网站](https://developer.nvidia.com/nccl/nccl-download): @@ -193,10 +180,12 @@ 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. 如果您已经正确安装了`nccl2`，就可以开始cmake了： + 2. 如果您已经正确安装了`nccl2`，就可以开始cmake了：(*For Python3: 请给PY_VERSION参数配置正确的python版本*) 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`请修改为安装环境的Python版本 9. 使用以下命令来编译： diff --git a/doc/fluid/beginners_guide/install/compile/fromsource.rst b/doc/fluid/beginners_guide/install/compile/fromsource.rst index afa77c3faec64..a591c3f106a5a 100644 --- a/doc/fluid/beginners_guide/install/compile/fromsource.rst +++ b/doc/fluid/beginners_guide/install/compile/fromsource.rst @@ -4,10 +4,10 @@ 您也可以选择源码编译的方式编译安装PaddlePaddle，但由于本机环境的多样性，在编译源码时易出现复杂问题，可能会造成您安装失败。为保证您顺利安装，推荐您优先选择普通安装方式。 -**编译PaddlePaddle** ---------------------- .. toctree:: + :hidden: + compile_Ubuntu.md compile_CentOS.md compile_MacOS.md diff --git a/doc/fluid/beginners_guide/install/Start.rst b/doc/fluid/beginners_guide/install/index_cn.rst similarity index 66% rename from doc/fluid/beginners_guide/install/Start.rst rename to doc/fluid/beginners_guide/install/index_cn.rst index 5c0cd67f93632..6a0b896a195e9 100644 --- a/doc/fluid/beginners_guide/install/Start.rst +++ b/doc/fluid/beginners_guide/install/index_cn.rst @@ -10,13 +10,13 @@ 请确保您的环境满足以上条件 -- 如果您希望使用 `pip `_ 进行安装PaddlePaddle可以直接使用以下命令: +- 如果您希望使用 `pip `_ 进行安装PaddlePaddle可以直接使用以下命令: -:code:`pip install paddlepaddle` （CPU版本最新） - -:code:`pip install paddlepaddle-gpu` （GPU版本最新） - -:code:`pip install paddlepaddle==[pip版本号]` +:code:`pip install paddlepaddle` （CPU版本最新） + +:code:`pip install paddlepaddle-gpu` （GPU版本最新） + +:code:`pip install paddlepaddle==[pip版本号]` 其中[pip版本号]请查阅 `PyPi.org `_ @@ -25,28 +25,13 @@ 其中[docker版本号]请查阅 `DockerHub `_ - -如果对上面的指令有疑问或者不能正常使用，请参见以下内容 - -安装PaddlePaddle ------------------------ - .. toctree:: - :maxdepth:1 + :hidden: install_Ubuntu.md install_CentOS.md install_MacOS.md install_Windows.md compile/fromsource.rst - -参考信息 ------------------------ - -如在安装或编译过程中遇到问题请参见 - -.. toctree:: - :maxdepth:1 - FAQ.md Tables.md diff --git a/doc/fluid/beginners_guide/install/install_CentOS.md b/doc/fluid/beginners_guide/install/install_CentOS.md index ef1deec8383d2..4eecd3a0b75f4 100644 --- a/doc/fluid/beginners_guide/install/install_CentOS.md +++ b/doc/fluid/beginners_guide/install/install_CentOS.md @@ -52,7 +52,7 @@ Python2.7： yum update && yum install -y epel-release && yum install -y python-devel python-pip && pip install paddlepaddle -Python3.5: (由于在CentOS下安装Python3的方法较为复杂，我们提供默认您已经正确安装python3.5已经pip3之后的安装命令） +Python3.5、3.6、3.7: (由于在CentOS下安装Python3的方法较为复杂，我们提供默认您已经正确安装python3.5+以及pip3之后的安装命令） yum update && yum install -y epel-release && pip3 install paddlepaddle @@ -67,21 +67,19 @@ Python3.5: (由于在CentOS下安装Python3的方法较为复杂，我们提供 其次，您的计算机需要满足以下要求： * Python2.7.x (devel)，Pip >= 9.0.1 - - > CentOS6需要编译Python2.7成[共享库](./FAQ.html/#FAQ)。 -* Python3.5.x (devel)，Pip3 >= 9.0.1 + > CentOS6需要编译Python2.7成[共享库](./FAQ.html/#FAQ)。 + +* Python3.5+.x (devel)，Pip3 >= 9.0.1 - > 您的CentOS上可能已经安装pip请使用pip -V来确认我们建议使用pip 9.0.1或更高版本来安装。 更新yum的源： `yum update` 并安装拓展源以安装pip： `yum install -y epel-release` - 使用以下命令安装或升级Python和pip到需要的版本： + 使用以下命令安装或升级Python和pip到需要的版本： - - - For Python2: `sudo yum install python-devel python-pip` - - For Python3: (这里由于python3.5的编译安装过程较为复杂，请参照Python官方流程安装） + - For Python2: `sudo yum install python-devel python-pip` + - For Python3: (请参照Python官方流程安装，并注意pip3命令对应的python3版本是否一致，如果有多个python3版本，请指定pip版本如pip3.7，或者将pip3软链到您使用的python版本下） > 即使您的环境中已经有`Python`也需要安装`python develop`套装。 @@ -91,13 +89,12 @@ Python3.5: (由于在CentOS下安装Python3的方法较为复杂，我们提供 * 对于需要**CPU版本PaddlePaddle**的用户：`pip install paddlepaddle` 或 `pip3 install paddlepaddle` - * 对于需要**GPU版本PaddlePaddle**的用户: `pip install paddlepaddle-gpu` 或 `pip3 install paddlepaddle-gpu` > 1. 为防止出现nccl.h找不到的问题请首先按照NVIDIA[官方网站](https://developer.nvidia.com/nccl/nccl-download)的指示正确安装nccl2 > 2. 如果您不规定pypi包版本号，我们默认为您提供支持Cuda 9/cuDNN v7的PaddlePaddle版本。 - 对于出现`Cannot uninstall 'six'.`问题的用户，可是由于您的系统中已有的Python安装问题造 成的，请使用`pip install paddlepaddle --ignore-installed six`（CPU）或`pip install paddlepaddle-gpu --ignore-installed six`（GPU）解决。 + * 对于出现`Cannot uninstall 'six'.`问题的用户，可是由于您的系统中已有的Python安装问题造 成的，请使用`pip install paddlepaddle --ignore-installed six`（CPU）或`pip install paddlepaddle-gpu --ignore-installed six`（GPU）解决。 * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` @@ -130,14 +127,10 @@ Python3.5: (由于在CentOS下安装Python3的方法较为复杂，我们提供 1. 使用以下指令拉取我们为您预安装好PaddlePaddle的镜像： - * 对于需要**CPU版本的PaddlePaddle**的用户请使用以下指令拉取我们为您预安装好*PaddlePaddle For CPU*的镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:1.1` - - - * 您也可以通过以下指令拉取任意的我们提供的Docker镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` diff --git a/doc/fluid/beginners_guide/install/install_MacOS.md b/doc/fluid/beginners_guide/install/install_MacOS.md index 0ed481c69365a..45c5acaf60234 100644 --- a/doc/fluid/beginners_guide/install/install_MacOS.md +++ b/doc/fluid/beginners_guide/install/install_MacOS.md @@ -38,13 +38,15 @@ 其次，您的计算机需要满足以下要求： -> **请不要使用MacOS中自带python**，对于**Python2**，建议您使用[Homebrew](https://brew.sh)或[Python.org](https://www.python.org/ftp/python/2.7.15/python-2.7.15-macosx10.9.pkg)提供的python2.7.15；对于**Python3**，请使用[Python.org](https://www.python.org/downloads/mac-osx/)提供的python3.5.x。 +> **请不要使用MacOS中自带python**，对于**Python2**，建议您使用[Homebrew](https://brew.sh)或[Python.org](https://www.python.org/ftp/python/2.7.15/python-2.7.15-macosx10.9.pkg)提供的python2.7.15；对于**Python3**，请使用[Python.org](https://www.python.org/downloads/mac-osx/)提供的python3.5.x、python3.6.x或python3.7.x。 For python2: brew install python@2 或 使用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 +* 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 > 注： 您的MacOS上可能已经安装pip请使用pip -V来确认我们建议使用pip 9.0.1或更高版本来安装。 @@ -54,8 +56,6 @@ 1. 使用pip install来安装PaddlePaddle： * 对于需要**CPU版本PaddlePaddle**的用户：`pip install paddlepaddle` 或 `pip3 install paddlepaddle` - - * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` @@ -84,12 +84,10 @@ 1. 使用以下指令拉取我们为您预安装好PaddlePaddle的镜像： - * 对于需要**CPU版本的PaddlePaddle**的用户请使用以下指令拉取我们为您预安装好*PaddlePaddle For CPU*的镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:1.1` - * 您也可以通过以下指令拉取任意的我们提供的Docker镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` diff --git a/doc/fluid/beginners_guide/install/install_Ubuntu.md b/doc/fluid/beginners_guide/install/install_Ubuntu.md index 44a14999d5f19..80867aef3198f 100644 --- a/doc/fluid/beginners_guide/install/install_Ubuntu.md +++ b/doc/fluid/beginners_guide/install/install_Ubuntu.md @@ -43,21 +43,28 @@

### ***使用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.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` + uname -m && cat /etc/*release > 上面的命令将会显示本机的操作系统和位数信息，请确保您的计算机和本教程的要求一致。 @@ -65,25 +72,24 @@ Python3.5（该指令适用于本机未安装python2的用户，否则，请卸 其次，您的电脑需要满足以下任一要求： * Python2.7.x (dev)，Pip >= 9.0.1 -* Python3.5.x (dev)，Pip3 >= 9.0.1 +* Python3.5+.x (dev)，Pip3 >= 9.0.1 - > 您的Ubuntu上可能已经安装pip请使用pip -V或pip3 -V来确认我们建议使用pip 9.0.1或更高版本来安装 +> 您的Ubuntu上可能已经安装pip请使用pip -V或pip3 -V来确认我们建议使用pip 9.0.1或更高版本来安装 更新apt的源： `apt update` - 使用以下命令安装或升级Python和pip到需要的版本： +使用以下命令安装或升级Python和pip到需要的版本：（python3.6、python3.7安装pip和dev在不同Ubuntu版本下差别较大，不一一描述） - For python2： `sudo apt install python-dev python-pip` - - For python3：`sudo apt install python3.5-dev` and `curl https://bootstrap.pypa.io/get-pip.py -o - | python3.5 && easy_install pip` - - > 即使您的环境中已经有Python2或Python3也需要安装Python-dev或Python3.5-dev。 + - 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： 我们默认您应准备好python3.6（3.7）以及对应版本的dev和pip3 +> 即使您的环境中已经有Python2或Python3也需要安装Python-dev或Python3.5（3.6、3.7）-dev。 现在，让我们来安装PaddlePaddle： 1. 使用pip install来安装PaddlePaddle - * 对于需要**CPU版本PaddlePaddle**的用户：`pip install paddlepaddle` 或 `pip3 install paddlepaddle` - + * 对于需要**CPU版本PaddlePaddle**的用户：`pip install paddlepaddle` 或 `pip3 install paddlepaddle` * 对于需要**GPU版本PaddlePaddle**的用户：`pip install paddlepaddle-gpu` 或 `pip3 install paddlepaddle-gpu` @@ -92,11 +98,9 @@ Python3.5（该指令适用于本机未安装python2的用户，否则，请卸 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. 如果您不规定pypi包版本号，我们默认为您提供支持Cuda 9/cuDNN v7的PaddlePaddle版本。 - - 对于出现`Cannot uninstall 'six'.`问题的用户，可是由于您的系统中已有的Python安装问题造成的，请使用`pip install paddlepaddle --ignore-installed six`（CPU）或`pip install paddlepaddle --ignore-installed six`（GPU）解决。 + * 对于出现`Cannot uninstall 'six'.`问题的用户，可是由于您的系统中已有的Python安装问题造成的，请使用`pip install paddlepaddle --ignore-installed six`（CPU）或`pip install paddlepaddle --ignore-installed six`（GPU）解决。 * 对于有**其他要求**的用户：`pip install paddlepaddle==[版本号]` 或 `pip3 install paddlepaddle==[版本号]` @@ -126,17 +130,14 @@ Python3.5（该指令适用于本机未安装python2的用户，否则，请卸 1. 使用以下指令拉取我们为您预安装好PaddlePaddle的镜像： - * 对于需要**CPU版本的PaddlePaddle**的用户请使用以下指令拉取我们为您预安装好*PaddlePaddle For CPU*的镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:1.1` - * 对于需要**GPU版本的PaddlePaddle**的用户请使用以下指令拉取我们为您预安装好*PaddlePaddle For GPU*的镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:1.1-gpu-cuda9.0-cudnn7` - * 您也可以通过以下指令拉取任意的我们提供的Docker镜像： `docker pull hub.baidubce.com/paddlepaddle/paddle:[tag]` diff --git a/doc/fluid/dev/new_op_cn.md b/doc/fluid/dev/new_op_cn.md index eb6ca6012487f..23e562d4cb7f4 100644 --- a/doc/fluid/dev/new_op_cn.md +++ b/doc/fluid/dev/new_op_cn.md @@ -1,4 +1,4 @@ -# 如何写新的Operator +# 如何写新的operator - [概念简介](#概念简介) - [实现C++类](#实现c类) diff --git a/doc/fluid/index_cn.rst b/doc/fluid/index_cn.rst index 1e0ece89ed803..d524b85496c0a 100644 --- a/doc/fluid/index_cn.rst +++ b/doc/fluid/index_cn.rst @@ -14,5 +14,5 @@ beginners_guide/index.rst user_guides/index.rst advanced_usage/index.rst - api/index_cn.rst + api_cn/index_cn.rst release_note.rst diff --git a/doc/fluid/user_guides/howto/basic_concept/index_cn.rst b/doc/fluid/user_guides/howto/basic_concept/index_cn.rst new file mode 100644 index 0000000000000..010b4bfaa2939 --- /dev/null +++ b/doc/fluid/user_guides/howto/basic_concept/index_cn.rst @@ -0,0 +1,12 @@ +############ +基本概念 +############ + +本文介绍Fluid版本基本使用概念： + +- `LoD-Tensor使用说明 `_ : LoD-Tensor是Fluid中特有的概念，它在Tensor基础上附加了序列信息，支持处理变长数据。 + +.. toctree:: + :hidden: + + lod_tensor.rst diff --git a/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md b/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst similarity index 56% rename from doc/fluid/user_guides/howto/prepare_data/lod_tensor.md rename to doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst index 01b28d2a372ce..67fa5af5ee550 100644 --- a/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md +++ b/doc/fluid/user_guides/howto/basic_concept/lod_tensor.rst @@ -1,10 +1,13 @@ -# LoD-Tensor使用说明 +################## +LoD-Tensor使用说明 +################## LoD(Level-of-Detail) Tensor是Fluid中特有的概念，它在Tensor基础上附加了序列信息。Fluid中可传输的数据包括：输入、输出、网络中的可学习参数，全部统一使用LoD-Tensor表示。 阅读本文档将帮助您了解 Fluid 中的 LoD-Tensor 设计思想，以便您更灵活的使用这一数据类型。 -## 变长序列的挑战 +变长序列的挑战 +================ 大多数的深度学习框架使用Tensor表示一个mini-batch。 @@ -19,7 +22,8 @@ LoD(Level-of-Detail) Tensor是Fluid中特有的概念，它在Tensor基础上附 Fluid引入了一个索引数据结构（LoD）来将张量分割成序列。 -## LoD 索引 +LoD 索引 +=========== 为了更好的理解LoD的概念，本节提供了几个例子供您参考： @@ -27,97 +31,118 @@ Fluid引入了一个索引数据结构（LoD）来将张量分割成序列。 假设一个mini-batch中有3个句子，每个句子中分别包含3个、1个和2个单词。我们可以用(3+1+2)xD维Tensor 加上一些索引信息来表示这个mini-batch: -``` -3 1 2 -| | | | | | -``` -上述表示中，每一个`|` 代表一个D维的词向量，数字3，1，2构成了 1-level LoD。 +.. code-block :: python + + 3 1 2 + | | | | | | + +上述表示中，每一个 :code:`|` 代表一个D维的词向量，数字3，1，2构成了 1-level LoD。 **递归序列** + 让我们来看另一个2-level LoD-Tensor的例子：假设存在一个mini-batch中包含3个句子、1个句子和2个句子的文章，每个句子都由不同数量的单词组成，则这个mini-batch的样式可以看作： -``` -3 1 2 -3 2 4 1 2 3 -||| || |||| | || ||| -``` + +.. code-block :: python + + 3 1 2 + 3 2 4 1 2 3 + ||| || |||| | || ||| + 表示的LoD信息为： -``` -[[3，1，2]/*level=0*/，[3，2，4，1，2，3]/*level=1*/] -``` + +.. code-block :: python + + [[3，1，2]/*level=0*/，[3，2，4，1，2，3]/*level=1*/] + **视频的mini-batch** 在视觉任务中，时常需要处理视频和图像这些元素是高维的对象，假设现存的一个nimi-batch包含3个视频，分别有3个，1个和2个帧，每个帧都具有相同大小：640x480，则这个mini-batch可以被表示为： -``` -3 1 2 -口口口 口 口口 -``` -最底层tensor大小为（3+1+2）x640x480，每一个`口` 表示一个640x480的图像 +.. code-block :: python + + 3 1 2 + 口口口 口 口口 + + +最底层tensor大小为（3+1+2）x640x480，每一个 :code:`口` 表示一个640x480的图像 **图像的mini-batch** 在传统的情况下，比如有N个固定大小的图像的mini-batch，LoD-Tensor表示为: -``` -1 1 1 1 1 -口口口口 ... 口 -``` +.. code-block :: python + + 1 1 1 1 1 + 口口口口 ... 口 + 在这种情况下，我们不会因为索引值都为1而忽略信息，仅仅把LoD-Tensor看作是一个普通的张量: -``` -口口口口 ... 口 -``` + +.. code-block :: python + + 口口口口 ... 口 **模型参数** 模型参数只是一个普通的张量，在Fluid中它们被表示为一个0-level LoD-Tensor。 - -## LoDTensor的偏移表示 +LoDTensor的偏移表示 +===================== 为了快速访问基本序列，Fluid提供了一种偏移表示的方法——保存序列的开始和结束元素，而不是保存长度。 在上述例子中，您可以计算基本元素的长度： -``` -3 2 4 1 2 3 -``` + +.. code-block :: python + + 3 2 4 1 2 3 + 将其转换为偏移表示： -``` -0 3 5 9 10 12 15 - = = = = = = - 3 2+3 4+5 1+9 2+10 3+12 -``` + +.. code-block :: python + + 0 3 5 9 10 12 15 + = = = = = = + 3 2+3 4+5 1+9 2+10 3+12 + 所以我们知道第一个句子是从单词0到单词3，第二个句子是从单词3到单词5。 类似的，LoD的顶层长度 -``` -3 1 2 -``` + +.. code-block :: python + + 3 1 2 + 可以被转化成偏移形式： -``` -0 3 4 6 - = = = - 3 3+1 4+2 -``` + +.. code-block :: python + + 0 3 4 6 + = = = + 3 3+1 4+2 因此该LoD-Tensor的偏移表示为： -``` -0 3 4 6 - 3 5 9 10 12 15 -``` -## LoD-Tensor +.. code-block :: python + + 0 3 4 6 + 3 5 9 10 12 15 + + +LoD-Tensor +============= 一个LoD-Tensor可以被看作是一个树的结构，树叶是基本的序列元素，树枝作为基本元素的标识。 -在 Fluid 中 LoD-Tensor 的序列信息有两种表述形式：原始长度和偏移量。在 Paddle 内部采用偏移量的形式表述 LoD-Tensor，以获得更快的序列访问速度；在 python API中采用原始长度的形式表述 LoD-Tensor 方便用户理解和计算，并将原始长度称为：`recursive_sequence_lengths` 。 +在 Fluid 中 LoD-Tensor 的序列信息有两种表述形式：原始长度和偏移量。在 Paddle 内部采用偏移量的形式表述 LoD-Tensor，以获得更快的序列访问速度；在 python API中采用原始长度的形式表述 LoD-Tensor 方便用户理解和计算，并将原始长度称为： :code:`recursive_sequence_lengths` 。 以上文提到的一个2-level LoD-Tensor为例： -``` -3 1 2 -3 2 4 1 2 3 -||| || |||| | || ||| -``` + +.. code-block :: python + + 3 1 2 + 3 2 4 1 2 3 + ||| || |||| | || ||| - 以偏移量表示此 LoD-Tensor:[ [0,3,4,6] , [0,3,5,9,10,12,15] ]， - 以原始长度表达此 Lod-Tensor：recursive_sequence_lengths=[ [3-0 , 4-3 , 6-4] , [3-0 , 5-3 , 9-5 , 10-9 , 12-10 , 15-12] ]。 @@ -125,115 +150,133 @@ Fluid引入了一个索引数据结构（LoD）来将张量分割成序列。 以文字序列为例： [3,1,2] 可以表示这个mini-batch中有3篇文章，每篇文章分别有3、2、1个句子，[3,2,4,1,2,3] 表示每个句子中分别含有3、2、4、1、2、3个字。 recursive_seq_lens 是一个双层嵌套列表，也就是列表的列表，最外层列表的size表示嵌套的层数，也就是lod-level的大小；内部的每个列表，对应表示每个lod-level下，每个元素的大小。 -```python -#查看lod-tensor嵌套层数 -print len(recursive_seq_lengths) -# output：2 -#查看最基础元素个数 -print sum(recursive_seq_lengths[-1]) -# output:15 (3+2+4+1+2+3=15) +.. code-block :: python + + #查看lod-tensor嵌套层数 + print len(recursive_seq_lengths) + # output：2 -``` + #查看最基础元素个数 + print sum(recursive_seq_lengths[-1]) + # output:15 (3+2+4+1+2+3=15) -## 代码示例 +代码示例 +=========== 本节代码将根据指定的级别y-lod，扩充输入变量x。本例综合了LoD-Tensor的多个重要概念，跟随代码实现，您将： -- 直观理解Fluid中 `fluid.layers.sequence_expand` 的实现过程 +- 直观理解Fluid中 :code:`fluid.layers.sequence_expand` 的实现过程 - 掌握如何在Fluid中创建LoD-Tensor - 学习如何打印LoDTensor内容 **创建LoD-Tensor** -Fluid中可以通过`fluid.create_lod_tensor()`创建一个LoD-Tensor，使用说明请参考[API reference](http://paddlepaddle.org/documentation/api/zh/develop/fluid.html#create-lod-tensor)。需要注意的是，这个API只能支持int64的数据，如果您希望处理float32的数据，推荐您使用下述方式创建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值： -```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 -``` + +.. 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 的数据进行扩充，关于`fluid.layers.sequence_expand` 的功能说明，请先阅读[API reference](http://www.paddlepaddle.org/documentation/api/zh/0.15.0/layers.html#sequence-expand)。 +layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充，关于 :code:`fluid.layers.sequence_expand` 的功能说明，请先阅读 :ref:`api_fluid_layers_sequence-expand` 。 序列扩充代码实现： -```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) -out = fluid.layers.sequence_expand(x=x, y=y, ref_level=0) -``` + +.. 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) + out = fluid.layers.sequence_expand(x=x, y=y, ref_level=0) + *说明*：输出LoD-Tensor的维度仅与传入的真实数据维度有关，在定义网络结构阶段为x、y设置的shape值，仅作为占位，并不影响结果。 **创建Executor** -```python -place = fluid.CPUPlace() -exe = fluid.Executor(place) -exe.run(fluid.default_startup_program()) -``` - + +.. code-block :: python + + place = fluid.CPUPlace() + exe = fluid.Executor(place) + exe.run(fluid.default_startup_program()) **准备数据** -这里我们使用[偏移量](#LoDTensor的偏移表示)的方法表示Tensor的LoD索引： +这里我们使用偏移量的方法表示Tensor的LoD索引： 假使x_d 为一个LoDTensor： -``` -x.lod = [[0,1,4]] -x.data = [[1],[2],[3],[4]] -x.dims = [4,1] -``` + +.. code-block :: shell + + x.lod = [[0,1,4]] + x.data = [[1],[2],[3],[4]] + x.dims = [4,1] + y_d 也为一个LoDTensor： -``` -y.lod = [[0, 1, 4], - [0, 2, 3, 5, 6]] -``` + +.. code-block :: shell + + y.lod = [[0, 1, 4], + [0, 2, 3, 5, 6]] + 其中，输出值只与 y 的LoD值有关，y_d 的 data 值在这里并不参与计算，维度上与LoD[-1]一致即可。 预期输出结果为： -``` -#预期输出lod的原始长度 -out.lod = [ [1, 3, 3, 3]] -#预期输出结果 -out.data = [ [1],[2],[3],[4],[2],[3],[4],[2],[3],[4]] -``` + +.. code-block :: shell + + #预期输出lod的原始长度 + out.lod = [ [1, 3, 3, 3]] + #预期输出结果 + out.data = [ [1],[2],[3],[4],[2],[3],[4],[2],[3],[4]] + 实现代码如下： -```python -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) -``` + +.. code-block :: python + + 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( )中添加`return_numpy=False`参数，获得LoD-Tensor的输出结果。 -```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) -``` +在Fluid中，LoD>1的Tensor与其他类型数据一样，使用feed定义数据传入顺序。此外，由于输出results是带有LoD信息的Tensor，需在exe.run( )中添加 :code: `return_numpy=False`参数，获得LoD-Tensor的输出结果。 + +.. 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) + **查看LodTensor结果** 由于LoDTensor的特殊属性，无法直接print查看内容，常用操作时将LoD-Tensor作为网络的输出fetch出来，然后执行 numpy.array(lod_tensor), 就能转成numpy array： -```python -np.array(results[0]) -``` +.. code-block :: python + + np.array(results[0]) + 输出结果为： -``` -array([[1],[2],[3],[4],[2],[3],[4],[2],[3],[4]]) -``` -可以看到与[准备数据](#准备数据)一节中的预期结果一致。 -## 总结 +.. code-block :: python + + array([[1],[2],[3],[4],[2],[3],[4],[2],[3],[4]]) + +可以看到与准备数据一节中的预期结果一致。 + +总结 +======== 至此，相信您已经基本掌握了LoD-Tensor的概念，尝试修改上述代码中的 x_d 与 y_d，观察输出结果，有助于您更好的理解这一灵活的结构。 -更多LoDTensor的模型应用，可以参考新手入门中的[词向量](../../../beginners_guide/basics/word2vec/index.html)、[个性化推荐](../../../beginners_guide/basics/recommender_system/index.html)、[情感分析](../../../beginners_guide/basics/understand_sentiment/index.html)等指导教程。 +更多LoDTensor的模型应用，可以参考新手入门中的 `词向量 <../../../beginners_guide/basics/word2vec/index.html>`_ 、`个性化推荐 <../../../beginners_guide/basics/recommender_system/index.html>`_、`情感分析 <../../../beginners_guide/basics/understand_sentiment/index.html>`_ 等指导教程。 -更高阶的应用案例，请参考[模型库](../../../user_guides/models/index.html)中的相关内容。 +更高阶的应用案例，请参考 `模型库 <../../../user_guides/models/index_cn.html>`_ 中的相关内容。 diff --git a/doc/fluid/user_guides/howto/evaluation_and_debugging/index.rst b/doc/fluid/user_guides/howto/evaluation_and_debugging/index.rst index e2395bc09ce5a..bb0ec018522fe 100644 --- a/doc/fluid/user_guides/howto/evaluation_and_debugging/index.rst +++ b/doc/fluid/user_guides/howto/evaluation_and_debugging/index.rst @@ -3,7 +3,7 @@ ############### .. toctree:: - :maxdepth: 2 + :maxdepth: 1 evaluation/metrics.rst debug/visualdl.md diff --git a/doc/fluid/user_guides/howto/prepare_data/index.rst b/doc/fluid/user_guides/howto/prepare_data/index.rst index 930a4dbcb2b4f..338035b8c136a 100644 --- a/doc/fluid/user_guides/howto/prepare_data/index.rst +++ b/doc/fluid/user_guides/howto/prepare_data/index.rst @@ -35,14 +35,14 @@ Python Reader是纯的Python端接口，数据传入与模型训练/预测过程 数据，具体请参考: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 feeding_data.rst Python Reader支持组batch、shuffle等高级功能，具体请参考： .. toctree:: - :maxdepth: 2 + :maxdepth: 1 reader.md @@ -52,17 +52,6 @@ py_reader接口异步方式 Fluid提供PyReader异步数据传入方式，数据传入与模型训练/预测过程是异步的，效率较高。具体请参考： .. toctree:: - :maxdepth: 2 + :maxdepth: 1 use_py_reader.rst - - -LoD-Tensor简介 -##################### - -LoD-Tensor是Fluid中特有的概念，它在Tensor基础上附加了序列信息，支持处理变长数据。具体请参考： - -.. toctree:: - :maxdepth:2 - - lod_tensor.md \ No newline at end of file diff --git a/doc/fluid/user_guides/howto/training/index.rst b/doc/fluid/user_guides/howto/training/index.rst index 68475101e26b3..f021e7f3bbde8 100644 --- a/doc/fluid/user_guides/howto/training/index.rst +++ b/doc/fluid/user_guides/howto/training/index.rst @@ -5,7 +5,7 @@ PaddlePaddle Fluid支持单机训练，和多节点训练。每种训练模式下，都支持多种训练方法。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 single_node multi_node diff --git a/doc/fluid/user_guides/howto/training/multi_node.rst b/doc/fluid/user_guides/howto/training/multi_node.rst index 93df4abd4d1bf..9008f47c1e88c 100644 --- a/doc/fluid/user_guides/howto/training/multi_node.rst +++ b/doc/fluid/user_guides/howto/training/multi_node.rst @@ -3,7 +3,7 @@ ######## .. toctree:: - :maxdepth: 2 + :maxdepth: 1 cluster_quick_start.rst cluster_howto.rst diff --git a/doc/fluid/user_guides/index.rst b/doc/fluid/user_guides/index.rst index 91e1e521c7f26..f828f3d0b8b81 100644 --- a/doc/fluid/user_guides/index.rst +++ b/doc/fluid/user_guides/index.rst @@ -2,15 +2,11 @@ 使用指南 ######## -============== - 概览 -============== .. todo:: 如果您已经掌握了新手入门阶段的内容，期望可以针对实际问题建模、搭建自己网络，本模块提供了一些 Fluid 的使用细节供您参考： - - - `Fluid 设计思想 <../user_guides/design_idea/fluid_design_idea.html>`_：介绍 Fluid 底层的设计思想，帮助用户更好的理解框架运作过程 + - `基本概念 <../user_guides/howto/basic_concept/index_cn.rst>`_ ：介绍了Fluid的基本使用概念 - `准备数据 <../user_guides/howto/prepare_data/index.html>`_ ：介绍使用 Fluid 训练网络时，数据的支持类型及传输方法 @@ -23,25 +19,16 @@ - `模型评估 <../user_guides/howto/evaluation_and_debugging/evaluation/metrics.html>`_：介绍常用模型评估指标的构造方法 - `Visual DL 工具 <../user_guides/howto/evaluation_and_debugging/debug/visualdl.html>`_：介绍如何利用 Visual DL 工具可视化训练过程 - - `预测部署 <../user_guides/howto/inference/index.html>`_：介绍如何应用训练好的模型进行预测 - - 基于 Fluid 复现的多领域经典模型： - `Fluid 模型库 <../user_guides/models/index_cn.html>`_ - -============== - 目录 -============== - .. toctree:: - :maxdepth: 2 + :hidden: + howto/basic_concept/index_cn.rst howto/prepare_data/index howto/configure_simple_model/index howto/training/index howto/evaluation_and_debugging/index - howto/inference/index models/index_cn.rst - design_idea/fluid_design_idea.md diff --git a/external/book b/external/book index b22b286a7ddf2..ef2934505b87e 160000 --- a/external/book +++ b/external/book @@ -1 +1 @@ -Subproject commit b22b286a7ddf2579541815aff98ee3b803fde9b3 +Subproject commit ef2934505b87eeb516eed7d083900ec88a62fb20