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 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
score.py 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.
README.md 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/model_artifact_validate.py 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
|-- score.py
|--<your-serialized-model>
|--<your-custom-module.py>
Important

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

The score.py 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.

Important

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.

The score.py 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 score.py if they're available in the artifact file or as part of the conda environment used for inference purposes such as the template.

Tip

You can define other helper functions in score.py 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 score.py files. We've examples for ONNX , scikit-learn, Keras, PyTorch, LightGBM, and XGBoost models.