Avvio rapido: Usare la libreria client o l'API REST di Riconoscimento moduloQuickstart: Use the Form Recognizer client library or REST API

Inizia con il riconoscimento del modulo usando il linguaggio di sviluppo che preferisci.Get started with the Form Recognizer using the development language of your choice. Riconoscimento modulo di Azure è un servizio cognitivo che consente di creare software di elaborazione dati automatica tramite la tecnologia di Machine Learning.Azure Form Recognizer is a cognitive service that lets you build automated data processing software using machine learning technology. Il servizio identifica ed estrae testo, coppie chiave-valore, dati delle tabelle e altro ancora dai moduli, quindi restituisce dati strutturati che includono le relazioni del file originale.Identify and extract text, key/value pairs, selection marks, table data and more from your form documents—the service outputs structured data that includes the relationships in the original file. È possibile usare Riconoscimento modulo tramite l'API REST o l'SDK.You can use Form Recognizer via the REST API or SDK. Seguire questi passaggi per installare il pacchetto SDK e provare il codice di esempio per le attività di base.Follow these steps to install the SDK package and try out the example code for basic tasks.

Usare Riconoscimento modulo per:Use Form Recognizer to:

Importante

Il codice di questo articolo usa metodi sincroni e archiviazione con credenziali non protette per motivi di semplicità.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (NuGet) | EsempiReference documentation | Library source code | Package (NuGet) | Samples

PrerequisitiPrerequisites

  • Sottoscrizione di Azure: creare un account gratuitoAzure subscription - Create one for free
  • IDE di Visual Studio o la versione corrente di .NET Core.The Visual Studio IDE or current version of .NET Core.
  • Un BLOB di Archiviazione di Azure contenente un set di dati di training.An Azure Storage blob that contains a set of training data. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di un set di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data set. Per questo argomento di avvio rapido, è possibile usare i file inclusi nella cartella Train del set di dati di esempio (scaricare ed estrarre sample_data.zip).For this quickstart, you can use the files under the Train folder of the sample data set (download and extract sample_data.zip).
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Riconoscimento modulo nel portale di Azure per ottenere la chiave e l'endpoint.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.After it deploys, click Go to resource.
    • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Riconoscimento modulo.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.You'll paste your key and endpoint into the code below later in the quickstart.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

ConfigurazioneSetting up

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome formrecognizer-quickstart.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name formrecognizer-quickstart. Questo comando crea un semplice progetto C# "Hello World" con un unico file di origine: program.cs.This command creates a simple "Hello World" C# project with a single source file: program.cs.

dotnet new console -n formrecognizer-quickstart

Spostarsi nella cartella dell'app appena creata.Change your directory to the newly created app folder. È possibile compilare l'applicazione con il comando seguente:You can build the application with:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.The build output should contain no warnings or errors.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installare la libreria clientInstall the client library

Nella directory dell'applicazione installare la libreria client di Riconoscimento modulo per .NET con il comando seguente:Within the application directory, install the Form Recognizer client library for .NET with the following command:

dotnet add package Azure.AI.FormRecognizer --version 3.0.0

Nota

L'SDK 3.0.0 di Riconoscimento modulo corrisponde alla versione 2.0 dell'APIThe Form Recognizer 3.0.0 SDK reflects API version 2.0

Suggerimento

Si vuole visualizzare l'intero file di codice dell'argomento di avvio rapido?Want to view the whole quickstart code file at once? È possibile trovarlo in GitHub, che contiene gli esempi di codice di questo argomento.You can find it on GitHub, which contains the code examples in this quickstart.

Dalla directory del progetto aprire il file Program.cs nell'ambiente di sviluppo integrato o nell'editor preferito.From the project directory, open the Program.cs file in your preferred editor or IDE. Aggiungere le direttive using seguenti:Add the following using directives:

using Azure;
using Azure.AI.FormRecognizer;  
using Azure.AI.FormRecognizer.Models;
using Azure.AI.FormRecognizer.Training;

using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

Nella classe Program dell'applicazione creare le variabili per l'endpoint e la chiave della risorsa.In the application's Program class, create variables for your resource's key and endpoint.

Importante

Accedere al portale di Azure.Go to the Azure portal. Se la risorsa di Riconoscimento modulo creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint della risorsa in Gestione risorse.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico.Remember to remove the key from your code when you're done, and never post it publicly. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali,For production, consider using a secure way of storing and accessing your credentials. Per altre informazioni, vedere l'articolo sulla sicurezza di Servizi cognitivi.See the Cognitive Services security article for more information.

private static readonly string endpoint = "<your api endpoint>";
private static readonly string apiKey = "<your Form Recognizer key>";
private static readonly AzureKeyCredential credential = new AzureKeyCredential(apiKey);

Nel metodo Main dell'applicazione aggiungere una chiamata alle attività asincrone usate in questa guida di avvio rapido.In the application's Main method, add a call to the asynchronous tasks used in this quickstart. Verranno implementate in seguito.You will implement them later.

static void Main(string[] args)
{
    var recognizerClient = AuthenticateClient();
    var trainingClient = AuthenticateTrainingClient();
    
    var recognizeContent = RecognizeContent(recognizerClient);
    Task.WaitAll(recognizeContent);

    var analyzeReceipt = AnalyzeReceipt(recognizerClient, receiptUrl);
    Task.WaitAll(analyzeReceipt); 

    var trainModel = TrainModel(trainingClient, trainingDataUrl);
    Task.WaitAll(trainModel); 

    var analyzeForm = AnalyzePdfForm(recognizerClient, trainModel, formUrl);
    Task.WaitAll(analyzeForm);
    
    var manageModels = ManageModels(trainingClient, trainingDataUrl);
    Task.WaitAll(manageModels);

}

Modello a oggettiObject model

Con Riconoscimento modulo è possibile creare due diversi tipi di client.With Form Recognizer, you can create two different client types. Il primo, FormRecognizerClient, viene usato per eseguire query sul servizio per riconoscere campi modulo e contenuti.The first, FormRecognizerClient is used to query the service to recognized form fields and content. Il secondo, FormTrainingClient, viene usato per creare e gestire modelli personalizzati da usare per migliorare il riconoscimento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient fornisce le operazioni per:FormRecognizerClient provides operations for:

  • Riconoscimento dei campi del modulo e del contenuto, utilizzo di modelli personalizzati con training per l'analisi dei moduli personalizzati.Recognizing form fields and content, using custom models trained to analyze your custom forms. Questi valori vengono restituiti in una raccolta di oggetti RecognizedForm.These values are returned in a collection of RecognizedForm objects. Vedere l'esempio Analizzare moduli personalizzati.See example Analyze custom forms.
  • Riconoscere i contenuti dei moduli, incluse tabelle, righe e parole, senza la necessità di eseguire il training di un modello.Recognizing form content, including tables, lines and words, without the need to train a model. I contenuti dei moduli vengono restituiti in una raccolta di oggetti FormPage.Form content is returned in a collection of FormPage objects. Vedere l'esempio Analizzare il layout.See example Analyze layout.
  • Riconoscere i campi comuni delle ricevute degli Stati Uniti, usando un modello di ricevuta con training preliminare nel servizio Riconoscimento modulo.Recognizing common fields from US receipts, using a pre-trained receipt model on the Form Recognizer service. Questi campi e i metadati vengono restituiti in una raccolta di oggetti RecognizedForm.These fields and meta-data are returned in a collection of RecognizedForm objects. Vedere l'esempio Analizzare ricevute.See example Analyze receipts.

FormTrainingClientFormTrainingClient

FormTrainingClient fornisce le operazioni per:FormTrainingClient provides operations for:

  • Training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati.Training custom models to analyze all fields and values found in your custom forms. CustomFormModelViene restituito un oggetto che indica i tipi di form che verrà analizzato dal modello e i campi da estrarre per ogni tipo di form.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type.
  • Training di modelli personalizzati per l'analisi di campi e valori specifici specificati tramite l'assegnazione di etichette ai moduli personalizzati.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Viene restituito un CustomFormModel che indica i campi che verranno estratti dal modello e l'accuratezza stimata per ogni campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field.
  • Gestire i modelli creati nell'account.Managing models created in your account.
  • Copiare un modello personalizzato da una risorsa Riconoscimento modulo a un'altra.Copying a custom model from one Form Recognizer resource to another.

Vedere gli esempi per Eseguire il training di un modello e Gestire modelli personalizzati.See examples for Train a Model and Manage Custom Models.

Nota

È possibile eseguire il training dei modelli anche con un'interfaccia utente grafica, ad esempio con lo strumento di etichettatura di Riconoscimento modulo.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Esempi di codiceCode examples

Questi frammenti di codice mostrano come eseguire le attività seguenti con la libreria client di Riconoscimento modulo per .NET:These code snippets show you how to do the following tasks with the Form Recognizer client library for .NET:

Autenticare il clientAuthenticate the client

Sotto Main creare un nuovo metodo denominato AuthenticateClient.Below Main, create a new method named AuthenticateClient. Verrà usato in altre attività per autenticare le richieste al servizio Riconoscimento modulo.You'll use this in other tasks to authenticate your requests to the Form Recognizer service. Questo metodo usa un oggetto AzureKeyCredential in modo che, se necessario, sia possibile aggiornare la chiave API senza creare nuovi oggetti client.This method uses the AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects.

Importante

Ottenere la chiave e l'endpoint nel portale di Azure.Get your key and endpoint from the Azure portal. Se la risorsa di Riconoscimento modulo creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint della risorsa in Gestione risorse.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico.Remember to remove the key from your code when you're done, and never post it publicly. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali,For production, consider using a secure way of storing and accessing your credentials. ad esempio Azure Key Vault.For example, Azure key vault.

static private FormRecognizerClient AuthenticateClient()
{
    var credential = new AzureKeyCredential(apiKey);
    var client = new FormRecognizerClient(new Uri(endpoint), credential);
    return client;
}

Ripetere i passaggi precedenti per un nuovo metodo che autentica un client di training.Repeat the steps above for a new method that authenticates a training client.

static private FormTrainingClient AuthenticateTrainingClient()
{
    var credential = new AzureKeyCredential(apiKey);
    var client = new FormTrainingClient(new Uri(endpoint), credential);
    return client;
}

Ottenere le risorse per il testGet assets for testing

Sarà inoltre necessario aggiungere riferimenti agli URL per i dati di training e di test.You'll also need to add references to the URLs for your training and testing data. Aggiungerli alla radice della classe Program.Add these to the root of your Program class.

  • Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

  • Ripetere quindi i passaggi precedenti per ottenere l'URL di firma di accesso condiviso di un singolo documento nel contenitore di archiviazione BLOB.Then, repeat the above steps to get the SAS URL of an individual document in blob storage container. Salvarlo anche in un percorso temporaneo.Save it to a temporary location as well.

  • Infine, salvare l'URL delle immagini di esempio incluse di seguito, disponibili anche in GitHub.Finally, save the URL of the sample image(s) included below (also available on GitHub).

private static string trainingDataUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>";
private static string formUrl = "<SAS-URL-of-a-form-in-blob-storage>";
private static string receiptUrl = "https://docs.microsoft.com/azure/cognitive-services/form-recognizer/media"
+ "/contoso-allinone.jpg";

Analizzare il layoutAnalyze layout

È possibile utilizzare il riconoscimento moduli per analizzare tabelle, righe e parole nei documenti, senza dover eseguire il training di un modello.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Il valore restituito è una raccolta di oggetti FormPage: uno per ogni pagina nel documento inviato.The returned value is a collection of FormPage objects: one for each page in the submitted document. Per ulteriori informazioni sull'estrazione del layout, vedere la Guida concettuale sul layout.For more information about layout extraction see the Layout conceptual guide.

Per analizzare il contenuto di un file in un determinato URL, utilizzare il StartRecognizeContentFromUri metodo.To analyze the content of a file at a given URL, use the StartRecognizeContentFromUri method.

private static async Task RecognizeContent(FormRecognizerClient recognizerClient)
{
    var invoiceUri = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/simple-invoice.png";
    FormPageCollection formPages = await recognizerClient
        .StartRecognizeContentFromUri(new Uri(invoiceUri))
        .WaitForCompletionAsync();

Suggerimento

È anche possibile ottenere contenuto da un file locale.You can also get content from a local file. Vedere i metodi FormRecognizerClient, ad esempio StartRecognizeContent.See the FormRecognizerClient methods, such as StartRecognizeContent. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

La parte rimanente di questa attività stampa le informazioni sul contenuto nella console.The rest of this task prints the content information to the console.

    foreach (FormPage page in formPages)
    {
        Console.WriteLine($"Form Page {page.PageNumber} has {page.Lines.Count} lines.");

        for (int i = 0; i < page.Lines.Count; i++)
        {
            FormLine line = page.Lines[i];
            Console.WriteLine($"    Line {i} has {line.Words.Count} word{(line.Words.Count > 1 ? "s" : "")}, and text: '{line.Text}'.");
        }

        for (int i = 0; i < page.Tables.Count; i++)
        {
            FormTable table = page.Tables[i];
            Console.WriteLine($"Table {i} has {table.RowCount} rows and {table.ColumnCount} columns.");
            foreach (FormTableCell cell in table.Cells)
            {
                Console.WriteLine($"    Cell ({cell.RowIndex}, {cell.ColumnIndex}) contains text: '{cell.Text}'.");
            }
        }
    }
}

OutputOutput

Form Page 1 has 18 lines.
    Line 0 has 1 word, and text: 'Contoso'.
    Line 1 has 1 word, and text: 'Address:'.
    Line 2 has 3 words, and text: 'Invoice For: Microsoft'.
    Line 3 has 4 words, and text: '1 Redmond way Suite'.
    Line 4 has 3 words, and text: '1020 Enterprise Way'.
    Line 5 has 3 words, and text: '6000 Redmond, WA'.
    Line 6 has 3 words, and text: 'Sunnayvale, CA 87659'.
    Line 7 has 1 word, and text: '99243'.
    Line 8 has 2 words, and text: 'Invoice Number'.
    Line 9 has 2 words, and text: 'Invoice Date'.
    Line 10 has 3 words, and text: 'Invoice Due Date'.
    Line 11 has 1 word, and text: 'Charges'.
    Line 12 has 2 words, and text: 'VAT ID'.
    Line 13 has 1 word, and text: '34278587'.
    Line 14 has 1 word, and text: '6/18/2017'.
    Line 15 has 1 word, and text: '6/24/2017'.
    Line 16 has 1 word, and text: '$56,651.49'.
    Line 17 has 1 word, and text: 'PT'.
Table 0 has 2 rows and 6 columns.
    Cell (0, 0) contains text: 'Invoice Number'.
    Cell (0, 1) contains text: 'Invoice Date'.
    Cell (0, 2) contains text: 'Invoice Due Date'.
    Cell (0, 3) contains text: 'Charges'.
    Cell (0, 5) contains text: 'VAT ID'.
    Cell (1, 0) contains text: '34278587'.
    Cell (1, 1) contains text: '6/18/2017'.
    Cell (1, 2) contains text: '6/24/2017'.
    Cell (1, 3) contains text: '$56,651.49'.
    Cell (1, 5) contains text: 'PT'.

Analizzare fattureAnalyze invoices

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Eseguire il training di un modello personalizzatoTrain a custom model

Questa sezione illustra come eseguire il training di un modello con i dati personali.This section demonstrates how to train a model with your own data. Un modello sottoposto a training restituisce dati strutturati che includono le relazioni chiave-valore del file originale.A trained model can output structured data that includes the key/value relationships in the original form document. Dopo il training del modello, è possibile testarlo, ripeterne il training e infine usarlo per estrarre dati in modo affidabile da altri moduli in base alle proprie esigenze.After you train the model, you can test and retrain it and eventually use it to reliably extract data from more forms according to your needs.

Nota

È anche possibile eseguire il training dei modelli con un'interfaccia utente grafica, ad esempio con lo Strumento di etichettatura campioni Riconoscimento modulo.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Eseguire il training di un modello senza etichetteTrain a model without labels

Eseguire il training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati senza etichettare manualmente i documenti di training.Train custom models to analyze all the fields and values found in your custom forms without manually labeling the training documents. Il metodo seguente esegue il training di un modello su un set di documenti specificato e ne stampa lo stato nella console.The following method trains a model on a given set of documents and prints the model's status to the console.

private static async Task<String> TrainModel(
    FormTrainingClient trainingClient, string trainingDataUrl)
{
    CustomFormModel model = await trainingClient
    .StartTrainingAsync(new Uri(trainingDataUrl), useTrainingLabels: false)
    .WaitForCompletionAsync();

    Console.WriteLine($"Custom Model Info:");
    Console.WriteLine($"    Model Id: {model.ModelId}");
    Console.WriteLine($"    Model Status: {model.Status}");
    Console.WriteLine($"    Training model started on: {model.TrainingStartedOn}");
    Console.WriteLine($"    Training model completed on: {model.TrainingCompletedOn}");

L' CustomFormModel oggetto restituito contiene informazioni sui tipi di form che il modello è in grado di analizzare e sui campi che è possibile estrarre da ogni tipo di form.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

foreach (CustomFormSubmodel submodel in model.Submodels)
{
    Console.WriteLine($"Submodel Form Type: {submodel.FormType}");
    foreach (CustomFormModelField field in submodel.Fields.Values)
    {
        Console.Write($"    FieldName: {field.Name}");
        if (field.Label != null)
        {
            Console.Write($", FieldLabel: {field.Label}");
        }
        Console.WriteLine("");
    }
}

Infine, restituisce l'ID del modello con training per l'uso nei passaggi successivi.Finally, return the trained model ID for use in later steps.

    return model.ModelId;
}

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

Merchant Name: 'Contoso Contoso', with confidence 0.516
Transaction Date: '6/10/2019 12:00:00 AM', with confidence 0.985
Item:
    Name: '8GB RAM (Black)', with confidence 0.916
    Total Price: '999', with confidence 0.559
Item:
    Name: 'SurfacePen', with confidence 0.858
    Total Price: '99.99', with confidence 0.386
Total: '1203.39', with confidence '0.774'
Form Page 1 has 18 lines.
    Line 0 has 1 word, and text: 'Contoso'.
    Line 1 has 1 word, and text: 'Address:'.
    Line 2 has 3 words, and text: 'Invoice For: Microsoft'.
    Line 3 has 4 words, and text: '1 Redmond way Suite'.
    Line 4 has 3 words, and text: '1020 Enterprise Way'.
    ...
Table 0 has 2 rows and 6 columns.
    Cell (0, 0) contains text: 'Invoice Number'.
    Cell (0, 1) contains text: 'Invoice Date'.
    Cell (0, 2) contains text: 'Invoice Due Date'.
    Cell (0, 3) contains text: 'Charges'.
    ... 
Custom Model Info:
    Model Id: 95035721-f19d-40eb-8820-0c806b42798b
    Model Status: Ready
    Training model started on: 8/24/2020 6:36:44 PM +00:00
    Training model completed on: 8/24/2020 6:36:50 PM +00:00
Submodel Form Type: form-95035721-f19d-40eb-8820-0c806b42798b
    FieldName: CompanyAddress
    FieldName: CompanyName
    FieldName: CompanyPhoneNumber
    ... 
Custom Model Info:
    Model Id: e7a1181b-1fb7-40be-bfbe-1ee154183633
    Model Status: Ready
    Training model started on: 8/24/2020 6:36:44 PM +00:00
    Training model completed on: 8/24/2020 6:36:52 PM +00:00
Submodel Form Type: form-0
    FieldName: field-0, FieldLabel: Additional Notes:
    FieldName: field-1, FieldLabel: Address:
    FieldName: field-2, FieldLabel: Company Name:
    FieldName: field-3, FieldLabel: Company Phone:
    FieldName: field-4, FieldLabel: Dated As:
    FieldName: field-5, FieldLabel: Details
    FieldName: field-6, FieldLabel: Email:
    FieldName: field-7, FieldLabel: Hero Limited
    FieldName: field-8, FieldLabel: Name:
    FieldName: field-9, FieldLabel: Phone:
    ...

Eseguire il training di un modello con etichetteTrain a model with labels

È inoltre possibile eseguire il training di modelli personalizzati etichettando manualmente i documenti di training.You can also train custom models by manually labeling the training documents. Il training con etichette consente prestazioni migliori in alcuni scenari.Training with labels leads to better performance in some scenarios. Per eseguire il training con etichette, è necessario avere file speciali di informazioni sulle etichette (\<filename\>.pdf.labels.json) nel contenitore di archiviazione BLOB insieme ai documenti di training.To train with labels, you need to have special label information files (\<filename\>.pdf.labels.json) in your blob storage container alongside the training documents. Lo Strumento di etichettatura campioni Riconoscimento modulo fornisce un'interfaccia utente che consente di creare questi file di etichette.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Quando sono disponibili è possibile chiamare il metodo StartTrainingAsync con il parametro uselabels impostato su true.Once you have them, you can call the StartTrainingAsync method with the uselabels parameter set to true.

private static async Task<Guid> TrainModelWithLabelsAsync(
    FormRecognizerClient trainingClient, string trainingDataUrl)
{
    CustomFormModel model = await trainingClient
    .StartTrainingAsync(new Uri(trainingDataUrl), useTrainingLabels: true)
    .WaitForCompletionAsync();
    Console.WriteLine($"Custom Model Info:");
    Console.WriteLine($"    Model Id: {model.ModelId}");
    Console.WriteLine($"    Model Status: {model.Status}");
    Console.WriteLine($"    Training model started on: {model.TrainingStartedOn}");
    Console.WriteLine($"    Training model completed on: {model.TrainingCompletedOn}");

L'oggetto CustomFormModel restituito indica i campi che il modello può estrarre, oltre all'accuratezza stimata in ogni campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

    foreach (CustomFormSubmodel submodel in model.Submodels)
    {
        Console.WriteLine($"Submodel Form Type: {submodel.FormType}");
        foreach (CustomFormModelField field in submodel.Fields.Values)
        {
            Console.Write($"    FieldName: {field.Name}");
            if (field.Label != null)
            {
                Console.Write($", FieldLabel: {field.Label}");
            }
            Console.WriteLine("");
        }
    }
    return model.ModelId;
}

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

Form Page 1 has 18 lines.
    Line 0 has 1 word, and text: 'Contoso'.
    Line 1 has 1 word, and text: 'Address:'.
    Line 2 has 3 words, and text: 'Invoice For: Microsoft'.
    Line 3 has 4 words, and text: '1 Redmond way Suite'.
    Line 4 has 3 words, and text: '1020 Enterprise Way'.
    Line 5 has 3 words, and text: '6000 Redmond, WA'.
    ...
Table 0 has 2 rows and 6 columns.
    Cell (0, 0) contains text: 'Invoice Number'.
    Cell (0, 1) contains text: 'Invoice Date'.
    Cell (0, 2) contains text: 'Invoice Due Date'.
    ... 
Merchant Name: 'Contoso Contoso', with confidence 0.516
Transaction Date: '6/10/2019 12:00:00 AM', with confidence 0.985
Item:
    Name: '8GB RAM (Black)', with confidence 0.916
    Total Price: '999', with confidence 0.559
Item:
    Name: 'SurfacePen', with confidence 0.858
    Total Price: '99.99', with confidence 0.386
Total: '1203.39', with confidence '0.774'
Custom Model Info:
    Model Id: 63c013e3-1cab-43eb-84b0-f4b20cb9214c
    Model Status: Ready
    Training model started on: 8/24/2020 6:42:54 PM +00:00
    Training model completed on: 8/24/2020 6:43:01 PM +00:00
Submodel Form Type: form-63c013e3-1cab-43eb-84b0-f4b20cb9214c
    FieldName: CompanyAddress
    FieldName: CompanyName
    FieldName: CompanyPhoneNumber
    FieldName: DatedAs
    FieldName: Email
    FieldName: Merchant
    ... 

Analizzare i moduli con un modello personalizzatoAnalyze forms with a custom model

Questa sezione illustra come estrarre informazioni chiave-valore e altro contenuto dai tipi di modulo personalizzati, usando i modelli a cui è stato eseguito il training con moduli personalizzati.This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.

Importante

Per implementare questo scenario è necessario avere già eseguito il training di un modello in modo da poter passare il relativo ID al metodo seguente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below.

Verrà usato il metodo StartRecognizeCustomFormsFromUri.You'll use the StartRecognizeCustomFormsFromUri method.

// Analyze PDF form data
private static async Task AnalyzePdfForm(
    FormRecognizerClient recognizerClient, String modelId, string formUrl)
{
    RecognizedFormCollection forms = await recognizerClient
    .StartRecognizeCustomFormsFromUri(modelId, new Uri(formUrl))
    .WaitForCompletionAsync();

Suggerimento

È anche possibile analizzare un file locale.You can also analyze a local file. Vedere i metodi FormRecognizerClient, ad esempio StartRecognizeCustomForms.See the FormRecognizerClient methods, such as StartRecognizeCustomForms. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

Il valore restituito è una raccolta di oggetti RecognizedForm: uno per ogni pagina nel documento inviato.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document. Il codice seguente stampa i risultati dell'analisi nella console.The following code prints the analysis results to the console. Stampa ogni campo riconosciuto e il valore corrispondente, insieme a un punteggio di attendibilità.It prints each recognized field and corresponding value, along with a confidence score.

    foreach (RecognizedForm form in forms)
    {
        Console.WriteLine($"Form of type: {form.FormType}");
        foreach (FormField field in form.Fields.Values)
        {
            Console.WriteLine($"Field '{field.Name}: ");

            if (field.LabelData != null)
            {
                Console.WriteLine($"    Label: '{field.LabelData.Text}");
            }

            Console.WriteLine($"    Value: '{field.ValueData.Text}");
            Console.WriteLine($"    Confidence: '{field.Confidence}");
        }
        Console.WriteLine("Table data:");
        foreach (FormPage page in form.Pages)
        {
            for (int i = 0; i < page.Tables.Count; i++)
            {
                FormTable table = page.Tables[i];
                Console.WriteLine($"Table {i} has {table.RowCount} rows and {table.ColumnCount} columns.");
                foreach (FormTableCell cell in table.Cells)
                {
                    Console.WriteLine($"    Cell ({cell.RowIndex}, {cell.ColumnIndex}) contains {(cell.IsHeader ? "header" : "text")}: '{cell.Text}'");
                }
            }
        }
    }
}

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

Custom Model Info:
    Model Id: 9b0108ee-65c8-450e-b527-bb309d054fc4
    Model Status: Ready
    Training model started on: 8/24/2020 7:00:31 PM +00:00
    Training model completed on: 8/24/2020 7:00:32 PM +00:00
Submodel Form Type: form-9b0108ee-65c8-450e-b527-bb309d054fc4
    FieldName: CompanyAddress
    FieldName: CompanyName
    FieldName: CompanyPhoneNumber
    ...
Form Page 1 has 18 lines.
    Line 0 has 1 word, and text: 'Contoso'.
    Line 1 has 1 word, and text: 'Address:'.
    Line 2 has 3 words, and text: 'Invoice For: Microsoft'.
    Line 3 has 4 words, and text: '1 Redmond way Suite'.
    ...

Table 0 has 2 rows and 6 columns.
    Cell (0, 0) contains text: 'Invoice Number'.
    Cell (0, 1) contains text: 'Invoice Date'.
    Cell (0, 2) contains text: 'Invoice Due Date'.
    ...
Merchant Name: 'Contoso Contoso', with confidence 0.516
Transaction Date: '6/10/2019 12:00:00 AM', with confidence 0.985
Item:
    Name: '8GB RAM (Black)', with confidence 0.916
    Total Price: '999', with confidence 0.559
Item:
    Name: 'SurfacePen', with confidence 0.858
    Total Price: '99.99', with confidence 0.386
Total: '1203.39', with confidence '0.774'
Custom Model Info:
    Model Id: dc115156-ce0e-4202-bbe4-7426e7bee756
    Model Status: Ready
    Training model started on: 8/24/2020 7:00:31 PM +00:00
    Training model completed on: 8/24/2020 7:00:41 PM +00:00
Submodel Form Type: form-0
    FieldName: field-0, FieldLabel: Additional Notes:
    FieldName: field-1, FieldLabel: Address:
    FieldName: field-2, FieldLabel: Company Name:
    FieldName: field-3, FieldLabel: Company Phone:
    FieldName: field-4, FieldLabel: Dated As:
    ... 
Form of type: custom:form
Field 'Azure.AI.FormRecognizer.Models.FieldValue:
    Value: '$56,651.49
    Confidence: '0.249
Field 'Azure.AI.FormRecognizer.Models.FieldValue:
    Value: 'PT
    Confidence: '0.245
Field 'Azure.AI.FormRecognizer.Models.FieldValue:
    Value: '99243
    Confidence: '0.114
   ...

Analizzare ricevuteAnalyze receipts

Questa sezione illustra come analizzare ed estrarre i campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione con training preliminare.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Per ulteriori informazioni sull'analisi della ricezione, vedere la Guida concettuale relativa alle ricevute.For more information about receipt analysis, see the Receipts conceptual guide.

Per analizzare le ricevute da un URL, usare il StartRecognizeReceiptsFromUri metodo.To analyze receipts from a URL, use the StartRecognizeReceiptsFromUri method.

private static async Task AnalyzeReceipt(
    FormRecognizerClient recognizerClient, string receiptUri)
{
    RecognizedFormCollection receipts = await recognizerClient.StartRecognizeReceiptsFromUri(new Uri(receiptUrl)).WaitForCompletionAsync();

Suggerimento

È anche possibile analizzare le immagini di ricezione locali.You can also analyze local receipt images. Vedere i metodi FormRecognizerClient, ad esempio StartRecognizeReceipts.See the FormRecognizerClient methods, such as StartRecognizeReceipts. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

Il valore restituito è una raccolta di oggetti RecognizedReceipt, uno per ogni pagina del documento inviato.The returned value is a collection of RecognizedReceipt objects: one for each page in the submitted document. Il codice seguente elabora una ricevuta in corrispondenza dell'URI specificato e stampa i campi e i valori principali nella console.The following code processes the receipt at the given URI and prints the major fields and values to the console.

    foreach (RecognizedForm receipt in receipts)
    {
        FormField merchantNameField;
        if (receipt.Fields.TryGetValue("MerchantName", out merchantNameField))
        {
            if (merchantNameField.Value.ValueType == FieldValueType.String)
            {
                string merchantName = merchantNameField.Value.AsString();

                Console.WriteLine($"Merchant Name: '{merchantName}', with confidence {merchantNameField.Confidence}");
            }
        }

        FormField transactionDateField;
        if (receipt.Fields.TryGetValue("TransactionDate", out transactionDateField))
        {
            if (transactionDateField.Value.ValueType == FieldValueType.Date)
            {
                DateTime transactionDate = transactionDateField.Value.AsDate();

                Console.WriteLine($"Transaction Date: '{transactionDate}', with confidence {transactionDateField.Confidence}");
            }
        }

        FormField itemsField;
        if (receipt.Fields.TryGetValue("Items", out itemsField))
        {
            if (itemsField.Value.ValueType == FieldValueType.List)
            {
                foreach (FormField itemField in itemsField.Value.AsList())
                {
                    Console.WriteLine("Item:");

                    if (itemField.Value.ValueType == FieldValueType.Dictionary)
                    {
                        IReadOnlyDictionary<string, FormField> itemFields = itemField.Value.AsDictionary();

                        FormField itemNameField;
                        if (itemFields.TryGetValue("Name", out itemNameField))
                        {
                            if (itemNameField.Value.ValueType == FieldValueType.String)
                            {
                                string itemName = itemNameField.Value.AsString();

                                Console.WriteLine($"    Name: '{itemName}', with confidence {itemNameField.Confidence}");
                            }
                        }

                        FormField itemTotalPriceField;
                        if (itemFields.TryGetValue("TotalPrice", out itemTotalPriceField))
                        {
                            if (itemTotalPriceField.Value.ValueType == FieldValueType.Float)
                            {
                                float itemTotalPrice = itemTotalPriceField.Value.AsFloat();

                                Console.WriteLine($"    Total Price: '{itemTotalPrice}', with confidence {itemTotalPriceField.Confidence}");
                            }
                        }
                    }
                }
            }
        }
        FormField totalField;
        if (receipt.Fields.TryGetValue("Total", out totalField))
        {
            if (totalField.Value.ValueType == FieldValueType.Float)
            {
                float total = totalField.Value.AsFloat();

                Console.WriteLine($"Total: '{total}', with confidence '{totalField.Confidence}'");
            }
        }
    }
}

OutputOutput

Form Page 1 has 18 lines.
    Line 0 has 1 word, and text: 'Contoso'.
    Line 1 has 1 word, and text: 'Address:'.
    Line 2 has 3 words, and text: 'Invoice For: Microsoft'.
    Line 3 has 4 words, and text: '1 Redmond way Suite'.
    Line 4 has 3 words, and text: '1020 Enterprise Way'.
    Line 5 has 3 words, and text: '6000 Redmond, WA'.
    Line 6 has 3 words, and text: 'Sunnayvale, CA 87659'.
    Line 7 has 1 word, and text: '99243'.
    Line 8 has 2 words, and text: 'Invoice Number'.
    Line 9 has 2 words, and text: 'Invoice Date'.
    Line 10 has 3 words, and text: 'Invoice Due Date'.
    Line 11 has 1 word, and text: 'Charges'.
    Line 12 has 2 words, and text: 'VAT ID'.
    Line 13 has 1 word, and text: '34278587'.
    Line 14 has 1 word, and text: '6/18/2017'.
    Line 15 has 1 word, and text: '6/24/2017'.
    Line 16 has 1 word, and text: '$56,651.49'.
    Line 17 has 1 word, and text: 'PT'.
Table 0 has 2 rows and 6 columns.
    Cell (0, 0) contains text: 'Invoice Number'.
    Cell (0, 1) contains text: 'Invoice Date'.
    Cell (0, 2) contains text: 'Invoice Due Date'.
    Cell (0, 3) contains text: 'Charges'.
    Cell (0, 5) contains text: 'VAT ID'.
    Cell (1, 0) contains text: '34278587'.
    Cell (1, 1) contains text: '6/18/2017'.
    Cell (1, 2) contains text: '6/24/2017'.
    Cell (1, 3) contains text: '$56,651.49'.
    Cell (1, 5) contains text: 'PT'.
Merchant Name: 'Contoso Contoso', with confidence 0.516
Transaction Date: '6/10/2019 12:00:00 AM', with confidence 0.985
Item:
    Name: '8GB RAM (Black)', with confidence 0.916
    Total Price: '999', with confidence 0.559
Item:
    Name: 'SurfacePen', with confidence 0.858
    Total Price: '99.99', with confidence 0.386
Total: '1203.39', with confidence '0.774'

Analizzare biglietti da visitaAnalyze business cards

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Gestire i modelli personalizzatiManage custom models

Questa sezione illustra come gestire modelli personalizzati archiviati nell'account.This section demonstrates how to manage the custom models stored in your account. Verranno eseguite più operazioni all'interno del metodo seguente:You'll do multiple operations within the following method:

private static async Task ManageModels(
    FormRecognizerClient trainingClient, string trainingFileUrl)
{

Verificare il numero dei modelli all'interno dell'account della risorsa FormRecognizerCheck the number of models in the FormRecognizer resource account

Il blocco di codice seguente consente di controllare il numero di modelli salvati nell'account di Riconoscimento modulo e di confrontarli con il limite dell'account.The following code block checks how many models you have saved in your Form Recognizer account and compares it to the account limit.

// Check number of models in the FormRecognizer account, 
// and the maximum number of models that can be stored.
AccountProperties accountProperties = trainingClient.GetAccountProperties();
Console.WriteLine($"Account has {accountProperties.CustomModelCount} models.");
Console.WriteLine($"It can have at most {accountProperties.CustomModelLimit} models.");

OutputOutput

Account has 20 models.
It can have at most 5000 models.

Elencare i modelli archiviati attualmente nell'account della risorsaList the models currently stored in the resource account

Il blocco di codice seguente elenca i modelli attuali presenti nell'account e stampa i relativi dettagli nella console.The following code block lists the current models in your account and prints their details to the console.

Pageable<CustomFormModelInfo> models = trainingClient.GetCustomModels();

foreach (CustomFormModelInfo modelInfo in models)
{
    Console.WriteLine($"Custom Model Info:");
    Console.WriteLine($"    Model Id: {modelInfo.ModelId}");
    Console.WriteLine($"    Model Status: {modelInfo.Status}");
    Console.WriteLine($"    Training model started on: {modelInfo.TrainingStartedOn}");
    Console.WriteLine($"    Training model completed on: {modelInfo.TrainingCompletedOn}");
}

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

Custom Model Info:
    Model Id: 05932d5a-a2f8-4030-a2ef-4e5ed7112515
    Model Status: Creating
    Training model started on: 8/24/2020 7:35:02 PM +00:00
    Training model completed on: 8/24/2020 7:35:02 PM +00:00
Custom Model Info:
    Model Id: 150828c4-2eb2-487e-a728-60d5d504bd16
    Model Status: Ready
    Training model started on: 8/24/2020 7:33:25 PM +00:00
    Training model completed on: 8/24/2020 7:33:27 PM +00:00
Custom Model Info:
    Model Id: 3303e9de-6cec-4dfb-9e68-36510a6ecbb2
    Model Status: Ready
    Training model started on: 8/24/2020 7:29:27 PM +00:00
    Training model completed on: 8/24/2020 7:29:36 PM +00:00

Ottenere un modello specifico con l'ID del modelloGet a specific model using the model's ID

Il blocco di codice seguente esegue il training di un nuovo modello, come descritto nella sezione Eseguire il training di un modello, e quindi ne recupera un secondo riferimento usando il relativo ID.The following code block trains a new model (just like in the Train a model section) and then retrieves a second reference to it using its ID.

// Create a new model to store in the account
CustomFormModel model = await trainingClient.StartTrainingAsync(
    new Uri(trainingFileUrl)).WaitForCompletionAsync();

// Get the model that was just created
CustomFormModel modelCopy = trainingClient.GetCustomModel(model.ModelId);

Console.WriteLine($"Custom Model {modelCopy.ModelId} recognizes the following form types:");

foreach (CustomFormSubmodel submodel in modelCopy.Submodels)
{
    Console.WriteLine($"Submodel Form Type: {submodel.FormType}");
    foreach (CustomFormModelField field in submodel.Fields.Values)
    {
        Console.Write($"    FieldName: {field.Name}");
        if (field.Label != null)
        {
            Console.Write($", FieldLabel: {field.Label}");
        }
        Console.WriteLine("");
    }
}

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

Custom Model Info:
    Model Id: 150828c4-2eb2-487e-a728-60d5d504bd16
    Model Status: Ready
    Training model started on: 8/24/2020 7:33:25 PM +00:00
    Training model completed on: 8/24/2020 7:33:27 PM +00:00
Submodel Form Type: form-150828c4-2eb2-487e-a728-60d5d504bd16
    FieldName: CompanyAddress
    FieldName: CompanyName
    FieldName: CompanyPhoneNumber
    FieldName: DatedAs
    FieldName: Email
    FieldName: Merchant
    FieldName: PhoneNumber
    FieldName: PurchaseOrderNumber
    FieldName: Quantity
    FieldName: Signature
    FieldName: Subtotal
    FieldName: Tax
    FieldName: Total
    FieldName: VendorName
    FieldName: Website
...

Eliminare un modello dall'account della risorsaDelete a model from the resource account

È inoltre possibile eliminare un modello dall'account facendo riferimento al relativo ID.You can also delete a model from your account by referencing its ID. Questo passaggio chiude anche il metodo.This step also closes out the method.

    // Delete the model from the account.
    trainingClient.DeleteModel(model.ModelId);
}

Eseguire l'applicazioneRun the application

Eseguire l'applicazione dalla directory dell'applicazione con il comando dotnet run.Run the application from your application directory with the dotnet run command.

dotnet run

Pulire le risorseClean up resources

Se si vuole pulire e rimuovere una sottoscrizione a Servizi cognitivi, è possibile eliminare la risorsa o il gruppo di risorse.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate.Deleting the resource group also deletes any other resources associated with it.

Risoluzione dei problemiTroubleshooting

Quando si interagisce con la libreria client di Riconoscimento modulo di Servizi cognitivi con .NET SDK, gli errori restituiti dal servizio genereranno un'eccezione RequestFailedException.When you interact with the Cognitive Services Form Recognizer client library using the .NET SDK, errors returned by the service will result in a RequestFailedException. Verrà incluso lo stesso codice di stato HTTP che verrebbe restituito da una richiesta API REST.They'll include the same HTTP status code that would have been returned by a REST API request.

Se, ad esempio, si invia un'immagine di ricevuta con un URI non valido, viene restituito un errore 400, che indica che la richiesta non è valida.For example, if you submit a receipt image with an invalid URI, a 400 error is returned, indicating "Bad Request".

