Biblioteca cliente de Inteligencia de documentos de Azure AI para Python, versión 1.0.0b1

Azure AI Document Intelligence (anteriormente conocido como Form Recognizer) es un servicio en la nube que usa el aprendizaje automático para analizar texto y datos estructurados de los documentos. Incluye las siguientes características principales:

• Diseño: extraiga contenido y estructura (por ejemplo, palabras, marcas de selección, tablas) de documentos.
• Documento: analice pares clave-valor además del diseño general de los documentos.
• Leer: leer información de página de documentos.
• Precompilado: extraiga valores de campo comunes de los tipos de documento seleccionados (por ejemplo, recibos, facturas, tarjetas de presentación, documentos de identificación, documentos fiscales W-2 de EE. UU., entre otros) mediante modelos precompilados.
• Personalizado: cree modelos personalizados a partir de sus propios datos para extraer valores de campo personalizados además del diseño general de los documentos.
• Clasificadores: cree modelos de clasificación personalizados que combinen características de diseño y lenguaje para detectar e identificar con precisión los documentos que procesa dentro de la aplicación.
• Funcionalidades de complementos: extraiga códigos de barras/códigos QR, fórmulas, fuente/estilo, etc. o habilite el modo de alta resolución para documentos grandes con parámetros opcionales.

Introducción

Instalación del paquete

python -m pip install azure-ai-documentintelligence

Requisitos previos

• Se requiere Python 3.7 o posterior para usar este paquete.
• Necesita una suscripción de Azure para usar este paquete.
• Una instancia existente de Inteligencia de documentos de Azure AI.

Creación de un recurso de Cognitive Services o Document Intelligence

Document Intelligence admite el acceso multiservicio y de un solo servicio. Cree un recurso de Cognitive Services si tiene previsto acceder a varios servicios de Cognitive Services en un único punto de conexión o clave. Para obtener acceso solo a Documento de inteligencia cree un recurso de Documento de inteligencia. Tenga en cuenta que necesitará un recurso de servicio único si piensa usar la autenticación de Azure Active Directory.

Puede crear cualquiera de los recursos mediante:

• Opción 1: Azure Portal.
• Opción 2: CLI de Azure.

A continuación se muestra un ejemplo de cómo puede crear un recurso de Document Intelligence mediante la 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 obtener más información sobre cómo crear el recurso o cómo obtener la información de ubicación y SKU , consulte aquí.

Autenticar el cliente

Para interactuar con el servicio De inteligencia de documentos, deberá crear una instancia de un cliente. Se necesita un punto de conexión y una credencial para crear instancias del objeto de cliente.

Obtención del punto de conexión

Puede encontrar el punto de conexión del recurso de Document Intelligence mediante Azure Portal o la CLI de Azure:

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

Se puede usar un punto de conexión regional o un subdominio personalizado para la autenticación. Tienen el siguiente formato:

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

Un punto de conexión regional es el mismo para cada recurso de una región. Aquí se puede consultar una lista completa de los puntos de conexión regionales admitidos. Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD.

Un subdominio personalizado, por otro lado, es un nombre que es único para el recurso de Inteligencia de documentos. Los recursos de un solo servicio solo los pueden usar.

Obtención de la clave de API

La clave de API se puede encontrar en Azure Portal o mediante la ejecución del siguiente comando de la CLI de Azure:

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

Creación del cliente con AzureKeyCredential

Para usar una clave de API como credential parámetro, pase la clave como una cadena a una instancia de 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)

Creación del cliente con una credencial de Azure Active Directory

AzureKeyCredential La autenticación se usa en los ejemplos de esta guía de introducción, pero también puede autenticarse con Azure Active Directory mediante la biblioteca azure-identity . Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. Cree un nombre de subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

Para usar el tipo DefaultAzureCredential que se muestra a continuación u otros tipos de credenciales proporcionados con el SDK de Azure, instale el azure-identity paquete:

pip install azure-identity

También deberá registrar una nueva aplicación de AAD y conceder acceso a Document Intelligence mediante la asignación del "Cognitive Services User" rol a la entidad de servicio.

Una vez completado, establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: 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)

Conceptos clave

DocumentIntelligenceClient

DocumentIntelligenceClient proporciona operaciones para analizar documentos de entrada mediante modelos precompilados y personalizados a través de la begin_analyze_document API. Use el model_id parámetro para seleccionar el tipo de modelo para su análisis. Consulte aquí una lista completa de los modelos admitidos. DocumentIntelligenceClient También proporciona operaciones para clasificar documentos a través de la begin_classify_document API. El modelo de clasificación personalizado puede clasificar cada página en un archivo de entrada para identificar los documentos que contiene y también puede identificar varios documentos o varias instancias de un único documento dentro de un archivo de entrada.

Aquí se proporcionan fragmentos de código de ejemplo para ilustrar el uso de ejemplos de DocumentIntelligenceClient. Puede encontrar más información sobre el análisis de documentos, incluidas las características admitidas, las configuraciones regionales y los tipos de documento en la documentación del servicio.

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient proporciona operaciones para:

• Crear modelos personalizados para analizar campos específicos que especifique mediante el etiquetado de los documentos personalizados. Se devuelve un DocumentModelDetails valor que indica los tipos de documento que el modelo puede analizar, así como la confianza estimada para cada campo. Consulte la documentación del servicio para obtener una explicación más detallada.
• Crear un modelo compuesto a partir de una colección de modelos existentes.
• La administración de los modelos creados en una cuenta.
• Enumerar operaciones u obtener una operación de modelo específica creada en las últimas 24 horas.
• La copia de un modelo personalizado entre recursos de Documento de inteligencia.
• Compile y administre un modelo de clasificación personalizado para clasificar los documentos que procesa dentro de la aplicación.

Tenga en cuenta que los modelos también se pueden crear mediante una interfaz gráfica de usuario, como Document Intelligence Studio.

Aquí se proporcionan fragmentos de código de ejemplo para ilustrar el uso de ejemplos de DocumentIntelligenceAdministrationClient.

Operaciones de larga duración

Las operaciones de ejecución prolongada son operaciones que constan de una solicitud inicial enviada al servicio para iniciar una operación, seguida de sondear el servicio a intervalos para determinar si la operación se ha completado o ha producido un error y, si se ha realizado correctamente, para obtener el resultado.

Los métodos que analizan documentos, modelos de compilación o modelos de copia/redacción se modelan como operaciones de larga duración. El cliente expone un begin_<method-name> método que devuelve o LROPollerAsyncLROPoller. Los autores de llamadas deben esperar a que se complete la operación llamando result() al objeto de sondeo devuelto desde el begin_<method-name> método . A continuación se proporcionan fragmentos de código de ejemplo para ilustrar el uso de operaciones de larga duración .

Ejemplos

En la siguiente sección se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Inteligencia de documentos, entre las que se incluyen:

• Extraer diseño
• Uso del modelo de documento general
• Uso de modelos precompilados
• Crear un modelo personalizado
• Análisis de documentos mediante un modelo personalizado
• Administrar los modelos
• Funcionalidades de complementos

Extraer diseño

Extraiga texto, marcas de selección, estilos de texto y estructuras de tabla, junto con sus coordenadas de región delimitador, de los 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("----------------------------------------")

Uso de modelos precompilados

Extraiga campos de tipos de documento seleccionados, como recibos, facturas, tarjetas de presentación, documentos de identidad y documentos fiscales W-2 de EE. UU. mediante modelos precompilados proporcionados por el servicio Document Intelligence.

Por ejemplo, para analizar los campos de un recibo de ventas, use el modelo de recibo precompilado proporcionado pasando model_id="prebuilt-receipt" al 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("--------------------------------------")

¡No se limita a los recibos! Hay algunos modelos precompilados entre los que elegir, cada uno de los cuales tiene su propio conjunto de campos admitidos. Consulte otros modelos precompilados admitidos aquí.

Crear un modelo personalizado

Cree un modelo personalizado en su propio tipo de documento. El modelo resultante se puede usar para analizar valores de los tipos de documentos en los que se entrenó. Proporcione una dirección URL de SAS de contenedor al contenedor de blobs de Azure Storage donde va a almacenar los documentos de entrenamiento.

Puede encontrar más detalles sobre la configuración de un contenedor y la estructura de archivos necesaria en la documentación del servicio.

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

Analizar documentos mediante un modelo personalizado

Analice campos de documento, tablas, marcas de selección, etc. Estos modelos se entrenan con sus propios datos, por lo que se adaptan a los documentos. Para obtener los mejores resultados, solo debe analizar documentos del mismo tipo de documento con el que se creó el modelo personalizado.

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

Además, también se puede usar una dirección URL de documento para analizar documentos mediante el 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()

Administrar los modelos

Administre los modelos personalizados asociados a su cuenta.

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

Funcionalidades del complemento

La inteligencia de documentos admite funcionalidades de análisis más sofisticadas. Estas características opcionales se pueden habilitar y deshabilitar en función del escenario de extracción de documentos.

Las siguientes funcionalidades de complemento están disponibles para las versiones 2023-07-31 (GA) y posteriores:

• código de código de barras/QR
• Fórmula
• font/style
• modo de alta resolución
• language

Tenga en cuenta que algunas funcionalidades de complemento incurrirán en cargos adicionales. Consulte precios: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

Solución de problemas

General

La biblioteca cliente de Document Intelligence generará excepciones definidas en Azure Core. Los códigos de error y los mensajes generados por el servicio Document Intelligence se pueden encontrar en la documentación del servicio.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro.

La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el INFO nivel.

El registro de nivel detallado DEBUG , incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados , se puede habilitar en el cliente o por operación con el argumento de palabra logging_enable clave.

Consulte la documentación completa del registro del SDK con ejemplos aquí.

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para reintentos, registro, protocolos de transporte, etc.

Pasos siguientes

Más código de ejemplo

Consulte el archivo Léame de ejemplo para varios fragmentos de código que ilustran patrones comunes que se usan en la API de Python de Inteligencia de documentos.

Documentación adicional

Para obtener documentación más amplia sobre La inteligencia de documentos de Azure AI, consulte la documentación de Document Intelligence sobre docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para obtener más información, vea las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com si tiene preguntas o comentarios.