Biblioteca de cliente do Azure AI Document Intelligence para JavaScript - versão 5.0.0

O Azure AI Document Intelligence é um serviço de nuvem que usa aprendizado de máquina para analisar texto e dados estruturados de seus documentos. Inclui as seguintes características principais:

• Layout - Extraia texto, estruturas de tabela e marcas de seleção, juntamente com suas coordenadas de região delimitadora, de documentos.
• Documento - Analise entidades, pares chave-valor, tabelas e marcas de seleção de documentos usando o modelo geral de documento pré-construído.
• Ler - Leia informações sobre elementos textuais, como palavras e linhas da página, além de informações sobre o idioma do texto.
• Pré-construído - Analise dados de certos tipos de documentos comuns (como recibos, faturas, cartões de visita ou documentos de identidade) usando modelos pré-construídos.
• Personalizado - Crie modelos personalizados para extrair texto, valores de campo, marcas de seleção e dados de tabela de documentos. Os modelos personalizados são criados com os seus próprios dados, para que sejam adaptados aos seus documentos.
• Classificadores - Crie classificadores personalizados para categorizar documentos em classes predefinidas.

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

Observação

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

Instalar o pacote @azure/ai-form-recognizer

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

npm install @azure/ai-form-recognizer

Primeiros passos

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 atualmente suportados

• versões LTS do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

• Uma assinatura do Azure
• Um recurso Serviços Cognitivos ou Reconhecedor de Formulários. Se precisar criar o recurso, você pode usar o do Portal do Azure ou da CLI do Azure.

Criar um recurso do Reconhecimento de Formulário

Observação: No momento da escrita, o portal do Azure ainda se refere ao recurso como um recurso "Reconhecimento de formulário". No futuro, isso pode ser atualizado para um recurso de "Document Intelligence". Por enquanto, a documentação a seguir usa o nome "Form Recognizer".

O Document Intelligence suporta acesso multisserviço e de serviço único. Crie um recurso de Serviços Cognitivos se você planeja acessar vários serviços cognitivos em um único ponto de extremidade/chave. Somente para acesso ao Reconhecimento de Formulário, crie um recurso de Reconhecimento de Formulário.

Você pode criar o recurso usando

Opção 1:Portal do Azure

Opção 2:CLI do Azure.

Abaixo está um exemplo de como você pode criar um recurso de reconhecimento de formulário 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 Document Intelligence, 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 de Document Intelligence, você precisará do endpoint do recurso Form Recognizer e de um credential. Os clientes podem usar um AzureKeyCredential com uma chave de API do seu recurso ou um TokenCredential que usa o RBAC do Azure Ative Directory para autorizar o cliente.

Você pode encontrar o ponto de extremidade para seu recurso de Reconhecimento de Formulário no do Portal do Azure ou usando o trecho de 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 do Portal do Azure para navegar até seu recurso do Reconhecimento de Formulário e recuperar uma chave de API ou use o trecho de da CLI do Azure abaixo:

Nota: Às vezes, a chave da API é chamada de "chave de assinatura" ou "chave da 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ê pode usá-lo da seguinte maneira:

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

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

Usar o Azure Ative Directory

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

npm install @azure/identity

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

Defina os valores do ID do cliente, ID do locatário e 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());

Conceitos-chave

DocumentAnalysisClient

DocumentAnalysisClient fornece operações para analisar documentos de entrada usando modelos personalizados e pré-construídos. Tem três métodos:

• beginAnalyzeDocument, que extrai dados de um fluxo de arquivo de documento de entrada usando um modelo personalizado ou pré-construído fornecido por sua ID de modelo. Para obter informações sobre os modelos pré-construídos suportados em todos os recursos e seus IDs/saídas de modelo, consulte a documentação do serviço dos modelos.
• beginAnalyzeDocumentFromUrl, que executa a mesma função que beginAnalyzeDocument, 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 a partir 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 de Armazenamento do Azure e organizados de acordo com uma convenção específica. Consulte a documentação do serviço sobre a criação de 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 submodelos é mais apropriado.
• beginCopyModelTo inicia uma operação para copiar um modelo personalizado de um recurso para outro (ou até mesmo para o mesmo recurso). Requer um CopyAuthorization do recurso de destino, que pode ser gerado usando o método getCopyAuthorization.
• getResourceDetails recupera informações sobre os limites do recurso, como o número de modelos personalizados e o número máximo de modelos que o recurso pode suportar.
• getDocumentModel, listDocumentModelse deleteDocumentModel permitem o gerenciamento de modelos no recurso.
• getOperation e listOperations permitem visualizar o status das operações de criação de modelo, mesmo aquelas operações que estão 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.

Trechos 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 longa duração

Operações de longa duração (LROs) são operações que consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguida de sondagem para obter um resultado em um determinado intervalo para determinar se a operação foi concluída e se falhou ou teve êxito. Em última análise, o LRO falhará com um erro ou produzirá um resultado.

No Azure AI Document Intelligence, as operações que criam modelos (incluindo copiar e compor modelos), bem como as operações de análise/extração de dados são LROs. Os clientes SDK fornecem métodos begin<operation-name> assíncronos que retornam Promise<PollerLike> objetos. O objeto PollerLike 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 método pollUntilDone no poller retornado do método begin<operation-name>. Trechos de código de exemplo são fornecidos para ilustrar o uso de operações de longa execução na próxima seção.

Exemplos

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

• Analisar um documento com um ID de modelo
• Use modelos de documentos pré-construídos
• Use o "layout" pré-construído
• Use o pré-construído "documento"
• Use o pré-construído "ler"
• Crie um modelo
• Gerenciar modelos

