tf.Graph

Вычисление TensorFlow, представленное в виде графа потоков данных.

tf.Graph() -> None

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

Графы используются объектами tf.function для представления вычислений функции. Каждый граф содержит набор объектов tf.Operation, представляющих единицы вычислений, и объектов tf.Tensor, представляющих единицы данных, передаваемые между операциями.

Непосредственное использование графов (устарело)

Объект tf.Graph можно создать и использовать напрямую, без объекта tf.function, как это требовалось в TensorFlow 1, однако такой подход устарел, и рекомендуется вместо него использовать объект tf.function. При непосредственном использовании графа для его выполнения также требуются другие устаревшие классы TensorFlow 1, например tf.compat.v1.Session.

Граф по умолчанию можно зарегистрировать с помощью менеджера контекста tf.Graph.as_default. Тогда операции будут добавляться в граф, а не выполняться немедленно. Например:

g = tf.Graph()
with g.as_default():
  # Define operations and tensors in `g`.
  c = tf.constant(30.0)
  assert c.graph is g

Для получения графа по умолчанию можно использовать tf.compat.v1.get_default_graph().

Важное замечание: этот класс не является потокобезопасным при построении графа. Все операции следует создавать из одного потока либо обеспечить внешнюю синхронизацию. Если не указано иное, все методы не являются потокобезопасными.

Экземпляр Graph поддерживает произвольное количество «коллекций», определяемых по имени. Для удобства при построении большого графа в коллекциях можно хранить группы связанных объектов: например, tf.Variable использует коллекцию (с именем tf.GraphKeys.GLOBAL_VARIABLES) для всех переменных, созданных при построении графа. Вызывающий код может определить дополнительные коллекции, указав новое имя.

Методы

Dismantle

Dismantle()

(self: handle) -> None

add_to_collection

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

add_to_collection(
    name, value
) -> None

Сохраняет value в коллекции с указанным name.

Обратите внимание, что коллекции не являются множествами, поэтому значение можно добавить в коллекцию несколько раз.

add_to_collections

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

add_to_collections(
    names, value
) -> None

Сохраняет value в коллекциях, заданных параметром names.

Обратите внимание, что коллекции не являются множествами, поэтому значение можно добавить в коллекцию несколько раз. Эта функция обеспечивает игнорирование повторов в names, но не проверяет, содержится ли уже value в какой-либо из коллекций в names.

names может быть любым итерируемым объектом, но если names является строкой, она рассматривается как имя одной коллекции.

as_default

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

as_default() -> ContextManager['Graph']

Возвращает менеджер контекста, который делает этот Graph графом по умолчанию.

Этот метод следует использовать, если вы хотите создать несколько графов в одном процессе. Для удобства предоставляется глобальный граф по умолчанию; если явно не создать новый граф, все операции будут добавляться в него.

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

Граф по умолчанию является свойством текущего потока. Если вы создаёте новый поток и хотите использовать в нём граф по умолчанию, необходимо явно добавить with g.as_default(): в функцию этого потока.

Следующие примеры кода эквивалентны:

# 1. Using Graph.as_default():
g = tf.Graph()
with g.as_default():
  c = tf.constant(5.0)
  assert c.graph is g

# 2. Constructing and making default:
with tf.Graph().as_default() as g:
  c = tf.constant(5.0)
  assert c.graph is g

Если включено eager-выполнение, операции, созданные в рамках этого менеджера контекста, будут добавляться в граф, а не выполняться немедленно.

as_graph_def

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

as_graph_def(
    from_version=None, add_shapes=False, use_pybind11_proto=False
) -> tf.compat.v1.GraphDef

Возвращает сериализованное представление этого графа в формате GraphDef.

Сериализованный объект GraphDef можно импортировать в другой объект Graph (с помощью tf.import_graph_def) или использовать с C++ Session API.

Этот метод потокобезопасен.

as_graph_element

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

as_graph_element(
    obj, allow_tensor=True, allow_operation=True
) -> Union[tensor_lib.Tensor, 'Operation']

Возвращает объект, на который ссылается obj, в виде Operation или Tensor.

Эта функция проверяет, что obj обозначает элемент этого графа, и выдаёт информативное сообщение об ошибке, если это не так.

Эта функция является стандартным способом получения и проверки объекта одного из допустимых типов по внешней ссылке на аргумент в Session API.

Этот метод можно одновременно вызывать из нескольких потоков.

clear_collection

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

clear_collection(
    name
) -> None

Удаляет все значения из коллекции.

colocate_with

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

