Biblioteca de clientes do Azure AI Document Intelligence para JavaScript – versão 5.1.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. Ele inclui os seguintes recursos 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 de chave-valor, tabelas e marcas de seleção de documentos usando o modelo de documento predefinido geral.
• Ler - Leia informações sobre elementos textuais, como palavras e linhas da página, além de informações de idioma do 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. Os modelos personalizados são criados com seus próprios dados, portanto, são adaptados aos seus documentos.
• Classificadores - Crie classificadores personalizados para categorizar documentos em classes predefinidas.

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

Observação

O serviço de Inteligência de Documentos era conhecido anteriormente como "Reconhecimento de Formulários do Azure". 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 Azure AI Document Intelligence. No momento da redação deste artigo, a renomeação do Reconhecimento de Formulários do Azure para Azure AI Document Intelligence está em andamento, portanto, "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

Como começar

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

Ambientes com suporte no momento

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

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

• Uma assinatura do Azure
• Um recurso dos Serviços Cognitivos ou do Reconhecimento de Formulários. Se você precisar criar o recurso, poderá usar o portal do Azure ou da CLI do Azure.

Criar um recurso do Reconhecimento de Formulários

Observação: no momento da redação deste artigo, o portal do Azure ainda se refere ao recurso como um recurso de "Reconhecimento de Formulários". No futuro, isso pode ser atualizado para um recurso "Document Intelligence". Por enquanto, a documentação a seguir usa o nome "Reconhecimento de Formulários".

O Document Intelligence oferece 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 único ponto de extremidade/chave. Para acesso exclusivo ao Form Recognizer, crie um recurso de Form Recognizer.

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á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 a 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 seu 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 use o snippet da CLI do Azure abaixo:

Observação: às vezes, a chave de API é conhecida como uma "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 endpoint, você pode usá-los da seguinte maneira:

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

Usar o Azure Active Directory

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 identidades 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 à sua entidade de serviço (observação: outras funções, como "Owner" não concederão as permissões necessárias, serão suficientes apenas "Cognitive Services User" para 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.

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

Nuvens Soberanas

Conecte-se a ambientes de nuvem alternativos do Azure (como Azure China ou Azure Government) especificando a audience opção ao criar seu cliente. Use a KnownFormRecognizerAudience enumeração para selecionar o valor correto para seu ambiente.

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

Se você não especificar a audience opção, o padrão será adequado para a Nuvem Pública do Azure (https://cognitiveservices.azure.com).

Conceitos principais

DocumentAnalysisClient

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

• beginAnalyzeDocument, que extrai dados de um fluxo de arquivo 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 o , 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 de 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 como criar um conjunto de dados de treinamento para obter uma explicação mais detalhada sobre a 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). Ele requer um CopyAuthorization 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 habilite o gerenciamento de modelos no recurso.
• getOperation e listOperations habilitar a exibição do status das operações de criação de modelo, mesmo aquelas que estão em andamento ou que falharam. As operações são retidas 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 pela sondagem de um resultado em um determinado intervalo para determinar se a operação foi concluída e se falhou ou foi bem-sucedida. 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 modelos de cópia e composição), 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. Trechos de código de exemplo são fornecidos para ilustrar o uso de operações de execução longa na próxima seção.

Exemplos

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

• Analisar um documento com uma ID de modelo
• Usar modelos de documentos predefinidos
• Use o "layout" pré-construído
• Use o "documento" pré-construído
• Use o pre-construído "read"
• Criar um modelo
• Gerenciar modelos

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 é adaptado aos 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).

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

Analisar um documento de uma URL

Como alternativa ao fornecimento de um fluxo legível, uma URL acessível publicamente pode ser fornecida usando o beginAnalyzeDocumentFromUrl método. "Acessível publicamente" 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 do Armazenamento do Azure que contém um token SAS nos parâmetros de consulta.

Usar modelos de documentos predefinidos

O beginAnalyzeDocument método também oferece 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 de Inteligência de Documentos. 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 samples. No exemplo a seguir, usaremos o PrebuiltReceiptModel arquivo from [prebuilt-receipt.ts] nesse diretório.

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

Como alternativa, como mencionado acima, em vez de usar PrebuiltReceiptModel, que produz o tipo de retorno mais forte, a ID do modelo do recibo pré-criado ("recibo pré-construído") pode ser usada, 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 predefinido tem seu próprio conjunto de campos suportados:

• Recibos, usando PrebuiltReceiptModel (como acima) ou a ID "prebuilt-receipt"do modelo de recibo predefinido.
• Cartões de visita, usando PrebuiltBusinessCardModel ou seu ID "prebuilt-businessCard"de modelo .
• Faturas, usando PrebuiltInvoiceModel ou seu ID "prebuilt-invoice"de modelo .
• 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 sua ID "prebuilt-tax.us.w2"de modelo .
• Cartões de seguro de saúde (Estados Unidos), usando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] ou seu ID de modelo "prebuilt-healthInsuranceCard.us".

Cada um dos modelos predefinidos acima produz documents (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" pré-criado abaixo), que extrai informações sobre elementos básicos de layout (OCR), como páginas e tabelas.
• O modelo de documento geral predefinido (consulte Usar o "documento" pré-criado abaixo), que adiciona pares de 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" pré-construída abaixo), que extrai apenas elementos textuais, como palavras e linhas da 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 pré-criados também podem ser acessados programaticamente usando o getDocumentModel método (por suas IDs de modelo) e DocumentModelAdministrationClient inspecionando o docTypes campo no resultado.

Use o "layout" pré-construído

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, juntamente com suas regiões delimitadoras e extensões 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 principal benefício da DocumentModelanálise baseada em são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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}"`);
  }
}

Use o "documento" pré-construído

O "prebuilt-document" modelo extrai informações sobre pares de valores-chave (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 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 principal benefício da DocumentModelanálise baseada em são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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})`);
  }
}

Use o pre-construído "read"

O "prebuilt-read" modelo 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 tipografia) 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 principal benefício da DocumentModelanálise baseada em são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do 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);
  }
}

Classificar um documento

O serviço de Inteligência de Documentos oferece 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 uma beginClassifyDocumentFromUrl contraparte que aceita uma URL acessível publicamente para um documento.

O exemplo a seguir mostra como classificar um documento usando um classificador 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 obter informações sobre como treinar um classificador personalizado, consulte a seção sobre treinamento de 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 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 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 Inteligência de Documentos para criar um modelo.

Embora forneçamos esses métodos para a criação de modelos programáticos, a equipe do serviço Document Intelligence criou um aplicativo Web interativo, o 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:

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

Os classificadores personalizados são criados de maneira semelhante usando o método em vez de beginBuildDocumentClassifierbeginBuildDocumentModel. Consulte o exemplo de 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 Document Intelligence.

Gerenciar modelos

DocumentModelAdministrationClient também fornece vários métodos para acessar e listar modelos. O exemplo a seguir mostra como iterar pelos modelos em um recurso (isso incluirá modelos personalizados no recurso, bem como modelos predefinidos comuns a todos os recursos), obter um modelo por ID e excluir um 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 semelhantes e getDocumentClassifier estão disponíveis para listar e obter informações sobre classificadores personalizados, além de deleteDocumentClassifier excluir classificadores personalizados.

Resolução de problemas

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

Registro

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 AZURE_LOG_LEVEL ambiente como info. Como alternativa, o registro em log pode ser habilitado em runtime chamandosetLogLevel:@azure/logger

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

setLogLevel("info");

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

Próximas etapas

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

Contribuindo

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