tf.Variable

См. руководство по переменным.

tf.Variable(
    initial_value=None,
    trainable=None,
    validate_shape=True,
    caching_device=None,
    name=None,
    variable_def=None,
    dtype=None,
    import_scope=None,
    constraint=None,
    synchronization=tf.VariableSynchronization.AUTO,
    aggregation=tf.compat.v1.VariableAggregation.NONE,
    shape=None,
    experimental_enable_variable_lifting=True
)

Используется в блокнотах

Переменная хранит общее постоянное состояние, которым управляет программа.

Конструктору Variable() требуется начальное значение переменной — Tensor любого типа и формы. Это начальное значение определяет тип и форму переменной. После создания тип и форма переменной не меняются. Значение можно изменить с помощью одного из методов присваивания.

v = tf.Variable(1.)
v.assign(2.)
<tf.Variable ... shape=() dtype=float32, numpy=2.0>
v.assign_add(0.5)
<tf.Variable ... shape=() dtype=float32, numpy=2.5>

Аргумент shape конструктора Variable позволяет создать переменную с менее определённой формой, чем у её initial_value:

v = tf.Variable(1., shape=tf.TensorShape(None))
v.assign([[1.]])
<tf.Variable ... shape=<unknown> dtype=float32, numpy=array([[1.]], ...)>

Как и любой Tensor, переменные, созданные с помощью Variable(), можно использовать в качестве входных данных операций. Кроме того, на переменные распространяется перегрузка всех операторов класса Tensor.

w = tf.Variable([[1.], [2.]])
x = tf.constant([[3., 4.]])
tf.matmul(w, x)
<tf.Tensor:... shape=(2, 2), ... numpy=
  array([[3., 4.],
         [6., 8.]], dtype=float32)>
tf.sigmoid(w + x)
<tf.Tensor:... shape=(2, 2), ...>

При создании модели машинного обучения часто бывает удобно различать переменные, содержащие обучаемые параметры модели, и другие переменные, например переменную step для подсчёта шагов обучения. Для этого конструктор переменной поддерживает параметр trainable=<bool>. По умолчанию tf.GradientTape отслеживает обучаемые переменные:

with tf.GradientTape(persistent=True) as tape:
  trainable = tf.Variable(1.)
  non_trainable = tf.Variable(2., trainable=False)
  x1 = trainable * 2.
  x2 = non_trainable * 3.
tape.gradient(x1, trainable)
<tf.Tensor:... shape=(), dtype=float32, numpy=2.0>
assert tape.gradient(x2, non_trainable) is None  # Unwatched

Переменные автоматически отслеживаются при присваивании атрибутам типов, наследующих tf.Module.

m = tf.Module()
m.v = tf.Variable([1.])
m.trainable_variables
(<tf.Variable ... shape=(1,) ... numpy=array([1.], dtype=float32)>,)

Такое отслеживание позволяет сохранять значения переменных в контрольные точки обучения или в SavedModels, содержащие сериализованные графы TensorFlow.

Переменные часто захватываются и используются в tf.function. Это работает так же, как и для функции без декоратора:

v = tf.Variable(0.)
read_and_decrement = tf.function(lambda: v.assign_sub(0.1))
read_and_decrement()
<tf.Tensor: shape=(), dtype=float32, numpy=-0.1>
read_and_decrement()
<tf.Tensor: shape=(), dtype=float32, numpy=-0.2>

Переменные, созданные внутри tf.function, должны принадлежать объекту вне функции и создаваться только один раз:

class M(tf.Module):
  @tf.function
  def __call__(self, x):
    if not hasattr(self, "v"):  # Or set self.v to None in __init__
      self.v = tf.Variable(x)
    return self.v * x
m = M()
m(2.)
<tf.Tensor: shape=(), dtype=float32, numpy=4.0>
m(3.)
<tf.Tensor: shape=(), dtype=float32, numpy=6.0>
m.v
<tf.Variable ... shape=() dtype=float32, numpy=2.0>

Подробности см. в документации по tf.function.

Дочерние классы

class SaveSliceInfo

Методы

assign

Посмотреть исходный код

assign(
    value, use_locking=False, name=None, read_value=True
)

Присваивает переменной новое значение.

По сути, это сокращённая запись для assign(self, value).

assign_add

Посмотреть исходный код

assign_add(
    delta, use_locking=False, name=None, read_value=True
)

Прибавляет значение к этой переменной.

По сути, это сокращённая запись для assign_add(self, delta).

assign_sub

Посмотреть исходный код

assign_sub(
    delta, use_locking=False, name=None, read_value=True
)

Вычитает значение из этой переменной.

По сути, это сокращённая запись для assign_sub(self, delta).

batch_scatter_update

Посмотреть исходный код

batch_scatter_update(
    sparse_delta, use_locking=False, name=None
)

Присваивает этой переменной значения tf.IndexedSlices пакетами.

Аналогично batch_gather. Предполагается, что эта переменная и разреженная переменная sparse_delta типа IndexedSlices имеют последовательность начальных измерений, совпадающих для всех них, а обновления выполняются по последнему измерению индексов. Иными словами, измерения должны быть следующими:

num_prefix_dims = sparse_delta.indices.ndims - 1 batch_dim = num_prefix_dims + 1 sparse_delta.updates.shape = sparse_delta.indices.shape + var.shape[ batch_dim:]

где

sparse_delta.updates.shape[:num_prefix_dims] == sparse_delta.indices.shape[:num_prefix_dims] == var.shape[:num_prefix_dims]

Выполняемую операцию можно записать следующим образом:

var[i_1, ..., i_n, sparse_delta.indices[i_1, ..., i_n, j]] = sparse_delta.updates[ i_1, ..., i_n, j]

Если sparse_delta.indices — одномерный тензор, эта операция эквивалентна scatter_update.

Чтобы не выполнять эту операцию, можно пройти циклом по первому ndims переменной и использовать scatter_update для подтензоров, полученных срезом по первому измерению. Это допустимый вариант для ndims = 1, но он менее эффективен, чем данная реализация.

count_up_to

Посмотреть исходный код

count_up_to(
    limit
)

Увеличивает значение этой переменной, пока оно не достигнет limit. (Устарело.)

При выполнении этой операции она пытается увеличить значение переменной на 1. Если в результате увеличения значение переменной превысит limit, операция вызовет исключение OutOfRangeError.

Если ошибка не возникает, операция выводит значение переменной до увеличения.

По сути, это сокращённая запись для count_up_to(self, limit).

eval

Посмотреть исходный код

eval(
    session=None
)

В сессии вычисляет и возвращает значение этой переменной.

Это не метод построения графа: он не добавляет операции в граф.

Для этого вспомогательного метода нужна сессия, в которой запущен граф, содержащий эту переменную. Если сессия не передана, используется сессия по умолчанию. Дополнительную информацию о запуске графа и сессиях см. в разделе tf.compat.v1.Session.

v = tf.Variable([1, 2])
init = tf.compat.v1.global_variables_initializer()

with tf.compat.v1.Session() as sess:
    sess.run(init)
    # Usage passing the session explicitly.
    print(v.eval(sess))
    # Usage with the default session.  The 'with' block
    # above makes 'sess' the default session.
    print(v.eval())

experimental_ref

Посмотреть исходный код

experimental_ref()

УСТАРЕВШАЯ ФУНКЦИЯ

from_proto

Посмотреть исходный код

@staticmethod
from_proto(
    variable_def, import_scope=None
)

Возвращает объект Variable, созданный из variable_def.

gather_nd

Посмотреть исходный код

gather_nd(
    indices, name=None
)

Собирает срезы из params в Tensor с формой, заданной indices.

Подробности см. в tf.gather_nd.

get_shape

Посмотреть исходный код

get_shape() -> tf.TensorShape

Синоним Variable.shape.

initialized_value

Посмотреть исходный код

initialized_value()

Возвращает значение инициализированной переменной. (Устарело.)

Используйте этот метод вместо самой переменной, чтобы инициализировать другую переменную значением, зависящим от значения этой переменной.

# Initialize 'v' with a random tensor.
v = tf.Variable(tf.random.truncated_normal([10, 40]))
# Use `initialized_value` to guarantee that `v` has been
# initialized before its value is used to initialize `w`.
# The random values are picked only once.
w = tf.Variable(v.initialized_value() * 2.0)

load

Посмотреть исходный код

load(
    value, session=None
)

Загружает в эту переменную новое значение. (Устарело.)

Записывает новое значение в память переменной. Не добавляет операции в граф.

Для этого вспомогательного метода нужна сессия, в которой запущен граф, содержащий эту переменную. Если сессия не передана, используется сессия по умолчанию. Дополнительную информацию о запуске графа и сессиях см. в разделе tf.compat.v1.Session.

v = tf.Variable([1, 2])
init = tf.compat.v1.global_variables_initializer()

