Tipos de extensiones de TensorFlow explicados con ejemplos

Contenido Overview Instalación Tipos de extensión Apoyo de APIs Requisitos Tipos de campo Mutabilidad Funcionalidad añadida por ExtensionType Constructor Impresión representativa Operadores de igualdad Método de validación Immutabilidad forzada Descripción de TypeSpec Tipos de extensiones personalizadas Reemplazar la representación impresible predeterminada Definición de métodos Definición de métodos de clase y métodos estáticos Definición de propiedades Descargar el constructor defectuoso El operador de igualdad por defecto (eq) Utilización de referencias avanzadas Definición de subclases Definición de campos privados Personalizar el TypeSpec de ExtensionType Instalación !pip install -q tf_nightly import tensorflow as tf import numpy as np from typing import Tuple, List, Mapping, Union, Optional import tempfile Tipos de extensión Los tipos definidos por el usuario pueden hacer que los proyectos sean más legibles, modulares y manejables. Sin embargo, la mayoría de las APIs de TensorFlow tienen un soporte muy limitado para los tipos de Python definidos por el usuario. , de , de ) y APIs de nivel inferior (como y El TensorFlow Puede ser usado para crear tipos orientados a objetos definidos por el usuario que funcionen sin problemas con las APIs de TensorFlow. Para crear un tipo de extensión, simplemente defina una clase de Python con como su base, y el uso especificar el tipo para cada campo. Keras F. Funciones tf.SavedModel tf.while_loop tf.concat extension types tf.experimental.ExtensionType Tipos de anotaciones class TensorGraph(tf.experimental.ExtensionType): """A collection of labeled nodes connected by weighted edges.""" edge_weights: tf.Tensor # shape=[num_nodes, num_nodes] node_labels: Mapping[str, tf.Tensor] # shape=[num_nodes]; dtype=any class MaskedTensor(tf.experimental.ExtensionType): """A tensor paired with a boolean mask, indicating which values are valid.""" values: tf.Tensor mask: tf.Tensor # shape=values.shape; false for missing/invalid values. class CSRSparseMatrix(tf.experimental.ExtensionType): """Compressed sparse row matrix (https://en.wikipedia.org/wiki/Sparse_matrix).""" values: tf.Tensor # shape=[num_nonzero]; dtype=any col_index: tf.Tensor # shape=[num_nonzero]; dtype=int64 row_index: tf.Tensor # shape=[num_rows+1]; dtype=int64 El La clase de base funciona de la misma manera que y de la biblioteca Python estándar. En particular, añade automáticamente un constructor y métodos especiales (como y ) basado en las anotaciones del tipo de campo. tf.experimental.ExtensionType typing.NamedTuple @dataclasses.dataclass __repr__ __eq__ Por lo general, los tipos de extensión tienden a caer en una de dos categorías: Las estructuras de datos, que agrupan una colección de valores relacionados, y pueden proporcionar operaciones útiles basadas en esos valores. Las estructuras de datos pueden ser bastante generales (como el ejemplo de TensorGraph anteriormente); o pueden ser altamente personalizadas para un modelo específico. Los tipos en esta categoría tienen un rango, una forma, y generalmente un tipo d; y tiene sentido usarlos con operaciones de Tensor (como tf.stack, tf.add, o tf.matmul). Las estructuras de datos Tipos de Tensores Apoyo de APIs Los tipos de extensión son compatibles con las siguientes APIs de TensorFlow: Keras: Los tipos de extensión se pueden utilizar como entradas y salidas para los modelos y capas de Keras. tf.data.Dataset: Los tipos de extensión se pueden incluir en Datasets, y se devuelven por iteradores de datasets. TensorFlow Hub: Los tipos de extensión se pueden utilizar como entradas y salidas para módulos tf.hub. SavedModel: Los tipos de extensión se pueden utilizar como entradas y salidas para las funciones de SavedModel. tf.function: Los tipos de extensión se pueden usar como argumentos y devolver valores para las funciones envueltas con el decorador de @tf.function. Mientras loop: Los tipos de extensión se pueden usar como variables de loop en tf.while_loop, y se pueden usar como argumentos y valores de retorno para el cuerpo del loop. Los tipos de extensión pueden ser seleccionados condicionalmente utilizando tf.cond y tf.case. tf.py_function: Los tipos de extensión se pueden usar como argumentos y devolver valores para el argumento de la función a tf.py_function. Opciones de Tensor: Los tipos de extensión se pueden ampliar para soportar la mayoría de las operaciones de TensorFlow que aceptan las entradas de Tensor (como tf.matmul, tf.gather y tf.reduce_sum). Estrategia de distribución: Los tipos de extensión se pueden utilizar como valores per-replica. Para obtener más detalles, consulte la sección sobre "API de TensorFlow que admiten ExtensionTypes" a continuación. Requisitos Tipos de campo Todos los campos – variables de instancia – deben declararse y debe proporcionar una anotación de tipo para cada campo. Type Example Python integers i: int Python floats f: float Python strings s: str Python booleans b: bool Python None n: None Tensor shapes shape: tf.TensorShape s Tensor dtype dtype: tf.DType Tensors t: tf.Tensor Extension types mt: MyMaskedTensor Ragged tensors rt: tf.RaggedTensor Sparse tensors st: tf.SparseTensor Indexed slices s: tf.IndexedSlices Optional tensors o: tf.experimental.Optional Type unions int_or_float: typing.Union[int, float] Tuples params: typing.Tuple[int, float, tf.Tensor, int] Var-length tuples lengths: typing.Tuple[int, ...] Mappings tags: typing.Mapping[str, tf.Tensor] Optional values weight: typing.Optional[tf.Tensor] Introducción a Python i: int Python flotaciones f: float Con Python Strings s: str Python Booleanos b: bool Python None n: None Tensores de forma shape: tf.TensorShape s Tensor dtype dtype: tf.DType Tensores t: tf.Tensor Tipos de extensión mt: MyMaskedTensor Tensores Tensores rt: tf.RaggedTensor Tensores de ahorro st: tf.SparseTensor Cajas indexadas s: tf.IndexedSlices Tensores opcionales o: tf.experimental.Optional Tipos de sindicatos int_or_float: typing.Union[int, float] Tuplas params: typing.Tuple[int, float, tf.Tensor, int] Duración de las tuplas lengths: typing.Tuple[int, ...] Mapas tags: typing.Mapping[str, tf.Tensor] Valores opcionales weight: typing.Optional[tf.Tensor] Mutabilidad Se requiere que los tipos de extensión sean inmutables. Esto asegura que puedan ser rastreados correctamente por los mecanismos de seguimiento de gráficos de TensorFlow. Si se encuentra deseando mutar un valor de tipo de extensión, considere definir métodos que transformen valores. Modificar el método a Puedes definir a Un sistema que devuelve una nueva : set_mask MaskedTensor replace_mask MaskedTensor class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor def replace_mask(self, new_mask): self.values.shape.assert_is_compatible_with(new_mask.shape) return MaskedTensor(self.values, new_mask) Funcionalidad agregada por ExtensionType Extensiones El La clase base ofrece la siguiente funcionalidad: ExtensionType Un constructor (__init__) Un método de representación impresible (__repr__). Activistas de igualdad y desigualdad (__eq__). Un método de validación (__validate__). La inmutabilidad forzada. Un tipo de nido. Tensor API Dispatch soporte. Ir a “Customización” s" sección de abajo para obtener más información sobre la personalización de esta funcionalidad. ExtensionType Constructor El constructor añadió toma cada campo como un argumento nombrado (en el orden en que fueron listados en la definición de clase). Este constructor escribirá cada parámetro, y los convertirá cuando sea necesario. Los campos se convierten usando • El Los campos se convierten en S; y Los campos se convierten en dictos inmutables. ExtensionType Tensor tf.convert_to_tensor Tuple tuple Mapping class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor # Constructor takes one parameter for each field. mt = MaskedTensor(values=[[1, 2, 3], [4, 5, 6]], mask=[[True, True, False], [True, False, True]]) # Fields are type-checked and converted to the declared types. # For example, `mt.values` is converted to a Tensor. print(mt.values) El constructor levanta un Si un valor de campo no puede ser convertido a su tipo declarado: TypeError try: MaskedTensor([1, 2, 3], None) except TypeError as e: print(f"Got expected TypeError: {e}") El valor predeterminado para un campo se puede especificar estableciendo su valor en el nivel de la clase: class Pencil(tf.experimental.ExtensionType): color: str = "black" has_erasor: bool = True length: tf.Tensor = 1.0 Pencil() Pencil(length=0.5, color="blue") Impresión representativa Escribe un artículo sobre el sistema de representación por defecto ( ) que incluye el nombre de la clase y el valor para cada campo: ExtensionType __repr__ print(MaskedTensor(values=[1, 2, 3], mask=[True, True, False])) Operadores de igualdad Añade los operadores de igualdad por defecto ( y ) que consideran dos valores iguales si tienen el mismo tipo y todos sus campos son iguales. campos de tensores se consideran iguales si tienen la misma forma y son elementalmente iguales para todos los elementos. ExtensionType __eq__ __ne__ a = MaskedTensor([1, 2], [True, False]) b = MaskedTensor([[3, 4], [5, 6]], [[False, True], [True, True]]) print(f"a == a: {a==a}") print(f"a == b: {a==b}") print(f"a == a.values: {a==a.values}") Nota: si cualquier campo contiene un Tensor, entonces __eq__ puede devolver un Tensor booleano escalar (en lugar de un valor booleano de Python). Si un campo contiene a Y entonces Puede devolver un booleano escalar (en lugar de un valor booleano de Python). Note: Tensor __eq__ Tensor Método de validación Añade a Se ejecuta después de que el constructor sea llamado, y después de que los campos hayan sido verificados y convertidos a sus tipos declarados, por lo que puede asumir que todos los campos tienen sus tipos declarados. ExtensionType __validate__ El siguiente ejemplo de actualizaciones Para validar el S y S de sus campos: MaskedTensor shape dtype class MaskedTensor(tf.experimental.ExtensionType): """A tensor paired with a boolean mask, indicating which values are valid.""" values: tf.Tensor mask: tf.Tensor def __validate__(self): self.values.shape.assert_is_compatible_with(self.mask.shape) assert self.mask.dtype.is_bool, 'mask.dtype must be bool' try: MaskedTensor([1, 2, 3], [0, 1, 0]) # Wrong `dtype` for mask. except AssertionError as e: print(f"Got expected AssertionError: {e}") try: MaskedTensor([1, 2, 3], [True, False]) # shapes don't match. except ValueError as e: print(f"Got expected ValueError: {e}") Immutabilidad forzada Supera los y métodos para prevenir la mutación, asegurando que los valores de tipo de extensión son inmutables. ExtensionType __setattr__ __delattr__ mt = MaskedTensor([1, 2, 3], [True, False, True]) try: mt.mask = [True, True, True] except AttributeError as e: print(f"Got expected AttributeError: {e}") try: mt.mask[0] = False except TypeError as e: print(f"Got expected TypeError: {e}") try: del mt.mask except AttributeError as e: print(f"Got expected AttributeError: {e}") Descripción de TypeSpec Cada uno La clase tiene una correspondencia clase, que se crea automáticamente y se almacena como . ExtensionType TypeSpec .Spec Esta clase captura toda la información de un valor para los valores de cualquier tensor niñado. en particular, el para un valor se crea reemplazando cualquier Tensor, ExtensionType o CompositeTensor anexado con su . excepto TypeSpec TypeSpec class Player(tf.experimental.ExtensionType): name: tf.Tensor attributes: Mapping[str, tf.Tensor] anne = Player("Anne", {"height": 8.3, "speed": 28.1}) anne_spec = tf.type_spec_from_value(anne) print(anne_spec.name) # Records `dtype` and `shape`, but not the string value. print(anne_spec.attributes) # Records keys and TensorSpecs for values. los valores pueden ser construidos explícitamente, o pueden ser construidos a partir de un Valor de uso : TypeSpec ExtensionType tf.type_spec_from_value spec1 = Player.Spec(name=tf.TensorSpec([], tf.float32), attributes={}) spec2 = tf.type_spec_from_value(anne) s son usadas por TensorFlow para dividir los valores en y a : TypeSpec static component dynamic component El componente estático (que se fija en el tiempo de grafo-construcción) se codifica con un tf.TypeSpec. El componente dinámico (que puede variar cada vez que se ejecuta el gráfico) se codifica como una lista de tf.Tensores. Por ejemplo, retrace su función envuelta cada vez que un argumento tiene un : tf.function TypeSpec @tf.function def anonymize_player(player): print(" >") return Player(" ", player.attributes) # Function gets traced (first time the function has been called): anonymize_player(Player("Anne", {"height": 8.3, "speed": 28.1})) # Function does NOT get traced (same TypeSpec: just tensor values changed) anonymize_player(Player("Bart", {"height": 8.1, "speed": 25.3})) # Function gets traced (new TypeSpec: keys for attributes changed): anonymize_player(Player("Chuck", {"height": 11.0, "jump": 5.3})) Para más información, ver el . TF.Guía de Funciones personalizado s ExtensionType Extensiones Además de simplemente declarar campos y sus tipos, los tipos de extensión pueden: Descarga de la representación impresible predeterminada (__repr__). Define los métodos. Métodos de clase y métodos estáticos. Definición de propiedades. Descarga el constructor predeterminado (__init__). Descargue el operador de igualdad por defecto (__eq__). Define los operadores (como __add__ y ). Declarar valores por defecto para campos. Definición de subclases. Reemplazar la representación impresible predeterminada Puede anular este operador de conversión de filas por defecto para los tipos de extensión.El siguiente ejemplo actualiza el clase para generar una representación de cadena más legible cuando se imprimen valores en modo Eager. MaskedTensor class MaskedTensor(tf.experimental.ExtensionType): """A tensor paired with a boolean mask, indicating which values are valid.""" values: tf.Tensor mask: tf.Tensor # shape=values.shape; false for invalid values. def __repr__(self): return masked_tensor_str(self.values, self.mask) def masked_tensor_str(values, mask): if isinstance(values, tf.Tensor): if hasattr(values, 'numpy') and hasattr(mask, 'numpy'): return f' ' else: return f'MaskedTensor(values={values}, mask={mask})' if len(values.shape) == 1: items = [repr(v) if m else '_' for (v, m) in zip(values, mask)] else: items = [masked_tensor_str(v, m) for (v, m) in zip(values, mask)] return '[%s]' % ', '.join(items) mt = MaskedTensor(values=[[1, 2, 3], [4, 5, 6]], mask=[[True, True, False], [True, False, True]]) print(mt) Definición de métodos Los tipos de extensión pueden definir métodos, al igual que cualquier clase normal de Python. El tipo puede definir a El método que devuelve una copia de con valores enmascarados reemplazados por un dado Los métodos pueden opcionalmente ser anotados con el El decorador. MaskedTensor with_default self default @tf.function class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor def with_default(self, default): return tf.where(self.mask, self.values, default) MaskedTensor([1, 2, 3], [True, False, True]).with_default(0) Definición S y s classmethod staticmethod Los tipos de extensión pueden definir métodos que utilizan el y La decoración, por ejemplo, es tipo podría definir un método de fábrica que oculta cualquier elemento con un valor dado: @classmethod @staticmethod MaskedTensor class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor def __repr__(self): return masked_tensor_str(self.values, self.mask) @staticmethod def from_tensor_and_value_to_mask(values, value_to_mask): return MaskedTensor(values, values != value_to_mask) x = tf.constant([[1, 0, 2], [3, 0, 0]]) MaskedTensor.from_tensor_and_value_to_mask(x, 0) Definición de propiedades Los tipos de extensión pueden definir propiedades utilizando el como cualquier clase normal de Python. por ejemplo, el El tipo puede definir a La propiedad que es una abreviatura para el de los valores: @property MaskedTensor dtype dtype class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor @property def dtype(self): return self.values.dtype MaskedTensor([1, 2, 3], [True, False, True]).dtype Descargar el constructor defectuoso Los constructores personalizados deben establecer un valor para cada campo declarado; y después de que el constructor personalizado regrese, todos los campos se checarán y los valores se convertirán como se describe anteriormente. class Toy(tf.experimental.ExtensionType): name: str price: tf.Tensor def __init__(self, name, price, discount=0): self.name = name self.price = price * (1 - discount) print(Toy("ball", 5.0, discount=0.2)) # On sale -- 20% off! Alternativamente, puede considerar dejar el constructor predeterminado como es, pero agregar uno o más métodos de fábrica. class Toy(tf.experimental.ExtensionType): name: str price: tf.Tensor @staticmethod def new_toy_with_discount(name, price, discount): return Toy(name, price * (1 - discount)) print(Toy.new_toy_with_discount("ball", 5.0, discount=0.2)) Desarrollo de la operación de igualdad por defecto ( ) __eq__ Puedes eliminar el defecto operador para los tipos de extensión. Las siguientes actualizaciones de ejemplo Ignorar los elementos enmascarados al comparar por igualdad. __eq__ MaskedTensor class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor def __repr__(self): return masked_tensor_str(self.values, self.mask) def __eq__(self, other): result = tf.math.equal(self.values, other.values) result = result | ~(self.mask & other.mask) return tf.reduce_all(result) x = MaskedTensor([1, 2, 3, 4], [True, True, False, True]) y = MaskedTensor([5, 2, 0, 4], [False, True, False, True]) print(x == y) Nota: Por lo general, no es necesario revertir, ya que su implementación predeterminada simplemente llama __eq__ y nega el resultado. Por lo general, no es necesario sobrepasar Como su implantación estándar simplemente llama y negar el resultado. Note: __ne__ __eq__ Utilización de referencias avanzadas Si el tipo para un campo aún no se ha definido, puede utilizar una cadena que contenga el nombre del tipo en su lugar. Se utiliza para anotar el El campo porque el El tipo no ha sido (totalmente) definido todavía. "Node" children Node class Node(tf.experimental.ExtensionType): value: tf.Tensor children: Tuple["Node", ...] = () Node(3, [Node(5), Node(2)]) Definición de subclases Los tipos de extensión pueden ser subclasificados usando la sintaxis estándar de Python. Las subclasificaciones de tipo de extensión pueden agregar nuevos campos, métodos y propiedades; y pueden suplantar el constructor, la representación impresible y el operador de igualdad. Una clase que utiliza tres campos para codificar un conjunto de bordes entre nodos. Después define una subclase que agrega un campo para registrar un "valor de característica" para cada nodo. La subclase también define un método para propagar los valores de característica a lo largo de los bordes. TensorGraph Tensor Tensor class TensorGraph(tf.experimental.ExtensionType): num_nodes: tf.Tensor edge_src: tf.Tensor # edge_src[e] = index of src node for edge e. edge_dst: tf.Tensor # edge_dst[e] = index of dst node for edge e. class TensorGraphWithNodeFeature(TensorGraph): node_features: tf.Tensor # node_features[n] = feature value for node n. def propagate_features(self, weight=1.0) -> 'TensorGraphWithNodeFeature': updates = tf.gather(self.node_features, self.edge_src) * weight new_node_features = tf.tensor_scatter_nd_add( self.node_features, tf.expand_dims(self.edge_dst, 1), updates) return TensorGraphWithNodeFeature( self.num_nodes, self.edge_src, self.edge_dst, new_node_features) g = TensorGraphWithNodeFeature( # Edges: 0->1, 4->3, 2->2, 2->1 num_nodes=5, edge_src=[0, 4, 2, 2], edge_dst=[1, 3, 2, 1], node_features=[10.0, 0.0, 2.0, 5.0, -1.0, 0.0]) print("Original features:", g.node_features) print("After propagating:", g.propagate_features().node_features) Definición de campos privados Los campos de un tipo de extensión pueden ser marcados privados prefixiándolos con un sub-score (siguiente a las convenciones estándar de Python). Esto no afecta a la forma en que TensorFlow trata los campos de ninguna manera; sino que simplemente sirve como una señal a cualquier usuario del tipo de extensión de que esos campos son privados. Personalizar el El s ExtensionType TypeSpec Cada uno La clase tiene una correspondencia clase, que se crea automáticamente y se almacena como Para más información, consulte la sección "Nested TypeSpec" de arriba. ExtensionType TypeSpec .Spec Para acostumbrar el , simplemente defina su propia clase anclada llamada , y se utilizará como base para la construcción de Puedes customizar el Clases por : TypeSpec Spec ExtensionType TypeSpec Spec Suprimir la representación impresible predeterminada. Descargar el constructor defectuoso. Definir métodos, métodos de clase, métodos estáticos y propiedades. El siguiente ejemplo muestra la costumbre Para que sea más fácil de usar: MaskedTensor.Spec class MaskedTensor(tf.experimental.ExtensionType): values: tf.Tensor mask: tf.Tensor shape = property(lambda self: self.values.shape) dtype = property(lambda self: self.values.dtype) def __repr__(self): return masked_tensor_str(self.values, self.mask) def with_values(self, new_values): return MaskedTensor(new_values, self.mask) class Spec: def __init__(self, shape, dtype=tf.float32): self.values = tf.TensorSpec(shape, dtype) self.mask = tf.TensorSpec(shape, tf.bool) def __repr__(self): return f"MaskedTensor.Spec(shape={self.shape}, dtype={self.dtype})" shape = property(lambda self: self.values.shape) dtype = property(lambda self: self.values.dtype) Nota: La clase Spec personalizada no puede usar ninguna variable de instancia que no estuviera declarada en el ExtensionType original. La costumbre La clase no puede utilizar ninguna variable de instancia que no se declarara en el original. . Note: Spec ExtensionType Originalmente publicado en el sitio web de TensorFlow, este artículo aparece aquí bajo un nuevo título y está licenciado bajo CC BY 4.0. Originalmente publicado en el sitio web de TensorFlow, este artículo aparece aquí bajo un nuevo título y está licenciado bajo CC BY 4.0. TensorFlow TensorFlow