Biblioteca de cliente do Document Intelligence do Azure AI para Python – versão 1.0.0b1

O Azure AI Document Intelligence (anteriormente conhecido como Reconhecedor de Formulários) é um serviço cloud que utiliza machine learning para analisar texto e dados estruturados dos seus documentos. Inclui as seguintes funcionalidades principais:

• Esquema – extraia conteúdo e estrutura (por exemplo, palavras, marcas de seleção, tabelas) de documentos.
• Documento – analise pares chave-valor para além do esquema geral a partir de documentos.
• Ler – ler informações da página a partir de documentos.
• Pré-criado – extraia valores de campo comuns de tipos de documentos selecionados (por exemplo, recibos, faturas, cartões de visita, documentos de ID, documentos fiscais W-2 dos E.U.A., entre outros) através de modelos pré-criados.
• Personalizado – crie modelos personalizados a partir dos seus próprios dados para extrair valores de campo personalizados, além do esquema geral dos documentos.
• Classificadores – crie modelos de classificação personalizados que combinem funcionalidades de esquema e idioma para detetar e identificar com precisão documentos que processa na sua aplicação.
• Capacidades de suplementos – extraia códigos de barras/códigos QR, fórmulas, tipo de letra/estilo, etc. ou ative o modo de alta resolução para documentos grandes com parâmetros opcionais.

Introdução

Instalar o pacote

python -m pip install azure-ai-documentintelligence

Pré-requisitos

• O Python 3.7 ou posterior é necessário para utilizar este pacote.
• Precisa de uma subscrição do Azure para utilizar este pacote.
• Uma instância do Azure AI Document Intelligence existente.

Criar um recurso dos Serviços Cognitivos ou do Document Intelligence

O Document Intelligence suporta o acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se planear aceder a múltiplos serviços cognitivos num único ponto final/chave. Apenas para acesso ao Document Intelligence, crie um recurso do Document Intelligence. Tenha em atenção que precisará de um recurso de serviço único se pretender utilizar a autenticação do Azure Active Directory.

Pode criar qualquer um dos recursos com:

• Opção 1: Portal do Azure.
• Opção 2: CLI do Azure.

Segue-se um exemplo de como pode criar um recurso do Document Intelligence com a 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

Para obter mais informações sobre como criar o recurso ou como obter a localização e as informações do SKU, veja aqui.

Autenticar o cliente

Para interagir com o serviço Document Intelligence, terá de criar uma instância de um cliente. É necessário um ponto final e uma credencial para instanciar o objeto de cliente.

Obter o ponto final

Pode encontrar o ponto final do recurso do Document Intelligence com o Portal do Azure ou a CLI do Azure:

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

Um ponto final regional ou um subdomínio personalizado pode ser utilizado para autenticação. São formatados da seguinte forma:

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

Um ponto final regional é o mesmo para cada recurso numa região. Pode consultar aqui uma lista completa dos pontos finais regionais suportados. Tenha em atenção que os pontos finais regionais não suportam a autenticação do AAD.

Um subdomínio personalizado, por outro lado, é um nome exclusivo do recurso do Document Intelligence. Só podem ser utilizados por recursos de serviço único.

Obter a chave de API

A chave de API pode ser encontrada no portal do Azure ou ao executar o seguinte comando da CLI do Azure:

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

Criar o cliente com o AzureKeyCredential

Para utilizar uma chave de API como parâmetro credential , transmita a chave como uma cadeia para uma instância do 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)

Criar o cliente com uma credencial do Azure Active Directory

AzureKeyCredential A autenticação é utilizada nos exemplos neste guia de introdução, mas também pode autenticar com o Azure Active Directory com a biblioteca de identidades do Azure . Tenha em atenção que os pontos finais regionais não suportam a autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para utilizar este tipo de autenticação.

Para utilizar o tipo DefaultAzureCredential mostrado abaixo ou outros tipos de credenciais fornecidos com o SDK do Azure, instale o azure-identity pacote:

pip install azure-identity

Também terá de registar uma nova aplicação do AAD e conceder acesso ao Document Intelligence ao atribuir a "Cognitive Services User" função ao principal de serviço.

Depois de concluído, defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: 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)

Conceitos-chave

DocumentIntelligenceClient

DocumentIntelligenceClient fornece operações para analisar documentos de entrada com modelos pré-criados e personalizados através da begin_analyze_document API. Utilize o model_id parâmetro para selecionar o tipo de modelo para análise. Veja uma lista completa dos modelos suportados aqui. O DocumentIntelligenceClient também fornece operações para classificar documentos através da begin_classify_document API. Os modelos de classificação personalizados podem classificar cada página num ficheiro de entrada para identificar os documentos no e também podem identificar vários documentos ou várias instâncias de um único documento num ficheiro de entrada.

Os fragmentos de código de exemplo são fornecidos para ilustrar a utilização de documentIntelligenceClient aqui. Pode encontrar mais informações sobre a análise de documentos, incluindo funcionalidades suportadas, regiões e tipos de documentos na documentação do serviço.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient fornece operações para:

• Criar modelos personalizados para analisar campos específicos que especificar ao etiquetar os seus documentos personalizados. É DocumentModelDetails devolvido um que indica os tipos de documento que o modelo pode analisar, bem como a confiança estimada para cada campo. Veja a documentação do serviço para obter uma explicação mais detalhada.
• Criar um modelo composto a partir de uma coleção de modelos existentes.
• Gerir modelos criados na sua conta.
• Listar operações ou obter uma operação de modelo específica criada nas últimas 24 horas.
• Copiar um modelo personalizado de um recurso do Document Intelligence para outro.
• Crie e faça a gestão de um modelo de classificação personalizado para classificar os documentos que processa na sua aplicação.

Tenha em atenção que os modelos também podem ser criados com uma interface gráfica, como o Document Intelligence Studio.

Os fragmentos de código de exemplo são fornecidos para ilustrar a utilização de documentIntelligenceAdministrationClient aqui.

Operações de execução prolongada

As operações de execução prolongada são operações que consistem num pedido inicial enviado ao serviço para iniciar uma operação, seguidas de consulta do serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Os métodos que analisam documentos, criam modelos ou copiam/compõem modelos são modelados como operações de execução prolongada. O cliente expõe um begin_<method-name> método que devolve um LROPoller ou AsyncLROPoller. Os autores da chamada devem aguardar que a operação seja concluída ao chamar result() o objeto poller devolvido do begin_<method-name> método . Os fragmentos de código de exemplo são fornecidos para ilustrar a utilização de operações de execução prolongada abaixo.

Exemplos

A secção seguinte fornece vários fragmentos de código que abrangem algumas das tarefas mais comuns do Document Intelligence, incluindo:

• Esquema de Extração
• Utilizar o Modelo Geral de Documentos
• Utilizar Modelos Pré-criados
• Criar um Modelo Personalizado
• Analisar Documentos Com um Modelo Personalizado
• Gerir os seus modelos
• Capacidades de suplementos

Esquema de Extração

Extraia texto, marcas de seleção, estilos de texto e estruturas de tabela, juntamente com as respetivas coordenadas de região delimitadora, de documentos.

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

Utilizar Modelos Pré-criados

Extraia campos de tipos de documento selecionados, tais como recibos, faturas, cartões de visita, documentos de identidade e documentos fiscais W-2 dos E.U.A. através de modelos pré-criados fornecidos pelo serviço document Intelligence.

Por exemplo, para analisar campos de um recibo de vendas, utilize o modelo de recibo pré-criado fornecido ao passar model_id="prebuilt-receipt" para o begin_analyze_document método :

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

Não está limitado a recibos! Existem alguns modelos pré-criados à escolha, cada um dos quais tem o seu próprio conjunto de campos suportados. Veja outros modelos pré-criados suportados aqui.

Criar um Modelo Personalizado

Crie um modelo personalizado no seu próprio tipo de documento. O modelo resultante pode ser utilizado para analisar valores dos tipos de documentos em que foi preparado. Forneça um URL de SAS de contentor para o contentor de Blobs de Armazenamento do Azure onde está a armazenar os documentos de preparação.

Pode encontrar mais detalhes sobre como configurar um contentor e a estrutura de ficheiros necessária na documentação do serviço.

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

Analisar Documentos Com um Modelo Personalizado

Analise campos de documentos, tabelas, marcas de seleção e muito mais. Estes modelos são preparados com os seus próprios dados, pelo que são adaptados aos seus documentos. Para obter os melhores resultados, só deve analisar documentos do mesmo tipo de documento com o qual o modelo personalizado foi criado.

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

Além disso, um URL de documento também pode ser utilizado para analisar documentos com o begin_analyze_document método .

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

Gerir os seus modelos

Faça a gestão dos modelos personalizados anexados à sua conta.

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

Capacidades do Suplemento

O Document Intelligence suporta capacidades de análise mais sofisticadas. Estas funcionalidades opcionais podem ser ativadas e desativadas consoante o cenário de extração de documentos.

As seguintes capacidades de suplemento estão disponíveis para 2023-07-31 (GA) e versões posteriores:

• código de barras/código QR
• fórmula
• tipo de letra/estilo
• modo de alta resolução
• idioma

Tenha em atenção que algumas capacidades de suplementos irão incorrer em custos adicionais. Veja os preços: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Resolução de problemas

Geral

A biblioteca de cliente do Document Intelligence irá gerar exceções definidas no Azure Core. Os códigos de erro e as mensagens gerados pelo serviço document Intelligence podem ser encontrados na documentação do serviço.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo.

As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao INFO nível.

O registo de nível detalhado DEBUG , incluindo os corpos de pedido/resposta e os cabeçalhos não retotados , pode ser ativado no cliente ou por operação com o logging_enable argumento de palavra-chave.

Veja a documentação completa do registo do SDK com exemplos aqui.

Configuração opcional

Os argumentos de palavra-chave opcionais podem ser transmitidos ao nível do cliente e por operação. A documentação de referência azure-core descreve as configurações disponíveis para repetições, registo, protocolos de transporte e muito mais.

Passos seguintes

Mais código de exemplo

Veja README de exemplo para obter vários fragmentos de código que ilustram padrões comuns utilizados na API python do Document Intelligence.

Documentação adicional

Para obter documentação mais extensa sobre o Document Intelligence do Azure AI, veja a documentação do Document Intelligence sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.