Merge remote-tracking branch 'upstream/master' into feature/snippets/mha

.ci/azure/android_arm64.yml

@@ -37,6 +37,9 @@ resources:
     name: openvinotoolkit/openvino_contrib
     ref: master
 
+variables:
+  - group: github
+
 jobs:
 - job: android_arm64
   # About 150% of total time
@@ -62,13 +65,19 @@ jobs:
     CCACHE_DIR: $(SHARE_DIR)/ccache/master/android_arm64
 
   steps:
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: '3.10'
+      addToPath: true
+      architecture: 'x64'
+      githubToken: $(auth_token)
+    displayName: Setup Python 3.10
+    name: setupPython
+
   - script: |
       curl -H Metadata:true --noproxy "*" "http://169.254.169.254/metadata/instance?api-version=2019-06-01"
       whoami
       uname -a
-      echo ls /usr/bin/python3.10
-      rm -rf /usr/bin/python3
-      sudo ln -s /usr/bin/python3.10 /usr/bin/python3
       echo Python3 info ; which python3 ; python3 --version
       echo Python info ; which python ; python --version
       echo Java info ; which java ; java -version

.ci/azure/linux_coverity.yml

@@ -6,6 +6,9 @@ resources:
     name: openvinotoolkit/openvino_contrib
     ref: master
 
+variables:
+  - group: github
+
 jobs:
 - job: Lin
   # About 150% of total time
@@ -31,13 +34,20 @@ jobs:
     CCACHE_DIR: $(SHARE_DIR)/ccache/master/linux_coverity
 
   steps:
+
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: '3.10'
+      addToPath: true
+      architecture: 'x64'
+      githubToken: $(auth_token)
+    displayName: Setup Python 3.10
+    name: setupPython
+
   - script: |
       curl -H Metadata:true --noproxy "*" "http://169.254.169.254/metadata/instance?api-version=2019-06-01"
       whoami
       uname -a
-      echo ls /usr/bin/python3.10
-      rm -rf /usr/bin/python3
-      sudo ln -s /usr/bin/python3.10 /usr/bin/python3
       echo Python3 info ; which python3 ; python3 --version
       echo Python info ; which python ; python --version
       echo Java info ; which java ; java -version

.ci/azure/mac.yml

@@ -41,6 +41,9 @@ resources:
     name: openvinotoolkit/testdata
     ref: master
 
+variables:
+  - group: github
+
 jobs:
 - job: Mac
   # About 250% of total time (perfomace of Mac hosts is unstable, 360 is max)
@@ -66,13 +69,18 @@ jobs:
     CCACHE_DIR: $(WORK_DIR)/ccache/mac
 
   steps:
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: '3.10'
+      addToPath: true
+      architecture: 'x64'
+      githubToken: $(auth_token)
+    displayName: Setup Python 3.10
+    name: setupPython
+
   - script: |
       whoami
       uname -a
-      echo test_debug ; which python3
-      echo ls /usr/bin/python3.10
-      sudo rm -rf /usr/bin/python3
-      sudo ln -s /usr/bin/python3.10 /usr/bin/python3
       echo Python3 info ; which python3 ; python3 --version
       echo Python info ; which python ; python --version
       echo Java info ; which java ; java -version

.ci/azure/windows_conditional_compilation.yml

@@ -36,6 +36,9 @@ resources:
     endpoint: openvinotoolkit
     name: openvinotoolkit/testdata
 
+variables:
+  - group: github
+
 jobs:
 - job: WinCC
   # About 150% of total time
@@ -60,6 +63,15 @@ jobs:
     SETUPVARS: $(INSTALL_DIR)\setupvars.bat
 
   steps:
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: '3.10'
+      addToPath: true
+      architecture: 'x64'
+      githubToken: $(auth_token)
+    displayName: Setup Python 3.10
+    name: setupPython
+
   - script: |
       powershell -command "Invoke-RestMethod -Headers @{\"Metadata\"=\"true\"} -Method GET -Uri http://169.254.169.254/metadata/instance/compute?api-version=2019-06-01 | format-custom"
       where python

src/bindings/python/CMakeLists.txt

