Azure AI Document Intelligence-Clientbibliothek für JavaScript – Version 5.1.0

Azure AI Document Intelligence ist ein Clouddienst, der maschinelles Lernen verwendet, um Text und strukturierte Daten aus Ihren Dokumenten zu analysieren. Es enthält die folgenden Hauptfunktionen:

• Layout - Extrahieren Sie Text, Tabellenstrukturen und Auswahlmarkierungen zusammen mit den Koordinaten der Begrenzungsbereiche aus Dokumenten.
• Dokument: Analysieren Sie Entitäten, Schlüssel-Wert-Paare, Tabellen und Auswahlmarkierungen aus Dokumenten mithilfe des allgemeinen vordefinierten Dokumentmodells.
• Lesen: Lesen Sie Informationen zu Textelementen, wie z. B. Seitenwörtern und -zeilen, zusätzlich zu Informationen zur Textsprache.
• Vordefiniert: Analysieren Sie Daten aus bestimmten Arten gängiger Dokumente (z. B. Quittungen, Rechnungen, Visitenkarten oder Ausweisdokumente) mithilfe vordefinierter Modelle.
• Benutzerdefiniert: Erstellen Sie benutzerdefinierte Modelle, um Text, Feldwerte, Auswahlmarkierungen und Tabellendaten aus Dokumenten zu extrahieren. Benutzerdefinierte Modelle werden mit Ihren eigenen Daten erstellt, sodass sie auf Ihre Dokumente zugeschnitten sind.
• Klassifikatoren - Erstellen Sie benutzerdefinierte Klassifikatoren, um Dokumente in vordefinierte Klassen zu kategorisieren.

Quellcode | Package (NPM) | API-Referenzdokumentation | Produktdokumentation | Beispiele

Hinweis

Der Document Intelligence-Dienst war früher als "Azure Form Recognizer" bekannt. Diese Dienste sind ein und derselbe, und das @azure/ai-form-recognizer Paket für JavaScript ist das Azure SDK-Paket für den Azure AI Document Intelligence-Dienst. Zum Zeitpunkt der Erstellung dieses Artikels ist die Umbenennung der Azure-Formularerkennung in Azure AI Document Intelligence im Gange, sodass "Formularerkennung" und "Document Intelligence" in einigen Fällen austauschbar verwendet werden können.

Installieren Sie das @azure/ai-form-recognizer-Paket

Installieren Sie die Azure Document Intelligence-Clientbibliothek für JavaScript mit npm:

npm install @azure/ai-form-recognizer

Erste Schritte

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

Derzeit unterstützte Umgebungen

• LTS-Versionen von Node.js
• Neueste Versionen von Safari, Chrome, Edge und Firefox.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

• Ein Azure-Abonnement
• Eine Cognitive Services- oder Formularerkennungsressource. Wenn Sie die Ressource erstellen müssen, können Sie das Azure Portal oder Azure CLIverwenden.

Erstellen einer Formularerkennungsressource

Hinweis: Zum Zeitpunkt der Erstellung dieses Artikels wird die Ressource im Azure-Portal noch als "Formularerkennungsressource" bezeichnet. In Zukunft kann dies zu einer "Document Intelligence"-Ressource aktualisiert werden. Im Moment wird in der folgenden Dokumentation der Name "Formularerkennung" verwendet.

Document Intelligence unterstützt sowohl den Multi-Service- als auch den Single-Service-Zugriff. Erstellen Sie eine Cognitive Services-Ressource, wenn Sie auf mehrere Cognitive Services unter einem einzigen Endpunkt/Schlüssel zugreifen möchten. Erstellen Sie eine Formularerkennungsressource, falls nur auf die Formularerkennung zugegriffen werden soll.

Sie können die Ressource mit

Option 1:Azure-Portal

Option 2:Azure CLI.

Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Formularerkennungsressource mithilfe der CLI erstellen können:

# 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

Wenn Sie die Azure CLI verwenden, ersetzen Sie <your-resource-group-name> und <your-resource-name> durch Ihre eigenen eindeutigen Namen:

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

Erstellen und Authentifizieren eines Clients

