Solução Jump Start: processamento de imagens de IA/ML no Cloud Functions

Last reviewed 2023-08-29 UTC

Neste guia, ajudamos você a entender, implantar e usar a Solução de início rápido de processamento de imagem de IA/ML no Cloud Functions. Nesta solução, são usados modelos de machine learning pré-treinados para analisar imagens fornecidas por usuários e gerar anotações de imagens.

A implantação dessa solução cria um serviço de processamento de imagens que pode ajudar você a fazer o seguinte e muito mais:

Lidar com conteúdo não seguro ou nocivo gerado pelo usuário.
Digitalizar o texto de documentos físicos.
Detectar e classificar objetos em imagens.

Este documento é destinado a desenvolvedores familiarizados com desenvolvimento de serviços de back-end, recursos de IA/ML e conceitos básicos de computação em nuvem. Embora não seja obrigatório, a experiência com o Terraform é útil.

Objetivos

Saiba como uma arquitetura sem servidor é usada para criar um serviço de processamento de imagem escalonável.
Entenda como o serviço de processamento de imagens usa modelos de machine learning pré-treinados para análise de imagens.
Implante o serviço de processamento de imagem e invoque-o por meio de chamadas da API REST ou em resposta a eventos de upload de imagem.
Revise a configuração e as configurações de segurança para entender como adaptar o serviço de processamento de imagens a diferentes necessidades.

Produtos usados

A solução usa os seguintes produtos do Google Cloud:

API Cloud Vision: uma API que oferece modelos avançados de machine learning pré-treinados para anotação de imagens. A solução usa a API Cloud Vision para analisar imagens e conseguir dados de anotação de imagem.
Cloud Storage: um serviço pronto para empresas que oferece armazenamento de objetos de baixo custo e sem limite para diversos tipos de dados. Os dados podem ser acessados de dentro e de fora do Google Cloud e são replicados geograficamente de modo redundante. A solução usa o Cloud Storage para armazenar imagens de entrada e dados de anotação de imagens resultantes.
Cloud Functions: um serviço de computação leve sem servidor que permite criar funções autônomas de finalidade única que podem responder a eventos do Google Cloud sem a necessidade de gerenciar um servidor ou um ambiente de execução. (em inglês). A solução usa o Cloud Functions para hospedar os endpoints do serviço de processamento de imagem.

Para informações sobre como esses produtos são configurados e como eles interagem, consulte a próxima seção.

Arquitetura

A solução consiste em um exemplo de serviço de processamento de imagens que analisa imagens de entrada e gera anotações para as imagens usando modelos de machine learning pré-treinados. O diagrama a seguir mostra a arquitetura dos recursos do Google Cloud usados na solução.

Arquitetura da infraestrutura necessária para o processamento de imagens de IA/ML na solução do Cloud Functions.

O serviço pode ser invocado de duas maneiras: diretamente por chamadas da API REST ou indiretamente em resposta a uploads de imagem.

Fluxo da solicitação

O fluxo de processamento de solicitações do serviço de processamento de imagens depende de como os usuários invocam o serviço. As etapas a seguir são numeradas conforme mostrado no diagrama de arquitetura anterior.

Quando o usuário invoca o serviço de processamento de imagem diretamente por meio de uma chamada da API REST:

O usuário faz uma solicitação para o endpoint da API REST do serviço de processamento de imagens, implantado como uma Função do Cloud. A solicitação especifica uma imagem como um URI ou um stream codificado em base64.
A Função do Cloud faz uma chamada à API Cloud Vision para gerar anotações para a imagem especificada. Os dados da anotação de imagem são retornados no formato JSON na resposta da função ao usuário.

Quando o usuário invoca o serviço de processamento de imagens indiretamente em resposta aos uploads de imagem:

O usuário faz upload de imagens para um bucket do Cloud Storage para entrada.
Cada upload de imagem gera um evento do Cloud Storage que aciona uma Função do Cloud para processar a imagem enviada.
A Função do Cloud faz uma chamada à API Cloud Vision para gerar anotações para a imagem especificada.
A Função do Cloud grava os dados de anotação de imagem como um arquivo JSON em outro bucket do Cloud Storage para saída.

Custo

Para uma estimativa dos custos dos recursos do Google Cloud usados pelo processamento de imagem de IA/ML no Cloud Functions, consulte a estimativa pré-calculada na calculadora de preços do Google Cloud.

Use a estimativa como um ponto de partida para calcular o custo da implantação. É possível modificar a estimativa para refletir as alterações de configuração planejadas para os recursos usados na solução.

A estimativa pré-calculada tem como base suposições específicas, incluindo o seguinte:

Os locais do Google Cloud em que os recursos são implantados.
A quantidade de tempo em que os recursos são usados.
A quantidade de dados armazenados no Cloud Storage.
O número de vezes que o serviço de processamento de imagem é invocado.

Antes de começar

Para implantar essa solução, primeiro você precisa de um projeto do Google Cloud e de algumas permissões do IAM.

Criar ou escolher um projeto do Google Cloud

Ao implantar a solução, escolha o projeto do Google Cloud em que os recursos serão implantados. Ao decidir entre usar um projeto existente ou criar um, considere os seguintes fatores:

Se você criar um projeto para a solução, quando não precisar mais da implantação, será possível excluir o projeto e evitar o faturamento contínuo. Se você usar um projeto existente, será preciso excluir a implantação quando não precisar mais dela.
Usar um novo projeto pode ajudar a evitar conflitos com recursos provisionados anteriormente, como recursos usados em cargas de trabalho de produção.

Se você quiser implantar a solução em um novo projeto, crie o projeto antes de iniciar a implantação.

Para criar um projeto, siga estas etapas:

No console do Google Cloud, acesse a página do seletor de projetos.

Acessar o seletor de projetos
Para começar a criar um projeto do Google Cloud, clique em Criar projeto.
Escolha o nome do projeto. Anote o código do projeto gerado.
Edite os outros campos conforme necessário.
Para criar o projeto, clique em Criar.

Receber as permissões de IAM necessárias

Para iniciar o processo de implantação, você precisa das permissões do Identity and Access Management (IAM) listadas na tabela a seguir. Se você tem o papel básico roles/owner no projeto em que planeja implantar a solução, você já tem todas as permissões necessárias. Se você não tiver o papel roles/owner, peça ao administrador para conceder essas permissões (ou os papéis que as incluam) a você.

Permissão do IAM necessária	Papel predefinido que inclui as permissões necessárias
`serviceusage.services.enable`	Administrador do Service Usage (`roles/serviceusage.serviceUsageAdmin`)
`iam.serviceAccounts.create`	Administrador da conta de serviço (`roles/iam.serviceAccountAdmin`)
`resourcemanager.projects.setIamPolicy`	Administrador de projetos do IAM (`roles/resourcemanager.projectIamAdmin`)
`config.deployments.create` `config.deployments.list`	Administrador do Cloud Infrastructure Manager (`roles/config.admin`)

Conta de serviço criada para a solução

Se você iniciar o processo de implantação pelo console, o Google criará uma conta de serviço para implantar a solução em seu nome (e excluir a implantação mais tarde, se você quiser). Essa conta de serviço recebe determinadas permissões do IAM temporariamente, ou seja, as permissões são revogadas automaticamente após a conclusão das operações de implantação e exclusão da solução. O Google recomenda que, após a exclusão da implantação, você exclua a conta de serviço, conforme descrito mais adiante neste guia.

Ver os papéis atribuídos à conta de serviço

Esses papéis são listados aqui caso um administrador do projeto ou da organização do Google Cloud precise dessas informações.

roles/serviceusage.serviceUsageAdmin
roles/iam.serviceAccountAdmin
roles/resourcemanager.projectIamAdmin
roles/cloudfunctions.admin
roles/run.admin
roles/storage.admin
roles/pubsublite.admin
roles/iam.securityAdmin
roles/logging.admin
roles/artifactregistry.reader
roles/cloudbuild.builds.editor
roles/compute.admin
roles/iam.serviceAccountUser

Implantar a solução

Esta seção orienta você no processo de implantação da solução.

Para ajudar você a implantar essa solução com esforço mínimo, é fornecida uma configuração do Terraform no GitHub. A configuração do Terraform define todos os recursos do Google Cloud necessários para a solução.

É possível implantar a solução usando um dos seguintes métodos:

Pelo console: use esse método se quiser testar a solução com a configuração padrão e ver como ela funciona. O Cloud Build implanta todos os recursos necessários para a solução. Quando você não precisar mais da solução implantada, será possível excluí-la no console. Todos os recursos criados depois da implantação da solução talvez precisem ser excluídos separadamente.

Para usar esse método de implantação, siga as instruções em Implantar no console.
Com a CLI do Terraform: use esse método se quiser personalizar a solução ou automatizar o provisionamento e o gerenciamento dos recursos usando a abordagem de infraestrutura como código (IaC). Faça o download da configuração do Terraform no GitHub, personalize o código conforme necessário e implante a solução usando a CLI do Terraform. Depois de implantar a solução, é possível continuar a usar o Terraform para gerenciá-la.

Para usar esse método de implantação, siga as instruções em Implantar usando a CLI do Terraform.

Implantar pelo console

Conclua as etapas a seguir para implantar a solução pré-configurada.

No catálogo de soluções do Google Cloud Jump Start, acesse a solução de processamento de imagens de IA/ML no Cloud Functions.

