Azure AI Vision 3.2 GA 読み取り OCR コンテナーをインストールする
コンテナーを使用すると、独自の環境で Azure AI Vision API を実行できます。 コンテナーは、特定のセキュリティ要件とデータ ガバナンス要件に適しています。 この記事では、Read (OCR) コンテナーをダウンロード、インストール、実行する方法について学習します。
Read コンテナーを使用すると、JPEG、PNG、BMP、PDF、TIFF の各ファイル形式をサポートするイメージとドキュメントから、印刷されたテキストおよび手書きのテキストを抽出できます。 詳細については、Read API 攻略ガイドに関するページを参照してください。
新機能
Read コンテナーの 3.2-model-2022-04-30 GA バージョンは、164 の言語とその他の機能強化のサポートと共に利用できます。 既存のお客様の場合は、ダウンロード手順に従って使用を開始してください。
Read 3.2 OCR コンテナーの最新の GA モデルでは、次の機能が提供されます。
- 精度の向上のための新しいモデル。
- 同じドキュメント内での複数言語のサポート。
- 合計 164 言語のサポート。 OCR でサポートされている言語の完全な一覧を参照してください。
- ドキュメントとイメージの両方に対する 1 つの操作。
- 大きなドキュメントとイメージのサポート。
- 信頼度スコア。
- 印刷および手書きの両方のテキストを含むドキュメントのサポート。
- ドキュメント内の選択したページからのみテキストを抽出する機能。
- テキスト行の出力順序の既定からより自然な読み取り順序への選択 (ラテン語系の言語のみ)。
- 手書きスタイルとしての、またはラテン言語に対してのみでないテキスト行の分類。
現時点で Read 2.0 コンテナーを使用している場合は、 移行ガイドに関する記事を参照して、新しいバージョンの変更点を確認してください。
前提条件
コンテナーを使用する前に、次の前提条件を満たす必要があります。
| 必須 | 目的 |
|---|---|
| Docker エンジン | ホスト コンピューターに Docker エンジンをインストールしておく必要があります。 Docker には、macOS、Windows、Linux 上で Docker 環境の構成を行うパッケージが用意されています。 Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。 コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。 Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。 |
| Docker に関する知識 | レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的な docker コマンドの知識が必要です。 |
| Computer Vision リソース | コンテナーを使用するためには、以下が必要です。 Computer Vision リソースとその関連する API キーおよびエンドポイント URI。 どちらの値も、対象リソースの概要ページとキー ページで使用でき、コンテナーを開始するために必要です。 {API_KEY} : [キー] ページにある 2 つの利用可能なリソース キーのどちらか {ENDPOINT_URI} : [概要] ページに提示されているエンドポイント |
Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。
必須パラメーターの収集
すべての Azure AI コンテナーに対して 3 つの主要なパラメーターが必須です。 Microsoft ソフトウェア ライセンス条項について、値 accept が示される必要があります。 エンドポイント URI と API キーも必要です。
エンドポイント URL
{ENDPOINT_URI} の値は、対応する Azure AI サービス リソースの Azure portal の[概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウスを合わせると、[クリップボードにコピー] アイコンが表示されます。 必要に応じて、エンドポイントをコピーして使用します。
キー
{API_KEY} の値はコンテナーを起動するために使用され、Azure portal で、対応する Azure AI サービス リソースの [キー] ページで入手できます。 [キー] ページに移動し、[クリップボードにコピー] アイコンを選択します。
重要
これらのサブスクリプション キーは、Azure AI サービス API にアクセスするために使用されます。 キーを共有しないでください。 安全に保管してください。 たとえば、Azure Key Vault を使用します。 また、これらのキーを定期的に再生成することをお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。
ホスト コンピューターの要件
ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。
- Azure Kubernetes Service。
- Azure Container Instances。
- Azure Stack にデプロイされた Kubernetes クラスター。 詳しくは、「Kubernetes を Azure Stack にデプロイする」をご覧ください。
Advanced Vector Extension のサポート
ホスト コンピューターとは、Docker コンテナーを実行するコンピューターのことです。 ホストは、高度なベクター拡張機能 (AVX2) を サポートしている必要があります。 次のコマンドを使用して、Linux ホストでの AVX2 サポートを確認できます。
grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected
警告
AVX2 をサポートするにはホスト コンピューターが必須です。 AVX2 サポートがないと、コンテナーは正しく機能しません。
コンテナーの要件と推奨事項
Note
要件と推奨事項は、29 行におよぶ合計 803 文字のビジネス レターのスキャン画像 (523 KB) を使用した、1 秒あたり 1 つの要求というベンチマークに基づいています。 推奨構成では、最小構成と比較して応答が約 2 倍高速という結果になりました。
次の表に、各 Read OCR コンテナーに割り当てるリソースの最小値と推奨値を示します。
| コンテナー | 最小値 | 推奨 |
|---|---|---|
| Read 3.2 2022-04-30 | 4 コア、8 GB のメモリ | 8 コア、16 GB のメモリ |
| Read 3.2 2021-04-12 | 4 コア、16 GB のメモリ | 8 コア、24 GB のメモリ |
- 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。
コアとメモリは、docker run コマンドの一部として使用される --cpus と --memory の設定に対応します。
コンテナー イメージを取得する
Azure AI Vision Read OCR コンテナー イメージは mcr.microsoft.com コンテナー レジストリ シンジケートにあります。 azure-cognitive-services リポジトリ内にあり、read という名前が付いています。 完全修飾コンテナー イメージ名は mcr.microsoft.com/azure-cognitive-services/vision/read です。
最新バージョンのコンテナーを使用するには、latest タグを使用できます。 また、MCR でタグの完全な一覧を確認することもできます。
読み取り用の次のコンテナー イメージを入手できます。
| コンテナー | コンテナー レジストリ / リポジトリ / イメージ名 | タグ |
|---|---|---|
| Read 3.2 GA | mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 |
latest、3.2、3.2-model-2022-04-30 |
docker pull コマンドを使用して、コンテナー イメージをダウンロードします。
docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30
ヒント
docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
コンテナーを使用する方法
コンテナーをホスト コンピューター上に用意できたら、次の手順を使用してコンテナーを操作します。
- 必要な課金設定を使用してコンテナーを実行します。
docker runコマンドの他の例もご覧いただけます。 - コンテナーの予測エンドポイントに対するクエリを実行します。
コンテナーを実行する
コンテナーを実行するには、docker run コマンドを使用します。 {ENDPOINT_URI} と {API_KEY} の値を取得する方法の詳細については、「必須パラメーターの収集」を参照してください。
docker run コマンドの例を利用できます。
docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
上のコマンドの内容は次のとおりです。
- コンテナー イメージから Read OCR の最新 GA のコンテナーを実行します。
- 8 つの CPU コアと 16 ギガバイト (GB) のメモリを割り当てます。
- TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てます。
- コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。
また、環境変数を使用してコンテナーを実行することもできます。
docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30
docker run コマンドの他の例もご覧いただけます。
重要
コンテナーを実行するには、Eula、Billing、ApiKey の各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。 詳細については、「課金」を参照してください。
より高いスループットが必要な場合 (複数ページのファイルを処理する場合など)、Azure Storage と Azure Queue を使用して、Kubernetes クラスターに複数のコンテナーをデプロイすることを検討してください。
処理用のイメージを格納するために Azure Storage を使用している場合は、コンテナーを呼び出すときに使用する接続文字列を作成できます。
接続文字列を見つけるには
- Azure portal でストレージ アカウントに移動し、自分のアカウントを見つけます。
- 左側のナビゲーション リストで [アクセス キー] を選択します。
- 接続文字列は、 [接続文字列] の下に配置されます。
同じホスト上で複数のコンテナーを実行する
公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。 たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。
このコンテナーと、別の Azure AI サービス コンテナーを HOST 上で一緒に実行することができます。 同じ Azure AI サービス コンテナーの複数のコンテナーを実行することもできます。
コンテナーが実行されていることを検証する
コンテナーが実行されていることを検証する方法は複数あります。 問題になっているコンテナーの "外部 IP" アドレスと公開ポートを特定し、任意の Web ブラウザーを開きます。 次の各種の要求 URL を使用して、コンテナーが実行中であることを確認します。 ここに示す要求例の URL は http://localhost:5000 ですが、実際のコンテナーは異なる可能性があります。 使用するコンテナーの外部 IP アドレスと公開ポートを基にしてください。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
コンテナーには、ホーム ページが用意されています。 |
http://localhost:5000/ready |
GET で要求することで、この URL により、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/status |
これも GET で要求することで、この URL により、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/swagger |
コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻った後、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。 |
コンテナーの予測エンドポイントに対するクエリの実行
コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。
コンテナー API には、ホストの http://localhost:5000 を使用します。 Swagger パスは http://localhost:5000/swagger/ で確認できます。
非同期読み取り
Azure AI Vision サービスで該当する REST 操作を使用する方法と同じように、POST /vision/v3.2/read/analyze 操作と GET /vision/v3.2/read/operations/{operationId} 操作を同時に使用して、画像を非同期に読み取ることができます。 非同期 POST メソッドでは、HTTP GET 要求に対する識別子として使用される operationId が返されます。
Swagger UI で Analyze を選択し、ブラウザーで展開します。 次に、 [Try it out](試してみる)>[Choose file](ファイルの選択) を選択します。 この例では、次の画像を使用します。
非同期 POST が正常に実行されると、HTTP 202 状態コードが返されます。 応答の一部として、要求の結果エンドポイントを保持する operation-location ヘッダーがあります。
content-length: 0
date: Fri, 04 Sep 2020 16:23:01 GMT
operation-location: http://localhost:5000/vision/v3.2/read/operations/a527d445-8a74-4482-8cb3-c98a65ec7ef9
server: Kestrel
operation-location は完全修飾 URL であり、HTTP GET を介してアクセスされます。 次に示すのは、前の画像から operation-location URL を実行すると返される JSON 応答です。
{
"status": "succeeded",
"createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
"lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
"analyzeResult": {
"version": "3.2.0",
"readResults": [
{
"page": 1,
"angle": 2.1243,
"width": 502,
"height": 252,
"unit": "pixel",
"lines": [
{
"boundingBox": [
58,
42,
314,
59,
311,
123,
56,
121
],
"text": "Tabs vs",
"appearance": {
"style": {
"name": "handwriting",
"confidence": 0.96
}
},
"words": [
{
"boundingBox": [
68,
44,
225,
59,
224,
122,
66,
123
],
"text": "Tabs",
"confidence": 0.933
},
{
"boundingBox": [
241,
61,
314,
72,
314,
123,
239,
122
],
"text": "vs",
"confidence": 0.977
}
]
},
{
"boundingBox": [
286,
171,
415,
165,
417,
197,
287,
201
],
"text": "paces",
"appearance": {
"style": {
"name": "handwriting",
"confidence": 0.746
}
},
"words": [
{
"boundingBox": [
286,
179,
404,
166,
405,
198,
290,
201
],
"text": "paces",
"confidence": 0.938
}
]
}
]
}
]
}
}
重要
Docker Compose または Kubernetes の下など、ロード バランサーの背後に複数の Read OCR コンテナーをデプロイする場合は、外部キャッシュが必要です。 処理コンテナーと GET 要求コンテナーは同じではない可能性があるため、外部キャッシュによって結果が格納され、コンテナーとの間で共有されます。 キャッシュ設定の詳細については、「Azure AI Vision Docker コンテナーを構成する」 をご覧ください。
同期読み取り
次の操作を使用して、画像を同期的に読み取ることができます。
POST /vision/v3.2/read/syncAnalyze
画像全体が読み込まれたら、そのときにだけ、API から JSON 応答が返されます。 この動作に対する唯一の例外は、エラーが発生した場合です。 エラーが発生すると、次の JSON が返されます。
{
"status": "Failed"
}
JSON 応答オブジェクトには、非同期バージョンと同じオブジェクト グラフが含まれます。 JavaScript を使用していて、タイプ セーフが必要な場合は、TypeScript を使用して、JSON 応答をキャストすることを検討してください。
ユースケースの例については、こちらの TypeScript サンドボックスを参照し、 [Run](実行) を選択してその使いやすさを確認してください。
インターネットから切断されたコンテナーを実行する
インターネットから切断されたこのコンテナーを使用するには、まずアプリケーションに入力し、コミットメント プランを購入してアクセスを要求する必要があります。 詳細については、「切断された環境での Docker コンテナーの使用」を参照してください。
インターネットから切断されたコンテナーの実行が承認されている場合は、次の例に使用する docker run コマンドの形式と、プレースホルダーの値を示しています。 これらのプレースホルダーの値は、実際の値に置き換えます。
docker run コマンドで DownloadLicense=True パラメーターを使用して、インターネットに接続されていないときに Docker コンテナーを実行できるようにするライセンス ファイルをダウンロードします。 有効期限も含まれており、それを過ぎると、そのライセンス ファイルを使用してコンテナーを実行できなくなります。 ライセンス ファイルは、お客様が承認されている対象の適切なコンテナーでのみ使用できます。 たとえば、音声テキスト変換コンテナーのライセンス ファイルを Document Intelligence コンテナーで使用することはできません。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
{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} |
自分の Text Analytics リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
{CONTAINER_LICENSE_DIRECTORY} |
コンテナーのローカル ファイル システム上のライセンス フォルダーの場所。 | /path/to/license/directory |
docker run --rm -it -p 5000:5000 \
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
ライセンス ファイルがダウンロードされたら、切断された環境でコンテナーを実行できます。 次の例では、使用する 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 --rm -it -p 5000:5000 --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}
コンテナーの停止
コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。
トラブルシューティング
出力マウントとログを有効にした状態でコンテナーを実行すると、コンテナーによってログ ファイルが生成されます。これらはコンテナーの起動時または実行時に発生した問題のトラブルシューティングに役立ちます。
ヒント
トラブルシューティング情報とガイダンスの詳細については、Azure AI コンテナーについてよくあるご質問 (FAQ) に関するページを参照してください。
Azure AI サービス コンテナーの実行で問題が発生している場合は、Microsoft 診断コンテナーを使用してみることができます。 このコンテナーを使用して、Azure AI コンテナーが想定どおりに機能しなくなる可能性がある、展開環境での一般的なエラーを診断します。
コンテナーを取得するには、次の docker pull コマンドを使用します。
docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic
その後で、コンテナーを実行します。 {ENDPOINT_URI} をエンドポイントに置き換え、{API_KEY} をリソースへのキーに置き換えます。
docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
コンテナーは、課金エンドポイントへのネットワーク接続をテストします。
課金
Azure AI コンテナーでは、Azure アカウントの対応するリソースを使用して、Azure に課金情報が送信されます。
コンテナーへのクエリは、 ApiKeyパラメーターに使用される Azure リソースの価格レベルで課金 されます。
Azure AI サービス コンテナーは、計測または課金エンドポイントに接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。 Azure AI サービス コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。
Azure に接続する
コンテナーには、実行する課金引数の値が必要です。 これらの値により、コンテナーは課金エンドポイントに接続することができます。 コンテナーから、約 10 ～ 15 分ごとに使用状況が報告されます。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。 接続は、10 ～15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Azure AI サービス コンテナーについてよく寄せられる質問 を参照してください。
課金引数
docker run コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。
| オプション | 説明 |
|---|---|
ApiKey |
課金情報を追跡するために使用される Azure AI サービス リソースの API キー。 このオプションの値には、 Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。 |
Billing |
課金情報を追跡するために使用される Azure AI サービス リソースのエンドポイント。 このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。 |
Eula |
お客様がコンテナーのライセンスに同意したことを示します。 このオプションの値は accept に設定する必要があります。 |
これらのオプションの詳細については、「コンテナーの構成」を参照してください。
まとめ
この記事では、Azure AI Vision コンテナーの概念とそのダウンロード、インストール、実行のワークフローについて説明しました。 要約すると:
- Azure AI Vision では、読み取りがカプセル化された、Docker 用の Linux コンテナーが提供されます。
- 読み取りコンテナー イメージを実行するには、アプリケーションが必要です。
- コンテナー イメージを Docker で実行します。
- REST API または SDK のいずれかを使用して、コンテナーのホスト URI を指定すると、Read OCR コンテナーの操作を呼び出すことができます。
- コンテナーをインスタンス化するときは、課金情報を指定する必要があります。
重要
Azure AI コンテナーは、計測のために Azure に接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に計測サービスに課金情報を伝えられるようにする必要があります。 Azure AI コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。
次のステップ
- 構成設定について、コンテナーの構成を確認する
- OCR の概要に関するページを読み、印刷および手書きのテキストの認識に関する詳細について確認する
- コンテナーでサポートされているメソッドの詳細について、Read API を参照する。
- よく寄せられる質問 (FAQ) を参照して、Azure AI Vision 機能に関連する問題を解決する。
- より多くの Azure AI コンテナーを使用する