Biblioteca de clientes do Azure Reconhecimento de Formulários para Python – versão 3.0.0

  • Artigo

Os Serviços Cognitivos do Azure Reconhecimento de Formulários é um serviço de nuvem que usa o aprendizado de máquina para reconhecer dados de texto e tabela de documentos de formulário. Ele inclui as seguintes funcionalidades principais:

  • Modelos personalizados – reconhecer valores de campo e dados de tabela de formulários. Esses modelos são treinados usando dados próprios e, portanto, são adaptados para seus formulários.
  • API de Conteúdo – reconhecer estruturas de texto e tabela, juntamente com suas coordenadas de caixa delimitadora, de documentos. Corresponde à API de Layout do serviço REST.
  • Modelo de recibo predefinido – reconhecer dados de recibos de vendas dos EUA usando um modelo predefinido.

Código-fonte | Pacote (PyPI) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes do Azure Reconhecimento de Formulários para Python – versão 3.0.0 com pip:

pip install azure-ai-formrecognizer

Observação: esta versão da biblioteca de clientes dá suporte à versão v2.0 do serviço Reconhecimento de Formulários

Criar um recurso do Reconhecimento de Formulários

Reconhecimento de Formulários dá suporte ao acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se você planeja acessar vários serviços cognitivos em um só ponto de extremidade/chave. Para acesso somente de Reconhecimento de Formulários, crie um recurso Reconhecimento de Formulários.

Você pode criar o recurso usando

Opção 1:Portal do Azure

Opção 2:CLI do Azure. Veja abaixo um exemplo de como você pode criar um recurso de Reconhecimento de Formulários usando a CLI:

# Create a new resource group to hold the form recognizer resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create form recognizer
az cognitiveservices account create \
    --name form-recognizer-resource \
    --resource-group my-resource-group \
    --kind FormRecognizer \
    --sku F0 \
    --location westus2 \
    --yes

Autenticar o cliente

Para interagir com o serviço Reconhecimento de Formulários, você precisará criar uma instância de um cliente. Um ponto de extremidade e uma credencial são necessários para instanciar o objeto cliente.

Pesquisando o ponto de extremidade

Você pode encontrar o ponto de extremidade do recurso Reconhecimento de Formulários usando o Portal do Azure ou a CLI do Azure:

# Get the endpoint for the form recognizer resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Obter a chave de API

A chave de API pode ser encontrada no Portal do Azure ou executando o seguinte comando da CLI do Azure:

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

Criar o cliente com AzureKeyCredential

Para usar uma chave de API como parâmetro credential , passe a chave como uma cadeia de caracteres para uma instância do AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")
form_recognizer_client = FormRecognizerClient(endpoint, credential)

Criar o cliente com uma credencial do Azure Active Directory

AzureKeyCredential A autenticação é usada nos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do azure . Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para usar esse tipo de autenticação.

Para usar o tipo DefaultAzureCredential mostrado abaixo ou outros tipos de credencial fornecidos com o SDK do Azure, instale o azure-identity pacote:

pip install azure-identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso a Reconhecimento de Formulários atribuindo a "Cognitive Services User" função à entidade de serviço.

Depois de concluído, defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

from azure.identity import DefaultAzureCredential
from azure.ai.formrecognizer import FormRecognizerClient
credential = DefaultAzureCredential()

form_recognizer_client = FormRecognizerClient(
    endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
    credential=credential
)

Principais conceitos

FormRecognizerClient

FormRecognizerClient fornece operações para:

  • Reconhecer campos e conteúdo do formulário usando modelos personalizados treinados para reconhecer seus formulários personalizados. Esses valores são retornados em uma coleção de objetos RecognizedForm.
  • Reconhecendo campos comuns de recibos dos EUA, usando um modelo de recibo pré-treinado. Esses campos e metadados são retornados em uma coleção de RecognizedForm objetos.
  • Reconhecer o conteúdo do formulário, incluindo tabelas, linhas e palavras, sem a necessidade de treinar um modelo. O conteúdo do formulário é retornado em uma coleção de objetos FormPage.

Snippets de código de exemplo são fornecidos para ilustrar o uso de um FormulárioRecognizerClient aqui.

FormTrainingClient

FormTrainingClient fornece operações para:

  • Treinar modelos personalizados sem rótulos para reconhecer todos os campos e valores encontrados em seus formulários personalizados. Um CustomFormModel é retornado indicando os tipos de formulário que o modelo reconhecerá e os campos que serão extraídos para cada tipo de formulário. Confira a documentação do serviço para obter uma explicação mais detalhada.
  • Treinar modelos personalizados com rótulos para reconhecer campos e valores específicos especificados rotulando seus formulários personalizados. Um CustomFormModel é retornado indicando os campos que o modelo extrairá, bem como a precisão estimada de cada campo. Confira a documentação do serviço para obter uma explicação mais detalhada.
  • Gerenciar modelos criados em sua conta.
  • Copiar um modelo personalizado de um recurso de Reconhecimento de Formulários para outro.

Observe que os modelos também podem ser treinados usando uma interface gráfica do usuário, como a Ferramenta de Rotulagem do Reconhecimento de Formulários.

Snippets de código de exemplo são fornecidos para ilustrar o uso de um formTrainingClient aqui.

