Biblioteca de clientes REST do Azure DocumentIntelligence (antigo FormRecognizer) para JavaScript – versão 1.0.0-beta.2

Artigo
03/22/2024

Extrai conteúdo, layout e dados estruturados de documentos.

Confie fortemente em nossos documentos de cliente REST para usar esta biblioteca

OBSERVAÇÃO: Reconhecimento de Formulários foi renomeado para Inteligência de Documentos. Marcar o Guia de Migração de @azure/ai-form-recognizer para @azure-rest/ai-document-intelligence.

Links principais:

Essa versão da biblioteca de clientes usa como padrão a "2024-02-29-preview" versão do serviço.

Esta tabela mostra a relação entre as versões do SDK e as versões de API com suporte do serviço:

Versão do SDK	Versão da API do serviço com suporte
1.0.0-beta.2	2024-02-29-preview
1.0.0-beta.1	2023-10-31-preview

Conte com a biblioteca mais antiga @azure/ai-form-recognizer por meio das versões mais antigas da API de serviço para modelos desativados, como "prebuilt-businessCard" e "prebuilt-document". Para obter mais informações, consulte Changelog.

A tabela abaixo descreve a relação de cada cliente e suas versões de API com suporte:

Versão da API de Serviço	Clientes com suporte	Pacote
2024-02-29-preview	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` versão `1.0.0-beta.2`
2023-10-31-preview	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` versão `1.0.0-beta.1`
2023-07-31	DocumentAnalysisClient e DocumentModelAdministrationClient	`@azure/ai-form-recognizer` versão `^5.0.0`
2022-08-01	DocumentAnalysisClient e DocumentModelAdministrationClient	`@azure/ai-form-recognizer` versão `^4.0.0`

Introdução

Ambientes com suporte no momento

Versões LTS do Node.js

Pré-requisitos

Você deve ter uma assinatura do Azure para usar esse pacote.

Instalar o pacote `@azure-rest/ai-document-intelligence`

Instale a biblioteca de clientes REST do cliente REST do Azure DocumentIntelligence(antigoFormRecognizer) para JavaScript com npm:

npm install @azure-rest/ai-document-intelligence

Criar e autenticar um `DocumentIntelligenceClient`

Para usar uma credencial de token do AAD (Azure Active Directory), forneça uma instância do tipo de credencial desejado obtido da biblioteca de @azure/identidade .

Para autenticar com o AAD, você deve primeiro npm instalar @azure/identity

Após a instalação, você pode escolher de qual tipo de credencial@azure/identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente.

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

Usando uma credencial de token

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential()
);

Usando uma CHAVE DE API

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

Modelos de documento

Analisar layout predefinido (urlSource)

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { locale: "en-IN" },
  });

Analisar layout predefinido (base64Source)

import fs from "fs";
import path from "path";

const filePath = path.join(ASSET_PATH, "forms", "Invoice_1.pdf");
const base64Source = fs.readFileSync(filePath, { encoding: "base64" });
const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { locale: "en-IN" },
  });

Continuar criando o sondador a partir da resposta inicial

import {
  getLongRunningPoller,
  AnalyzeResultOperationOutput,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = await getLongRunningPoller(client, initialResponse);
const result = (await poller.pollUntilDone()).body as AnalyzeResultOperationOutput;
console.log(result);
// {
//   status: 'succeeded',
//   createdDateTime: '2023-11-10T13:31:31Z',
//   lastUpdatedDateTime: '2023-11-10T13:31:34Z',
//   analyzeResult: {
//     apiVersion: '2023-10-31-preview',
//     .
//     .
//     .
//     contentFormat: 'text'
//   }
// }

Formato de conteúdo de Markdown

Dá suporte à saída com o formato de conteúdo markdown junto com o texto sem formatação padrão. Por enquanto, isso só tem suporte para "layout predefinido". O formato de conteúdo markdown é considerado um formato mais amigável para consumo de LLM em um cenário de uso de chat ou automação.

O serviço segue a especificação GFM (GitHub Flavored Markdown) para o formato Markdown. Também apresenta uma nova propriedade contentFormat com o valor "text" ou "markdown" para indicar o formato de conteúdo do resultado.

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { outputContentFormat: "markdown" }, // <-- new query parameter
  });

Campos de consulta

Quando esse sinalizador de recurso for especificado, o serviço extrairá ainda mais os valores dos campos especificados por meio do parâmetro de consulta queryFields para complementar todos os campos existentes definidos pelo modelo como fallback.

await client.path("/documentModels/{modelId}:analyze", "prebuilt-layout").post({
  contentType: "application/json",
  body: { urlSource: "..." },
  queryParameters: {
    features: ["queryFields"],
    queryFields: ["NumberOfGuests", "StoreNumber"],
  }, // <-- new query parameter
});

Opções de divisão

Nas versões anteriores da API compatíveis com a biblioteca mais antiga @azure/ai-form-recognizer , a operação de divisão e classificação de documentos ("/documentClassifiers/{classifierId}:analyze") sempre tentou dividir o arquivo de entrada em vários documentos.

Para habilitar um conjunto mais amplo de cenários, o serviço apresenta um parâmetro de consulta "divisão" com a nova versão de serviço "2023-10-31-preview". Os seguintes valores têm suporte:

split: "auto"

Deixe o serviço determinar onde dividir.
split: "none"

Todo o arquivo é tratado como um único documento. Nenhuma divisão é executada.
split: "perPage"

Cada página é tratada como um documento separado. Cada página vazia é mantida como seu próprio documento.

Classificadores de documento #Build

import {
  DocumentClassifierBuildOperationDetailsOutput,
  getLongRunningPoller,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

const containerSasUrl = (): string =>
  process.env["DOCUMENT_INTELLIGENCE_TRAINING_CONTAINER_SAS_URL"];
const initialResponse = await client.path("/documentClassifiers:build").post({
  body: {
    classifierId: `customClassifier${getRandomNumber()}`,
    description: "Custom classifier description",
    docTypes: {
      foo: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
      bar: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
    },
  },
});

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = await getLongRunningPoller(client, initialResponse);
const response = (await poller.pollUntilDone())
  .body as DocumentClassifierBuildOperationDetailsOutput;
console.log(response);
//  {
//    operationId: '31466834048_f3ee629e-73fb-48ab-993b-1d55d73ca460',
//    kind: 'documentClassifierBuild',
//    status: 'succeeded',
//    .
//    .
//    result: {
//      classifierId: 'customClassifier10978',
//      createdDateTime: '2023-11-09T12:45:56Z',
//      .
//      .
//      description: 'Custom classifier description'
//    },
//    apiVersion: '2023-10-31-preview'
//  }

Obter informações

const response = await client.path("/info").get();
if (isUnexpected(response)) {
  throw response.body.error;
}
console.log(response.body.customDocumentModels.limit);
// 20000

Listar modelos de documento

import { paginate } from "@azure-rest/ai-document-intelligence";
const response = await client.path("/documentModels").get();
if (isUnexpected(response)) {
  throw response.body.error;
}

const modelsInAccount: string[] = [];
for await (const model of paginate(client, response)) {
  console.log(model.modelId);
}

Solução de problemas

Registro em log

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

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

setLogLevel("info");

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

Biblioteca de clientes REST do Azure DocumentIntelligence (antigo FormRecognizer) para JavaScript – versão 1.0.0-beta.2

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote `@azure-rest/ai-document-intelligence`

Criar e autenticar um `DocumentIntelligenceClient`

Usando uma credencial de token

Usando uma CHAVE DE API

Modelos de documento

Analisar layout predefinido (urlSource)

Analisar layout predefinido (base64Source)

Formato de conteúdo de Markdown

Campos de consulta

Opções de divisão

Classificadores de documento #Build

Obter informações

Listar modelos de documento

Solução de problemas

Registro em log

Comentários

Recursos adicionais

Biblioteca de clientes REST do Azure DocumentIntelligence (antigo FormRecognizer) para JavaScript – versão 1.0.0-beta.2

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote @azure-rest/ai-document-intelligence

Criar e autenticar um DocumentIntelligenceClient

Usando uma credencial de token

Usando uma CHAVE DE API

Modelos de documento

Analisar layout predefinido (urlSource)

Analisar layout predefinido (base64Source)

Formato de conteúdo de Markdown

Campos de consulta

Opções de divisão

Classificadores de documento #Build

Obter informações

Listar modelos de documento

Solução de problemas

Registro em log

Comentários

Recursos adicionais

Instalar o pacote `@azure-rest/ai-document-intelligence`

Criar e autenticar um `DocumentIntelligenceClient`