Wallaroo MLOps API Essentials Guide: Model Management

How to use the Wallaroo API for Model Management

Model Naming Requirements

Model names map onto Kubernetes objects, and must be DNS compliant. The strings for model names must be lower case ASCII alpha-numeric characters or dash (-) only. . and _ are not allowed.

Models

The Wallaroo MLOps API allows users to upload different types of ML models and frameworks into Wallaroo.

Upload Model to Workspace

See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations

List Models in Workspace

  • Endpoint: /v1/api/models/list

Returns a list of models added to a specific workspace.

List Models in Workspace Parameters

FieldTypeDescription
workspace_idInteger (REQUIRED)The workspace id to list.

List Models in Workspace Returns

Field TypeDescription
models List[models]List of models in the workspace.
 idIntegerThe numerical id of the model.
 **owner_idStringIdentifer of the model owner.
 created_atStringDateTime of the model’s creation.
 updated_atStringDateTime of the model’s last update.

List Models in Workspace Examples

Display the models for the workspace. This is assumed to be workspace_id of 10. Adjust the script for your own use.

List models in workspace via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/models/list"

data = {
  "workspace_id": workspace_id
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
display(response)
{
  "models": [
    {
      "id": 15,
      "name": "api-upload-pytorch-multi-io",
      "owner_id": "\"\"",
      "created_at": "2023-11-29T16:30:53.716526+00:00",
      "updated_at": "2023-11-29T18:20:39.610964+00:00"
    },
    {
      "id": 14,
      "name": "api-sample-model",
      "owner_id": "\"\"",
      "created_at": "2023-11-29T16:26:06.011817+00:00",
      "updated_at": "2023-11-29T16:26:06.011817+00:00"
    }
  ]
}

List models in workspace via curl.

curl {wl.api_endpoint}/v1/api/models/list \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"workspace_id": {workspace_id}}}'
{
  "models": [
    {
      "id": 15,
      "name": "api-upload-pytorch-multi-io",
      "owner_id": "\"\"",
      "created_at": "2023-11-29T16:30:53.716526+00:00",
      "updated_at": "2023-11-29T18:20:39.610964+00:00"
    },
    {
      "id": 14,
      "name": "api-sample-model",
      "owner_id": "\"\"",
      "created_at": "2023-11-29T16:26:06.011817+00:00",
      "updated_at": "2023-11-29T16:26:06.011817+00:00"
    }
  ]
}

Get Model Details By ID

  • Endpoint: /v1/api/models/get_by_id

Returns the model details by the specific model id.

Get Model Details By ID Parameters

FieldTypeDescription
workspace_idInteger (REQUIRED)The workspace id to list.

Get Model Details By ID Returns

FieldTypeDescription
idIntegerNumerical id of the model.
owner_idStringId of the owner of the model.
workspace_idIntegerNumerical of the id the model is in.
nameStringName of the model.
updated_atStringDateTime of the model’s last update.
created_atStringDateTime of the model’s creation.
model_configStringDetails of the model’s configuration.

Model Config Options

Model version configurations are updated with the wallaroo.model_version.config and include the following parameters. Most are optional unless specified.

ParameterTypeDescription
runtimeString (Optional)The model runtime from wallaroo.framework. }
tensor_fields(List[string]) (Optional)A list of alternate input fields. For example, if the model accepts the input fields ['variable1', 'variable2'], tensor_fields allows those inputs to be overridden to ['square_feet', 'house_age'], or other values as required.
input_schemapyarrow.lib.SchemaThe input schema for the model in pyarrow.lib.Schema format.
output_schemapyarrow.lib.SchemaThe output schema for the model in pyarrow.lib.Schema format.
batch_config(List[string]) (Optional)Batch config is either None for multiple-input inferences, or single to accept an inference request with only one row of data.

Get Model Details By ID Examples

Retrieve the details for the model uploaded in the Upload Model to Workspace step. This will first list the models in the workspace with the id 10, then use that first model to display information. This assumes the workspace id and that there is at least one model uploaded to it.

Get Model Details By ID via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/models/list"

data = {
  "workspace_id": workspace_id
}

# first get the list of models in the workspace
response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
example_model_id = response['models'][0]['id']
example_model_name = response['models'][0]['name']

# Get model details by id
# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/models/get_by_id"

data = {
  "id": example_model_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
display(response)
{
    'id': 15,
    'owner_id': '""',
    'workspace_id': 10,
    'name': 'api-upload-pytorch-multi-io',
    'updated_at': '2023-11-29T18:20:39.610964+00:00',
    'created_at': '2023-11-29T16:30:53.716526+00:00',
    'model_config': {
        'id': 25,
        'runtime': 'flight',
        'tensor_fields': None,
        'filter_threshold': None
    }
}

Get Model Details By ID via curl.

curl {wl.api_endpoint}/v1/api/models/get_by_id \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"id": {example_model_id}}}'
{
  "id": 15,
  "owner_id": "\"\"",
  "workspace_id": 10,
  "name": "api-upload-pytorch-multi-io",
  "updated_at": "2023-11-29T18:20:39.610964+00:00",
  "created_at": "2023-11-29T16:30:53.716526+00:00",
  "model_config": {
    "id": 25,
    "runtime": "flight",
    "tensor_fields": null,
    "filter_threshold": null
  }
}

Get Model Versions

  • Endpoint: /v1/api/models/list_versions

Retrieves all versions of a model based on either the name of the model or the model_pk_id.

Get Model Versions Parameters

FieldTypeDescription
model_idString (REQUIRED)The model name.
models_pk_idInteger (REQUIRED)The model’s numerical id.

Get Model Versions Returns

Field TypeDescription
Unnamed List[models]A list of model versions for the requested model.
 shaStringThe sha hash of the model version.
 models_pk_idIntegerThe pk id of the model.
 model_versionStringThe UUID identifier of the model version.
 owner_idStringThe Keycloak user id of the model’s owner.
 model_idStringThe name of the model.
 idIntegerThe integer id of the model.
 file_nameStringThe filename used when uploading the model.
 image_pathStringThe image path of the model.

Retrieve the versions for a previously uploaded model. This assumes a workspace with id 10 has models already loaded into it.

Retrieve model versions via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/models/list"

data = {
  "workspace_id": workspace_id
}

# first get the list of models in the workspace
response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
example_model_id = response['models'][0]['id']
example_model_name = response['models'][0]['name']

## List model versions

# Retrieve the token 
headers = wl.auth.auth_header()
endpoint = f"{wl.api_endpoint}/v1/api/models/list_versions"

data = {
  "model_id": example_model_name,
  "models_pk_id": example_model_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
display(response)
[{'sha': '792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8',
  'models_pk_id': 15,
  'model_version': '271875ae-92ee-4137-b54f-c2ce1e88121c',
  'owner_id': '""',
  'model_id': 'api-upload-pytorch-multi-io',
  'id': 19,
  'file_name': 'model-auto-conversion_pytorch_multi_io_model.pt',
  'image_path': None,
  'status': 'error'},
 {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
  'models_pk_id': 15,
  'model_version': 'ce648f2a-faee-4c8d-8a7b-e2789f3ab919',
  'owner_id': '""',
  'model_id': 'api-upload-pytorch-multi-io',
  'id': 17,
  'file_name': 'ccfraud.onnx',
  'image_path': None,
  'status': 'error'},
 {'sha': '792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8',
  'models_pk_id': 15,
  'model_version': 'a6762893-be27-4142-ba09-4ce1b87b74a8',
  'owner_id': '""',
  'model_id': 'api-upload-pytorch-multi-io',
  'id': 15,
  'file_name': 'api-upload-pytorch-multi-io',
  'image_path': None,
  'status': 'error'},
 {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
  'models_pk_id': 15,
  'model_version': '0f96fae1-8ebc-41d8-a11d-3eaa3bc26526',
  'owner_id': '""',
  'model_id': 'api-upload-pytorch-multi-io',
  'id': 18,
  'file_name': 'ccfraud.onnx',
  'image_path': None,
  'status': 'error'},
 {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
  'models_pk_id': 15,
  'model_version': '9150b046-5df0-4c41-a60b-3016355f89d5',
  'owner_id': '""',
  'model_id': 'api-upload-pytorch-multi-io',
  'id': 16,
  'file_name': 'ccfraud.onnx',
  'image_path': 'proxy.replicated.com/proxy/wallaroo/ghcr.io/wallaroolabs/mlflow-deploy:v2023.4.0-4103',
  'status': 'ready'}]

Retrieve model versions via curl.

curl {wl.api_endpoint}/v1/api/models/list_versions \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    -d '{json.dumps(data)}'
[
  {
    "sha": "792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8",
    "models_pk_id": 15,
    "model_version": "271875ae-92ee-4137-b54f-c2ce1e88121c",
    "owner_id": "\"\"",
    "model_id": "api-upload-pytorch-multi-io",
    "id": 19,
    "file_name": "model-auto-conversion_pytorch_multi_io_model.pt",
    "image_path": null,
    "status": "error"
  },
  {
    "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
    "models_pk_id": 15,
    "model_version": "ce648f2a-faee-4c8d-8a7b-e2789f3ab919",
    "owner_id": "\"\"",
    "model_id": "api-upload-pytorch-multi-io",
    "id": 17,
    "file_name": "ccfraud.onnx",
    "image_path": null,
    "status": "error"
  },
  {
    "sha": "792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8",
    "models_pk_id": 15,
    "model_version": "a6762893-be27-4142-ba09-4ce1b87b74a8",
    "owner_id": "\"\"",
    "model_id": "api-upload-pytorch-multi-io",
    "id": 15,
    "file_name": "api-upload-pytorch-multi-io",
    "image_path": null,
    "status": "error"
  },
  {
    "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
    "models_pk_id": 15,
    "model_version": "0f96fae1-8ebc-41d8-a11d-3eaa3bc26526",
    "owner_id": "\"\"",
    "model_id": "api-upload-pytorch-multi-io",
    "id": 18,
    "file_name": "ccfraud.onnx",
    "image_path": null,
    "status": "error"
  },
  {
    "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
    "models_pk_id": 15,
    "model_version": "9150b046-5df0-4c41-a60b-3016355f89d5",
    "owner_id": "\"\"",
    "model_id": "api-upload-pytorch-multi-io",
    "id": 16,
    "file_name": "ccfraud.onnx",
    "image_path": "proxy.replicated.com/proxy/wallaroo/ghcr.io/wallaroolabs/mlflow-deploy:v2023.4.0-4103",
    "status": "ready"
  }
]

Get Model Configuration by Id

  • Endpoints: /v1/api/models/get_config_by_id

Returns the model’s configuration details.

Get Model Configuration by Id Parameters

FieldTypeDescription
model_idInteger (Required)The numerical value of the model’s id.

Get Model Configuration by Id Returns

FieldTypeDescription

Get Model Configuration by Id Examples

Submit the model id for the model uploaded in the Upload Model to Workspace step to retrieve configuration details.

Retrieve model configuration via Requests.

## Get model config by id

# Retrieve the token 
headers = wl.auth.auth_header()
endpoint = f"{wl.api_endpoint}/v1/api/models/get_config_by_id"

data = {
  "model_id": example_model_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
response
{'model_config': {'id': 25,
      'runtime': 'flight',
      'tensor_fields': None,
      'filter_threshold': None}}

Retrieve model configuration via curl.

curl {wl.api_endpoint}/v1/api/models/get_config_by_id \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    -d '{json.dumps(data)}'
{
  "model_config": {
    "id": 25,
    "runtime": "flight",
    "tensor_fields": null,
    "filter_threshold": null
  }
}

Set Model Configuration by ID

  • Endpoint: /v1/api/models/insert_model_config

Model configurations are added with the endpoint /v1/api/models/insert_model_config endpoint. This sets the model configuration for the model version. Once uploaded, the model version configuration is set to the uploaded model config.

Set Model Configuration by ID Parameters

FieldTypeDescription
model_version_idInteger (REQUIRED)The model version id in numerical format.
tensor_fieldsList[String] (OPTIONAL)Overrides the model’s default input fields. Mainly used with ONNX models.
batch_configString (OPTIONAL)single: Only accepts one row of data at a time. None: Accepts multiple rows.
filter_thresholdInteger (OPTIONAL)The model’s filter threshold.
input_schemaString (OPTIONAL)The model’s input schema in PyArrow.Schema format. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
output_schemaString (OPTIONAL)The model’s output schema in PyArrow.Schema format. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
tensor_fieldsList[String] (OPTIONAL)The input field names for the model types. Primarily used to override ONNX model input fields.

Set Model Configuration by ID Returns

Returns the model config with the following fields.

FieldTypeDescription
idIntegerThe model configuration id.
model_version_idIntegerThe model version id.
runtimeStringThe Wallaroo runtime. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
tensor_fieldsList[String]The model input fields.
filter_thresholdIntegerThe model’s filter threshold.
input_schemaStringThe model’s input schema in PyArrow.Schema format. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
output_schemaStringThe model’s output schema in PyArrow.Schema format. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
tensor_fieldsList[String]The input field names for the model types. Primarily used to override ONNX model input fields.

Set Model Configuration by ID Example

The following example uses the Requests library to set a model’s configuration.

# Retrieve the token 
headers = wl.auth.auth_header()
api_request = f"{APIURL}/v1/api/models/insert_model_config"

data = {
    "model_version_id": 6,
    "batch_config": None,  # str
    "filter_threshold": 0.1,
    "input_schema": None,  # str
    "output_schema": None,  # str
    "tensor_fields": ["dense_1"]  # List[str]
}


response = requests.post(api_request, json=data, headers=headers, verify=True).json()
response

{'model_config': {'id': 20,
  'model_version_id': 6,
  'runtime': 'onnx',
  'filter_threshold': 0.1,
  'tensor_fields': ['dense_1'],
  'input_schema': None,
  'output_schema': None,
  'batch_config': None}}

Get Model Details

  • Endpoint: /v1/api/models/get

Get Model Details Parameters

Returns details regarding a single model, including versions.

FieldTypeDescription
model_idInteger (REQUIRED)The numerical value of the model’s id.

Get Model Details Returns

Field TypeDescription
id IntegerThe numerical value of the model’s id.
name StringThe name of the model.
owner_id StringThe model owner.
created_at StringDateTime of the model’s creation.
updated_at StringDateTime of the model’s last update.
models List[models]The list of model versions associated with this model.
 shaStringThe sha hash of the model version.
 models_pk_idIntegerThe model id.
 model_versionStringThe UUID identifier of the model version.
 owner_idStringThe model owner.
 model_idStringThe name of the model.
 idIntegerThe numerical identifier of the model version.
 file_nameStringThe file name used when uploading the model version
 image_pathString or NoneThe image path of the model verison.

Get Model Details Examples

Submit the model id for the model uploaded in the Upload Model to Workspace step to retrieve configuration details.

Get model details via Requests.

# Get model config by id
# Retrieve the token 
headers = wl.auth.auth_header()
endpoint = f"{wl.api_endpoint}/v1/api/models/get"

data = {
  "id": example_model_id
}

response = requests.post(endpoint, json=data, headers=headers, verify=True).json()
response
{'id': 15,
     'name': 'api-upload-pytorch-multi-io',
     'owner_id': '""',
     'created_at': '2023-11-29T16:30:53.716526+00:00',
     'updated_at': '2023-11-29T18:20:39.610964+00:00',
     'models': [{'sha': '792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8',
       'models_pk_id': 15,
       'model_version': '271875ae-92ee-4137-b54f-c2ce1e88121c',
       'owner_id': '""',
       'model_id': 'api-upload-pytorch-multi-io',
       'id': 19,
       'file_name': 'model-auto-conversion_pytorch_multi_io_model.pt',
       'image_path': None},
      {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
       'models_pk_id': 15,
       'model_version': 'ce648f2a-faee-4c8d-8a7b-e2789f3ab919',
       'owner_id': '""',
       'model_id': 'api-upload-pytorch-multi-io',
       'id': 17,
       'file_name': 'ccfraud.onnx',
       'image_path': None},
      {'sha': '792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8',
       'models_pk_id': 15,
       'model_version': 'a6762893-be27-4142-ba09-4ce1b87b74a8',
       'owner_id': '""',
       'model_id': 'api-upload-pytorch-multi-io',
       'id': 15,
       'file_name': 'api-upload-pytorch-multi-io',
       'image_path': None},
      {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
       'models_pk_id': 15,
       'model_version': '0f96fae1-8ebc-41d8-a11d-3eaa3bc26526',
       'owner_id': '""',
       'model_id': 'api-upload-pytorch-multi-io',
       'id': 18,
       'file_name': 'ccfraud.onnx',
       'image_path': None},
      {'sha': 'bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507',
       'models_pk_id': 15,
       'model_version': '9150b046-5df0-4c41-a60b-3016355f89d5',
       'owner_id': '""',
       'model_id': 'api-upload-pytorch-multi-io',
       'id': 16,
       'file_name': 'ccfraud.onnx',
       'image_path': 'proxy.replicated.com/proxy/wallaroo/ghcr.io/wallaroolabs/mlflow-deploy:v2023.4.0-4103'}]}

Get model details via curl.

curl {wl.api_endpoint}/v1/api/models/get \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    -d '{{"id": {example_model_id}}}'
{
  "id": 15,
  "name": "api-upload-pytorch-multi-io",
  "owner_id": "\"\"",
  "created_at": "2023-11-29T16:30:53.716526+00:00",
  "updated_at": "2023-11-29T18:20:39.610964+00:00",
  "models": [
    {
      "sha": "792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8",
      "models_pk_id": 15,
      "model_version": "271875ae-92ee-4137-b54f-c2ce1e88121c",
      "owner_id": "\"\"",
      "model_id": "api-upload-pytorch-multi-io",
      "id": 19,
      "file_name": "model-auto-conversion_pytorch_multi_io_model.pt",
      "image_path": null
    },
    {
      "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
      "models_pk_id": 15,
      "model_version": "ce648f2a-faee-4c8d-8a7b-e2789f3ab919",
      "owner_id": "\"\"",
      "model_id": "api-upload-pytorch-multi-io",
      "id": 17,
      "file_name": "ccfraud.onnx",
      "image_path": null
    },
    {
      "sha": "792db9ee9f41aded3c1d4705f50ccdedd21cafb8b6232c03e4a849b6da1050a8",
      "models_pk_id": 15,
      "model_version": "a6762893-be27-4142-ba09-4ce1b87b74a8",
      "owner_id": "\"\"",
      "model_id": "api-upload-pytorch-multi-io",
      "id": 15,
      "file_name": "api-upload-pytorch-multi-io",
      "image_path": null
    },
    {
      "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
      "models_pk_id": 15,
      "model_version": "0f96fae1-8ebc-41d8-a11d-3eaa3bc26526",
      "owner_id": "\"\"",
      "model_id": "api-upload-pytorch-multi-io",
      "id": 18,
      "file_name": "ccfraud.onnx",
      "image_path": null
    },
    {
      "sha": "bc85ce596945f876256f41515c7501c399fd97ebcb9ab3dd41bf03f8937b4507",
      "models_pk_id": 15,
      "model_version": "9150b046-5df0-4c41-a60b-3016355f89d5",
      "owner_id": "\"\"",
      "model_id": "api-upload-pytorch-multi-io",
      "id": 16,
      "file_name": "ccfraud.onnx",
      "image_path": "proxy.replicated.com/proxy/wallaroo/ghcr.io/wallaroolabs/mlflow-deploy:v2023.4.0-4103"
    }
  ]
}