Esta página foi traduzida pela API Cloud Translation.

Implante automaticamente o aplicativo da Web Go de IA generativa do controle de versões para o Cloud Run

1. Visão geral

Implantar um aplicativo da Web pela primeira vez pode ser assustador. Mesmo após a primeira implantação, se o processo for muito trabalhoso, você poderá evitar a implantação de novas versões do aplicativo. Com a implantação contínua, você pode implantar mudanças no seu aplicativo de forma automática e fácil.

Neste laboratório, você vai criar um aplicativo da Web e configurar o Cloud Run para implantar automaticamente o aplicativo quando uma alteração for feita no código-fonte. Em seguida, modifique e implante o aplicativo novamente.

O que você vai aprender

Programar um aplicativo da Web com o Cloud Shell Editor
Armazenar o código do aplicativo no GitHub
Implantar seu aplicativo automaticamente no Cloud Run

Adicionar a IA generativa ao seu aplicativo usando a Vertex AI

2. Pré-requisitos

Se você ainda não tem uma Conta do Google, crie uma.
- Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
Se você ainda não tiver uma conta do GitHub, crie uma
- Use uma conta do GitHub existente, se você tiver uma. O GitHub tem mais probabilidade de bloquear uma nova conta como spam.
- Configure a autenticação de dois fatores na sua conta do GitHub para reduzir as chances de sua conta ser marcada como spam.

3. Configurar o projeto

Faça login no Console do Google Cloud.
Ative o faturamento no Console do Cloud.
- A conclusão deste laboratório deve custar menos de US $1 em recursos do Cloud.
- Siga as etapas no final deste laboratório para excluir recursos e evitar cobranças.
- Novos usuários estão qualificados para o teste sem custo financeiro de US$300.
- Vai participar de um evento da IA generativa para desenvolvedores? Um crédito de US$1 pode estar disponível.
Crie um novo projeto ou escolha reutilizar um projeto atual.

4. Abrir editor do Cloud Shell

Acesse o editor do Cloud Shell.
Se o terminal não aparecer na parte de baixo da tela, abra-o:
- Clique no menu de navegação .
- Clique em Terminal.
- Clique em Novo Terminal.
No terminal, defina o projeto com este comando:
- Formato:
```
gcloud config set project [PROJECT_ID]
```
- Exemplo:
```
gcloud config set project lab-project-id-example
```
- Se você não souber o ID do projeto:
  - É possível listar todos os IDs de projeto com:
```
gcloud projects list | awk '/PROJECT_ID/{print $2}'
```
Se for preciso autorizar, clique em Autorizar para continuar.
Você vai receber esta mensagem:
```
Updated property [core/project].
```
Se você receber uma WARNING e receber uma solicitação Do you want to continue (Y/N)?, provavelmente inseriu o ID do projeto incorretamente. Pressione N, pressione Enter e tente executar o comando gcloud config set project novamente.

5. Ativar APIs

No terminal, ative as APIs:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

Esse comando pode levar alguns minutos para ser concluído, mas vai gerar uma mensagem de sucesso semelhante a esta:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Configurar o Git

Defina o e-mail do usuário global do Git:

git config --global user.email "you@example.com"

Defina seu nome de usuário global do Git:

git config --global user.name "Your Name"

Defina a ramificação padrão do Git global como main:
```
git config --global init.defaultBranch main
```

7. Escrever seu código

Para escrever um aplicativo em Go:

Navegue até o diretório principal:
```
cd ~
```
Crie o diretório codelab-genai:
```
mkdir codelab-genai
```
Navegue até o diretório codelab-genai:
```
cd codelab-genai
```
Inicialize um arquivo go.mod para declarar nosso módulo:
```
go mod init codelab-genai
```
Crie um arquivo main.go:
```
touch main.go
```
Abra o arquivo main.go no editor do Cloud Shell:
```
cloudshell edit main.go
```
Um arquivo vazio vai aparecer na parte de cima da tela. É aqui que você pode editar o arquivo main.go.

Edite main.go e cole o seguinte código:

package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello, world!")
    })

    port := os.Getenv("PORT")

    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        log.Fatal(err)
    }
}

