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

Обязательно

Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например). https://westus2.api.cognitive.microsoft.com

credential

AzureKeyCredential или TokenCredential

Обязательно

Учетные данные, необходимые клиенту для подключения к Azure. Это экземпляр AzureKeyCredential, если используется ключ API или учетные данные маркера из identity.

api_version

str или FormRecognizerApiVersion

Версия API службы, используемая для запросов. По умолчанию используется API версии 2.1. Установка более старой версии может привести к снижению совместимости функций. Чтобы использовать последнюю поддерживаемую версию и функции API, создайте экземпляр DocumentModelAdministrationClient.

Примеры

Создание FormTrainingClient с конечной точкой и ключом API.

   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	Создает составную модель из коллекции существующих моделей, которые были обучены с помощью меток. Составная модель позволяет вызывать несколько моделей с одним идентификатором модели. При отправке документа для анализа с помощью идентификатора созданной модели сначала выполняется классификация, которая направляется в нужную пользовательскую модель. Новые возможности в версии 2.1: метод клиента begin_create_composed_model
begin_training	Создание и обучение пользовательской модели. Запрос должен включать параметр training_files_url , который является доступным извне URI контейнера BLOB-объектов службы хранилища Azure (предпочтительно URI подписанного URL-адреса). Обратите внимание, что URI контейнера (без SAS) принимается только в том случае, если контейнер является общедоступным или для него настроено управляемое удостоверение. Дополнительные сведения о настройке управляемых удостоверений для работы с Распознаватель документов см. здесь: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Модели обучаются с использованием документов, которые относятся к следующему типу контента: "application/pdf", "image/jpeg", "image/png", "image/tiff" или "image/bmp". Другие типы содержимого в контейнере игнорируются. Новые возможности в версии 2.1: аргумент model_name ключевое слово
close	FormTrainingClient Закройте сеанс.
delete_model	Пометка модели для удаления. Артефакты модели будут окончательно удалены в течение заданного периода.
get_account_properties	Получение сведений о моделях в учетной записи распознавателя документов.
get_copy_authorization	Создайте авторизацию для копирования пользовательской модели в целевой ресурс Распознаватель документов. Он должен вызываться целевым ресурсом (куда будет копироваться модель), а выходные данные могут передаваться в качестве целевого параметра в begin_copy_model.
get_custom_model	Получите описание пользовательской модели, включая типы форм, которые она может распознать, и поля, которые она извлекает для каждого типа формы.
get_form_recognizer_client	Получение экземпляра FormRecognizerClient из FormTrainingClient.
list_custom_models	Список сведений для каждой модели, включая идентификатор модели, ее состояние, а также время ее создания и последнего изменения.
send_request	Выполняет сетевой запрос, используя существующий конвейер клиента. URL-адрес запроса может быть относительно базового URL-адреса. Версия API службы, используемая для запроса, совпадает с версией клиента, если не указано иное. Переопределение настроенной версии API клиента в относительном URL-адресе поддерживается на клиенте с API версии 2022-08-31 и более поздних версий. Переопределение в абсолютном URL-адресе, поддерживаемом на клиенте с любой версией API. Этот метод не вызывает, если ответ является ошибкой; чтобы вызвать исключение, вызовите 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

Создает составную модель из коллекции существующих моделей, которые были обучены с помощью меток.

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

Новые возможности в версии 2.1: метод клиента begin_create_composed_model

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

Параметры

model_ids

list[str]

Обязательно

Список идентификаторов моделей, используемых в составной модели.

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 , который является доступным извне URI контейнера BLOB-объектов службы хранилища Azure (предпочтительно URI подписанного URL-адреса). Обратите внимание, что URI контейнера (без SAS) принимается только в том случае, если контейнер является общедоступным или для него настроено управляемое удостоверение. Дополнительные сведения о настройке управляемых удостоверений для работы с Распознаватель документов см. здесь: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. Модели обучаются с использованием документов, которые относятся к следующему типу контента: "application/pdf", "image/jpeg", "image/png", "image/tiff" или "image/bmp". Другие типы содержимого в контейнере игнорируются.

Новые возможности в версии 2.1: аргумент model_name ключевое слово

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

Параметры

training_files_url

str

Обязательно

URI SAS контейнера BLOB-объектов службы хранилища Azure. URI контейнера (без SAS) можно использовать, если контейнер является общедоступным или имеет настроенное управляемое удостоверение. Дополнительные сведения о настройке набора данных для обучения см. в разделе https://aka.ms/azsdk/formrecognizer/buildtrainingset.

use_training_labels

bool

Обязательно

Следует ли обучаться с метками или нет. Соответствующие помеченные файлы должны существовать в контейнере BLOB-объектов, если задано значение True.

prefix

str

Строка префикса с учетом регистра для фильтрации документов в исходном пути для обучения. Например, при использовании URI большого двоичного объекта службы хранилища Azure используйте префикс, чтобы ограничить вложенные папки для обучения.

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 целевого Распознаватель документов ресурса, в который будет скопирована модель.

resource_region

str

Обязательно

Расположение целевого ресурса Распознаватель документов. Допустимое имя региона Azure, поддерживаемое Cognitive Services. Например, "westus", "eastus" и т. д. Сведения о доступности Cognitive Services в регионах см 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

Примеры

Получение пользовательской модели с идентификатором модели.

   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

Получение экземпляра FormRecognizerClient из FormTrainingClient.

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

Возвращаемое значение

A FormRecognizerClient

Возвращаемый тип

FormRecognizerClient

Исключения

HttpResponseError

list_custom_models

Список сведений для каждой модели, включая идентификатор модели, ее состояние, а также время ее создания и последнего изменения.

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 клиента в относительном URL-адресе поддерживается на клиенте с API версии 2022-08-31 и более поздних версий. Переопределение в абсолютном URL-адресе, поддерживаемом на клиенте с любой версией API. Этот метод не вызывает, если ответ является ошибкой; чтобы вызвать исключение, вызовите 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