FormTrainingClient 클래스
FormTrainingClient는 사용자 지정 모델을 만들고 관리하는 데 사용할 Form Recognizer 인터페이스입니다. 제공하는 양식에서 모델을 학습시키는 방법뿐만 아니라 모델을 보고 삭제하고, 계정 속성에 액세스하고, 모델을 다른 Form Recognizer 리소스로 복사하고, 레이블로 학습된 기존 모델 컬렉션에서 모델을 구성하는 방법을 제공합니다.
참고
FormTrainingClient는 API 버전 <=v2.1과 함께 사용해야 합니다.
API 버전 2022-08-31을 사용하려면 DocumentModelAdministrationClient를 인스턴스화합니다.
- 상속
-
azure.ai.formrecognizer._form_base_client.FormRecognizerClientBaseFormTrainingClient
생성자
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]
매개 변수
- continuation_token
- str
저장된 상태에서 폴러를 다시 시작하는 연속 토큰입니다.
반환
LROPoller의 instance. 폴러 개체에서 result() 를 호출하여 를 반환합니다 CustomFormModelInfo.
반환 형식
예외
예제
원본 리소스에서 대상 리소스로 모델 복사
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_name
- str
모델과 연결할 선택적 사용자 정의 이름입니다.
- continuation_token
- str
저장된 상태에서 폴러를 다시 시작하는 연속 토큰입니다.
반환
LROPoller의 instance. 폴러 개체에서 result() 를 호출하여 를 반환합니다 CustomFormModel.
반환 형식
예외
예제
구성형 모델 만들기
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.
반환 형식
예외
학습이 실패하면 예외가 발생하지만 "잘못된" 상태 있는 모델은 계속 만들어집니다. 를 호출하여 이 모델을 삭제할 수 있습니다.
예제
사용자 지정 양식을 사용하여 모델 학습(레이블 없음)
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
delete_model
삭제할 모델을 표시합니다. 모델 아티팩트는 미리 결정된 기간 내에 영구적으로 제거됩니다.
delete_model(model_id: str, **kwargs: Any) -> None
매개 변수
반환 형식
예외
예제
사용자 지정 모델을 삭제합니다.
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
반환
계정의 모델 요약 - 사용자 지정 모델 수, 사용자 지정 모델 제한.
반환 형식
예외
예제
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_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".
반환 형식
예외
예제
복사된 모델을 받을 대상 리소스에 권한을 부여합니다.
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
매개 변수
반환
CustomFormModel
반환 형식
예외
예제
모델 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
반환 형식
예외
list_custom_models
모델 ID, 모델 상태, 모델을 만들고 마지막으로 수정한 시기를 포함하여 각 모델에 대한 정보를 나열합니다.
list_custom_models(**kwargs: Any) -> ItemPaged[CustomFormModelInfo]
반환
ItemPaged[CustomFormModelInfo]
반환 형식
예외
예제
계정의 각 모델에 대한 모델 정보를 나열합니다.
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
매개 변수
- stream
- bool
응답 페이로드가 스트리밍될지 여부입니다. 기본값은 False입니다.
반환
네트워크 호출의 응답입니다. 응답에 대한 오류 처리는 수행하지 않습니다.
반환 형식
예외
Azure SDK for Python