Utilizar o contentor do Azure AI Vision com o Kubernetes e o Helm

Artigo
02/27/2024

Uma opção para gerir os contentores do Azure AI Vision no local é utilizar o Kubernetes e o Helm. Com o Kubernetes e o Helm para definir uma imagem de contentor do Azure AI Vision, vamos criar um pacote do Kubernetes. Este pacote será implementado num cluster do Kubernetes no local. Por fim, vamos explorar como testar os serviços implementados. Para obter mais informações sobre como executar contentores do Docker sem orquestração do Kubernetes, veja Instalar e executar contentores do Azure AI Vision.

Pré-requisitos

Os seguintes pré-requisitos antes de utilizar contentores do Azure AI Vision no local:

Necessário	Objetivo
Conta do Azure	Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Kubernetes CLI	A CLI do Kubernetes é necessária para gerir as credenciais partilhadas a partir do registo de contentor. O Kubernetes também é necessário antes do Helm, que é o gestor de pacotes do Kubernetes.
Helm CLI	Instale a CLI do Helm, que é utilizada para instalar um gráfico helm (definição de pacote de contentor).
Imagem Digitalizada recurso	Para utilizar o contentor, tem de ter: Um recurso Imagem Digitalizada e a chave de API associada ao URI do ponto final. Ambos os valores estão disponíveis nas páginas Descrição Geral e Chaves do recurso e são necessários para iniciar o contentor. {API_KEY}: Uma das duas chaves de recursos disponíveis na página Chaves {ENDPOINT_URI}: O ponto final conforme fornecido na página Descrição geral

Recolher os parâmetros necessários

São necessários três parâmetros principais para todos os contentores de IA do Azure. Os Termos de Licenciamento para Software Microsoft têm de estar presentes com um valor de aceitação. Também é necessário um URI de Ponto Final e uma chave de API.

URI do ponto final

O {ENDPOINT_URI} valor está disponível na página Descrição geral do portal do Azure do recurso de serviços de IA do Azure correspondente. Aceda à página Descrição geral , paire o cursor sobre o ponto final e é apresentado um ícone Copiar para a área de transferência . Copie e utilize o ponto final sempre que necessário.

Captura de ecrã que mostra a recolha do URI do ponto final para utilização posterior.

Chaves

O {API_KEY} valor é utilizado para iniciar o contentor e está disponível na página Chaves do portal do Azure do recurso de serviços do Azure AI correspondente. Aceda à página Chaves e selecione o ícone Copiar para a área de transferência .

Captura de ecrã que mostra a obtenção de uma das duas chaves para utilização posterior.

Importante

Estas chaves de subscrição são utilizadas para aceder à sua API de serviços de IA do Azure. Não partilhe as suas chaves. Armazene-os de forma segura. Por exemplo, utilize o Azure Key Vault. Também recomendamos que volte a gerar estas chaves regularmente. Só é necessária uma chave para fazer uma chamada à API. Quando regenerar a primeira chave, pode utilizar a segunda chave para continuar a aceder ao serviço.

O computador anfitrião

O anfitrião é um computador baseado em x64 que executa o contentor do Docker. Pode ser um computador no local ou um serviço de alojamento do Docker no Azure, como:

Azure Kubernetes Service.
Azure Container Instances.
Um cluster do Kubernetes implementado no Azure Stack. Para obter mais informações, veja Implementar o Kubernetes no Azure Stack.

Requisitos e recomendações de contentores

Nota

Os requisitos e recomendações baseiam-se em referências com um único pedido por segundo, utilizando uma imagem de 523 KB de uma carta de negócio digitalizada que contém 29 linhas e um total de 803 carateres. A configuração recomendada resultou numa resposta aproximadamente 2x mais rápida em comparação com a configuração mínima.

A tabela seguinte descreve a alocação mínima e recomendada de recursos para cada contentor OCR de Leitura.

Contentor	Mínimo	Recomendado
Ler 3.2 2022-04-30	4 núcleos, 8 GB de memória	8 núcleos, 16 GB de memória
Ler 3.2 2021-04-12	4 núcleos, 16 GB de memória	8 núcleos, 24 GB de memória

Cada núcleo tem de ter, pelo menos, 2,6 gigahertz (GHz) ou mais rápido.

O núcleo e a memória correspondem às --cpus definições e --memory , que são utilizadas como parte do docker run comando .

Ligar ao cluster do Kubernetes

Espera-se que o computador anfitrião tenha um cluster do Kubernetes disponível. Veja este tutorial sobre como implementar um cluster do Kubernetes para obter uma compreensão conceptual de como implementar um cluster do Kubernetes num computador anfitrião. Pode encontrar mais informações sobre implementações na documentação do Kubernetes.

Configurar valores do gráfico Helm para implementação

Comece por criar uma pasta com o nome read. Em seguida, cole o seguinte conteúdo YAML num novo ficheiro com o nome 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/

Para configurar os valores predefinidos do gráfico Helm, copie e cole o seguinte YAML num ficheiro com o nome values.yaml. Substitua os # {ENDPOINT_URI} comentários e # {API_KEY} pelos seus próprios valores. Configure resultExpirationPeriod, Redis e RabbitMQ, se necessário.

# 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

Importante

Se os billing valores e apikey não forem fornecidos, os serviços expiram após 15 minutos. Da mesma forma, a verificação falha porque os serviços não estão disponíveis.
Se implementar vários contentores OCR de Leitura atrás de um balanceador de carga, por exemplo, em Docker Compose ou Kubernetes, tem de ter uma cache externa. Uma vez que o contentor de processamento e o contentor de pedidos GET podem não ser os mesmos, uma cache externa armazena os resultados e partilha-os entre contentores. Para obter detalhes sobre as definições de cache, veja Configurar contentores do Docker do Azure AI Vision.

Crie uma pasta de modelos no diretório de leitura . Copie e cole o seguinte YAML num ficheiro com o nome deployment.yaml. O deployment.yaml ficheiro servirá como um modelo do Helm.

Os modelos geram ficheiros de manifesto, que são descrições de recursos formatadas com YAML que o Kubernetes pode compreender. - Guia do Modelo de Gráfico 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

Na mesma pasta de modelos , copie e cole as seguintes funções auxiliares no helpers.tpl. helpers.tpl define funções úteis para ajudar a gerar o modelo 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 -}}

O modelo especifica um serviço de balanceador de carga e a implementação do contentor/imagem para Leitura.

O pacote do Kubernetes (gráfico Helm)

O gráfico Helm contém a configuração das imagens do Docker a solicitar do mcr.microsoft.com registo de contentor.

Um gráfico Helm é uma coleção de ficheiros que descrevem um conjunto relacionado de recursos do Kubernetes. Um único gráfico pode ser utilizado para implementar algo simples, como um pod memcached ou algo complexo, como uma pilha de aplicações Web completa com servidores HTTP, bases de dados, caches, etc.

Os gráficos Helm fornecidos extraem as imagens do docker do Serviço de Visão de IA do Azure e o serviço correspondente do mcr.microsoft.com registo de contentor.

Instalar o gráfico Helm no cluster do Kubernetes

Para instalar o gráfico helm, teremos de executar o helm install comando . Certifique-se de que executa o comando de instalação a partir do diretório acima da read pasta.

helm install read ./read

Eis um resultado de exemplo que poderá esperar ver a partir de uma execução de instalação bem-sucedida:

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

A implementação do Kubernetes pode demorar vários minutos a concluir. Para confirmar que os pods e os serviços estão corretamente implementados e disponíveis, execute o seguinte comando:

kubectl get all

Deverá ver algo semelhante ao seguinte resultado:

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

Implementar vários contentores v3 no cluster do Kubernetes

A partir da v3 do contentor, pode utilizar os contentores em paralelo ao nível da tarefa e da página.

Por predefinição, cada contentor v3 tem um distribuidor e uma função de trabalho de reconhecimento. O despachante é responsável por dividir uma tarefa de várias páginas em múltiplas subtarefas de página única. A função de trabalho de reconhecimento está otimizada para reconhecer um documento de página única. Para alcançar o paralelismo ao nível da página, implemente vários contentores v3 atrás de um balanceador de carga e permita que os contentores partilhem um armazenamento e uma fila universais.

Nota

Atualmente, só são suportados o Armazenamento do Azure e a Fila do Azure.

O contentor que recebe o pedido pode dividir a tarefa em subtarefas de página única e adicioná-las à fila universal. Qualquer função de trabalho de reconhecimento de um contentor menos ocupado pode consumir subtarefas de página única da fila, efetuar reconhecimento e carregar o resultado para o armazenamento. O débito pode ser melhorado até n vezes, dependendo do número de contentores que são implementados.

O contentor v3 expõe a API de pesquisa de liveness no /ContainerLiveness caminho. Utilize o seguinte exemplo de implementação para configurar uma sonda liveness para o Kubernetes.

Copie e cole o seguinte YAML num ficheiro com o nome deployment.yaml. Substitua os # {ENDPOINT_URI} comentários e # {API_KEY} pelos seus próprios valores. Substitua o comentário pela # {AZURE_STORAGE_CONNECTION_STRING} Cadeia de Ligação do Armazenamento do Azure. Configure replicas para o número que pretende, que está definido como 3 no exemplo seguinte.

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

Execute o seguinte comando.

kubectl apply -f deployment.yaml

Segue-se um exemplo de saída que poderá ver a partir de uma execução de implementação bem-sucedida:

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

A implementação do Kubernetes pode demorar vários minutos a ser concluída. Para confirmar que os pods e os serviços estão corretamente implementados e disponíveis, execute o seguinte comando:

kubectl get all

Deverá ver um resultado da consola semelhante ao seguinte:

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

Validar que um contentor está em execução

Existem várias formas de validar que o contentor está em execução. Localize o Endereço IP externo e a porta exposta do contentor em questão e abra o seu browser favorito. Utilize os vários URLs de pedido que se seguem para validar que o contentor está em execução. Os URLs de pedido de exemplo listados aqui são http://localhost:5000, mas o contentor específico pode variar. Certifique-se de que depende do endereço IP externo do contentor e da porta exposta.

URL do Pedido	Objetivo
`http://localhost:5000/`	O contentor fornece uma home page.
`http://localhost:5000/ready`	Pedido com GET, este URL fornece uma verificação de que o contentor está pronto para aceitar uma consulta em relação ao modelo. Este pedido pode ser utilizado para pesquisas de liveness e preparação do Kubernetes.
`http://localhost:5000/status`	Também solicitado com GET, este URL verifica se a chave de API utilizada para iniciar o contentor é válida sem causar uma consulta de ponto final. Este pedido pode ser utilizado para pesquisas de liveness e preparação do Kubernetes.
`http://localhost:5000/swagger`	O contentor fornece um conjunto completo de documentação para os pontos finais e uma funcionalidade Experimentar. Com esta funcionalidade, pode introduzir as suas definições num formulário HTML baseado na Web e fazer a consulta sem ter de escrever código. Após a devolução da consulta, é fornecido um comando CURL de exemplo para demonstrar os cabeçalhos HTTP e o formato do corpo necessários.

Home page do contentor

Passos seguintes

Para obter mais detalhes sobre como instalar aplicações com o Helm no Azure Kubernetes Service (AKS), visite aqui.

Contentores de IA do Azure