com.azure.ai.formrecognizer.training

Class FormTrainingClient

java.lang.Object

com.azure.ai.formrecognizer.training.FormTrainingClient

public final class FormTrainingClient
extends Object

This class provides a synchronous client that contains model management the operations that apply to Azure Form Recognizer. Operations allowed by the client are creating, training of custom models, deleting models, listing models and getting subscription account information.

Instantiating a synchronous Form Training Client

FormTrainingClient formTrainingClient = new FormTrainingClientBuilder().buildClient();

See Also:

FormTrainingClientBuilder, FormTrainingClient

Method Summary

Modifier and Type	Method and Description
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModelInfo>	beginCopyModel(String modelId, CopyAuthorization target) Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModelInfo>	beginCopyModel(String modelId, CopyAuthorization target, Duration pollInterval, com.azure.core.util.Context context) Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel>	beginCreateComposedModel(List<String> modelIds) Create a composed model from the provided list of existing models in the account.
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel>	beginCreateComposedModel(List<String> modelIds, CreateComposedModelOptions createComposedModelOptions, com.azure.core.util.Context context) Create a composed model from the provided list of existing models in the account.
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel>	beginTraining(String trainingFilesUrl, boolean useTrainingLabels) Create and train a custom model.
com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel>	beginTraining(String trainingFilesUrl, boolean useTrainingLabels, TrainingOptions trainingOptions, com.azure.core.util.Context context) Create and train a custom model.
void	deleteModel(String modelId) Deletes the specified custom model.
com.azure.core.http.rest.Response<Void>	deleteModelWithResponse(String modelId, com.azure.core.util.Context context) Deletes the specified custom model.
AccountProperties	getAccountProperties() Get account information of the form recognizer account.
com.azure.core.http.rest.Response<AccountProperties>	getAccountPropertiesWithResponse(com.azure.core.util.Context context) Get account information of the form recognizer account with an Http response and a specified Context.
CopyAuthorization	getCopyAuthorization(String resourceId, String resourceRegion) Generate authorization for copying a custom model into the target Form Recognizer resource.
com.azure.core.http.rest.Response<CopyAuthorization>	getCopyAuthorizationWithResponse(String resourceId, String resourceRegion, com.azure.core.util.Context context) Generate authorization for copying a custom model into the target Form Recognizer resource.
CustomFormModel	getCustomModel(String modelId) Get detailed information for a specified custom model id.
com.azure.core.http.rest.Response<CustomFormModel>	getCustomModelWithResponse(String modelId, com.azure.core.util.Context context) Get detailed information for a specified custom model id.
FormRecognizerClient	getFormRecognizerClient() Creates a new FormRecognizerClient object.
com.azure.core.http.rest.PagedIterable<CustomFormModelInfo>	listCustomModels() List information for each model on the form recognizer account.
com.azure.core.http.rest.PagedIterable<CustomFormModelInfo>	listCustomModels(com.azure.core.util.Context context) List information for each model on the form recognizer account with an Http response and a specified Context.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFormRecognizerClient

public FormRecognizerClient getFormRecognizerClient()

Creates a new FormRecognizerClient object. The new FormTrainingClient uses the same request policy pipeline as the FormTrainingClient.

Returns:

A new FormRecognizerClient object.

beginTraining

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel> beginTraining(String trainingFilesUrl,
                                                                                                           boolean useTrainingLabels)

Create and train a custom model.

Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff'. Other type of content is ignored.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

String trainingFilesUrl = "{SAS-URL-of-your-container-in-blob-storage}";
boolean useTrainingLabels = true;
CustomFormModel customFormModel =
    formTrainingClient.beginTraining(trainingFilesUrl, useTrainingLabels).getFinalResult();
System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Form Type: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

trainingFilesUrl - an externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri). For instructions on setting up forms for training in an Azure Storage Blob Container, see here.

useTrainingLabels - boolean to specify the use of labeled files for training the model.

Returns:

A SyncPoller that polls the training model operation until it has completed, has failed, or has been cancelled. The completed operation returns the trained custom form model.

Throws:

FormRecognizerException - If training fails and model with ModelStatus.INVALID is created.

NullPointerException - If trainingFilesUrl is null.

beginTraining

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel> beginTraining(String trainingFilesUrl,
                                                                                                           boolean useTrainingLabels,
                                                                                                           TrainingOptions trainingOptions,
                                                                                                           com.azure.core.util.Context context)

Create and train a custom model. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff'. Other type of content is ignored.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

String trainingFilesUrl = "{SAS-URL-of-your-container-in-blob-storage}";
TrainingFileFilter trainingFileFilter = new TrainingFileFilter().setSubfoldersIncluded(false).setPrefix("Invoice");
boolean useTrainingLabels = true;

CustomFormModel customFormModel = formTrainingClient.beginTraining(trainingFilesUrl, useTrainingLabels,
    new TrainingOptions()
        .setTrainingFileFilter(trainingFileFilter)
        .setPollInterval(Duration.ofSeconds(5)), Context.NONE)
    .getFinalResult();

System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Form Type: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

trainingFilesUrl - an externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri). For instructions on setting up forms for training in an Azure Storage Blob Container, see here.

useTrainingLabels - boolean to specify the use of labeled files for training the model.

trainingOptions - The additional configurable options that may be passed when training a model.

context - Additional context that is passed through the HTTP pipeline during the service call.

Returns:

A SyncPoller that polls the training model operation until it has completed, has failed, or has been cancelled. The completed operation returns the trained custom form model.

Throws:

FormRecognizerException - If training fails and model with ModelStatus.INVALID is created.

NullPointerException - If trainingFilesUrl is null.

getCustomModel

public CustomFormModel getCustomModel(String modelId)

Get detailed information for a specified custom model id.

Code sample

String modelId = "{model_id}";
CustomFormModel customFormModel = formTrainingClient.getCustomModel(modelId);
System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Form Type: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

modelId - The UUID string format model identifier.

Returns:

The detailed information for the specified model.

Throws:

IllegalArgumentException - If modelId is null or empty.

getCustomModelWithResponse

public com.azure.core.http.rest.Response<CustomFormModel> getCustomModelWithResponse(String modelId,
                                                                                     com.azure.core.util.Context context)

Get detailed information for a specified custom model id.

Code sample

String modelId = "{model_id}";
Response<CustomFormModel> response = formTrainingClient.getCustomModelWithResponse(modelId, Context.NONE);
System.out.printf("Response Status Code: %d.", response.getStatusCode());
CustomFormModel customFormModel = response.getValue();
System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Field: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

modelId - The UUID string format model identifier.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

The detailed information for the specified model.

Throws:

IllegalArgumentException - If modelId is null or empty.

getAccountProperties

public AccountProperties getAccountProperties()

Get account information of the form recognizer account.

Code sample

AccountProperties accountProperties = formTrainingClient.getAccountProperties();
System.out.printf("Max number of models that can be trained for this account: %d%n",
    accountProperties.getCustomModelLimit());
System.out.printf("Current count of trained custom models: %d%n", accountProperties.getCustomModelCount());

Returns:

The requested account information of the form recognizer account.

getAccountPropertiesWithResponse

public com.azure.core.http.rest.Response<AccountProperties> getAccountPropertiesWithResponse(com.azure.core.util.Context context)

Get account information of the form recognizer account with an Http response and a specified Context.

Code sample

Response<AccountProperties> response = formTrainingClient.getAccountPropertiesWithResponse(Context.NONE);
System.out.printf("Response Status Code: %d.", response.getStatusCode());
AccountProperties accountProperties = response.getValue();
System.out.printf("Max number of models that can be trained for this account: %s%n",
    accountProperties.getCustomModelLimit());
System.out.printf("Current count of trained custom models: %d%n", accountProperties.getCustomModelCount());

Parameters:

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

The requested account information of the form recognizer account.

deleteModel

public void deleteModel(String modelId)

Deletes the specified custom model.

Code sample

String modelId = "{model_id}";
formTrainingClient.deleteModel(modelId);
System.out.printf("Model Id: %s is deleted.%n", modelId);

Parameters:

modelId - The UUID string format model identifier.

Throws:

IllegalArgumentException - If modelId is null or empty.

deleteModelWithResponse

public com.azure.core.http.rest.Response<Void> deleteModelWithResponse(String modelId,
                                                                       com.azure.core.util.Context context)

Deletes the specified custom model.

Code sample

String modelId = "{model_id}";
Response<Void> response = formTrainingClient.deleteModelWithResponse(modelId, Context.NONE);
System.out.printf("Response Status Code: %d.", response.getStatusCode());
System.out.printf("Model Id: %s is deleted.%n", modelId);

Parameters:

modelId - The UUID string format model identifier.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response containing containing status code and HTTP headers.

Throws:

IllegalArgumentException - If modelId is null or empty.

listCustomModels

public com.azure.core.http.rest.PagedIterable<CustomFormModelInfo> listCustomModels()

List information for each model on the form recognizer account.

Code sample

formTrainingClient.listCustomModels()
    .forEach(customModel ->
        System.out.printf("Model Id: %s, Model status: %s, Training started on: %s, Training completed on: %s.%n",
            customModel.getModelId(),
            customModel.getStatus(),
            customModel.getTrainingStartedOn(),
            customModel.getTrainingCompletedOn())
    );

Returns:

PagedIterable of CustomFormModelInfo custom form model information.

listCustomModels

public com.azure.core.http.rest.PagedIterable<CustomFormModelInfo> listCustomModels(com.azure.core.util.Context context)

List information for each model on the form recognizer account with an Http response and a specified Context.

Code sample

formTrainingClient.listCustomModels(Context.NONE)
    .forEach(customModel ->
        System.out.printf("Model Id: %s, Model status: %s, Training started on: %s, Training completed on: %s.%n",
            customModel.getModelId(),
            customModel.getStatus(),
            customModel.getTrainingStartedOn(),
            customModel.getTrainingCompletedOn())
    );

Parameters:

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

PagedIterable of CustomFormModelInfo custom form model information.

beginCopyModel

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModelInfo> beginCopyModel(String modelId,
                                                                                                                CopyAuthorization target)

Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.

This should be called with the source Form Recognizer resource (with the model that is intended to be copied). The target parameter should be supplied from the target resource's output from FormTrainingAsyncClient.getCopyAuthorization(String, String) method.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

String resourceId = "target-resource-Id";
String resourceRegion = "target-resource-region";
String copyModelId = "copy-model-Id";
formTrainingAsyncClient.getCopyAuthorization(resourceId, resourceRegion)
    .flatMapMany(copyAuthorization -> formTrainingAsyncClient.beginCopyModel(copyModelId, copyAuthorization))
    .flatMap(AsyncPollResponse::getFinalResult)
    .subscribe(customFormModelInfo ->
        System.out.printf("Copied model has model Id: %s, model status: %s, training started on: %s,"
            + " training completed on: %s.%n",
        customFormModelInfo.getModelId(),
        customFormModelInfo.getStatus(),
        customFormModelInfo.getTrainingStartedOn(),
        customFormModelInfo.getTrainingCompletedOn()));

Parameters:

modelId - Model identifier of the model to copy to the target Form Recognizer resource

target - the copy authorization to the target Form Recognizer resource. The copy authorization can be generated from the target resource's call to FormTrainingClient.getCopyAuthorization(String, String)

Returns:

A SyncPoller that polls the copy model operation until it has completed, has failed, or has been cancelled.

beginCopyModel

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModelInfo> beginCopyModel(String modelId,
                                                                                                                CopyAuthorization target,
                                                                                                                Duration pollInterval,
                                                                                                                com.azure.core.util.Context context)

Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource.

This should be called with the source Form Recognizer resource (with the model that is intended to be copied). The target parameter should be supplied from the target resource's output from FormTrainingClient.getCopyAuthorization(String, String) method.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

// The resource to copy model to
String resourceId = "target-resource-Id";
String resourceRegion = "target-resource-region";
// The Id of the model to be copied
String copyModelId = "copy-model-Id";

CopyAuthorization copyAuthorization = targetFormTrainingClient.getCopyAuthorization(resourceId,
    resourceRegion);
formTrainingClient.beginCopyModel(copyModelId, copyAuthorization, Duration.ofSeconds(5), Context.NONE)
    .waitForCompletion();
CustomFormModel modelCopy = targetFormTrainingClient.getCustomModel(copyAuthorization.getModelId());
System.out.printf("Copied model has model Id: %s, model status: %s, was requested on: %s,"
        + " transfer completed on: %s.%n",
    modelCopy.getModelId(),
    modelCopy.getModelStatus(),
    modelCopy.getTrainingStartedOn(),
    modelCopy.getTrainingCompletedOn());

Parameters:

modelId - Model identifier of the model to copy to the target Form Recognizer resource

target - the copy authorization to the target Form Recognizer resource. The copy authorization can be generated from the target resource's call to FormTrainingClient.getCopyAuthorization(String, String)

pollInterval - Duration between each poll for the operation status. If none is specified, a default of 5 seconds is used.

context - Additional context that is passed through the HTTP pipeline during the service call.

Returns:

A SyncPoller that polls the copy model operation until it has completed, has failed, or has been cancelled.

getCopyAuthorization

public CopyAuthorization getCopyAuthorization(String resourceId,
                                              String resourceRegion)

Generate authorization for copying a custom model into the target Form Recognizer resource.

Parameters:

resourceId - Azure Resource Id of the target Form Recognizer resource where the model will be copied to. This information can be found in the 'Properties' section of the Form Recognizer resource in the Azure Portal.

resourceRegion - Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services. This information can be found in the 'Keys and Endpoint' section of the Form Recognizer resource in the Azure Portal.

Code sample

String resourceId = "target-resource-Id";
String resourceRegion = "target-resource-region";
CopyAuthorization copyAuthorization = formTrainingClient.getCopyAuthorization(resourceId, resourceRegion);
System.out.printf("Copy Authorization for model id: %s, access token: %s, expiration time: %s, "
        + "target resource Id; %s, target resource region: %s%n",
    copyAuthorization.getModelId(),
    copyAuthorization.getAccessToken(),
    copyAuthorization.getExpiresOn(),
    copyAuthorization.getResourceId(),
    copyAuthorization.getResourceRegion()
);

Returns:

The CopyAuthorization

getCopyAuthorizationWithResponse

public com.azure.core.http.rest.Response<CopyAuthorization> getCopyAuthorizationWithResponse(String resourceId,
                                                                                             String resourceRegion,
                                                                                             com.azure.core.util.Context context)

Generate authorization for copying a custom model into the target Form Recognizer resource. This should be called by the target resource (where the model will be copied to) and the output can be passed as the target parameter into FormTrainingAsyncClient.beginCopyModel(String, CopyAuthorization).

Parameters:

resourceId - Azure Resource Id of the target Form Recognizer resource where the model will be copied to. This information can be found in the 'Properties' section of the Form Recognizer resource in the Azure Portal.

resourceRegion - Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services.This information can be found in the 'Keys and Endpoint' section of the Form Recognizer resource in the Azure Portal.

context - Additional context that is passed through the Http pipeline during the service call.

Code sample

String resourceId = "target-resource-Id";
String resourceRegion = "target-resource-region";
Response<CopyAuthorization> copyAuthorizationResponse =
    formTrainingClient.getCopyAuthorizationWithResponse(resourceId, resourceRegion, Context.NONE);
System.out.printf("Copy Authorization operation returned with status: %s",
    copyAuthorizationResponse.getStatusCode());
CopyAuthorization copyAuthorization = copyAuthorizationResponse.getValue();
System.out.printf("Copy model id: %s, access token: %s, expiration time: %s, "
        + "target resource Id; %s, target resource region: %s%n",
    copyAuthorization.getModelId(),
    copyAuthorization.getAccessToken(),
    copyAuthorization.getExpiresOn(),
    copyAuthorization.getResourceId(),
    copyAuthorization.getResourceRegion()
);

Returns:

A Response containing the CopyAuthorization

beginCreateComposedModel

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel> beginCreateComposedModel(List<String> modelIds)

Create a composed model from the provided list of existing models in the account.

This operations fails if the list consists of an invalid, non-existing model Id or duplicate Ids. This operation is currently only supported for custom models trained using labels.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

String labeledModelId1 = "5f21ab8d-71a6-42d8-9856-ef5985c486a8";
String labeledModelId2 = "d7b0904c-841f-46f9-a9f4-3f2273eef7c9";
final CustomFormModel customFormModel
    = formTrainingClient.beginCreateComposedModel(Arrays.asList(labeledModelId1, labeledModelId2))
    .getFinalResult();
System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
System.out.printf("Is this a composed model: %s%n",
    customFormModel.getCustomModelProperties().isComposed());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Form type: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

modelIds - The list of models Ids to form the composed model.

Returns:

A SyncPoller that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the composed model.

Throws:

FormRecognizerException - If create composed model operation fails and model with OperationStatus.FAILED is created.

NullPointerException - If the list of modelIds is null or empty.

beginCreateComposedModel

public com.azure.core.util.polling.SyncPoller<FormRecognizerOperationResult,CustomFormModel> beginCreateComposedModel(List<String> modelIds,
                                                                                                                      CreateComposedModelOptions createComposedModelOptions,
                                                                                                                      com.azure.core.util.Context context)

Create a composed model from the provided list of existing models in the account.

This operations fails if the list consists of an invalid, non-existing model Id or duplicate Ids. This operation is currently only supported for custom models trained using labels.

The service does not support cancellation of the long running operation and returns with an error message indicating absence of cancellation support.

Code sample

String labeledModelId1 = "5f21ab8d-71a6-42d8-9856-ef5985c486a8";
String labeledModelId2 = "d7b0904c-841f-46f9-a9f4-3f2273eef7c9";
final CustomFormModel customFormModel =
    formTrainingClient.beginCreateComposedModel(Arrays.asList(labeledModelId1, labeledModelId2),
        new CreateComposedModelOptions()
            .setModelName("my composed model name"),
        Context.NONE)
        .setPollInterval(Duration.ofSeconds(5))
        .getFinalResult();
System.out.printf("Model Id: %s%n", customFormModel.getModelId());
System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
System.out.printf("Model display name: %s%n", customFormModel.getModelName());
System.out.printf("Is this a composed model: %s%n",
    customFormModel.getCustomModelProperties().isComposed());
customFormModel.getSubmodels()
    .forEach(customFormSubmodel -> customFormSubmodel.getFields()
        .forEach((key, customFormModelField) ->
            System.out.printf("Form type: %s Field Text: %s Field Accuracy: %f%n",
                key, customFormModelField.getName(), customFormModelField.getAccuracy())));

Parameters:

modelIds - The list of models Ids to form the composed model.

createComposedModelOptions - The configurable options to pass when creating a composed model.

context - Additional context that is passed through the HTTP pipeline during the service call.

Returns:

A SyncPoller that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the composed model.

Throws:

FormRecognizerException - If create composed model operation fails and model with OperationStatus.FAILED is created.

NullPointerException - If the list of modelIds is null or empty.