Поделиться через

Клиентская библиотека Azure Распознаватель документов для Python версии 3.0.0

  • Статья

Azure Cognitive Services Распознаватель документов — это облачная служба, которая использует машинное обучение для распознавания текстовых и табличных данных из документов форм. Он включает в себя следующие основные функции:

  • Пользовательские модели — распознавание значений полей и табличных данных из форм. Эти модели обучаются по вашим данным, а значит хорошо адаптированы для работы с вашими формами.
  • API содержимого — распознавание структур текста и таблиц, а также их координаты ограничивающего прямоугольника из документов. Соответствует API макета службы REST.
  • Предварительно созданная модель квитанций— распознавание данных из США квитанций о продажах с помощью предварительно созданной модели.

Исходный код | Пакет (PyPI) | Справочная документация по| API Документация по продукту | Образцы

Начало работы

Предварительные требования

Установка пакета

Установите клиентную библиотеку Azure Распознаватель документов для Python версии 3.0.0 с pip:

pip install azure-ai-formrecognizer

Примечание. Эта версия клиентской библиотеки поддерживает версию 2.0 службы Распознаватель документов.

Создание ресурса Распознавателя документов

Распознаватель документов поддерживает доступ как с несколькими службами, так и с одной службой. Создайте ресурс Cognitive Services, если планируете осуществлять доступ к нескольким службам с помощью одной конечной точки или ключа. Для доступа только к Распознавателю документов создайте ресурс Распознавателя документов.

Вы можете создать ресурс с помощью

Вариант 1.Портал Azure

Вариант 2:Azure 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

Аутентификация клиента

Чтобы взаимодействовать со службой Распознаватель документов, необходимо создать экземпляр клиента. Для создания экземпляра клиентского объекта необходимы конечная точка и учетные данные .

Поиск конечной точки

Вы можете найти конечную точку для ресурса Распознаватель документов с помощью портала Azure или Azure CLI:

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

Получение ключа API

Ключ API можно найти на портале Azure или с помощью следующей команды Azure CLI:

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

Создание клиента с помощью AzureKeyCredential

Чтобы использовать ключ API в credential качестве параметра, передайте ключ в виде строки в экземпляр 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)

Создание клиента с учетными данными Azure Active Directory

AzureKeyCredential Проверка подлинности используется в примерах в этом руководстве по началу работы, но вы также можете пройти проверку подлинности в Azure Active Directory с помощью библиотеки azure-identity . Обратите внимание, что региональные конечные точки не поддерживают проверку подлинности AAD. Создайте пользовательское имя поддомена для ресурса, чтобы использовать этот тип проверки подлинности.

Чтобы использовать тип DefaultAzureCredential, показанный ниже, или другие типы учетных данных, предоставляемые пакетом azure-identity SDK для Azure, установите пакет :

pip install azure-identity

Вам также потребуется зарегистрировать новое приложение AAD и предоставить доступ к Распознаватель документов, назначив "Cognitive Services User" роль субъекту-службе.

После завершения задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: 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
)

Основные понятия

FormRecognizerClient

FormRecognizerClient предоставляет операции для перечисленных ниже целей.

  • Распознавание полей форм и содержимого с помощью настраиваемых моделей, обученных для распознавания пользовательских форм. Эти значения возвращаются в коллекцию объектов RecognizedForm.
  • Распознавание общих полей из квитанций США с помощью предварительно обученной модели квитанций. Эти поля и метаданные возвращаются в коллекции RecognizedForm объектов .
  • Распознавание содержимого формы, в том числе таблиц, строк и слов, без необходимости обучения модели. Содержимое форм возвращается в коллекцию объектов FormPage.

Примеры фрагментов кода приведены для демонстрации использования FormRecognizerClient здесь.

FormTrainingClient

FormTrainingClient предоставляет операции для перечисленных ниже целей.

  • Обучение пользовательских моделей без меток для распознавания всех полей и значений, найденных в пользовательских формах. Возвращаемый объект CustomFormModel задает типы форм, которые будет распознавать модель, и поля, которые она будет извлекать для каждого из этих типов. Более подробное описание см. в документации по службам .
  • Обучение пользовательских моделей с помощью меток для распознавания определенных полей и значений, заданных путем добавления меток к пользовательским формам. Возвращаемый объект CustomFormModel задает поля, которые будут извлечены моделью, а также предполагаемую точность для каждого поля. Более подробное описание см. в документации по службам .
  • Управление моделями, созданными в учетной записи.
  • Копирование настраиваемой модели из одного ресурса Распознавателя документов в другой.

Обратите внимание, что модель можно также обучить с помощью графического пользовательского интерфейса, например средства разметки Распознавателя документов.

Примеры фрагментов кода приведены для иллюстрации с помощью FormTrainingClient здесь.

Операции Long-Running

Длительные операции — это операции, состоящие из первоначального запроса, отправленного службе для запуска операции, за которым следует опрос службы с интервалами, чтобы определить, была ли операция завершена или завершилась сбоем, и если она была успешной, для получения результата.

Методы, которые обучают модели, распознают значения из форм или модели копирования, моделируются как длительные операции. Клиент предоставляет метод, возвращающий begin_<method-name>LROPoller или AsyncLROPoller. Вызывающие объекты должны дождаться завершения операции, вызвав result() объект опроса, возвращенный из begin_<method-name> метода . Примеры фрагментов кода приведены для демонстрации с помощью длительных операций ниже.

Примеры

В следующем разделе представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач Распознаватель документов, в том числе:

Распознавание форм с помощью пользовательской модели

Распознавание пар "имя-значение" и табличных данных из форм. Эти модели обучаются по вашим данным, а значит хорошо адаптированы для работы с вашими формами. Для достижения наилучших результатов следует распознавать только формы с тем же типом формы, по которому была обучена пользовательская модель.

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

Кроме того, URL-адрес формы можно также использовать для распознавания пользовательских форм с помощью begin_recognize_custom_forms_from_url метода . Методы _from_url существуют для всех методов распознавания.

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

Распознавание содержимого

Распознавание текстовых и табличных структур вместе с их координатами ограничивающего прямоугольника из документов.

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

Распознавание квитанций

Распознавание данных из США квитанций о продажах с помощью предварительно созданной модели. Поля квитанций, распознанные службой, можно найти здесь.

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

Обучение модели

Обучение пользовательской модели на основе собственного типа формы. Результирующая модель может использоваться для распознавания значений из типов форм, для которого она была обучена. Укажите URL-адрес SAS контейнера для контейнера BLOB-объектов службы хранилища Azure, в котором хранятся обучающие документы. Если обучающие файлы находятся во вложенной папке контейнера, используйте аргумент префикса ключевого слова, чтобы указать, в какой папке следует обучать.

Дополнительные сведения о настройке контейнера и требуемой структуре файлов см. в документации по службе.

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

Управление моделями

Управление пользовательскими моделями, подключенными к учетной записи.

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

Устранение неполадок

Общие сведения

Распознаватель документов клиентская библиотека вызовет исключения, определенные в Azure Core.

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

С помощью аргумента-ключевого слова logging_enable можно включить в клиенте ведение журнала на уровне отладки (DEBUG), на котором фиксируются сведения о телах запросов и ответов, а также заголовки без изменений:

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)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

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

Дополнительная настройка

Необязательные аргументы ключевого слова можно передать на уровне клиента и на уровне операций. В справочной документации azure-Core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Дальнейшие действия

В следующем разделе представлено несколько фрагментов кода, иллюстрирующих распространенные шаблоны, используемые в API Python Распознаватель документов.

Больше примеров кода

В этих примерах кода показаны распространенные операции сценария с клиентской библиотекой Azure Распознаватель документов.

Асинхронные API

Эта библиотека также включает полный асинхронный API, поддерживаемый в Python 3.5 и более поздних версий. Чтобы использовать его, необходимо сначала установить асинхронный транспорт, например aiohttp. Асинхронные клиенты находятся в azure.ai.formrecognizer.aio пространстве имен.

Дополнительная документация

Более подробную документацию по azure Cognitive Services Распознаватель документов см. в документации по Распознаватель документов docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см . на странице cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.