DocumentModelAdministrationClient Class

DocumentModelAdministrationClient is the Form Recognizer interface to use for building and managing models.

It provides methods for building models, as well as methods for viewing and deleting models, viewing document model operations, accessing account information, copying models to another Form Recognizer resource, and composing a new model from a collection of existing models.

Note

DocumentModelAdministrationClient should be used with API versions

2021-09-30-preview and up. To use API versions <=v2.1, instantiate a FormTrainingClient.

New in version 2021-09-30-preview: The DocumentModelAdministrationClient and its client methods.

Inheritance

azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase

DocumentModelAdministrationClient

Constructor

DocumentModelAdministrationClient(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)

Parameters

endpoint

str

Required

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).

credential

AzureKeyCredential or TokenCredential

Required

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.

api_version

str or DocumentAnalysisApiVersion

The API version of the service to use for requests. It defaults to the latest service version. Setting to an older version may result in reduced feature compatibility. To use API versions <=v2.1, instantiate a FormTrainingClient.

Examples

Creating the DocumentModelAdministrationClient with an endpoint and API key.

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import DocumentModelAdministrationClient

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

   document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))

Creating the DocumentModelAdministrationClient 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 import DocumentModelAdministrationClient
   from azure.identity import DefaultAzureCredential

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

   document_model_admin_client = DocumentModelAdministrationClient(endpoint, credential)

Methods

begin_build_model	Build a custom model. The request must include a source 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 built 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 v2022-01-30-preview: The required build_mode parameter and tags keyword argument
begin_copy_model_to	Copy a 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. 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 v2022-01-30-preview: The tags keyword argument
close	Close the DocumentModelAdministrationClient session.
delete_model	Delete a custom model.
get_account_info	Get information about the models under the Form Recognizer resource.
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_to. New in version v2022-01-30-preview: The tags keyword argument
get_document_analysis_client	Get an instance of a DocumentAnalysisClient from DocumentModelAdministrationClient.
get_model	Get a model by its ID.
get_operation	Get a document model operation by its ID. Get a document model operation associated with the Form Recognizer resource. Note that operation information only persists for 24 hours. If the operation was successful, the document model can be accessed using the get_model or list_models APIs.
list_models	List information for each model, including its model ID, description, and when it was created.
list_operations	List information for each document model operation. Lists all document model operations associated with the Form Recognizer resource. Note that operation information only persists for 24 hours. If the operation was successful, the document model can be accessed using the get_model or list_models APIs.

begin_build_model

Build a custom model.

The request must include a source 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 built 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 v2022-01-30-preview: The required build_mode parameter and tags keyword argument

begin_build_model(source: str, build_mode: Union[str, azure.ai.formrecognizer._models.DocumentBuildMode], **kwargs: Any) -> azure.ai.formrecognizer._polling.DocumentModelAdministrationLROPoller[azure.ai.formrecognizer._models.DocumentModel]

Parameters

source

str

Required

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.

build_mode

str or DocumentBuildMode

Required

The custom model build mode. Possible values include: "template", "neural". For more information about build modes, see: https://aka.ms/azsdk/formrecognizer/buildmode.

model_id

str

A unique ID for your model. If not specified, a model ID will be created for you.

description

str

An optional description to add to the model.

prefix

str

A case-sensitive prefix string to filter documents in the source path. For example, when using an Azure storage blob URI, use the prefix to restrict sub folders. prefix should end in '/' to avoid cases where filenames share the same prefix.

tags

dict[str, str]

List of user defined key-value tag attributes associated with the model.

continuation_token

str

A continuation token to restart a poller from a saved state.

Returns

An instance of an DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Exceptions

HttpResponseError

Examples

Building a model from training files.

   from azure.ai.formrecognizer import DocumentModelAdministrationClient, DocumentBuildMode
   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"]

   document_model_admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential(key))
   poller = document_model_admin_client.begin_build_model(
       container_sas_url, DocumentBuildMode.TEMPLATE, description="my model description"
   )
   model = poller.result()

   print("Model ID: {}".format(model.model_id))
   print("Description: {}".format(model.description))
   print("Model created on: {}\n".format(model.created_on))
   print("Doc types the model can recognize:")
   for name, doc_type in model.doc_types.items():
       print("\nDoc Type: '{}' built with '{}' mode which has the following fields:".format(name, doc_type.build_mode))
       for field_name, field in doc_type.field_schema.items():
           print("Field: '{}' has type '{}' and confidence score {}".format(
               field_name, field["type"], doc_type.field_confidence[field_name]
           ))

