FormTrainingClient Classe

FormTrainingClient é a interface Reconhecedor de Formulários a utilizar para criar e gerir modelos personalizados. Fornece métodos para modelos de preparação nos formulários fornecidos, bem como métodos para visualizar e eliminar modelos, aceder às propriedades da conta, copiar modelos para outro recurso Reconhecedor de Formulários e compor modelos de uma coleção de modelos existentes preparados com etiquetas.

Nota

FormTrainingClient deve ser utilizado com as versões <da API =v2.1.

Para utilizar as versões de API 2022-08-31 e mais, instanciar 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

Necessário

Pontos finais dos Serviços Cognitivos suportados (protocolo e nome do anfitrião, por exemplo: https://westus2.api.cognitive.microsoft.com).

credential

AzureKeyCredential ou TokenCredential

Necessário

Credenciais necessárias para que o cliente se ligue ao Azure. Esta é uma instância do AzureKeyCredential se utilizar 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 utilizar para pedidos. A predefinição é a versão da API v2.1. Definir para uma versão mais antiga pode resultar numa compatibilidade de funcionalidades reduzida. Para utilizar a versão e as funcionalidades da API suportadas mais recentes, instancia um DocumentModelAdministrationClient.

Exemplos

Criar o FormTrainingClient com um ponto final 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))

Criar 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 neste recurso (a origem) para o utilizador especificado Reconhecedor de Formulários recurso. Isto deve ser chamado com o recurso de Reconhecedor 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 ao chamar o get_copy_authorization método.
begin_create_composed_model	Cria um modelo composto a partir de uma coleção de modelos existentes que foram preparados com etiquetas. Um modelo composto permite que vários modelos sejam chamados com um único ID de modelo. Quando um documento é submetido para ser analisado com um ID de modelo composto, é executado um passo de classificação pela primeira vez 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 preparar um modelo personalizado. O pedido tem de incluir um parâmetro de training_files_url que seja um URI de contentor de blobs de armazenamento do Azure acessível externamente (preferencialmente um URI de Assinatura de Acesso Partilhado). Tenha em atenção que um URI de contentor (sem SAS) só é aceite quando o contentor é público ou tem uma identidade gerida configurada, veja mais sobre como configurar identidades geridas para trabalhar com Reconhecedor de Formulários aqui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Os modelos são preparados com documentos do seguinte tipo de conteúdo – "application/pdf", "image/jpeg", "image/png", "image/tiff" ou "image/bmp". Outros tipos de conteúdo no contentor 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 eliminação. Os artefactos de modelo serão removidos permanentemente num período pré-determinado.
get_account_properties	Obtenha informações sobre os modelos na conta do reconhecedor de formulários.
get_copy_authorization	Gerar autorização para copiar um modelo personalizado para o recurso de destino Reconhecedor de Formulários. Isto deve ser chamado pelo recurso de destino (para o qual o modelo será copiado) e a saída pode ser transmitida 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 pode reconhecer e os campos que irá extrair para cada tipo de formulário.
get_form_recognizer_client	Obtenha uma instância de um FormRecognizerClient a partir de FormTrainingClient.
list_custom_models	Liste informações para cada modelo, incluindo o ID do modelo, o estado do modelo e quando foi criado e modificado pela última vez.
send_request	Executa um pedido de rede com o pipeline existente do cliente. O URL do pedido pode ser relativo ao URL base. A versão da API de serviço utilizada para o pedido é igual à do cliente, salvo especificação em contrário. Substituir a versão da API configurada do cliente no URL relativo é suportada no cliente com a versão da API 2022-08-31 e posterior. Substituir o URL absoluto suportado no cliente com qualquer versão da API. Este método não aumenta se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta devolvido. Para obter mais informações sobre como enviar pedidos personalizados com este método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

begin_copy_model

Copie um modelo personalizado armazenado neste recurso (a origem) para o utilizador especificado Reconhecedor de Formulários recurso. Isto deve ser chamado com o recurso de Reconhecedor 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 ao 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

Necessário

Identificador de modelo do modelo a copiar para o recurso de destino.

target

Dict[str, Union[str, int]]

Necessário

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

continuation_token

str

Um token de continuação para reiniciar um poller a partir de um estado guardado.

Devoluções

Uma instância de um LROPoller. Chame o resultado() no objeto do poller para devolver 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 a partir de uma coleção de modelos existentes que foram preparados com etiquetas.

Um modelo composto permite que vários modelos sejam chamados com um único ID de modelo. Quando um documento é submetido para ser analisado com um ID de modelo composto, é executado um passo de classificação pela primeira vez 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]

Necessário

Lista de IDs de modelo a utilizar no modelo composto.

model_name

str

Um nome opcional definido pelo utilizador para associar ao modelo.

continuation_token

str

Um token de continuação para reiniciar um poller a partir de um estado guardado.

Devoluções

Uma instância de um LROPoller. Chame o resultado() no objeto do poller para devolver 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 preparar um modelo personalizado. O pedido tem de incluir um parâmetro de training_files_url que seja um URI de contentor de blobs de armazenamento do Azure acessível externamente (preferencialmente um URI de Assinatura de Acesso Partilhado). Tenha em atenção que um URI de contentor (sem SAS) só é aceite quando o contentor é público ou tem uma identidade gerida configurada, veja mais sobre como configurar identidades geridas para trabalhar com Reconhecedor de Formulários aqui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Os modelos são preparados com documentos do seguinte tipo de conteúdo – "application/pdf", "image/jpeg", "image/png", "image/tiff" ou "image/bmp". Outros tipos de conteúdo no contentor 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

Necessário

URI de SAS de um contentor de blobs do Armazenamento do Azure. Um URI de contentor (sem SAS) pode ser utilizado se o contentor for público ou tiver uma identidade gerida configurada. Para obter mais informações sobre como configurar um conjunto de dados de preparação, consulte: https://aka.ms/azsdk/formrecognizer/buildtrainingset.

use_training_labels

bool

Necessário

Quer se prepare com etiquetas ou não. Os ficheiros etiquetados correspondentes têm de existir no contentor de blobs, se definidos como Verdadeiro.

prefix

str

Uma cadeia de prefixo sensível a maiúsculas e minúsculas para filtrar documentos no caminho de origem para preparação. Por exemplo, ao utilizar um URI de blobs de armazenamento do Azure, utilize o prefixo para restringir subpastas para preparação.

include_subfolders

bool

Um sinalizador para indicar se as subpastas dentro do conjunto de pastas de prefixo também terão de ser incluídas quando procurar conteúdo a ser pré-processado. Não suportado se a preparação com etiquetas não for suportada.

model_name

str

Um nome opcional definido pelo utilizador para associar ao modelo.

continuation_token

str

Um token de continuação para reiniciar um poller a partir de um estado guardado.

Devoluções

Uma instância de um LROPoller. Chame o resultado() no objeto do poller para devolver um CustomFormModel.

Tipo de retorno

LROPoller[CustomFormModel]

Exceções

HttpResponseError

Tenha em atenção que, se a preparação falhar, a exceção é gerada, mas ainda é criado um modelo com um estado "inválido". Pode eliminar este modelo ao chamar

delete_model

Exemplos

Preparar um modelo (sem etiquetas) com os 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 eliminação. Os artefactos de modelo serão removidos permanentemente num período pré-determinado.

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

Parâmetros

model_id

str

Necessário

Identificador de modelo.

Tipo de retorno

None

Exceções

HttpResponseError

ResourceNotFoundError

Exemplos

Eliminar 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

Devoluções

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

Tipo de retorno

AccountProperties

Exceções

HttpResponseError

Exemplos

Obtenha 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

Gerar autorização para copiar um modelo personalizado para o recurso de destino Reconhecedor de Formulários. Isto deve ser chamado pelo recurso de destino (para o qual o modelo será copiado) e a saída pode ser transmitida 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

Necessário

ID de Recurso do Azure do recurso de destino Reconhecedor de Formulários para o qual o modelo será copiado.

resource_region

str

Necessário

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

Devoluções

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 pode reconhecer e os campos que irá extrair para cada tipo de formulário.

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

Parâmetros

model_id

str

Necessário

Identificador de modelo.

Devoluções

CustomFormModel

Tipo de retorno

CustomFormModel

Exceções

HttpResponseError

ResourceNotFoundError

Exemplos

Obter um modelo personalizado com um 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 a partir de FormTrainingClient.

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

Devoluções

Um FormulárioRecognizerClient

Tipo de retorno

FormRecognizerClient

Exceções

HttpResponseError

list_custom_models

Liste informações para cada modelo, incluindo o ID do modelo, o estado do modelo e quando foi criado e modificado pela última vez.

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

Devoluções

ItemPaged[CustomFormModelInfo]

Tipo de retorno

ItemPaged

Exceções

HttpResponseError

Exemplos

Liste as informações do 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 um pedido de rede com o pipeline existente do cliente.

O URL do pedido pode ser relativo ao URL base. A versão da API de serviço utilizada para o pedido é igual à do cliente, salvo especificação em contrário. Substituir a versão da API configurada do cliente no URL relativo é suportada no cliente com a versão da API 2022-08-31 e posterior. Substituir o URL absoluto suportado no cliente com qualquer versão da API. Este método não aumenta se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta devolvido. Para obter mais informações sobre como enviar pedidos personalizados com este método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

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

Parâmetros

request

HttpRequest

Necessário

O pedido de rede que pretende fazer.

stream

bool

Se o payload de resposta será transmitido em fluxo. Predefinições para Falso.

Devoluções

A resposta da chamada de rede. Não efetua o processamento de erros na resposta.

Tipo de retorno

HttpResponse

Exceções

HttpResponseError