mlmodel

Documentation

Overview

Package mlmodel defines the client and server for a service that can take in a map of input tensors/arrays, pass them through an inference engine, and then return a map output tensors/arrays. For more information, see the ML model service docs.

Index

• Constants
• Variables
• func Named(name string) resource.Name
• func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}
• func ProtoToTensors(pbft *pb.FlatTensors) (ml.Tensors, error)
• func TensorsToProto(ts ml.Tensors) (*servicepb.FlatTensors, error)
• type File
• type LabelType
• type MLMetadata
• type Service
  • func FromRobot(r robot.Robot, name string) (Service, error)
  • func NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, ...) (Service, error)
• type TensorInfo

Constants

const (
	// LabelTypeUnspecified means the label type is not known.
	LabelTypeUnspecified = LabelType("UNSPECIFIED")
	// LabelTypeTensorValue means the labels are assigned by the actual value in the tensor
	// e.g. for 4 results and 3 categories : [0, 1, 2, 1].
	LabelTypeTensorValue = LabelType("TENSOR_VALUE")
	// LabelTypeTensorAxis means labels are assigned by the position within the tensor axis
	// e.g. for 4 results and 3 categories : [[.8, .1, .1], [.2, .7, .1], [.1, .1, .8],[.05, .9, .05]].
	LabelTypeTensorAxis = LabelType("TENSOR_AXIS")
)

const SubtypeName = "mlmodel"

SubtypeName is the name of the type of service.

Variables

var API = resource.APINamespaceRDK.WithServiceType(SubtypeName)

API is a variable that identifies the ML model service resource API.

Functions

func Named

func Named(name string) resource.Name

Named is a helper for getting the named ML model service's typed resource name.

func NewRPCServiceServer

func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}

NewRPCServiceServer constructs a ML Model gRPC service server. It is intentionally untyped to prevent use outside of tests.

func ProtoToTensors

func ProtoToTensors(pbft *pb.FlatTensors) (ml.Tensors, error)

ProtoToTensors takes pb.FlatTensors and turns it into a Tensors map.

func TensorsToProto

func TensorsToProto(ts ml.Tensors) (*servicepb.FlatTensors, error)

TensorsToProto turns the ml.Tensors map into a protobuf message of FlatTensors.

Types

type File

type File struct {
	Name        string // e.g. category_labels.txt
	Description string
	LabelType   LabelType // TENSOR_VALUE, or TENSOR_AXIS
}

File contains information about how to interpret the numbers within the tensor/array. The label type describes how to read the tensor in order to successfully label the numbers.

type LabelType

type LabelType string

LabelType describes how labels from the file are assigned to the tensors. TENSOR_VALUE means that labels are the actual value in the tensor. TENSOR_AXIS means that labels are positional within the tensor axis.

type MLMetadata

type MLMetadata struct {
	ModelName        string
	ModelType        string // e.g. object_detector, text_classifier
	ModelDescription string
	Inputs           []TensorInfo
	Outputs          []TensorInfo
}

MLMetadata contains the metadata of the model file, such as the name of the model, what kind of model it is, and the expected tensor/array shape and types of the inputs and outputs of the model.

type Service

type Service interface {
	resource.Resource
	// Infer returns an output tensor map after running an input tensor map through an interface model.
	Infer(ctx context.Context, tensors ml.Tensors) (ml.Tensors, error)

	// Metadata returns the metadata: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model.
	Metadata(ctx context.Context) (MLMetadata, error)
}

Service defines the ML Model interface, which takes a map of inputs, runs it through an inference engine, and creates a map of outputs. Metadata is necessary in order to build the struct that will decode that map[string]interface{} correctly. For more information, see the ML model service docs.

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

Metadata example:

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

func FromRobot

func FromRobot(r robot.Robot, name string) (Service, error)

FromRobot is a helper for getting the named ML model service from the given Robot.

func NewClientFromConn

func NewClientFromConn(
	ctx context.Context,
	conn rpc.ClientConn,
	remoteName string,
	name resource.Name,
	logger logging.Logger,
) (Service, error)

NewClientFromConn constructs a new Client from connection passed in.

type TensorInfo

type TensorInfo struct {
	Name            string // e.g. bounding_boxes
	Description     string
	DataType        string // e.g. uint8, float32, int
	Shape           []int  // number of dimensions in the array
	AssociatedFiles []File
	Extra           map[string]interface{}
}

TensorInfo contains all the information necessary to build a struct from the input and output maps. it describes the name of the output field, what data type it has, and how many dimensions the array/tensor will have. AssociatedFiles points to where more information is located, e.g. in case the ints within the array/tensor need to be converted into a string.