FormTrainingAsyncClient Class
- java.
lang. Object - com.
azure. ai. formrecognizer. training. FormTrainingAsyncClient
- com.
public final class FormTrainingAsyncClient
This class provides an asynchronous client to connect to the Form Recognizer Azure Cognitive Service.
This client provides asynchronous methods to:
- Train a custom model: Train a custom model to analyze and extract data from forms and documents specific to your business using the beginTraining(String trainingFilesUrl, boolean useTrainingLabels) method.
- Copy custom model: Copy a custom Form Recognizer model to a target Form Recognizer resource using the beginCopyModel method.
- List custom models: Get information about all custom models using the getCustomModel(String modelId) and listCustomModels() methods respectively.
- 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 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();
Method Summary
Methods inherited from java.lang.Object
Method Details
beginCopyModel
public PollerFlux
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 resourceId, String resourceRegion) 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:
Returns:
beginCopyModel
public PollerFlux
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 resourceId, String resourceRegion) 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:
Returns:
beginCreateComposedModel
public PollerFlux
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:
Returns:
beginCreateComposedModel
public PollerFlux
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:
Returns:
beginTraining
public PollerFlux
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:
Returns:
beginTraining
public PollerFlux
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:
Returns:
deleteModel
public Mono
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:
Returns:
deleteModelWithResponse
public Mono<>
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:
Returns:
getAccountProperties
public Mono
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:
getAccountPropertiesWithResponse
public Mono<>
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:
getCopyAuthorization
public Mono
Generate authorization for copying a custom model into the target Form Recognizer resource.
Parameters:
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:
getCopyAuthorizationWithResponse
public Mono<>
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 modelId, CopyAuthorization target).
Parameters:
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:
getCustomModel
public Mono
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:
Returns:
getCustomModelWithResponse
public Mono<>
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:
Returns:
getFormRecognizerAsyncClient
public FormRecognizerAsyncClient getFormRecognizerAsyncClient()
Creates a new FormRecognizerAsyncClient object. The new FormTrainingAsyncClient
uses the same request policy pipeline as the FormTrainingAsyncClient
.
Returns:
listCustomModels
public PagedFlux
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: