Share via

Azure Form Recognizer Python-ügyfélkódtár – 3.0.0-s verzió

  • Cikk

Az Azure Cognitive Services Form Recognizer egy felhőalapú szolgáltatás, amely gépi tanulással ismeri fel az űrlapdokumentumokból származó szöveges és táblázatadatokat. A következő fő funkciókat tartalmazza:

  • Egyéni modellek – Mezőértékek és táblaadatok felismerése űrlapokból. Ezek a modellek saját adatokkal vannak betanva, így az űrlapokra vannak szabva.
  • Content API – A dokumentumok szöveg- és táblázatstruktúráinak, valamint határolókeret-koordinátáinak felismerése. A REST szolgáltatás Layout API-jának felel meg.
  • Előre összeállított visszaigazolási modell – Az USA-beli értékesítési nyugtákból származó adatok felismerése előre összeállított modellel.

Forráskód | Csomag (PyPI) | API-referenciadokumentáció| Termékdokumentáció | Minták

Első lépések

Előfeltételek

A csomag telepítése

Telepítse a Pythonhoz készült Azure Form Recognizer ügyfélkódtárat – 3.0.0-s verzió pip használatával:

pip install azure-ai-formrecognizer

Megjegyzés: Az ügyfélkódtár ezen verziója támogatja a Form Recognizer szolgáltatás 2.0-s verzióját

Form Recognizer-erőforrás létrehozása

Form Recognizer támogatja a többszolgáltatásos és az egyszolgáltatásos hozzáférést is. Létrehozhat egy Cognitive Services-erőforrást, ha több kognitív szolgáltatást szeretne elérni egyetlen végpont/kulcs alatt. Csak Form Recognizer hozzáféréshez hozzon létre egy Form Recognizer erőforrást.

Az erőforrást a következővel hozhatja létre:

1. lehetőség:Azure Portal

2. lehetőség:Azure CLI. Az alábbiakban egy példa látható arra, hogyan hozhat létre Form Recognizer erőforrást a parancssori felület használatával:

# 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

Az ügyfél hitelesítése

A Form Recognizer szolgáltatás használatához létre kell hoznia egy ügyfélpéldányt. Az ügyfélobjektum példányosításához végpontra és hitelesítő adatokra van szükség.

A végpont keresése

A Form Recognizer erőforrás végpontját az Azure Portalon vagy az Azure CLI-vel találja meg:

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

Az API-kulcs lekérése

Az API-kulcs megtalálható az Azure Portalon, vagy az alábbi Azure CLI-parancs futtatásával:

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

Az ügyfél létrehozása az AzureKeyCredential használatával

Ha egy API-kulcsot szeretne paraméterként credential használni, adja át a kulcsot sztringként az AzureKeyCredential egy példányába.

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)

Az ügyfél létrehozása Azure Active Directory-hitelesítő adatokkal

AzureKeyCredential a hitelesítést az első lépések útmutatójában szereplő példákban használjuk, de az Azure Active Directoryval is hitelesíthető az azure-identity kódtár használatával. Vegye figyelembe, hogy a regionális végpontok nem támogatják az AAD-hitelesítést. Hozzon létre egy egyéni altartománynevet az erőforráshoz az ilyen típusú hitelesítés használatához.

Az alább látható DefaultAzureCredential típus vagy az Azure SDK-hoz biztosított egyéb hitelesítő adattípusok használatához telepítse a azure-identity csomagot:

pip install azure-identity

Emellett regisztrálnia kell egy új AAD-alkalmazást, és hozzáférést kell adnia a Form Recognizer a szerepkörnek a "Cognitive Services User" szolgáltatásnévhez való hozzárendelésével.

Miután végzett, állítsa be az AAD-alkalmazás ügyfél-azonosítójának, bérlőazonosítójának és titkos ügyfélkulcsának értékeit környezeti változókként: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_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
)

Fő fogalmak

FormRecognizerClient

FormRecognizerClient a következő műveletekhez nyújt műveleteket:

  • Űrlapmezők és -tartalmak felismerése az egyéni űrlapok felismerésére betanított egyéni modellek használatával. Ezeket az értékeket a rendszer objektumgyűjteményben RecognizedForm adja vissza.
  • Az egyesült államokbeli nyugták gyakori mezőinek felismerése előre betanított nyugtamodell használatával. Ezek a mezők és metaadatok objektumgyűjteményben RecognizedForm jelennek meg.
  • Az űrlap tartalmának felismerése, beleértve a táblákat, vonalakat és szavakat, anélkül, hogy be kellene tanítani egy modellt. Az űrlap tartalma objektumgyűjteményben FormPage lesz visszaadva.

A mintakódrészletek a FormRecognizerClient ) használatával történő szemléltetésére szolgálnak itt.

FormTrainingClient

