fluid.layers

SourceEnglish

control_flow

SourceEnglish

array_length

SourceEnglish

• paddle.fluid.layers.arraylength(_array)
• 得到输入LoDTensorArray的长度

此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。

• 相关API:
• • array_read
  • array_write
  • While
• 参数：
• • array (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度返回：输入数组LoDTensorArray的长度

返回类型：变量（Variable）

代码示例:

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)

array_read

SourceEnglish

• paddle.fluid.layers.arrayread(_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）

代码示例：

array = fluid.layers.create_array(dtype='float32')
i = fluid.layers.fill_constant(shape=[1],dtype='int64',value=10)
item = fluid.layers.array_read(array, i)

array_write

SourceEnglish

• paddle.fluid.layers.arraywrite(_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）

代码示例

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)

create_array

SourceEnglish

• paddle.fluid.layers.createarray(_dtype)

• 创建LoDTensorArray数组。它主要用于实现RNN与array_write, array_read和While。

• 参数:

• • dtype (int |float) — lod_tensor_array中存储元素的数据类型。返回: lod_tensor_array， 元素数据类型为dtype。

返回类型: Variable。

代码示例

data = fluid.layers.create_array(dtype='float32')

DynamicRNN

SourceEnglish

• class paddle.fluid.layers.DynamicRNN(name=None)
• 动态RNN可以处理一批序列数据,每个样本序列的长度可以不同。这个API自动批量处理它们。

必须设置输入lod，请参考 lod_tensor

代码示例

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()获得输出序列。

注解

目前不支持在DynamicRNN中任何层上配置 is_sparse = True

• stepinput(_x, level=0)

• 将序列标记为动态RNN输入。

• 参数:

• x (Variable) - 输入序列

• level (int) - 用于拆分步骤的LOD层级，默认值0返回:当前的输入序列中的timestep。

• staticinput(_x)

• 将变量标记为RNN输入。输入不会分散到timestep中。

• 参数:

• • x (Variable) - 输入序列返回:可以访问的RNN的输入变量,。

• block()

• 用户在RNN中定义operators的block。

• memory(init=None, shape=None, value=0.0, need_reorder=False, dtype='float32')

• 为动态rnn创建一个memory 变量。

如果 init 不是None， memory 将由这个变量初始化。参数 need_reorder 用于将memory重新排序作为输入变量。当memory初始化依赖于输入样本时，应该将其设置为true。

例如

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 初始化

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_size
  • value (float) – 初始化的值
  • need_reorder (bool) – memory初始化依赖于输入样本时设置为True
  • dtype (str|numpy.dtype) – 初始化memory的数据类型返回：memory Variable

• updatememory(_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

• output(*outputs)

• 标记RNN输出变量。

• 参数:

• • *outputs - 输出变量。返回:None

equal

SourceEnglish

• paddle.fluid.layers.equal(x, y, cond=None)
• equal该层返回

按逐元素运算而得的真值。

• 参数：
• • x (Variable)-equal的第一个操作数
  • y (Variable)-equal的第二个操作数
  • cond (Variable|None)-输出变量（可选），用来存储equal的结果返回：张量类型的变量，存储equal的输出结果

返回类型：变量（Variable）

代码示例:

less = fluid.layers.equal(x=label,y=limit)

IfElse

SourceEnglish

• class paddle.fluid.layers.IfElse(cond, name=None)

• if-else控制流。

• 参数：

• • cond (Variable)-用于比较的条件
  • Name (str,默认为空（None）)-该层名称代码示例：

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()

increment

SourceEnglish

• paddle.fluid.layers.increment(x, value=1.0, in_place=True)
• 该函数为输入 x 增加 value 大小, value 即函数中待传入的参数。该函数默认直接在原变量 x 上进行运算。

注解

x 中元素个数必须为1

• 参数:
• • x (Variable|list) – 含有输入值的张量(tensor)
  • value (float) – 需要增加在 x 变量上的值
  • in_place (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本返回： 每个元素增加后的对象

返回类型：变量(variable)

代码示例

data = fluid.layers.data(name='data', shape=[1], dtype='float32',
                     append_batch_size=False)
data = fluid.layers.increment(x=data, value=3.0, in_place=True)

is_empty

SourceEnglish

• paddle.fluid.layers.isempty(_x, cond=None)

• 测试变量是否为空

• 参数：

• • x (Variable)-测试的变量
  • cond (Variable|None)-输出参数。返回给定x的测试结果，默认为空（None）返回：布尔类型的标量。如果变量x为空则值为真

返回类型：变量（Variable）

抛出异常：TypeError-如果input不是变量或cond类型不是变量

代码示例：

res = fluid.layers.is_empty(x=input)
# or:
fluid.layers.is_empty(x=input, cond=res)

less_than

SourceEnglish

• paddle.fluid.layers.lessthan(_x, y, force_cpu=None, cond=None)
• 该函数按元素出现顺序依次在X,Y上操作，并返回 Out ，它们三个都是n维tensor（张量）。其中，X、Y可以是任何类型的tensor，Out张量的各个元素可以通过

计算得出。

代码示例

import paddle.fluid as fluid
less = fluid.layers.less_than(x=label, y=limit)

• 参数：
• • x (Variable) – less_than 运算的左操作数
  • y (Variable) – less_than 运算的右操作数
  • force_cpu (BOOLEAN) – 值True则强制将输出变量写入CPU内存中。否则，将其写入目前所在的运算设备上。默认为True
  • cond (Variable|None) – 可选的用于存储 lessthan 输出结果的变量，为None则由函数自动生成Out变量返回： n维bool型tensor，其中各个元素可以通过 _Out=X<Y 计算得出

Print

SourceEnglish

• 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）

代码示例：

value = some_layer(...)
Print(value, summarize=10,
message="The content of some_layer: ")

reorder_lod_tensor_by_rank

SourceEnglish

• paddle.fluid.layers.reorderlod_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

StaticRNN

SourceEnglish

• class paddle.fluid.layers.StaticRNN(name=None)

• 用于创建static RNN。RNN将有自己的参数，比如输入、输出、memory、状态和长度。

• 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大小的索引

Switch

SourceEnglish

• class 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所对应的分支，且仅此分支。

代码示例

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)

• case(condition)

• 为该condition（情况，条件）建立新的block（块）。

• default()

• 为该switch建立default case。

While

SourceEnglish

• class paddle.fluid.layers.While(cond, is_test=False, name=None)

• 该类用于实现while循环控制功能。

• 参数：

• • cond (Variable) – 用于比较的条件
  • is_test (bool) – 用于表明是不是在测试阶段执行
  • name (str) - 该层的命名代码示例

d0 = fluid.layers.data("d0", shape=[10], dtype='float32')
data_array = fluid.layers.array_write(x=d0, i=i)
array_len = fluid.layers.fill_constant(shape=[1],dtype='int64', value=3)
 
cond = fluid.layers.less_than(x=i, y=array_len)
while_op = fluid.layers.While(cond=cond)
with while_op.block():
    d = fluid.layers.array_read(array=data_array, i=i)
    i = fluid.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)

io

SourceEnglish

batch

SourceEnglish

• paddle.fluid.layers.batch(reader, batch_size)

• 该层是一个reader装饰器。接受一个reader变量并添加batching装饰。读取装饰的reader，输出数据自动组织成batch的形式。

• 参数：

• • reader (Variable)-装饰有“batching”的reader变量
  • batch_size (int)-批尺寸返回：装饰有batching的reader变量

返回类型：变量(Variable)

代码示例：

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数据而不是一个实例。

create_py_reader_by_data

SourceEnglish

• paddle.fluid.layers.createpy_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) - 缓冲区容量由 py_reader 维护
  • feed_list (list(Variable)) - 传输数据列表
  • name (basestring) - 前缀Python队列名称和 reader 名称。不定义时将自动生成名称。
  • use_double_buffer (bool) - 是否使用 double buffer返回： Variable: 一种reader，我们可以从中获得输入数据。

