Bibliothèque cliente Azure AI Document Intelligence pour JavaScript - version 5.0.0

Azure AI Document Intelligence est un service cloud qui utilise le Machine Learning pour analyser le texte et les données structurées de vos documents. Il comprend les fonctionnalités main suivantes :

• Disposition : extrayez du texte, des structures de tableau et des marques de sélection, ainsi que leurs coordonnées de région englobante, à partir de documents.
• Document : analysez les entités, les paires clé-valeur, les tables et les marques de sélection à partir de documents à l’aide du modèle de document prédéfini général.
• Lecture : lit des informations sur les éléments textuels, comme les mots de page et les lignes, en plus des informations sur la langue du texte.
• Prédéfini : analysez les données de certains types de documents courants (tels que des reçus, des factures, des cartes de visite ou des documents d’identité) à l’aide de modèles prédéfinis.
• Personnalisé : créez des modèles personnalisés pour extraire du texte, des valeurs de champ, des marques de sélection et des données de tableau à partir de documents. Les modèles personnalisés sont créés avec vos propres données, de sorte qu’ils sont adaptés à vos documents.
• Classifieurs : créez des classifieurs personnalisés pour classer les documents en classes prédéfinies.

Code source | Package (NPM) | Documentation de référence API | Documentation de produits | Exemples

Notes

Le service Document Intelligence était anciennement appelé « Azure Form Recognizer ». Ces services sont identiques et le @azure/ai-form-recognizer package pour JavaScript est le package sdk Azure pour le service Azure AI Document Intelligence. Au moment de la rédaction du présent article, le changement de nom d’Azure Form Recognizer en Azure AI Document Intelligence étant en cours, « Form Recognizer » et « Document Intelligence » peuvent être utilisés de manière interchangeable dans certains cas.

Installez le package @azure/ai-form-recognizer

Installez la bibliothèque cliente Azure Document Intelligence pour JavaScript avec npm:

npm install @azure/ai-form-recognizer

Prise en main

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

Environnements actuellement pris en charge

• Versions LTS de Node.js
• Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre politique de support .

Prérequis

• Un abonnement Azure
• Ressource Cognitive Services ou Form Recognizer. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure ou Azure CLI.

Créer une ressource Form Recognizer

Remarque : Au moment de la rédaction de cet article, le Portail Azure fait toujours référence à la ressource en tant que ressource « Form Recognizer ». À l’avenir, il peut être mis à jour vers une ressource « Document Intelligence ». Pour l’instant, la documentation suivante utilise le nom « Form Recognizer ».

Document Intelligence prend en charge l’accès multiservices et à service unique. Créez une ressource Cognitive Services si vous envisagez d’accéder à plusieurs services Cognitive Services sous un seul point de terminaison/clé. Pour l’accès à Form Recognizer uniquement, créez une ressource Form Recognizer.

Vous pouvez créer la ressource à l’aide de

Option 1 :Portail Azure

Option 2 :Azure CLI.

Voici un exemple de création d’une ressource Form Recognizer à l’aide de l’interface 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

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-resource-name> par vos propres noms uniques :

az cognitiveservices account create --kind FormRecognizer --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

Créer et authentifier un client

Pour interagir avec le service Document Intelligence, vous devez sélectionner un ou un DocumentAnalysisClient et créer une DocumentModelAdministrationClientinstance de ce type. Dans les exemples suivants, nous allons utiliser DocumentAnalysisClient. Pour créer un client instance d’accéder à l’API Document Intelligence, vous aurez besoin de la endpoint ressource de votre Form Recognizer et d’un credential. Les clients peuvent utiliser un AzureKeyCredential avec une clé API de votre ressource ou un TokenCredential RBAC Azure Active Directory pour autoriser le client.

Vous trouverez le point de terminaison de votre ressource Form Recognizer dans le portail Azure ou à l’aide de l’extrait de code Azure CLI ci-dessous :

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

Utiliser une clé API

Utilisez le portail Azure pour accéder à votre ressource Form Recognizer et récupérer une clé API, ou utilisez l’extrait de code Azure CLI ci-dessous :

Note: Parfois, la clé API est appelée « clé d’abonnement » ou « clé API d’abonnement ».

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

Une fois que vous avez une clé API et un point de terminaison, vous pouvez les utiliser comme suit :

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

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

Utiliser Azure Active Directory

L’autorisation de clé API est utilisée dans la plupart des exemples, mais vous pouvez également authentifier le client auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le @azure/identity package :

npm install @azure/identity

Pour vous authentifier à l’aide d’un principal de service, vous devez également inscrire une application AAD et accorder l’accès au service en attribuant le "Cognitive Services User" rôle à votre principal de service (remarque : d’autres rôles tels que n’accorderont "Owner" pas les autorisations nécessaires, suffiront "Cognitive Services User" uniquement pour exécuter les exemples et l’exemple de code).

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.

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

const client = new DocumentAnalysisClient("<endpoint>", new DefaultAzureCredential());

Concepts clés

DocumentAnalysisClient

DocumentAnalysisClient fournit des opérations d’analyse de documents d’entrée à l’aide de modèles personnalisés et prédéfinis. Il comporte trois méthodes :

• beginAnalyzeDocument, qui extrait les données d’un flux de fichier de document d’entrée à l’aide d’un modèle personnalisé ou prédéfini donné par son ID de modèle. Pour plus d’informations sur les modèles prédéfinis pris en charge dans toutes les ressources et leurs ID/sorties de modèle, consultez la documentation du service sur les modèles.
• beginAnalyzeDocumentFromUrl, qui exécute la même fonction que beginAnalyzeDocument, mais envoie une URL accessible publiquement d’un fichier au lieu d’un flux de fichiers.

DocumentModelAdministrationClient

DocumentModelAdministrationClient fournit des opérations de gestion (création, lecture, référencement et suppression) de modèles dans la ressource :

• beginBuildDocumentModel démarre une opération pour créer un modèle de document à partir de votre propre jeu de données d’entraînement. Le modèle créé peut extraire des champs en fonction d’un schéma personnalisé. Les données d’entraînement doivent être situées dans un conteneur stockage Azure et organisées selon une convention particulière. Consultez la documentation du service sur la création d’un jeu de données d’entraînement pour obtenir une explication plus détaillée de l’application d’étiquettes à un jeu de données d’entraînement.
• beginComposeDocumentModel démarre une opération pour composer plusieurs modèles en un seul modèle. Lorsqu’il est utilisé pour la reconnaissance de formulaire personnalisé, le nouveau modèle composé effectue d’abord une classification des documents d’entrée pour déterminer lequel de ses sous-modèles est le plus approprié.
• beginCopyModelTo démarre une opération pour copier un modèle personnalisé d’une ressource vers une autre (ou même vers la même ressource). Il nécessite un CopyAuthorization à partir de la ressource cible, qui peut être généré à l’aide de la getCopyAuthorization méthode .
• getResourceDetails récupère des informations sur les limites de la ressource, telles que le nombre de modèles personnalisés et le nombre maximal de modèles que la ressource peut prendre en charge.
• getDocumentModel, listDocumentModelset deleteDocumentModel activez la gestion des modèles dans la ressource.
• getOperationet listOperations permettent d’afficher les status des opérations de création de modèle, même celles qui sont en cours ou qui ont échoué. Les opérations sont conservées pendant 24 heures.

Notez que les modèles peuvent également être créés à l’aide de l’interface utilisateur graphique du service Document Intelligence : Document Intelligence Studio.

Vous trouverez ci-dessous des exemples d’extraits de code illustrant l’utilisation de DocumentModelAdministrationClient pour générer un modèle, dans la section exemple « Générer un modèle ».

Opérations de longue durée

Les opérations de longue durée (LRO) sont des opérations qui se composent d’une demande initiale envoyée au service pour démarrer une opération, suivie d’une interrogation pour obtenir un résultat à un certain intervalle pour déterminer si l’opération s’est terminée et si elle a échoué ou réussi. En fin de compte, le LRO échoue avec une erreur ou produit un résultat.

Dans Azure AI Document Intelligence, les opérations qui créent des modèles (y compris la copie et la composition de modèles) ainsi que les opérations d’analyse/extraction de données sont des LRO. Les clients du KIT de développement logiciel (SDK) fournissent des méthodes asynchrones begin<operation-name> qui retournent Promise<PollerLike> des objets. L’objet PollerLike représente l’opération, qui s’exécute de manière asynchrone sur l’infrastructure du service, et un programme peut attendre que l’opération se termine en appelant et en attendant la pollUntilDone méthode sur l’polleur retourné par la begin<operation-name> méthode. Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’opérations de longue durée dans la section suivante.

Exemples

La section suivante fournit plusieurs extraits de code JavaScript illustrant les modèles courants utilisés dans les bibliothèques clientes Document Intelligence.

• Analyser un document avec un ID de modèle
• Utiliser des modèles de document prédéfinis
• Utiliser le prédéfini « layout »
• Utiliser le « document » prédéfini
• Utiliser le prédéfini « read »
• Générer un modèle
• Gérer les modèles

Analyser un document avec un ID de modèle

La beginAnalyzeDocument méthode peut extraire des champs et des données de table à partir de documents. L’analyse peut utiliser un modèle personnalisé, entraîné avec vos propres données, ou un modèle prédéfini fourni par le service (voir Utiliser des modèles prédéfinis ci-dessous). Un modèle personnalisé étant adapté à vos propres documents, il ne doit être utilisé qu’avec des documents de la même structure que l’un des types de documents dans le modèle (il peut y en avoir plusieurs, par exemple dans un modèle composé).

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

Analyser un document à partir d’une URL

En guise d’alternative à la fourniture d’un flux lisible, une URL accessible au public peut être fournie à l’aide de la beginAnalyzeDocumentFromUrl méthode . « Accessible publiquement » signifie que les sources d’URL doivent être accessibles à partir de l’infrastructure du service (en d’autres termes, une URL intranet privée, ou des URL qui utilisent des secrets basés sur un en-tête ou un certificat, ne fonctionnent pas, car le service Document Intelligence doit être en mesure d’accéder à l’URL). Toutefois, l’URL elle-même peut encoder un secret, tel qu’une URL d’objet blob stockage Azure qui contient un jeton SAP dans les paramètres de requête.

Utiliser des modèles de document prédéfinis

La beginAnalyzeDocument méthode prend également en charge l’extraction de champs de certains types de documents courants tels que les reçus, les factures, les cartes de visite, les documents d’identité, etc. à l’aide de modèles prédéfinis fournis par le service Document Intelligence. Les modèles prédéfinis peuvent être fournis sous forme de chaînes d’ID de modèle (identiques aux modèles de document personnalisés ( voir la section des autres modèles prédéfinis ci-dessous) ou à l’aide d’un DocumentModel objet. Lors de l’utilisation d’un DocumentModel, le Kit de développement logiciel (SDK) Document Intelligence pour JavaScript fournit un type TypeScript beaucoup plus fort pour les documents extraits résultants en fonction du schéma du modèle, et il sera converti pour utiliser des conventions de nommage JavaScript.

Vous trouverez des exemples DocumentModel d’objets pour la version actuelle de l’API de service (2022-08-31) dans le prebuilt répertoire des exemples. Dans l’exemple suivant, nous allons utiliser le PrebuiltReceiptModel à partir du fichier [prebuilt-receipt.ts] dans ce répertoire.

Étant donné que l’main’avantage de l’analyse basée sur les contraintes de type TypeScript plus fortes, l’exemple suivant est écrit en TypeScript à l’aide de DocumentModella syntaxe du module 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);
});

Comme mentionné ci-dessus, au lieu d’utiliser PrebuiltReceiptModel, qui produit le type de retour le plus fort, l’ID de modèle du reçu prédéfini (« prédéfini-receipt ») peut être utilisé, mais les champs de document ne seront pas fortement tapés dans TypeScript, et les noms de champs seront généralement en « PascalCase » au lieu de « camelCase ».

Autres modèles prédéfinis

Vous n’êtes pas limité aux reçus ! Il existe quelques modèles prédéfinis parmi lesquels choisir, avec d’autres modèles en cours. Chaque modèle prédéfini a son propre ensemble de champs pris en charge :

• Reçus, en utilisant PrebuiltReceiptModel (comme ci-dessus) ou l’ID "prebuilt-receipt"de modèle de reçu prédéfini .
• Cartes de visite, à l’aide PrebuiltBusinessCardModel de ou de son ID de "prebuilt-businessCard"modèle .
• Factures, à l’aide PrebuiltInvoiceModel de ou de son ID de "prebuilt-invoice"modèle .
• Documents d’identité (tels que les permis de conduire et les passeports), à l’aide PrebuiltIdDocumentModel de ou de son ID de "prebuilt-idDocument"modèle .
• Formulaires fiscaux W2 (États-Unis), à l’aide de PrebuiltTaxUsW2Model ou de son ID de "prebuilt-tax.us.w2"modèle .
• Cartes d’assurance maladie (États-Unis), à l’aide de [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] ou de son ID de "prebuilt-healthInsuranceCard.us"modèle .

Chacun des modèles prédéfinis ci-dessus produit (instances extraites documents du schéma de champ du modèle). Il existe également trois modèles prédéfinis qui n’ont pas de schémas de champ et ne produisent documentsdonc pas . Il s'agit des éléments suivants :

• Modèle de disposition prédéfini (voir Utiliser le prédéfini « layout » ci-dessous), qui extrait des informations sur les éléments de disposition de base (OCR), tels que les pages et les tables.
• Modèle de document général prédéfini (voir Utiliser le « document » prédéfini ci-dessous), qui ajoute des paires clé-valeur (associations dirigées entre des éléments de page, tels que des éléments étiquetés) aux informations produites par le modèle de disposition.
• Modèle de lecture prédéfini (voir Utiliser le prédéfini « read » ci-dessous), qui extrait uniquement les éléments textuels, tels que les mots de page et les lignes, ainsi que des informations sur la langue du document.

Pour plus d’informations sur les champs de tous ces modèles, consultez la documentation du service sur les modèles prédéfinis disponibles.

Les champs de tous les modèles prédéfinis peuvent également être consultés par programmation à l’aide de la getDocumentModel méthode (par leurs ID de modèle) de et en DocumentModelAdministrationClient inspectant le docTypes champ dans le résultat.

Utiliser le prédéfini « layout »

Le "prebuilt-layout" modèle extrait uniquement les éléments de base du document, tels que les pages (qui se composent de mots/lignes de texte et de marques de sélection), les tableaux et les styles de texte visuel, ainsi que leurs régions et étendues englobantes dans le contenu texte des documents d’entrée. Nous fournissons un instance PrebuiltLayoutModel fortement typé DocumentModel nommé qui appelle ce modèle ou, comme toujours, son ID "prebuilt-layout" de modèle peut être utilisé directement.

Étant donné que l’main’avantage de l’analyse basée sur les contraintes de type TypeScript plus fortes, l’exemple suivant est écrit en TypeScript à l’aide de DocumentModella syntaxe du module 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);
});

Utiliser le « document » prédéfini

Le "prebuilt-document" modèle extrait des informations sur les paires clé-valeur (associations dirigées entre les éléments de page, tels que les champs étiquetés) en plus des propriétés produites par la méthode d’extraction de disposition. Ce modèle de document prédéfini (général) fournit des fonctionnalités similaires aux modèles personnalisés entraînés sans informations d’étiquette dans les itérations précédentes du service Document Intelligence, mais il est désormais fourni en tant que modèle prédéfini qui fonctionne avec un large éventail de documents. Nous fournissons un instance PrebuiltDocumentModel fortement typé DocumentModel nommé qui appelle ce modèle ou, comme toujours, son ID "prebuilt-document" de modèle peut être utilisé directement.

Étant donné que l’main’avantage de l’analyse basée sur les contraintes de type TypeScript plus fortes, l’exemple suivant est écrit en TypeScript à l’aide de DocumentModella syntaxe du module 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);
});

Utiliser le prédéfini « read »

Le "prebuilt-read" modèle extrait les informations textuelles d’un document, telles que les mots et les paragraphes, et analyse la langue et le style d’écriture (par exemple, manuscrit ou typeet) de ce texte. Nous fournissons un instance PrebuiltReadModel fortement typé DocumentModel nommé qui appelle ce modèle ou, comme toujours, son ID "prebuilt-read" de modèle peut être utilisé directement.

Étant donné que l’main’avantage de l’analyse basée sur les contraintes de type TypeScript plus fortes, l’exemple suivant est écrit en TypeScript à l’aide de DocumentModella syntaxe du module 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);
});

Classifier un document

Le service Document Intelligence prend en charge les classifieurs de documents personnalisés qui peuvent classer les documents dans un ensemble de catégories prédéfinies en fonction d’un jeu de données d’entraînement. Les documents peuvent être classés avec un classifieur personnalisé à l’aide de la beginClassifyDocument méthode de DocumentAnalysisClient. Comme beginAnalyzeDocument ci-dessus, cette méthode accepte un fichier ou un flux contenant le document à classer, et elle a un beginClassifyDocumentFromUrl équivalent qui accepte une URL accessible publiquement à un document à la place.

L’exemple suivant montre comment classifier un document à l’aide d’un classifieur personnalisé :

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

Pour plus d’informations sur l’apprentissage d’un classifieur personnalisé, consultez la section sur l’apprentissage du classifieur à la fin de la section suivante.

Générer un modèle

Le Kit de développement logiciel (SDK) prend également en charge la création de modèles à l’aide de la DocumentModelAdministrationClient classe . La génération d’un modèle à partir de données d’entraînement étiquetées crée un nouveau modèle qui est entraîné sur vos propres documents, et le modèle résultant sera en mesure de reconnaître les valeurs des structures de ces documents. L’opération de génération de modèles accepte une URL encodée SAS vers un conteneur d’objets blob stockage Azure qui contient les documents d’apprentissage. L’infrastructure du service Document Intelligence lit les fichiers dans le conteneur et crée un modèle en fonction de leur contenu. Pour plus d’informations sur la création et la structure d’un conteneur de données d’apprentissage, consultez la documentation du service Document Intelligence pour la création d’un modèle.

Bien que nous fournissons ces méthodes pour la création de modèles par programmation, l’équipe du service Document Intelligence a créé une application web interactive, Document Intelligence Studio, qui permet de créer et de gérer des modèles sur le web.

Par exemple, le programme suivant génère un modèle de document personnalisé à l’aide d’une URL encodée SAS vers un conteneur stockage Azure préexistant :

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

Les classifieurs personnalisés sont générés de la même manière à l’aide de la beginBuildDocumentClassifier méthode plutôt que de beginBuildDocumentModel. Consultez l’exemple de classifieur de build pour plus d’informations sur la création d’un classifieur personnalisé, car les données d’entraînement d’entrée sont fournies dans un format légèrement différent. Pour plus d’informations sur la création d’un jeu de données d’entraînement pour un classifieur personnalisé, consultez la documentation du service Document Intelligence.

Gérer les modèles

DocumentModelAdministrationClient fournit également plusieurs méthodes pour accéder aux modèles et les répertorier. L’exemple suivant montre comment itérer à travers les modèles d’une ressource (cela inclut à la fois des modèles personnalisés dans la ressource ainsi que des modèles prédéfinis communs à toutes les ressources), obtenir un modèle par ID et supprimer un modèle.

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

Des méthodes listDocumentClassifiers similaires et getDocumentClassifier sont disponibles pour répertorier et obtenir des informations sur les classifieurs personnalisés en plus de la deleteDocumentClassifier suppression des classifieurs personnalisés.

Dépannage

Pour obtenir de l’aide sur la résolution des problèmes, consultez le guide de résolution des problèmes.

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir 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 @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples de code détaillés qui montrent comment utiliser cette bibliothèque, y compris plusieurs fonctionnalités et méthodes qui ne sont pas indiquées dans la section « Exemples » ci-dessus, telles que la copie et la composition de modèles, la liste des opérations de gestion des modèles et la suppression de modèles.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.