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의 instance.

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	레이블을 사용하여 학습된 기존 모델 컬렉션에서 구성된 모델을 만듭니다. 구성된 모델을 사용하면 단일 모델 ID로 여러 모델을 호출할 수 있습니다. 작성된 모델 ID로 분석하기 위해 문서를 제출하면 먼저 분류 단계를 수행하여 올바른 사용자 지정 모델로 라우팅합니다. 버전 v2.1의 새로운 기능: begin_create_composed_model 클라이언트 메서드
begin_training	사용자 지정 모델을 만들고 학습합니다. 요청에는 외부에서 액세스할 수 있는 Azure Storage Blob 컨테이너 URI(가급적 공유 액세스 서명 URI)인 training_files_url 매개 변수가 포함되어야 합니다. 컨테이너가 공용이거나 관리 ID가 구성된 경우에만 SAS가 없는 컨테이너 URI가 허용됩니다. 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의 instance 가져옵니다.
list_custom_models	모델 ID, 모델 상태, 모델을 만들고 마지막으로 수정한 시기를 포함하여 각 모델에 대한 정보를 나열합니다.
send_request	클라이언트의 기존 파이프라인을 사용하여 네트워크 요청을 실행합니다. 요청 URL은 기본 URL을 기준으로 할 수 있습니다. 요청에 사용되는 서비스 API 버전은 달리 지정하지 않는 한 클라이언트의 버전과 동일합니다. 상대 URL에서 클라이언트의 구성된 API 버전을 재정의하는 것은 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의 instance. 폴러 개체에서 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의 instance. 폴러 개체에서 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 Storage Blob 컨테이너 URI(가급적 공유 액세스 서명 URI)인 training_files_url 매개 변수가 포함되어야 합니다. 컨테이너가 공용이거나 관리 ID가 구성된 경우에만 SAS가 없는 컨테이너 URI가 허용됩니다. 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가 구성된 경우 SAS 없이 컨테이너 URI를 사용할 수 있습니다. 학습 데이터 집합 설정에 대한 자세한 내용은 을 참조하세요 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의 instance. 폴러 개체에서 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 Recognizer 계정에 대한 속성을 가져옵니다.

   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의 instance 가져옵니다.

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 버전은 달리 지정하지 않는 한 클라이언트의 버전과 동일합니다. 상대 URL에서 클라이언트의 구성된 API 버전을 재정의하는 것은 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