The OrtModelEditorApi struct provides functions to create or edit an ONNX model. More...

#include <onnxruntime_c_api.h>

Public Member Functions
OrtStatus *	CreateTensorTypeInfo (const OrtTensorTypeAndShapeInfo tensor_info, OrtTypeInfo *type_info)
	Create an OrtTypeInfo instance for a Tensor.

OrtStatus *	CreateSparseTensorTypeInfo (const OrtTensorTypeAndShapeInfo tensor_info, OrtTypeInfo *type_info)
	Create an OrtTypeInfo instance for a SparseTensor.

OrtStatus *	CreateMapTypeInfo (ONNXTensorElementDataType map_key_type, const OrtTypeInfo map_value_type, OrtTypeInfo *type_info)
	Create an OrtTypeInfo instance for a Map.

OrtStatus *	CreateSequenceTypeInfo (const OrtTypeInfo sequence_type, OrtTypeInfo *type_info)
	Create an OrtTypeInfo instance for a Sequence.

OrtStatus *	CreateOptionalTypeInfo (const OrtTypeInfo contained_type, OrtTypeInfo *type_info)
	Create an OrtTypeInfo instance for an Optional.

OrtStatus *	CreateValueInfo (const char name, const OrtTypeInfo type_info, OrtValueInfo **value_info)
	Create an OrtValueInfo for use as an OrtGraph input or output.

OrtStatus *	CreateNode (const char operator_name, const char domain_name, const char node_name, const char const input_names, size_t input_names_len, const char const output_names, size_t output_names_len, OrtOpAttr attributes, size_t attribs_len, OrtNode *node)
	Create an OrtNode to add to an OrtGraph.

OrtStatus *	CreateGraph (OrtGraph **graph)
	Create an OrtGraph.

OrtStatus *	SetGraphInputs (OrtGraph graph, OrtValueInfo *inputs, size_t inputs_len)
	Set the inputs for the OrtGraph.

OrtStatus *	SetGraphOutputs (OrtGraph graph, OrtValueInfo *outputs, size_t outputs_len)
	Set the outputs for the OrtGraph.

OrtStatus *	AddInitializerToGraph (OrtGraph graph, const char name, OrtValue *tensor, bool data_is_external)
	Add an initializer to the OrtGraph.

OrtStatus *	AddNodeToGraph (OrtGraph graph, OrtNode node)
	Add an OrtNode to an OrtGraph.

OrtStatus *	CreateModel (const char const domain_names, const int opset_versions, size_t opset_entries_len, OrtModel *model)
	Create an OrtModel.

OrtStatus *	AddGraphToModel (OrtModel model, OrtGraph graph)
	Add an OrtGraph to an OrtModel.

OrtStatus *	CreateSessionFromModel (const OrtEnv env, const OrtModel model, const OrtSessionOptions options, OrtSession *out)
	Create an OrtSession using the OrtModel.

OrtStatus *	CreateModelEditorSession (const OrtEnv env, const char model_path, const OrtSessionOptions options, OrtSession *out)
	Create an OrtSession to augment an existing model.

OrtStatus *	CreateModelEditorSessionFromArray (const OrtEnv env, const void model_data, size_t model_data_length, const OrtSessionOptions options, OrtSession *out)
	Create an OrtSession to augment an existing model.

OrtStatus *	SessionGetOpsetForDomain (const OrtSession session, const char domain, int *opset)
	Query the session for the opset version of a domain.

OrtStatus *	ApplyModelToModelEditorSession (OrtSession session, OrtModel model)
	Apply changes to augment the ONNX model in a session created using CreateModelEditorSession[FromArray].

OrtStatus *	FinalizeModelEditorSession (OrtSession session, const OrtSessionOptions options, OrtPrepackedWeightsContainer *prepacked_weights_container)
	Finalize the Model Editor session that was created using CreateModelEditorSession[FromArray].

Detailed Description

The OrtModelEditorApi struct provides functions to create or edit an ONNX model.

ORT Model Editor API

See onnxruntime/test/shared_lib/test_model_editor_api.cc for example usage.

Since: Version 1.21.

Member Function Documentation

◆ AddGraphToModel()

OrtStatus * OrtModelEditorApi::AddGraphToModel	(	OrtModel *	model,
		OrtGraph *	graph
	)

Add an OrtGraph to an OrtModel.

Add the graph to a model. This should be called once when creating a new model.

The OrtModel takes ownership of the OrtGraph and you should NOT call ReleaseOrtGraph.

Parameters

[in]	model	The OrtModel instance to update.
[in]	graph	The OrtGraph instance to add to the model.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ AddInitializerToGraph()

OrtStatus * OrtModelEditorApi::AddInitializerToGraph	(	OrtGraph *	graph,
		const char *	name,
		OrtValue *	tensor,
		bool	data_is_external
	)

Add an initializer to the OrtGraph.

ORT will take ownership of the OrtValue and you should NOT call ReleaseOrtValue.

Two options:

Allocated memory: Use CreateTensorAsOrtValue (allocates memory) and populate the tensor with the data. Set data_is_external to false.

Pre-existing memory: Use CreateTensorWithDataAsOrtValue or CreateTensorWithDataAndDeleterAsOrtValue to create an OrtValue with a tensor that contains a pointer to the existing data. Set data_is_external to true.

The pointer must remain valid for the duration of the inference session. If using CreateTensorWithDataAsOrtValue you are responsible for freeing the memory after the inference session is released. If using CreateTensorWithDataAndDeleterAsOrtValue, ORT will free the memory using the provided deleter as soon as the OrtValue is no longer in use.

NOTE: A tensor containing pre-existing memory MUST have 128 bytes of data or more. For smaller tensors use CreateTensorAsOrtValue.

ONNX shape inferencing does not support external data. An initializer involved in shape inferencing is typically small (a single value or limited by the rank of a tensor) and uses less than 128 bytes of memory, so this limit acts as a simple catch-all rule to avoid issues. e.g. Reshape's shape, Clip's min and max, various ops axes.

Parameters

[in]	graph	The OrtGraph instance to update.
[in]	name	The value name for the initializer.
[in]	tensor	The OrtValue instance containing the tensor data.
[in]	data_is_external	Set to true if the data is external and should not be copied.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ AddNodeToGraph()

OrtStatus * OrtModelEditorApi::AddNodeToGraph	(	OrtGraph *	graph,
		OrtNode *	node
	)

Add an OrtNode to an OrtGraph.

Add the node to the graph. The OrtGraph will take ownership of OrtNode and you should NOT call ReleaseOrtNode.

Parameters

[in]	graph	The OrtGraph instance to update.
[in]	node	The OrtNode instance to add to the graph.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ ApplyModelToModelEditorSession()

OrtStatus * OrtModelEditorApi::ApplyModelToModelEditorSession	(	OrtSession *	session,
		OrtModel *	model
	)

Apply changes to augment the ONNX model in a session created using CreateModelEditorSession[FromArray].

Adds new nodes and updates graph inputs/outputs using model to augment the original ONNX model in the session. All changes will be validated. Call FinalizeModelEditorSession to prepare the session for inferencing.

Existing input/outputs will only be updated if the OrtGraph inputs/outputs are set in the OrtModel. i.e. you don't need to call SetGraphInputs/SetGraphOutputs if they are unchanged.

ReleaseOrtModel must be called to free the OrtModel after it is applied to the session.

Parameters

[in]	session	OrtSession to update. Session must have been created using CreateModelEditorSession[FromArray].
[in]	model	OrtModel containing new nodes, new initializers, and updated graph input and/or output info.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateGraph()

OrtStatus * OrtModelEditorApi::CreateGraph ( OrtGraph ** graph )

Create an OrtGraph.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateMapTypeInfo()

