JavaScript 用 Azure AI ドキュメントインテリジェンスクライアントライブラリ - バージョン 5.0.0

[アーティクル]
08/16/2023

Azure AI ドキュメントインテリジェンスは、機械学習を使用してドキュメントのテキストと構造化データを分析するクラウドサービスです。これには、次のメイン機能が含まれています。

レイアウト - テキスト、テーブル構造、選択マーク、および境界領域座標をドキュメントから抽出します。
ドキュメント - 一般的な事前構築済みドキュメントモデルを使用して、ドキュメントのエンティティ、キーと値のペア、テーブル、および選択マークを分析します。
読み取り - テキスト言語情報に加えて、ページの単語や行など、テキスト要素に関する情報を読み取ります。
事前構築済み - 事前構築済みモデルを使用して、特定の種類の一般的なドキュメント (領収書、請求書、名刺、ID ドキュメントなど) のデータを分析します。
カスタム - テキスト、フィールド値、選択マーク、およびテーブルデータをドキュメントから抽出するカスタムモデルを構築します。カスタムモデルは独自のデータを使用して構築されるため、ドキュメントに合わせて調整されます。
分類子 - ドキュメントを定義済みのクラスに分類するカスタム分類子を構築します。

ソースコード | パッケージ (NPM) | API リファレンスドキュメント | 製品ドキュメント | サンプル

注意

ドキュメントインテリジェンスサービスは、以前は "Azure Form Recognizer" と呼れていました。これらのサービスは同じであり、@azure/ai-form-recognizerJavaScript 用のパッケージは Azure AI ドキュメントインテリジェンスサービス用の Azure SDK パッケージです。執筆時点では、Azure Form Recognizerから Azure AI ドキュメントインテリジェンスへの名前変更が進行中であるため、場合によっては"Form Recognizer" と "ドキュメントインテリジェンス" が同じ意味で使用される場合があります。

`@azure/ai-form-recognizer` パッケージのインストール

を使用して JavaScript 用の Azure ドキュメントインテリジェンスクライアントライブラリを npmインストールします。

npm install @azure/ai-form-recognizer

はじめに

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

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、Microsoft のサポートポリシーを参照してください。

前提条件

Azure サブスクリプション
Cognitive Services または Form Recognizer リソース。リソースを作成する必要がある場合は、 Azure Portal または Azure CLI を使用できます。

Form Recognizer リソースを作成する

注: 書き込み時に、Azure portalはリソースを "Form Recognizer" リソースとして引き続き参照します。今後、これは "ドキュメントインテリジェンス" リソースに更新される可能性があります。ここでは、次のドキュメントで "Form Recognizer" 名を使用しています。

ドキュメントインテリジェンスでは、マルチサービスアクセスとシングルサービスアクセスの両方がサポートされます。 1 つのエンドポイント/キーで複数の Cognitive Services にアクセスする予定の場合は、Cognitive Services リソースを作成します。 Form Recognizer アクセスのみの場合は、Form Recognizer リソースを作成します。

を使用してリソースを作成できます。

オプション 1:Azure Portal

オプション 2:Azure CLI。

CLI を使用してForm Recognizer リソースを作成する方法の例を次に示します。

# 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

Azure CLI を使用する場合は、と <your-resource-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

az cognitiveservices account create --kind FormRecognizer --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

クライアントを作成して認証する

ドキュメントインテリジェンスサービスを操作するには、または DocumentModelAdministrationClientのいずれかをDocumentAnalysisClient選択し、この型のインスタンスを作成する必要があります。次の例では、を使用 DocumentAnalysisClientします。ドキュメントインテリジェンス API にアクセスするためのクライアントインスタンスを作成するには、Form Recognizer リソースのと credentialが必要endpointです。クライアントは、リソースの API キーと共にを AzureKeyCredential 使用するか TokenCredential 、Azure Active Directory RBAC を使用してクライアントを承認するを使用できます。

Form Recognizer リソースのエンドポイントは、Azure Portal または以下の Azure CLI スニペットを使用して確認できます。

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

API キーを使用する

Azure Portal を使用してForm Recognizer リソースを参照し、API キーを取得するか、次の Azure CLI スニペットを使用します。

メモ： API キーは、"サブスクリプションキー" または "サブスクリプション API キー" と呼ばれる場合があります。

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

API キーとエンドポイントを取得したら、次のように使用できます。

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

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

Azure Active Directory を使用する

API キーの承認はほとんどの例で使用されますが、Azure Id ライブラリを使用して Azure Active Directory でクライアントを認証することもできます。以下に示す DefaultAzureCredential プロバイダーまたは Azure SDK で提供されている他の資格情報プロバイダーを使用するには、パッケージを @azure/identity インストールしてください。

npm install @azure/identity

サービスプリンシパルを使用して認証するには、 AAD アプリケーションを登録し、サービスプリンシパルにロールを "Cognitive Services User" 割り当ててサービスへのアクセス権を付与する必要もあります (注: などの "Owner" 他のロールは必要なアクセス許可を付与せず、例とサンプルコードを実行するだけで "Cognitive Services User" 十分です)。

AAD アプリケーションのクライアント ID、テナント ID、およびクライアントシークレットの値を、環境変数 AZURE_CLIENT_IDAZURE_TENANT_ID、、AZURE_CLIENT_SECRET、として設定します。

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

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

主要な概念

`DocumentAnalysisClient`

DocumentAnalysisClient には、カスタムモデルと事前構築済みモデルを使用して入力ドキュメントを分析するための操作が用意されています。これには、次の 3 つの方法があります。

beginAnalyzeDocument: モデル ID によって指定されたカスタムモデルまたは事前構築済みモデルを使用して、入力ドキュメントファイルストリームからデータを抽出します。すべてのリソースでサポートされている事前構築済みモデルとそのモデル ID/出力については、モデルのサービスのドキュメントを参照してください。
beginAnalyzeDocumentFromUrlはと同じ関数 beginAnalyzeDocumentを実行しますが、ファイルストリームではなく、パブリックにアクセス可能なファイルの URL を送信します。

`DocumentModelAdministrationClient`

DocumentModelAdministrationClient は、リソース内のモデルの管理 (作成、読み取り、一覧表示、および削除) のための操作を提供します。

beginBuildDocumentModel は、独自のトレーニングデータセットから新しいドキュメントモデルを作成する操作を開始します。作成されたモデルでは、カスタムスキーマに従ってフィールドを抽出できます。トレーニングデータは、Azure Storage コンテナーに配置され、特定の規則に従って整理されることが想定されています。トレーニングデータセットにラベルを適用する方法の詳細については、トレーニングデータセットの作成に関するサービスのドキュメントを参照してください。
beginComposeDocumentModel は、複数のモデルを 1 つのモデルに作成する操作を開始します。カスタムフォーム認識に使用する場合、新しい構成済みモデルは、最初に入力ドキュメントの分類を実行して、どのサブモデルが最も適切かを判断します。
beginCopyModelTo は、あるリソースから別のリソース (または同じリソースに) カスタムモデルをコピーする操作を開始します。ターゲットリソースのが CopyAuthorization 必要です。これは、メソッドを getCopyAuthorization 使用して生成できます。
getResourceDetails は、カスタムモデルの数や、リソースでサポートできるモデルの最大数など、リソースの制限に関する情報を取得します。
getDocumentModel、 listDocumentModels、およびを使用して deleteDocumentModel 、リソース内のモデルの管理を有効にします。
getOperation とを使用すると listOperations 、進行中の操作や失敗した操作であっても、モデル作成操作の状態を表示できます。操作は 24 時間保持されます。

ドキュメントインテリジェンスサービスのグラフィカルユーザーインターフェイスである Document Intelligence Studio を使用してモデルを作成することもできます。

を使用して DocumentModelAdministrationClient モデルを構築する方法を示すサンプルコードスニペットについては、「モデルのビルド」の例セクションを参照してください。

長時間にわたって実行される操作

実行時間の長い操作 (LRO) は、操作を開始するためにサービスに送信された最初の要求で構成される操作です。その後、一定の間隔で結果をポーリングして、操作が完了したかどうか、および操作が失敗したか成功したかを判断します。最終的には、LRO はエラーで失敗するか、結果を生成します。

Azure AI ドキュメントインテリジェンスでは、モデルを作成する操作 (モデルのコピーと作成を含む) と分析/データ抽出操作は、LRO です。 SDK クライアントは、オブジェクトを返Promise<PollerLike>す非同期begin<operation-name>メソッドを提供します。オブジェクトはPollerLike、サービスのインフラストラクチャで非同期的に実行される操作を表し、プログラムはメソッドから返されたポーリングツールでメソッドを呼び出して待機することで、操作の完了をbegin<operation-name>待機pollUntilDoneできます。次のセクションで実行時間の長い操作を使用する方法を示すサンプルコードスニペットが提供されています。

例

次のセクションでは、ドキュメントインテリジェンスクライアントライブラリで使用される一般的なパターンを示す JavaScript コードスニペットをいくつか示します。

モデル ID を使用してドキュメントを分析する
事前構築済みのドキュメントモデルを使用する
事前構築済みの "レイアウト" を使用する
事前構築済みの "ドキュメント" を使用する
事前構築済みの "読み取り" を使用する
モデルのビルド
モデルを管理する

モデル ID を使用してドキュメントを分析する

メソッドは beginAnalyzeDocument 、ドキュメントからフィールドとテーブルデータを抽出できます。分析では、カスタムモデル、独自のデータでトレーニングされたモデル、またはサービスによって提供される事前構築済みモデルを使用できます (以下の「 事前構築済みモデルを使用 する」を参照)。カスタムモデルは独自のドキュメントに合わせて調整されるため、モデル内のドキュメントの種類の 1 つと同じ構造のドキュメントでのみ使用する必要があります (構成済みモデルなど、複数存在する場合があります)。

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

URL からドキュメントを分析する

読み取り可能なストリームを提供する代わりに、メソッドを使用して beginAnalyzeDocumentFromUrl パブリックにアクセス可能な URL を指定できます。 "パブリックにアクセス可能" とは、サービスのインフラストラクチャから URL ソースにアクセスできる必要があることを意味します (つまり、ヘッダーまたは証明書ベースのシークレットを使用するプライベートイントラネット URL、または URL は機能しません。ドキュメントインテリジェンスサービスは URL にアクセスできる必要があります)。ただし、URL 自体は、クエリパラメーターに SAS トークンを含む Azure Storage BLOB URL などのシークレットをエンコードできます。

事前構築済みのドキュメントモデルを使用する

このメソッドでは beginAnalyzeDocument 、ドキュメントインテリジェンスサービスによって提供される事前構築済みモデルを使用して、領収書、請求書、名刺、ID ドキュメントなど、特定の種類の一般的なドキュメントからフィールドを抽出することもできます。事前構築済みモデルは、モデル ID 文字列 (カスタムドキュメントモデルと同じですが、以下の 他の事前構築済みモデル のセクションを参照) またはオブジェクトを DocumentModel 使用して提供できます。を使用 DocumentModelする場合、Document Intelligence SDK for JavaScript は、モデルのスキーマに基づいて抽出された結果のドキュメントに対してはるかに強力な TypeScript 型を提供し、JavaScript の名前付け規則を使用するように変換されます。

DocumentModel現在のサービス API バージョン (2022-08-31) のサンプルオブジェクトは、samples ディレクトリにありますprebuilt。次の例では、そのディレクトリの [prebuilt-receipt.ts] ファイルからを使用PrebuiltReceiptModelします。

ベースの分析のメイン利点DocumentModelは TypeScript 型制約の方が強力であるため、次のサンプルは ECMAScript モジュール構文を使用して TypeScript で記述されています。

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

または、前述のように、より強力な戻り値の型を生成するを使用 PrebuiltReceiptModelする代わりに、事前構築済みのレシートのモデル ID ("事前構築済みレシート") を使用できますが、ドキュメントフィールドは TypeScript では厳密に型指定されず、フィールド名は一般に "camelCase" ではなく "PascalCase" になります。

その他の事前構築済みモデル

レシートに限りません! いくつかの事前構築済みモデルから選択できます。さらに多くのモデルが用意されています。各事前構築済みモデルには、サポートされているフィールドの独自のセットがあります。

(上記のように) または事前構築済みのレシートモデル ID を"prebuilt-receipt"使用PrebuiltReceiptModelしたレシート。
名刺、またはそのモデル ID を使用 PrebuiltBusinessCardModel します "prebuilt-businessCard"。
またはモデル ID "prebuilt-invoice"を使用したPrebuiltInvoiceModel請求書。
ID ドキュメント (運転免許証やパスポートなど)、またはモデル ID "prebuilt-idDocument"を使用PrebuiltIdDocumentModelします。
W2 税フォーム (米国)、またはそのモデル ID を"prebuilt-tax.us.w2"使用PrebuiltTaxUsW2Modelします。
健康保険カード (米国)、[][samples-prebuilt-healthinsurancecard.us] またはそのモデル ID を"prebuilt-healthInsuranceCard.us"使用PrebuiltHealthInsuranceCardUsModelします。

