FormTrainingClient Classe

FormTrainingClient é a interface Reconhecimento de Formulários a ser usada para criar e gerenciar modelos personalizados. Ele fornece métodos para modelos de treinamento nos formulários que você fornece, bem como métodos para exibir e excluir modelos, acessar propriedades de conta, copiar modelos para outro recurso Reconhecimento de Formulários e redigir modelos de uma coleção de modelos existentes treinados com rótulos.

Observação

FormTrainingClient deve ser usado com versões <de API =v2.1.

Para usar as versões da API 2022-08-31 e posteriores, instancie um DocumentModelAdministrationClient.

Herança

azure.ai.formrecognizer.aio._form_base_client_async.FormRecognizerClientBaseAsync

FormTrainingClient

Construtor

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

Parâmetros

endpoint

str

Obrigatório

Pontos de extremidade dos Serviços Cognitivos com suporte (protocolo e nome do host, por exemplo: https://westus2.api.cognitive.microsoft.com).

credential

AzureKeyCredential ou AsyncTokenCredential

Obrigatório

Credenciais necessárias para que o cliente se conecte ao Azure. Essa é uma instância do AzureKeyCredential se estiver usando uma chave de API ou uma credencial de token de identity.

api_version

str ou FormRecognizerApiVersion

A versão da API do serviço a ser usada para solicitações. Ele usa como padrão a versão da API v2.1. A configuração para uma versão mais antiga pode resultar em compatibilidade de recursos reduzida. Para usar a versão e os recursos mais recentes da API com suporte, instancie um DocumentModelAdministrationClient.

Exemplos

Criando o FormTrainingClient com um ponto de extremidade e uma chave de API.

   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))

