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.FormRecognizerClientBaseAsyncFormTrainingClient
Construtor
FormTrainingClient(endpoint: str, credential: AzureKeyCredential | AsyncTokenCredential, **kwargs: Any)
Parâmetros
- endpoint
- str
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
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
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
Exceções
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_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
Exceções
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
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
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
Exceções
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
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
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
Retornos
Nenhum
Tipo de retorno
Exceções
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
Exceções
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
A ID de Recurso do Azure do recurso de Reconhecimento de Formulários de destino no qual o modelo será copiado.
- resource_region
- str
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
Exceções
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
Retornos
CustomFormModel
Tipo de retorno
Exceções
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
Exceções
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
Exceções
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
Retornos
A resposta da sua chamada de rede. Não faz tratamento de erros em sua resposta.
Tipo de retorno
Exceções
Azure SDK for Python