Contrib Ops

What are contrib ops?

Contrib Ops can be used to support operators that are not officially in ONNX.

Contrib ops may be removed or changed in a backwards incompatible way if and only if it has not been included in an ORT release. Once it's been in a release, it must remain for backwards compatibility. Because this incurs backwards compatibility obligations, contrib op usage should be minimized when possible.

Contrib Ops vs Custom Ops

Contrib ops and custom ops solve similar problems, and a contrib op can be considered a subgroup of custom ops. The difference is contrib ops are part of the core ONNX Runtime codebase, while custom ops are implemented and registered separately from the core ONNX Runtime build. See Add Custom Op.

When to use/implement contrib ops?

Contrib ops may be needed when an operator is new and is not yet part of the ONNX spec. It may also be needed for operator fusions or other graph optimizations for better perf.

ONNX requires that operators are implemented and validated for correctness prior to adding to the standardization spec. As such, an ORT contrib op may be eventually added to ONNX (which will require a re-registration), or in some cases an operator may never make sense to add to ONNX.

Generally, contrib ops should be aligned with an operation already available from an existing framework. Fully custom operations should not be added to contrib ops in ORT master and instead should be implemented as a custom op or registered as contrib op in a fork or branch of ORT.

Contrib ops should be added in kMSDomain, except in specialized cases as evaluated on a case-by-case basis (i.e. kMSNchwcDomain, kMSFeaturizersDomain).

Versioning for Contrib Ops

For MS domain ops, ONNX runtime MUST support backward compatibility. However, for the sake of simplicity there will be no versioning for contrib ops. All contrib ops will always remain at version 1. An existing contrib op can only be updated in a non backward compatibility breaking manner. When a bc breaking change is needed, a new contrib op should be created.

When adding a new operator, the op should use opset #1.
When updating an existing contrib op in onnxruntime, consider whether it's a bc breaking change. If so, create a new contrib op. If not, the existing op can be updated.

The following changes are considered bc breaking changes:

1. Adding/removing/renaming a required attribute.
2. Adding required inputs or outputs
3. Removing/reordering inputs or outputs.
4. Removing types supported by inputs and outputs, and changing types used by attributes.

These are not considered as bc breaking changes:

1. Clarifications of specification ambiguities to match prevailing implementation practice.
2. Adding optional attributes, inputs and or outputs.
3. Supporting new behavior even when the existing parameter signature is otherwise identical (e.g. implicitly supporting tensor broadcasting in the Mean operator).
4. Adding a new type supported by inputs and outputs.

Promoting a contrib op to official op

Once an op is added to the ONNX spec, it should be supported by the onnx domain instead of the MS domain. If the contrib op was previously included in an ORT release or was released with a production model, this contrib op should not be deleted from ms domain after promoting it to onnx domain.

For example:

1. OP-A (domain: com.microsoft) was shipped in ORT.
2. OP-A accepted in ONNX spec.
3. OP-A should be supported in domain com.microsoft for backward compatibility. The equivalent OP-A that complies with the ONNX spec should be registered in the official ONNX domain.