Kubernetes 및 Helm과 함께 Azure AI 비전 컨테이너 사용
온-프레미스에서 Azure AI 비전 컨테이너를 관리하는 한 가지 옵션은 Kubernetes 및 Helm을 사용하는 것입니다. Kubernetes 및 Helm을 사용하여 Azure AI 비전 컨테이너 이미지를 정의하고 Kubernetes 패키지를 만듭니다. 이 패키지는 Kubernetes 클러스터 온-프레미스에 배포됩니다. 마지막으로 배포된 서비스를 테스트하는 방법을 살펴보겠습니다. Kubernetes 오케스트레이션을 사용하지 않고 Docker 컨테이너를 실행하는 방법에 대한 자세한 내용은 Azure AI 비전 컨테이너 설치 및 실행을 참조하세요.
필수 조건
온-프레미스에서 Azure AI 비전 컨테이너를 사용하기 전에 다음 필수 구성 요소를 충족해야 합니다.
| Required | 목적 |
|---|---|
| Azure 계정 | Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다. |
| Kubernetes CLI | Kubernetes CLI는 컨테이너 레지스트리에서 공유 자격 증명을 관리하는 데 필요합니다. Kubernetes는 Kubernetes 패키지 관리자인 Helm 이전에도 필요합니다. |
| Helm CLI | Helm 차트(컨테이너 패키지 정의)를 설치하는 데 사용되는 Helm CLI를 설치합니다. |
| Computer Vision 리소스 | 컨테이너를 사용하려면 다음이 있어야 합니다. Computer Vision 리소스 및 관련 API 키 엔드포인트 URI입니다. 두 값은 모두 리소스의 개요 및 키 페이지에서 제공되며 컨테이너를 시작하는 데 필요합니다. {API_KEY}: 키 페이지에 제공된 두 개의 리소스 키 중 하나 {ENDPOINT_URI}: 개요 페이지에 제공된 엔드포인트 |
필수 매개 변수 수집
모든 Azure AI 컨테이너에는 세 가지 기본 매개 변수가 필요합니다. Microsoft Software 사용 조건에는 동의 값이 있어야 합니다. 엔드포인트 URI 및 API 키도 필요합니다.
엔드포인트 URI
{ENDPOINT_URI} 값은 해당 Azure AI 서비스 리소스의 Azure Portal 개요 페이지에서 확인할 수 있습니다. 개요 페이지로 이동하여 마우스로 엔드포인트 위를 가리키면 클립보드로 복사 아이콘이 표시됩니다. 필요한 경우 엔드포인트를 복사하여 사용합니다.
구성
{API_KEY} 값은 컨테이너를 시작하는 데 사용되며 해당 Azure AI 서비스 리소스에 대한 Azure portal의 키 페이지에서 사용할 수 있습니다. 키 페이지로 이동하여 클립보드로 복사 아이콘을 선택합니다.
Important
이러한 구독 키는 Azure AI 서비스 API에 액세스하는 데 사용됩니다. 키를 공유하지 마세요. 안전하게 저장하세요. 예를 들어 Azure Key Vault를 사용합니다. 또한 이러한 키를 정기적으로 다시 생성하는 것이 좋습니다. API 호출을 수행하는 데는 키가 하나만 필요합니다. 첫 번째 키를 다시 생성하는 경우 두 번째 키를 사용하여 서비스에 계속 액세스할 수 있습니다.
호스트 컴퓨터
호스트는 Docker 컨테이너를 실행하는 x64 기반 컴퓨터입니다. 다음과 같이 Azure에서 컴퓨터 온-프레미스 또는 Docker 호스팅 서비스일 수 있습니다.
- Azure Kubernetes Service.
- Azure Container Instances.
- Kubernetes 클러스터는 Azure Stack에 배포됩니다. 자세한 내용은 Azure Stack에 Kubernetes 배포를 참조하세요.
컨테이너 요구 사항 및 추천
참고 항목
요구 사항 및 권장 사항은 초당 단일 요청을 포함하는 벤치마크를 기준으로 하며, 523KB의 스캔된 비즈니스 문자 이미지를 사용하여 29개 줄과 총 803 문자를 포함합니다. 권장 구성으로 인해 최소 구성에 비해 응답 속도가 약 2배 더 빨라집니다.
다음 표에서는 각 Read OCR 컨테이너에 대한 최소 및 권장 리소스 할당을 설명합니다.
| Container | 최소 | 권장 |
|---|---|---|
| Read 3.2 2022-04-30 | 4개 코어, 8GB 메모리 | 8 코어, 16-GB 메모리 |
| Read 3.2 2021-04-12 | 4개 코어, 16GB 메모리 | 8 코어, 24-GB 메모리 |
- 각 코어는 속도가 2.6GHz 이상이어야 합니다.
docker run 명령의 일부로 사용되는 --cpus 및 --memory 설정에 해당하는 코어 및 메모리.
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
Important
billing및apikey값이 제공되지 않은 경우 서비스는 15분 후에 만료됩니다. 마찬가지로 서비스를 사용할 수 없기 때문에 확인에 실패합니다.예를 들어 Docker Compose 또는 Kubernetes에서 부하 분산 장치 뒤에 여러 Read 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 서버, 데이터베이스, 캐시 등이 포함된 전체 웹앱 스택과 같이 복잡한 항목을 배포할 수 있습니다.
제공된 Helm 차트는 Azure AI 비전 서비스의 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 배포를 완료하는 데 몇 분 정도 걸릴 수 있습니다. 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 Storage 및 Azure Queue만 지원됩니다.
요청을 수신하는 컨테이너는 작업을 단일 페이지 하위 작업으로 분할하고, 범용 큐에 추가할 수 있습니다. 사용량이 적은 컨테이너의 모든 인식 작업자는 큐의 단일 페이지 하위 작업을 사용하고, 인식을 수행하고, 결과를 스토리지에 업로드할 수 있습니다. 처리량은 배포된 컨테이너 수에 따라 최대 n배까지 향상될 수 있습니다.
v3 컨테이너는 /ContainerLiveness 경로 아래에 활동성 프로브 API를 노출합니다. 다음 배포 예제를 사용하여 Kubernetes에 대한 활동성 프로브를 구성합니다.
다음 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 배포를 완료하는 데 몇 분 정도 걸릴 수 있습니다. 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 |
컨테이너는 엔드포인트에 대한 전체 설명서 세트와 사용해 보기 기능을 제공합니다. 이 기능을 사용하면 웹 기반 HTML 양식으로 설정을 입력할 수 있고 코드 작성 없이 쿼리를 만들 수 있습니다. 쿼리가 반환되면 필요한 HTTP 헤더 및 본문 형식을 보여주기 위해 예제 CURL 명령이 제공됩니다. |
다음 단계
AKS(Azure Kubernetes Service)에서 Helm을 사용하여 애플리케이션을 설치하는 방법에 대한 자세한 내용은 여기를 참조하세요.