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

Field	Type	Description
workspace_id	Integer (REQUIRED)	The workspace id to list.

List Models in Workspace Returns

Field		Type	Description
models		List[models]	List of models in the workspace.
	id	Integer	The numerical id of the model.
	**owner_id	String	Identifer of the model owner.
	created_at	String	DateTime of the model’s creation.
	updated_at	String	DateTime 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

Field	Type	Description
workspace_id	Integer (REQUIRED)	The workspace id to list.

Get Model Details By ID Returns

Field	Type	Description
id	Integer	Numerical id of the model.
owner_id	String	Id of the owner of the model.
workspace_id	Integer	Numerical of the id the model is in.
name	String	Name of the model.
updated_at	String	DateTime of the model’s last update.
created_at	String	DateTime of the model’s creation.
model_config	String	Details 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.

Parameter	Type	Description
runtime	String (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_schema	pyarrow.lib.Schema	The input schema for the model in `pyarrow.lib.Schema` format.
output_schema	pyarrow.lib.Schema	The 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

Field	Type	Description
model_id	String (REQUIRED)	The model name.
models_pk_id	Integer (REQUIRED)	The model’s numerical id.

Get Model Versions Returns

Field		Type	Description
Unnamed		List[models]	A list of model versions for the requested model.
	sha	String	The `sha` hash of the model version.
	models_pk_id	Integer	The pk id of the model.
	model_version	String	The UUID identifier of the model version.
	owner_id	String	The Keycloak user id of the model’s owner.
	model_id	String	The name of the model.
	id	Integer	The integer id of the model.
	file_name	String	The filename used when uploading the model.
	image_path	String	The 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

Field	Type	Description
model_id	Integer (Required)	The numerical value of the model’s id.

Get Model Configuration by Id Returns

Field	Type	Description

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

Field	Type	Description
model_version_id	Integer (REQUIRED)	The model version id in numerical format.
tensor_fields	List[String] (OPTIONAL)	Overrides the model’s default input fields. Mainly used with ONNX models.
batch_config	String (OPTIONAL)	`single`: Only accepts one row of data at a time. `None`: Accepts multiple rows.
filter_threshold	Integer (OPTIONAL)	The model’s filter threshold.
input_schema	String (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_schema	String (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_fields	List[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.

Field	Type	Description
id	Integer	The model configuration id.
model_version_id	Integer	The model version id.
runtime	String	The Wallaroo runtime. See Wallaroo MLOps API Essentials Guide: Model Upload and Registrations for details on supported model frameworks.
tensor_fields	List[String]	The model input fields.
filter_threshold	Integer	The model’s filter threshold.
input_schema	String	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_schema	String	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_fields	List[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.

Field	Type	Description
model_id	Integer (REQUIRED)	The numerical value of the model’s id.

Get Model Details Returns

Field		Type	Description
id		Integer	The numerical value of the model’s id.
name		String	The name of the model.
owner_id		String	The model owner.
created_at		String	DateTime of the model’s creation.
updated_at		String	DateTime of the model’s last update.
models		List[models]	The list of model versions associated with this model.
	sha	String	The sha hash of the model version.
	models_pk_id	Integer	The model id.
	model_version	String	The UUID identifier of the model version.
	owner_id	String	The model owner.
	model_id	String	The name of the model.
	id	Integer	The numerical identifier of the model version.
	file_name	String	The file name used when uploading the model version
	image_path	String or None	The 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"
    }
  ]
}

Previous: Wallaroo MLOps API Essentials Guide: Workspace Management

Next: Wallaroo MLOps API Essentials Guide: Model Registry