Python 用 Azure AI ドキュメント インテリジェンス クライアント ライブラリ - バージョン 1.0.0b1

Azure AI ドキュメント インテリジェンス (旧称 Form Recognizer) は、機械学習を使用してドキュメントのテキストと構造化データを分析するクラウド サービスです。 これには、次のメイン機能が含まれています。

• レイアウト - ドキュメントからコンテンツと構造 (単語、選択マーク、テーブルなど) を抽出します。
• ドキュメント - ドキュメントの一般的なレイアウトに加えて、キーと値のペアを分析します。
• 読み取り - ドキュメントからページ情報を読み取ります。
• 事前構築済み - 事前構築済みモデルを使用して、選択したドキュメントの種類 (領収書、請求書、名刺、ID ドキュメント、米国 W-2 税ドキュメントなど) から共通フィールド値を抽出します。
• カスタム - 独自のデータからカスタム モデルを構築し、ドキュメントから一般的なレイアウトに加えて、調整されたフィールド値を抽出します。
• 分類子 - レイアウト機能と言語機能を組み合わせて、アプリケーション内で処理するドキュメントを正確に検出して識別するカスタム分類モデルを構築します。
• アドオン機能 - バーコード/QR コード、数式、フォント/スタイルなどを抽出するか、省略可能なパラメーターを持つ大きなドキュメントの高解像度モードを有効にします。

作業の開始

パッケージのインストール

python -m pip install azure-ai-documentintelligence

前提条件

• このパッケージを使用するには、Python 3.7 以降が必要です。
• このパッケージを使用するには 、Azure サブスクリプション が必要です。
• 既存の Azure AI ドキュメント インテリジェンス インスタンス。

Cognitive Services またはドキュメント インテリジェンス リソースを作成する

ドキュメント インテリジェンスでは、 マルチサービス アクセスとシングル サービス アクセスの両方がサポートされます。 1 つのエンドポイント/キーで複数の Cognitive Services にアクセスする予定の場合は、Cognitive Services リソースを作成します。 Document Intelligence へのアクセスのみの場合は、Document Intelligence リソースを作成します。 Azure Active Directory 認証を使用する場合は、単一サービス リソースが必要であることに注意してください。

次を使用して、いずれかのリソースを作成できます。

• オプション 1: Azure Portal。
• オプション 2: Azure CLI。

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

リソースの作成の詳細、または場所と SKU の情報を取得する方法については、 こちらを参照してください。

クライアントを認証する

ドキュメント インテリジェンス サービスを操作するには、クライアントのインスタンスを作成する必要があります。 クライアント オブジェクトをインスタンス化するには、 エンドポイント と 資格情報 が必要です。

エンドポイントを取得する

ドキュメント インテリジェンス リソースのエンドポイントは、 Azure Portal または 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 Portal で、または次の 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-identity ライブラリを使用して Azure Active Directory で認証することもできます。 リージョン エンドポイントは AAD 認証をサポートしないことに注意してください。 この種類の認証を使用するには、リソースの カスタム サブドメイン 名を作成します。

次に示す DefaultAzureCredential 型、または Azure SDK で提供されているその他の資格情報の種類を使用するには、パッケージを azure-identity インストールしてください。

pip install azure-identity

また、 新しい AAD アプリケーションを登録し、 サービス プリンシパルにロールを "Cognitive Services User" 割り当てることでドキュメント インテリジェンスへのアクセス権を付与する必要があります。

完了したら、AAD アプリケーションのクライアント ID、テナント ID、およびクライアント シークレットの値を環境変数 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 は、API を介して事前構築済みモデルとカスタム モデルを使用して入力ドキュメントを分析するための操作を begin_analyze_document 提供します。 パラメーターを model_id 使用して、分析するモデルの種類を選択します。 サポートされているモデルの完全な一覧 については、こちらを参照してください。 DocumentIntelligenceClientには、API を使用してbegin_classify_documentドキュメントを分類するための操作も用意されています。 カスタム分類モデルは、入力ファイル内の各ページを分類してその中のドキュメントを識別できます。また、入力ファイル内の複数のドキュメントまたは 1 つのドキュメントの複数のインスタンスを識別することもできます。

サンプル コード スニペットは、DocumentIntelligenceClient をここに示すために用意されています。 サポートされている機能、ロケール、ドキュメントの種類など、ドキュメントの分析の詳細については、 サービス ドキュメントを参照してください。

DocumentIntelligenceAdministrationClient

DocumentIntelligenceAdministrationClient には、以下を目的とした操作が用意されています。

• カスタム ドキュメントにラベルを付けることで、指定した特定のフィールドを分析するためのカスタム モデルの構築。 DocumentModelDetailsモデルが分析できるドキュメントの種類と、各フィールドの推定信頼度を示す が返されます。 詳細な説明については、 サービスのドキュメントを参照してください 。
• 既存のモデルのコレクションから構成済みモデルを作成する。
• アカウントに作成されたモデルを管理する。
• 操作を一覧表示するか、過去 24 時間以内に作成された特定のモデル操作を取得します。
• Document Intelligence リソース間でカスタム モデルをコピーする。
• カスタム分類モデルを構築して管理し、アプリケーション内で処理するドキュメントを分類します。

モデルは、 Document Intelligence Studio などのグラフィカル ユーザー インターフェイスを使用して構築することもできます。

サンプル コード スニペットは、DocumentIntelligenceAdministrationClient をここに示すために用意されています。

長時間にわたって実行される操作

実行時間の長い操作は、操作を開始するためにサービスに送信された最初の要求で構成される操作です。その後、間隔を指定してサービスをポーリングし、操作が完了したか失敗したか、成功したかどうかを判断して結果を取得します。

ドキュメントの分析、モデルの構築、またはモデルのコピー/作成を行うメソッドは、実行時間の長い操作としてモデル化されます。 クライアントは、 または AsyncLROPollerをbegin_<method-name>返すメソッドをLROPoller公開します。 呼び出し元は、 メソッドから返された poller オブジェクトに対して を呼び出 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("----------------------------------------")

事前構築済みモデルの使用

ドキュメント インテリジェンス サービスによって提供される事前構築済みモデルを使用して、領収書、請求書、名刺、ID ドキュメント、米国 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("--------------------------------------")

レシートに限りません! 選択できる事前構築済みモデルがいくつかあります。各モデルには、サポートされているフィールドの独自のセットがあります。 サポートされているその他の事前構築済みモデル については、こちらを参照してください。

カスタム モデルを構築する

独自のドキュメントの種類でカスタム モデルを構築します。 結果のモデルを使用して、トレーニング対象のドキュメントの種類の値を分析できます。 トレーニング ドキュメントを格納している Azure Storage BLOB コンテナーにコンテナー SAS URL を指定します。

コンテナーの設定と必要なファイル構造の詳細については、サービスのドキュメントを 参照してください。

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

アドオン機能

ドキュメント インテリジェンスでは、より高度な分析機能がサポートされています。 これらのオプション機能は、ドキュメント抽出のシナリオに応じて有効または無効にすることができます。

2023-07-31 (GA) 以降のリリースでは、次のアドオン機能を使用できます。

• バーコード/QR コード
• 式
• font/style
• 高解像度モード
• language

一部のアドオン機能では追加料金が発生します。 「価格: https://azure.microsoft.com/pricing/details/ai-document-intelligence/」を参照してください。

トラブルシューティング

全般

ドキュメント インテリジェンス クライアント ライブラリでは、 Azure Core で定義されている例外が発生します。 ドキュメント インテリジェンス サービスによって発生するエラー コードとメッセージは、 サービスドキュメントにあります。

ログの記録

このライブラリでは、標準の ログ記録 ライブラリを使用してログを記録します。

HTTP セッション (URL、ヘッダーなど) に関する基本情報は、レベルで INFO ログに記録されます。

要求/応答本文や未作成のヘッダーなど、詳細なDEBUGレベルのログ記録は、クライアントで有効にすることも、キーワード (keyword)引数を使用してlogging_enable操作ごとに有効にすることもできます。

SDK のログ記録に関する完全なドキュメントと例 については、こちらを参照してください。

オプションの構成

省略可能なキーワード (keyword)引数は、クライアントレベルと操作ごとのレベルで渡すことができます。 azure-core リファレンス ドキュメント では、再試行、ログ記録、トランスポート プロトコルなどの使用可能な構成について説明しています。

次のステップ

その他のサンプル コード

ドキュメント インテリジェンス Python API で使用される一般的なパターンを示すいくつかのコード スニペットについては、 README のサンプル を参照してください。

その他のドキュメント

Azure AI ドキュメント インテリジェンスに関するより広範なドキュメントについては、docs.microsoft.com に関する ドキュメント インテリジェンスのドキュメント を参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳細については、「倫理規定の FAQ」をご覧ください。追加の質問やコメントがある場合は opencode@microsoft.com にお問い合わせください。