py_func

paddle.fluid.layers. py_func ( func, x, out, backward_func=None, skip_vars_in_backward_input=None ) [源代码]

PaddlePaddle 通过py_func在Python端注册OP。py_func的设计原理在于Paddle中的Tensor与numpy数组可以方便的互相转换，从而可使用Python中的numpy API来自定义一个Python OP。

该自定义的Python OP的前向函数是 func, 反向函数是 backward_func 。 Paddle将在前向部分调用 func ，并在反向部分调用 backward_func （如果 backward_func 不是None)。 x 为 func 的输入，必须为Tensor类型； out 为 func 的输出， 既可以是Tensor类型, 也可以是numpy数组。

反向函数 backward_func 的输入依次为：前向输入 x 、前向输出 out 、 out 的梯度。 如果 out 的某些输出没有梯度，则 backward_func 的相关输入为None。如果 x 的某些变量没有梯度，则用户应在 backward_func 中主动返回None。

在调用该接口之前，还应正确设置 out 的数据类型和形状，而 out 和 x 对应梯度的数据类型和形状将自动推断而出。

此功能还可用于调试正在运行的网络，可以通过添加没有输出的 py_func 运算，并在 func 中打印输入 x 。

参数:

  • func （callable） - 所注册的Python OP的前向函数，运行网络时，将根据该函数与前向输入 x ，计算前向输出 out 。 在 func 建议先主动将Tensor转换为numpy数组，方便灵活的使用numpy相关的操作，如果未转换成numpy，则可能某些操作无法兼容。

  • x (Tensor|tuple(Tensor)|list[Tensor]) - 前向函数 func 的输入，多个Tensor以tuple(Tensor)或list[Tensor]的形式传入。

  • out (T|tuple(T)|list[T]) - 前向函数 func 的输出，可以为T|tuple(T)|list[T]，其中T既可以为Tensor，也可以为numpy数组。由于Paddle无法自动推断 out 的形状和数据类型，必须应事先创建 out 。

  • backward_func (callable，可选) - 所注册的Python OP的反向函数。默认值为None，意味着没有反向计算。若不为None，则会在运行网络反向时调用 backward_func 计算 x 的梯度。

  • skip_vars_in_backward_input (Tensor) - backward_func 的输入中不需要的变量，可以是Tensor|tuple(Tensor)|list[Tensor]。 这些变量必须是 x 和 out 中的一个。默认值为None，意味着没有变量需要从 x 和 out 中去除。若不为None，则这些变量将不是 backward_func 的输入。该参数仅在 backward_func 不为None时有用。

返回: 前向函数的输出 out

返回类型: Tensor|tuple(Tensor)|list[Tensor]

示例代码1:

  1. import paddle
  2. import six
  3. import numpy as np
  5. paddle.enable_static()
  7. # 自定义的前向函数，可直接输入LoDTenosor
  8. def tanh(x):
  9.     return np.tanh(x)
  11. # 在反向函数中跳过前向输入x，返回x的梯度。
  12. # 必须使用np.array主动将LodTensor转换为numpy，否则"+/-"等操作无法使用
  13. def tanh_grad(y, dy):
  14.     return np.array(dy) * (1 - np.square(np.array(y)))
  16. # 自定义的前向函数，可用于调试正在运行的网络（打印值）
  17. def debug_func(x):
  18.     print(x)
  20. def create_tmp_var(name, dtype, shape):
  21.     return paddle.static.default_main_program().current_block().create_var(
  22.         name=name, dtype=dtype, shape=shape)
  24. def simple_net(img, label):
  25.     hidden = img
  26.     for idx in six.moves.range(4):
  27.         hidden = paddle.static.nn.fc(hidden, size=200)
  28.         new_hidden = create_tmp_var(name='hidden_{}'.format(idx),
  29.             dtype=hidden.dtype, shape=hidden.shape)
  31.         # 用户自定义的前向反向计算
  32.         hidden = paddle.static.py_func(func=tanh, x=hidden,
  33.             out=new_hidden, backward_func=tanh_grad,
  34.             skip_vars_in_backward_input=hidden)
  36.         # 用户自定义的调试函数，打印出输入的LodTensor
  37.         paddle.static.py_func(func=debug_func, x=hidden, out=None)
  39.     prediction = paddle.static.nn.fc(hidden, size=10, activation='softmax')
  40.     ce_loss = paddle.nn.loss.CrossEntropyLoss()
  41.     return ce_loss(prediction, label)
  43. x = paddle.static.data(name='x', shape=[None, 4], dtype='float32')
  44. y = paddle.static.data(name='y', shape=[10], dtype='int64')
  45. res = simple_net(x, y)
  47. exe = paddle.static.Executor(paddle.CPUPlace())
  48. exe.run(paddle.static.default_startup_program())
  49. input1 = np.random.random(size=[10, 4]).astype('float32')
  50. input2 = np.random.randint(1, 10, size=[10], dtype='int64')
  51. out = exe.run(paddle.static.default_main_program(),
  52.               feed={'x':input1, 'y':input2},
  53.               fetch_list=[res.name])
  54. print(out)

示例代码2:

  1. # 该示例展示了如何将LoDTensor转化为numpy数组，并利用numpy API来自定义一个OP
  2. import paddle
  3. import numpy as np
  5. paddle.enable_static()
  7. def element_wise_add(x, y):
  8.     # 必须先手动将LodTensor转换为numpy数组，否则无法支持numpy的shape操作
  9.     x = np.array(x)
  10.     y = np.array(y)
  12.     if x.shape != y.shape:
  13.         raise AssertionError("the shape of inputs must be the same!")
  15.     result = np.zeros(x.shape, dtype='int32')
  16.     for i in range(len(x)):
  17.         for j in range(len(x[0])):
  18.             result[i][j] = x[i][j] + y[i][j]
  20.     return result
  22. def create_tmp_var(name, dtype, shape):
  23.     return paddle.static.default_main_program().current_block().create_var(
  24.                 name=name, dtype=dtype, shape=shape)
  26. def py_func_demo():
  27.     start_program = paddle.static.default_startup_program()
  28.     main_program = paddle.static.default_main_program()
  30.     # 创建前向函数的输入变量
  31.     x = paddle.static.data(name='x', shape=[2,3], dtype='int32')
  32.     y = paddle.static.data(name='y', shape=[2,3], dtype='int32')
  34.     # 创建前向函数的输出变量，必须指明变量名称name/数据类型dtype/维度shape
  35.     output = create_tmp_var('output','int32', [3,1])
  37.     # 输入多个LodTensor以list[Variable]或tuple(Variable)形式
  38.     paddle.static.py_func(func=element_wise_add, x=[x,y], out=output)
  40.     exe=paddle.static.Executor(fluid.CPUPlace())
  41.     exe.run(start_program)
  43.     # 给program喂入numpy数组
  44.     input1 = np.random.randint(1, 10, size=[2,3], dtype='int32')
  45.     input2 = np.random.randint(1, 10, size=[2,3], dtype='int32')
  46.     out = exe.run(main_program,
  47.                 feed={'x':input1, 'y':input2},
  48.                 fetch_list=[output.name])
  49.     print("{0} + {1} = {2}".format(input1, input2, out))
  51. py_func_demo()
  53. # 参考输出：
  54. # [[5, 9, 9]   + [[7, 8, 4]  =  [array([[12, 17, 13]
  55. #  [7, 5, 2]]     [1, 3, 3]]            [8, 8, 5]], dtype=int32)]