Document Intelligence バッチ分析

[アーティクル]
02/07/2025

バッチ分析 API を使用すると、1 つの非同期要求を使用して複数のドキュメントを一括処理できます。ドキュメントを個別に送信して複数の要求 ID を追跡するのではなく、請求書、一連の融資ドキュメント、カスタムドキュメントのグループなどのドキュメントのコレクションを同時に分析できます。バッチ API では、Azure Blob Storage からドキュメントを読み取り、結果を BLOB ストレージに書き込む機能がサポートされています。

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

バッチ分析のガイダンス

1 回のバッチ分析要求 (スキップされたドキュメントを含む) あたりの処理されるドキュメントの最大数は 10,000 です。
操作結果は、完了後 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 を指定します。

入力ファイルを指定する

バッチ API では、処理するファイルを指定するための 2 つのオプションがサポートされています。コンテナーまたはフォルダー内のすべてのファイルを処理する必要があり、ファイル数が 1 回のバッチ要求の制限である 10,000 未満である場合は、azureBlobSource コンテナーを使用します。

コンテナーまたはフォルダー内に処理する特定のファイルがある場合、または処理するファイルの数が 1 回のバッチの上限を超えている場合は、azureBlobFileListSource を使用します。データセットを複数のバッチに分割し、コンテナーのルートフォルダーに、処理するファイルのリストを JSONL 形式で含むファイルを追加します。ファイルリスト形式の例を次に示します。

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

結果の場所を指定する

resultContainerUrl を使用して、バッチ分析結果のための Azure Blob Storage コンテナー URL を指定します。誤って上書きされないようにするために、ソースドキュメントと処理済みドキュメントに個別のコンテナーを使用することをお勧めします。

同じファイル名を持つ既存の結果を上書きしない場合は、 overwriteExisting ブール値プロパティを false に設定します。この設定は課金には影響せず、入力ファイルの処理後に結果が上書きされるのを防ぐだけです。

resultPrefix を設定して、バッチ API のこの実行からの結果に名前空間を設定します。

入力と出力の両方に同じコンテナーを使用する予定の場合は、入力 azureBlobSource と一致するように resultContainerUrl と resultPrefix を設定します。
同じコンテナーを使用する場合は、overwriteExisting フィールドを含めることで、分析結果ファイルでファイルを上書きするかどうかを決定できます。

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

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

次のサンプルは、azureBlobSource プロパティを要求に追加する方法を示しています。

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

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

次のサンプルは、azureBlobFileListSource プロパティを要求に追加する方法を示しています。

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

正常な応答

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 の結果を取得する

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

次のステップ

フィードバック

その他のリソース

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

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