begin_copy_model_to

Copy a 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_copy_model_to(model_id: str, target: Dict, **kwargs: Any) -> azure.ai.formrecognizer._polling.DocumentModelAdministrationLROPoller[azure.ai.formrecognizer._models.DocumentModel]

Parameters

model_id

str

Required

Model identifier of the model to copy to target resource.

target

dict

Required

The copy authorization generated from the target resource's call to get_copy_authorization.

continuation_token

str

A continuation token to restart a poller from a saved state.

Returns

An instance of a DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Exceptions

HttpResponseError

begin_create_composed_model

Creates a composed model from a collection of existing models.

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 v2022-01-30-preview: The tags keyword argument

begin_create_composed_model(component_model_ids: List[str], **kwargs: Any) -> azure.ai.formrecognizer._polling.DocumentModelAdministrationLROPoller[azure.ai.formrecognizer._models.DocumentModel]

Parameters

component_model_ids

list[str]

Required

List of model IDs to use in the composed model.

model_id

str

A unique ID for your composed model. If not specified, a model ID will be created for you.

description

str

An optional description to add to the model.

tags

dict[str, str]

List of user defined key-value tag attributes associated with the model.

continuation_token

str

A continuation token to restart a poller from a saved state.

Returns

An instance of an DocumentModelAdministrationLROPoller. Call result() on the poller object to return a DocumentModel.

Return type

DocumentModelAdministrationLROPoller[DocumentModel]

Exceptions

HttpResponseError

Examples

Creating a composed model with existing models.

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import DocumentModelAdministrationClient, DocumentBuildMode

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   po_supplies = os.environ['PURCHASE_ORDER_OFFICE_SUPPLIES_SAS_URL']
   po_equipment = os.environ['PURCHASE_ORDER_OFFICE_EQUIPMENT_SAS_URL']
   po_furniture = os.environ['PURCHASE_ORDER_OFFICE_FURNITURE_SAS_URL']
   po_cleaning_supplies = os.environ['PURCHASE_ORDER_OFFICE_CLEANING_SUPPLIES_SAS_URL']

   document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   supplies_poller = document_model_admin_client.begin_build_model(
       po_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Office supplies"
   )
   equipment_poller = document_model_admin_client.begin_build_model(
       po_equipment, DocumentBuildMode.TEMPLATE, description="Purchase order-Office Equipment"
   )
   furniture_poller = document_model_admin_client.begin_build_model(
       po_furniture, DocumentBuildMode.TEMPLATE, description="Purchase order-Furniture"
   )
   cleaning_supplies_poller = document_model_admin_client.begin_build_model(
       po_cleaning_supplies, DocumentBuildMode.TEMPLATE, description="Purchase order-Cleaning Supplies"
   )
   supplies_model = supplies_poller.result()
   equipment_model = equipment_poller.result()
   furniture_model = furniture_poller.result()
   cleaning_supplies_model = cleaning_supplies_poller.result()

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

   poller = document_model_admin_client.begin_create_composed_model(
       purchase_order_models, description="Office Supplies Composed Model"
   )
   model = poller.result()

   print("Office Supplies Composed Model Info:")
   print("Model ID: {}".format(model.model_id))
   print("Description: {}".format(model.description))
   print("Model created on: {}\n".format(model.created_on))
   print("Doc types the model can recognize:")
   for name, doc_type in model.doc_types.items():
       print("\nDoc Type: '{}' which has the following fields:".format(name))
       for field_name, field in doc_type.field_schema.items():
           print("Field: '{}' has type '{}' and confidence score {}".format(
               field_name, field["type"], doc_type.field_confidence[field_name]
           ))

close

Close the DocumentModelAdministrationClient session.

close() -> None

Exceptions

HttpResponseError

delete_model

Delete a custom model.

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

Parameters

model_id

str

Required

Model identifier.

Return type

None

Exceptions

HttpResponseError

ResourceNotFoundError

Examples

Delete a model.

   document_model_admin_client.delete_model(model_id=my_model.model_id)

   try:
       document_model_admin_client.get_model(model_id=my_model.model_id)
   except ResourceNotFoundError:
       print("Successfully deleted model with ID {}".format(my_model.model_id))

get_account_info

Get information about the models under the Form Recognizer resource.

get_account_info(**kwargs: Any) -> azure.ai.formrecognizer._models.AccountInfo

Returns

Summary of models under the resource - model count and limit.

Return type

AccountInfo

Exceptions

HttpResponseError

Examples

