Dutch Analytics - Xenia documentation

📘

Currently, the CLI is only available for API version v1.1. However, because v2.1 has a compatibility layer for v1.1 it is still possible to use the CLI for models running on v2.1

Xenia also offers a CLI that has the same functionality (and even more!) as the Xenia user interface. This is very handy, for example, if you want to deploy your model directly from the command line. You can find more information on the CLI on Github

Installation

Install the Xenia CLI using PIP.

# pip version >= 18.1
pip install git+https://github.com/DutchAnalytics/xenia-cli.git

# pip version < 18.1
pip install git+https://github.com/DutchAnalytics/xenia-cli.git --process-dependency-links

To check the version of your installation, use:

xenia --version

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

xenia --help

Authentication

Sign in to Xenia 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:
xenia signin

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

You will be asked for the API endpoint you want to use. The default API endpoint is the latest compatible version of the API. Press enter to use the default.
Then 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.

To check if you are authorized, use:

xenia 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:

xenia user

To sign out, use:

xenia signout

Default project

To manage your resources, you need the name of your project. Since we don't want to provide this as input for every command, we would like to set a 'current' project.

To list your projects, use:

xenia projects list

To set PROJECT_NAME as your current project, use:

xenia projects current --set PROJECT_NAME

To show your current project, use:

enia projects current

If you list your projects again, you will see the same pointer in the 'CURRENT' column.

xenia projects list

The current project is an example of a configuration. To list all your configurations, use:

xenia config list

You will find your default project in the configuration default.project. You can manage your configurations via get, set and remove, for example;

# get default project
xenia config get default.project

# set PROJECT_NAME as default project
xenia config set default.project PROJECT_NAME

MNIST tutorial

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

curl -X GET https://storage.googleapis.com/da-xenia/example-model-package/1.jpg -o 1.jpg
curl -X GET https://storage.googleapis.com/da-xenia/example-model-package/mnist_model_package.zip -o mnist_model_package.zip

Unzip the mnist_model_package.zip.

To list your models in your project, use:

xenia models list

If you got an error that says "Error: Missing option '-p' / '--project_name'", please set a current project as described above, or provide the project name (e.g. PROJECT_NAME) as option:

xenia models list -p PROJECT_NAME

For all commands below, we assume you have a current project. If this is not the case, you can always use the '-p' or '--project_name' option. If you have a current project set, but you want to use a different project for your command, you can do so using the '-p' or '--project_name' option too.

Deploy model

The next step is to create the MNIST model in your project. The model parameters can be specified using a yaml file:

echo "model_name: mnist
model_description: Xenia CLI mnist tutorial.
input_type: blob
output_type: structured
output_fields:
  - name: prediction
    data_type: int
  - name: probability
    data_type: double" > mnist.yaml
xenia models create -f mnist.yaml

Click here for more information about the possible model parameters.

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 mnist-duplicate) as argument. This is especially useful if you want to duplicate a model:

xenia models create -f mnist.yaml mnist-duplicate

The next step is to deploy the model code. You can find the MNIST code by unzipping the mnist_model_package.zip. This results in a directory model_package, which includes a model.py. Click here for more information about the model code structure.

The configurations of the deployment (e.g. programming language, memory allocation and unused shutdown time) can either be provided by a yaml file, or via command options. Please, use the '-h' or '--help' option for more information.

The 'deploy' functionality of the Xenia CLI automatically zips your code for you, so you only need to provide the directory of your code you want to zip, which must contain the model.py file in its root. The generated zip file will be stored in the location specified by the '-o' or '--output_path' option, or in the current directory if not specified. If you don't want to store the generated zip file, please use the '--no_zip' option.

echo "language: python3.6
memory_allocation: 2048" > mnist_v1.yaml
xenia models deploy mnist -v v1 -d model_package/ -f mnist_v1.yaml --no_zip

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

xenia models versions list mnist

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

Creating requests

How to create a request depends on the input type of your model.

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

For the MNIST model, we can create a request to classify the digit in the example image (1.jpg):

xenia models blob-requests create mnist -v v1 -f 1.jpg

This will return a request_id which can be used to collect the results of the request later.

Collecting request results

How to collect the results depends on the output type of your model.

# Replace MODEL_NAME, VERSION_NAME and REQUEST_ID for your own application.
xenia models requests get MODEL_NAME -v VERSION_NAME REQUEST_ID
# Replace MODEL_NAME, VERSION_NAME, REQUEST_ID and OUTPUT_LOCATION for your own application.
xenia models blob-requests get MODEL_NAME -v VERSION_NAME -o OUTPUT_LOCATION REQUEST_ID

The MNIST model has a structured output type. Therefore, the results of the created request can be obtained as follows. Please, replace REQUEST_ID with the request_id you retrieved upon creation.

# Replace REQUEST_ID with the request_id obtained earlier.
xenia models requests get mnist -v v1 REQUEST_ID

When the request is finished, you will see that the digit in the image is classified as a 2 (see 'result').

Clean up

You can delete the model version using:

xenia models versions delete mnist -v v1

You will be prompted for confirmation. Press 'y' to confirm.

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

xenia models delete mnist

You will be prompted for confirmation. Press 'y' to confirm.

Updated 4 days ago

CLI


Suggested Edits are limited on API Reference Pages

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