FormTrainingClient Class

FormTrainingClient is the Form Recognizer interface to use for creating and managing custom models. It provides methods for training models on the forms you provide, as well as methods for viewing and deleting models, accessing account properties, copying models to another Form Recognizer resource, and composing models from a collection of existing models trained with labels.

Note

FormTrainingClient should be used with API versions <=v2.1.

To use API versions 2022-08-31 and up, instantiate a DocumentModelAdministrationClient.

Inheritance

azure.ai.formrecognizer.aio._form_base_client_async.FormRecognizerClientBaseAsync

FormTrainingClient

Constructor

FormTrainingClient(endpoint: str, credential: AzureKeyCredential | AsyncTokenCredential, **kwargs: Any)

Parameters

Name	Description
endpoint Required	str Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential Required	AzureKeyCredential or AsyncTokenCredential Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential from identity.

Keyword-Only Parameters

Name	Description
api_version	str or FormRecognizerApiVersion The API version of the service to use for requests. It defaults to API version v2.1. Setting to an older version may result in reduced feature compatibility. To use the latest supported API version and features, instantiate a DocumentModelAdministrationClient instead.

Examples

Creating the FormTrainingClient with an endpoint and API key.

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer.aio import FormTrainingClient
   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))

Creating the FormTrainingClient with a token credential.

   """DefaultAzureCredential will use the values from these environment
   variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
   """
   from azure.ai.formrecognizer.aio import FormTrainingClient
   from azure.identity.aio import DefaultAzureCredential

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   credential = DefaultAzureCredential()

   form_training_client = FormTrainingClient(endpoint, credential)

Methods

begin_copy_model	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 calling the get_copy_authorization method.
begin_create_composed_model	Creates a composed model from a collection of existing models that were trained with labels. A composed model allows multiple models to be called with a single model ID. When a document is submitted to be analyzed with a composed model ID, a classification step is first performed to route it to the correct custom model. New in version v2.1: The begin_create_composed_model client method
begin_training	Create and train a custom model. The request must include a training_files_url parameter that is an externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that a container URI (without SAS) is accepted only when the container is public or has a managed identity configured, see more about configuring managed identities to work with Form Recognizer here: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored. New in version v2.1: The model_name keyword argument
close	Close the FormTrainingClient session.
delete_model	Mark model for deletion. Model artifacts will be permanently removed within a predetermined period.
get_account_properties	Get information about the models on the form recognizer account.
get_copy_authorization	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 begin_copy_model.
get_custom_model	Get a description of a custom model, including the types of forms it can recognize, and the fields it will extract for each form type.
get_form_recognizer_client	Get an instance of a FormRecognizerClient from FormTrainingClient.
list_custom_models	List information for each model, including model id, model status, and when it was created and last modified.
send_request	Runs a network request using the client's existing pipeline. The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

begin_copy_model

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 calling the get_copy_authorization method.

async begin_copy_model(model_id: str, target: Dict[str, str | int], **kwargs: Any) -> AsyncLROPoller[CustomFormModelInfo]

Parameters

Name	Description
model_id Required	str Model identifier of the model to copy to target resource.
target Required	Dict[str, Union[str, int]] The copy authorization generated from the target resource's call to get_copy_authorization.

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AsyncLROPoller[CustomFormModelInfo]	An instance of an AsyncLROPoller. Call result() on the poller object to return a CustomFormModelInfo.

Exceptions

Type	Description
HttpResponseError

Examples

Copy a model from the source resource to the target resource

   source_client = FormTrainingClient(endpoint=source_endpoint, credential=AzureKeyCredential(source_key))

   async with source_client:
       poller = await source_client.begin_copy_model(
           model_id=source_model_id,
           target=target  # output from target client's call to get_copy_authorization()
       )
       copied_over_model = await poller.result()

       print("Model ID: {}".format(copied_over_model.model_id))
       print("Status: {}".format(copied_over_model.status))

begin_create_composed_model

Creates a composed model from a collection of existing models that were trained with labels.

A composed model allows multiple models to be called with a single model ID. When a document is submitted to be analyzed with a composed model ID, a classification step is first performed to route it to the correct custom model.

New in version v2.1: The begin_create_composed_model client method

async begin_create_composed_model(model_ids: List[str], **kwargs: Any) -> AsyncLROPoller[CustomFormModel]

Parameters

Name	Description
model_ids Required	list[str] List of model IDs to use in the composed model.

Keyword-Only Parameters

Name	Description
model_name	str An optional, user-defined name to associate with your model.
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AsyncLROPoller[CustomFormModel]	An instance of an AsyncLROPoller. Call result() on the poller object to return a CustomFormModel.

Exceptions

Type	Description
HttpResponseError

Examples

Create a composed model

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer.aio import FormTrainingClient

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   po_supplies = os.environ['PURCHASE_ORDER_OFFICE_SUPPLIES_SAS_URL_V2']
   po_equipment = os.environ['PURCHASE_ORDER_OFFICE_EQUIPMENT_SAS_URL_V2']
   po_furniture = os.environ['PURCHASE_ORDER_OFFICE_FURNITURE_SAS_URL_V2']
   po_cleaning_supplies = os.environ['PURCHASE_ORDER_OFFICE_CLEANING_SUPPLIES_SAS_URL_V2']

   form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   async with form_training_client:
       supplies_poller = await form_training_client.begin_training(
           po_supplies, use_training_labels=True, model_name="Purchase order - Office supplies"
       )
       equipment_poller = await form_training_client.begin_training(
           po_equipment, use_training_labels=True, model_name="Purchase order - Office Equipment"
       )
       furniture_poller = await form_training_client.begin_training(
           po_furniture, use_training_labels=True, model_name="Purchase order - Furniture"
       )
       cleaning_supplies_poller = await form_training_client.begin_training(
           po_cleaning_supplies, use_training_labels=True, model_name="Purchase order - Cleaning Supplies"
       )
       supplies_model = await supplies_poller.result()
       equipment_model = await equipment_poller.result()
       furniture_model = await furniture_poller.result()
       cleaning_supplies_model = await cleaning_supplies_poller.result()

       models_trained_with_labels = [
           supplies_model.model_id,
           equipment_model.model_id,
           furniture_model.model_id,
           cleaning_supplies_model.model_id
       ]

       poller = await form_training_client.begin_create_composed_model(
           models_trained_with_labels, model_name="Office Supplies Composed Model"
       )
       model = await poller.result()

   print("Office Supplies Composed Model Info:")
   print("Model ID: {}".format(model.model_id))
   print("Model name: {}".format(model.model_name))
   print("Is this a composed model?: {}".format(model.properties.is_composed_model))
   print("Status: {}".format(model.status))
   print("Composed model creation started on: {}".format(model.training_started_on))
   print("Creation completed on: {}".format(model.training_completed_on))

begin_training

Create and train a custom model. The request must include a training_files_url parameter that is an externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that a container URI (without SAS) is accepted only when the container is public or has a managed identity configured, see more about configuring managed identities to work with Form Recognizer here: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored.

New in version v2.1: The model_name keyword argument

async begin_training(training_files_url: str, use_training_labels: bool, **kwargs: Any) -> AsyncLROPoller[CustomFormModel]

Parameters

Name	Description
training_files_url Required	str An Azure Storage blob container's SAS URI. A container URI (without SAS) can be used if the container is public or has a managed identity configured. For more information on setting up a training data set, see: https://aka.ms/azsdk/formrecognizer/buildtrainingset.
use_training_labels Required	bool Whether to train with labels or not. Corresponding labeled files must exist in the blob container if set to True.

Keyword-Only Parameters

Name	Description
prefix	str A case-sensitive prefix string to filter documents in the source path for training. For example, when using an Azure storage blob URI, use the prefix to restrict sub folders for training.
include_subfolders	bool A flag to indicate if subfolders within the set of prefix folders will also need to be included when searching for content to be preprocessed. Not supported if training with labels.
model_name	str An optional, user-defined name to associate with your model.
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AsyncLROPoller[CustomFormModel]	An instance of an AsyncLROPoller. Call result() on the poller object to return a CustomFormModel.

Exceptions

Type	Description
HttpResponseError	Note that if the training fails, the exception is raised, but a model with an "invalid" status is still created. You can delete this model by calling
delete_model

Examples

Training a model (without labels) with your custom forms.

   from azure.ai.formrecognizer.aio import FormTrainingClient
   from azure.core.credentials import AzureKeyCredential

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   container_sas_url = os.environ["CONTAINER_SAS_URL_V2"]

   async with FormTrainingClient(
       endpoint, AzureKeyCredential(key)
   ) as form_training_client:

       poller = await form_training_client.begin_training(container_sas_url, use_training_labels=False)
       model = await poller.result()

       # Custom model information
       print("Model ID: {}".format(model.model_id))
       print("Status: {}".format(model.status))
       print("Model name: {}".format(model.model_name))
       print("Training started on: {}".format(model.training_started_on))
       print("Training completed on: {}".format(model.training_completed_on))

       print("Recognized fields:")
       # Looping through the submodels, which contains the fields they were trained on
       for submodel in model.submodels:
           print("...The submodel has form type '{}'".format(submodel.form_type))
           for name, field in submodel.fields.items():
               print("...The model found field '{}' to have label '{}'".format(
                   name, field.label
               ))

close

Close the FormTrainingClient session.

async close() -> None

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Exceptions

Type	Description
HttpResponseError

delete_model

Mark model for deletion. Model artifacts will be permanently removed within a predetermined period.

async delete_model(model_id: str, **kwargs: Any) -> None

Parameters

Name	Description
model_id Required	str Model identifier.

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError

Examples

Delete a custom model.

   await form_training_client.delete_model(model_id=custom_model.model_id)

   try:
       await form_training_client.get_custom_model(model_id=custom_model.model_id)
   except ResourceNotFoundError:
       print("Successfully deleted model with id {}".format(custom_model.model_id))

get_account_properties

Get information about the models on the form recognizer account.

async get_account_properties(**kwargs: Any) -> AccountProperties

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AccountProperties	Summary of models on account - custom model count, custom model limit.

Exceptions

Type	Description
HttpResponseError

Examples

Get properties for the form recognizer account.

   async with FormTrainingClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   ) as form_training_client:
       # First, we see how many custom models we have, and what our limit is
       account_properties = await form_training_client.get_account_properties()
       print("Our account has {} custom models, and we can have at most {} custom models\n".format(
           account_properties.custom_model_count, account_properties.custom_model_limit
       ))

get_copy_authorization

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 begin_copy_model.

async get_copy_authorization(resource_id: str, resource_region: str, **kwargs: Any) -> Dict[str, str | int]

Parameters

Name	Description
resource_id Required	str Azure Resource Id of the target Form Recognizer resource where the model will be copied to.
resource_region Required	str Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services. For example, 'westus', 'eastus' etc. See https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services for the regional availability of Cognitive Services.

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
Dict[str, Union[str, int]]	A dictionary with values for the copy authorization - "modelId", "accessToken", "resourceId", "resourceRegion", and "expirationDateTimeTicks".

Exceptions

Type	Description
HttpResponseError

Examples

Authorize the target resource to receive the copied model

   target_client = FormTrainingClient(endpoint=target_endpoint, credential=AzureKeyCredential(target_key))

   async with target_client:
       target = await target_client.get_copy_authorization(
           resource_region=target_region,
           resource_id=target_resource_id
       )
   # model ID that target client will use to access the model once copy is complete
   print("Model ID: {}".format(target["modelId"]))

get_custom_model

Get a description of a custom model, including the types of forms it can recognize, and the fields it will extract for each form type.

async get_custom_model(model_id: str, **kwargs: Any) -> CustomFormModel

Parameters

Name	Description
model_id Required	str Model identifier.

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
CustomFormModel	CustomFormModel

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError

Examples

Get a custom model with a model ID.

   custom_model = await form_training_client.get_custom_model(model_id=model_info.model_id)
   print("\nModel ID: {}".format(custom_model.model_id))
   print("Status: {}".format(custom_model.status))
   print("Model name: {}".format(custom_model.model_name))
   print("Is this a composed model?: {}".format(custom_model.properties.is_composed_model))
   print("Training started on: {}".format(custom_model.training_started_on))
   print("Training completed on: {}".format(custom_model.training_completed_on))

get_form_recognizer_client

Get an instance of a FormRecognizerClient from FormTrainingClient.

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
FormRecognizerClient	A FormRecognizerClient

Exceptions

Type	Description
HttpResponseError

list_custom_models

List information for each model, including model id, model status, and when it was created and last modified.

list_custom_models(**kwargs: Any) -> AsyncItemPaged[CustomFormModelInfo]

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AsyncItemPaged	AsyncItemPaged[CustomFormModelInfo]

Exceptions

Type	Description
HttpResponseError

Examples

List model information for each model on the account.

   custom_models = form_training_client.list_custom_models()

   print("We have models with the following IDs:")
   async for model in custom_models:
       print(model.model_id)

send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the base URL. The service API version used for the request is the same as the client's unless otherwise specified. Overriding the client's configured API version in relative URL is supported on client with API version 2022-08-31 and later. Overriding in absolute URL supported on client with any API version. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

async send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> AsyncHttpResponse

Parameters

Name	Description
request Required	HttpRequest The network request you want to make.

Keyword-Only Parameters

Name	Description
continuation_token	str A continuation token to restart a poller from a saved state.

Returns

Type	Description
AsyncHttpResponse	The response of your network call. Does not do error handling on your response.

Exceptions

Type	Description
HttpResponseError