代码示例：

py_reader 的基本用法如下所示：

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()

data

SourceEnglish

• 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)-声明维度信息的list。如果 append_batch_size 为True且内部没有维度值为-1，则应将其视为每个样本的形状。 否则，应将其视为batch数据的形状。

  • append_batch_size (bool)-

1.如果为真，则在维度shape的开头插入-1“如果shape=[1],则输出shape为[-1,1].”

2.如果维度shape包含-1，比如shape=[-1,1],“append_batch_size则为False（表示无效）”

• dtype (basestring)-数据类型：float32,float_16,int等

• type (VarType)-输出类型。默认为LOD_TENSOR

• lod_level (int)-LoD层。0表示输入数据不是一个序列

• stop_gradient (bool)-布尔类型，提示是否应该停止计算梯度

返回：全局变量，可进行数据访问

返回类型：变量(Variable)

代码示例：

data = fluid.layers.data(name='x', shape=[784], dtype='float32')

double_buffer

SourceEnglish

• paddle.fluid.layers.doublebuffer(_reader, place=None, name=None)

• 生成一个双缓冲队列reader. 数据将复制到具有双缓冲队列的位置（由place指定），如果 place=none 则将使用executor执行的位置。

• 参数:

• • reader (Variable) – 需要wrap的reader
  • place (Place) – 目标数据的位置. 默认是executor执行样本的位置.
  • name (str) – Variable 的名字. 默认为None，不关心名称时也可以设置为None返回： 双缓冲队列的reader

代码示例

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)

load

SourceEnglish

• paddle.fluid.layers.load(out, file_path, load_as_fp16=None)
• Load操作命令将从磁盘文件中加载LoDTensor/SelectedRows变量。

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

open_files

SourceEnglish

• paddle.fluid.layers.openfiles(_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)

代码示例：

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)

Preprocessor

SourceEnglish

• class paddle.fluid.layers.Preprocessor(reader, name=None)

• reader变量中数据预处理块。

• 参数：

• • reader (Variable)-reader变量
  • name (str,默认None)-reader的名称代码示例:

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())

py_reader

SourceEnglish

• paddle.fluid.layers.pyreader(_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 基本使用如下代码

    import paddle
    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.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()
 
fluid.io.save_inference_model(dirname='./model', feeded_var_names=[img, label],target_vars=[loss], executor=fluid.Executor(fluid.CUDAPlace(0)))

2.训练和测试应使用不同的名称创建两个不同的py_reader，例如：

import paddle
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.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()

random_data_generator

SourceEnglish

• paddle.fluid.layers.randomdata_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)

代码示例：

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)

read_file

SourceEnglish

• paddle.fluid.layers.readfile(_reader)
• 执行给定的reader变量并从中获取数据

reader也是变量。可以为由fluid.layers.open_files()生成的原始reader或者由fluid.layers.double_buffer()生成的装饰变量，等等。

• 参数：
• • reader (Variable)-将要执行的reader返回：从给定的reader中读取数据

返回类型: tuple（元组）

代码示例：

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)

shuffle

SourceEnglish

• paddle.fluid.layers.shuffle(reader, buffer_size)

• 创建一个特殊的数据读取器，它的输出数据会被重洗(shuffle)。由原始读取器创建的迭代器得到的输出将会被暂存到shuffle缓存区，其后会对其进行重洗运算。shuffle缓存区的大小由参数 buffer_size 决定。

• 参数:

• • reader (callable) – 输出会被shuffle的原始reader
  • buffer_size (int) – 进行shuffle的buffer的大小返回:其输出会被shuffle的一个reader（读取器）

返回类型:Variable

nn

SourceEnglish

adaptive_pool2d

SourceEnglish

• paddle.fluid.layers.adaptivepool2d(_input, pool_size, pool_type='max', require_index=False, name=None)
• pooling2d操作根据输入 input ， pool_size ， pool_type 参数计算输出。 输入（X）和输出（Out）采用NCHW格式，其中N是批大小batch size，C是通道数，H是feature(特征)的高度，W是feature（特征）的宽度。 参数 pool_size 由两个元素构成, 这两个元素分别代表高度和宽度。 输出（Out）的H和W维与 pool_size 大小相同。

对于平均adaptive pool2d:

• 参数：
• • input （Variable） - 池化操作的输入张量。 输入张量的格式为NCHW，其中N是batch大小，C是通道数，H是特征的高度，W是特征的宽度。
  • pool_size （int | list | tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含两个整数（pool_size_Height，pool_size_Width）。
  • pool_type （string）- 池化类型，可输入“max”代表max-pooling，或者“avg”代表average-pooling。
  • require_index （bool） - 如果为true，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为true。
  • name （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。返回： 池化结果

返回类型: Variable

抛出异常:

• ValueError – pool_type 不是 ‘max’ 或 ‘avg’
• ValueError – 当 pool_type 是 ‘avg’ 时，错误地设置 ‘require_index’ 为true .
• ValueError – pool_size 应为一个长度为2的列表或元组

# 假设输入形为[N, C, H, W], `pool_size` 为 [m, n],
# 输出形为 [N, C, m, n], adaptive pool 将输入的 H 和 W 维度
# 平均分割为 m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
# adaptive average pool 进行如下操作
#
#     for i in range(m):
#         for j in range(n):
#             hstart = floor(i * H / m)
#             hend = ceil((i + 1) * H / m)
#             wstart = floor(i * W / n)
#             wend = ceil((i + 1) * W / n)
#             output[:, :, i, j] = avg(input[:, :, hstart: hend, wstart: wend])
#
data = fluid.layers.data(
    name='data', shape=[3, 32, 32], dtype='float32')
pool_out = fluid.layers.adaptive_pool2d(
                  input=data,
                  pool_size=[3, 3],
                  pool_type='avg')

adaptive_pool3d

SourceEnglish

• paddle.fluid.layers.adaptivepool3d(_input, pool_size, pool_type='max', require_index=False, name=None)
• pooling3d操作根据输入 input ，pool_size ， pool_type 参数计算输出。 输入（X）和输出（输出）采用NCDHW格式，其中N是批大小batch size，C是通道数，D是特征(feature)的深度，H是特征的高度，W是特征的宽度。 参数 pool_size 由三个元素组成。 这三个元素分别代表深度，高度和宽度。输出（Out）的D,H,W维与 pool_size 相同。

对于平均adaptive pool3d:

• 参数：
• • input （Variable） - 池化操作的输入张量。 输入张量的格式为NCDHW，其中N是batch大小，C是通道数，D为特征的深度，H是特征的高度，W是特征的宽度。
  • pool_size （int | list | tuple） - 池化核大小。 如果池化核大小是元组或列表，则它必须包含三个整数（Depth, Height, Width）。
  • pool_type （string）- 池化类型，可输入“max”代表max-pooling，或者“avg”代表average-pooling。
  • require_index （bool） - 如果为true，则输出中带有最大池化点所在的索引。 如果pool_type为avg,该项不可被设置为true。
  • name （str | None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。返回： 池化结果

返回类型: Variable

抛出异常:

• ValueError – pool_type 不是 ‘max’ 或 ‘avg’
• ValueError – 当 pool_type 是 ‘avg’ 时，错误地设置 ‘require_index’ 为true .
• ValueError – pool_size 应为一个长度为3的列表或元组

# 假设输入形为[N, C, D, H, W], `pool_size` 为 [l, m, n],
# 输出形为 [N, C, l, m, n], adaptive pool 将输入的D, H 和 W 维度
# 平均分割为 l * m * n 个栅格(grid) ，然后为每个栅格进行池化得到输出
# adaptive average pool 进行如下操作
#
#     for i in range(l):
#         for j in range(m):
#             for k in range(n):
#                 dstart = floor(i * D / l)
#                 dend = ceil((i + 1) * D / l)
#                 hstart = floor(j * H / m)
#                 hend = ceil((j + 1) * H / m)
#                 wstart = floor(k * W / n)
#                 wend = ceil((k + 1) * W / n)
#                 output[:, :, i, j, k] =
#                     avg(input[:, :, dstart:dend, hstart: hend, wstart: wend])
#
data = fluid.layers.data(
name='data', shape=[3, 32, 32], dtype='float32')
pool_out, mask = fluid.layers.adaptive_pool3d(
                  input=data,
                  pool_size=[3, 3, 3],
                  pool_type='avg')

add_position_encoding

SourceEnglish

• paddle.fluid.layers.addposition_encoding(_input, alpha, beta, name=None)
• 添加位置编码层

接受形状为[N×M×P]的三维输入张量，并返回一个形为[N×M×P]的输出张量，且输出张量具有位置编码值。

可参考论文: Attention Is All You Need

• 其中:
• • PE(pos, 2i): 偶数位置上数字的增量
  • PE(pos, 2i + 1): 奇数位置上数字的增量
• 参数:
• • input (Variable) – 形状为[N x M x P]的三维输入张量
  • alpha (float) – 输入张量的倍数
  • beta (float) – 位置编码张量Positional Encoding Tensor的倍数
  • name (string) – 位置编码层的名称返回: 具有位置编码的三维形状张量[N×M×P]

返回类型: Variable

代码示例：

position_tensor = fluid.layers.add_position_encoding(input=tensor)

affine_channel

SourceEnglish

• paddle.fluid.layers.affinechannel(_x, scale=None, bias=None, data_layout='NCHW', name=None, act=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): 此层的名称
  • act (str, default None): 应用于该层输出的激活函数返回： out (Variable): 与x具有相同形状和数据布局的张量。

affine_grid

SourceEnglish

• paddle.fluid.layers.affinegrid(_theta, out_shape, name=None)
• 它使用仿射变换的参数生成(x,y)坐标的网格，这些参数对应于一组点，在这些点上，输入特征映射应该被采样以生成转换后的输出特征映射。

* 例 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:
      按下列公式计算输出

• 参数：
• • 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: 如果输入了不支持的参数类型

代码示例：

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])

autoincreased_step_counter

SourceEnglish

• paddle.fluid.layers.autoincreasedstep_counter(_counter_name=None, begin=1, step=1)

• 创建一个自增变量，每个mini-batch返回主函数运行次数，变量自动加1，默认初始值为1.

• 参数：

• • counter_name (str)-计数名称，默认为 @STEP_COUNTER@
  • begin (int)-开始计数
  • step (int)-执行之间增加的步数返回：全局运行步数

返回类型：变量（Variable）

代码示例：

global_step = fluid.layers.autoincreased_step_counter(
    counter_name='@LR_DECAY_COUNTER@', begin=begin, step=1)

batch_norm

SourceEnglish

• paddle.fluid.layers.batchnorm(_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, use_global_stats=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的输入特征。

当use_global_stats = True时，

和 不是一个minibatch的统计数据。 它们是全局（或运行）统计数据。 （它通常来自预先训练好的模型。）训练和测试（或预测）具有相同的行为：

• 参数：
• • input (Variable) - 输入变量的排序，可以为 2, 3, 4, 5
  • act （string，默认None）- 激活函数类型，linear|relu|prelu|…
  • is_test （bool,默认False） - 指示它是否在测试阶段。
  • momentum （float，默认0.9）- 此值用于计算 moving_mean and moving_var. 更新公式为:)) ， 默认值0.9.
  • epsilon （float，默认1e-05）- 加在分母上为了数值稳定的值。默认值为1e-5。
  • param_attr （ParamAttr|None） - batch_norm参数范围的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为param_attr。如果没有设置param_attr的初始化函数，参数初始化为Xavier。默认：None
  • bias_attr （ParamAttr|None） - batch_norm bias参数的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为bias_attr。如果没有设置bias_attr的初始化函数，参数初始化为0。默认：None
  • data_layout （string,默认NCHW) - NCHW|NHWC
  • in_place （bool，默认False）- 得出batch norm可复用记忆的输入和输出
  • name （string，默认None）- 该层名称（可选）。若设为None，则自动为该层命名
  • moving_mean_name （string，默认None）- moving_mean的名称，存储全局Mean
  • moving_variance_name （string，默认None）- moving_variance的名称，存储全局变量
  • do_model_average_for_mean_and_var （bool，默认False）- 是否为mean和variance做模型均值
  • fuse_with_relu （bool）- 如果为True，batch norm后该操作符执行relu
  • use_global_stats （bool, Default False） – 是否使用全局均值和方差。 在预测或测试模式下，将use_global_stats设置为true或将is_test设置为true，并且行为是等效的。 在训练模式中，当设置use_global_stats为True时，在训练期间也使用全局均值和方差。返回： 张量，在输入中运用批正则后的结果

返回类型：变量（Variable）

代码示例：

hidden1 = fluid.layers.fc(input=x, size=200, param_attr='fc1.w')
hidden2 = fluid.layers.batch_norm(input=hidden1)

beam_search

SourceEnglish

• paddle.fluid.layers.beamsearch(_pre_ids, pre_scores, ids, scores, beam_size, end_id, level=0, is_accumulated=True, name=None, return_parent_idx=False)
• 在机器翻译任务中，束搜索(Beam search)是选择候选词的一种经典算法

更多细节参考 Beam Search

该层在一时间步中按束进行搜索。具体而言，根据候选词使用于源句子所得的 scores , 从候选词 ids 中选择当前步骤的 top-K （最佳K）候选词的id，其中 K 是 beam_size ， ids ， scores 是计算单元的预测结果。如果没有提供 ids ，则将会根据 scores 计算得出。 另外， pre_id 和 pre_scores 是上一步中 beam_search 的输出，用于特殊处理翻译的结束边界。

注意，如果 is_accumulated 为 True，传入的 scores 应该是累积分数。反之，scores 会被认为为直接得分(straightforward scores)， 并且会被转化为log值并且在此运算中会被累积到 pre_scores 中。在计算累积分数之前应该使用额外的 operators 进行长度惩罚。

有关束搜索用法演示，请参阅以下示例：

fluid/tests/book/test_machine_translation.py

• 参数:

• • pre_ids （Variable） - LodTensor变量，它是上一步 beam_search 的输出。在第一步中。它应该是LodTensor，shape为，

  • pre_scores （Variable） - LodTensor变量，它是上一步中beam_search的输出

  • ids （Variable） - 包含候选ID的LodTensor变量。shape为，其中 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中。
  • is_accumulated （bool，默认为True） - 输入分数是否为累计分数。
  • name （str | None） - 该层的名称（可选）。如果设置为None，则自动命名该层。
  • return_parent_idx （bool） - 是否返回一个额外的Tensor变量，在输出的pre_ids中保留selected_ids的双亲indice，可用于在下一个时间步收集单元状态。返回：LodTensor元组。包含所选的id和与其相应的分数。 如果return_parent_idx为True，则包含一个保留selected_ids的双亲indice的额外Tensor变量。

返回类型：Variable

代码示例

# 假设 `probs` 包含计算神经元所得的预测结果
# `pre_ids` 和 `pre_scores` 为beam_search之前时间步的输出
topk_scores, topk_indices = fluid.layers.topk(probs, k=beam_size)
accu_scores = fluid.layers.elementwise_add(
                                      x=layers.log(x=topk_scores)),
                                      y=layers.reshape(
                                          pre_scores, shape=[-1]),
                                      axis=0)
selected_ids, selected_scores = fluid.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)

beam_search_decode

SourceEnglish

• paddle.fluid.layers.beamsearch_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）

代码示例

# 假设 `ids` 和 `scores` 为 LodTensorArray变量，它们保留了
# 选择出的所有时间步的id和score
finished_ids, finished_scores = fluid.layers.beam_search_decode(
    ids, scores, beam_size=5, end_id=0)

bilinear_tensor_product

SourceEnglish

• paddle.fluid.layers.bilineartensor_product(_x, y, size, act=None, name=None, param_attr=None, bias_attr=None)
• 该层对两个输入执行双线性张量积。

例如:

• 在这个公式中：
• • : 第一个输入，包含M个元素，形状为[batch_size, M]
  • : 第二个输入，包含N个元素，形状为[batch_size, N]
  • : 第i个被学习的权重，形状是[M, N]
  • : out的第i个元素，形状是[batch_size, size]
  • :的转置
• 参数：
• • 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张量

代码示例：

tensor = bilinear_tensor_product(x=layer1, y=layer2, size=1000)

bpr_loss

SourceEnglish

• paddle.fluid.layers.bprloss(_input, label, name=None)
• Bayesian Personalized Ranking Loss Operator. (贝叶斯个性化排序损失计算)

该算子属于pairwise的排序类型，其标签是期望物品。在某次会话中某一给定点的损失值由下式计算而得:

更多细节请参考 Session Based Recommendations with Recurrent Neural Networks

• 参数:
• • input (Variable|list): 一个形为[N x D]的2-D tensor , 其中 N 为批大小batch size ，D 为种类的数量。该输入为logits而非概率。
  • label (Variable|list): 2-D tensor 类型的真实值, 形为[N x 1]
  • name (str|None): （可选）该层的命名。 如果为None, 则自动为该层命名。 默认为None.返回: 形为[N x 1]的2D张量，即bpr损失

代码示例：

cost = fluid.layers.bpr_loss(input=predict, label=label)

brelu

SourceEnglish

• paddle.fluid.layers.brelu(x, t_min=0.0, t_max=24.0, name=None)
• BRelu 激活函数

• 参数:
• • x (Variable) - BReluoperator的输入
  • t_min (FLOAT|0.0) - BRelu的最小值
  • t_max (FLOAT|24.0) - BRelu的最大值
  • name (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名代码示例：

x = fluid.layers.data(name="x", shape=[2,3,16,16], dtype=”float32”)
y = fluid.layers.brelu(x, t_min=1.0, t_max=20.0)

chunk_eval

SourceEnglish

• paddle.fluid.layers.chunkeval(_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（元组）

代码示例：

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)

clip

SourceEnglish

• paddle.fluid.layers.clip(x, min, max, name=None)
• clip算子

clip算子限制给定输入的值在一个区间内。间隔使用参数”min”和”max”来指定：公式为

• 参数：
• • x （Variable）- （Tensor）clip运算的输入，维数必须在[1,9]之间。
  • min （FLOAT）- （float）最小值，小于该值的元素由min代替。
  • max （FLOAT）- （float）最大值，大于该值的元素由max替换。
  • name （basestring | None）- 输出的名称。返回： （Tensor）clip操作后的输出和输入（X）具有形状（shape）

返回类型： 输出（Variable）。

代码示例：

input = fluid.layers.data(
    name='data', shape=[1], dtype='float32')
reward = fluid.layers.clip(x=input, min=-1.0, max=1.0)

clip_by_norm

SourceEnglish

• paddle.fluid.layers.clipby_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 ，如下面的公式所示：

其中，

代表 x 的L2范数。

• 参数：
• • x (Variable)- (Tensor) clip_by_norm运算的输入，维数必须在[1,9]之间。
  • max_norm (float)- 最大范数值。
  • name (basestring | None)- 输出的名称。返回： (Tensor)clip_by_norm操作后的输出和输入(X)具有形状(shape).

返回类型： Variable

代码示例：

input = fluid.layers.data(
    name='data', shape=[1], dtype='float32')
reward = fluid.layers.clip_by_norm(x=input, max_norm=1.0)

conv2d

SourceEnglish

• 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，有等式：

• 其中：
• • ：输入值，NCHW格式的张量（Tensor）
  • ：滤波器值，MCHW格式的张量（Tensor）
  • ： 卷积操作
  • ：Bias值，二维张量（Tensor），shape为 [M,1]
  • ：激活函数
  • ：输出值，Out 和 X 的shape可能不同示例

• 输入：

输入shape：

滤波器shape：

• 输出：

输出shape：

其中

• 参数：
• • 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的初始化函数未设置，参数则初始化为，并且std为。默认为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不匹配。代码示例：

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")

conv2d_transpose

SourceEnglish

• paddle.fluid.layers.conv2dtranspose(_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，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数。

输入

和输出 函数关系如下：

• 其中：
• • : 输入张量，具有 NCHW 格式
  • : 滤波器张量，具有 NCHW 格式
  • : 卷积操作
  • : 偏置（bias），二维张量，shape为 [M,1]
  • : 激活函数
  • : 输出值，Out和 X 的 shape 可能不一样样例：

输入：

输出：

其中

• 参数:
• • 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是一个元组，那么元组的形式为(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代码示例

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)

conv3d

SourceEnglish

• 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)
• 3D卷积层（convolution3D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀（dilations）、组数参数计算得到输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积三维（Convlution3D）和卷积二维（Convlution2D）相似，但多了一维深度（depth）。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。

对每个输入X，有等式：

• 其中：
• • ：输入值，NCDHW格式的张量（Tensor）
  • ：滤波器值，MCDHW格式的张量（Tensor）
  • ： 卷积操作
  • ：Bias值，二维张量（Tensor），形为 [M,1]
  • ：激活函数
  • ：输出值, 和 X 的形状可能不同示例
• • 输入：
  • 输入shape：

滤波器shape：

• • 输出：
  • 输出shape：

其中

• 参数：
• • input (Variable) - 格式为[N,C,D,H,W]格式的输入图像
  • num_fliters (int) - 滤波器数。和输出图像通道相同
  • filter_size (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含三个整型数，(filter_size_D, filter_size_H, filter_size_W)。否则，滤波器为棱长为int的立方体形。
  • stride (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含三个整型数， (stride_D, stride_H, stride_W)。否则，stride_D = stride_H = stride_W = stride。默认：stride = 1
  • padding (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含三个整型数，(padding_D, padding_H, padding_W)。否则， padding_D = padding_H = padding_W = padding。默认：padding = 0
  • dilation (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数， (dilation_D, dilation_H, dilation_W)。否则，dilation_D = 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的初始化函数未设置，参数则初始化为，并且std为。默认为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 不匹配。代码示例：

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")

conv3d_transpose

SourceEnglish

• paddle.fluid.layers.conv3dtranspose(_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，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数

输入X和输出Out函数关系X，有等式如下：

• 其中：
• • : 输入张量，具有 NCDHW 格式
  • : 滤波器张量，，具有 NCDHW 格式
  • : 卷积操作
  • : 偏置（bias），二维张量，shape为 [M,1]
  • : 激活函数
  • : 输出值， Out 和 X 的 shape可能不一样样例

输入:

输出:

其中：

• 参数:
• • 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代码示例

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)

cos_sim

SourceEnglish

• paddle.fluid.layers.cossim(_X, Y)
• 余弦相似度算子（Cosine Similarity Operator）

输入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)

crf_decoding

SourceEnglish

• paddle.fluid.layers.crfdecoding(_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<int64_t>)decoding结果。具体内容根据 Label 参数是否提供而定。请参照函数介绍来详细了解。

返回类型： Variable

代码示例

crf_decode = fluid.layers.crf_decoding(
     input=hidden, param_attr=ParamAttr(name="crfw"))

crop

SourceEnglish

• 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

代码示例:

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])

cross_entropy

SourceEnglish

• paddle.fluid.layers.crossentropy(_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的类别所具的索引:

   

2. Soft-label cross-entropy算法

   soft_label = True, Label[i, j] 表明样本i对应类别j的soft label(软标签):

   

   请确保采用此算法时识别为各软标签的概率总和为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时生效。 默认值: kIgnoreIndex返回： 一个形为[N x 1]的二维tensor，承载了交叉熵损失

弹出异常： ValueError

1. 当 input 的第一维和 label 的第一维不相等时，弹出异常
2. 当 soft_label 值为True， 且 input 的第二维和 label 的第二维不相等时，弹出异常
3. 当 soft_label 值为False，且 label 的第二维不是1时，弹出异常

代码示例

predict = fluid.layers.fc(input=net, size=classdim, act='softmax')
cost = fluid.layers.cross_entropy(input=predict, label=label)

ctc_greedy_decoder

SourceEnglish

• paddle.fluid.layers.ctcgreedy_decoder(_input, blank, name=None)
• 此op用于贪婪策略解码序列，步骤如下:
• • 获取输入中的每一行的最大值索引，也就是numpy.argmax(input, axis=0)。
  • 对于step1结果中的每个序列，在两个空格之间合并重复部分（即合并重复的上一步中的到的索引值）并删除所有空格。简单举一个例子，

已知：
 
input.data = [[0.6, 0.1, 0.3, 0.1],
              [0.3, 0.2, 0.4, 0.1],
              [0.1, 0.5, 0.1, 0.3],
              [0.5, 0.1, 0.3, 0.1],
 
              [0.5, 0.1, 0.3, 0.1],
              [0.2, 0.2, 0.2, 0.4],
              [0.2, 0.2, 0.1, 0.5],
              [0.5, 0.1, 0.3, 0.1]]
 
input.lod = [[4, 4]]
 
计算过程：
 
1. 将argmax的运算结果应用于输入的第一个序列，即 input.data[0:4] 。
   则得出的结果为[[0], [2], [1], [0]]
2. 合并重复的索引值部分，删除空格，即为0的值。
   则第一个输入序列对应的输出为：[[2], [1]]
 
最后
 
output.data = [[2],
               [1],
               [3]]
 
output.lod = [[2, 1]]