FormTrainingClient Classe

FormTrainingClient è l'interfaccia Riconoscimento modulo da usare per la creazione e la gestione di modelli personalizzati. Fornisce metodi per il training dei modelli nei moduli forniti, nonché metodi per la visualizzazione e l'eliminazione di modelli, l'accesso alle proprietà dell'account, la copia di modelli in un'altra risorsa Riconoscimento modulo e la composizione di modelli da una raccolta di modelli esistenti sottoposti a training con etichette.

Nota

FormTrainingClient deve essere usato con le versioni <dell'API =v2.1.

Per usare le versioni API 2022-08-31 e successive, creare un'istanza di DocumentModelAdministrationClient.

Ereditarietà

azure.ai.formrecognizer._form_base_client.FormRecognizerClientBase

FormTrainingClient

Costruttore

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

Parametri

endpoint

str

Necessario

Endpoint di Servizi cognitivi supportati (protocollo e nome host, ad esempio: https://westus2.api.cognitive.microsoft.com).

credential

AzureKeyCredential oppure TokenCredential

Necessario

Credenziali necessarie per la connessione del client ad Azure. Si tratta di un'istanza di AzureKeyCredential se si usa una chiave API o una credenziale token da identity.

api_version

str oppure FormRecognizerApiVersion

Versione API del servizio da usare per le richieste. Per impostazione predefinita, l'API versione 2.1 è predefinita. L'impostazione su una versione precedente può comportare una riduzione della compatibilità delle funzionalità. Per usare la versione e le funzionalità dell'API supportate più recenti, creare un'istanza di DocumentModelAdministrationClient.

Esempio

Creazione di FormTrainingClient con un endpoint e una chiave 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))

Creazione di FormTrainingClient con credenziali del token.

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

Metodi

begin_copy_model	Copiare un modello personalizzato archiviato in questa risorsa (origine) all'utente specificato Riconoscimento modulo risorsa. Questa operazione deve essere chiamata con la risorsa di Riconoscimento modulo di origine (con il modello che deve essere copiato). Il parametro di destinazione deve essere fornito dall'output della risorsa di destinazione chiamando il get_copy_authorization metodo .
begin_create_composed_model	Crea un modello composto da una raccolta di modelli esistenti sottoposti a training con etichette. Un modello composto consente di chiamare più modelli con un singolo ID modello. Quando un documento viene inviato per essere analizzato con un ID modello composto, viene prima eseguito un passaggio di classificazione per instradarlo al modello personalizzato corretto. Novità nella versione 2.1: Metodo client begin_create_composed_model
begin_training	Creare ed eseguire il training di un modello personalizzato. La richiesta deve includere un parametro training_files_url che è un URI del contenitore BLOB di archiviazione di Azure accessibile esternamente (preferibilmente un URI firma di accesso condiviso). Si noti che un URI del contenitore (senza firma di accesso condiviso) viene accettato solo quando il contenitore è pubblico o ha un'identità gestita configurata, vedere altre informazioni sulla configurazione delle identità gestite da usare con Riconoscimento modulo qui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. I modelli vengono sottoposti a training usando documenti del tipo di contenuto seguente: 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' o 'image/bmp'. Altri tipi di contenuto nel contenitore vengono ignorati. Novità nella versione 2.1: Argomento della parola chiave model_name
close	Chiudere la FormTrainingClient sessione.
delete_model	Contrassegnare il modello per l'eliminazione. Gli artefatti del modello verranno rimossi definitivamente entro un periodo predeterminato.
get_account_properties	Ottenere informazioni sui modelli nell'account di riconoscimento modulo.
get_copy_authorization	Generare l'autorizzazione per la copia di un modello personalizzato nella risorsa di Riconoscimento modulo di destinazione. Questa operazione deve essere chiamata dalla risorsa di destinazione (in cui il modello verrà copiato) e l'output può essere passato come parametro di destinazione in begin_copy_model.
get_custom_model	Ottenere una descrizione di un modello personalizzato, inclusi i tipi di moduli che può riconoscere e i campi estratti per ogni tipo di modulo.
get_form_recognizer_client	Ottenere un'istanza di FormRecognizerClient da FormTrainingClient.
list_custom_models	Elencare le informazioni per ogni modello, incluso l'ID modello, lo stato del modello e quando è stata creata e l'ultima modifica.
send_request	Esegue una richiesta di rete usando la pipeline esistente del client. L'URL della richiesta può essere relativo all'URL di base. La versione dell'API del servizio usata per la richiesta è uguale a quella del client, a meno che non sia specificato in altro modo. L'override della versione dell'API configurata del client nell'URL relativo è supportata nel client con API versione 2022-08-31 e versioni successive. Override nell'URL assoluto supportato nel client con qualsiasi versione dell'API. Questo metodo non genera se la risposta è un errore; per generare un'eccezione, chiamare raise_for_status() nell'oggetto risposta restituito. Per altre informazioni su come inviare richieste personalizzate con questo metodo, vedere https://aka.ms/azsdk/dpcodegen/python/send_request.

