FormTrainingClient Classe

FormTrainingClient é a interface Reconhecimento de Formulários a ser usada para criar e gerenciar modelos personalizados. Ele fornece métodos para treinar modelos 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 de API 2022-08-31 e posteriores, instancie um DocumentModelAdministrationClient.

Herança

azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase

FormTrainingClient

Construtor

FormTrainingClient(endpoint: str, credential: AzureKeyCredential | TokenCredential, **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 TokenCredential

Obrigatório

Credenciais necessárias para que o cliente se conecte ao Azure. Essa é uma instância de 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 v2.1 da API. A configuração para uma versão mais antiga pode resultar em redução da compatibilidade de recursos. Para usar a versão e os recursos mais recentes da API com suporte, crie uma instância de 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 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 import FormTrainingClient
   from azure.identity 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 destino especificado pelo usuário Reconhecimento de Formulários recurso. 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 de 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 model_name palavra-chave
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 reconhecedor 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 do modelo, status de modelo 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 de 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 destino especificado pelo usuário Reconhecimento de Formulários recurso. 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_copy_model(model_id: str, target: Dict[str, str | int], **kwargs: Any) -> LROPoller[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 sondador de um estado salvo.

Retornos

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

Tipo de retorno

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

   poller = 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 = 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 de cliente begin_create_composed_model

begin_create_composed_model(model_ids: List[str], **kwargs: Any) -> LROPoller[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 para associar ao seu modelo.

continuation_token

str

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

Retornos

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

Tipo de retorno

LROPoller[CustomFormModel]

Exceções

HttpResponseError

Exemplos

Criar um modelo composto

   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer 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))
   supplies_poller = form_training_client.begin_training(
       po_supplies, use_training_labels=True, model_name="Purchase order - Office supplies"
   )
   equipment_poller = form_training_client.begin_training(
       po_equipment, use_training_labels=True, model_name="Purchase order - Office Equipment"
   )
   furniture_poller = form_training_client.begin_training(
       po_furniture, use_training_labels=True, model_name="Purchase order - Furniture"
   )
   cleaning_supplies_poller = form_training_client.begin_training(
       po_cleaning_supplies, use_training_labels=True, model_name="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()

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

   poller = form_training_client.begin_create_composed_model(
       models_trained_with_labels, model_name="Office Supplies Composed Model"
   )
   model = 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 model_name palavra-chave

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

Parâmetros

training_files_url

str

Obrigatório

Um URI SAS do 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 o 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 para associar ao seu modelo.

continuation_token

str

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

Retornos

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

Tipo de retorno

LROPoller[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 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"]

   form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))
   poller = form_training_client.begin_training(container_sas_url, use_training_labels=False)
   model = 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.

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.

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

Parâmetros

model_id

str

Obrigatório

Identificador de modelo.

Tipo de retorno

None

Exceções

HttpResponseError

ResourceNotFoundError

Exemplos

Excluir um modelo personalizado.

   form_training_client.delete_model(model_id=custom_model.model_id)

   try:
       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 reconhecedor de formulários.

get_account_properties(**kwargs: Any) -> AccountProperties

Retornos

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

Tipo de retorno

AccountProperties

Exceções

HttpResponseError

Exemplos

Obter propriedades para a conta do reconhecedor de formulários.

   form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   # First, we see how many custom models we have, and what our limit is
   account_properties = 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.

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 para o 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 compatível com os Serviços Cognitivos. Por exemplo, 'westus', 'eastus' etc. Consulte https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services para obter 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))

   target = 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.

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 = form_training_client.get_custom_model(model_id=model.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 do modelo, status de modelo e quando ele foi criado e modificado pela última vez.

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

Retornos

ItemPaged[CustomFormModelInfo]

Tipo de retorno

ItemPaged

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:")
   for model_info in custom_models:
       print(model_info.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 de 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.

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

Parâmetros

request

HttpRequest

Obrigatório

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

stream

bool

Se o conteúdo da resposta será transmitido. Usa False como padrão.

Retornos

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

Tipo de retorno

HttpResponse

Exceções

HttpResponseError