Condividi tramite

FormTrainingClient Classe

  • Riferimento

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 <api =v2.1.

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

Ereditarietà
azure.ai.formrecognizer.aio._form_base_client_async.FormRecognizerClientBaseAsync
FormTrainingClient

Costruttore

FormTrainingClient(endpoint: str, credential: AzureKeyCredential | AsyncTokenCredential, **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 AsyncTokenCredential
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.aio 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.aio import FormTrainingClient
   from azure.identity.aio 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 .

async begin_copy_model(model_id: str, target: Dict[str, str | int], **kwargs: Any) -> AsyncLROPoller[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 AsyncLROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModelInfooggetto .

Tipo restituito

AsyncLROPoller[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))

   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

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

async begin_create_composed_model(model_ids: List[str], **kwargs: Any) -> AsyncLROPoller[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 AsyncLROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModeloggetto .

Tipo restituito

AsyncLROPoller[CustomFormModel]

Eccezioni

HttpResponseError

Esempio

Creare un modello composto


   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

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

async begin_training(training_files_url: str, use_training_labels: bool, **kwargs: Any) -> AsyncLROPoller[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 AsyncLROPoller. Chiamare result() nell'oggetto poller per restituire un CustomFormModeloggetto .

Tipo restituito

AsyncLROPoller[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.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

Chiudere la FormTrainingClient sessione.

async close() -> None

Eccezioni

HttpResponseError

delete_model

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

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

Parametri

model_id
str
Necessario

Identificatore del modello.

Restituisce

Nessuno

Tipo restituito

None

Eccezioni

HttpResponseError
ResourceNotFoundError

Esempio

Eliminare un modello personalizzato.


   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

Ottenere informazioni sui modelli nell'account di riconoscimento modulo.

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


   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

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.

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

   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

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

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

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) -> AsyncItemPaged[CustomFormModelInfo]

Restituisce

AsyncItemPaged[CustomFormModelInfo]

Tipo restituito

AsyncItemPaged

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:")
   async for model in custom_models:
       print(model.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.

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

Parametri

request
HttpRequest
Necessario

Richiesta di rete da effettuare.

Restituisce

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

Tipo restituito

AsyncHttpResponse

Eccezioni

HttpResponseError