Azure Form Recognizer Python-ügyfélkódtár – 3.0.0-s verzió
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 használatához Python 2.7 vagy 3.5 vagy újabb verzió szükséges.
- A csomag használatához Azure-előfizetéssel és Cognitive Services- vagy Form Recognizer-erőforrással kell rendelkeznie.
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_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
)
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
- Tartalom felismerése
- Nyugták felismerése
- Modell betanítása
- A modellek kezelése
Ű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.
- Ügyfélhitelesítés: sample_authentication.py
- Nyugták felismerése: sample_recognize_receipts.py
- Visszaigazolások felismerése URL-címről: sample_recognize_receipts_from_url.py
- Tartalom felismerése: sample_recognize_content.py
- Egyéni űrlapok felismerése: sample_recognize_custom_forms.py
- Modell betanítása címkék nélkül: sample_train_model_without_labels.py
- Modell betanítása címkékkel: sample_train_model_with_labels.py
- Egyéni modellek kezelése: sample_manage_custom_models.py
- Modell másolása Form Recognizer erőforrások között: sample_copy_model.py
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.
- Ügyfélhitelesítés: sample_authentication_async.py
- Nyugták felismerése: sample_recognize_receipts_async.py
- Visszaigazolások felismerése URL-címről: sample_recognize_receipts_from_url_async.py
- Tartalom felismerése: sample_recognize_content_async.py
- Egyéni űrlapok felismerése: sample_recognize_custom_forms_async.py
- Modell betanítása címkék nélkül: sample_train_model_without_labels_async.py
- Modell betanítása címkékkel: sample_train_model_with_labels_async.py
- Egyéni modellek kezelése: sample_manage_custom_models_async.py
- Modell másolása Form Recognizer erőforrások között: sample_copy_model_async.py
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.
Azure SDK for Python
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: