Document Intelligence バッチ分析 (プレビュー)

[アーティクル]
09/03/2024

重要

Document Intelligence パブリックプレビューリリースは、開発中の機能への早期アクセスを提供します。機能、アプローチ、およびプロセスは、一般提供 (GA) の前に、ユーザーからのフィードバックに基づいて変更される可能性があります。
Document Intelligence クライアントライブラリのパブリックプレビューバージョンは、REST API バージョン 2024-07-31-preview にデフォルトで設定されています。
パブリックプレビューバージョン 2024-07-31-preview は、現在、次の Azure リージョンでのみ使用できます。 AI Studio のカスタム生成 (ドキュメントフィールド抽出) モデルは、米国中北部リージョンでのみ使用できます。
- 米国東部
- 米国西部 2
- "西ヨーロッパ"
- 米国中北部

バッチ分析 API を使用すると、1 つの非同期要求を使用して複数のドキュメントを一括処理できます。ドキュメントを個別に送信して複数の要求 ID を追跡する必要はなく、請求書のコレクション、一連の融資ドキュメント、またはカスタムモデルトレーニングドキュメントのグループを同時に分析できます。

バッチ分析を利用するには、ソースドキュメントと処理された出力の両方のための特定のコンテナーを持つ Azure Blob Storage アカウントが必要です。
完了すると、バッチ操作の結果として、処理されたすべての個々のドキュメントと、それらの状態 (succeeded、skipped、failed など) が一覧表示されます。
Batch API プレビューバージョンは、従量課金制の価格で入手できます。

次のモデルでは、バッチ分析がサポートされています。

読み取り。フォームとドキュメントからテキスト行、単語、検出された言語、手書きのスタイルを抽出します。
レイアウト。フォームとドキュメントからテキスト、テーブル、選択マーク、および構造情報を抽出します。
カスタムテンプレート。構造化されたフォームからキーと値のペア、選択マーク、テーブル、署名フィールド、および領域を抽出するようにモデルをトレーニングします。
カスタムニューラル。構造化ドキュメント、半構造化ドキュメント、および非構造化ドキュメントから指定されたデータフィールドを抽出するようにモデルをトレーニングします。
カスタム生成。入れ子になったテーブル、抽象/生成フィールド、真非構造化フォーマットなどの複雑なオブジェクトから指定されたデータを抽出するようにモデルをトレーニングします。

バッチ分析のガイダンス

1 回のバッチ分析要求 (スキップされたドキュメントを含む) あたりの処理されるドキュメントの最大数は 10,000 です。
azureBlobFileListSource パラメーターを使用すると、より大きな要求をより小さな要求に分割できます。
操作結果は、完了後 24 時間保持されます。ドキュメントと結果は指定されたストレージアカウントに含まれますが、操作の状態は完了後 24 時間後に使用できなくなります。

使い始める準備はできていますか。

前提条件

アクティブな Azure サブスクリプションが必要です。 Azure サブスクリプションがない場合は、無料で作成することができます。
Azure サブスクリプションを入手したら、Azure portal で Document Intelligence インスタンスを作成します。 Free 価格レベル (F0) を利用して、サービスを試用できます。
リソースがデプロイされたら、[リソースに移動] を選択してキーとエンドポイントを取得します。
- アプリケーションを Document Intelligence サービスに接続するには、リソースのキーとエンドポイントが必要です。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。これらの値は Azure portal の [キーとエンドポイント] ページで確認できます。
Azure Blob Storage アカウント。 Azure Blob Storage アカウント内に、ソースファイルと結果ファイルのためのコンテナーを作成します。
- ソースのコンテナー。このコンテナーに分析対象のファイルをアップロードします (必須)。
- 結果コンテナー。このコンテナーは、処理されたファイルが保存される場所です (省略可能)。

ソースドキュメントと処理済みドキュメントのために、同じ Azure Blob Storage コンテナーを指定できます。ただし、誤ってデータを上書きする可能性を最小限に抑えるために、別のコンテナーを選択することをお勧めします。

ストレージコンテナーの承認

ドキュメントリソースへのアクセスを承認するには、次のいずれかのオプションを選択できます。

✔️マネージド ID。マネージド ID は、Microsoft Entra ID と、Azure 管理対象リソースの固有アクセス許可を作成するサービスプリンシパルです。マネージド ID を使用すると、コードに資格情報を埋め込む必要なく、Document Intelligence アプリケーションを実行できます。マネージド ID は、ストレージデータへのアクセスを許可するためのより安全な方法で、ソース URL と結果 URL に Shared Access Signature トークン (SAS) を含める必要がなくなります。

詳細については、「Document Intelligence のマネージド ID」を参照してください。

マネージド ID フロー (ロールベースのアクセス制御) のスクリーンショット。

重要

マネージド ID を使用する場合、HTTP 要求に SAS トークン URL を含めないでください。要求は失敗します。マネージド ID を使用すると、Shared Access Signature トークン (SAS) を含める必要がなくなります。