try
{
    RecognizedReceiptCollection receipts = await client.StartRecognizeReceiptsFromUri(new Uri(receiptUri)).WaitForCompletionAsync();
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Si noterà che vengono registrate informazioni aggiuntive, ad esempio l'ID richiesta client dell'operazione.You'll notice that additional information, like the client request ID of the operation, is logged.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":"FailedToDownloadImage","innerError":
    {"requestId":"8ca04feb-86db-4552-857c-fde903251518"},
    "message":"Failed to download image from input URL."}}

Headers:
    Transfer-Encoding: chunked
    x-envoy-upstream-service-time: REDACTED
    apim-request-id: REDACTED
    Strict-Transport-Security: REDACTED
    X-Content-Type-Options: REDACTED
    Date: Mon, 20 Apr 2020 22:48:35 GMT
    Content-Type: application/json; charset=utf-8

Passaggi successiviNext steps

In questo argomento di avvio rapido è stata usata la libreria client di Riconoscimento modulo per .NET per eseguire il training di modelli e analizzare i moduli in modi diversi.In this quickstart, you used the Form Recognizer .NET client library to train models and analyze forms in different ways. In seguito, è possibile ottenere suggerimenti per creare un set di dati di training migliore e produrre modelli più accurati.Next, learn tips to create a better training data set and produce more accurate models.

Importante

Il codice di questo articolo usa metodi sincroni e archiviazione con credenziali non protette per motivi di semplicità.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (Maven) | EsempiReference documentation | Library source code | Package (Maven) | Samples

PrerequisitiPrerequisites

  • Sottoscrizione di Azure: creare un account gratuitoAzure subscription - Create one for free
  • La versione più recente di Java Development Kit (JDK)The current version of the Java Development Kit (JDK)
  • Lo strumento di compilazione Gradle o un'altra utilità di gestione dipendenze.The Gradle build tool, or another dependency manager.
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Riconoscimento modulo nel portale di Azure per ottenere la chiave e l'endpoint.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.After it deploys, click Go to resource.
    • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Riconoscimento modulo.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.You'll paste your key and endpoint into the code below later in the quickstart.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Un BLOB di Archiviazione di Azure contenente un set di dati di training.An Azure Storage blob that contains a set of training data. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di un set di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data set. Per questo argomento di avvio rapido, è possibile usare i file inclusi nella cartella Train del set di dati di esempio (scaricare ed estrarre sample_data.zip).For this quickstart, you can use the files under the Train folder of the sample data set (download and extract sample_data.zip).

ConfigurazioneSetting up

Creare un nuovo progetto GradleCreate a new Gradle project

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app.In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.

mkdir myapp && cd myapp

Eseguire il comando gradle init dalla directory di lavoro.Run the gradle init command from your working directory. Questo comando creerà i file di compilazione essenziali per Gradle, tra cui build.gradle.kts, che viene usato in fase di esecuzione per creare e configurare l'applicazione.This command will create essential build files for Gradle, including build.gradle.kts which is used at runtime to create and configure your application.

gradle init --type basic

Quando viene chiesto di scegliere un linguaggio DSL, selezionare Kotlin.When prompted to choose a DSL, select Kotlin.

Installare la libreria clientInstall the client library

Questo argomento di avvio rapido usa l'utilità di gestione dipendenze Gradle.This quickstart uses the Gradle dependency manager. La libreria client e le informazioni per altre utilità di gestione dipendenze sono disponibili in Maven Central Repository.You can find the client library and information for other dependency managers on the Maven Central Repository.

Nel file build.gradle.kts del progetto includere la libreria client come istruzione implementation, unitamente ai plug-in e alle impostazioni necessari.In your project's build.gradle.kts file, include the client library as an implementation statement, along with the required plugins and settings.

plugins {
    java
    application
}
application {
    mainClass.set("FormRecognizer")
}
repositories {
    mavenCentral()
}
dependencies {
    implementation(group = "com.azure", name = "azure-ai-formrecognizer", version = "3.0.0")
}

Nota

L'SDK 3.0.0 di Riconoscimento modulo corrisponde alla versione 2.0 dell'APIThe Form Recognizer 3.0.0 SDK reflects API version 2.0

Creare un file JavaCreate a Java file

Dalla directory di lavoro eseguire il comando seguente:From your working directory, run the following command:

mkdir -p src/main/java

Passare alla nuova cartella e creare un file denominato FormRecognizer.java.Navigate to the new folder and create a file called FormRecognizer.java. Aprirlo in un editor o un IDE a scelta e importare le istruzioni import seguenti:Open it in your preferred editor or IDE and add the following import statements:

import com.azure.ai.formrecognizer.*;
import com.azure.ai.formrecognizer.training.*;
import com.azure.ai.formrecognizer.models.*;
import com.azure.ai.formrecognizer.training.models.*;

import java.util.concurrent.atomic.AtomicReference;
import java.util.List;
import java.util.Map;
import java.time.LocalDate;

import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.http.rest.PagedIterable;
import com.azure.core.util.Context;
import com.azure.core.util.polling.SyncPoller;

Suggerimento

Si vuole visualizzare l'intero file di codice dell'argomento di avvio rapido?Want to view the whole quickstart code file at once? È possibile trovarlo in GitHub, che contiene gli esempi di codice di questo argomento.You can find it on GitHub, which contains the code examples in this quickstart.

Nella classe FormRecognizer dell'applicazione creare le variabili per l'endpoint e la chiave della risorsa.In the application's FormRecognizer class, create variables for your resource's key and endpoint.

static final String key = "<replace-with-your-form-recognizer-key>";
static final String endpoint = "<replace-with-your-form-recognizer-endpoint>";

Importante

Accedere al portale di Azure.Go to the Azure portal. Se la risorsa di Riconoscimento modulo creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint della risorsa in Gestione risorse.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico.Remember to remove the key from your code when you're done, and never post it publicly. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali,For production, consider using a secure way of storing and accessing your credentials. Per altre informazioni, vedere l'articolo sulla sicurezza di Servizi cognitivi.See the Cognitive Services security article for more information.

Nel metodo main dell'applicazione aggiungere le chiamate per i metodi usati in questa guida di avvio rapido.In the application's main method, add calls for the methods used in this quickstart. Verranno definiti in un secondo momento.You'll define these later. Sarà inoltre necessario aggiungere riferimenti agli URL per i dati di training e di test.You'll also need to add references to the URLs for your training and testing data.

  • Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

  • Per ottenere un URL di un modulo da testare è possibile usare i passaggi precedenti per ottenere l'URL di firma di accesso condiviso di un singolo documento nell'archivio BLOB.To get a URL of a form to test, you can use the above steps to get the SAS URL of an individual document in blob storage. In alternativa, prendere l'URL di un documento situato altrove.Or, take the URL of a document located elsewhere.

  • Usare il metodo precedente per ottenere l'URL anche di un'immagine di una ricevuta.Use the above method to get the URL of a receipt image as well.

String trainingDataUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>";
String formUrl = "<SAS-URL-of-a-form-in-blob-storage>";
String receiptUrl = "https://docs.microsoft.com/azure/cognitive-services/form-recognizer/media"
        + "/contoso-allinone.jpg";
// Call Form Recognizer scenarios:
System.out.println("Get form content...");
GetContent(recognizerClient, formUrl);

System.out.println("Analyze receipt...");
AnalyzeReceipt(recognizerClient, receiptUrl);

System.out.println("Train Model with training data...");
String modelId = TrainModel(trainingClient, trainingDataUrl);

System.out.println("Analyze PDF form...");
AnalyzePdfForm(recognizerClient, modelId, formUrl);

System.out.println("Manage models...");
ManageModels(trainingClient, trainingDataUrl);

Modello a oggettiObject model

Con Riconoscimento modulo è possibile creare due diversi tipi di client.With Form Recognizer, you can create two different client types. Il primo, FormRecognizerClient, viene usato per eseguire query sul servizio per riconoscere campi modulo e contenuti.The first, FormRecognizerClient is used to query the service to recognized form fields and content. Il secondo, FormTrainingClient, viene usato per creare e gestire modelli personalizzati da usare per migliorare il riconoscimento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient fornisce le operazioni per:FormRecognizerClient provides operations for:

  • Riconoscimento dei campi del modulo e del contenuto, utilizzo di modelli personalizzati con training per l'analisi dei moduli personalizzati.Recognizing form fields and content, using custom models trained to analyze your custom forms. Questi valori vengono restituiti in una raccolta di oggetti RecognizedForm.These values are returned in a collection of RecognizedForm objects. Vedere l'esempio Analizzare moduli personalizzati.See example Analyze custom forms.
  • Riconoscere i contenuti dei moduli, incluse tabelle, righe e parole, senza la necessità di eseguire il training di un modello.Recognizing form content, including tables, lines and words, without the need to train a model. I contenuti dei moduli vengono restituiti in una raccolta di oggetti FormPage.Form content is returned in a collection of FormPage objects. Vedere l'esempio Analizzare il layout.See example Analyze layout.
  • Riconoscere i campi comuni delle ricevute degli Stati Uniti, usando un modello di ricevuta con training preliminare nel servizio Riconoscimento modulo.Recognizing common fields from US receipts, using a pre-trained receipt model on the Form Recognizer service. Questi campi e i metadati vengono restituiti in una raccolta di oggetti RecognizedForm.These fields and meta-data are returned in a collection of RecognizedForm objects. Vedere l'esempio Analizzare ricevute.See example Analyze receipts.

FormTrainingClientFormTrainingClient

FormTrainingClient fornisce le operazioni per:FormTrainingClient provides operations for:

  • Training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati.Training custom models to analyze all fields and values found in your custom forms. CustomFormModelViene restituito un oggetto che indica i tipi di form che verrà analizzato dal modello e i campi da estrarre per ogni tipo di form.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type.
  • Training di modelli personalizzati per l'analisi di campi e valori specifici specificati tramite l'assegnazione di etichette ai moduli personalizzati.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Viene restituito un CustomFormModel che indica i campi che verranno estratti dal modello e l'accuratezza stimata per ogni campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field.
  • Gestire i modelli creati nell'account.Managing models created in your account.
  • Copiare un modello personalizzato da una risorsa Riconoscimento modulo a un'altra.Copying a custom model from one Form Recognizer resource to another.

Nota

È possibile eseguire il training dei modelli anche con un'interfaccia utente grafica, ad esempio con lo strumento di etichettatura di Riconoscimento modulo.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Esempi di codiceCode examples

Questi frammenti di codice mostrano come eseguire le attività seguenti con la libreria client di Riconoscimento modulo per Java:These code snippets show you how to do the following tasks with the Form Recognizer client library for Java:

Autenticare il clientAuthenticate the client

All'inizio del metodo principale, aggiungere il codice seguente.At the top of your main method, add the following code. In questo caso si eseguirà l'autenticazione dei due oggetti client con le variabili di sottoscrizione definite in precedenza.Here, you'll authenticate two client objects using the subscription variables you defined above. Si userà un oggetto AzureKeyCredential in modo che, se necessario, sia possibile aggiornare la chiave API senza creare nuovi oggetti client.You'll use an AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects.

FormRecognizerClient recognizerClient = new FormRecognizerClientBuilder()
        .credential(new AzureKeyCredential(key)).endpoint(endpoint).buildClient();

FormTrainingClient trainingClient = new FormTrainingClientBuilder().credential(new AzureKeyCredential(key))
        .endpoint(endpoint).buildClient();

Analizzare il layoutAnalyze layout

È possibile utilizzare il riconoscimento moduli per analizzare tabelle, righe e parole nei documenti, senza dover eseguire il training di un modello.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Per ulteriori informazioni sull'estrazione del layout, vedere la Guida concettuale sul layout.For more information about layout extraction see the Layout conceptual guide.

Per analizzare il contenuto di un file in un determinato URL, utilizzare il metodo beginRecognizeContentFromUrl .To analyze the content of a file at a given URL, use the beginRecognizeContentFromUrl method.

private static void GetContent(FormRecognizerClient recognizerClient, String invoiceUri) {
    String analyzeFilePath = invoiceUri;
    SyncPoller<FormRecognizerOperationResult, List<FormPage>> recognizeContentPoller = recognizerClient
            .beginRecognizeContentFromUrl(analyzeFilePath);

    List<FormPage> contentResult = recognizeContentPoller.getFinalResult();

Suggerimento

È anche possibile ottenere contenuto da un file locale.You can also get content from a local file. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeContent.See the FormRecognizerClient methods, such as beginRecognizeContent. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

Il valore restituito è una raccolta di oggetti FormPage: uno per ogni pagina nel documento inviato.The returned value is a collection of FormPage objects: one for each page in the submitted document. Il codice seguente esegue l'iterazione di questi oggetti e stampa le coppie chiave-valore estratte con i dati della tabella.The following code iterates through these objects and prints the extracted key/value pairs and table data.

    contentResult.forEach(formPage -> {
        // Table information
        System.out.println("----Recognizing content ----");
        System.out.printf("Has width: %f and height: %f, measured with unit: %s.%n", formPage.getWidth(),
                formPage.getHeight(), formPage.getUnit());
        formPage.getTables().forEach(formTable -> {
            System.out.printf("Table has %d rows and %d columns.%n", formTable.getRowCount(),
                    formTable.getColumnCount());
            formTable.getCells().forEach(formTableCell -> {
                System.out.printf("Cell has text %s.%n", formTableCell.getText());
            });
            System.out.println();
        });
    });
}

OutputOutput

Get form content...
----Recognizing content ----
Has width: 8.500000 and height: 11.000000, measured with unit: inch.
Table has 2 rows and 6 columns.
Cell has text Invoice Number.
Cell has text Invoice Date.
Cell has text Invoice Due Date.
Cell has text Charges.
Cell has text VAT ID.
Cell has text 458176.
Cell has text 3/28/2018.
Cell has text 4/16/2018.
Cell has text $89,024.34.
Cell has text ET.

Analizzare fattureAnalyze invoices

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Eseguire il training di un modello personalizzatoTrain a custom model

Questa sezione illustra come eseguire il training di un modello con i dati personali.This section demonstrates how to train a model with your own data. Un modello sottoposto a training restituisce dati strutturati che includono le relazioni chiave-valore del file originale.A trained model can output structured data that includes the key/value relationships in the original form document. Dopo il training del modello, è possibile testarlo, ripeterne il training e infine usarlo per estrarre dati in modo affidabile da altri moduli in base alle proprie esigenze.After you train the model, you can test and retrain it and eventually use it to reliably extract data from more forms according to your needs.

Nota

È anche possibile eseguire il training dei modelli con un'interfaccia utente grafica, ad esempio con lo Strumento di etichettatura campioni Riconoscimento modulo.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Eseguire il training di un modello senza etichetteTrain a model without labels

Eseguire il training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati senza etichettare manualmente i documenti di training.Train custom models to analyze all fields and values found in your custom forms without manually labeling the training documents.

Il metodo seguente esegue il training di un modello su un set di documenti specificato e ne stampa lo stato nella console.The following method trains a model on a given set of documents and prints the model's status to the console.

private static String TrainModel(FormTrainingClient trainingClient, String trainingDataUrl) {
    SyncPoller<FormRecognizerOperationResult, CustomFormModel> trainingPoller = trainingClient
            .beginTraining(trainingDataUrl, false);

    CustomFormModel customFormModel = trainingPoller.getFinalResult();

    // Model Info
    System.out.printf("Model Id: %s%n", customFormModel.getModelId());
    System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
    System.out.printf("Training started on: %s%n", customFormModel.getTrainingStartedOn());
    System.out.printf("Training completed on: %s%n%n", customFormModel.getTrainingCompletedOn());

L'oggetto CustomFormModel restituito contiene informazioni sui tipi di form che il modello è in grado di analizzare e sui campi che è possibile estrarre da ogni tipo di form.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

System.out.println("Recognized Fields:");
// looping through the subModels, which contains the fields they were trained on
// Since the given training documents are unlabeled, we still group them but
// they do not have a label.
customFormModel.getSubmodels().forEach(customFormSubmodel -> {
    // Since the training data is unlabeled, we are unable to return the accuracy of
    // this model
    System.out.printf("The subModel has form type %s%n", customFormSubmodel.getFormType());
    customFormSubmodel.getFields().forEach((field, customFormModelField) -> System.out
            .printf("The model found field '%s' with label: %s%n", field, customFormModelField.getLabel()));
});

Infine, questo metodo restituisce l'ID univoco del modello.Finally, this method returns the unique ID of the model.

    return customFormModel.getModelId();
}

OutputOutput

Train Model with training data...
Model Id: 20c3544d-97b4-49d9-b39b-dc32d85f1358
Model Status: ready
Training started on: 2020-08-31T16:52:09Z
Training completed on: 2020-08-31T16:52:23Z

Recognized Fields:
The subModel has form type form-0
The model found field 'field-0' with label: Address:
The model found field 'field-1' with label: Charges
The model found field 'field-2' with label: Invoice Date
The model found field 'field-3' with label: Invoice Due Date
The model found field 'field-4' with label: Invoice For:
The model found field 'field-5' with label: Invoice Number
The model found field 'field-6' with label: VAT ID

Eseguire il training di un modello con etichetteTrain a model with labels

È inoltre possibile eseguire il training di modelli personalizzati etichettando manualmente i documenti di training.You can also train custom models by manually labeling the training documents. Il training con etichette consente prestazioni migliori in alcuni scenari.Training with labels leads to better performance in some scenarios. Per eseguire il training con etichette, è necessario avere file speciali di informazioni sulle etichette ( <filename>.pdf. labels.json) nel contenitore di archiviazione BLOB insieme ai documenti di training.To train with labels, you need to have special label information files (<filename>.pdf.labels.json) in your blob storage container alongside the training documents. Lo Strumento di etichettatura campioni Riconoscimento modulo fornisce un'interfaccia utente che consente di creare questi file di etichette.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Una volta creati, è possibile chiamare il metodo beginTraining con il parametro useTrainingLabels impostato su true.Once you have them, you can call the beginTraining method with the useTrainingLabels parameter set to true.

private static String TrainModelWithLabels(FormTrainingClient trainingClient, String trainingDataUrl) {
    // Train custom model
    String trainingSetSource = trainingDataUrl;
    SyncPoller<FormRecognizerOperationResult, CustomFormModel> trainingPoller = trainingClient
            .beginTraining(trainingSetSource, true);

    CustomFormModel customFormModel = trainingPoller.getFinalResult();

    // Model Info
    System.out.printf("Model Id: %s%n", customFormModel.getModelId());
    System.out.printf("Model Status: %s%n", customFormModel.getModelStatus());
    System.out.printf("Training started on: %s%n", customFormModel.getTrainingStartedOn());
    System.out.printf("Training completed on: %s%n%n", customFormModel.getTrainingCompletedOn());

L'oggetto CustomFormModel restituito indica i campi che il modello può estrarre, insieme alla relativa precisione stimata in ogni campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

    // looping through the subModels, which contains the fields they were trained on
    // The labels are based on the ones you gave the training document.
    System.out.println("Recognized Fields:");
    // Since the data is labeled, we are able to return the accuracy of the model
    customFormModel.getSubmodels().forEach(customFormSubmodel -> {
        System.out.printf("The subModel with form type %s has accuracy: %.2f%n", customFormSubmodel.getFormType(),
                customFormSubmodel.getAccuracy());
        customFormSubmodel.getFields()
                .forEach((label, customFormModelField) -> System.out.printf(
                        "The model found field '%s' to have name: %s with an accuracy: %.2f%n", label,
                        customFormModelField.getName(), customFormModelField.getAccuracy()));
    });
    return customFormModel.getModelId();
}

OutputOutput

Train Model with training data...
Model Id: 20c3544d-97b4-49d9-b39b-dc32d85f1358
Model Status: ready
Training started on: 2020-08-31T16:52:09Z
Training completed on: 2020-08-31T16:52:23Z

Recognized Fields:
The subModel has form type form-0
The model found field 'field-0' with label: Address:
The model found field 'field-1' with label: Charges
The model found field 'field-2' with label: Invoice Date
The model found field 'field-3' with label: Invoice Due Date
The model found field 'field-4' with label: Invoice For:
The model found field 'field-5' with label: Invoice Number
The model found field 'field-6' with label: VAT ID

Analizzare i moduli con un modello personalizzatoAnalyze forms with a custom model

Questa sezione illustra come estrarre informazioni chiave-valore e altro contenuto dai tipi di modulo personalizzati, usando i modelli a cui è stato eseguito il training con moduli personalizzati.This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.

Importante

Per implementare questo scenario è necessario avere già eseguito il training di un modello in modo da poter passare il relativo ID al metodo seguente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Vedere la sezione Eseguire il training di un modello.See the Train a model section.

Si userà il metodo beginRecognizeCustomFormsFromUrl.You'll use the beginRecognizeCustomFormsFromUrl method.

