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.
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 aDeployment
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.
- An
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 freshpip
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
.
- 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:
- 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 thedeployment
file.
- 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
- 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).
- You could output the dataframe as a list of dictionaries using the Pandas
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.