Preparing a Model Artifact

After a model is trained, you must create a model artifact to save with the model in a model catalog.

This creates centralized storage of model artifacts and enables you to track model metadata.

A model artifact is a zip archive of the files necessary to deploy the model as a model deployment or load it back in a notebook session.

We've provided various model catalog examples that include model artifacts for various machine learning frameworks and model formats. We've examples for ONNX , Scikit-learn, Keras, PyTorch, LightGBM, and XGBoost models. Get started by obtaining our model artifact template, which includes these files:

File Description Contains your custom logic for loading serialized model objects to memory, and define an inference endpoint (predict()).
runtime.yaml Provides instructions about which conda environment to use when deploying the model using a Data Science model deployment. Gives you a series of step-by-step instructions to prepare and save a model artifact to the model catalog. We highly recommend that you follow these steps.
artifact-introspection-test/requirements.txt Lists the third-party dependencies that you must install in your local environment before running introspection tests.
artifact-introspection-test/ Provides an optional series of test definitions that you can run on your model artifact before saving it to the model catalog. These model introspection tests capture many of the most common errors when preparing a model artifact.

The model artifact directory structure must match this example:

|-- runtime.yaml

More Python modules that are imported in We recommend any code used for inference be zipped at the same level as or any level under the file. If any required files are present at folder levels preceding the file, then the files are ignored and could result in deployment failure.

The File

This file contains the function definitions that are necessary to load a model to memory and make predictions.

The two functions are called, load_model() and predict(). The function parameters are not customizable. For example, you can define data transformations in predict() before calling the inference method of the estimator object. You can load more than one estimator object to memory and perform an ensemble evaluation. The predict() function is behind the /predict endpoint of a model deployment. Ensure that the data type of the data parameter in predict() matches the payload format you expect with model deployment.


Model deployment only supports JSON payload and bytes. Ensure that the data parameter in predict() is a JSON blob or bytes.

ADS (oracle-ads) provides model registration framework specific classes. For example, if the SklearnModel class is used with .prepare(), by default ADS serializes the model to joblib. When XgboostModel is used, by default .prepare() saves the model to a JSON file.

This template uses the load_model() to return the model estimator object. The predict() function takes in data and the model object returned by the load_model(). Both functions are customizable and require definitions. The body of predict() can include data transformations and other data manipulation tasks before a model prediction is made. Any custom Python modules can be imported in if they're available in the artifact file or as part of the conda environment used for inference purposes such as the template.


You can define other helper functions in that are invoked in predict(). For example, you could define a data_transformation() function that defines custom transformations.

Review the Best Practices for Model Artifacts to help you effectively create these files.

We've provided various model catalog examples and templates including the files. We've examples for ONNX , scikit-learn, Keras, PyTorch, LightGBM, and XGBoost models. Template

    This boilerplate is based on a n sklearn model serialized with cloudpickle.
import json
import os
from cloudpickle import cloudpickle

    Replace with your own model object and your own serialization library (e.g. pickle, onnx, etc).
model_name = 'model.pkl'

   Inference script. This script is used for prediction by scoring server when schema is known.

def load_model(model_file_name=model_name):
    Loads model from the serialized format
    model:  a model instance on which predict API can be invoked
    model_dir = os.path.dirname(os.path.realpath(__file__))
    contents = os.listdir(model_dir)
    if model_file_name in contents:
        with open(os.path.join(os.path.dirname(os.path.realpath(__file__)), model_file_name), "rb") as file:
            return cloudpickle.load(file)
        raise Exception('{0} is not found in model directory {1}'.format(model_file_name, model_dir))

def predict(data, model=load_model()):
    Returns prediction given the model and data to predict
    model: Model instance returned by load_model API
    data: Data format as expected by the predict API of the core estimator. For eg. in case of sckit models it could be numpy array/List of list/Panda DataFrame
    predictions: Output from scoring server
        Format: {'prediction':output from model.predict method}
    from pandas import read_json, DataFrame
    from io import StringIO
    data = read_json(StringIO(data)) if isinstance(data, str) else DataFrame.from_dict(data)
    pred = model.predict(data).tolist()
    return {'prediction': pred}

Oracle ADS (oracle-ads) provides model registration framework specific classes that take a model and pushes it to production in a few quick steps. Use the .prepare() method to create model artifacts. The file is created and customized to a model class.