with tf.compat.v1.Session() as sess:
    sess.run(init)
    # Usage passing the session explicitly.
    v.load([2, 3], sess)
    print(v.eval(sess)) # prints [2 3]
    # Usage with the default session.  The 'with' block
    # above makes 'sess' the default session.
    v.load([3, 4], sess)
    print(v.eval()) # prints [3 4]

read_value

Посмотреть исходный код

read_value()

Возвращает значение этой переменной, считанное в текущем контексте.

Оно может отличаться от value(), если переменная находится на другом устройстве, имеет зависимости управления и т. д.

ref

Посмотреть исходный код

ref()

Возвращает хешируемый объект-ссылку на эту переменную.

Основной сценарий использования этого API — добавление переменных в множество или словарь. Начиная с TensorFlow 2.0, переменные нельзя добавлять в множество или словарь, поскольку variable.__hash__() больше недоступен.

Следующий код начиная с версии 2.0 вызовет исключение:

x = tf.Variable(5)
y = tf.Variable(10)
z = tf.Variable(10)
variable_set = {x, y, z}
Traceback (most recent call last):

TypeError: Variable is unhashable. Instead, use tensor.ref() as the key.
variable_dict = {x: 'five', y: 'ten'}
Traceback (most recent call last):

TypeError: Variable is unhashable. Instead, use tensor.ref() as the key.

Вместо этого можно использовать variable.ref().

variable_set = {x.ref(), y.ref(), z.ref()}
x.ref() in variable_set
True
variable_dict = {x.ref(): 'five', y.ref(): 'ten', z.ref(): 'ten'}
variable_dict[y.ref()]
'ten'

Кроме того, объект-ссылка предоставляет функцию .deref(), которая возвращает исходную переменную.

x = tf.Variable(5)
x.ref().deref()
<tf.Variable 'Variable:0' shape=() dtype=int32, numpy=5>

scatter_add

Посмотреть исходный код

scatter_add(
    sparse_delta, use_locking=False, name=None
)

Прибавляет к этой переменной значения tf.IndexedSlices.

scatter_div

Посмотреть исходный код

scatter_div(
    sparse_delta, use_locking=False, name=None
)

Разделить эту переменную на tf.IndexedSlices.

scatter_max

Посмотреть исходный код

scatter_max(
    sparse_delta, use_locking=False, name=None
)

Обновляет эту переменную, записывая в неё максимум из tf.IndexedSlices и самой переменной.

scatter_min

Посмотреть исходный код

scatter_min(
    sparse_delta, use_locking=False, name=None
)

Обновляет эту переменную, записывая в неё минимум из tf.IndexedSlices и самой переменной.

scatter_mul

Посмотреть исходный код

scatter_mul(
    sparse_delta, use_locking=False, name=None
)

Умножить эту переменную на tf.IndexedSlices.

scatter_nd_add

Посмотреть исходный код

scatter_nd_add(
    indices, updates, name=None
)

Выполняет разреженное сложение отдельных значений или срезов переменной.

Ранг переменной равен P, а indices — это Tensor ранга Q.

indices должен быть целочисленным тензором, содержащим индексы в self. Его форма должна быть [d_0, ..., d_{Q-2}, K], где 0 < K <= P.

Внутреннее измерение indices (длиной K) соответствует индексам элементов (если K = P) или срезов (если K < P) вдоль измерения self с номером K.

updates — это Tensor ранга Q-1+P-K со следующей формой:

[d_0, ..., d_{Q-2}, self.shape[K], ..., self.shape[P-1]].

Например, предположим, что нужно добавить 4 разрозненных элемента к тензору ранга 1, состоящему из 8 элементов. В Python это обновление выглядело бы так:

v = tf.Variable([1, 2, 3, 4, 5, 6, 7, 8])
indices = tf.constant([[4], [3], [1] ,[7]])
updates = tf.constant([9, 10, 11, 12])
v.scatter_nd_add(indices, updates)
print(v)

В результате переменная v обновилась бы следующим образом:

[1, 13, 3, 14, 14, 6, 7, 20]

Подробнее об обновлении срезов см. в разделе tf.scatter_nd.

scatter_nd_sub

Посмотреть исходный код

scatter_nd_sub(
    indices, updates, name=None
)

Выполняет разреженное вычитание отдельных значений или срезов переменной.

Предполагается, что ранг переменной равен P, а indices — это Tensor ранга Q.

indices должен быть целочисленным тензором, содержащим индексы в self. Его форма должна быть [d_0, ..., d_{Q-2}, K], где 0 < K <= P.

Внутреннее измерение indices (длиной K) соответствует индексам элементов (если K = P) или срезов (если K < P) вдоль измерения self с номером K.

updates — это Tensor ранга Q-1+P-K со следующей формой:

[d_0, ..., d_{Q-2}, self.shape[K], ..., self.shape[P-1]].

Например, предположим, что нужно добавить 4 разрозненных элемента к тензору ранга 1, состоящему из 8 элементов. В Python это обновление выглядело бы так:

v = tf.Variable([1, 2, 3, 4, 5, 6, 7, 8])
indices = tf.constant([[4], [3], [1] ,[7]])
updates = tf.constant([9, 10, 11, 12])
v.scatter_nd_sub(indices, updates)
print(v)

После обновления v выглядела бы так:

[1, -9, 3, -6, -4, 6, 7, -4]

Подробнее об обновлении срезов см. в разделе tf.scatter_nd.

scatter_nd_update

Посмотреть исходный код

scatter_nd_update(
    indices, updates, name=None
)

Выполняет разреженное присваивание отдельных значений или срезов переменной.

Ранг переменной равен P, а indices — это Tensor ранга Q.

indices должен быть целочисленным тензором, содержащим индексы в self. Его форма должна быть [d_0, ..., d_{Q-2}, K], где 0 < K <= P.

Внутреннее измерение indices (длиной K) соответствует индексам элементов (если K = P) или срезов (если K < P) вдоль измерения self с номером K.

updates — это Tensor ранга Q-1+P-K со следующей формой:

[d_0, ..., d_{Q-2}, self.shape[K], ..., self.shape[P-1]].

Например, предположим, что нужно добавить 4 разрозненных элемента к тензору ранга 1, состоящему из 8 элементов. В Python это обновление выглядело бы так:

v = tf.Variable([1, 2, 3, 4, 5, 6, 7, 8])
indices = tf.constant([[4], [3], [1] ,[7]])
updates = tf.constant([9, 10, 11, 12])
v.scatter_nd_update(indices, updates)
print(v)

В результате переменная v обновилась бы следующим образом:

[1, 11, 3, 10, 9, 6, 7, 12]

Подробнее об обновлении срезов см. в разделе tf.scatter_nd.

scatter_sub

Посмотреть исходный код

scatter_sub(
    sparse_delta, use_locking=False, name=None
)

Вычитает tf.IndexedSlices из этой переменной.

scatter_update

Посмотреть исходный код

scatter_update(
    sparse_delta, use_locking=False, name=None
)

Присваивает этой переменной значение tf.IndexedSlices.

set_shape

Посмотреть исходный код

set_shape(
    shape
)

Переопределяет форму этой переменной.

sparse_read

Посмотреть исходный код

sparse_read(
    indices, name=None
)

Извлекает срезы из params по оси axis в соответствии с индексами.

Эта функция поддерживает подмножество возможностей tf.gather. Подробнее об использовании см. в документации tf.gather.

to_proto

Посмотреть исходный код

to_proto(
    export_scope=None
)

Преобразует Variable в протокольный буфер VariableDef.

value

Посмотреть исходный код

value()

Возвращает последний снимок этой переменной.

Обычно вызывать этот метод не нужно, так как все операции, которым требуется значение переменной, вызывают его автоматически с помощью вызова convert_to_tensor().

Возвращает Tensor, содержащий значение переменной. Нельзя присвоить этому тензору новое значение, поскольку он не является ссылкой на переменную.

Чтобы избежать копирования, если потребитель возвращённого значения находится на том же устройстве, что и переменная, фактически возвращается текущее значение переменной, а не его копия. Потребитель видит обновления переменной. Если потребитель находится на другом устройстве, ему передаётся копия переменной.

__abs__

Посмотреть исходный код

__abs__(
    name=None
)

__add__

Посмотреть исходный код

__add__(
    y
)

__and__

Посмотреть исходный код

__and__(
    y
)

__div__

Посмотреть исходный код

__div__(
    y
)

__eq__

Посмотреть исходный код

__eq__(
    other
)

Поэлементно сравнивает две переменные на равенство.

__floordiv__

Посмотреть исходный код

__floordiv__(
    y
)

__ge__

__ge__(
    y: Annotated[Any, tf.raw_ops.Any],
    name=None
) -> Annotated[Any, tf.raw_ops.Any]

Поэлементно возвращает логическое значение выражения (x >= y).

Примечание: math.greater_equal поддерживает broadcasting. Подробнее о broadcasting — здесь

Пример:

x = tf.constant([5, 4, 6, 7])
y = tf.constant([5, 2, 5, 10])
tf.math.greater_equal(x, y) ==> [True, True, True, False]

