Azure Form Recognizer-clientbibliotheek voor Python - versie 3.0.0

  • Artikel

Azure Cognitive Services Form Recognizer is een cloudservice die gebruikmaakt van machine learning om tekst- en tabelgegevens uit formulierdocumenten te herkennen. Het bevat de volgende hoofdfuncties:

  • Aangepaste modellen: veldwaarden en tabelgegevens uit formulieren herkennen. Deze modellen worden getraind met uw eigen gegevens, zodat ze zijn afgestemd op uw formulieren.
  • Inhouds-API: tekst- en tabelstructuren herkennen, samen met de coördinaten van het begrenzingsvak, uit documenten. Komt overeen met de lay-out-API van de REST-service.
  • Vooraf samengesteld ontvangstbewijsmodel: gegevens van amerikaanse verkoopbevestigingen herkennen met behulp van een vooraf samengesteld model.

Broncode | Pakket (PyPI) | API-referentiedocumentatie| Productdocumentatie | Monsters

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Form Recognizer-clientbibliotheek voor Python - versie 3.0.0 met pip:

pip install azure-ai-formrecognizer

Opmerking: deze versie van de clientbibliotheek ondersteunt de versie v2.0 van de Form Recognizer-service

Een Form Recognizer-resource maken

Form Recognizer ondersteunt toegang tot zowel meerdere services als toegang met één service. Maak een Cognitive Services-resource als u van plan bent toegang te krijgen tot meerdere cognitieve services onder één eindpunt/sleutel. Maak een Form Recognizer resource voor alleen Form Recognizer toegang.

U kunt de resource maken met behulp van

Optie 1:Azure Portal

Optie 2:Azure CLI. Hieronder ziet u een voorbeeld van hoe u een Form Recognizer resource kunt maken met behulp van de 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

De client verifiëren

Als u wilt communiceren met de Form Recognizer-service, moet u een exemplaar van een client maken. Er zijn een eindpunt en referenties nodig om het clientobject te instantiëren.

Het eindpunt opzoeken

U kunt het eindpunt voor uw Form Recognizer-resource vinden met behulp van Azure Portal of Azure CLI:

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

De API-sleutel ophalen

U vindt de API-sleutel in Azure Portal of door de volgende Azure CLI-opdracht uit te voeren:

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

De client maken met AzureKeyCredential

Als u een API-sleutel als credential parameter wilt gebruiken, geeft u de sleutel door als een tekenreeks aan een exemplaar van 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)

De client maken met een Azure Active Directory-referentie

AzureKeyCredential verificatie wordt gebruikt in de voorbeelden in deze introductiehandleiding, maar u kunt zich ook verifiëren met Azure Active Directory met behulp van de azure-identity-bibliotheek . Houd er rekening mee dat regionale eindpunten geen ondersteuning bieden voor AAD-verificatie. Maak een aangepaste subdomeinnaam voor uw resource om dit type verificatie te kunnen gebruiken.

Als u het hieronder weergegeven Type DefaultAzureCredential of andere referentietypen wilt gebruiken die worden geleverd met de Azure SDK, installeert u het azure-identity pakket:

pip install azure-identity

U moet ook een nieuwe AAD-toepassing registreren en toegang verlenen tot Form Recognizer door de "Cognitive Services User" rol toe te wijzen aan uw service-principal.

Wanneer dit is voltooid, stelt u de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: 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
)

Belangrijkste concepten

FormRecognizerClient

FormRecognizerClient biedt bewerkingen voor:

  • Het herkennen van formuliervelden en -inhoud met aangepaste modellen die zijn getraind om uw aangepaste formulieren te herkennen. Deze waarden worden geretourneerd in een verzameling RecognizedForm-objecten.
  • Algemene velden herkennen van Amerikaanse ontvangstbewijzen, met behulp van een vooraf getraind ontvangstbewijsmodel. Deze velden en metagegevens worden geretourneerd in een verzameling RecognizedForm objecten.
  • Het herkennen van formulierinhoud, met inbegrip van tabellen, regels en woorden, zonder dat u een model hoeft te trainen. Formulierinhoud wordt geretourneerd in een verzameling FormPage-objecten.

Er worden voorbeeldcodefragmenten verstrekt ter illustratie van een FormRecognizerClient (FormRecognizerClient Recognize Forms Using a Custom Model).

FormTrainingClient

FormTrainingClient biedt bewerkingen voor:

  • Aangepaste modellen zonder labels trainen om alle velden en waarden in uw aangepaste formulieren te herkennen. Er wordt een CustomFormModel geretourneerd, dat aangeeft welke formuliertypen het model zal herkennen en welke velden het zal extraheren voor elk formuliertype. Zie de servicedocumentatie voor een gedetailleerdere uitleg.
  • Aangepaste modellen trainen met labels om specifieke velden en waarden die u opgeeft te herkennen door uw aangepaste formulieren te labelen. Er wordt een CustomFormModel geretourneerd, dat aangeeft welke velden het model zal extraheren, evenals de geschatte nauwkeurigheid van elk veld. Zie de servicedocumentatie voor een gedetailleerdere uitleg.
  • Modellen beheren die zijn gemaakt in uw account.
  • Het kopiëren van een aangepast model van de ene Form Recognizer-resource naar de andere.

Denk eraan dat modellen ook kunnen worden getraind met een grafische gebruikersinterface zoals het hulpprogramma voor het labelen van Form Recognizer.

Hier worden voorbeeldcodefragmenten verstrekt ter illustratie met behulp van een FormTrainingClient .

Long-Running bewerkingen

Langlopende bewerkingen zijn bewerkingen die bestaan uit een initiële aanvraag die naar de service wordt verzonden om een bewerking te starten, gevolgd door het pollen van de service met intervallen om te bepalen of de bewerking is voltooid of mislukt, en of deze is geslaagd, om het resultaat te verkrijgen.

Methoden voor het trainen van modellen, het herkennen van waarden uit formulieren of het kopiëren van modellen worden gemodelleerd als langdurige bewerkingen. De client maakt een begin_<method-name> methode beschikbaar die een LROPoller of AsyncLROPollerretourneert. Aanroepers moeten wachten tot de bewerking is voltooid door het poller-object aan te roepen result() dat is geretourneerd door de begin_<method-name> methode. Voorbeeldcodefragmenten worden gegeven ter illustratie van het gebruik van langlopende bewerkingen hieronder.

Voorbeelden

De volgende sectie bevat verschillende codefragmenten voor enkele van de meest voorkomende Form Recognizer taken, waaronder:

Formulieren herkennen met een aangepast model

Naam/waardeparen en tabelgegevens uit formulieren herkennen. Deze modellen worden getraind met uw eigen gegevens, zodat ze zijn afgestemd op uw formulieren. Voor de beste resultaten moet u alleen formulieren herkennen van hetzelfde formuliertype waarop het aangepaste model is getraind.

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

U kunt ook een formulier-URL gebruiken om aangepaste formulieren te herkennen met behulp van de begin_recognize_custom_forms_from_url methode . De _from_url methoden bestaan voor alle methoden voor herkennen.

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()

Inhoud herkennen

Tekst- en tabelstructuren herkennen, samen met de coördinaten van het begrenzingsvak, uit documenten.

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

Ontvangstbevestigingen herkennen

Gegevens van amerikaanse verkoopontvangsten herkennen met behulp van een vooraf samengesteld model. Ontvangstbewijzen die door de service worden herkend, vindt u hier.

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

Een model trainen

Een aangepast model trainen op uw eigen formuliertype. Het resulterende model kan worden gebruikt om waarden te herkennen uit de typen formulieren waarop het is getraind. Geef een SAS-URL van de container op voor uw Azure Storage Blob-container waar u de trainingsdocumenten opslaat. Als trainingsbestanden zich in een submap in de container bevinden, gebruikt u het trefwoordargument voorvoegsel om op te geven onder welke map moet worden getraind.

Meer informatie over het instellen van een container en de vereiste bestandsstructuur vindt u in de servicedocumentatie.

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

Uw modellen beheren

Beheer de aangepaste modellen die aan uw account zijn gekoppeld.

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

Problemen oplossen

Algemeen

Form Recognizer clientbibliotheek genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op DEBUG-niveau met aanvraag/antwoord-body's en niet-geredigeerde headers, kan worden ingeschakeld op een client met het sleutelwoordargument 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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

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

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de naslagdocumentatie van Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Volgende stappen

De volgende sectie bevat verschillende codefragmenten die veelvoorkomende patronen illustreren die worden gebruikt in de Form Recognizer Python-API.

Meer voorbeeldcode

Deze codevoorbeelden tonen veelvoorkomende scenariobewerkingen met de Azure Form Recognizer-clientbibliotheek.

Asynchrone API's

Deze bibliotheek bevat ook een volledige asynchrone API die wordt ondersteund in Python 3.5+. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Asynchrone clients bevinden zich onder de azure.ai.formrecognizer.aio naamruimte.

Aanvullende documentatie

Zie de Form Recognizer documentatie over docs.microsoft.com voor uitgebreidere documentatie over Azure Cognitive Services Form Recognizer.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.