Biblioteca de cliente 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. 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 @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 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

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

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

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

Pré-requisitos

• Uma assinatura do Azure
• Um recurso de 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 redação, 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 acesso 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 de Inteligência de Documentos, você precisará selecionar um DocumentAnalysisClient ou um DocumentModelAdministrationClient, e 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á endpoint do recurso Form Recognizer e de um credentialarquivo . 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 Portal do Azure ou usando o trecho 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é seu recurso de Reconhecimento de Formulário e recuperar uma chave de API ou use o trecho 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:

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 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 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 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, apenas "Cognitive Services User" serão suficientes 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.

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 o Azure China ou o Azure Government) especificando a audience opção ao criar seu cliente. Use o KnownFormRecognizerAudience enum 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-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 beginAnalyzeDocumento , mas envia um URL acessível ao público 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 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 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 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 que o recurso pode suportar.
• getDocumentModel, listDocumentModelse habilite deleteDocumentModel o gerenciamento de modelos no recurso.
• getOperation e listOperations permitir a visualização do status das operações de criação de modelo, mesmo as 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 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 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
• Usar modelos de documentos pré-construídos
• Use o "layout" pré-construído
• Use o "documento" pré-construído
• Use a "leitura" pré-construída
• Criar um modelo
• Gerenciar modelos

Analisar um documento com um 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 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).

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 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 beginAnalyzeDocumentFromUrl método. "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 beginAnalyzeDocument método 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 de outros modelos pré-construídos abaixo) ou usando um DocumentModel objeto. 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 ele será convertido para usar convenções de nomenclatura JavaScript.

Exemplos DocumentModel de objetos 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 arquivo from the [prebuilt-receipt.ts] nesse diretório.

Como o principal benefício da análise baseada em -based são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do DocumentModelmó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, 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 "prebuilt-receipt"do modelo de recibo pré-construído.
• 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 cartas de condução e passaportes), utilizando PrebuiltIdDocumentModel ou o seu modelo de identificação "prebuilt-idDocument".
• W2 Tax Forms (Estados Unidos), usando PrebuiltTaxUsW2Model ou seu 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 "prebuilt-healthInsuranceCard.us"de modelo .

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 Usar 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 Usar 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 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 pré-construídos disponíveis.

Os campos de todos os modelos pré-construídos também podem ser acessados programaticamente usando o getDocumentModel método (por seus 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 análise baseada em -based são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do DocumentModelmó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 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 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 análise baseada em -based são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do DocumentModelmó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 a "leitura" pré-construída

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 datilografado) 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 análise baseada em -based são restrições de tipo TypeScript mais fortes, o exemplo a seguir é escrito em TypeScript usando a sintaxe do DocumentModelmó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 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 beginClassifyDocument método de DocumentAnalysisClient. Como beginAnalyzeDocument acima, esse método aceita um arquivo ou fluxo contendo 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 classificadores no final da próxima seção.

Criar um modelo

O SDK também suporta a 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 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, 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 construídos de maneira semelhante usando o beginBuildDocumentClassifier método em vez de beginBuildDocumentModel. Consulte o 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.

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.

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 AZURE_LOG_LEVEL variável de ambiente como info. Como alternativa, o registro em log pode ser habilitado em tempo de execução chamando setLogLevel o @azure/logger:

import { setLogLevel } from "@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 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 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.