JavaScript용 Azure DocumentIntelligence(이전 FormRecognizer) REST 클라이언트 라이브러리 - 버전 1.0.0

아티클
12/21/2024

문서에서 콘텐츠, 레이아웃 및 구조적 데이터를 추출합니다.

이 라이브러리를 사용하려면 REST 클라이언트 문서 많이

참고: Form Recognizer가 문서 인텔리전스로 브랜드를 다시 지정했습니다. 마이그레이션 가이드를 확인하세요.

키 링크:

소스 코드
NPM(패키지)
API 참조 설명서
샘플
Changelog
Form Recognizer 마이그레이션 가이드

이 버전의 클라이언트 라이브러리는 기본적으로 서비스의 "2024-11-30" 버전으로 설정됩니다.

이 표에서는 SDK 버전과 지원되는 서비스 API 버전 간의 관계를 보여 줍니다.

SDK 버전	지원되는 API 버전의 서비스
1.0.0	2024-11-30

"prebuilt-businessCard" 및 "prebuilt-document"같은 사용 중지된 모델에 대한 이전 서비스 API 버전을 통해 이전 @azure/ai-form-recognizer 라이브러리를 사용하세요. 자세한 내용은 Changelog참조하세요.

아래 표에서는 각 클라이언트와 지원되는 API 버전의 관계를 설명합니다.

서비스 API 버전	지원되는 클라이언트	패키지
2024-11-30	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` 버전 `1.0.0`
2023-07-31	DocumentAnalysisClient 및 DocumentModelAdministrationClient	`@azure/ai-form-recognizer` 버전 `^5.0.0`
2022-08-01	DocumentAnalysisClient 및 DocumentModelAdministrationClient	`@azure/ai-form-recognizer` 버전 `^4.0.0`

시작

현재 지원되는 환경

LTS 버전의 Node.js

필수 구성 요소

이 패키지를 사용하려면 Azure 구독 있어야 합니다.

`@azure-rest/ai-document-intelligence` 패키지 설치

npm사용하여 JavaScript용 Azure DocumentIntelligence(이전의FormRecognizer) REST 클라이언트 REST 클라이언트 라이브러리를 설치합니다.

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

`DocumentIntelligenceClient` 만들기 및 인증

AAD(Azure Active Directory) 토큰 자격 증명사용하려면 @azure/ID 라이브러리에서 가져온 원하는 자격 증명 유형의 인스턴스를 제공합니다.

AAD를 사용하여 인증하려면 먼저 npm 설치해야 @azure/identity

설치 후 사용할 @azure/identity자격 증명 유형을 선택할 수 있습니다. 예를 들어 DefaultAzureCredential 사용하여 클라이언트를 인증할 수 있습니다.

AAD 애플리케이션의 클라이언트 ID, 테넌트 ID 및 클라이언트 암호 값을 환경 변수로 설정합니다. AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

토큰 자격 증명 사용

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

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

API KEY 사용

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

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

문서 모델

미리 빌드된 레이아웃 분석(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" },
  });

미리 빌드된 레이아웃 분석(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" },
  });

초기 응답에서 폴러를 계속 만듭니다.

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

일괄 처리 분석

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 콘텐츠 형식

기본 일반 텍스트함께 Markdown 콘텐츠 형식의 출력을 지원합니다. 지금은 "미리 빌드된 레이아웃"에 대해서만 지원됩니다. Markdown 콘텐츠 형식은 채팅 또는 자동화 사용 시나리오에서 LLM 사용에 더 친숙한 형식으로 간주됩니다.

서비스는 Markdown 형식에 대한 GFM 사양(GitHub Flavored Markdown)을 따릅니다. 또한 결과 콘텐츠 형식을 나타내는 값이 "text" 또는 "markdown"인 새 contentFormat 속성을 소개합니다.

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

쿼리 필드

이 기능 플래그를 지정하면 서비스에서 queryFields 쿼리 매개 변수를 통해 지정된 필드의 값을 추가로 추출하여 모델에 정의된 기존 필드를 대체(fallback)로 보완합니다.

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

분할 옵션

이전 @azure/ai-form-recognizer 라이브러리에서 지원되는 이전 API 버전에서 문서 분할 및 분류 작업("/documentClassifiers/{classifierId}:analyze")은 항상 입력 파일을 여러 문서로 분할하려고 했습니다.

더 넓은 시나리오 집합을 사용하도록 설정하기 위해 서비스는 새로운 "2023-10-31-preview" 서비스 버전으로 "분할" 쿼리 매개 변수를 도입합니다. 지원되는 값은 다음과 같습니다.

split: "auto"

서비스가 분할할 위치를 결정하도록 합니다.
split: "none"

전체 파일은 단일 문서로 처리됩니다. 분할이 수행되지 않습니다.
split: "perPage"

각 페이지는 별도의 문서로 처리됩니다. 각 빈 페이지는 자체 문서로 유지됩니다.

문서 분류자 #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'
//  }

문서 분석에서 생성된 PDF 출력 가져오기

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

문서 분석에서 지정된 그림의 생성된 잘린 이미지 가져오기

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

정보 가져오기

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

문서 모델 나열

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

문제 해결

로깅

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 @azure/loggersetLogLevel 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

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

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서확인할 수 있습니다.

다음을 통해 공유

JavaScript용 Azure DocumentIntelligence(이전 FormRecognizer) REST 클라이언트 라이브러리 - 버전 1.0.0

시작

현재 지원되는 환경

필수 구성 요소

`@azure-rest/ai-document-intelligence` 패키지 설치

`DocumentIntelligenceClient` 만들기 및 인증

토큰 자격 증명 사용

API KEY 사용

문서 모델

미리 빌드된 레이아웃 분석(urlSource)

미리 빌드된 레이아웃 분석(base64Source)

일괄 처리 분석

Markdown 콘텐츠 형식

쿼리 필드

분할 옵션

문서 분류자 #Build

문서 분석에서 생성된 PDF 출력 가져오기

문서 분석에서 지정된 그림의 생성된 잘린 이미지 가져오기

정보 가져오기

문서 모델 나열

문제 해결

로깅

추가 리소스

다음을 통해 공유

JavaScript용 Azure DocumentIntelligence(이전 FormRecognizer) REST 클라이언트 라이브러리 - 버전 1.0.0

시작

현재 지원되는 환경

필수 구성 요소

@azure-rest/ai-document-intelligence 패키지 설치

DocumentIntelligenceClient 만들기 및 인증

토큰 자격 증명 사용

API KEY 사용

문서 모델

미리 빌드된 레이아웃 분석(urlSource)

미리 빌드된 레이아웃 분석(base64Source)

일괄 처리 분석

Markdown 콘텐츠 형식

쿼리 필드

분할 옵션

문서 분류자 #Build

문서 분석에서 생성된 PDF 출력 가져오기

문서 분석에서 지정된 그림의 생성된 잘린 이미지 가져오기

정보 가져오기

문서 모델 나열

문제 해결

로깅

추가 리소스

`@azure-rest/ai-document-intelligence` 패키지 설치

`DocumentIntelligenceClient` 만들기 및 인증