✔️ Shared Access Signature (SAS)。共有アクセス署名は、Document Intelligence サービスに対して、指定した期間の制限付きアクセスを許可する URL です。この方法を使うには、ソースコンテナーと結果のコンテナーのために Shared Access Signature (SAS) トークンを作成する必要があります。ソースコンテナーと結果のコンテナーには Shared Access Signature (SAS) トークンを含める必要があり、クエリ文字列として追加します。トークンは、コンテナーまたは特定の BLOB に割り当てることができます。

ストレージ URI に SAS トークンが追加されたスクリーンショット。

ソースコンテナーまたは BLOB には、読み取り、書き込み、一覧表示、削除のアクセス権が指定されている必要があります。
結果のコンテナーまたは BLOB には、書き込み、一覧表示、削除のアクセス権が指定されている必要があります。

詳細については、「SAS トークンの作成」をご覧ください。

バッチ分析 API の呼び出し

azureBlobSource または azureBlobFileListSource オブジェクト内のソースドキュメントセットのための Azure Blob Storage コンテナー URL を指定します。
resultContainerUrl を使用して、バッチ分析結果のための Azure Blob Storage コンテナー URL を指定します。誤って上書きされないようにするために、ソースドキュメントと処理済みドキュメントに個別のコンテナーを使用することをお勧めします。
- 同じコンテナーを使用する場合は、入力 azureBlobSource に合わせて resultContainerUrl と resultPrefix を設定します。
- 同じコンテナーを使用する場合は、overwriteExisting フィールドを含めることで、分析結果ファイルでファイルを上書きするかどうかを決定できます。

POST 要求をビルドして実行する

POST 要求を実行する前に、{your-source-container-SAS-URL} と {your-result-container-SAS-URL} を Azure Blob Storage コンテナーインスタンスの値に置き換えます。

azureBlobSource または azureBlobFileListSource のいずれか 1 つだけを許可します。

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

正常な応答

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

バッチ分析 API の結果を取得する

Batch API 操作が実行されたら、GET 操作を使用してバッチ分析結果を取得できます。この操作は、操作の状態情報、操作の完了率、および操作の作成と更新の日付/時刻をフェッチします。

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

ステータスメッセージの解釈

セットのドキュメントごとに、succeeded、failed、または skipped のいずれかの状態が割り当てられます。各ドキュメントには、結果を検証するための 2 つの URL が用意されています。成功した入力ドキュメントのソース BLOB ストレージコンテナーの sourceUrl と、resultContainerUrl と resultPrefix を組み合わせてソースファイルと .ocr.json の相対パスを作成することで構築された resultUrl です。

状態 notStarted または running。バッチ分析操作が開始されていないか、完了していません。すべてのドキュメントに対する操作が完了するまで待ちます。
状態 completed。バッチ分析操作が完了しました。
状態 failed。バッチ操作に失敗しました。この応答は、通常、要求について全体的な問題がある場合に発生します。すべてのファイルが失敗した場合でも、バッチレポート応答では個々のファイルのエラーが返されます。たとえば、ストレージエラーはバッチ操作全体を停止しないため、バッチレポートの応答を介して部分的な結果にアクセスできます。

succeeded 状態のファイルについてのみ、応答で resultUrl プロパティが生成されます。これにより、モデルトレーニングで .ocr.json で終わるファイル名を検出してトレーニングに使用できる唯一のファイルとして識別できます。

succeeded 状態の応答の例:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

failed 状態の応答の例:

このエラーは、バッチ要求全体においてエラーがある場合にのみ返されます。
バッチ分析操作が開始されると、すべてのファイルの状態が failed の場合でも、個々のドキュメント操作の状態はバッチジョブ全体の状態には影響しません。

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

skipped 状態の応答の例:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

バッチ分析結果は、正常に分析されたファイルを特定して、resultUrl にあるファイルと resultContainerUrl にある出力ファイルを比較して分析結果を検証するのに役立ちます。

Note

ドキュメントセット全体のバッチ分析が完了するまで、個々のファイルの分析結果は返されません。 percentCompleted 以外の詳細な進行状況を追跡するには、resultContainerUrl に書き込まれる *.ocr.json ファイルを監視できます。

次のステップ

GitHub でコードサンプルを見る。

次の方法で共有

Document Intelligence バッチ分析 (プレビュー)

バッチ分析のガイダンス

前提条件

ストレージコンテナーの承認

バッチ分析 API の呼び出し

POST 要求をビルドして実行する

バッチ分析 API の結果を取得する

ステータスメッセージの解釈

次のステップ

フィードバック

その他のリソース

次の方法で共有

Document Intelligence バッチ分析 (プレビュー)

バッチ分析のガイダンス

前提条件

ストレージ コンテナーの承認

バッチ分析 API の呼び出し

POST 要求をビルドして実行する

バッチ分析 API の結果を取得する

ステータス メッセージの解釈

次のステップ

フィードバック

その他のリソース

ストレージコンテナーの承認

ステータスメッセージの解釈