Condividi tramite

Libreria client di Azure Riconoscimento modulo per Python - versione 3.0.0

  • Articolo

Servizi cognitivi di Azure Riconoscimento modulo è un servizio cloud che usa Machine Learning per riconoscere i dati di testo e tabella dai documenti del modulo. Include le funzionalità principali seguenti:

  • Modelli personalizzati: riconoscere i valori dei campi e i dati della tabella dai moduli. Questi modelli vengono sottoposti a training con i dati dell'utente, quindi sono personalizzati per i suoi moduli.
  • API contenuto: riconoscere le strutture di testo e tabella, insieme alle coordinate del rettangolo di selezione, dai documenti. Corrisponde all'API Layout del servizio REST.
  • Modello di ricevuta predefinito: riconoscere i dati dalle ricevute di vendita USA usando un modello predefinito.

Codice | sorgente Pacchetto (PyPI) | Documentazione di| riferimento sulle API Documentazione | del prodotto Campioni

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di Azure Riconoscimento modulo per Python - versione 3.0.0 con pip:

pip install azure-ai-formrecognizer

Nota: questa versione della libreria client supporta la versione v2.0 del servizio Riconoscimento modulo

Creare una risorsa di riconoscimento modulo

Riconoscimento modulo supporta sia l'accesso a più servizi che a servizio singolo. Creare una risorsa Servizi cognitivi se si prevede di accedere a più servizi cognitivi con un singolo endpoint/chiave. Per accedere solo a Riconoscimento modulo, creare una risorsa Riconoscimento modulo.

È possibile creare la risorsa usando

Opzione 1:Portale di Azure

Opzione 2:Interfaccia della riga dicomando di Azure. Di seguito è riportato un esempio di come creare una risorsa Riconoscimento modulo usando l'interfaccia della riga di comando:

# 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

Autenticare il client

Per interagire con il servizio Riconoscimento modulo, è necessario creare un'istanza di un client. Un endpoint e le credenziali sono necessari per creare un'istanza dell'oggetto client.

Ricerca dell'endpoint

È possibile trovare l'endpoint per la risorsa Riconoscimento modulo usando il portale di Azure o l'interfaccia della riga di comando di Azure:

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

Ottenere la chiave API

La chiave API è disponibile nel portale di Azure o eseguendo il comando dell'interfaccia della riga di comando di Azure seguente:

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

Creare il client con AzureKeyCredential

Per usare una chiave API come credential parametro, passare la chiave come stringa in un'istanza di 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)

Creare il client con una credenziale di Azure Active Directory

AzureKeyCredential l'autenticazione viene usata negli esempi di questa guida introduttiva, ma è anche possibile eseguire l'autenticazione con Azure Active Directory usando la libreria azure-identity . Si noti che gli endpoint a livello di area non supportano l'autenticazione AAD. Creare un nome di sottodominio personalizzato per la risorsa per usare questo tipo di autenticazione.

Per usare il tipo DefaultAzureCredential illustrato di seguito o altri tipi di credenziali forniti con Azure SDK, installare il azure-identity pacchetto:

pip install azure-identity

Sarà anche necessario registrare una nuova applicazione AAD e concedere l'accesso a Riconoscimento modulo assegnando il ruolo all'entità "Cognitive Services User" servizio.

Al termine, impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: 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
)

Concetti chiave

FormRecognizerClient

FormRecognizerClient fornisce le operazioni per:

  • Riconoscere campi modulo e contenuti usando modelli personalizzati sottoposti a training per riconoscere i moduli personalizzati. Questi valori vengono restituiti in una raccolta di oggetti RecognizedForm.
  • Riconoscimento di campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione pre-sottoposto a training. Questi campi e metadati vengono restituiti in una raccolta di RecognizedForm oggetti.
  • Riconoscere i contenuti dei moduli, incluse tabelle, righe e parole, senza la necessità di eseguire il training di un modello. I contenuti dei moduli vengono restituiti in una raccolta di oggetti FormPage.

I frammenti di codice di esempio vengono forniti per illustrare l'uso di moduli Di riconoscimento FormRecognizerClient qui.

FormTrainingClient

FormTrainingClient fornisce le operazioni per:

  • Eseguire il training di modelli personalizzati senza etichette per riconoscere tutti i campi e i valori trovati nei moduli personalizzati. Viene restituito un CustomFormModel che indica i tipi di modulo che il modello riconoscerà e i campi che estrarrà per ogni tipo di modulo. Per una spiegazione più dettagliata, vedere la documentazione del servizio.
  • Eseguire il training di modelli personalizzati con etichette per riconoscere campi e valori specifici specificati etichettando i moduli personalizzati. Viene restituito un CustomFormModel che indica i campi che verranno estratti dal modello e l'accuratezza stimata per ogni campo. Per una spiegazione più dettagliata, vedere la documentazione del servizio.
  • Gestire i modelli creati nell'account.
  • Copiare un modello personalizzato da una risorsa Riconoscimento modulo a un'altra.

Tenere presente che è possibile eseguire il training dei modelli anche con un'interfaccia utente grafica, ad esempio con lo strumento di etichettatura di Riconoscimento modulo.

I frammenti di codice di esempio vengono forniti per illustrare l'uso di un modulo FormTrainingClient here.

operazioni Long-Running

Le operazioni a esecuzione prolungata sono operazioni costituite da una richiesta iniziale inviata al servizio per avviare un'operazione, seguita dal polling del servizio a intervalli per determinare se l'operazione è stata completata o non riuscita e, se ha avuto esito positivo, per ottenere il risultato.

I metodi che eseguono il training dei modelli, riconoscono i valori dai moduli o i modelli di copia vengono modellati come operazioni a esecuzione prolungata. Il client espone un begin_<method-name> metodo che restituisce un LROPoller oggetto o AsyncLROPoller. I chiamanti devono attendere il completamento dell'operazione chiamando result() l'oggetto poller restituito dal begin_<method-name> metodo . I frammenti di codice di esempio vengono forniti per illustrare l'uso di esempi di operazioni a esecuzione prolungata di seguito.

Esempio

La sezione seguente fornisce diversi frammenti di codice che coprono alcune delle attività di Riconoscimento modulo più comuni, tra cui:

Riconoscere i moduli usando un modello personalizzato

Riconoscere coppie nome/valore e dati di tabella dai moduli. Questi modelli vengono sottoposti a training con i dati dell'utente, quindi sono personalizzati per i suoi moduli. Per ottenere risultati ottimali, è consigliabile riconoscere solo le forme dello stesso tipo di modulo su cui è stato eseguito il training del modello personalizzato.

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

In alternativa, è anche possibile usare un URL del modulo per riconoscere moduli personalizzati usando il begin_recognize_custom_forms_from_url metodo . I _from_url metodi esistono per tutti i metodi di riconoscimento.

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

Riconoscere il contenuto

Riconoscere le strutture di testo e tabella, insieme alle coordinate del rettangolo di selezione, dai documenti.

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

Riconoscere le ricevute

Riconoscere i dati dalle ricevute di vendita USA usando un modello predefinito. I campi ricevuti riconosciuti dal servizio sono disponibili qui.

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

Eseguire il training di un modello

Eseguire il training di un modello personalizzato nel proprio tipo di modulo. Il modello risultante può essere usato per riconoscere i valori dai tipi di moduli in cui è stato eseguito il training. Specificare un URL della firma di accesso condiviso contenitore al contenitore BLOB di Archiviazione di Azure in cui vengono archiviati i documenti di training. Se i file di training si trovano all'interno di una sottocartella nel contenitore, usare l'argomento parola chiave prefisso per specificare in quale cartella eseguire il training.

Altre informazioni sulla configurazione di un contenitore e sulla struttura di file necessaria sono disponibili nella documentazione del servizio.

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

Gestire i modelli

Gestire i modelli personalizzati collegati all'account.

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

Risoluzione dei problemi

Generale

Riconoscimento modulo libreria client genererà eccezioni definite in Azure Core.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di debug, inclusi i corpi di richiesta-risposta e le intestazioni non modificate, può essere abilitata su un client con l'argomento parola chiave 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

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

Configurazione facoltativa

Gli argomenti di parole chiave facoltativi possono essere passati al client e al livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.

Passaggi successivi

La sezione seguente fornisce diversi frammenti di codice che illustrano i modelli comuni usati nell'API Python Riconoscimento modulo.

Altro codice di esempio

Questi esempi di codice illustrano operazioni di scenario comuni con la libreria client di Azure Riconoscimento modulo.

API asincrone

Questa libreria include anche un'API asincrona completa supportata in Python 3.5+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. I client asincroni si trovano nello spazio dei azure.ai.formrecognizer.aio nomi .

Documentazione aggiuntiva

Per una documentazione più completa su Servizi cognitivi di Azure Riconoscimento modulo, vedere la documentazione Riconoscimento modulo su docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.