Skip to content

Model package structure

Your model code needs to be packaged in a defined structure for the UbiOps platform to run it.

The packaged model is a zip file containing a number of required files and directories. This page specifies in what structure UbiOps expects your model file.

Deploying a model into UbiOps


Template structures are available for the supported programming languages on our Github. You can download an example model package .zip here: Download Example Model Package zip

Model package structure

The structure of the package is similar for every language:

  • A model file that contains code which instructs UbiOps how to initialize and use your model for inference.
  • (optional) Files containing package and library requirements that are installed and managed by UbiOps, for example requirements.txt for Python.
  • (optional) Files containing model artifacts and attributes. For instance a model parameter file or pickle file.
  • (optional) A directory libraries where you can include dependencies that your model uses. This directory is added to the system $PATH variable, such that its contents can be easily imported.

Each model package should be uploaded as a ZIP archive. This ZIP can have any name, but it must contain a directory called model_package in the root of the ZIP. Therefore, when this ZIP is extracted, it should result in a model_package directory which then contains all model files.

Model template structure

The Python code for a model has a few requirements as well in terms of structure. UbiOps supports Python 3.5+. All of these languages use the same Python template, that can be found in our Github.


For Python models, the model_package directory is required to contain:

  • - Main script for the model. It should include a Model class containing:
    • An __init__ method used for initialization and loading data which can be re-used between model requests. This method is called every time the model becomes active in UbiOps.
    • A request method that contains the main logic which is called at each model request.

In addition, the model_package can contain the following:

  • requirements.txt - A list of Python packages required for the model. UbiOps will install the packages defined in this file for you using a fresh pip virtual environment once you upload your model. After this build step the dependencies are fixed and won't change.
  • libraries/ - directory where packages and system libraries are installed. This directory is added to the system $PATH variable.
  • Any custom files in any location of the package.

The maximum size for a model package is 1 gigabyte.

Model input and output types

When creating a new model, a user defines what data the model expects when making a request, and what data it returns. UbiOps supports two types of data input and output:

  • Structured: Structured data consists of a dictionary with one or more fields (key value pairs) with an associated data type (integer, string, double, boolean, array of integers, array of doubles, array of strings or file ('blob')).
  • Plain: Any string without structure.

Combinations between input and output types are supported, for example a model with structured input and plain output, or vice-versa.


The request method has an attribute called data. This attribute will contain the data that is used as an input into the instance of the model.

  • When using a structured input, the data attribute will contain a dictionary.
    • If a structured field is of type file ('blob'), the value will contain the absolute path where the model can access the file. For example, if you create a request with the file 'input.csv' as one of the input fields, the value will be: /home/model/blobs/.../input.csv.
  • For a plain input the data will contain the plain text string as input.


The request method is expected to return output in the format you defined when setting up the model. It is required that the output is JSON serializable.

  • When using a structured output, the returned value should be a JSON serializable dictionary (single), or a list of these JSON serializable dictionaries (plural).
    • If a structured field is of type file ('blob'), the value for this key should contain the absolute path where the output file is stored. UbiOps will then collect this file and process it as an output of your model request. You can easily create the absolute path using the 'base_directory' passed in the __init__ method of the model file.
  • In case of plain output, the returned parameter should be a string.

Numpy and Pandas objects are not JSON serializable

Numpy and Pandas objects are not JSON serializable, therefore they need to be cast before returning them in structured output.

  • For Numpy array's, you could use the Numpy tolist method: ndarray.tolist()
  • For Numpy float's you could use the Python build-in float method: float(npfloat)
  • For Pandas DataFrames:

    • You could output the dataframe as a list of dictionaries using the Pandas to_json method : df.to_json(orient='records'). This approach is particularly useful when you want to insert multiple rows to a connector at once.
      • You could output each column as an array of integers/doubles/strings depending on the content of the column.
      • You could store the data in a CSV file and return the file path.

Testing your model

The model template in our Github project contains an example script to test whether your model is working correctly within our model wrapper.

Edit and execute the file according to your model to simulate the UbiOps back-end that initializes the model and makes a request. Please do not include these testing scripts in your model package.