Após alguns segundos, o editor do Cloud Shell vai salvar o código automaticamente. Esse código responde a solicitações HTTP com a saudação "Hello world!".

O código inicial do aplicativo foi concluído e está pronto para ser armazenado no controle de versão.

8. Criar um repositório

Volte ao terminal do Cloud Shell na parte de baixo da tela.
Verifique se você ainda está no diretório correto:
```
cd ~/codelab-genai
```
Inicializar o repositório do Git
```
git init -b main
```
Faça login no GitHub CLI
```
gh auth login
```
Pressione Enter para aceitar as opções padrão e siga as instruções na ferramenta GitHub CLI, incluindo:
1. Em qual conta você quer fazer login? GitHub.com
2. Qual é seu protocolo preferido para operações do Git neste host? HTTPS
3. Autenticar o Git com suas credenciais do GitHub? Y (pule se não aparecer)
4. Como você quer autenticar o GitHub CLI? Login with a web browser
5. Copiar seu código único
6. Abra https://github.com/login/device.
7. Cole seu código único
8. Clique em Authorize github.
9. Concluir o login
Confirme que você fez login:
```
gh api user -q ".login"
```
Se você fez login, o nome de usuário do GitHub vai aparecer.

Crie uma variável GITHUB_USERNAME

GITHUB_USERNAME=$(gh api user -q ".login")

Confirme se você criou a variável de ambiente:
```
echo ${GITHUB_USERNAME}
```
Se você criou a variável, o nome de usuário do GitHub vai ser exibido.
Crie um repositório vazio do GitHub com o nome codelab-genai:
```
gh repo create codelab-genai --private
```
Se você receber o erro:
```
GraphQL: Name already exists on this account (createRepository)
```
significa que já tem um repositório com o nome codelab-genai. Você tem duas opções para continuar seguindo este tutorial:
- Excluir o repositório do GitHub
- Crie um repositório com um nome diferente e mude o nome nos comandos a seguir.

Adicione o repositório codelab-genai como o origin remoto:

git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. Compartilhar seu código

Confirme se você está no diretório correto:
```
cd ~/codelab-genai
```
Adicione todos os arquivos no diretório atual a esta confirmação:
```
git add .
```
Crie a primeira confirmação:
```
git commit -m "add http server"
```
Envie a confirmação para a ramificação main do repositório origin:
```
git push -u origin main
```

Execute este comando e acesse o URL resultante para conferir o código do aplicativo no GitHub:

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/main.go \n\n"

10. Configurar implantações automáticas

Deixe a guia do editor do Cloud Shell aberta. Vamos voltar a esta guia mais tarde.
Em uma nova guia, acesse a página do Cloud Run.
Selecione o projeto do Google Cloud correto no console
Clique em CONECTAR REPOSITÓRIO.
Clique em CONFIGURAR COM O CLOUD BUILD
1. Selecione GitHub como o provedor do repositório
  - Se você não tiver feito login na sua conta do GitHub no navegador, faça login com suas credenciais.
2. Clique em Autenticar e em Continuar.
3. Depois de fazer login, você vai receber uma mensagem na página do Cloud Run informando que o app GitHub não está instalado em nenhum dos seus repositórios.
4. Clique no botão INSTALL GOOGLE CLOUD BUILD.
  - Na página de configuração da instalação, selecione Somente repositórios selecionados e escolha o repositório codelab-genai que você criou pela CLI.
  - Clique em Instalar.
  - Observação: se você tiver muitos repositórios do GitHub, o carregamento pode levar alguns minutos.
5. Selecione your-user-name/codelab-genai como Repositório
  - Se o repositório não estiver presente, clique no link Gerenciar repositórios conectados.
6. Deixe Ramificação como ^main$
7. Clique em Go, Node.js, Python, Java, .NET Core, Ruby ou PHP usando os buildpacks do Google Cloud
  - Deixe os outros campos (Build context directory, Entrypoint e Function target) como estão.
8. Clique em Salvar.
Role a tela para baixo até Autenticação.
Clique em Permitir invocações não autenticadas.
Clique em CRIAR.

Quando o build terminar (o que levará vários minutos), execute este comando e acesse o URL resultante para conferir o aplicativo em execução:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. Mudar o código

