Sdílet prostřednictvím

Klientská knihovna Azure Rozpoznávání formulářů pro Python – verze 3.0.0

  • Článek

Azure Cognitive Services Rozpoznávání formulářů je cloudová služba, která pomocí strojového učení rozpoznává textová a tabulková data z formulářových dokumentů. Zahrnuje následující hlavní funkce:

  • Vlastní modely – Rozpoznávají hodnoty polí a data tabulky z formulářů. Tyto modely se trénují s vlastními daty, takže jsou přizpůsobené vašim formulářům.
  • Rozhraní CONTENT API – Rozpozná z dokumentů textové struktury a struktury tabulek spolu se souřadnicemi ohraničujícího rámečku. Odpovídá rozhraní LAYOUT API služby REST.
  • Předem vytvořený model účtenky – Rozpozná data z prodejních dokladů USA pomocí předem vytvořeného modelu.

Zdrojový kód | Balíček (PyPI) | Referenční dokumentace k| rozhraní API Dokumentace k | produktu Vzorky

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Rozpoznávání formulářů pro Python verze 3.0.0 pomocí příkazu pip:

pip install azure-ai-formrecognizer

Poznámka: Tato verze klientské knihovny podporuje verzi v2.0 služby Rozpoznávání formulářů.

Vytvoření prostředku Rozpoznávání formulářů

Rozpoznávání formulářů podporuje přístup s více službami i s jednou službou. Pokud plánujete přístup k více kognitivním službám v rámci jednoho koncového bodu nebo klíče, vytvořte prostředek Cognitive Services. Pouze pro Rozpoznávání formulářů přístup vytvořte prostředek Rozpoznávání formulářů.

Prostředek můžete vytvořit pomocí příkazu

Možnost 1:Azure Portal

Možnost 2:Azure CLI Níže je příklad vytvoření prostředku Rozpoznávání formulářů pomocí rozhraní příkazového řádku:

# 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

Ověření klienta

Pokud chcete pracovat se službou Rozpoznávání formulářů, budete muset vytvořit instanci klienta. K vytvoření instance objektu klienta jsou nezbytné koncové body a přihlašovací údaje .

Vyhledání koncového bodu

Koncový bod pro prostředek Rozpoznávání formulářů můžete najít pomocí webu Azure Portal nebo Azure CLI:

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

Získání klíče rozhraní API

Klíč rozhraní API najdete na webu Azure Portal nebo spuštěním následujícího příkazu Azure CLI:

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

Vytvoření klienta pomocí AzureKeyCredential

Pokud chcete jako credential parametr použít klíč rozhraní API, předejte klíč jako řetězec do instance 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)

Vytvoření klienta s přihlašovacími údaji Azure Active Directory

AzureKeyCredential Ověřování se používá v příkladech v této příručce Začínáme, ale můžete se také ověřit v Azure Active Directory pomocí knihovny azure-identity . Upozorňujeme, že regionální koncové body nepodporují ověřování AAD. Vytvořte pro svůj prostředek vlastní název subdomény , abyste mohli tento typ ověřování používat.

Pokud chcete použít níže uvedený typ DefaultAzureCredential nebo jiné typy přihlašovacích údajů poskytované se sadou Azure SDK, nainstalujte azure-identity balíček :

pip install azure-identity

Budete také muset zaregistrovat novou aplikaci AAD a udělit přístup k Rozpoznávání formulářů přiřazením role k instančnímu objektu"Cognitive Services User".

Po dokončení nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: 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
)

Klíčové koncepty

FormRecognizerClient

FormRecognizerClient poskytuje operace pro:

  • Rozpoznávání polí a obsahu formuláře pomocí vlastních modelů vytrénovaných tak, aby rozpoznaly vaše vlastní formuláře. Tyto hodnoty jsou vráceny v kolekci RecognizedForm objektů.
  • Rozpoznávání běžných polí z účtenek USA pomocí předem natrénovaného modelu účtenek Tato pole a metadata jsou vrácena v kolekci RecognizedForm objektů.
  • Rozpoznávání obsahu formuláře, včetně tabulek, řádků a slov, bez nutnosti trénování modelu Obsah formuláře je vrácen v kolekci FormPage objektů.

Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití FormRecognizerClient .

FormTrainingClient

FormTrainingClient poskytuje operace pro:

  • Trénování vlastních modelů bez popisků k rozpoznávání všech polí a hodnot nalezených ve vlastních formulářích Vrátí se hodnota označující CustomFormModel typy formulářů, které model rozpozná, a pole, která bude extrahovat pro každý typ formuláře. Podrobnější vysvětlení najdete v dokumentaci ke službě .
  • Trénování vlastních modelů pomocí popisků k rozpoznávání konkrétních polí a hodnot, které zadáte popisky vlastních formulářů. Vrátí CustomFormModel se hodnota označující pole, která bude model extrahovat, a také odhadovanou přesnost jednotlivých polí. Podrobnější vysvětlení najdete v dokumentaci ke službě .
  • Správa modelů vytvořených ve vašem účtu
  • Kopírování vlastního modelu z jednoho prostředku Rozpoznávání formulářů do jiného.

Mějte na paměti, že modely lze také vytrénovat pomocí grafického uživatelského rozhraní, jako je Rozpoznávání formulářů Labeling Tool.

Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití třídy FormTrainingClient .

operace Long-Running

Dlouhotrvající operace jsou operace, které se skládají z počátečního požadavku odeslaného službě na spuštění operace, po kterém následuje dotazování služby v intervalech, aby se zjistilo, jestli se operace dokončila nebo selhala, a jestli byla úspěšná, aby získala výsledek.

Metody, které trénují modely, rozpoznávají hodnoty z formulářů nebo kopírují modely, se modelují jako dlouhotrvající operace. Klient zveřejňuje metodu begin_<method-name> , která vrací LROPoller nebo AsyncLROPoller. Volající by měli počkat na dokončení operace voláním result() na poller objekt vrácený metodou begin_<method-name> . Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití dlouhotrvajících operací jsou uvedené níže.

Příklady

Následující část obsahuje několik fragmentů kódu, které pokrývají některé nejběžnější úlohy Rozpoznávání formulářů, mezi které patří:

Rozpoznávání formulářů pomocí vlastního modelu

Rozpoznávat páry název/hodnota a data tabulky z formulářů. Tyto modely se trénují s vlastními daty, takže jsou přizpůsobené vašim formulářům. Nejlepších výsledků dosáhnete, když rozpoznáte pouze formuláře stejného typu, na který byl vlastní model trénován.

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

Alternativně lze k rozpoznávání vlastních formulářů použít také adresu URL formuláře pomocí metody .begin_recognize_custom_forms_from_url Metody _from_url existují pro všechny metody rozpoznávání.

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

Rozpoznávání obsahu

Rozpoznávání textových a tabulkových struktur spolu se souřadnicemi ohraničujícího rámečku v dokumentech

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

Recognize Receipts

Rozpoznávání dat z prodejních dokladů USA pomocí předem připraveného modelu Pole účtenky rozpoznaná službou najdete tady.

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

Učení modelu

Trénování vlastního modelu na vlastním typu formuláře Výsledný model lze použít k rozpoznávání hodnot z typů formulářů, na které byl natrénován. Zadejte adresu URL SAS kontejneru pro kontejner Azure Storage Blob, do kterého ukládáte trénovací dokumenty. Pokud se trénovací soubory nacházejí v podsložce kontejneru, použijte argument předpony klíčového slova a určete, ve které složce se má trénovat.

Další podrobnosti o nastavení kontejneru a požadované struktury souborů najdete v dokumentaci ke službě.

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

Správa modelů

Spravujte vlastní modely připojené k vašemu účtu.

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

Poradce při potížích

Obecné

Rozpoznávání formulářů klientská knihovna vyvolá výjimky definované v Azure Core.

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně DEBUG, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit v klientovi s argumentem klíčového logging_enable slova:

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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Volitelná konfigurace

Volitelné argumenty klíčových slov lze předat na úrovni klienta a pro jednotlivé operace. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Další kroky

Následující část obsahuje několik fragmentů kódu, které ilustrují běžné vzory používané v rozhraní Rozpoznávání formulářů Python API.

Další vzorový kód

Tyto ukázky kódu ukazují běžné scénáře operací s klientskou knihovnou Azure Rozpoznávání formulářů.

Asynchronní rozhraní API

Tato knihovna také obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.5 nebo novějším. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Asynchronní klienti se nacházejí v oboru azure.ai.formrecognizer.aio názvů .

Další dokumentace

Podrobnější dokumentaci ke službě Azure Cognitive Services Rozpoznávání formulářů najdete v dokumentaci k Rozpoznávání formulářů docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete v cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.