Retrain a Dataset

Retrains a dataset and updates a model. Use this API call when you want to update a model and keep the model ID instead of creating a new model. Available in Einstein Vision API version 2.0 and later.

Request Parameters

Name

Type

Description

Available Version

algorithm

string

Specifies the algorithm used to train the dataset. Optional. Use this parameter only when training a dataset with a type of image-detection. Valid values are:

  • object-detection-v1—Uses the original training algorithm. The training process defaults to this algorithm if the parameter isn’t supplied.
  • object-detection-v2—Uses fewer training samples than the previous algorithms. With this algorithm you can use as few as 50 bounding boxes of annotation per object.
  • retail-execution—Uses the training algorithm that's optimized to detect items displayed on retail shelves.

2.0

epochs

int

Number of training iterations for the neural network. Optional. Valid values are 1–1,000.
If not specified:

  • For image and multi-label datasets, the default is calculated based on the dataset size.
  • For detection datasets, the default is 20 epochs.

The larger the number, the longer the training takes to complete.

2.0

learningRate

float

Specifies how much the gradient affects the optimization of the model at each time step. Optional. Use this parameter to tune your model. Valid values are between 0.0001 and 0.01. If not specified, the default is 0.0001. We recommend keeping this value between 0.0001 and 0.001.

This parameter isn't used when training a detection dataset.

2.0

modelId

string

ID of the model to be updated from the training.

2.0

trainParams

object

JSON that contains parameters that specify how the model is created. Optional. Valid values:

  • {"trainSplitRatio": 0.n}—Lets you specify the ratio of data used to train the dataset and the data used to test the model. The default split ratio is 0.9; 90% of the data is used to train the dataset and create the model and 10% of the data is used to test the model. If you pass in a split ratio of 0.6, then 60% of the data is used to train the dataset and create the model and 40% of the data is used to test the model.

  • {"withFeedback": true}—Lets you specify that feedback examples are included in the data to be trained to create the model. If you omit this parameter, feedback examples aren't used in training. Available in Einstein Vision API version 2.0 and later.

  • {"withGlobalDatasetId": <DATASET_ID>}—Lets you specify that a global dataset is used in addition to the specified dataset to create the model. Available in Einstein Vision API version 2.0 and later.
    This parameter isn't used when training a detection dataset.

2.0

This call retrains the dataset associated with model specified in the request parameters. Use this call to retrain a dataset and update the model after new examples are added to a dataset or after feedback examples are added to a dataset.

  • A dataset can have only one training in progress at a time. Let's say you retrain a dataset and there's a model with a status of RUNNING or QUEUED. If you attempt to retrain the same dataset again, you receive an error.

  • If you try to retrain a dataset that was deleted or that has a status of DELETE_PENDING, you receive an error.

  • If you try to retrain a dataset and pass in a model ID for a model that was deleted, you receive an error.

To see the values specified in the trainParams parameter when the model was trained, such as withFeedback or withGlobalDatasetId, see Get Training Status.

Response Body

Name

Type

Description

Available Version

algorithm

string

Algorithm used to create the model. Returned only when the modelType is image-detection. Default is object-detection-v1.

2.0

createdAt

date

Date and time that the model was created.

2.0

datasetId

long

ID of the dataset trained to create the model.

2.0

datasetVersionId

int

N/A

2.0

epochs

int

Number of epochs used during training.

2.0

language

string

Model language inherited from the dataset language. Default is N/A.

2.0

learningRate

float

Learning rate used during training.

2.0

modelId

string

ID of the model. Contains letters and numbers.

2.0

modelType

string

Type of data from which the model was created. Inferred from the dataset type. Valid values are:

  • image
  • image-detection— Available in Einstein Vision API version 2.0 and later.
  • image-multi-label— Available in Einstein Vision API version 2.0 and later.

2.0

name

string

Name of the model.

2.0

object

string

Object returned; in this case, training.

2.0

progress

float

How far the training job has progressed. Values are between 0–1.

2.0

queuePosition

int

Where the training job is in the queue. This field appears in the response only if the status is QUEUED.

2.0

status

string

Status of the training job. Valid values are:

  • QUEUED—The training job is in the queue.
  • RUNNING—The training job is running.
  • SUCCEEDED—The training job succeeded, and the model was created.
  • FAILED—The training job failed.

2.0

trainParams

object

Training parameters passed into the request. For example, if you sent in a split of 0.7, the response contains "trainParams": {"trainSplitRatio": 0.7}

2.0

trainStats

object

Returns null when you train a dataset. Training statistics are returned when the status is SUCCEEDED or FAILED.

2.0

updatedAt

date

Date and time that the model was last updated.

2.0

This cURL command sends in the trainParams request parameter. This command has double quotes and escaped double quotes around trainSplitRatio to run on Windows. You might need to reformat it to run on another OS.

curl -X POST -H "Authorization: Bearer <TOKEN>" -H "Cache-Control: no-cache" -H "Content-Type: multipart/form-data" -F "modelId=7JXCXTRXTMNLJCEF2DR5CJ46QU" -F "trainParams={\"trainSplitRatio\":0.7}" https://api.einstein.ai/v2/vision/retrain

You can pass in multiple training parameters. For example, you specify withFeedback and trainSplitRatio using this JSON: {"withFeedback" : true, "trainSplitRatio" : 0.7}.

Language