上記の各事前構築済みモデルでは documents 、(モデルのフィールドスキーマの抽出されたインスタンス) が生成されます。また、フィールドスキーマがないためにを生成 documentsしない 3 つの事前構築済みモデルもあります。これらは次のとおりです。

事前構築済みのレイアウトモデル (以下 の「事前構築済みのレイアウト」を使用 する) では、ページやテーブルなどの基本的なレイアウト (OCR) 要素に関する情報が抽出されます。
レイアウトモデルによって生成される情報にキーと値のペア (ラベル付き要素などのページ要素間の方向付き関連付け) を追加する、事前構築済みの一般ドキュメントモデル (以下の 「ドキュメント」を使用 する) を参照してください。
事前構築済みの読み取りモデル (以下 の「読み取り」を使用 する) では、ページの単語や行などのテキスト要素のみが抽出され、ドキュメントの言語に関する情報が抽出されます。

これらのすべてのモデルのフィールドについては、使用可能な事前構築済みモデルに関するサービスのドキュメントを参照してください。

すべての事前構築済みモデルのフィールドには、のメソッド (モデル ID によって) DocumentModelAdministrationClient を使用してgetDocumentModelプログラムでアクセスし、結果のフィールドをdocTypes検査することもできます。

事前構築済みの "レイアウト" を使用する

このモデルでは "prebuilt-layout" 、ページなどのドキュメントの基本的な要素 (テキストの単語/行と選択マークで構成される)、テーブル、およびビジュアルテキストスタイルと、その境界領域と入力ドキュメントのテキストコンテンツ内のスパンのみが抽出されます。このモデルを呼び出すという名前PrebuiltLayoutModelの厳密に型指定されたDocumentModelインスタンスを提供します。また、常にモデル ID を"prebuilt-layout"直接使用することもできます。

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

事前構築済みの "ドキュメント" を使用する

モデルは "prebuilt-document" 、レイアウト抽出メソッドによって生成されるプロパティに加えて、キーと値のペア (ラベル付きフィールドなどのページ要素間の方向付き関連付け) に関する情報を抽出します。この事前構築済み (一般的な) ドキュメントモデルは、ドキュメントインテリジェンスサービスの以前のイテレーションでラベル情報なしでトレーニングされたカスタムモデルと同様の機能を提供しますが、さまざまなドキュメントで動作する事前構築済みモデルとして提供されるようになりました。このモデルを呼び出すという名前PrebuiltDocumentModelの厳密に型指定されたDocumentModelインスタンスを提供します。また、常にモデル ID を"prebuilt-document"直接使用することもできます。

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

事前構築済みの "読み取り" を使用する

このモデルは "prebuilt-read" 、単語や段落などの文書内のテキスト情報を抽出し、そのテキストの言語と書き方 (手書きとタイプセットなど) を分析します。このモデルを呼び出すという名前PrebuiltReadModelの厳密に型指定されたDocumentModelインスタンスを提供します。また、常にモデル ID を"prebuilt-read"直接使用することもできます。

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

ドキュメントを分類する

ドキュメントインテリジェンスサービスでは、トレーニングデータセットに基づいてドキュメントを定義済みのカテゴリのセットに分類できるカスタムドキュメント分類子がサポートされています。ドキュメントは、のメソッドDocumentAnalysisClientを使用してカスタム分類子でbeginClassifyDocument分類できます。上記と同様 beginAnalyzeDocument に、このメソッドは、分類するドキュメントを含むファイルまたはストリームを受け入れ、代わりにパブリックにアクセス可能な URL をドキュメントに受け入れる対応するメソッドを持 beginClassifyDocumentFromUrl っています。

次の例は、カスタム分類子を使用してドキュメントを分類する方法を示しています。

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

カスタム分類子のトレーニングの詳細については、次のセクションの最後にある分類子トレーニングに関するセクションを参照してください。

モデルの構築

SDK では、クラスを使用した DocumentModelAdministrationClient モデルの作成もサポートされています。ラベル付きトレーニングデータからモデルを構築すると、独自のドキュメントでトレーニングされる新しいモデルが作成され、結果のモデルはそれらのドキュメントの構造から値を認識できるようになります。モデル構築操作では、トレーニングドキュメントを保持する Azure Storage BLOB コンテナーへの SAS エンコード URL を受け入れます。ドキュメントインテリジェンスサービスのインフラストラクチャは、コンテナー内のファイルを読み取り、その内容に基づいてモデルを作成します。トレーニングデータコンテナーを作成および構造化する方法の詳細については、ドキュメントインテリジェンスサービスのモデル構築に関するドキュメントを参照してください。

プログラムによるモデル作成用にこれらのメソッドを提供しますが、ドキュメントインテリジェンスサービスチームは、Web 上でモデルを作成および管理できる対話型 Web アプリケーション Document Intelligence Studio を作成しました。

たとえば、次のプログラムは、既存の Azure Storage コンテナーへの SAS エンコード URL を使用してカスタムドキュメントモデルを構築します。

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

カスタム分類子は、ではなく beginBuildDocumentModelメソッドを使用して同様のbeginBuildDocumentClassifier方法で構築されます。入力トレーニングデータは少し異なる形式で提供されるため、カスタム分類子の構築の詳細については、ビルド分類子のサンプルを参照してください。カスタム分類子のトレーニングデータセットの構築の詳細については、ドキュメントインテリジェンスサービスのドキュメントを参照してください。

モデルを管理する

DocumentModelAdministrationClient には、モデルにアクセスして一覧表示するためのいくつかの方法も用意されています。次の例は、リソース内のモデルを反復処理する方法を示しています (これには、リソース内のカスタムモデルと、すべてのリソースに共通の事前構築済みモデルの両方が含まれます)、ID でモデルを取得し、モデルを削除します。

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

同様の listDocumentClassifiers 方法と getDocumentClassifier は、カスタム分類子の削除に加えて deleteDocumentClassifier 、カスタム分類子に関する情報を一覧表示および取得するために使用できます。

トラブルシューティング

トラブルシューティングに関するサポートについては、トラブルシューティングガイドを参照してください。

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次の手順

モデルのコピーと作成、モデル管理操作の一覧表示、モデルの削除など、上記の「例」セクションに示されていないいくつかの機能とメソッドを含む、このライブラリの使用方法を示す詳細なコードサンプルについては、サンプルディレクトリを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数

次の方法で共有

JavaScript 用 Azure AI ドキュメントインテリジェンスクライアントライブラリ - バージョン 5.0.0

注意

`@azure/ai-form-recognizer` パッケージのインストール

はじめに

現在サポートされている環境

前提条件

Form Recognizer リソースを作成する

クライアントを作成して認証する

API キーを使用する

Azure Active Directory を使用する

主要な概念

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`

長時間にわたって実行される操作

例

モデル ID を使用してドキュメントを分析する

URL からドキュメントを分析する

事前構築済みのドキュメントモデルを使用する

その他の事前構築済みモデル

事前構築済みの "レイアウト" を使用する

事前構築済みの "ドキュメント" を使用する

事前構築済みの "読み取り" を使用する

ドキュメントを分類する

モデルの構築

モデルを管理する

トラブルシューティング

ログの記録

次の手順

共同作成

その他のリソース

次の方法で共有

JavaScript 用 Azure AI ドキュメント インテリジェンス クライアント ライブラリ - バージョン 5.0.0

注意

@azure/ai-form-recognizer パッケージのインストール

はじめに

現在サポートされている環境

前提条件

Form Recognizer リソースを作成する

クライアントを作成して認証する

API キーを使用する

Azure Active Directory を使用する

主要な概念

DocumentAnalysisClient

DocumentModelAdministrationClient

長時間にわたって実行される操作

例

モデル ID を使用してドキュメントを分析する

URL からドキュメントを分析する

事前構築済みのドキュメント モデルを使用する

その他の事前構築済みモデル

事前構築済みの "レイアウト" を使用する

事前構築済みの "ドキュメント" を使用する

事前構築済みの "読み取り" を使用する

ドキュメントを分類する

モデルの構築

モデルを管理する

トラブルシューティング

ログの記録

次の手順

共同作成

その他のリソース

JavaScript 用 Azure AI ドキュメントインテリジェンスクライアントライブラリ - バージョン 5.0.0

`@azure/ai-form-recognizer` パッケージのインストール

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`

事前構築済みのドキュメントモデルを使用する