Klientská knihovna REST Azure DocumentIntelligence (dříve FormRecognizer) pro JavaScript – verze 1.0.0

Článek
12/21/2024

Extrahuje obsah, rozložení a strukturovaná data z dokumentů.

Pokud chcete používat tuto knihovnu, spoléhat se na naši klientských dokumentů REST.

POZNÁMKA: Rozpoznávání formulářů bylo přejmenováno na Document Intelligence. Projděte si průvodce migrací z @azure/ai-form-recognizer do @azure-rest/ai-document-intelligence.

Klíčové odkazy:

zdrojového kódu
balíčku (NPM)
Referenční dokumentace k rozhraní API
ukázky
protokolu změn
Průvodce migrací z rozpoznávání formulářů

Tato verze klientské knihovny je ve výchozím nastavení "2024-11-30" verze služby.

Tato tabulka ukazuje vztah mezi verzemi sady SDK a podporovanými verzemi rozhraní API služby:

Verze sady SDK	Podporovaná verze služby API
1.0.0	2024-11-30

Pro vyřazené modely, jako jsou "prebuilt-businessCard" a "prebuilt-document", se prosím spolehněte na starší knihovnu @azure/ai-form-recognizer prostřednictvím starších verzí rozhraní API služby. Další informace naleznete v tématu protokolu změn.

Následující tabulka popisuje relaci jednotlivých klientů a podporovaných verzí rozhraní API:

Verze rozhraní API služby	Podporovaní klienti	Balíček
2024-11-30	DocumentIntelligenceClient	`1.0.0` verze `@azure-rest/ai-document-intelligence`
2023-07-31	DocumentAnalysisClient a DocumentModelAdministrationClient	`^5.0.0` verze `@azure/ai-form-recognizer`
2022-08-01	DocumentAnalysisClient a DocumentModelAdministrationClient	`^4.0.0` verze `@azure/ai-form-recognizer`

Začínáme

Aktuálně podporovaná prostředí

Verze LTS Node.js

Požadavky

Abyste mohli tento balíček používat, musíte mít předplatné Azure.

Instalace balíčku `@azure-rest/ai-document-intelligence`

Nainstalujte klientskou knihovnu REST REST pro Azure DocumentIntelligence(dříveFormRecognizer) pro JavaScript s npm:

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

Vytvoření a ověření `DocumentIntelligenceClient`

Pokud chcete použít přihlašovací údaje tokenu Azure Active Directory (AAD), zadejte instanci požadovaného typu přihlašovacích údajů získaného z knihovny @azure/identity.

Pokud se chcete ověřit pomocí AAD, musíte nejdřív npm nainstalovat @azure/identity

Po nastavení můžete z @azure/identity zvolit, jaký typ přihlašovacích údajů použít. Například DefaultAzureCredential lze použít k ověření klienta.

Nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Použití přihlašovacích údajů tokenu

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

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

Použití klíče rozhraní API

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

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

Modely dokumentů

Analýza předem připraveného rozložení (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" },
  });

Analýza předem připraveného rozložení (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" },
  });

Pokračovat v vytváření poller z počáteční odpovědi

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'
//   }
// }

Dávková analýza

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

Formát obsahu Markdownu

Podporuje výstup s formátem obsahu Markdownu spolu s výchozím prostým textem. Prozatím se to podporuje jenom u předem připravených rozložení. Formát obsahu Markdownu se považuje za popisnější formát pro spotřebu LLM ve scénáři použití chatu nebo automatizace.

Služba se řídí specifikací GFM (GitHub Flavored Markdown) pro formát Markdownu. Zavádí také novou contentFormat vlastnost s hodnotou "text" nebo "markdown", která označuje formát výsledného obsahu.

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

Pole dotazu

Pokud je zadán příznak této funkce, služba dále extrahuje hodnoty polí zadaných pomocí parametru dotazu queryFields, aby doplnila všechna existující pole definovaná modelem jako záložní.

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

Možnosti rozdělení

V předchozích verzích rozhraní API podporovaných starší knihovnou @azure/ai-form-recognizer se operace dělení a klasifikace dokumentů ("/documentClassifiers/{classifierId}:analyze") vždy pokusila rozdělit vstupní soubor do více dokumentů.

Aby služba umožnila širší sadu scénářů, zavádí parametr dotazu "split" s novou verzí služby "2023-10-31-preview". Podporují se následující hodnoty:

split: "auto"

Nechte službu určit, kde se má rozdělení rozdělit.
split: "none"

Celý soubor se považuje za jeden dokument. Neprovádí se žádné rozdělení.
split: "perPage"

Každá stránka se považuje za samostatný dokument. Každá prázdná stránka se uchovává jako vlastní dokument.

Klasifikátory dokumentů #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'
//  }

Získání vygenerovaného výstupu PDF z analýzy dokumentů

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

Získání vygenerovaného oříznutého obrázku zadaného obrázku z analýzy dokumentu

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

Získat informace

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

Výpis modelů dokumentů

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

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Sdílet prostřednictvím

Klientská knihovna REST Azure DocumentIntelligence (dříve FormRecognizer) pro JavaScript – verze 1.0.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku `@azure-rest/ai-document-intelligence`

Vytvoření a ověření `DocumentIntelligenceClient`

Použití přihlašovacích údajů tokenu

Použití klíče rozhraní API

Modely dokumentů

Analýza předem připraveného rozložení (urlSource)

Analýza předem připraveného rozložení (base64Source)

Dávková analýza

Formát obsahu Markdownu

Pole dotazu

Možnosti rozdělení

Klasifikátory dokumentů #Build

Získání vygenerovaného výstupu PDF z analýzy dokumentů

Získání vygenerovaného oříznutého obrázku zadaného obrázku z analýzy dokumentu

Získat informace

Výpis modelů dokumentů

Řešení problémů

Protokolování

Další materiály

Sdílet prostřednictvím

Klientská knihovna REST Azure DocumentIntelligence (dříve FormRecognizer) pro JavaScript – verze 1.0.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku @azure-rest/ai-document-intelligence

Vytvoření a ověření DocumentIntelligenceClient

Použití přihlašovacích údajů tokenu

Použití klíče rozhraní API

Modely dokumentů

Analýza předem připraveného rozložení (urlSource)

Analýza předem připraveného rozložení (base64Source)

Dávková analýza

Formát obsahu Markdownu

Pole dotazu

Možnosti rozdělení

Klasifikátory dokumentů #Build

Získání vygenerovaného výstupu PDF z analýzy dokumentů

Získání vygenerovaného oříznutého obrázku zadaného obrázku z analýzy dokumentu

Získat informace

Výpis modelů dokumentů

Řešení problémů

Protokolování

Další materiály

Instalace balíčku `@azure-rest/ai-document-intelligence`

Vytvoření a ověření `DocumentIntelligenceClient`