テキスト認識コンテナーをインストールして実行するInstall and run Recognize Text containers

Computer Vision のテキスト認識部分も Docker コンテナーとして利用できます。The Recognize Text portion of Computer Vision is also available as a Docker container. レシート、ポスター、名刺など、さまざまな表面や背景を持ついろいろなオブジェクトのイメージから、印刷されたテキストを検出して、抽出できます。It allows you to detect and extract printed text from images of various objects with different surfaces and backgrounds, such as receipts, posters, and business cards.

重要

テキスト認識コンテナーは現在のところ、英語でのみ機能します。The Recognize Text container currently works only with English.

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

テキスト認識コンテナーを使用する前に、次の前提条件を満たす必要があります。You must meet the following prerequisites before using Recognize Text containers:

必須Required 目的Purpose
Docker エンジンDocker Engine ホスト コンピューターに Docker エンジンをインストールしておく必要があります。You need the Docker Engine installed on a host computer. Docker には、macOSWindowsLinux 上で Docker 環境の構成を行うパッケージが用意されています。Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。For a primer on Docker and container basics, see the Docker overview.

コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。Docker must be configured to allow the containers to connect with and send billing data to Azure.

Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。On Windows, Docker must also be configured to support Linux containers.

Docker に関する知識Familiarity with Docker レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的な docker コマンドの知識が必要です。You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
Azure Cognitive Services リソースAzure Cognitive Services resource コンテナーを使用するためには、以下が必要です。In order to use the container, you must have:

Cognitive Services Azure リソースおよび関連する課金キー (課金エンドポイント URI)。A Cognitive Services Azure resource and the associated billing key the billing endpoint URI. どちらの値も、対象リソースの概要ページとキー ページで使用でき、コンテナーを開始するために必要です。Both values are available on the Overview and Keys pages for the resource and are required to start the container. vision/v2.0 ルーティングをエンドポイント URI に追加する必要があります。次の BILLING_ENDPOINT_URI の例を参照してください。You need to add the vision/v2.0 routing to the endpoint URI as shown in the following BILLING_ENDPOINT_URI example.

{BILLING_KEY}: リソース キー{BILLING_KEY}: resource key

{BILLING_ENDPOINT_URI}: エンドポイントURI の例: https://westus.api.cognitive.microsoft.com/vision/v2.0{BILLING_ENDPOINT_URI}: endpoint URI example is: https://westus.api.cognitive.microsoft.com/vision/v2.0

プライベート コンテナー レジストリへのアクセスの要求Request access to the private container registry

まず、Cognitive Services Vision Containers Request フォームに入力して、送信し、コンテナーへのアクセスを要求する必要があります。You must first complete and submit the Cognitive Services Vision Containers Request form to request access to the container. このフォームでは、ユーザー、会社、コンテナーを使用するユーザー シナリオに関する情報が要求されます。The form requests information about you, your company, and the user scenario for which you'll use the container. 送信すると、Azure Cognitive Services チームによってフォームがレビューされ、プライベート コンテナー レジストリにアクセスするための条件を満たしていることが確認されます。Once submitted, the Azure Cognitive Services team reviews the form to ensure that you meet the criteria for access to the private container registry.

重要

フォームでは、Microsoft アカウント (MSA) または Azure Active Directory (Azure AD) アカウントに関連付けられた電子メール アドレスを使用する必要があります。You must use an email address associated with either a Microsoft Account (MSA) or Azure Active Directory (Azure AD) account in the form.

要求が承認されると、資格情報を取得して、プライベート コンテナー レジストリにアクセスする方法を説明する手順を記載した電子メールを受け取ります。If your request is approved, you then receive an email with instructions describing how to obtain your credentials and access the private container registry.

プライベート コンテナー レジストリへのログインLog in to the private container registry

Cognitive Services コンテナーのプライベート コンテナー レジストリを認証する方法はいくつかありますが、コマンドラインからの推奨される方法は、Docker CLI を使用することです。There are several ways to authenticate with the private container registry for Cognitive Services Containers, but the recommended method from the command line is by using the Docker CLI.

次の例のように docker login コマンドを使用し、Cognitive Services コンテナーのプライベート コンテナー レジストリである containerpreview.azurecr.io にログインします。Use the docker login command, as shown in the following example, to log into containerpreview.azurecr.io, the private container registry for Cognitive Services Containers. <username><password> を Azure Cognitive Services チームから受け取った資格情報に指定されているユーザー名とパスワードにそれぞれ置き換えます。Replace <username> with the user name and <password> with the password provided in the credentials you received from the Azure Cognitive Services team.