OrtStatus * OrtModelEditorApi::CreateMapTypeInfo	(	ONNXTensorElementDataType	map_key_type,
		const OrtTypeInfo *	map_value_type,
		OrtTypeInfo **	type_info
	)

Create an OrtTypeInfo instance for a Map.

Create an OrtTypeInfo instance for a Map to use as graph inputs/outputs with the Model Editor API.

User can release map_value_type after creating the OrtTypeInfo.

Parameters

[in]	map_key_type	Key type for the map.
[in]	map_value_type	Value type for the map.
[out]	type_info	TypeInfo instance for the map.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateModel()

OrtStatus * OrtModelEditorApi::CreateModel	(	const char const	domain_names,
		const int *	opset_versions,
		size_t	opset_entries_len,
		OrtModel **	model
	)

Create an OrtModel.

This can be used to build a new model, or to augment an existing model.

Parameters

[in]	domain_names	The domain names for the model. If augmenting an existing model add additional domains if needed.
[in]	opset_versions	The opset versions for the model. If augmenting an existing model add additional opset versions if needed.
[in]	opset_entries_len	The number of domain_names and opset_versions entries. Domain and opset entries should be 1:1
[out]	model	The OrtModel instance.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateModelEditorSession()

OrtStatus * OrtModelEditorApi::CreateModelEditorSession	(	const OrtEnv *	env,
		const char *	model_path,
		const OrtSessionOptions *	options,
		OrtSession **	out
	)

Create an OrtSession to augment an existing model.

Create an OrtSession with an existing model that will be augmented with additional nodes and initializers. Nodes can be added before or after the existing nodes in the model. ONNX Runtime will connect the nodes when the model is finalized.

To add nodes and initializers to the existing model, first create an OrtModel using CreateModel. Add nodes and initializers to the OrtModel using AddNodeToGraph and AddInitializerToGraph. Graph inputs/outputs should be updated with SetGraphInputs and SetGraphOutputs as needed to reflect changes made by the new nodes. The list of graph inputs/outputs should be for the overall model and not just the new nodes.

Add the new information from the OrtModel to the original model using ApplyModelToSession, and prepare the session for inferencing by calling FinalizeModelEditorSession.

Parameters

env	The OrtEnv instance.
model_path	The path to the existing ONNX model to augment.
options	The OrtSessionOptions instance.
out	The created OrtSession instance. Returns If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateModelEditorSessionFromArray()

OrtStatus * OrtModelEditorApi::CreateModelEditorSessionFromArray	(	const OrtEnv *	env,
		const void *	model_data,
		size_t	model_data_length,
		const OrtSessionOptions *	options,
		OrtSession **	out
	)

Create an OrtSession to augment an existing model.

Create an OrtSession with an existing model that will be augmented with additional nodes and initializers. Nodes can be added before or after the existing nodes in the model. ONNX Runtime will connect the nodes when the model is finalized.

To add nodes and initializers to the existing model, first create an OrtModel using CreateModel. Add nodes and initializers to the OrtModel using AddNodeToGraph and AddInitializerToGraph. Graph inputs/outputs should be updated with SetGraphInputs and SetGraphOutputs as needed to reflect changes made by the new nodes. The list of graph inputs/outputs should be for the overall model and not just the new nodes.

Add the new information from the OrtModel to the original model using ApplyModelToSession, and prepare the session for inferencing by calling FinalizeModelEditorSession.

Parameters

env	The OrtEnv instance.
model_data	The model data for the existing model to augment.
model_data_length	The length of the model data.
options	The OrtSessionOptions instance.
out	The created OrtSession instance.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateNode()

OrtStatus * OrtModelEditorApi::CreateNode	(	const char *	operator_name,
		const char *	domain_name,
		const char *	node_name,
		const char const	input_names,
		size_t	input_names_len,
		const char const	output_names,
		size_t	output_names_len,
		OrtOpAttr **	attributes,
		size_t	attribs_len,
		OrtNode **	node
	)

