Bibliothèque de client Azure Form Recognizer pour Python - version 3.0.0

  • Article

Azure Cognitive Services Form Recognizer est un service cloud qui utilise le Machine Learning pour reconnaître les données de texte et de tableau à partir de documents de formulaire. Il inclut les principales fonctionnalités suivantes :

  • Modèles personnalisés : reconnaître les valeurs de champ et les données de table des formulaires. Ces modèles étant entraînés avec vos propres données, ils sont adaptés à vos formulaires.
  • API de contenu : reconnaître les structures de texte et de tableau, ainsi que leurs coordonnées de cadre englobant, à partir de documents. Correspond à l’API De disposition du service REST.
  • Modèle de reçu prédéfini : reconnaître les données des reçus de vente aux États-Unis à l’aide d’un modèle prédéfini.

| Code sourcePackage (PyPI) | Documentation de référence sur les| API | Documentation produitÉchantillons

Prise en main

Prérequis

Installer le package

Installez la bibliothèque de client Azure Form Recognizer pour Python - version 3.0.0 avec pip :

pip install azure-ai-formrecognizer

Remarque : Cette version de la bibliothèque cliente prend en charge la version v2.0 du service Form Recognizer

Créer une ressource Form Recognizer

Form Recognizer prend en charge à la fois l’accès multiservices et l’accès à service unique. Créez une ressource Cognitive Services si vous envisagez d’accéder à plusieurs services Cognitive Services sous un seul point de terminaison/clé. Pour l’accès à Form Recognizer uniquement, créez une ressource Form Recognizer.

Vous pouvez créer la ressource à l’aide de

Option 1 :Portail Azure

Option 2 :Azure CLI. Voici un exemple de création d’une ressource Form Recognizer à l’aide de l’interface 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

Authentifier le client

Pour interagir avec le service Form Recognizer, vous devez créer une instance d’un client. Un point de terminaison et des informations d’identification sont nécessaires pour instancier l’objet client.

Recherche du point de terminaison

Vous pouvez trouver le point de terminaison de votre ressource Form Recognizer à l’aide du portail Azure ou d’Azure CLI :

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

Obtenir la clé API

La clé API se trouve dans le portail Azure ou en exécutant la commande Azure CLI suivante :

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

Créer le client avec AzureKeyCredential

Pour utiliser une clé API comme credential paramètre, passez la clé sous forme de chaîne dans une instance d’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)

Créer le client avec des informations d’identification Azure Active Directory

AzureKeyCredential L’authentification est utilisée dans les exemples de ce guide de prise en main, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque azure-identity . Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Créez un nom de sous-domaine personnalisé pour votre ressource afin d’utiliser ce type d’authentification.

Pour utiliser le type DefaultAzureCredential indiqué ci-dessous, ou d’autres types d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le azure-identity package :

pip install azure-identity

Vous devez également inscrire une nouvelle application AAD et accorder l’accès à Form Recognizer en attribuant le "Cognitive Services User" rôle à votre principal de service.

Une fois l’opération terminée, définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : 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
)

Concepts clés

FormRecognizerClient

FormRecognizerClient propose des opérations pour :

  • Reconnaître les champs et le contenu de formulaires à l’aide de modèles personnalisés entraînés pour reconnaître vos formulaires personnalisés. Ces valeurs sont retournées dans une collection d’objets RecognizedForm.
  • Reconnaissance des champs courants des reçus américains, à l’aide d’un modèle de reçu préentraîné. Ces champs et métadonnées sont retournés dans une collection d’objets RecognizedForm .
  • Reconnaître le contenu des formulaires, notamment les tableaux, les lignes et les mots, sans avoir à entraîner un modèle. Le contenu des formulaires est retourné dans une collection d’objets FormPage.

Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’un FormulaireRecognizerClient ici.

FormTrainingClient

FormTrainingClient propose des opérations pour :

  • Formation de modèles personnalisés sans étiquettes pour reconnaître tous les champs et valeurs trouvés dans vos formulaires personnalisés. Un CustomFormModel est retourné indiquant les types de formulaire que le modèle va reconnaître et les champs qu’il va extraire pour chaque type de formulaire. Consultez la documentation du service pour obtenir une explication plus détaillée.
  • Formation de modèles personnalisés avec des étiquettes pour reconnaître des champs et des valeurs spécifiques que vous spécifiez en étiquetant vos formulaires personnalisés. Un CustomFormModel est retourné indiquant les champs que le modèle va extraire ainsi que la précision estimée pour chaque champ. Consultez la documentation du service pour obtenir une explication plus détaillée.
  • Gérer les modèles créés dans votre compte.
  • Copier un modèle personnalisé d’une ressource Form Recognizer vers une autre.

Notez que les modèles peuvent aussi être entraînés à partir d’une interface graphique utilisateur comme l’outil d’étiquetage Form Recognizer.

Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’un modèle FormTrainingClient .

opérations Long-Running

Les opérations de longue durée sont des opérations qui se composent d’une demande initiale envoyée au service pour démarrer une opération, suivie d’une interrogation du service à intervalles réguliers pour déterminer si l’opération s’est terminée ou a échoué, et si elle a réussi, pour obtenir le résultat.

Les méthodes qui entraînent des modèles, reconnaissent les valeurs des formulaires ou copient des modèles sont modélisées comme des opérations de longue durée. Le client expose une begin_<method-name> méthode qui retourne un LROPoller ou AsyncLROPoller. Les appelants doivent attendre la fin de l’opération en appelant result() sur l’objet poller retourné par la begin_<method-name> méthode . Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’opérations de longue durée ci-dessous.

Exemples

La section suivante fournit plusieurs extraits de code couvrant certaines des tâches Form Recognizer les plus courantes, notamment :

Reconnaître des formulaires à l’aide d’un modèle personnalisé

Reconnaître les paires nom/valeur et les données de table des formulaires. Ces modèles étant entraînés avec vos propres données, ils sont adaptés à vos formulaires. Pour de meilleurs résultats, vous devez reconnaître uniquement les formulaires du même type de formulaire que celui sur lequel le modèle personnalisé a été entraî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
        ))

Vous pouvez également utiliser une URL de formulaire pour reconnaître les formulaires personnalisés à l’aide de la begin_recognize_custom_forms_from_url méthode . Les _from_url méthodes existent pour toutes les méthodes de reconnaissance.

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

Reconnaître le contenu

Reconnaître les structures de texte et de tableau, ainsi que leurs coordonnées de cadre englobant, à partir de documents.

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

Reconnaître les reçus

Reconnaître les données des reçus de vente des États-Unis à l’aide d’un modèle prédéfini. Les champs reçus reconnus par le service sont disponibles ici.

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

Effectuer l’apprentissage d’un modèle

Effectuez l’apprentissage d’un modèle personnalisé sur votre propre type de formulaire. Le modèle résultant peut être utilisé pour reconnaître des valeurs à partir des types de formulaires sur 2000. Fournissez une URL SAP de conteneur à votre conteneur d’objets blob stockage Azure dans lequel vous stockez les documents d’apprentissage. Si les fichiers d’apprentissage se trouvent dans un sous-dossier du conteneur, utilisez l’argument de mot clé préfixe pour spécifier sous quel dossier effectuer l’apprentissage.

Pour plus d’informations sur la configuration d’un conteneur et de la structure de fichiers requise, consultez la documentation du service.

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

Gérer vos modèles

Gérez les modèles personnalisés attachés à votre compte.

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

Dépannage

Général

Form Recognizer bibliothèque cliente déclenche des exceptions définies dans Azure Core.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée de niveau DEBUG, comprenant le corps de la demande et/ou de la réponse et les en-têtes non rédigés, peut être activée sur un client à l’aide de l’argument de mot clé 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

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

Configuration facultative

Les arguments de mot clé facultatifs peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Étapes suivantes

La section suivante fournit plusieurs extraits de code illustrant les modèles courants utilisés dans l’API Python Form Recognizer.

Autres exemples de code

Ces exemples de code illustrent les opérations de scénario courantes avec la bibliothèque cliente Azure Form Recognizer.

API asynchrones

Cette bibliothèque inclut également une API asynchrone complète prise en charge sur Python 3.5+. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Les clients asynchrones se trouvent sous l’espace de azure.ai.formrecognizer.aio noms.

Documentation complémentaire

Pour obtenir une documentation plus complète sur les Form Recognizer Azure Cognitive Services, consultez la documentation Form Recognizer sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.