Document Intelligence v3.1 への移行

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 ファイルでアドオン機能が要求された場合に、エラーなしで空の配列が返されます。

分析機能

✓ - 有効 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 エンドポイントの変更

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 に設定され、エラーが返されます。

分析要求の本文

分析対象のコンテンツは、要求本文で提供されます。 要求を作成するには、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

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

次のステップ

• 新しい REST API を確認する
• Document Intelligence とは
• ドキュメント インテリジェンスのクイックスタート