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

Azure AI Document Intelligence è un servizio cloud che usa l'apprendimento automatico per analizzare testo e dati strutturati dai documenti. Include le funzionalità principali seguenti:

• Layout: consente di estrarre dai documenti il testo, le strutture delle tabelle e i segni di selezione, insieme alle coordinate della regione di delimitazione.
• Documento: consente di analizzare entità, coppie chiave-valore, tabelle e contrassegni di selezione dai documenti utilizzando il modello di documento predefinito generale.
• Lettura: consente di leggere le informazioni sugli elementi testuali, ad esempio le parole e le righe della pagina, oltre alle informazioni sulla lingua del testo.
• Predefinito: analizza i dati di determinati tipi di documenti comuni (ad esempio ricevute, fatture, biglietti da visita o documenti di identità) utilizzando modelli predefiniti.
• Personalizzato: crea modelli personalizzati per estrarre testo, valori di campo, segni di selezione e dati di tabella dai documenti. I modelli personalizzati vengono creati con i tuoi dati, quindi sono personalizzati in base ai tuoi documenti.
• Classificatori: crea classificatori personalizzati per classificare i documenti in classi predefinite.

Codice sorgente | Pacchetto (NPM) | Documentazione | di riferimento APIDocumentazione del | prodottoCampioni

Annotazioni

Il servizio Document Intelligence era precedentemente noto come "Azure Form Recognizer". Questi servizi sono gli stessi e il @azure/ai-form-recognizer pacchetto per JavaScript è il pacchetto Azure SDK per il servizio Azure AI Document Intelligence. Al momento della scrittura, è in corso la ridenominazione di Riconoscimento modulo di Azure in Azure AI Document Intelligence, quindi "Riconoscimento modulo" e "Document Intelligence" possono essere usati 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

Come iniziare

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node: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 = createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

const { pages, tables, styles, keyValuePairs, documents } = await poller.pollUntilDone();

Ambienti attualmente supportati

• Versioni LTS di Node.js
• Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

• Una sottoscrizione di Azure
• Una risorsa di 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 Form Recognizer

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

Document Intelligence supporta sia l'accesso multiservizio che quello a servizio singolo. Creare una risorsa di Servizi cognitivi se si prevede di accedere a più servizi cognitivi in un singolo endpoint/chiave. Per accedere esclusivamente a Form Recognizer, creare una risorsa di Form Recognizer.

È possibile creare la risorsa utilizzando

Opzione 1:portale di Azure

Opzione 2:interfaccia della riga di comando di Azure.

Di seguito è riportato un esempio di come è possibile 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 e autenticare un client

Per interagire con il servizio di Document Intelligence, è necessario selezionare a DocumentAnalysisClient o a DocumentModelAdministrationClient, e creare un'istanza di questo tipo. Negli esempi seguenti, utilizzeremo DocumentAnalysisClient. Per creare un'istanza client per accedere all'API di Document Intelligence, è necessario disporre endpoint della risorsa Riconoscimento modulo e di un credentialfile . I client possono usare una AzureKeyCredential chiave API della risorsa o una TokenCredential che usa il 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 codice della riga di comando di Azure riportato di seguito:

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

Utilizzare una chiave API

Usare il portale di Azure per passare alla risorsa Riconoscimento modulo e recuperare una chiave API oppure usare il frammento di codice 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>

Una volta che hai una chiave API e un endpoint, puoi usarli come segue:

import { AzureKeyCredential, DocumentAnalysisClient } from "@azure/ai-form-recognizer";

const credential = new AzureKeyCredential("<API key>");
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

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 usando un'entità servizio, è anche necessario registrare un'applicazione AAD e concedere l'accesso al servizio assegnando il ruolo all'entità "Cognitive Services User" servizio (nota: altri ruoli come "Owner" non concederanno le autorizzazioni necessarie, saranno sufficienti solo "Cognitive Services User" per eseguire 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_ID, AZURE_CLIENT_SECRET.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

Cloud sovrani

Connettersi ad ambienti cloud Azure alternativi (ad esempio Azure Cina o Azure per enti pubblici) specificando l'opzione durante la creazione del audience client. Usare l'enumerazione KnownFormRecognizerAudience per selezionare il valore corretto per l'ambiente.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient, KnownFormRecognizerAudience } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com", // endpoint
  credential,
  {
    audience: KnownFormRecognizerAudience.AzureGovernment,
  }
);

Se non si specifica l'opzione audience , l'impostazione predefinita è adatta per il cloud pubblico di Azure (https://cognitiveservices.azure.com).

Concetti chiave

DocumentAnalysisClient

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

• beginAnalyzeDocument, che estrae i dati da un flusso di file di documento di input utilizzando un modello personalizzato o predefinito fornito dal relativo ID modello. Per informazioni sui modelli predefiniti supportati in tutte le risorse e sui relativi ID/output dei modelli, vedere la documentazione dei modelli del servizio.
• beginAnalyzeDocumentFromUrl, che svolge 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 i campi in base a uno schema personalizzato. I dati di training devono trovarsi in un contenitore di archiviazione di Azure e essere organizzati in base a una convenzione specifica. Consulta la documentazione del servizio sulla creazione di un set di dati di addestramento per una spiegazione più dettagliata dell'applicazione di etichette a un set di dati di addestramento.
• beginComposeDocumentModel Avvia un'operazione per comporre più modelli in un unico modello. Quando viene utilizzato per il riconoscimento di moduli personalizzati, il nuovo modello composto eseguirà prima una classificazione dei documenti di input per determinare quale dei suoi sottomodelli è più appropriato.
• beginCopyModelTo Avvia un'operazione per copiare un modello personalizzato da una risorsa a un'altra (o anche alla stessa risorsa). Richiede un CopyAuthorization dalla risorsa di destinazione, che può essere generato utilizzando 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 deleteDocumentModel e listDocumentModelsabilitare la gestione dei modelli nella risorsa.
• getOperation e listOperations abilitare la visualizzazione dello stato delle operazioni di creazione del modello, anche quelle in corso o non riuscite. Le operazioni vengono mantenute per 24 ore.

Si prega di notare che i modelli possono essere creati anche utilizzando l'interfaccia utente grafica del servizio di Document Intelligence: Document Intelligence Studio.

Frammenti di codice di esempio che illustrano l'uso di DocumentModelAdministrationClient per costruire un modello sono disponibili di seguito, nella sezione di esempio "Costruire un modello".

Operazioni a esecuzione prolungata

Le operazioni a esecuzione prolungata sono operazioni che consistono in 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 è riuscita o ha avuto esito positivo. Alla fine, l'LRO fallirà con un errore o produrrà un risultato.

In Azure AI Document Intelligence le operazioni che creano modelli (tra cui 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 attendendo il pollUntilDone metodo sul poller restituito dal begin<operation-name> metodo. Nella sezione successiva vengono forniti frammenti di codice di esempio per illustrare l'uso di operazioni a esecuzione prolungata.

Esempi

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

• Analizzare un documento con un ID modello
• Utilizzare modelli di documento predefiniti
• Usa il "layout" predefinito
• Usa il "documento" predefinito
• Usa la funzione predefinita di "lettura"
• Costruisci 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ò utilizzare 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 in base ai propri documenti, pertanto deve essere utilizzato solo con documenti della stessa struttura di uno dei tipi di documento nel modello (possono essere presenti più documenti, ad esempio in un modello composto).

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const modelId = "<model id>";
const path = "<path to a document>";
const readStream = createReadStream(path);

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 content '${field.content}' 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}"`);
  }
}

Analizzare un documento da un URL

In alternativa alla fornitura di un flusso leggibile, è possibile fornire un URL accessibile pubblicamente utilizzando 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 URL che utilizzano segreti basati su intestazioni o certificati, non funzioneranno, poiché il servizio di 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.

Utilizzare modelli di documento predefiniti

Il beginAnalyzeDocument metodo supporta anche l'estrazione di campi da alcuni tipi di documenti comuni come ricevute, fatture, biglietti da visita, documenti di identità e altro ancora utilizzando modelli predefiniti forniti dal servizio di Document Intelligence. I modelli predefiniti possono essere forniti come stringhe di ID modello (come per i modelli di documenti personalizzati, vedere la sezione Altri modelli predefiniti di seguito) o utilizzando un DocumentModel oggetto. Quando si usa , DocumentModelDocument 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 per usare le convenzioni di denominazione JavaScript.

Gli oggetti di esempio DocumentModel per la versione corrente dell'API del servizio (2022-08-31) sono disponibili nella prebuilt directory degli esempi. Nell'esempio seguente, utilizzeremo il PrebuiltReceiptModel file from [prebuilt-receipt.ts] in quella directory.

Poiché il vantaggio principale dell'analisi DocumentModelbasata su -based è costituito da vincoli di tipo TypeScript più forti, l'esempio seguente viene scritto in TypeScript utilizzando la sintassi del modulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReceiptModel } from "../samples-dev/prebuilt/prebuilt-receipt.js";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const path = "<path to a document>";
const readStream = createReadStream(path);

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

In alternativa, come accennato in precedenza, invece di utilizzare PrebuiltReceiptModel, che produce il tipo di ritorno più forte, è possibile utilizzare l'ID modello della ricevuta predefinita ("prebuilt-receipt"), ma i campi del documento non saranno fortemente tipizzati in TypeScript e i nomi dei campi saranno generalmente in "PascalCase" anziché in "camelCase".

Altri modelli preassemblati

Non sei limitato alle ricevute! Ci sono alcuni modelli preassemblati tra cui scegliere, con altri in arrivo. Ogni modello predefinito dispone di un proprio set di campi supportati:

• Ricevute, utilizzando PrebuiltReceiptModel (come sopra) o l'ID "prebuilt-receipt"del modello di ricevuta predefinito.
• Biglietti da visita, utilizzando PrebuiltBusinessCardModel o il suo modello ID "prebuilt-businessCard".
• Fatture, utilizzando PrebuiltInvoiceModel o il suo modello ID "prebuilt-invoice".
• Documenti di identità (come patenti di guida e passaporti), utilizzando PrebuiltIdDocumentModel o il suo modello ID "prebuilt-idDocument".
• W2 Tax Forms (Stati Uniti), utilizzando PrebuiltTaxUsW2Model o il suo modello ID "prebuilt-tax.us.w2".
• Tessere di assicurazione sanitaria (Stati Uniti), utilizzando [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] o il suo ID "prebuilt-healthInsuranceCard.us"modello .

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

• Il modello di layout predefinito (vedere Utilizzare il "layout" predefinito di seguito), che estrae informazioni sugli elementi di layout di base (OCR) come pagine e tabelle.
• Il modello di documento generale predefinito (vedere Utilizzare il "documento" predefinito di seguito), che aggiunge coppie chiave-valore (associazioni dirette tra gli elementi della pagina, ad esempio gli elementi etichettati) alle informazioni prodotte dal modello di layout.
• Il modello di lettura predefinito (vedere Utilizzare la funzione di lettura predefinita di seguito), che estrae solo elementi testuali, ad esempio parole e righe della pagina, insieme a informazioni sulla lingua del documento.

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

È inoltre possibile accedere ai campi di tutti i modelli predefiniti a livello di codice utilizzando il getDocumentModel metodo (in base agli ID modello) e DocumentModelAdministrationClient ispezionando il docTypes campo nel risultato.

Usa il "layout" predefinito

Il "prebuilt-layout" modello estrae solo gli elementi di base del documento, ad esempio le pagine (che consistono in parole/righe di testo e segni di selezione), le tabelle e gli stili di testo visivi insieme alle relative aree di delimitazione e intervalli all'interno del contenuto di testo dei documenti di input. Viene fornita un'istanza fortemente tipizzata DocumentModel denominata PrebuiltLayoutModel che richiama questo modello o, come sempre, è possibile utilizzare direttamente l'ID "prebuilt-layout" modello.

Poiché il vantaggio principale dell'analisi DocumentModelbasata su -based è costituito da vincoli di tipo TypeScript più forti, l'esempio seguente viene scritto in TypeScript utilizzando la sintassi del modulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltLayoutModel } from "../samples-dev/prebuilt/prebuilt-layout.js";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const path = "<path to a document>";
const readStream = createReadStream(path);

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

Usa il "documento" predefinito

