Como implantar o Imagen no Cloud Run

1. Sobre este codelab

Última atualização:11/10/2024

Escrito por:Laurie White

Geração de imagens

Vamos ser honestos, a geração de imagens por modelos de linguagem grandes (LLMs) pode ser divertida. É claro que há muitos aplicativos empresariais para gerar imagens a partir de um comando, que vão de publicidade personalizada a apresentações atraentes. O site do Google Cloud tem muitos usos específicos de empresas que usam agentes criativos. Ainda assim, ver os resultados quando você pede uma imagem de "cachorros verdes felizes em um campo" pode ser bastante divertido.

Se você estiver interessado na geração de imagens por motivos profissionais ou recreativos (ou ambos), há alguns desafios entre o uso de um programa de geração de imagens e a implantação de um aplicativo da Web. Este laboratório vai ajudar você a superar esses desafios.

O que você vai criar

Neste codelab, você vai criar um app que vai receber um comando de texto e retornar uma página da Web com uma imagem gerada usando esse comando.

O que você aprenderá

Neste laboratório, você vai aprender a:

Como usar o Google Imagen para criar imagens a partir de comandos de texto em ambientes de notebook
As dificuldades de mover o código do Imagen de um notebook para um app da Web
Como implantar um aplicativo do Cloud Run que usa o Imagen para gerar imagens
Como incluir uma imagem do Imagen em HTML

Este codelab é focado no Imagen e na implantação. Conceitos e blocos de códigos sem relevância não serão abordados. Eles são incluídos somente para você copiar e colar.

O que é necessário

Uma versão recente do navegador Chrome.
Algum conhecimento do Cloud Run. Você pode acessar esse codelab bastante curto aqui.
Familiaridade com a edição de arquivos no Cloud Shell ou no editor do Cloud Shell. Saiba mais sobre o Cloud Shell e o editor do Cloud Shell em neste codelab.
Um projeto do Google Cloud com o faturamento ativado. Este guia mostra como criar um projeto. Há vários produtos com níveis sem custo financeiro e testes sem custo financeiro disponíveis.

O código completo deste codelab está disponível em https://github.com/Annie29/imagen-deployment (link em inglês).

2. Ativar APIs

Selecione um projeto para usar neste codelab. Talvez você queira criar um novo projeto para facilitar a remoção de todo o trabalho quando terminar.

Antes de começar a usar o Imagen, você precisa ativar algumas APIs.

Acesse o Console do Google Cloud.
Navegue até o painel da Vertex AI.
Selecione "Ativar todas as APIs recomendadas".

3. Como explorar o Google Imagen (opcional)

Se você já conhece o Imagen, pule esta seção.

Antes de tentar criar um app da Web que use o Imagen, é útil ver o que ele pode fazer. Felizmente, há vários notebooks que executam um código simples do Imagen. Vamos começar com um deles.

Acesse o notebook em https://github.com/GoogleCloudPlatform/generative-ai/blob/main/vision/getting-started/image_generation.ipynb (link em inglês).
Selecione "Abrir no Colab" para abrir o notebook no servidor de notebook do Google.
Selecione "Arquivo -> Salvar uma cópia no Drive" ou clique em "Copiar para o Drive" na parte de cima da página para criar sua própria cópia desse notebook.
Feche a cópia original (apenas para evitar trabalhar na cópia errada).
Você precisa se conectar a um ambiente de execução clicando no botão "Conectar" no canto superior direito.
Comece a trabalhar em cada uma das células do notebook.
Para executar uma célula, clique em [] ou na seta à esquerda da célula ou use a opção "Executar seleção" no menu "Ambiente de execução" (ou o atalho):
Ao reiniciar o ambiente de execução atual, você receberá uma mensagem informando que o sistema falhou. Não entre em pânico. Isso é normal.
Você precisará autenticar o ambiente do notebook.
Você pode inserir o ID do projeto (não o nome) e o local (us-central1 funciona se você não tiver definido um local) nas caixas à direita do código e fazer com que o Colab os insira no código.
Quando você chegar a "Gerar uma imagem", terá a oportunidade de ver o que o Imagen pode fazer. Mude o comando e execute a célula novamente para conferir a variedade de imagens que você pode receber.
Nesse momento, você já deve ter uma boa ideia de como o Imagen pode criar imagens de um notebook. Conclua este notebook para saber mais sobre os parâmetros de imagem agora ou em um momento conveniente.

4. Começar a criar um aplicativo da Web para mostrar uma imagem

Vamos usar o Python com o framework Flask no Cloud Run para criar nosso app.

Os apps Python Flask são configurados em uma pasta da seguinte maneira:

app-folder
    templates
        template.html
        (etc.)
        anothertemplate.html
    main.py
    requirements.txt

Modelos são arquivos que contêm HTML, geralmente com marcadores nomeados em que o programa insere texto gerado. main.py é o próprio app do servidor da Web, e requirements.txt é uma lista de todas as bibliotecas não padrão que main.py usa.

O aplicativo terá duas páginas: a primeira para receber um comando e a segunda para mostrar a imagem e permitir que o usuário insira outro comando.

Primeiro, crie o framework do projeto.

Como criar a estrutura de arquivos

Este codelab pressupõe que seu projeto esteja na pasta imageapp. Se você usar um nome diferente, atualize os comandos conforme necessário.

Acesse o Cloud Shell selecionando o ícone de comando no canto superior direito da tela.

Você pode ter mais espaço para trabalhar se mover o shell para uma nova guia, usando a seta na parte de cima da janela do shell:

No diretório principal do Cloud Shell, crie a pasta imageapp, mude para ela e crie as pastas templates. Você pode fazer isso na linha de comando ou no editor do Cloud Shell.

Criar os modelos

O aplicativo terá duas páginas: a primeira (que vamos chamar de home.html) para receber um comando e a segunda (que vamos chamar de display.html) para mostrar a imagem e permitir que o usuário insira outro comando.

Usando o editor do Cloud Shell ou o editor Linux de sua escolha, crie dois modelos. Na pasta imageapp/templates, crie a página inicial que o usuário verá, home.html. Ela usa a variável prompt para retornar a descrição inserida pelo usuário.

templates/home.html

<!DOCTYPE html>
<html>
   <head>
       <title>Let's draw a picture</title>
   </head>
   <body>
       <h1>Let's draw a picture</h1>
       <form  action="/" method="post" >
           <input type="text" id="prompt" name="prompt">
           <input type="submit" value="Send">
       </form>
   </body>
</html>

Em seguida, crie display.html, que vai mostrar a imagem. O local da imagem estará em image_url.

templates/display.html

<!DOCTYPE html>
<html>
   <head>
       <title>Let's draw a picture</title>
   </head>
   <body>
       <h1>Let's draw a picture</h1>

       <div>
           <form  action="/" method="post" >
               <input type="text" id="prompt" name="prompt">
               <input type="submit" value="Send">
           </form>

           <p></p>
       </div>

       <div id="picture">
           <img id="pict" name="pict" alt="The created image" src="{{image_uri}}" style="width:100%;">
       </div>

   </body>
</html>

5. Como iniciar o código

Você precisa criar o arquivo requirements.txt para garantir que todas as bibliotecas necessárias para o programa estejam disponíveis. Por enquanto, inclua apenas flask no arquivo requirements.txt.

O arquivo main.py contém o código que vai atender às solicitações da Web. Há apenas duas solicitações que precisamos processar: uma solicitação GET para a página inicial e uma solicitação POST que envia o formulário descrevendo a imagem que queremos gerar.

Usando o editor do Cloud Shell ou o editor Linux de sua escolha, crie o main.py arquivo na pasta imageapp. Vamos começar com o esqueleto abaixo:

main.py

import flask

app = flask.Flask(__name__)

@app.route("/", methods=["GET"])
def home_page():
    return flask.render_template("home.html")

@app.route("/", methods=["POST"])
def display_image():
    # Code to get the prompt (called prompt) from the submitted form
    # Code to generate the image
    # Code to create a URL for the image (called image_url)

    return flask.render_template("display.html", prompt=prompt, image_url=image_url)

# Initialize the web server app when the code locally (Cloud Run handles it in that environment)
if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=8080)

Na verdade, esse é quase o app inteiro. Há três comentários em display_image que precisam ser preenchidos com código Python, e é isso.

Vamos começar a preencher essas partes ausentes. O Flask facilita a recuperação do comando. Adicione uma linha após o comentário, conforme mostrado abaixo:

# Code to get the prompt (called prompt) from the submitted form
prompt = flask.request.form["prompt"]

Se você quiser testar o app agora, adicione uma linha antes da instrução return em display_image para dar um valor a image_url (um URL válido que aponta para uma imagem).

Por exemplo: image_url="<your url here>"

Você pode executar o programa localmente no Cloud Shell (usando o comando python main.py) e visualizá-lo usando a opção "Visualizar na porta 8080" no canto superior direito da tela.

Como o programa está agora, você sempre verá a imagem no URL fornecido. Vamos continuar e ver como receber esse valor do app. Remova a linha que dá um valor estático a image_url.

6. Como criar a imagem

O Google Cloud tem uma API Python para IA generativa na Vertex AI. Para usá-la, precisamos adicionar uma linha importando-a com as outras importações perto da parte de cima do nosso programa:

from vertexai.vision_models import ImageGenerationModel

e incluir vertexai no arquivo requirements.txt.

A documentação do ImageGenerationModel mostra como usá-lo. Vamos criar um modelo e gerar uma imagem dele, com um comando. Adicione o código a main.py para a segunda etapa, criando a imagem e armazenando-a em response:

# Code to generate the image
model = ImageGenerationModel.from_pretrained("imagegeneration@006")
response = model.generate_images(prompt=prompt)[0]

Até quatro imagens podem ser criadas por vez, dependendo dos parâmetros enviados para generate_images. Portanto, o valor retornado será uma lista de GeneratedImage, mesmo que haja apenas uma imagem retornada, como neste caso.

Agora precisamos mostrar a imagem em uma página da Web. O GeneratedImage tem um método para show a imagem, mas ele só funciona em um ambiente de notebook. No entanto, há um método para salvar a imagem. Vamos salvar a imagem e enviar o URL da imagem salva quando renderizarmos o modelo.

Isso é um pouco complicado e há muitas maneiras de fazer isso. Vamos analisar uma das abordagens mais simples, etapa por etapa. Há uma imagem das etapas abaixo se você for um aprendiz mais visual.

Primeiro, precisamos salvar a imagem. Mas qual será o nome dela? Pode haver problemas ao usar um nome estático, já que o programa pode ser usado por muitas pessoas ao mesmo tempo. Embora possamos criar nomes de imagens separados para cada usuário (com algo como UUID), uma maneira mais simples é usar a biblioteca tempfile do Python, que vai criar um arquivo temporário com um nome exclusivo. O código abaixo vai criar um arquivo temporário, receber o nome dele e gravar a resposta da etapa de geração de imagens no arquivo temporário. Ainda não vamos inseri-lo no nosso código, já que precisamos receber um URL primeiro.

with tempfile.NamedTemporaryFile("wb") as f:
    filename = f.name
    response.save(filename, include_generation_parameters=False)
    # process the saved file here, before it goes away

Há várias maneiras de processar o arquivo salvo, mas uma das mais simples e seguras é usar um URL de dados.

Os URLs de dados permitem que os dados reais sejam enviados no URL, não apenas um caminho para ele. A sintaxe de um URL de dados é:

data:[image/png][;base64],<data>

Para receber a codificação base64 da imagem, precisamos abrir o arquivo salvo por tempfile e lê-lo em uma variável. Sim, essa será uma string grande, mas isso não deve ser um problema com navegadores e servidores modernos. Em seguida, vamos usar a biblioteca base64 para codificar isso em uma string que podemos enviar no URL de dados.

Nosso código final para fazer a terceira etapa (criar o URL) será:

# Code to create a URL for the image (called image_url)
with tempfile.NamedTemporaryFile("wb") as f:
    filename = f.name
    response.save(filename, include_generation_parameters=False)
    # process the saved file here, before it goes away
    with open(filename, "rb") as image_file:
        binary_image = image_file.read()
        base64_image = base64.b64encode(binary_image).decode("utf-8")
        image_url = f"data:image/png;base64,{base64_image}"

Você pode conferir todas essas etapas na imagem abaixo:

Você precisa importar tempfile e base64 no início do programa.

import tempfile
import base64

Tente executar o programa no Cloud Shell. Confirme que você está na pasta com main.py e execute o comando:

python main.py

Em seguida, visualize-o usando a opção "Visualizar na porta 8080" no canto superior direito da tela.

7. Um erro comum

Em algum momento, você pode notar que, ao executar o programa (durante o teste ou após a implantação), você recebe uma mensagem como esta:

Isso provavelmente é causado por um comando que viola as práticas de IA responsável do Google . Um comando tão simples quanto "gatinhos brincando com bolas coloridas" pode causar esse problema. Mas não se preocupe, é possível receber imagens de "gatinhos brincando com brinquedos coloridos".

Para lidar com esse erro, vamos adicionar um código para detectar a exceção gerada quando tentamos gerar a imagem. Se houver uma, vamos renderizar o modelo home.html novamente, com uma mensagem mostrando.

Primeiro, vamos adicionar uma div no modelo home.html após o primeiro formulário que será mostrado se houver um erro:

<!DOCTYPE html>
<html>
   <head>
       <title>Let's draw a picture</title>
   </head>
   <body>
       <h1>Let's draw a picture</h1>
       <form  action="/" method="post" >
           <input type="text" id="prompt" name="prompt">
           <input type="submit" value="Send">
       </form>
       {% if mistake %}
       <div id="warning">
       The prompt contains sensitive words that violate
       <a href=\"https://ai.google/responsibility/responsible-ai-practices\">
           Google's Responsible AI practices</a>.
       Try rephrasing the prompt."</div>

       {% endif %}

   </body>
</html>

Em seguida, adicione o código em main.py para detectar uma possível exceção ao chamar o código generate_images em display_image. Se houver uma exceção, o código vai renderizar o modelo home.html com uma mensagem.

# Code to generate the image
   model = ImageGenerationModel.from_pretrained("imagegeneration@006")
   try:
       response = model.generate_images(prompt=prompt)[0]   
   except:
       #  This is probably due to a questionable prompt
       return flask.render_template("home.html", warning=True)

Esse não é o único recurso de IA responsável do Imagen. Há vários recursos que protegem a geração de pessoas e crianças e filtros gerais nas imagens. Saiba mais sobre eles aqui.

8. Como implantar o app na Web

Você pode implantar o app na Web usando o comando da pasta imageapp no Cloud Shell. Use o ID real do projeto no comando.

gcloud run deploy imageapp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --project your-project-id

Você vai receber uma resposta como esta, informando onde encontrar o aplicativo:

Service [imageapp] revision [imageapp-00001-t48] has been deployed and is serving 100 percent of traffic.
Service URL: https://imageapp-708208532564.us-central1.run.app```

9. Como fazer a limpeza

Ainda que o Cloud Run não gere custos quando o serviço não estiver em uso, é possível que receba cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. É possível excluir o repositório ou o projeto na nuvem para evitar cobranças. A exclusão do projeto na nuvem interrompe o faturamento de todos os recursos usados nele.

Para excluir o repositório de imagens de contêineres:

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Para excluir o serviço do Cloud Run:

gcloud run services delete imageapp \
  --platform managed \
  --region $REGION

Para excluir o projeto do Google Cloud:

Recupere o ID do projeto atual:

PROJECT_ID=$(gcloud config get-value core/project)

Confirme se é o projeto que você quer excluir:

echo $PROJECT_ID

Excluir o projeto:

gcloud projects delete $PROJECT_ID

10. Parabéns

Parabéns, você criou um aplicativo da Web que mostra imagens criadas pelo Imagen. Como você pode usar isso no seu aplicativo?

Qual é a próxima etapa?

Confira alguns destes codelabs: