你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure 表单识别器客户端库 - 版本 3.0.0

Azure 认知服务表单识别器是一项云服务，它使用机器学习来识别表单文档中的文本和表数据。 它包括以下主要功能：

• 自定义模型 - 识别表单中的字段值和表数据。 这些模型都是用你自己的数据训练的，因此是针对你的表单量身定制的。
• 内容 API - 从文档中识别文本和表结构及其边界框坐标。 对应于 REST 服务的布局 API。
• 预生成收据模型 - 使用预生成模型识别来自美国销售收据的数据。

源代码 | 包 (PyPI) | API 参考文档| 产品文档 | 样品

入门

先决条件

• 使用此包需要 Python 2.7 或 3.5 或更高版本。
• 必须具有 Azure 订阅和认知服务或表单识别器资源才能使用此包。

安装包

使用 pip 安装适用于 Python 的 Azure 表单识别器客户端库 - 版本 3.0.0：

pip install azure-ai-formrecognizer

注意：此版本的客户端库支持 v2.0 版本的 表单识别器 服务

创建表单识别器资源

表单识别器支持多服务和单服务访问。 如果计划通过一个终结点/密钥访问多个认知服务，请创建认知服务资源。 若要仅访问表单识别器，请创建表单识别器资源。

可以使用 创建资源

选项 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 门户中或通过运行以下 Azure CLI 命令找到 API 密钥：

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 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量： 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))

训练模型

根据自己的窗体类型训练自定义模型。 生成的模型可用于识别其训练所基于的形式类型中的值。 提供用于存储训练文档的 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-core 参考文档 介绍了重试、日志记录、传输协议等的可用配置。

后续步骤

以下部分提供了几个代码片段，说明了 表单识别器 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 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。