Implementation:Microsoft Onnxruntime Generate Artifacts

Overview

Generates all required training artifacts (training model, eval model, optimizer model, checkpoint) from a forward-only ONNX model using the onnxruntime.training.artifacts.generate_artifacts API.

Metadata

Field	Value
Implementation Name	Generate_Artifacts
Type	API Doc
Language	Python
API	onnxruntime.training.artifacts.generate_artifacts(model, requires_grad, frozen_params, loss, optimizer, artifact_directory)
Import	from onnxruntime.training import artifacts
Domain	On_Device_Training, Model_Optimization
Repository	microsoft/onnxruntime
Source Reference	docs/python/on_device_training/training_artifacts.rst:L23-40
Last Updated	2026-02-10

Description

The generate_artifacts function automates the transformation of a forward-only ONNX model into the complete set of files required for on-device training. It applies automatic differentiation to construct the backward graph, appends the specified loss function, generates the optimizer model, and serializes an initial checkpoint.

This function supports both built-in loss types (via the LossType enum) and custom loss functions (via onnxblock.Block subclasses). Similarly, optimizer types are specified through the OptimType enum.

API Signature

from onnxruntime.training import artifacts

artifacts.generate_artifacts(
    model,                # onnx.ModelProto: forward-only ONNX model
    requires_grad,        # list[str]: parameter names requiring gradients
    frozen_params,        # list[str]: parameter names to freeze
    loss,                 # LossType or Block: loss function specification
    optimizer,            # OptimType: optimizer type (e.g., AdamW)
    artifact_directory,   # str: output directory for generated files
)

Key Parameters

Parameter	Type	Description
model	onnx.ModelProto	The forward-only ONNX model loaded via onnx.load(). Must contain all parameter initializers.
requires_grad	list[str]	List of parameter names that will participate in gradient computation and be updated by the optimizer.
frozen_params	list[str]	List of parameter names that are included in the model but will not be updated during training.
loss	LossType or Block	The loss function to append to the forward graph. Built-in options include LossType.CrossEntropyLoss and LossType.MSELoss. Custom losses are created by subclassing onnxblock.Block.
optimizer	OptimType	The optimizer algorithm to use for parameter updates. Options include OptimType.AdamW.
artifact_directory	str	Directory path where the four output artifacts will be written.

I/O Contract

Direction	Type	Description
Input	onnx.ModelProto	Forward-only ONNX model with parameter initializers
Output	training_model.onnx	Training model with forward graph, loss function, and backward graph
Output	eval_model.onnx	Evaluation model with forward graph and loss function (no backward graph)
Output	optimizer_model.onnx	Optimizer model encoding parameter update rules
Output	checkpoint	Initial checkpoint with parameter values and zero-initialized optimizer states

Code Reference

From docs/python/on_device_training/training_artifacts.rst:

from onnxruntime.training import artifacts

# Load the forward only onnx model
model = onnx.load(path_to_forward_only_onnx_model)

# Generate the training artifacts
artifacts.generate_artifacts(model,
                             requires_grad = ["parameters", "needing", "gradients"],
                             frozen_params = ["parameters", "not", "needing", "gradients"],
                             loss = artifacts.LossType.CrossEntropyLoss,
                             optimizer = artifacts.OptimType.AdamW,
                             artifact_directory = path_to_output_artifact_directory)

Usage Example

Standard Usage with Built-in Loss

import onnx
from onnxruntime.training import artifacts

# Load the ONNX model exported from PyTorch
model = onnx.load("model.onnx")

# Generate training artifacts
artifacts.generate_artifacts(
    model,
    requires_grad=["fc1.weight", "fc1.bias", "fc2.weight", "fc2.bias"],
    frozen_params=["embedding.weight"],
    loss=artifacts.LossType.CrossEntropyLoss,
    optimizer=artifacts.OptimType.AdamW,
    artifact_directory="training_artifacts/",
)
# Outputs in training_artifacts/:
#   training_model.onnx
#   eval_model.onnx
#   optimizer_model.onnx
#   checkpoint

Custom Loss Function

import onnxruntime.training.onnxblock as onnxblock
from onnxruntime.training import artifacts

class WeightedAverageLoss(onnxblock.Block):
    def __init__(self):
        self._loss1 = onnxblock.loss.MSELoss()
        self._loss2 = onnxblock.loss.MSELoss()
        self._w1 = onnxblock.blocks.Constant(0.4)
        self._w2 = onnxblock.blocks.Constant(0.6)
        self._add = onnxblock.blocks.Add()
        self._mul = onnxblock.blocks.Mul()

    def build(self, loss_input_name1, loss_input_name2):
        return self._add(
            self._mul(self._w1(), self._loss1(loss_input_name1, target_name="target1")),
            self._mul(self._w2(), self._loss2(loss_input_name2, target_name="target2")),
        )

my_custom_loss = WeightedAverageLoss()

artifacts.generate_artifacts(
    model,
    requires_grad=["weight1", "bias1", "weight2", "bias2"],
    frozen_params=["weight3", "bias3"],
    loss=my_custom_loss,
    optimizer=artifacts.OptimType.AdamW,
)

Implements

Principle:Microsoft_Onnxruntime_Training_Artifact_Generation

Related Pages

• Torch Onnx Export -- Produces the forward-only ONNX model consumed by this API
• CheckpointState Load -- Loads the generated checkpoint for training
• Module Optimizer Scheduler Init -- Uses the generated artifacts to create training components