Share via

Biblioteca cliente de Azure AI Document Intelligence para JavaScript: versión 5.0.0

  • Artículo

Azure AI Document Intelligence es un servicio en la nube que usa el aprendizaje automático para analizar texto y datos estructurados de los documentos. Incluye las siguientes características principales:

  • Diseño: extraiga texto, estructuras de tabla y marcas de selección, junto con sus coordenadas de región delimitador, de los documentos.
  • Documento: analice entidades, pares clave-valor, tablas y marcas de selección de documentos mediante el modelo de documento precompilado general.
  • Leer: leer información sobre elementos textuales, como palabras de página y líneas, además de la información del idioma de texto.
  • Precompilado: analice datos de determinados tipos de documentos comunes (como recibos, facturas, tarjetas de presentación o documentos de identidad) mediante modelos creados previamente.
  • Personalizado: cree modelos personalizados para extraer texto, valores de campo, marcas de selección y datos de tabla de documentos. Los modelos personalizados se crean con sus propios datos, por lo que se adaptan a los documentos.
  • Clasificadores: cree clasificadores personalizados para clasificar documentos en clases predefinidas.

Código fuente | Paquete (NPM) | Documentación de referencia de API | Documentación del producto | Ejemplos

Nota

El servicio Document Intelligence se conocía anteriormente como "Azure Form Recognizer". Estos servicios son uno y el mismo, y el @azure/ai-form-recognizer paquete para JavaScript es el paquete del SDK de Azure para el servicio Azure AI Document Intelligence. En el momento de escribirlo, el cambio de nombre de Azure Form Recognizer a La inteligencia de documentos de Azure AI está en curso, por lo que "Form Recognizer" y "Inteligencia de documentos" se pueden usar indistintamente en algunos casos.

Instalar el paquete @azure/ai-form-recognizer

Instale la biblioteca cliente de Azure Document Intelligence para JavaScript con npm:

npm install @azure/ai-form-recognizer

Introducción

const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
const { DefaultAzureCredential } = require("@azure/identity");

const fs = require("fs");

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential
);

// Document Intelligence supports many different types of files.
const file = fs.createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

const { pages, tables, styles, keyValuePairs, entities, documents } = await poller.pollUntilDone();

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Creación de un recurso de Form Recognizer

Nota: En el momento de escribir, el Azure Portal todavía hace referencia al recurso como un recurso de "Form Recognizer". En el futuro, esto se puede actualizar a un recurso de "Inteligencia de documentos". Por ahora, la siguiente documentación usa el nombre "Form Recognizer".

La inteligencia de documentos admite el acceso de varios servicios y de un solo servicio. Cree un recurso de Cognitive Services si tiene previsto acceder a varios servicios de Cognitive Services en un único punto de conexión o clave. Para acceder únicamente a Form Recognizer, cree un recurso de Form Recognizer.

Puede crear el recurso mediante .

Opción 1:Azure Portal

Opción 2:CLI de Azure.

A continuación se muestra un ejemplo de cómo puede crear un recurso de Form Recognizer mediante la CLI:

# Create a new resource group to hold the Form Recognizer resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos:

az cognitiveservices account create --kind FormRecognizer --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

Creación y autenticación de un cliente

Para interactuar con el servicio De inteligencia de documentos, deberá seleccionar o DocumentAnalysisClient , DocumentModelAdministrationClienty crear una instancia de este tipo. En los ejemplos siguientes, usaremos DocumentAnalysisClient. Para crear una instancia de cliente para acceder a document Intelligence API, necesitará el endpoint de su recurso de Form Recognizer y un credential. Los clientes pueden usar un AzureKeyCredential con una clave de API del recurso o un que TokenCredential use RBAC de Azure Active Directory para autorizar al cliente.

Puede encontrar el punto de conexión del recurso de Form Recognizer en Azure Portal o mediante el fragmento de código de la CLI de Azure siguiente:

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "properties.endpoint"

Uso de una clave de API

Use Azure Portal para ir al recurso de Form Recognizer y recuperar una clave de API, o bien use el fragmento de código de la CLI de Azure siguiente:

Nota: A veces, la clave de API se conoce como "clave de suscripción" o "clave de API de suscripción".

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Una vez que tenga una clave de API y un punto de conexión, puede usarlo de la siguiente manera:

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

const client = new DocumentAnalysisClient("<endpoint>", new AzureKeyCredential("<API key>"));

Uso de Azure Active Directory

La autorización de clave de API se usa en la mayoría de los ejemplos, pero también puede autenticar el cliente con Azure Active Directory mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install @azure/identity

Para autenticarse mediante una entidad de servicio, también tendrá que registrar una aplicación de AAD y conceder acceso al servicio mediante la asignación del "Cognitive Services User" rol a la entidad de servicio (tenga en cuenta que otros roles "Owner" como no concederán los permisos necesarios, solo "Cognitive Services User" bastarán para ejecutar los ejemplos y el código de ejemplo).

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new DocumentAnalysisClient("<endpoint>", new DefaultAzureCredential());

Conceptos clave

DocumentAnalysisClient

DocumentAnalysisClient proporciona operaciones para analizar documentos de entrada mediante modelos personalizados y creados previamente. Tiene tres métodos:

  • beginAnalyzeDocument, que extrae datos de un flujo de archivo de documento de entrada mediante un modelo personalizado o precompilado proporcionado por su identificador de modelo. Para obtener información sobre los modelos precompilados admitidos en todos los recursos y sus identificadores o salidas de modelo, consulte la documentación del servicio de los modelos.
  • beginAnalyzeDocumentFromUrl, que realiza la misma función que beginAnalyzeDocument, pero envía una dirección URL accesible públicamente de un archivo en lugar de una secuencia de archivos.

DocumentModelAdministrationClient

DocumentModelAdministrationClient proporciona operaciones para administrar (crear, leer, enumerar y eliminar) modelos en el recurso:

  • beginBuildDocumentModel inicia una operación para crear un nuevo modelo de documento a partir de su propio conjunto de datos de entrenamiento. El modelo creado puede extraer campos según un esquema personalizado. Se espera que los datos de entrenamiento se encuentren en un contenedor de Azure Storage y se organicen según una convención determinada. Consulte la documentación del servicio sobre cómo crear un conjunto de datos de entrenamiento para obtener una explicación más detallada de cómo aplicar etiquetas a un conjunto de datos de entrenamiento.
  • beginComposeDocumentModel inicia una operación para componer varios modelos en un único modelo. Cuando se usa para el reconocimiento de formularios personalizado, el nuevo modelo compuesto realizará primero una clasificación de los documentos de entrada para determinar cuál de sus submodelos es más adecuado.
  • beginCopyModelTo inicia una operación para copiar un modelo personalizado de un recurso a otro (o incluso al mismo recurso). Requiere un CopyAuthorization elemento del recurso de destino, que se puede generar mediante el getCopyAuthorization método .
  • getResourceDetails recupera información sobre los límites del recurso, como el número de modelos personalizados y el número máximo de modelos que puede admitir el recurso.
  • getDocumentModel, listDocumentModelsy deleteDocumentModel habilitan la administración de modelos en el recurso.
  • getOperation y listOperations permiten ver el estado de las operaciones de creación de modelos, incluso aquellas que están en curso o que han fallado. Las operaciones se conservan durante 24 horas.

Tenga en cuenta que los modelos también se pueden crear mediante la interfaz gráfica de usuario del servicio Document Intelligence: Document Intelligence Studio.

A continuación se muestran fragmentos de código de ejemplo que ilustran el uso de DocumentModelAdministrationClient para compilar un modelo, en la sección de ejemplo "Compilar un modelo".

Operaciones de larga duración

