Dutch Analytics - Xenia documentation

Command Line Interface

UbiOps offers a Command Line Interface (CLI) to interact with the UbiOps API. You can find more information about the CLI on Github.

Installation

The ubiops command line interface is available on PyPi and can be installed using PIP:

pip install ubiops-cli

To check the version of your installation, use:

ubiops --version

If you need help while using the UbiOps CLI, please use the -h or --help option.

ubiops --help

Authentication

Sign in to UbiOps via the CLI. If you want to use a service user token (api token) to sign in, please add the --token option.

# to authenticate with email and password:
ubiops signin

# to authenticate with a service user token:
ubiops signin --token

You will be prompted to fill in your credentials (email + password, or API token if you used the --token option). If you use your email and password to authenticate, a temporary access token is generated in the background, which provides you access for 3 hours.

It's also possible to provide your email and password directly using the --email and --password options. If you are using the --token option, you can use the --password option to provide your API token. Specify your token in the format Token <YOUR_API_KEY>.

To check if you are authorized, use:

ubiops status

If you use your email and password to authenticate, your email will automatically be stored as default user. To check the current user, use:

ubiops user get

To sign out, use:

ubiops signout

Default project

To manage your resources, you need the name of your project. By default, the first project name is selected. To show the current project, use:

ubiops current_project get

To list all your projects, use:

ubiops projects list

To set PROJECT_NAME as your current project, use:

ubiops current_project set PROJECT_NAME

Quickstart

The first step is to download a prepared model. You can do this by either clicking on the link, or using a curl command in your terminal.

curl -X GET https://storage.googleapis.com/ubiops/example-model-packages/example_model_package.zip -o example_model_package.zip

To list your models in your project, use:

ubiops models list

Create model

The next step is to create the structure of the prepared model in your project. The model parameters can be specified using a yaml file. Use either the echo shell command below to create the yaml file, or save the content in the second tab below in a file named example_model.yaml.

echo "model_name: example
model_description: UbiOps CLI tutorial.
input_type: structured
input_fields:
  - name: input
    data_type: double
output_type: structured
output_fields:
  - name: output
    data_type: double" > example_model.yaml
model_name: example
model_description: UbiOps CLI tutorial.
input_type: structured
input_fields:
  - name: input
    data_type: double
output_type: structured
output_fields:
  - name: output
    data_type: double

Click here for more information about the possible model parameters.

Create the model:

ubiops models create -f example_model.yaml

📘

Duplicating models

If you want to overwrite the model name in the yaml file upon model creation, you can easily do so by adding a model name (.e.g example-duplicate) as argument. This is especially useful if you want to duplicate a model:

ubiops models create -f example_model.yaml example-duplicate

Deploy

The next step is to deploy the code. Code can be deployed using two different approaches: a step-by-step approach in which you zip your code, create a new model version, and upload the zip, and a second approach which does these steps all together.

Step-by-step approach

  1. The first step is zipping your code directory (CODE_DIRECTORY). Since the zip of this example was already provided, this step could be skipped.

An ignore file (.ubiops-ignore) could be used to specify files and directories in the code directory that should be excluded in the zip. The structure of the ignore file is assumed to be similar to the well-known .gitignore file.

ubiops models package -d CODE_DIRECTORY
  1. The second step is creating a model version. The parameters of the version can both be specified by a yaml file or command options. In this tutorial, a yaml file will be used. Use either the echo shell command below to create the yaml file, or save the content in the second tab below in a file named example_model_version.yaml.
echo "version_name: v1
model_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800" > example_model_version.yaml
version_name: v1
model_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800

Create the model version:

ubiops model_versions create -f example_model_version.yaml
  1. The last step of the step-by-step deployment is uploading the zip to model example version v1.
ubiops models upload example -v v1 -z example_model_package.zip

Single-command approach

To use the single-command approach, the downloaded zip should be unzipped first, as the command expects a directory instead of a zip. After unzipping example_model_package.zip, the code directory can be found as model_package or example_model_package/model_package, depending on how you unzip. The root of this code directory contains a model.py which is used by UbiOps as entry point of your code. Click here for more information about the model code structure.

If you did not specify example_model_version.yaml yet, please use the echo shell command below or copy the content of the second tab in a yaml file called example_model_version.yaml.

echo "version_name: v1
model_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800" > example_model_version.yaml
version_name: v1
model_name: example
language: python3.7
memory_allocation: 256
minimum_instances: 0
maximum_instances: 1
maximum_idle_time: 1800

Deploy the code in model_package (or example_model_package/model_package) to a new model version v2 of model example:

ubiops models deploy example -v v2 -d model_package/ -f example_model_version.yaml

If you would like to store a local copy of the created and uploaded zip, please use the --output_path (or -o) option.

List model versions

To list all deployed versions of the example model, use:

ubiops model_versions list -m example

When your model version is available we can create model requests.

Creating requests

# Replace MODEL_NAME, VERSION_NAME and the input data for your own application.
ubiops models requests create MODEL_NAME -v VERSION_NAME --data "{\"input_param_1\": \"input_value_1\", \"input_param_2\": \"input_value_2\"}"
# Replace MODEL_NAME, VERSION_NAME and the input data for your own application.
ubiops models requests create MODEL_NAME -v VERSION_NAME --data "plain input"

If you would like to pass an input file (INPUT_FILE) to your model, use:

ubiops blobs create -f INPUT_FILE

and use the returned blob ID in the input data of the request.


The example model in this tutorial multiplies the input float input by a random number and returns it as output. To create a request input=100 to version v1, use:

ubiops models request example -v v1 --data "{\"input\": 100}"

When the request is finished, you will see the output of the model.

If you would like to create one or more requests without waiting for the result, you could use batch_requests, which returns the IDs of the requests, which you can use to get the results later.

For example, create 3 requests:

ubiops models batch_requests create example -v v1 --data "{\"input\": 1}" --data "{\"input\": 2}" --data "{\"input\": 3}"

and collect the results by using the returned IDs (ID1, ID2 and ID3):

ubiops models batch_requests get example -v v1 -id "ID1" -id "ID2" -id "ID3"

Clean up

You can delete version v1 of model example using:

ubiops model_versions delete v1 -m example

You will be prompted for confirmation. Press 'y' to confirm. You could also add the -y option.

You can delete the whole model (and all its versions) using:

ubiops models delete example

You will be prompted for confirmation. Press 'y' to confirm. You could also add the -y option.

Updated 4 days ago

Command Line Interface


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.