Biblioteca de clientes do Azure AI Document Intelligence para JavaScript – versão 5.0.0

  • Artigo

O Azure AI Document Intelligence é um serviço de nuvem que usa o aprendizado de máquina para analisar texto e dados estruturados de seus documentos. Ele inclui os seguintes recursos de main:

  • Layout – extraia texto, estruturas de tabela e marcas de seleção, juntamente com suas coordenadas de região delimitador, de documentos.
  • Documento – Analisar entidades, pares chave-valor, tabelas e marcas de seleção de documentos usando o modelo de documento predefinido geral.
  • Leitura – Leia informações sobre elementos textuais, como palavras de página e linhas, além de informações de linguagem de texto.
  • Predefinido – analise dados de determinados tipos de documentos comuns (como recibos, faturas, cartões de visita ou documentos de identidade) usando modelos predefinidos.
  • Personalizado – crie modelos personalizados para extrair texto, valores de campo, marcas de seleção e dados de tabela de documentos. Modelos personalizados são criados com seus próprios dados, portanto, eles são adaptados aos seus documentos.
  • Classificadores – crie classificadores personalizados para categorizar documentos em classes predefinidas.

Pacote de | Código-fonte (NPM) | Documentação de referência da API | Documentação do produto | Exemplos

Observação

O serviço de Inteligência de Documentos era anteriormente conhecido como "Azure Reconhecimento de Formulários". Esses serviços são um e o mesmo, e o @azure/ai-form-recognizer pacote para JavaScript é o pacote do SDK do Azure para o serviço de Inteligência de Documentos de IA do Azure. No momento da gravação, a renomeação da Reconhecimento de Formulários do Azure para o Azure AI Document Intelligence está em andamento, de modo que "Reconhecimento de Formulários" e "Inteligência de Documentos" podem ser usados de forma intercambiável em alguns casos.

Instalar o pacote @azure/ai-form-recognizer

Instale a biblioteca de clientes do Azure Document Intelligence para JavaScript com npm:

npm install @azure/ai-form-recognizer

Introdução

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

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

Criar um recurso do Reconhecimento de Formulários

Observação: no momento da gravação, o portal do Azure ainda se refere ao recurso como um recurso "Reconhecimento de Formulários". No futuro, isso poderá ser atualizado para um recurso de "Inteligência de Documentos". Por enquanto, a documentação a seguir usa o nome "Reconhecimento de Formulários".

O Document Intelligence dá suporte ao acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se você planeja acessar vários serviços cognitivos em um só ponto de extremidade/chave. Para acesso somente de Reconhecimento de Formulários, crie um recurso Reconhecimento de Formulários.

Você pode criar o recurso usando

Opção 1:Portal do Azure

Opção 2:CLI do Azure.

Veja abaixo um exemplo de como você pode criar um recurso de Reconhecimento de Formulários usando a 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

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> por seus próprios nomes exclusivos:

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

Criar e autenticar um cliente

Para interagir com o serviço de Inteligência de Documentos, você precisará selecionar um DocumentAnalysisClient ou um DocumentModelAdministrationCliente criar uma instância desse tipo. Nos exemplos a seguir, usaremos DocumentAnalysisClient. Para criar uma instância de cliente para acessar a API do Document Intelligence, você precisará do endpoint recurso Reconhecimento de Formulários e de um credential. Os clientes podem usar um AzureKeyCredential com uma chave de API do recurso ou um TokenCredential que usa o RBAC do Azure Active Directory para autorizar o cliente.

Você pode encontrar o ponto de extremidade do recurso Reconhecimento de Formulários no Portal do Azure ou usando o snippet da CLI do Azure abaixo:

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

Usar uma chave de API

Use o Portal do Azure para navegar até o recurso Reconhecimento de Formulários e recuperar uma chave de API ou usar o snippet da CLI do Azure abaixo:

Nota: Às vezes, a chave de API é chamada de "chave de assinatura" ou "chave de API de assinatura".

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

Depois de ter uma chave de API e um ponto de extremidade, você poderá usá-la da seguinte maneira:

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

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

Use o Azure Active Directory Domain Services

A autorização de chave de API é usada na maioria dos exemplos, mas você também pode autenticar o cliente com o Azure Active Directory usando a biblioteca de Identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Para autenticar usando uma entidade de serviço, você também precisará registrar um aplicativo do AAD e conceder acesso ao serviço atribuindo a "Cognitive Services User" função à entidade de serviço (observação: outras funções, como, por "Owner" exemplo, não concederão as permissões necessárias, bastará "Cognitive Services User" executar os exemplos e o código de exemplo).

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

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

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

Principais conceitos

DocumentAnalysisClient

DocumentAnalysisClient fornece operações para analisar documentos de entrada usando modelos personalizados e predefinidos. Ele tem três métodos:

  • beginAnalyzeDocument, que extrai dados de um fluxo de arquivos de documento de entrada usando um modelo personalizado ou predefinido fornecido por sua ID de modelo. Para obter informações sobre os modelos predefinidos com suporte em todos os recursos e suas IDs/saídas de modelo, consulte a documentação do serviço dos modelos.
  • beginAnalyzeDocumentFromUrl, que executa a mesma função beginAnalyzeDocumentque , mas envia uma URL acessível publicamente de um arquivo em vez de um fluxo de arquivos.

DocumentModelAdministrationClient

DocumentModelAdministrationClient fornece operações para gerenciar (criar, ler, listar e excluir) modelos no recurso:

  • beginBuildDocumentModel inicia uma operação para criar um novo modelo de documento do seu próprio conjunto de dados de treinamento. O modelo criado pode extrair campos de acordo com um esquema personalizado. Espera-se que os dados de treinamento estejam localizados em um contêiner do Armazenamento do Azure e organizados de acordo com uma convenção específica. Consulte a documentação do serviço sobre como criar um conjunto de dados de treinamento para obter uma explicação mais detalhada da aplicação de rótulos a um conjunto de dados de treinamento.
  • beginComposeDocumentModel inicia uma operação para compor vários modelos em um único modelo. Quando usado para reconhecimento de formulário personalizado, o novo modelo composto primeiro executará uma classificação dos documentos de entrada para determinar qual de seus submodels é mais apropriado.
  • beginCopyModelTo inicia uma operação para copiar um modelo personalizado de um recurso para outro (ou até mesmo para o mesmo recurso). Ele requer um CopyAuthorization do recurso de destino, que pode ser gerado usando o getCopyAuthorization método .
  • getResourceDetails recupera informações sobre os limites do recurso, como o número de modelos personalizados e o número máximo de modelos aos quais o recurso pode dar suporte.
  • getDocumentModel, listDocumentModelse deleteDocumentModel habilitam o gerenciamento de modelos no recurso.
  • getOperatione listOperations habilitam a exibição do status de operações de criação de modelo, mesmo aquelas operações em andamento ou que falharam. As operações são mantidas por 24 horas.

Observe que os modelos também podem ser criados usando a interface gráfica do usuário do serviço Document Intelligence: Document Intelligence Studio.

Snippets de código de exemplo que ilustram o uso de DocumentModelAdministrationClient para criar um modelo podem ser encontrados abaixo, na seção de exemplo "Criar um Modelo".

Operações de execução longa

LROs (operações de execução prolongada) são operações que consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguidas por sondagem de um resultado em um determinado intervalo para determinar se a operação foi concluída e se ela falhou ou teve êxito. Por fim, o LRO falhará com um erro ou produzirá um resultado.

No Azure AI Document Intelligence, as operações que criam modelos (incluindo copiar e redigir modelos), bem como as operações de análise/extração de dados são LROs. Os clientes do SDK fornecem métodos assíncronos begin<operation-name> que retornam Promise<PollerLike> objetos. O PollerLike objeto representa a operação , que é executada de forma assíncrona na infraestrutura do serviço, e um programa pode aguardar a conclusão da operação chamando e aguardando o pollUntilDone método no poller retornado do begin<operation-name> método . Snippets de código de exemplo são fornecidos para ilustrar o uso de operações de execução prolongada na próxima seção.

Exemplos

A seção a seguir fornece vários snippets de código JavaScript ilustrando padrões comuns usados nas bibliotecas de clientes do Document Intelligence.

Analisar um documento com uma ID de modelo

O beginAnalyzeDocument método pode extrair campos e dados de tabela de documentos. A análise pode usar um modelo personalizado, treinado com seus próprios dados ou um modelo predefinido fornecido pelo serviço (consulte Usar modelos predefinidos abaixo). Um modelo personalizado é personalizado para seus próprios documentos, portanto, ele só deve ser usado com documentos da mesma estrutura que um dos tipos de documento no modelo (pode haver vários, como em um modelo composto).

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

Analisar um documento de uma URL

Como alternativa para fornecer um fluxo legível, uma URL acessível publicamente pode ser fornecida usando o beginAnalyzeDocumentFromUrl método . "Publicamente acessível" significa que as fontes de URL devem estar acessíveis da infraestrutura do serviço (em outras palavras, uma URL de intranet privada ou URLs que usam segredos baseados em cabeçalho ou certificado, não funcionarão, pois o serviço de Inteligência de Documento deve ser capaz de acessar a URL). No entanto, a URL em si poderia codificar um segredo, como uma URL de blob do Armazenamento do Azure que contém um token SAS nos parâmetros de consulta.

Usar modelos de documento predefinidos

O beginAnalyzeDocument método também dá suporte à extração de campos de determinados tipos de documentos comuns, como recibos, faturas, cartões de visita, documentos de identidade e muito mais usando modelos predefinidos fornecidos pelo serviço document intelligence. Os modelos predefinidos podem ser fornecidos como cadeias de caracteres de ID de modelo (o mesmo que modelos de documento personalizados– consulte a seção outros modelos predefinidos abaixo) ou usando um DocumentModel objeto . Ao usar um DocumentModel, o SDK do Document Intelligence para JavaScript fornece um tipo TypeScript muito mais forte para os documentos extraídos resultantes com base no esquema do modelo e ele será convertido para usar convenções de nomenclatura javaScript.

Objetos de exemplo DocumentModel para a versão atual da API de serviço (2022-08-31) podem ser encontrados no prebuilt diretório de exemplos. No exemplo a seguir, usaremos o PrebuiltReceiptModel do arquivo [prebuilt-receipt.ts] nesse diretório.

Como o main benefício da DocumentModelanálise baseada é restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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, conforme mencionado acima, em vez de usar PrebuiltReceiptModel, que produz o tipo de retorno mais forte, a ID do modelo do recibo predefinido ("recibo predefinido") pode ser usada, mas os campos do documento não serão fortemente tipados em TypeScript e os nomes de campo geralmente estarão em "PascalCase" em vez de "camelCase".

Outros modelos predefinidos

Você não está limitado a recibos! Há alguns modelos predefinidos para escolher, com mais no caminho. Cada modelo predefinido tem seu próprio conjunto de campos com suporte:

  • Recibos, usando PrebuiltReceiptModel (conforme acima) ou a ID do modelo de recibo predefinido "prebuilt-receipt".
  • Cartões de visita, usando PrebuiltBusinessCardModel ou sua ID "prebuilt-businessCard"de modelo.
  • Faturas, usando PrebuiltInvoiceModel ou sua ID "prebuilt-invoice"de modelo.
  • Documentos de identidade (como carteiras de motorista e passaportes), usando PrebuiltIdDocumentModel ou sua ID "prebuilt-idDocument"de modelo.
  • W2 Tax Forms (Estados Unidos), usando PrebuiltTaxUsW2Model ou sua ID "prebuilt-tax.us.w2"de modelo .
  • Cartões de Seguro de Saúde (Estados Unidos), usando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] ou sua ID "prebuilt-healthInsuranceCard.us"de modelo .

Cada um dos modelos documents predefinidos acima produz (instâncias extraídas do esquema de campo do modelo). Há também três modelos predefinidos que não têm esquemas de campo e, portanto, não produzem documents. Eles são:

  • O modelo de Layout predefinido (consulte Usar o "layout" predefinido abaixo), que extrai informações sobre elementos de layout básico (OCR), como páginas e tabelas.
  • O modelo de Documento Geral predefinido (consulte Usar o "documento" predefinido abaixo), que adiciona pares chave-valor (associações direcionadas entre elementos de página, como elementos rotulados) às informações produzidas pelo modelo de layout.
  • O modelo de leitura predefinido (consulte Usar a "leitura" predefinida abaixo), que extrai apenas elementos textuais, como palavras e linhas de página, juntamente com informações sobre o idioma do documento.

Para obter informações sobre os campos de todos esses modelos, consulte a documentação do serviço dos modelos predefinidos disponíveis.

Os campos de todos os modelos predefinidos também podem ser acessados programaticamente usando o getDocumentModel método (por suas IDs de modelo) de DocumentModelAdministrationClient e inspecionando o docTypes campo no resultado.

Usar o "layout" predefinido

O "prebuilt-layout" modelo extrai apenas os elementos básicos do documento, como páginas, (que consistem em palavras/linhas de texto e marcas de seleção), tabelas e estilos de texto visual junto com suas regiões delimitador e intervalos dentro do conteúdo de texto dos documentos de entrada. Fornecemos uma instância fortemente tipada DocumentModel chamada PrebuiltLayoutModel que invoca esse modelo ou, como sempre, sua ID "prebuilt-layout" de modelo pode ser usada diretamente.