Acessar a solução de processamento de imagens de IA/ML no Cloud Functions
Revise as informações fornecidas na página, como o custo estimado da solução e o tempo estimado de implantação.
Quando estiver tudo pronto para começar a implantar a solução, clique em Implantar.

Veja um guia interativo passo a passo.
Conclua estas etapas no guia interativo.

Anote o nome inserido para a implantação. Ele será necessário depois de excluir a implantação.

Quando você clica em Implantar, a página Implantações da solução é exibida. O campo Status nesta página mostra Implantação.
Aguarde a solução ser implantada.

Se a implantação falhar, o campo Status vai mostrar Falha. Use o registro do Cloud Build para diagnosticar os erros. Para mais informações, consulte Erros ao implantar no console.

Depois que a implantação for concluída, o campo Status mudará para Implantado.
Para ver os recursos do Google Cloud implantados e as configurações deles, faça um tour interativo.

Iniciar o tour

Em seguida, para testar a solução por conta própria, consulte Explorar a solução.

Quando você não precisar mais da solução, exclua a implantação para evitar o faturamento contínuo dos recursos do Google Cloud. Para mais informações, consulte Excluir a implantação.

Implantar usando a CLI do Terraform

Nesta seção, descrevemos como personalizar a solução ou automatizar o provisionamento e o gerenciamento dela usando a CLI do Terraform. As soluções que você implanta usando a CLI do Terraform não são exibidas na página Implantações da solução no console do Google Cloud.

Configurar o cliente do Terraform

É possível executar o Terraform no Cloud Shell ou no seu host local. Neste guia, descrevemos como executar o Terraform no Cloud Shell, que tem o Terraform pré-instalado e configurado para autenticação com o Google Cloud.

O código do Terraform para esta solução está disponível em um repositório do GitHub.

Clone o repositório do GitHub no Cloud Shell.

Você verá um prompt para confirmar o download do repositório do GitHub para o Cloud Shell.
Clique em Confirmar.

O Cloud Shell é iniciado em uma guia separada do navegador, e o código do Terraform é transferido por download para o diretório $HOME/cloudshell_open do seu ambiente do Cloud Shell.
No Cloud Shell, verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Esse é o diretório que contém os arquivos de configuração do Terraform para a solução. Se você precisar mudar para esse diretório, execute o seguinte comando:
```
cd $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra
```
Inicialize o Terraform executando o seguinte comando:
```
terraform init
```
Aguarde até ver a seguinte mensagem:
```
Terraform has been successfully initialized!
```

Configurar as variáveis do Terraform

O código do Terraform que você salvou inclui variáveis que podem ser usadas para personalizar a implantação com base nos seus requisitos. Por exemplo, é possível especificar o projeto do Google Cloud e a região em que você quer que a solução seja implantada.

Verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Se não estiver, acesse esse diretório.
No mesmo diretório, crie um arquivo de texto chamado terraform.tfvars.
No arquivo terraform.tfvars, copie o snippet de código a seguir e defina valores para as variáveis necessárias.
- Siga as instruções fornecidas como comentários no snippet de código.
- Esse snippet de código inclui apenas as variáveis para as quais você precisa definir valores. A configuração do Terraform inclui outras variáveis que têm valores padrão. Para revisar todas as variáveis e os valores padrão, consulte o arquivo variables.tf disponível no diretório $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra.
- Verifique se cada valor definido no arquivo terraform.tfvars corresponde ao tipo da variável, conforme declarado no arquivo variables.tf. Por exemplo, se o tipo definido para uma variável no arquivo variables.tf for bool, especifique true ou false como o valor dessa variável no arquivo terraform.tfvars.
```
# This is an example of the terraform.tfvars file.
# The values in this file must match the variable types declared in variables.tf.
# The values in this file override any defaults in variables.tf.

# ID of the project in which you want to deploy the solution
project_id = "PROJECT_ID"
```

Validar e revisar a configuração do Terraform

Verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Se não estiver, acesse esse diretório.
Verifique se a configuração do Terraform não tem erros:
```
terraform validate
```
Se o comando retornar algum erro, faça as correções necessárias na configuração e execute o comando terraform validate novamente. Repita essa etapa até o comando retornar a seguinte mensagem:
```
Success! The configuration is valid.
```
Analise os recursos definidos na configuração:
```
terraform plan
```
Se você não tiver criado o arquivo terraform.tfvars conforme descrito anteriormente, o Terraform solicitará que você insira valores das variáveis que não têm valores padrão. Insira os valores obrigatórios.

A saída do comando terraform plan é uma lista dos recursos provisionados pelo Terraform quando você aplica a configuração.

Se você quiser fazer alterações, edite a configuração e execute os comandos terraform validate e terraform plan novamente.

Provisionar os recursos

Quando nenhuma outra alteração for necessária na configuração, implante os recursos:

Verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Se não estiver, acesse esse diretório.
Aplique a configuração do Terraform:
```
terraform apply
```
Se você não tiver criado o arquivo terraform.tfvars conforme descrito anteriormente, o Terraform solicitará que você insira valores das variáveis que não têm valores padrão. Insira os valores obrigatórios.

O Terraform exibe uma lista dos recursos que serão criados.
Quando for solicitado que você execute as ações, digite yes.

O Terraform exibe mensagens mostrando o progresso da implantação.

Se não for possível concluir a implantação, o Terraform exibirá os erros que causaram a falha. Analise as mensagens de erro e atualize a configuração para corrigi-los. Em seguida, execute o comando terraform apply novamente. Para receber ajuda com a solução de problemas do Terraform, consulte Erros ao implantar a solução usando a CLI do Terraform.

Depois que todos os recursos forem criados, o Terraform exibirá a seguinte mensagem:
```
Apply complete!
```
A saída do Terraform também inclui o URL do ponto de entrada do serviço de processamento de imagens, o nome do bucket de entrada do Cloud Storage para upload de imagens e o nome do bucket de saída do Cloud Storage que contém dados de anotação de imagem, conforme mostrado no exemplo de saída a seguir:
```
vision_annotations_gcs = "gs://vision-annotations-1234567890"
vision_input_gcs = "gs://vision-input-1234567890"
vision_prediction_url = [
  "https://annotate-http-abcde1wxyz-wn.a.run.app",
  "ingressIndex:0",
  "ingressValue:ALLOW_ALL",
  "isAuthenticated:false",
]
```
Para ver os recursos do Google Cloud implantados e as configurações deles, faça um tour interativo.

Iniciar o tour

Em seguida, você poderá explorar a solução e ver como ela funciona.

Quando você não precisar mais da solução, exclua a implantação para evitar o faturamento contínuo dos recursos do Google Cloud. Para mais informações, consulte Excluir a implantação.

Conhecer a solução

Nesta seção, você pode tentar usar a solução para vê-la em ação. O serviço de processamento de imagens pode ser chamado de duas maneiras: chamando a API REST diretamente ou fazendo upload de imagens para o bucket de entrada do Cloud Storage.

Invocar o serviço usando a API REST

Nos cenários em que você quer processar imagens de maneira síncrona em um fluxo de solicitação/resposta, use a API REST do serviço de processamento de imagens.

A função annotate-http implantada pela solução é o ponto de entrada para a API REST do serviço de processamento de imagens. O URL dessa função pode ser encontrado no console ou, se você a implantou usando a CLI do Terraform, na variável de saída vision_prediction_url. Esse URL de ponto de entrada expõe um endpoint chamado /annotate para fazer solicitações de processamento de imagem. O endpoint /annotate é compatível com solicitações GET e POST com os seguintes parâmetros:

Parâmetro	Descrição
`image`	(Somente solicitações `POST`) Conteúdo da imagem, enviado em formato binário ou especificado como dados de imagem codificados em base64.
`image_uri`	Um URI que aponta para uma imagem.
`features`	(Opcional) Uma lista separada por vírgulas de recursos de anotação da API Vision para solicitar. Os valores possíveis dos recursos são: `CROP_HINTS` `DOCUMENT_TEXT_DETECTION` `FACE_DETECTION` `IMAGE_PROPERTIES` `LABEL_DETECTION` `LANDMARK_DETECTION` `LOGO_DETECTION` `OBJECT_LOCALIZATION` `PRODUCT_SEARCH` `SAFE_SEARCH_DETECTION` `TEXT_DETECTION` `WEB_DETECTION`

Para especificar a imagem a ser analisada, inclua apenas um dos parâmetros image ou image_uri. Se você especificar ambos, image_uri será usado.

Por exemplo, para realizar a detecção de objetos em uma imagem com um URI da Internet, envie uma solicitação GET como a seguinte usando curl:

curl "YOUR_ENTRYPOINT_URL/annotate?features=OBJECT_LOCALIZATION&image_uri=YOUR_IMAGE_URI"

Como alternativa, para especificar o conteúdo da imagem diretamente usando um arquivo de imagem local, use uma solicitação POST como a seguinte:

curl -X POST -F image=@YOUR_IMAGE_FILENAME -F features=OBJECT_LOCALIZATION "YOUR_ENTRYPOINT_URL/annotate"

A resposta contém as anotações de imagem da API Vision no formato JSON.

Invocar o serviço usando o upload de imagens no Cloud Storage

Nos cenários em que você quer processar imagens de maneira assíncrona ou por upload em lote, use o acionador do Cloud Storage do serviço de processamento de imagens, que invoca automaticamente o serviço em resposta a uploads de imagens.

