Document Intelligence v3.1 への移行

[アーティクル]
05/23/2024

このコンテンツは、v4.0 (プレビュー)v3.1 (GA)v3.0 (GA)v2.1 (GA) に適用されます

重要

Document Intelligence REST API v3.1 では、REST API の要求と分析の応答 JSON で破壊的変更が行われています。

v3.1 プレビュー API バージョンからの移行

プレビュー API は定期的に非推奨になっています。プレビュー API バージョンを使用している場合は、GA API バージョンをターゲットにするようにアプリケーションを更新します。 SDK を使用して 2023-02-28-preview API バージョンから 2023-07-31 (GA) API バージョンに移行するには、現在のバージョンの言語固有の SDK に更新します。

2023-07-31 (GA) API には、プレビュー API バージョンからの更新プログラムと変更が含まれています。

既定で有効になる機能は、待機時間と応答サイズの削減というメリットが得られる特定のモデルに不可欠な機能に限定されています。追加された機能は、features パラメーターの列挙値を使用して有効にすることができます。
prebuilt-{document,invoice} 以外の prebuilt-read と keyValuePairs の一部のレイアウト機能はサポートされなくなりました。
prebuilt-read と prebuilt-layout、prebuilt-read の言語、prebuilt-invoice の keyValuePairs では、バーコードが既定で無効になります。
注釈の抽出は削除されています。
クエリフィールドと、キーと値のペアの共通名は削除されています。
Office/HTML ファイルは prebuilt-read モデルでサポートされており、境界ボックスを使用せずに単語や段落を抽出します。埋め込みイメージはサポートされなくなりました。 Office/HTML ファイルでアドオン機能が要求された場合に、エラーなしで空の配列が返されます。

分析機能

モデル ID	テキスト抽出	段落	段落の役割	選択マーク	テーブル	キーと値のペア	言語	バーコード	ドキュメント分析	数式*	StyleFont*	OCR の高解像度*
prebuilt-read	✓	✓					O	O		O	O	O
事前構築済みレイアウト	✓	✓	✓	✓	✓		O	O		O	O	O
事前構築済みドキュメント	✓	✓	✓	✓	✓	✓	O	O		O	O	O
事前構築された名刺	✓								✓
prebuilt-idDocument	✓						O	O	✓	O	O	O
prebuilt-invoice	✓			✓	✓	O	O	O	✓	O	O	O
prebuilt-receipt	✓						O	O	✓	O	O	O
prebuilt-healthInsuranceCard.us	✓						O	O	✓	O	O	O
prebuilt-tax.us.w2	✓			✓			O	O	✓	O	O	O
prebuilt-tax.us.1098	✓			✓			O	O	✓	O	O	O
prebuilt-tax.us.1098E	✓			✓			O	O	✓	O	O	O
prebuilt-tax.us.1098T	✓			✓			O	O	✓	O	O	O
prebuilt-contract	✓	✓	✓	✓			O	O	✓	O	O	O
{ customModelName }	✓	✓	✓	✓	✓		O	O	✓	O	O	O

✓ - 有効 O - オプション数式/StyleFont/OCR の高解像度* - Premium 機能には追加コストがかかります

v3.0 からの移行

Document Intelligence v3.1 には、3.0 と比べた場合にいくつかの新機能が導入されています。

バーコード抽出。
高解像度、数式、フォントプロパティの抽出などのアドオン機能。
ドキュメントの分割と分類のためのカスタム分類モデル。
Invoice と Receipt モデルでの言語の拡張と新しいフィールドのサポート。
ID document モデルでの新しい種類のドキュメントのサポート。
事前構築済みの Health insurance card モデル。
Office/HTML ファイルは prebuilt-read モデルでサポートされており、境界ボックスを使用せずに単語や段落を抽出します。埋め込みイメージはサポートされなくなりました。 Office/HTML ファイルでアドオン機能が要求された場合に、エラーなしで空の配列が返されます。
抽出と分類のカスタムモデルの有効期限 - 新しいカスタムモデルは大規模な基本モデルに基づいて構築されますが、基本モデルは品質向上のために定期的に更新されます。すべてのカスタムモデルに有効期限を導入し、対応する基本モデルを廃止できるようにしています。カスタムモデルの有効期限が切れたら、最新の API バージョン (基本モデル) を使用してそのモデルを再トレーニングする必要があります。

GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}

カスタムニューラルモデルの構築クォータ - 各サブスクリプションで毎月構築できるニューラルモデルのリージョンごとの数は制限されています。クォータと使用された情報を含むように結果の JSON を拡張し、GET /info によって返されるリソース情報の一部として現在の使用状況を把握できるようにしています。

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

分析操作に対するオプションの features クエリパラメーターを使用すると、必要に応じて特定の機能を有効にすることができます。一部の Premium 機能には、追加料金が発生する可能性があります。詳細については、分析機能の一覧を参照してください。
可能な場合は、抽出した通貨フィールドオブジェクトを拡張して、正規化された通貨コードフィールドを出力します。現在、通貨フィールドからは金額 (例:123.45) と currencySymbol (例: $) が返されます。この機能を使うと、通貨記号が正規の ISO 4217 コード (米国ドルなど) にマップされます。このモデルでは、必要に応じてグローバルドキュメントのコンテンツを使用して、通貨コードを明確にしたり推測したりすることができます。

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

モデルの品質を向上するだけでなく、これらの新機能を利用できるように、アプリケーションを更新して v3.1 を使用することを強くお勧めします。

v2.1 または v2.0 からの移行

Document Intelligence v3.1 は最新の GA バージョンになっており、豊富な機能を備え、ほとんどの種類の言語とドキュメントに対応し、モデルの品質を向上しています。 v3.1 で使用できる機能については、モデルの概要に関するページを参照してください。

v3.0 以降、Document Intelligence REST API は再設計されており、使いやすさが向上しました。このセクションでは、Document Intelligence の v2.0、v2.1、v3.1 の違い、および新しいバージョンの API に移行する方法について説明します。

注意事項

REST API 2023-07-31 リリースには、REST API 分析応答 JSON の破壊的変更が含まれています。
boundingBox プロパティは各インスタンスで polygon に名前が変更されます。

REST API エンドポイントの変更

v3.1 の REST API では、レイアウト分析 (事前構築済みレイアウト) と事前構築済みモデルに documentModels と modelId を割り当てて、レイアウト分析、事前構築済みモデル、カスタムモデルの分析操作を 1 組の操作として結合しています。

POST 要求

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

GET 要求

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

分析操作

要求ペイロードと呼び出しパターンは変更されていません。
分析操作では、入力ドキュメントとコンテンツ固有の構成が指定され、応答の Operation-Location ヘッダーを介して分析結果 URL が返されます。
GET 要求を使用してこの分析結果 URL をポーリングし、分析操作の状態を調べます (要求の推奨最小間隔は 1 秒です)。
成功すると、状態は succeeded に設定され、analyzeResult が応答本文で返されます。エラーが発生した場合、状態は failed に設定され、エラーが返されます。

モデル	v2.0	v2.1	v3.1
要求 URL のプレフィックス	https://{your-form-recognizer-endpoint}/formrecognizer/v2.0	https:// /formrecognizer/v2.1	https:///formrecognizer
一般的なドキュメント	該当なし	該当なし	`/documentModels/prebuilt-document:analyze`
レイアウト	/layout/analyze	/layout/analyze	`/documentModels/prebuilt-layout:analyze`
カスタム	/custom/models/{modelId}/analyze	/custom/<モデル ID>/analyze	`/documentModels/{modelId}:analyze`
請求書	該当なし	/prebuilt/invoice/analyze	`/documentModels/prebuilt-invoice:analyze`
Receipt	/prebuilt/receipt/analyze	/prebuilt/receipt/analyze	`/documentModels/prebuilt-receipt:analyze`
身分証明書	該当なし	/prebuilt/idDocument/analyze	`/documentModels/prebuilt-idDocument:analyze`
名刺	該当なし	/prebuilt/businessCard/analyze	`/documentModels/prebuilt-businessCard:analyze`
W-2	該当なし	該当なし	`/documentModels/prebuilt-tax.us.w2:analyze`
医療保険カード	該当なし	該当なし	`/documentModels/prebuilt-healthInsuranceCard.us:analyze`
コントラクト	該当なし	該当なし	`/documentModels/prebuilt-contract:analyze`

分析要求の本文

分析対象のコンテンツは、要求本文で提供されます。要求を作成するには、URL または base64 でエンコードされたデータを使用できます。

