# ML model service API

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

The [ML model service](https://docs.viam.com/vision/deploy-and-maintain/deploy-from-registry/) supports the following methods:

| Method Name | Description |
| --- | --- |
| [`Infer`](https://docs.viam.com/reference/apis/services/ml/#infer) | Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map. |
| [`Metadata`](https://docs.viam.com/reference/apis/services/ml/#metadata) | Get the metadata: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model. |
| [`Reconfigure`](https://docs.viam.com/reference/apis/services/ml/#reconfigure) | Reconfigure this resource. |
| [`DoCommand`](https://docs.viam.com/reference/apis/services/ml/#docommand) | Execute model-specific commands that are not otherwise defined by the service API. |
| [`GetResourceName`](https://docs.viam.com/reference/apis/services/ml/#getresourcename) | Get the `ResourceName` for this instance of the ML model service. |
| [`Close`](https://docs.viam.com/reference/apis/services/ml/#close) | Safely shut down the resource and prevent further use. |

## API

### Infer

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

- [Python](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-1-0)
- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-1-1)

**Parameters:**

- `input_tensors` (Dict[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), [typing.NDArray](https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray)]) (required): A dictionary of input flat tensors as specified in the metadata.
- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), [typing.NDArray](https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray)]): : A dictionary of output flat tensors as specified in the metadata.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.infer).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `tensors` [(ml.Tensors)](https://pkg.go.dev/go.viam.com/rdk/ml#Tensors): The input map of tensors, as specified in the metadata.

**Returns:**

- [(ml.Tensors)](https://pkg.go.dev/go.viam.com/rdk/ml#Tensors): The output map of tensors, as specified in the metadata, after being run through an inference engine.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

Copy

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/mlmodel#Service).

### Metadata

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

- [Python](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-2-0)
- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-2-1)

**Parameters:**

- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.metadata).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

**Returns:**

- [(MLMetadata)](https://pkg.go.dev/go.viam.com/rdk/services/mlmodel#MLMetadata): Name, type, expected tensor/array shape, inputs, and outputs associated with the ML model.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

Copy

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/mlmodel#Service).

### Reconfigure

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

- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-3-0)

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `deps` [(Dependencies)](https://pkg.go.dev/go.viam.com/rdk/resource#Dependencies): The resource dependencies.
- `conf` [(Config)](https://pkg.go.dev/go.viam.com/rdk/resource#Config): The resource configuration.

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

### DoCommand

Execute model-specific commands that are not otherwise defined by the service API. Most models do not implement `DoCommand`. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own ML model service and want to add features that have no corresponding built-in API method, you can implement them with [`DoCommand`](https://docs.viam.com/reference/sdks/docommand/).

- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-4-0)

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `cmd` [(map[string]interface{})](https://go.dev/blog/maps): The command to execute.

**Returns:**

- [(map[string]interface{})](https://pkg.go.dev/builtin#string): The command response.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

Copy

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

### GetResourceName

Get the `ResourceName` for this instance of the ML model service.

- [Python](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-5-0)
- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-5-1)

**Parameters:**

- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource.

**Returns:**

- ( [viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.get_resource_name).

**Parameters:**

- None.

**Returns:**

- [(Name)](https://pkg.go.dev/go.viam.com/rdk@v0.89.0/resource#Name)

**Example:**

```go

```

Copy

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

### Close

Safely shut down the resource and prevent further use.

- [Python](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-6-0)
- [Go](https://docs.viam.com/reference/apis/services/ml/#tabset-referenceapisservicesml-6-1)

**Parameters:**

- None.

**Returns:**

- None.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.close).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

Copy

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).