// Analyze PDF form data
private static void AnalyzePdfForm(FormRecognizerClient formClient, String modelId, String pdfFormUrl) {
    SyncPoller<FormRecognizerOperationResult, List<RecognizedForm>> recognizeFormPoller = formClient
            .beginRecognizeCustomFormsFromUrl(modelId, pdfFormUrl);

    List<RecognizedForm> recognizedForms = recognizeFormPoller.getFinalResult();

Suggerimento

È anche possibile analizzare un file locale.You can also analyze a local file. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeCustomForms.See the FormRecognizerClient methods, such as beginRecognizeCustomForms. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

Il valore restituito è una raccolta di oggetti RecognizedForm, uno per ogni pagina del documento inviato. Il codice seguente stampa i risultati dell'analisi nella console.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document.The following code prints the analysis results to the console. Stampa ogni campo riconosciuto e il valore corrispondente, insieme a un punteggio di attendibilità.It prints each recognized field and corresponding value, along with a confidence score.

    for (int i = 0; i < recognizedForms.size(); i++) {
        final RecognizedForm form = recognizedForms.get(i);
        System.out.printf("----------- Recognized custom form info for page %d -----------%n", i);
        System.out.printf("Form type: %s%n", form.getFormType());
        form.getFields().forEach((label, formField) ->
        // label data is populated if you are using a model trained with unlabeled data,
        // since the service needs to make predictions for labels if not explicitly
        // given to it.
        System.out.printf("Field '%s' has label '%s' with a confidence " + "score of %.2f.%n", label,
                formField.getLabelData().getText(), formField.getConfidence()));
    }
}

OutputOutput

Analyze PDF form...
----------- Recognized custom form info for page 0 -----------
Form type: form-0
Field 'field-0' has label 'Address:' with a confidence score of 0.91.
Field 'field-1' has label 'Invoice For:' with a confidence score of 1.00.
Field 'field-2' has label 'Invoice Number' with a confidence score of 1.00.
Field 'field-3' has label 'Invoice Date' with a confidence score of 1.00.
Field 'field-4' has label 'Invoice Due Date' with a confidence score of 1.00.
Field 'field-5' has label 'Charges' with a confidence score of 1.00.
Field 'field-6' has label 'VAT ID' with a confidence score of 1.00.

Analizzare ricevuteAnalyze receipts

Questa sezione illustra come analizzare ed estrarre i campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione con training preliminare.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Per ulteriori informazioni sull'analisi della ricezione, vedere la Guida concettuale relativa alle ricevute.For more information about receipt analysis, see the Receipts conceptual guide.

Per analizzare le ricevute da un URI, usare il metodo beginRecognizeReceiptsFromUrl .To analyze receipts from a URI, use the beginRecognizeReceiptsFromUrl method.

private static void AnalyzeReceipt(FormRecognizerClient recognizerClient, String receiptUri) {
    SyncPoller<FormRecognizerOperationResult, List<RecognizedForm>> syncPoller = recognizerClient
            .beginRecognizeReceiptsFromUrl(receiptUri);
    List<RecognizedForm> receiptPageResults = syncPoller.getFinalResult();

Suggerimento

È anche possibile analizzare le immagini di ricezione locali.You can also analyze local receipt images. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeReceipts.See the FormRecognizerClient methods, such as beginRecognizeReceipts. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

Il valore restituito è una raccolta di oggetti RecognizedReceipt, uno per ogni pagina del documento inviato.The returned value is a collection of RecognizedReceipt objects: one for each page in the submitted document. Il blocco di codice successivo esegue l'iterazione delle ricevute e nel stampa i dettagli nella console.The next block of code iterates through the receipts and prints their details to the console.

for (int i = 0; i < receiptPageResults.size(); i++) {
    RecognizedForm recognizedForm = receiptPageResults.get(i);
    Map<String, FormField> recognizedFields = recognizedForm.getFields();
    System.out.printf("----------- Recognized Receipt page %d -----------%n", i);
    FormField merchantNameField = recognizedFields.get("MerchantName");
    if (merchantNameField != null) {
        if (FieldValueType.STRING == merchantNameField.getValue().getValueType()) {
            String merchantName = merchantNameField.getValue().asString();
            System.out.printf("Merchant Name: %s, confidence: %.2f%n", merchantName,
                    merchantNameField.getConfidence());
        }
    }
    FormField merchantAddressField = recognizedFields.get("MerchantAddress");
    if (merchantAddressField != null) {
        if (FieldValueType.STRING == merchantAddressField.getValue().getValueType()) {
            String merchantAddress = merchantAddressField.getValue().asString();
            System.out.printf("Merchant Address: %s, confidence: %.2f%n", merchantAddress,
                    merchantAddressField.getConfidence());
        }
    }
    FormField transactionDateField = recognizedFields.get("TransactionDate");
    if (transactionDateField != null) {
        if (FieldValueType.DATE == transactionDateField.getValue().getValueType()) {
            LocalDate transactionDate = transactionDateField.getValue().asDate();
            System.out.printf("Transaction Date: %s, confidence: %.2f%n", transactionDate,
                    transactionDateField.getConfidence());
        }
    }

Il blocco di codice successivo esegue l'iterazione dei singoli elementi rilevati nella ricevuta e stampa i relativi dettagli nella console.The next block of code iterates through the individual items detected on the receipt and prints their details to the console.

        FormField receiptItemsField = recognizedFields.get("Items");
        if (receiptItemsField != null) {
            System.out.printf("Receipt Items: %n");
            if (FieldValueType.LIST == receiptItemsField.getValue().getValueType()) {
                List<FormField> receiptItems = receiptItemsField.getValue().asList();
                receiptItems.stream()
                        .filter(receiptItem -> FieldValueType.MAP == receiptItem.getValue().getValueType())
                        .map(formField -> formField.getValue().asMap())
                        .forEach(formFieldMap -> formFieldMap.forEach((key, formField) -> {
                            if ("Name".equals(key)) {
                                if (FieldValueType.STRING == formField.getValue().getValueType()) {
                                    String name = formField.getValue().asString();
                                    System.out.printf("Name: %s, confidence: %.2fs%n", name,
                                            formField.getConfidence());
                                }
                            }
                            if ("Quantity".equals(key)) {
                                if (FieldValueType.FLOAT == formField.getValue().getValueType()) {
                                    Float quantity = formField.getValue().asFloat();
                                    System.out.printf("Quantity: %f, confidence: %.2f%n", quantity,
                                            formField.getConfidence());
                                }
                            }
                            if ("Price".equals(key)) {
                                if (FieldValueType.FLOAT == formField.getValue().getValueType()) {
                                    Float price = formField.getValue().asFloat();
                                    System.out.printf("Price: %f, confidence: %.2f%n", price,
                                            formField.getConfidence());
                                }
                            }
                            if ("TotalPrice".equals(key)) {
                                if (FieldValueType.FLOAT == formField.getValue().getValueType()) {
                                    Float totalPrice = formField.getValue().asFloat();
                                    System.out.printf("Total Price: %f, confidence: %.2f%n", totalPrice,
                                            formField.getConfidence());
                                }
                            }
                        }));
            }
        }
    }
}

OutputOutput

Analyze receipt...
----------- Recognized Receipt page 0 -----------
Merchant Name: Contoso Contoso, confidence: 0.62
Merchant Address: 123 Main Street Redmond, WA 98052, confidence: 0.99
Transaction Date: 2020-06-10, confidence: 0.90
Receipt Items:
Name: Cappuccino, confidence: 0.96s
Quantity: null, confidence: 0.957s]
Total Price: 2.200000, confidence: 0.95
Name: BACON & EGGS, confidence: 0.94s
Quantity: null, confidence: 0.927s]
Total Price: null, confidence: 0.93

Analizzare biglietti da visitaAnalyze business cards

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Gestire i modelli personalizzatiManage custom models

Questa sezione illustra come gestire modelli personalizzati archiviati nell'account.This section demonstrates how to manage the custom models stored in your account. Il codice seguente esegue tutte le attività di gestione dei modelli in un singolo metodo, come esempio.The following code does all of the model management tasks in a single method, as an example. Per iniziare, copiare la firma del metodo seguente:Start by copying the method signature below:

private static void ManageModels(FormTrainingClient trainingClient, String trainingFileUrl) {

Verificare il numero dei modelli all'interno dell'account della risorsa FormRecognizerCheck the number of models in the FormRecognizer resource account

Il blocco di codice seguente consente di controllare il numero di modelli salvati nell'account di Riconoscimento modulo e di confrontarli con il limite dell'account.The following code block checks how many models you have saved in your Form Recognizer account and compares it to the account limit.

AtomicReference<String> modelId = new AtomicReference<>();

// First, we see how many custom models we have, and what our limit is
AccountProperties accountProperties = trainingClient.getAccountProperties();
System.out.printf("The account has %s custom models, and we can have at most %s custom models",
        accountProperties.getCustomModelCount(), accountProperties.getCustomModelLimit());

OutputOutput

The account has 12 custom models, and we can have at most 250 custom models

Elencare i modelli archiviati attualmente nell'account della risorsaList the models currently stored in the resource account

Il blocco di codice seguente elenca i modelli attuali presenti nell'account e stampa i relativi dettagli nella console.The following code block lists the current models in your account and prints their details to the console.

// Next, we get a paged list of all of our custom models
PagedIterable<CustomFormModelInfo> customModels = trainingClient.listCustomModels();
System.out.println("We have following models in the account:");
customModels.forEach(customFormModelInfo -> {
    System.out.printf("Model Id: %s%n", customFormModelInfo.getModelId());
    // get custom model info
    modelId.set(customFormModelInfo.getModelId());
    CustomFormModel customModel = trainingClient.getCustomModel(customFormModelInfo.getModelId());
    System.out.printf("Model Id: %s%n", customModel.getModelId());
    System.out.printf("Model Status: %s%n", customModel.getModelStatus());
    System.out.printf("Training started on: %s%n", customModel.getTrainingStartedOn());
    System.out.printf("Training completed on: %s%n", customModel.getTrainingCompletedOn());
    customModel.getSubmodels().forEach(customFormSubmodel -> {
        System.out.printf("Custom Model Form type: %s%n", customFormSubmodel.getFormType());
        System.out.printf("Custom Model Accuracy: %.2f%n", customFormSubmodel.getAccuracy());
        if (customFormSubmodel.getFields() != null) {
            customFormSubmodel.getFields().forEach((fieldText, customFormModelField) -> {
                System.out.printf("Field Text: %s%n", fieldText);
                System.out.printf("Field Accuracy: %.2f%n", customFormModelField.getAccuracy());
            });
        }
    });
});

OutputOutput

Questa risposta è stata troncata per migliorare la leggibilità.This response has been truncated for readability.

We have following models in the account:
Model Id: 0b048b60-86cc-47ec-9782-ad0ffaf7a5ce
Model Id: 0b048b60-86cc-47ec-9782-ad0ffaf7a5ce
Model Status: ready
Training started on: 2020-06-04T18:33:08Z
Training completed on: 2020-06-04T18:33:10Z
Custom Model Form type: form-0b048b60-86cc-47ec-9782-ad0ffaf7a5ce
Custom Model Accuracy: 1.00
Field Text: invoice date
Field Accuracy: 1.00
Field Text: invoice number
Field Accuracy: 1.00
...

Eliminare un modello dall'account della risorsaDelete a model from the resource account

È inoltre possibile eliminare un modello dall'account facendo riferimento al relativo ID.You can also delete a model from your account by referencing its ID.

    // Delete Custom Model
    System.out.printf("Deleted model with model Id: %s, operation completed with status: %s%n", modelId.get(),
            trainingClient.deleteModelWithResponse(modelId.get(), Context.NONE).getStatusCode());
}

Eseguire l'applicazioneRun the application

Tornare alla directory principale del progetto.Navigate back to your main project directory. Compilare quindi l'app con il comando seguente:Then, build the app with the following command:

gradle build

Eseguire l'applicazione con il comando run:Run the application with the run goal:

gradle run

Pulire le risorseClean up resources

Se si vuole pulire e rimuovere una sottoscrizione a Servizi cognitivi, è possibile eliminare la risorsa o il gruppo di risorse.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate.Deleting the resource group also deletes any other resources associated with it.

Risoluzione dei problemiTroubleshooting

I client di Riconoscimento modulo generano le eccezioni ErrorResponseException.From Recognizer clients raise ErrorResponseException exceptions. Se ad esempio si prova a specificare un URL di origine file non valido, verrà generata un'eccezione ErrorResponseException con un messaggio che indica la causa del problema.For example, if you try to provide an invalid file source URL an ErrorResponseException would be raised with an error indicating the failure cause. Nel frammento di codice seguente l'errore viene gestito normalmente rilevando l'eccezione e visualizzando informazioni aggiuntive sull'errore.In the following code snippet, the error is handled gracefully by catching the exception and display the additional information about the error.

try {
    formRecognizerClient.beginRecognizeContentFromUrl("invalidSourceUrl");
} catch (ErrorResponseException e) {
    System.out.println(e.getMessage());
}

Abilitare la registrazione clientEnable client logging

Azure SDK per Java offre un'esperienza di registrazione coerente per facilitare la l'individuazione degli errori dell'applicazione e velocizzarne la risoluzione.Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and speeding up their resolution. I log prodotti acquisiranno il flusso di un'applicazione prima di raggiungere lo stato terminale per facilitare l'individuazione del problema radice.The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. Per informazioni sull'abilitazione della registrazione, vedere la pagina wiki corrispondente.View the logging wiki for guidance about enabling logging.

Passaggi successiviNext steps

In questo argomento di avvio rapido è stata usata la libreria client di Riconoscimento modulo per JavaP per eseguire il training di modelli e analizzare i moduli in modi diversi.In this quickstart, you used the Form Recognizer Java client library to train models and analyze forms in different ways. In seguito, è possibile ottenere suggerimenti per creare un set di dati di training migliore e produrre modelli più accurati.Next, learn tips to create a better training data set and produce more accurate models.

Importante

  • Il codice di questo articolo usa metodi sincroni e archiviazione con credenziali non protette per motivi di semplicità.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons. Vedere la documentazione di riferimento di seguito.See the reference documentation below.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (npm) | EsempiReference documentation | Library source code | Package (npm) | Samples

PrerequisitiPrerequisites

  • Sottoscrizione di Azure: creare un account gratuitoAzure subscription - Create one for free
  • Versione corrente di Node.jsThe current version of Node.js
  • Un BLOB di Archiviazione di Azure contenente un set di dati di training.An Azure Storage blob that contains a set of training data. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di un set di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data set. Per questo argomento di avvio rapido, è possibile usare i file inclusi nella cartella Train del set di dati di esempio (scaricare ed estrarre sample_data.zip).For this quickstart, you can use the files under the Train folder of the sample data set (download and extract sample_data.zip).
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Riconoscimento modulo nel portale di Azure per ottenere la chiave e l'endpoint.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.After it deploys, click Go to resource.
    • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Riconoscimento modulo.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.You'll paste your key and endpoint into the code below later in the quickstart.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

ConfigurazioneSetting up

Creare una nuova applicazione Node.jsCreate a new Node.js application

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app.In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.

mkdir myapp && cd myapp

Eseguire il comando npm init per creare un'applicazione Node con un file package.json.Run the npm init command to create a node application with a package.json file.

npm init

Installare la libreria clientInstall the client library

Installare il pacchetto NPM ai-form-recognizer:Install the ai-form-recognizer NPM package:

npm install @azure/ai-form-recognizer

Il file package.json dell'app viene aggiornato con le dipendenze.Your app's package.json file will be updated with the dependencies.

Creare un file denominato index.js, aprirlo e importare le librerie seguenti:Create a file named index.js, open it, and import the following libraries:

const { FormRecognizerClient, FormTrainingClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");
const fs = require("fs");

Suggerimento

Si vuole visualizzare l'intero file di codice dell'argomento di avvio rapido?Want to view the whole quickstart code file at once? È possibile trovarlo in GitHub, che contiene gli esempi di codice di questo argomento.You can find it on GitHub, which contains the code examples in this quickstart.

Creare le variabili per l'endpoint e la chiave di Azure della risorsa.Create variables for your resource's Azure endpoint and key.

// You will need to set these environment variables or edit the following values
const endpoint = "<paste-your-form-recognizer-endpoint-here>";
const apiKey = "<paste-your-form-recognizer-key-here>";

Importante

Accedere al portale di Azure.Go to the Azure portal. Se la risorsa di Riconoscimento modulo creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint della risorsa in Gestione risorse.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico.Remember to remove the key from your code when you're done, and never post it publicly. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali,For production, consider using a secure way of storing and accessing your credentials. Per altre informazioni, vedere l'articolo sulla sicurezza di Servizi cognitivi.See the Cognitive Services security article for more information.

Modello a oggettiObject model

Con Riconoscimento modulo è possibile creare due diversi tipi di client.With Form Recognizer, you can create two different client types. Il primo, FormRecognizerClient, viene usato per eseguire query sul servizio per riconoscere campi modulo e contenuti.The first, FormRecognizerClient is used to query the service to recognized form fields and content. Il secondo, FormTrainingClient, viene usato per creare e gestire modelli personalizzati da usare per migliorare il riconoscimento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient fornisce le operazioni per:FormRecognizerClient provides operations for:

  • Riconoscimento dei campi del modulo e del contenuto con modelli personalizzati con training per l'analisi dei moduli personalizzati.Recognizing form fields and content using custom models trained to analyze your custom forms. Questi valori vengono restituiti in una raccolta di oggetti RecognizedForm.These values are returned in a collection of RecognizedForm objects.
  • Riconoscere i contenuti dei moduli, incluse tabelle, righe e parole, senza la necessità di eseguire il training di un modello.Recognizing form content, including tables, lines and words, without the need to train a model. I contenuti dei moduli vengono restituiti in una raccolta di oggetti FormPage.Form content is returned in a collection of FormPage objects.
  • Riconoscere i campi comuni delle ricevute, usando un modello di ricevuta con training preliminare nel servizio Riconoscimento modulo.Recognizing common fields from receipts, using a pre-trained receipt model on the Form Recognizer service. Questi campi e i metadati vengono restituiti in una raccolta di oggetti RecognizedReceipt.These fields and meta-data are returned in a collection of RecognizedReceipt.

FormTrainingClientFormTrainingClient

FormTrainingClient fornisce le operazioni per:FormTrainingClient provides operations for:

  • Training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati.Training custom models to analyze all fields and values found in your custom forms. CustomFormModelViene restituito un oggetto che indica i tipi di form che verrà analizzato dal modello e i campi da estrarre per ogni tipo di form.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type. Per una spiegazione più dettagliata della creazione di un training set, vedere la documentazione del servizio sul training di modelli non etichettati.See the service's documentation on unlabeled model training for a more detailed explanation of creating a training data set.
  • Training di modelli personalizzati per l'analisi di campi e valori specifici specificati tramite l'assegnazione di etichette ai moduli personalizzati.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Viene restituito un CustomFormModel che indica i campi che verranno estratti dal modello e l'accuratezza stimata per ogni campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field. Per una spiegazione più dettagliata dell'applicazione di etichette a un training set, vedere la documentazione del servizio sul training di modelli etichettati.See the service's documentation on labeled model training for a more detailed explanation of applying labels to a training data set.
  • Gestire i modelli creati nell'account.Managing models created in your account.
  • Copiare un modello personalizzato da una risorsa Riconoscimento modulo a un'altra.Copying a custom model from one Form Recognizer resource to another.

Nota

È possibile eseguire il training dei modelli anche con un'interfaccia utente grafica, ad esempio con lo strumento di etichettatura di Riconoscimento modulo.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Esempi di codiceCode examples

Questi frammenti di codice mostrano come eseguire le attività seguenti con la libreria client di Riconoscimento modulo per JavaScript:These code snippets show you how to do the following tasks with the Form Recognizer client library for JavaScript:

Autenticare il clientAuthenticate the client

Eseguire l'autenticazione di un oggetto client usando le variabili di sottoscrizione definite in precedenza.Authenticate a client object using the subscription variables you defined. Si userà un oggetto AzureKeyCredential in modo che, se necessario, sia possibile aggiornare la chiave API senza creare nuovi oggetti client.You'll use an AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects. Verrà inoltre creato un oggetto client di training.You'll also create a training client object.

const trainingClient = new FormTrainingClient(endpoint, new AzureKeyCredential(apiKey));
const client = new FormRecognizerClient(endpoint, new AzureKeyCredential(apiKey));

Ottenere le risorse per il testGet assets for testing

Sarà inoltre necessario aggiungere riferimenti agli URL per i dati di training e di test.You'll also need to add references to the URLs for your training and testing data.

  • Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

  • Usare il modulo di esempio e le immagini di ricevute inclusi negli esempi seguenti (disponibili anche in GitHub) oppure usare la procedura precedente per ottenere l'URL di firma di accesso condiviso di un singolo documento nell'archivio BLOB.Use the sample from and receipt images included in the samples below (also available on GitHub) or you can use the above steps to get the SAS URL of an individual document in blob storage.

Analizzare il layoutAnalyze layout

È possibile utilizzare il riconoscimento moduli per analizzare tabelle, righe e parole nei documenti, senza dover eseguire il training di un modello.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Per ulteriori informazioni sull'estrazione del layout, vedere la Guida concettuale sul layout.For more information about layout extraction see the Layout conceptual guide. Per analizzare il contenuto di un file in un URI specificato, utilizzare il beginRecognizeContentFromUrl metodo.To analyze the content of a file at a given URI, use the beginRecognizeContentFromUrl method.

async function recognizeContent() {
    const formUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/simple-invoice.png";
    const poller = await client.beginRecognizeContentFromUrl(formUrl);
    const pages = await poller.pollUntilDone();

    if (!pages || pages.length === 0) {
        throw new Error("Expecting non-empty list of pages!");
    }

    for (const page of pages) {
        console.log(
            `Page ${page.pageNumber}: width ${page.width} and height ${page.height} with unit ${page.unit}`
        );
        for (const table of page.tables) {
            for (const cell of table.cells) {
                console.log(`cell [${cell.rowIndex},${cell.columnIndex}] has text ${cell.text}`);
            }
        }
    }
}

recognizeContent().catch((err) => {
    console.error("The sample encountered an error:", err);
});

Suggerimento

È anche possibile ottenere contenuto da un file locale.You can also get content from a local file. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeContent.See the FormRecognizerClient methods, such as beginRecognizeContent. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

Page 1: width 8.5 and height 11 with unit inch
cell [0,0] has text Invoice Number
cell [0,1] has text Invoice Date
cell [0,2] has text Invoice Due Date
cell [0,3] has text Charges
cell [0,5] has text VAT ID
cell [1,0] has text 34278587
cell [1,1] has text 6/18/2017
cell [1,2] has text 6/24/2017
cell [1,3] has text $56,651.49
cell [1,5] has text PT

Eseguire il training di un modello personalizzatoTrain a custom model

Questa sezione illustra come eseguire il training di un modello con i dati personali.This section demonstrates how to train a model with your own data. Un modello sottoposto a training restituisce dati strutturati che includono le relazioni chiave-valore del file originale.A trained model can output structured data that includes the key/value relationships in the original form document. Dopo il training del modello, è possibile testarlo, ripeterne il training e infine usarlo per estrarre dati in modo affidabile da altri moduli in base alle proprie esigenze.After you train the model, you can test and retrain it and eventually use it to reliably extract data from more forms according to your needs.

Nota

È anche possibile eseguire il training dei modelli con un'interfaccia utente grafica, ad esempio con lo Strumento di etichettatura campioni Riconoscimento modulo.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Eseguire il training di un modello senza etichetteTrain a model without labels

Eseguire il training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati senza etichettare manualmente i documenti di training.Train custom models to analyze all the fields and values found in your custom forms without manually labeling the training documents.

La funzione seguente esegue il training di un modello su un set di documenti specificato e ne stampa lo stato nella console.The following function trains a model on a given set of documents and prints the model's status to the console.

async function trainModel() {

    const containerSasUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>";

    const poller = await trainingClient.beginTraining(containerSasUrl, false, {
        onProgress: (state) => { console.log(`training status: ${state.status}`); }
    });
    const model = await poller.pollUntilDone();

    if (!model) {
        throw new Error("Expecting valid training result!");
    }

    console.log(`Model ID: ${model.modelId}`);
    console.log(`Status: ${model.status}`);
    console.log(`Training started on: ${model.trainingStartedOn}`);
    console.log(`Training completed on: ${model.trainingCompletedOn}`);

    if (model.submodels) {
        for (const submodel of model.submodels) {
            // since the training data is unlabeled, we are unable to return the accuracy of this model
            console.log("We have recognized the following fields");
            for (const key in submodel.fields) {
                const field = submodel.fields[key];
                console.log(`The model found field '${field.name}'`);
            }
        }
    }
    // Training document information
    if (model.trainingDocuments) {
        for (const doc of model.trainingDocuments) {
            console.log(`Document name: ${doc.name}`);
            console.log(`Document status: ${doc.status}`);
            console.log(`Document page count: ${doc.pageCount}`);
            console.log(`Document errors: ${doc.errors}`);
        }
    }
}

trainModel().catch((err) => {
    console.error("The sample encountered an error:", err);
});

OutputOutput

Questo è l'output di un modello sottoposto a training con i dati di training disponibili in JavaScript SDK. Questo output di esempio è stato troncato per migliorare la leggibilità.This is the output for a model trained with the training data available from the JavaScript SDK.This sample output has been truncated for readability.

training status: creating
training status: ready
Model ID: 9d893595-1690-4cf2-a4b1-fbac0fb11909
Status: ready
Training started on: Thu Aug 20 2020 20:27:26 GMT-0700 (Pacific Daylight Time)
Training completed on: Thu Aug 20 2020 20:27:37 GMT-0700 (Pacific Daylight Time)
We have recognized the following fields
The model found field 'field-0'
The model found field 'field-1'
The model found field 'field-2'
The model found field 'field-3'
The model found field 'field-4'
The model found field 'field-5'
The model found field 'field-6'
The model found field 'field-7'
...
Document name: Form_1.jpg
Document status: succeeded
Document page count: 1
Document errors: 
Document name: Form_2.jpg
Document status: succeeded
Document page count: 1
Document errors: 
Document name: Form_3.jpg
Document status: succeeded
Document page count: 1
Document errors: 
...

Eseguire il training di un modello con etichetteTrain a model with labels

È inoltre possibile eseguire il training di modelli personalizzati etichettando manualmente i documenti di training.You can also train custom models by manually labeling the training documents. Il training con etichette consente prestazioni migliori in alcuni scenari.Training with labels leads to better performance in some scenarios. Per eseguire il training con etichette, è necessario avere file speciali di informazioni sulle etichette (\<filename\>.pdf.labels.json) nel contenitore di archiviazione BLOB insieme ai documenti di training.To train with labels, you need to have special label information files (\<filename\>.pdf.labels.json) in your blob storage container alongside the training documents. Lo Strumento di etichettatura campioni Riconoscimento modulo fornisce un'interfaccia utente che consente di creare questi file di etichette.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Quando sono disponibili è possibile chiamare il metodo beginTraining con il parametro uselabels impostato su true.Once you have them, you can call the beginTraining method with the uselabels parameter set to true.

async function trainModelLabels() {

    const containerSasUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>";

    const poller = await trainingClient.beginTraining(containerSasUrl, true, {
        onProgress: (state) => { console.log(`training status: ${state.status}`); }
    });
    const model = await poller.pollUntilDone();

    if (!model) {
        throw new Error("Expecting valid training result!");
    }

    console.log(`Model ID: ${model.modelId}`);
    console.log(`Status: ${model.status}`);
    console.log(`Training started on: ${model.trainingStartedOn}`);
    console.log(`Training completed on: ${model.trainingCompletedOn}`);

    if (model.submodels) {
        for (const submodel of model.submodels) {
            // since the training data is unlabeled, we are unable to return the accuracy of this model
            console.log("We have recognized the following fields");
            for (const key in submodel.fields) {
                const field = submodel.fields[key];
                console.log(`The model found field '${field.name}'`);
            }
        }
    }
    // Training document information
    if (model.trainingDocuments) {
        for (const doc of model.trainingDocuments) {
            console.log(`Document name: ${doc.name}`);
            console.log(`Document status: ${doc.status}`);
            console.log(`Document page count: ${doc.pageCount}`);
            console.log(`Document errors: ${doc.errors}`);
        }
    }
}

trainModelLabels().catch((err) => {
    console.error("The sample encountered an error:", err);
});

OutputOutput

Questo è l'output di un modello sottoposto a training con i dati di training disponibili in JavaScript SDK. Questo output di esempio è stato troncato per migliorare la leggibilità.This is the output for a model trained with the training data available from the JavaScript SDK.This sample output has been truncated for readability.

training status: creating
training status: ready
Model ID: 789b1b37-4cc3-4e36-8665-9dde68618072
Status: ready
Training started on: Thu Aug 20 2020 20:30:37 GMT-0700 (Pacific Daylight Time)
Training completed on: Thu Aug 20 2020 20:30:43 GMT-0700 (Pacific Daylight Time)
We have recognized the following fields
The model found field 'CompanyAddress'
The model found field 'CompanyName'
The model found field 'CompanyPhoneNumber'
The model found field 'DatedAs'
...
Document name: Form_1.jpg
Document status: succeeded
Document page count: 1
Document errors: undefined
Document name: Form_2.jpg
Document status: succeeded
Document page count: 1
Document errors: undefined
Document name: Form_3.jpg
Document status: succeeded
Document page count: 1
Document errors: undefined
...

Analizzare i moduli con un modello personalizzatoAnalyze forms with a custom model

Questa sezione illustra come estrarre informazioni chiave-valore e altro contenuto dai tipi di modulo personalizzati, usando i modelli a cui è stato eseguito il training con moduli personalizzati.This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.

Importante

Per implementare questo scenario è necessario avere già eseguito il training di un modello in modo da poter passare il relativo ID al metodo seguente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Vedere la sezione Eseguire il training di un modello.See the Train a model section.

Verrà usato il metodo beginRecognizeCustomFormsFromUrl.You'll use the beginRecognizeCustomFormsFromUrl method. Il valore restituito è una raccolta di oggetti RecognizedForm: uno per ogni pagina nel documento inviato.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document.

async function recognizeCustom() {
    // Model ID from when you trained your model.
    const modelId = "<modelId>";
    const formUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/simple-invoice.png";

    const poller = await client.beginRecognizeCustomForms(modelId, formUrl, {
        onProgress: (state) => { console.log(`status: ${state.status}`); }
    });
    const forms = await poller.pollUntilDone();

    console.log("Forms:");
    for (const form of forms || []) {
        console.log(`${form.formType}, page range: ${form.pageRange}`);
        console.log("Pages:");
        for (const page of form.pages || []) {
            console.log(`Page number: ${page.pageNumber}`);
            console.log("Tables");
            for (const table of page.tables || []) {
                for (const cell of table.cells) {
                    console.log(`cell (${cell.rowIndex},${cell.columnIndex}) ${cell.text}`);
                }
            }
        }

        console.log("Fields:");
        for (const fieldName in form.fields) {
            // each field is of type FormField
            const field = form.fields[fieldName];
            console.log(
                `Field ${fieldName} has value '${field.value}' with a confidence score of ${field.confidence}`
            );
        }
    }
}

recognizeCustom().catch((err) => {
    console.error("The sample encountered an error:", err);
});

Suggerimento

È anche possibile analizzare i file locali.You can also analyze local files. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeCustomForms.See the FormRecognizerClient methods, such as beginRecognizeCustomForms. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

status: notStarted
status: succeeded
Forms:
custom:form, page range: [object Object]
Pages:
Page number: 1
Tables
cell (0,0) Invoice Number
cell (0,1) Invoice Date
cell (0,2) Invoice Due Date
cell (0,3) Charges
cell (0,5) VAT ID
cell (1,0) 34278587
cell (1,1) 6/18/2017
cell (1,2) 6/24/2017
cell (1,3) $56,651.49
cell (1,5) PT
Fields:
Field Merchant has value 'Invoice For:' with a confidence score of 0.116
Field CompanyPhoneNumber has value '$56,651.49' with a confidence score of 0.249
Field VendorName has value 'Charges' with a confidence score of 0.145
Field CompanyAddress has value '1 Redmond way Suite 6000 Redmond, WA' with a confidence score of 0.258
Field CompanyName has value 'PT' with a confidence score of 0.245
Field Website has value '99243' with a confidence score of 0.114
Field DatedAs has value 'undefined' with a confidence score of undefined
Field Email has value 'undefined' with a confidence score of undefined
Field PhoneNumber has value 'undefined' with a confidence score of undefined
Field PurchaseOrderNumber has value 'undefined' with a confidence score of undefined
Field Quantity has value 'undefined' with a confidence score of undefined
Field Signature has value 'undefined' with a confidence score of undefined
Field Subtotal has value 'undefined' with a confidence score of undefined
Field Tax has value 'undefined' with a confidence score of undefined
Field Total has value 'undefined' with a confidence score of undefined

Analizzare ricevuteAnalyze receipts

Questa sezione illustra come analizzare ed estrarre i campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione con training preliminare.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Per ulteriori informazioni sull'analisi della ricezione, vedere la Guida concettuale relativa alle ricevute.For more information about receipt analysis, see the Receipts conceptual guide.

Per analizzare le ricevute da un URI, usare il beginRecognizeReceiptsFromUrl metodo.To analyze receipts from a URI, use the beginRecognizeReceiptsFromUrl method. Il codice seguente elabora una ricevuta in corrispondenza dell'URI specificato e stampa i campi e i valori principali nella console.The following code processes a receipt at the given URI and prints the major fields and values to the console.

async function recognizeReceipt() {
    receiptUrl = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/master/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png";
    const poller = await client.beginRecognizeReceiptsFromUrl(receiptUrl, {
        onProgress: (state) => { console.log(`status: ${state.status}`); }
    });

    const receipts = await poller.pollUntilDone();

    if (!receipts || receipts.length <= 0) {
        throw new Error("Expecting at lease one receipt in analysis result");
    }

    const receipt = receipts[0];
    console.log("First receipt:");
    const receiptTypeField = receipt.fields["ReceiptType"];
    if (receiptTypeField.valueType === "string") {
        console.log(`  Receipt Type: '${receiptTypeField.value || "<missing>"}', with confidence of ${receiptTypeField.confidence}`);
    }
    const merchantNameField = receipt.fields["MerchantName"];
    if (merchantNameField.valueType === "string") {
        console.log(`  Merchant Name: '${merchantNameField.value || "<missing>"}', with confidence of ${merchantNameField.confidence}`);
    }
    const transactionDate = receipt.fields["TransactionDate"];
    if (transactionDate.valueType === "date") {
        console.log(`  Transaction Date: '${transactionDate.value || "<missing>"}', with confidence of ${transactionDate.confidence}`);
    }
    const itemsField = receipt.fields["Items"];
    if (itemsField.valueType === "array") {
        for (const itemField of itemsField.value || []) {
            if (itemField.valueType === "object") {
                const itemNameField = itemField.value["Name"];
                if (itemNameField.valueType === "string") {
                    console.log(`    Item Name: '${itemNameField.value || "<missing>"}', with confidence of ${itemNameField.confidence}`);
                }
            }
        }
    }
    const totalField = receipt.fields["Total"];
    if (totalField.valueType === "number") {
        console.log(`  Total: '${totalField.value || "<missing>"}', with confidence of ${totalField.confidence}`);
    }
}

recognizeReceipt().catch((err) => {
    console.error("The sample encountered an error:", err);
});

Suggerimento

È anche possibile analizzare le immagini di ricezione locali.You can also analyze local receipt images. Vedere i metodi FormRecognizerClient, ad esempio beginRecognizeReceipts.See the FormRecognizerClient methods, such as beginRecognizeReceipts. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

status: notStarted
status: running
status: succeeded
First receipt:
  Receipt Type: 'Itemized', with confidence of 0.659
  Merchant Name: 'Contoso Contoso', with confidence of 0.516
  Transaction Date: 'Sun Jun 09 2019 17:00:00 GMT-0700 (Pacific Daylight Time)', with confidence of 0.985
    Item Name: '8GB RAM (Black)', with confidence of 0.916
    Item Name: 'SurfacePen', with confidence of 0.858
  Total: '1203.39', with confidence of 0.774

Gestire i modelli personalizzatiManage your custom models

Questa sezione illustra come gestire modelli personalizzati archiviati nell'account.This section demonstrates how to manage the custom models stored in your account. Il codice seguente esegue tutte le attività di gestione dei modelli in una singola funzione, come esempio.The following code does all of the model management tasks in a single function, as an example.

Ottenere il numero di modelliGet number of models

Il blocco di codice seguente ottiene il numero di modelli attualmente presenti nell'account.The following code block gets the number of models currently in your account.

async function countModels() {
    // First, we see how many custom models we have, and what our limit is
    const accountProperties = await trainingClient.getAccountProperties();
    console.log(
        `Our account has ${accountProperties.customModelCount} custom models, and we can have at most ${accountProperties.customModelLimit} custom models`
    );
}
countModels().catch((err) => {
    console.error("The sample encountered an error:", err);
});

Ottenere l'elenco di modelli nell'accountGet list of models in account

Il blocco di codice seguente fornisce un elenco completo dei modelli disponibili nell'account, incluse le informazioni sulla data di creazione del modello e sullo stato corrente.The following code block provides a full list of available models in your account including information about when the model was created and its current status.

async function listModels() {

    // returns an async iteratable iterator that supports paging
    const result = trainingClient.listCustomModels();
    let i = 0;
    for await (const modelInfo of result) {
        console.log(`model ${i++}:`);
        console.log(modelInfo);
    }
}

listModels().catch((err) => {
    console.error("The sample encountered an error:", err);
});

OutputOutput

model 0:
{
  modelId: '453cc2e6-e3eb-4e9f-aab6-e1ac7b87e09e',
  status: 'invalid',
  trainingStartedOn: 2020-08-20T22:28:52.000Z,
  trainingCompletedOn: 2020-08-20T22:28:53.000Z
}
model 1:
{
  modelId: '628739de-779c-473d-8214-d35c72d3d4f7',
  status: 'ready',
  trainingStartedOn: 2020-08-20T23:16:51.000Z,
  trainingCompletedOn: 2020-08-20T23:16:59.000Z
}
model 2:
{
  modelId: '789b1b37-4cc3-4e36-8665-9dde68618072',
  status: 'ready',
  trainingStartedOn: 2020-08-21T03:30:37.000Z,
  trainingCompletedOn: 2020-08-21T03:30:43.000Z
}
model 3:
{
  modelId: '9d893595-1690-4cf2-a4b1-fbac0fb11909',
  status: 'ready',
  trainingStartedOn: 2020-08-21T03:27:26.000Z,
  trainingCompletedOn: 2020-08-21T03:27:37.000Z
}

Ottenere l'elenco degli ID modello per paginaGet list of model IDs by page

Questo blocco di codice fornisce un elenco impaginato di modelli e ID modello.This code block provides a paginated list of models and model IDs.

async function listModelsByPage() {
    // using `byPage()`
    i = 1;
    for await (const response of trainingClient.listCustomModels().byPage()) {
        for (const modelInfo of response.modelList) {
            console.log(`model ${i++}: ${modelInfo.modelId}`);
        }
    }
}
listModelsByPage().catch((err) => {
    console.error("The sample encountered an error:", err);
});

OutputOutput

model 1: 453cc2e6-e3eb-4e9f-aab6-e1ac7b87e09e
model 2: 628739de-779c-473d-8214-d35c72d3d4f7
model 3: 789b1b37-4cc3-4e36-8665-9dde68618072

Ottenere il modello in base all'IDGet model by ID

La funzione seguente ottiene l'oggetto modello corrispondente a un ID modello.The following function takes a model ID and gets the matching model object. Questa funzione non viene chiamata per impostazione predefinita.This function isn't called by default.

async function getModel(modelId) {
    // Now we'll get the first custom model in the paged list
    const model = await client.getCustomModel(modelId);
    console.log("--- First Custom Model ---");
    console.log(`Model Id: ${model.modelId}`);
    console.log(`Status: ${model.status}`);
    console.log("Documents used in training:");
    for (const doc of model.trainingDocuments || []) {
        console.log(`- ${doc.name}`);
    }
}

Eliminare un modello dall'account della risorsaDelete a model from the resource account

È inoltre possibile eliminare un modello dall'account facendo riferimento al relativo ID.You can also delete a model from your account by referencing its ID. Questa funzione elimina il modello con l'ID specificato.This function deletes the model with the given ID. Questa funzione non viene chiamata per impostazione predefinita.This function isn't called by default.

async function deleteModel(modelId) {
    await client.deleteModel(modelId);
    try {
        const deleted = await client.getCustomModel(modelId);
        console.log(deleted);
    } catch (err) {
        // Expected
        console.log(`Model with id ${modelId} has been deleted`);
    }
}

OutputOutput

Model with id 789b1b37-4cc3-4e36-8665-9dde68618072 has been deleted

Eseguire l'applicazioneRun the application

Eseguire l'applicazione con il comando node nel file quickstart.Run the application with the node command on your quickstart file.

node index.js

Pulire le risorseClean up resources

Se si vuole pulire e rimuovere una sottoscrizione a Servizi cognitivi, è possibile eliminare la risorsa o il gruppo di risorse.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate.Deleting the resource group also deletes any other resources associated with it.

Risoluzione dei problemiTroubleshooting

Abilitare i logEnable logs

È possibile impostare la variabile di ambiente seguente per visualizzare i log di debug quando si usa questa libreria.You can set the following environment variable to see debug logs when using this library.

export DEBUG=azure*

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione sul pacchetto @azure/logger.For more detailed instructions on how to enable logs, see the @azure/logger package docs.

Passaggi successiviNext steps

In questo argomento di avvio rapido è stata usata la libreria client di Riconoscimento modulo per JavaScript per eseguire il training di modelli e analizzare i moduli in modi diversi.In this quickstart, you used the Form Recognizer JavaScript client library to train models and analyze forms in different ways. In seguito, è possibile ottenere suggerimenti per creare un set di dati di training migliore e produrre modelli più accurati.Next, learn tips to create a better training data set and produce more accurate models.

Vedere ancheSee also

Importante

  • Il codice di questo articolo usa metodi sincroni e archiviazione con credenziali non protette per motivi di semplicità.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons. Vedere la documentazione di riferimento di seguito.See the reference documentation below.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (PyPi) | EsempiReference documentation | Library source code | Package (PyPi) | Samples

PrerequisitiPrerequisites

  • Sottoscrizione di Azure: creare un account gratuitoAzure subscription - Create one for free
  • Python 3.xPython 3.x
  • Un BLOB di Archiviazione di Azure contenente un set di dati di training.An Azure Storage blob that contains a set of training data. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di un set di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data set. Per questo argomento di avvio rapido, è possibile usare i file inclusi nella cartella Train del set di dati di esempio (scaricare ed estrarre sample_data.zip).For this quickstart, you can use the files under the Train folder of the sample data set (download and extract sample_data.zip).
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Riconoscimento modulo nel portale di Azure per ottenere la chiave e l'endpoint.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.After it deploys, click Go to resource.
    • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Riconoscimento modulo.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.You'll paste your key and endpoint into the code below later in the quickstart.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

ConfigurazioneSetting up

Installare la libreria clientInstall the client library

Dopo l'installazione di Python, è possibile installare la versione più recente della libreria client di Riconoscimento modulo con:After installing Python, you can install the latest version of the Form Recognizer client library with:

pip install azure-ai-formrecognizer

Nota

L'ultima versione di Riconoscimento modulo corrisponde alla versione 2.0 dell'APIThe latest Form Recognizer reflects API version 2.0

Creare una nuova applicazione PythonCreate a new python application

Creare una nuova applicazione Python nell'ambiente di sviluppo integrato o nell'editor preferito.Create a new Python application in your preferred editor or IDE. Importare quindi le librerie seguenti.Then import the following libraries.

import os
from azure.core.exceptions import ResourceNotFoundError
from azure.ai.formrecognizer import FormRecognizerClient
from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

Suggerimento

Si vuole visualizzare l'intero file di codice dell'argomento di avvio rapido?Want to view the whole quickstart code file at once? È possibile trovarlo in GitHub, che contiene gli esempi di codice di questo argomento.You can find it on GitHub, which contains the code examples in this quickstart.

Creare le variabili per l'endpoint e la chiave di Azure della risorsa.Create variables for your resource's Azure endpoint and key.

endpoint = "<paste-your-form-recognizer-endpoint-here>"
key = "<paste-your-form-recognizer-key-here>"  

Modello a oggettiObject model

Con Riconoscimento modulo è possibile creare due diversi tipi di client.With Form Recognizer, you can create two different client types. Il primo, form_recognizer_client, viene usato per eseguire query sul servizio per riconoscere campi modulo e contenuti.The first, form_recognizer_client is used to query the service to recognized form fields and content. Il secondo, form_training_client, viene usato per creare e gestire modelli personalizzati da usare per migliorare il riconoscimento.The second, form_training_client is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

form_recognizer_client fornisce le operazioni per:form_recognizer_client provides operations for:

  • Riconoscimento dei campi del modulo e del contenuto con modelli personalizzati con training per l'analisi dei moduli personalizzati.Recognizing form fields and content using custom models trained to analyze your custom forms.
  • Riconoscere i contenuti dei moduli, incluse tabelle, righe e parole, senza la necessità di eseguire il training di un modello.Recognizing form content, including tables, lines and words, without the need to train a model.
  • Riconoscere i campi comuni delle ricevute, usando un modello di ricevuta con training preliminare nel servizio Riconoscimento modulo.Recognizing common fields from receipts, using a pre-trained receipt model on the Form Recognizer service.

FormTrainingClientFormTrainingClient

form_training_client fornisce le operazioni per:form_training_client provides operations for:

  • Training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati.Training custom models to analyze all fields and values found in your custom forms. Per una spiegazione più dettagliata della creazione di un training set, vedere la documentazione del servizio sul training di modelli non etichettati.See the service's documentation on unlabeled model training for a more detailed explanation of creating a training data set.
  • Training di modelli personalizzati per l'analisi di campi e valori specifici specificati tramite l'assegnazione di etichette ai moduli personalizzati.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Per una spiegazione più dettagliata dell'applicazione di etichette a un training set, vedere la documentazione del servizio sul training di modelli etichettati.See the service's documentation on labeled model training for a more detailed explanation of applying labels to a training data set.
  • Gestire i modelli creati nell'account.Managing models created in your account.
  • Copiare un modello personalizzato da una risorsa Riconoscimento modulo a un'altra.Copying a custom model from one Form Recognizer resource to another.

Nota

È possibile eseguire il training dei modelli anche con un'interfaccia utente grafica, ad esempio con lo strumento di etichettatura di Riconoscimento modulo.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Esempi di codiceCode examples

Questi frammenti di codice mostrano come eseguire le attività seguenti con la libreria client di Riconoscimento modulo per Python:These code snippets show you how to do the following tasks with the Form Recognizer client library for Python:

Autenticare il clientAuthenticate the client

In questo caso si eseguirà l'autenticazione dei due oggetti client con le variabili di sottoscrizione definite in precedenza.Here, you'll authenticate two client objects using the subscription variables you defined above. Si userà un oggetto AzureKeyCredential in modo che, se necessario, sia possibile aggiornare la chiave API senza creare nuovi oggetti client.You'll use an AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects.

form_recognizer_client = FormRecognizerClient(endpoint, AzureKeyCredential(key))
form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))

