Kubernetes と Helm と共に Azure AI Vision コンテナーを使用する
オンプレミスの 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 portal の対応する Azure AI サービス リソースの [概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウス ポインターを合わせると、[クリップボードにコピー] アイコンが表示されます。 必要に応じて、エンドポイントをコピーして使用します。
キー
{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 にデプロイする」をご覧ください。
コンテナーの要件と推奨事項
注意
要件と推奨事項は、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 を使用したアプリケーションのインストールについて詳しくは、こちらをご覧ください。