Biblioteca cliente de Azure Form Recognizer para Python: versión 3.0.0

  • Artículo

Azure Cognitive Services Form Recognizer es un servicio en la nube que usa aprendizaje automático para reconocer texto y datos de tabla de documentos de formularios. Incluye las siguientes funcionalidades principales:

  • Modelos personalizados: reconozca los valores de campo y los datos de tabla de los formularios. Puede entrenar estos modelos con sus propios datos para que se adapten a sus formularios.
  • Content API: reconoce las estructuras de texto y tabla, junto con sus coordenadas de rectángulo delimitador, a partir de documentos. Corresponde a la API de diseño del servicio REST.
  • Modelo de recibo precompilado: reconoce los datos de los recibos de ventas de EE. UU. mediante un modelo precompilado.

Código | fuente Paquete (PyPI) | Documentación | de referencia de API | Documentación del productoMuestras

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de Azure Form Recognizer para Python, versión 3.0.0 con pip:

pip install azure-ai-formrecognizer

Nota: Esta versión de la biblioteca cliente admite la versión v2.0 del servicio Form Recognizer

Creación de un recurso de Form Recognizer

Form Recognizer admite el acceso de varios servicios 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 acceder únicamente a Form Recognizer, cree un recurso de Form Recognizer.

Puede crear el recurso 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 Form Recognizer mediante la CLI:

# Create a new resource group to hold the form recognizer resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create form recognizer
az cognitiveservices account create \
    --name form-recognizer-resource \
    --resource-group my-resource-group \
    --kind FormRecognizer \
    --sku F0 \
    --location westus2 \
    --yes

Autenticar el cliente

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

Búsqueda del punto de conexión

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

# Get the endpoint for the form recognizer resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

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.formrecognizer import FormRecognizerClient

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")
form_recognizer_client = FormRecognizerClient(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 Form Recognizer 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.

from azure.identity import DefaultAzureCredential
from azure.ai.formrecognizer import FormRecognizerClient
credential = DefaultAzureCredential()

form_recognizer_client = FormRecognizerClient(
    endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
    credential=credential
)

Conceptos clave

FormRecognizerClient

FormRecognizerClient proporciona operaciones para:

  • El reconocimiento de los campos de formulario y el contenido mediante modelos personalizados entrenados para reconocer los formularios personalizados. Estos valores se devuelven en una colección de objetos RecognizedForm.
  • Reconocer campos comunes de recibos de EE. UU., mediante un modelo de recibo entrenado previamente. Estos campos y metadatos se devuelven en una colección de RecognizedForm objetos .
  • El reconocimiento del contenido de los formularios, incluidas tablas, líneas y palabras, sin necesidad de entrenar un modelo. El contenido del formulario se devuelve en una colección de objetos FormPage.

Aquí se proporcionan fragmentos de código de ejemplo para ilustrar el uso de formularios FormRecognizerClient aquí.

FormTrainingClient

FormTrainingClient proporciona operaciones para:

  • Entrenar modelos personalizados sin etiquetas para reconocer todos los campos y valores que se encuentran en los formularios personalizados. Se devuelve un CustomFormModel que indica los tipos de formulario que el modelo reconocerá y los campos que se extraerán para cada tipo de formulario. Consulte la documentación del servicio para obtener una explicación más detallada.
  • Entrenar modelos personalizados con etiquetas para reconocer campos y valores específicos que especifique mediante el etiquetado de los formularios personalizados. Se devuelve un CustomFormModel que indica los campos que el modelo va a extraer, así como la precisión estimada para cada campo. Consulte la documentación del servicio para obtener una explicación más detallada.
  • La administración de los modelos creados en una cuenta.
  • La copia de un modelo personalizado entre recursos de Form Recognizer.

Tenga en cuenta que los modelos también se pueden entrenar mediante una interfaz gráfica de usuario, como la herramienta de etiquetado de Form Recognizer.

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

Operaciones de Long-Running

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 entrenan modelos, reconocen valores de formularios o modelos de copia 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 Form Recognizer más comunes, entre las que se incluyen:

Reconocimiento de formularios mediante un modelo personalizado

Reconocer pares nombre-valor y datos de tabla de formularios. Puede entrenar estos modelos con sus propios datos para que se adapten a sus formularios. Para obtener los mejores resultados, solo debe reconocer formularios del mismo tipo de formulario en el que se entrenó el modelo personalizado.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)
model_id = "<your custom model id>"

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_custom_forms(model_id=model_id, form=form)
result = poller.result()

for recognized_form in result:
    print("Form type: {}".format(recognized_form.form_type))
    for name, field in recognized_form.fields.items():
        print("Field '{}' has label '{}' with value '{}' and a confidence score of {}".format(
            name,
            field.label_data.text if field.label_data else name,
            field.value,
            field.confidence
        ))

Como alternativa, también se puede usar una dirección URL de formulario para reconocer formularios personalizados mediante el begin_recognize_custom_forms_from_url método . Los _from_url métodos existen para todos los métodos de reconocimiento.

form_url = "<url_of_the_form>"
poller = form_recognizer_client.begin_recognize_custom_forms_from_url(model_id=model_id, form_url=form_url)
result = poller.result()

Reconocer contenido

Reconocer estructuras de texto y tabla, junto con sus coordenadas de rectángulo delimitador, de documentos.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_content(form)
page = poller.result()

table = page[0].tables[0] # page 1, table 1
print("Table found on page {}:".format(table.page_number))
for cell in table.cells:
    print("Cell text: {}".format(cell.text))
    print("Location: {}".format(cell.bounding_box))
    print("Confidence score: {}\n".format(cell.confidence))

Reconocimiento de recibos

Reconocer datos de recibos de ventas de EE. UU. mediante un modelo precompilado. Los campos de recibo reconocidos por el servicio se pueden encontrar aquí.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your receipt>", "rb") as fd:
    receipt = fd.read()

poller = form_recognizer_client.begin_recognize_receipts(receipt)
result = poller.result()

for receipt in result:
    for name, field in receipt.fields.items():
        if name == "Items":
            print("Receipt Items:")
            for idx, items in enumerate(field.value):
                print("...Item #{}".format(idx+1))
                for item_name, item in items.value.items():
                    print("......{}: {} has confidence {}".format(item_name, item.value, item.confidence))
        else:
            print("{}: {} has confidence {}".format(name, field.value, field.confidence))

Entrenamiento de un modelo

Entrenar un modelo personalizado en su propio tipo de formulario. El modelo resultante se puede usar para reconocer valores de los tipos de formularios 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. Si los archivos de entrenamiento están dentro de una subcarpeta del contenedor, use el argumento de palabra clave de prefijo para especificar en qué carpeta se va a entrenar.

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 FormTrainingClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
poller = form_training_client.begin_training(
    container_sas_url, use_training_labels=False
)
model = poller.result()

# Custom model information
print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

Administrar los modelos

Administre los modelos personalizados asociados a su cuenta.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

# Here we get a paged list of all of our custom models
custom_models = form_training_client.list_custom_models()
print("We have models with the following ids: {}".format(
    ", ".join([m.model_id for m in custom_models])
))

# Replace with the custom model ID from the "Train a model" sample
model_id = "<model_id from the Train a Model sample>"

custom_model = form_training_client.get_custom_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

# Finally, we will delete this model by ID
form_training_client.delete_model(model_id=custom_model.model_id)

try:
    form_training_client.get_custom_model(model_id=custom_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with id {}".format(custom_model.model_id))

Solución de problemas

General

Form Recognizer biblioteca cliente generará excepciones definidas en Azure Core.

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

El registro detallado del nivel de depuración, incluidos los cuerpos de solicitud y respuesta, y los encabezados no redactados, se puede habilitar en un cliente con el argumento de palabra clave logging_enable:

import sys
import logging
from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

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

# This client will log detailed information about its HTTP sessions, at DEBUG level
form_recognizer_client = FormRecognizerClient(endpoint, credential, logging_enable=True)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

poller = form_recognizer_client.begin_recognize_receipts(receipt, logging_enable=True)

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

En la sección siguiente se proporcionan varios fragmentos de código que ilustran patrones comunes que se usan en la API de Python de Form Recognizer.

Más código de ejemplo

Estos ejemplos de código muestran operaciones de escenario comunes con la biblioteca cliente de Azure Form Recognizer.

API asincrónicas

Esta biblioteca también incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Los clientes asincrónicos se encuentran en el azure.ai.formrecognizer.aio espacio de nombres .

Documentación adicional

Para obtener documentación más amplia sobre la Form Recognizer de Azure Cognitive Services, consulte la documentación de Form Recognizer 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 obtener más información, visite 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 más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.