Bibliothèque de client Azure AI Document Intelligence pour Python - version 1.0.0b1

Azure AI Document Intelligence (anciennement Form Recognizer) est un service cloud qui utilise le Machine Learning pour analyser du texte et des données structurées à partir de vos documents. Il comprend les fonctionnalités de main suivantes :

• Disposition : extrayez le contenu et la structure (par exemple, mots, marques de sélection, tableaux) à partir de documents.
• Document : analysez les paires clé-valeur en plus de la mise en page générale des documents.
• Lecture - Lire les informations de page à partir de documents.
• Prédéfini : extrayez les valeurs de champs courantes de certains types de documents (par exemple, reçus, factures, cartes de visite, documents d’identité, documents fiscaux U.S. W-2, entre autres) à l’aide de modèles prédéfinis.
• Personnalisé : créez des modèles personnalisés à partir de vos propres données pour extraire des valeurs de champ personnalisées en plus de la mise en page générale des documents.
• Classifieurs : créez des modèles de classification personnalisés qui combinent des fonctionnalités de disposition et de langage pour détecter et identifier avec précision les documents que vous traitez dans votre application.
• Fonctionnalités complémentaires : extraire des codes-barres/codes QR, des formules, une police/style, etc. ou activer le mode haute résolution pour les documents volumineux avec des paramètres facultatifs.

Prise en main

Installation du package

python -m pip install azure-ai-documentintelligence

Configuration requise

• Python 3.7 ou version ultérieure est requis pour utiliser ce package.
• Vous avez besoin d’un abonnement Azure pour utiliser ce package.
• Un instance Azure AI Document Intelligence existant.

Créer une ressource Cognitive Services ou Document Intelligence

Document Intelligence prend en charge 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 un accès à l’Intelligence documentaire uniquement, créez une ressource d’Intelligence documentaire. Notez que vous aurez besoin d’une ressource à service unique si vous envisagez d’utiliser l’authentification Azure Active Directory.

Vous pouvez créer l’une ou l’autre ressource à l’aide de :

• Option 1 : Portail Azure.
• Option 2 : Azure CLI.

Voici un exemple de création d’une ressource Document Intelligence à l’aide de l’interface CLI :

# Create a new resource group to hold the Document Intelligence resource
# if using an existing resource group, skip this step
az group create --name <your-resource-name> --location <location>

# Create the Document Intelligence resource
az cognitiveservices account create \
    --name <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind FormRecognizer \
    --sku <sku> \
    --location <location> \
    --yes

Pour plus d’informations sur la création de la ressource ou sur la façon d’obtenir l’emplacement et les informations de référence SKU , consultez ici.

Authentifier le client

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

Obtenir le point de terminaison

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

# Get the endpoint for the Document Intelligence resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

Un point de terminaison régional ou un sous-domaine personnalisé peut être utilisé pour l’authentification. Ils sont mis en forme comme suit :

Regional endpoint: https://<region>.api.cognitive.microsoft.com/
Custom subdomain: https://<resource-name>.cognitiveservices.azure.com/

Un point de terminaison régional est le même pour chaque ressource d’une région. Vous pouvez consulter la liste complète des points de terminaison régionaux pris en charge ici. Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD.

En revanche, un sous-domaine personnalisé est un nom propre à la ressource Document Intelligence. Elles ne peuvent être utilisées que par des ressources à service unique.

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 un instance d’AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_analysis_client = DocumentIntelligenceClient(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 à Document Intelligence 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.

"""DefaultAzureCredential will use the values from these environment
variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
"""
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
credential = DefaultAzureCredential()

document_analysis_client = DocumentIntelligenceClient(endpoint, credential)

Concepts clés

DocumentIntelligenceClient

DocumentIntelligenceClient fournit des opérations pour l’analyse des documents d’entrée à l’aide de modèles prédéfinis et personnalisés via l’API begin_analyze_document . Utilisez le model_id paramètre pour sélectionner le type de modèle à des fins d’analyse. Consultez la liste complète des modèles pris en charge ici. Fournit DocumentIntelligenceClient également des opérations pour classifier des documents via l’API begin_classify_document . Les modèles de classification personnalisés peuvent classifier chaque page d’un fichier d’entrée pour identifier le ou les documents à l’intérieur et peuvent également identifier plusieurs documents ou plusieurs instances d’un seul document dans un fichier d’entrée.

Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’un DocumentIntelligenceClient ici. Vous trouverez plus d’informations sur l’analyse des documents, notamment les fonctionnalités prises en charge, les paramètres régionaux et les types de documents dans la documentation du service.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient propose des opérations pour :

• Création de modèles personnalisés pour analyser des champs spécifiques que vous spécifiez en étiquetant vos documents personnalisés. Un DocumentModelDetails est retourné indiquant le ou les types de document que le modèle peut analyser, ainsi que la confiance estimée pour chaque champ. Consultez la documentation du service pour obtenir une explication plus détaillée.
• Création d’un modèle composé à partir d’une collection de modèles existants.
• Gérer les modèles créés dans votre compte.
• Répertorier les opérations ou obtenir une opération de modèle spécifique créée au cours des dernières 24 heures.
• Copier un modèle personnalisé d’une ressource Intelligence documentaire vers une autre.
• Créez et gérez un modèle de classification personnalisé pour classifier les documents que vous traitez dans votre application.

Notez que les modèles peuvent également être générés à l’aide d’une interface utilisateur graphique telle que Document Intelligence Studio.

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

Opérations de longue durée

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 analysent des documents, créent des modèles ou copient/composent 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 Document Intelligence les plus courantes, notamment :

• Extraire la disposition
• Utilisation du modèle de document général
• Utilisation de modèles prédéfinis
• Créer un modèle personnalisé
• Analyser des documents à l’aide d’un modèle personnalisé
• Gérer vos modèles
• Fonctionnalités de module complémentaire

Extraire la disposition

Extrayez du texte, des marques de sélection, des styles de texte et des structures de tableau, ainsi que leurs coordonnées de région englobante, à partir de documents.

from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

document_intelligence_client = DocumentIntelligenceClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
    poller = document_intelligence_client.begin_analyze_document(
        "prebuilt-layout", analyze_request=f, content_type="application/octet-stream"
    )
result = poller.result()

for idx, style in enumerate(result.styles):
    print(
        "Document contains {} content".format(
            "handwritten" if style.is_handwritten else "no handwritten"
        )
    )

for page in result.pages:
    print("----Analyzing layout from page #{}----".format(page.page_number))
    print(
        "Page has width: {} and height: {}, measured with unit: {}".format(
            page.width, page.height, page.unit
        )
    )

    for line_idx, line in enumerate(page.lines):
        words = line.get_words()
        print(
            "...Line # {} has word count {} and text '{}' within bounding polygon '{}'".format(
                line_idx,
                len(words),
                line.content,
                line.polygon,
            )
        )

        for word in words:
            print(
                "......Word '{}' has a confidence of {}".format(
                    word.content, word.confidence
                )
            )

    for selection_mark in page.selection_marks:
        print(
            "...Selection mark is '{}' within bounding polygon '{}' and has a confidence of {}".format(
                selection_mark.state,
                selection_mark.polygon,
                selection_mark.confidence,
            )
        )

for table_idx, table in enumerate(result.tables):
    print(
        "Table # {} has {} rows and {} columns".format(
            table_idx, table.row_count, table.column_count
        )
    )
    for region in table.bounding_regions:
        print(
            "Table # {} location on page: {} is {}".format(
                table_idx,
                region.page_number,
                region.polygon,
            )
        )
    for cell in table.cells:
        print(
            "...Cell[{}][{}] has content '{}'".format(
                cell.row_index,
                cell.column_index,
                cell.content,
            )
        )
        for region in cell.bounding_regions:
            print(
                "...content on page {} is within bounding polygon '{}'".format(
                    region.page_number,
                    region.polygon,
                )
            )

print("----------------------------------------")

Utilisation de modèles prédéfinis

Extrayez des champs de certains types de documents, tels que des reçus, des factures, des cartes de visite, des documents d’identité et des documents fiscaux U.S. W-2 à l’aide de modèles prédéfinis fournis par le service Document Intelligence.

Par exemple, pour analyser les champs d’un reçu de vente, utilisez le modèle de reçu prédéfini fourni en passant model_id="prebuilt-receipt" dans la begin_analyze_document méthode :

from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

document_analysis_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
with open(path_to_sample_documents, "rb") as f:
    poller = document_analysis_client.begin_analyze_document(
        "prebuilt-receipt", analyze_request=f, locale="en-US", content_type="application/octet-stream"
    )
receipts = poller.result()

for idx, receipt in enumerate(receipts.documents):
    print(f"--------Analysis of receipt #{idx + 1}--------")
    print(f"Receipt type: {receipt.doc_type if receipt.doc_type else 'N/A'}")
    merchant_name = receipt.fields.get("MerchantName")
    if merchant_name:
        print(f"Merchant Name: {merchant_name.get('valueString')} has confidence: " f"{merchant_name.confidence}")
    transaction_date = receipt.fields.get("TransactionDate")
    if transaction_date:
        print(
            f"Transaction Date: {transaction_date.get('valueDate')} has confidence: "
            f"{transaction_date.confidence}"
        )
    if receipt.fields.get("Items"):
        print("Receipt items:")
        for idx, item in enumerate(receipt.fields.get("Items").get("valueArray")):
            print(f"...Item #{idx + 1}")
            item_description = item.get("valueObject").get("Description")
            if item_description:
                print(
                    f"......Item Description: {item_description.get('valueString')} has confidence: "
                    f"{item_description.confidence}"
                )
            item_quantity = item.get("valueObject").get("Quantity")
            if item_quantity:
                print(
                    f"......Item Quantity: {item_quantity.get('valueString')} has confidence: "
                    f"{item_quantity.confidence}"
                )
            item_total_price = item.get("valueObject").get("TotalPrice")
            if item_total_price:
                print(
                    f"......Total Item Price: {format_price(item_total_price.get('valueCurrency'))} has confidence: "
                    f"{item_total_price.confidence}"
                )
    subtotal = receipt.fields.get("Subtotal")
    if subtotal:
        print(f"Subtotal: {format_price(subtotal.get('valueCurrency'))} has confidence: {subtotal.confidence}")
    tax = receipt.fields.get("TotalTax")
    if tax:
        print(f"Total tax: {format_price(tax.get('valueCurrency'))} has confidence: {tax.confidence}")
    tip = receipt.fields.get("Tip")
    if tip:
        print(f"Tip: {format_price(tip.get('valueCurrency'))} has confidence: {tip.confidence}")
    total = receipt.fields.get("Total")
    if total:
        print(f"Total: {format_price(total.get('valueCurrency'))} has confidence: {total.confidence}")
    print("--------------------------------------")

Vous n’êtes pas limité aux reçus ! Vous avez le choix entre quelques modèles prédéfinis, chacun ayant son propre ensemble de champs pris en charge. Consultez les autres modèles prédéfinis pris en charge ici.

Créer un modèle personnalisé

Créez un modèle personnalisé sur votre propre type de document. Le modèle résultant peut être utilisé pour analyser des valeurs à partir des types de documents sur lequel il a été entraîné. Fournissez une URL SAP de conteneur à votre conteneur d’objets blob stockage Azure dans lequel vous stockez les documents d’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 (
    DocumentIntelligenceAdministrationClient,
    ModelBuildMode,
)
from azure.core.credentials import AzureKeyCredential

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
container_sas_url = os.environ["CONTAINER_SAS_URL"]

document_model_admin_client = DocumentIntelligenceAdministrationClient(
    endpoint, AzureKeyCredential(key)
)
poller = document_model_admin_client.begin_build_document_model(
    ModelBuildMode.TEMPLATE,
    blob_container_url=container_sas_url,
    description="my model description",
)
model = poller.result()

print(f"Model ID: {model.model_id}")
print(f"Description: {model.description}")
print(f"Model created on: {model.created_on}")
print(f"Model expires on: {model.expires_on}")
print("Doc types the model can recognize:")
for name, doc_type in model.doc_types.items():
    print(
        f"Doc Type: '{name}' built with '{doc_type.build_mode}' mode which has the following fields:"
    )
    for field_name, field in doc_type.field_schema.items():
        print(
            f"Field: '{field_name}' has type '{field['type']}' and confidence score "
            f"{doc_type.field_confidence[field_name]}"
        )

Analyser des documents à l’aide d’un modèle personnalisé

Analysez les champs de document, les tableaux, les marques de sélection, etc. Ces modèles étant entraînés avec vos propres données, ils sont adaptés à vos documents. Pour de meilleurs résultats, vous devez uniquement analyser les documents du même type de document que celui avec lequel le modèle personnalisé a été créé.

from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]
model_id = os.getenv("CUSTOM_BUILT_MODEL_ID", custom_model_id)

document_analysis_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))

# Make sure your document's type is included in the list of document types the custom model can analyze
with open(path_to_sample_documents, "rb") as f:
    poller = document_analysis_client.begin_analyze_document(
        model_id=model_id, analyze_request=f, content_type="application/octet-stream"
    )
result = poller.result()

for idx, document in enumerate(result.documents):
    print(f"--------Analyzing document #{idx + 1}--------")
    print(f"Document has type {document.doc_type}")
    print(f"Document has document type confidence {document.confidence}")
    print(f"Document was analyzed with model with ID {result.model_id}")
    for name, field in document.fields.items():
        field_value = field.get("valueString") if field.get("valueString") else field.content
        print(
            f"......found field of type '{field.type}' with value '{field_value}' and with confidence {field.confidence}"
        )

# iterate over tables, lines, and selection marks on each page
for page in result.pages:
    print(f"\nLines found on page {page.page_number}")
    for line in page.lines:
        print(f"...Line '{line.content}'")
    for word in page.words:
        print(f"...Word '{word.content}' has a confidence of {word.confidence}")
    if page.selection_marks:
        print(f"\nSelection marks found on page {page.page_number}")
        for selection_mark in page.selection_marks:
            print(
                f"...Selection mark is '{selection_mark.state}' and has a confidence of {selection_mark.confidence}"
            )

for i, table in enumerate(result.tables):
    print(f"\nTable {i + 1} can be found on page:")
    for region in table.bounding_regions:
        print(f"...{region.page_number}")
    for cell in table.cells:
        print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")
print("-----------------------------------")

En outre, une URL de document peut également être utilisée pour analyser des documents à l’aide de la begin_analyze_document méthode .

from azure.core.credentials import AzureKeyCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.ai.documentintelligence.models import AnalyzeDocumentRequest

endpoint = os.environ["DOCUMENTINTELLIGENCE_ENDPOINT"]
key = os.environ["DOCUMENTINTELLIGENCE_API_KEY"]

document_analysis_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))
url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/documentintelligence/azure-ai-documentintelligence/tests/sample_forms/receipt/contoso-receipt.png"
poller = document_analysis_client.begin_analyze_document("prebuilt-receipt", AnalyzeDocumentRequest(url_source=url))
receipts = poller.result()

Gérer vos modèles

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

from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

document_model_admin_client = DocumentIntelligenceAdministrationClient(endpoint, credential)

account_details = document_model_admin_client.get_resource_info()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_details.custom_document_models.count, account_details.custom_document_models.limit
))

# Here we get a paged list of all of our models
models = document_model_admin_client.list_models()
print("We have models with the following ids: {}".format(
    ", ".join([m.model_id for m in models])
))

# Replace with the custom model ID from the "Build a model" sample
model_id = "<model_id from the Build a Model sample>"

custom_model = document_model_admin_client.get_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Description: {}".format(custom_model.description))
print("Model created on: {}\n".format(custom_model.created_on))

# Finally, we will delete this model by ID
document_model_admin_client.delete_model(model_id=custom_model.model_id)

try:
    document_model_admin_client.get_model(model_id=custom_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with id {}".format(custom_model.model_id))

Fonctionnalités de module complémentaire

Document Intelligence prend en charge des fonctionnalités d’analyse plus sophistiquées. Ces fonctionnalités facultatives peuvent être activées et désactivées en fonction du scénario d’extraction de document.

Les fonctionnalités complémentaires suivantes sont disponibles pour les versions 2023-07-31 (GA) et ultérieures :

• code-barres/CODE QR
• Formule
• police/style
• mode haute résolution
• language

Notez que certaines fonctionnalités de module complémentaire entraînent des frais supplémentaires. Consultez la tarification : https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Dépannage

Général

La bibliothèque cliente Document Intelligence déclenche des exceptions définies dans Azure Core. Les codes d’erreur et les messages déclenchés par le service Document Intelligence se trouvent dans la documentation du service.

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 INFO niveau.

La journalisation détaillée DEBUG au niveau, y compris les corps de requête/réponse et les en-têtes non expurgées, peut être activée sur le client ou par opération avec l’argument logging_enable mot clé.

Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.

Configuration facultative

Les arguments mot clé facultatifs peuvent être passés 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

Autres exemples de code

Consultez l’exemple README pour obtenir plusieurs extraits de code illustrant les modèles courants utilisés dans l’API Python Document Intelligence.

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure AI Document Intelligence, consultez la documentation Document Intelligence 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, visitez https://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 la FAQ sur le code de conduite ou contactez opencode@microsoft.com pour toute question ou tout commentaire supplémentaire.