[Opset15][Spec] Add and update specifications for EmbeddingBag ops

docs/articles_en/documentation/openvino-ir-format/operation-sets/operation-specs/sparse/embedding-bag-offsets-15.rst

@@ -0,0 +1,112 @@
+.. {#openvino_docs_ops_sparse_EmbeddingBagOffsets_15}
+
+EmbeddingBagOffsets
+======================
+
+
+.. meta::
+  :description: Learn about EmbeddingBagOffsets-15 - a sparse operation, which
+                can be performed on three required and two optional input tensors.
+
+**Versioned name**: *EmbeddingBagOffsets-15*
+
+**Category**: *Sparse*
+
+**Short description**: Computes sums or means of "bags" of embeddings, without instantiating the intermediate embeddings.
+
+**Detailed description**:
+
+Operation EmbeddingBagOffsets is an implementation of ``torch.nn.EmbeddingBag`` with indices and offsets inputs being 1D tensors.
+
+For each index in ``indices`` this operator gathers values from ``emb_table`` embedding table. Indices that are in range of same bag based on ``offset`` input values are then reduced according to ``reduction`` attribute.
+Values in ``offsets`` define starting index in ``indices`` tensor of each "bag",
+e.g. ``offsets`` with value ``[0, 3, 4, 4, 6]`` define 5 "bags" containing ``[3, 1, 0, 2, num_indices-6]`` elements corresponding to ``[indices[0:3], indices[3:4], empty_bag, indices[4:6], indices[6:]]`` slices of indices per bag.
+
+**Attributes**:
+
+* *reduction*
+
+  * **Description**: reduction mode. 
+  * **Range of values**:
+
+    * sum - compute weighted sum, using corresponding values of ``per_sample_weights`` as weights if provided.
+    * mean - compute average of values in bag. Input ``per_sample_weights`` is not supported and will raise exception.
+
+  * **Type**: ``string``
+  * **Default value**: sum
+  * **Required**: *no*
+
+**Inputs**:
+
+* **1**: ``emb_table`` tensor containing the embedding lookup table of the module of shape ``[num_emb, emb_dim1, emb_dim2, ...]`` and  of type *T*. **Required.**
+* **2**: ``indices`` tensor of shape ``[num_indices]`` and of type *T_IND*. **Required.**
+* **3**: ``offsets`` tensor of shape ``[batch]`` and of type *T_IND* containing the starting index positions of each "bag" in ``indices``. Maximum value of offsets cannot be greater than length of ``indices``. **Required.**
+* **4**: ``default_index`` scalar of type *T_IND* containing default index in embedding table to fill empty "bags". If set to ``-1`` or not provided, empty "bags" are filled with zeros. Reverse indexing using negative values is not supported. **Optional.**
+* **5**: ``per_sample_weights`` tensor of the same shape as ``indices`` and of type *T*. Each value in this tensor are multiplied with each value pooled from embedding table for each index. Optional, default is tensor of ones. **Optional.**
+
+**Outputs**:
+
+* **1**: tensor of shape ``[batch, emb_dim1, emb_dim2, ...]`` and of type *T* containing embeddings for each bag.
+
+**Types**
+
+* *T*: any numeric type.
+* *T_IND*: ``int32`` or ``int64``.
+
+**Example**
+
+.. code-block:: cpp
+
+   <layer ... type="EmbeddingBagOffsets" ... >
+       <input>
+           <port id="0">     <!-- emb_table value is: [[-0.2, -0.6], [-0.1, -0.4], [-1.9, -1.8], [-1.,  1.5], [ 0.8, -0.7]] -->
+               <dim>5</dim>
+               <dim>2</dim>
+           </port>
+           <port id="1">     <!-- indices value is: [0, 2, 3, 4] -->
+               <dim>4</dim>
+           </port>
+           <port id="2">     <!-- offsets value is: [0, 2, 2] - 3 "bags" containing [2,0,4-2] elements, second "bag" is empty -->
+               <dim>3</dim>
+           </port>
+           <port id="3"/>    <!-- default_index value is: 0 -->
+           <port id="4"/>    <!-- per_sample_weights value is: [0.5, 0.5, 0.5, 0.5] -->
+               <dim>4</dim>
+           </port>
+       </input>
+       <output>
+           <port id="5">     <!-- output value is: [[-1.05, -1.2], [-0.2, -0.6], [-0.1, 0.4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </output>
+   </layer>
+
+.. code-block:: cpp
+
+   <layer ... type="EmbeddingBagOffsets" ... >
+       <input>
+           <port id="0">     <!-- emb_table value is: [[-0.2, -0.6], [-0.1, -0.4], [-1.9, -1.8], [-1.,  1.5], [ 0.8, -0.7]] -->
+               <dim>5</dim>
+               <dim>2</dim>
+           </port>
+           <port id="1">     <!-- indices value is: [0, 2, 3, 4] -->
+               <dim>4</dim>
+           </port>
+           <port id="2">     <!-- offsets value is: [0, 2, 2] - 3 "bags" containing [2,0,4-2] elements, second "bag" is empty -->
+               <dim>3</dim>
+           </port>
+           <port id="3"/>    <!-- default_index value is: -1 - fill empty bag with 0-->
+           <port id="4"/>    <!-- per_sample_weights value is: [0.5, 0.5, 0.5, 0.5] -->
+               <dim>4</dim>
+           </port>
+       </input>
+       <output>
+           <port id="5">     <!-- output value is: [[-1.05, -1.2], [0, 0], [-0.1, 0.4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </output>
+   </layer>
+
+

docs/articles_en/documentation/openvino-ir-format/operation-sets/operation-specs/sparse/embedding-bag-offsets-sum-3.rst

@@ -14,17 +14,23 @@ EmbeddingBagOffsetsSum
 
 **Short description**: Computes sums of "bags" of embeddings, without instantiating the intermediate embeddings.
 
-**Detailed description**: This is the second case of the PyTorch `EmbeddingBag <https://pytorch.org/docs/stable/nn.html#embeddingbag>`__ , it has indices in two 1D tensors provided as 2nd and 3rd inputs. For each index in ``indices`` this operator gets values from ``data`` embedding table and sums all values belonging to each bag. Values in ``offsets`` define starting index in ``indices`` tensor of each "bag", e.g. ``offsets`` with value ``[0,3,4,4,6]`` define 5 "bags" containing ``[3,1,0,2,n-6]`` elements.
+**Detailed description**:
+
+Operation EmbeddingBagOffsets is an implementation of ``torch.nn.EmbeddingBag`` with indices and offsets inputs being 1D tensors.
+
+For each index in ``indices`` this operator gathers values from ``emb_table`` embedding table. Indices that are in range of same bag based on ``offset`` input values are then reduced using sum  operation.
+Values in ``offsets`` define starting index in ``indices`` tensor of each "bag",
+e.g. ``offsets`` with value ``[0, 3, 4, 4, 6]`` define 5 "bags" containing ``[3, 1, 0, 2, num_indices-6]`` elements corresponding to ``[indices[0:3], indices[3:4], empty_bag, indices[4:6], indices[6:]]`` slices of indices per bag.
 
 **Attributes**: EmbeddingBagOffsetsSum operation has no attributes.
 
 **Inputs**:
 
 * **1**: ``emb_table`` tensor containing the embedding lookup table of the module of shape ``[num_emb, emb_dim1, emb_dim2, ...]`` and  of type *T*. **Required.**
 * **2**: ``indices`` tensor of shape ``[num_indices]`` and of type *T_IND*. **Required.**
-* **3**: ``offsets`` tensor of shape ``[batch]`` and of type *T_IND* containing the starting index positions of each "bag" in ``indices``. **Required.**
-* **4**: ``default_index`` scalar of type *T_IND* containing default index in embedding table to fill empty "bags". If not provided empty "bags" are filled with zeros. **Optional.**
-* **5**: ``per_sample_weights`` tensor of the same shape as ``indices`` and of type *T*. Each value in this tensor are multiplied with each value pooled from embedding table for each index. Optional, default is tensor of ones.
+* **3**: ``offsets`` tensor of shape ``[batch]`` and of type *T_IND* containing the starting index positions of each "bag" in ``indices``. Maximum value of offsets cannot be greater than length of ``indices``. **Required.**
+* **4**: ``default_index`` scalar of type *T_IND* containing default index in embedding table to fill empty "bags". If set to ``-1`` or not provided, empty "bags" are filled with zeros. Reverse indexing using negative values is not supported. **Optional.**
+* **5**: ``per_sample_weights`` tensor of the same shape as ``indices`` and of type *T*. Each value in this tensor are multiplied with each value pooled from embedding table for each index. Optional, default is tensor of ones. **Optional.**
 
 **Outputs**:
 

docs/articles_en/documentation/openvino-ir-format/operation-sets/operation-specs/sparse/embedding-bag-packed-15.rst

@@ -0,0 +1,126 @@
+.. {#openvino_docs_ops_sparse_EmbeddingBagPacked_15}
+
+EmbeddingBagPacked
+=====================
+
+
+.. meta::
+  :description: Learn about EmbeddingBagPacked-15 - a sparse operation, which
+                can be performed on two required and one optional input tensor.
+
+**Versioned name**: *EmbeddingBagPacked-15*
+
+**Category**: *Sparse*
+
+**Short description**: Computes sums or means of "bags" of embeddings, without instantiating the intermediate embeddings.
+
+**Detailed description**:
+
+Operation EmbeddingBagPacked is an implementation of ``torch.nn.EmbeddingBag`` with indices input being 2D tensor of shape ``[batch, indices_per_bag]``.
+Operation is equivalent to *gather_op = Gather(emb_table, indices, axis=0)* followed by reduction:
+
+  * *sum* - *ReduceSum(Multiply(gather_op, Unsqueeze(per_sample_weights, -1)), axis=1)*,
+  * *mean* - *ReduceMean(gather_op, axis=1)*.
+
+**Attributes**:
+
+* *reduction*
+
+  * **Description**: reduction mode. 
+  * **Range of values**:
+
+    * sum - compute weighted sum, using corresponding values of ``per_sample_weights`` as weights if provided.
+    * mean - compute average of values in bag. Input ``per_sample_weights`` is not supported and will raise exception.
+
+  * **Type**: ``string``
+  * **Default value**: sum
+  * **Required**: *no*
+
+**Inputs**:
+
+* **1**: ``emb_table`` tensor containing the embedding lookup table of the module of shape ``[num_emb, emb_dim1, emb_dim2, ...]`` and of type *T*. **Required.**
+* **2**: ``indices`` tensor of shape ``[batch, indices_per_bag]`` and of type *T_IND*. **Required.**
+* **3**: ``per_sample_weights`` tensor of the same shape as ``indices`` and of type *T* supported only in ``sum`` mode. Each value in this tensor are multiplied with each value pooled from embedding table for each index. Optional, default is tensor of ones. **Optional.**
+
+**Outputs**:
+
+* **1**: tensor of shape ``[batch, emb_dim1, emb_dim2, ...]`` and of type *T* containing embeddings for each bag.
+
+**Types**
+
+* *T*: any numeric type.
+* *T_IND*: ``int32`` or ``int64``.
+
+**Example**
+
+.. code-block:: cpp
+
+   <layer ... type="EmbeddingBagPacked" ... >
+       <data reduction="sum"/>
+       <input>
+           <port id="0">     <!-- emb_table value is: [[-0.2, -0.6], [-0.1, -0.4], [-1.9, -1.8], [-1.,  1.5], [ 0.8, -0.7]] -->
+               <dim>5</dim>
+               <dim>2</dim>
+           </port>
+           <port id="1">     <!-- indices value is: [[0, 2], [1, 2], [3, 4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </input>
+       <output>
+           <port id="2">     <!-- output value is: [[-2.1, -2.4], [-2., -2.2], [-0.2, 0.8]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </output>
+   </layer>
+
+
+.. code-block:: cpp
+
+   <layer ... type="EmbeddingBagPacked" ... >
+       <data reduction="sum"/>
+       <input>
+           <port id="0">     <!-- emb_table value is: [[-0.2, -0.6], [-0.1, -0.4], [-1.9, -1.8], [-1.,  1.5], [ 0.8, -0.7]] -->
+               <dim>5</dim>
+               <dim>2</dim>
+           </port>
+           <port id="1">     <!-- indices value is: [[0, 2], [1, 2], [3, 4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+           <port id="2"/>    <!-- per_sample_weights value is: [[0.5, 0.5], [0.5, 0.5], [0.5, 0.5]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </input>
+       <output>
+           <port id="3">     <!-- output value is: [[-1.05, -1.2], [-1., -1.1], [-0.1, 0.4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </output>
+   </layer>
+
+.. code-block:: cpp
+
+   <layer ... type="EmbeddingBagPacked" ... >
+       <data reduction="mean"/>
+       <input>
+           <port id="0">     <!-- emb_table value is: [[-0.2, -0.6], [-0.1, -0.4], [-1.9, -1.8], [-1.,  1.5], [ 0.8, -0.7]] -->
+               <dim>5</dim>
+               <dim>2</dim>
+           </port>
+           <port id="1">     <!-- indices value is: [[0, 2], [1, 2], [3, 4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </input>
+       <output>
+           <port id="3">     <!-- output value is: [[-1.05, -1.2], [-1., -1.1], [-0.1, 0.4]] -->
+               <dim>3</dim>
+               <dim>2</dim>
+           </port>
+       </output>
+   </layer>
+

docs/articles_en/documentation/openvino-ir-format/operation-sets/operation-specs/sparse/embedding-bag-packed-sum-3.rst

@@ -14,7 +14,10 @@ EmbeddingBagPackedSum
 
 **Short description**: Computes sums of "bags" of embeddings, without instantiating the intermediate embeddings.
 
-**Detailed description**: This is the first case of the PyTorch `EmbeddingBag <https://pytorch.org/docs/stable/nn.html#embeddingbag>`__ , it has indices in the tensor of format ``[batch, indices_per_bag]``. If 3rd input is not provided, this operation is equivalent to *Gather* followed by *ReduceSum(axis=0)*. However, *EmbeddingBagPackedSum* is much more time and memory efficient than using a chain of these operations.
+**Detailed description**:
+
+Operation EmbeddingBagPackedSum is an implementation of ``torch.nn.EmbeddingBag`` in ``sum`` mode, which indices input being 2D tensor of shape ``[batch, indices_per_bag]``.
+Operation is equivalent to *ReduceSum(Multiply(Gather(emb_table, indices, axis=0), Unsqueeze(per_sample_weights, -1)), axis=1)*.
 
 **Attributes**: EmbeddingBagPackedSum operation has no attributes.