Libreria client di Azure AI Document Intelligence per JavaScript - versione 5.0.0

Intelligenza artificiale di Azure è un servizio cloud che usa Machine Learning per analizzare il testo e i dati strutturati dai documenti. Include le seguenti funzionalità principali:

• Layout: estrarre testo, strutture di tabella e contrassegni di selezione, insieme alle coordinate dell'area di associazione, dai documenti.
• Documento: analizzare entità, coppie chiave-valore, tabelle e contrassegni di selezione da documenti usando il modello di documento predefinito generale.
• Lettura: leggere informazioni sugli elementi testuali, ad esempio parole di pagina e righe oltre alle informazioni sulla lingua di testo.
• Predefinito: analizzare i dati da determinati tipi di documenti comuni(ad esempio ricevute, fatture, biglietti da visita o documenti di identità) usando modelli predefiniti.
• Personalizzato: creare modelli personalizzati per estrarre testo, valori di campo, contrassegni di selezione e dati di tabella dai documenti. I modelli personalizzati vengono creati con i propri dati, quindi sono personalizzati per i documenti.
• Classificatori: compilare classificatori personalizzati per classificare i documenti in classi predefinite.

Codice | sorgentePacchetto (NPM) | Documentazione di | riferimento sulle APIDocumentazione | del prodottoCampioni

Nota

Il servizio Document Intelligence era in precedenza noto come "Azure Riconoscimento modulo". Questi servizi sono uno e gli stessi e il pacchetto per JavaScript è il pacchetto Azure SDK per il @azure/ai-form-recognizer servizio Azure AI Document Intelligence. Al momento della scrittura, la ridenominazione di Azure Riconoscimento modulo in Azure AI Document Intelligence è in corso, quindi "Riconoscimento modulo" e "Document Intelligence" può essere usata in modo intercambiabile in alcuni casi.

Installare il pacchetto @azure/ai-form-recognizer

Installare la libreria client di Azure Document Intelligence per JavaScript con npm:

npm install @azure/ai-form-recognizer

Introduzione

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

Ambienti attualmente supportati

• Versioni LTS di Node.js
• Ultime versioni di Safari, Chrome, Edge e Firefox.

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

• Una sottoscrizione di Azure
• Risorsa Servizi cognitivi o Riconoscimento modulo. Se è necessario creare la risorsa, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure.

Creare una risorsa di riconoscimento modulo

Nota: al momento della scrittura, il portale di Azure fa ancora riferimento alla risorsa come risorsa "Riconoscimento modulo". In futuro, questo può essere aggiornato a una risorsa "Document Intelligence". Per il momento, la documentazione seguente usa il nome "Riconoscimento modulo".

Document Intelligence supporta sia l'accesso a più servizi che a servizio singolo. Creare una risorsa Servizi cognitivi se si prevede di accedere a più servizi cognitivi con un singolo endpoint/chiave. Per accedere solo a Riconoscimento modulo, creare una risorsa Riconoscimento modulo.

È possibile creare la risorsa usando

Opzione 1:Portale di Azure

Opzione 2:Interfaccia della riga dicomando di Azure.

Di seguito è riportato un esempio di come creare una risorsa Riconoscimento modulo usando l'interfaccia della riga di comando:

# 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 si usa l'interfaccia della riga di comando di Azure, sostituire <your-resource-group-name> e <your-resource-name> con i propri nomi univoci:

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

Creare ed autenticare un client

Per interagire con il servizio Document Intelligence, è necessario selezionare o un DocumentAnalysisClientDocumentModelAdministrationClientoggetto e creare un'istanza di questo tipo. Negli esempi seguenti verrà usato DocumentAnalysisClient. Per creare un'istanza client per accedere all'API Document Intelligence, sarà necessario disporre della endpoint risorsa Riconoscimento modulo e di un credentialoggetto . I client possono usare un oggetto AzureKeyCredential con una chiave API della risorsa o un TokenCredential controllo degli accessi in base al ruolo di Azure Active Directory per autorizzare il client.

È possibile trovare l'endpoint per la risorsa Riconoscimento modulo nel portale di Azure o usando il frammento di interfaccia della riga di comando di Azure seguente:

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

Usare una chiave API

Usare il portale di Azure per passare alla risorsa Riconoscimento modulo e recuperare una chiave API oppure usare il frammento di interfaccia della riga di comando di Azure seguente:

Nota: A volte la chiave API viene definita "chiave di sottoscrizione" o "chiave API di sottoscrizione".

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

Dopo avere una chiave API e un endpoint, è possibile usarlo come segue:

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

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

Usare Azure Active Directory

L'autorizzazione della chiave API viene usata nella maggior parte degli esempi, ma è anche possibile autenticare il client con Azure Active Directory usando la libreria di identità di Azure. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il @azure/identity pacchetto:

npm install @azure/identity

Per eseguire l'autenticazione tramite un'entità servizio, è anche necessario registrare un'applicazione AAD e concedere l'accesso al servizio assegnando il "Cognitive Services User" ruolo all'entità servizio (nota: altri ruoli "Owner" come non concederanno le autorizzazioni necessarie, "Cognitive Services User" sarà sufficiente eseguire solo gli esempi e il codice di esempio).

Impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: AZURE_CLIENT_ID, AZURE_TENANT_IDAZURE_CLIENT_SECRET.

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

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

Concetti chiave

DocumentAnalysisClient

DocumentAnalysisClient fornisce operazioni per l'analisi dei documenti di input usando modelli personalizzati e predefiniti. Ha tre metodi:

• beginAnalyzeDocument, che estrae i dati da un flusso di file di documento di input usando un modello personalizzato o predefinito specificato dall'ID modello. Per informazioni sui modelli predefiniti supportati in tutte le risorse e i relativi ID modello/output, vedere la documentazione del servizio sui modelli.
• beginAnalyzeDocumentFromUrl, che esegue la stessa funzione di beginAnalyzeDocument, ma invia un URL accessibile pubblicamente di un file anziché un flusso di file.

DocumentModelAdministrationClient

DocumentModelAdministrationClient fornisce operazioni per la gestione (creazione, lettura, elenco ed eliminazione) dei modelli nella risorsa:

• beginBuildDocumentModel avvia un'operazione per creare un nuovo modello di documento dal proprio set di dati di training. Il modello creato può estrarre campi in base a uno schema personalizzato. I dati di training devono trovarsi in un contenitore di archiviazione di Azure e organizzati in base a una determinata convenzione. Vedere la documentazione del servizio sulla creazione di un set di dati di training per una spiegazione più dettagliata dell'applicazione delle etichette a un set di dati di training.
• beginComposeDocumentModel avvia un'operazione per comporre più modelli in un singolo modello. Quando viene usato per il riconoscimento personalizzato dei moduli, il nuovo modello composto eseguirà prima una classificazione dei documenti di input per determinare quale dei relativi sottomodelli è più appropriato.
• beginCopyModelTo avvia un'operazione per copiare un modello personalizzato da una risorsa a un'altra (o anche nella stessa risorsa). Richiede un CopyAuthorization oggetto dalla risorsa di destinazione, che può essere generato usando il getCopyAuthorization metodo .
• getResourceDetails recupera informazioni sui limiti della risorsa, ad esempio il numero di modelli personalizzati e il numero massimo di modelli che la risorsa può supportare.
• getDocumentModel, listDocumentModelse deleteDocumentModel abilitare la gestione dei modelli nella risorsa.
• getOperation e listOperations abilitare la visualizzazione dello stato delle operazioni di creazione del modello, anche quelle operazioni in corso o non riuscite. Le operazioni vengono mantenute per 24 ore.

Si noti che è anche possibile creare modelli usando l'interfaccia utente grafica del servizio Document Intelligence: Document Intelligence Studio.

Di seguito sono riportati frammenti di codice di esempio che illustrano l'uso di DocumentModelAdministrationClient per compilare un modello, nella sezione di esempio "Build a Model".

Operazioni a esecuzione prolungata

Le operazioni a esecuzione prolungata (LROs) sono operazioni costituite da una richiesta iniziale inviata al servizio per avviare un'operazione, seguita dal polling di un risultato a un determinato intervallo per determinare se l'operazione è stata completata e se ha avuto esito negativo o riuscito. In definitiva, l'LRO avrà esito negativo con un errore o genera un risultato.

In Azure AI Document Intelligence le operazioni che creano modelli (inclusa la copia e la composizione di modelli) e le operazioni di analisi/estrazione dei dati sono LRO. I client SDK forniscono metodi asincroni begin<operation-name> che restituiscono Promise<PollerLike> oggetti. L'oggetto PollerLike rappresenta l'operazione, che viene eseguita in modo asincrono sull'infrastruttura del servizio e un programma può attendere il completamento dell'operazione chiamando e aspettando il pollUntilDone metodo sul poller restituito dal begin<operation-name> metodo . I frammenti di codice di esempio vengono forniti per illustrare l'uso di operazioni a esecuzione prolungata nella sezione successiva.

Esempio

La sezione seguente fornisce diversi frammenti di codice JavaScript che illustrano modelli comuni usati nelle librerie client di Document Intelligence.

• Analizzare un documento con un ID modello
• Usare modelli di documento predefiniti
• Usare la predefinita "layout"
• Usare la predefinita "document"
• Usare la predefinita "read"
• Creare un modello
• Gestire i modelli

Analizzare un documento con un ID modello

Il beginAnalyzeDocument metodo può estrarre campi e dati di tabella dai documenti. L'analisi può usare un modello personalizzato, sottoposto a training con i propri dati o un modello predefinito fornito dal servizio (vedere Usare modelli predefiniti di seguito). Un modello personalizzato è personalizzato per i propri documenti, quindi deve essere usato solo con documenti della stessa struttura di uno dei tipi di documento nel modello ( ad esempio in un modello 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);
});

Analizzare un documento da un URL

In alternativa a fornire un flusso leggibile, è possibile fornire un URL accessibile pubblicamente usando il beginAnalyzeDocumentFromUrl metodo . "Accessibile pubblicamente" significa che le origini URL devono essere accessibili dall'infrastruttura del servizio (in altre parole, un URL intranet privato o GLI URL che usano segreti basati su intestazioni o certificati, non funzioneranno, poiché il servizio Document Intelligence deve essere in grado di accedere all'URL). Tuttavia, l'URL stesso potrebbe codificare un segreto, ad esempio un URL BLOB di archiviazione di Azure che contiene un token di firma di accesso condiviso nei parametri di query.

Usare modelli di documento predefiniti

Il beginAnalyzeDocument metodo supporta anche l'estrazione di campi da determinati tipi di documenti comuni, ad esempio ricevute, fatture, biglietti da visita, documenti di identità e altro ancora usando modelli predefiniti forniti dal servizio Di Intelligence documenti. I modelli predefiniti possono essere forniti come stringhe ID modello (uguali ai modelli di documento personalizzati), vedere la sezione seguente di altri modelli predefiniti o l'uso di un DocumentModel oggetto. Quando si usa un DocumentModeloggetto , Document Intelligence SDK per JavaScript fornisce un tipo TypeScript molto più forte per i documenti estratti risultanti in base allo schema del modello e verrà convertito in modo da usare convenzioni di denominazione JavaScript.

Gli oggetti di esempio DocumentModel per la versione corrente dell'API prebuiltdel servizio (2022-08-31) sono disponibili nella directory degli esempi. Nell'esempio seguente si userà il PrebuiltReceiptModel file dal file [prebuilt-receipt.ts] in tale directory.

Poiché il vantaggio principale dell'analisi basata su è maggiore vincoli di tipo TypeScript, l'esempio seguente viene scritto in TypeScript usando la sintassi del DocumentModelmodulo 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);
});

In alternativa, come indicato in precedenza, anziché usare PrebuiltReceiptModel, che produce il tipo restituito più forte, l'ID modello della ricevuta predefinita ("ricevuta predefinita") può essere usato, ma i campi del documento non saranno fortemente tipizzata in TypeScript e i nomi dei campi saranno in genere in "PascalCase" anziché "camelCase".

