FormTrainingClient クラス

リファレンス

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

注意

FormTrainingClient は、API バージョン =v2.1 で使用する <必要があります。

API バージョン 2022-08-31 以降を使用するには、DocumentModelAdministrationClient をインスタンス化します。

継承: azure.ai.formrecognizer.aio._form_base_client_async.FormRecognizerClientBaseAsync

FormTrainingClient

コンストラクター

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

パラメーター

endpoint: str

必須

サポートされている Cognitive Services エンドポイント (プロトコルとホスト名など)。 https://westus2.api.cognitive.microsoft.com

credential: AzureKeyCredential または AsyncTokenCredential

必須

クライアントが 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.aio 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.aio import FormTrainingClient
   from azure.identity.aio 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 が構成されている場合にのみ受け入れられることに注意してください。マネージド ID の構成に関する詳細については、Form Recognizerhttps://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 に対する相対 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必要があります。

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

パラメーター

model_id: str

必須

ターゲットリソースにコピーするモデルのモデル識別子。

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

必須

ターゲットリソースのの呼び出し get_copy_authorizationから生成されたコピー承認。

continuation_token: str

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

戻り値

AsyncLROPoller のインスタンス。 poller オブジェクトで result() を呼び出して、を CustomFormModelInfo返します。

の戻り値の型 :

AsyncLROPoller[CustomFormModelInfo]

例外

HttpResponseError

例

ソースリソースからターゲットリソースにモデルをコピーする


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

   async with source_client:
       poller = await 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 = await 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 クライアントメソッド

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

パラメーター

model_ids: list[str]

必須

構成済みモデルで使用するモデル ID の一覧。

model_name: str

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

continuation_token: str

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

戻り値

AsyncLROPoller のインスタンス。 poller オブジェクトで result() を呼び出して、を CustomFormModel返します。

の戻り値の型 :

AsyncLROPoller[CustomFormModel]

例外

HttpResponseError

例

作成済みモデルを作成する


   from azure.core.credentials import AzureKeyCredential
   from azure.ai.formrecognizer.aio 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))
   async with form_training_client:
       supplies_poller = await form_training_client.begin_training(
           po_supplies, use_training_labels=True, model_name="Purchase order - Office supplies"
       )
       equipment_poller = await form_training_client.begin_training(
           po_equipment, use_training_labels=True, model_name="Purchase order - Office Equipment"
       )
       furniture_poller = await form_training_client.begin_training(
           po_furniture, use_training_labels=True, model_name="Purchase order - Furniture"
       )
       cleaning_supplies_poller = await form_training_client.begin_training(
           po_cleaning_supplies, use_training_labels=True, model_name="Purchase order - Cleaning Supplies"
       )
       supplies_model = await supplies_poller.result()
       equipment_model = await equipment_poller.result()
       furniture_model = await furniture_poller.result()
       cleaning_supplies_model = await 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 = await form_training_client.begin_create_composed_model(
           models_trained_with_labels, model_name="Office Supplies Composed Model"
       )
       model = await 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 が構成されている場合にのみ受け入れられることに注意してください。マネージド ID の構成に関する詳細については、Form Recognizerhttps://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) 引数

async begin_training(training_files_url: str, use_training_labels: bool, **kwargs: Any) -> AsyncLROPoller[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 ストレージ BLOB URI を使用する場合は、プレフィックスを使用してトレーニング用のサブフォルダーを制限します。

include_subfolders: bool

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

model_name: str

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

continuation_token: str

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

戻り値

AsyncLROPoller のインスタンス。 poller オブジェクトで result() を呼び出して、を CustomFormModel返します。

の戻り値の型 :

AsyncLROPoller[CustomFormModel]

例外

HttpResponseError

トレーニングが失敗した場合は例外が発生しますが、"無効" 状態のモデルは引き続き作成されることに注意してください。このモデルは、を呼び出して削除できます。

delete_model

例

カスタムフォームを使用してモデルをトレーニングする (ラベルなし)。


   from azure.ai.formrecognizer.aio 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"]

   async with FormTrainingClient(
       endpoint, AzureKeyCredential(key)
   ) as form_training_client:

       poller = await form_training_client.begin_training(container_sas_url, use_training_labels=False)
       model = await 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 閉じます。

async close() -> None

例外

HttpResponseError

delete_model

モデルを削除対象としてマークします。モデル成果物は、事前に定義された期間内に完全に削除されます。

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

パラメーター

model_id: str

必須

モデル識別子。

戻り値

なし

の戻り値の型 :

None

例外

HttpResponseError

ResourceNotFoundError

例

カスタムモデルを削除します。


   await form_training_client.delete_model(model_id=custom_model.model_id)

   try:
       await 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 アカウントのモデルに関する情報を取得します。

async get_account_properties(**kwargs: Any) -> AccountProperties

戻り値

アカウント上のモデルの概要 - カスタムモデル数、カスタムモデルの制限。

の戻り値の型 :

AccountProperties

例外

HttpResponseError

例

form recognizer アカウントのプロパティを取得します。


   async with FormTrainingClient(
       endpoint=endpoint, credential=AzureKeyCredential(key)
   ) as form_training_client:
       # First, we see how many custom models we have, and what our limit is
       account_properties = await 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渡すことができます。

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

   async with target_client:
       target = await 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

認識できるフォームの種類や、フォームの種類ごとに抽出されるフィールドなど、カスタムモデルの説明を取得します。

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

パラメーター

model_id: str

必須

モデル識別子。

戻り値

CustomFormModel

の戻り値の型 :

CustomFormModel

例外

HttpResponseError

ResourceNotFoundError

例

モデル ID を持つカスタムモデルを取得します。


   custom_model = await form_training_client.get_custom_model(model_id=model_info.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) -> AsyncItemPaged[CustomFormModelInfo]

例

アカウントの各モデルのモデル情報を一覧表示します。


   custom_models = form_training_client.list_custom_models()

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

send_request

クライアントの既存のパイプラインを使用してネットワーク要求を実行します。

要求 URL は、ベース URL に対する相対 URL にすることができます。要求に使用されるサービス API のバージョンは、特に指定がない限り、クライアントのと同じです。クライアントの構成済み API バージョンを相対 URL でオーバーライドすることは、API バージョン 2022-08-31 以降のクライアントでサポートされています。任意の API バージョンでクライアントでサポートされている絶対 URL でのオーバーライド。応答がエラーの場合、このメソッドは発生しません。例外を発生させる場合は、返された応答オブジェクトで raise_for_status() を呼び出します。このメソッドを使用してカスタム要求を送信する方法の詳細については、「」を参照してください https://aka.ms/azsdk/dpcodegen/python/send_request。

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

パラメーター

request: HttpRequest

必須

作成するネットワーク要求。

戻り値

ネットワーク呼び出しの応答。応答でエラー処理を行いません。

の戻り値の型 :

AsyncHttpResponse

例外

HttpResponseError

Share via

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

パラメーター

戻り値

の戻り値の型 :

例外

フィードバック

その他のリソース