搭配 Kubernetes 和 Helm 使用 Azure AI 視覺容器
於內部管理 Azure AI 視覺容器的選項之一，是使用 Kubernetes 和 Helm。 使用 Kubernetes 和 Helm 定義 Azure AI 視覺容器映像時，我們將建立 Kubernetes 套件。 此套件將會部署到內部部署的 Kubernetes 叢集。 最後，我們將探索如何測試已部署的服務。 如需執行不含 Kubernetes 協調流程的 Docker 容器詳細資訊，請參閱安裝並執行 Azure AI 視覺容器。
必要條件
於內部使用 Azure AI 視覺容器之前的必要條件如下：
| 必要 | 目的 |
|---|---|
| Azure 帳戶 | 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。 |
| Kubernetes CLI | 需要 Kubernetes CLI 才能管理容器登錄中的共用認證。 Helm (也就是 Kubernetes 套件管理員) 之前也需要 Kubernetes。 |
| Helm CLI | 安裝 Helm CLI，而這用來安裝 Helm 圖表 (容器套件定義)。 |
| 電腦視覺資源 | 若要使用此容器，您必須具備： 電腦視覺資源和相關聯的 API 金鑰 (端點 URI)。 這兩個值都可在資源的 [概觀] 和 [金鑰] 頁面上取得，需要這些值才能啟動容器。 {API_KEY}：「金鑰」頁面上兩個可用資源金鑰的其中一個 {ENDPOINT_URI}：「概觀」頁面上提供的端點 |
收集必要參數
所有 Azure AI 容器都需要三個主要參數。 Microsoft 軟體授權條款必須具有「接受」值。 也需要端點 URI 和 API 金鑰。
端點 URI
{ENDPOINT_URI} 值可在相對應 Azure AI 服務資源的 Azure 入口網站 [概觀] 頁面上取得。 移至 [概觀] 頁面，並將滑鼠停留在端點上方，[複製至剪貼簿] 圖示隨即出現。 複製端點，並將其用在需要之處。
索引鍵
{API_KEY} 值可用來啟動容器，並可在相對應 Azure AI 服務資源的 Azure 入口網站 [金鑰] 頁面上取得。 移至 [金鑰] 頁面，然後選取 [複製至剪貼簿] 圖示。
重要
這些訂用帳戶金鑰可用於存取 Azure AI 服務 API。 請不要共用您的金鑰。 安全地儲存金鑰。 例如，使用 Azure Key Vault。 我們也建議您定期重新產生這些金鑰。 呼叫 API 只需一把金鑰。 重新產生第一個金鑰時，您可以使用第二個金鑰繼續存取服務。
主機電腦
主機是執行 Docker 容器的 x64 型電腦。 它可以是您內部部署的電腦，或是在 Azure 中裝載服務的 Docker，例如：
- Azure Kubernetes Service。
- Azure 容器執行個體。
- 部署至 Azure Stack 的 Kubernetes \(英文\) 叢集。 如需詳細資訊，請參閱將 Kubernetes 部署至 Azure Stack。
容器的需求和建議
注意
這些需求和建議是以每秒單一要求的基準為基礎，使用已掃描商務信件的 523 KB 映像 (包含 29 行，共 803 個字元)。 相較於最低設定，建議設定的回應速度大約是 2 倍。
下表說明每個讀取 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 或更快。
核心和記憶體會對應至 --cpus 和 --memory 設定，用來作為 docker run 命令的一部分。
連線至 Kubernetes 叢集
主機電腦預期有一個可用的 Kubernetes 叢集。 請參閱此教學課程的部署 Kubernetes 叢集，以了解如何將 Kubernetes 叢集部署到主機電腦的概念。 您可以在 Kubernetes 文件中找到部署的詳細資訊。
設定用於部署的 Helm 圖表值
首先，建立名為 read 的資料夾。 然後，在名為 chart.yaml 的新檔案中貼上下列 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) 後部署多個讀取 OCR 容器，則您必須有外部快取。 因為處理容器和 GET 要求容器可能不同，所以外部快取會儲存結果，並在容器之間共用這些結果。 如需快取設定的詳細資料，請參閱設定 Azure AI 視覺 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 資源。 單一圖表可用來部署簡易的項目 (例如 Memcached Pod) 或複雜的項目 (例如包含 HTTP 伺服器、資料庫、快取等的完整 Web 應用程式堆疊)。
提供的「Helm 圖表」會提取 Azure AI 視覺服務的 Docker 映像，以及 mcr.microsoft.com 容器登錄中的對應服務。
在 Kubernetes 叢集上安裝 Helm 圖表
若要安裝「Helm 圖表」，我們必須執行 helm install 命令。 請確定從 read 資料夾上方的目錄執行安裝命令。
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 部署可能需要幾分鐘的時間才能完成。 若要確認 Pod 和服務都已正確部署且可供使用，請執行下列命令：
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 容器都有發送器和辨識背景工作角色。 發送器會負責將多頁工作分割成多個單一頁面子工作。 辨識背景工作角色已針對辨識單一頁面文件最佳化。 若要達到頁面層級平行處理原則，請在負載平衡器後方部署多個 v3 容器，並讓容器共用通用儲存體和佇列。
注意
目前僅支援 Azure 儲存體和 Azure 佇列。
接收要求的容器可以將工作分割成單一頁面子工作，並將其新增至通用佇列。 任何來自較不忙碌容器的辨識背景工作角色，都可以從佇列取用單一頁面子工作、執行辨識，然後將結果上傳至儲存體。 視部署的容器數目而定，輸送量可以提升最多 n 倍。
v3 容器會公開 /ContainerLiveness 路徑底下的活躍度探查 API。 使用下列部署範例來設定 Kubernetes 的活躍度探查。
將下列 YAML 複製並貼到名為 deployment.yaml 的檔案。 以您自己的值取代 # {ENDPOINT_URI} 和 # {API_KEY} 註解。 以您的 Azure 儲存體連接字串取代 # {AZURE_STORAGE_CONNECTION_STRING} 註解。 將 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 部署可能需要幾分鐘的時間才能完成。 若要確認 Pod 和服務都已正確部署且可供使用，請執行下列命令：
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 位址和公開的連接埠，然後開啟您最愛的網頁瀏覽器。 使用下列各項要求 URL，以驗證容器是否正在執行。 此處列出的範例要求 URL 為 http://localhost:5000，但您的特定容器可能會有所不同。 請務必依賴您容器的「外部 IP」 位址和公開的連接埠。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
容器會提供首頁。 |
http://localhost:5000/ready |
以 GET 提出要求，此 URL 將會驗證容器是否已準備好接受對模型的查詢。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/status |
也會以 GET 提出要求，此 URL 會在不需進行端點查詢的同時，確認用來啟動容器的 API 金鑰是否有效。 此要求可用來進行 Kubernetes 活躍度和整備度探查 \(英文\)。 |
http://localhost:5000/swagger |
容器會為端點提供一組完整的文件和立即試用功能。 使用此功能，您可以將自己的設定輸入至以 Web 為基礎的 HTML 表單並進行查詢，而無須撰寫任何程式碼。 當查詢傳回時，會提供範例 CURL 命令來示範所需的 HTTP 標頭和本文格式。 |
下一步
如需在 Azure Kubernetes Service (AKS) 中使用 Helm 安裝應用程式的詳細資訊，請瀏覽這裡。
意見反映
即將推出：我們會在 2024 年淘汰 GitHub 問題，並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交及檢視以下的意見反映：