Operações de Long-Running

Operações de execução prolongada são operações que consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguidas por sondar o serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Métodos que treinam modelos, reconhecem valores de formulários ou copiam modelos são modelados como operações de execução prolongada. O cliente expõe um begin_<method-name> método que retorna um LROPoller ou AsyncLROPoller. Os chamadores devem aguardar a conclusão da operação chamando result() o objeto poller retornado do begin_<method-name> método . Snippets de código de exemplo são fornecidos para ilustrar o uso de operações de execução prolongada abaixo.

Exemplos

A seção a seguir fornece vários snippets de código que abrangem algumas das tarefas de Reconhecimento de Formulários mais comuns, incluindo:

Reconhecer formulários usando um modelo personalizado

Reconhecer pares de nome/valor e dados de tabela de formulários. Esses modelos são treinados usando dados próprios e, portanto, são adaptados para seus formulários. Para obter melhores resultados, você só deve reconhecer formas do mesmo tipo de formulário em que o modelo personalizado foi treinado.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)
model_id = "<your custom model id>"

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_custom_forms(model_id=model_id, form=form)
result = poller.result()

for recognized_form in result:
    print("Form type: {}".format(recognized_form.form_type))
    for name, field in recognized_form.fields.items():
        print("Field '{}' has label '{}' with value '{}' and a confidence score of {}".format(
            name,
            field.label_data.text if field.label_data else name,
            field.value,
            field.confidence
        ))

Como alternativa, uma URL de formulário também pode ser usada para reconhecer formulários personalizados usando o begin_recognize_custom_forms_from_url método . Os _from_url métodos existem para todos os métodos de reconhecimento.

form_url = "<url_of_the_form>"
poller = form_recognizer_client.begin_recognize_custom_forms_from_url(model_id=model_id, form_url=form_url)
result = poller.result()

Reconhecer Conteúdo

Reconhecer estruturas de texto e tabela, juntamente com suas coordenadas de caixa delimitadora, de documentos.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_content(form)
page = poller.result()

table = page[0].tables[0] # page 1, table 1
print("Table found on page {}:".format(table.page_number))
for cell in table.cells:
    print("Cell text: {}".format(cell.text))
    print("Location: {}".format(cell.bounding_box))
    print("Confidence score: {}\n".format(cell.confidence))

Reconhecer recibos

Reconhecer dados de recibos de vendas dos EUA usando um modelo predefinido. Os campos de recibo reconhecidos pelo serviço podem ser encontrados aqui.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your receipt>", "rb") as fd:
    receipt = fd.read()

poller = form_recognizer_client.begin_recognize_receipts(receipt)
result = poller.result()

for receipt in result:
    for name, field in receipt.fields.items():
        if name == "Items":
            print("Receipt Items:")
            for idx, items in enumerate(field.value):
                print("...Item #{}".format(idx+1))
                for item_name, item in items.value.items():
                    print("......{}: {} has confidence {}".format(item_name, item.value, item.confidence))
        else:
            print("{}: {} has confidence {}".format(name, field.value, field.confidence))

Treinar um modelo

Treine um modelo personalizado em seu próprio tipo de formulário. O modelo resultante pode ser usado para reconhecer valores dos tipos de formulários em que foi treinado. Forneça uma URL SAS de contêiner para seu contêiner de Blob de Armazenamento do Azure em que você está armazenando os documentos de treinamento. Se os arquivos de treinamento estiverem dentro de uma subpasta no contêiner, use o argumento de palavra-chave prefixo para especificar sob qual pasta treinar.

Mais detalhes sobre como configurar um contêiner e a estrutura de arquivo necessária podem ser encontrados na documentação do serviço.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
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("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

Gerenciar seus modelos

Gerencie os modelos personalizados anexados à sua conta.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

# Here we get a paged list of all of our custom models
custom_models = form_training_client.list_custom_models()
print("We have models with the following ids: {}".format(
    ", ".join([m.model_id for m in custom_models])
))

# Replace with the custom model ID from the "Train a model" sample
model_id = "<model_id from the Train a Model sample>"

custom_model = form_training_client.get_custom_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

# Finally, we will delete this model by ID
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))

Solução de problemas

Geral

Reconhecimento de Formulários biblioteca de clientes gerará exceções definidas no Azure Core.

Log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado no nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o argumento de palavra-chave logging_enable:

import sys
import logging
from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
form_recognizer_client = FormRecognizerClient(endpoint, credential, logging_enable=True)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

poller = form_recognizer_client.begin_recognize_receipts(receipt, logging_enable=True)

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Próximas etapas

A seção a seguir fornece vários snippets de código ilustrando padrões comuns usados na API do Python Reconhecimento de Formulários.

Mais códigos de exemplo

Esses exemplos de código mostram operações de cenário comuns com a biblioteca de clientes Reconhecimento de Formulários do Azure.

APIs assíncronas

Essa biblioteca também inclui uma API assíncrona completa com suporte no Python 3.5+. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Os clientes assíncronos são encontrados no azure.ai.formrecognizer.aio namespace .

Documentação adicional

Para obter uma documentação mais abrangente sobre os Serviços Cognitivos do Azure Reconhecimento de Formulários, consulte a documentação Reconhecimento de Formulários sobre docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.