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

FormTrainingClient 类

参考

FormTrainingClient 是用于创建和管理自定义模型的表单识别器接口。它提供在提供的表单上训练模型的方法，以及用于查看和删除模型、访问帐户属性、将模型复制到另一个表单识别器资源以及从使用标签训练的现有模型集合中组合模型的方法。

注意

FormTrainingClient 应与 API 版本 <=v2.1 一起使用。

若要使用 API 版本 2022-08-31 及更新版本，请实例化 DocumentModelAdministrationClient。

继承: azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase

FormTrainingClient

构造函数

FormTrainingClient(endpoint: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)

参数

endpoint: str

必需

支持的认知服务终结点 (协议和主机名，例如： https://westus2.api.cognitive.microsoft.com) 。

credential: AzureKeyCredential 或 TokenCredential

必需

客户端连接到 Azure 所需的凭据。如果使用 API 密钥或中的 identity令牌凭据，则这是 AzureKeyCredential 的实例。

api_version: str 或 FormRecognizerApiVersion

要用于请求的服务的 API 版本。它默认为 API 版本 v2.1。设置为较旧版本可能会导致功能兼容性降低。若要使用支持的最新 API 版本和功能，请改为实例化 DocumentModelAdministrationClient。

示例

使用终结点和 API 密钥创建 FormTrainingClient。


   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import FormTrainingClient
   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

   form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))

使用令牌凭据创建 FormTrainingClient。


   """DefaultAzureCredential will use the values from these environment
   variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
   """
   from azure.ai.formrecognizer import FormTrainingClient
   from azure.identity import DefaultAzureCredential

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   credential = DefaultAzureCredential()

   form_training_client = FormTrainingClient(endpoint, credential)

方法