Altri modelli predefiniti

Non sei limitato alle ricevute! Ci sono alcuni modelli predefiniti da scegliere, con più sul modo. Ogni modello predefinito ha un proprio set di campi supportati:

• Ricevute, usando PrebuiltReceiptModel (come sopra) o l'ID "prebuilt-receipt"del modello di ricevuta predefinito .
• Biglietti da visita, usando PrebuiltBusinessCardModel o il relativo ID "prebuilt-businessCard"modello.
• Fatture, usando PrebuiltInvoiceModel o il relativo ID "prebuilt-invoice"modello.
• Documenti di identità (ad esempio licenze di conducente e passaporti), usando PrebuiltIdDocumentModel o il relativo ID "prebuilt-idDocument"modello .
• Moduli fiscali W2 (Stati Uniti), usando PrebuiltTaxUsW2Model o il relativo ID "prebuilt-tax.us.w2"modello .
• Schede di assicurazione sanitaria (Stati Uniti), usando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] o il relativo ID "prebuilt-healthInsuranceCard.us"modello .

Ognuno dei modelli predefiniti precedenti produce documents (istanze estratte dello schema del campo del modello). Esistono anche tre modelli predefiniti che non dispongono di schemi di campo e pertanto non producono documents. ovvero:

• Il modello layout predefinito (vedere Usare la predefinita "layout") che estrae informazioni sugli elementi di layout di base (OCR), ad esempio pagine e tabelle.
• Il modello documento generale predefinito (vedere Usare la predefinita "document") che aggiunge coppie chiave-valore (associazioni dirette tra elementi di pagina, ad esempio elementi etichettati) alle informazioni prodotte dal modello di layout.
• Modello di lettura predefinito (vedere Usare la prebuilt "read" sotto), che estrae solo elementi testuali, ad esempio parole di pagina e righe, insieme alle informazioni sulla lingua del documento.

Per informazioni sui campi di tutti questi modelli, vedere la documentazione del servizio sui modelli predefiniti disponibili.

I campi di tutti i modelli predefiniti possono anche essere accessibili a livello di codice usando il metodo (in base agli ID modello) e DocumentModelAdministrationClient controllando il getDocumentModeldocTypes campo nel risultato.

Usare la predefinita "layout"

Il "prebuilt-layout" modello estrae solo gli elementi di base del documento, ad esempio le pagine, che sono costituite da parole di testo/righe e segni di selezione, tabelle e stili di testo visivi insieme alle relative aree di limite e si estende all'interno del contenuto di testo dei documenti di input. Viene fornita un'istanza fortemente tipizzata denominata DocumentModelPrebuiltLayoutModel che richiama questo modello o, come sempre, l'ID "prebuilt-layout" modello può essere usato direttamente.

Poiché il vantaggio principale dell'analisi basata su è maggiore vincoli di tipo TypeScript, l'esempio seguente viene scritto in TypeScript usando la sintassi del DocumentModelmodulo 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);
});

Usare la predefinita "document"

Il "prebuilt-document" modello estrae informazioni sulle coppie chiave-valore (associazioni dirette tra elementi di pagina, ad esempio campi etichettati) oltre alle proprietà prodotte dal metodo di estrazione del layout. Questo modello di documento predefinito (generale) offre funzionalità simili ai modelli personalizzati sottoposti a training senza informazioni sull'etichetta nelle iterazioni precedenti del servizio Di Intelligence documenti, ma viene ora fornito come modello predefinito che funziona con un'ampia gamma di documenti. Viene fornita un'istanza fortemente tipizzata denominata DocumentModelPrebuiltDocumentModel che richiama questo modello o, come sempre, l'ID "prebuilt-document" modello può essere usato direttamente.

Poiché il vantaggio principale dell'analisi basata su è maggiore vincoli di tipo TypeScript, l'esempio seguente viene scritto in TypeScript usando la sintassi del DocumentModelmodulo 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);
});

Usare la predefinita "read"

Il "prebuilt-read" modello estrae informazioni testuali in un documento, ad esempio parole e paragrafi, e analizza il linguaggio e lo stile di scrittura (ad esempio, set di tipi scritti a mano) di tale testo. Viene fornita un'istanza fortemente tipizzata denominata DocumentModelPrebuiltReadModel che richiama questo modello o, come sempre, l'ID "prebuilt-read" modello può essere usato direttamente.

Poiché il vantaggio principale dell'analisi basata su è maggiore vincoli di tipo TypeScript, l'esempio seguente viene scritto in TypeScript usando la sintassi del DocumentModelmodulo 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);
});

Classificare un documento

Il servizio Document Intelligence supporta classificatori di documenti personalizzati che possono classificare i documenti in un set di categorie predefinite in base a un set di dati di training. I documenti possono essere classificati con un classificatore personalizzato usando il beginClassifyDocument metodo di DocumentAnalysisClient. Come beginAnalyzeDocument sopra, questo metodo accetta un file o un flusso contenente il documento da classificare e ha una beginClassifyDocumentFromUrl controparte che accetta un URL accessibile pubblicamente in un documento.

L'esempio seguente illustra come classificare un documento usando un classificatore personalizzato:

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

Per informazioni sul training di un classificatore personalizzato, vedere la sezione relativa al training del classificatore alla fine della sezione successiva.

Creare un modello

L'SDK supporta anche la creazione di modelli usando la DocumentModelAdministrationClient classe . La creazione di un modello dai dati di training etichettati crea un nuovo modello sottoposto a training sui propri documenti e il modello risultante sarà in grado di riconoscere i valori dalle strutture di tali documenti. L'operazione di compilazione del modello accetta un URL codificato con firma di accesso condiviso in un contenitore BLOB di archiviazione di Azure che contiene i documenti di training. L'infrastruttura del servizio Document Intelligence leggerà i file nel contenitore e creerà un modello in base al contenuto. Per altre informazioni su come creare e strutturare un contenitore di dati di training, vedere la documentazione del servizio Document Intelligence per la creazione di un modello.

Anche se vengono forniti questi metodi per la creazione di modelli a livello di codice, il team del servizio Document Intelligence ha creato un'applicazione Web interattiva, Document Intelligence Studio, che consente di creare e gestire modelli sul Web.

Ad esempio, il programma seguente compila un modello di documento personalizzato usando un URL codificato con firma di accesso condiviso a un contenitore di Archiviazione di Azure preesistente:

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

I classificatori personalizzati vengono compilati in modo simile usando il beginBuildDocumentClassifier metodo anziché beginBuildDocumentModel. Per altre informazioni sulla creazione di un classificatore personalizzato, vedere l'esempio di classificatore di compilazione , poiché i dati di training di input vengono forniti in un formato leggermente diverso. Per informazioni sulla creazione di un set di dati di training per un classificatore personalizzato, vedere la documentazione del servizio Document Intelligence.

Gestire i modelli

DocumentModelAdministrationClient fornisce anche diversi metodi per l'accesso e l'elenco dei modelli. Nell'esempio seguente viene illustrato come eseguire l'iterazione dei modelli in una risorsa ,che include entrambi i modelli personalizzati nella risorsa e i modelli predefiniti comuni a tutte le risorse, ottenere un modello per ID ed eliminare un modello.

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

listDocumentClassifiers Metodi simili e sono disponibili per l'elenco e getDocumentClassifier ottenere informazioni sui classificatori personalizzati oltre all'eliminazione deleteDocumentClassifier di classificatori personalizzati.

Risoluzione dei problemi

Per assistenza alla risoluzione dei problemi, vedere la guida alla risoluzione dei problemi.

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Esaminare la directory degli esempi per esempi di codice dettagliati che illustrano come usare questa libreria, incluse diverse funzionalità e metodi non visualizzati nella sezione "Esempi", ad esempio la copia e la composizione di modelli, l'elenco delle operazioni di gestione dei modelli e l'eliminazione di modelli.

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.