Package com.azure.ai.formrecognizer.training

Class FormTrainingAsyncClient

java.lang.Object
com.azure.ai.formrecognizer.training.FormTrainingAsyncClient
public final class FormTrainingAsyncClient extends Object

This class provides an asynchronous client to connect to the Form Recognizer Azure Cognitive Service.

This client provides asynchronous methods to:

  1. Train a custom model: Train a custom model to analyze and extract data from forms and documents specific to your business using the beginTraining method.
  2. Copy custom model: Copy a custom Form Recognizer model to a target Form Recognizer resource using the beginCopyModel method.
  3. List custom models: Get information about all custom models using the getCustomModel and listCustomModels methods respectively.
  4. Polling and Callbacks: It includes mechanisms for polling the service to check the status of an analysis operation or registering callbacks to receive notifications when the analysis is complete.

Note: This client only supports FormRecognizerServiceVersion.V2_1 and lower. Recommended to use a newer service version, DocumentModelAdministrationClient and DocumentModelAdministrationAsyncClient.

Refer to the Migration guide to use API versions 2022-08-31 and up.

Service clients are the point of interaction for developers to use Azure Form Recognizer. FormTrainingClient is the synchronous service client and FormTrainingAsyncClient is the asynchronous service client. The examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the Azure Identity documentation".

Sample: Construct a FormTrainingAsyncClient with DefaultAzureCredential

The following code sample demonstrates the creation of a FormTrainingAsyncClient, using the `DefaultAzureCredentialBuilder` to configure it.

 FormTrainingAsyncClient client = new FormTrainingClientBuilder()
     .endpoint("{endpoint}")
     .credential(new DefaultAzureCredentialBuilder().build())
     .buildAsyncClient();

Further, see the code sample below to use AzureKeyCredential for client creation.

 FormTrainingAsyncClient formTrainingAsyncClient = new FormTrainingClientBuilder()
     .credential(new AzureKeyCredential("{key}"))
     .endpoint("{endpoint}")
     .buildAsyncClient();
See Also:

  • Method Details

    • getFormRecognizerAsyncClient

      public FormRecognizerAsyncClient getFormRecognizerAsyncClient()
      Creates a new FormRecognizerAsyncClient object. The new FormTrainingAsyncClient uses the same request policy pipeline as the FormTrainingAsyncClient.
      Returns:
      A new FormRecognizerAsyncClient object.

    • beginTraining

      public com.azure.core.util.polling.PollerFlux<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.

      See here for information on building your own training data set.

      Code sample

       String trainingFilesUrl = "{SAS-URL-of-your-container-in-blob-storage}";
 boolean useTrainingLabels = true;
 formTrainingAsyncClient.beginTraining(trainingFilesUrl, useTrainingLabels)
     // if training polling operation completed, retrieve the final result.
     .flatMap(AsyncPollResponse::getFinalResult)
     .subscribe(customFormModel -> {
         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 - source URL parameter that is an externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri).
      useTrainingLabels - boolean to specify the use of labeled files for training the model.
      Returns:
      A PollerFlux 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 a model with ModelStatus.INVALID is created.
      NullPointerException - If trainingFilesUrl is null.

    • beginTraining

      public com.azure.core.util.polling.PollerFlux<FormRecognizerOperationResult,CustomFormModel> beginTraining(String trainingFilesUrl, boolean useTrainingLabels, TrainingOptions trainingOptions)
      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.

      See here for information on building your own training data set.

      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(true).setPrefix("Invoice");

 formTrainingAsyncClient.beginTraining(trainingFilesUrl, true,
     new TrainingOptions()
         .setTrainingFileFilter(trainingFileFilter)
         .setPollInterval(Duration.ofSeconds(5)))
     // if training polling operation completed, retrieve the final result.
     .flatMap(AsyncPollResponse::getFinalResult)
     .subscribe(customFormModel -> {
         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).
      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.
      Returns:
      A PollerFlux 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 Mono<CustomFormModel> getCustomModel(String modelId)
      Get detailed information for a specified custom model id.

      Code sample

       String modelId = "{model_id}";
 formTrainingAsyncClient.getCustomModel(modelId).subscribe(customFormModel -> {
     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 Mono<com.azure.core.http.rest.Response<CustomFormModel>> getCustomModelWithResponse(String modelId)
      Get detailed information for a specified custom model id with Http response.

      Code sample

       String modelId = "{model_id}";
 formTrainingAsyncClient.getCustomModelWithResponse(modelId).subscribe(response -> {
     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("Form Type: %s Field Text: %s Field Accuracy: %f%n",
                     key, customFormModelField.getName(), customFormModelField.getAccuracy())));
 });
      Parameters:
      modelId - The UUID string format model identifier.
      Returns:
      A Response containing the requested model.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • getAccountProperties

      public Mono<AccountProperties> getAccountProperties()
      Get account information of the form recognizer account.

      Code sample

       formTrainingAsyncClient.getAccountProperties()
     .subscribe(accountProperties -> {
         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 details.

    • getAccountPropertiesWithResponse

      public Mono<com.azure.core.http.rest.Response<AccountProperties>> getAccountPropertiesWithResponse()
      Get account information of the form recognizer account with an Http response.

      Code sample

       formTrainingAsyncClient.getAccountPropertiesWithResponse()
     .subscribe(response -> {
         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: %d%n",
             accountProperties.getCustomModelLimit());
         System.out.printf("Current count of trained custom models: %d%n",
             accountProperties.getCustomModelCount());
     });
      Returns:
      A Response containing the requested account information details.

    • deleteModel

      public Mono<Void> deleteModel(String modelId)
      Deletes the specified custom model.

      Code sample

       String modelId = "{model_id}";
 formTrainingAsyncClient.deleteModel(modelId)
     .subscribe(ignored -> System.out.printf("Model Id: %s is deleted%n", modelId));
      Parameters:
      modelId - The UUID string format model identifier.
      Returns:
      An empty Mono.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • deleteModelWithResponse

      public Mono<com.azure.core.http.rest.Response<Void>> deleteModelWithResponse(String modelId)
      Deletes the specified custom model.

      Code sample

       String modelId = "{model_id}";
 formTrainingAsyncClient.deleteModelWithResponse(modelId)
     .subscribe(response -> {
         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.
      Returns:
      A Response containing the status code and HTTP headers.
      Throws:
      IllegalArgumentException - If modelId is null or empty.

    • listCustomModels

      public com.azure.core.http.rest.PagedFlux<CustomFormModelInfo> listCustomModels()
      List information for each model on the form recognizer account.

      Code sample

       formTrainingAsyncClient.listCustomModels()
     .subscribe(customModel ->
         System.out.printf("Model Id: %s, Model status: %s, Created on: %s, Last updated on: %s.%n",
             customModel.getModelId(),
             customModel.getStatus(),
             customModel.getTrainingStartedOn(),
             customModel.getTrainingCompletedOn()));
      Returns:
      PagedFlux of CustomFormModelInfo.

    • beginCopyModel

      public com.azure.core.util.polling.PollerFlux<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 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 getCopyAuthorization(String, String)
      Returns:
      A PollerFlux that polls the copy model operation until it has completed, has failed, or has been cancelled. The completed operation returns the copied model CustomFormModelInfo.
      Throws:
      FormRecognizerException - If copy operation fails and model with OperationStatus.FAILED is created.
      NullPointerException - If modelId, target is null.

    • beginCopyModel

      public com.azure.core.util.polling.PollerFlux<FormRecognizerOperationResult,CustomFormModelInfo> beginCopyModel(String modelId, CopyAuthorization target, Duration pollInterval)
      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 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,
         Duration.ofSeconds(5)))
     .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 getCopyAuthorization(String, String)
      pollInterval - Duration between each poll for the operation status. If none is specified, a default of 5 seconds is used.
      Returns:
      A PollerFlux that polls the copy model operation until it has completed, has failed, or has been cancelled. The completed operation returns the copied model CustomFormModelInfo.
      Throws:
      FormRecognizerException - If copy operation fails and model with OperationStatus.FAILED is created.
      NullPointerException - If modelId, target is null.

    • getCopyAuthorization

      public Mono<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.
      resourceRegion - Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services.

      Code sample

       String resourceId = "target-resource-Id";
 String resourceRegion = "target-resource-region";
 formTrainingAsyncClient.getCopyAuthorization(resourceId, resourceRegion)
     .subscribe(copyAuthorization ->
         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 that could be used to authorize copying model between resources.
      Throws:
      NullPointerException - If resourceId, resourceRegion is null.

    • getCopyAuthorizationWithResponse

      public Mono<com.azure.core.http.rest.Response<CopyAuthorization>> getCopyAuthorizationWithResponse(String resourceId, String resourceRegion)
      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 beginCopyModel(String, CopyAuthorization).
      Parameters:
      resourceId - Azure Resource Id of the target Form Recognizer resource where the model will be copied to.
      resourceRegion - Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services.

      Code sample

       String resourceId = "target-resource-Id";
 String resourceRegion = "target-resource-region";
 formTrainingAsyncClient.getCopyAuthorizationWithResponse(resourceId, resourceRegion)
     .subscribe(copyAuthorization ->
         System.out.printf("Copy Authorization response status: %s, for model id: %s, access token: %s, "
                 + "expiration time: %s, target resource Id; %s, target resource region: %s%n",
         copyAuthorization.getStatusCode(),
         copyAuthorization.getValue().getModelId(),
         copyAuthorization.getValue().getAccessToken(),
         copyAuthorization.getValue().getExpiresOn(),
         copyAuthorization.getValue().getResourceId(),
         copyAuthorization.getValue().getResourceRegion()
     ));
      Returns:
      A Response containing the CopyAuthorization that could be used to authorize copying model between resources.
      Throws:
      NullPointerException - If resourceId, resourceRegion is null.

    • beginCreateComposedModel

      public com.azure.core.util.polling.PollerFlux<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";
 formTrainingAsyncClient.beginCreateComposedModel(Arrays.asList(labeledModelId1, labeledModelId2))
     // if training polling operation completed, retrieve the final result.
     .flatMap(AsyncPollResponse::getFinalResult)
     .subscribe(customFormModel -> {
         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 PollerFlux that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the created 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.PollerFlux<FormRecognizerOperationResult,CustomFormModel> beginCreateComposedModel(List<String> modelIds, CreateComposedModelOptions createComposedModelOptions)
      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";
 formTrainingAsyncClient.beginCreateComposedModel(Arrays.asList(labeledModelId1, labeledModelId2),
     new CreateComposedModelOptions()
         .setModelName("my composed model name"))
     .setPollInterval(Duration.ofSeconds(5))
     // if training polling operation completed, retrieve the final result.
     .flatMap(AsyncPollResponse::getFinalResult)
     .subscribe(customFormModel -> {
         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.
      Returns:
      A PollerFlux that polls the create composed model operation until it has completed, has failed, or has been cancelled. The completed operation returns the copied model CustomFormModel.
      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.