FormTrainingClient Class
- java.
lang. Object - com.
azure. ai. formrecognizer. training. FormTrainingClient
- com.
public final class FormTrainingClient
This class provides a synchronous client to connect to the Form Recognizer Azure Cognitive Service.
This client provides synchronous 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(String modelId, CopyAuthorization target) 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, DocumentModelAdministrationAsyncClient and DocumentModelAdministrationClient.
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 FormTrainingClient with DefaultAzureCredential
The following code sample demonstrates the creation of a FormTrainingClient, using the `DefaultAzureCredentialBuilder` to configure it.
FormTrainingClient client = new FormTrainingClientBuilder()
.endpoint("{endpoint}")
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
Further, see the code sample below to use AzureKeyCredential for client creation.
FormTrainingClient formTrainingClient = new FormTrainingClientBuilder()
.credential(new AzureKeyCredential("{key}"))
.endpoint("{endpoint}")
.buildClient();
Method Summary
Methods inherited from java.lang.Object
Method Details
beginCopyModel
public SyncPoller
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 SyncPoller
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
// 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:
Returns:
beginCreateComposedModel
public SyncPoller
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:
Returns:
beginCreateComposedModel
public SyncPoller
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:
Returns:
beginTraining
public SyncPoller
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:
Returns:
beginTraining
public SyncPoller
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:
Returns:
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:
deleteModelWithResponse
public Response
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:
Returns:
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:
getAccountPropertiesWithResponse
public Response
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:
Returns:
getCopyAuthorization
public CopyAuthorization getCopyAuthorization(String resourceId, String resourceRegion)
Generate authorization for copying a custom model into the target Form Recognizer resource.
Parameters:
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:
getCopyAuthorizationWithResponse
public Response
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"; 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:
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:
Returns:
getCustomModelWithResponse
public Response
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:
Returns:
getFormRecognizerClient
public FormRecognizerClient getFormRecognizerClient()
Creates a new FormRecognizerClient object. The new FormTrainingClient uses the same request policy pipeline as the FormTrainingClient.
Returns:
listCustomModels
public PagedIterable
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:
listCustomModels
public PagedIterable
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:
Returns: