Share via

Клиентская библиотека Azure AI Document Intelligence для Python версии 1.0.0b1

  • Статья

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

  • Макет — извлечение содержимого и структуры (например, слов, меток выделения, таблиц) из документов.
  • Документ — анализ пар "ключ-значение" в дополнение к общему макету из документов.
  • Чтение — чтение сведений о страницах из документов.
  • Предварительно созданная . Извлечение общих значений полей из некоторых типов документов (например, квитанций, счетов, визитных карточек, документов, удостоверений личности, налоговых документов W-2 США и т. д.) с помощью предварительно созданных моделей.
  • Пользовательский — создание пользовательских моделей на основе собственных данных для извлечения настраиваемых значений полей в дополнение к общему макету из документов.
  • Классификаторы. Создавайте пользовательские модели классификации, сочетающие функции макета и языка для точного обнаружения и идентификации документов, обрабатываемых в приложении.
  • Дополнительные возможности. Извлечение штрихкодов, QR-кодов, формул, шрифтов и стилей и т. д. или включение режима высокого разрешения для больших документов с необязательными параметрами.

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

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

python -m pip install azure-ai-documentintelligence

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

  • Для использования этого пакета требуется Python 3.7 или более поздней версии.
  • Для использования этого пакета требуется подписка Azure .
  • Существующий экземпляр Azure AI Document Intelligence.

Создание ресурса Cognitive Services или аналитики документов

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

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

Ниже приведен пример создания ресурса аналитики документов с помощью ИНТЕРФЕЙСА командной строки:

# 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

Дополнительные сведения о создании ресурса или получении сведений о расположении и номере SKU см. здесь.

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

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

Получение конечной точки

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

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

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

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

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

Пользовательский поддомен, с другой стороны, — это имя, уникальное для ресурса Аналитики документов. Они могут использоваться только ресурсами с одной службой.

Получение ключа 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.documentintelligence import DocumentIntelligenceClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_analysis_client = DocumentIntelligenceClient(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.

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

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

DocumentIntelligenceClient

DocumentIntelligenceClient предоставляет операции для анализа входных документов с помощью предварительно созданных и пользовательских моделей через begin_analyze_document API. Используйте параметр , model_id чтобы выбрать тип модели для анализа. Полный список поддерживаемых моделей см. здесь. Также DocumentIntelligenceClient предоставляет операции для классификации документов с помощью begin_classify_document API. Пользовательские модели классификации могут классифицировать каждую страницу входного файла для идентификации документов внутри, а также определить несколько документов или несколько экземпляров одного документа во входном файле.

Примеры фрагментов кода предоставляются для демонстрации с помощью DocumentIntelligenceClient здесь. Дополнительные сведения об анализе документов, включая поддерживаемые функции, языковые стандарты и типы документов, см. в документации по службе.

DocumentIntelligenceAdministrationClient

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

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

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

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

Длительные операции

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

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

Примеры

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

Извлечение макета

Извлечение текста, меток выделения, стилей текста и структур таблиц вместе с координатами ограничивающей области из документов.

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

Использование предварительно созданных моделей

Извлекайте поля из документов некоторых типов, таких как квитанции, счета, визитные карточки, документы, удостоверяющие личность, и налоговые документы W-2 США, с помощью готовых моделей, предоставляемых службой аналитики документов.

Например, чтобы проанализировать поля из квитанции о продаже, используйте предварительно созданную модель квитанции, предоставляемую путем передачи model_id="prebuilt-receipt"begin_analyze_document в метод :

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

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

Создание пользовательской модели

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

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

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

Анализ документов с помощью пользовательской модели

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

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

Кроме того, URL-адрес документа также можно использовать для анализа документов с помощью begin_analyze_document метода .

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

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

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

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

Возможности надстройки

Аналитика документов поддерживает более сложные возможности анализа. Эти необязательные функции можно включить и отключить в зависимости от сценария извлечения документа.

Следующие возможности надстройки доступны для 31.07.2023 (ga) и более поздних выпусков:

Обратите внимание, что за некоторые дополнительные возможности взимается дополнительная плата. См. цены: https://azure.microsoft.com/pricing/details/ai-document-intelligence/.

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

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

Клиентская библиотека аналитики документов вызывает исключения, определенные в Azure Core. Коды ошибок и сообщения, создаваемые службой аналитики документов, можно найти в документации по службе.

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

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала.

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

Подробное DEBUG ведение журнала на уровне, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте или на операцию с помощью аргумента logging_enable ключевое слово.

См. полную документацию по ведению журнала пакета SDK с примерами здесь.

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

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

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

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

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

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

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

Участие

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

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

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