azure.ai.formrecognizer.FormTrainingClient.yml

### YamlMime:PythonClass
uid: azure.ai.formrecognizer.FormTrainingClient
name: FormTrainingClient
fullName: azure.ai.formrecognizer.FormTrainingClient
module: azure.ai.formrecognizer
inheritances:
- azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase
summary: '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.

  >'
constructor:
  syntax: 'FormTrainingClient(endpoint: str, credential: AzureKeyCredential | TokenCredential,
    **kwargs: Any)'
  parameters:
  - name: endpoint
    description: 'Supported Cognitive Services endpoints (protocol and hostname,

      for example: [https://westus2.api.cognitive.microsoft.com](https://westus2.api.cognitive.microsoft.com)).'
    isRequired: true
    types:
    - <xref:str>
  - name: credential
    description: '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 <xref:azure.identity>.'
    isRequired: true
    types:
    - <xref:azure.core.credentials.AzureKeyCredential>
    - <xref:azure.core.credentials.TokenCredential>
  - name: api_version
    description: '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.'
    types:
    - <xref:str>
    - <xref:azure.ai.formrecognizer.FormRecognizerApiVersion>
methods:
- uid: azure.ai.formrecognizer.FormTrainingClient.begin_copy_model
  name: begin_copy_model
  summary: '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 <xref:azure.ai.formrecognizer.FormTrainingClient.get_copy_authorization>
    method.'
  signature: 'begin_copy_model(model_id: str, target: Dict[str, str | int], **kwargs:
    Any) -> LROPoller[CustomFormModelInfo]'
  parameters:
  - name: model_id
    description: Model identifier of the model to copy to target resource.
    isRequired: true
    types:
    - <xref:str>
  - name: target
    description: 'The copy authorization generated from the target resource''s call
      to

      <xref:azure.ai.formrecognizer.FormTrainingClient.get_copy_authorization>.'
    isRequired: true
    types:
    - <xref:Dict>[<xref:str>, <xref:Union>[<xref:str>, <xref:int>]]
  - name: continuation_token
    description: A continuation token to restart a poller from a saved state.
    types:
    - <xref:str>
  return:
    description: 'An instance of an LROPoller. Call *result()* on the poller

      object to return a <xref:azure.ai.formrecognizer.CustomFormModelInfo>.'
    types:
    - <xref:azure.core.polling.LROPoller>[<xref:azure.ai.formrecognizer.CustomFormModelInfo>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.FormTrainingClient.begin_create_composed_model
  name: begin_create_composed_model
  summary: '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'
  signature: 'begin_create_composed_model(model_ids: List[str], **kwargs: Any) ->
    LROPoller[CustomFormModel]'
  parameters:
  - name: model_ids
    description: List of model IDs to use in the composed model.
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: model_name
    description: An optional, user-defined name to associate with your model.
    types:
    - <xref:str>
  - name: continuation_token
    description: A continuation token to restart a poller from a saved state.
    types:
    - <xref:str>
  return:
    description: 'An instance of an LROPoller. Call *result()* on the poller

      object to return a <xref:azure.ai.formrecognizer.CustomFormModel>.'
    types:
    - <xref:azure.core.polling.LROPoller>[<xref:azure.ai.formrecognizer.CustomFormModel>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.FormTrainingClient.begin_training
  name: begin_training
  summary: '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](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'
  signature: 'begin_training(training_files_url: str, use_training_labels: bool, **kwargs:
    Any) -> LROPoller[CustomFormModel]'
  parameters:
  - name: training_files_url
    description: '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](https://aka.ms/azsdk/formrecognizer/buildtrainingset).'
    isRequired: true
    types:
    - <xref:str>
  - name: use_training_labels
    description: 'Whether to train with labels or not. Corresponding labeled files
      must

      exist in the blob container if set to *True*.'
    isRequired: true
    types:
    - <xref:bool>
  - name: prefix
    description: '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.'
    types:
    - <xref:str>
  - name: include_subfolders
    description: '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.'
    types:
    - <xref:bool>
  - name: model_name
    description: An optional, user-defined name to associate with your model.
    types:
    - <xref:str>
  - name: continuation_token
    description: A continuation token to restart a poller from a saved state.
    types:
    - <xref:str>
  return:
    description: 'An instance of an LROPoller. Call *result()* on the poller

      object to return a <xref:azure.ai.formrecognizer.CustomFormModel>.'
    types:
    - <xref:azure.core.polling.LROPoller>[<xref:azure.ai.formrecognizer.CustomFormModel>]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
    description: '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'
  - type: azure.ai.formrecognizer.FormTrainingClient.delete_model
- uid: azure.ai.formrecognizer.FormTrainingClient.close
  name: close
  summary: Close the <xref:azure.ai.formrecognizer.FormTrainingClient> session.
  signature: close() -> None
- uid: azure.ai.formrecognizer.FormTrainingClient.delete_model
  name: delete_model
  summary: 'Mark model for deletion. Model artifacts will be permanently

    removed within a predetermined period.'
  signature: 'delete_model(model_id: str, **kwargs: Any) -> None'
  parameters:
  - name: model_id
    description: Model identifier.
    isRequired: true
    types:
    - <xref:str>
  return:
    types:
    - <xref:None>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
  - type: azure.core.exceptions.ResourceNotFoundError
- uid: azure.ai.formrecognizer.FormTrainingClient.get_account_properties
  name: get_account_properties
  summary: Get information about the models on the form recognizer account.
  signature: 'get_account_properties(**kwargs: Any) -> AccountProperties'
  return:
    description: 'Summary of models on account - custom model count,

      custom model limit.'
    types:
    - <xref:azure.ai.formrecognizer.AccountProperties>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.FormTrainingClient.get_copy_authorization
  name: get_copy_authorization
  summary: '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 <xref:azure.ai.formrecognizer.FormTrainingClient.begin_copy_model>.'
  signature: 'get_copy_authorization(resource_id: str, resource_region: str, **kwargs:
    Any) -> Dict[str, str | int]'
  parameters:
  - name: resource_id
    description: 'Azure Resource Id of the target Form Recognizer resource

      where the model will be copied to.'
    isRequired: true
    types:
    - <xref:str>
  - name: resource_region
    description: '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](https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services)

      for the regional availability of Cognitive Services.'
    isRequired: true
    types:
    - <xref:str>
  return:
    description: 'A dictionary with values for the copy authorization -

      "modelId", "accessToken", "resourceId", "resourceRegion", and "expirationDateTimeTicks".'
    types:
    - <xref:Dict>[<xref:str>, <xref:Union>[<xref:str>, <xref:int>]]
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
- uid: azure.ai.formrecognizer.FormTrainingClient.get_custom_model
  name: get_custom_model
  summary: '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.'
  signature: 'get_custom_model(model_id: str, **kwargs: Any) -> CustomFormModel'
  parameters:
  - name: model_id
    description: Model identifier.
    isRequired: true
    types:
    - <xref:str>
  return:
    description: CustomFormModel
    types:
    - <xref:azure.ai.formrecognizer.CustomFormModel>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError
  - type: azure.core.exceptions.ResourceNotFoundError
- uid: azure.ai.formrecognizer.FormTrainingClient.get_form_recognizer_client
  name: get_form_recognizer_client
  summary: Get an instance of a FormRecognizerClient from FormTrainingClient.
  signature: 'get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient'
  return:
    description: A FormRecognizerClient
    types:
    - <xref:azure.ai.formrecognizer.FormRecognizerClient>
- uid: azure.ai.formrecognizer.FormTrainingClient.list_custom_models
  name: list_custom_models
  summary: 'List information for each model, including model id,

    model status, and when it was created and last modified.'
  signature: 'list_custom_models(**kwargs: Any) -> ItemPaged[CustomFormModelInfo]'
  return:
    description: ItemPaged[<xref:azure.ai.formrecognizer.CustomFormModelInfo>]
    types:
    - <xref:azure.core.paging.ItemPaged>
  exceptions:
  - type: azure.core.exceptions.HttpResponseError