Como o main benefício da DocumentModelanálise baseada é restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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 o "documento" predefinido

O "prebuilt-document" modelo extrai informações sobre pares chave-valor (associações direcionadas entre elementos de página, como campos rotulados) além das propriedades produzidas pelo método de extração de layout. Esse modelo de documento predefinido (geral) fornece funcionalidade semelhante aos modelos personalizados treinados sem informações de rótulo em iterações anteriores do serviço de Inteligência de Documentos, mas agora é fornecido como um modelo predefinido que funciona com uma ampla variedade de documentos. Fornecemos uma instância fortemente tipada DocumentModel chamada PrebuiltDocumentModel que invoca esse modelo ou, como sempre, sua ID "prebuilt-document" de modelo pode ser usada diretamente.

Como o main benefício da DocumentModelanálise baseada é restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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 a "leitura" predefinida

O "prebuilt-read" modelo extrai informações textuais em um documento, como palavras e parágrafos, e analisa o idioma e o estilo de escrita (por exemplo, manuscrito vs. typeset) desse texto. Fornecemos uma instância fortemente tipada DocumentModel chamada PrebuiltReadModel que invoca esse modelo ou, como sempre, sua ID "prebuilt-read" de modelo pode ser usada diretamente.

Como o main benefício da DocumentModelanálise baseada é restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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);
});

Classificar um documento

O serviço Document Intelligence dá suporte a classificadores de documentos personalizados que podem classificar documentos em um conjunto de categorias predefinidas com base em um conjunto de dados de treinamento. Os documentos podem ser classificados com um classificador personalizado usando o beginClassifyDocument método de DocumentAnalysisClient. Como beginAnalyzeDocument acima, esse método aceita um arquivo ou fluxo que contém o documento a ser classificado e tem um beginClassifyDocumentFromUrl equivalente que aceita uma URL publicamente acessível para um documento.

O exemplo a seguir mostra como classificar um documento usando um classificador 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 obter informações sobre como treinar um classificador personalizado, consulte a seção sobre o treinamento do classificador no final da próxima seção.

Criar um modelo

O SDK também dá suporte à criação de modelos usando a DocumentModelAdministrationClient classe . A criação de um modelo com base em dados de treinamento rotulados cria um novo modelo treinado em seus próprios documentos e o modelo resultante poderá reconhecer valores das estruturas desses documentos. A operação de criação de modelo aceita uma URL codificada em SAS para um contêiner de Blob de Armazenamento do Azure que contém os documentos de treinamento. A infraestrutura do serviço de Inteligência de Documentos lerá os arquivos no contêiner e criará um modelo com base em seu conteúdo. Para obter mais detalhes sobre como criar e estruturar um contêiner de dados de treinamento, consulte a documentação do serviço de Inteligência de Documentos para criar um modelo.

Embora forneçamos esses métodos para a criação de modelo programático, a equipe do serviço de Inteligência de Documentos criou um aplicativo Web interativo, o Document Intelligence Studio, que permite a criação e o gerenciamento de modelos na Web.

Por exemplo, o programa a seguir cria um modelo de documento personalizado usando uma URL codificada em SAS para um contêiner de Armazenamento do Azure pré-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);
});

Os classificadores personalizados são criados de maneira semelhante usando o beginBuildDocumentClassifier método em vez de beginBuildDocumentModel. Consulte o exemplo do classificador de build para obter mais informações sobre como criar um classificador personalizado, pois os dados de treinamento de entrada são fornecidos em um formato ligeiramente diferente. Para obter informações sobre como criar um conjunto de dados de treinamento para um classificador personalizado, consulte a documentação do serviço de Inteligência de Documentos.

Gerenciar modelos

DocumentModelAdministrationClient também fornece vários métodos para acessar e listar modelos. O exemplo a seguir mostra como iterar por meio dos modelos em um recurso (isso incluirá modelos personalizados no recurso, bem como modelos predefinidos que são comuns a todos os recursos), obter um modelo por ID e excluir um 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);
});

Métodos semelhantes listDocumentClassifiers e getDocumentClassifier estão disponíveis para listagem e obtenção de informações sobre classificadores personalizados, além de deleteDocumentClassifier para excluir classificadores personalizados.

Solução de problemas

Para obter assistência com a solução de problemas, consulte o guia de solução de problemas.

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Examine o diretório de exemplos para obter exemplos de código detalhados que mostram como usar essa biblioteca, incluindo vários recursos e métodos que não são mostrados na seção "Exemplos" acima, como copiar e redigir modelos, listar operações de gerenciamento de modelos e excluir modelos.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões