FormTrainingClient クラス

リファレンス

FormTrainingClient は、カスタムモデルの作成と管理に使用するForm Recognizer インターフェイスです。指定したフォームでモデルをトレーニングするためのメソッドと、モデルの表示と削除、アカウントプロパティへのアクセス、別のForm Recognizer リソースへのモデルのコピー、ラベルでトレーニングされた既存のモデルのコレクションからのモデルの作成を行うメソッドを提供します。

注意

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 に接続するために必要な資格情報。 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	このリソース (ソース) に格納されているカスタムモデルを、ユーザー指定のターゲット Form Recognizer リソースにコピーします。これは、ソース Form Recognizer リソース (コピー対象のモデル) で呼び出す必要があります。ターゲットパラメーターは、メソッドの呼び出しからのターゲットリソースの出力から指定するget_copy_authorization必要があります。
begin_create_composed_model	ラベルを使用してトレーニングされた既存のモデルのコレクションから構成済みモデルを作成します。構成済みモデルを使用すると、1 つのモデル ID で複数のモデルを呼び出すことができます。作成済みのモデル ID を使用して分析するドキュメントが送信されると、分類ステップが最初に実行され、適切なカスタムモデルにルーティングされます。バージョン v2.1 の新機能: begin_create_composed_model クライアントメソッド
begin_training	カスタムモデルを作成してトレーニングします。要求には、外部からアクセス可能な Azure ストレージ BLOB コンテナー URI (できれば Shared Access Signature URI) である training_files_url パラメーターを含める必要があります。コンテナー URI (SAS なし) は、コンテナーがパブリックであるか、マネージド ID が構成されている場合にのみ受け入れられることに注意してください。Form Recognizerで動作するようにマネージド ID を構成する方法の詳細については、「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	Form Recognizer アカウントのモデルに関する情報を取得します。
get_copy_authorization	ターゲット Form Recognizer リソースにカスタムモデルをコピーするための承認を生成します。これはターゲットリソース (モデルのコピー先) によって呼び出され、出力はターゲットパラメーターとしてに begin_copy_model渡すことができます。
get_custom_model	認識できるフォームの種類や、フォームの種類ごとに抽出されるフィールドなど、カスタムモデルの説明を取得します。
get_form_recognizer_client	FormTrainingClient から FormRecognizerClient のインスタンスを取得します。
list_custom_models	モデル ID、モデルの状態、およびモデルが作成および最後に変更された日時など、各モデルの情報を一覧表示します。
send_request	クライアントの既存のパイプラインを使用してネットワーク要求を実行します。要求 URL は、ベース URL を基準にして指定できます。要求に使用されるサービス API のバージョンは、特に指定がない限り、クライアントと同じです。クライアントの構成済み API バージョンを相対 URL でオーバーライドすることは、API バージョン 2022-08-31 以降のクライアントでサポートされています。任意の API バージョンでクライアントでサポートされている絶対 URL でのオーバーライド。応答がエラーの場合、このメソッドは発生しません。例外を発生させる場合は、返された応答オブジェクトに対して raise_for_status() を呼び出します。このメソッドを使用してカスタム要求を送信する方法の詳細については、「」を参照してください https://aka.ms/azsdk/dpcodegen/python/send_request。

begin_copy_model

このリソース (ソース) に格納されているカスタムモデルを、ユーザー指定のターゲット Form Recognizer リソースにコピーします。これは、ソース Form Recognizer リソース (コピー対象のモデル) で呼び出す必要があります。 ターゲット パラメーターは、メソッドの呼び出しからのターゲットリソースの出力から指定する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 のインスタンス。 poller オブジェクトで 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

ラベルを使用してトレーニングされた既存のモデルのコレクションから構成済みモデルを作成します。

構成済みモデルを使用すると、1 つのモデル 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 のインスタンス。 poller オブジェクトで 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

カスタムモデルを作成してトレーニングします。要求には、外部からアクセス可能な Azure ストレージ BLOB コンテナー URI (できれば Shared Access Signature URI) である training_files_url パラメーターを含める必要があります。コンテナー URI (SAS なし) は、コンテナーがパブリックであるか、マネージド ID が構成されている場合にのみ受け入れられることに注意してください。Form Recognizerで動作するようにマネージド ID を構成する方法の詳細については、「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 Storage BLOB コンテナーの SAS URI。コンテナーがパブリックであるか、マネージド ID が構成されている場合は、コンテナー URI (SAS なし) を使用できます。トレーニングデータセットの設定の詳細については、「」を参照してください https://aka.ms/azsdk/formrecognizer/buildtrainingset。

use_training_labels: bool

必須

ラベルを使用してトレーニングするかどうか。 True に設定されている場合は、対応するラベル付きファイルが BLOB コンテナーに存在する必要があります。

prefix: str

トレーニング用のソースパス内のドキュメントをフィルター処理するための大文字と小文字を区別するプレフィックス文字列。たとえば、Azure Storage BLOB URI を使用する場合は、プレフィックスを使用してトレーニング用のサブフォルダーを制限します。

include_subfolders: bool

プリプロセスするコンテンツを検索するときに、プレフィックスフォルダーのセット内のサブフォルダーも含める必要があるかどうかを示すフラグ。ラベルを使用したトレーニングの場合はサポートされません。

model_name: str

モデルに関連付ける省略可能なユーザー定義名。

continuation_token: str

保存された状態からポーリングを再開するための継続トークン。

戻り値

LROPoller のインスタンス。 poller オブジェクトで 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

Form Recognizer アカウントのモデルに関する情報を取得します。

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

ターゲット Form Recognizer リソースにカスタムモデルをコピーするための承認を生成します。これはターゲットリソース (モデルのコピー先) によって呼び出され、出力は ターゲット パラメーターとしてに begin_copy_model渡すことができます。

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

パラメーター

resource_id: str

必須

モデルのコピー先となるターゲット Form Recognizer リソースの Azure リソース ID。

resource_region: str

必須

ターゲット Form Recognizer リソースの場所。 Cognitive Services でサポートされている有効な Azure リージョン名。たとえば、'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

例

モデル 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 バージョンを相対 URL でオーバーライドすることは、API バージョン 2022-08-31 以降のクライアントでサポートされています。任意の 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

パラメーター

戻り値

の戻り値の型 :

例外

その他のリソース