Um mit dem Document Intelligence-Dienst interagieren zu können, müssen Sie entweder a DocumentAnalysisClient oder a DocumentModelAdministrationClientauswählen und eine Instanz dieses Typs erstellen. In den folgenden Beispielen verwenden DocumentAnalysisClientwir . Um eine Clientinstanz für den Zugriff auf die Document Intelligence-API zu erstellen, benötigen Sie die endpoint der Formularerkennungsressource und eine credential. Die Clients können entweder einen AzureKeyCredential API-Schlüssel Ihrer Ressource oder einen TokenCredential verwenden, der Azure Active Directory RBAC verwendet, um den Client zu autorisieren.

Den Endpunkt für Ihre Formularerkennungsressource finden Sie entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Codeausschnitts :

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

Verwenden eines API-Schlüssels

Navigieren Sie im Azure-Portal zu Ihrer Formularerkennungsressource, um einen API-Schlüssel abzurufen, oder verwenden Sie den folgenden Azure CLI-Codeausschnitt :

Hinweis: Manchmal wird der API-Schlüssel als "Abonnementschlüssel" oder "Abonnement-API-Schlüssel" bezeichnet.

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

Sobald Sie über einen API-Schlüssel und einen Endpunkt verfügen, können Sie diese wie folgt verwenden:

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

Verwenden von Azure Active Directory

In den meisten Beispielen wird die API-Schlüsselautorisierung verwendet, aber Sie können den Client auch mithilfe der Azure Identity-Bibliothek mit Azure Active Directory authentifizieren. Um den unten gezeigten DefaultAzureCredential-Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das @azure/identity Paket:

npm install @azure/identity

Um sich mit einem Dienstprinzipal zu authentifizieren, müssen Sie auch eine AAD-Anwendung registrieren und Zugriff auf den Dienst gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen (Hinweis: Andere Rollen "Owner" erteilen nicht die erforderlichen Berechtigungen, sondern reichen nur "Cognitive Services User" zum Ausführen der Beispiele und des Beispielcodes aus).

Legen Sie die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: 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,
);

Souveräne Clouds

Stellen Sie eine Verbindung mit alternativen Azure-Cloudumgebungen (z. B. Azure China oder Azure Government) her, indem Sie die audience Option beim Erstellen Ihres Clients angeben. Verwenden Sie die KnownFormRecognizerAudience Enumeration, um den richtigen Wert für Ihre Umgebung auszuwählen.

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