Ottenere le risorse per il testGet assets for testing

Sarà necessario aggiungere riferimenti agli URL per i dati di training e di test.You'll need to add references to the URLs for your training and testing data.

  • Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

  • Usare il modulo di esempio e le immagini di ricevute inclusi negli esempi seguenti (disponibili anche in GitHub) oppure usare la procedura precedente per ottenere l'URL di firma di accesso condiviso di un singolo documento nell'archivio BLOB.Use the sample from and receipt images included in the samples below (also available on GitHub or you can use the above steps to get the SAS URL of an individual document in blob storage.

Nota

I frammenti di codice di questa guida usano i moduli remoti a cui si accede tramite URL.The code snippets in this guide use remote forms accessed by URLs. Se invece si desidera elaborare i documenti del modulo locale, vedere i metodi correlati nella documentazione di riferimento e negli esempi.If you want to process local form documents instead, see the related methods in the reference documentation and samples.

Analizzare il layoutAnalyze layout

È possibile utilizzare il riconoscimento moduli per analizzare tabelle, righe e parole nei documenti, senza dover eseguire il training di un modello.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Per ulteriori informazioni sull'estrazione del layout, vedere la Guida concettuale sul layout.For more information about layout extraction see the Layout conceptual guide.

Per analizzare il contenuto di un file in un determinato URL, utilizzare il begin_recognize_content_from_url metodo.To analyze the content of a file at a given URL, use the begin_recognize_content_from_url method. Il valore restituito è una raccolta di oggetti FormPage: uno per ogni pagina nel documento inviato.The returned value is a collection of FormPage objects: one for each page in the submitted document. Il codice seguente esegue l'iterazione di questi oggetti e stampa le coppie chiave-valore estratte con i dati della tabella.The following code iterates through these objects and prints the extracted key/value pairs and table data.

formUrl = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/master/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/forms/Form_1.jpg"

poller = form_recognizer_client.begin_recognize_content_from_url(formUrl)
page = poller.result()

table = page[0].tables[0] # page 1, table 1
print("Table found on page {}:".format(table.page_number))
for cell in table.cells:
    print("Cell text: {}".format(cell.text))
    print("Location: {}".format(cell.bounding_box))
    print("Confidence score: {}\n".format(cell.confidence))

Suggerimento

È anche possibile ottenere contenuto dalle immagini locali.You can also get content from local images. Vedere i metodi FormRecognizerClient, ad esempio begin_recognize_content.See the FormRecognizerClient methods, such as begin_recognize_content. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

Table found on page 1:
Cell text: Invoice Number
Location: [Point(x=0.5075, y=2.8088), Point(x=1.9061, y=2.8088), Point(x=1.9061, y=3.3219), Point(x=0.5075, y=3.3219)]
Confidence score: 1.0

Cell text: Invoice Date
Location: [Point(x=1.9061, y=2.8088), Point(x=3.3074, y=2.8088), Point(x=3.3074, y=3.3219), Point(x=1.9061, y=3.3219)]
Confidence score: 1.0

Cell text: Invoice Due Date
Location: [Point(x=3.3074, y=2.8088), Point(x=4.7074, y=2.8088), Point(x=4.7074, y=3.3219), Point(x=3.3074, y=3.3219)]
Confidence score: 1.0

Cell text: Charges
Location: [Point(x=4.7074, y=2.8088), Point(x=5.386, y=2.8088), Point(x=5.386, y=3.3219), Point(x=4.7074, y=3.3219)]
Confidence score: 1.0
...

Analizzare fattureAnalyze invoices

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Eseguire il training di un modello personalizzatoTrain a custom model

Questa sezione illustra come eseguire il training di un modello con i dati personali.This section demonstrates how to train a model with your own data. Un modello sottoposto a training restituisce dati strutturati che includono le relazioni chiave-valore del file originale.A trained model can output structured data that includes the key/value relationships in the original form document. Dopo il training del modello, è possibile testarlo, ripeterne il training e infine usarlo per estrarre dati in modo affidabile da altri moduli in base alle proprie esigenze.After you train the model, you can test and retrain it and eventually use it to reliably extract data from more forms according to your needs.

Nota

È anche possibile eseguire il training dei modelli con un'interfaccia utente grafica, ad esempio con lo Strumento di etichettatura campioni Riconoscimento modulo.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Eseguire il training di un modello senza etichetteTrain a model without labels

Eseguire il training di modelli personalizzati per analizzare tutti i campi e i valori trovati nei moduli personalizzati senza etichettare manualmente i documenti di training.Train custom models to analyze all fields and values found in your custom forms without manually labeling the training documents.

Il codice seguente usa il client di training con la funzione begin_training per eseguire il training di un modello in un determinato set di documenti.The following code uses the training client with the begin_training function to train a model on a given set of documents. L' CustomFormModel oggetto restituito contiene informazioni sui tipi di form che il modello è in grado di analizzare e sui campi che è possibile estrarre da ogni tipo di form.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

# To train a model you need an Azure Storage account.
# Use the SAS URL to access your training files.
trainingDataUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>"

poller = form_training_client.begin_training(trainingDataUrl, use_training_labels=False)
model = poller.result()

print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

OutputOutput

Questo è l'output di un modello sottoposto a training con i dati di training disponibili in Python SDK.This is the output for a model trained with the training data available from the Python SDK.

Model ID: 628739de-779c-473d-8214-d35c72d3d4f7
Status: ready
Training started on: 2020-08-20 23:16:51+00:00
Training completed on: 2020-08-20 23:16:59+00:00

Recognized fields:
The submodel with form type 'form-0' has recognized the following fields: Additional Notes:, Address:, Company Name:, Company Phone:, Dated As:, Details, Email:, Hero Limited, Name:, Phone:, Purchase Order, Purchase Order #:, Quantity, SUBTOTAL, Seattle, WA 93849 Phone:, Shipped From, Shipped To, TAX, TOTAL, Total, Unit Price, Vendor Name:, Website:
Document name: Form_1.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_2.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_3.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_4.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_5.jpg
Document status: succeeded
Document page count: 1
Document errors: []

Eseguire il training di un modello con etichetteTrain a model with labels

È inoltre possibile eseguire il training di modelli personalizzati etichettando manualmente i documenti di training.You can also train custom models by manually labeling the training documents. Il training con etichette consente prestazioni migliori in alcuni scenari.Training with labels leads to better performance in some scenarios. L'oggetto CustomFormModel restituito indica i campi che il modello può estrarre, oltre all'accuratezza stimata in ogni campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. Il blocco di codice seguente stampa queste informazioni all'interno della console.The following code block prints this information to the console.

Importante

Per eseguire il training con etichette, è necessario avere file speciali di informazioni sulle etichette (\<filename\>.pdf.labels.json) nel contenitore di archiviazione BLOB insieme ai documenti di training.To train with labels, you need to have special label information files (\<filename\>.pdf.labels.json) in your blob storage container alongside the training documents. Lo Strumento di etichettatura campioni Riconoscimento modulo fornisce un'interfaccia utente che consente di creare questi file di etichette.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Una volta creati, è possibile chiamare la funzione begin_training con il parametro use_training_labels impostato su true.Once you have them, you can call the begin_training function with the use_training_labels parameter set to true.

# To train a model you need an Azure Storage account.
# Use the SAS URL to access your training files.
trainingDataUrl = "<SAS-URL-of-your-form-folder-in-blob-storage>"

poller = form_training_client.begin_training(trainingDataUrl, use_training_labels=True)
model = poller.result()

print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

OutputOutput

Questo è l'output di un modello sottoposto a training con i dati di training disponibili in Python SDK.This is the output for a model trained with the training data available from the Python SDK.

Model ID: ae636292-0b14-4e26-81a7-a0bfcbaf7c91

Status: ready
Training started on: 2020-08-20 23:20:56+00:00
Training completed on: 2020-08-20 23:20:57+00:00

Recognized fields:
The submodel with form type 'form-ae636292-0b14-4e26-81a7-a0bfcbaf7c91' has recognized the following fields: CompanyAddress, CompanyName, CompanyPhoneNumber, DatedAs, Email, Merchant, PhoneNumber, PurchaseOrderNumber, Quantity, Signature, Subtotal, Tax, Total, VendorName, Website
Document name: Form_1.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_2.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_3.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_4.jpg
Document status: succeeded
Document page count: 1
Document errors: []
Document name: Form_5.jpg
Document status: succeeded
Document page count: 1
Document errors: []

Analizzare i moduli con un modello personalizzatoAnalyze forms with a custom model

Questa sezione illustra come estrarre informazioni chiave-valore e altro contenuto dai tipi di modulo personalizzati, usando i modelli a cui è stato eseguito il training con moduli personalizzati.This section demonstrates how to extract key/value information and other content from your custom form types, using models you trained with your own forms.

Importante

Per implementare questo scenario è necessario avere già eseguito il training di un modello in modo da poter passare il relativo ID al metodo seguente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Vedere la sezione Eseguire il training di un modello.See the Train a model section.

Verrà usato il metodo begin_recognize_custom_forms_from_url.You'll use the begin_recognize_custom_forms_from_url method. Il valore restituito è una raccolta di oggetti RecognizedForm: uno per ogni pagina nel documento inviato.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document. Il codice seguente stampa i risultati dell'analisi nella console.The following code prints the analysis results to the console. Stampa ogni campo riconosciuto e il valore corrispondente, insieme a un punteggio di attendibilità.It prints each recognized field and corresponding value, along with a confidence score.

# Model ID from when you trained your model.
model_id = "<your custom model id>"

poller = form_recognizer_client.begin_recognize_custom_forms_from_url(
    model_id=model_id, form_url=formUrl)
result = poller.result()

for recognized_form in result:
    print("Form type: {}".format(recognized_form.form_type))
    for name, field in recognized_form.fields.items():
        print("Field '{}' has label '{}' with value '{}' and a confidence score of {}".format(
            name,
            field.label_data.text if field.label_data else name,
            field.value,
            field.confidence
        ))

Suggerimento

È anche possibile analizzare le immagini locali.You can also analyze local images. Vedere i metodi FormRecognizerClient, ad esempio begin_recognize_custom_forms.See the FormRecognizerClient methods, such as begin_recognize_custom_forms. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

Usando il modello dell'esempio precedente viene fornito l'output seguente.Using the model from the previous example, the following output is provided.

Form type: form-ae636292-0b14-4e26-81a7-a0bfcbaf7c91
Field 'Merchant' has label 'Merchant' with value 'Invoice For:' and a confidence score of 0.116
Field 'CompanyAddress' has label 'CompanyAddress' with value '1 Redmond way Suite 6000 Redmond, WA' and a confidence score of 0.258
Field 'Website' has label 'Website' with value '99243' and a confidence score of 0.114
Field 'VendorName' has label 'VendorName' with value 'Charges' and a confidence score of 0.145
Field 'CompanyPhoneNumber' has label 'CompanyPhoneNumber' with value '$56,651.49' and a confidence score of 0.249
Field 'CompanyName' has label 'CompanyName' with value 'PT' and a confidence score of 0.245
Field 'DatedAs' has label 'DatedAs' with value 'None' and a confidence score of None
Field 'Email' has label 'Email' with value 'None' and a confidence score of None
Field 'PhoneNumber' has label 'PhoneNumber' with value 'None' and a confidence score of None
Field 'PurchaseOrderNumber' has label 'PurchaseOrderNumber' with value 'None' and a confidence score of None
Field 'Quantity' has label 'Quantity' with value 'None' and a confidence score of None
Field 'Signature' has label 'Signature' with value 'None' and a confidence score of None
Field 'Subtotal' has label 'Subtotal' with value 'None' and a confidence score of None
Field 'Tax' has label 'Tax' with value 'None' and a confidence score of None
Field 'Total' has label 'Total' with value 'None' and a confidence score of None

Analizzare ricevuteAnalyze receipts

Questa sezione illustra come analizzare ed estrarre i campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione con training preliminare.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Per ulteriori informazioni sull'analisi della ricezione, vedere la Guida concettuale relativa alle ricevute.For more information about receipt analysis, see the Receipts conceptual guide. Per analizzare le ricevute da un URL, usare il begin_recognize_receipts_from_url metodo.To analyze receipts from a URL, use the begin_recognize_receipts_from_url method.

receiptUrl = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/master/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png"

poller = form_recognizer_client.begin_recognize_receipts_from_url(receiptUrl)
result = poller.result()

for receipt in result:
    for name, field in receipt.fields.items():
        if name == "Items":
            print("Receipt Items:")
            for idx, items in enumerate(field.value):
                print("...Item #{}".format(idx + 1))
                for item_name, item in items.value.items():
                    print("......{}: {} has confidence {}".format(item_name, item.value, item.confidence))
        else:
            print("{}: {} has confidence {}".format(name, field.value, field.confidence))

Suggerimento

È anche possibile analizzare le immagini di ricezione locali.You can also analyze local receipt images. Vedere i metodi FormRecognizerClient, ad esempio begin_recognize_receipts.See the FormRecognizerClient methods, such as begin_recognize_receipts. In alternativa, per gli scenari con immagini locali, vedere il codice di esempio in GitHub.Or, see the sample code on GitHub for scenarios involving local images.

OutputOutput

ReceiptType: Itemized has confidence 0.659
MerchantName: Contoso Contoso has confidence 0.516
MerchantAddress: 123 Main Street Redmond, WA 98052 has confidence 0.986
MerchantPhoneNumber: None has confidence 0.99
TransactionDate: 2019-06-10 has confidence 0.985
TransactionTime: 13:59:00 has confidence 0.968
Receipt Items:
...Item #1
......Name: 8GB RAM (Black) has confidence 0.916
......TotalPrice: 999.0 has confidence 0.559
...Item #2
......Quantity: None has confidence 0.858
......Name: SurfacePen has confidence 0.858
......TotalPrice: 99.99 has confidence 0.386
Subtotal: 1098.99 has confidence 0.964
Tax: 104.4 has confidence 0.713
Total: 1203.39 has confidence 0.774

Analizzare biglietti da visitaAnalyze business cards

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Gestire i modelli personalizzatiManage your custom models

Questa sezione illustra come gestire modelli personalizzati archiviati nell'account.This section demonstrates how to manage the custom models stored in your account.

Verificare il numero dei modelli all'interno dell'account della risorsa FormRecognizerCheck the number of models in the FormRecognizer resource account

Il blocco di codice seguente consente di controllare il numero di modelli salvati nell'account di Riconoscimento modulo e di confrontarli con il limite dell'account.The following code block checks how many models you have saved in your Form Recognizer account and compares it to the account limit.

account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

OutputOutput

Our account has 5 custom models, and we can have at most 5000 custom models

Elencare i modelli archiviati attualmente nell'account della risorsaList the models currently stored in the resource account

Il blocco di codice seguente elenca i modelli attuali presenti nell'account e stampa i relativi dettagli nella console.The following code block lists the current models in your account and prints their details to the console. Consente inoltre di salvare un riferimento relativo al primo modello.It also saves a reference to the first model.

# Next, we get a paged list of all of our custom models
custom_models = form_training_client.list_custom_models()

print("We have models with the following ids:")

# Let's pull out the first model
first_model = next(custom_models)
print(first_model.model_id)
for model in custom_models:
    print(model.model_id)

OutputOutput

Questo è un output di esempio per l'account di test.This is a sample output for the test account.

We have models with the following ids:
453cc2e6-e3eb-4e9f-aab6-e1ac7b87e09e
628739de-779c-473d-8214-d35c72d3d4f7
ae636292-0b14-4e26-81a7-a0bfcbaf7c91
b4b5df77-8538-4ffb-a996-f67158ecd305
c6309148-6b64-4fef-aea0-d39521452699

Ottenere un modello specifico con l'ID del modelloGet a specific model using the model's ID

Il blocco di codice seguente usa l'ID del modello salvato dalla sezione precedente e lo usa per recuperare i dettagli sul modello.The following code block uses the model ID saved from the previous section and uses it to retrieve details about the model.

model_id = "<model_id from the Train a Model sample>"

custom_model = form_training_client.get_custom_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

OutputOutput

Questo è l'output di esempio per il modello personalizzato creato nell'esempio precedente.This is the sample output for the custom model created in the previous example.

Model ID: ae636292-0b14-4e26-81a7-a0bfcbaf7c91
Status: ready
Training started on: 2020-08-20 23:20:56+00:00
Training completed on: 2020-08-20 23:20:57+00:00

Eliminare un modello dall'account della risorsaDelete a model from the resource account

È inoltre possibile eliminare un modello dall'account facendo riferimento al relativo ID.You can also delete a model from your account by referencing its ID. Questo codice elimina il modello usato nella sezione precedente.This code deletes the model used in the previous section.

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

Eseguire l'applicazioneRun the application

Eseguire l'applicazione con il comando python nel file quickstart.Run the application with the python command on your quickstart file.

python quickstart-file.py

Pulire le risorseClean up resources

Se si vuole pulire e rimuovere una sottoscrizione a Servizi cognitivi, è possibile eliminare la risorsa o il gruppo di risorse.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate.Deleting the resource group also deletes any other resources associated with it.

Risoluzione dei problemiTroubleshooting

GeneraleGeneral

La libreria client di Riconoscimento modulo genererà le eccezioni definite in Azure Core.The Form Recognizer client library will raise exceptions defined in Azure Core.

RegistrazioneLogging

Per la registrazione questa libreria usa la libreria di registrazione standard.This library uses the standard logging library for logging. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via), vengono registrate a livello di informazioni.Basic information about HTTP sessions (URLs, headers, and so on) is logged at the INFO level.

La registrazione dettagliata a livello di debug, inclusi i corpi di richiesta-risposta e le intestazioni non modificate, può essere abilitata su un client con l'argomento parola chiave logging_enable:Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the logging_enable keyword argument:

import sys
import logging
from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
form_recognizer_client = FormRecognizerClient(endpoint, credential, logging_enable=True)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:Similarly, logging_enable can enable detailed logging for a single operation, even when it isn't enabled for the client:

poller = form_recognizer_client.begin_recognize_receipts(receipt, logging_enable=True)

Passaggi successiviNext steps

In questo argomento di avvio rapido è stata usata la libreria client di Riconoscimento modulo per Python per eseguire il training di modelli e analizzare i moduli in modi diversi.In this quickstart, you used the Form Recognizer Python client library to train models and analyze forms in different ways. In seguito, è possibile ottenere suggerimenti per creare un set di dati di training migliore e produrre modelli più accurati.Next, learn tips to create a better training data set and produce more accurate models.

Nota

Questa guida usa cURL per eseguire chiamate alle API REST.This guide uses cURL to execute REST API calls. È anche disponibile un codice di esempio in GitHub che illustra come chiamare le API REST con Python.There is also sample code on GitHub that illustrates how to call the REST APIs with Python.

PrerequisitiPrerequisites

  • cURL installato.cURL installed.
  • Sottoscrizione di Azure: creare un account gratuitoAzure subscription - Create one for free
  • Un BLOB di Archiviazione di Azure contenente un set di dati di training.An Azure Storage blob that contains a set of training data. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di un set di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data set. Per questo argomento di avvio rapido, è possibile usare i file inclusi nella cartella Train del set di dati di esempio (scaricare ed estrarre sample_data.zip).For this quickstart, you can use the files under the Train folder of the sample data set (download and extract sample_data.zip).
  • Dopo aver creato la sottoscrizione di Azure, creare una risorsa di Riconoscimento modulo nel portale di Azure per ottenere la chiave e l'endpoint.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.After it deploys, click Go to resource.
    • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Riconoscimento modulo.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.You'll paste your key and endpoint into the code below later in the quickstart.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Un URL di un'immagine di una ricevuta.A URL for an image of a receipt. Per questo argomento di avvio rapido è possibile usare un'immagine di esempio.You can use a sample image for this quickstart.
  • Un URL dell'immagine di un biglietto da visita.A URL for an image of a business card. Per questo argomento di avvio rapido è possibile usare un'immagine di esempio.You can use a sample image for this quickstart.
  • Un URL dell'immagine di una fattura.A URL for an image of an invoice. Per questa guida di avvio rapido, è possibile usare un documento di esempio.You can use a sample document for this quickstart.

Analizzare il layoutAnalyze layout

È possibile utilizzare il riconoscimento moduli per analizzare ed estrarre tabelle, contrassegni di selezione, testo e struttura nei documenti, senza dover eseguire il training di un modello.You can use Form Recognizer to analyze and extract tables, selection marks, text, and structure in documents, without needing to train a model. Per ulteriori informazioni sull'estrazione del layout, vedere la Guida concettuale sul layout.For more information about layout extraction see the Layout conceptual guide. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Sostituire \"{your-document-url} con uno degli URL di esempio.Replace \"{your-document-url} with one of the example URLs.
curl -v -i POST "https://{Endpoint}/formrecognizer/v2.0/layout/analyze" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'source': '{your-document-url}'}"

Si riceverà una risposta 202 (Success) che include un'intestazione Operation-Location.You'll receive a 202 (Success) response that includes am Operation-Location header. Il valore di questa intestazione contiene un ID operazione che è possibile usare per eseguire una query sullo stato dell'operazione asincrona e ottenere i risultati.The value of this header contains an operation ID that you can use to query the status of the asynchronous operation and get the results. Nell'esempio seguente, la stringa dopo analyzeResults/ è l'ID operazione.In the following example, the string after analyzeResults/ is the operation ID.

https://cognitiveservice/formrecognizer/v2.1-preview.2/layout/analyzeResults/54f0b076-4e38-43e5-81bd-b85b8835fdfb

Ottenere i risultati del layoutGet layout results

Dopo aver chiamato l'API Analyze Layout , chiamare l'API Get Analyze Layout Result per ottenere lo stato dell'operazione e i dati estratti.After you've called the Analyze Layout API, you call the Get Analyze Layout Result API to get the status of the operation and the extracted data. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Sostituire {resultId} con l'ID operazione del passaggio precedente.Replace {resultId} with the operation ID from the previous step.
curl -v -X GET "https://{Endpoint}/formrecognizer/v2.0/layout/analyzeResults/{resultId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Esaminare i risultatiExamine the results

Si riceverà una risposta 200 (success) con il contenuto JSON.You'll receive a 200 (success) response with JSON content.

Vedere l'immagine di fattura seguente e il corrispondente output JSON.See the following invoice image and its corresponding JSON output.

  • Il nodo "readResults" contiene ogni riga di testo con il rispettivo posizionamento del rettangolo di selezione nella pagina.The "readResults" node contains every line of text with its respective bounding box placement on the page.
  • Il nodo "selectionMarks" (in v2.1.preview) mostra ogni indicatore di selezione (casella di controllo, pulsante di opzione) e se il relativo stato è "selezionato" o "non selezionato".The "selectionMarks" node (in v2.1 preview) shows every selection mark (checkbox, radio mark) and whether its status is "selected" or "unselected".
  • La "pageResults" sezione include le tabelle estratte.The "pageResults" section includes the tables extracted. Per ogni tabella vengono estratti il testo, l'indice di riga e di colonna, lo spanning di righe e colonne, il rettangolo di delimitazione e altro.For each table, the text, row, and column index, row and column spanning, bounding box, and more are extracted.

Documento di rendiconto su un progetto Contoso con una tabella.

Questo output è stato abbreviato per semplicità.This output has been shortened for simplicity. Vedere l' output di esempio completo su GitHub.See the full sample output on GitHub.

{
    "status": "succeeded",
    "createdDateTime": "2020-08-20T20:36:52Z",
    "lastUpdatedDateTime": "2020-08-20T20:36:58Z",
    "analyzeResult": {
        "version": "2.0.0",
        "readResults": [
            {
                "page": 1,
                "language": "en",
                "angle": 0,
                "width": 8.5,
                "height": 11,
                "unit": "inch",
                "lines": [
                    {
                        "boundingBox": [
                            0.5826,
                            0.4411,
                            2.3387,
                            0.4411,
                            2.3387,
                            0.7969,
                            0.5826,
                            0.7969
                        ],
                        "text": "Contoso, Ltd.",
                        "words": [
                            {
                                "boundingBox": [
                                    0.5826,
                                    0.4411,
                                    1.744,
                                    0.4411,
                                    1.744,
                                    0.7969,
                                    0.5826,
                                    0.7969
                                ],
                                "text": "Contoso,",
                                "confidence": 1
                            },
                            {
                                "boundingBox": [
                                    1.8448,
                                    0.4446,
                                    2.3387,
                                    0.4446,
                                    2.3387,
                                    0.7631,
                                    1.8448,
                                    0.7631
                                ],
                                "text": "Ltd.",
                                "confidence": 1
                            }
                        ]
                    },
                    ...
                ]
            }
        ],
        "pageResults": [
            {
                "page": 1,
                "tables": [
                    {
                        "rows": 5,
                        "columns": 5,
                        "cells": [
                            {
                                "rowIndex": 0,
                                "columnIndex": 0,
                                "text": "Training Date",
                                "boundingBox": [
                                    0.5133,
                                    4.2167,
                                    1.7567,
                                    4.2167,
                                    1.7567,
                                    4.4492,
                                    0.5133,
                                    4.4492
                                ],
                                "elements": [
                                    "#/readResults/0/lines/14/words/0",
                                    "#/readResults/0/lines/14/words/1"
                                ]
                            },
                            ...
                        ]
                    },
                    ...
                ]
            }
        ]
    }
}

Analizzare fattureAnalyze invoices

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Eseguire il training di un modello personalizzatoTrain a custom model

Per eseguire il training di un modello personalizzato, è necessario un set di dati di training in un BLOB del servizio di archiviazione di Azure.To train a custom model, you'll need a set of training data in an Azure Storage blob. Sono necessari almeno cinque form compilati (documenti PDF e/o immagini) dello stesso tipo/struttura.You need a minimum of five filled-in forms (PDF documents and/or images) of the same type/structure. Consultare Compilare un training set per un modello personalizzato per suggerimenti e opzioni per la creazione di dati di training.See Build a training data set for a custom model for tips and options for putting together your training data.

Il training senza dati con etichetta è l'operazione predefinita ed è più semplice.Training without labeled data is the default operation and is simpler. In alternativa, è possibile etichettare manualmente alcuni o tutti i dati di training in anticipo.Alternatively, you can manually label some or all of your training data beforehand. Si tratta di una procedura più complessa, ma il risultato è un training del modello più efficace.This is a more complex process but results in a better trained model.

Nota

È anche possibile eseguire il training dei modelli con un'interfaccia utente grafica, ad esempio con lo Strumento di etichettatura campioni Riconoscimento modulo.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Eseguire il training di un modello senza etichetteTrain a model without labels

Per eseguire il training di un modello di Riconoscimento modulo con i documenti del contenitore BLOB di Azure, chiamare l'API Train Custom Model eseguendo il comando cURL seguente.To train a Form Recognizer model with the documents in your Azure blob container, call the Train Custom Model API by running the following cURL command. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.

  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.

  3. Sostituire {SAS URL} con l'URL della firma di accesso condiviso (SAS) del contenitore di archiviazione BLOB di Azure.Replace {SAS URL} with the Azure Blob storage container's shared access signature (SAS) URL. Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

curl -i -X POST "https://{Endpoint}/formrecognizer/v2.0/custom/models" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{ 'source': '{SAS URL}'}"

Si riceverà una risposta 201 (Success) con l'intestazione Location.You'll receive a 201 (Success) response with a Location header. Il valore di questa intestazione corrisponde all'ID del nuovo modello da sottoporre a training.The value of this header is the ID of the new model being trained.

Eseguire il training di un modello con etichetteTrain a model with labels

Per eseguire il training con etichette, è necessario avere file speciali di informazioni sulle etichette (\<filename\>.pdf.labels.json) nel contenitore di archiviazione BLOB insieme ai documenti di training.To train with labels, you need to have special label information files (\<filename\>.pdf.labels.json) in your blob storage container alongside the training documents. Lo Strumento di etichettatura campioni Riconoscimento modulo fornisce un'interfaccia utente che consente di creare questi file di etichette.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Una volta disponibili, è possibile chiamare l'API del modello di training personalizzato , con il "useLabelFile" parametro impostato su true nel corpo JSON.Once you have them, you can call the Train Custom Model API, with the "useLabelFile" parameter set to true in the JSON body.

Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.

  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.

  3. Sostituire {SAS URL} con l'URL della firma di accesso condiviso (SAS) del contenitore di archiviazione BLOB di Azure.Replace {SAS URL} with the Azure Blob storage container's shared access signature (SAS) URL. Per recuperare l'URL di firma di accesso condiviso per i dati di training del modello personalizzato, passare alla risorsa di archiviazione nel portale di Azure e selezionare la scheda Storage Explorer. Passare al contenitore, fare clic con il pulsante destro del mouse e scegliere Ottieni firma di accesso condiviso.To retrieve the SAS URL for your custom model training data, go to your storage resource in the Azure portal and select the Storage Explorer tab. Navigate to your container, right-click, and select Get shared access signature. È importante ottenere la firma di accesso condiviso per il contenitore, non per l'account di archiviazione.It's important to get the SAS for your container, not for the storage account itself. Assicurarsi che le autorizzazioni Lettura ed Elenco siano selezionate e fare clic su Crea.Make sure the Read and List permissions are checked, and click Create. A questo punto, copiare il valore dalla sezione URL in una posizione temporanea.Then copy the value in the URL section to a temporary location. Dovrebbe essere in questo formato: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.It should have the form: https://<storage account>.blob.core.windows.net/<container name>?<SAS value>.

    Recupero dell'URL di firma di accesso condiviso

curl -i -X POST "https://{Endpoint}/formrecognizer/v2.0/custom/models" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{ 'source': '{SAS URL}', 'useLabelFile':true }"

Si riceverà una risposta 201 (Success) con l'intestazione Location.You'll receive a 201 (Success) response with a Location header. Il valore di questa intestazione corrisponde all'ID del nuovo modello da sottoporre a training.The value of this header is the ID of the new model being trained.

Ottenere i risultati del trainingGet training results

Dopo aver avviato il training, usare una nuova operazione, Get Custom Model , per verificare lo stato dell'operazione.After you've started the train operation, you use a new operation, Get Custom Model to check the training status. Passare l'ID modello in questa chiamata API per controllare lo stato del training:Pass the model ID into this API call to check the training status:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la chiave di sottoscrizione di riconoscimento modulo,Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription key.
  2. Sostituire {subscription key} con la chiave di sottoscrizioneReplace {subscription key} with your subscription key
  3. Sostituire {model ID} con l'ID modello ricevuto nel passaggio precedenteReplace {model ID} with the model ID you received in the previous step
curl -X GET "https://{Endpoint}/formrecognizer/v2.0/custom/models/{model ID}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Si riceverà una risposta 200 (Success) con un corpo JSON nel formato seguente.You'll receive a 200 (Success) response with a JSON body in the following format. Osservare il campo "status".Notice the "status" field. Al termine del training, avrà il valore "ready".This will have the value "ready" once training is complete. Se il training del modello non è stato completato, è necessario eseguire di nuovo una query sul servizio ripetendo il comando.If the model is not finished training, you'll need to query the service again by rerunning the command. Si consiglia di attendere almeno un secondo tra le chiamate.We recommend an interval of one second or more between calls.

Il campo "modelId" contiene l'ID del modello da sottoporre a training.The "modelId" field contains the ID of the model you're training. Servirà per il passaggio successivo.You'll need this for the next step.

{
  "modelInfo":{
    "status":"ready",
    "createdDateTime":"2019-10-08T10:20:31.957784",
    "lastUpdatedDateTime":"2019-10-08T14:20:41+00:00",
    "modelId":"1cfb372bab404ba3aa59481ab2c63da5"
  },
  "trainResult":{
    "trainingDocuments":[
      {
        "documentName":"invoices\\Invoice_1.pdf",
        "pages":1,
        "errors":[

        ],
        "status":"succeeded"
      },
      {
        "documentName":"invoices\\Invoice_2.pdf",
        "pages":1,
        "errors":[

        ],
        "status":"succeeded"
      },
      {
        "documentName":"invoices\\Invoice_3.pdf",
        "pages":1,
        "errors":[

        ],
        "status":"succeeded"
      },
      {
        "documentName":"invoices\\Invoice_4.pdf",
        "pages":1,
        "errors":[

        ],
        "status":"succeeded"
      },
      {
        "documentName":"invoices\\Invoice_5.pdf",
        "pages":1,
        "errors":[

        ],
        "status":"succeeded"
      }
    ],
    "errors":[

    ]
  },
  "keys":{
    "0":[
      "Address:",
      "Invoice For:",
      "Microsoft",
      "Page"
    ]
  }
}

Analizzare i moduli con un modello personalizzatoAnalyze forms with a custom model

Quindi, usare il modello appena sottoposto a training per analizzare un documento da cui estrarre le coppie chiave-valore e le tabelle.Next, you'll use your newly trained model to analyze a document and extract key-value pairs and tables from it. Chiamare l'API Analyze Form eseguendo il comando cURL seguente.Call the Analyze Form API by running the following cURL command. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto dalla chiave di sottoscrizione di riconoscimento modulo,Replace {Endpoint} with the endpoint that you obtained from your Form Recognizer subscription key. disponibile nella scheda Overview (Panoramica) della risorsa di riconoscimento modulo.You can find it on your Form Recognizer resource Overview tab.
  2. Sostituire {model ID} con l'ID modello ricevuto nella sezione precedente.Replace {model ID} with the model ID that you received in the previous section.
  3. Sostituire {SAS URL} con un URL di firma di accesso condiviso per il file in archiviazione di Azure.Replace {SAS URL} with an SAS URL to your file in Azure storage. Seguire la procedura decritta nella sezione Training, ma invece di ottenere un URL di firma di accesso condiviso per l'intero contenitore BLOB ottenerne uno per il file specifico da analizzare.Follow the steps in the Training section, but instead of getting a SAS URL for the whole blob container, get one for the specific file you want to analyze.
  4. Sostituire {subscription key} con la chiave di sottoscrizione.Replace {subscription key} with your subscription key.
curl -v "https://{Endpoint}/formrecognizer/v2.0/custom/models/{model ID}/analyze?includeTextDetails=true" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" -d "{ 'source': '{SAS URL}' } "

Si riceverà una risposta 202 (Success) che include l'intestazione Operation-Location.You'll receive a 202 (Success) response with an Operation-Location header. Il valore di questa intestazione include un ID risultati da usare per tenere traccia dei risultati dell'operazione di analisi.The value of this header includes a results ID you use to track the results of the Analyze operation. Salvare questo ID risultati per il passaggio successivo.Save this results ID for the next step.

Ottenere i risultati dell'analisiGet the Analyze results

