TensorFlow Extension Types Explained with Examples(例で説明されたTensorFlow拡張タイプ)

コンテンツ概要 セットアップ 拡張タイプ APIs サポート 要件 フィールドタイプ 変異性 ExtensionType によって追加された機能 建設者 印刷代表 平等事業者 検証方法 強制不変性 タイトルTypeSpec 拡張型のカスタマイズ Default Printable Representation を表示する 定義方法 クラスメソッドとスタティックメソッドの定義 資産の定義 「Default Constructor」 デフォルト平等演算子(eq) forward references を使用する サブクラスの定義 個人フィールドの定義 ExtensionType の TypeSpec をカスタマイズする セットアップ !pip install -q tf_nightly import tensorflow as tf import numpy as np from typing import Tuple, List, Mapping, Union, Optional import tempfile 拡張タイプ User-defined types can make projects more readable, modular, maintenanceable. However, most TensorFlow APIs have very limited support for user-defined Python types. This includes both high-level APIs (such as で、 で、 )および低レベルのAPI(例えば、 そして 【TensorFlow】 TensorFlow の API でシームレスに動作するユーザー定義のオブジェクト指向型を作成するために使用できます。 基礎として、利用 各フィールドの種類を指定します。 カラス TF機能 tf.SavedModel tf.while_loop tf.concat extension types tf.experimental.ExtensionType 注記の種類 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 THE ベースクラスは、同じように働く。 そして 標準の Python ライブラリから、特に、自動的に Constructor と特別なメソッド(例えば、 そして ) フィールドタイプの注釈に基づいて。 tf.experimental.ExtensionType typing.NamedTuple @dataclasses.dataclass __repr__ __eq__ 通常、拡張タイプは、2つのカテゴリのいずれかに該当する傾向があります。 Data structures, which group together a collection of related values, and can provide useful operations based on those values. Data structures may be fairly general (such as the TensorGraph example above); or they may be highly customized to a specific model. データ構造は、比較的一般的である場合があります。 このカテゴリのタイプには、ランク、形状、および通常は dtype があり、tf.stack、tf.add、または tf.matmul などの Tensor 操作でそれらを使用することは合理的です。 データ構造 テニスタイプ APIs サポート 拡張タイプは、以下の TensorFlow API によってサポートされています。 Keras: 拡張タイプは、Keras モデルとレイヤーの入力と出力として使用できます。 tf.data.Dataset: Extension types can be included in Datasets, and returned by dataset Iterators. 拡張型は、データセットイタレーターによってデータセットに含まれることができます。 TensorFlow Hub: 拡張タイプは、tf.hub モジュールの入力と出力として使用できます。 SavedModel: 拡張型は、SavedModel 関数の入力と出力として使用できます。 tf.function: Extension types can be used as arguments and return values for functions wrapped with the @tf.function decorator. tf.function: 拡張タイプは、 @tf.function decorator で包装された関数のアルゴリズムとして使用し、値を返します。 While loops: Extension types can be used as loop variables in tf.while_loop, and can be used as arguments and return values for the while-loop's body. Extension types can be used as loop variables in tf.while_loop, and can be used as arguments and return values for the while-loop's body. 条件付き: 拡張タイプは tf.cond および tf.case を使用して条件付きで選択できます。 tf.py_function: 拡張型は、arguments として使用し、tf.py_function の func アルゴリズムの値を返します。 Tensor ops: 拡張タイプは、Tensor inputs (tf.matmul、tf.gather、tf.reduce_sum など) をサポートするほとんどの TensorFlow オプションをサポートするように拡張できます。 Distribution strategy: Extension types can be used as per-replica values. 拡張型は複製値として使用できます。 詳細については、「ExtensionTypes をサポートする TensorFlow API」のセクションを参照してください。 要件 フィールドタイプ すべてのフィールド — インスタンス変数 — は宣言され、各フィールドにはタイプの注記が提供されなければなりません。 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 integersについて i: int Python フロート f: float Python Stringsについて s: str Python Booleansについて b: bool Python None n: None タンセンサー形状 shape: tf.TensorShape s テンサー dtype dtype: tf.DType テネス t: tf.Tensor 拡張タイプ mt: MyMaskedTensor ラグジット TENSOR rt: tf.RaggedTensor 緊張の節約 st: tf.SparseTensor インデックスシリーズ s: tf.IndexedSlices オプションTENSOR o: tf.experimental.Optional 組合の種類 int_or_float: typing.Union[int, float] ダブル params: typing.Tuple[int, float, tf.Tensor, int] 久しぶりのTuples lengths: typing.Tuple[int, ...] マップ tags: typing.Mapping[str, tf.Tensor] オプション値 weight: typing.Optional[tf.Tensor] 変異性 拡張型は不変である必要があります。これは、TensorFlowのグラフトラッキングメカニズムによって適切に追跡できることを保証します。拡張型の値を変異したい場合は、代わりに値を変換する方法を定義することを検討してください。 変換方法 A あなたはAを定義することができます。 新しい方法を返す方法 : 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) 機能追加 by 拡張型 拡張型 THE base class は、以下の機能を提供します。 ExtensionType 作り手(かんたん) 印刷可能な表示方法(__repr__) 平等と不平等(__eq__) 検証方法(検証方法) 不変性の強化 ネイティブなタイプ。 Tensor API Dispatch サポート Go to “カスタマイズ” s」のセクションは、この機能をカスタマイズする方法についての詳細を参照してください。 ExtensionType 建設者 建築家 追加 by 各フィールドを名称アルゴリズムとして使用します(クラス定義に記載された順序で)。このコンクリエイターは、各パラメータの入力をチェックし、必要に応じて変換します。 フィールドは使用して変換されます ; ; フィールドが変換される S、および フィールドは不変のディクトルに変換されます。 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) 建築家は、A フィールド値が宣言されたタイプに変換できない場合: TypeError try: MaskedTensor([1, 2, 3], None) except TypeError as e: print(f"Got expected TypeError: {e}") フィールドのデフォルト値は、クラスレベルに値を設定することで指定できます。 class Pencil(tf.experimental.ExtensionType): color: str = "black" has_erasor: bool = True length: tf.Tensor = 1.0 Pencil() Pencil(length=0.5, color="blue") 印刷代表 デフォルトのプリント可能な表現方法を追加します( ) クラス名と各フィールドの値を含む: ExtensionType __repr__ print(MaskedTensor(values=[1, 2, 3], mask=[True, True, False])) 平等事業者 デフォルト平等運用者を追加する( そして ) 2つの値が同じタイプで、そのすべてのフィールドが同じである場合に等しいとみなす。 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}") 注: フィールドに Tensor が含まれている場合、 __eq__ は Scalar Boolean Tensor (Python Boolean 値ではなく) を返す場合があります。 注: フィールドに Tensor が含まれている場合、 __eq__ は Scalar Boolean Tensor (Python Boolean 値ではなく) を返す場合があります。 検証方法 追加A フィールドの検証を実行するためにオーバーリードすることができる方法. It is run after the constructor is called, and after fields have been type-checked and converted to their declared types, so it can assume that all fields have their declared types. フィールドは、構築者が呼び出され、フィールドがタイプ検証され、宣言されたタイプに変換された後、実行されます。 ExtensionType __validate__ 次の例の更新 を評価するために Sと S のフィールド: 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}") 強制不変性 Overrides the そして 変異を防止する方法は、拡張型の値が不変であることを保証する。 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}") タイトルTypeSpec 各 クラスは相応の 自動的に作成され、保存されるクラスは、 . ExtensionType TypeSpec .Spec このクラスは、値からすべての情報を収集します。 すべてのトランスフォーメーションの値のために、特に、 for a value is created by replacing any nested Tensor, ExtensionType, or CompositeTensor with its . 除く 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. 価値は明示的に構築されるか、あるいはそれらは、 利用価値 : TypeSpec ExtensionType tf.type_spec_from_value spec1 = Player.Spec(name=tf.TensorSpec([], tf.float32), attributes={}) spec2 = tf.type_spec_from_value(anne) s は TensorFlow によって、値を a に分割するために使用されます。 そしてA : TypeSpec static component dynamic component 静的コンポーネント(グラフ構造時間に固定)はtf.TypeSpecで暗号化されます。 ダイナミックコンポーネント(グラフが実行されるたびに変化する)は、tf.Tensorsのリストとして暗号化されます。 例えば、 以前見たことのないアルバムが存在するたびにその巻き込まれた機能を追跡します。 : 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})) より詳しい情報は、The . tf.function ガイド カスタマイズ s 拡張型 拡張型 フィールドとそのタイプを単純に宣言することに加えて、拡張タイプは次のようになります。 デフォルト印刷可能な表示(__repr__)をオーバーライドします。 方法を定義する。 クラス方法と静的方法を定義する。 資産の定義 デフォルトコンクリエイター(__init__)をオブレードします。 デフォルト平等オペレーター(__eq__)を上回ります。 オペレーターを定義する (such as __add__ and ) フィールドのデフォルト値を宣言します。 サブクラスの定義 Default Printable Representation を表示する このデフォルトの String Conversion オペレーターを拡張タイプに置き換えることができます。 クラスは、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) 定義方法 Extension types can define methods, just like any normal Python class. たとえば、 型はAを定義することができる。 コピーを返す方法 指定された値に置き換えられた仮面値 Value. Methods can optionally be annotated with the デザイナー 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) 定義 Sと s classmethod staticmethod Extension types can define methods using the そして デザイナー: 例えば、 type は、特定の値を含むすべての要素をマスクする工場方法を定義することができる。 @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) 資産の定義 Extension types can define properties using the 普通のPythonクラスと同じように、 型はAを定義することができる。 不動産は、そのための短縮です。 価値観について: @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 「Default Constructor」 Custom constructors must set a value for each declared field; and after the custom constructor returns, all fields will be type-checked, and values will be converted as described above. カスタマイズされた constructors must set a value for each declared field; and after the custom constructor returns, all fields will be type-checked, and values will be converted as described above. 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! 代わりに、デフォルトのコンクリエーター as-is を残すことを検討する場合がありますが、1 つまたは複数の工場メソッドを追加します。 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)) デフォルト平等運用者( ) __eq__ デフォルトを省略できる 拡張タイプのオペレーター. The following example updates 平等を求めて比較する際に仮面した要素を無視する。 __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) 注: デフォルトの実装が単に __eq__ を呼び出し、結果を否定するため、一般にオーバーレードする必要はありません。 あなたは通常、オーバーライドする必要はありません。 デフォルトの実装が単に呼びかけているので、 結果を否定する。 Note: __ne__ __eq__ forward references を使用する フィールドの型がまだ定義されていない場合は、代わりにそのタイプの名前を含む文字列を使用できます。 を記録するのに使われている。 フィールドは、なぜなら タイプはまだ(完全に)定義されていません。 "Node" children Node class Node(tf.experimental.ExtensionType): value: tf.Tensor children: Tuple["Node", ...] = () Node(3, [Node(5), Node(2)]) サブクラスの定義 Extension types can be subclassed using the standard Python syntax. Extension type subclasses may add new fields, methods, and properties; and may override the constructor, the printable representation, and the equality operator. The following example defines a basic 3 使用するクラス ノード間のエッジのセットをコードするためのフィールド. It then defines a subclass that adds a 各ノードの「機能値」を記録するためのフィールド. The subclass also defines a method to propagate the feature values along the edges. 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) 個人フィールドの定義 拡張型のフィールドは、サブスコア(標準のPython条約に従って)でプレフィックスすることによってプライベートにマークされることがあります。これはTensorFlowがフィールドを何らかの方法で扱う方法に影響しません。 をカスタマイズ 「S」 ExtensionType TypeSpec 各 クラスは相応の 自動的に作成され、保存されるクラスは、 詳細については、上記の「Nested TypeSpec」を参照してください。 ExtensionType TypeSpec .Spec 習慣化するために , simply define your own nested class named という名前のクラスです。 そして、 これを自動的に作り上げるための基盤として使います。 You can customize the クラス by: TypeSpec Spec ExtensionType TypeSpec Spec デフォルトの印刷可能な表示を上回ります。 デフォルト・ビルダーをダウンロードする 方法、クラス方法、静的方法、および属性を定義する。 次の例では、従来の 使いやすくするためのクラス: 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) 注: Custom Spec クラスでは、元の ExtensionType で宣言されていないインスタンス変数を使用することはできません。 風習 クラスは、オリジナルで宣言されていないインスタンス変数を使用することはできません。 . Note: Spec ExtensionType 最初はTensorFlowのウェブサイトに掲載され、この記事はここに新しいタイトルの下に表示され、CC BY 4.0でライセンスを受けています。 最初はTensorFlowのウェブサイトに掲載され、この記事はここに新しいタイトルの下に表示され、CC BY 4.0でライセンスを受けています。 TensorFlowについて TensorFlowについて