Inicio rápido: Uso de la biblioteca cliente o API REST de Form RecognizerQuickstart: Use the Form Recognizer client library or REST API

Comience a usar Form Recognizer mediante el lenguaje de desarrollo de su elección.Get started with the Form Recognizer using the development language of your choice. Azure Form Recognizer es un servicio cognitivo que le permite crear software de procesamiento de datos automatizado mediante tecnología de aprendizaje automático.Azure Form Recognizer is a cognitive service that lets you build automated data processing software using machine learning technology. Identifique y extraiga texto, pares clave-valor, marcas de selección, datos de tabla, etc., de los documentos de formulario; el servicio genera datos estructurados que incluyen las relaciones en el archivo original.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. Puede usar Form Recognizer a través de la API REST o el SDK.You can use Form Recognizer via the REST API or SDK. Siga estos pasos para instalar el paquete SDK y probar el código de ejemplo para realizar tareas básicas.Follow these steps to install the SDK package and try out the example code for basic tasks.

Use Form Recognizer para:Use Form Recognizer to:

Importante

Por motivos de simplicidad, en el código de este artículo se usan métodos sincrónicos y almacenamiento de credenciales no protegidas.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons.

Documentación de referencia | Código fuente de la biblioteca | Paquete (NuGet) | EjemplosReference documentation | Library source code | Package (NuGet) | Samples

PrerrequisitosPrerequisites

  • Una suscripción a Azure: cree una cuenta gratuitaAzure subscription - Create one for free
  • El IDE de Visual Studio o la versión actual de .NET Core.The Visual Studio IDE or current version of .NET Core.
  • Un blob de Azure Storage que contenga un conjunto de datos de entrenamiento.An Azure Storage blob that contains a set of training data. Consulte Creación de un conjunto de datos de aprendizaje para un modelo personalizado para ver sugerencias y opciones para reunir el conjunto de datos de aprendizaje.See Build a training data set for a custom model for tips and options for putting together your training data set. En este inicio rápido puede usar los archivos de la carpeta Train del conjunto de datos de ejemplo (descargue y extraiga 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).
  • Una vez que tenga la suscripción de Azure, create a Form Recognizer resource en Azure Portal para obtener la clave y el punto de conexión.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Una vez que se implemente, haga clic en Ir al recurso.After it deploys, click Go to resource.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a Form Recognizer API.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.You'll paste your key and endpoint into the code below later in the quickstart.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

InstalaciónSetting up

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre 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. Este comando crea un sencillo proyecto de C#, "Hola mundo", con un solo archivo de origen: program.cs.This command creates a simple "Hello World" C# project with a single source file: program.cs.

dotnet new console -n formrecognizer-quickstart

Cambie el directorio a la carpeta de aplicaciones recién creada.Change your directory to the newly created app folder. Para compilar la aplicación:You can build the application with:

dotnet build

La salida de la compilación no debe contener advertencias ni errores.The build output should contain no warnings or errors.

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

Instalación de la biblioteca clienteInstall the client library

Dentro del directorio de aplicaciones, instale la biblioteca cliente de Form Recognizer para .NET con el siguiente comando: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

El SDK de Form Recognizer 3.0.0 refleja la versión 2.0 de la API.The Form Recognizer 3.0.0 SDK reflects API version 2.0

Sugerencia

¿Desea ver todo el archivo de código de inicio rápido de una vez?Want to view the whole quickstart code file at once? Puede encontrarlo en GitHub, que contiene los ejemplos de código de este inicio rápido.You can find it on GitHub, which contains the code examples in this quickstart.

En el directorio del proyecto, abra el archivo Program.cs en el editor o IDE que prefiera.From the project directory, open the Program.cs file in your preferred editor or IDE. Agregue las siguientes directivas using: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;

En la clase Program de la aplicación, cree variables para el punto de conexión y la clave del recurso.In the application's Program class, create variables for your resource's key and endpoint.

Importante

Vaya a Azure Portal.Go to the Azure portal. Si el recurso de Form Recognizer que ha creado en la sección Requisitos previos se ha implementado correctamente, haga clic en el botón Ir al recurso en Pasos siguientes.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. Puede encontrar su clave y punto de conexión en la página de clave y punto de conexión del recurso, en Administración de recursos.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública.Remember to remove the key from your code when you're done, and never post it publicly. En el caso de producción, considere la posibilidad de usar alguna forma segura de almacenar las credenciales, y acceder a ellas.For production, consider using a secure way of storing and accessing your credentials. Para más información, consulte el artículo sobre la seguridad de Cognitive Services.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);

En el método Main de la aplicación, agregue una llamada a las tareas asincrónicas que se usan en este inicio rápido.In the application's Main method, add a call to the asynchronous tasks used in this quickstart. Las implementará más adelante.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);

}

Modelo de objetosObject model

Con Form Recognizer, puede crear dos tipos de cliente diferentes.With Form Recognizer, you can create two different client types. El primero, FormRecognizerClient, se utiliza para consultar el servicio con los campos de formulario y el contenido reconocidos.The first, FormRecognizerClient is used to query the service to recognized form fields and content. El segundo, FormTrainingClient, se usa para crear y administrar los modelos personalizados que puede usar para mejorar el reconocimiento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient proporciona operaciones para:FormRecognizerClient provides operations for:

  • Reconocimiento de los campos de formulario y del contenido, mediante el uso de modelos personalizados entrenados para analizar los formularios personalizados.Recognizing form fields and content, using custom models trained to analyze your custom forms. Estos valores se devuelven en una colección de objetos RecognizedForm.These values are returned in a collection of RecognizedForm objects. Vea el ejemplo Análisis de formularios personalizados.See example Analyze custom forms.
  • El reconocimiento del contenido de los formularios, incluidas tablas, líneas y palabras, sin necesidad de entrenar un modelo.Recognizing form content, including tables, lines and words, without the need to train a model. El contenido del formulario se devuelve en una colección de objetos FormPage.Form content is returned in a collection of FormPage objects. Consulte el ejemplo Análisis de diseño.See example Analyze layout.
  • Reconocimiento de los campos comunes de los recibos de EE. UU. con un modelo de recibo entrenado previamente en el servicio Form Recognizer.Recognizing common fields from US receipts, using a pre-trained receipt model on the Form Recognizer service. Estos campos y metadatos se devuelven en una colección de objetos RecognizedForm.These fields and meta-data are returned in a collection of RecognizedForm objects. Consulte el ejemplo Análisis de confirmaciones de recepción.See example Analyze receipts.

FormTrainingClientFormTrainingClient

FormTrainingClient proporciona operaciones para:FormTrainingClient provides operations for:

  • El entrenamiento de modelos personalizados para analizar todos los campos y los valores que se encuentren en los formularios personalizados.Training custom models to analyze all fields and values found in your custom forms. Se devuelve un CustomFormModel que indica los tipos de formulario que el modelo analizará y los campos que se extraerán para cada tipo de formulario.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type.
  • El entrenamiento de modelos personalizados para analizar los campos y los valores concretos que especifique mediante la etiqueta de los formularios personalizados.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Se devuelve un CustomFormModel que indica los campos que el modelo va a extraer, así como la precisión estimada para cada campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field.
  • La administración de los modelos creados en una cuenta.Managing models created in your account.
  • La copia de un modelo personalizado entre recursos de Form Recognizer.Copying a custom model from one Form Recognizer resource to another.

Vea ejemplos de entrenar un modelo y administrar modelos personalizados.See examples for Train a Model and Manage Custom Models.

Nota

Los modelos también se pueden entrenar mediante una interfaz gráfica de usuario, como la herramienta de etiquetado de Form Recognizer.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Ejemplos de códigoCode examples

Estos fragmentos de código muestran cómo realizar las siguientes tareas con la biblioteca cliente de Form Recognizer para .NET:These code snippets show you how to do the following tasks with the Form Recognizer client library for .NET:

Autenticar el clienteAuthenticate the client

Debajo de Main, cree un método denominado AuthenticateClient.Below Main, create a new method named AuthenticateClient. Lo usará en otras tareas para autenticar las solicitudes en el servicio Form Recognizer.You'll use this in other tasks to authenticate your requests to the Form Recognizer service. Este método usa el objeto AzureKeyCredential, de modo que, si es necesario, pueda actualizar la clave de API sin crear otros objetos de cliente.This method uses the AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects.

Importante

Obtenga la clave y el punto de conexión en Azure Portal.Get your key and endpoint from the Azure portal. Si el recurso de Form Recognizer que ha creado en la sección Requisitos previos se ha implementado correctamente, haga clic en el botón Ir al recurso en Pasos siguientes.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. Puede encontrar su clave y punto de conexión en la página de clave y punto de conexión del recurso, en Administración de recursos.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública.Remember to remove the key from your code when you're done, and never post it publicly. En el caso de producción, considere la posibilidad de usar alguna forma segura de almacenar las credenciales, y acceder a ellas.For production, consider using a secure way of storing and accessing your credentials. Por ejemplo, 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;
}

Repita los pasos anteriores para realizar un nuevo método que autentique un cliente de entrenamiento.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;
}

Obtención de recursos para pruebasGet assets for testing

También tendrá que agregar referencias a las direcciones URL de los datos de entrenamiento y prueba.You'll also need to add references to the URLs for your training and testing data. Agréguelas a la raíz de la clase Program.Add these to the root of your Program class.

  • Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

  • A continuación, repita los pasos anteriores para obtener la dirección URL de SAS de un documento individual del contenedor de almacenamiento de blobs.Then, repeat the above steps to get the SAS URL of an individual document in blob storage container. Guárdela también en una ubicación temporal.Save it to a temporary location as well.

  • Por último, guarde la dirección URL de las imágenes de ejemplo que se incluyen a continuación (también están disponibles en 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";

Análisis de diseñoAnalyze layout

Puede usar Form Recognizer para analizar tablas, líneas y palabras de los documentos sin necesidad de entrenar un modelo.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. El valor devuelto es una colección de objetos FormPage, uno para cada página del documento enviado.The returned value is a collection of FormPage objects: one for each page in the submitted document. Para más información sobre la extracción del diseño, consulte la guía conceptual sobre diseño.For more information about layout extraction see the Layout conceptual guide.

Para analizar el contenido de un archivo en una dirección URL determinada, use el método StartRecognizeContentFromUri.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();

Sugerencia

También puede obtener contenido de un archivo local.You can also get content from a local file. Consulte los métodos FormRecognizerClient, como StartRecognizeContent.See the FormRecognizerClient methods, such as StartRecognizeContent. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

En el resto de esta tarea se imprime la información de contenido en la consola.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}'.");
            }
        }
    }
}

ResultadosOutput

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

Análisis de facturasAnalyze invoices

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Entrenamiento de un modelo personalizadoTrain a custom model

