Rest-Clientbibliothek für Azure DocumentIntelligence (früher FormRecognizer) für JavaScript – Version 1.0.0

Artikel
12/21/2024

Extrahiert Inhalte, Layout und strukturierte Daten aus Dokumenten.

Verlassen Sie sich auf unsere REST-Clientdokumente, um diese Bibliothek

HINWEIS: Die Formularerkennung wurde in Dokumentintelligenz umbenannt. Bitte überprüfen Sie den Migrationsleitfaden von @azure/ai-form-recognizer zu @azure-rest/ai-document-intelligence.

Wichtige Links:

Diese Version der Clientbibliothek ist standardmäßig auf die "2024-11-30" Version des Diensts festgelegt.

Diese Tabelle zeigt die Beziehung zwischen SDK-Versionen und unterstützten API-Versionen des Diensts:

SDK-Version	Unterstützte API-Version des Diensts
1.0.0	2024-11-30

Verlassen Sie sich auf die ältere @azure/ai-form-recognizer-Bibliothek über die älteren Dienst-API-Versionen für eingestellte Modelle, z. B. "prebuilt-businessCard" und "prebuilt-document". Weitere Informationen finden Sie unter Changelog.

Die folgende Tabelle beschreibt die Beziehung zwischen den einzelnen Clients und den unterstützten API-Versionen:

Dienst-API-Version	Unterstützte Clients	Paket
2024-11-30	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` Version `1.0.0`
2023-07-31	DocumentAnalysisClient und DocumentModelAdministrationClient	`@azure/ai-form-recognizer` Version `^5.0.0`
2022-08-01	DocumentAnalysisClient und DocumentModelAdministrationClient	`@azure/ai-form-recognizer` Version `^4.0.0`

Erste Schritte

Derzeit unterstützte Umgebungen

LTS-Versionen von Node.js

Voraussetzungen

Sie müssen über ein Azure-Abonnement verfügen,, um dieses Paket zu verwenden.

Installieren des `@azure-rest/ai-document-intelligence`-Pakets

Installieren Sie die REST-Client-REST-Clientbibliothek von Azure DocumentIntelligence(früherFormRecognizer) für JavaScript mit npm:

npm install @azure-rest/ai-document-intelligence

Erstellen und Authentifizieren einer `DocumentIntelligenceClient`

Um eine Azure Active Directory (AAD)-Tokenanmeldeinformationenzu verwenden, stellen Sie eine Instanz des gewünschten Anmeldeinformationstyps bereit, der aus der @azure/Identitätsbibliothek Bibliothek abgerufen wird.

Um sich bei AAD zu authentifizieren, müssen Sie zuerst npm installieren @azure/identity

Nach dem Setup können Sie auswählen, welche Art von Anmeldeinformationen von @azure/identity verwendet werden soll. Beispielsweise können DefaultAzureCredential- zum Authentifizieren des Clients verwendet werden.

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

Verwenden von Tokenanmeldeinformationen

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential()
);

Verwenden eines API-SCHLÜSSELs

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

Dokumentmodelle

Analysieren des vordefinierten Layouts (urlSource)

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { locale: "en-IN" },
  });

Analysieren des vordefinierten Layouts (base64Source)

import fs from "fs";
import path from "path";

const filePath = path.join(ASSET_PATH, "forms", "Invoice_1.pdf");
const base64Source = fs.readFileSync(filePath, { encoding: "base64" });
const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { locale: "en-IN" },
  });

Erstellen des Abrufers aus der ursprünglichen Antwort fortsetzen

import {
  getLongRunningPoller,
  AnalyzeResultOperationOutput,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = getLongRunningPoller(client, initialResponse);
const result = (await poller.pollUntilDone()).body as AnalyzeResultOperationOutput;
console.log(result);
// {
//   status: 'succeeded',
//   createdDateTime: '2023-11-10T13:31:31Z',
//   lastUpdatedDateTime: '2023-11-10T13:31:34Z',
//   analyzeResult: {
//     apiVersion: '2023-10-31-preview',
//     .
//     .
//     .
//     contentFormat: 'text'
//   }
// }

Batchanalyse

import { parseResultIdFromResponse, isUnexpected } from "@azure-rest/ai-document-intelligence";

// 1. Analyze a batch of documents
const initialResponse = await client
  .path("/documentModels/{modelId}:analyzeBatch", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      azureBlobSource: {
        containerUrl: batchTrainingFilesContainerUrl(),
      },
      resultContainerUrl: batchTrainingFilesResultContainerUrl(),
      resultPrefix: "result",
    },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const resultId = parseResultIdFromResponse(initialResponse);
console.log("resultId: ", resultId);

// (Optional) You can poll for the batch analysis result but be aware that a job may take unexpectedly long time, and polling could incur additional costs.
// const poller = getLongRunningPoller(client, initialResponse);
// await poller.pollUntilDone();

// 2. At a later time, you can retrieve the operation result using the resultId
const output = await client
  .path("/documentModels/{modelId}/analyzeResults/{resultId}", "prebuilt-layout", resultId)
  .get();
console.log(output);

Markdown-Inhaltsformat

Unterstützt die Ausgabe mit dem Markdown-Inhaltsformat zusammen mit dem standardmäßigen einfachen Text. Derzeit wird dies nur für "vordefiniertes Layout" unterstützt. Markdown-Inhaltsformat gilt als benutzerfreundlicher für die LLM-Nutzung in einem Chat- oder Automatisierungsverwendungsszenario.

Service folgt der GFM-Spezifikation (GitHub Flavored Markdown) für das Markdown-Format. Führt außerdem eine neue contentFormat- Eigenschaft mit dem Wert "text" oder "markdown" ein, um das Ergebnisinhaltsformat anzugeben.

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { outputContentFormat: "markdown" }, // <-- new query parameter
  });

Abfragefelder

Wenn dieses Feature-Flag angegeben wird, extrahiert der Dienst die Werte der über den Abfrageparameter "queryFields" angegebenen Felder weiter, um alle vorhandenen Felder zu ergänzen, die vom Modell als Fallback definiert sind.

await client.path("/documentModels/{modelId}:analyze", "prebuilt-layout").post({
  contentType: "application/json",
  body: { urlSource: "..." },
  queryParameters: {
    features: ["queryFields"],
    queryFields: ["NumberOfGuests", "StoreNumber"],
  }, // <-- new query parameter
});

Geteilte Optionen

In den vorherigen API-Versionen, die von der älteren @azure/ai-form-recognizer-Bibliothek unterstützt werden, versuchten Dokumentaufteilung und Klassifizierungsvorgang ("/documentClassifiers/{classifierId}:analyze") immer, die Eingabedatei in mehrere Dokumente aufzuteilen.

Um eine breitere Gruppe von Szenarien zu aktivieren, führt der Dienst einen "split"-Abfrageparameter mit der neuen Dienstversion "2023-10-31-preview" ein. Die folgenden Werte werden unterstützt:

split: "auto"

Lassen Sie den Dienst bestimmen, wo geteilt werden soll.
split: "none"

Die gesamte Datei wird als einzelnes Dokument behandelt. Es wird keine Aufteilung durchgeführt.
split: "perPage"

Jede Seite wird als separates Dokument behandelt. Jede leere Seite wird als eigenes Dokument beibehalten.

Dokumentklassifizierungen #Build

import {
  DocumentClassifierBuildOperationDetailsOutput,
  getLongRunningPoller,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

const containerSasUrl = (): string =>
  process.env["DOCUMENT_INTELLIGENCE_TRAINING_CONTAINER_SAS_URL"];
const initialResponse = await client.path("/documentClassifiers:build").post({
  body: {
    classifierId: `customClassifier${getRandomNumber()}`,
    description: "Custom classifier description",
    docTypes: {
      foo: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
      bar: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
    },
  },
});

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = getLongRunningPoller(client, initialResponse);
const response = (await poller.pollUntilDone())
  .body as DocumentClassifierBuildOperationDetailsOutput;
console.log(response);
//  {
//    operationId: '31466834048_f3ee629e-73fb-48ab-993b-1d55d73ca460',
//    kind: 'documentClassifierBuild',
//    status: 'succeeded',
//    .
//    .
//    result: {
//      classifierId: 'customClassifier10978',
//      createdDateTime: '2023-11-09T12:45:56Z',
//      .
//      .
//      description: 'Custom classifier description'
//    },
//    apiVersion: '2023-10-31-preview'
//  }

Abrufen der generierten PDF-Ausgabe aus der Dokumentanalyse

const filePath = path.join(ASSET_PATH, "layout-pageobject.pdf");

const base64Source = await fs.readFile(filePath, { encoding: "base64" });

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-read")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { output: ["pdf"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse);

await poller.pollUntilDone();

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/pdf",
    "prebuilt-read",
    parseResultIdFromResponse(initialResponse)
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const pdfData = await streamToUint8Array(output.body);
fs.promises.writeFile(`./output.pdf`, pdfData);
// Or you can consume the NodeJS.ReadableStream directly

Abrufen des generierten zugeschnittenen Bilds der angegebenen Abbildung aus der Dokumentanalyse

const filePath = path.join(ASSET_PATH, "layout-pageobject.pdf");

const base64Source = fs.readFileSync(filePath, { encoding: "base64" });

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { output: ["figures"] },
  });

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}

const poller = getLongRunningPoller(client, initialResponse, { ...testPollingOptions });

const result = (await poller.pollUntilDone()).body as AnalyzeResultOperationOutput;
const figures = result.analyzeResult?.figures;
assert.isArray(figures);
assert.isNotEmpty(figures?.[0]);
const figureId = figures?.[0].id || "";
assert.isDefined(figureId);

const output = await client
  .path(
    "/documentModels/{modelId}/analyzeResults/{resultId}/figures/{figureId}",
    "prebuilt-layout",
    parseResultIdFromResponse(initialResponse),
    figureId
  )
  .get()
  .asNodeStream(); // output.body would be NodeJS.ReadableStream

if (output.status !== "200" || !output.body) {
  throw new Error("The response was unexpected, expected NodeJS.ReadableStream in the body.");
}

const imageData = await streamToUint8Array(output.body);
fs.promises.writeFile(`./figures/${figureId}.png`, imageData);
// Or you can consume the NodeJS.ReadableStream directly

Abrufen von Informationen

const response = await client.path("/info").get();
if (isUnexpected(response)) {
  throw response.body.error;
}
console.log(response.body.customDocumentModels.limit);
// 20000

Dokumentmodelle auflisten

import { paginate } from "@azure-rest/ai-document-intelligence";
const response = await client.path("/documentModels").get();
if (isUnexpected(response)) {
  throw response.body.error;
}

const modelsInAccount: string[] = [];
for await (const model of paginate(client, response)) {
  console.log(model.modelId);
}

Fehlerbehebung

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 infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

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

Freigeben über

Rest-Clientbibliothek für Azure DocumentIntelligence (früher FormRecognizer) für JavaScript – Version 1.0.0

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des `@azure-rest/ai-document-intelligence`-Pakets

Erstellen und Authentifizieren einer `DocumentIntelligenceClient`

Verwenden von Tokenanmeldeinformationen

Verwenden eines API-SCHLÜSSELs

Dokumentmodelle

Analysieren des vordefinierten Layouts (urlSource)

Analysieren des vordefinierten Layouts (base64Source)

Batchanalyse

Markdown-Inhaltsformat

Abfragefelder

Geteilte Optionen

Dokumentklassifizierungen #Build

Abrufen der generierten PDF-Ausgabe aus der Dokumentanalyse

Abrufen des generierten zugeschnittenen Bilds der angegebenen Abbildung aus der Dokumentanalyse

Abrufen von Informationen

Dokumentmodelle auflisten

Fehlerbehebung

Protokollierung

Zusätzliche Ressourcen

Freigeben über

Rest-Clientbibliothek für Azure DocumentIntelligence (früher FormRecognizer) für JavaScript – Version 1.0.0

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des @azure-rest/ai-document-intelligence-Pakets

Erstellen und Authentifizieren einer DocumentIntelligenceClient

Verwenden von Tokenanmeldeinformationen

Verwenden eines API-SCHLÜSSELs

Dokumentmodelle

Analysieren des vordefinierten Layouts (urlSource)

Analysieren des vordefinierten Layouts (base64Source)

Batchanalyse

Markdown-Inhaltsformat

Abfragefelder

Geteilte Optionen

Dokumentklassifizierungen #Build

Abrufen der generierten PDF-Ausgabe aus der Dokumentanalyse

Abrufen des generierten zugeschnittenen Bilds der angegebenen Abbildung aus der Dokumentanalyse

Abrufen von Informationen

Dokumentmodelle auflisten

Fehlerbehebung

Protokollierung

Zusätzliche Ressourcen

Installieren des `@azure-rest/ai-document-intelligence`-Pakets

Erstellen und Authentifizieren einer `DocumentIntelligenceClient`