Wenn Sie die audience Option nicht angeben, ist die Standardeinstellung für die Azure Public Cloud geeignet (https://cognitiveservices.azure.com).

Wichtige Begriffe

DocumentAnalysisClient

DocumentAnalysisClient Stellt Vorgänge zum Analysieren von Eingabedokumenten mithilfe von benutzerdefinierten und vordefinierten Modellen bereit. Es gibt drei Methoden:

• beginAnalyzeDocument, die Daten aus einem Eingabedokumentdateistream unter Verwendung eines benutzerdefinierten oder vordefinierten Modells extrahiert, das durch seine Modell-ID angegeben wird. Informationen zu den vordefinierten Modellen, die in allen Ressourcen unterstützt werden, und deren Modell-IDs/-Ausgaben finden Sie in der Dokumentation des Diensts zu den Modellen.
• beginAnalyzeDocumentFromUrl, die die gleiche Funktion wie beginAnalyzeDocumentausführt, aber eine öffentlich zugängliche URL einer Datei anstelle eines Dateistreams übermittelt.

DocumentModelAdministrationClient

DocumentModelAdministrationClient Stellt Vorgänge zum Verwalten (Erstellen, Lesen, Auflisten und Löschen) von Modellen in der Ressource bereit:

• beginBuildDocumentModel Startet einen Vorgang, um ein neues Dokumentmodell aus Ihrem eigenen Trainingsdataset zu erstellen. Das erstellte Modell kann Felder gemäß einem benutzerdefinierten Schema extrahieren. Es wird erwartet, dass sich die Trainingsdaten in einem Azure Storage-Container befinden und gemäß einer bestimmten Konvention organisiert sind. Eine ausführlichere Erläuterung des Anwendens von Bezeichnungen auf ein Trainingsdataset finden Sie in der Dokumentation des Diensts zum Erstellen eines Trainingsdatasets .
• beginComposeDocumentModel Startet einen Vorgang, um mehrere Modelle zu einem einzigen Modell zusammenzusetzen. Bei der Verwendung für die Erkennung benutzerdefinierter Formulare führt das neue zusammengesetzte Modell zunächst eine Klassifizierung der Eingabedokumente durch, um zu bestimmen, welches seiner Untermodelle am besten geeignet ist.
• beginCopyModelTo Startet einen Vorgang, um ein benutzerdefiniertes Modell von einer Ressource in eine andere (oder sogar in dieselbe Ressource) zu kopieren. Es wird ein von CopyAuthorization der Zielressource benötigt, das mit der getCopyAuthorization Methode generiert werden kann.
• getResourceDetails Ruft Informationen zu den Grenzwerten der Ressource ab, z. B. die Anzahl der benutzerdefinierten Modelle und die maximale Anzahl von Modellen, die von der Ressource unterstützt werden können.
• getDocumentModel, listDocumentModelsund deleteDocumentModel aktivieren Sie die Verwaltung von Modellen in der Ressource.
• getOperation und listOperations ermöglichen die Anzeige des Status von Modellerstellungsvorgängen, auch von Vorgängen, die ausgeführt werden oder fehlgeschlagen sind. Vorgänge werden 24 Stunden lang aufbewahrt.

Bitte beachten Sie, dass Modelle auch über die grafische Benutzeroberfläche des Document Intelligence Service erstellt werden können: Document Intelligence Studio.

Beispielcodeausschnitte, die die Verwendung von DocumentModelAdministrationClient zum Erstellen eines Modells veranschaulichen, finden Sie unten im Beispielabschnitt "Erstellen eines Modells".

Zeitintensive Vorgänge

Vorgänge mit langer Ausführungszeit (Long Running Operations, LROs) sind Vorgänge, die aus einer ersten Anforderung bestehen, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von einem Abruf eines Ergebnisses in einem bestimmten Intervall, um zu bestimmen, ob der Vorgang abgeschlossen ist und ob er fehlgeschlagen oder erfolgreich war. Letztendlich schlägt das LRO entweder mit einem Fehler fehl oder führt zu einem Ergebnis.

In Azure AI Document Intelligence sind Vorgänge, die Modelle erstellen (einschließlich Kopieren und Erstellen von Modellen) sowie die Analyse-/Datenextraktionsvorgänge LROs. Die SDK-Clients stellen asynchrone begin<operation-name> Methoden bereit, die Objekte zurückgeben Promise<PollerLike> . Das PollerLike Objekt stellt den Vorgang dar, der asynchron in der Infrastruktur des Diensts ausgeführt wird, und ein Programm kann warten, bis der Vorgang abgeschlossen ist, indem es die pollUntilDone Methode auf dem von der begin<operation-name> Methode zurückgegebenen Abfragemodul aufruft und darauf wartet. Beispielcodeausschnitte werden bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungszeit im nächsten Abschnitt zu veranschaulichen.

Beispiele

Der folgende Abschnitt enthält mehrere JavaScript-Codeausschnitte, die gängige Muster veranschaulichen, die in den Document Intelligence-Clientbibliotheken verwendet werden.

• Analysieren eines Dokuments mit einer Modell-ID
• Verwenden Sie vorgefertigte Dokumentmodelle
• Verwenden Sie das vorgefertigte "Layout"
• Verwenden Sie das vorgefertigte "Dokument"
• Verwenden Sie die vorgefertigte Option "read"
• Erstellen eines Modells
• Verwalten von Modellen

Analysieren eines Dokuments mit einer Modell-ID

Die beginAnalyzeDocument Methode kann Felder und Tabellendaten aus Dokumenten extrahieren. Bei der Analyse kann entweder ein benutzerdefiniertes Modell verwendet werden, das mit Ihren eigenen Daten trainiert wurde, oder ein vordefiniertes Modell, das vom Service bereitgestellt wird (siehe Verwenden von vordefinierten Modellen unten). Ein benutzerdefiniertes Modell ist auf Ihre eigenen Dokumente zugeschnitten und sollte daher nur mit Dokumenten verwendet werden, die dieselbe Struktur wie einer der Dokumenttypen im Modell haben (es können mehrere vorhanden sein, z. B. in einem zusammengesetzten Modell).

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

Analysieren eines Dokuments über eine URL

Als Alternative zum Bereitstellen eines lesbaren Streams kann stattdessen eine öffentlich zugängliche URL mit der beginAnalyzeDocumentFromUrl Methode bereitgestellt werden. "Öffentlich zugänglich" bedeutet, dass URL-Quellen über die Infrastruktur des Dienstes zugänglich sein müssen (mit anderen Worten, eine private Intranet-URL oder URLs, die header- oder zertifikatbasierte Geheimnisse verwenden, funktionieren nicht, da der Document Intelligence-Dienst auf die URL zugreifen können muss). Die URL selbst kann jedoch ein Geheimnis codieren, z. B. eine Azure Storage-Blob-URL, die ein SAS-Token in den Abfrageparametern enthält.

Verwenden Sie vorgefertigte Dokumentmodelle

Die beginAnalyzeDocument Methode unterstützt auch das Extrahieren von Feldern aus bestimmten Arten allgemeiner Dokumente, z. B. Quittungen, Rechnungen, Visitenkarten, Ausweisdokumente und mehr, mithilfe vorgefertigter Modelle, die vom Document Intelligence-Dienst bereitgestellt werden. Die vordefinierten Modelle können entweder als Modell-ID-Zeichenfolgen (wie bei benutzerdefinierten Dokumentmodellen – siehe Abschnitt "Andere vordefinierte Modelle " weiter unten) oder mithilfe eines Objekts DocumentModel bereitgestellt werden. Wenn Sie ein DocumentModelverwenden, stellt das Document Intelligence SDK für JavaScript einen viel stärkeren TypeScript-Typ für die resultierenden extrahierten Dokumente basierend auf dem Schema des Modells bereit, und es wird konvertiert, um JavaScript-Namenskonventionen zu verwenden.

Beispielobjekte DocumentModel für die aktuelle Service-API-Version (2022-08-31) finden Sie im prebuilt Verzeichnis samples. Im folgenden Beispiel verwenden wir die PrebuiltReceiptModel aus der Datei [prebuilt-receipt.ts] in diesem Verzeichnis.

Da der Hauptvorteil der DocumentModel-basierten Analyse in stärkeren TypeScript-Typeinschränkungen besteht, wurde das folgende Beispiel in TypeScript unter Verwendung der ECMAScript-Modulsyntax geschrieben:

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

Alternativ kann, wie oben erwähnt, anstelle von PrebuiltReceiptModel, was den stärkeren Rückgabetyp erzeugt, die Modell-ID des vordefinierten Belegs ("prebuilt-receipt") verwendet werden, aber die Dokumentfelder werden in TypeScript nicht stark typisiert, und die Feldnamen werden im Allgemeinen in "PascalCase" anstelle von "camelCase" angegeben.

Andere vorgefertigte Modelle

Sie sind nicht auf Quittungen beschränkt! Es stehen einige vorgefertigte Modelle zur Auswahl, weitere sind auf dem Weg. Jedes vordefinierte Modell verfügt über einen eigenen Satz unterstützter Felder:

• Zugänge mit PrebuiltReceiptModel (wie oben) oder der vordefinierten Belegmodell-ID "prebuilt-receipt".
• Visitenkarten, mit PrebuiltBusinessCardModel oder deren Modell-ID "prebuilt-businessCard".
• Rechnungen, mit PrebuiltInvoiceModel oder deren Modell-ID "prebuilt-invoice".
• Ausweisdokumente (z. B. Führerscheine und Reisepässe), die einen Personalausweis verwenden PrebuiltIdDocumentModel oder dessen Modellausweis "prebuilt-idDocument"verwenden.
• W2 Tax Forms (USA), unter Verwendung der PrebuiltTaxUsW2Model Modell-ID "prebuilt-tax.us.w2".
• Krankenversicherungskarten (USA) unter Verwendung von [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] oder seiner Modell-ID "prebuilt-healthInsuranceCard.us".

Jedes der oben genannten vordefinierten Modelle erzeugt documents (extrahierte Instanzen des Feldschemas des Modells). Es gibt auch drei vordefinierte Modelle, die keine Feldschemata haben und daher keine documents. Sie lauten wie folgt:

• Das vordefinierte Layout-Modell (siehe Verwenden des vordefinierten "Layouts" unten), das Informationen über grundlegende Layoutelemente (OCR) wie Seiten und Tabellen extrahiert.
• Das vordefinierte Modell "Allgemeines Dokument" (siehe Verwenden des vordefinierten "Dokuments" unten), das den vom Layoutmodell erzeugten Informationen Schlüssel-Wert-Paare (gerichtete Assoziationen zwischen Seitenelementen, z. B. beschriftete Elemente) hinzufügt.
• Das vordefinierte Lesemodell (siehe Verwenden des vordefinierten "read"-Modells unten), das nur Textelemente wie Seitenwörter und Zeilen zusammen mit Informationen über die Sprache des Dokuments extrahiert.

Informationen zu den Feldern all dieser Modelle finden Sie in der Dokumentation des Diensts zu den verfügbaren vordefinierten Modellen.

Auf die Felder aller vordefinierten Modelle kann auch programmgesteuert zugegriffen werden, indem die getDocumentModel Methode (anhand ihrer Modell-IDs) verwendet DocumentModelAdministrationClient und das docTypes Feld im Ergebnis überprüft wird.

Verwenden Sie das vorgefertigte "Layout"

Das "prebuilt-layout" Modell extrahiert nur die grundlegenden Elemente des Dokuments, z. B. Seiten (die aus Textwörtern/-zeilen und Auswahlmarkierungen bestehen), Tabellen und visuelle Textstile zusammen mit ihren Begrenzungsbereichen und -bereichen innerhalb des Textinhalts der Eingabedokumente. Wir stellen eine stark typisierte DocumentModel Instanz mit dem Namen PrebuiltLayoutModel bereit, die dieses Modell aufruft, oder wie immer kann ihre Modell-ID "prebuilt-layout" direkt verwendet werden.

Da der Hauptvorteil der DocumentModel-basierten Analyse in stärkeren TypeScript-Typeinschränkungen besteht, wurde das folgende Beispiel in TypeScript unter Verwendung der ECMAScript-Modulsyntax geschrieben:

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

Verwenden Sie das vorgefertigte "Dokument"

Das "prebuilt-document" Modell extrahiert Informationen zu Schlüssel-Wert-Paaren (gerichtete Zuordnungen zwischen Seitenelementen, z. B. beschriftete Felder) zusätzlich zu den Eigenschaften, die von der Layoutextraktionsmethode erzeugt werden. Dieses vordefinierte (allgemeine) Dokumentmodell bietet ähnliche Funktionen wie die benutzerdefinierten Modelle, die in früheren Iterationen des Document Intelligence-Diensts ohne Bezeichnungsinformationen trainiert wurden, aber es wird jetzt als vordefiniertes Modell bereitgestellt, das mit einer Vielzahl von Dokumenten funktioniert. Wir stellen eine stark typisierte DocumentModel Instanz mit dem Namen PrebuiltDocumentModel bereit, die dieses Modell aufruft, oder wie immer kann ihre Modell-ID "prebuilt-document" direkt verwendet werden.

Da der Hauptvorteil der DocumentModel-basierten Analyse in stärkeren TypeScript-Typeinschränkungen besteht, wurde das folgende Beispiel in TypeScript unter Verwendung der ECMAScript-Modulsyntax geschrieben:

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

Verwenden Sie die vorgefertigte Option "read"

Das "prebuilt-read" Modell extrahiert Textinformationen in einem Dokument, wie z. B. Wörter und Absätze, und analysiert die Sprache und den Schreibstil (z. B. handschriftlich vs. gesetzt) dieses Textes. Wir stellen eine stark typisierte DocumentModel Instanz mit dem Namen PrebuiltReadModel bereit, die dieses Modell aufruft, oder wie immer kann ihre Modell-ID "prebuilt-read" direkt verwendet werden.

Da der Hauptvorteil der DocumentModel-basierten Analyse in stärkeren TypeScript-Typeinschränkungen besteht, wurde das folgende Beispiel in TypeScript unter Verwendung der ECMAScript-Modulsyntax geschrieben:

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

Klassifizieren eines Dokuments

Der Document Intelligence-Dienst unterstützt benutzerdefinierte Dokumentklassifikatoren, die Dokumente basierend auf einem Trainingsdataset in eine Reihe vordefinierter Kategorien klassifizieren können. Dokumente können mit einem benutzerdefinierten Klassifikator klassifiziert werden, indem die beginClassifyDocument Methode von DocumentAnalysisClientverwendet wird. Wie beginAnalyzeDocument oben akzeptiert diese Methode eine Datei oder einen Stream, die das zu klassifizierende Dokument enthält, und sie verfügt über ein beginClassifyDocumentFromUrl Gegenstück, das stattdessen eine öffentlich zugängliche URL zu einem Dokument akzeptiert.

Das folgende Beispiel zeigt, wie ein Dokument mithilfe eines benutzerdefinierten Klassifizierers klassifiziert wird:

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

Informationen zum Trainieren eines benutzerdefinierten Klassifizierers finden Sie im Abschnitt zum Klassifizierertraining am Ende des nächsten Abschnitts.

Modell erstellen

Das SDK unterstützt auch das Erstellen von Modellen mit der DocumentModelAdministrationClient Klasse. Beim Erstellen eines Modells aus bezeichneten Trainingsdaten wird ein neues Modell erstellt, das mit Ihren eigenen Dokumenten trainiert wird, und das resultierende Modell ist in der Lage, Werte aus den Strukturen dieser Dokumente zu erkennen. Der Modellerstellungsvorgang akzeptiert eine SAS-codierte URL für einen Azure Storage-Blobcontainer, der die Trainingsdokumente enthält. Die Infrastruktur des Document Intelligence-Diensts liest die Dateien im Container und erstellt ein Modell basierend auf ihrem Inhalt. Weitere Informationen zum Erstellen und Strukturieren eines Trainingsdatencontainers finden Sie in der Dokumentation des Document Intelligence-Diensts zum Erstellen eines Modells.

Während wir diese Methoden für die programmgesteuerte Modellerstellung bereitstellen, hat das Document Intelligence-Dienstteam eine interaktive Webanwendung, Document Intelligence Studio, erstellt, die das Erstellen und Verwalten von Modellen im Web ermöglicht.

Das folgende Programm erstellt z. B. ein benutzerdefiniertes Dokumentmodell mit einer SAS-codierten URL für einen bereits vorhandenen Azure Storage-Container:

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

Benutzerdefinierte Klassifizierer werden auf ähnliche Weise mit der Methode und nicht beginBuildDocumentModelmit .beginBuildDocumentClassifier Weitere Informationen zum Erstellen eines benutzerdefinierten Klassifizierers finden Sie im Beispiel für einen Buildklassifizierer , da die Eingabetrainingsdaten in einem etwas anderen Format bereitgestellt werden. Informationen zum Erstellen eines Trainingsdatasets für einen benutzerdefinierten Klassifizierer finden Sie in der Dokumentation zum Document Intelligence-Dienst.

Verwalten von Modellen

DocumentModelAdministrationClient Bietet außerdem mehrere Methoden für den Zugriff auf und das Auflisten von Modellen. Im folgenden Beispiel wird gezeigt, wie Sie die Modelle in einer Ressource durchlaufen (dies umfasst sowohl benutzerdefinierte Modelle in der Ressource als auch vordefinierte Modelle, die für alle Ressourcen gelten), ein Modell nach ID abrufen und ein Modell löschen.

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

Ähnliche Methoden listDocumentClassifiers stehen getDocumentClassifier zum Auflisten und Abrufen von Informationen zu benutzerdefinierten Klassifizierern sowie deleteDocumentClassifier zum Löschen von benutzerdefinierten Klassifizierern zur Verfügung.

Problembehandlung

Hilfe zur Problembehandlung finden Sie im Handbuch zur Problembehandlung.

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf info. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie folgendes setLogLevelaufrufen@azure/logger:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Werfen Sie einen Blick auf das Beispielverzeichnis für detaillierte Codebeispiele, die zeigen, wie diese Bibliothek verwendet wird, einschließlich mehrerer Funktionen und Methoden, die im obigen Abschnitt "Beispiele" nicht gezeigt werden, z. B. das Kopieren und Erstellen von Modellen, das Auflisten von Modellverwaltungsvorgängen und das Löschen von Modellen.

Mitarbeit

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.