En esta sección se muestra cómo entrenar un modelo con sus propios datos.This section demonstrates how to train a model with your own data. Un modelo entrenado puede generar datos estructurados que incluyan las relaciones clave-valor del documento de formulario original.A trained model can output structured data that includes the key/value relationships in the original form document. Después de entrenar el modelo, puede probarlo, volver a entrenarlo y finalmente usarlo para extraer datos de forma confiable de más formularios en función de las propias necesidades.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

También puede entrenar modelos con una interfaz gráfica de usuario, como la herramienta de etiquetado de ejemplo de Form Recognizer.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Entrenamiento de un modelo sin etiquetasTrain a model without labels

Entrene modelos personalizados para analizar todos los campos y valores que se encuentran en los formularios personalizados sin etiquetar manualmente los documentos de entrenamiento.Train custom models to analyze all the fields and values found in your custom forms without manually labeling the training documents. El método siguiente entrena un modelo en un conjunto de documentos dado e imprime el estado del modelo en la consola.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}");

El objeto devuelto CustomFormModel contiene información sobre los tipos de formulario que el modelo puede analizar y los campos que puede extraer de cada tipo de formulario.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. El siguiente bloque de código imprime esta información en la consola.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("");
    }
}

Por último, devuelva el identificador del modelo entrenado para usarlo en pasos posteriores.Finally, return the trained model ID for use in later steps.

    return model.ModelId;
}

ResultadosOutput

Esta respuesta se ha truncado para facilitar la lectura.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:
    ...

Entrenamiento de un modelo con etiquetasTrain a model with labels

También puede entrenar modelos personalizados mediante el etiquetado manual de los documentos de entrenamiento.You can also train custom models by manually labeling the training documents. En algunos escenarios, el entrenamiento con etiquetas conduce a un mejor rendimiento.Training with labels leads to better performance in some scenarios. Para realizar el entrenamiento con etiquetas, debe disponer de archivos de información con etiquetas especiales (\<filename\>.pdf.labels.json) en el contenedor de almacenamiento de blobs junto con los documentos para el entrenamiento.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. La herramienta de etiquetado de ejemplo de Form Recognizer proporciona una interfaz de usuario para ayudarle a crear estos archivos de etiqueta.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Cuando los tenga, puede llamar al método StartTrainingAsync con el parámetro uselabels establecido en 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}");

El valor de CustomFormModel devuelto indica los campos que el modelo puede extraer, junto con su precisión estimada en cada campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. El siguiente bloque de código imprime esta información en la consola.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

Esta respuesta se ha truncado para facilitar la lectura.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
    ... 

Analizar formularios con un modelo personalizadoAnalyze forms with a custom model

En esta sección, se muestra cómo extraer información de clave-valor y otro contenido de los tipos de formulario personalizados, con los modelos que ha entrenado con sus propios formularios.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

Para implementar este escenario, debe haber entrenado ya un modelo para que pueda pasar su identificador al método siguiente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below.

Usará el método 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();

Sugerencia

También puede analizar un archivo local.You can also analyze a local file. Consulte los métodos FormRecognizerClient, como StartRecognizeCustomForms.See the FormRecognizerClient methods, such as StartRecognizeCustomForms. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

El valor devuelto es una colección de objetos RecognizedForm, uno para cada página del documento enviado.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document. El código siguiente imprime los resultados del análisis en la consola.The following code prints the analysis results to the console. Imprime cada campo reconocido y el valor correspondiente, junto con una puntuación de confianza.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}'");
                }
            }
        }
    }
}

ResultadosOutput

Esta respuesta se ha truncado para facilitar la lectura.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
   ...

Análisis de las confirmaciones de recepciónAnalyze receipts

En esta sección se muestra cómo analizar y extraer campos comunes de recibos de EE. UU. mediante un modelo de recibos entrenado previamente.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Para más información sobre el análisis de recibos, consulte la guía conceptual sobre recibos.For more information about receipt analysis, see the Receipts conceptual guide.

Para analizar recibos de una dirección URL, use el método StartRecognizeReceiptsFromUri.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();

Sugerencia

También puede analizar imágenes de recibos locales.You can also analyze local receipt images. Consulte los métodos FormRecognizerClient, como StartRecognizeReceipts.See the FormRecognizerClient methods, such as StartRecognizeReceipts. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

El valor devuelto es una colección de objetos RecognizedReceipt, uno para cada página del documento enviado.The returned value is a collection of RecognizedReceipt objects: one for each page in the submitted document. En el código siguiente se procesa el recibo en el URI especificado y se imprimen los campos y valores principales en la consola.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}'");
            }
        }
    }
}

ResultadosOutput

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'

Análisis de tarjetas de presentaciónAnalyze business cards

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Administración de modelos personalizadosManage custom models

En esta sección se muestra cómo administrar los modelos personalizados almacenados en su cuenta.This section demonstrates how to manage the custom models stored in your account. Realizará varias operaciones en el método siguiente:You'll do multiple operations within the following method:

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

Comprobación del número de modelos de la cuenta de recursos de FormRecognizerCheck the number of models in the FormRecognizer resource account

El siguiente bloque de código comprueba cuántos modelos se han guardado en la cuenta de Form Recognizer y compara esta cifra con el límite de la cuenta.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.

Enumeración de los modelos almacenados actualmente en la cuenta de recursosList the models currently stored in the resource account

El siguiente bloque de código enumera los modelos actuales de la cuenta e imprime los detalles en la consola.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}");
}

ResultadosOutput

Esta respuesta se ha truncado para facilitar la lectura.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

Obtención de un modelo específico mediante el identificador del modeloGet a specific model using the model's ID

El siguiente bloque de código entrena un nuevo modelo (al igual que en la sección Entrenamiento de un modelo) y, luego, recupera una segunda referencia a él mediante su identificador.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("");
    }
}

ResultadosOutput

Esta respuesta se ha truncado para facilitar la lectura.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
...

Eliminación de un modelo de la cuenta de recursosDelete a model from the resource account

También puede eliminar un modelo de su cuenta haciendo referencia a su identificador.You can also delete a model from your account by referencing its ID. Este paso también cierra el método.This step also closes out the method.

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

Ejecución de la aplicaciónRun the application

Ejecute la aplicación desde el directorio de la aplicación con el comando dotnet run.Run the application from your application directory with the dotnet run command.

dotnet run

Limpieza de recursosClean up resources

Si quiere limpiar y eliminar una suscripción a Cognitive Services, puede eliminar el recurso o grupo de recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.Deleting the resource group also deletes any other resources associated with it.

Solución de problemasTroubleshooting

Al interactuar con la biblioteca cliente de Form Recognizer de Cognitive Services mediante el SDK de .NET, los errores devueltos por el servicio producirán una excepción 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. Incluirán el mismo código de estado HTTP que se habría devuelto con una solicitud de API REST.They'll include the same HTTP status code that would have been returned by a REST API request.

Por ejemplo, si envía la imagen de un recibo con un URI no válido, se devuelve un error 400, que indica "solicitud incorrecta".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());
}

Observará que se registra información adicional, como el identificador de la solicitud del cliente de la operación.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

Pasos siguientesNext steps

En este inicio rápido, se ha usado la biblioteca cliente de .NET para Form Recognizer para entrenar modelos y analizar formularios de maneras diferentes.In this quickstart, you used the Form Recognizer .NET client library to train models and analyze forms in different ways. A continuación, obtenga sugerencias para crear un mejor conjunto de datos de entrenamiento y generar modelos más precisos.Next, learn tips to create a better training data set and produce more accurate models.

Importante

Por motivos de simplicidad, en el código de este artículo se usan métodos sincrónicos y almacenamiento de credenciales no protegidas.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons.

Documentación de referencia | Código fuente de la biblioteca | Paquete (Maven) | EjemplosReference documentation | Library source code | Package (Maven) | Samples

Requisitos previosPrerequisites

  • Una suscripción a Azure: cree una cuenta gratuitaAzure subscription - Create one for free
  • La última versión de Java Development Kit (JDK)The current version of the Java Development Kit (JDK)
  • La herramienta de compilación de Gradle u otro administrador de dependencias.The Gradle build tool, or another dependency manager.
  • Una vez que tenga la suscripción de Azure, create a Form Recognizer resource en Azure Portal para obtener la clave y el punto de conexión.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Una vez que se implemente, haga clic en Ir al recurso.After it deploys, click Go to resource.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a Form Recognizer API.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.You'll paste your key and endpoint into the code below later in the quickstart.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Un blob de Azure Storage que contenga un conjunto de datos de entrenamiento.An Azure Storage blob that contains a set of training data. Consulte Creación de un conjunto de datos de aprendizaje para un modelo personalizado para ver sugerencias y opciones para reunir el conjunto de datos de aprendizaje.See Build a training data set for a custom model for tips and options for putting together your training data set. En este inicio rápido puede usar los archivos de la carpeta Train del conjunto de datos de ejemplo (descargue y extraiga 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).

InstalaciónSetting up

Creación de un proyecto de GradleCreate a new Gradle project

En una ventana de la consola (como cmd, PowerShell o Bash), cree un directorio para la aplicación y vaya a él.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

Ejecute el comando gradle init desde el directorio de trabajo.Run the gradle init command from your working directory. Este comando creará archivos de compilación esenciales para Gradle, como build.gradle.kts, que se usa en el runtime para crear y configurar la aplicación.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

Cuando se le solicite que elija un DSL, seleccione Kotlin.When prompted to choose a DSL, select Kotlin.

Instalación de la biblioteca clienteInstall the client library

En este inicio rápido se usa el administrador de dependencias Gradle.This quickstart uses the Gradle dependency manager. Puede encontrar la biblioteca de cliente y la información de otros administradores de dependencias en el repositorio central de Maven.You can find the client library and information for other dependency managers on the Maven Central Repository.

En el archivo build.gradle.kts del proyecto, incluya la biblioteca cliente como una instrucción implementation, junto con los complementos y la configuración necesarios.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

El SDK de Form Recognizer 3.0.0 refleja la versión 2.0 de la API.The Form Recognizer 3.0.0 SDK reflects API version 2.0

Creación de un archivo JavaCreate a Java file

En el directorio de trabajo, ejecute el siguiente comando:From your working directory, run the following command:

mkdir -p src/main/java

Vaya a la nueva carpeta y cree un archivo llamado FormRecognizer.java.Navigate to the new folder and create a file called FormRecognizer.java. Ábralo en el editor o el IDE que prefiera y agregue las siguientes instrucciones import: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;

Sugerencia

¿Desea ver todo el archivo de código de inicio rápido de una vez?Want to view the whole quickstart code file at once? Puede encontrarlo en GitHub, que contiene los ejemplos de código de este inicio rápido.You can find it on GitHub, which contains the code examples in this quickstart.

En la clase FormRecognizer de la aplicación, cree variables para el punto de conexión y la clave del recurso.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

Vaya a Azure Portal.Go to the Azure portal. Si el recurso de Form Recognizer que ha creado en la sección Requisitos previos se ha implementado correctamente, haga clic en el botón Ir al recurso en Pasos siguientes.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. Puede encontrar su clave y punto de conexión en la página de clave y punto de conexión del recurso, en Administración de recursos.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública.Remember to remove the key from your code when you're done, and never post it publicly. En el caso de producción, considere la posibilidad de usar alguna forma segura de almacenar las credenciales, y acceder a ellas.For production, consider using a secure way of storing and accessing your credentials. Para más información, consulte el artículo sobre la seguridad de Cognitive Services.See the Cognitive Services security article for more information.

En el método main de la aplicación, agregue llamadas para los métodos que se usan en este inicio rápido.In the application's main method, add calls for the methods used in this quickstart. Se definirán más adelante.You'll define these later. También tendrá que agregar referencias a las direcciones URL de los datos de entrenamiento y prueba.You'll also need to add references to the URLs for your training and testing data.

  • Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

  • Para obtener una dirección URL de un formulario para prueba, puede usar los pasos anteriores para obtener la dirección URL de SAS de un documento del almacenamiento de blobs.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. También puede tomar la dirección URL de un documento situado en otro lugar.Or, take the URL of a document located elsewhere.

  • Use el método anterior para obtener también la dirección URL de una imagen de recibo.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);

Modelo de objetosObject model

Con Form Recognizer, puede crear dos tipos de cliente diferentes.With Form Recognizer, you can create two different client types. El primero, FormRecognizerClient, se utiliza para consultar el servicio con los campos de formulario y el contenido reconocidos.The first, FormRecognizerClient is used to query the service to recognized form fields and content. El segundo, FormTrainingClient, se usa para crear y administrar los modelos personalizados que puede usar para mejorar el reconocimiento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient proporciona operaciones para:FormRecognizerClient provides operations for:

  • Reconocimiento de los campos de formulario y del contenido, mediante el uso de modelos personalizados entrenados para analizar los formularios personalizados.Recognizing form fields and content, using custom models trained to analyze your custom forms. Estos valores se devuelven en una colección de objetos RecognizedForm.These values are returned in a collection of RecognizedForm objects. Vea el ejemplo Análisis de formularios personalizados.See example Analyze custom forms.
  • El reconocimiento del contenido de los formularios, incluidas tablas, líneas y palabras, sin necesidad de entrenar un modelo.Recognizing form content, including tables, lines and words, without the need to train a model. El contenido del formulario se devuelve en una colección de objetos FormPage.Form content is returned in a collection of FormPage objects. Consulte el ejemplo Análisis de diseño.See example Analyze layout.
  • Reconocimiento de los campos comunes de los recibos de EE. UU. con un modelo de recibo entrenado previamente en el servicio Form Recognizer.Recognizing common fields from US receipts, using a pre-trained receipt model on the Form Recognizer service. Estos campos y metadatos se devuelven en una colección de objetos RecognizedForm.These fields and meta-data are returned in a collection of RecognizedForm objects. Consulte el ejemplo Análisis de confirmaciones de recepción.See example Analyze receipts.

FormTrainingClientFormTrainingClient

FormTrainingClient proporciona operaciones para:FormTrainingClient provides operations for:

  • El entrenamiento de modelos personalizados para analizar todos los campos y los valores que se encuentren en los formularios personalizados.Training custom models to analyze all fields and values found in your custom forms. Se devuelve un CustomFormModel que indica los tipos de formulario que el modelo analizará y los campos que se extraerán para cada tipo de formulario.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type.
  • El entrenamiento de modelos personalizados para analizar los campos y los valores concretos que especifique mediante la etiqueta de los formularios personalizados.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Se devuelve un CustomFormModel que indica los campos que el modelo va a extraer, así como la precisión estimada para cada campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field.
  • La administración de los modelos creados en una cuenta.Managing models created in your account.
  • La copia de un modelo personalizado entre recursos de Form Recognizer.Copying a custom model from one Form Recognizer resource to another.

Nota

Los modelos también se pueden entrenar mediante una interfaz gráfica de usuario, como la herramienta de etiquetado de Form Recognizer.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Ejemplos de códigoCode examples

Estos fragmentos de código muestran cómo realizar las siguientes tareas con la biblioteca cliente de Form Recognizer para Java:These code snippets show you how to do the following tasks with the Form Recognizer client library for Java:

Autenticar el clienteAuthenticate the client

En la parte superior del método main, agregue el código siguiente.At the top of your main method, add the following code. Aquí, autenticará dos objetos de cliente mediante las variables de suscripción que definió anteriormente.Here, you'll authenticate two client objects using the subscription variables you defined above. Usará un objeto AzureKeyCredential, de modo que, si es necesario, pueda actualizar la clave de API sin crear otros objetos de cliente.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();

Análisis de diseñoAnalyze layout

Puede usar Form Recognizer para analizar tablas, líneas y palabras de los documentos sin necesidad de entrenar un modelo.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Para más información sobre la extracción del diseño, consulte la guía conceptual sobre diseño.For more information about layout extraction see the Layout conceptual guide.

Para analizar el contenido de un archivo en una dirección URL determinada, use el método 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();

Sugerencia

También puede obtener contenido de un archivo local.You can also get content from a local file. Consulte los métodos FormRecognizerClient, como beginRecognizeContent.See the FormRecognizerClient methods, such as beginRecognizeContent. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

El valor devuelto es una colección de objetos FormPage, uno para cada página del documento enviado.The returned value is a collection of FormPage objects: one for each page in the submitted document. El código siguiente recorre en iteración estos objetos e imprime los pares clave-valor y los datos de tabla extraídos.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.

Análisis de facturasAnalyze invoices

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Entrenamiento de un modelo personalizadoTrain a custom model

En esta sección se muestra cómo entrenar un modelo con sus propios datos.This section demonstrates how to train a model with your own data. Un modelo entrenado puede generar datos estructurados que incluyan las relaciones clave-valor del documento de formulario original.A trained model can output structured data that includes the key/value relationships in the original form document. Después de entrenar el modelo, puede probarlo, volver a entrenarlo y finalmente usarlo para extraer datos de forma confiable de más formularios en función de las propias necesidades.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

También puede entrenar modelos con una interfaz gráfica de usuario, como la herramienta de etiquetado de ejemplo de Form Recognizer.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Entrenamiento de un modelo sin etiquetasTrain a model without labels

Entrene modelos personalizados para analizar todos los campos y valores que se encuentran en los formularios personalizados sin etiquetar manualmente los documentos de entrenamiento.Train custom models to analyze all fields and values found in your custom forms without manually labeling the training documents.

El método siguiente entrena un modelo en un conjunto de documentos dado e imprime el estado del modelo en la consola.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());

El objeto devuelto CustomFormModel contiene información sobre los tipos de formulario que el modelo puede analizar y los campos que puede extraer de cada tipo de formulario.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. El siguiente bloque de código imprime esta información en la consola.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()));
});

Por último, este método devuelve el identificador único del modelo.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

Entrenamiento de un modelo con etiquetasTrain a model with labels

También puede entrenar modelos personalizados mediante el etiquetado manual de los documentos de entrenamiento.You can also train custom models by manually labeling the training documents. En algunos escenarios, el entrenamiento con etiquetas conduce a un mejor rendimiento.Training with labels leads to better performance in some scenarios. Para realizar el entrenamiento con etiquetas, debe disponer de archivos de información de etiquetas especiales ( <filename>.pdf.labels.json) en el contenedor de almacenamiento de blobs junto con los documentos de entrenamiento.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. La herramienta de etiquetado de ejemplo de Form Recognizer proporciona una interfaz de usuario para ayudarle a crear estos archivos de etiqueta.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Cuando los tenga, puede llamar al método beginTraining con el parámetro useTrainingLabels establecido en 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());

El valor de CustomFormModel devuelto indica los campos que el modelo puede extraer, junto con su precisión estimada en cada campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. El siguiente bloque de código imprime esta información en la consola.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();
}

ResultadosOutput

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

Analizar formularios con un modelo personalizadoAnalyze forms with a custom model

En esta sección, se muestra cómo extraer información de clave-valor y otro contenido de los tipos de formulario personalizados, con los modelos que ha entrenado con sus propios formularios.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

Para implementar este escenario, debe haber entrenado ya un modelo para que pueda pasar su identificador al método siguiente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Consulte la sección Entrenamiento de un modelo.See the Train a model section.

Usará el método 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();

Sugerencia

También puede analizar un archivo local.You can also analyze a local file. Consulte los métodos FormRecognizerClient, como beginRecognizeCustomForms.See the FormRecognizerClient methods, such as beginRecognizeCustomForms. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

El valor devuelto es una colección de objetos RecognizedForm, uno para cada página del documento enviado. El código siguiente imprime los resultados del análisis en la consola.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. Imprime cada campo reconocido y el valor correspondiente, junto con una puntuación de confianza.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()));
    }
}

ResultadosOutput

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.

Análisis de las confirmaciones de recepciónAnalyze receipts

En esta sección se muestra cómo analizar y extraer campos comunes de recibos de EE. UU. mediante un modelo de recibos entrenado previamente.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Para más información sobre el análisis de recibos, consulte la guía conceptual sobre recibos.For more information about receipt analysis, see the Receipts conceptual guide.

Para analizar los recibos a partir de un URI, use el método 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();

Sugerencia

También puede analizar imágenes de recibos locales.You can also analyze local receipt images. Consulte los métodos FormRecognizerClient, como beginRecognizeReceipts.See the FormRecognizerClient methods, such as beginRecognizeReceipts. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

El valor devuelto es una colección de objetos RecognizedReceipt, uno para cada página del documento enviado.The returned value is a collection of RecognizedReceipt objects: one for each page in the submitted document. El siguiente bloque de código recorre en iteración los recibos e imprime los detalles en la consola.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());
        }
    }

El siguiente bloque de código recorre en iteración los elementos detectados en el recibo e imprime los detalles en la consola.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());
                                }
                            }
                        }));
            }
        }
    }
}

ResultadosOutput

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

Análisis de tarjetas de presentaciónAnalyze business cards

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Administración de modelos personalizadosManage custom models

En esta sección se muestra cómo administrar los modelos personalizados almacenados en su cuenta.This section demonstrates how to manage the custom models stored in your account. Como ejemplo, en el código siguiente se realizan todas las tareas de administración del modelo en un único método.The following code does all of the model management tasks in a single method, as an example. Comience por copiar la firma del método siguiente:Start by copying the method signature below:

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

Comprobación del número de modelos de la cuenta de recursos de FormRecognizerCheck the number of models in the FormRecognizer resource account

El siguiente bloque de código comprueba cuántos modelos se han guardado en la cuenta de Form Recognizer y compara esta cifra con el límite de la cuenta.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

Enumeración de los modelos almacenados actualmente en la cuenta de recursosList the models currently stored in the resource account

El siguiente bloque de código enumera los modelos actuales de la cuenta e imprime los detalles en la consola.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());
            });
        }
    });
});

ResultadosOutput

Esta respuesta se ha truncado para facilitar la lectura.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
...

Eliminación de un modelo de la cuenta de recursosDelete a model from the resource account

También puede eliminar un modelo de su cuenta haciendo referencia a su identificador.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());
}

Ejecución de la aplicaciónRun the application

Vuelva al directorio principal del proyecto.Navigate back to your main project directory. Luego, compile la aplicación con el siguiente comando:Then, build the app with the following command:

gradle build

Ejecute la aplicación con el objetivo run:Run the application with the run goal:

gradle run

Limpieza de recursosClean up resources

Si quiere limpiar y eliminar una suscripción a Cognitive Services, puede eliminar el recurso o grupo de recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.Deleting the resource group also deletes any other resources associated with it.

Solución de problemasTroubleshooting

Los clientes de From Recognizer generan excepciones ErrorResponseException.From Recognizer clients raise ErrorResponseException exceptions. Por ejemplo, si intenta proporcionar una dirección URL de origen de archivo no válida, se producirá una excepción ErrorResponseException con un error que indica la causa.For example, if you try to provide an invalid file source URL an ErrorResponseException would be raised with an error indicating the failure cause. En el siguiente fragmento de código, el error se controla correctamente mediante la captura y presentación de la información adicional sobre el error.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());
}

Habilitación del registro de clienteEnable client logging

Los SDK de Azure para Java ofrecen un escenario de registro coherente que ayuda a solucionar los errores de la aplicación y a acelerar su resolución.Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and speeding up their resolution. Los registros generados capturarán el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz.The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. Consulte la wiki de registro para obtener instrucciones sobre cómo habilitar el registro.View the logging wiki for guidance about enabling logging.

Pasos siguientesNext steps

En este inicio rápido, se ha usado la biblioteca cliente de Java para Form Recognizer para entrenar modelos y analizar formularios de maneras diferentes.In this quickstart, you used the Form Recognizer Java client library to train models and analyze forms in different ways. A continuación, obtenga sugerencias para crear un mejor conjunto de datos de entrenamiento y generar modelos más precisos.Next, learn tips to create a better training data set and produce more accurate models.

Importante

  • Por motivos de simplicidad, en el código de este artículo se usan métodos sincrónicos y almacenamiento de credenciales no protegidas.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons. Para más información, consulte la siguiente documentación de referencia.See the reference documentation below.

Documentación de referencia | Código fuente de la biblioteca | Paquete (npm) | EjemplosReference documentation | Library source code | Package (npm) | Samples

Requisitos previosPrerequisites

  • Una suscripción a Azure: cree una cuenta gratuitaAzure subscription - Create one for free
  • La versión actual de Node.jsThe current version of Node.js
  • Un blob de Azure Storage que contenga un conjunto de datos de entrenamiento.An Azure Storage blob that contains a set of training data. Consulte Creación de un conjunto de datos de aprendizaje para un modelo personalizado para ver sugerencias y opciones para reunir el conjunto de datos de aprendizaje.See Build a training data set for a custom model for tips and options for putting together your training data set. En este inicio rápido puede usar los archivos de la carpeta Train del conjunto de datos de ejemplo (descargue y extraiga 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).
  • Una vez que tenga la suscripción de Azure, create a Form Recognizer resource en Azure Portal para obtener la clave y el punto de conexión.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Una vez que se implemente, haga clic en Ir al recurso.After it deploys, click Go to resource.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a Form Recognizer API.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.You'll paste your key and endpoint into the code below later in the quickstart.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

InstalaciónSetting up

Creación de una aplicación Node.jsCreate a new Node.js application

En una ventana de la consola (como cmd, PowerShell o Bash), cree un directorio para la aplicación y vaya a él.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

Ejecute el comando npm init para crear una aplicación de nodo con un archivo package.json.Run the npm init command to create a node application with a package.json file.

npm init

Instalación de la biblioteca clienteInstall the client library

Instale el paquete NPM ai-form-recognizer:Install the ai-form-recognizer NPM package:

npm install @azure/ai-form-recognizer

el archivo package.json de la aplicación se actualizará con las dependencias.Your app's package.json file will be updated with the dependencies.

Cree un archivo llamado index.js, ábralo e importe las bibliotecas siguientes: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");

Sugerencia

¿Desea ver todo el archivo de código de inicio rápido de una vez?Want to view the whole quickstart code file at once? Puede encontrarlo en GitHub, que contiene los ejemplos de código de este inicio rápido.You can find it on GitHub, which contains the code examples in this quickstart.

Cree variables para el punto de conexión y la clave de Azure del recurso.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

Vaya a Azure Portal.Go to the Azure portal. Si el recurso de Form Recognizer que ha creado en la sección Requisitos previos se ha implementado correctamente, haga clic en el botón Ir al recurso en Pasos siguientes.If the Form Recognizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. Puede encontrar su clave y punto de conexión en la página de clave y punto de conexión del recurso, en Administración de recursos.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública.Remember to remove the key from your code when you're done, and never post it publicly. En el caso de producción, considere la posibilidad de usar alguna forma segura de almacenar las credenciales, y acceder a ellas.For production, consider using a secure way of storing and accessing your credentials. Para más información, consulte el artículo sobre la seguridad de Cognitive Services.See the Cognitive Services security article for more information.

Modelo de objetosObject model

Con Form Recognizer, puede crear dos tipos de cliente diferentes.With Form Recognizer, you can create two different client types. El primero, FormRecognizerClient, se utiliza para consultar el servicio con los campos de formulario y el contenido reconocidos.The first, FormRecognizerClient is used to query the service to recognized form fields and content. El segundo, FormTrainingClient, se usa para crear y administrar los modelos personalizados que puede usar para mejorar el reconocimiento.The second, FormTrainingClient is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

FormRecognizerClient proporciona operaciones para:FormRecognizerClient provides operations for:

  • Reconocimiento de los campos de formulario y del contenido mediante el uso de modelos personalizados entrenados para analizar los formularios personalizados.Recognizing form fields and content using custom models trained to analyze your custom forms. Estos valores se devuelven en una colección de objetos RecognizedForm.These values are returned in a collection of RecognizedForm objects.
  • El reconocimiento del contenido de los formularios, incluidas tablas, líneas y palabras, sin necesidad de entrenar un modelo.Recognizing form content, including tables, lines and words, without the need to train a model. El contenido del formulario se devuelve en una colección de objetos FormPage.Form content is returned in a collection of FormPage objects.
  • El reconocimiento de los campos comunes de las recepciones mediante un modelo de recepción entrenado previamente en el servicio Form Recognizer.Recognizing common fields from receipts, using a pre-trained receipt model on the Form Recognizer service. Estos campos y metadatos se devuelven en una colección de RecognizedReceipt.These fields and meta-data are returned in a collection of RecognizedReceipt.

FormTrainingClientFormTrainingClient

FormTrainingClient proporciona operaciones para:FormTrainingClient provides operations for:

  • El entrenamiento de modelos personalizados para analizar todos los campos y los valores que se encuentren en los formularios personalizados.Training custom models to analyze all fields and values found in your custom forms. Se devuelve un CustomFormModel que indica los tipos de formulario que el modelo analizará y los campos que se extraerán para cada tipo de formulario.A CustomFormModel is returned indicating the form types the model will analyze, and the fields it will extract for each form type. Consulte la documentación del servicio sobre el entrenamiento de modelos sin etiquetas si desea obtener una explicación más detallada de la creación de un conjunto de datos de entrenamiento.See the service's documentation on unlabeled model training for a more detailed explanation of creating a training data set.
  • El entrenamiento de modelos personalizados para analizar los campos y los valores concretos que especifique mediante la etiqueta de los formularios personalizados.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Se devuelve un CustomFormModel que indica los campos que el modelo va a extraer, así como la precisión estimada para cada campo.A CustomFormModel is returned indicating the fields the model will extract, as well as the estimated accuracy for each field. Consulte la documentación del servicio sobre el entrenamiento de modelos con etiqueta para obtener una explicación más detallada de cómo aplicar etiquetas a un conjunto de datos de entrenamiento.See the service's documentation on labeled model training for a more detailed explanation of applying labels to a training data set.
  • La administración de los modelos creados en una cuenta.Managing models created in your account.
  • La copia de un modelo personalizado entre recursos de Form Recognizer.Copying a custom model from one Form Recognizer resource to another.

Nota

Los modelos también se pueden entrenar mediante una interfaz gráfica de usuario, como la herramienta de etiquetado de Form Recognizer.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Ejemplos de códigoCode examples

Estos fragmentos de código muestran cómo realizar las siguientes tareas con la biblioteca cliente de Form Recognizer para JavaScript:These code snippets show you how to do the following tasks with the Form Recognizer client library for JavaScript:

Autenticar el clienteAuthenticate the client

Autentique un objeto de cliente mediante las variables de suscripción que ha definido.Authenticate a client object using the subscription variables you defined. Usará un objeto AzureKeyCredential, de modo que, si es necesario, pueda actualizar la clave de API sin crear otros objetos de cliente.You'll use an AzureKeyCredential object, so that if needed, you can update the API key without creating new client objects. También creará un objeto de cliente de entrenamiento.You'll also create a training client object.

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

Obtención de recursos para pruebasGet assets for testing

También tendrá que agregar referencias a las direcciones URL de los datos de entrenamiento y prueba.You'll also need to add references to the URLs for your training and testing data.

  • Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

  • Use las imágenes de envío y de recepción que se incluyen en los ejemplos siguientes (también disponibles en GitHub). O bien, siga los pasos anteriores para obtener la dirección URL de SAS de un documento individual en el almacenamiento de blobs.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.

Análisis de diseñoAnalyze layout

Puede usar Form Recognizer para analizar tablas, líneas y palabras de los documentos sin necesidad de entrenar un modelo.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Para más información sobre la extracción del diseño, consulte la guía conceptual sobre diseño.For more information about layout extraction see the Layout conceptual guide. Para analizar el contenido de un archivo de un URI determinado, use el método beginRecognizeContentFromUrl.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);
});

Sugerencia

También puede obtener contenido de un archivo local.You can also get content from a local file. Consulte los métodos FormRecognizerClient, como beginRecognizeContent.See the FormRecognizerClient methods, such as beginRecognizeContent. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

ResultadosOutput

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

Entrenamiento de un modelo personalizadoTrain a custom model

En esta sección se muestra cómo entrenar un modelo con sus propios datos.This section demonstrates how to train a model with your own data. Un modelo entrenado puede generar datos estructurados que incluyan las relaciones clave-valor del documento de formulario original.A trained model can output structured data that includes the key/value relationships in the original form document. Después de entrenar el modelo, puede probarlo, volver a entrenarlo y finalmente usarlo para extraer datos de forma confiable de más formularios en función de las propias necesidades.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

También puede entrenar modelos con una interfaz gráfica de usuario, como la herramienta de etiquetado de ejemplo de Form Recognizer.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Entrenamiento de un modelo sin etiquetasTrain a model without labels

Entrene modelos personalizados para analizar todos los campos y valores que se encuentran en los formularios personalizados sin etiquetar manualmente los documentos de entrenamiento.Train custom models to analyze all the fields and values found in your custom forms without manually labeling the training documents.

La función siguiente entrena un modelo en un conjunto de documentos determinado e imprime el estado del modelo en la consola.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);
});

ResultadosOutput

Esta es la salida de un modelo entrenado con los datos disponibles en el SDK de JavaScript. La salida de ejemplo se ha recortado para facilitar la lectura.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: 
...

Entrenamiento de un modelo con etiquetasTrain a model with labels

También puede entrenar modelos personalizados mediante el etiquetado manual de los documentos de entrenamiento.You can also train custom models by manually labeling the training documents. En algunos escenarios, el entrenamiento con etiquetas conduce a un mejor rendimiento.Training with labels leads to better performance in some scenarios. Para realizar el entrenamiento con etiquetas, debe disponer de archivos de información con etiquetas especiales (\<filename\>.pdf.labels.json) en el contenedor de almacenamiento de blobs junto con los documentos para el entrenamiento.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. La herramienta de etiquetado de ejemplo de Form Recognizer proporciona una interfaz de usuario para ayudarle a crear estos archivos de etiqueta.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Cuando los tenga, puede llamar al método beginTraining con el parámetro uselabels establecido en 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

Esta es la salida de un modelo entrenado con los datos disponibles en el SDK de JavaScript. La salida de ejemplo se ha recortado para facilitar la lectura.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
...

Analizar formularios con un modelo personalizadoAnalyze forms with a custom model

En esta sección, se muestra cómo extraer información de clave-valor y otro contenido de los tipos de formulario personalizados, con los modelos que ha entrenado con sus propios formularios.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

Para implementar este escenario, debe haber entrenado ya un modelo para que pueda pasar su identificador al método siguiente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Consulte la sección Entrenamiento de un modelo.See the Train a model section.

Usará el método beginRecognizeCustomFormsFromUrl.You'll use the beginRecognizeCustomFormsFromUrl method. El valor devuelto es una colección de objetos RecognizedForm, uno para cada página del documento enviado.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);
});

Sugerencia

También puede analizar archivos locales.You can also analyze local files. Consulte los métodos FormRecognizerClient, como beginRecognizeCustomForms.See the FormRecognizerClient methods, such as beginRecognizeCustomForms. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.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

Análisis de las confirmaciones de recepciónAnalyze receipts

En esta sección se muestra cómo analizar y extraer campos comunes de recibos de EE. UU. mediante un modelo de recibos entrenado previamente.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Para más información sobre el análisis de recibos, consulte la guía conceptual sobre recibos.For more information about receipt analysis, see the Receipts conceptual guide.

Para analizar los recibos de un identificador URI, use el método beginRecognizeReceiptsFromUrl.To analyze receipts from a URI, use the beginRecognizeReceiptsFromUrl method. En el código siguiente se procesa un recibo en el URI especificado y se imprimen los campos y valores principales en la consola.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);
});

Sugerencia

También puede analizar imágenes de recibos locales.You can also analyze local receipt images. Consulte los métodos FormRecognizerClient, como beginRecognizeReceipts.See the FormRecognizerClient methods, such as beginRecognizeReceipts. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

ResultadosOutput

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

Administración de modelos personalizadosManage your custom models

En esta sección se muestra cómo administrar los modelos personalizados almacenados en su cuenta.This section demonstrates how to manage the custom models stored in your account. Como ejemplo, el código siguiente realiza todas las tareas de administración del modelo en una única función.The following code does all of the model management tasks in a single function, as an example.

Obtención del número de modelosGet number of models

El siguiente bloque de código obtiene el número de modelos que hay actualmente en su cuenta.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);
});

Obtención de una lista de modelos en la cuentaGet list of models in account

El siguiente bloque de código proporciona una lista completa de los modelos disponibles en su cuenta, incluida información sobre cuándo se creó el modelo y su estado actual.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);
});

ResultadosOutput

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
}

Obtención de una lista de identificadores de modelo por páginaGet list of model IDs by page

Este bloque de código proporciona una lista paginada de modelos e identificadores de modelo.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);
});

ResultadosOutput

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

Obtención del modelo en función del identificadorGet model by ID