Las operaciones de larga duración (LRO) son operaciones que constan de una solicitud inicial enviada al servicio para iniciar una operación, seguida de sondear un resultado en un intervalo determinado para determinar si la operación se ha completado y si se ha producido un error o se ha realizado correctamente. En última instancia, el LRO producirá un error o generará un resultado.

En Inteligencia de documentos de Azure AI, las operaciones que crean modelos (incluidos los modelos de copia y redacción), así como las operaciones de análisis y extracción de datos son LRO. Los clientes del SDK proporcionan métodos asincrónicos begin<operation-name> que devuelven Promise<PollerLike> objetos. El PollerLike objeto representa la operación , que se ejecuta de forma asincrónica en la infraestructura del servicio, y un programa puede esperar a que se complete la operación llamando y esperando el pollUntilDone método en el sondeo devuelto desde el begin<operation-name> método . Se proporcionan fragmentos de código de ejemplo para ilustrar el uso de operaciones de larga duración en la sección siguiente.

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código de JavaScript que ilustran patrones comunes que se usan en las bibliotecas cliente de Document Intelligence.

Análisis de un documento con un identificador de modelo

El beginAnalyzeDocument método puede extraer campos y datos de tabla de documentos. El análisis puede usar un modelo personalizado, entrenado con sus propios datos o un modelo precompilado proporcionado por el servicio (consulte Usar modelos precompilados a continuación). Un modelo personalizado se adapta a sus propios documentos, por lo que solo debe usarse con documentos de la misma estructura que uno de los tipos de documento del modelo (puede haber varios, como en un modelo compuesto).

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

const fs = require("fs");

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const modelId = "<model id>";
  const path = "<path to a document>";

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(modelId, readStream, {
    onProgress: ({ status }) => {
      console.log(`status: ${status}`);
    },
  });

  // There are more fields than just these three
  const { documents, pages, tables } = await poller.pollUntilDone();

  console.log("Documents:");
  for (const document of documents || []) {
    console.log(`Type: ${document.docType}`);
    console.log("Fields:");
    for (const [name, field] of Object.entries(document.fields)) {
      console.log(
        `Field ${name} has value '${field.value}' with a confidence score of ${field.confidence}`
      );
    }
  }
  console.log("Pages:");
  for (const page of pages || []) {
    console.log(`Page number: ${page.pageNumber} (${page.width}x${page.height} ${page.unit})`);
  }

  console.log("Tables:");
  for (const table of tables || []) {
    console.log(`- Table (${table.columnCount}x${table.rowCount})`);
    for (const cell of table.cells) {
      console.log(`  - cell (${cell.rowIndex},${cell.columnIndex}) "${cell.content}"`);
    }
  }
}

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

Análisis de un documento desde una dirección URL

Como alternativa a proporcionar una secuencia legible, se puede proporcionar una dirección URL accesible públicamente mediante el beginAnalyzeDocumentFromUrl método . "Accesible públicamente" significa que los orígenes de direcciones URL deben ser accesibles desde la infraestructura del servicio (es decir, una dirección URL de intranet privada o direcciones URL que usen secretos basados en encabezados o certificados, no funcionará, ya que el servicio De inteligencia de documentos debe poder acceder a la dirección URL). Sin embargo, la propia dirección URL podría codificar un secreto, como una dirección URL de blob de Azure Storage que contiene un token de SAS en los parámetros de consulta.

Uso de modelos de documentos precompilados

El beginAnalyzeDocument método también admite la extracción de campos de determinados tipos de documentos comunes, como recibos, facturas, tarjetas de presentación, documentos de identidad, etc. mediante modelos precompilados proporcionados por el servicio Document Intelligence. Los modelos creados previamente se pueden proporcionar como cadenas de identificador de modelo (igual que los modelos de documentos personalizados), consulte la sección otros modelos precompilados a continuación) o mediante un DocumentModel objeto . Cuando se usa , DocumentModelel SDK de Document Intelligence para JavaScript proporciona un tipo TypeScript mucho más seguro para los documentos extraídos resultantes en función del esquema del modelo y se convertirá para usar convenciones de nomenclatura de JavaScript.

Los objetos de ejemplo DocumentModel de la versión actual de la API de servicio (2022-08-31) se pueden encontrar en el prebuilt directorio de ejemplos. En el ejemplo siguiente, usaremos el PrebuiltReceiptModel del archivo [prebuilt-receipt.ts] en ese directorio.

Dado que la principal ventaja del DocumentModelanálisis basado en es una restricción de tipo TypeScript más sólida, el ejemplo siguiente se escribe en TypeScript mediante la sintaxis del módulo ECMAScript:

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the file from the above-linked sample directory so that it can be imported in this module
import { PrebuiltReceiptModel } from "./prebuilt/prebuilt-receipt";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to your receipt document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));

  // The PrebuiltReceiptModel `DocumentModel` instance encodes both the model ID and a stronger return type for the operation
  const poller = await client.beginAnalyzeDocument(PrebuiltReceiptModel, readStream, {
    onProgress: ({ status }) => {
      console.log(`status: ${status}`);
    },
  });

  const {
    documents: [receiptDocument],
  } = await poller.pollUntilDone();

  // The fields of the document constitute the extracted receipt data.
  const receipt = receiptDocument.fields;

  if (receipt === undefined) {
    throw new Error("Expected at least one receipt in analysis result.");
  }

  console.log(`Receipt data (${receiptDocument.docType})`);
  console.log("  Merchant Name:", receipt.merchantName?.value);

  // The items of the receipt are an example of a `DocumentArrayValue`
  if (receipt.items !== undefined) {
    console.log("Items:");
    for (const { properties: item } of receipt.items.values) {
      console.log("- Description:", item.description?.value);
      console.log("  Total Price:", item.totalPrice?.value);
    }
  }

  console.log("  Total:", receipt.total?.value);
}

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

Como alternativa, como se mencionó anteriormente, en lugar de usar PrebuiltReceiptModel, que genera el tipo de valor devuelto más seguro, se puede usar el identificador de modelo del recibo precompilado ("recibo precompilado"), pero los campos de documento no se escribirán fuertemente en TypeScript y los nombres de campo generalmente estarán en "PascalCase" en lugar de "camelCase".

Otros modelos precompilados

¡No se limita a los recibos! Hay algunos modelos precompilados entre los que elegir, con más información en el camino. Cada modelo precompilado tiene su propio conjunto de campos admitidos:

  • Recibos, mediante PrebuiltReceiptModel (como se indica anteriormente) o el identificador "prebuilt-receipt"del modelo de recibo precompilado .
  • Tarjetas de presentación, mediante PrebuiltBusinessCardModel o su identificador de "prebuilt-businessCard"modelo .
  • Facturas, mediante PrebuiltInvoiceModel o su identificador de "prebuilt-invoice"modelo .
  • Documentos de identidad (como licencias de conducir y pasaportes), mediante PrebuiltIdDocumentModel o su identificador de "prebuilt-idDocument"modelo .
  • Formularios fiscales W2 (Estados Unidos), mediante PrebuiltTaxUsW2Model o su identificador de "prebuilt-tax.us.w2"modelo .
  • Tarjetas de seguro de salud (Estados Unidos), usando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] o su id. de "prebuilt-healthInsuranceCard.us"modelo .

Cada uno de los modelos precompilados anteriores genera documents (instancias extraídas del esquema de campo del modelo). También hay tres modelos precompilados que no tienen esquemas de campo y, por lo tanto, no generan documents. Son las siguientes:

Para obtener información sobre los campos de todos estos modelos, consulte la documentación del servicio de los modelos precompilados disponibles.

También se puede tener acceso a los campos de todos los modelos precompilados mediante programación mediante el getDocumentModel método (por sus identificadores de modelo) de DocumentModelAdministrationClient e inspeccionar el docTypes campo en el resultado.

Usar el precompilado "layout"

El "prebuilt-layout" modelo extrae solo los elementos básicos del documento, como las páginas (que constan de palabras y líneas de texto y marcas de selección), tablas y estilos de texto visual junto con sus regiones delimitador y abarca dentro del contenido de texto de los documentos de entrada. Proporcionamos una instancia fuertemente tipada DocumentModel denominada PrebuiltLayoutModel que invoca este modelo, o como siempre se puede usar su identificador "prebuilt-layout" de modelo directamente.

Dado que la principal ventaja del DocumentModelanálisis basado en es una restricción de tipo TypeScript más sólida, el ejemplo siguiente se escribe en TypeScript mediante la sintaxis del módulo ECMAScript:

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltLayoutModel } from "./prebuilt/prebuilt-layout";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltLayoutModel, readStream);
  const { pages, tables } = await poller.pollUntilDone();

  for (const page of pages || []) {
    console.log(`- Page ${page.pageNumber}: (${page.width}x${page.height} ${page.unit})`);
  }

  for (const table of tables || []) {
    console.log(`- Table (${table.columnCount}x${table.rowCount})`);
    for (const cell of table.cells) {
      console.log(`  cell [${cell.rowIndex},${cell.columnIndex}] "${cell.content}"`);
    }
  }
}

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

Usar el precompilado "document"

El "prebuilt-document" modelo extrae información sobre los pares clave-valor (asociaciones dirigidas entre elementos de página, como campos etiquetados) además de las propiedades generadas por el método de extracción de diseño. Este modelo de documento precompilado (general) proporciona una funcionalidad similar a los modelos personalizados entrenados sin información de etiquetas en iteraciones anteriores del servicio De inteligencia de documentos, pero ahora se proporciona como un modelo precompilado que funciona con una amplia variedad de documentos. Proporcionamos una instancia fuertemente tipada DocumentModel denominada PrebuiltDocumentModel que invoca este modelo, o como siempre se puede usar su identificador "prebuilt-document" de modelo directamente.

Dado que la principal ventaja del DocumentModelanálisis basado en es una restricción de tipo TypeScript más sólida, el ejemplo siguiente se escribe en TypeScript mediante la sintaxis del módulo ECMAScript:

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltDocumentModel } from "./prebuilt/prebuilt-document";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltDocumentModel, readStream);

  // `pages`, `tables` and `styles` are also available as in the "layout" example above, but for the sake of this
  // example we won't show them here.
  const { keyValuePairs } = await poller.pollUntilDone();

  if (!keyValuePairs || keyValuePairs.length <= 0) {
    console.log("No key-value pairs were extracted from the document.");
  } else {
    console.log("Key-Value Pairs:");
    for (const { key, value, confidence } of keyValuePairs) {
      console.log("- Key  :", `"${key.content}"`);
      console.log("  Value:", `"${value?.content ?? "<undefined>"}" (${confidence})`);
    }
  }
}

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

Usar el precompilado "read"

El "prebuilt-read" modelo extrae información textual en un documento, como palabras y párrafos, y analiza el idioma y el estilo de escritura (por ejemplo, escrito a mano frente al conjunto de tipos) de ese texto. Proporcionamos una instancia fuertemente tipada DocumentModel denominada PrebuiltReadModel que invoca este modelo, o como siempre se puede usar su identificador "prebuilt-read" de modelo directamente.

Dado que la principal ventaja del DocumentModelanálisis basado en es una restricción de tipo TypeScript más sólida, el ejemplo siguiente se escribe en TypeScript mediante la sintaxis del módulo ECMAScript:

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltReadModel } from "./prebuilt/prebuilt-read";

// See the samples directory for a definition of this helper function.
import { getTextOfSpans } from "./utils";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltReadModel, readStream);

  // The "prebuilt-read" model (`beginReadDocument` method) only extracts information about the textual content of the
  // document, such as page text elements, text styles, and information about the language of the text.
  const { content, pages, languages } = await poller.pollUntilDone();

  if (!pages || pages.length <= 0) {
    console.log("No pages were extracted from the document.");
  } else {
    console.log("Pages:");
    for (const page of pages) {
      console.log("- Page", page.pageNumber, `(unit: ${page.unit})`);
      console.log(`  ${page.width}x${page.height}, angle: ${page.angle}`);
      console.log(
        `  ${page.lines && page.lines.length} lines, ${page.words && page.words.length} words`
      );

      if (page.lines && page.lines.length > 0) {
        console.log("  Lines:");

        for (const line of page.lines) {
          console.log(`  - "${line.content}"`);
        }
      }
    }
  }

  if (!languages || languages.length <= 0) {
    console.log("No language spans were extracted from the document.");
  } else {
    console.log("Languages:");
    for (const languageEntry of languages) {
      console.log(
        `- Found language: ${languageEntry.locale} (confidence: ${languageEntry.confidence})`
      );

      for (const text of getTextOfSpans(content, languageEntry.spans)) {
        const escapedText = text.replace(/\r?\n/g, "\\n").replace(/"/g, '\\"');
        console.log(`  - "${escapedText}"`);
      }
    }
  }
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Clasificación de un documento

El servicio Document Intelligence admite clasificadores de documentos personalizados que pueden clasificar documentos en un conjunto de categorías predefinidas basadas en un conjunto de datos de entrenamiento. Los documentos se pueden clasificar con un clasificador personalizado mediante el beginClassifyDocument método de DocumentAnalysisClient. Al igual beginAnalyzeDocument que anteriormente, este método acepta un archivo o una secuencia que contiene el documento que se va a clasificar y tiene un beginClassifyDocumentFromUrl homólogo que acepta una dirección URL accesible públicamente en un documento en su lugar.

En el ejemplo siguiente se muestra cómo clasificar un documento mediante un clasificador personalizado:

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

async function main() {
  const endpoint = "<endpoint>";
  const credential = new AzureKeyCredential("<api key>");

  const documentUrl =
    "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/invoice/Invoice_1.pdf";

  const client = new DocumentAnalysisClient(endpoint, credential);

  const poller = await client.beginClassifyDocumentFromUrl("<classifier id>", documentUrl);

  const result = await poller.pollUntilDone();

  if (result.documents === undefined || result.documents.length === 0) {
    throw new Error("Failed to extract any documents.");
  }

  for (const document of result.documents) {
    console.log(
      `Extracted a document with type '${document.docType}' on page ${document.boundingRegions?.[0].pageNumber} (confidence: ${document.confidence})`
    );
  }
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Para obtener información sobre cómo entrenar un clasificador personalizado, consulte la sección sobre el entrenamiento del clasificador al final de la sección siguiente.

Compilación de un modelo

El SDK también admite la creación de modelos mediante la DocumentModelAdministrationClient clase . La creación de un modelo a partir de datos de entrenamiento etiquetados crea un nuevo modelo entrenado en sus propios documentos y el modelo resultante podrá reconocer valores de las estructuras de esos documentos. La operación de creación de modelos acepta una dirección URL codificada por SAS en un contenedor de blobs de Azure Storage que contiene los documentos de entrenamiento. La infraestructura del servicio Document Intelligence leerá los archivos del contenedor y creará un modelo en función de su contenido. Para más información sobre cómo crear y estructurar un contenedor de datos de entrenamiento, consulte la documentación del servicio Document Intelligence para crear un modelo.

Aunque proporcionamos estos métodos para la creación de modelos mediante programación, el equipo del servicio Document Intelligence ha creado una aplicación web interactiva, Document Intelligence Studio, que permite crear y administrar modelos en la web.

Por ejemplo, el siguiente programa compila un modelo de documento personalizado mediante una dirección URL codificada por SAS en un contenedor de Azure Storage existente:

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

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const containerSasUrl = "<SAS url to the blob container storing training documents>";

  const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));

  // You must provide the model ID. It can be any text that does not start with "prebuilt-".
  // For example, you could provide a randomly generated GUID using the "uuid" package.
  // The second parameter is the SAS-encoded URL to an Azure Storage container with the training documents.
  // The third parameter is the build mode: one of "template" (the only mode prior to 4.0.0-beta.3) or "neural".
  // See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes.
  const poller = await client.beginBuildDocumentModel("<model ID>", containerSasUrl, "template", {
    // The model description is optional and can be any text.
    description: "This is my new model!",
    onProgress: ({ status }) => {
      console.log(`operation status: ${status}`);
    },
  });
  const model = await poller.pollUntilDone();

  console.log("Model ID:", model.modelId);
  console.log("Description:", model.description);
  console.log("Created:", model.createdOn);

  // A model may contain several document types, which describe the possible object structures of fields extracted using
  // this model

  console.log("Document Types:");
  for (const [docType, { description, fieldSchema: schema }] of Object.entries(
    model.docTypes ?? {}
  )) {
    console.log(`- Name: "${docType}"`);
    console.log(`  Description: "${description}"`);

    // For simplicity, this example will only show top-level field names
    console.log("  Fields:");

    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
      console.log(`  - "${fieldName}" (${fieldSchema.type})`);
      console.log(`    ${fieldSchema.description ?? "<no description>"}`);
    }
  }
}

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

Los clasificadores personalizados se compilan de forma similar mediante el beginBuildDocumentClassifier método en lugar de beginBuildDocumentModel. Consulte el ejemplo de clasificador de compilación para obtener más información sobre cómo crear un clasificador personalizado, ya que los datos de entrenamiento de entrada se proporcionan en un formato ligeramente diferente. Para obtener información sobre cómo crear un conjunto de datos de entrenamiento para un clasificador personalizado, consulte la documentación del servicio Document Intelligence.

Administración de modelos

DocumentModelAdministrationClient también proporciona varios métodos para acceder a los modelos y enumerar. En el ejemplo siguiente se muestra cómo recorrer en iteración los modelos de un recurso (esto incluirá ambos modelos personalizados en el recurso, así como modelos precompilados que son comunes a todos los recursos), obtener un modelo por identificador y eliminar un modelo.

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

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));

  // Produces an async iterable that supports paging (`PagedAsyncIterableIterator`). The `listDocumentModels` method will only
  // iterate over model summaries, which do not include detailed schema information. Schema information is only returned
  // from `getDocumentModel` as part of the full model information.
  const models = client.listDocumentModels();
  let i = 1;
  for await (const summary of models) {
    console.log(`Model ${i++}:`, summary);
  }

  // The iterable is paged, and the application can control the flow of paging if needed
  i = 1;
  for await (const page of client.listDocumentModels().byPage()) {
    for (const summary of page) {
      console.log(`Model ${i++}`, summary);
    }
  }

  // We can also get a full ModelInfo by ID. Here we only show the basic information. See the documentation and the
  // `getDocumentModel` sample program for information about the `docTypes` field, which contains the model's document type
  // schemas.
  const model = await client.getDocumentModel("<model ID>");
  console.log("ID", model.modelId);
  console.log("Created:", model.createdOn);
  console.log("Description: ", model.description ?? "<none>");

  // A model can also be deleted by its model ID. Once it is deleted, it CANNOT be recovered.
  const modelIdToDelete = "<model ID that should be deleted forever>";
  await client.deleteDocumentModel(modelIdToDelete);
}

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

Los métodos listDocumentClassifiers similares y getDocumentClassifier están disponibles para enumerar y obtener información sobre clasificadores personalizados, además de deleteDocumentClassifier para eliminar clasificadores personalizados.

Solución de problemas

Para obtener ayuda con la solución de problemas, consulte la guía de solución de problemas.

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para ver ejemplos de código detallados que muestran cómo usar esta biblioteca, incluidas varias características y métodos que no se muestran en la sección "Ejemplos" anterior, como copiar y redactar modelos, enumerar las operaciones de administración de modelos y eliminar modelos.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones