Custom Models - Train

Service:

Azure AI Services

API Version:

2.1

Create and train a custom model. The request must include a source parameter that is either an externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be under the source folder or sub folders under it. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Other type of content is ignored.

POST {endpoint}/formrecognizer/v2.1/custom/models

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Request Body

Name	Required	Type	Description
source	True	string	Source path containing the training documents.
modelName		string	Optional user defined model name (max length: 1024).
sourceFilter		TrainSourceFilter	Filter to apply to the documents in the source path for training.
useLabelFile		boolean	Use label file for training a model.

Responses

Name	Type	Description
201 Created		Request is queued successfully. Headers Location: string
Other Status Codes	ErrorResponse	Response entity accompanying non-successful responses containing additional details about the error.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Train custom model

Train custom model with subfolder filter options

Train custom model

Sample request

HTTP

POST {endpoint}/formrecognizer/v2.1/custom/models


{
  "source": "{azure_blob_endpoint}/input/data1?sasToken"
}

Sample response

Status code:

201

Location: {endpoint}/formrecognizer/v2.1/custom/models/f973e3c1-1148-43bb-bea8-49d0603ab3a8

Train custom model with subfolder filter options

Sample request

HTTP

POST {endpoint}/formrecognizer/v2.1/custom/models


{
  "source": "{azure_blob_endpoint}/input/data1?sasToken",
  "sourceFilter": {
    "prefix": "",
    "includeSubFolders": false
  },
  "useLabelFile": false
}

Sample response

Status code:

201

Location: {endpoint}/formrecognizer/v2.1/custom/models/f973e3c1-1148-43bb-bea8-49d0603ab3a8

Definitions

Name	Description
ErrorInformation
ErrorResponse
TrainRequest	Request parameter to train a new custom model.
TrainSourceFilter	Filter to apply to the documents in the source path for training.

ErrorInformation

Name	Type	Description
code	string
message	string

ErrorResponse

Name	Type	Description
error	ErrorInformation

TrainRequest

Request parameter to train a new custom model.

Name	Type	Default value	Description
modelName	string		Optional user defined model name (max length: 1024).
source	string		Source path containing the training documents.
sourceFilter	TrainSourceFilter		Filter to apply to the documents in the source path for training.
useLabelFile	boolean	False	Use label file for training a model.

TrainSourceFilter

Filter to apply to the documents in the source path for training.

Name	Type	Default value	Description
includeSubFolders	boolean	False	A flag to indicate if sub folders within the set of prefix folders will also need to be included when searching for content to be preprocessed.
prefix	string		A case-sensitive prefix string to filter documents in the source path for training. For example, when using a Azure storage blob Uri, use the prefix to restrict sub folders for training.