Create an OrtNode to add to an OrtGraph.

Create an OrtNode.

Create attributes with CreateOpAttr. OrtOpAttr instances are copied.

Parameters

[in]	operator_name	The name of the operator.
[in]	domain_name	The domain of the operator. Use an empty string for ONNX operators.
[in]	node_name	The name of the node.
[in]	input_names	The names of the inputs.
[in]	input_names_len	The number of input names.
[in]	output_names	The names of the outputs.
[in]	output_names_len	The number of output names.
[in]	attributes	The optional attributes of the node.
[in]	attribs_len	The number of attributes. May be zero.
[out]	node	The OrtNode instance.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateOptionalTypeInfo()

OrtStatus * OrtModelEditorApi::CreateOptionalTypeInfo	(	const OrtTypeInfo *	contained_type,
		OrtTypeInfo **	type_info
	)

Create an OrtTypeInfo instance for an Optional.

Create an OrtTypeInfo instance for an Optional to use as graph inputs/outputs with the Model Editor API.

User can release contained_type after creating the OrtTypeInfo.

Parameters

[in]	contained_type	Tensor type and shape information.
[out]	type_info	TypeInfo instance for the tensor.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateSequenceTypeInfo()

OrtStatus * OrtModelEditorApi::CreateSequenceTypeInfo	(	const OrtTypeInfo *	sequence_type,
		OrtTypeInfo **	type_info
	)

Create an OrtTypeInfo instance for a Sequence.

Create an OrtTypeInfo instance for a Sequence to use as graph inputs/outputs with the Model Editor API.

User can release sequence_type after creating the OrtTypeInfo.

Parameters

[in]	sequence_type	Sequence type and shape information.
[out]	type_info	TypeInfo instance for the sequence.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateSessionFromModel()

OrtStatus * OrtModelEditorApi::CreateSessionFromModel	(	const OrtEnv *	env,
		const OrtModel *	model,
		const OrtSessionOptions *	options,
		OrtSession **	out
	)

Create an OrtSession using the OrtModel.

Create an inference session using the OrtModel instance. The OrtModel should have been populated with an OrtGraph containing nodes and initializers, and SetGraphInputs and SetGraphOutputs must have been called. This will validate the model, run optimizers, and prepare the session for inferencing.

ReleaseOrtModel must be called to free the OrtModel after session creation.

Parameters

[in]	env	The OrtEnv instance.
[in]	model	The OrtModel instance.
[in]	options	The OrtSessionOptions instance.
[out]	out	The OrtSession instance.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateSparseTensorTypeInfo()

OrtStatus * OrtModelEditorApi::CreateSparseTensorTypeInfo	(	const OrtTensorTypeAndShapeInfo *	tensor_info,
		OrtTypeInfo **	type_info
	)

Create an OrtTypeInfo instance for a SparseTensor.

Create an OrtTypeInfo instance for a SparseTensor to use as graph inputs/outputs with the Model Editor API.

User can release tensor_info after creating the OrtTypeInfo.

Parameters

[in]	tensor_info	SparseTensor type and shape information.
[out]	type_info	TypeInfo instance for the tensor.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateTensorTypeInfo()

OrtStatus * OrtModelEditorApi::CreateTensorTypeInfo	(	const OrtTensorTypeAndShapeInfo *	tensor_info,
		OrtTypeInfo **	type_info
	)

Create an OrtTypeInfo instance for a Tensor.

Create an OrtTypeInfo instance for a Tensor to use as graph inputs/outputs with the Model Editor API.

User can release tensor_info after creating the OrtTypeInfo.

Parameters

[in]	tensor_info	Tensor type and shape information.
[out]	type_info	TypeInfo instance for the tensor.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ CreateValueInfo()

OrtStatus * OrtModelEditorApi::CreateValueInfo	(	const char *	name,
		const OrtTypeInfo *	type_info,
		OrtValueInfo **	value_info
	)

Create an OrtValueInfo for use as an OrtGraph input or output.

Parameters

[in]	name	The name of the input or output.
[in]	type_info	The type information for the input or output. The provided value is copied.
[out]	value_info	The OrtValueInfo instance.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ FinalizeModelEditorSession()

OrtStatus * OrtModelEditorApi::FinalizeModelEditorSession	(	OrtSession *	session,
		const OrtSessionOptions *	options,
		OrtPrepackedWeightsContainer *	prepacked_weights_container
	)

Finalize the Model Editor session that was created using CreateModelEditorSession[FromArray].

Finalize the Model Editor session that augmented an ONNX model by adding new nodes. This will run optimizers and prepare the session for inferencing.

Parameters

[in]	session	OrtSession to finalize. Session must have been created using CreateModelEditorSession[FromArray].
[in]	options	OrtSessionOptions to use for the session.
[in]	prepacked_weights_container	Optional OrtPrepackedWeightsContainer to use for the session. Set to nullptr if not used. Returns If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ SessionGetOpsetForDomain()

OrtStatus * OrtModelEditorApi::SessionGetOpsetForDomain	(	const OrtSession *	session,
		const char *	domain,
		int *	opset
	)

Query the session for the opset version of a domain.

When using the Model Editor API to augment a model, any new nodes must conform to the opset version of the original model. To do that the user must be able to discover that opset version. Returns an error if the domain is not used in the model.

Parameters

[in]	session	OrtSession to query
[in]	domain	Domain to query. The ONNX domain is an empty string.
[out]	opset	The opset version of the domain.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ SetGraphInputs()

OrtStatus * OrtModelEditorApi::SetGraphInputs	(	OrtGraph *	graph,
		OrtValueInfo **	inputs,
		size_t	inputs_len
	)

Set the inputs for the OrtGraph.

Set the graph inputs. This will replace any existing inputs with the new values. The OrtGraph takes ownership of the OrtValueInfo instances and you should NOT call ReleaseOrtValueInfo.

Parameters

[in]	graph	The OrtGraph instance to update.
[in]	inputs	The input OrtValueInfo instances.
[in]	inputs_len	The number of input OrtValueInfo instances.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

◆ SetGraphOutputs()

OrtStatus * OrtModelEditorApi::SetGraphOutputs	(	OrtGraph *	graph,
		OrtValueInfo **	outputs,
		size_t	outputs_len
	)

Set the outputs for the OrtGraph.

Set the graph outputs. This will replace any existing outputs with the new values. The OrtGraph takes ownership of the OrtValueInfo instances provided and you should NOT call ReleaseOrtValueInfo.

Parameters

[in]	graph	The OrtGraph instance to update.
[in]	outputs	The output OrtValueInfo instances.
[in]	outputs_len	The number of output OrtValueInfo instances.

Returns: If no error, nullptr will be returned. If there is an error, a pointer to an OrtStatus that contains error details will be returned. Use OrtApi::ReleaseStatus to free this pointer.

Since: Version 1.21.

Public Member Functions

Detailed Description

Member Function Documentation

◆ AddGraphToModel()

◆ AddInitializerToGraph()

◆ AddNodeToGraph()

◆ ApplyModelToModelEditorSession()

◆ CreateGraph()

◆ CreateMapTypeInfo()

◆ CreateModel()

◆ CreateModelEditorSession()

◆ CreateModelEditorSessionFromArray()

◆ CreateNode()

◆ CreateOptionalTypeInfo()

◆ CreateSequenceTypeInfo()

◆ CreateSessionFromModel()

◆ CreateSparseTensorTypeInfo()

◆ CreateTensorTypeInfo()

◆ CreateValueInfo()

◆ FinalizeModelEditorSession()

◆ SessionGetOpsetForDomain()

◆ SetGraphInputs()

◆ SetGraphOutputs()