FormTrainingClient a következő műveletekhez nyújt műveleteket:

  • Egyéni modellek betanítása címkék nélkül az egyéni űrlapokon található összes mező és érték felismeréséhez. A CustomFormModel visszaadott érték azt jelzi, hogy a modell milyen űrlaptípusokat ismer fel, és az egyes űrlaptípusokhoz kinyert mezőket. Részletesebb magyarázatért tekintse meg a szolgáltatás dokumentációját .
  • Egyéni modellek betanítása címkékkel az egyéni űrlapok címkézésével megadott mezők és értékek felismeréséhez. A CustomFormModel visszaadott érték jelzi a modell által kinyert mezőket, valamint az egyes mezők becsült pontosságát. Részletesebb magyarázatért tekintse meg a szolgáltatás dokumentációját .
  • A fiókban létrehozott modellek kezelése.
  • Egyéni modell másolása Form Recognizer erőforrásból egy másikba.

Vegye figyelembe, hogy a modelleket grafikus felhasználói felülettel is be lehet tanítani, például a Form Recognizer címkézési eszközzel.

Mintakódrészleteket biztosítunk, amelyek a FormTrainingClient segítségével szemléltetik itt.

Long-Running műveletek

A hosszú ideig futó műveletek olyan műveletek, amelyek a szolgáltatásnak küldött kezdeti kérésből állnak a művelet elindításához, majd a szolgáltatás időközönkénti lekérdezése annak megállapításához, hogy a művelet befejeződött-e vagy sikertelen volt-e, és ha sikerült, lekérni az eredményt.

A modellek betanítása, az űrlapokból származó értékek felismerése vagy a másolási modellek hosszú ideig futó műveletek. Az ügyfél egy metódust begin_<method-name> tesz elérhetővé, amely egy vagy AsyncLROPoller.LROPoller A hívóknak meg kell várniuk, amíg a művelet befejeződik a metódusból begin_<method-name> visszaadott poller objektum meghívásávalresult(). Az alábbi példákat talál a hosszú ideig futó műveletek szemléltetésére.

Példák

A következő szakasz számos kódrészletet tartalmaz, amelyek a leggyakoribb Form Recognizer feladatokat tartalmazzák, többek között a következőket:

Űrlapok felismerése egyéni modellel

Név-érték párok és táblaadatok felismerése űrlapokból. Ezek a modellek saját adatokkal vannak betanva, így az űrlapokra vannak szabva. A legjobb eredmény érdekében csak az egyéni modell betanításakor használt űrlaptípusú űrlapokat kell felismernie.

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

Másik lehetőségként az űrlap URL-címe is használható az egyéni űrlapok felismerésére a begin_recognize_custom_forms_from_url metódus használatával. A _from_url metódusok az összes felismerési metódushoz léteznek.

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

Tartalom felismerése

Szöveg- és táblázatszerkezetek felismerése a határolókeret koordinátáival együtt a dokumentumokból.

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

Nyugták felismerése

Az usa-beli értékesítési nyugtákból származó adatok felismerése előre összeállított modellel. A szolgáltatás által felismert nyugtamezők itt találhatók.

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

Modell betanítása

Egyéni modell betanítása saját űrlaptípuson. Az eredményként kapott modell használható a betanított űrlaptípusok értékeinek felismerésére. Adjon meg egy tároló SAS URL-címét az Azure Storage Blob-tárolóhoz, ahol a betanítási dokumentumokat tárolja. Ha a betanítási fájlok a tároló egyik almappájában találhatók, az előtag kulcsszóargumentumával adja meg, hogy melyik mappában kell betanítást végezni.

A tárolók és a szükséges fájlstruktúra beállításával kapcsolatos további részletek a szolgáltatás dokumentációjában találhatók.

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

A modellek kezelése

Kezelheti a fiókjához csatolt egyéni modelleket.

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

Hibaelhárítás

Általános kérdések

Form Recognizer ügyfélkódtár kivételeket hoz létre az Azure Core-ban.

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információk az INFO szintjén naplózva lesznek.

Részletes HIBAKERESÉSi szintű naplózás, beleértve a kérelem-/választörzseket és a nem felügyelt fejléceket, engedélyezhető egy ügyfélen a logging_enable kulcsszóargumentummal:

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)

Hasonlóképpen logging_enable , engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:

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

Választható konfiguráció

A választható kulcsszóargumentumok az ügyfél és a művelet szintjén is átadhatók. Az azure-core referenciadokumentáció az újrapróbálkozásokhoz, naplózáshoz, átviteli protokollokhoz és egyebekhez elérhető konfigurációkat ismerteti.

Következő lépések

Az alábbi szakasz számos kódrészletet tartalmaz, amely a Form Recognizer Python API-ban használt gyakori mintákat szemlélteti.

További mintakód

Ezek a kódminták az Azure Form Recognizer ügyfélkódtár gyakori forgatókönyvműveleteit mutatják be.

Async API-k

Ez a kódtár a Python 3.5+-on támogatott teljes async API-t is tartalmazza. A használatához először telepítenie kell egy aszinkron átvitelt, például az aiohttp-t. Az aszinkron ügyfelek a azure.ai.formrecognizer.aio névtérben találhatók.

További dokumentáció

Az Azure Cognitive Services Form Recognizer részletesebb dokumentációját a docs.microsoft.com Form Recognizer dokumentációjában találja.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. A részletekért látogasson el a cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.