Get model counts and limits under the Form Recognizer resource.

   document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

   account_info = document_model_admin_client.get_account_info()
   print("Our account has {} custom models, and we can have at most {} custom models\n".format(
       account_info.document_model_count, account_info.document_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_to.

New in version v2022-01-30-preview: The tags keyword argument

get_copy_authorization(**kwargs: Any) -> Dict[str, str]

Parameters

model_id

str

A unique ID for your copied model. If not specified, a model ID will be created for you.

description

str

An optional description to add to the model.

tags

dict[str, str]

List of user defined key-value tag attributes associated with the model.

Returns

A dictionary with values necessary for the copy authorization.

Return type

<xref:Dict>[str, str]

Exceptions

HttpResponseError

get_document_analysis_client

Get an instance of a DocumentAnalysisClient from DocumentModelAdministrationClient.

get_document_analysis_client(**kwargs: Any) -> azure.ai.formrecognizer._document_analysis_client.DocumentAnalysisClient

Returns

A DocumentAnalysisClient

Return type

DocumentAnalysisClient

Exceptions

HttpResponseError

get_model

Get a model by its ID.

get_model(model_id: str, **kwargs: Any) -> azure.ai.formrecognizer._models.DocumentModel

Parameters

model_id

str

Required

Model identifier.

Returns

DocumentModel

Return type

DocumentModel

Exceptions

HttpResponseError

ResourceNotFoundError

Examples

Get a model by its ID.

   my_model = document_model_admin_client.get_model(model_id=model.model_id)
   print("\nModel ID: {}".format(my_model.model_id))
   print("Description: {}".format(my_model.description))
   print("Model created on: {}".format(my_model.created_on))

get_operation

Get a document model operation by its ID.

Get a document model operation associated with the Form Recognizer resource. Note that operation information only persists for 24 hours. If the operation was successful, the document model can be accessed using the get_model or list_models APIs.

get_operation(operation_id: str, **kwargs: Any) -> azure.ai.formrecognizer._models.ModelOperation

Parameters

operation_id

str

Required

The operation ID.

Returns

ModelOperation

Return type

ModelOperation

Exceptions

HttpResponseError

Examples

Get a document model operation by its ID.

   # Get an operation by ID
   if operations:
       print("\nGetting operation info by ID: {}".format(operations[0].operation_id))
       operation_info = document_model_admin_client.get_operation(operations[0].operation_id)
       if operation_info.status == "succeeded":
           print("My {} operation is completed.".format(operation_info.kind))
           result = operation_info.result
           print("Model ID: {}".format(result.model_id))
       elif operation_info.status == "failed":
           print("My {} operation failed.".format(operation_info.kind))
           error = operation_info.error
           print("{}: {}".format(error.code, error.message))
       else:
           print("My operation status is {}".format(operation_info.status))
   else:
       print("No operations found.")

list_models

List information for each model, including its model ID, description, and when it was created.

list_models(**kwargs: Any) -> azure.core.paging.ItemPaged[azure.ai.formrecognizer._models.DocumentModelInfo]

Returns

Pageable of DocumentModelInfo.

Return type

ItemPaged[DocumentModelInfo]

Exceptions

HttpResponseError

Examples

List all models that were built successfully under the Form Recognizer resource.

   models = document_model_admin_client.list_models()

   print("We have the following 'ready' models with IDs and descriptions:")
   for model in models:
       print("{} | {}".format(model.model_id, model.description))

list_operations

List information for each document model operation.

Lists all document model operations associated with the Form Recognizer resource. Note that operation information only persists for 24 hours. If the operation was successful, the document model can be accessed using the get_model or list_models APIs.

list_operations(**kwargs: Any) -> azure.core.paging.ItemPaged[azure.ai.formrecognizer._models.ModelOperationInfo]

Returns

A pageable of ModelOperationInfo.

Return type

ItemPaged[ModelOperationInfo]

Exceptions

HttpResponseError

Examples

List all document model operations in the past 24 hours.

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import DocumentModelAdministrationClient

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

   document_model_admin_client = DocumentModelAdministrationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

   operations = list(document_model_admin_client.list_operations())

   print("The following document model operations exist under my resource:")
   for operation in operations:
       print("\nOperation ID: {}".format(operation.operation_id))
       print("Operation kind: {}".format(operation.kind))
       print("Operation status: {}".format(operation.status))
       print("Operation percent completed: {}".format(operation.percent_completed))
       print("Operation created on: {}".format(operation.created_on))
       print("Operation last updated on: {}".format(operation.last_updated_on))
       print("Resource location of successful operation: {}".format(operation.resource_location))