Siga as etapas para analisar imagens usando o acionador do Cloud Storage:

No console, acesse a página Buckets do Cloud Storage.

Acesse o Cloud Storage
Clique no nome do bucket de entrada (vision-input-ID) para acessar a página Detalhes do bucket.
Na guia Objetos, clique em Fazer upload de arquivos.
Selecione os arquivos de imagem que você quer analisar.
Após a conclusão do upload, volte para a página Buckets do Cloud Storage.

Acesse o Cloud Storage
Clique no nome do bucket de saída da anotação (vision-annotations-ID) para acessar a página Detalhes do bucket.
A guia Objetos contém um arquivo JSON separado para cada imagem enviada. Os arquivos JSON contêm os dados da anotação de cada imagem.

Observação: se um arquivo JSON correspondente não aparecer no bucket de saída da anotação, aguarde um pouco para que o processamento da imagem seja concluído e atualize a página.

Personalizar a solução

Nesta seção, fornecemos informações que os desenvolvedores do Terraform podem usar para modificar o processamento de imagem de IA/ML na solução do Cloud Functions para atender aos próprios requisitos técnicos e comerciais. As orientações nesta seção só serão relevantes se você implantar a solução usando a CLI do Terraform.

A configuração do Terraform para esta solução fornece as seguintes variáveis que podem ser usadas para personalizar o serviço de processamento de imagem:

Variável	Descrição	Valor padrão
`region`	A região do Google Cloud em que o Cloud Functions e outros recursos da solução serão implantados. Consulte Locais do Cloud Functions para mais informações.	`us-west4`
`gcf_max_instance_count`	O número máximo de instâncias do Cloud Functions para o serviço. Isso ajuda a controlar o comportamento de escalonamento do serviço. Consulte Como usar instâncias máximas para mais informações.	10
`gcf_timeout_seconds`	O tempo limite para solicitações ao serviço, em segundos. Isso controla quanto tempo o serviço pode levar para responder. Consulte Tempo limite da função para mais informações.	120
`gcf_http_ingress_type_index`	Controla se o serviço pode ser invocado por recursos fora do projeto do Google Cloud. Consulte Configurações de entrada para mais informações. Estes são os valores possíveis: 0 (Permitir todos) 1 (Permitir somente para uso interno) 2 (Permitir balanceamento de carga interno e do Cloud Load Balancing)	0 (Permitir todos)
`gcf_require_http_authentication`	Controla se a autenticação é necessária para fazer uma solicitação ao serviço. Para mais informações, consulte Como autenticar para invocação.	`false`
`gcf_annotation_features`	Uma lista separada por vírgulas de recursos de anotação da API Vision para o serviço incluir por padrão. Isso pode ser substituído para solicitações individuais. Os valores possíveis dos recursos são: `CROP_HINTS` `DOCUMENT_TEXT_DETECTION` `FACE_DETECTION` `IMAGE_PROPERTIES` `LABEL_DETECTION` `LANDMARK_DETECTION` `LOGO_DETECTION` `OBJECT_LOCALIZATION` `PRODUCT_SEARCH` `SAFE_SEARCH_DETECTION` `TEXT_DETECTION` `WEB_DETECTION`	`FACE_DETECTION,PRODUCT_SEARCH,SAFE_SEARCH_DETECTION`

Para personalizar a solução, conclua as seguintes etapas no Cloud Shell:

Verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Se não estiver, acesse esse diretório.
Abra o arquivo terraform.tfvars e faça as alterações necessárias, especificando os valores apropriados para as variáveis listadas na tabela anterior.

Observação: para orientações sobre os efeitos da personalização na confiabilidade, segurança, desempenho, custo e operações, consulteRecomendações de design.
Valide e revise a configuração do Terraform.
Provisione os recursos.

Recomendações de projeto

À medida que você faz alterações na solução, alterando os valores das variáveis fornecidas do Terraform ou modificando a configuração do Terraform, consulte os recursos nesta seção para ajudá-lo a desenvolver uma arquitetura que atenda aos seus requisitos para segurança, confiabilidade, custo e desempenho.

Observações:

Antes de fazer qualquer mudança no design, avalie o impacto no custo e considere possíveis vantagens e desvantagens com outros recursos. É possível avaliar o impacto de mudanças no design usando a calculadora de preços do Google Cloud.
Para implementar mudanças de design na solução, você precisa de experiência em programação com Terraform e conhecimento avançado dos serviços do Google Cloud usados na solução.
Se você modificar a configuração do Terraform fornecida pelo Google e se encontrar erros, crie problemas no GitHub. Os problemas do GitHub são analisados com base no melhor esforço e não se destinam a perguntas gerais de uso.
Para mais informações sobre como criar e configurar ambientes de nível de produção no Google Cloud, consulte Design da zona de destino no Google Cloud e Lista de verificação de configuração do Google Cloud.

Segurança

Por padrão, o serviço de processamento de imagens permite solicitações da Internet e não requer autenticação para solicitações. Em um ambiente de produção, convém restringir o acesso ao serviço.

É possível controlar onde as solicitações para seu serviço podem se originar modificando a variável gcf_http_ingress_type_index do Terraform. Tenha cuidado com o acesso acidental aos endpoints de serviço da solução e, involuntariamente, acesse a Internet publicamente. Consulte Como definir as configurações de rede na documentação do Cloud Functions para mais informações.

É possível exigir autenticação para solicitações para a API REST do serviço de processamento de imagens modificando a variável gcf_require_http_authentication do Terraform. Isso ajuda a controlar o acesso individual ao serviço. Se você precisar de autenticação, os autores das chamadas do serviço precisarão fornecer credenciais para fazer uma solicitação. Consulte Como autenticar para invocação na documentação do Cloud Functions para mais informações.

Para ver mais recomendações de segurança, consulte as diretrizes do framework de arquitetura do Google Cloud para Segurança, privacidade e conformidade.

Confiabilidade

Quando os usuários fazem upload de imagens para o bucket de entrada do Cloud Storage, eles podem enfrentar diferentes níveis de latência na saída de anotação resultante. Por padrão, os usuários precisam pesquisar o bucket de saída para determinar quando as anotações estão disponíveis. Para que seu aplicativo realize ações de maneira confiável assim que o processamento da imagem for concluído, assine os eventos do Cloud Storage no bucket de saída. Por exemplo, é possível implantar outra função do Cloud para processar os dados de anotação. Para mais informações, consulte Gatilhos do Cloud Storage na documentação do Cloud Functions.

Para mais recomendações, consulte os guias a seguir para ajudar a otimizar a confiabilidade dos produtos usados nesta solução:

Desempenho

A capacidade do serviço de processamento de imagens é diretamente afetada pela capacidade de escalonamento do Cloud Functions. O Cloud Functions é escalonado automaticamente criando instâncias de função para lidar com a carga de tráfego de entrada, até um limite de instância configurável. É possível controlar o escalonamento das funções e, por sua vez, alterar a capacidade do serviço de processamento de imagens alterando o limite máximo de instâncias ou removendo o limite. Use a variável gcf_max_instance_count do Terraform para alterar o limite. Para mais informações, consulte Como usar instâncias máximas e Comportamento do escalonamento automático na documentação do Cloud Functions.

Além disso, você pode ajudar a otimizar o desempenho respeitando as seguintes práticas recomendadas:

Custo

Use as recomendações nos guias a seguir para ajudar a otimizar o custo da sua solução:

Excluir a implantação

Quando você não precisar mais da implantação da solução, exclua a implantação para evitar o faturamento contínuo dos recursos criados.

Excluir usando o console

Use este procedimento se você tiver implantado a solução pelo console.

No console do Google Cloud, acesse a página Implantações da solução.

Acessar implantações de solução
Selecione o projeto que contém a implantação que você quer excluir.
Localize a implantação que você quer excluir.
Clique em Ações e selecione Excluir.
Digite o nome da implantação e clique em Confirmar.

O campo Status mostra Excluindo.

Se a exclusão falhar, consulte as orientações de solução de problemas em Erro ao excluir uma implantação.

Quando você não precisar mais do projeto do Google Cloud usado na solução, exclua-o. Para mais informações, consulte Opcional: excluir o projeto.

Excluir usando a CLI do Terraform

Use este procedimento se você implantou a solução usando a CLI do Terraform.

No Cloud Shell, verifique se o diretório de trabalho atual é $HOME/cloudshell_open/terraform-ml-image-annotation-gcf/infra. Se não estiver, acesse esse diretório.
Remova os recursos provisionados pelo Terraform:
```
terraform destroy
```
O Terraform exibe uma lista dos recursos que serão destruídos.
Quando for solicitado que você execute as ações, digite yes.

O Terraform exibe as mensagens que mostram o progresso. Depois que todos os recursos forem excluídos, o Terraform exibirá a seguinte mensagem:
```
Destroy complete!
```
Se a exclusão falhar, consulte as orientações de solução de problemas em Erro ao excluir uma implantação.

Quando você não precisar mais do projeto do Google Cloud usado na solução, exclua-o. Para mais informações, consulte Opcional: excluir o projeto.

Excluir o projeto

Se você tiver implantado a solução em um novo projeto do Google Cloud e não for mais usar o projeto, exclua-o seguindo estas etapas:

No Console do Google Cloud, acesse a página Gerenciar recursos.
Acessar "Gerenciar recursos"
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
No prompt, digite o ID do projeto e clique em Encerrar.

