Compartir a través de

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

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 delimitadora, de los documentos.
  • Documento: analice entidades, pares clave-valor, tablas y marcas de selección de documentos mediante el modelo general de documentos prediseñados.
  • Lectura: lea información sobre elementos textuales, como palabras y líneas de página, además de información sobre el idioma del texto.
  • Prediseñados: analice datos de determinados tipos de documentos comunes (como recibos, facturas, tarjetas de visita o documentos de identidad) mediante modelos prediseñados.
  • 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 sus documentos.
  • Clasificadores: cree clasificadores personalizados para clasificar documentos en clases predefinidas.

documentación de referencia de | Package (NPM) | 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 escribir este artículo, se está llevando a cabo el cambio de nombre de Azure Form Recognizer a Azure AI Document Intelligence, por lo que "Form Recognizer" y "Document Intelligence" se pueden usar indistintamente en algunos casos.

Instalación del paquete @azure/ai-form-recognizer

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

npm install @azure/ai-form-recognizer

Cómo empezar

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node: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 = createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

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

Entornos admitidos actualmente

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerrequisitos

Creación de un recurso de Form Recognizer

Nota: En el momento de escribir este artículo, Azure Portal sigue haciendo referencia al recurso como un recurso de "Form Recognizer". En el futuro, esto puede actualizarse a un recurso de "Inteligencia de documentos". Por ahora, en la siguiente documentación se usa el nombre "Form Recognizer".

Document Intelligence admite el acceso multiservicio y de un solo servicio. Cree un recurso de Cognitive Services si planea acceder a varios servicios cognitivos con 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:Portal de Azure

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>

Crear y autenticar un cliente

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

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

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

Usar una clave de API

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

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 usarlos de la siguiente manera:

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

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

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 identidad 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 deberá registrar una aplicación de AAD y conceder acceso al servicio asignando el "Cognitive Services User" rol a la entidad de servicio (nota: otros roles, por "Owner" ejemplo, no concederán los permisos necesarios, solo "Cognitive Services User" bastarán con 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_ID, AZURE_CLIENT_SECRET.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

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

Nubes soberanas

Conéctese a entornos alternativos en la nube de Azure (como Azure China o Azure Government) especificando la opción al crear el audience cliente. Utilice la KnownFormRecognizerAudience enumeración para seleccionar el valor correcto para su entorno.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient, KnownFormRecognizerAudience } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com", // endpoint
  credential,
  {
    audience: KnownFormRecognizerAudience.AzureGovernment,
  }
);

Si no especifica la audience opción, el valor predeterminado es adecuado para la nube pública de Azure (https://cognitiveservices.azure.com).

Conceptos clave

DocumentAnalysisClient

DocumentAnalysisClient Proporciona operaciones para analizar documentos de entrada mediante modelos personalizados y prediseñados. Tiene tres métodos:

  • beginAnalyzeDocument, que extrae datos de un flujo de archivos de documento de entrada mediante un modelo personalizado o precompilado dado por su ID de modelo. Para obtener información sobre los modelos precompilados compatibles con todos los recursos y sus identificadores/salidas de modelos, consulte la documentación del servicio de los modelos.
  • beginAnalyzeDocumentFromUrl, que realiza la misma función que beginAnalyzeDocument, pero envía una URL de acceso público 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 de acuerdo con 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 la creación de un conjunto de datos de entrenamiento para obtener una explicación más detallada de la aplicación de etiquetas a un conjunto de datos de entrenamiento.
  • beginComposeDocumentModel Inicia una operación para componer varios modelos en un solo modelo. Cuando se utiliza para el reconocimiento de formularios personalizados, el nuevo modelo compuesto realizará primero una clasificación de los documentos de entrada para determinar cuál de sus submodelos es el 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 from el 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 habilite la administración de modelos en el recurso.
  • getOperation y listOperations permiten ver el estado de las operaciones de creación de modelos, incluso las operaciones que están en curso o que han fallado. Las operaciones se retienen durante 24 horas.

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

A continuación, en la sección de ejemplo "Construir un modelo", se pueden encontrar fragmentos de código de ejemplo que ilustran el uso de DocumentModelAdministrationClient para crear un modelo.

Operaciones de larga duración

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

En Azure AI Document Intelligence, las operaciones que crean modelos (incluidos los modelos de copia y composició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 sondeador devuelto por el begin<operation-name> método. En la sección siguiente se proporcionan fragmentos de código de ejemplo para ilustrar el uso de operaciones de larga duración.

Ejemplos

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

Analizar un documento con un ID 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 documentos del modelo (puede haber varios, como en un modelo compuesto).

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";

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

const modelId = "<model id>";
const path = "<path to a document>";
const readStream = createReadStream(path);

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 content '${field.content}' 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}"`);
  }
}

Analizar un documento desde una URL

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

Uso de modelos de documentos predefinidos

El beginAnalyzeDocument método también admite la extracción de campos de ciertos 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 precompilados se pueden proporcionar como cadenas de ID de modelo (lo mismo que los modelos de documentos personalizados, consulte la sección otros modelos precompilados a continuación) o mediante un DocumentModel objeto. Cuando se utiliza un DocumentModel, el SDK de Document Intelligence para JavaScript proporciona un tipo de 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 para la versión actual de la API de servicio (2022-08-31) se pueden encontrar en el directorio de prebuilt ejemplos. En el siguiente ejemplo, usaremos el PrebuiltReceiptModel archivo fromprebuilt-receipt.ts [] en ese directorio.

Dado que la principal ventaja del análisis basado en -es que las restricciones de DocumentModeltipo de TypeScript son más fuertes, el siguiente ejemplo se escribe en TypeScript utilizando la sintaxis del módulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReceiptModel } from "../samples-dev/prebuilt/prebuilt-receipt.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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

Alternativamente, como se mencionó anteriormente, en lugar de usar PrebuiltReceiptModel, que produce el tipo de retorno más fuerte, se puede usar el ID de modelo del recibo precompilado ("recibo prediseñado"), pero los campos del documento no se escribirán fuertemente en TypeScript y los nombres de campo generalmente estarán en "PascalCase" en lugar de "camelCase".

Otros modelos preconstruidos

¡No estás limitado a los recibos! Hay algunos modelos preconstruidos para elegir, y hay más en camino. Cada modelo precompilado tiene su propio conjunto de campos admitidos:

  • Recibos, utilizando PrebuiltReceiptModel (como se indicó anteriormente) o el ID "prebuilt-receipt"de modelo de recibo prediseñado.
  • Tarjetas de visita, utilizando PrebuiltBusinessCardModel o su ID "prebuilt-businessCard"de modelo.
  • Facturas, utilizando PrebuiltInvoiceModel o su ID "prebuilt-invoice"de modelo.
  • Documentos de identidad (como licencias de conducir y pasaportes), utilizando PrebuiltIdDocumentModel o su identificación de modelo "prebuilt-idDocument".
  • W2 Tax Forms (Estados Unidos), utilizando PrebuiltTaxUsW2Model o su ID "prebuilt-tax.us.w2"de modelo .
  • Tarjetas de seguro médico (Estados Unidos), utilizando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] o su ID de "prebuilt-healthInsuranceCard.us"modelo .

Cada uno de los modelos precompilados anteriores produce 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 producen documentsarchivos . Son las siguientes:

  • El modelo de diseño precompilado (consulte Usar el "diseño" prediseñado a continuación), que extrae información sobre los elementos de diseño básico (OCR), como páginas y tablas.
  • El modelo de documento general precompilado (consulte Usar el "documento" precompilado a continuación), que agrega pares clave-valor (asociaciones dirigidas entre elementos de página, como elementos etiquetados) a la información generada por el modelo de diseño.
  • El modelo de lectura precompilado (consulte Usar la lectura predefinida a continuación), que extrae solo elementos textuales, como palabras y líneas de página, junto con información sobre el idioma del documento.

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 acceder a los campos de todos los modelos precompilados mediante programación mediante el getDocumentModel método (por sus identificadores de modelo) e DocumentModelAdministrationClient inspeccionando el docTypes campo en el resultado.

Usar el "diseño" preconstruido

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

Dado que la principal ventaja del análisis basado en -es que las restricciones de DocumentModeltipo de TypeScript son más fuertes, el siguiente ejemplo se escribe en TypeScript utilizando la sintaxis del módulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltLayoutModel } from "../samples-dev/prebuilt/prebuilt-layout.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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}"`);
  }
}

Utilice el "documento" precompilado

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 etiqueta en iteraciones anteriores del servicio Document Intelligence, pero ahora se proporciona como un modelo precompilado que funciona con una amplia variedad de documentos. Proporcionamos una instancia fuertemente tipada denominada DocumentModelPrebuiltDocumentModel que invoca este modelo o, como siempre, su ID "prebuilt-document" de modelo se puede usar directamente.

Dado que la principal ventaja del análisis basado en -es que las restricciones de DocumentModeltipo de TypeScript son más fuertes, el siguiente ejemplo se escribe en TypeScript utilizando la sintaxis del módulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltDocumentModel } from "../samples-dev/prebuilt/prebuilt-document.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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})`);
  }
}

Utilice el archivo precompilado "read"

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

Dado que la principal ventaja del análisis basado en -es que las restricciones de DocumentModeltipo de TypeScript son más fuertes, el siguiente ejemplo se escribe en TypeScript utilizando la sintaxis del módulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReadModel } from "../samples-dev/prebuilt/prebuilt-read.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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}"`);
    }
  }
}

function* getTextOfSpans(content, spans) {
  for (const span of spans) {
    yield content.slice(span.offset, span.offset + span.length);
  }
}

Clasificar un documento

El servicio Document Intelligence admite clasificadores de documentos personalizados que pueden clasificar documentos en un conjunto de categorías predefinidas en función de 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 en el caso anterior, este método acepta un archivo o secuencia que contiene el documento que se va a clasificar y, en su lugar, tiene un beginClassifyDocumentFromUrl homólogo que acepta una dirección URL de acceso público a un documento.

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

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

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

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

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

const result = await poller.pollUntilDone();

if (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})`,
  );
}

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

Crear un modelo

El SDK también admite la creación de modelos mediante la DocumentModelAdministrationClient clase. Al crear un modelo a partir de datos de entrenamiento etiquetados, se crea un nuevo modelo que se entrena 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 en SAS para 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 basado en su contenido. Para obtener 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.

Mientras proporcionamos estos métodos para la creación de modelos programáticos, el equipo de servicios de 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 crea un modelo de documento personalizado mediante una dirección URL codificada en SAS para un contenedor de Azure Storage preexistente:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

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

const containerSasUrl = "<SAS url to the blob container storing training documents>";

// 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>"}`);
  }
}

Los clasificadores personalizados se crean de manera similar utilizando 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 enumerarlos. En el ejemplo siguiente se muestra cómo iterar a través de los modelos de un recurso (esto incluirá tanto los modelos personalizados en el recurso como los modelos precompilados que son comunes a todos los recursos), obtener un modelo por ID y eliminar un modelo.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

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

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

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

Registro

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

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener 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 componer modelos, enumerar operaciones de administración de modelos y eliminar modelos.

Contribución

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