Variable¶

class paddle.static. Variable [源代码] ¶

注意：

1. 请不要直接调用 Variable 的构造函数，因为这会造成严重的错误发生！

2. 在静态图形模式下：请使用 Block.create_var 创建一个静态的 Variable ，该静态的 Variable 在使用 Executor 执行前是没有实际数据的。

3. 在 Dygraph 模式下：请使用 cn_api_fluid_dygraph_to_variable 创建一个拥有实际数据的 Variable

在Fluid中，OP的每个输入和输出都是 Variable 。多数情况下， Variable 用于保存不同种类的数据或训练标签。

Variable 总是属于某一个 Block 。所有 Variable 都有其自己的 name ,不同 Block 中的两个 Variable 可以具有相同的名称。如果使用的 不是 Dygraph 模式，那么同一个 Block 中的两个或更多 Variable 拥有相同 name 将意味着他们会共享相同的内容。通常我们使用这种方式来实现 参数共享

Variable 有很多种。它们每种都有自己的属性和用法。请参考 framework.proto 以获得详细信息。 Variable 的大多数成员变量可以设置为 None。它的意思是它不可用或稍后指定。

如果您希望创建一个 Variable 那么可以参考如下示例：

示例代码：

在静态图形模式下：

import paddle.fluid as fluid
cur_program = fluid.Program()
cur_block = cur_program.current_block()
new_variable = cur_block.create_var(name="X",
                                    shape=[-1, 23, 48],
                                    dtype='float32')

在 Dygraph 模式下：

import paddle.fluid as fluid
import numpy as np
with fluid.dygraph.guard():
    new_variable = fluid.dygraph.to_variable(np.arange(10))

detach ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

2. detach 后的 Variable 将会成为临时变量

产生一个新的，和当前计算图分离的，但是拥有当前 Variable 其内容的临时变量

返回：一个新的，和当前计算图分离的，但是拥有当前 Variable 其内容的临时 Variable

返回类型：（Variable | 和输入的 Dtype 一致）

示例代码

import paddle.fluid as fluid
from paddle.fluid.dygraph.base import to_variable
from paddle.fluid.dygraph import Linear
import numpy as np

data = np.random.uniform(-1, 1, [30, 10, 32]).astype('float32')
with fluid.dygraph.guard():
      linear = Linear(32, 64)
      data = to_variable(data)
      x = linear(data)
      y = x.detach()

numpy ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

返回一个 ndarray 来表示当前 Variable 的值

返回：numpy 的数组，表示当前 Variable 的实际值

返回类型：ndarray，dtype 和输入的 dtype 一致

示例代码

import paddle.fluid as fluid
from paddle.fluid.dygraph.base import to_variable
from paddle.fluid.dygraph import Linear
import numpy as np

data = np.random.uniform(-1, 1, [30, 10, 32]).astype('float32')
with fluid.dygraph.guard():
    linear = Linear(32, 64)
    data = to_variable(data)
    x = linear(data)
    print(x.numpy())

set_value ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

为此 Variable 设置一个新的值。

参数:

• value: ( Variable 或 ndarray ) 要赋值给此 Variable 的新的值。

返回：无

抛出异常： ValueError - 当要赋于的新值的 shape 和此 Variable 原有的 shape 不同时，抛出 ValueError 。

示例代码

import paddle.fluid as fluid
from paddle.fluid.dygraph.base import to_variable
from paddle.fluid.dygraph import Linear
import numpy as np

data = np.ones([3, 1024], dtype='float32')
with fluid.dygraph.guard():
    linear = fluid.dygraph.Linear(1024, 4)
    t = to_variable(data)
    linear(t)  # 使用默认参数值调用前向
    custom_weight = np.random.randn(1024, 4).astype("float32")
    linear.weight.set_value(custom_weight)  # 将参数修改为自定义的值
    out = linear(t)  # 使用新的参数值调用前向

backward ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

2. 由于如果该 Variable 以上没有任何地方需要梯度，那么仅仅设置该 Variable 的梯度为 1 是没有意义的。因此，这种情况下，为了节省一些计算，我们不去产生该 Variable 的梯度

从该节点开始执行反向

参数:

• retain_graph (bool，可选) – 该参数用于确定反向梯度更新完成后反向梯度计算图是否需要保留（retain_graph为True则保留反向梯度计算图）。若用户打算在执行完该方法（ backward ）后，继续向之前已构建的计算图中添加更多的Op，则需要设置 retain_graph 值为True（这样才会保留之前计算得到的梯度）。可以看出，将 retain_graph 设置为False可降低内存的占用。默认值为False。

返回：无

示例代码

import numpy as np
import paddle
paddle.disable_static()
x = np.ones([2, 2], np.float32)
inputs = []
for _ in range(10):
    tmp = paddle.to_tensor(x)
    # 如果这里我们不为输入tmp设置stop_gradient=False，那么后面loss也将因为这个链路都不需要梯度
    # 而不产生梯度
    tmp.stop_gradient=False
    inputs.append(tmp)
ret = paddle.sums(inputs)
loss = paddle.reduce_sum(ret)
loss.backward()

gradient ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

2. 由于如果该 Variable 以上没有任何地方需要梯度，那么仅仅设置该 Variable 的梯度为 1 是没有意义的。因此，这种情况下，为了节省一些计算，我们不去产生该 Variable 的梯度

获取该 Variable 的梯度值

返回：如果 Variable 的类型是LoDTensor（参见 cn_user_guide_lod_tensor ），返回该 Variable 类型为 ndarray 的梯度值；如果 Variable 的类型是SelectedRows，返回该 Variable 类型为 ndarray 的梯度值和类型为 ndarray 的词id组成的tuple。

返回类型：ndarray 或者 tuple of ndarray , 返回类型 tuple of ndarray 仅在 Embedding 层稀疏更新时产生。

示例代码

import paddle.fluid as fluid
import numpy as np

# example1: 返回ndarray
x = np.ones([2, 2], np.float32)
with fluid.dygraph.guard():
    inputs2 = []
    for _ in range(10):
        tmp = fluid.dygraph.base.to_variable(x)
        tmp.stop_gradient=False
        inputs2.append(tmp)
    ret2 = fluid.layers.sums(inputs2)
    loss2 = fluid.layers.reduce_sum(ret2)
    loss2.backward()
    print(loss2.gradient())

# example2: 返回tuple of ndarray
with fluid.dygraph.guard():
    embedding = fluid.dygraph.Embedding(
        size=[20, 32],
        param_attr='emb.w',
        is_sparse=True)
    x_data = np.arange(12).reshape(4, 3).astype('int64')
    x_data = x_data.reshape((-1, 3, 1))
    x = fluid.dygraph.base.to_variable(x_data)
    out = embedding(x)
    out.backward()
    print(embedding.weight.gradient())

clear_gradient ( ) ¶

注意：

1. 该API只在 Dygraph 模式下生效

2. 只有当该 Variable 有梯度时才可调用，通常我们都会为参数调用这个方法，因为临时变量的梯度将会在其离开作用域时被 python 自动清除

设置该 Variable 的梯度为零

返回：无

示例代码

import paddle.fluid as fluid
import numpy as np

x = np.ones([2, 2], np.float32)
with fluid.dygraph.guard():
    inputs2 = []
    for _ in range(10):
        tmp = fluid.dygraph.base.to_variable(x)
        tmp.stop_gradient=False
        inputs2.append(tmp)
    ret2 = fluid.layers.sums(inputs2)
    loss2 = fluid.layers.reduce_sum(ret2)
    loss2.backward()
    print(loss2.gradient())
    loss2.clear_gradient()
    print("After clear {}".format(loss2.gradient()))

to_string ( ) ¶

注意：

1. 该API只在非 Dygraph 模式下生效

获取该 Variable 的静态描述字符串

参数：（仅在非 Dygraph 模式下生效）

• throw_on_error (bool) - 是否在没有设置必需字段时抛出异常。

• with_details (bool) - 值为true时，打印更多关于 Variable 的信息，如 error_clip , stop_gradient 等

返回：用于静态描述该 Variable 的字符串

返回类型： str

抛出异常： ValueError - 当 throw_on_error == true ，当没有设置任何必需的字段时，抛出 ValueError 。

示例代码

import paddle.fluid as fluid

cur_program = fluid.Program()
cur_block = cur_program.current_block()
new_variable = cur_block.create_var(name="X",
                                    shape=[-1, 23, 48],
                                    dtype='float32')
print(new_variable.to_string(True))
print("\n=============with detail===============\n")
print(new_variable.to_string(True, True))

clone ( self ) ¶

返回一个新的 Variable , 其复制原 Variable 并且新的 Variable 也被保留在计算图中，即复制的新 Variable 也参与反向计算。调用 out = tensor.clone() 与 out = assign(tensor) 效果一样。

返回：复制的新 Variable

返回类型： Variable

示例代码

import paddle

paddle.enable_static()

# create a static Variable
x = paddle.static.data(name='x', shape=[3, 2, 1])
# create a cloned Variable
y = x.clone()

astype ( self, dtype ) ¶

将该 Variable 中的数据转换成目标 Dtype

参数：

• self ( Variable ) - 当前 Variable ， 用户不需要传入。

• dtype (int | float | float64) - 希望转换成的 Dtype

返回：一个全新的转换了 Dtype 的 Variable

返回类型： Variable

示例代码

在静态图模式下：

import paddle.fluid as fluid

startup_prog = fluid.Program()
main_prog = fluid.Program()
with fluid.program_guard(startup_prog, main_prog):
    original_variable = fluid.data(name = "new_variable", shape=[2,2], dtype='float32')
    new_variable = original_variable.astype('int64')
    print("new var's dtype is: {}".format(new_variable.dtype))

在 Dygraph 模式下：

import paddle.fluid as fluid
import numpy as np

x = np.ones([2, 2], np.float32)
with fluid.dygraph.guard():
    original_variable = fluid.dygraph.to_variable(x)
    print("original var's dtype is: {}, numpy dtype is {}".format(original_variable.dtype, original_variable.numpy().dtype))
    new_variable = original_variable.astype('int64')
    print("new var's dtype is: {}, numpy dtype is {}".format(new_variable.dtype, new_variable.numpy().dtype))