x = tf.constant([5, 4, 6, 7])
y = tf.constant([5])
tf.math.greater_equal(x, y) ==> [True, False, True, True]

__getitem__

Посмотреть исходный код

__getitem__(
    slice_spec
)

Создаёт вспомогательный объект среза для заданной переменной.

Это позволяет создать подтензор из части текущего содержимого переменной. Подробные примеры создания срезов см. в разделе tf.Tensor.getitem.

Кроме того, эта функция позволяет присваивать значения выбранному срезу. Это похоже на функциональность __setitem__ в Python. Однако синтаксис отличается, чтобы пользователь мог сохранить операцию присваивания для группировки или передачи в sess.run() в TF1. Например:

import tensorflow as tf
A = tf.Variable([[1,2,3], [4,5,6], [7,8,9]], dtype=tf.float32)
print(A[:2, :2])  # => [[1,2], [4,5]]

A[:2,:2].assign(22. * tf.ones((2, 2))))
print(A) # => [[22, 22, 3], [22, 22, 6], [7,8,9]]

Обратите внимание, что в настоящее время присваивания не поддерживают семантику broadcasting NumPy.

__gt__

__gt__(
    y: Annotated[Any, tf.raw_ops.Any],
    name=None
) -> Annotated[Any, tf.raw_ops.Any]

Поэлементно возвращает логическое значение выражения (x > y).

Примечание: math.greater поддерживает broadcasting. Подробнее о broadcasting — здесь

Пример:

x = tf.constant([5, 4, 6])
y = tf.constant([5, 2, 5])
tf.math.greater(x, y) ==> [False, True, True]

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.greater(x, y) ==> [False, False, True]

__invert__

Посмотреть исходный код

__invert__(
    name=None
)

__iter__

Посмотреть исходный код

__iter__()

При eager-выполнении перебирает значения переменной.

__le__

__le__(
    y: Annotated[Any, tf.raw_ops.Any],
    name=None
) -> Annotated[Any, tf.raw_ops.Any]

Поэлементно возвращает логическое значение выражения (x <= y).

Примечание: math.less_equal поддерживает broadcasting. Подробнее о broadcasting — здесь

Пример:

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less_equal(x, y) ==> [True, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 6])
tf.math.less_equal(x, y) ==> [True, True, True]

__lt__

__lt__(
    y: Annotated[Any, tf.raw_ops.Any],
    name=None
) -> Annotated[Any, tf.raw_ops.Any]

Поэлементно возвращает логическое значение выражения (x < y).

Примечание: math.less поддерживает broadcasting. Подробнее о broadcasting — здесь

Пример:

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less(x, y) ==> [False, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 7])
tf.math.less(x, y) ==> [False, True, True]

__matmul__

Посмотреть исходный код

__matmul__(
    y
)

__mod__

Посмотреть исходный код

__mod__(
    y
)

__mul__

Посмотреть исходный код

__mul__(
    y
)

__ne__

Посмотреть исходный код

__ne__(
    other
)

Поэлементно сравнивает две переменные на равенство.

__neg__

__neg__(
    name=None
) -> Annotated[Any, tf.raw_ops.Any]

Вычисляет поэлементное числовое отрицание.

То есть \(y = -x\).

__or__

Посмотреть исходный код

__or__(
    y
)

__pow__

Посмотреть исходный код

__pow__(
    y
)

__radd__

Посмотреть исходный код

__radd__(
    x
)

__rand__

Посмотреть исходный код

__rand__(
    x
)

__rdiv__

Посмотреть исходный код

__rdiv__(
    x
)

__rfloordiv__

Посмотреть исходный код

__rfloordiv__(
    x
)

__rmatmul__

Посмотреть исходный код

__rmatmul__(
    x
)

__rmod__

Посмотреть исходный код

__rmod__(
    x
)

__rmul__

Посмотреть исходный код

__rmul__(
    x
)

__ror__

Посмотреть исходный код

__ror__(
    x
)

__rpow__

Посмотреть исходный код

__rpow__(
    x
)

__rsub__

Посмотреть исходный код

__rsub__(
    x
)

__rtruediv__

Посмотреть исходный код

__rtruediv__(
    x
)

__rxor__

Посмотреть исходный код

__rxor__(
    x
)

__sub__

Посмотреть исходный код

__sub__(
    y
)

__truediv__

Посмотреть исходный код

__truediv__(
    y
)

__xor__

Посмотреть исходный код

__xor__(
    y
)