Il "prebuilt-document" modello estrae informazioni sulle coppie chiave-valore (associazioni dirette tra gli elementi della pagina, ad esempio i 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 Document Intelligence, ma ora viene fornito come modello predefinito che funziona con un'ampia gamma di documenti. Viene fornita un'istanza fortemente tipizzata DocumentModel denominata PrebuiltDocumentModel che richiama questo modello o, come sempre, è possibile utilizzare direttamente l'ID "prebuilt-document" modello.

Poiché il vantaggio principale dell'analisi DocumentModelbasata su -based è costituito da vincoli di tipo TypeScript più forti, l'esempio seguente viene scritto in TypeScript utilizzando la sintassi del modulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltDocumentModel } from "../samples-dev/prebuilt/prebuilt-document.js";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const path = "<path to a document>";
const readStream = createReadStream(path);

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

Usa la funzione predefinita di "lettura"

Il "prebuilt-read" modello estrae informazioni testuali in un documento, come parole e paragrafi, e analizza la lingua e lo stile di scrittura (ad esempio, scritto a mano o impaginato) di quel testo. Viene fornita un'istanza fortemente tipizzata DocumentModel denominata PrebuiltReadModel che richiama questo modello o, come sempre, è possibile utilizzare direttamente l'ID "prebuilt-read" modello.

Poiché il vantaggio principale dell'analisi DocumentModelbasata su -based è costituito da vincoli di tipo TypeScript più forti, l'esempio seguente viene scritto in TypeScript utilizzando la sintassi del modulo ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReadModel } from "../samples-dev/prebuilt/prebuilt-read.js";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const path = "<path to a document>";
const readStream = createReadStream(path);

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

function* getTextOfSpans(content, spans) {
  for (const span of spans) {
    yield content.slice(span.offset, span.offset + span.length);
  }
}

Classificare un documento

Il servizio Document Intelligence supporta classificatori di documenti personalizzati in grado di 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 utilizzando il beginClassifyDocument metodo di DocumentAnalysisClient. Come beginAnalyzeDocument sopra, questo metodo accetta un file o un flusso contenente il documento da classificare e ha invece una beginClassifyDocumentFromUrl controparte che accetta un URL accessibile pubblicamente a un documento.

Nell'esempio seguente viene illustrato come classificare un documento utilizzando un classificatore personalizzato:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const documentUrl =
  "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/invoice/Invoice_1.pdf";

const poller = await client.beginClassifyDocumentFromUrl("<classifier id>", documentUrl);

const result = await poller.pollUntilDone();

if (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})`,
  );
}

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 utilizzando la DocumentModelAdministrationClient classe. La creazione di un modello da 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 con codifica SAS in un contenitore BLOB di archiviazione di Azure che contiene i documenti di training. L'infrastruttura del servizio di Document Intelligence leggerà i file nel contenitore e creerà un modello basato sul loro contenuto. Per ulteriori dettagli su come creare e strutturare un contenitore di dati di addestramento, vedere la documentazione del servizio Document Intelligence per la creazione di un modello.

Sebbene forniamo 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 la creazione e la gestione di modelli sul Web.

Ad esempio, il programma seguente crea un modello di documento personalizzato usando un URL con codifica SAS per un contenitore di archiviazione di Azure preesistente:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentModelAdministrationClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

const containerSasUrl = "<SAS url to the blob container storing training documents>";

// 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>"}`);
  }
}

I classificatori personalizzati vengono compilati in modo simile utilizzando il metodo anziché beginBuildDocumentModel.beginBuildDocumentClassifier 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 inoltre diversi metodi per accedere ed elencare i modelli. Nell'esempio seguente viene illustrato come scorrere i modelli in una risorsa (inclusi sia i modelli personalizzati nella risorsa che i modelli predefiniti comuni a tutte le risorse), ottenere un modello in base all'ID ed eliminare un modello.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentModelAdministrationClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential,
);

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

Metodi listDocumentClassifiers simili e getDocumentClassifier sono disponibili per elencare e ottenere informazioni sui classificatori personalizzati, oltre deleteDocumentClassifier che per eliminare i classificatori personalizzati.

Risoluzione dei problemi

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

Registrazione

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

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

Passaggi successivi

Dai un'occhiata alla directory degli esempi per esempi di codice dettagliati che mostrano come utilizzare questa libreria, incluse diverse funzionalità e metodi che non sono mostrati nella sezione "Esempi" precedente, come la copia e la composizione di modelli, l'elenco delle operazioni di gestione dei modelli e l'eliminazione dei modelli.

Contribuire

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