docker login containerpreview.azurecr.io -u <username> -p <password>

テキスト ファイルで資格情報をセキュリティ保護した場合は、次の例に示すように、cat コマンドを使用して、そのテキスト ファイルの内容を docker login コマンドに連結することができます。If you have secured your credentials in a text file, you can concatenate the contents of that text file, using the cat command, to the docker login command as shown in the following example. <passwordFile> を、パスワードを含むテキスト ファイルのパスと名前に置き換え、<username> を資格情報に指定されているユーザー名に置き換えます。Replace <passwordFile> with the path and name of the text file containing the password and <username> with the user name provided in your credentials.

cat <passwordFile> | docker login containerpreview.azurecr.io -u <username> --password-stdin

ホスト コンピューターThe host computer

ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。The host is a x64-based computer that runs the docker container. お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。It can be a computer on your premises or a docker hosting service in Azure including:

コンテナーの要件と推奨事項Container requirements and recommendations

次の表に、各テキスト認識コンテナーに割り当てる CPU コアとメモリの最小値と推奨値を示します。The following table describes the minimum and recommended CPU cores and memory to allocate for each Recognize Text container.

コンテナーContainer 最小値Minimum 推奨Recommended TPSTPS
(最小、最大)(Minimum, Maximum)
テキスト認識Recognize Text 1 コア、8 GB メモリ、0.5 TPS1 core, 8 GB memory, 0.5 TPS 2 コア、8 GB メモリ、1 TPS2 cores, 8 GB memory, 1 TPS 0.5、10.5, 1
  • 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。Each core must be at least 2.6 gigahertz (GHz) or faster.
  • TPS - 1 秒あたりのトランザクション数TPS - transactions per second

コアとメモリは、docker run コマンドの一部として使用される --cpus--memory の設定に対応します。Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

docker pull によるコンテナー イメージの取得Get the container image with docker pull

テキスト認識のコンテナー イメージを利用できます。Container images for Recognize Text are available.

コンテナーContainer リポジトリRepository
テキスト認識Recognize Text containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text:latest

docker pull コマンドを使用して、コンテナー イメージをダウンロードします。Use the docker pull command to download a container image.

テキスト認識コンテナー用の Docker pullDocker pull for the Recognize Text container

docker pull containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text:latest

ヒント

docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。You can use the docker images command to list your downloaded container images. たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

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

IMAGE ID            REPOSITORY              TAG
ebbee78a6baa       <container-name>         latest

コンテナーを使用する方法How to use the container

コンテナーをホスト コンピューター上に用意できたら、次の手順を使用してコンテナーを操作します。Once the container is on the host computer, use the following process to work with the container.

  1. 必要な課金設定を使用してコンテナーを実行します。Run the container, with the required billing settings. docker run コマンドの他のもご覧いただけます。More examples of the docker run command are available.
  2. コンテナーの予測エンドポイントに対するクエリを実行しますQuery the container's prediction endpoint.

docker run によるコンテナーの実行Run the container with docker run

コンテナーを実行するには、docker run コマンドを使用します。Use the docker run command to run the container. このコマンドには、次のパラメーターが使用されます。The command uses the following parameters:

プレースホルダーPlaceholder Value
{BILLING_KEY}{BILLING_KEY} このキーは、コンテナーを起動するために使用され、Azure Cognitive Services のキー ページ上で使用できます。This key is used to start the container, and is available on the Azure Cognitive Services Keys page.
{BILLING_ENDPOINT_URI}{BILLING_ENDPOINT_URI} 課金エンドポイント URI の値。The billing endpoint URI value. 例: https://westus.api.cognitive.microsoft.com/vision/v2.0Example is: https://westus.api.cognitive.microsoft.com/vision/v2.0

vision/v2.0 ルーティングをエンドポイント URI に追加する必要があります。次の BILLING_ENDPOINT_URI の例を参照してください。You need to add the vision/v2.0 routing to the endpoint URI as shown in the following BILLING_ENDPOINT_URI example.

次の例の docker run コマンドでは、これらのパラメーターをお客様独自の値に置き換えてください。Replace these parameters with your own values in the following example docker run command.

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text \
Eula=accept \
Billing={BILLING_ENDPOINT_URI} \
ApiKey={BILLING_KEY}