begin_copy_model

Copiare un modello personalizzato archiviato in questa risorsa (origine) all'utente specificato Riconoscimento modulo risorsa. Questa operazione deve essere chiamata con la risorsa di Riconoscimento modulo di origine (con il modello che deve essere copiato). Il parametro di destinazione deve essere fornito dall'output della risorsa di destinazione chiamando il get_copy_authorization metodo .

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

Parametri

model_id

str

Necessario

Identificatore del modello da copiare nella risorsa di destinazione.

target

Dict[str, Union[str, int]]

Necessario

Autorizzazione di copia generata dalla chiamata della risorsa di destinazione a get_copy_authorization.

continuation_token

str

Token di continuazione per riavviare un poller da uno stato salvato.

Restituisce

Istanza di un'istanza di LROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModelInfooggetto .

Tipo restituito

LROPoller[CustomFormModelInfo]

Eccezioni

HttpResponseError

Esempio

Copiare un modello dalla risorsa di origine alla risorsa di destinazione

   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

Crea un modello composto da una raccolta di modelli esistenti sottoposti a training con etichette.

Un modello composto consente di chiamare più modelli con un singolo ID modello. Quando un documento viene inviato per essere analizzato con un ID modello composto, viene prima eseguito un passaggio di classificazione per instradarlo al modello personalizzato corretto.

Novità nella versione 2.1: Metodo client begin_create_composed_model

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

Parametri

model_ids

list[str]

Necessario

Elenco degli ID modello da usare nel modello composto.

model_name

str

Nome facoltativo definito dall'utente da associare al modello.

continuation_token

str

Token di continuazione per riavviare un poller da uno stato salvato.

Restituisce

Istanza di un'istanza di LROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModeloggetto .

Tipo restituito

LROPoller[CustomFormModel]

Eccezioni

HttpResponseError

Esempio

Creare un modello composto

   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

Creare ed eseguire il training di un modello personalizzato. La richiesta deve includere un parametro training_files_url che è un URI del contenitore BLOB di archiviazione di Azure accessibile esternamente (preferibilmente un URI firma di accesso condiviso). Si noti che un URI del contenitore (senza firma di accesso condiviso) viene accettato solo quando il contenitore è pubblico o ha un'identità gestita configurata, vedere altre informazioni sulla configurazione delle identità gestite da usare con Riconoscimento modulo qui: https://docs.microsoft.com/azure/applied-ai-services/form-recognizer/managed-identities. I modelli vengono sottoposti a training usando documenti del tipo di contenuto seguente: 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' o 'image/bmp'. Altri tipi di contenuto nel contenitore vengono ignorati.

Novità nella versione 2.1: Argomento della parola chiave model_name

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

Parametri

training_files_url

str

Necessario

URI di firma di accesso condiviso del contenitore BLOB di Archiviazione di Azure. Un URI del contenitore (senza firma di accesso condiviso) può essere usato se il contenitore è pubblico o ha un'identità gestita configurata. Per altre informazioni sulla configurazione di un set di dati di training, vedere: https://aka.ms/azsdk/formrecognizer/buildtrainingset.

use_training_labels

bool

Necessario

Se eseguire il training con etichette o meno. I file etichettati corrispondenti devono esistere nel contenitore BLOB se impostato su True.

prefix

str

Stringa di prefisso con distinzione tra maiuscole e minuscole per filtrare i documenti nel percorso di origine per il training. Ad esempio, quando si usa un URI BLOB di archiviazione di Azure, usare il prefisso per limitare le sottocartella per il training.

include_subfolders

bool

Un flag per indicare se le sottocartelle all'interno del set di cartelle di prefisso devono essere incluse anche durante la ricerca di contenuto da pre-elaborare. Non supportato se il training con etichette.

model_name

str

Nome facoltativo definito dall'utente da associare al modello.

continuation_token

str

Token di continuazione per riavviare un poller da uno stato salvato.

Restituisce

Istanza di un'istanza di LROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModeloggetto .

Tipo restituito

LROPoller[CustomFormModel]