@tf_contextlib.contextmanager
colocate_with(
    op, ignore_existing=False
) -> Iterator[None]

Возвращает менеджер контекста, задающий операцию, с которой следует разместить совместно.

Примечание: эта функция предназначена не для публичного использования, а только для внутренних библиотек.

Например:

a = tf.Variable([1.0])
with g.colocate_with(a):
  b = tf.constant(1.0)
  c = tf.add(a, b)

b и c всегда будут размещаться совместно с a независимо от того, где в конечном итоге будет размещён a.

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

Если op имеет значение None, то ignore_existing должно иметь значение True, а новая область сбрасывает все ограничения на совместное размещение и устройства.

container

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

@tf_contextlib.contextmanager
container(
    container_name
) -> Iterator[str]

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

Операции с состоянием, такие как переменные и очереди, могут сохранять своё состояние на устройствах, чтобы им могли совместно пользоваться несколько процессов. Контейнер ресурсов — это строковое имя, по которому отслеживаются такие операции с состоянием. Эти ресурсы можно освободить или очистить с помощью tf.Session.reset().

Например:

with g.container('experiment0'):
  # All stateful Operations constructed in this context will be placed
  # in resource container "experiment0".
  v1 = tf.Variable([1.0])
  v2 = tf.Variable([2.0])
  with g.container("experiment1"):
    # All stateful Operations constructed in this context will be
    # placed in resource container "experiment1".
    v3 = tf.Variable([3.0])
    q1 = tf.queue.FIFOQueue(10, tf.float32)
  # All stateful Operations constructed in this context will be
  # be created in the "experiment0".
  v4 = tf.Variable([4.0])
  q1 = tf.queue.FIFOQueue(20, tf.float32)
  with g.container(""):
    # All stateful Operations constructed in this context will be
    # be placed in the default resource container.
    v5 = tf.Variable([5.0])
    q3 = tf.queue.FIFOQueue(30, tf.float32)

# Resets container "experiment0", after which the state of v1, v2, v4, q1
# will become undefined (such as uninitialized).
tf.Session.reset(target, ["experiment0"])

control_dependencies

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

control_dependencies(
    control_inputs
) -> _ControlDependenciesController

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

Используйте ключевое слово with, чтобы указать, что все операции, созданные в контексте, должны иметь управляющие зависимости от control_inputs. Например:

with g.control_dependencies([a, b, c]):
  # `d` and `e` will only run after `a`, `b`, and `c` have executed.
  d = ...
  e = ...

Вызовы control_dependencies() можно вкладывать друг в друга; в этом случае новая операция Operation будет иметь управляющие зависимости от объединения всех control_inputs из активных контекстов.

with g.control_dependencies([a, b]):
  # Ops constructed here run after `a` and `b`.
  with g.control_dependencies([c, d]):
    # Ops constructed here run after `a`, `b`, `c`, and `d`.

Чтобы очистить управляющие зависимости, можно передать None:

with g.control_dependencies([a, b]):
  # Ops constructed here run after `a` and `b`.
  with g.control_dependencies(None):
    # Ops constructed here run normally, not waiting for either `a` or `b`.
    with g.control_dependencies([c, d]):
      # Ops constructed here run after `c` and `d`, also not waiting
      # for either `a` or `b`.

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

# WRONG
def my_func(pred, tensor):
  t = tf.matmul(tensor, tensor)
  with tf.control_dependencies([pred]):
    # The matmul op is created outside the context, so no control
    # dependency will be added.
    return t

# RIGHT
def my_func(pred, tensor):
  with tf.control_dependencies([pred]):
    # The matmul op is created in the context, so a control dependency
    # will be added.
    return tf.matmul(tensor, tensor)

Также обратите внимание: хотя выполнение операций, созданных в этой области, запускает выполнение зависимостей, такие операции всё равно могут быть удалены при оптимизации обычного графа TensorFlow. Например, в следующем фрагменте кода зависимости никогда не выполняются:

loss = model.loss()
with tf.control_dependencies(dependencies):
  loss = loss + tf.constant(1)  # note: dependencies ignored in the
                                # backward pass
return tf.gradients(loss, model.variables)

Это происходит потому, что для вычисления графа градиентов не требуется вычислять операцию constant(1), созданную при прямом проходе.

create_op

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

create_op(
    op_type,
    inputs,
    dtypes=None,
    input_types=None,
    name=None,
    attrs=None,
    op_def=None,
    compute_shapes=True,
    compute_device=True
) -> 'Operation'

Создаёт Operation в этом графе. (Устаревшие аргументы)

