Biblioteca de clientes do Azure Reconhecimento de Formulários para Python – versão 3.0.0
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
- O Python 2.7 ou 3.5 ou posterior é necessário para usar esse pacote.
- Você deve ter uma assinatura do Azure e um recurso dos Serviços Cognitivos ou Reconhecimento de Formulários para usar esse pacote.
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 Conteúdo
- Reconhecer recibos
- Treinar um modelo
- Gerenciar seus modelos
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.
- Autenticação do cliente: sample_authentication.py
- Reconhecer recibos: sample_recognize_receipts.py
- Reconhecer recibos de uma URL: sample_recognize_receipts_from_url.py
- Reconhecer conteúdo: sample_recognize_content.py
- Reconhecer formulários personalizados: sample_recognize_custom_forms.py
- Treinar um modelo sem rótulos: sample_train_model_without_labels.py
- Treinar um modelo com rótulos: sample_train_model_with_labels.py
- Gerenciar modelos personalizados: sample_manage_custom_models.py
- Copiar um modelo entre recursos de Reconhecimento de Formulários: sample_copy_model.py
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 .
- Autenticação do cliente: sample_authentication_async.py
- Reconhecer recibos: sample_recognize_receipts_async.py
- Reconhecer recibos de uma URL: sample_recognize_receipts_from_url_async.py
- Reconhecer conteúdo: sample_recognize_content_async.py
- Reconhecer formulários personalizados: sample_recognize_custom_forms_async.py
- Treinar um modelo sem rótulos: sample_train_model_without_labels_async.py
- Treinar um modelo com rótulos: sample_train_model_with_labels_async.py
- Gerenciar modelos personalizados: sample_manage_custom_models_async.py
- Copiar um modelo entre recursos de Reconhecimento de Formulários: sample_copy_model_async.py
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.
Azure SDK for Python