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

O Azure AI Document Intelligence (anteriormente conhecido como Reconhecimento de Formulários) é um serviço de nuvem que usa o aprendizado de máquina para analisar texto e dados estruturados de seus documentos. Ele inclui os seguintes recursos de main:

• Layout – extrair conteúdo e estrutura (ex. palavras, marcas de seleção, tabelas) de documentos.
• Documento – Analisar pares chave-valor, além do layout geral de documentos.
• Ler – Ler informações de página de documentos.
• Predefinido – Extraia valores de campo comuns de tipos de documento selecionados (por exemplo, recibos, faturas, cartões de visita, documentos de ID, documentos fiscais do W-2 dos EUA, entre outros) usando modelos predefinidos.
• Personalizado – crie modelos personalizados de seus próprios dados para extrair valores de campo personalizados, além do layout geral de documentos.
• Classificadores – crie modelos de classificação personalizados que combinam recursos de layout e linguagem para detectar e identificar com precisão documentos que você processa em seu aplicativo.
• Recursos de complemento – extraia códigos de barras/códigos de código de barras/QR, fórmulas, fonte/estilo etc. ou habilite o modo de alta resolução para documentos grandes com parâmetros opcionais.

Introdução

Instalando o pacote

python -m pip install azure-ai-documentintelligence

Pré-requisitos

• É necessário ter o Python 3.7 ou posterior para usar esse pacote.
• Você precisa de uma assinatura do Azure para usar esse pacote.
• Uma instância existente do Azure AI Document Intelligence.

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

O Document Intelligence dá suporte ao acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se você planeja acessar vários serviços cognitivos em um só ponto de extremidade/chave. Somente para acesso ao Document Intelligence, crie um recurso do Document Intelligence. Observe que você precisará de um recurso de serviço único se pretende usar a autenticação do Azure Active Directory.

Você pode criar qualquer recurso usando:

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

Veja abaixo um exemplo de como você pode criar um recurso do Document Intelligence usando 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 as informações de localização e sku, consulte aqui.

Autenticar o cliente

Para interagir com o serviço de Inteligência de Documentos, você precisará criar uma instância de um cliente. Um ponto de extremidade e uma credencial são necessários para instanciar o objeto cliente.

Obter o ponto de extremidade

Você pode encontrar o ponto de extremidade para o recurso do Document Intelligence usando 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 de extremidade regional ou um subdomínio personalizado podem ser usados para autenticação. Eles são formatados da seguinte maneira:

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

Um ponto de extremidade regional é o mesmo para cada recurso em uma região. Uma lista completa de pontos de extremidade regionais com suporte pode ser consultada aqui. Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD.

Um subdomínio personalizado, por outro lado, é um nome exclusivo para o recurso de Inteligência de Documento. Eles só podem ser usados por recursos de serviço único.

Obter a chave de API

A chave de API pode ser encontrada no Portal do Azure ou executando o seguinte comando da CLI do Azure:

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

Criar o cliente com AzureKeyCredential

Para usar uma chave de API como parâmetro credential , passe a chave como uma cadeia de caracteres 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 é usada nos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do azure . Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para usar esse tipo de autenticação.

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

pip install azure-identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao Document Intelligence atribuindo a "Cognitive Services User" função à sua entidade de serviço.

Depois de concluído, defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo 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)

Principais conceitos

DocumentIntelligenceClient

DocumentIntelligenceClient fornece operações para analisar documentos de entrada usando modelos predefinidos e personalizados por meio da begin_analyze_document API. Use o model_id parâmetro para selecionar o tipo de modelo para análise. Veja uma lista completa de modelos com suporte aqui. O DocumentIntelligenceClient também fornece operações para classificar documentos por meio da begin_classify_document API. Os modelos de classificação personalizados podem classificar cada página em um arquivo de entrada para identificar o(s) documento(s) e também podem identificar vários documentos ou várias instâncias de um único documento em um arquivo de entrada.

Snippets de código de exemplo são fornecidos para ilustrar usando um DocumentIntelligenceClient aqui. Mais informações sobre como analisar documentos, incluindo recursos com suporte, localidades e tipos de documento, podem ser encontradas na documentação do serviço.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient fornece operações para:

• Criando modelos personalizados para analisar campos específicos especificados rotulando seus documentos personalizados. Um DocumentModelDetails é retornado indicando os tipos de documento que o modelo pode analisar, bem como a confiança estimada para cada campo. Consulte a documentação do serviço para obter uma explicação mais detalhada.
• Criando um modelo composto de uma coleção de modelos existentes.
• Gerenciar modelos criados em 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 da Informação de Documentos para outro.
• Crie e gerencie um modelo de classificação personalizado para classificar os documentos que você processa em seu aplicativo.

Observe que os modelos também podem ser criados usando uma interface gráfica do usuário, como o Document Intelligence Studio.

Snippets de código de exemplo são fornecidos para ilustrar usando um DocumentIntelligenceAdministrationClient aqui.

Operações de execução longa

Operações de execução prolongada são operações que consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguidas por sondar o serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Métodos que analisam documentos, modelos de build ou modelos de cópia/composição são modelados como operações de execução prolongada. O cliente expõe um begin_<method-name> método que retorna um LROPoller ou AsyncLROPoller. Os chamadores devem aguardar a conclusão da operação chamando result() o objeto poller retornado do begin_<method-name> método . Snippets de código de exemplo são fornecidos para ilustrar o uso de operações de execução prolongada abaixo.

Exemplos

A seção a seguir fornece vários snippets de código que abrangem algumas das tarefas mais comuns do Document Intelligence, incluindo:

• Extrair Layout
• Usando o modelo de documento geral
• Usando modelos predefinidos
• Criar um modelo personalizado
• Analisar documentos usando um modelo personalizado
• Gerenciar seus modelos
• Recursos de complemento

Extrair Layout

Extraia texto, marcas de seleção, estilos de texto e estruturas de tabela, juntamente com suas coordenadas de região delimitador, 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("----------------------------------------")

Usando modelos predefinidos

Extraia campos de tipos de documento selecionados, como recibos, faturas, cartões de visita, documentos de identidade e documentos fiscais do W-2 dos EUA usando modelos predefinidos fornecidos pelo serviço de Inteligência de Documentos.

Por exemplo, para analisar campos de um recibo de vendas, use o modelo de recibo predefinido fornecido passando 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("--------------------------------------")

Você não está limitado a recibos! Há alguns modelos predefinidos para escolher, cada um com seu próprio conjunto de campos com suporte. Veja outros modelos predefinidos com suporte aqui.

Criar um modelo personalizado

Crie um modelo personalizado em seu próprio tipo de documento. O modelo resultante pode ser usado para analisar valores dos tipos de documentos nos quais foi treinado. Forneça uma URL SAS de contêiner para seu contêiner de Blob de Armazenamento do Azure em que você está armazenando os documentos de treinamento.

Mais detalhes sobre como configurar um contêiner e a estrutura de arquivo necessária podem ser encontrados 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 usando um modelo personalizado

Analise campos de documento, tabelas, marcas de seleção e muito mais. Esses modelos são treinados com seus próprios dados, portanto, eles são adaptados aos seus documentos. Para obter melhores resultados, você 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, uma URL de documento também pode ser usada para analisar documentos usando 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()

Gerenciar seus modelos

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

Recursos de complemento

O Document Intelligence dá suporte a recursos de análise mais sofisticados. Esses recursos opcionais podem ser habilitados e desabilitados dependendo do cenário de extração de documentos.

Os seguintes recursos de complemento estão disponíveis para GA (2023-07-31) e versões posteriores:

• código de barras/código QR
• Fórmula
• font/style
• modo de alta resolução
• linguagem

Observe que alguns recursos de complemento incorrerão em encargos adicionais. Confira preços: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Solução de problemas

Geral

A biblioteca de clientes do Document Intelligence gerará exceções definidas no Azure Core. Códigos de erro e mensagens geradas pelo serviço de Inteligência de Documentos podem ser encontrados na documentação do serviço.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log.

Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no INFO nível.

O log de nível detalhadoDEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado no cliente ou por operação com o logging_enable argumento palavra-chave.

Confira a documentação completa de registro em log do SDK com exemplos aqui.

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Próximas etapas

Mais códigos de exemplo

Consulte o EXEMPLO README para obter vários snippets de código que ilustram padrões comuns usados na API python do Document Intelligence.

Documentação adicional

Para obter uma documentação mais abrangente sobre o Azure AI Document Intelligence, consulte a documentação do Document Intelligence sobre docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para saber mais, confira as Perguntas frequentes sobre o Código de Conduta ou contate o opencode@microsoft.com caso tenha outras dúvidas ou comentários.