@@ -21,7 +21,7 @@ endif()
 #
 
 set(ov_python_req "${OpenVINOPython_SOURCE_DIR}/requirements.txt")
-set(ie_python_req "cython>=0.29.22")
+set(ie_python_req "cython>=0.29.32")
 
 function(ov_check_python_build_conditions)
     # user explicitly specified ENABLE_PYTHON=ON

src/frontends/onnx/docs/architecture.md

@@ -2,7 +2,54 @@
 
 The class diagram below shows the structure and relations between the basic classes of ONNX Frontend:
 
-TBD - 93001
+```mermaid
+flowchart TB
+    fw_model[(ONNX)]
+    style fw_model fill:#427cb0
+
+    subgraph frontend [ov::frontend::onnx::FrontEnd]
+        direction TB
+        load_impl["load_impl"]
+        convert["convert"]
+        decode["decode"]
+        add_extension["add_extension"]
+        fe_name["get_name"]
+    end
+
+    subgraph input_model [ov::frontend::onnx::InputModel]
+        get_place["get_place_by_tensor_name"]
+        set_tensor_name["set_name_for_tensor"]
+        others["other editing capabilities..."]
+        set_pt_shape["set_partial_shape"]
+        add_output["add_output"]
+        extract_sub["extract_subgraph"]
+    end
+
+    subgraph extension [ov::Extension]
+        so["SOExtension as path to *.so/*.dll"]
+        ov::frontend::onnx::ConversionExtension
+        ov::frontend::onnx::OpExtension
+        others2["others..."]
+    end
+
+    proto([onnx/protobuf libs])
+    ov_model[ov::Model]
+    ov_model_partial[ov::Model represented via ONNXFrameworkNodes]
+    onnx_name[onnx]
+    true_false[true/false]
+
+    fw_model--as stream/as path-->load_impl
+    load_impl--ParseFromIstream-->proto
+    proto--ModelProto-->load_impl
+
+    load_impl-->input_model
+    input_model-->convert
+    input_model-->decode
+    convert-->ov_model
+    decode-->ov_model_partial
+    extension-->add_extension
+    fe_name-->onnx_name
+```
 
 ## See also
  * [OpenVINO ONNX Frontend README](../README.md)

src/frontends/onnx/docs/how_to_add_op.md

@@ -1,11 +1,105 @@
 # How to add a new operation
 
-## How to implement a new operation
+## How to implement a new operation in ONNX FE codebase
+ONNX operations ("op" or "ops" for short in this article) can be distinguished into two main categories: [the official ops defined in the ONNX standard](https://github.com/onnx/onnx/blob/main/docs/Operators.md) and the custom-domain ops (such as ops from the `org.openvinotoolkit`, `com.microsoft`, and `org.pytorch.aten` domains). Multiple operator handlers for different versions of an op can be defined. When importing a model, ONNX FE tries to use a handler that matches the version of the opset in the model. If such implementation doesn't exist, it will try to use the existing handler(s) starting with the greatest opset number. When adding a new operator's implementation, the implementation has to be registered using version `1` (according to an implementation requirement of ONNX FE), even if the operation has been added to the ONNX standard in an opset greater than 1.
 
-## How to register a custom operation via Extension mechanism
+For example, we want to implement our new `org.openvinotoolkit.CustomAdd` operation in version `1`.
+The first step is to add `.cpp` and `.hpp` files in [the ops folder](../../../../src/frontends/onnx/frontend/src/op). For this particular case, it should be [op/org.openvinotoolkit](../../../../src/frontends/onnx/frontend/src/op/org.openvinotoolkit) to be consistent with the op folder layout.
+The declaration in `.hpp` can look like:
+```cpp
+#pragma once
 
+#include "ngraph/node.hpp"
+#include "onnx_import/core/node.hpp"
 
-TBD - 93001
+namespace ngraph {
+namespace onnx_import {
+namespace op {
+namespace set_1 {
+
+OutputVector custom_add(const Node& node);
+
+}  // namespace set_1
+}  // namespace op
+}  // namespace onnx_import
+}  // namespace ngraph
+```
+The definition in `.cpp` contains an implementation of transformation from [ngraph::onnx_import::Node](../../../../src/frontends/onnx/frontend/include/onnx_import/core/node.hpp) to [ov::OutputVector](../../../../src/core/include/openvino/core/node_vector.hpp). Such implementation can look like:
+```cpp
+#include "op/org.openvinotoolkit/custom_add.hpp"
+
+#include <memory>
+
+#include "default_opset.hpp"
+#include "utils/common.hpp"
+
+namespace ngraph {
+namespace onnx_import {
+namespace op {
+namespace set_1 {
+
+OutputVector custom_add(const Node& node) {
+    const auto in1 = node.get_ng_inputs().at(0);
+    const auto in2 = node.get_ng_inputs().at(1);
+    const auto alpha = node.get_attribute_value<float>("alpha", 1);
+    const auto alpha_node =
+        std::make_shared<default_opset::Convert>(default_opset::Constant::create(element::f32, {}, {alpha}),
+                                                 in1.get_element_type());
+
+    const auto add = std::make_shared<default_opset::Add>(in1, in2);
+    return {std::make_shared<default_opset::Multiply>(add, alpha_node)};
+}
+
+}  // namespace set_1
+}  // namespace op
+}  // namespace onnx_import
+}  // namespace ngraph
+```
+The next step is to register a new op in [ops_bridge](../../../../src/frontends/onnx/frontend/src/ops_bridge.cpp). For `org.openvinotoolkit.CustomAdd`, the registration can look like:
+```cpp
+#include "op/org.openvinotoolkit/custom_add.hpp"
+...
+REGISTER_OPERATOR_WITH_DOMAIN(OPENVINO_ONNX_DOMAIN, "CustomAdd", 1, custom_add);
+```
+The minimum requirement to receive an approval during the code review is the implementation of [C++ unit tests](tests.md#C++-tests) for a new operation.
+
+
+## How to register a custom operation via extensions mechanism
+The complete tutorial about custom frontends extensions can be found in [frontend extensions](../../../../docs/Extensibility_UG/frontend_extensions.md). The section below will show you the most useful ways of adding extensions for the ONNX Frontend.
+### C++ based extensions
+To register your ONNX node-OV subgraph mapping, you can use `ConversionExtension` with syntax as below:
+```cpp
+core.add_extension(ov::frontend::onnx::ConversionExtension("org.openvinotoolkit", "CustomAdd", ov::frontend::CreatorFunction(
+                                                            [](const ov::frontend::NodeContext& context)
+                                                            {
+                                                                const auto add = std::make_shared<ov::opset9::Add>(context.get_input(0), context.get_input(1));
+                                                                return add->outputs();
+                                                            })));
+```
+If an OpenVINO Core operation provides exactly what you need (without decomposition to subgraph), `OpExtension` can be a good choice. An example of usage can look like below:
+```cpp
+core.add_extension(ov::frontend::onnx::OpExtension<ov::opset9::Add>("org.openvinotoolkit", "CustomAdd"));
+```
+If you need to register an custom operation for a [Model Optimizer](../../../../tools/mo) scenario, you should consider `SOExtension`. More details about it can be found in [Library with Extensions](../../../../docs/Extensibility_UG/Intro.md#create-a-library-with-extensions).
+### Python-based extensions
+C++ based extensions have their equivalents in Python. For `ConversionExtension`, an example of usage can look like:
+```python
+from openvino.frontend.onnx import ConversionExtension
+...
+def custom_add(node: NodeContext):
+    input_1 = node.get_input(0)
+    input_2 = node.get_input(1)
+    add = ops.add(input_1, input_2)
+    return [add.output(0)]
+
+fe.add_extension(ConversionExtension("CustomAdd", "org.openvinotoolkit", custom_add))
+```
+If you use `OpExtension`, an custom op registration can look like:
+```python
+from openvino.frontend.onnx import OpExtension
+...
+fe.add_extension(OpExtension("opset9.Add", "CustomAdd", "org.openvinotoolkit", {}, {"auto_broadcast": "numpy"}))
+```
 
 ## See also
  * [OpenVINO ONNX Frontend README](../README.md)