Volte ao terminal do Cloud Shell na parte de baixo da tela.
Verifique se você ainda está no diretório correto:
```
cd ~/codelab-genai
```
Reabrir main.go no editor do Cloud Shell
```
cloudshell edit main.go
```

Instale o SDK da Vertex AI para Go:

go get cloud.google.com/go/vertexai/genai

Instale a biblioteca de metadados para Go para receber o ID do projeto atual:
```
go get cloud.google.com/go/compute/metadata
```

Substitua o código no arquivo main.go por:

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "cloud.google.com/go/compute/metadata"
    "cloud.google.com/go/vertexai/genai"
)

func main() {
    ctx := context.Background()
    var projectId string
    var err error
    projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
    if projectId == "" {
        projectId, err = metadata.ProjectIDWithContext(ctx)
        if err != nil {
            return
        }
    }
    var client *genai.Client
    client, err = genai.NewClient(ctx, projectId, "us-central1")
    if err != nil {
        return
    }
    defer client.Close()

    model := client.GenerativeModel("gemini-1.5-flash-001")

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        animal := r.URL.Query().Get("animal")
        if animal == "" {
            animal = "dog"
        }

        resp, err := model.GenerateContent(
            ctx,
            genai.Text(
                fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)),
        )

        if err != nil {
            w.WriteHeader(http.StatusServiceUnavailable)
            return
        }

        if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
            htmlContent := resp.Candidates[0].Content.Parts[0]
            w.Header().Set("Content-Type", "text/html; charset=utf-8")
            fmt.Fprint(w, htmlContent)
        }
    })

    port := os.Getenv("PORT")

    if port == "" {
        port = "8080"
    }
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        log.Fatal(err)
    }
}

12. Reimplantar

Verifique se você ainda está no diretório correto no Cloud Shell:
```
cd ~/codelab-genai
```
Execute estes comandos para confirmar uma nova versão do aplicativo no repositório local do Git:
```
git add .
git commit -m "add latest changes"
```
Envie as alterações para o GitHub:
```
git push
```

Quando o build terminar, execute este comando e acesse o aplicativo implantado:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

Pode levar alguns minutos para que o build seja concluído e você possa conferir as mudanças.

Confira o histórico de todas as revisões aqui: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (Opcional) Auditar o uso da Vertex AI

Assim como em outros serviços do Google Cloud, é possível auditar as operações da Vertex AI. Os registros de auditoria ajudam a responder às perguntas "Quem fez o quê, onde e quando?". Os registros de auditoria administrativos da Vertex AI são ativados por padrão. Para auditar solicitações de geração de conteúdo, ative os registros de auditoria de acesso a dados:

No console do Google Cloud, acesse a página Registros de auditoria:

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.
Verifique se o projeto do Google Cloud atual é aquele em que você vai criar o aplicativo do Cloud Run.
Na tabela Configuração dos registros de auditoria de acesso a dados, selecione Vertex AI API na coluna "Serviço".
Na guia Tipos de registro, selecione os tipos de registro de auditoria de acesso a dados Admin read e Data read.
Clique em Salvar.

Depois de ativar, você poderá conferir os registros de auditoria para cada invocação do aplicativo. Para conferir os registros de auditoria com detalhes de invocação, faça o seguinte:

Volte para o aplicativo implantado e atualize a página para acionar o registro.
No console do Google Cloud, acesse a página Análise de registros:

Na janela de consulta, digite:

LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"

Clique em Executar consulta.

Os registros de auditoria capturam o uso da API Vertex AI, mas não permitem observar dados relacionados à carga de trabalho, como instruções ou detalhes de resposta.

14. (Opcional) Aumentar a observabilidade da carga de trabalho de IA

Os registros de auditoria não capturam informações relacionadas à carga de trabalho. Para aumentar a observabilidade das cargas de trabalho, é necessário registrar essas informações explicitamente. Você pode usar sua estrutura de registro favorita para fazer isso. As etapas a seguir demonstram uma maneira de fazer isso usando a biblioteca de geração de registros estruturados do Go.

Reabrir main.go no editor do Cloud Shell

cloudshell edit ~/codelab-genai/main.go

Mude o bloco de importação para incluir a geração de registros estruturados e as bibliotecas JSON do Go:

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "log/slog"
    "net/http"
    "os"

    "cloud.google.com/go/compute/metadata"
    "cloud.google.com/go/vertexai/genai"
)

Depois de inicializar o cliente do Vertex (linha 33), adicione as linhas a seguir para inicializar um registrador estruturado que use os campos corretos para o Google Cloud Logging:

opts := &slog.HandlerOptions{
	Level: slog.LevelDebug,
	ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
        if a.Key == slog.LevelKey {
            return slog.Attr{Key: "severity", Value: a.Value}
        }
        if a.Key == slog.MessageKey {
            return slog.Attr{Key: "message", Value: a.Value}
        }
        return slog.Attr{Key: a.Key, Value: a.Value}
	},
}

jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
slog.SetDefault(slog.New(jsonHandler))

Depois de verificar uma resposta para GenerateContent (linha 69), adicione as linhas abaixo dentro do bloco if:
```
jsonBytes, err := json.Marshal(resp)
if err != nil {
    slog.Error("Failed to marshal response to JSON", "error", err)
} else {
    jsonString := string(jsonBytes)
    slog.Debug("Complete response content", "json_response", jsonString)
}
```
Esse código grava informações sobre o conteúdo gerado em stdout usando o formato de registro estruturado. Um agente de registro no Cloud Run captura a saída gerada em stdout e grava esse formato no Cloud Logging.
Abra novamente o Cloud Shell e digite o seguinte comando para garantir que você esteja no diretório correto:
```
cd ~/codelab-genai
```

Confirme as alterações:

git commit -am "Observe generated content"

Envie as alterações para o GitHub para acionar a nova implantação da versão modificada:
```
git push
```

Depois que a nova versão for implantada, você poderá observar as informações de depuração sobre as chamadas para a Vertex AI.

Para conferir os registros do aplicativo, faça o seguinte:

No console do Google Cloud, acesse a página Análise de registros:

Na janela de consulta, digite:

LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG

Clique em Executar consulta.

O resultado da consulta mostra registros com a solicitação e a resposta da Vertex AI, incluindo "classificações de segurança" que podem ser usadas para monitorar práticas de segurança.

15. (Opcional) Limpar

O Cloud Run não gera custos quando o serviço não está em uso, mas você ainda pode receber cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. Você pode excluir seu projeto do Cloud para evitar cobranças. A exclusão do projeto do Cloud interrompe o faturamento de todos os recursos usados nesse projeto.

Se quiser, exclua o projeto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Você também pode excluir recursos desnecessários do disco do cloudshell. Você pode:

Exclua o diretório do projeto do codelab:
```
rm -rf ~/codelab-genai
```
Limpe todos os pacotes Go que não forem mais necessários:
```
cd ~
go clean -modcache
```
Aviso: Não é possível desfazer essa ação. Se você quiser excluir tudo no Cloud Shell para liberar espaço, exclua o diretório principal inteiro. Confira se tudo o que você quer manter está salvo em outro lugar.
```
sudo rm -rf $HOME
```

16. Parabéns

Neste laboratório, você criou um aplicativo da Web e configurou o Cloud Run para implantar automaticamente o aplicativo quando uma mudança for feita no código-fonte. Em seguida, você modificou o aplicativo e o implantou novamente.

Se você gostou deste laboratório, tente novamente em outra linguagem de programação ou framework:

Se você tem interesse em participar de um estudo de pesquisa de experiência do usuário (UX) para melhorar os produtos com que trabalha hoje, faça sua inscrição aqui.

Confira algumas opções para continuar aprendendo:

Documentos: use o Firebase GenKit como uma abstração de modelo flexível que facilita a integração de qualquer API de modelo e o uso de modelos mantidos pela comunidade.
Codelab: Como implantar um app de chat com tecnologia Gemini no Cloud Run
Como usar a chamada de função do Gemini com o Cloud Run
Workshop sob demanda: Integração do Google Kubernetes Engine
Como usar a API Video Intelligence do Cloud Run Jobs para processar um vídeo cena por cena