Kubernetes と Helm と共に Computer Vision コンテナーを使用する

オンプレミスの Computer Vision コンテナーを管理するための 1 つの方法は、Kubernetes と Helm を使用することです。 Kubernetes と Helm を使用して Computer Vision コンテナー イメージを定義し、Kubernetes パッケージを作成します。 このパッケージは、オンプレミスの Kubernetes クラスターに展開されます。 最後に、デプロイされたサービスをテストする方法を検討します。 Kubernetes オーケストレーションを使用せずに Docker コンテナーを実行する方法の詳細については、「Computer Vision コンテナーをインストールして実行する」を参照してください。

前提条件

オンプレミスの Computer Vision コンテナーを使用する前の前提条件は次のとおりです。

必須 目的
Azure アカウント Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。
Kubernetes CLI コンテナー レジストリからの共有資格情報を管理するには、Kubernetes CLI が必要です。 また、Kubernetes は、Kubernetes のパッケージ マネージャーである Helm の前に必要です。
Helm CLI Helm Chart (コンテナー パッケージ定義) のインストールに使用される Helm CLI をインストールします。
Computer Vision リソース コンテナーを使用するためには、以下が必要です。

Azure Computer Vision リソースとその関連する API キーおよびエンドポイント URI。 どちらの値も、対象リソースの概要ページとキー ページで使用でき、コンテナーを開始するために必要です。

{API_KEY} : [キー] ページにある 2 つの利用可能なリソース キーのどちらか

{ENDPOINT_URI} : [概要] ページに提示されているエンドポイント

必須パラメーターの収集

すべての Cognitive Services のコンテナーに対して必須である、3 つの主要なパラメーターがあります。 エンドユーザー使用許諾契約書 (EULA) は、accept の値と共に提示される必要があります。 さらに、エンドポイント URL と API キーの両方が必要です。

エンドポイント URL {ENDPOINT_URI}

エンドポイント URI の値は、Azure portal で、対応する Cognitive Service リソースの [概要] ページで入手できます。 [概要] ページに移動して、エンドポイントの上にマウス ポインターを移動すると、Copy to clipboard アイコンが表示されます。 必要に応じてコピーして使用します。

後で使用するためにエンドポイント URI を収集する

キー {API_KEY}

このキーはコンテナーを起動するために使用され、Azure portal で、対応する Cognitive Service リソースの [キー] ページで入手できます。 [キー] ページに移動し、Copy to clipboard アイコンをクリックします。

後で使用するために 2 つのキーのどちらかを入手する

重要

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

ホスト コンピューター

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

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

注意

要件と推奨事項は、29 行におよぶ合計 803 文字のビジネス レターのスキャン画像 (523 KB) を使用した、1 秒あたり 1 つの要求というベンチマークに基づいています。 推奨構成では、最小構成と比較して応答が約 2 倍高速という結果になりました。

次の表に、各 Read OCR コンテナーに割り当てるリソースの最小値と推奨値を示します。

コンテナー 最小値 推奨
Read 2.0-preview 1 コア、8 GB のメモリ 8 コア、16 GB のメモリ
Read 3.2 4 コア、16 GB のメモリ 8 コア、24 GB のメモリ
  • 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。

コアとメモリは、docker run コマンドの一部として使用される --cpus--memory の設定に対応します。

Kubernetes クラスターに接続する

ホスト コンピューターには使用可能な Kubernetes クラスターがあることが想定されます。 ホスト コンピューターへの Kubernetes クラスターの展開方法の概念を理解するには、Kubernetes クラスターの展開に関するこのチュートリアルをご覧ください。 デプロイの詳細については、Kubernetes のドキュメントをご覧ください。

展開に対する Helm チャートの値を構成する

まず、read という名前のフォルダを作成します。 次に、次の YAML コンテンツを chart.yaml という名前の新しいファイルに貼り付けます。

apiVersion: v2
name: read
version: 1.0.0
description: A Helm chart to deploy the Read OCR container to a Kubernetes cluster
dependencies:
- name: rabbitmq
  condition: read.image.args.rabbitmq.enabled
  version: ^6.12.0
  repository: https://kubernetes-charts.storage.googleapis.com/