パブリックにアクセスできる Web URL を指定するには、Content-Type を application/json に設定して、次の JSON 本文を送信します。

{
  "urlSource": "{urlPath}"
}

Base 64 エンコードは、ドキュメントインテリジェンス v3.0 でもサポートされています。

{
  "base64Source": "{base64EncodedContent}"
}

追加でサポートされるパラメーター

引き続きサポートされるパラメーター:

pages : ドキュメントの中で特定の数ページのみを分析します。分析するページ番号の一覧。番号 1 からインデックスが付けられます。例: "1-3,5,7-9"
locale : テキスト認識とドキュメント分析のためのロケールヒント。値には言語コード (en や fr など) または BCP 47 言語タグ ("en-US" など) が含まれていることがあります。

サポートされなくなったパラメーター:

includeTextDetails

新しい応答形式はいっそうコンパクトで、常に完全な出力が返されます。

結果の分析に関する変更

分析応答は、複数ページの要素をサポートするため、次の最上位レベルの結果にリファクタリングされています。

pages
tables
keyValuePairs
entities
styles
documents

Note

analyzeResult 応答の変更には、ページのプロパティから analyzeResult 内の最上位レベルのプロパティへの移動など、多くの変更が含まれます。


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

モデルの構築またはトレーニング

モデルオブジェクトの新しい API には 3 つの更新が含まれています

modelId は、モデルで人間が読むことのできる名前に設定できるプロパティです。
modelName の名前が description に変更されました
buildMode は新しいプロパティで、値はカスタムフォームモデルの場合は template、カスタムニューラルモデルの場合は neural です。

build 操作は、モデルをトレーニングするために呼び出されます。要求ペイロードと呼び出しパターンは変更されていません。構築操作では、モデルとトレーニングデータセットを指定し、応答の Operation-Location ヘッダーで結果が返されます。 GET 要求を使用してこのモデル操作 URL をポーリングし、構築操作の状態を調べます (要求の推奨最小間隔は 1 秒です)。 v2.1 とは異なり、この URL はモデルのリソースの場所ではありません。代わりに、モデルの URL は、特定の modelId から作成でき、応答の resourceLocation プロパティから取得することもできます。成功すると、状態が succeeded に設定され、結果にカスタムモデル情報が含まれます。エラーが発生した場合、状態は failed に設定され、エラーが返されます。

次のコードは、SAS トークンを使用した構築要求の例です。プレフィックスまたはフォルダーパスを設定するときの、末尾のスラッシュに注意してください。

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

モデルの構成に関する変更

モデルの構成は、単一レベルの入れ子に制限されるようになりました。構成されたモデルはカスタムモデルと一貫性が保たれ、modelId プロパティと description プロパティが追加されています。

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

モデルのコピーに関する変更

コピーモデルの呼び出しパターンは変更されていません。

authorizeCopy を呼び出してターゲットリソースでコピー操作を承認します。現在は POST 要求。
copyTo を呼び出し、ソースリソースに承認を送信してモデルをコピーします
返された操作をポーリングして、操作が正常に完了したことを検証します

モデルコピー関数に対する変更は次のものだけです。

authorizeCopy に対する HTTP アクションが POST 要求になりました。
承認ペイロードには、コピー要求を送信するために必要なすべての情報が含まれています。

コピーを承認する

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

承認アクションからの応答本文を使用して、コピーの要求を作成します。

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

モデルの一覧表示に関する変更

モデルの一覧表示が拡張され、事前構築済みモデルとカスタムモデルが返されるようになりました。事前構築済みモデルの名前はすべて、prebuilt- で始まります。状態が成功のモデルのみが返されます。失敗したモデルまたは進行中のモデルを一覧表示するには、一覧表示操作に関するページを参照してください。

モデル一覧表示要求の例

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

モデルの取得に関する変更

モデルの取得に事前構築済みモデルが含まれるようになったので、取得操作からは docTypes ディクショナリが返されます。各ドキュメントの種類の記述は、その名前、省略可能な説明、フィールドスキーマ、および省略可能なフィールド信頼度を含みます。フィールドスキーマでは、そのドキュメントの種類で返される可能性のあるフィールドの一覧が記述されています。

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

新しい情報取得操作

サービスに対する info 操作からは、カスタムモデルの数とカスタムモデルの制限が返されます。

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

応答のサンプル

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

次の方法で共有