Это низкоуровневый интерфейс для создания Operation. Большинство программ не вызывают этот метод напрямую, а используют конструкторы операций Python, например tf.constant(), которые добавляют операции в граф по умолчанию.

device

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

@tf_contextlib.contextmanager
device(
    device_name_or_function
) -> Iterator[None]

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

Аргумент device_name_or_function может быть строкой с именем устройства, функцией устройства или None:

• Если это строка с именем устройства, всем операциям, созданным в этом контексте, будет назначено устройство с таким именем, если это не переопределено вложенным контекстом device().
• Если это функция, она будет рассматриваться как функция, преобразующая объекты Operation в строки с именами устройств, и вызываться при создании каждой новой операции Operation. Операции будет назначено устройство с возвращённым именем.
• Если это None, все вызовы device() из охватывающего контекста будут игнорироваться.

Сведения о допустимом синтаксисе строк с именами устройств см. в документации в DeviceNameUtils.

Например:

with g.device('/device:GPU:0'):
  # All operations constructed in this context will be placed
  # on GPU 0.
  with g.device(None):
    # All operations constructed in this context will have no
    # assigned device.

# Defines a function from `Operation` to device string.
def matmul_on_gpu(n):
  if n.type == "MatMul":
    return "/device:GPU:0"
  else:
    return "/cpu:0"

with g.device(matmul_on_gpu):
  # All operations of type "MatMul" constructed in this context
  # will be placed on GPU 0; all other operations will be placed
  # on CPU 0.

Примечание: Область устройства может быть переопределена обёртками операций или другим кодом библиотеки. Например, операция присваивания переменной v.assign() должна размещаться совместно с v объекта tf.Variable, поэтому несовместимые области устройств будут игнорироваться.

finalize

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

finalize() -> None

Окончательно фиксирует этот граф, делая его доступным только для чтения.

После вызова g.finalize() в g нельзя добавлять новые операции. Этот метод используется, чтобы гарантировать, что в граф не добавляются операции при совместном использовании несколькими потоками, например при использовании tf.compat.v1.train.QueueRunner.

get

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

get() -> GraphType

get_all_collection_keys

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

get_all_collection_keys() -> list[str]

Возвращает список коллекций, используемых в этом графе.

get_collection

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

get_collection(
    name, scope=None
) -> list[Any]

Возвращает список значений коллекции с указанным name.

Этот метод отличается от get_collection_ref(), который всегда возвращает фактический список коллекции, если она существует: данный метод при каждом вызове возвращает новый список.

get_collection_ref

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

get_collection_ref(
    name
) -> list[Any]

Возвращает список значений коллекции с указанным name.

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

Это отличается от get_collection(), который всегда возвращает копию списка коллекции, если она существует, и никогда не создает пустую коллекцию.

get_name_scope

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

get_name_scope() -> str

Возвращает текущую область имен.

Например:

with tf.name_scope('scope1'):
  with tf.name_scope('scope2'):
    print(tf.compat.v1.get_default_graph().get_name_scope())

выведет строку scope1/scope2.

get_operation_by_name

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

get_operation_by_name(
    name
) -> 'Operation'

Возвращает Operation с указанным name.

Этот метод можно вызывать одновременно из нескольких потоков.

get_operations

get_operations()

(self: handle) -> list

get_tensor_by_name

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

get_tensor_by_name(
    name
) -> tf.Tensor

Возвращает Tensor с указанным name.

Этот метод можно вызывать одновременно из нескольких потоков.

gradient_override_map

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

@tf_contextlib.contextmanager
gradient_override_map(
    op_type_map
) -> Iterator[None]

ЭКСПЕРИМЕНТАЛЬНО: менеджер контекста для переопределения функций градиента.

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

Например:

@tf.RegisterGradient("CustomSquare")
def _custom_square_grad(op, grad):
  # ...

with tf.Graph().as_default() as g:
  c = tf.constant(5.0)
  s_1 = tf.square(c)  # Uses the default gradient for tf.square.
  with g.gradient_override_map({"Square": "CustomSquare"}):
    s_2 = tf.square(s_2)  # Uses _custom_square_grad to compute the
                          # gradient of s_2.

is_feedable

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

is_feedable(
    tensor
) -> bool

Возвращает True тогда и только тогда, когда tensor допускает подачу данных.

is_fetchable

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

is_fetchable(
    tensor_or_op
) -> bool

Возвращает True тогда и только тогда, когда tensor_or_op можно получить.

name_scope

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

@tf_contextlib.contextmanager
name_scope(
    name
) -> Iterator[str]

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

Граф поддерживает стек областей имен. Инструкция with name_scope(...): помещает новое имя в стек на время существования контекста.

Аргумент name интерпретируется следующим образом:

• Строка (не оканчивающаяся символом '/') создает новую область имен, в которой name добавляется в качестве префикса ко всем операциям, созданным в контексте. Если name уже использовалось, оно будет сделано уникальным с помощью вызова self.unique_name(name).
• Область, ранее захваченная из инструкции with g.name_scope(...) as scope:, считается «абсолютной» областью имен, что позволяет повторно входить в существующие области.
• Значение None или пустая строка сбрасывает текущую область имен до верхнего уровня (пустой области имен).

Например:

with tf.Graph().as_default() as g:
  c = tf.constant(5.0, name="c")
  assert c.op.name == "c"
  c_1 = tf.constant(6.0, name="c")
  assert c_1.op.name == "c_1"

  # Creates a scope called "nested"
  with g.name_scope("nested") as scope:
    nested_c = tf.constant(10.0, name="c")
    assert nested_c.op.name == "nested/c"

    # Creates a nested scope called "inner".
    with g.name_scope("inner"):
      nested_inner_c = tf.constant(20.0, name="c")
      assert nested_inner_c.op.name == "nested/inner/c"

    # Create a nested scope called "inner_1".
    with g.name_scope("inner"):
      nested_inner_1_c = tf.constant(30.0, name="c")
      assert nested_inner_1_c.op.name == "nested/inner_1/c"

      # Treats `scope` as an absolute name scope, and
      # switches to the "nested/" scope.
      with g.name_scope(scope):
        nested_d = tf.constant(40.0, name="d")
        assert nested_d.op.name == "nested/d"

        with g.name_scope(""):
          e = tf.constant(50.0, name="e")
          assert e.op.name == "e"

Имя самой области можно получить с помощью with g.name_scope(...) as scope:, который сохраняет имя области в переменной scope. Это значение можно использовать, чтобы задать имя операции, представляющей общий результат выполнения операций в области. Например:

inputs = tf.constant(...)
with g.name_scope('my_layer') as scope:
  weights = tf.Variable(..., name="weights")
  biases = tf.Variable(..., name="biases")
  affine = tf.matmul(inputs, weights) + biases
  output = tf.nn.relu(affine, name=scope)

Примечание: Этот конструктор проверяет указанное name. Допустимые имена областей соответствуют одному из следующих регулярных выражений:

[A-Za-z0-9.][A-Za-z0-9_.\-/]* (for scopes at the root)
[A-Za-z0-9_.\-/]* (for other scopes)

new_operations

new_operations()

(self: handle) -> List[TF_Operation]

num_operations

num_operations()

(self: handle) -> int

op_def_for_type

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

op_def_for_type(
    type
) -> op_def_pb2.OpDef

Возвращает протокол OpDef для type. type — это строка.

prevent_feeding

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

prevent_feeding(
    tensor
) -> None

Помечает указанный tensor как недоступный для подачи данных в этом графе.

prevent_fetching

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

prevent_fetching(
    op
) -> None

Помечает указанный op как недоступный для получения в этом графе.

switch_to_thread_local

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

switch_to_thread_local() -> None

Сделать стеки устройств, совместного размещения и зависимостей локальными для потока.

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

После вызова этого метода стеки становятся локальными для потока. Если к ним обращаются несколько потоков, состояние не является общим. Каждый поток использует собственное значение; изменяя такой стек, поток не влияет на другие потоки.

Начальное значение стека каждого потока задается текущим значением стека на момент первого вызова switch_to_thread_local().

unique_name

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

unique_name(
    name, mark_as_used=True
) -> str

Возвращает уникальное имя операции для name.

Примечание: Обычно нет необходимости вызывать unique_name() напрямую. В большинстве случаев достаточно создавать блоки with g.name_scope() для формирования структурированных имен.

unique_name используется для формирования структурированных имен, разделенных "/", чтобы упростить идентификацию операций при отладке графа. Имена операций отображаются в сообщениях об ошибках среды выполнения TensorFlow и в различных средствах визуализации, таких как TensorBoard.

Если для mark_as_used задано значение True (значение по умолчанию), создается новое уникальное имя и помечается как используемое. Если задано значение False, возвращается уникальное имя, но оно не помечается как использованное. Это полезно, когда вызывающему коду нужно только узнать, какое имя будет создано.

__enter__

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

__enter__() -> GraphType

__exit__

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

__exit__(
    *args
) -> None