次の方法で共有

コンテナーのインストールと実行

このコンテンツは適用対象:チェックマークv3.0 (GA)チェックマークv3.1 (GA)チェックマークv4.0 (GA)

Azure AI ドキュメント インテリジェンスは、機械学習テクノロジを利用して自動データ処理ソフトウェアを構築できる Azure AI サービスです。 ドキュメント インテリジェンスを使用すると、ドキュメントからテキスト、キーと値のペア、選択マーク、テーブル データなどを識別して抽出できます。 結果は、元のファイル内の関係を含む構造化データとして出力されます。 コンテナーは、提供されたデータのみを処理し、アクセスが許可されているリソースのみを利用します。 コンテナーは、他のリージョンのデータを処理できません。

この記事では、ドキュメント インテリジェンス コンテナーをダウンロード、インストール、実行する方法について説明します。 コンテナーを使用すると、独自の環境でドキュメント インテリジェンス サービスを実行できます。 コンテナーは、特定のセキュリティ要件とデータ ガバナンス要件に適しています。

  • レイアウト モデルは、ドキュメント インテリジェンス v4.0 コンテナーでサポートされています。

  • 読み取り、レイアウト、ID ドキュメント、領収書、請求書の各モデルは、Document Intelligence v3.1 コンテナーでサポートされています。

  • 読み取り、レイアウト、一般的なドキュメント、名刺、カスタムの各モデルは、Document Intelligence v3.0 コンテナーでサポートされています。

バージョンのサポート

現在、コンテナーのサポートは、すべてのモデルのドキュメント インテリジェンス バージョン v3.0: 2022-08-31 (GA) 、読み取り、レイアウト、ID ドキュメント、領収書、請求書モデルの v3.1 2023-07-31 (GA) 、およびレイアウトの v4.0 2024-11-30 (GA) で利用できます。

前提条件

開始するには、アクティブな Azure アカウントが必要です。 アカウントがない場合は、無料アカウントを作成できます。

ドキュメント インテリジェンス コンテナーを使用するには、次のものも必要です。

必須 目的
Docker に関する知識 レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的なdocker用語とコマンドの知識が必要です。
Docker Engine がインストールされている
  • ホスト コンピューターに Docker エンジンをインストールしておく必要があります。 Docker には、macOS、Windows、Linux 上で Docker 環境の構成を行うパッケージが用意されています。 Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。
  • コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。
  • Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。
ドキュメント インテリジェンス リソース Azure portal のシングルサービス Azure AI ドキュメント インテリジェンスまたはマルチサービス リソース。 コンテナーを使用するには、関連付けられているキーとエンドポイント URI が必要です。 どちらの値も、Azure portal の Document Intelligence の [キーとエンドポイント] ページで入手できます。
  • {FORM_RECOGNIZER_API_KEY}: 利用可能な 2 つのリソース キーのどちらか一方。
  • {FORM_RECOGNIZER_ENDPOINT_URI} : 課金情報を追跡するために使用されるリソースのエンドポイント。
オプション 目的
Azure CLI (コマンド ライン インターフェイス) Azure CLI を使用すると、一連のオンライン コマンドを使用して Azure リソースを作成および管理できます。 Windows、macOS、Linux 環境にインストールが可能で、Docker コンテナーと Azure Cloud Shell で実行できます。

ホスト コンピューターの要件

ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。

注

Studio コンテナーを Azure Kubernetes Service にデプロイして実行することはできません。 Studio コンテナーは、ローカル コンピューターでのみ実行できます。

コンテナーの要件と推奨事項

必要なサポート コンテナー

次の表は、ダウンロードする各 Document Intelligence コンテナーのサポート コンテナーを一覧表示したものです。 詳細については、「請求先」セクションを参照してください。

機能コンテナー サポート コンテナー
読み取り 必要なし
レイアウト 必要なし
名刺 読み取り
一般的なドキュメント レイアウト
請求書 レイアウト
領収書 読み取り または レイアウト
身分証明書 読み取り
カスタム テンプレート レイアウト

注

最小値と推奨値は、Docker の制限に基づくもので、ホスト マシンのリソースに基づくものではありません。

ドキュメント インテリジェンス コンテナー
コンテナー 最小値 推奨
Read 8 コア、10 GB のメモリ 8 コア、24 GB のメモリ
Layout 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
Business Card 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
General Document 8 コア、12 GB のメモリ 8 コア、24 GB のメモリ
ID Document 8 コア、8 GB のメモリ 8 コア、24 GB のメモリ
Invoice 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
Receipt 8 コア、11 GB のメモリ 8 コア、24 GB のメモリ
Custom Template 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
  • 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。
  • コアとメモリは、--cpus または --memory コマンドの一部として使用される docker compose と docker run の設定に対応します。

ヒント

docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

docker-compose up コマンドを使用してコンテナーを実行する

  • {ENDPOINT_URI} と {API_KEY} の値を、Azure リソース ページのリソース エンドポイント URI とキーに置き換えます。

    Azure portal の [キーとエンドポイント] ページのスクリーンショット。

  • EULA 値が accept に設定されていることを確認します。

  • EULA、Billing、ApiKey の各値が指定されている必要があります。指定されてない場合、コンテナーは起動できません。

重要

キーは、ドキュメント インテリジェンス リソースにアクセスするために使用されます。 キーを共有しないでください。 Azure Key Vault を使用するなどして、安全に保管してください。 これらのキーを定期的に再生成することもお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。

次のコード サンプルは、ドキュメント インテリジェンス レイアウト コンテナーを実行する自己完結 docker compose 型の例です。 docker compose では、YAML ファイルを使用してアプリケーションのサービスを構成します。 次に、docker-compose up コマンドを使用して、構成からすべてのサービスを作成し、開始します。 レイアウト コンテナー インスタンスの {FORM_RECOGNIZER_ENDPOINT_URI} と {FORM_RECOGNIZER_KEY} の値を入力します。

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-4.0
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

これで、docker compose コマンドを使用してサービスを開始できます。

docker-compose up

docker-compose up コマンドを使用してコンテナーを実行する

  • {ENDPOINT_URI} と {API_KEY} の値を、Azure リソース ページのリソース エンドポイント URI とキーに置き換えます。

    Azure portal の [キーとエンドポイント] ページのスクリーンショット。

  • EULA 値が accept に設定されていることを確認します。

  • EULA、Billing、ApiKey の各値が指定されている必要があります。指定されてない場合、コンテナーは起動できません。

重要

キーは、ドキュメント インテリジェンス リソースにアクセスするために使用されます。 キーを共有しないでください。 Azure Key Vault を使用するなどして、安全に保管してください。 これらのキーを定期的に再生成することもお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。

次のコード サンプルは、ドキュメント インテリジェンス レイアウト コンテナーを実行する自己完結 docker compose 型の例です。 docker compose では、YAML ファイルを使用してアプリケーションのサービスを構成します。 次に、docker-compose up コマンドを使用して、構成からすべてのサービスを作成し、開始します。 レイアウト コンテナー インスタンスの {FORM_RECOGNIZER_ENDPOINT_URI} と {FORM_RECOGNIZER_KEY} の値を入力します。

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

これで、docker compose コマンドを使用してサービスを開始できます。

docker-compose up

docker compose ファイルを作成する

  1. このファイルに「docker-compose.yml」という名前を付けます。

  2. 次のコード サンプルは、Document Intelligence のレイアウト、スタジオ、カスタム テンプレート コンテナーを一緒に実行する自己完結型の docker compose の例です。 docker compose では、YAML ファイルを使用してアプリケーションのサービスを構成します。 次に、docker-compose up コマンドを使用して、構成からすべてのサービスを作成し、開始します。

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.0:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.0
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

docker compose ファイルを作成する

  1. このファイルに「docker-compose.yml」という名前を付けます。

  2. 次のコード サンプルは、Document Intelligence のレイアウト、スタジオ、カスタム テンプレート コンテナーを一緒に実行する自己完結型の docker compose の例です。 docker compose では、YAML ファイルを使用してアプリケーションのサービスを構成します。 次に、docker-compose up コマンドを使用して、構成からすべてのサービスを作成し、開始します。

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.1:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.1
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

カスタム テンプレート コンテナーとレイアウト コンテナーでは、Azure Storage キューまたはメモリ内キューを使用できます。 Storage:ObjectStore:AzureBlob:ConnectionString および queue:azure:connectionstring 環境変数は、Azure Storage キューを使用している場合にのみ設定する必要があります。 ローカルで実行する場合は、これらの変数を削除します。

サービスが実行されていることを確認する

サービスが稼働していることを確認するには、 Ubuntu シェルでこれらのコマンドを実行します。

$cd <folder containing the docker-compose file>

$source .env

$docker-compose up

カスタム テンプレート コンテナーは、いくつかの異なる構成を必要とし、その他のオプション構成をサポートしています。

設定 必須 説明
EULA はい ライセンスへの同意の例: Eula=accept
課金 はい FR リソースの課金エンドポイント URI
APIキー はい FR リソースのエンドポイント キー
Queue:Azure:ConnectionString いいえ Azure Queue の接続文字列
Storage:ObjectStore:AzureBlob:ConnectionString いいえ Azure Blob の接続文字列
ヘルスチェック:メモリ上限(MB) いいえ 異常を正常に報告するためのメモリしきい値。 既定値: 推奨されるメモリと同じ
ストレージの生存時間（分） いいえ 中間ファイルと最終ファイルをすべて削除する TTL 期間。 既定値: 2 日間。TTL は 5 分から 7 日の間で設定できます
Task:MaxRunningTimeSpanInMinutes いいえ 要求をタイムアウトとして扱う最大実行時間。既定値: 60 分
HTTP_PROXY_BYPASS_URLS (HTTPプロキシバイパスURL) いいえ プロキシをバイパスするための URL を指定する 例: HTTP_PROXY_BYPASS_URLS = abc.com, xyz.com
AzureCognitiveServiceReadHost (Receipt、IdDocument コンテナーのみ) はい コンテナー URI の読み取りを指定する 例: AzureCognitiveServiceReadHost=http://onprem-frread:5000
AzureCognitiveServiceLayoutHost (ドキュメント、請求書コンテナーのみ) はい レイアウト コンテナー URI の読み取りを指定する 例: AzureCognitiveServiceLayoutHost=http://onprem-frlayout:5000

ドキュメント インテリジェンス スタジオを使用してモデルをトレーニングする

  • 同じ種類の少なくとも 5 つのフォームのセットをまとめます。 このデータを使用して、モデルのトレーニングとフォームのテストを行います。 サンプル データセットを使用できます (sample_data.zip をダウンロードして展開します)。

  • コンテナーが実行されていることを確認できたら、ブラウザーを開いて、コンテナーがデプロイされているエンドポイントに移動します。 このデプロイがローカル コンピューターの場合、エンドポイントは [http://localhost:5001](http://localhost:5001) です。

  • カスタム抽出モデル タイルを選択します。

  • Create project オプションを選択します。

  • プロジェクト名と、必要に応じて説明を指定します

  • [リソースの構成] ステップで、カスタム テンプレート モデルにエンドポイントを指定します。 コンテナーをローカル マシンにデプロイした場合は、この URL [http://localhost:5000](http://localhost:5000) を使用します。

  • files フォルダー内のトレーニング データが配置される場所のサブフォルダーを指定します。

  • 最後に、プロジェクトを作成します

これで、ラベル付けの準備が整ったプロジェクトが作成されました。 トレーニング データをアップロードし、ラベル付けを開始します。 ラベル付けを初めて使用する場合は、「カスタム モデルの構築とトレーニング」を参照してください。

API を使用したトレーニング

API を直接呼び出してモデルをトレーニングする予定の場合、カスタム テンプレート モデル トレーニング API には、ラベル付けプロジェクトの内容である base64 でエンコードされた zip ファイルが必要です。 PDF またはイメージ ファイルを省略し、JSON ファイルのみを送信できます。

データセットにラベル付けし、*.ocr.json、*.labels.json、fields.json ファイルを zip に追加したら、PowerShell コマンドを使用して base64 でエンコードされた文字列を生成します。

$bytes = [System.IO.File]::ReadAllBytes("<your_zip_file>.zip")
$b64String = [System.Convert]::ToBase64String($bytes, [System.Base64FormattingOptions]::None)

ビルド モデル API を使用して要求を投稿します。


  POST http://localhost:5000/formrecognizer/documentModels:build?api-version=2023-07-31

  {
      "modelId": "mymodel",
      "description": "test model",
      "buildMode": "template",

      "base64Source": "<Your base64 encoded string>",
      "tags": {
         "additionalProp1": "string",
         "additionalProp2": "string",
         "additionalProp3": "string"
       }
  }

サービスが実行されていることを検証する

コンテナーが実行されていることを検証する方法は複数あります。

  • コンテナーでは、コンテナーが実行されていることを視覚的に検証するために、\ にホームページを用意しています。

  • 使い慣れた Web ブラウザーを開いて、問題のコンテナーの外部 IP アドレスと公開ポートに移動できます。 一覧で示されている要求 URL を使って、コンテナーが実行中であることを確認します。 一覧で示されている要求 URL の例は http://localhost:5000 ですが、実際のコンテナーは異なる可能性があります。 実際のコンテナーの外部 IP アドレスと公開ポートに移動していることに注意してください。

    要求 URL 目的
    http://localhost:5000/ コンテナーには、ホーム ページが用意されています。
    http://localhost:5000/ready GET で要求することで、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。
    http://localhost:5000/status GET で要求することで、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。
    http://localhost:5000/swagger コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻ると、必要な HTTP のヘッダーと本文の形式を示すサンプル CURL コマンドが得られます。

Azure コンテナーのウェルカム ページのスクリーンショット。

コンテナーを停止する

コンテナーを停止するには、次のコマンドを使用します。

docker-compose down

課金

ドキュメント インテリジェンス コンテナーは、Azure アカウントのドキュメント インテリジェンス リソースを使用して、Azure に課金情報を送信します。

コンテナーへのクエリは、API Key に使われる Azure リソースの価格レベルで課金されます。 課金は、ドキュメントと画像の処理に使用されるコンテナー インスタンスごとに計算されます。

"コンテナーが有効な状態ではありません。'OutOfQuota' API キーの状態がクォータ不足でサブスクリプションの検証に失敗しました" というエラーが発生した場合。 これは、コンテナーが課金エンドポイントと通信していないことを示しています。

Azure に接続する

コンテナーには、実行する課金引数の値が必要です。 これらの値により、コンテナーは課金エンドポイントに接続することができます。 コンテナーから、約 10 ～ 15 分ごとに使用状況が報告されます。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。 接続は、10 ～15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Azure AI コンテナーに関する FAQ を参照してください。

課金引数

docker-compose up コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。

オプション 説明
ApiKey 課金情報の追跡に使用される Azure AI Foundry リソースのキー。
このオプションの値には、Billing に指定されたプロビジョニング済みのリソースのキーが設定されている必要があります。
Billing 課金情報の追跡に使用される Azure AI Foundry リソースのエンドポイント。
このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。
Eula お客様がコンテナーのライセンスに同意したことを示します。
このオプションの値は accept に設定する必要があります。

これらのオプションの詳細については、「コンテナーの構成」を参照してください。

まとめ

これで終わりです。 この記事では、ドキュメント インテリジェンス コンテナーの概念と、コンテナーのダウンロード、インストール、および実行のワークフローについて学習しました。 要約すると:

  • ドキュメント インテリジェンスは、Docker 用の 7 つの Linux コンテナーを提供します。
  • コンテナー イメージは mcr からダウンロードされます。
  • コンテナー イメージを Docker で実行します。
  • コンテナーをインスタンス化するときには、課金情報を指定する必要があります。

重要

Azure AI コンテナーは、計測のために Azure に接続されていないと、実行のライセンスが許可されません。 お客様は、課金情報をコンテナーから測定サービスに常に送信できるようにする必要があります。 Azure AI コンテナーは、顧客データ (分析中の画像やテキストなど) を Microsoft に送信しません。

次のステップ