Azure Formigenkänning-klientbibliotek för Python – version 3.0.0

  • Artikel

Azure Cognitive Services Formigenkänning är en molntjänst som använder maskininlärning för att identifiera text- och tabelldata från formulärdokument. Den innehåller följande huvudsakliga funktioner:

  • Anpassade modeller – Identifiera fältvärden och tabelldata från formulär. Dessa modeller tränas med dina egna data, så de är skräddarsydda för dina formulär.
  • Innehålls-API – Identifiera text- och tabellstrukturer, tillsammans med deras koordinater för avgränsningsrutor, från dokument. Motsvarar REST-tjänstens Layout-API.
  • Fördefinierad kvittomodell – Identifiera data från försäljningskvitton i USA med hjälp av en fördefinierad modell.

| Källkod Paket (PyPI) | API-referensdokumentation| Produktdokumentation | Prover

Komma igång

Förutsättningar

Installera paketet

Installera Azure Formigenkänning-klientbiblioteket för Python – version 3.0.0 med pip:

pip install azure-ai-formrecognizer

Obs! Den här versionen av klientbiblioteket stöder v2.0-versionen av Formigenkänning-tjänsten

Skapa en Formigenkänning resurs

Formigenkänning stöder åtkomst med både flera tjänster och en enda tjänst. Skapa en Cognitive Services-resurs om du planerar att komma åt flera kognitiva tjänster under en enda slutpunkt/nyckel. För endast Formigenkänning åtkomst skapar du en Formigenkänning resurs.

Du kan skapa resursen med hjälp av

Alternativ 1:Azure-portalen

Alternativ 2:Azure CLI. Nedan visas ett exempel på hur du kan skapa en Formigenkänning resurs med hjälp av 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

Autentisera klienten

För att kunna interagera med Formigenkänning-tjänsten måste du skapa en instans av en klient. En slutpunkt och autentiseringsuppgifter krävs för att instansiera klientobjektet.

Leta upp slutpunkten

Du hittar slutpunkten för din Formigenkänning resurs med hjälp av Azure-portalen eller Azure CLI:

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

Hämta API-nyckeln

DU hittar API-nyckeln i Azure-portalen eller genom att köra följande Azure CLI-kommando:

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

Skapa klienten med AzureKeyCredential

Om du vill använda en API-nyckel som credential parameter skickar du nyckeln som en sträng till en instans av 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)

Skapa klienten med en Azure Active Directory-autentiseringsuppgift

AzureKeyCredential autentisering används i exemplen i den här komma igång-guiden, men du kan också autentisera med Azure Active Directory med hjälp av biblioteket azure-identity . Observera att regionala slutpunkter inte stöder AAD-autentisering. Skapa ett anpassat underdomännamn för resursen för att kunna använda den här typen av autentisering.

Om du vill använda typen DefaultAzureCredential som visas nedan eller andra typer av autentiseringsuppgifter som medföljer Azure SDK installerar azure-identity du paketet:

pip install azure-identity

Du måste också registrera ett nytt AAD-program och bevilja åtkomst till Formigenkänning genom att tilldela "Cognitive Services User" rollen till tjänstens huvudnamn.

När det är klart anger du värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: 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
)

Viktiga begrepp

FormRecognizerClient

FormRecognizerClient tillhandahåller åtgärder för:

  • Känna igen formulärfält och innehåll med hjälp av anpassade modeller som tränats att känna igen dina anpassade formulär. Dessa värden returneras i en samling RecognizedForm objekt.
  • Känna igen vanliga fält från amerikanska kvitton med hjälp av en förtränad kvittomodell. Dessa fält och metadata returneras i en samling RecognizedForm objekt.
  • Känna igen formulärinnehåll, inklusive tabeller, rader och ord, utan att behöva träna en modell. Formulärinnehåll returneras i en samling FormPage objekt.

Exempelkodfragment tillhandahålls för att illustrera med hjälp av ett FormRecognizerClient ) här.

FormTrainingClient

FormTrainingClient tillhandahåller åtgärder för:

  • Träna anpassade modeller utan etiketter för att identifiera alla fält och värden som finns i dina anpassade formulär. En CustomFormModel returneras som anger de formulärtyper som modellen känner igen och de fält som den extraherar för varje formulärtyp. En mer detaljerad förklaring finns i tjänstdokumentationen .
  • Träna anpassade modeller med etiketter för att identifiera specifika fält och värden som du anger genom att märka dina anpassade formulär. En CustomFormModel returneras som anger de fält som modellen ska extrahera, samt den uppskattade noggrannheten för varje fält. En mer detaljerad förklaring finns i tjänstdokumentationen .
  • Hantera modeller som skapats i ditt konto.
  • Kopiera en anpassad modell från en Formigenkänning resurs till en annan.

Observera att modeller också kan tränas med hjälp av ett grafiskt användargränssnitt, till exempel Formigenkänning Labeling Tool.

Exempelkodfragment tillhandahålls för att illustrera med hjälp av en FormTrainingClient här.

Long-Running åtgärder

Långvariga åtgärder är åtgärder som består av en första begäran som skickas till tjänsten för att starta en åtgärd, följt av avsökning av tjänsten med jämna mellanrum för att avgöra om åtgärden har slutförts eller misslyckats, och om den har lyckats för att få resultatet.

Metoder som tränar modeller, identifierar värden från formulär eller kopierar modeller modelleras som långvariga åtgärder. Klienten exponerar en begin_<method-name> metod som returnerar en LROPoller eller AsyncLROPoller. Anropare bör vänta tills åtgärden har slutförts genom att anropa result() det pollerobjekt som returneras från begin_<method-name> metoden . Exempelkodfragment tillhandahålls för att illustrera med hjälp av långvariga åtgärder nedan.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Formigenkänning uppgifter, inklusive:

Identifiera formulär med en anpassad modell

Identifiera namn/värde-par och tabelldata från formulär. Dessa modeller tränas med dina egna data, så de är skräddarsydda för dina formulär. För bästa resultat bör du bara känna igen formulär av samma formulärtyp som den anpassade modellen har tränats på.

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

Du kan också använda en formulär-URL för att identifiera anpassade formulär med hjälp av begin_recognize_custom_forms_from_url metoden . Metoderna _from_url finns för alla igenkänningsmetoder.

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

Identifiera innehåll

Identifiera text- och tabellstrukturer, tillsammans med deras koordinater för avgränsningsrutor, från dokument.

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

Identifiera kvitton

Identifiera data från försäljningskvitton i USA med hjälp av en fördefinierad modell. Kvittofält som identifieras av tjänsten finns här.

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

Träna en modell

Träna en anpassad modell på din egen formulärtyp. Den resulterande modellen kan användas för att identifiera värden från de typer av formulär som den har tränats på. Ange en CONTAINER-SAS-URL till din Azure Storage Blob-container där du lagrar träningsdokumenten. Om träningsfilerna finns i en undermapp i containern använder du nyckelordsargumentet prefix för att ange under vilken mapp som ska tränas.

Mer information om hur du konfigurerar en container och nödvändig filstruktur finns i tjänstdokumentationen.

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

Hantera dina modeller

Hantera de anpassade modeller som är kopplade till ditt konto.

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

Felsökning

Allmänt

Formigenkänning klientbibliotek skapar undantag som definierats i Azure Core.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med nyckelordsargumentet 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)

logging_enable På samma sätt kan du aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

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

Valfri konfiguration

Valfria nyckelordsargument kan skickas på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Nästa steg

I följande avsnitt finns flera kodfragment som illustrerar vanliga mönster som används i Formigenkänning Python API.

Mer exempelkod

Dessa kodexempel visar vanliga scenarioåtgärder med Azure Formigenkänning-klientbiblioteket.

Async-API:er

Det här biblioteket innehåller även ett fullständigt asynkront API som stöds i Python 3.5+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Async-klienter finns under azure.ai.formrecognizer.aio namnområdet.

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Cognitive Services-Formigenkänning finns i Formigenkänning dokumentation om docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.