適用于 Python 的 Azure 表格辨識器 用戶端程式庫 - 3.0.0 版

Azure 認知服務表格辨識器是一項雲端服務，會使用機器學習來辨識表單檔中的文字和資料表資料。 它包含下列主要功能：

• 自訂模型 - 辨識表單中的域值和資料表資料。 這些模型會使用您自己的資料進行定型，因此會針對您的表單量身打造。
• 內容 API - 從檔辨識文字和資料表結構及其周框方塊座標。 對應至 REST 服務的版面配置 API。
• 預建收據模型 - 使用預先建置模型辨識來自美國銷售收據的資料。

| 原始程式碼套件 (PyPI) | API 參考檔| 產品檔 | 樣品

開始使用

Prerequisites

• 需要 Python 2.7 或 3.5 或更新版本才能使用此套件。
• 您必須擁有Azure 訂用帳戶和認知服務或表格辨識器資源，才能使用此套件。

安裝套件

使用pip安裝適用于 Python 的 Azure 表格辨識器 用戶端程式庫 - 3.0.0 版：

pip install azure-ai-formrecognizer

注意：此版本的用戶端程式庫支援 表格辨識器 服務的 v2.0 版本

建立表格辨識器資源

表格辨識器支援多重服務和單一服務存取。 如果您打算在單一端點/金鑰下存取多個認知服務，請建立認知服務資源。 僅針對 Azure 表格辨識器的存取，請建立 Azure 表格辨識器資源。

您可以使用 建立資源

選項 1：Azure 入口網站

選項 2：Azure CLI。 以下是如何使用 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 入口網站或 AzureCLI找到表格辨識器資源的端點：

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

取得 API 金鑰

您可以在 Azure 入口網站中找到 API 金鑰，或執行下列 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-identity 程式庫向 Azure Active Directory 進行驗證。 請注意，區域端點不支援 AAD 驗證。 為您的資源建立 自訂子域 名稱，以使用此類型的驗證。

若要使用如下所示的 DefaultAzureCredential 類型，或 Azure SDK 提供的其他認證類型，請安裝 azure-identity 套件：

pip install azure-identity

您也需要註冊新的 AAD 應用程式，並將角色指派 "Cognitive Services User" 給服務主體，以授與表格辨識器的存取權。

完成後，請將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： AZURE_CLIENT_ID 、、 AZURE_TENANT_IDAZURE_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))

將模型定型

在您自己的表單類型上定型自訂模型。 產生的模型可用來辨識所定型之表單類型的值。 提供您用來儲存訓練檔的 Azure 儲存體 Blob 容器的容器 SAS URL。 如果定型檔案位於容器的子資料夾中，請使用 prefix 關鍵字引數來指定要定型的資料夾。

如需有關設定容器和必要檔案結構的詳細資訊，請參閱 服務檔。

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 關鍵字引數的用戶端啟用詳細的「偵錯」層級記錄，包括要求/回應本文和未刪改的標頭：

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 核心 參考檔 說明重試、記錄、傳輸通訊協定等可用的組態。

下一步

下一節提供數個程式碼片段，說明 表格辨識器 Python API 中使用的常見模式。

更多的程式碼範例

這些程式碼範例示範 Azure 表格辨識器 用戶端程式庫的常見案例作業。

• 用戶端驗證： sample_authentication.py
• 辨識收據： sample_recognize_receipts.py
• 辨識來自 URL 的收據： sample_recognize_receipts_from_url.py
• 辨識內容： sample_recognize_content.py
• 辨識自訂表單： sample_recognize_custom_forms.py
• 在沒有標籤的情況下定型模型： sample_train_model_without_labels.py
• 使用標籤定型模型： sample_train_model_with_labels.py
• 管理自訂模型： sample_manage_custom_models.py
• 在表格辨識器資源之間複製模型：sample_copy_model.py

非同步 API

此程式庫也包含 Python 3.5+ 上支援的完整非同步 API。 若要使用它，您必須先安裝非同步傳輸，例如 aioHTTP。 非同步用戶端位於 命名空間底下 azure.ai.formrecognizer.aio 。

• 用戶端驗證： sample_authentication_async.py
• 辨識收據： sample_recognize_receipts_async.py
• 辨識來自 URL 的收據： sample_recognize_receipts_from_url_async.py
• 辨識內容： sample_recognize_content_async.py
• 辨識自訂表單： sample_recognize_custom_forms_async.py
• 在沒有標籤的情況下定型模型： sample_train_model_without_labels_async.py
• 使用標籤定型模型： sample_train_model_with_labels_async.py
• 管理自訂模型： sample_manage_custom_models_async.py
• 在表格辨識器資源之間複製模型：sample_copy_model_async.py

其他文件

如需 Azure 認知服務表格辨識器的詳細資訊檔，請參閱docs.microsoft.com 表格辨識器檔。

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資訊，請造訪 cla.microsoft.com。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。