切断された (オフライン) 環境のコンテナー
現在、コンテナーのサポートは、すべてのモデルに対してドキュメント インテリジェンスのバージョン 2022-08-31 (GA)
で使用可能であり、読み取り、レイアウト、請求書、領収書、ID ドキュメントのモデルに対してバージョン 2023-07-31 (GA)
で使用可能です。
- REST API
2022-08-31 (GA)
- REST API
2023-07-31 (GA)
REST API 2022-08-31 (GA)
をターゲットにするクライアント ライブラリREST API 2023-07-31 (GA)
をターゲットにするクライアント ライブラリ
✔️ サポートされているコンテナーのドキュメントについては、 切断された環境でのDocument Intelligence v3.0 コンテナー を参照してください。
このコンテンツの適用対象: v3.0 (GA) v3.1 (GA)
切断されたコンテナーとは
Azure AI コンテナーを使用すると、いくつかの Document Intelligence サービスをコンテナー内で柔軟ンにローカル実行することができます。 接続されたコンテナーは、環境内でローカルに実行され、課金のために使用状況情報をクラウドに送信します。 切断されたコンテナーは、コンテナーを実行する際にクラウドと接続する必要がないシナリオを対象としています。
Azure AI Document Intelligence コンテナーにより、コンテナー化の利点を活用して Document Intelligence API を使用できます。 切断されたコンテナーはコミットメント レベルの価格で提供されており、従量課金制の価格と比べて割引料金で提供されています。 コミットメント レベルの価格では、ワークロードのニーズに基づく固定料金で Document Intelligence の機能の使用にコミットでき、合計コストを予測できます。
はじめに
オフライン環境で Docker コンテナーの実行を試みる前に、コンテナーを正常にダウンロードして使用するための以下の要件をよく理解しておいてください。
- ホスト コンピューターの要件と推奨事項。
- コンテナーをダウンロードするための Docker
pull
コマンド。 - コンテナーが実行されていることを検証する方法。
- 実行後に、コンテナーのエンドポイントにクエリを送信する方法。
切断された環境でコンテナーを使用するためのアクセスを要求する
切断された環境で Document Intelligence コンテナーを使用するには、まず要求フォームに入力して送信し、コミットメント プランを購入する必要があります。
Azure portal で新しいリソースを作成する
ポータルで新しいリソースをプロビジョニングすることから開始します。
価格レベルに
Commitment tier disconnected containers DC0
オプションを選択していることを確認しますカスタム、読み取り、または事前構築済みのコミットメントレベルの少なくとも 1 つから適切な価格レベルを選択します
コンテナー | 最小値 | 推奨 | コミットメント プラン |
---|---|---|---|
Read |
8 コア、10 GB のメモリ |
8 コア、24 GB のメモリ |
OCR (読み取り) |
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 のメモリ |
カスタム API |
必須パラメーターの収集
Azure AI サービスのすべてのコンテナーには次の 3 つの必須パラメーターがあります。
- 使用許諾契約 (EULA) が、accept の値と共に存在する必要があります。
- Azure portal からのリソースのエンドポイント URL。
- Azure portal からのリソースの API キー。
コンテナーを初めて実行して、切断された状態で使用できるように構成する際には、エンドポイント URL と API キーの両方が必要です。 キーとエンドポイントは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで確認できます。
重要
キーとエンドポイントは、切断された環境で実行するようにコンテナーを構成するためにのみ使用します。 コンテナーを構成したら、API 要求を送信するためにキーとエンドポイントの値は必要ありません。 Azure Key Vault を使用するなどして、安全に保管してください。 このプロセスに必要なキーは 1 つだけです。
docker pull
を使用した Docker コンテナーのダウンロード
切断された環境での実行が承認されている Docker コンテナーをダウンロードします。 次に例を示します。
docker pull コマンド | 値 | 形式 |
---|---|---|
● docker pull [image] ● docker pull [image]latest |
最新のコンテナー イメージ。 | ● mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest ● mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.0:latest |
docker pull コマンドの例
docker pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice:latest
切断された環境で実行されるようにコンテナーを構成する
切断されたコンテナーのイメージは、接続されたコンテナーと同じです。 主な違いは、切断されたコンテナーにはライセンス ファイルが必要になることです。 このライセンス ファイルをダウンロードするには、downloadLicense パラメーターを true に設定して接続モードでコンテナーを起動します。
これでコンテナーがダウンロードされたので、次のパラメーターを指定して docker run
コマンドを実行する必要があります。
DownloadLicense=True
. このパラメーターは、インターネットに接続されていないときに Docker コンテナーを実行できるようにするライセンス ファイルをダウンロードします。 有効期限も含まれており、それを過ぎると、そのライセンス ファイルを使用してコンテナーを実行できなくなります。 ライセンス ファイルは、対応する承認済みコンテナーでのみ使用できます。
重要
docker run
コマンドによって生成されるテンプレートを使って、コンテナーを実行できます。 テンプレートには、ダウンロードしたモデルと構成ファイルに必要なパラメーターが含まれています。 このテンプレートを保存してください。
次の例では、使用する docker run
コマンドの形式と、プレースホルダーの値を示します。 これらのプレースホルダーの値は、実際の値に置き換えます。
プレースホルダー | 値 | 形式または例 |
---|---|---|
{IMAGE} |
使用するコンテナー イメージ。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{LICENSE_MOUNT} |
ライセンスがダウンロードされ、マウントされるパス。 | /host/license:/path/to/license/directory |
{ENDPOINT_URI} |
サービス要求を認証するためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API_KEY} |
Document Intelligence リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | {string} |
{CONTAINER_LICENSE_DIRECTORY} |
コンテナーのローカル ファイル システム上のライセンス フォルダーの場所。 | /path/to/license/directory |
docker run
コマンドの例
docker run --rm -it -p 5000:5050 \
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
次のコマンドで、フォルダー パス、課金エンドポイント、API キーの各プレースホルダーを置き換えて、レイアウト コンテナーのライセンス ファイルをダウンロードします。
docker run -v {folder path}:/license --env Mounts:License=/license --env DownloadLicense=True --env Eula=accept --env Billing={billing endpoint} --env ApiKey={api key} mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
コンテナーが構成されたら、次のセクションに従って、ライセンスを使用し、適切なメモリと CPU の割り当てを行って、環境でコンテナーを実行します。
Document Intelligence コンテナーのモデルと構成
コンテナーを構成したら、ダウンロードした Document Intelligence モデルとコンテナー構成の値が生成され、コンテナーの出力に表示されます。
切断された環境でコンテナーを実行する
ライセンス ファイルをダウンロードしたら、ライセンス、適切なメモリ、適切な CPU 割り当てを使用し、切断された環境でコンテナーを実行できます。 次の例では、docker run
コマンドの形式と、プレースホルダーの値を示します。 これらのプレースホルダーの値を実際の値に置き換えます。
コンテナーを実行するときは常に、ライセンス ファイルをコンテナーにマウントする必要があり、コンテナーのローカル ファイルシステム上にあるライセンス フォルダーの場所を Mounts:License=
で指定する必要があります。 さらに、課金用の使用状況レコードを書き込むことができるように、出力のマウントを指定する必要があります。
プレースホルダー | 値 | 形式または例 |
---|---|---|
{IMAGE} |
使用するコンテナー イメージ。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{MEMORY_SIZE} |
コンテナーに割り当てるメモリの適切なサイズ。 | 4g |
{NUMBER_CPUS} |
コンテナーに割り当てる CPU の適切な数。 | 4 |
{LICENSE_MOUNT} |
ライセンスが配置され、マウントされるパス。 | /host/license:/path/to/license/directory |
{OUTPUT_PATH} |
使用状況レコードを記録するための出力パス。 | /host/output:/path/to/output/directory |
{CONTAINER_LICENSE_DIRECTORY} |
コンテナーのローカル ファイル システム上のライセンス フォルダーの場所。 | /path/to/license/directory |
{CONTAINER_OUTPUT_DIRECTORY} |
コンテナーのローカル ファイル システム上の出力フォルダーの場所。 | /path/to/output/directory |
docker run
コマンドの例
docker run --rm -it -p 5000:5050 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \
-v {LICENSE_MOUNT} \
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}
切断されたコンテナーの開始は、接続されたコンテナーの開始と同様です。 切断されたコンテナーには、追加のライセンス パラメーターが必要になります。 切断モードでカスタム コンテナーを開始するための docker-compose.yml ファイルのサンプルを以下に示します。 値が設定されている CUSTOM_LICENSE_MOUNT_PATH 環境変数を、ダウンロードしたライセンス ファイルが含まれるフォルダーに追加し、値が設定されている OUTPUT_MOUNT_PATH
環境変数を、使用ログが含まれるフォルダーに追加します。
version: '3.3'
services:
nginx:
image: nginx:alpine
container_name: reverseproxy
volumes:
- ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
ports:
- "5000:5050"
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: /shared
Mounts:Shared: /shared
Mounts:Output: /logs
Mounts:License: /license
volumes:
- type: bind
source: ${SHARED_MOUNT_PATH}
target: /shared
- type: bind
source: ${OUTPUT_MOUNT_PATH}
target: /logs
- type: bind
source: ${LAYOUT_LICENSE_MOUNT_PATH}
target: /license
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: /shared
Mounts:Shared: /shared
Mounts:Output: /logs
Mounts:License: /license
volumes:
- type: bind
source: ${SHARED_MOUNT_PATH}
target: /shared
- type: bind
source: ${OUTPUT_MOUNT_PATH}
target: /logs
- type: bind
source: ${CUSTOM_LICENSE_MOUNT_PATH}
target: /license
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 コンテナーを運用する場合、コンテナーは、使用状況レコードをボリュームに書き込んで、時間をかけて収集されるようにします。 REST API エンドポイントを呼び出して、サービス使用状況に関するレポートを生成することもできます。
ログを格納するための引数
切断された環境で実行する場合は、使用状況ログを格納するために、コンテナーで出力マウントを利用できる必要があります。 たとえば、{OUTPUT_PATH}
をログの格納場所のパスに置き換えて、-v /host/output:{OUTPUT_PATH}
と Mounts:Output={OUTPUT_PATH}
を次の例に含めます。
docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}
コンテナー エンドポイントを使用してレコードを取得する
コンテナーには、その使用状況に関するレコードを返すための 2 つのエンドポイントが用意されています。
すべてのレコードを取得する
次のエンドポイントは、マウントされた課金レコード ディレクトリに収集されたすべての使用状況を要約するレポートを提供します。
https://<service>/records/usage-logs/
HTTPS エンドポイントの例
http://localhost:5000/records/usage-logs
使用状況ログ エンドポイントからは、次の例のような JSON 応答が返されます。
{
"apiType": "string",
"serviceName": "string",
"meters": [
{
"name": "string",
"quantity": 256345435
}
]
}
特定の月のレコードを取得する
次のエンドポイントは、特定の月と年の使用状況を要約したレポートを提供します。
https://<service>/records/usage-logs/{MONTH}/{YEAR}
この使用状況ログ エンドポイントからは、次の例のような JSON 応答が返されます。
{
"apiType": "string",
"serviceName": "string",
"meters": [
{
"name": "string",
"quantity": 56097
}
]
}
トラブルシューティング
出力マウントとログを有効にしてコンテナーを実行します。 これらの設定により、コンテナーによるログ ファイルの生成が有効になり、コンテナーの開始時または実行中に発生する問題のトラブルシューティングに役立ちます。
ヒント
トラブルシューティング情報とガイダンスの詳細については、「切断されたコンテナーについてよくあるご質問 (FAQ)」を参照してください。