このコマンドは、次の操作を行います。This command:

  • コンテナー イメージから認識コンテナーを実行します。Runs a recognize container from the container image
  • 1 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てます。Allocates one CPU core and 4 gigabytes (GB) of memory
  • TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てますExposes TCP port 5000 and allocates a pseudo-TTY for the container
  • コンテナーの終了後にそれを自動的に削除します。Automatically removes the container after it exits. ホスト コンピューター上のコンテナー イメージは引き続き利用できます。The container image is still available on the host computer.

docker run コマンドの他のもご覧いただけます。More examples of the docker run command are available.

重要

コンテナーを実行するには、EulaBillingApiKey の各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. 詳細については、「課金」を参照してください。For more information, see Billing.

同じホスト上で複数のコンテナーを実行するRunning multiple containers on the same host

公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。For example, run the first container on port 5000 and the second container on port 5001.

このコンテナーと別のコグニティブ サービス コンテナーをホスト上で一緒に実行したり、同じコグニティブ サービス コンテナーの複数のコンテナーを実行したりできます。You can have this container and a different Cognitive Service container running on the HOST together or you can have multiple containers of the same Cognitive Service container running.

コンテナーの予測エンドポイントに対するクエリの実行Query the container's prediction endpoint

コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。The container provides REST-based query prediction endpoint APIs.

コンテナーの API のホストとしては https://localhost:5000 を使用します。Use the host, https://localhost:5000, for container APIs.

非同期のテキスト認識Asynchronous text recognition