Criando o FormTrainingClient com uma credencial de token.

   """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)

Métodos

begin_copy_model	Copie um modelo personalizado armazenado nesse recurso (a origem) para o recurso de Reconhecimento de Formulários de destino especificado pelo usuário. Isso deve ser chamado com o recurso de Reconhecimento de Formulários de origem (com o modelo que se destina a ser copiado). O parâmetro de destino deve ser fornecido a partir da saída do recurso de destino de chamar o get_copy_authorization método .
begin_create_composed_model	Cria um modelo composto de uma coleção de modelos existentes que foram treinados com rótulos. Um modelo composto permite que vários modelos sejam chamados com uma única ID de modelo. Quando um documento é enviado para ser analisado com uma ID de modelo composto, uma etapa de classificação é executada primeiro para encaminhá-lo para o modelo personalizado correto. Novo na versão v2.1: o método cliente begin_create_composed_model
begin_training	Criar e treinar um modelo personalizado. A solicitação deve incluir um parâmetro training_files_url que seja um URI de contêiner de blob de armazenamento do Azure acessível externamente (preferencialmente um URI de Assinatura de Acesso Compartilhado). Observe que um URI de contêiner (sem SAS) é aceito somente quando o contêiner é público ou tem uma identidade gerenciada configurada, confira mais sobre como configurar identidades gerenciadas para trabalhar com Reconhecimento de Formulários aqui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Os modelos são treinados usando documentos do seguinte tipo de conteúdo : 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' ou 'image/bmp'. Outros tipos de conteúdo no contêiner são ignorados. Novo na versão v2.1: o argumento palavra-chave model_name
close	Feche a FormTrainingClient sessão.
delete_model	Marcar modelo para exclusão. Os artefatos de modelo serão removidos permanentemente dentro de um período predeterminado.
get_account_properties	Obtenha informações sobre os modelos na conta do reconhecimento de formulários.
get_copy_authorization	Gere autorização para copiar um modelo personalizado para o recurso de Reconhecimento de Formulários de destino. Isso deve ser chamado pelo recurso de destino (para o qual o modelo será copiado) e a saída pode ser passada como o parâmetro de destino para begin_copy_model.
get_custom_model	Obtenha uma descrição de um modelo personalizado, incluindo os tipos de formulários que ele pode reconhecer e os campos que ele extrairá para cada tipo de formulário.
get_form_recognizer_client	Obtenha uma instância de um FormRecognizerClient do FormTrainingClient.
list_custom_models	Listar informações para cada modelo, incluindo id de modelo, modelo status e quando ele foi criado e modificado pela última vez.
send_request	Executa uma solicitação de rede usando o pipeline existente do cliente. A URL de solicitação pode ser relativa à URL base. A versão da API de serviço usada para a solicitação é a mesma do cliente, a menos que especificado de outra forma. A substituição da versão da API configurada do cliente na URL relativa tem suporte no cliente com a versão da API 2022-08-31 e posterior. Substituição em URL absoluta com suporte no cliente com qualquer versão da API. Esse método não será gerado se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta retornado. Para obter mais informações sobre como enviar solicitações personalizadas com esse método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

begin_copy_model

Copie um modelo personalizado armazenado nesse recurso (a origem) para o recurso de Reconhecimento de Formulários de destino especificado pelo usuário. Isso deve ser chamado com o recurso de Reconhecimento de Formulários de origem (com o modelo que se destina a ser copiado). O parâmetro de destino deve ser fornecido a partir da saída do recurso de destino de chamar o get_copy_authorization método .

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

Parâmetros

model_id

str

Obrigatório

Identificador de modelo do modelo a ser copiado para o recurso de destino.

target

Dict[str, Union[str, int]]

Obrigatório

A autorização de cópia gerada da chamada do recurso de destino para get_copy_authorization.

continuation_token

str

Um token de continuação para reiniciar um poller de um estado salvo.

Retornos

Uma instância de um AsyncLROPoller. Chame result() no objeto poller para retornar um CustomFormModelInfo.

Tipo de retorno

AsyncLROPoller[CustomFormModelInfo]

Exceções

HttpResponseError

Exemplos

Copiar um modelo do recurso de origem para o recurso de destino

   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

Cria um modelo composto de uma coleção de modelos existentes que foram treinados com rótulos.

Um modelo composto permite que vários modelos sejam chamados com uma única ID de modelo. Quando um documento é enviado para ser analisado com uma ID de modelo composto, uma etapa de classificação é executada primeiro para encaminhá-lo para o modelo personalizado correto.

Novo na versão v2.1: o método cliente begin_create_composed_model

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

Parâmetros

model_ids

list[str]

Obrigatório

Lista de IDs de modelo a serem usadas no modelo composto.

model_name

str

Um nome opcional definido pelo usuário a ser associado ao modelo.

continuation_token

str

Um token de continuação para reiniciar um poller de um estado salvo.

Retornos

Uma instância de um AsyncLROPoller. Chame result() no objeto poller para retornar um CustomFormModel.

Tipo de retorno

AsyncLROPoller[CustomFormModel]

Exceções

HttpResponseError

Exemplos

Criar um modelo composto

   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

Criar e treinar um modelo personalizado. A solicitação deve incluir um parâmetro training_files_url que seja um URI de contêiner de blob de armazenamento do Azure acessível externamente (preferencialmente um URI de Assinatura de Acesso Compartilhado). Observe que um URI de contêiner (sem SAS) é aceito somente quando o contêiner é público ou tem uma identidade gerenciada configurada, confira mais sobre como configurar identidades gerenciadas para trabalhar com Reconhecimento de Formulários aqui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Os modelos são treinados usando documentos do seguinte tipo de conteúdo : 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' ou 'image/bmp'. Outros tipos de conteúdo no contêiner são ignorados.

Novo na versão v2.1: o argumento palavra-chave model_name

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

Parâmetros

training_files_url

str

Obrigatório

Um URI SAS de contêiner de blob do Armazenamento do Azure. Um URI de contêiner (sem SAS) poderá ser usado se o contêiner for público ou tiver uma identidade gerenciada configurada. Para obter mais informações sobre como configurar um conjunto de dados de treinamento, consulte: https://aka.ms/azsdk/formrecognizer/buildtrainingset.

use_training_labels

bool

Obrigatório

Se você deve treinar com rótulos ou não. Os arquivos rotulados correspondentes devem existir no contêiner de blob se definido como True.

prefix

str

Uma cadeia de caracteres de prefixo que diferencia maiúsculas de minúsculas para filtrar documentos no caminho de origem para treinamento. Por exemplo, ao usar um URI de blob de armazenamento do Azure, use o prefixo para restringir subpastas para treinamento.

include_subfolders

bool

Um sinalizador para indicar se as subpastas dentro do conjunto de pastas de prefixo também precisarão ser incluídas ao pesquisar conteúdo a ser pré-processado. Não há suporte para treinamento com rótulos.

model_name

str

Um nome opcional definido pelo usuário a ser associado ao modelo.

continuation_token

str

Um token de continuação para reiniciar um poller de um estado salvo.

Retornos

Uma instância de um AsyncLROPoller. Chame result() no objeto poller para retornar um CustomFormModel.

Tipo de retorno

AsyncLROPoller[CustomFormModel]

Exceções

HttpResponseError

Observe que, se o treinamento falhar, a exceção será gerada, mas um modelo com um status "inválido" ainda será criado. Você pode excluir esse modelo chamando

delete_model

Exemplos

Treinar um modelo (sem rótulos) com seus formulários personalizados.

   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

Feche a FormTrainingClient sessão.

async close() -> None

Exceções

HttpResponseError

delete_model

Marcar modelo para exclusão. Os artefatos de modelo serão removidos permanentemente dentro de um período predeterminado.

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

Parâmetros

model_id

str

Obrigatório

Identificador de modelo.

Retornos

Nenhum

Tipo de retorno

None

Exceções

HttpResponseError

ResourceNotFoundError

Exemplos

Excluir um modelo personalizado.

   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

Obtenha informações sobre os modelos na conta do reconhecimento de formulários.

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

Retornos

Resumo dos modelos na conta – contagem de modelos personalizados, limite de modelo personalizado.

Tipo de retorno

AccountProperties

Exceções

HttpResponseError

Exemplos

Obtenha propriedades para a conta do reconhecimento de formulários.

   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

Gere autorização para copiar um modelo personalizado para o recurso de Reconhecimento de Formulários de destino. Isso deve ser chamado pelo recurso de destino (para o qual o modelo será copiado) e a saída pode ser passada como o parâmetro de destino para begin_copy_model.

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

Parâmetros

resource_id

str

Obrigatório

A ID de Recurso do Azure do recurso de Reconhecimento de Formulários de destino no qual o modelo será copiado.

resource_region

str

Obrigatório

Local do recurso de Reconhecimento de Formulários de destino. Um nome de região válido do Azure com suporte dos Serviços Cognitivos. Por exemplo, 'westus', 'eastus' etc. Confira https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services a disponibilidade regional dos Serviços Cognitivos.

Retornos

Um dicionário com valores para a autorização de cópia – "modelId", "accessToken", "resourceId", "resourceRegion" e "expirationDateTimeTicks".

Tipo de retorno

Dict[str, Union[str, int]]

Exceções

HttpResponseError

Exemplos

Autorizar o recurso de destino a receber o modelo copiado

   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

Obtenha uma descrição de um modelo personalizado, incluindo os tipos de formulários que ele pode reconhecer e os campos que ele extrairá para cada tipo de formulário.

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

Parâmetros

model_id

str

Obrigatório

Identificador de modelo.

Retornos

CustomFormModel

Tipo de retorno

CustomFormModel

Exceções

HttpResponseError

ResourceNotFoundError

Exemplos

Obtenha um modelo personalizado com uma ID de modelo.

   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

Obtenha uma instância de um FormRecognizerClient do FormTrainingClient.

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

Retornos

Um FormRecognizerClient

Tipo de retorno

FormRecognizerClient

Exceções

HttpResponseError

list_custom_models

Listar informações para cada modelo, incluindo id de modelo, modelo status e quando ele foi criado e modificado pela última vez.

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

Retornos

AsyncItemPaged[CustomFormModelInfo]

Tipo de retorno

AsyncItemPaged

Exceções

HttpResponseError

Exemplos

Listar informações de modelo para cada modelo na conta.

   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

Executa uma solicitação de rede usando o pipeline existente do cliente.

A URL de solicitação pode ser relativa à URL base. A versão da API de serviço usada para a solicitação é a mesma do cliente, a menos que especificado de outra forma. A substituição da versão da API configurada do cliente na URL relativa tem suporte no cliente com a versão da API 2022-08-31 e posterior. Substituição em URL absoluta com suporte no cliente com qualquer versão da API. Esse método não será gerado se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta retornado. Para obter mais informações sobre como enviar solicitações personalizadas com esse método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

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

Parâmetros

request

HttpRequest

Obrigatório

A solicitação de rede que você deseja fazer.

Retornos

A resposta da sua chamada de rede. Não faz tratamento de erros em sua resposta.

Tipo de retorno

AsyncHttpResponse

Exceções

HttpResponseError