Models - Create

Reference

Service:: Azure AI Services

API Version:: 2023-04-01-preview

Start training a custom model.

Status codes returned:

201: Operation completed successfully.
400: The request was malformed.
409: A model with the specified name already exists.

PUT /models/{name}?api-version=2023-04-01-preview

URI Parameters

Name In Required Type Description

Name	In	Required	Type	Description
name	path	True	string	A name that can be used to uniquely identify the model after it has been created. Regex pattern: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`
api-version	query	True	string	Requested API version.

name

path

True

string

A name that can be used to uniquely identify the model after it has been created.

Regex pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]*$

api-version

query

True

string

Requested API version.

Request Body

Media Types: "application/json-patch+json"

Name	Required	Type	Description
trainingParameters	True	TrainingParameters	Parameters for specifying how a training run trains a custom model.
createdDateTime		string	Read only. The date and time when the training run was first created, in UTC.
error		ErrorResponseDetails	Error info.
evaluationParameters		ModelEvaluationParameters	Parameters for specifying how a model is evaluated.
modelPerformance		ModelPerformance	Performance metrics for a custom trained model.
name		string	Read only. The name that is used to uniquely identify the training run.
status		ModelState	Read only. The current state of the training run.
updatedDateTime		string	Read only. The date and time when the training run was last updated, in UTC.

Responses

Name	Type	Description
201 Created	Model	Created
Other Status Codes	ErrorResponse	Error Headers x-ms-error-code: string

Name

Type

Description

201 Created

Model

Created

Other Status Codes

ErrorResponse

Error

Headers

x-ms-error-code: string

Examples

Models_Create

Sample request

HTTP

PUT /models/model_name?api-version=2023-04-01-preview

{
  "trainingParameters": {
    "timeBudgetInHours": 100,
    "trainingDatasetName": "my_dataset_name"
  }
}

Sample response

Status code:: 201

{
  "name": "model_name",
  "createdDateTime": "2023-01-13T20:46:21.210Z",
  "updatedDateTime": "2023-01-13T20:46:21.210Z",
  "status": "notStarted",
  "trainingParameters": {
    "timeBudgetInHours": 100,
    "trainingDatasetName": "my_dataset_name"
  }
}

Definitions

Name	Description
ErrorResponse	Response returned when an error occurs.
ErrorResponseDetails	Error info.
ErrorResponseInnerError	Detailed error.
Model	Describes a training run for training a custom model.
ModelEvaluationParameters	Parameters for specifying how a model is evaluated.
ModelKind	Model kind.
ModelPerformance	Performance metrics for a custom trained model.
ModelState	Read only. The current state of the training run.
ModelTagPerformance	Performance metrics for each tag recognized by a custom trained model.
TrainingParameters	Parameters for specifying how a training run trains a custom model.

ErrorResponse

Response returned when an error occurs.

Name	Type	Description
error	ErrorResponseDetails	Error info.

ErrorResponseDetails

Error info.

Name	Type	Description
code	string	Error code.
details	ErrorResponseDetails[]	List of detailed errors.
innererror	ErrorResponseInnerError	Detailed error.
message	string	Error message.
target	string	Target of the error.

ErrorResponseInnerError

Detailed error.

Name	Type	Description
code	string	Error code.
innererror	ErrorResponseInnerError	Detailed error.
message	string	Error message.

Model

Describes a training run for training a custom model.

Name	Type	Description
createdDateTime	string	Read only. The date and time when the training run was first created, in UTC.
error	ErrorResponseDetails	Error info.
evaluationParameters	ModelEvaluationParameters	Parameters for specifying how a model is evaluated.
modelPerformance	ModelPerformance	Performance metrics for a custom trained model.
name	string	Read only. The name that is used to uniquely identify the training run.
status	ModelState	Read only. The current state of the training run.
trainingCostInMinutes	integer	Read only. Actual training cost consumed, in minutes. Present only if the training run as completed.
trainingParameters	TrainingParameters	Parameters for specifying how a training run trains a custom model.
updatedDateTime	string	Read only. The date and time when the training run was last updated, in UTC.

ModelEvaluationParameters

Parameters for specifying how a model is evaluated.

Name	Type	Description
testDatasetName	string	The dataset name used for testing.

ModelKind

Model kind.

Name	Type	Description
Generic-Classifier	string
Generic-Detector	string
Product-Recognizer	string

ModelPerformance

Performance metrics for a custom trained model.

Name	Type	Description
accuracyTop1	number	Read only. For multiclass classification models. The proportion of test samples where the ground truth class matches the predicted class.
accuracyTop5	number	Read only. For multiclass classification models. The proportion of test samples where the ground truth class is in the top five predicted classes.
averagePrecision	number	Read only. A measure of the model performance, it summarizes the precision and recall at different confidence thresholds.
calibrationECE	number	Read only. For multiclass classification models. Expected calibration error.
meanAveragePrecision30	number	Read only. For object detection models. Mean average precision at a threshold of 30%.
meanAveragePrecision50	number	Read only. For object detection models. Mean average precision at a threshold of 50%.
meanAveragePrecision75	number	Read only. For object detection models. Mean average precision at a threshold of 75%.
tagPerformance	<string, ModelTagPerformance>	Read only. Performance metrics for each tag recognized by the model.

ModelState

Read only. The current state of the training run.

Name	Type	Description
cancelled	string
cancelling	string
failed	string
notStarted	string
succeeded	string
training	string

ModelTagPerformance

Performance metrics for each tag recognized by a custom trained model.

Name	Type	Description
accuracy	number	Read only. For multiclass models. Tag accuracy.
averagePrecision50	number	Read only. For object detection models. Average precision at a threshold of 50%.

TrainingParameters

Parameters for specifying how a training run trains a custom model.

Name	Type	Description
modelKind	ModelKind	Model kind.
timeBudgetInHours	integer	Time budget for training, in hours. The minimum allowed value is 1, and the maximum allowed value is 336 hours for GenericClassifier, 1344 hours for GenericDetector. This is the maximum amount of compute time that will be spent to train the model.
trainingDatasetName	string	The dataset name used for training.

Share via

Models - Create

URI Parameters

Request Body

Responses

Examples

Models_Create

Sample request

Sample response

Definitions

ErrorResponse

ErrorResponseDetails

ErrorResponseInnerError

Model

ModelEvaluationParameters

ModelKind

ModelPerformance

ModelState

ModelTagPerformance

TrainingParameters

Additional resources