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

  • Artigo

O Azure AI Document Intelligence é um serviço cloud que utiliza machine learning para analisar texto e dados estruturados a partir dos seus documentos. Inclui as seguintes principais funcionalidades:

  • Esquema – extraia texto, estruturas de tabelas e marcas de seleção, juntamente com as respetivas coordenadas de região delimitadora, a partir de documentos.
  • Documento – analisar entidades, pares chave-valor, tabelas e marcas de seleção de documentos com o modelo de documento pré-criado geral.
  • Leitura – leia informações sobre elementos textuais, como palavras de página e linhas, além de informações de idioma de texto.
  • Pré-criado – analise dados de determinados tipos de documentos comuns (como recibos, faturas, cartões de visita ou documentos de identidade) com modelos pré-criados.
  • 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, pelo que 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 | produtoExemplos

Nota

O serviço document Intelligence era anteriormente conhecido como "Azure Reconhecedor de Formulários". Estes 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 escrita, o nome da Reconhecedor de Formulários do Azure para o Azure AI Document Intelligence está em curso, pelo que "Reconhecedor de Formulários" e "Document Intelligence" podem ser utilizados 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

Introdução

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

const fs = require("fs");

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

// Document Intelligence supports many different types of files.
const file = fs.createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

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

Ambientes atualmente suportados

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

Pré-requisitos

Criar um recurso Reconhecedor de Formulários

Nota: no momento da escrita, o portal do Azure ainda se refere ao recurso como um recurso "Reconhecedor de Formulários". No futuro, isto poderá ser atualizado para um recurso "Document Intelligence". Por agora, a seguinte documentação utiliza o nome "Reconhecedor de Formulários".

O Document Intelligence suporta o acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se planear aceder a múltiplos serviços cognitivos num único ponto final/chave. Para Reconhecedor de Formulários acesso apenas, crie um recurso Reconhecedor de Formulários.

Pode criar o recurso com

Opção 1:Portal do Azure

Opção 2:CLI do Azure.

Segue-se um exemplo de como pode criar um recurso Reconhecedor de Formulários com 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 utilizar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> pelos 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, terá de selecionar um DocumentAnalysisClient ou um DocumentModelAdministrationCliente criar uma instância deste tipo. Nos exemplos seguintes, vamos utilizar DocumentAnalysisClient. Para criar uma instância de cliente para aceder à API do Document Intelligence, precisará do endpoint recurso do Reconhecedor de Formulários e de um credential. Os clientes podem utilizar uma AzureKeyCredential chave de API do recurso ou uma TokenCredential que utilize o RBAC do Azure Active Directory para autorizar o cliente.

Pode encontrar o ponto final do recurso Reconhecedor de Formulários no Portal do Azure ou através do fragmento da CLI do Azure abaixo:

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

Utilizar uma chave de API

Utilize o Portal do Azure para navegar para o recurso Reconhecedor de Formulários e obter uma chave de API ou utilize o fragmento da CLI do Azure abaixo:

Nota: Por vezes, a chave de API é referida como uma "chave de subscrição" ou "chave de API de subscrição".

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

Assim que tiver uma chave de API e um ponto final, pode utilizá-la da seguinte forma:

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

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

Utilizar o Azure Active Directory

A autorização da chave de API é utilizada na maioria dos exemplos, mas também pode autenticar o cliente com o Azure Active Directory com a biblioteca de Identidade do Azure. Para utilizar o fornecedor DefaultAzureCredential apresentado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Para autenticar através de um principal de serviço, também terá de registar uma aplicação do AAD e conceder acesso ao serviço ao atribuir a "Cognitive Services User" função ao principal de serviço (nota: 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, do ID do inquilino e do segredo do cliente da aplicação do 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 com modelos personalizados e pré-criados. Tem três métodos:

  • beginAnalyzeDocument, que extrai dados de um fluxo de ficheiros de documento de entrada com um modelo personalizado ou pré-criado fornecido pelo respetivo ID de modelo. Para obter informações sobre os modelos pré-criados suportados em todos os recursos e os respetivos IDs/saídas de modelos, consulte a documentação do serviço sobre os modelos.
  • beginAnalyzeDocumentFromUrl, que executa a mesma função que beginAnalyzeDocument, mas submete um URL acessível publicamente de um ficheiro em vez de um fluxo de ficheiros.

DocumentModelAdministrationClient

DocumentModelAdministrationClient fornece operações para gerir (criar, ler, listar e eliminar) 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 preparação. O modelo criado pode extrair campos de acordo com um esquema personalizado. Espera-se que os dados de preparação estejam localizados num contentor do Armazenamento do Azure e organizados de acordo com uma convenção específica. Veja a documentação do serviço sobre como criar um conjunto de dados de preparação para obter uma explicação mais detalhada sobre a aplicação de etiquetas a um conjunto de dados de preparação.
  • beginComposeDocumentModel inicia uma operação para compor vários modelos num único modelo. Quando utilizado para o reconhecimento de formulários personalizado, o novo modelo composto executará primeiro uma classificação dos documentos de entrada para determinar qual dos respetivos submodelos é mais adequado.
  • beginCopyModelTo inicia uma operação para copiar um modelo personalizado de um recurso para outro (ou mesmo para o mesmo recurso). Requer um CopyAuthorization recurso de destino, que pode ser gerado com o getCopyAuthorization método .
  • getResourceDetails obtém 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 ative a gestão de modelos no recurso.
  • getOperation e listOperations ative a visualização do estado das operações de criação de modelos, mesmo as operações em curso ou que falharam. As operações são mantidas durante 24 horas.

Tenha em atenção que os modelos também podem ser criados com a interface gráfica do serviço Document Intelligence: Document Intelligence Studio.

Os fragmentos de código de exemplo que ilustram a utilização de DocumentModelAdministrationClient para criar um modelo podem ser encontrados abaixo, na secção de exemplo "Criar um Modelo".

Operações de execução prolongada

As operações de execução prolongada (LROs) são operações que consistem num pedido inicial enviado ao serviço para iniciar uma operação, seguidas de consulta de um resultado num 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 do SDK fornecem métodos assíncronos begin<operation-name> que devolvem 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 que a operação seja concluída ao chamar e aguardar o pollUntilDone método no poller devolvido do begin<operation-name> método. São fornecidos fragmentos de código de exemplo para ilustrar a utilização de operações de execução prolongada na secção seguinte.

Exemplos

A secção seguinte fornece vários fragmentos de código JavaScript que ilustram padrões comuns utilizados nas bibliotecas de cliente do Document Intelligence.

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 utilizar um modelo personalizado, preparado com os seus próprios dados ou um modelo pré-criado fornecido pelo serviço (consulte Utilizar Modelos Pré-criados abaixo). Um modelo personalizado é adaptado aos seus próprios documentos, pelo que só deve ser utilizado com documentos da mesma estrutura que um dos tipos de documento no modelo (pode haver múltiplos, como num 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, pode ser fornecido um URL acessível publicamente através do beginAnalyzeDocumentFromUrl método . "Acessível publicamente" significa que as origens de URL têm de estar acessíveis a partir da infraestrutura do serviço (por outras palavras, um URL de intranet privada ou URLs que utilizem segredos baseados em cabeçalhos ou certificados, não funcionarão, uma vez que o serviço document Intelligence tem de conseguir aceder ao URL). No entanto, o URL em si pode codificar um segredo, como um URL de blob do Armazenamento do Azure que contém um token SAS nos parâmetros de consulta.

Utilizar modelos de documentos pré-criados

O beginAnalyzeDocument método também suporta a extração de campos de determinados tipos de documentos comuns, tais como recibos, faturas, cartões de visita, documentos de identidade e muito mais através de modelos pré-criados fornecidos pelo serviço Document Intelligence. Os modelos pré-criados podem ser fornecidos como cadeias de ID de modelo (as mesmas que os modelos de documentos personalizados— veja a secção outros modelos pré-criados abaixo) ou utilizando um DocumentModel objeto. Ao utilizar 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 será convertido para utilizar convenções de nomenclatura JavaScript.

Os DocumentModel objetos de exemplo para a versão atual da API de serviço (2022-08-31) podem ser encontrados no prebuilt diretório de exemplos. No exemplo seguinte, vamos utilizar o PrebuiltReceiptModel do ficheiro [prebuilt-receipt.ts] nesse diretório.

Uma vez que o principal benefício da DocumentModelanálise baseada em restrições de tipo TypeScript é mais forte, o exemplo seguinte é escrito em TypeScript com 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);
});

Em alternativa, como mencionado acima, em vez de utilizar PrebuiltReceiptModelo , que produz o tipo de retorno mais forte, o ID de modelo do recibo pré-criado ("pré-recibo") pode ser utilizado, mas os campos do documento não serão fortemente escritos em TypeScript e os nomes de campo estarão geralmente em "PascalCase" em vez de "camelCase".

Outros modelos pré-criados

Não está limitado a recibos! Existem alguns modelos pré-criados à escolha, com mais informações a caminho. Cada modelo pré-criado tem o seu próprio conjunto de campos suportados:

  • Recibos, com PrebuiltReceiptModel (como acima) ou o ID "prebuilt-receipt"do modelo de recibo pré-criado .
  • Cartões de visita, utilizando PrebuiltBusinessCardModel ou o respetivo ID de "prebuilt-businessCard"modelo .
  • Faturas, utilizando PrebuiltInvoiceModel ou o respetivo ID de "prebuilt-invoice"modelo .
  • Documentos de Identidade (como cartas de condução e passaportes), com PrebuiltIdDocumentModel ou o respetivo ID de "prebuilt-idDocument"modelo .
  • Formulários Fiscais W2 (Estados Unidos), utilizando PrebuiltTaxUsW2Model ou o respetivo ID de "prebuilt-tax.us.w2"modelo .
  • Cartões de Seguro de Saúde (Estados Unidos), com [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] ou o respetivo ID de "prebuilt-healthInsuranceCard.us"modelo .

Cada um dos modelos pré-criados acima produz documents (instâncias extraídas do esquema de campo do modelo). Existem também três modelos pré-criados que não têm esquemas de campo e, por conseguinte, não produzem documents. A saber:

  • O modelo de Esquema pré-criado (veja Utilizar o "esquema" pré-criado abaixo), que extrai informações sobre elementos de esquema básico (OCR), como páginas e tabelas.
  • O modelo de Documento Geral pré-criado (veja Utilizar o "documento" pré-criado abaixo), que adiciona pares chave-valor (associações direcionadas entre elementos de página, como elementos etiquetados) às informações produzidas pelo modelo de esquema.
  • O modelo de Leitura pré-criado (veja Utilizar o pré-criado "ler" abaixo), que extrai apenas elementos textuais, como palavras de página e linhas, juntamente com informações sobre o idioma do documento.

Para obter informações sobre os campos de todos estes modelos, veja a documentação do serviço sobre os modelos pré-criados disponíveis.

Os campos de todos os modelos pré-criados também podem ser acedidos programaticamente com o getDocumentModel método (pelos respetivos IDs de modelo) de DocumentModelAdministrationClient e inspecionar o docTypes campo no resultado.

Utilizar o "esquema" pré-criado

O "prebuilt-layout" modelo extrai apenas os elementos básicos do documento, tais como páginas, (que consistem em palavras/linhas de texto e marcas de seleção), tabelas e estilos de texto visual, juntamente com as regiões delimitadoras e abrange o conteúdo de texto dos documentos de entrada. Fornecemos uma instância fortemente escrita DocumentModel com o nome PrebuiltLayoutModel que invoca este modelo ou, como sempre, o respetivo ID "prebuilt-layout" de modelo pode ser utilizado diretamente.

Uma vez que o principal benefício da DocumentModelanálise baseada em restrições de tipo TypeScript é mais forte, o exemplo seguinte é escrito em TypeScript com 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);
});

Utilizar o "documento" pré-criado

O "prebuilt-document" modelo extrai informações sobre pares chave-valor (associações direcionadas entre elementos de página, como campos etiquetados), além das propriedades produzidas pelo método de extração de esquemas. Este modelo de documento pré-criado (geral) fornece funcionalidades semelhantes aos modelos personalizados preparados sem informações de etiqueta em iterações anteriores do serviço Document Intelligence, mas agora é fornecido como um modelo pré-criado que funciona com uma grande variedade de documentos. Fornecemos uma instância fortemente escrita DocumentModel com o nome PrebuiltDocumentModel que invoca este modelo ou, como sempre, o respetivo ID "prebuilt-document" de modelo pode ser utilizado diretamente.

Uma vez que o principal benefício da DocumentModelanálise baseada em restrições de tipo TypeScript é mais forte, o exemplo seguinte é escrito em TypeScript com 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);
});

Utilizar o pré-criado "ler"

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

