Azure Formularerkennung-Clientbibliothek für Python– Version 3.0.0

  • Artikel

Azure Cognitive Services Formularerkennung ist ein Clouddienst, der maschinelles Lernen verwendet, um Text- und Tabellendaten aus Formulardokumenten zu erkennen. Es umfasst die folgenden Hauptfunktionen:

  • Benutzerdefinierte Modelle: Erkennen von Feldwerten und Tabellendaten aus Formularen. Diese Modelle werden mit Ihren eigenen Daten trainiert, sodass Sie auf Ihre Formulare zugeschnitten sind.
  • Inhalts-API: Erkennt Text- und Tabellenstrukturen zusammen mit ihren Begrenzungsrahmenkoordinaten aus Dokumenten. Entspricht der Layout-API des REST-Diensts.
  • Vordefiniertes Belegmodell: Erkennt Daten von US-Verkaufsbelegen mithilfe eines vordefinierten Modells.

Quellcode | Paket (PyPI) | API-Referenzdokumentation| Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Formularerkennung-Clientbibliothek für Python– Version 3.0.0 mit pip:

pip install azure-ai-formrecognizer

Hinweis: Diese Version der Clientbibliothek unterstützt die v2.0-Version des Formularerkennung-Diensts.

Erstellen einer Formularerkennungsressource

Formularerkennung unterstützt sowohl den Zugriff mit mehreren Diensten als auch den Zugriff mit einem einzelnen Dienst. Erstellen Sie eine Cognitive Services-Ressource, wenn Sie planen, über einen einzelnen Endpunkt bzw. Schlüssel auf mehrere Cognitive Services-Instanzen zuzugreifen. Erstellen Sie eine Formularerkennungsressource, falls nur auf die Formularerkennung zugegriffen werden soll.

Sie können die Ressource mit

Option 1:Azure-Portal

Option 2:Azure CLI. Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Formularerkennung-Ressource mithilfe der CLI erstellen können:

# 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

Authentifizieren des Clients

Um mit dem Formularerkennung-Dienst zu interagieren, müssen Sie eine Instanz eines Clients erstellen. Ein Endpunkt und Anmeldeinformationen sind erforderlich, um das Clientobjekt zu instanziieren.

Nachschlagen des Endpunkts

Sie finden den Endpunkt für Ihre Formularerkennung-Ressource über das Azure-Portal oder die Azure CLI:

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

Abrufen des API-Schlüssels

Den API-Schlüssel finden Sie im Azure-Portal oder durch Ausführen des folgenden Azure CLI-Befehls:

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

Erstellen des Clients mit AzureKeyCredential

Um einen API-Schlüssel als credential Parameter zu verwenden, übergeben Sie den Schlüssel als Zeichenfolge an eine Instanz von 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)

Erstellen des Clients mit Azure Active Directory-Anmeldeinformationen

AzureKeyCredential Die Authentifizierung wird in den Beispielen in diesem Leitfaden zu den ersten Schritten verwendet, Aber Sie können sich auch mithilfe der Azure-Identity-Bibliothek bei Azure Active Directory authentifizieren. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie einen benutzerdefinierten Unterdomänennamen für Ihre Ressource, um diese Art der Authentifizierung zu verwenden.

Um den unten gezeigten DefaultAzureCredential-Typ oder andere Anmeldeinformationstypen zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das azure-identity Paket:

pip install azure-identity

Außerdem müssen Sie eine neue AAD-Anwendung registrieren und Zugriff auf Formularerkennung gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Legen Sie nach Abschluss des Vorgangs die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: 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
)

Wichtige Begriffe

FormRecognizerClient

FormRecognizerClient stellt Vorgänge für Folgendes bereit:

  • Erkennen von Formularfeldern und -inhalten mithilfe von benutzerdefinierten Modellen, die zur Erkennung Ihrer benutzerdefinierten Formulare trainiert wurden. Diese Werte werden in einer Sammlung von RecognizedForm-Objekten zurückgegeben.
  • Erkennen gängiger Felder aus US-Belegen mithilfe eines vorab trainierten Belegmodells. Diese Felder und Metadaten werden in einer Auflistung von RecognizedForm -Objekten zurückgegeben.
  • Erkennen von Formularinhalten (einschließlich Tabellen, Zeilen und Wörtern), ohne dass ein Modell trainiert werden muss. Der Formularinhalt wird in einer Sammlung von FormPage-Objekten zurückgegeben.

Beispielcodeausschnitte werden bereitgestellt, um die Verwendung eines FormRecognizerClient hier zu veranschaulichen.

FormTrainingClient

FormTrainingClient stellt Vorgänge für Folgendes bereit:

  • Trainieren von benutzerdefinierten Modellen ohne Bezeichnungen, um alle Felder und Werte in Ihren benutzerdefinierten Formularen zu erkennen. Ein CustomFormModel-Element wird zurückgegeben, das angibt, welche Formulartypen vom Modell erkannt und welche Felder für jeden Formtyp extrahiert werden. Eine ausführlichere Erläuterung finden Sie in der Dienstdokumentation .
  • Trainieren von benutzerdefinierten Modellen mit Bezeichnungen, um bestimmte Felder und Werte zu erkennen, die Sie angeben, indem Sie Ihre benutzerdefinierten Formulare bezeichnen. Ein CustomFormModel-Element wird zurückgegeben, das die vom Modell extrahierten Felder sowie die geschätzte Genauigkeit für jedes Feld angibt. Eine ausführlichere Erläuterung finden Sie in der Dienstdokumentation .
  • Verwalten der in Ihrem Konto erstellten Modelle
  • Kopieren eines benutzerdefinierten Modells aus einer Formularerkennungsressource in eine andere

Beachten Sie, dass Modelle auch mithilfe einer grafischen Benutzeroberfläche trainiert werden können, z. B. mit dem Formularerkennungstool für die Bezeichnung.

Beispielcodeausschnitte werden bereitgestellt, um die Verwendung eines FormTrainingClient hier zu veranschaulichen.

Long-Running Vorgänge

Vorgänge mit langer Ausführungsdauer sind Vorgänge, die aus einer anfänglichen Anforderung bestehen, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von der Abfrage des Diensts in Intervallen, um festzustellen, ob der Vorgang abgeschlossen oder fehlgeschlagen ist, und ob er erfolgreich war, um das Ergebnis zu erhalten.

Methoden, die Modelle trainieren, Werte aus Formularen erkennen oder Modelle kopieren, werden als Vorgänge mit langer Ausführungsdauer modelliert. Der Client macht eine begin_<method-name> Methode verfügbar, die ein LROPoller oder AsyncLROPollerzurückgibt. Aufrufer sollten warten, bis der Vorgang abgeschlossen ist, indem sie für das Von der begin_<method-name> -Methode zurückgegebene Poller-Objekt aufrufenresult(). Beispielcodeausschnitte werden bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungszeit zu veranschaulichen unten.

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die einige der gängigsten Formularerkennung Aufgaben abdecken, einschließlich:

Erkennen von Formularen mithilfe eines benutzerdefinierten Modells

Erkennen von Name-Wert-Paaren und Tabellendaten aus Formularen. Diese Modelle werden mit Ihren eigenen Daten trainiert, sodass Sie auf Ihre Formulare zugeschnitten sind. Um optimale Ergebnisse zu erzielen, sollten Sie nur Formulare desselben Formulartyps erkennen, für den das benutzerdefinierte Modell trainiert wurde.

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

Alternativ kann auch eine Formular-URL verwendet werden, um benutzerdefinierte Formulare mithilfe der begin_recognize_custom_forms_from_url -Methode zu erkennen. Die _from_url Methoden sind für alle Erkennungsmethoden vorhanden.

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

Erkennen von Inhalten

Erkennen von Text- und Tabellenstrukturen zusammen mit ihren Begrenzungsrahmenkoordinaten aus Dokumenten.

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

Erkennen von Belegen

Erkennen von Daten aus US-Verkaufsbelegen mithilfe eines vordefinierten Modells. Die vom Dienst erkannten Belegfelder finden Sie 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))

Trainieren eines Modells

Trainieren Sie ein benutzerdefiniertes Modell für Ihren eigenen Formulartyp. Das resultierende Modell kann verwendet werden, um Werte aus den Formulartypen zu erkennen, für die es trainiert wurde. Geben Sie eine CONTAINER-SAS-URL für Ihren Azure Storage-Blobcontainer an, in dem Sie die Trainingsdokumente speichern. Wenn sich Trainingsdateien in einem Unterordner im Container befinden, verwenden Sie das Präfixschlüsselwortargument , um anzugeben, unter welchem Ordner trainiert werden soll.

Weitere Informationen zum Einrichten eines Containers und zur erforderlichen Dateistruktur finden Sie in der Dienstdokumentation.

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

Verwalten Ihrer Modelle

Verwalten Sie die benutzerdefinierten Modelle, die an Ihr Konto angefügt sind.

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

Problembehandlung

Allgemein

Formularerkennung Clientbibliothek löst ausnahmen aus, die in Azure Core definiert sind.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine ausführliche Protokollierung auf der Ebene DEBUG, einschließlich Anforderungs-/Antworttexten und vollständiger Header, kann auf einem Client mit dem Schlüsselwortargument logging_enable aktiviert werden:

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)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

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

Optionale Konfiguration

Optionale Schlüsselwortargumente können auf Client- und Vorgangsebene übergeben werden. Die azure-core-Referenzdokumentation beschreibt verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr.

Nächste Schritte

Der folgende Abschnitt enthält mehrere Codeausschnitte, die gängige Muster veranschaulichen, die in der Formularerkennung Python-API verwendet werden.

Weiterer Beispielcode

Diese Codebeispiele zeigen häufige Szenariovorgänge mit der Azure Formularerkennung-Clientbibliothek.

Asynchrone APIs

Diese Bibliothek enthält auch eine vollständige asynchrone API, die unter Python 3.5 und höher unterstützt wird. Um ihn verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Asynchrone Clients befinden sich unter dem azure.ai.formrecognizer.aio Namespace.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Cognitive Services Formularerkennung finden Sie in der Formularerkennung-Dokumentation zu docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.