Compartilhar via


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

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

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.