<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L497-L2156) |

The TPUEmbedding mid level API running on TPU with sparse core accelerator.

#### View aliases


**Compat aliases for migration**

See
[Migration guide](https://www.tensorflow.org/guide/migrate) for
more details.

[`tf.compat.v1.tpu.experimental.embedding.TPUEmbeddingV2`](https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/TPUEmbeddingV2)

<br />

    tf.tpu.experimental.embedding.TPUEmbeddingV2(
        feature_config: Union[https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/FeatureConfig, Iterable],
        optimizer: Optional[tpu_embedding_v2_utils._Optimizer] = None,
        pipeline_execution_with_tensor_core: bool = False,
        sparse_core_embedding_config: Optional[https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/SparseCoreEmbeddingConfig] = None
    )

<br />

<br />

<br />

| ## Args ||
|---|---|
| `feature_config` | A nested structure of [`tf.tpu.experimental.embedding.FeatureConfig`](https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/FeatureConfig) configs. |
| `optimizer` | An instance of one of [`tf.tpu.experimental.embedding.SGD`](https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/SGD), [`tf.tpu.experimental.embedding.Adagrad`](https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/Adagrad) or [`tf.tpu.experimental.embedding.Adam`](https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/Adam). When not created under TPUStrategy may be set to None to avoid the creation of the optimizer slot variables, useful for optimizing memory consumption when exporting the model for serving where slot variables aren't needed. |
| `pipeline_execution_with_tensor_core` | If True, the TPU embedding computations will overlap with the TensorCore computations (and hence will be one step old). Set to True for improved performance. |
| `sparse_core_embedding_config` | Configs for sparse core embedding including settings for table stacking, input feature static buffer size etc. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | If optimizer is not one of tf.tpu.experimental.embedding.(SGD, Adam or Adagrad) or None when created under a TPUStrategy. |
| `RuntimeError` | If not created under TPUStrategy. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `embedding_layouts` | Returns how the tables are laid out in the variables. <br /> The SparseCoreTableLayout describes how a table is stored in its internal state. You need this only if you need to pull apart the internal state. |
| `embedding_table_shards` | Returns a dict of embedding tables, keyed by `TableConfig`. |
| `embedding_tables` | Returns a dict of embedding tables, keyed by stacked table name. |
| `variables` | Returns a dict of variables, keyed by `TableConfig`, then by slot name. |

<br />

## Methods

### `apply_gradients`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1141-L1345)

    apply_gradients(
        gradients: Any, preserved_outputs: Dict[str, PartitionedCsrFormatTensor]
    )

Applies the gradient update to the embedding tables.

If a gradient of `None` is passed in any position of the nested structure,
then a gradient update with a zero gradient is applied for that feature.
For optimizers like SGD or Adagrad, this is the same as applying no update
at all. For lazy Adam and other sparsely applied optimizers with decay,
ensure you understand the effect of applying a zero gradient.

<br />

<br />

<br />

| Args ||
|---|---|
| `gradients` | A nested structure of gradients, with structure matching the `feature_config` passed to this object. |
| `preserved_outputs` | A dicts of PartitionedCsrFormatTensor, coming from the second output of the embedding lookup call. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `RuntimeError` | if not built. |
| `ValueError` | If a non-[`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) non-`None` gradient is passed in, or a [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) of the incorrect shape is passed in. Also if the size of any sequence in `gradients` does not match corresponding sequence in `feature_config`. |
| `TypeError` | If the type of any sequence in `gradients` does not match corresponding sequence in `feature_config`. |

<br />

### `build`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1132-L1139)

    build()

Create variables and slots variables for TPU embeddings.

### `compute_sparse_core_stats`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1383-L1478)

    @classmethod
    compute_sparse_core_stats(
        features: Any,
        feature_config: Union[https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/TableConfig, Iterable],
        num_tpu_chips: int,
        num_sc_per_chip: int = 4,
        optimizer: Optional[tpu_embedding_v2_utils._Optimizer] = None,
        sparse_core_embedding_config: Optional[https://www.tensorflow.org/api_docs/python/tf/tpu/experimental/embedding/SparseCoreEmbeddingConfig] = None
    ) -> Tuple[Any, Any]

Computes the max_ids/unique ids settings from the input features.

### `dequeue`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1605-L1673)

    dequeue(
        partitioned_tensors: Tuple[Dict[str, PartitionedCsrFormatTensor], int, int]
    ) -> Tuple[Any, Dict[str, PartitionedCsrFormatTensor]]

Perform embedding lookup.

### `embedding_lookup`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1675-L1718)

    embedding_lookup(
        features: Any, weights: Optional[Any] = None
    ) -> Tuple[Any, Dict[str, PartitionedCsrFormatTensor]]

Perform embedding lookup on the input feature.

<br />

<br />

<br />

| Args ||
|---|---|
| `features` | A nested structure of [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor)s, [`tf.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor)s or [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor)s, with the same structure as `feature_config`. Inputs will be downcast to [`tf.int32`](https://www.tensorflow.org/api_docs/python/tf#int32). Only one type out of [`tf.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor) or [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor) is supported per call. |
| `weights` | If not `None`, a nested structure of [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor)s, [`tf.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor)s or [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor)s, matching the above, except that the tensors should be of float type (and they will be downcast to [`tf.float32`](https://www.tensorflow.org/api_docs/python/tf#float32)). For [`tf.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor)s we assume the `indices` are the same for the parallel entries from `features` and similarly for [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor)s we assume the row_splits are the same. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If the input feature is not one of the Tensor, SparseTensor or RaggedTensor type. |
| `TypeError` | If the type of any sequence in `features` does not match corresponding sequence in `feature_config`. Similarly for `weights`, if not `None`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `packed_activations` | Embedding lookup results packed as the same sequence of the input feature. |
| `packed_output` | A dict of PartitionedCsrFormatTensors. |

<br />

### `enqueue`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1480-L1553)

    enqueue(
        features: Any, weights: Optional[Any] = None, device: Optional[str] = None
    ) -> Any

Preprocessing the features on host.

### `__call__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.21.0/tensorflow/python/tpu/tpu_embedding_v3.py#L1347-L1351)

    __call__(
        features: Any, weights: Optional[Any] = None
    ) -> Tuple[Any, Dict[str, PartitionedCsrFormatTensor]]

Call the mid level api to do embedding lookup.

<br />

<br />

<br />

| ## Class Variables ||
|---|---|
| DEFAULT_MAX_IDS_PER_TABLE | `256` |
| DEFAULT_MAX_UNIQUE_IDS_PER_TABLE | `256` |

<br />