Chiamare l'API Get Analyze result form per eseguire una query sui risultati dell'operazione di analisi.Call the Get Analyze Form Result API to query the results of the Analyze operation.

  1. Sostituire {Endpoint} con l'endpoint ottenuto dalla chiave di sottoscrizione di riconoscimento modulo,Replace {Endpoint} with the endpoint that you obtained from your Form Recognizer subscription key. disponibile nella scheda Overview (Panoramica) della risorsa di riconoscimento modulo.You can find it on your Form Recognizer resource Overview tab.
  2. Sostituire {result ID} con l'ID ricevuto nella sezione precedente.Replace {result ID} with the ID that you received in the previous section.
  3. Sostituire {subscription key} con la chiave di sottoscrizione.Replace {subscription key} with your subscription key.
curl -X GET "https://{Endpoint}/formrecognizer/v2.0/custom/models/{model ID}/analyzeResults/{result ID}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Si riceverà una risposta 200 (Success) con un corpo JSON nel formato seguente.You'll receive a 200 (Success) response with a JSON body in the following format. L'output è stato abbreviato per semplicità.The output has been shortened for simplicity. Osservare il campo "status" verso la fine.Notice the "status" field near the bottom. Al termine dell'operazione di analisi, avrà il valore "succeeded".This will have the value "succeeded" when the Analyze operation is complete. Se l'operazione di analisi non è stata completata, è necessario eseguire di nuovo una query sul servizio ripetendo il comando.If the Analyze operation hasn't completed, you'll need to query the service again by rerunning the command. Si consiglia di attendere almeno un secondo tra le chiamate.We recommend an interval of one second or more between calls.

Nei modelli personalizzati sottoposti a training senza etichette, le associazioni di coppie chiave/valore e le tabelle si trovano nel "pageResults" nodo dell'output JSON.In custom models trained without labels, the key/value pair associations and tables are in the "pageResults" node of the JSON output. Nei modelli personalizzati sottoposti a training con etichette, le associazioni di coppie chiave/valore si trovano nel "documentResults" nodo.In custom models trained with labels, the key/value pair associations are in the "documentResults" node. Se è stata specificata anche l'estrazione di testo normale tramite il parametro URL includeTextDetails, il nodo "readResults" mostrerà il contenuto e le posizioni di tutto il testo nel documento.If you also specified plain text extraction through the includeTextDetails URL parameter, then the "readResults" node will show the content and positions of all the text in the document.

Questo output JSON di esempio è stato abbreviato per semplicità.This sample JSON output has been shortened for simplicity. Vedere l' output di esempio completo su GitHub.See the full sample output on GitHub.

{
  "status": "succeeded",
  "createdDateTime": "2020-08-21T00:46:25Z",
  "lastUpdatedDateTime": "2020-08-21T00:46:32Z",
  "analyzeResult": {
    "version": "2.0.0",
    "readResults": [
      {
        "page": 1,
        "angle": 0,
        "width": 8.5,
        "height": 11,
        "unit": "inch",
        "lines": [
          {
            "text": "Project Statement",
            "boundingBox": [
              5.0153,
              0.275,
              8.0944,
              0.275,
              8.0944,
              0.7125,
              5.0153,
              0.7125
            ],
            "words": [
              {
                "text": "Project",
                "boundingBox": [
                  5.0153,
                  0.275,
                  6.2278,
                  0.275,
                  6.2278,
                  0.7125,
                  5.0153,
                  0.7125
                ]
              },
              {
                "text": "Statement",
                "boundingBox": [
                  6.3292,
                  0.275,
                  8.0944,
                  0.275,
                  8.0944,
                  0.7125,
                  6.3292,
                  0.7125
                ]
              }
            ]
          }, 
        ...
        ]
      }
    ],
    "pageResults": [
      {
        "page": 1,
        "keyValuePairs": [
          {
            "key": {
              "text": "Date:",
              "boundingBox": [
                6.9722,
                1.0264,
                7.3417,
                1.0264,
                7.3417,
                1.1931,
                6.9722,
                1.1931
              ],
              "elements": [
                "#/readResults/0/lines/2/words/0"
              ]
            },
            "confidence": 1
          },
         ...
        ],
        "tables": [
          {
            "rows": 4,
            "columns": 5,
            "cells": [
              {
                "text": "Training Date",
                "rowIndex": 0,
                "columnIndex": 0,
                "boundingBox": [
                  0.6931,
                  4.2444,
                  1.5681,
                  4.2444,
                  1.5681,
                  4.4125,
                  0.6931,
                  4.4125
                ],
                "confidence": 1,
                "rowSpan": 1,
                "columnSpan": 1,
                "elements": [
                  "#/readResults/0/lines/15/words/0",
                  "#/readResults/0/lines/15/words/1"
                ],
                "isHeader": true,
                "isFooter": false
              },
              ...
            ]
          }
        ], 
        "clusterId": 0
      }
    ],
    "documentResults": [],
    "errors": []
  }
}

Migliorare i risultatiImprove results

Esaminare i valori di "confidence" per ogni risultato di chiave-valore nel nodo "pageResults".Examine the "confidence" values for each key/value result under the "pageResults" node. È inoltre consigliabile esaminare i punteggi di attendibilità nel nodo "readResults", che corrispondono all'operazione di lettura del testo.You should also look at the confidence scores in the "readResults" node, which correspond to the text read operation. L'attendibilità dei risultati della lettura non influisce su quella dei risultati dell'estrazione di coppie chiave-valore, quindi è necessario controllare entrambi.The confidence of the read results does not affect the confidence of the key/value extraction results, so you should check both.

  • Se i punteggi di attendibilità dell'operazione di lettura sono bassi, provare a migliorare la qualità dei documenti di input. Vedere Requisiti di input.If the confidence scores for the read operation are low, try to improve the quality of your input documents (see Input requirements).
  • Se i punteggi di attendibilità per l'operazione di estrazione di coppie chiave-valore sono bassi, assicurarsi che i documenti da analizzare siano dello stesso tipo di quelli usati nel set di training.If the confidence scores for the key/value extraction operation are low, ensure that the documents being analyzed are of the same type as documents used in the training set. Se i documenti del set di training hanno aspetti diversi, è consigliabile dividerli in cartelle diverse ed eseguire il training di un modello per ogni variante.If the documents in the training set have variations in appearance, consider splitting them into different folders and training one model for each variation.

I punteggi di attendibilità obiettivo dipendono dal caso d'uso, ma in genere è consigliabile avere come obiettivo un punteggio di almeno l'80%.The confidence scores you target will depend on your use case, but generally it's a good practice to target a score of 80% or above. Per i casi più sensibili, come la lettura di record medici o gli estratti conto, è consigliabile un punteggio del 100%.For more sensitive cases, like reading medical records or billing statements, a score of 100% is recommended.

Analizzare ricevuteAnalyze receipts

Questa sezione illustra come analizzare ed estrarre i campi comuni dalle ricevute degli Stati Uniti, usando un modello di ricezione con training preliminare.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Per ulteriori informazioni sull'analisi della ricezione, vedere la Guida concettuale relativa alle ricevute.For more information about receipt analysis, see the Receipts conceptual guide. Per iniziare ad analizzare una ricevuta, chiamare l'API Analyze Receipt usando il comando cURL seguente.To start analyzing a receipt, call the Analyze Receipt API using the cURL command below. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {your receipt URL} con l'indirizzo URL dell'immagine di una ricevuta.Replace {your receipt URL} with the URL address of a receipt image.
  3. Sostituire {subscription key> con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key> with the subscription key you copied from the previous step.
curl -i -X POST "https://{Endpoint}/formrecognizer/v2.0/prebuilt/receipt/analyze" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{ 'source': '{your receipt URL}'}"

Si riceverà una risposta 202 (Success) che include un'intestazione Operation-Location.You'll receive a 202 (Success) response that includes am Operation-Location header. Il valore di questa intestazione contiene un ID operazione che è possibile usare per eseguire una query sullo stato dell'operazione asincrona e ottenere i risultati.The value of this header contains an operation ID that you can use to query the status of the asynchronous operation and get the results. Nell'esempio seguente, la stringa dopo operations/ è l'ID operazione.In the following example, the string after operations/ is the operation ID.

https://cognitiveservice/formrecognizer/v2.1-preview.2/prebuilt/receipt/operations/54f0b076-4e38-43e5-81bd-b85b8835fdfb

Ottenere i risultati della ricevutaGet the receipt results

Dopo aver chiamato l'API Analyze Receipt, chiamare l'API Get Analyze Receipt Result per ottenere lo stato dell'operazione e i dati estratti.After you've called the Analyze Receipt API, you call the Get Analyze Receipt Result API to get the status of the operation and the extracted data. Prima di eseguire il comando, apportare queste modifiche:Before you run the command, make these changes:

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la chiave di sottoscrizione di riconoscimento modulo,Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription key. disponibile nella scheda Overview (Panoramica) della risorsa di riconoscimento modulo.You can find it on your Form Recognizer resource Overview tab.
  2. Sostituire {operationId} con l'ID operazione del passaggio precedente.Replace {operationId} with the operation ID from the previous step.
  3. Sostituire {subscription key} con la chiave di sottoscrizione.Replace {subscription key} with your subscription key.
curl -X GET "https://{Endpoint}/formrecognizer/v2.0/prebuilt/receipt/analyzeResults/{operationId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Esaminare i risultatiExamine the response

Si riceverà una risposta 200 (Success) con un output JSON.You'll receive a 200 (Success) response with JSON output. Il primo campo, "status", indica lo stato dell'operazione.The first field, "status", indicates the status of the operation. Se l'operazione non è stata completata, il valore di "status" sarà "running" o "notStarted" e si dovrà chiamare nuovamente l'API, manualmente o tramite uno script.If the operation is not complete, the value of "status" will be "running" or "notStarted", and you should call the API again, either manually or through a script. Si consiglia di attendere almeno un secondo tra le chiamate.We recommend an interval of one second or more between calls.

Il nodo "readResults" contiene tutto il testo riconosciuto, se si imposta il parametro facoltativo includeTextDetails su true.The "readResults" node contains all of the recognized text (if you set the optional includeTextDetails parameter to true). Il testo è organizzato in base alla pagina, quindi alla riga, infine in base a singole parole.Text is organized by page, then by line, then by individual words. Il nodo "documentResults" contiene i valori specifici della ricevuta individuati dal modello.The "documentResults" node contains the receipt-specific values that the model discovered. Qui si troveranno utili coppie chiave-valore, come l'imposta, il totale, l'indirizzo del fornitore e così via.This is where you'll find useful key/value pairs like the tax, total, merchant address, and so on.

Osservare l'immagine di ricevuta seguente e il corrispondente output JSON.See the following receipt image and its corresponding JSON output.

Ricevuta di un negozio Contoso

Questo output è stato abbreviato per migliorare la leggibilità.This output has been shortened for readability. Vedere l' output di esempio completo su GitHub.See the full sample output on GitHub.

{
  "status":"succeeded",
  "createdDateTime":"2019-12-17T04:11:24Z",
  "lastUpdatedDateTime":"2019-12-17T04:11:32Z",
  "analyzeResult":{
    "version":"2.1.0",
    "readResults":[
      {
        "page":1,
        "angle":0.6893,
        "width":1688,
        "height":3000,
        "unit":"pixel",
        "language":"en",
        "lines":[
          {
            "text":"Contoso",
            "boundingBox":[
              635,
              510,
              1086,
              461,
              1098,
              558,
              643,
              604
            ],
            "words":[
              {
                "text":"Contoso",
                "boundingBox":[
                  639,
                  510,
                  1087,
                  461,
                  1098,
                  551,
                  646,
                  604
                ],
                "confidence":0.955
              }
            ]
          },
          ...
        ]
      }
    ],
    "documentResults":[
      {
        "docType":"prebuilt:receipt",
        "pageRange":[
          1,
          1
        ],
        "fields":{
          "ReceiptType":{
            "type":"string",
            "valueString":"Itemized",
            "confidence":0.692
          },
          "MerchantName":{
            "type":"string",
            "valueString":"Contoso Contoso",
            "text":"Contoso Contoso",
            "boundingBox":[
              378.2,
              292.4,
              1117.7,
              468.3,
              1035.7,
              812.7,
              296.3,
              636.8
            ],
            "page":1,
            "confidence":0.613,
            "elements":[
              "#/readResults/0/lines/0/words/0",
              "#/readResults/0/lines/1/words/0"
            ]
          },
          "MerchantAddress":{
            "type":"string",
            "valueString":"123 Main Street Redmond, WA 98052",
            "text":"123 Main Street Redmond, WA 98052",
            "boundingBox":[
              302,
              675.8,
              848.1,
              793.7,
              809.9,
              970.4,
              263.9,
              852.5
            ],
            "page":1,
            "confidence":0.99,
            "elements":[
              "#/readResults/0/lines/2/words/0",
              "#/readResults/0/lines/2/words/1",
              "#/readResults/0/lines/2/words/2",
              "#/readResults/0/lines/3/words/0",
              "#/readResults/0/lines/3/words/1",
              "#/readResults/0/lines/3/words/2"
            ]
          },
          "MerchantPhoneNumber":{
            "type":"phoneNumber",
            "valuePhoneNumber":"+19876543210",
            "text":"987-654-3210",
            "boundingBox":[
              278,
              1004,
              656.3,
              1054.7,
              646.8,
              1125.3,
              268.5,
              1074.7
            ],
            "page":1,
            "confidence":0.99,
            "elements":[
              "#/readResults/0/lines/4/words/0"
            ]
          },
          "TransactionDate":{
            "type":"date",
            "valueDate":"2019-06-10",
            "text":"6/10/2019",
            "boundingBox":[
              265.1,
              1228.4,
              525,
              1247,
              518.9,
              1332.1,
              259,
              1313.5
            ],
            "page":1,
            "confidence":0.99,
            "elements":[
              "#/readResults/0/lines/5/words/0"
            ]
          },
          "TransactionTime":{
            "type":"time",
            "valueTime":"13:59:00",
            "text":"13:59",
            "boundingBox":[
              541,
              1248,
              677.3,
              1261.5,
              668.9,
              1346.5,
              532.6,
              1333
            ],
            "page":1,
            "confidence":0.977,
            "elements":[
              "#/readResults/0/lines/5/words/1"
            ]
          },
          "Items":{
            "type":"array",
            "valueArray":[
              {
                "type":"object",
                "valueObject":{
                  "Quantity":{
                    "type":"number",
                    "text":"1",
                    "boundingBox":[
                      245.1,
                      1581.5,
                      300.9,
                      1585.1,
                      295,
                      1676,
                      239.2,
                      1672.4
                    ],
                    "page":1,
                    "confidence":0.92,
                    "elements":[
                      "#/readResults/0/lines/7/words/0"
                    ]
                  },
                  "Name":{
                    "type":"string",
                    "valueString":"Cappuccino",
                    "text":"Cappuccino",
                    "boundingBox":[
                      322,
                      1586,
                      654.2,
                      1601.1,
                      650,
                      1693,
                      317.8,
                      1678
                    ],
                    "page":1,
                    "confidence":0.923,
                    "elements":[
                      "#/readResults/0/lines/7/words/1"
                    ]
                  },
                  "TotalPrice":{
                    "type":"number",
                    "valueNumber":2.2,
                    "text":"$2.20",
                    "boundingBox":[
                      1107.7,
                      1584,
                      1263,
                      1574,
                      1268.3,
                      1656,
                      1113,
                      1666
                    ],
                    "page":1,
                    "confidence":0.918,
                    "elements":[
                      "#/readResults/0/lines/8/words/0"
                    ]
                  }
                }
              },
              ...
            ]
          },
          "Subtotal":{
            "type":"number",
            "valueNumber":11.7,
            "text":"11.70",
            "boundingBox":[
              1146,
              2221,
              1297.3,
              2223,
              1296,
              2319,
              1144.7,
              2317
            ],
            "page":1,
            "confidence":0.955,
            "elements":[
              "#/readResults/0/lines/13/words/1"
            ]
          },
          "Tax":{
            "type":"number",
            "valueNumber":1.17,
            "text":"1.17",
            "boundingBox":[
              1190,
              2359,
              1304,
              2359,
              1304,
              2456,
              1190,
              2456
            ],
            "page":1,
            "confidence":0.979,
            "elements":[
              "#/readResults/0/lines/15/words/1"
            ]
          },
          "Tip":{
            "type":"number",
            "valueNumber":1.63,
            "text":"1.63",
            "boundingBox":[
              1094,
              2479,
              1267.7,
              2485,
              1264,
              2591,
              1090.3,
              2585
            ],
            "page":1,
            "confidence":0.941,
            "elements":[
              "#/readResults/0/lines/17/words/1"
            ]
          },
          "Total":{
            "type":"number",
            "valueNumber":14.5,
            "text":"$14.50",
            "boundingBox":[
              1034.2,
              2617,
              1387.5,
              2638.2,
              1380,
              2763,
              1026.7,
              2741.8
            ],
            "page":1,
            "confidence":0.985,
            "elements":[
              "#/readResults/0/lines/19/words/0"
            ]
          }
        }
      }
    ]
  }
}

Analizzare biglietti da visitaAnalyze business cards

Importante

Questa funzionalità non è disponibile nella versione dell'API selezionata.This feature isn't available in the selected API version.

Gestire i modelli personalizzatiManage custom models

Ottenere un elenco di modelli personalizzatiGet a list of custom models

Usare l'API List Custom Models nel comando seguente per restituire un elenco di tutti i modelli personalizzati che appartengono alla sottoscrizione.Use the List Custom Models API in the following command to return a list of all the custom models that belong to your subscription.

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.
curl -v -X GET "https://{Endpoint}/formrecognizer/v2.0/custom/models?op=full"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

Si riceverà una risposta 200 di operazione riuscita con dati JSON simili ai seguenti.You'll receive a 200 success response, with JSON data like the following. L'elemento "modelList" contiene tutti i modelli creati e le relative informazioni.The "modelList" element contains all of your created models and their information.

{
  "summary": {
    "count": 0,
    "limit": 0,
    "lastUpdatedDateTime": "string"
  },
  "modelList": [
    {
      "modelId": "string",
      "status": "creating",
      "createdDateTime": "string",
      "lastUpdatedDateTime": "string"
    }
  ],
  "nextLink": "string"
}

Ottenere un modello specificoGet a specific model

Per recuperare informazioni dettagliate su un modello personalizzato specifico, usare l'API di recupero del modello personalizzato nel comando seguente.To retrieve detailed information about a specific custom model, use the Get Custom Model API in the following command.

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Sostituire {modelId} con l'ID del modello personalizzato da cercare.Replace {modelId} with the ID of the custom model you want to look up.
curl -v -X GET "https://{Endpoint}/formrecognizer/v2.0/custom/models/{modelId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Si riceverà una risposta 200 di operazione riuscita con dati JSON simili ai seguenti.You'll receive a 200 success response, with JSON data like the following.

{
  "modelInfo": {
    "modelId": "string",
    "status": "creating",
    "createdDateTime": "string",
    "lastUpdatedDateTime": "string"
  },
  "keys": {
    "clusters": {}
  },
  "trainResult": {
    "trainingDocuments": [
      {
        "documentName": "string",
        "pages": 0,
        "errors": [
          "string"
        ],
        "status": "succeeded"
      }
    ],
    "fields": [
      {
        "fieldName": "string",
        "accuracy": 0.0
      }
    ],
    "averageModelAccuracy": 0.0,
    "errors": [
      {
        "message": "string"
      }
    ]
  }
}

Eliminare un modello dall'account della risorsaDelete a model from the resource account

È inoltre possibile eliminare un modello dall'account facendo riferimento al relativo ID.You can also delete a model from your account by referencing its ID. Questo comando chiama l'API del modello personalizzato Delete per eliminare il modello usato nella sezione precedente.This command calls the Delete Custom Model API to delete the model used in the previous section.

  1. Sostituire {Endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Sostituire {modelId} con l'ID del modello personalizzato da cercare.Replace {modelId} with the ID of the custom model you want to look up.
curl -v -X DELETE "https://{Endpoint}/formrecognizer/v2.0/custom/models/{modelId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Si riceverà una 204 risposta di esito positivo, che indica che il modello è contrassegnato per l'eliminazione.You'll receive a 204 success response, indicating that your model is marked for deletion. Gli elementi del modello verranno rimossi entro 48 ore.Model artifacts will be removed within 48 hours.

Passaggi successiviNext steps

In questa guida di avvio rapido è stata usata l'API REST Riconoscimento modulo per eseguire il training di modelli e analizzare moduli in vari modi.In this quickstart, you used the Form Recognizer REST API to train models and analyze forms in different ways. A questo punto, vedere la documentazione di riferimento per esplorare l'API di Riconoscimento modulo in maggior dettaglio.Next, see the reference documentation to explore the Form Recognizer API in more depth.