Se você decidir manter o projeto, exclua a conta de serviço criada para essa solução, conforme descrito na próxima seção.

Opcional: excluir a conta de serviço

Se você excluiu o projeto usado para a solução, pule esta seção.

Como mencionado anteriormente neste guia, quando você implantou a solução, uma conta de serviço foi criada em seu nome. A conta de serviço recebeu determinadas permissões do IAM temporariamente, ou seja, as permissões foram revogadas automaticamente após a conclusão das operações de implantação e exclusão da solução, mas a conta de serviço não foi excluída. O Google recomenda que você exclua essa conta de serviço.

Se você implantou a solução pelo console do Google Cloud, acesse a página Implantações da solução. Se você já estiver nessa página, atualize o navegador. Um processo é acionado em segundo plano para excluir a conta de serviço. Nenhuma outra ação é necessária.
Se você implantou a solução usando a CLI do Terraform, conclua as etapas a seguir:
1. No Console do Google Cloud, acesse a página Contas de serviço.
  
  Acessar Contas de serviço
2. Selecione o projeto usado para a solução.
3. Selecione a conta de serviço que você quer excluir.
  
  O ID de e-mail da conta de serviço que foi criada para a solução está no seguinte formato:
```
goog-sc-DEPLOYMENT_NAME-NNN@PROJECT_ID.iam.gserviceaccount.com
```
  O ID de e-mail contém os seguintes valores:
  - DEPLOYMENT_NAME: o nome da implantação.
  - NNN: um número aleatório de três dígitos.
  - PROJECT_ID é o ID do projeto em que você implantou a solução.
4. Clique em Excluir.

Solucionar erros

As ações que podem ser realizadas para diagnosticar e resolver erros dependem do método de implantação e da complexidade dele.

Erros ao implantar usando o console

Se a implantação falhar quando você usar o console, faça o seguinte:

Acesse a página Implantações da solução.

Se a implantação falhou, o campo Status mostra Falha.
Para ver os detalhes dos erros que causaram a falha, faça o seguinte:
1. Clique em Ações.
2. Selecione Ver registros do Cloud Build.
Analise o registro do Cloud Build e tome as medidas apropriadas para resolver o problema que causou a falha.

Erros ao implantar usando a CLI do Terraform

Se a implantação falhar quando você usar o Terraform, a saída do comando terraform apply incluirá mensagens de erro que podem ser analisadas para diagnosticar o problema.

Os exemplos nas seções a seguir mostram erros de implantação que podem ser encontrados ao usar o Terraform.

API não ativado

Se você criar um projeto e tentar implantar imediatamente a solução no novo projeto, a implantação poderá falhar e apresentar um erro como este:

Error: Error creating Network: googleapi: Error 403: Compute Engine API has not
been used in project PROJECT_ID before or it is disabled. Enable it by visiting
https://console.developers.google.com/apis/api/compute.googleapis.com/overview?project=PROJECT_ID
then retry. If you enabled this API recently, wait a few minutes for the action
to propagate to our systems and retry.

Se esse erro ocorrer, aguarde alguns minutos e execute o comando terraform apply novamente.

Se um erro de API não ativada persistir, siga o link na mensagem de erro para ativar a API. Aguarde alguns instantes para a API ser ativada e execute o comando terraform apply novamente.

Não é possível atribuir o endereço solicitado

Quando você executa o comando terraform apply, pode ocorrer um erro cannot assign requested address, com uma mensagem como esta:

Error: Error creating service account:
 Post "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts:
 dial tcp [2001:db8:ffff:ffff::5f]:443:
 connect: cannot assign requested address

Se esse erro ocorrer, execute o comando terraform apply novamente.

Erro ao excluir uma implantação

Em alguns casos, as tentativas de excluir uma implantação podem falhar:

Depois de implantar uma solução no console, se você alterar qualquer recurso provisionado por ela e tentar excluir a implantação, a exclusão poderá falhar. O campo Status na página Implantações da solução mostra Com falha e o registro do Cloud Build mostra a causa do erro.
Depois de implantar uma solução usando a CLI do Terraform, se você alterar qualquer recurso usando uma interface diferente do Terraform (por exemplo, o console) e, em seguida, tentar excluir a implantação, a exclusão poderá falhar. As mensagens na saída do comando terraform destroy mostram a causa do erro.

Revise os registros de erro e as mensagens, identifique e exclua os recursos que causaram o erro e tente excluir a implantação novamente.

Se uma implantação baseada em console não for excluída e não for possível diagnosticar o erro usando o registro do Cloud Build, será possível excluir a implantação usando a CLI do Terraform, conforme descrito na próxima seção.

Excluir uma implantação com base no console usando a CLI do Terraform

Nesta seção, descrevemos como excluir uma implantação baseada em console em caso de erros ao tentar excluí-la no console. Nesta abordagem, faça o download da configuração do Terraform para a implantação que você quer excluir e use a CLI do Terraform para excluir a implantação.

Identifique a região em que o código, os registros e outros dados do Terraform da implantação são armazenados. Essa região pode ser diferente da região selecionada durante a implantação da solução.
1. No console do Google Cloud, acesse a página Implantações de soluções.
  
  Acessar implantações de solução
2. Selecione o projeto que contém a implantação que você quer excluir.
3. Na lista de implantações, identifique a linha da implantação que você quer excluir.
4. Clique em Consultar todo o conteúdo da linha.
5. Na coluna Local, observe o segundo local, conforme destacado no exemplo a seguir:
No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Crie variáveis de ambiente para o ID do projeto, a região e o nome da implantação que você quer excluir:
```
export REGION="REGION"
export PROJECT_ID="PROJECT_ID"
export DEPLOYMENT_NAME="DEPLOYMENT_NAME"
```
Nesses comandos, substitua o seguinte:
- REGION: o local que você anotou anteriormente neste procedimento.
- PROJECT_ID: o ID do projeto em que você implantou a solução.
- DEPLOYMENT_NAME: o nome da implantação que você quer excluir.

Encontre o ID da revisão mais recente da implantação que você quer excluir:

export REVISION_ID=$(curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://config.googleapis.com/v1alpha2/projects/${PROJECT_ID}/locations/${REGION}/deployments/${DEPLOYMENT_NAME}" \
    | jq .latestRevision -r)
    echo $REVISION_ID

O resultado será assim:

projects/PROJECT_ID/locations/REGION/deployments/DEPLOYMENT_NAME/revisions/r-0

Encontre o local do Cloud Storage na configuração do Terraform para a implantação:

export CONTENT_PATH=$(curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://config.googleapis.com/v1alpha2/${REVISION_ID}" \
    | jq .applyResults.content -r)
    echo $CONTENT_PATH

Veja a seguir um exemplo da saída desse comando:

gs://PROJECT_ID-REGION-blueprint-config/DEPLOYMENT_NAME/r-0/apply_results/content

Faça o download da configuração do Terraform do Cloud Storage para o Cloud Shell:
```
gsutil cp -r $CONTENT_PATH $HOME
cd $HOME/content/infra
```
Aguarde até que a mensagem Operation completed seja exibida, conforme mostrado no exemplo a seguir:
```
Operation completed over 45 objects/268.5 KiB
```

Inicialize o Terraform:

terraform init

Aguarde até ver a seguinte mensagem:

Terraform has been successfully initialized!

Remova os recursos implantados:
```
terraform destroy
```
O Terraform exibe uma lista dos recursos que serão destruídos.

Se forem exibidos avisos sobre variáveis não declaradas, ignore-os.
Quando for solicitado que você execute as ações, digite yes.

O Terraform exibe as mensagens que mostram o progresso. Depois que todos os recursos forem excluídos, o Terraform exibirá a seguinte mensagem:
```
Destroy complete!
```

Exclua o artefato de implantação:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://config.googleapis.com/v1alpha2/projects/${PROJECT_ID}/locations/${REGION}/deployments/${DEPLOYMENT_NAME}?force=true&delete_policy=abandon"

Aguarde alguns segundos e verifique se o artefato de implantação foi excluído:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://config.googleapis.com/v1alpha2/projects/${PROJECT_ID}/locations/${REGION}/deployments/${DEPLOYMENT_NAME}" \
    | jq .error.message

Se a saída mostrar null, aguarde alguns segundos e execute o comando novamente.

Depois que o artefato de implantação for excluído, uma mensagem, como mostrado no exemplo a seguir, será exibida:

Resource 'projects/PROJECT_ID/locations/REGION/deployments/DEPLOYMENT_NAME' was not found

Enviar feedback

As Soluções de início rápido são apenas para fins informativos e não são produtos oficialmente compatíveis. O Google pode alterar ou remover soluções sem aviso prévio.

Para resolver erros, analise os registros do Cloud Build e a saída do Terraform.

Para enviar feedback, faça o seguinte:

Para ver a documentação, os tutoriais no console ou a solução, use o botão Enviar feedback na página.

Para código não modificado do Terraform, crie problemas no repositório do GitHub. Os problemas do GitHub são analisados com base no melhor esforço e não se destinam a perguntas gerais de uso.

Para problemas com produtos usados na solução, entre em contato com o Cloud Customer Care.

A seguir

Saiba mais sobre a computação sem servidor no Google Cloud.
Saiba mais sobre machine learning para análise de imagens no Google Cloud.
Saiba mais sobre arquiteturas orientadas a eventos.
Entenda os recursos e os limites dos produtos usados nesta solução: