Edit

ML model service API

The ML model service API allows you to make inferences based on a provided ML model.

The ML Model service supports the following methods:

Method Name	Description
`Infer`	Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.
`Metadata`	Get the metadata: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the ML model service with the given name.
`Close`	Safely shut down the resource and prevent further use.

Establish a connection

Viam Python SDK Support

To use the ML model service from the Viam Python SDK, install the Python SDK using the mlmodel extra:

pip install 'viam-sdk[mlmodel]'

To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page on the Viam app, navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

API key and API key ID

By default, the sample code does not include your machine API key and API key ID. We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.

To show your machine’s API key and API key ID in the sample code, toggle Include API key on the CONNECT tab’s Code sample page.

Caution

Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.

When executed, this sample code creates a connection to your machine as a client.

The following examples assume that you have a machine configured with an MLModel service called "my_mlmodel_service", and that you have installed the mlmodel extra for the Python SDK. If your ML model service has a different name, change the name in the code.

Be sure to import the mlmodel package for the SDK you are using:

Python
Go

from viam.services.mlmodel import MLModelClient

import (
  "go.viam.com/rdk/services/mlmodel"
)

API

Infer

Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.

Python
Go

Parameters:

input_tensors (Dict[str, typing.NDArray]) (required): A dictionary of input flat tensors as specified in the metadata.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(Dict[str, typing.NDArray]): A dictionary of output flat tensors as specified in the metadata.

Example:

import numpy as np

my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")

nd_array = np.array([1, 2, 3], dtype=np.float64)
input_tensors = {"0": nd_array}

output_tensors = await my_mlmodel.infer(input_tensors)

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
tensors (ml.Tensors): The input map of tensors, as specified in the metadata.

Returns:

(ml.Tensors): The output map of tensors, as specified in the metadata, after being run through an inference engine.
(error): An error, if one occurred.

Example:

input_tensors := ml.Tensors{"0": tensor.New(tensor.WithShape(1, 2, 3), tensor.WithBacking([]int{1, 2, 3, 4, 5, 6}))}

output_tensors, err := myMLModel.Infer(context.Background(), input_tensors)

For more information, see the Go SDK Docs.

Metadata

Get the metadata: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model.

Python
Go

Parameters:

timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(viam.services.mlmodel.mlmodel.Metadata): The metadata.

Example:

my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")

metadata = await my_mlmodel.metadata()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(MLMetadata): Name, type, expected tensor/array shape, inputs, and outputs associated with the ML model.
(error): An error, if one occurred.

Example:

metadata, err := myMLModel.Metadata(context.Background())

For more information, see the Go SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
deps (Dependencies): The resource dependencies.
conf (Config): The resource configuration.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the service API. For built-in service models, any model-specific commands available are covered with each model’s documentation. If you are implementing your own ML model service and add features that have no built-in API method, you can access them with DoCommand.

Python
Go

Parameters:

command (Mapping[str, ValueTypes]) (required): The command to execute.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(Mapping[str, viam.utils.ValueTypes])

Example:

service = MLModelClient.from_robot(robot, "my_mlmodel_svc")

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

# Can be used with any resource, using the motion service as an example
await service.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

Example:

myMlmodel, err := mlmodel.FromRobot(machine, "my_mlmodel")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myMlmodel.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

GetResourceName

Get the ResourceName for this instance of the ML model service with the given name.

Python

Parameters:

name (str) (required): The name of the Resource.

Returns:

(viam.proto.common.ResourceName): The ResourceName of this Resource.

Example:

my_mlmodel_svc_name = MLModelClient.get_resource_name("my_mlmodel_svc")

For more information, see the Python SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python
Go

Parameters:

None.

Returns:

None.

Example:

await my_mlmodel_svc.close()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(error): An error, if one occurred.

Example:

my_mlmodel, err := mlmodel.FromRobot(machine, "my_ml_model")

err := my_mlmodel.Close(context.Background())

For more information, see the Go SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!