Sdílet prostřednictvím

Klientská knihovna Azure AI Document Intelligence pro Python – verze 1.0.0b1

  • Článek

Azure AI Document Intelligence (dříve označovaná jako Rozpoznávání formulářů) je cloudová služba, která pomocí strojového učení analyzuje text a strukturovaná data z vašich dokumentů. Zahrnuje následující hlavní funkce:

  • Rozložení – extrahuje obsah a strukturu (například slova, značky výběru, tabulky) z dokumentů.
  • Dokument – Kromě obecného rozložení dokumentů můžete analyzovat páry klíč-hodnota.
  • Čtení – čtení informací o stránce z dokumentů.
  • Předem připravené – extrahujte hodnoty společných polí z vybraných typů dokumentů (např. účtenky, faktury, vizitky, doklady ID, daňové doklady USA W-2 a další) pomocí předem připravených modelů.
  • Vlastní – vytvářejte vlastní modely z vlastních dat a extrahujte z dokumentů kromě obecného rozložení i přizpůsobené hodnoty polí.
  • Klasifikátory – vytvářejte vlastní klasifikační modely, které kombinují funkce rozložení a jazyka, aby bylo možné přesně rozpoznat a identifikovat dokumenty, které zpracováváte v rámci aplikace.
  • Možnosti doplňků – Extrahujte čárové kódy/ kódy QR, vzorce, písmo, styl atd. nebo povolte režim vysokého rozlišení pro velké dokumenty s volitelnými parametry.

Začínáme

Instalace balíčku

python -m pip install azure-ai-documentintelligence

Požadavky

  • K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější.
  • K použití tohoto balíčku potřebujete předplatné Azure .
  • Existující instance funkce Document Intelligence v Azure AI.

Vytvoření prostředku služeb Cognitive Services nebo Document Intelligence

Funkce Document Intelligence podporuje přístup s více službami i s jednou službou. Pokud plánujete přístup k více kognitivním službám v rámci jednoho koncového bodu nebo klíče, vytvořte prostředek Cognitive Services. Pouze pro přístup k document intelligence vytvořte prostředek Document Intelligence. Mějte na paměti, že pokud máte v úmyslu používat ověřování Azure Active Directory, budete potřebovat prostředek s jednou službou.

Můžete vytvořit některý z těchto prostředků pomocí:

Níže je příklad vytvoření prostředku Document Intelligence pomocí rozhraní příkazového řádku:

# 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

Další informace o vytvoření prostředku nebo o tom, jak získat informace o umístění a skladové pořiďte , najdete tady.

Ověření klienta

Abyste mohli pracovat se službou Document Intelligence, budete muset vytvořit instanci klienta. Koncový bod a přihlašovací údaje jsou nezbytné k vytvoření instance objektu klienta.

Získání koncového bodu

Koncový bod pro prostředek Document Intelligence můžete najít pomocí webu Azure Portal nebo 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"

K ověřování je možné použít místní koncový bod nebo vlastní subdoménu. Formátují se takto:

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

Místní koncový bod je stejný pro každý prostředek v oblasti. Úplný seznam podporovaných regionálních koncových bodů najdete tady. Upozorňujeme, že místní koncové body nepodporují ověřování AAD.

Vlastní subdoména je naopak název, který je jedinečný pro prostředek Document Intelligence. Můžou je používat jenom prostředky s jednou službou.

Získání klíče rozhraní API

Klíč rozhraní API najdete na webu Azure Portal nebo spuštěním následujícího příkazu Azure CLI:

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

Vytvoření klienta pomocí AzureKeyCredential

Pokud chcete jako credential parametr použít klíč rozhraní API, předejte klíč jako řetězec do instance 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)

Vytvoření klienta s přihlašovacími údaji Azure Active Directory

AzureKeyCredential ověřování se používá v příkladech v této příručce Začínáme, ale můžete se také ověřit pomocí azure Active Directory pomocí knihovny azure-identity . Upozorňujeme, že místní koncové body nepodporují ověřování AAD. Vytvořte vlastní název subdomény pro váš prostředek, abyste mohli použít tento typ ověřování.

Pokud chcete použít níže uvedený typ DefaultAzureCredential nebo jiné typy přihlašovacích údajů, které jsou součástí sady Azure SDK, nainstalujte azure-identity balíček:

pip install azure-identity

Budete také muset zaregistrovat novou aplikaci AAD a udělit přístup k funkci Document Intelligence přiřazením role k instančnímu objektu "Cognitive Services User" .

Po dokončení nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: 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)

Klíčové koncepty

DocumentIntelligenceClient

DocumentIntelligenceClient poskytuje operace pro analýzu vstupních dokumentů pomocí předem připravených a vlastních modelů prostřednictvím begin_analyze_document rozhraní API. Pomocí parametru model_id vyberte typ modelu pro analýzu. Úplný seznam podporovaných modelů najdete tady. Poskytuje DocumentIntelligenceClient také operace pro klasifikaci dokumentů prostřednictvím begin_classify_document rozhraní API. Vlastní klasifikační modely mohou klasifikovat každou stránku ve vstupním souboru a identifikovat dokumenty v rámci a také identifikovat více dokumentů nebo více instancí jednoho dokumentu ve vstupním souboru.

Ukázkové fragmenty kódu jsou k dispozici pro ilustraci pomocí DocumentIntelligenceClient zde. Další informace o analýze dokumentů, včetně podporovaných funkcí, národních prostředí a typů dokumentů, najdete v dokumentaci ke službě.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient poskytuje operace pro:

  • Vytváření vlastních modelů pro analýzu konkrétních polí, která zadáte popiskem vlastních dokumentů. Vrátí DocumentModelDetails se kód označující typy dokumentů, které model může analyzovat, a také odhadovanou spolehlivost jednotlivých polí. Podrobnější vysvětlení najdete v dokumentaci ke službě .
  • Vytvoření složeného modelu z kolekce existujících modelů
  • Správa modelů vytvořených ve vašem účtu
  • Výpis operací nebo získání konkrétní operace modelu vytvořené během posledních 24 hodin
  • Kopírování vlastního modelu z jednoho prostředku Document Intelligence do jiného
  • Vytvořte a spravujte vlastní klasifikační model pro klasifikaci dokumentů, které zpracováváte v rámci aplikace.

Upozorňujeme, že modely lze také vytvářet pomocí grafického uživatelského rozhraní, jako je Document Intelligence Studio.

Ukázkové fragmenty kódu jsou k dispozici pro ilustraci pomocí DocumentIntelligenceAdministrationClient.

Dlouhotrvající operace

Dlouhotrvající operace jsou operace, které se skládají z počátečního požadavku odeslaného službě na spuštění operace a následného dotazování služby v intervalech, aby se zjistilo, jestli se operace dokončila nebo selhala, a pokud byla úspěšná, aby se získal výsledek.

Metody, které analyzují dokumenty, vytvářejí modely nebo modely kopírování/vytváření, se modelují jako dlouhotrvající operace. Klient zveřejňuje metodu begin_<method-name> , která vrací LROPoller nebo AsyncLROPoller. Volající by měli počkat na dokončení operace voláním result() objektu poller vráceného begin_<method-name> z metody. Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití dlouhotrvajících operací níže.

Příklady

Následující část obsahuje několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh funkce Document Intelligence, mezi které patří:

Extrahovat rozložení

Extrahujte z dokumentů text, značky výběru, styly textu a struktury tabulek spolu se souřadnicemi ohraničující oblasti.

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

Použití předem připravených modelů

Extrahujte pole z vybraných typů dokumentů, jako jsou účtenky, faktury, vizitky, doklady totožnosti a daňové doklady USA W-2, pomocí předem připravených modelů poskytovaných službou Document Intelligence.

Pokud chcete například analyzovat pole z prodejního dokladu, použijte předem vytvořený model účtenky, který poskytuje předáním model_id="prebuilt-receipt"begin_analyze_document do metody:

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

Nejste omezeni na účtenky! Můžete si vybrat z několika předem připravených modelů, z nichž každý má vlastní sadu podporovaných polí. Další podporované předem připravené modely najdete tady.

Vytvoření vlastního modelu

Vytvořte vlastní model podle vlastního typu dokumentu. Výsledný model lze použít k analýze hodnot z typů dokumentů, na které byl natrénován. Zadejte adresu URL SAS kontejneru do kontejneru objektů blob služby Azure Storage, do kterého ukládáte trénovací dokumenty.

Další podrobnosti o nastavení kontejneru a požadované struktuře souborů najdete v dokumentaci ke službě.

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

Analýza dokumentů pomocí vlastního modelu

Analyzujte pole dokumentu, tabulky, výběrové značky a další možnosti. Tyto modely se trénují s vlastními daty, takže jsou přizpůsobené vašim dokumentům. Nejlepších výsledků dosáhnete, když budete analyzovat jenom dokumenty stejného typu, pomocí kterého byl vytvořený vlastní model.

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

Kromě toho je možné použít adresu URL dokumentu také k analýze dokumentů pomocí metody .begin_analyze_document

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

Správa modelů

Spravujte vlastní modely připojené k vašemu účtu.

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

Možnosti doplňků

Funkce Document Intelligence podporuje sofistikovanější analytické funkce. Tyto volitelné funkce je možné povolit a zakázat v závislosti na scénáři extrakce dokumentu.

Ve verzi 2023-07-31 (GA) a novějších verzích jsou k dispozici následující možnosti doplňků:

Upozorňujeme, že za některé možnosti doplňků se účtují další poplatky. Viz ceny: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Řešení potíží

Obecné

Klientská knihovna document intelligence vyvolá výjimky definované v Azure Core. Kódy chyb a zprávy vyvolané službou Document Intelligence najdete v dokumentaci ke službě.

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování .

Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na INFO úrovni.

Podrobné DEBUG protokolování úrovně, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit u klienta nebo pro jednotlivé operace pomocí argumentu klíčového logging_enable slova.

Kompletní dokumentaci k protokolování sady SDK s příklady najdete tady.

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a pro jednotlivé operace. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Další kroky

Další vzorový kód

V ukázkovém souboru README najdete několik fragmentů kódu, které ilustrují běžné vzory používané v rozhraní Api Pythonu pro analýzu dokumentů.

Další dokumentace

Podrobnější dokumentaci k funkcím Document Intelligence v Azure AI najdete v dokumentaci funkce Document Intelligence na docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.