Computer Vision サービスで該当する REST 操作を使用する方法と同じように、POST /vision/v2.0/recognizeText 操作と GET /vision/v2.0/textOperations/*{id}* 操作を同時に使用し、イメージ内の印刷テキストを非同期認識できます。You can use the POST /vision/v2.0/recognizeText and GET /vision/v2.0/textOperations/*{id}* operations in concert to asynchronously recognize printed text in an image, similar to how the Computer Vision service uses those corresponding REST operations. テキスト認識コンテナーでは現在のところ、印刷されたテキストのみ認識され、手書きのテキストは認識されません。そのため、Computer Vision サービス操作に通常指定される mode パラメーターはテキスト認識コンテナーで無視されます。The Recognize Text container only recognizes printed text, not handwritten text, at this time, so the mode parameter normally specified for the Computer Vision service operation is ignored by the Recognize Text container.

同期のテキスト認識Synchronous text recognition

POST /vision/v2.0/recognizeTextDirect 操作を使用し、イメージ内の印刷されたテキストが同期認識されます。You can use the POST /vision/v2.0/recognizeTextDirect operation to synchronously recognize printed text in an image. この操作は同期のため、この操作の要求本文は POST /vision/v2.0/recognizeText 操作のそれと同じになりますが、この操作の応答本文は GET /vision/v2.0/textOperations/*{id}* 操作によって返されるそれと同じになります。Because this operation is synchronous, the request body for this operation is the same as that for the POST /vision/v2.0/recognizeText operation, but the response body for this operation is the same as that returned by the GET /vision/v2.0/textOperations/*{id}* operation.

コンテナーが実行されていることを検証するValidate container is running

コンテナーが実行されていることを検証する方法は複数あります。There are several ways to validate the container is running:

RequestRequest 目的Purpose
http://localhost:5000/ コンテナーには、ホーム ページが用意されています。The container provides a homepage.
http://localhost:5000/status GET で要求され、エンドポイント クエリを発生させずにコンテナーが実行されていることを検証します。Requested with GET, to validate the container is running without causing an endpoint query. これは Kubernetes の liveness probe と readiness probe に対して使用できます。This can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger コンテナーには、エンドポイントの完全なドキュメント一式のほか、Try it now 機能が用意されています。The container provides a full set of documentation for the endpoints as well as a Try it now feature. この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりすることができます。This feature allows you to enter your settings into a web-based HTML form and make the query without having to write any code. クエリから戻ると、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。Once the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format required.

コンテナーのホーム ページ

コンテナーの停止Stop the container

コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。To shut down the container, in the command-line environment where the container is running, press Ctrl+C.

トラブルシューティングTroubleshooting

出力マウントとログを有効にした状態でコンテナーを実行すると、コンテナーによってログ ファイルが生成されます。これらはコンテナーの起動時または実行時に発生した問題のトラブルシューティングに役立ちます。If you run the container with an output mount and logging enabled, the container generates log files that are helpful to troubleshoot issues that happen while starting or running the container.

課金Billing

テキスト認識コンテナーは、Azure アカウントの テキスト認識 リソースを使用して、Azure に課金情報を送信します。The Recognize Text containers send billing information to Azure, using a Recognize Text resource on your Azure account.

コンテナーへのクエリは、<ApiKey> に使用される Azure リソースの価格レベルで課金されます。Queries to the container are billed at the pricing tier of the Azure resource used for the <ApiKey>.

Cognitive Services コンテナーは、計測のために課金エンドポイントに接続していないと、実行のライセンスが許可されません。Cognitive Services containers are not licensed to run without being connected to the billing endpoint for metering. お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。Customers need to enable the containers to communicate billing information with billing endpoint at all times. Cognitive Services コンテナーが、顧客データ (解析対象の画像やテキストなど) を Microsoft に送信することはありません。Cognitive Services containers do not send customer data (for example, the image or text that is being analyzed) to Microsoft.

Azure への接続Connecting to Azure

コンテナーには、実行する課金引数の値が必要です。The container needs the billing argument values to run. これらの値により、コンテナーは課金エンドポイントに接続することができます。These values allow the container to connect to billing endpoint. コンテナーから、約 10 ~ 15 分ごとに使用状況が報告されます。The container reports usage about every 10 to 15 minutes. 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。If the container doesn't connect within the allowed time window to Azure, the container will continue to run but will not serve queries until the billing endpoint is restored. 接続は、10 ~15 分の同じ時間間隔で、10 回試行されます。The connection is attempted 10 times at the same time interval of 10 to 15 minutes. 10 回以内に課金エンドポイントに接続できなかった場合は、コンテナーの実行が停止されます。If it can't connect to the billing endpoint within the 10 tries, the container will stop running.

課金引数Billing arguments

docker run コマンドでコンテナーを起動するには、次の 3 つのオプションすべてに有効な値を指定する必要があります。All three of the following options must be specified with valid values in order for the docker run command to start the container:

オプションOption 説明Description
ApiKey 課金情報を追跡するために使用される Cognitive Service リソースの API キー。The API key of the Cognitive Service resource used to track billing information.
このオプションの値には、Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。The value of this option must be set to an API key for the provisioned resource specified in Billing.
Billing 課金情報を追跡するために使用される Cognitive Service リソースのエンドポイント。The endpoint of the Cognitive Service resource used to track billing information.
このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula コンテナーのライセンスに同意していることを示します。Indicates that you've accepted the license for the container.
このオプションの値は accept に設定する必要があります。The value of this option must be set to accept.

これらのオプションの詳細については、「コンテナーの構成」を参照してください。For more information about these options, see Configure containers.

まとめSummary

この記事では、テキスト認識コンテナーの概念とそのダウンロード、インストール、および実行のワークフローについて説明しました。In this article, you learned concepts and workflow for downloading, installing, and running Recognize Text containers. 要約すると:In summary:

  • テキスト認識は、テキスト認識をカプセル化する、Docker 用の Linux コンテナーを提供します。Recognize Text provides a Linux container for Docker, encapsulating recognize text.
  • コンテナー イメージは、Azure の Microsoft Container Registry (MCR) からダウンロードされます。Container images are downloaded from the Microsoft Container Registry (MCR) in Azure.
  • コンテナー イメージを Docker で実行します。Container images run in Docker.
  • REST API または SDK を使用して、コンテナーのホスト URI を指定することによって、テキスト認識コンテナーの操作を呼び出すことができます。You can use either the REST API or SDK to call operations in Recognize Text containers by specifying the host URI of the container.
  • コンテナーをインスタンス化するときは、課金情報を指定する必要があります。You must specify billing information when instantiating a container.

重要

Cognitive Services コンテナーは、計測のために Azure に接続していないと、実行のライセンスが許可されません。Cognitive Services containers are not licensed to run without being connected to Azure for metering. お客様は、コンテナーが常に計測サービスに課金情報を伝えられるようにする必要があります。Customers need to enable the containers to communicate billing information with the metering service at all times. Cognitive Services コンテナーが、顧客データ (解析対象の画像やテキストなど) を Microsoft に送信することはありません。Cognitive Services containers do not send customer data (for example, the image or text that is being analyzed) to Microsoft.

次の手順Next steps