- name: redis
  condition: read.image.args.redis.enabled
  version: ^6.0.0
  repository: https://kubernetes-charts.storage.googleapis.com/

Helm チャートの既定値を構成するために、次の YAML をコピーし、values.yaml という名前のファイルに貼り付けます。 # {ENDPOINT_URI}# {API_KEY} のコメントを独自の値に置き換えます。 必要に応じて、resultExpirationPeriod、Redis、RabbitMQ を構成します。

# These settings are deployment specific and users can provide customizations
read:
  enabled: true
  image:
    name: cognitive-services-read
    registry:  mcr.microsoft.com/
    repository: azure-cognitive-services/vision/read
    tag: 3.2-preview.1
    args:
      eula: accept
      billing: # {ENDPOINT_URI}
      apikey: # {API_KEY}
      
      # Result expiration period setting. Specify when the system should clean up recognition results.
      # For example, resultExpirationPeriod=1, the system will clear the recognition result 1hr after the process.
      # resultExpirationPeriod=0, the system will clear the recognition result after result retrieval.
      resultExpirationPeriod: 1
      
      # Redis storage, if configured, will be used by read OCR container to store result records.
      # A cache is required if multiple read OCR containers are placed behind load balancer.
      redis:
        enabled: false # {true/false}
        password: password

      # RabbitMQ is used for dispatching tasks. This can be useful when multiple read OCR containers are
      # placed behind load balancer.
      rabbitmq:
        enabled: false # {true/false}
        rabbitmq:
          username: user
          password: password

重要

  • billing 値と apikey 値が指定されていない場合、サービスは 15 分後に期限切れになります。 さらに、サービスが利用できないため、検証は失敗します。

  • Docker Compose または Kubernetes の下など、ロード バランサーの背後に複数の Read OCR コンテナーをデプロイする場合は、外部キャッシュが必要です。 処理コンテナーと GET 要求コンテナーは同じではない可能性があるため、外部キャッシュによって結果が格納され、コンテナーとの間で共有されます。 キャッシュ設定の詳細については、「Computer Vision Docker コンテナーを構成する」をご覧ください。

read ディレクトリの下に templates フォルダーを作成します。 次の YAML をコピーし、deployment.yaml という名前のファイルに貼り付けます。 deployment.yaml ファイルは Helm テンプレートとして機能します。

テンプレートによってマニフェスト ファイルが生成されます。マニフェスト ファイルは、Kubernetes が理解できる YAML 形式のリソース記述です。 - Helm チャート テンプレート ガイド

apiVersion: apps/v1
kind: Deployment
metadata:
  name: read
  labels:
    app: read-deployment
spec:
  selector:
    matchLabels:
      app: read-app
  template:
    metadata:
      labels:
        app: read-app       
    spec:
      containers:
      - name: {{.Values.read.image.name}}
        image: {{.Values.read.image.registry}}{{.Values.read.image.repository}}
        ports:
        - containerPort: 5000
        env:
        - name: EULA
          value: {{.Values.read.image.args.eula}}
        - name: billing
          value: {{.Values.read.image.args.billing}}
        - name: apikey
          value: {{.Values.read.image.args.apikey}}
        args:        
        - ReadEngineConfig:ResultExpirationPeriod={{ .Values.read.image.args.resultExpirationPeriod }}
        {{- if .Values.read.image.args.rabbitmq.enabled }}
        - Queue:RabbitMQ:HostName={{ include "rabbitmq.hostname" . }}
        - Queue:RabbitMQ:Username={{ .Values.read.image.args.rabbitmq.rabbitmq.username }}
        - Queue:RabbitMQ:Password={{ .Values.read.image.args.rabbitmq.rabbitmq.password }}
        {{- end }}      
        {{- if .Values.read.image.args.redis.enabled }}
        - Cache:Redis:Configuration={{ include "redis.connStr" . }}
        {{- end }}
      imagePullSecrets:
      - name: {{.Values.read.image.pullSecret}}      
--- 
apiVersion: v1
kind: Service
metadata:
  name: read-service
spec:
  type: LoadBalancer
  ports:
  - port: 5000
  selector:
    app: read-app

同じ templates フォルダーで、次のヘルパー関数をコピーして helpers.tpl に貼り付けます。 helpers.tpl には、Helm テンプレートの生成に役立つ便利な関数が定義されています。

注意

この記事には、Microsoft が使用しなくなった "スレーブ" という用語への言及が含まれています。 この用語は、ソフトウェアから削除された時点でこの記事から削除されます。

{{- define "rabbitmq.hostname" -}}
{{- printf "%s-rabbitmq" .Release.Name -}}
{{- end -}}

{{- define "redis.connStr" -}}
{{- $hostMain := printf "%s-redis-master:6379" .Release.Name }}
{{- $hostReplica := printf "%s-redis-slave:6379" .Release.Name -}}
{{- $passWord := printf "password=%s" .Values.read.image.args.redis.password -}}
{{- $connTail := "ssl=False,abortConnect=False" -}}
{{- printf "%s,%s,%s,%s" $hostMain $hostReplica $passWord $connTail -}}
{{- end -}}

テンプレートでは、ロード バランサー サービスと、読み取り用のコンテナー/イメージのデプロイが指定されています。

Kubernetes パッケージ (Helm チャート)

"Helm チャート" には、mcr.microsoft.com コンテナー レジストリからプルする Docker イメージの構成が含まれます。

Helm チャート は、関連する Kubernetes リソースのセットが記述されているファイルのコレクションです。 1 つのチャートを使って、memcached ポッドのような単純なものや、HTTP サーバー、データベース、キャッシュなどを含む完全な Web アプリ スタックのような複雑なものを、展開できます。

提供されている "Helm チャート" では、Computer Vision サービスと対応するサービスの Docker イメージが、mcr.microsoft.com コンテナー レジストリからプルされます。

Kubernetes クラスターに Helm チャートをインストールする

"Helm チャート" をインストールするには、helm install コマンドを実行する必要があります。 必ず read フォルダーの上のディレクトリから install コマンドを実行します。

helm install read ./read

インストールが正常に実行されると表示される出力の例を次に示します。

NAME: read
LAST DEPLOYED: Thu Sep 04 13:24:06 2019
NAMESPACE: default
STATUS: DEPLOYED

RESOURCES:
==> v1/Pod(related)
NAME                    READY  STATUS             RESTARTS  AGE
read-57cb76bcf7-45sdh   0/1    ContainerCreating  0         0s

==> v1/Service
NAME     TYPE          CLUSTER-IP    EXTERNAL-IP  PORT(S)         AGE
read     LoadBalancer  10.110.44.86  localhost    5000:31301/TCP  0s

==> v1beta1/Deployment
NAME    READY  UP-TO-DATE  AVAILABLE  AGE
read    0/1    1           0          0s

Kubernetes の展開が完了するには数分かかります。 ポッドとサービスの両方が適切に展開されて使用可能なことを確認するには、次のコマンドを実行します。

kubectl get all

次のような出力結果が表示されます。

kubectl get all
NAME                        READY   STATUS    RESTARTS   AGE
pod/read-57cb76bcf7-45sdh   1/1     Running   0          17s

NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
service/kubernetes     ClusterIP      10.96.0.1      <none>        443/TCP          45h
service/read           LoadBalancer   10.110.44.86   localhost     5000:31301/TCP   17s

NAME                   READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/read   1/1     1            1           17s

NAME                              DESIRED   CURRENT   READY   AGE
replicaset.apps/read-57cb76bcf7   1         1         1       17s

Kubernetes クラスターに複数の v3 コンテナーを展開する

コンテナーの v3 以降、タスク レベルとページ レベルの両方でコンテナーを並列利用できます。

設計上、各 v3 コンテナーにはディスパッチャーと認識 worker が与えられています。 ディスパッチャーは、複数ページのタスクを複数のシングル ページ サブタスクに分割する役割を担います。 認識 worker は、シングル ページのドキュメントを認識するように最適化されています。 ページ レベルで並列処理するには、ロード バランサーの背後に v3 コンテナーを展開し、共通のストレージとキューをコンテナーに共有させます。

注意

現在のところ、Azure Storage と Azure Queue のみがサポートされています。

要求を受け取るコンテナーによって、タスクをシングル ページのサブタスクに分割し、それを共通キューに追加できます。 負荷の少ないコンテナーに認識 worker がある場合、そのコンテナーによって、キューからシングル ページのサブタスクを使用し、認識を実行し、結果をストレージにアップロードできます。 展開されているコンテナーの数に基づき、スループットは n 回まで上げることができます。

v3 コンテナーにより、/ContainerLiveness パス以下の liveness probe API が公開されています。 次のデプロイ例を使用して、Kubernetes 用に liveness probe を構成します。

次の YAML をコピーし、deployment.yaml という名前のファイルに貼り付けます。 # {ENDPOINT_URI}# {API_KEY} のコメントを独自の値に置き換えます。 # {AZURE_STORAGE_CONNECTION_STRING} コメントを Azure Storage 接続文字列に置換します。 replicas を任意の数値に構成します。次の例では 3 に設定されています。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: read
  labels:
    app: read-deployment
spec:
  selector:
    matchLabels:
      app: read-app
  replicas: # {NUMBER_OF_READ_CONTAINERS}
  template:
    metadata:
      labels:
        app: read-app
    spec:
      containers:
      - name: cognitive-services-read
        image: mcr.microsoft.com/azure-cognitive-services/vision/read
        ports:
        - containerPort: 5000
        env:
        - name: EULA
          value: accept
        - name: billing
          value: # {ENDPOINT_URI}
        - name: apikey
          value: # {API_KEY}
        - name: Storage__ObjectStore__AzureBlob__ConnectionString
          value: # {AZURE_STORAGE_CONNECTION_STRING}
        - name: Queue__Azure__ConnectionString
          value: # {AZURE_STORAGE_CONNECTION_STRING}
        livenessProbe:
          httpGet:
            path: /ContainerLiveness
            port: 5000
          initialDelaySeconds: 60
          periodSeconds: 60
          timeoutSeconds: 20
--- 
apiVersion: v1
kind: Service
metadata:
  name: azure-cognitive-service-read
spec:
  type: LoadBalancer
  ports:
  - port: 5000
    targetPort: 5000
  selector:
    app: read-app

次のコマンドを実行します。

kubectl apply -f deployment.yaml

正常に展開されると表示される出力の例を次に示します。

deployment.apps/read created
service/azure-cognitive-service-read created

Kubernetes 展開の完了には数分かかることがあります。 ポッドとサービスの両方が適切に展開されて使用可能なことを確認するには、次のコマンドを実行します。

kubectl get all

コンソールに次のように出力されるはずです。

kubectl get all
NAME                       READY   STATUS    RESTARTS   AGE
pod/read-6cbbb6678-58s9t   1/1     Running   0          3s
pod/read-6cbbb6678-kz7v4   1/1     Running   0          3s
pod/read-6cbbb6678-s2pct   1/1     Running   0          3s

NAME                                   TYPE           CLUSTER-IP   EXTERNAL-IP    PORT(S)          AGE
service/azure-cognitive-service-read   LoadBalancer   10.0.134.0   <none>         5000:30846/TCP   17h
service/kubernetes                     ClusterIP      10.0.0.1     <none>         443/TCP          78d

NAME                   READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/read   3/3     3            3           3s

NAME                             DESIRED   CURRENT   READY   AGE
replicaset.apps/read-6cbbb6678   3         3         3       3s

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

コンテナーが実行されていることを検証する方法は複数あります。 問題になっているコンテナーの "外部 IP" アドレスと公開ポートを特定し、任意の Web ブラウザーを開きます。 以下に示した各種の要求 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 Kubernetes Service (AKS) での Helm を使用したアプリケーションのインストールについて詳しくは、こちらをご覧ください