Azure Reconhecedor de Formulários biblioteca de clientes para Python - versão 3.0.0

  • Artigo

Azure Cognitive Services Reconhecedor de Formulários é um serviço de nuvem que usa machine learning para reconhecer texto e dados de tabelas a partir de documentos de formulário. Inclui as seguintes funcionalidades principais:

  • Modelos personalizados - Reconhecer valores de campo e dados de tabela a partir de formulários. Estes modelos são treinados com os seus próprios dados, por isso são adaptados aos seus formulários.
  • Conteúdo API - Reconhecer estruturas de texto e mesa, juntamente com as suas coordenadas de caixa de delimitação, a partir de documentos. Corresponde à API layout do serviço REST.
  • Modelo de recibo pré-construído - Reconheça os dados dos recibos de venda dos EUA utilizando um modelo pré-construído.

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

Introdução

Pré-requisitos

Instale o pacote

Instale a biblioteca cliente Azure Reconhecedor de Formulários para Python - versão 3.0.0 com pip:

pip install azure-ai-formrecognizer

Nota: Esta versão da biblioteca do cliente suporta a versão v2.0 do serviço Reconhecedor de Formulários

Criar um recurso Reconhecedor de Formulários

Reconhecedor de Formulários suporta o acesso a vários serviços e a um serviço único. Crie um recurso de Serviços Cognitivos se planeia aceder a múltiplos serviços cognitivos sob um único ponto final/tecla. Apenas para Reconhecedor de Formulários o acesso, crie um recurso Reconhecedor de Formulários.

Pode criar o recurso utilizando

Opção 1:Portal Azure

Opção 2:Azure CLI. Abaixo está um exemplo de como pode criar um recurso Reconhecedor de Formulários utilizando o 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 Reconhecedor de Formulários, terá de criar uma instância de um cliente. Um ponto final e credencial são necessários para instantaneaizar o objeto do cliente.

Olhando para o ponto final

Pode encontrar o ponto final para o seu recurso Reconhecedor de Formulários utilizando o Portal Azure ou O Azure CLI:

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

Obtenha a chave API

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

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

Criar o cliente com AzureKeyCredential

Para utilizar uma chave API como credential parâmetro, passe a chave como uma corda para um exemplo de 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 Azure Ative Directory

AzureKeyCredential A autenticação é utilizada nos exemplos deste guia de arranque, mas também pode autenticar com o Azure Ative Directory utilizando a biblioteca de identidade azul . Note que os pontos finais regionais não suportam a autenticação da AAD. Crie um nome de subdomínio personalizado para o seu recurso para utilizar este tipo de autenticação.

Para utilizar o tipo DefaultAzureCredential apresentado abaixo, ou outros tipos de credenciais fornecidos com o Azure SDK, por favor instale a azure-identity embalagem:

pip install azure-identity

Também terá de registar uma nova aplicação AAD e conceder acesso a Reconhecedor de Formulários atribuindo o "Cognitive Services User" papel ao seu diretor de serviço.

Uma vez concluídos, decreta os valores do ID do cliente, identificação de inquilino e segredo de cliente da aplicação AAD como variáveis ambientais: 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
)

Conceitos-chave

FormulárioRecognizerClient

FormRecognizerClient Fornece operações para:

  • Reconhecendo campos de formulários e conteúdos usando modelos personalizados treinados para reconhecer os seus formulários personalizados. Estes valores são devolvidos numa coleção de RecognizedForm objetos.
  • Reconhecendo campos comuns a partir de recibos dos EUA, usando um modelo de recibo pré-treinado. Estes campos e metadados são devolvidos numa coleção de RecognizedForm objetos.
  • Reconhecendo o conteúdo da forma, incluindo tabelas, linhas e palavras, sem a necessidade de treinar um modelo. O conteúdo do formulário é devolvido numa coleção de FormPage objetos.

Os fragmentos de código de amostra são fornecidos para ilustrar usando um FormulárioRecognizerClient aqui.

FormaTrainingClient

FormTrainingClient Fornece operações para:

  • Treinar modelos personalizados sem etiquetas para reconhecer todos os campos e valores encontrados nas suas formas personalizadas. A CustomFormModel é devolvido indicando os tipos de formulário que o modelo reconhecerá, e os campos que irá extrair para cada tipo de forma. Consulte a documentação do serviço para obter uma explicação mais detalhada.
  • Treinar modelos personalizados com etiquetas para reconhecer campos e valores específicos que especifica, rotulando os seus formulários personalizados. A CustomFormModel é devolvido indicando os campos que o modelo irá extrair, bem como a precisão estimada para cada campo. Consulte a documentação do serviço para obter uma explicação mais detalhada.
  • Gestão de modelos criados na sua conta.
  • Copiar um modelo personalizado de um Reconhecedor de Formulários recurso para outro.

Tenha em atenção que os modelos também podem ser treinados utilizando uma interface gráfica do utilizador, como a Ferramenta de Rotulagem Reconhecedor de Formulários.

Os fragmentos de código de amostra são fornecidos para ilustrar usando um formTrainingClient aqui.

Operações Long-Running

As operações de longa duração são operações que consistem num pedido inicial enviado ao serviço para iniciar uma operação, seguida de sondagens ao serviço a intervalos para determinar se a operação foi concluída ou falhou, e se conseguiu, para obter o resultado.

Métodos que treinam modelos, reconhecem valores a partir de formulários ou modelos de cópia são modelados como operações de longa duração. O cliente expõe um begin_<method-name> método que devolve um LROPoller ou AsyncLROPoller. Os chamadores devem esperar que a operação esteja concluída, chamando result() o objeto poller devolvido do begin_<method-name> método. Os fragmentos de código de amostra são fornecidos para ilustrar a utilização de operações de longo prazo abaixo.

Exemplos

A secção seguinte fornece vários fragmentos de código que cobrem algumas das tarefas de Reconhecedor de Formulários mais comuns, incluindo:

Reconhecer formas usando um modelo personalizado

Reconhecer pares de nome/valor e dados de tabela a partir de formulários. Estes modelos são treinados com os seus próprios dados, por isso são adaptados aos seus formulários. Para obter melhores resultados, só deve reconhecer formas do mesmo tipo de forma 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
        ))

Alternativamente, um URL de formulário também pode ser usado para reconhecer formas personalizadas 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 mesa, juntamente com as suas coordenadas de caixa de delimitação, a partir 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 pré-construído. Os campos de recibos reconhecidos pelo serviço podem ser consultados 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))

Preparar um modelo

Treine um modelo personalizado no seu próprio tipo de formulário. O modelo resultante pode ser usado para reconhecer valores a partir dos tipos de formas em que foi treinado. Forneça um URL SAS de contentor ao seu recipiente Azure Storage Blob onde está a armazenar os documentos de treino. Se os ficheiros de treino estiverem dentro de uma subpasta no recipiente, utilize o argumento da palavra-chave de prefixo para especificar em que pasta treinar.

Mais detalhes sobre a configuração de um recipiente e 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))

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

Resolução de problemas

Geral

Reconhecedor de Formulários biblioteca de clientes irá aumentar as exceções definidas no Núcleo Azure.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos. Informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível info.

A registo detalhado do nível DEBUG, incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos, pode ser ativado num cliente com o argumento da logging_enable palavra-chave:

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 permitir a registo detalhado para uma única operação, mesmo quando não está habilitado para o cliente:

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

Configuração opcional

Os argumentos de palavras-chave opcionais podem ser transmitidos ao cliente e ao nível por operação. A documentação de referência do núcleo azul descreve as configurações disponíveis para recaídas, registos, protocolos de transporte e muito mais.

Passos seguintes

A secção seguinte fornece vários fragmentos de código que ilustram padrões comuns usados na API python Reconhecedor de Formulários.

Mais código de amostra

Estas amostras de código mostram operações de cenário comum com a biblioteca de clientes Azure Reconhecedor de Formulários.

Async APIs

Esta biblioteca também inclui uma API completa async suportada em Python 3.5+. Para usá-lo, primeiro deve instalar um transporte de async, como aiohttp. Os clientes async são encontrados sob o espaço de azure.ai.formrecognizer.aio nome.

Documentação adicional

Para documentação mais extensa sobre os serviços cognitivos da Azure Reconhecedor de Formulários, consulte a documentação Reconhecedor de Formulários sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.