Types d'extension TensorFlow expliqués par des exemples

Vue d'ensemble du contenu établissement Type d’extension Appui aux APIs exigences types de champs Mutabilité Fonctionnalités ajoutées par ExtensionType Constructeur Représentation imprimable Les opérateurs d’égalité Méthode de validation Immutabilité forcée Télécharger TypeSpec Type d’extension personnalisée Supprimer la représentation imprimable par défaut Définir les méthodes Définir les méthodes de classe et les méthodes statiques Définir les propriétés Supprimer le constructeur par défaut Supprimer l’opérateur d’égalité par défaut (eq) Utiliser des références avancées Définition des sous-classes Définir les espaces privés Personnaliser le TypeSpec de l'extensionType établissement !pip install -q tf_nightly import tensorflow as tf import numpy as np from typing import Tuple, List, Mapping, Union, Optional import tempfile Type d’extension Les types définis par l'utilisateur peuvent rendre les projets plus lisibles, modulaires et maintenables. Cependant, la plupart des APIs TensorFlow ont un support très limité pour les types Python définis par l'utilisateur. , à , à des niveaux inférieurs (tels que et Le TensorFlow peut être utilisé pour créer des types orientés objet définis par l'utilisateur qui fonctionnent en toute simplicité avec les API de TensorFlow. La base, et son utilisation spécifier le type pour chaque champ. Keras tf. fonction tf.SavedModel tf.while_loop tf.concat extension types tf.experimental.ExtensionType Types d’annotations 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 Le La classe de base fonctionne de la même manière que et de la bibliothèque Python standard. En particulier, il ajoute automatiquement un constructeur et des méthodes spéciales (telles que et ) en fonction des annotations de type champ. tf.experimental.ExtensionType typing.NamedTuple @dataclasses.dataclass __repr__ __eq__ Typiquement, les types d’extension ont tendance à tomber dans l’une des deux catégories : Structures de données, qui regroupent une collection de valeurs liées et peuvent fournir des opérations utiles basées sur ces valeurs.Structures de données peuvent être assez générales (comme l'exemple de TensorGraph ci-dessus); ou elles peuvent être hautement personnalisées à un modèle spécifique. Les types de cette catégorie ont un rang, une forme, et généralement un dtype; et il est logique de les utiliser avec les opérations de Tensor (tels que tf.stack, tf.add, ou tf.matmul). Structures de données Types de ténors Appui aux APIs Les types d'extension sont pris en charge par les API TensorFlow suivants : Keras: Les types d'extension peuvent être utilisés comme entrées et sorties pour les modèles et les couches Keras. tf.data.Dataset: Les types d'extension peuvent être inclus dans les datasets et retournés par les itérateurs de datasets. TensorFlow Hub: Les types d'extension peuvent être utilisés comme entrées et sorties pour les modules tf.hub. SavedModel: Les types d'extension peuvent être utilisés comme entrées et sorties pour les fonctions SavedModel. tf.function: Les types d'extension peuvent être utilisés comme arguments et renvoyer des valeurs pour les fonctions enveloppées avec le décorateur @tf.function. Pendant que les boucles : Les types d'extension peuvent être utilisés comme variables de boucle dans tf.while_loop, et peuvent être utilisés comme arguments et valeurs de retour pour le corps du boucle pendant. Les types d'extension peuvent être sélectionnés conditionnellement en utilisant tf.cond et tf.case. tf.py_function: Les types d'extension peuvent être utilisés comme arguments et retourner des valeurs pour l'argument func à tf.py_function. Options Tensor: Les types d'extension peuvent être étendus pour prendre en charge la plupart des options TensorFlow qui acceptent les entrées Tensor (telles que tf.matmul, tf.gather et tf.reduce_sum). Stratégie de distribution: Les types d'extension peuvent être utilisés comme valeurs par réplique. Pour plus de détails, consultez la section « APIs TensorFlow qui prennent en charge ExtensionTypes » ci-dessous. exigences types de champs Tous les champs — variables d'instance — doivent être déclarés et une annotation de type doit être fournie pour chaque champ. Les annotations de type suivantes sont prises en charge: 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] Python intégré i: int Python flottant f: float Python pour Strings s: str Python bouléens b: bool Python None n: None Tensions de forme shape: tf.TensorShape s Ténor dtype dtype: tf.DType Tensions t: tf.Tensor Type d’extension mt: MyMaskedTensor Tensions électriques rt: tf.RaggedTensor économiser des tensions st: tf.SparseTensor Indice des tranches s: tf.IndexedSlices Tensions optionnelles o: tf.experimental.Optional Types de syndicats int_or_float: typing.Union[int, float] Les doubles params: typing.Tuple[int, float, tf.Tensor, int] Tuples de longueur lengths: typing.Tuple[int, ...] Mappings tags: typing.Mapping[str, tf.Tensor] Valeurs optionnelles weight: typing.Optional[tf.Tensor] Mutabilité Les types d'extension doivent être immuables. Cela garantit qu'ils peuvent être correctement suivis par les mécanismes de suivi des graphiques de TensorFlow. Si vous souhaitez modifier une valeur de type d'extension, envisagez plutôt de définir des méthodes qui transforment des valeurs. Modifier la méthode A Vous pouvez définir une Une méthode qui renvoie à une : 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) Fonctionnalité ajoutée par Extension de type Extension de type Le La classe de base offre les fonctionnalités suivantes : ExtensionType Un constructeur (__init__) Une méthode de représentation imprimable (__repr__). Les acteurs de l’égalité et de l’inégalité (__eq__). Une méthode de validation (__validate__) Une immuabilité forcée. Une sorte de TypeSpec. Tensor API dispatch support. Aller à la page « personnalisation » s" section ci-dessous pour plus d'informations sur la personnalisation de cette fonctionnalité. ExtensionType Constructeur Le constructeur a ajouté prend chaque champ comme un argument nommé (dans l'ordre dans lequel ils ont été répertoriés dans la définition de la classe). Ce constructeur va taper chaque paramètre, et les convertir si nécessaire. Les champs sont convertis en utilisant ; ; Les champs sont convertis en s ; et Les champs sont convertis en dicts immuables. 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) Le constructeur met en place un si une valeur de champ ne peut pas être convertie en son type déclaré : TypeError try: MaskedTensor([1, 2, 3], None) except TypeError as e: print(f"Got expected TypeError: {e}") La valeur par défaut pour un champ peut être spécifiée en définissant sa valeur au niveau de la classe : class Pencil(tf.experimental.ExtensionType): color: str = "black" has_erasor: bool = True length: tf.Tensor = 1.0 Pencil() Pencil(length=0.5, color="blue") Représentation imprimable Il s’agit d’une méthode d’impression par défaut ( ) qui comprend le nom de la classe et la valeur pour chaque champ : ExtensionType __repr__ print(MaskedTensor(values=[1, 2, 3], mask=[True, True, False])) Les opérateurs d’égalité Les opérateurs d'égalité par défaut ( et ) qui considèrent deux valeurs égales si elles ont le même type et que tous leurs champs sont égaux. 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}") Remarque : si un champ contient un Tensor, alors __eq__ peut retourner un Tensor Boolean scalaire (au lieu d'une valeur Boolean Python). Remarque : si un champ contient un Tensor, alors __eq__ peut retourner un Tensor Boolean scalaire (au lieu d'une valeur Boolean Python). Méthode de validation Ajoutez A Il est exécuté après que le constructeur est appelé, et après que les champs ont été vérifiés et convertis à leurs types déclarés, de sorte qu'il peut supposer que tous les champs ont leurs types déclarés. ExtensionType __validate__ Les exemples suivants de mises à jour Pour valider le S et S de ses champs : 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}") Immutabilité forcée Il dépasse les et des méthodes pour prévenir les mutations, en veillant à ce que les valeurs de type d'extension soient immuables. 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}") Télécharger TypeSpec Chaque La classe est correspondante class, qui est créé automatiquement et stocké comme . ExtensionType TypeSpec .Spec Cette classe capture toutes les informations d'une valeur pour les valeurs de n'importe quel tenseur niché. en particulier, le pour une valeur est créée en remplaçant n'importe quel Tensor, ExtensionType ou CompositeTensor . Excepté 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. Les valeurs peuvent être construites explicitement, ou elles peuvent être construites à partir d'un Valeur d’utilisation : TypeSpec ExtensionType tf.type_spec_from_value spec1 = Player.Spec(name=tf.TensorSpec([], tf.float32), attributes={}) spec2 = tf.type_spec_from_value(anne) s sont utilisés par TensorFlow pour diviser les valeurs en et a : TypeSpec static component dynamic component Le composant statique (qui est fixé au temps de construction graphique) est codé avec un tf.TypeSpec. Le composant dynamique (qui peut varier chaque fois que le graphique est exécuté) est codé comme une liste de tf.Tensors. Par exemple, retrace sa fonction enveloppée chaque fois qu'un argument a une valeur précédemment invisible. : 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})) Pour plus d’informations, voir le . TF.Function Guide personnalisé s Extension de type Extension de type En plus de simplement déclarer les champs et leurs types, les types d’extension peuvent : Supprimer la représentation imprimable par défaut (__repr__). Définir les méthodes. Définir les méthodes de classe et les méthodes statiques. Définir les propriétés. Ouvrir le constructeur par défaut (__init__). Ouvrir l’opérateur d’égalité par défaut (__eq__). Définir les opérateurs (tels que __add__ et ). Déclarer les valeurs par défaut pour les champs. Définir les sous-classes. Supprimer la représentation imprimable par défaut Vous pouvez remplacer cet opérateur de conversion de chaîne par défaut pour les types d'extension. classe pour générer une représentation de chaîne plus lisible lorsque les valeurs sont imprimées en mode 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) Définir les méthodes Les types d'extension peuvent définir des méthodes, tout comme toute classe Python normale. Le type peut définir a méthode qui renvoie une copie de avec des valeurs masquées remplacées par une donnée méthodes peuvent optionnellement être annotées avec le Le décorateur. 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) Définir S et s classmethod staticmethod Les types d'extension peuvent définir des méthodes utilisant le et decorators. For example, the type pourrait définir une méthode d'usine qui masque tout élément avec une valeur donnée : @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) Définir les propriétés Les types d'extension peuvent définir des propriétés à l'aide de C’est le cas de toutes les classes Python normales, par exemple. Le type peut définir a Propriété qui est un raccourci pour le Sur les valeurs : @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 Supprimer le constructeur par défaut Les constructeurs personnalisés doivent définir une valeur pour chaque champ déclaré ; et après le retour du constructeur personnalisé, tous les champs seront vérifiés et les valeurs seront converties comme décrit ci-dessus. 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! Alternativement, vous pouvez envisager de laisser le constructeur par défaut comme il est, mais d'ajouter une ou plusieurs méthodes d'usine. 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)) L’opérateur d’égalité par défaut ( ) __eq__ Vous pouvez supprimer le défaut l'opérateur pour les types d'extension. Les exemples suivants sont mis à jour d'ignorer les éléments masqués lors de la comparaison pour l'égalité. __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) Remarque : Vous n'avez généralement pas besoin de surcharger , car sa mise en œuvre par défaut appelle simplement __eq__ et négate le résultat. Remarque : Vous n'avez généralement pas besoin de surcharger , car sa mise en œuvre par défaut appelle simplement __eq__ et négate le résultat. Utiliser des références avancées Si le type d'un champ n'a pas encore été défini, vous pouvez utiliser une chaîne contenant le nom du type. Il est utilisé pour noter le champs parce que le Le type n'a pas encore été (entièrement) défini. "Node" children Node class Node(tf.experimental.ExtensionType): value: tf.Tensor children: Tuple["Node", ...] = () Node(3, [Node(5), Node(2)]) Définition des sous-classes Les sous-classes de type d'extension peuvent ajouter de nouveaux champs, méthodes et propriétés; et peuvent remplacer le constructeur, la représentation imprimable et l'opérateur d'égalité. Une classe qui utilise trois champs pour coder un ensemble de bords entre les nœuds. Il définit ensuite une sous-classe qui ajoute une champ pour enregistrer une « valeur de caractère » pour chaque nœud. La sous-classe définit également une méthode pour propager les valeurs de caractère le long des bords. 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) Définir les espaces privés Les champs d'un type d'extension peuvent être marqués privés en les préfixant avec une sous-marque (en suivant les conventions Python standard). Cela n'affecte pas la façon dont TensorFlow traite les champs de quelque manière que ce soit; mais sert simplement de signal à tout utilisateur du type d'extension que ces champs sont privés. personnaliser le et s ExtensionType TypeSpec Chaque La classe est correspondante class, qui est créé automatiquement et stocké comme Pour plus d'informations, voir la section "Nested TypeSpec" ci-dessus. ExtensionType TypeSpec .Spec Pour habituer le , il suffit de définir votre propre classe niché nommée et Il servira de base à la construction automatique. Vous pouvez personnaliser le Classe par : TypeSpec Spec ExtensionType TypeSpec Spec Supprimer la représentation imprimable par défaut. Supprimer le constructeur par défaut. Définir les méthodes, méthodes de classe, méthodes statiques et propriétés. L’exemple suivant démontre la Pour le rendre plus facile à utiliser : 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) Remarque : La classe Spec personnalisée ne peut pas utiliser de variables d’instance qui n’ont pas été déclarées dans l’extensionType d’origine. Remarque : La classe Spec personnalisée ne peut pas utiliser de variables d’instance qui n’ont pas été déclarées dans l’extensionType d’origine. Publié à l'origine sur le site Web de TensorFlow, cet article apparaît ici sous un nouveau titre et est sous licence CC BY 4.0. Publié à l'origine sur le site Web de TensorFlow, cet article apparaît ici sous un nouveau titre et est sous licence CC BY 4.0. TensorFlow TensorFlow