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

[アーティクル]
02/27/2024

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

前提条件

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

必須	目的
Azure アカウント	Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
Kubernetes CLI	コンテナーレジストリからの共有資格情報を管理するには、Kubernetes CLI が必要です。また、Kubernetes は、Kubernetes のパッケージマネージャーである Helm の前に必要です。
Helm CLI	Helm Chart (コンテナーパッケージ定義) のインストールに使用される Helm CLI をインストールします。
Computer Vision リソース	コンテナーを使用するためには、以下が必要です。 Computer Vision リソースとその関連する API キーおよびエンドポイント URI。どちらの値も、対象リソースの概要ページとキーページで使用でき、コンテナーを開始するために必要です。 {API_KEY} : [キー] ページにある 2 つの利用可能なリソースキーのどちらか {ENDPOINT_URI} : [概要] ページに提示されているエンドポイント

必須パラメーターの収集

すべての Azure AI コンテナーに対して 3 つの主要なパラメーターが必須です。 Microsoft ソフトウェアライセンス条項について、値 accept が示される必要があります。エンドポイント URI と API キーも必要です。

エンドポイント URL

{ENDPOINT_URI} の値は、対応する Azure AI サービスリソースの Azure portal の[概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウスを合わせると、[クリップボードにコピー] アイコンが表示されます。必要に応じて、エンドポイントをコピーして使用します。

後で使用するためのエンドポイント URI の収集を示すスクリーンショット。

キー

{API_KEY} の値はコンテナーを起動するために使用され、Azure portal で、対応する Azure AI サービスリソースの [キー] ページで入手できます。 [キー] ページに移動し、[クリップボードにコピー] アイコンを選択します。

後で使用するための 2 つのキーのいずれかの取得を示すスクリーンショット。

重要

これらのサブスクリプションキーは、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 にデプロイする」をご覧ください。

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

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 の設定に対応します。

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 要求コンテナーは同じではない可能性があるため、外部キャッシュによって結果が格納され、コンテナーとの間で共有されます。キャッシュ設定の詳細については、「Azure AI 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 テンプレートの生成に役立つ便利な関数が定義されています。

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

{{- define "redis.connStr" -}}
{{- $hostMain := printf "%s-redis-master:6379" .Release.Name }}
{{- $hostReplica := printf "%s-redis-replica: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 チャート" では、Azure AI Vision サービスと対応するサービスの Docker イメージが、mcr.microsoft.com コンテナーレジストリからプルされます。

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

Helm Chart をインストールするには、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 コンテナーを展開し、共通のストレージとキューをコンテナーに共有させます。

Note

現在のところ、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 で要求することで、この 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 コマンドが得られます。

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

次のステップ

Azure Kubernetes Service (AKS) での Helm を使用したアプリケーションのインストールについて詳しくは、こちらをご覧ください。

Azure AI コンテナー