Biblioteka klienta REST usługi Azure DocumentIntelligence (dawniej FormRecognizer) dla języka JavaScript — wersja 1.0.0

Artykuł
12/22/2024

Wyodrębnia zawartość, układ i dane ustrukturyzowane z dokumentów.

w dużym stopniu polegaj na naszych dokumentacji klienta REST do korzystania z tej biblioteki

UWAGA: Rozpoznawanie formularzy zostało przemianowane na analizę dokumentów. Zapoznaj się z przewodnikiem migracji z @azure/ai-form-recognizer do @azure-rest/ai-document-intelligence.

Kluczowe linki:

kod źródłowy
pakietu (NPM)
Dokumentacja referencyjna interfejs u API
przykładów
dziennika zmian
przewodnik migracji z rozpoznawania formularzy

Ta wersja biblioteki klienta jest domyślnie ustawiona na "2024-11-30" wersji usługi.

W tej tabeli przedstawiono relację między wersjami zestawu SDK i obsługiwanymi wersjami interfejsu API usługi:

Wersja zestawu SDK	Obsługiwana wersja usługi interfejsu API
1.0.0	2024-11-30

Skorzystaj ze starszej biblioteki @azure/ai-form-recognizer za pośrednictwem starszych wersji interfejsu API usługi dla wycofanych modeli, takich jak "prebuilt-businessCard" i "prebuilt-document". Aby uzyskać więcej informacji, zobacz Changelog.

W poniższej tabeli opisano relację poszczególnych klientów i obsługiwanych wersji interfejsu API:

Wersja interfejsu API usługi	Obsługiwani klienci	Pakiet
2024-11-30	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` wersja `1.0.0`
2023-07-31	DocumentAnalysisClient i DocumentModelAdministrationClient	`@azure/ai-form-recognizer` wersja `^5.0.0`
2022-08-01	DocumentAnalysisClient i DocumentModelAdministrationClient	`@azure/ai-form-recognizer` wersja `^4.0.0`

Wprowadzenie

Obecnie obsługiwane środowiska

Wersje LTS Node.js

Warunki wstępne

Aby korzystać z tego pakietu, musisz mieć subskrypcji platformy Azure.

Instalowanie pakietu `@azure-rest/ai-document-intelligence`

Zainstaluj bibliotekę klienta REST klienta REST usługi Azure DocumentIntelligence(dawniejFormRecognizer) dla języka JavaScript przy użyciu npm:

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

Tworzenie i uwierzytelnianie `DocumentIntelligenceClient`

Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki @azure/tożsamości.

Aby uwierzytelnić się w usłudze AAD, musisz najpierw npm zainstalować @azure/identity

Po skonfigurowaniu możesz wybrać typ poświadczeń z do użycia. Na przykład do uwierzytelniania klienta można użyć DefaultAzureCredential.

Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i wpisu tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Używanie poświadczeń tokenu

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

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

Używanie klucza interfejsu API

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

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

Modele dokumentów

Analizowanie wstępnie utworzonego układu (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" },
  });

Analizowanie wstępnie utworzonego układu (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" },
  });

Kontynuuj tworzenie narzędzia poller na podstawie początkowej odpowiedzi

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

Analiza wsadowa

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

Format zawartości markdown

Obsługuje dane wyjściowe z formatem zawartości języka Markdown wraz z domyślnym tekstem . Na razie jest to obsługiwane tylko w przypadku "wstępnie utworzonego układu". Format zawartości języka Markdown jest uznawany za bardziej przyjazny dla użycia funkcji LLM w scenariuszu użycia czatu lub automatyzacji.

Usługa jest zgodna ze specyfikacją GFM (GitHub Flavored Markdown) dla formatu Markdown. Wprowadzono również nową właściwość contentFormat o wartości "text" lub "markdown", aby wskazać format zawartości wynikowej.

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

Pola zapytania

Po określeniu tej flagi funkcji usługa będzie dalej wyodrębniać wartości pól określonych za pośrednictwem parametru zapytania QueryFields, aby uzupełnić wszystkie istniejące pola zdefiniowane przez model jako rezerwowe.

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

Opcje podziału

W poprzednich wersjach interfejsu API obsługiwanych przez starszą bibliotekę @azure/ai-form-recognizer operacja dzielenia dokumentów i klasyfikacji ("/documentClassifiers/{classifierId}:analyze") zawsze próbowała podzielić plik wejściowy na wiele dokumentów.

Aby włączyć szerszy zestaw scenariuszy, usługa wprowadza parametr zapytania "split" z nową wersją usługi "2023-10-31-preview". Obsługiwane są następujące wartości:

split: "auto"

Pozwól usłudze określić, gdzie należy się podzielić.
split: "none"

Cały plik jest traktowany jako pojedynczy dokument. Nie jest wykonywane dzielenie.
split: "perPage"

Każda strona jest traktowana jako oddzielny dokument. Każda pusta strona jest przechowywana jako własny dokument.

Klasyfikatory dokumentów #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'
//  }

Pobieranie wygenerowanych danych wyjściowych pdf z analizy dokumentów

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

Pobieranie wygenerowanego przyciętego obrazu określonego rysunku z analizy dokumentów

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

Uzyskiwanie informacji

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

Wyświetlanie listy modeli dokumentów

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

Rozwiązywanie problemów

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Udostępnij za pośrednictwem

Biblioteka klienta REST usługi Azure DocumentIntelligence (dawniej FormRecognizer) dla języka JavaScript — wersja 1.0.0

Wprowadzenie

Obecnie obsługiwane środowiska

Warunki wstępne

Instalowanie pakietu `@azure-rest/ai-document-intelligence`

Tworzenie i uwierzytelnianie `DocumentIntelligenceClient`

Używanie poświadczeń tokenu

Używanie klucza interfejsu API

Modele dokumentów

Analizowanie wstępnie utworzonego układu (urlSource)

Analizowanie wstępnie utworzonego układu (base64Source)

Analiza wsadowa

Format zawartości markdown

Pola zapytania

Opcje podziału

Klasyfikatory dokumentów #Build

Pobieranie wygenerowanych danych wyjściowych pdf z analizy dokumentów

Pobieranie wygenerowanego przyciętego obrazu określonego rysunku z analizy dokumentów

Uzyskiwanie informacji

Wyświetlanie listy modeli dokumentów

Rozwiązywanie problemów

Wyrąb

Dodatkowe zasoby

Udostępnij za pośrednictwem

Biblioteka klienta REST usługi Azure DocumentIntelligence (dawniej FormRecognizer) dla języka JavaScript — wersja 1.0.0

Wprowadzenie

Obecnie obsługiwane środowiska

Warunki wstępne

Instalowanie pakietu @azure-rest/ai-document-intelligence

Tworzenie i uwierzytelnianie DocumentIntelligenceClient

Używanie poświadczeń tokenu

Używanie klucza interfejsu API

Modele dokumentów

Analizowanie wstępnie utworzonego układu (urlSource)

Analizowanie wstępnie utworzonego układu (base64Source)

Analiza wsadowa

Format zawartości markdown

Pola zapytania

Opcje podziału

Klasyfikatory dokumentów #Build

Pobieranie wygenerowanych danych wyjściowych pdf z analizy dokumentów

Pobieranie wygenerowanego przyciętego obrazu określonego rysunku z analizy dokumentów

Uzyskiwanie informacji

Wyświetlanie listy modeli dokumentów

Rozwiązywanie problemów

Wyrąb

Dodatkowe zasoby

Instalowanie pakietu `@azure-rest/ai-document-intelligence`

Tworzenie i uwierzytelnianie `DocumentIntelligenceClient`