Analisar um documento com um ID de modelo

O método beginAnalyzeDocument 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 pré-construído fornecido pelo serviço (consulte Usar modelos pré-construídos abaixo). Um modelo personalizado é adaptado aos seus próprios documentos, por isso 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 a partir de um URL

Como alternativa ao fornecimento de um fluxo legível, um URL acessível ao público pode ser fornecido usando o método beginAnalyzeDocumentFromUrl. "Acessível ao público" significa que as fontes de URL devem ser acessíveis a partir 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 Documentos deve ser capaz de acessar a URL). No entanto, a própria URL pode codificar um segredo, como uma URL de blob de Armazenamento do Azure que contém um token SAS nos parâmetros de consulta.

Usar modelos de documentos pré-construídos

O método beginAnalyzeDocument também suporta a extração de campos de certos tipos de documentos comuns, como recibos, faturas, cartões de visita, documentos de identidade e muito mais, usando modelos pré-construídos fornecidos pelo serviço de Inteligência de Documentos. Os modelos pré-construídos podem ser fornecidos como cadeias de caracteres de ID de modelo (o mesmo que modelos de documentos personalizados — consulte a seção outros modelos pré-construídos abaixo) ou usando um objeto DocumentModel. Ao usar um DocumentModel, o SDK de Inteligência Documental para JavaScript fornece um tipo TypeScript muito mais forte para os documentos extraídos resultantes com base no esquema do modelo e será convertido para usar convenções de nomenclatura JavaScript.

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

Como o principal benefício da análise baseada em DocumentModelsão 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, como mencionado acima, em vez de usar PrebuiltReceiptModel, que produz o tipo de retorno mais forte, o ID do modelo do recibo pré-construído ("recibo pré-construído") pode ser usado, mas os campos do documento não serão fortemente digitados em TypeScript, e os nomes dos campos geralmente estarão em "PascalCase" em vez de "camelCase".

Outros modelos pré-construídos

Você não está limitado a recibos! Existem alguns modelos pré-construídos para escolher, com mais a caminho. Cada modelo pré-construído tem seu próprio conjunto de campos suportados:

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

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

• O modelo de layout pré-construído (consulte Use o "layout" pré-construído abaixo), que extrai informações sobre elementos básicos de layout (OCR), como páginas e tabelas.
• O modelo de documento geral pré-construído (consulte Use o "documento" pré-construído 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 pré-construído (consulte Use o pré-construído "ler" 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 pré-construídos disponíveis.

Os campos de todos os modelos pré-construídos também podem ser acessados programaticamente usando o método getDocumentModel (por seus IDs de modelo) de DocumentModelAdministrationClient e inspecionando o campo docTypes no resultado.

Use o "layout" pré-construído

O modelo "prebuilt-layout" 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, juntamente com suas regiões delimitadoras e extensões dentro do conteúdo de texto dos documentos de entrada. Fornecemos uma instância de DocumentModel fortemente tipada chamada PrebuiltLayoutModel que invoca esse modelo ou, como sempre, sua ID de modelo "prebuilt-layout" pode ser usada diretamente.

Como o principal benefício da análise baseada em DocumentModelsão 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);
});

Use o "documento" pré-construído

O modelo "prebuilt-document" 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 pré-construído (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 pré-construído que funciona com uma ampla variedade de documentos. Fornecemos uma instância de DocumentModel fortemente tipada chamada PrebuiltDocumentModel que invoca esse modelo ou, como sempre, sua ID de modelo "prebuilt-document" pode ser usada diretamente.

Como o principal benefício da análise baseada em DocumentModelsão 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);
});

Use a "leitura" pré-construída

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

Como o principal benefício da análise baseada em DocumentModelsão 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 suporta 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 método beginClassifyDocument de DocumentAnalysisClient. Como beginAnalyzeDocument acima, esse método aceita um arquivo ou fluxo que contém o documento a ser classificado e tem uma contraparte beginClassifyDocumentFromUrl que aceita uma URL acessível publicamente 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 treinamento de classificadores no final da próxima seção.

Criar um modelo

O SDK também suporta a criação de modelos usando a classe DocumentModelAdministrationClient. A criação de um modelo a partir de dados de treinamento rotulados cria um novo modelo que é treinado em seus próprios documentos, e o modelo resultante será capaz de 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 Documental 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 Document Intelligence para criar um modelo.

Enquanto fornecemos esses métodos para a criação de modelos programáticos, a equipe do serviço Document Intelligence criou um aplicativo Web interativo, Document Intelligence Studio, que permite criar e gerenciar 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);
});

classificadores personalizados são construídos de maneira semelhante usando o método beginBuildDocumentClassifier em vez de beginBuildDocumentModel. Consulte o de exemplo de classificador de compilação 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 Document Intelligence.

Gerenciar modelos

DocumentModelAdministrationClient também fornece vários métodos para acessar e listar modelos. O exemplo a seguir mostra como iterar através dos modelos em um recurso (isso incluirá modelos personalizados no recurso, bem como modelos pré-construídos 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 listar e obter informações sobre classificadores personalizados, além de deleteDocumentClassifier para excluir classificadores personalizados.

Solução de problemas

Para obter ajuda com a solução de problemas, consulte o guia de solução de problemas .

Registo

Habilitar o registro em 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 registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Próximos passos

Dê uma olhada no exemplos diretório 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 compor modelos, listar operações de gerenciamento de modelo e excluir modelos.

Contribuição

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