begin_copy_model	将源) (存储在此资源中的自定义模型复制到用户指定的目标表单识别器资源。应将源表单识别器资源 (调用，该模型旨在) 复制。目标参数应通过调用 get_copy_authorization 方法从目标资源的输出中提供。
begin_create_composed_model	从使用标签训练的现有模型集合创建组合模型。组合模型允许使用单个模型 ID 调用多个模型。提交要使用组合模型 ID 分析的文档时，首先会执行分类步骤以将其路由到正确的自定义模型。 v2.1 版中的新增功能： begin_create_composed_model 客户端方法
begin_training	创建和训练自定义模型。请求必须包含一个 training_files_url 参数，该参数是外部可访问的 Azure 存储 Blob 容器 URI， (最好是共享访问签名 URI) 。请注意，仅当容器为公共或配置了托管标识时，才接受没有 SAS) 的容器 (URI，请参阅此处有关配置托管标识以使用表单识别器的详细信息：https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities。模型使用以下内容类型的文档（“application/pdf”、“image/jpeg”、“image/png”、“image/tiff”或“image/bmp”）进行训练。将忽略容器中其他类型的内容。 v2.1 版中的新增功能：model_name 关键字 (keyword) 参数
close	FormTrainingClient关闭会话。
delete_model	标记要删除的模型。模型项目将在预先确定的时间段内永久删除。
get_account_properties	获取有关表单识别器帐户上的模型的信息。
get_copy_authorization	生成用于将自定义模型复制到目标表单识别器资源的授权。这应由目标资源 (调用，其中模型将复制到) ，输出可以作为目标参数传递到 begin_copy_model。
get_custom_model	获取自定义模型的说明，包括它可以识别的表单类型，以及它将为每个表单类型提取的字段。
get_form_recognizer_client	从 FormTrainingClient 获取 FormRecognizerClient 的实例。
list_custom_models	列出每个模型的信息，包括模型 ID、模型状态以及创建和上次修改时间。
send_request	使用客户端的现有管道运行网络请求。请求 URL 可以相对于基 URL。除非另行指定，否则用于请求的服务 API 版本与客户端的版本相同。 API 版本 2022-08-31 及更高版本的客户端支持在相对 URL 中替代客户端配置的 API 版本。使用任何 API 版本在客户端上支持的绝对 URL 中重写。如果响应是错误，则此方法不会引发;若要引发异常，请对返回的响应对象调用 raise_for_status () 。有关如何使用此方法发送自定义请求的详细信息，请参阅 https://aka.ms/azsdk/dpcodegen/python/send_request。

begin_copy_model

将源) (存储在此资源中的自定义模型复制到用户指定的目标表单识别器资源。应将源表单识别器资源 (调用，该模型旨在) 复制。 目标参数应通过调用 get_copy_authorization 方法从目标资源的输出中提供。

begin_copy_model(model_id: str, target: Dict[str, str | int], **kwargs: Any) -> LROPoller[CustomFormModelInfo]

参数

model_id: str

必需

要复制到目标资源的模型的模型标识符。

target: Dict[str, Union[str, int]]

必需

从目标资源的调用 get_copy_authorization生成的复制授权。

continuation_token: str

用于从保存状态重启轮询的延续标记。

LROPoller 的实例。在轮询器对象上调用 result () 以返回 CustomFormModelInfo。

返回类型

LROPoller[CustomFormModelInfo]

例外

HttpResponseError

示例

将模型从源资源复制到目标资源


   source_client = FormTrainingClient(endpoint=source_endpoint, credential=AzureKeyCredential(source_key))

   poller = source_client.begin_copy_model(
       model_id=source_model_id,
       target=target  # output from target client's call to get_copy_authorization()
   )
   copied_over_model = poller.result()

   print("Model ID: {}".format(copied_over_model.model_id))
   print("Status: {}".format(copied_over_model.status))

begin_create_composed_model

从使用标签训练的现有模型集合创建组合模型。

组合模型允许使用单个模型 ID 调用多个模型。提交要使用组合模型 ID 分析的文档时，首先会执行分类步骤以将其路由到正确的自定义模型。

v2.1 版中的新增功能： begin_create_composed_model 客户端方法

begin_create_composed_model(model_ids: List[str], **kwargs: Any) -> LROPoller[CustomFormModel]

参数

model_ids: list[str]

必需

在组合模型中使用的模型 ID 列表。

model_name: str

要与模型关联的可选用户定义名称。

continuation_token: str

用于从保存状态重启轮询的延续标记。

LROPoller 的实例。在轮询器对象上调用 result () 以返回 CustomFormModel。

返回类型

LROPoller[CustomFormModel]

例外

HttpResponseError

示例

创建组合模型


   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer import FormTrainingClient

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   po_supplies = os.environ['PURCHASE_ORDER_OFFICE_SUPPLIES_SAS_URL_V2']
   po_equipment = os.environ['PURCHASE_ORDER_OFFICE_EQUIPMENT_SAS_URL_V2']
   po_furniture = os.environ['PURCHASE_ORDER_OFFICE_FURNITURE_SAS_URL_V2']
   po_cleaning_supplies = os.environ['PURCHASE_ORDER_OFFICE_CLEANING_SUPPLIES_SAS_URL_V2']

   form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   supplies_poller = form_training_client.begin_training(
       po_supplies, use_training_labels=True, model_name="Purchase order - Office supplies"
   )
   equipment_poller = form_training_client.begin_training(
       po_equipment, use_training_labels=True, model_name="Purchase order - Office Equipment"
   )
   furniture_poller = form_training_client.begin_training(
       po_furniture, use_training_labels=True, model_name="Purchase order - Furniture"
   )
   cleaning_supplies_poller = form_training_client.begin_training(
       po_cleaning_supplies, use_training_labels=True, model_name="Purchase order - Cleaning Supplies"
   )
   supplies_model = supplies_poller.result()
   equipment_model = equipment_poller.result()
   furniture_model = furniture_poller.result()
   cleaning_supplies_model = cleaning_supplies_poller.result()

   models_trained_with_labels = [
       supplies_model.model_id,
       equipment_model.model_id,
       furniture_model.model_id,
       cleaning_supplies_model.model_id
   ]

   poller = form_training_client.begin_create_composed_model(
       models_trained_with_labels, model_name="Office Supplies Composed Model"
   )
   model = poller.result()

   print("Office Supplies Composed Model Info:")
   print("Model ID: {}".format(model.model_id))
   print("Model name: {}".format(model.model_name))
   print("Is this a composed model?: {}".format(model.properties.is_composed_model))
   print("Status: {}".format(model.status))
   print("Composed model creation started on: {}".format(model.training_started_on))
   print("Creation completed on: {}".format(model.training_completed_on))

begin_training

创建和训练自定义模型。请求必须包含一个 training_files_url 参数，该参数是外部可访问的 Azure 存储 Blob 容器 URI， (最好是共享访问签名 URI) 。请注意，仅当容器为公共或配置了托管标识时，才接受没有 SAS) 的容器 (URI，请参阅此处有关配置托管标识以使用表单识别器的详细信息：https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities。模型使用以下内容类型的文档（“application/pdf”、“image/jpeg”、“image/png”、“image/tiff”或“image/bmp”）进行训练。将忽略容器中其他类型的内容。

v2.1 版中的新增功能：model_name 关键字 (keyword) 参数

begin_training(training_files_url: str, use_training_labels: bool, **kwargs: Any) -> LROPoller[CustomFormModel]

参数

training_files_url: str

必需

Azure 存储 Blob 容器的 SAS URI。如果容器 (是公共的，或者配置了托管标识，则可以使用没有 SAS) 的容器 URI。有关设置训练数据集的详细信息，请参阅： https://aka.ms/azsdk/formrecognizer/buildtrainingset。

use_training_labels: bool

必需

是否使用标签进行训练。如果设置为 True，则 Blob 容器中必须存在相应的标记文件。

prefix: str

一个区分大小写的前缀字符串，用于筛选用于训练的源路径中的文档。例如，使用 Azure 存储 Blob URI 时，请使用前缀来限制子文件夹进行训练。

include_subfolders: bool

一个标志，指示在搜索要预处理的内容时，还需要包含前缀文件夹集中的子文件夹。如果使用标签进行训练，则不支持。

model_name: str

要与模型关联的可选用户定义名称。

continuation_token: str

用于从保存状态重启轮询的延续标记。

LROPoller 的实例。在轮询器对象上调用 result () 以返回 CustomFormModel。

返回类型

LROPoller[CustomFormModel]

例外

HttpResponseError

请注意，如果训练失败，则会引发异常，但仍会创建状态为“无效”的模型。可以通过调用来删除此模型

delete_model

示例

使用自定义窗体训练 (没有标签) 模型。


   from azure.ai.formrecognizer import FormTrainingClient
   from azure.core.credentials import AzureKeyCredential

   endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
   key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]
   container_sas_url = os.environ["CONTAINER_SAS_URL_V2"]

   form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))
   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("Model name: {}".format(model.model_name))
   print("Training started on: {}".format(model.training_started_on))
   print("Training completed on: {}".format(model.training_completed_on))

   print("Recognized fields:")
   # Looping through the submodels, which contains the fields they were trained on
   for submodel in model.submodels:
       print("...The submodel has form type '{}'".format(submodel.form_type))
       for name, field in submodel.fields.items():
           print("...The model found field '{}' to have label '{}'".format(
               name, field.label
           ))

close

FormTrainingClient关闭会话。

close() -> None

例外

HttpResponseError

delete_model

标记要删除的模型。模型项目将在预先确定的时间段内永久删除。

delete_model(model_id: str, **kwargs: Any) -> None

参数

model_id: str

必需

模型标识符。

返回类型

None

例外

HttpResponseError

ResourceNotFoundError

示例

删除自定义模型。


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

get_account_properties

获取有关表单识别器帐户上的模型的信息。

get_account_properties(**kwargs: Any) -> AccountProperties

帐户上的模型摘要 - 自定义模型计数、自定义模型限制。

返回类型

AccountProperties

例外

HttpResponseError

示例

获取表单识别器帐户的属性。


   form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key))
   # First, we see how many custom models we have, and what our limit is
   account_properties = form_training_client.get_account_properties()
   print("Our account has {} custom models, and we can have at most {} custom models\n".format(
       account_properties.custom_model_count, account_properties.custom_model_limit
   ))

get_copy_authorization

生成用于将自定义模型复制到目标表单识别器资源的授权。这应由目标资源 (调用，其中模型将复制到) ，输出可以作为目标参数传递到 begin_copy_model。

get_copy_authorization(resource_id: str, resource_region: str, **kwargs: Any) -> Dict[str, str | int]