Uma vez que o principal benefício da DocumentModelanálise baseada em restrições de tipo TypeScript é mais forte, o exemplo seguinte é escrito em TypeScript com 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 num conjunto de categorias predefinidas com base num conjunto de dados de preparação. Os documentos podem ser classificados com um classificador personalizado com o beginClassifyDocument método de DocumentAnalysisClient. Tal como beginAnalyzeDocument acima, este método aceita um ficheiro ou fluxo que contém o documento para ser classificado e tem uma beginClassifyDocumentFromUrl contrapartida que aceita um URL acessível publicamente a um documento.

O exemplo seguinte mostra como classificar um documento com 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 a preparação de um classificador personalizado, consulte a secção sobre a preparação do classificador no final da secção seguinte.

Criar um modelo

O SDK também suporta a criação de modelos com a DocumentModelAdministrationClient classe. Criar um modelo a partir de dados de preparação etiquetados cria um novo modelo preparado nos seus próprios documentos e o modelo resultante poderá reconhecer valores das estruturas desses documentos. A operação de criação de modelos aceita um URL codificado por SAS para um contentor de Blobs de Armazenamento do Azure que contém os documentos de preparação. A infraestrutura do serviço Document Intelligence irá ler os ficheiros no contentor e criar um modelo com base nos respetivos conteúdos. Para obter mais detalhes sobre como criar e estruturar um contentor de dados de preparação, veja a documentação do serviço Document Intelligence para criar um modelo.

Embora forneçamos estes métodos para a criação de modelos programáticos, a equipa do serviço Document Intelligence criou uma aplicação Web interativa, o Document Intelligence Studio, que permite criar e gerir modelos na Web.

Por exemplo, o programa seguinte cria um modelo de documento personalizado com um URL codificado por SAS para um contentor de Armazenamento do Azure pré-existente:

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

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const containerSasUrl = "<SAS url to the blob container storing training documents>";

  const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));

  // You must provide the model ID. It can be any text that does not start with "prebuilt-".
  // For example, you could provide a randomly generated GUID using the "uuid" package.
  // The second parameter is the SAS-encoded URL to an Azure Storage container with the training documents.
  // The third parameter is the build mode: one of "template" (the only mode prior to 4.0.0-beta.3) or "neural".
  // See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes.
  const poller = await client.beginBuildDocumentModel("<model ID>", containerSasUrl, "template", {
    // The model description is optional and can be any text.
    description: "This is my new model!",
    onProgress: ({ status }) => {
      console.log(`operation status: ${status}`);
    },
  });
  const model = await poller.pollUntilDone();

  console.log("Model ID:", model.modelId);
  console.log("Description:", model.description);
  console.log("Created:", model.createdOn);

  // A model may contain several document types, which describe the possible object structures of fields extracted using
  // this model

  console.log("Document Types:");
  for (const [docType, { description, fieldSchema: schema }] of Object.entries(
    model.docTypes ?? {}
  )) {
    console.log(`- Name: "${docType}"`);
    console.log(`  Description: "${description}"`);

    // For simplicity, this example will only show top-level field names
    console.log("  Fields:");

    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
      console.log(`  - "${fieldName}" (${fieldSchema.type})`);
      console.log(`    ${fieldSchema.description ?? "<no description>"}`);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Os classificadores personalizados são criados de forma semelhante com o beginBuildDocumentClassifier método em vez de beginBuildDocumentModel. Veja o exemplo do classificador de compilação para obter mais informações sobre a criação de um classificador personalizado, uma vez que os dados de preparação de entrada são fornecidos num formato ligeiramente diferente. Para obter informações sobre a criação de um conjunto de dados de preparação para um classificador personalizado, veja a documentação do serviço Document Intelligence.

Gerir modelos

DocumentModelAdministrationClient também fornece vários métodos para aceder e listar modelos. O exemplo seguinte mostra como iterar através dos modelos num recurso (isto incluirá modelos personalizados no recurso, bem como modelos pré-criados que são comuns a todos os recursos), obter um modelo por ID e eliminar 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 deleteDocumentClassifier de para eliminar classificadores personalizados.

Resolução de problemas

Para obter ajuda com a resolução de problemas, veja o guia de resolução de problemas.

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar registos, pode ver os documentos do pacote de @azure/logger.

Passos seguintes

Veja o diretório de exemplos para obter exemplos de código detalhados que mostram como utilizar esta biblioteca, incluindo várias funcionalidades e métodos que não são apresentados na secção "Exemplos" acima, como copiar e compor modelos, listar operações de gestão de modelos e eliminar modelos.

Contribuir

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

Impressões