Freigeben über

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

  • Artikel

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 Standard Features:

  • Layout: Extrahieren Sie Text, Tabellenstrukturen und Auswahlmarkierungen zusammen mit ihren Begrenzungsbereichskoordinaten aus Dokumenten.
  • Dokument: Analysieren von Entitäten, Schlüssel-Wert-Paaren, Tabellen und Auswahlzeichen aus Dokumenten mithilfe des allgemeinen vordefinierten Dokumentmodells.
  • Lesen: Lesen Sie zusätzlich zu Textsprachinformationen Informationen zu Textelementen, z. B. Seitenwörter und Zeilen.
  • Vordefiniertes Analysemodell: Analysieren von Daten aus bestimmten Arten gängiger Dokumente (z. B. Belege, Rechnungen, Visitenkarten oder Identitätsdokumente) 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.
  • Klassifizierer: Erstellen Sie benutzerdefinierte Klassifizierer, um Dokumente in vordefinierte Klassen zu kategorisieren.

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

Hinweis

Der Document Intelligence-Dienst wurde früher als "Azure Formularerkennung" bezeichnet. Diese Dienste sind ein und dasselbe, 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 des Schreibens ist die Umbenennung von 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 Paket @azure/ai-form-recognizer.

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

npm install @azure/ai-form-recognizer

Erste Schritte

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

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Erstellen einer Formularerkennungsressource

Hinweis: Zum Zeitpunkt des Schreibens bezieht sich der Azure-Portal weiterhin auf die Ressource als "Formularerkennung"-Ressource. In Zukunft kann dies in eine "Document Intelligence"-Ressource aktualisiert werden. In der folgenden Dokumentation wird vorerst der Name "Formularerkennung" verwendet.

Document Intelligence unterstützt sowohl den Zugriff mit mehreren Diensten als auch den Einzeldienst. Erstellen Sie eine Cognitive Services-Ressource, wenn Sie planen, über einen einzelnen Endpunkt bzw. Schlüssel auf mehrere Cognitive Services-Instanzen zuzugreifen. 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 Formularerkennung-Ressource 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 <your-resource-group-name> Sie 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 zu interagieren, müssen Sie entweder einen DocumentAnalysisClient oder einen DocumentModelAdministrationClientauswählen und eine instance dieses Typs erstellen. In den folgenden Beispielen wird verwendet DocumentAnalysisClient. Um einen Client instance für den Zugriff auf die Document Intelligence-API zu erstellen, benötigen Sie die endpoint ihrer Formularerkennung-Ressource und eine credential. Die Clients können entweder einen AzureKeyCredential mit einem API-Schlüssel Ihrer Ressource oder eine TokenCredential verwenden, die Azure Active Directory RBAC verwendet, um den Client zu autorisieren.

Sie finden den Endpunkt für Ihre Formularerkennung Ressource entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Ausschnitts:

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

Verwenden eines API-Schlüssels

Verwenden Sie das Azure-Portal, um zu Ihrer Formularerkennung Ressource zu navigieren und 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 -Endpunkt verfügen, können Sie ihn wie folgt verwenden:

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

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

Verwenden von Azure Active Directory

Die API-Schlüsselautorisierung wird in den meisten Beispielen verwendet, Aber Sie können den Client auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothek authentifizieren. Um den unten gezeigten Anbieter DefaultAzureCredential oder andere Anbieter von Anmeldeinformationen 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 den Zugriff auf den Dienst gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen (Hinweis: Andere Rollen wie erteilen "Owner" nicht die erforderlichen Berechtigungen, reichen nur "Cognitive Services User" aus, um die Beispiele und den Beispielcode auszuführen).

Legen Sie die Werte der Client-ID, Mandanten-ID und geheimen Clientschlüssel der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

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

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

Wichtige Begriffe

DocumentAnalysisClient

DocumentAnalysisClient stellt Vorgänge zum Analysieren von Eingabedokumenten mit benutzerdefinierten und vordefinierten Modellen bereit. Es verfügt über drei Methoden:

  • beginAnalyzeDocument, das Daten aus einem Datenstrom der Eingabedokumentdatei mithilfe eines benutzerdefinierten oder vordefinierten Modells extrahiert, das durch die Modell-ID angegeben wird. Informationen zu den vordefinierten Modellen, die in allen Ressourcen und ihren Modell-IDs/Ausgaben unterstützt werden, finden Sie in der Dokumentation der Modelle des Diensts.
  • 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 zum Erstellen eines neuen Dokumentmodells aus Ihrem eigenen Trainingsdataset. Das erstellte Modell kann Felder nach 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 zum Anwenden von Bezeichnungen auf ein Trainingsdataset finden Sie in der Dokumentation des Diensts zum Erstellen eines Trainingsdatasets .
  • beginComposeDocumentModel startet einen Vorgang, um mehrere Modelle in einem einzelnen Modell zusammenzustellen. Bei Verwendung für die benutzerdefinierte Formularerkennung 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 erfordert eine CopyAuthorization aus der Zielressource, die mit der getCopyAuthorization -Methode generiert werden kann.
  • getResourceDetails ruft Informationen zu den Grenzwerten der Ressource ab, z. B. die Anzahl benutzerdefinierter Modelle und die maximale Anzahl von Modellen, die die Ressource unterstützen kann.
  • getDocumentModel, listDocumentModelsund deleteDocumentModel aktivieren Sie die Verwaltung von Modellen in der Ressource.
  • getOperationund listOperations aktivieren Sie das Anzeigen der status von Modellerstellungsvorgängen, auch der laufenden oder fehlgeschlagenen Vorgänge. Vorgänge werden 24 Stunden lang beibehalten.

Beachten Sie, dass Modelle auch mithilfe der grafischen Benutzeroberfläche des Document Intelligence-Diensts erstellt werden können: Document Intelligence Studio.

Beispielcodeausschnitte, die die Verwendung von DocumentModelAdministrationClient veranschaulichen, um ein Modell zu erstellen, finden Sie unten im Abschnitt "Modell erstellen".

Zeitintensive Vorgänge

Vorgänge mit langer Ausführung (Long Running Operations, LROs) sind Vorgänge, die aus einer anfänglichen Anforderung bestehen, die an den Dienst zum Starten eines Vorgangs gesendet wird, gefolgt von der Abfrage nach einem Ergebnis in einem bestimmten Intervall, um zu ermitteln, ob der Vorgang abgeschlossen wurde und ob er fehlgeschlagen oder erfolgreich war. Letztendlich schlägt die LRO entweder mit einem Fehler fehl oder erzeugt ein Ergebnis.

In Azure AI Document Intelligence sind Vorgänge zum Erstellen von Modellen (einschließlich Kopieren und Komponieren 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 -Methode für den pollUntilDone von der begin<operation-name> -Methode zurückgegebenen Poller aufruft und wartet. Beispielcodeausschnitte werden bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungsdauer 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

Die beginAnalyzeDocument Methode kann Felder und Tabellendaten aus Dokumenten extrahieren. Die Analyse kann entweder ein benutzerdefiniertes Modell verwenden, das mit Ihren eigenen Daten trainiert wurde, oder ein vom Dienst bereitgestelltes vordefiniertes Modell (siehe Verwenden vordefinierter Modelle unten). Ein benutzerdefiniertes Modell ist auf Ihre eigenen Dokumente zugeschnitten, sodass es nur mit Dokumenten mit derselben Struktur wie einer der Dokumenttypen im Modell verwendet werden sollte (es kann mehrere geben, z. B. in einem zusammengesetzten Modell).

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

Analysieren eines Dokuments über eine URL

Alternativ zum Bereitstellen eines lesbaren Streams kann stattdessen mithilfe der beginAnalyzeDocumentFromUrl -Methode eine öffentlich zugängliche URL bereitgestellt werden. "Öffentlich zugänglich" bedeutet, dass URL-Quellen über die Infrastruktur des Diensts zugänglich sein müssen (d. h. 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 vordefinierter Dokumentmodelle

Die beginAnalyzeDocument -Methode unterstützt auch das Extrahieren von Feldern aus bestimmten Arten von allgemeinen Dokumenten wie Quittungen, Rechnungen, Visitenkarten, Identitätsdokumenten und mehr mithilfe vordefinierter Modelle, die vom Document Intelligence-Dienst bereitgestellt werden. Die vordefinierten Modelle können entweder als Modell-ID-Zeichenfolgen (identisch mit benutzerdefinierten Dokumentmodellen – siehe abschnitt mit den anderen vordefinierten Modellen unten) oder mithilfe eines DocumentModel -Objekts 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 er wird konvertiert, um JavaScript-Namenskonventionen zu verwenden.

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

Da der Standard Vorteil der DocumentModel-basierten Analyse stärkere TypeScript-Typeinschränkungen sind, wird das folgende Beispiel in TypeScript mithilfe der ECMAScript-Modulsyntax geschrieben:

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

Alternativ kann, wie oben erwähnt, anstelle von PrebuiltReceiptModelverwendet werden, wodurch der stärkere Rückgabetyp erzeugt wird, die Modell-ID des vordefinierten Belegs ("vordefinierter Beleg") verwendet werden, aber die Dokumentfelder werden in TypeScript nicht stark typisiert, und die Feldnamen befinden sich in der Regel in "PascalCase" anstelle von "camelCase".

Andere vordefinierte Modelle

Sie sind nicht auf Belege beschränkt! Es gibt einige vordefinierte Modelle, aus denen Sie wählen können, wobei weitere auf dem Weg sind. Jedes vordefinierte Modell verfügt über einen eigenen Satz unterstützter Felder:

  • Belege, die (wie oben) oder die vordefinierte Belegmodell-ID "prebuilt-receipt"verwenden PrebuiltReceiptModel .
  • Visitenkarten mit PrebuiltBusinessCardModel oder deren Modell-ID "prebuilt-businessCard".
  • Rechnungen mit PrebuiltInvoiceModel oder deren Modell-ID "prebuilt-invoice".
  • Identitätsdokumente (z. B. Führerscheine und Pässe) mit PrebuiltIdDocumentModel oder deren Modell-ID "prebuilt-idDocument".
  • W2 Steuerformulare (USA), mit PrebuiltTaxUsW2Model oder deren Modell-ID "prebuilt-tax.us.w2".
  • Krankenversicherungskarten (USA), mit [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] oder ihrer 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 Feldschemas haben und daher nicht erzeugen documents. Sie lauten wie folgt:

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 mit der -Methode (durch die getDocumentModel Modell-IDs) von und der Untersuchung des DocumentModelAdministrationClientdocTypes Felds im Ergebnis zugegriffen werden.

Verwenden des vordefinierten Layouts

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 sowie deren Begrenzungsbereiche und Spannen innerhalb des Textinhalts der Eingabedokumente. Wir stellen eine stark typisierte DocumentModel instance namens bereitPrebuiltLayoutModel, die dieses Modell aufruft, oder wie immer kann seine Modell-ID "prebuilt-layout" direkt verwendet werden.

Da der Standard Vorteil der DocumentModel-basierten Analyse stärkere TypeScript-Typeinschränkungen sind, wird das folgende Beispiel in TypeScript mithilfe der ECMAScript-Modulsyntax geschrieben:

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

Verwenden des "document"-Vordefinierten

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

Da der Standard Vorteil der DocumentModel-basierten Analyse stärkere TypeScript-Typeinschränkungen sind, wird das folgende Beispiel in TypeScript mithilfe der ECMAScript-Modulsyntax geschrieben:

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

Verwenden des "Read"-Vorbaus

Das "prebuilt-read" Modell extrahiert Textinformationen in einem Dokument, z. B. Wörter und Absätze, und analysiert die Sprache und den Schreibstil (z. B. handschriftlich im Vergleich zum Typsatz) dieses Texts. Wir stellen eine stark typisierte DocumentModel instance namens bereitPrebuiltReadModel, die dieses Modell aufruft, oder wie immer kann seine Modell-ID "prebuilt-read" direkt verwendet werden.

Da der Standard Vorteil der DocumentModel-basierten Analyse stärkere TypeScript-Typeinschränkungen sind, wird das folgende Beispiel in TypeScript mithilfe der ECMAScript-Modulsyntax geschrieben:

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

Klassifizieren eines Dokuments

Der Document Intelligence-Dienst unterstützt benutzerdefinierte Dokumentklassifizierer, die Dokumente basierend auf einem Trainingsdataset in eine Reihe vordefinierter Kategorien klassifizieren können. Dokumente können mithilfe der -Methode von mit einem benutzerdefinierten Klassifizierer beginClassifyDocumentDocumentAnalysisClientklassifiziert werden. Wie beginAnalyzeDocument oben akzeptiert diese Methode eine Datei oder einen Stream, der das zu klassifizierende Dokument enthält, und verfügt über eine beginClassifyDocumentFromUrl Entsprechung, die stattdessen eine öffentlich zugängliche URL zu einem Dokument akzeptiert.

Im folgenden Beispiel wird gezeigt, wie Sie ein Dokument mithilfe eines benutzerdefinierten Klassifizierers klassifizieren:

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

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

Erstellen eines Modells

Das SDK unterstützt auch das Erstellen von Modellen mithilfe der DocumentModelAdministrationClient -Klasse. Beim Erstellen eines Modells aus bezeichneten Trainingsdaten wird ein neues Modell erstellt, das für Ihre eigenen Dokumente trainiert wird, und das resultierende Modell kann Werte aus den Strukturen dieser Dokumente erkennen. Der Modellerstellungsvorgang akzeptiert eine SAS-codierte URL zu einem Azure Storage-Blobcontainer, der die Trainingsdokumente enthält. Die Infrastruktur des Document Intelligence-Diensts liest die Dateien im Container und erstellt basierend auf ihren Inhalten ein Modell. 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 mit dem Namen Document Intelligence Studio erstellt, die das Erstellen und Verwalten von Modellen im Web ermöglicht.

Das folgende Programm erstellt beispielsweise ein benutzerdefiniertes Dokumentmodell mithilfe einer SAS-codierten URL für einen bereits vorhandenen Azure Storage-Container:

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

Benutzerdefinierte Klassifizierer werden auf ähnliche Weise erstellt, indem die -Methode anstelle beginBuildDocumentModelvon beginBuildDocumentClassifier verwendet wird. Weitere Informationen zum Erstellen eines benutzerdefinierten Klassifizierers finden Sie im Buildklassifizierungsbeispiel , 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 stellt außerdem mehrere Methoden für den Zugriff auf und die Auflistung von Modellen bereit. Das folgende Beispiel zeigt, 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 gemeinsam sind), ein Modell nach ID abrufen und ein Modell löschen.

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

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

Problembehandlung

Hilfe bei der Problembehandlung finden Sie im Leitfaden zur Problembehandlung.

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Nächste Schritte

Sehen Sie sich das Beispielverzeichnis für detaillierte Codebeispiele an, die zeigen, wie Sie diese Bibliothek verwenden, einschließlich mehrerer Features und Methoden, die im Abschnitt "Beispiele" oben nicht angezeigt werden, z. B. Kopieren und Komponieren von Modellen, Auflisten von Modellverwaltungsvorgängen und Löschen von Modellen.

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe