Deployment package structure¶

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

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

Deploying to UbiOps

Templates available on GitHub

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

Deployment package structure¶

The structure of the package is similar for every language:

A deployment file that contains code which instructs UbiOps how to initialize and use your deployment 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 deployment artifacts and attributes. For instance a model parameter file or pickle file.
(optional) A directory libraries where you can include dependencies that your deployment uses. This directory is added to the system $PATH variable, such that its contents can be easily imported.

Each deployment package should be uploaded as a ZIP archive. This ZIP can have any name. The ZIP must contain a directory, which can have any name, in the root of the ZIP. If your ZIP contains multiple directories, it will look for a directory called deployment_package. The directory then contains all deployment files. we will refer to this directory as the deployment package directory.

Deployment template structure¶

The Python code for a deployment 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 deployments, the deployment package directory is required to contain:

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

In addition, the deployment package directory can contain the following:

requirements.txt - A list of Python packages required for the deployment. UbiOps will install the packages defined in this file for you using a fresh pip virtual environment once you upload your deployment. 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 deployment package directory.

The maximum size for a deployment package is 1 gigabyte.

Deployment input and output types¶

When creating a new deployment, a user defines what data the deployment 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 key value pairs with an associated data type (integer, string, double, boolean, array of integers, array of doubles, array of strings or a file (see 'blob')).
Plain: Any string without structure.

You can use different data types for input and output, for example a deployment with structured input and plain output, or vice-versa.

Input¶

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 deployment.

When using a structured input, the data attribute will contain a dictionary.
- When sending a file (a structured field of type 'blob'), the value will contain the absolute path where the deployment 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 a path: .../input.csv.
For a plain input the data will contain the plain text string as input.

Output¶

The request method is expected to return output in the format you defined when setting up the deployment. 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 request. You can easily create the absolute path using the 'base_directory' passed in the __init__ method of the deployment 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'). Note that if you use this approach in a pipeline, each Pandas row (dictionary) will be treated as individual request for the next deployment in the pipeline.
  - 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 absolute file path (use the base_directory passed in the __init__ method).

Testing your deployment¶

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

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