Eccezioni

HttpResponseError

Si noti che se il training ha esito negativo, viene generata l'eccezione, ma viene ancora creato un modello con stato "non valido". È possibile eliminare questo modello chiamando

delete_model

Esempio

Training di un modello (senza etichette) con i moduli personalizzati.

   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

Chiudere la FormTrainingClient sessione.

close() -> None

Eccezioni

HttpResponseError

delete_model

Contrassegnare il modello per l'eliminazione. Gli artefatti del modello verranno rimossi definitivamente entro un periodo predeterminato.

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

Parametri

model_id

str

Necessario

Identificatore del modello.

Tipo restituito

None

Eccezioni

HttpResponseError

ResourceNotFoundError

Esempio

Eliminare un modello personalizzato.

   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

Ottenere informazioni sui modelli nell'account di riconoscimento modulo.

get_account_properties(**kwargs: Any) -> AccountProperties

Restituisce

Riepilogo dei modelli nell'account: numero di modelli personalizzati, limite del modello personalizzato.

Tipo restituito

AccountProperties

Eccezioni

HttpResponseError

Esempio

Ottenere le proprietà per l'account di riconoscimento modulo.

   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

Generare l'autorizzazione per la copia di un modello personalizzato nella risorsa di Riconoscimento modulo di destinazione. Questa operazione deve essere chiamata dalla risorsa di destinazione (in cui il modello verrà copiato) e l'output può essere passato come parametro di destinazione in begin_copy_model.

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

Parametri

resource_id

str

Necessario

ID risorsa di Azure della risorsa di destinazione Riconoscimento modulo in cui verrà copiato il modello.

resource_region

str

Necessario

Posizione della risorsa di Riconoscimento modulo di destinazione. Nome dell'area di Azure valido supportato da Servizi cognitivi. Ad esempio, "westus", "eastus" e così via. Vedere https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services per la disponibilità a livello regionale di Servizi cognitivi.

Restituisce

Dizionario con valori per l'autorizzazione di copia - "modelId", "accessToken", "resourceId", "resourceRegion" e "expirationDateTimeTicks".

Tipo restituito

Dict[str, Union[str, int]]

Eccezioni

HttpResponseError

Esempio

Autorizzare la risorsa di destinazione a ricevere il modello copiato

   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

Ottenere una descrizione di un modello personalizzato, inclusi i tipi di moduli che può riconoscere e i campi estratti per ogni tipo di modulo.

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

Parametri

model_id

str

Necessario

Identificatore del modello.

Restituisce

CustomFormModel

Tipo restituito

CustomFormModel

Eccezioni

HttpResponseError

ResourceNotFoundError

Esempio

Ottenere un modello personalizzato con un ID modello.

   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

Ottenere un'istanza di FormRecognizerClient da FormTrainingClient.

get_form_recognizer_client(**kwargs: Any) -> FormRecognizerClient

Restituisce

A FormRecognizerClient

Tipo restituito

FormRecognizerClient

Eccezioni

HttpResponseError

list_custom_models

Elencare le informazioni per ogni modello, incluso l'ID modello, lo stato del modello e quando è stata creata e l'ultima modifica.

list_custom_models(**kwargs: Any) -> ItemPaged[CustomFormModelInfo]

Restituisce

ItemPaged[CustomFormModelInfo]

Tipo restituito

ItemPaged

Eccezioni

HttpResponseError

Esempio

Elencare le informazioni sul modello per ogni modello nell'account.

   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

Esegue una richiesta di rete usando la pipeline esistente del client.

L'URL della richiesta può essere relativo all'URL di base. La versione dell'API del servizio usata per la richiesta è uguale a quella del client, a meno che non sia specificato in altro modo. L'override della versione dell'API configurata del client nell'URL relativo è supportata nel client con API versione 2022-08-31 e versioni successive. Override nell'URL assoluto supportato nel client con qualsiasi versione dell'API. Questo metodo non genera se la risposta è un errore; per generare un'eccezione, chiamare raise_for_status() nell'oggetto risposta restituito. Per altre informazioni su come inviare richieste personalizzate con questo metodo, vedere https://aka.ms/azsdk/dpcodegen/python/send_request.

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

Parametri

request

HttpRequest

Necessario

Richiesta di rete da effettuare.

stream

bool

Indica se il payload della risposta verrà trasmesso. Il valore predefinito è False.

Restituisce

Risposta della chiamata di rete. Non esegue la gestione degli errori nella risposta.

Tipo restituito

HttpResponse

Eccezioni

HttpResponseError