Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Form Recognizer dla języka Python — wersja 3.0.0

  • Artykuł

Azure Cognitive Services Form Recognizer to usługa w chmurze, która używa uczenia maszynowego do rozpoznawania danych tekstowych i tabel z dokumentów formularzy. Obejmuje ona następujące główne funkcje:

  • Modele niestandardowe — rozpoznawanie wartości pól i danych tabeli z formularzy. Te modele są trenowane przy użyciu własnych danych, więc są dostosowane do formularzy.
  • Interfejs API zawartości — rozpoznawanie struktur tekstu i tabel wraz ze współrzędnymi pola ograniczenia na podstawie dokumentów. Odpowiada interfejsowi API układu usługi REST.
  • Wstępnie utworzony model paragonu — rozpoznawanie danych z rachunków sprzedaży w USA przy użyciu wstępnie utworzonego modelu.

Kod | źródłowy Pakiet (PyPI) | Dokumentacja referencyjna interfejsu| API Dokumentacja | produktu Próbki

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta usługi Azure Form Recognizer dla języka Python — wersja 3.0.0 za pomocą narzędzia pip:

pip install azure-ai-formrecognizer

Uwaga: ta wersja biblioteki klienta obsługuje wersję 2.0 usługi Form Recognizer

Tworzenie zasobu Form Recognizer

Form Recognizer obsługuje zarówno dostęp do wielu usług, jak i z jedną usługą. Utwórz zasób usług Cognitive Services, jeśli planujesz dostęp do wielu usług Cognitive Services w ramach jednego punktu końcowego/klucza. W przypadku dostępu tylko Form Recognizer utwórz zasób Form Recognizer.

Zasób można utworzyć przy użyciu polecenia

Opcja 1.Witryna Azure Portal

Opcja 2:Interfejs wiersza polecenia platformy Azure. Poniżej przedstawiono przykład tworzenia zasobu Form Recognizer przy użyciu interfejsu wiersza polecenia:

# 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

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Form Recognizer, należy utworzyć wystąpienie klienta. Punkt końcowy i poświadczenia są niezbędne do utworzenia wystąpienia obiektu klienta.

Szukanie punktu końcowego

Punkt końcowy zasobu Form Recognizer można znaleźć przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure:

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

Pobieranie klucza interfejsu API

Klucz interfejsu API można znaleźć w witrynie Azure Portal lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:

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

Tworzenie klienta za pomocą elementu AzureKeyCredential

Aby użyć klucza interfejsu API jako parametru credential , przekaż klucz jako ciąg do wystąpienia obiektu 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)

Tworzenie klienta przy użyciu poświadczeń usługi Azure Active Directory

AzureKeyCredential uwierzytelnianie jest używane w przykładach w tym przewodniku wprowadzającym, ale można również uwierzytelniać się w usłudze Azure Active Directory przy użyciu biblioteki azure-identity . Należy pamiętać, że regionalne punkty końcowe nie obsługują uwierzytelniania usługi AAD. Utwórz niestandardową nazwę poddomeny dla zasobu, aby użyć tego typu uwierzytelniania.

Aby użyć poniższego typu DefaultAzureCredential lub innych typów poświadczeń dostarczonych z zestawem Azure SDK, zainstaluj azure-identity pakiet:

pip install azure-identity

Należy również zarejestrować nową aplikację usługi AAD i udzielić dostępu do Form Recognizer, przypisując "Cognitive Services User" rolę do jednostki usługi.

Po zakończeniu ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i klucza tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: 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
)

Kluczowe pojęcia

FormRecognizerClient

FormRecognizerClient udostępnia operacje dla:

  • Rozpoznawanie pól formularzy i zawartości przy użyciu modeli niestandardowych wyszkolonych do rozpoznawania formularzy niestandardowych. Te wartości są zwracane w kolekcji RecognizedForm obiektów.
  • Rozpoznawanie typowych pól pochodzących z amerykańskich paragonów przy użyciu wstępnie wytrenowanego modelu paragonu. Te pola i metadane są zwracane w kolekcji RecognizedForm obiektów.
  • Rozpoznawanie zawartości formularza, w tym tabel, wierszy i słów, bez konieczności trenowania modelu. Zawartość formularza jest zwracana w kolekcji FormPage obiektów.

Przykładowe fragmenty kodu są udostępniane w celu zilustrowania przy użyciu formularzy Rozpoznawanie formularzy FormRecognizerClient tutaj.

FormTrainingClient

FormTrainingClient udostępnia operacje dla:

  • Trenowanie modeli niestandardowych bez etykiet w celu rozpoznawania wszystkich pól i wartości znalezionych w formularzach niestandardowych. Zwracany CustomFormModel jest element wskazujący typy formularzy rozpoznawane przez model, a pola wyodrębnione dla każdego typu formularza. Zapoznaj się z dokumentacją usługi , aby uzyskać bardziej szczegółowe wyjaśnienie.
  • Trenowanie modeli niestandardowych z etykietami w celu rozpoznawania określonych pól i wartości określonych przez etykietowanie formularzy niestandardowych. Zwracana CustomFormModel jest wartość wskazująca pola wyodrębnione przez model, a także szacowaną dokładność dla każdego pola. Zapoznaj się z dokumentacją usługi , aby uzyskać bardziej szczegółowe wyjaśnienie.
  • Zarządzanie modelami utworzonymi na koncie.
  • Kopiowanie modelu niestandardowego z jednego zasobu Form Recognizer do innego.

Należy pamiętać, że modele można również wytrenować przy użyciu graficznego interfejsu użytkownika, takiego jak narzędzie do etykietowania Form Recognizer.

Udostępniono przykładowe fragmenty kodu, aby zilustrować użycie metody FormTrainingClient w tym miejscu).

Operacje Long-Running

Długotrwałe operacje to operacje, które składają się z początkowego żądania wysłanego do usługi w celu uruchomienia operacji, a następnie sondowania usługi w odstępach czasu w celu ustalenia, czy operacja została ukończona, czy nie powiodła się, i jeśli zakończyła się pomyślnie, aby uzyskać wynik.

Metody uczenia modeli, rozpoznawania wartości z formularzy lub modeli kopiowania są modelowane jako długotrwałe operacje. Klient uwidacznia metodę zwracającą begin_<method-name> element LROPoller lub AsyncLROPoller. Obiekty wywołujące powinny czekać na zakończenie operacji przez wywołanie result() obiektu poller zwróconego begin_<method-name> z metody . Przykładowe fragmenty kodu są udostępniane w celu zilustrowania użycia długotrwałych operacji .

Przykłady

Poniższa sekcja zawiera kilka fragmentów kodu obejmujących niektóre z najczęstszych zadań Form Recognizer, w tym:

Rozpoznawanie formularzy przy użyciu modelu niestandardowego

Rozpoznawanie par nazwa/wartość i dane tabeli z formularzy. Te modele są trenowane przy użyciu własnych danych, więc są dostosowane do formularzy. Aby uzyskać najlepsze wyniki, należy rozpoznać tylko formularze tego samego typu, na którym został wytrenowany model niestandardowy.

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

Alternatywnie adres URL formularza może służyć do rozpoznawania formularzy niestandardowych przy użyciu begin_recognize_custom_forms_from_url metody . Metody _from_url istnieją dla wszystkich metod rozpoznawania.

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

Rozpoznawanie zawartości

Rozpoznawanie struktur tekstu i tabeli wraz ze współrzędnymi pola ograniczenia na podstawie dokumentów.

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

Rozpoznawanie potwierdzeń

Rozpoznawanie danych z rachunków sprzedaży w USA przy użyciu wstępnie utworzonego modelu. Pola paragonu rozpoznane przez usługę można znaleźć tutaj.

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

Szkolenie modelu

Trenowanie modelu niestandardowego na podstawie własnego typu formularza. Wynikowy model może służyć do rozpoznawania wartości z typów formularzy, na których został wytrenowany. Podaj adres URL sygnatury dostępu współdzielonego kontenera do kontenera obiektów blob usługi Azure Storage, w którym są przechowywane dokumenty szkoleniowe. Jeśli pliki szkoleniowe znajdują się w podfolderze w kontenerze, użyj argumentu słowa kluczowego prefiks , aby określić, w którym folderze mają być trenowane.

Więcej informacji na temat konfigurowania kontenera i wymaganej struktury plików można znaleźć w dokumentacji usługi.

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

Zarządzanie modelami

Zarządzanie modelami niestandardowymi dołączonymi do konta.

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

Rozwiązywanie problemów

Ogólne

Form Recognizer biblioteka klienta zgłosi wyjątki zdefiniowane w usłudze Azure Core.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem słowa kluczowego 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 Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje dotyczące ponownych prób, rejestrowania, protokołów transportowych i nie tylko.

Następne kroki

Poniższa sekcja zawiera kilka fragmentów kodu ilustrujących typowe wzorce używane w interfejsie API języka Python Form Recognizer.

Więcej przykładów kodu

Te przykłady kodu pokazują typowe operacje scenariuszy w bibliotece klienta usługi Azure Form Recognizer.

Asynchroniczne interfejsy API

Ta biblioteka zawiera również kompletny interfejs API asynchroniczny obsługiwany w języku Python 3.5 lub nowszym. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Klienci asynchroniczny znajdują się w azure.ai.formrecognizer.aio przestrzeni nazw.

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Cognitive Services Form Recognizer, zobacz dokumentację Form Recognizer dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.