La siguiente función toma un identificador de modelo y obtiene el objeto de modelo correspondiente.The following function takes a model ID and gets the matching model object. Esta función no recibe una llamada de forma predeterminada.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}`);
    }
}

Eliminación de un modelo de la cuenta de recursosDelete a model from the resource account

También puede eliminar un modelo de su cuenta haciendo referencia a su identificador.You can also delete a model from your account by referencing its ID. Esta función elimina el modelo con el identificador especificado.This function deletes the model with the given ID. Esta función no recibe una llamada de forma predeterminada.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

Ejecución de la aplicaciónRun the application

Ejecute la aplicación con el comando node en el archivo de inicio rápido.Run the application with the node command on your quickstart file.

node index.js

Limpieza de recursosClean up resources

Si quiere limpiar y eliminar una suscripción a Cognitive Services, puede eliminar el recurso o grupo de recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.Deleting the resource group also deletes any other resources associated with it.

Solución de problemasTroubleshooting

Habilitamiento de registrosEnable logs

Puede establecer la siguiente variable de entorno para ver los registros de depuración cuando se usa esta biblioteca.You can set the following environment variable to see debug logs when using this library.

export DEBUG=azure*

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, vea los documentos del paquete @azure/logger.For more detailed instructions on how to enable logs, see the @azure/logger package docs.

Pasos siguientesNext steps

En este inicio rápido, se ha usado la biblioteca cliente de Form Recognizer para JavaScript con el fin de entrenar modelos y analizar formularios de diversas maneras.In this quickstart, you used the Form Recognizer JavaScript client library to train models and analyze forms in different ways. A continuación, obtenga sugerencias para crear un mejor conjunto de datos de entrenamiento y generar modelos más precisos.Next, learn tips to create a better training data set and produce more accurate models.

Consulte tambiénSee also

Importante

  • Por motivos de simplicidad, en el código de este artículo se usan métodos sincrónicos y almacenamiento de credenciales no protegidas.The code in this article uses synchronous methods and un-secured credentials storage for simplicity reasons. Para más información, consulte la siguiente documentación de referencia.See the reference documentation below.

Documentación de referencia | Código fuente de la biblioteca | Paquete (PyPi) | EjemplosReference documentation | Library source code | Package (PyPi) | Samples

PrerrequisitosPrerequisites

  • Una suscripción a Azure: cree una cuenta gratuitaAzure subscription - Create one for free
  • Python 3.xPython 3.x
  • Un blob de Azure Storage que contenga un conjunto de datos de entrenamiento.An Azure Storage blob that contains a set of training data. Consulte Creación de un conjunto de datos de aprendizaje para un modelo personalizado para ver sugerencias y opciones para reunir el conjunto de datos de aprendizaje.See Build a training data set for a custom model for tips and options for putting together your training data set. En este inicio rápido puede usar los archivos de la carpeta Train del conjunto de datos de ejemplo (descargue y extraiga 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).
  • Una vez que tenga la suscripción de Azure, create a Form Recognizer resource en Azure Portal para obtener la clave y el punto de conexión.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Una vez que se implemente, haga clic en Ir al recurso.After it deploys, click Go to resource.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a Form Recognizer API.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.You'll paste your key and endpoint into the code below later in the quickstart.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

InstalaciónSetting up

Instalación de la biblioteca clienteInstall the client library

Después de instalar Python, puede instalar la versión más reciente de la biblioteca de cliente de Form Recognizer con:After installing Python, you can install the latest version of the Form Recognizer client library with:

pip install azure-ai-formrecognizer

Nota

La última versión de Form Recognizer refleja la versión 2.0 de la API.The latest Form Recognizer reflects API version 2.0

Creación de una nueva aplicación de PythonCreate a new python application

Cree una aplicación de Python en el IDE o editor que prefiera.Create a new Python application in your preferred editor or IDE. A continuación, importe las bibliotecas siguientes.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

Sugerencia

¿Desea ver todo el archivo de código de inicio rápido de una vez?Want to view the whole quickstart code file at once? Puede encontrarlo en GitHub, que contiene los ejemplos de código de este inicio rápido.You can find it on GitHub, which contains the code examples in this quickstart.

Cree variables para el punto de conexión y la clave de Azure del recurso.Create variables for your resource's Azure endpoint and key.

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

Modelo de objetosObject model

Con Form Recognizer, puede crear dos tipos de cliente diferentes.With Form Recognizer, you can create two different client types. El primero, form_recognizer_client, se utiliza para consultar el servicio con los campos de formulario y el contenido reconocidos.The first, form_recognizer_client is used to query the service to recognized form fields and content. El segundo, form_training_client, se usa para crear y administrar los modelos personalizados que puede usar para mejorar el reconocimiento.The second, form_training_client is use to create and manage custom models that you can use to improve recognition.

FormRecognizerClientFormRecognizerClient

form_recognizer_client proporciona operaciones para:form_recognizer_client provides operations for:

  • Reconocimiento de los campos de formulario y del contenido mediante el uso de modelos personalizados entrenados para analizar los formularios personalizados.Recognizing form fields and content using custom models trained to analyze your custom forms.
  • El reconocimiento del contenido de los formularios, incluidas tablas, líneas y palabras, sin necesidad de entrenar un modelo.Recognizing form content, including tables, lines and words, without the need to train a model.
  • El reconocimiento de los campos comunes de las recepciones mediante un modelo de recepción entrenado previamente en el servicio Form Recognizer.Recognizing common fields from receipts, using a pre-trained receipt model on the Form Recognizer service.

FormTrainingClientFormTrainingClient

form_training_client proporciona operaciones para:form_training_client provides operations for:

  • El entrenamiento de modelos personalizados para analizar todos los campos y los valores que se encuentren en los formularios personalizados.Training custom models to analyze all fields and values found in your custom forms. Consulte la documentación del servicio sobre el entrenamiento de modelos sin etiquetas si desea obtener una explicación más detallada de la creación de un conjunto de datos de entrenamiento.See the service's documentation on unlabeled model training for a more detailed explanation of creating a training data set.
  • El entrenamiento de modelos personalizados para analizar los campos y los valores concretos que especifique mediante la etiqueta de los formularios personalizados.Training custom models to analyze specific fields and values you specify by labeling your custom forms. Consulte la documentación del servicio sobre el entrenamiento de modelos con etiqueta para obtener una explicación más detallada de cómo aplicar etiquetas a un conjunto de datos de entrenamiento.See the service's documentation on labeled model training for a more detailed explanation of applying labels to a training data set.
  • La administración de los modelos creados en una cuenta.Managing models created in your account.
  • La copia de un modelo personalizado entre recursos de Form Recognizer.Copying a custom model from one Form Recognizer resource to another.

Nota

Los modelos también se pueden entrenar mediante una interfaz gráfica de usuario, como la herramienta de etiquetado de Form Recognizer.Models can also be trained using a graphical user interface such as the Form Recognizer Labeling Tool.

Ejemplos de códigoCode examples

En estos fragmentos de código, se muestra cómo realizar las siguientes tareas con la biblioteca cliente de Form Recognizer para Python:These code snippets show you how to do the following tasks with the Form Recognizer client library for Python:

Autenticar el clienteAuthenticate the client

Aquí, autenticará dos objetos de cliente mediante las variables de suscripción que definió anteriormente.Here, you'll authenticate two client objects using the subscription variables you defined above. Usará un objeto AzureKeyCredential, de modo que, si es necesario, pueda actualizar la clave de API sin crear otros objetos de cliente.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))

Obtención de recursos para pruebasGet assets for testing

Es preciso que agregue referencias a las direcciones URL de los datos de entrenamiento y de prueba.You'll need to add references to the URLs for your training and testing data.

  • Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

  • Use las imágenes de envío y de recepción que se incluyen en los ejemplos siguientes (también disponibles en GitHub). O bien, puede seguir los pasos anteriores para obtener la dirección URL de SAS de un documento individual en el almacenamiento de blobs.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

Los fragmentos de código de esta guía usan formularios remotos con acceso mediante direcciones URL.The code snippets in this guide use remote forms accessed by URLs. En cambio, si quiere procesar documentos de formulario locales, consulte los métodos relacionados en la documentación de referencia y los ejemplos.If you want to process local form documents instead, see the related methods in the reference documentation and samples.

Análisis de diseñoAnalyze layout

Puede usar Form Recognizer para analizar tablas, líneas y palabras de los documentos sin necesidad de entrenar un modelo.You can use Form Recognizer to analyze tables, lines, and words in documents, without needing to train a model. Para más información sobre la extracción del diseño, consulte la guía conceptual sobre diseño.For more information about layout extraction see the Layout conceptual guide.

Para analizar el contenido de un archivo en una dirección URL determinada, use el método begin_recognize_content_from_url.To analyze the content of a file at a given URL, use the begin_recognize_content_from_url method. El valor devuelto es una colección de objetos FormPage, uno para cada página del documento enviado.The returned value is a collection of FormPage objects: one for each page in the submitted document. El código siguiente recorre en iteración estos objetos e imprime los pares clave-valor y los datos de tabla extraídos.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))

Sugerencia

También puede obtener contenido de imágenes locales.You can also get content from local images. Consulte los métodos FormRecognizerClient, como begin_recognize_content.See the FormRecognizerClient methods, such as begin_recognize_content. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.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
...

Análisis de facturasAnalyze invoices

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Entrenamiento de un modelo personalizadoTrain a custom model

En esta sección se muestra cómo entrenar un modelo con sus propios datos.This section demonstrates how to train a model with your own data. Un modelo entrenado puede generar datos estructurados que incluyan las relaciones clave-valor del documento de formulario original.A trained model can output structured data that includes the key/value relationships in the original form document. Después de entrenar el modelo, puede probarlo, volver a entrenarlo y finalmente usarlo para extraer datos de forma confiable de más formularios en función de las propias necesidades.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

También puede entrenar modelos con una interfaz gráfica de usuario, como la herramienta de etiquetado de ejemplo de Form Recognizer.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Entrenamiento de un modelo sin etiquetasTrain a model without labels

Entrene modelos personalizados para analizar todos los campos y valores que se encuentran en los formularios personalizados sin etiquetar manualmente los documentos de entrenamiento.Train custom models to analyze all fields and values found in your custom forms without manually labeling the training documents.

El código siguiente usa el cliente de entrenamiento con la función begin_training para entrenar un modelo en un conjunto de documentos determinado.The following code uses the training client with the begin_training function to train a model on a given set of documents. El objeto devuelto CustomFormModel contiene información sobre los tipos de formulario que el modelo puede analizar y los campos que puede extraer de cada tipo de formulario.The returned CustomFormModel object contains information on the form types the model can analyze and the fields it can extract from each form type. El siguiente bloque de código imprime esta información en la consola.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

Esta es la salida para un modelo entrenado con los datos de entrenamiento disponibles en el SDK de Python.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: []

Entrenamiento de un modelo con etiquetasTrain a model with labels

También puede entrenar modelos personalizados mediante el etiquetado manual de los documentos de entrenamiento.You can also train custom models by manually labeling the training documents. En algunos escenarios, el entrenamiento con etiquetas conduce a un mejor rendimiento.Training with labels leads to better performance in some scenarios. El valor de CustomFormModel devuelto indica los campos que el modelo puede extraer, junto con su precisión estimada en cada campo.The returned CustomFormModel indicates the fields the model can extract, along with its estimated accuracy in each field. El siguiente bloque de código imprime esta información en la consola.The following code block prints this information to the console.

Importante

Para realizar el entrenamiento con etiquetas, debe disponer de archivos de información con etiquetas especiales (\<filename\>.pdf.labels.json) en el contenedor de almacenamiento de blobs junto con los documentos para el entrenamiento.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. La herramienta de etiquetado de ejemplo de Form Recognizer proporciona una interfaz de usuario para ayudarle a crear estos archivos de etiqueta.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Cuando los tenga, puede llamar a la función begin_training con el parámetro use_training_labels establecido en 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

Esta es la salida para un modelo entrenado con los datos de entrenamiento disponibles en el SDK de Python.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: []

Analizar formularios con un modelo personalizadoAnalyze forms with a custom model

En esta sección, se muestra cómo extraer información de clave-valor y otro contenido de los tipos de formulario personalizados, con los modelos que ha entrenado con sus propios formularios.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

Para implementar este escenario, debe haber entrenado ya un modelo para que pueda pasar su identificador al método siguiente.In order to implement this scenario, you must have already trained a model so you can pass its ID into the method below. Consulte la sección Entrenamiento de un modelo.See the Train a model section.

Usará el método begin_recognize_custom_forms_from_url.You'll use the begin_recognize_custom_forms_from_url method. El valor devuelto es una colección de objetos RecognizedForm, uno para cada página del documento enviado.The returned value is a collection of RecognizedForm objects: one for each page in the submitted document. El código siguiente imprime los resultados del análisis en la consola.The following code prints the analysis results to the console. Imprime cada campo reconocido y el valor correspondiente, junto con una puntuación de confianza.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
        ))

Sugerencia

También puede analizar imágenes locales.You can also analyze local images. Consulte los métodos FormRecognizerClient, como begin_recognize_custom_forms.See the FormRecognizerClient methods, such as begin_recognize_custom_forms. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.Or, see the sample code on GitHub for scenarios involving local images.

ResultadosOutput

Con el modelo del ejemplo anterior, se proporciona la siguiente salida.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

Análisis de las confirmaciones de recepciónAnalyze receipts

En esta sección se muestra cómo analizar y extraer campos comunes de recibos de EE. UU. mediante un modelo de recibos entrenado previamente.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Para más información sobre el análisis de recibos, consulte la guía conceptual sobre recibos.For more information about receipt analysis, see the Receipts conceptual guide. Para analizar recibos de una dirección URL, use el método begin_recognize_receipts_from_url.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))

Sugerencia

También puede analizar imágenes de recibos locales.You can also analyze local receipt images. Consulte los métodos FormRecognizerClient, como begin_recognize_receipts.See the FormRecognizerClient methods, such as begin_recognize_receipts. O bien, consulte el código de ejemplo en GitHub para escenarios relacionados con imágenes locales.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

Análisis de tarjetas de presentaciónAnalyze business cards

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Administración de modelos personalizadosManage your custom models

En esta sección se muestra cómo administrar los modelos personalizados almacenados en su cuenta.This section demonstrates how to manage the custom models stored in your account.

Comprobación del número de modelos de la cuenta de recursos de FormRecognizerCheck the number of models in the FormRecognizer resource account

El siguiente bloque de código comprueba cuántos modelos se han guardado en la cuenta de Form Recognizer y compara esta cifra con el límite de la cuenta.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

Enumeración de los modelos almacenados actualmente en la cuenta de recursosList the models currently stored in the resource account

El siguiente bloque de código enumera los modelos actuales de la cuenta e imprime los detalles en la consola.The following code block lists the current models in your account and prints their details to the console. También se guarda una referencia al primer modelo.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)

ResultadosOutput

Esta es una salida de ejemplo para la cuenta de prueba.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

Obtención de un modelo específico mediante el identificador del modeloGet a specific model using the model's ID

El siguiente bloque de código usa el identificador de modelo guardado en la sección anterior y lo emplea para recuperar detalles sobre el modelo.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

Esta es la salida de ejemplo para el modelo personalizado creado en el ejemplo anterior.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

Eliminación de un modelo de la cuenta de recursosDelete a model from the resource account

También puede eliminar un modelo de su cuenta haciendo referencia a su identificador.You can also delete a model from your account by referencing its ID. Este código elimina el modelo usado en la sección anterior.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))

Ejecución de la aplicaciónRun the application

Ejecute la aplicación con el comando python en el archivo de inicio rápido.Run the application with the python command on your quickstart file.

python quickstart-file.py

Limpieza de recursosClean up resources

Si quiere limpiar y eliminar una suscripción a Cognitive Services, puede eliminar el recurso o grupo de recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.Deleting the resource group also deletes any other resources associated with it.

Solución de problemasTroubleshooting

GeneralGeneral

La biblioteca cliente de Form Recognizer producirá excepciones definidas en Azure Core.The Form Recognizer client library will raise exceptions defined in Azure Core.

RegistroLogging

Esta biblioteca usa la biblioteca de registro estándar para el registro.This library uses the standard logging library for logging. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel de información.Basic information about HTTP sessions (URLs, headers, and so on) is logged at the INFO level.

El registro detallado del nivel de depuración, incluidos los cuerpos de solicitud y respuesta, y los encabezados no redactados, se puede habilitar en un cliente con el argumento de palabra clave 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)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente: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)

Pasos siguientesNext steps

En este inicio rápido, se ha usado la biblioteca cliente de Python para Form Recognizer para entrenar modelos y analizar formularios de maneras diferentes.In this quickstart, you used the Form Recognizer Python client library to train models and analyze forms in different ways. A continuación, obtenga sugerencias para crear un mejor conjunto de datos de entrenamiento y generar modelos más precisos.Next, learn tips to create a better training data set and produce more accurate models.

Nota

En esta guía se usa cURL para ejecutar llamadas a la API REST.This guide uses cURL to execute REST API calls. También hay código de ejemplo en GitHub que muestra cómo llamar a las API REST con Python.There is also sample code on GitHub that illustrates how to call the REST APIs with Python.

Requisitos previosPrerequisites

  • cURL instalado.cURL installed.
  • Una suscripción a Azure: cree una cuenta gratuitaAzure subscription - Create one for free
  • Un blob de Azure Storage que contenga un conjunto de datos de entrenamiento.An Azure Storage blob that contains a set of training data. Consulte Creación de un conjunto de datos de aprendizaje para un modelo personalizado para ver sugerencias y opciones para reunir el conjunto de datos de aprendizaje.See Build a training data set for a custom model for tips and options for putting together your training data set. En este inicio rápido puede usar los archivos de la carpeta Train del conjunto de datos de ejemplo (descargue y extraiga 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).
  • Una vez que tenga la suscripción de Azure, create a Form Recognizer resource en Azure Portal para obtener la clave y el punto de conexión.Once you have your Azure subscription, create a Form Recognizer resource in the Azure portal to get your key and endpoint. Una vez que se implemente, haga clic en Ir al recurso.After it deploys, click Go to resource.
    • Necesitará la clave y el punto de conexión del recurso que cree para conectar la aplicación a Form Recognizer API.You will need the key and endpoint from the resource you create to connect your application to the Form Recognizer API. En una sección posterior de este mismo inicio rápido pegará la clave y el punto de conexión en el código siguiente.You'll paste your key and endpoint into the code below later in the quickstart.
    • Puede usar el plan de tarifa gratis (F0) para probar el servicio y actualizarlo más adelante a un plan de pago para producción.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Una dirección URL para la imagen de un recibo.A URL for an image of a receipt. En este inicio rápido, puede usar una imagen de ejemplo.You can use a sample image for this quickstart.
  • La dirección URL de una imagen de una tarjeta de presentación.A URL for an image of a business card. En este inicio rápido, puede usar una imagen de ejemplo.You can use a sample image for this quickstart.
  • La dirección URL de una imagen de un recibo.A URL for an image of an invoice. Puede usar un documento de ejemplo para esta guía de inicio rápido.You can use a sample document for this quickstart.

Análisis de diseñoAnalyze layout

Puede usar Form Recognizer para analizar y extraer tablas, marcas de selección, texto y estructuras de los documentos sin necesidad de entrenar un modelo.You can use Form Recognizer to analyze and extract tables, selection marks, text, and structure in documents, without needing to train a model. Para más información sobre la extracción del diseño, consulte la guía conceptual sobre diseño.For more information about layout extraction see the Layout conceptual guide. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Reemplace \"{your-document-url} por una de las direcciones URL de ejemplo.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}'}"

Recibirá una respuesta 202 (Success) que incluye un encabezado Operation-Location.You'll receive a 202 (Success) response that includes am Operation-Location header. El valor de este encabezado contiene un identificador de operación que puede usar para consultar el estado de la operación asincrónica y obtener los resultados.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. En el siguiente ejemplo, la cadena después de analyzeResults/ es el identificador de operación.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

Obtención de los resultados del diseñoGet layout results

Tras la llamada a la API Analyze Layout , llame a la API Get Analyze Layout Result para obtener el estado de la operación y los datos extraídos.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. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Reemplace {resultId} por el identificador de operación del paso anterior.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}"

Examen de los resultadosExamine the results

Recibirá una respuesta 200 (success) con contenido JSON.You'll receive a 200 (success) response with JSON content.

Consulte la siguiente imagen de una factura y su correspondiente salida JSON.See the following invoice image and its corresponding JSON output. La salida se ha abreviado por motivos de simplicidad.The output has been shortened for simplicity. El nodo "readResults" contiene cada línea de texto con su correspondiente posición de cuadro de límite en la página.The "readResults" node contains every line of text with its respective bounding box placement on the page. El nodo "selectionMarks" (en la versión preliminar v2.1) muestra todas las casillas de selección (casilla, botón de opción) y si su estado es "seleccionado" o "no seleccionado".The "selectionMarks" node (in v2.1 preview) shows every selection mark (checkbox, radio mark) and whether its status is "selected" or "unselected". En la sección "pageResults" se incluyen las tablas extraídas.The "pageResults" section includes the tables extracted. Para cada tabla, se extraen el texto, el índice de filas y columnas, la expansión de filas y columnas, el rectángulo de selección, etc.For each table, the text, row, and column index, row and column spanning, bounding box, and more are extracted.

Documento de instrucciones de proyecto de Contoso con una tabla.

{
    "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"
                                ]
                            },
                            ...
                        ]
                    },
                    ...
                ]
            }
        ]
    }
}

Análisis de facturasAnalyze invoices

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Entrenamiento de un modelo personalizadoTrain a custom model

Para entrenar un modelo personalizado, necesitará un conjunto de datos de entrenamiento en un blob de Azure Storage.To train a custom model, you'll need a set of training data in an Azure Storage blob. Necesita un mínimo de cinco formularios rellenados (documentos PDF o imágenes) de la misma estructura y tipo.You need a minimum of five filled-in forms (PDF documents and/or images) of the same type/structure. Consulte Build a training data set for a custom model (Creación de un conjunto de datos de aprendizaje para un modelo personalizado) para ver sugerencias y opciones para reunir los datos de entrenamiento.See Build a training data set for a custom model for tips and options for putting together your training data.

El entrenamiento sin datos etiquetados es la operación predeterminada y la más sencilla.Training without labeled data is the default operation and is simpler. De forma alternativa, puede etiquetar manualmente algunos o todos los datos de entrenamiento de antemano.Alternatively, you can manually label some or all of your training data beforehand. Se trata de un proceso más complejo, pero el resultado es un modelo mejor entrenado.This is a more complex process but results in a better trained model.

Nota

También puede entrenar modelos con una interfaz gráfica de usuario, como la herramienta de etiquetado de ejemplo de Form Recognizer.You can also train models with a graphical user interface such as the Form Recognizer sample labeling tool.

Entrenamiento de un modelo sin etiquetasTrain a model without labels

Para entrenar un modelo de Form Recognizer con los documentos del contenedor de blobs de Azure, llame a la API Train Custom Model mediante la ejecución del siguiente comando de cURL.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. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.

  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.

  3. Reemplace {SAS URL} por la dirección URL de la firma de acceso compartido (SAS) del contenedor de almacenamiento de blobs de Azure.Replace {SAS URL} with the Azure Blob storage container's shared access signature (SAS) URL. Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

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}'}"

Recibirá una respuesta 201 (Success) con un encabezado Location (Ubicación).You'll receive a 201 (Success) response with a Location header. El valor de este encabezado es el identificador del nuevo modelo que se va a entrenar.The value of this header is the ID of the new model being trained.

Entrenamiento de un modelo con etiquetasTrain a model with labels

Para realizar el entrenamiento con etiquetas, debe disponer de archivos de información con etiquetas especiales (\<filename\>.pdf.labels.json) en el contenedor de almacenamiento de blobs junto con los documentos para el entrenamiento.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. La herramienta de etiquetado de ejemplo de Form Recognizer proporciona una interfaz de usuario para ayudarle a crear estos archivos de etiqueta.The Form Recognizer sample labeling tool provides a UI to help you create these label files. Una vez que los tenga, puede llamar a la API Train Custom Model con el parámetro "useLabelFile" establecido en true en el cuerpo JSON.Once you have them, you can call the Train Custom Model API, with the "useLabelFile" parameter set to true in the JSON body.

Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.

  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.

  3. Reemplace {SAS URL} por la dirección URL de la firma de acceso compartido (SAS) del contenedor de almacenamiento de blobs de Azure.Replace {SAS URL} with the Azure Blob storage container's shared access signature (SAS) URL. Para recuperar la dirección URL de la firma de acceso compartido para los datos de entrenamiento del modelo personalizado, vaya al recurso de almacenamiento en Azure Portal y seleccione la pestaña Explorador de Storage. Vaya al contenedor, haga clic con el botón derecho y seleccione Obtener firma de acceso compartido.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. Es importante obtener la firma de acceso compartido para el contenedor, no para la propia cuenta de almacenamiento.It's important to get the SAS for your container, not for the storage account itself. Asegúrese de que los permisos de lectura y enumeración están marcados y haga clic en Create (Crear).Make sure the Read and List permissions are checked, and click Create. A continuación, copie el valor de la sección URL en una ubicación temporal.Then copy the value in the URL section to a temporary location. Debe tener el 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>.

    Recuperación de la dirección URL de SAS

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

Recibirá una respuesta 201 (Success) con un encabezado Location (Ubicación).You'll receive a 201 (Success) response with a Location header. El valor de este encabezado es el identificador del nuevo modelo que se va a entrenar.The value of this header is the ID of the new model being trained.

Obtención de los resultados del entrenamientoGet training results

Una vez iniciada la operación de entrenamiento, utilizará una nueva operación, Obtención del modelo personalizado , para comprobar el estado del entrenamiento.After you've started the train operation, you use a new operation, Get Custom Model to check the training status. Pase el identificador de modelo a esta llamada API para comprobar el estado del entrenamiento:Pass the model ID into this API call to check the training status:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la clave de suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription key.
  2. Reemplace {subscription key} por la clave de suscripción.Replace {subscription key} with your subscription key
  3. Reemplace {model ID} por el identificador de modelo que recibió en el paso anterior.Replace {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}"

Recibirá una respuesta 200 (Success) con un cuerpo JSON con el formato siguiente:You'll receive a 200 (Success) response with a JSON body in the following format. Observe el campo "status".Notice the "status" field. Este tendrá el valor "ready" una vez que se complete el entrenamiento.This will have the value "ready" once training is complete. Si el modelo no ha finalizado el entrenamiento, tendrá que consultar de nuevo el servicio volviendo a ejecutar el comando.If the model is not finished training, you'll need to query the service again by rerunning the command. Se recomienda un intervalo de uno o varios segundos entre llamadas.We recommend an interval of one second or more between calls.

El campo "modelId" contiene el identificador del modelo que se está entrenando.The "modelId" field contains the ID of the model you're training. Lo necesitará para el siguiente paso.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"
    ]
  }
}

Analizar formularios con un modelo personalizadoAnalyze forms with a custom model

A continuación, utilizará el modelo recién entrenado para analizar un documento y extraerá de él tanto los pares clave-valor como las tablas.Next, you'll use your newly trained model to analyze a document and extract key-value pairs and tables from it. Llame a la API Analyze Form mediante la ejecución del siguiente comando cURL.Call the Analyze Form API by running the following cURL command. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo de la clave de suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained from your Form Recognizer subscription key. Lo encontrará en la pestaña Información general del recurso Form Recognizer.You can find it on your Form Recognizer resource Overview tab.
  2. Reemplace {model ID} por el identificador de modelo que recibió en la sección anterior.Replace {model ID} with the model ID that you received in the previous section.
  3. Reemplace {SAS URL} por una dirección URL de SAS en el archivo de Azure Storage.Replace {SAS URL} with an SAS URL to your file in Azure storage. Siga los pasos de la sección de entrenamiento, pero en lugar de obtener una dirección URL de SAS para todo el contenedor de blobs, obtenga una para el archivo específico que desea analizar.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. Reemplace {subscription key} por la clave de suscripción.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}' } "

Recibirá una respuesta 202 (Success) con un encabezado Operation-Location (Operación-ubicación).You'll receive a 202 (Success) response with an Operation-Location header. El valor de este encabezado incluye un identificador de resultados que se usa para realizar el seguimiento de los resultados de la operación de análisis.The value of this header includes a results ID you use to track the results of the Analyze operation. Guarde este identificador de resultados para el siguiente paso.Save this results ID for the next step.

Obtención de los resultados del análisisGet the Analyze results

Llame a la API Get Analyze Form Result para consultar los resultados de la operación de análisis.Call the Get Analyze Form Result API to query the results of the Analyze operation.

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo de la clave de suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained from your Form Recognizer subscription key. Lo encontrará en la pestaña Información general del recurso Form Recognizer.You can find it on your Form Recognizer resource Overview tab.
  2. Reemplace {result ID} por el identificador que recibió en la sección anterior.Replace {result ID} with the ID that you received in the previous section.
  3. Reemplace {subscription key} por la clave de suscripción.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}"

Recibirá una respuesta 200 (Success) con un cuerpo JSON con el formato siguiente:You'll receive a 200 (Success) response with a JSON body in the following format. La salida se ha abreviado por motivos de simplicidad.The output has been shortened for simplicity. Observe el campo "status" situado cerca de la parte inferior.Notice the "status" field near the bottom. Este tendrá el valor "succeeded" cuando se complete la operación de análisis.This will have the value "succeeded" when the Analyze operation is complete. Si la operación de análisis no se ha completado, tendrá que consultar de nuevo el servicio volviendo a ejecutar el comando.If the Analyze operation hasn't completed, you'll need to query the service again by rerunning the command. Se recomienda un intervalo de uno o varios segundos entre llamadas.We recommend an interval of one second or more between calls.

En los modelos personalizados entrenados sin etiquetas, las tablas y asociaciones de pares clave-valor se encuentran en el nodo "pageResults" de la salida JSON.In custom models trained without labels, the key/value pair associations and tables are in the "pageResults" node of the JSON output. En los modelos personalizados entrenados con etiquetas, las asociaciones de pares clave-valor se encuentran en el nodo "documentResults".In custom models trained with labels, the key/value pair associations are in the "documentResults" node. Si también especificó la extracción de texto sin formato mediante el parámetro de URL includeTextDetails, el nodo "readResults" mostrará el contenido y las posiciones de todo el texto del 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.

Esta salida JSON de ejemplo se ha abreviado por motivos de simplicidad.This sample JSON output has been shortened for simplicity.

{
  "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": []
  }
}

Mejora de los resultadosImprove results

Examine los valores de "confidence" de cada resultado de clave-valor en el nodo "pageResults".Examine the "confidence" values for each key/value result under the "pageResults" node. También debe examinar las puntuaciones de confianza del nodo "readResults", que se corresponden a la operación de lectura de texto.You should also look at the confidence scores in the "readResults" node, which correspond to the text read operation. La confianza de los resultados de la lectura no afecta a la confianza de los resultados de la extracción de los pares clave-valor, por lo que debe comprobar ambos.The confidence of the read results does not affect the confidence of the key/value extraction results, so you should check both.

  • Si las puntuaciones de confianza de la operación de lectura son bajas, intente mejorar la calidad de los documentos de entrada (consulte Requisitos de entrada).If the confidence scores for the read operation are low, try to improve the quality of your input documents (see Input requirements).
  • Si las puntuaciones de confianza de la operación de extracción de pares clave-valor son bajas, asegúrese de que los documentos que se están analizando sean del mismo tipo que los documentos usados en el conjunto de entrenamiento.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. Si los documentos del conjunto de entrenamiento tienen variantes de apariencia, considere la posibilidad de dividirlos en carpetas diferentes y entrenar un modelo para cada 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.

El objetivo de puntuación de confianza dependerá de su caso de uso pero, por lo general, se recomienda establecer una puntuación del 80 % o superior.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. Para casos más confidenciales, como la lectura de registros médicos o instrucciones de facturación, se recomienda una puntuación del 100 %.For more sensitive cases, like reading medical records or billing statements, a score of 100% is recommended.

Análisis de las confirmaciones de recepciónAnalyze receipts

En esta sección se muestra cómo analizar y extraer campos comunes de recibos de EE. UU. mediante un modelo de recibos entrenado previamente.This section demonstrates how to analyze and extract common fields from US receipts, using a pre-trained receipt model. Para más información sobre el análisis de recibos, consulte la guía conceptual sobre recibos.For more information about receipt analysis, see the Receipts conceptual guide. Para empezar a analizar un recibo, llame a la API Analyze Receipt con el siguiente comando cURL.To start analyzing a receipt, call the Analyze Receipt API using the cURL command below. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {your receipt URL} por la dirección URL de una imagen del recibo.Replace {your receipt URL} with the URL address of a receipt image.
  3. Reemplace {subscription key> con la clave de suscripción que copió en el paso anterior.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}'}"

Recibirá una respuesta 202 (Success) que incluye un encabezado Operation-Location.You'll receive a 202 (Success) response that includes am Operation-Location header. El valor de este encabezado contiene un identificador de operación que puede usar para consultar el estado de la operación asincrónica y obtener los resultados.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. En el siguiente ejemplo, la cadena después de operations/ es el identificador de operación.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

Obtención de los resultados del reciboGet the receipt results

Tras la llamada a la API Analyze Receipt, llame a la API Get Receipt Result para obtener el estado de la operación y los datos extraídos.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. Antes de ejecutar el comando, realice estos cambios:Before you run the command, make these changes:

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la clave de suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription key. Lo encontrará en la pestaña Información general del recurso Form Recognizer.You can find it on your Form Recognizer resource Overview tab.
  2. Reemplace {operationId} por el identificador de operación del paso anterior.Replace {operationId} with the operation ID from the previous step.
  3. Reemplace {subscription key} por la clave de suscripción.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}"

Examen de la respuestaExamine the response

Recibirá una respuesta 200 (Success) con la salida JSON.You'll receive a 200 (Success) response with JSON output. El primer campo, "status", indica el estado de la operación.The first field, "status", indicates the status of the operation. Si la operación se ha completado, e campo "readResults" contiene todas las líneas de texto que se ha extrajeron del recibo y el campo "documentResults" contiene información de del par clave-valor de las partes más importantes del recibo.If the operation is complete, the "readResults" field contains every line of text that was extracted from the receipt, and the "documentResults" field contains key/value information for the most relevant parts of the receipt. Si la operación no está completa, el valor de "status" será "running" o "notStarted", y debe llamar a la API de nuevo, ya sea manualmente o a través de un 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. Se recomienda un intervalo de uno o varios segundos entre llamadas.We recommend an interval of one second or more between calls.

Consulte la siguiente imagen del recibo y su correspondiente salida JSON.See the following receipt image and its corresponding JSON output. La salida se ha abreviado para que se pueda leer mejor.The output has been shortened for readability.

Un recibo del almacén de Contoso

El nodo "readResults" contiene todo el texto reconocido (si el parámetro includeTextDetails opcional se ha establecido en true).The "readResults" node contains all of the recognized text (if you set the optional includeTextDetails parameter to true). El texto se organiza por página, después, por líneas y, finalmente, por palabras individuales.Text is organized by page, then by line, then by individual words. El nodo "documentResults" contiene los valores específicos del recibo que el modelo ha descubierto.The "documentResults" node contains the receipt-specific values that the model discovered. Aquí encontrará pares clave-valor útiles como los impuestos, el total, la dirección del vendedor, etc.This is where you'll find useful key/value pairs like the tax, total, merchant address, and so on.

{
  "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"
            ]
          }
        }
      }
    ]
  }
}

Análisis de tarjetas de presentaciónAnalyze business cards

Importante

Esta característica no está disponible en la versión de API seleccionada.This feature isn't available in the selected API version.

Administración de modelos personalizadosManage custom models

Obtener una lista de modelos personalizadosGet a list of custom models

Use la API List Custom Models del comando siguiente para devolver una lista de todos los modelos personalizados que pertenecen a la suscripción.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. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.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}"

Recibirá una respuesta 200 correcta, con datos JSON como los siguientes.You'll receive a 200 success response, with JSON data like the following. El elemento "modelList" contiene todos los modelos creados y su información.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"
}

Obtención de un modelo específicoGet a specific model

Para recuperar información detallada sobre un modelo personalizado específico, use la API Get Custom Model en el siguiente comando.To retrieve detailed information about a specific custom model, use the Get Custom Model API in the following command.

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Reemplace {modelId} por el identificador del modelo personalizado que desea buscar.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}"

Recibirá una respuesta 200 correcta, con datos JSON como los siguientes.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"
      }
    ]
  }
}

Eliminación de un modelo de la cuenta de recursosDelete a model from the resource account

También puede eliminar un modelo de su cuenta haciendo referencia a su identificador.You can also delete a model from your account by referencing its ID. Este comando llama a la API Delete Custom Model API para eliminar el modelo usado en la sección anterior.This command calls the Delete Custom Model API to delete the model used in the previous section.

  1. Reemplace {Endpoint} por el punto de conexión que obtuvo con la suscripción de Form Recognizer.Replace {Endpoint} with the endpoint that you obtained with your Form Recognizer subscription.
  2. Reemplace {subscription key} con la clave de suscripción que copió en el paso anterior.Replace {subscription key} with the subscription key you copied from the previous step.
  3. Reemplace {modelId} por el identificador del modelo personalizado que desea buscar.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}"

Recibirá una respuesta 204 de operación correcta que indica que el modelo está marcado para su eliminación.You'll receive a 204 success response, indicating that your model is marked for deletion. Los artefactos del modelo se eliminarán en un plazo máximo de 48 horas.Model artifacts will be removed within 48 hours.

Pasos siguientesNext steps

En este inicio rápido, ha usado la API REST de Form Recognizer para entrenar modelos y analizar formularios de maneras diferentes.In this quickstart, you used the Form Recognizer REST API to train models and analyze forms in different ways. A continuación, consulte la documentación de referencia para explorar la API de Form Recognizer con mayor profundidad.Next, see the reference documentation to explore the Form Recognizer API in more depth.