Partager via

Bibliothèque de client REST Azure DocumentIntelligence (anciennement FormRecognizer) pour JavaScript - version 1.0.0

  • Article

Extrait le contenu, la disposition et les données structurées à partir de documents.

S’il vous plaît s’appuyer fortement sur nos documents clients REST pour utiliser cette bibliothèque

REMARQUE : Form Recognizer a été renommé Document Intelligence. Consultez le guide de migration de @azure/ai-form-recognizer à @azure-rest/ai-document-intelligence.

Liens clés :

Cette version de la bibliothèque cliente est par défaut la version "2024-11-30" du service.

Ce tableau présente la relation entre les versions du SDK et les versions d’API prises en charge du service :

Version du Kit de développement logiciel (SDK Version d’API prise en charge du service
1.0.0 2024-11-30

S’il vous plaît compter sur l’ancienne bibliothèque de @azure/ai-form-recognizer via les anciennes versions de l’API de service pour les modèles supprimés, tels que "prebuilt-businessCard" et "prebuilt-document". Pour plus d’informations, consultez Changelog .

Le tableau ci-dessous décrit la relation entre chaque client et ses versions d’API prises en charge :

Version de l’API de service Clients pris en charge Colis
2024-11-30 DocumentIntelligenceClient @azure-rest/ai-document-intelligence version 1.0.0
2023-07-31 DocumentAnalysisClient et DocumentModelAdministrationClient @azure/ai-form-recognizer version ^5.0.0
2022-08-01 DocumentAnalysisClient et DocumentModelAdministrationClient @azure/ai-form-recognizer version ^4.0.0

Commencer

Environnements actuellement pris en charge

  • Versions LTS de Node.js

Conditions préalables

  • Vous devez disposer d’un abonnement Azure pour utiliser ce package.

Installer le package @azure-rest/ai-document-intelligence

Installez la bibliothèque de client REST rest Azure DocumentIntelligence(anciennementFormRecognizer) pour JavaScript avec npm:

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

Créer et authentifier un DocumentIntelligenceClient

Pour utiliser un d’informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenu à partir de la bibliothèque @azure/identity.

Pour vous authentifier auprès d’AAD, vous devez d’abord npm installer @azure/identity

Après l’installation, vous pouvez choisir le type d’informations d’identification de @azure/identity à utiliser. Par exemple, DefaultAzureCredential pouvez être utilisé pour authentifier le client.

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Utilisation d’informations d’identification de jeton

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

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

Utilisation d’une CLÉ API

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

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

Modèles de document

Analyser la disposition prédéfinie (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" },
  });

Analyser la disposition prédéfinie (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" },
  });

Continuer à créer l’polleur à partir de la réponse initiale

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

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = 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'
//   }
// }

Analyse par lots

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

// 1. Analyze a batch of documents
const initialResponse = await client
  .path("/documentModels/{modelId}:analyzeBatch", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      azureBlobSource: {
        containerUrl: batchTrainingFilesContainerUrl(),
      },
      resultContainerUrl: batchTrainingFilesResultContainerUrl(),
      resultPrefix: "result",
    },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const resultId = parseResultIdFromResponse(initialResponse);
console.log("resultId: ", resultId);

// (Optional) You can poll for the batch analysis result but be aware that a job may take unexpectedly long time, and polling could incur additional costs.
// const poller = getLongRunningPoller(client, initialResponse);
// await poller.pollUntilDone();

// 2. At a later time, you can retrieve the operation result using the resultId
const output = await client
  .path("/documentModels/{modelId}/analyzeResults/{resultId}", "prebuilt-layout", resultId)
  .get();
console.log(output);

Format de contenu Markdown

Prend en charge la sortie avec le format de contenu Markdown, ainsi que le texte brut par défaut. Pour l’instant, cela n’est pris en charge que pour la « disposition prédéfinie ». Le format de contenu Markdown est considéré comme un format plus convivial pour la consommation LLM dans un scénario d’utilisation de conversation ou d’automatisation.

Le service suit la spécification GFM (GitHub Flavored Markdown) pour le format Markdown. Introduit également une nouvelle propriété contentFormat avec la valeur « text » ou « markdown » pour indiquer le format de contenu du résultat.

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

Champs de requête

Lorsque cet indicateur de fonctionnalité est spécifié, le service extrait davantage les valeurs des champs spécifiés via le paramètre de requête queryFields pour compléter les champs existants définis par le modèle comme secours.

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

Options de fractionnement

Dans les versions d’API précédentes prises en charge par l’ancienne bibliothèque de @azure/ai-form-recognizer, l’opération de fractionnement et de classification des documents ("/documentClassifiers/{classifierId}:analyze") a toujours essayé de fractionner le fichier d’entrée en plusieurs documents.

Pour permettre un ensemble plus large de scénarios, le service introduit un paramètre de requête « fractionné » avec la nouvelle version du service « 2023-10-31-preview ». Les valeurs suivantes sont prises en charge :

  • split: "auto"

    Laissez le service déterminer où fractionner.

  • split: "none"

    Le fichier entier est traité comme un document unique. Aucun fractionnement n’est effectué.

  • split: "perPage"

    Chaque page est traitée comme un document distinct. Chaque page vide est conservée en tant que propre document.

Classifieurs de documents #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 = 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'
//  }

Obtenir la sortie PDF générée à partir de l’analyse de document

const filePath = path.join(ASSET_PATH, "layout-pageobject.pdf");

const base64Source = await fs.readFile(filePath, { encoding: "base64" });

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-read")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { output: ["pdf"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);

await poller.pollUntilDone();

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/pdf",
    "prebuilt-read",
    parseResultIdFromResponse(initialResponse)
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const pdfData = await streamToUint8Array(output.body);
fs.promises.writeFile(`./output.pdf`, pdfData);
// Or you can consume the NodeJS.ReadableStream directly

Obtenir l’image rognée générée de la figure spécifiée à partir de l’analyse de document

const filePath = path.join(ASSET_PATH, "layout-pageobject.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: { output: ["figures"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse, { ...testPollingOptions });

const result = (await poller.pollUntilDone()).body as AnalyzeResultOperationOutput;
const figures = result.analyzeResult?.figures;
assert.isArray(figures);
assert.isNotEmpty(figures?.[0]);
const figureId = figures?.[0].id || "";
assert.isDefined(figureId);

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/figures/{figureId}",
    "prebuilt-layout",
    parseResultIdFromResponse(initialResponse),
    figureId
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const imageData = await streamToUint8Array(output.body);
fs.promises.writeFile(`./figures/${figureId}.png`, imageData);
// Or you can consume the NodeJS.ReadableStream directly

Obtenir des informations

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

Répertorier les modèles de document

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

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.