Form Recognizer v2.1-preview コンテナーのインストールと実行

重要

  • Form Recognizer コンテナーは、限定的なプレビュー段階にあります。 これらを使用するには、オンライン リクエストを送信し、承認を受ける必要があります。 詳細については、以下のコンテナーを実行するための承認を要求する方法に関するセクションを参照してください。

  • オンライン リクエスト フォームでは、Azure サブスクリプション ID を所有する組織に属している有効なメール アドレスを指定する必要があり、ご自身がそのサブスクリプションを所有しているか、そのアクセス権を付与されている必要があります。

Azure Form Recognizer は、機械学習テクノロジを利用して自動データ処理ソフトウェアを構築することができる Azure Applied AI Services です。 Form Recognizer を使用すると、テキスト、キーと値のペア、選択マーク、表データなどを特定してフォーム ドキュメントから抽出することができます。 結果は、元のファイル内の関係を含む構造化データとして出力されます。

この記事では、Form Recognizer コンテナーをダウンロード、インストール、実行する方法について説明します。 コンテナーを使用すると、独自の環境で Form Recognizer サービスを実行できます。 コンテナーは、特定のセキュリティ要件とデータ ガバナンス要件に適しています。 Form Recognizer 機能は、レイアウト名刺身分証明書レシート請求書カスタム の 6 つの Form Recognizer 機能コンテナーによってサポートされています (レシート、名刺、身分証明書のコンテナーには、OCR の 読み取り コンテナーも必要になります)。

前提条件

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

Form Recognizer コンテナーを使用するには、以下も必要です。

必須 目的
Docker に関する知識 レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的な docker用語とコマンドの知識が必要です。
Docker Engine がインストールされている
  • ホスト コンピューターに Docker エンジンをインストールしておく必要があります。 Docker には、macOSWindowsLinux 上で Docker 環境の構成を行うパッケージが用意されています。 Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。
  • コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。
  • Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。
Form Recognizer リソース Azure portal 内の単一サービスの Azure Form Recognizer またはマルチサービスの Cognitive Services リソース。 コンテナーを使用するには、関連付けられているキーとエンドポイント URI が必要です。 どちらの値も、Azure portal の Form Recognizer の [キーとエンドポイント] ページで入手できます。
  •      {FORM_RECOGNIZER_API_KEY}: 利用可能な 2 つのリソース キーのどちらか一方。
  • {FORM_RECOGNIZER_ENDPOINT_URI} : 課金情報を追跡するために使用されるリソースのエンドポイント。
Computer Vision API リソース 名刺、身分証明書、またはレシートを処理するには、Computer Vision リソースが必要です。
  • Azure リソース (REST API または SDK) または cognitive-services-recognize-textコンテナーのいずれかとして、テキスト認識機能にアクセスできます。 通常の課金の料金が適用されます。
  • cognitive-services-recognize-text コンテナーを使用する場合は、Form Recognizer コンテナーの Computer Vision キーが、cognitive-services-recognize-text コンテナーに対して Computer Vision の docker run または docker compose コマンドで指定されたキーであることと、課金エンドポイントがコンテナーのエンドポイント (例: http://localhost:5000) であることを確認してください。 同じホスト上で Computer Vision コンテナーと Form Recognizer コンテナーの両方を一緒に使用する場合、既定のポート 5000 を使用してその両方を起動することはできません。
     
Computer Vision Azure クラウドまたは Cognitive Services コンテナーのキーとエンドポイントの両方を渡します:
  •      {COMPUTER_VISION_API_KEY}: 利用可能な 2 つのリソース キーのどちらか一方。
  • {COMPUTER_VISION_ENDPOINT_URI} : 課金情報を追跡するために使用されるリソースのエンドポイント。
オプション 目的
Azure CLI (コマンド ライン インターフェイス) Azure CLI を使用すると、一連のオンライン コマンドを使用して Azure リソースを作成および管理できます。 Windows、macOS、Linux 環境にインストールが可能で、Docker コンテナーと Azure Cloud Shell で実行できます。

コンテナーを実行するための承認を要求する

コンテナーを実行するための承認を依頼するには、限定サービスの申請フォームに入力して送信します。

このフォームでは、ユーザー、会社、コンテナーを使用するユーザー シナリオに関する情報が要求されます。 フォームを送信すると、そのフォームは Azure Cognitive Services チームによって確認されます。その後、10 営業日以内にチームから決定事項がメールで届きます。

このフォームでは、Azure サブスクリプション ID に関連付けられているメール アドレスを使用する必要があります。 コンテナーの実行に使用する Azure リソースは、承認された Azure サブスクリプション ID で作成されている必要があります。 Microsoft からのアプリケーションの状態に関する更新については、電子メール (受信トレイと迷惑フォルダーの両方) を確認してください。 承認されると、この記事で後述する Microsoft Container Registry(MCR) からコンテナーをダウンロードした後、コンテナーを実行できるようになります。

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

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

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

必要なコンテナー

次のテーブルに、ダウンロードした Form Recognizer コンテナーごとのサポート コンテナーを示します。 詳細については、「請求先」セクションを参照してください。

機能コンテナー サポート コンテナー
レイアウト なし
名刺 Computer Vision 読み取り
身分証明書 Computer Vision 読み取り
請求書 レイアウト
Receipt Computer Vision 読み取り
Custom カスタム APIカスタムの教師ありレイアウト

注意

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

読み取り、レイアウト、および事前構築済みのコンテナー
コンテナー 最小値 推奨
Read 3.2 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
Layout 2.1-preview 8 コア、16 GB のメモリ 8 コア、24 GB のメモリ
Business Card 2.1-preview 2 コア、4 GB のメモリ 4 コア、4 GB のメモリ
ID Document 2.1-preview 1 コア、2 GB メモリ 2 コア、2 GB のメモリ
Invoice 2.1-preview 4 コア、8 GB のメモリ 8 コア、8 GB のメモリ
Receipt 2.1-preview 4 コア、8 GB のメモリ 8 コア、8 GB のメモリ
カスタム コンテナー

要求のトレーニングと分析を行う場合は、次のホスト マシン要件が適用されます。

コンテナー 最小値 推奨
カスタム API 0.5 コア、0.5 GB のメモリ 1 コア、1 GB のメモリ
カスタムの教師あり 4 コア、2 GB のメモリ 8 コア、4 GB のメモリ
  • 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。
  • コアとメモリは、docker compose または docker run コマンドの一部として使用される --cpus--memory の設定に対応します。

ヒント

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" に設定されていることを確認します。

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

重要

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

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

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

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

docker-compose up

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

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

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

  • 使い慣れた 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 ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。

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

コンテナーを停止する

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

docker-compose down

課金

Form Recognizer コンテナーでは、Azure アカウントの Form Recognizer リソースを使用して、Azure に課金情報を送信します。

コンテナーへのクエリは、Key に使用される Azure リソースの価格レベルで課金されます。 ドキュメントとイメージの処理に使用されるコンテナー インスタンスごとに課金されます。 したがって、名刺機能を使用する場合は、Form Recognizer BusinessCard および Computer Vision Read コンテナー インスタンスに対して課金されます。 請求書機能の場合は、Form Recognizer Invoice および Layout コンテナー インスタンスに対して課金されます。 Form Recognizer と Computer Vision 読み取り機能コンテナーの価格に関する記事を "参照してください"。

Azure Cognitive Services コンテナーは、計測または課金エンドポイントに接続していないと、実行のライセンスが許可されません。 コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。 Cognitive Services コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。

Azure に接続する

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

課金引数

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

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

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

まとめ

これで完了です。 この記事では、Form Recognizer コンテナーの概念とそのダウンロード、インストール、および実行のワークフローについて学習しました。 要約すると:

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

重要

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

次のステップ