参数

resource_id: str

必需

目标表单识别器将模型复制到的资源的 Azure 资源 ID。

resource_region: str

必需

目标表单识别器资源的位置。认知服务支持的有效 Azure 区域名称。例如，“westus”、“eastus”等。有关认知服务的区域可用性，请参阅 https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services 。

包含复制授权值的字典 -“modelId”、“accessToken”、“resourceId”、“resourceRegion”和“expirationDateTimeTicks”。

返回类型

Dict[str, Union[str, int]]

例外

HttpResponseError

示例

授权目标资源接收复制的模型


   target_client = FormTrainingClient(endpoint=target_endpoint, credential=AzureKeyCredential(target_key))

   target = target_client.get_copy_authorization(
       resource_region=target_region,
       resource_id=target_resource_id
   )
   # model ID that target client will use to access the model once copy is complete
   print("Model ID: {}".format(target["modelId"]))

get_custom_model

获取自定义模型的说明，包括它可以识别的表单类型，以及它将为每个表单类型提取的字段。

get_custom_model(model_id: str, **kwargs: Any) -> CustomFormModel

参数

model_id: str

必需

模型标识符。

CustomFormModel

返回类型

CustomFormModel

例外

HttpResponseError

ResourceNotFoundError

示例

获取具有模型 ID 的自定义模型。


   custom_model = form_training_client.get_custom_model(model_id=model.model_id)
   print("\nModel ID: {}".format(custom_model.model_id))
   print("Status: {}".format(custom_model.status))
   print("Model name: {}".format(custom_model.model_name))
   print("Is this a composed model?: {}".format(custom_model.properties.is_composed_model))
   print("Training started on: {}".format(custom_model.training_started_on))
   print("Training completed on: {}".format(custom_model.training_completed_on))

get_form_recognizer_client

从 FormTrainingClient 获取 FormRecognizerClient 的实例。

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

A FormRecognizerClient

返回类型

FormRecognizerClient

例外

HttpResponseError

list_custom_models

列出每个模型的信息，包括模型 ID、模型状态以及创建和上次修改时间。

list_custom_models(**kwargs: Any) -> ItemPaged[CustomFormModelInfo]

ItemPaged[CustomFormModelInfo]

返回类型

ItemPaged

例外

HttpResponseError

示例

列出帐户上每个模型的模型信息。


   custom_models = form_training_client.list_custom_models()

   print("We have models with the following IDs:")
   for model_info in custom_models:
       print(model_info.model_id)

send_request

使用客户端的现有管道运行网络请求。

请求 URL 可以相对于基 URL。除非另行指定，否则用于请求的服务 API 版本与客户端的版本相同。 API 版本 2022-08-31 及更高版本的客户端支持在相对 URL 中替代客户端配置的 API 版本。使用任何 API 版本在客户端上支持的绝对 URL 中重写。如果响应是错误，则此方法不会引发;若要引发异常，请对返回的响应对象调用 raise_for_status () 。有关如何使用此方法发送自定义请求的详细信息，请参阅 https://aka.ms/azsdk/dpcodegen/python/send_request。

send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> HttpResponse

参数

request: HttpRequest

必需

要发出网络请求。

stream: bool

是否对响应有效负载进行流式处理。默认为 False。

网络呼叫的响应。不对响应执行错误处理。

返回类型

HttpResponse

例外

HttpResponseError

通过

FormTrainingClient 类

构造函数

参数

示例

方法

begin_copy_model

参数

返回

返回类型

例外

示例

begin_create_composed_model

参数

返回

返回类型

例外

示例

begin_training

参数

返回

返回类型

例外

示例

close

例外

delete_model

参数

返回类型

例外

示例

get_account_properties

返回

返回类型

例外

示例

get_copy_authorization

参数

返回

返回类型

例外

示例

get_custom_model

参数

返回

返回类型

例外

示例

get_form_recognizer_client

返回

返回类型

例外

list_custom_models

返回

返回类型

例外

示例

send_request

参数

返回

返回类型

例外

其他资源