Libreria client di Azure AI Document Intelligence per Python - versione 1.0.0b1

L'intelligenza dei documenti di Intelligenza artificiale di Azure (nota in precedenza come Riconoscimento modulo) è un servizio cloud che usa Machine Learning per analizzare il testo e i dati strutturati dai documenti. Include le funzionalità principali seguenti:

• Layout: estrarre contenuto e struttura (ad esempio parole, segni di selezione, tabelle) dai documenti.
• Documento: analizzare le coppie chiave-valore oltre al layout generale dei documenti.
• Lettura: consente di leggere le informazioni sulla pagina dai documenti.
• Predefinita: estrai valori di campo comuni dai tipi di documento selezionati (ad esempio ricevute, fatture, biglietti da visita, documenti ID, documenti fiscali U.S. W-2, tra gli altri) usando modelli predefiniti.
• Personalizzato: consente di creare modelli personalizzati dai propri dati per estrarre valori di campo personalizzati oltre al layout generale dai documenti.
• Classificatori: consente di creare modelli di classificazione personalizzati che combinano funzionalità di layout e linguaggio per rilevare e identificare in modo accurato i documenti elaborati all'interno dell'applicazione.
• Funzionalità del componente aggiuntivo: estrarre codici a barre/codici a matrice, formule, font/stile e così via oppure abilitare la modalità ad alta risoluzione per documenti di grandi dimensioni con parametri facoltativi.

Guida introduttiva

Installazione del pacchetto

python -m pip install azure-ai-documentintelligence

Prerequisiti

• Python 3.7 o versione successiva è necessario per usare questo pacchetto.
• Per usare questo pacchetto è necessaria una sottoscrizione di Azure .
• Istanza esistente di Document Intelligence per intelligenza artificiale di Azure.

Creare una risorsa di Servizi cognitivi o Document Intelligence

Document Intelligence supporta sia l'accesso multiservizio che l'accesso a un servizio singolo. Creare una risorsa Servizi cognitivi se si prevede di accedere a più servizi cognitivi con un singolo endpoint/chiave. Solo per l'accesso a Document Intelligence, creare una risorsa di Document Intelligence. Si noti che sarà necessaria una risorsa a servizio singolo se si intende usare l'autenticazione di Azure Active Directory.

È possibile creare una delle due risorse usando:

• Opzione 1: Portale di Azure.
• Opzione 2: Interfaccia della riga di comando di Azure.

Di seguito è riportato un esempio di come creare una risorsa di Document Intelligence usando l'interfaccia della riga di comando:

# 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

Per altre informazioni sulla creazione della risorsa o su come ottenere la posizione e le informazioni sullo SKU, vedere qui.

Autenticare il client

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

Ottenere l'endpoint

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

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

È possibile usare un endpoint a livello di area o un sottodominio personalizzato per l'autenticazione. Sono formattati come segue:

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

Un endpoint a livello di area è lo stesso per ogni risorsa in un'area. Un elenco completo degli endpoint regionali supportati è disponibile qui. Si noti che gli endpoint a livello di area non supportano l'autenticazione AAD.

Un sottodominio personalizzato, d'altra parte, è un nome univoco per la risorsa di Intelligence documenti. Possono essere usati solo dalle risorse a servizio singolo.

Ottenere la chiave API

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

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.documentintelligence import DocumentIntelligenceClient

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

Creare il client con credenziali 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 Document Intelligence 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.

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

Concetti chiave

DocumentIntelligenceClient

DocumentIntelligenceClient fornisce operazioni per analizzare i documenti di input usando modelli predefiniti e personalizzati tramite l'API begin_analyze_document . Usare il model_id parametro per selezionare il tipo di modello per l'analisi. Vedere un elenco completo dei modelli supportati qui. fornisce DocumentIntelligenceClient anche operazioni per classificare i documenti tramite l'API begin_classify_document . I modelli di classificazione personalizzati possono classificare ogni pagina in un file di input per identificare i documenti all'interno e identificare anche più documenti o più istanze di un singolo documento all'interno di un file di input.

I frammenti di codice di esempio vengono forniti per illustrare l'uso di esempi documentIntelligenceClient qui. Altre informazioni sull'analisi dei documenti, incluse le funzionalità supportate, le impostazioni locali e i tipi di documento, sono disponibili nella documentazione del servizio.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient fornisce le operazioni per:

• Creazione di modelli personalizzati per analizzare campi specifici specificati etichettando i documenti personalizzati. Viene restituito un DocumentModelDetails valore che indica i tipi di documento che il modello può analizzare, nonché l'attendibilità stimata per ogni campo. Per una spiegazione più dettagliata, vedere la documentazione del servizio.
• Creazione di un modello composto da una raccolta di modelli esistenti.
• Gestire i modelli creati nell'account.
• Elencare le operazioni o ottenere un'operazione di modello specifica creata nelle ultime 24 ore.
• Copia di un modello personalizzato da una risorsa di Document Intelligence a un'altra.
• Compilare e gestire un modello di classificazione personalizzato per classificare i documenti elaborati all'interno dell'applicazione.

Si noti che i modelli possono essere compilati anche usando un'interfaccia utente grafica, ad esempio Document Intelligence Studio.

I frammenti di codice di esempio vengono forniti per illustrare l'uso di un esempio documentIntelligenceAdministrationClient .

Operazioni a esecuzione prolungata

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 analizzano documenti, compilano modelli o modelli di copia/composizione 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() sull'oggetto poller restituito dal begin_<method-name> metodo . Di seguito vengono forniti frammenti di codice di esempio per illustrare l'uso di operazioni a esecuzione prolungata

Esempio

La sezione seguente fornisce diversi frammenti di codice che illustrano alcune delle attività più comuni di Document Intelligence, tra cui:

• Estrai layout
• Utilizzo del modello di documento generale
• Uso di modelli predefiniti
• Creare un modello personalizzato
• Analizzare i documenti usando un modello personalizzato
• Gestire i modelli
• Funzionalità dei componenti aggiuntivi

Estrai layout

Estrarre testo, segni di selezione, stili di testo e strutture di tabella, insieme alle coordinate dell'area di delimitazione, dai documenti.

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

Uso di modelli predefiniti

Estrarre campi dai tipi di documento selezionati, ad esempio ricevute, fatture, biglietti da visita, documenti di identità e documenti fiscali W-2 statunitensi usando modelli predefiniti forniti dal servizio Document Intelligence.

Ad esempio, per analizzare i campi da una ricevuta di vendita, usare il modello di ricevuta predefinito fornito passando model_id="prebuilt-receipt" al begin_analyze_document metodo :

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

Non ci si limita alle ricevute! Esistono alcuni modelli predefiniti tra cui scegliere, ognuno dei quali ha un proprio set di campi supportati. Vedere altri modelli predefiniti supportati qui.

Creare un modello personalizzato

Creare un modello personalizzato in base al tipo di documento. Il modello risultante può essere usato per analizzare i valori dai tipi di documenti su cui è stato eseguito il training. Specificare un URL di firma di accesso condiviso del contenitore al contenitore BLOB di Archiviazione di Azure in cui archiviare i documenti di 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 (
    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]}"
        )

Analizzare i documenti usando un modello personalizzato

Analizzare campi, tabelle, segni di selezione e altro ancora. Questi modelli vengono sottoposti a training con i propri dati, quindi sono personalizzati per i documenti. Per ottenere risultati ottimali, è consigliabile analizzare solo i documenti dello stesso tipo di documento con cui è stato creato il modello personalizzato.

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

Inoltre, è possibile usare un URL di documento per analizzare i documenti usando il begin_analyze_document metodo .

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

Gestire i modelli

Gestire i modelli personalizzati associati all'account.

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

Funzionalità del componente aggiuntivo

Document Intelligence supporta funzionalità di analisi più sofisticate. Queste funzionalità facoltative possono essere abilitate e disabilitate a seconda dello scenario dell'estrazione di documenti.

Le funzionalità aggiuntive seguenti sono disponibili per la versione 2023-07-31 (GA) e versioni successive:

• codice a barre/a matrice
• Formula
• font/style
• modalità ad alta risoluzione
• language

Si noti che alcune funzionalità del componente aggiuntivo comportano costi aggiuntivi. Vedere i prezzi: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Risoluzione dei problemi

Generale

La libreria client di Document Intelligence genererà eccezioni definite in Azure Core. I codici di errore e i messaggi generati dal servizio Document Intelligence sono disponibili nella documentazione del servizio.

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

La registrazione a livello dettagliato DEBUG , inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate , può essere abilitata nel client o per operazione con l'argomento logging_enable parola chiave.

Vedere la documentazione completa sulla registrazione dell'SDK con esempi qui.

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

Altro codice di esempio

Vedere il file README di esempio per diversi frammenti di codice che illustrano i modelli comuni usati nell'API Python di Document Intelligence.

Documentazione aggiuntiva

Per una documentazione più completa su Document Intelligence per intelligenza artificiale di Azure, vedere la documentazione di Document Intelligence in 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, vedere https://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) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.