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 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 de trabalho ou escolar. 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 reutilize um projeto atual.
- Confirme se o faturamento está ativado em Meus projetos no Cloud Billing
- .
- Se o novo projeto mostrar
Billing is disabled
na colunaBilling account
:- Clique nos três pontos na coluna
Actions
. - Clique em Mudar faturamento.
- Selecione a conta de faturamento que você quer usar.
- Clique nos três pontos na coluna
- Se você estiver participando de um evento de IA de última geração para desenvolvedores, a conta provavelmente terá o nome Conta de faturamento de teste do Google Cloud Platform.
- Se o novo projeto mostrar
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.
- Clique no menu de navegação
- 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 projetos com:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- É possível listar todos os IDs de projetos com:
- Formato:
- Se for preciso autorizar, clique em Autorizar para continuar.
- Você vai receber esta mensagem:
Se você receber umaUpdated property [core/project].
WARNING
e receber uma solicitaçãoDo you want to continue (Y/N)?
, provavelmente inseriu o ID do projeto incorretamente. PressioneN
, pressioneEnter
e tente executar o comandogcloud 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 global do Git como
main
:git config --global init.defaultBranch main
7. Escrever seu código
Para escrever um aplicativo em Next.js:
- Navegue até o diretório principal:
cd ~
- Crie o novo aplicativo
codelab-genai
Next.js:npx create-next-app@latest codelab-genai \ --ts \ --eslint \ --tailwind \ --no-src-dir \ --app \ --no-import-alias
- Se você for solicitado a instalar o
create-next-app
, pressioneEnter
para continuar:Need to install the following packages: create-next-app@14.2.14 Ok to proceed? (y)
- Navegue até o diretório
codelab-genai
:cd codelab-genai
- Abra o arquivo
page.tsx
no editor do Cloud Shell: Um arquivo vai aparecer na parte de cima da tela. É aqui que você pode editar o arquivocloudshell edit app/page.tsx
page.tsx
. - Exclua o código atual. Copie e cole o código abaixo no arquivo
page.tsx
aberto: Depois de 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!".import React from "react"; export default function Home() { return ( <main> Hello World! </main> ); }
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 seu repositório do Git
git init -b main
- Fazer login na CLI do GitHub
Pressionegh auth login
Enter
para aceitar as opções padrão e siga as instruções na ferramenta CLI do GitHub, incluindo:- Em qual conta você quer fazer login?
GitHub.com
- Qual é seu protocolo preferido para operações do Git neste host?
HTTPS
- Autenticar o Git com suas credenciais do GitHub?
Y
(pule se não aparecer) - Como você quer autenticar o GitHub CLI?
Login with a web browser
- Copiar o código único
- Abra https://github.com/login/device.
- Cole seu código único
- Clique em Autorizar GitHub.
- Concluir o login
- Em qual conta você quer fazer login?
- Confirme que você fez login:
Se você tiver feito login, o nome de usuário do GitHub vai aparecer.gh api user -q ".login"
- Criar uma variável
GITHUB_USERNAME
GITHUB_USERNAME=$(gh api user -q ".login")
- Confirme se você criou a variável de ambiente:
Se você criou a variável, o nome de usuário do GitHub vai ser exibido.echo ${GITHUB_USERNAME}
- Crie um repositório do GitHub vazio chamado
codelab-genai
: Se você receber o erro:gh repo create codelab-genai --private
Você já tem um repositório chamadoGraphQL: Name already exists on this account (createRepository)
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 oorigin
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 este commit:
git add .
- Crie a primeira confirmação:
git commit -m "add http server"
- Envie a confirmação para a ramificação
main
do repositórioorigin
: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/app/page.tsx \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 correto do Google Cloud no console
- Clique em CONECTAR REPOSITÓRIO.
- Clique em CONFIGURAR COM O CLOUD BUILD
- .
- 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.
- Clique em Autenticar e em Continuar.
- Depois de fazer login, uma mensagem vai aparecer na página do Cloud Run informando que o app GitHub não está instalado em nenhum dos seus repositórios.
- 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.
- Selecione
your-user-name/codelab-genai
como Repositório- .
- Se o repositório não estiver presente, clique no link Gerenciar repositórios conectados.
- Deixe Ramificação como
^main$
- 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
eFunction target
) como estão.
- Deixe os outros campos (
- Clique em Salvar.
- Selecione GitHub como o provedor do repositório
- 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
Voltar ao editor do Cloud Shell
Se o editor do Cloud Shell ainda estiver aberto, pule estas etapas.
- 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.
- Clique no menu de navegação
- 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 projetos com:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- É possível listar todos os IDs de projetos com:
- Formato:
- Se for preciso autorizar, clique em Autorizar para continuar.
- Você vai receber esta mensagem:
Se você receber umaUpdated property [core/project].
WARNING
e receber uma solicitaçãoDo you want to continue (Y/N)?
, provavelmente inseriu o ID do projeto incorretamente. PressioneN
, pressioneEnter
e tente executar o comandogcloud config set project
novamente.
Adicionar a Vertex AI ao seu aplicativo
- Volte ao terminal do Cloud Shell na parte de baixo da tela.
- Verifique se você ainda está no diretório correto:
cd ~/codelab-genai
- Instale o SDK da Vertex AI para Node.js:
npm install @google-cloud/vertexai
- Instale o SDK do Google Auth para Node.js:
npm install google-auth-library
- Crie
app/actions.ts
no terminaltouch app/actions.ts
- Abra
actions.ts
no editor do Cloud Shellcloudshell edit app/actions.ts
- Copie e cole o código abaixo no arquivo
actions.ts
aberto:'use server' import { VertexAI } from '@google-cloud/vertexai'; import { GoogleAuth } from 'google-auth-library'; const auth = new GoogleAuth(); export async function getFunFactsAction(animal: string) { const project = await auth.getProjectId(); const vertex = new VertexAI({ project: project }); const generativeModel = vertex.getGenerativeModel({ model: 'gemini-1.5-flash' }); const prompt = `Give me 10 fun facts about ${animal || 'dog'}. Return as json as an array in the format ['fact 1', 'fact 2'] Remove backticks and other markdown formatting.`; const resp = await generativeModel.generateContent(prompt); if (!resp.response.candidates) { throw new Error('Did not receive response candidates.') } console.log({ text: resp.response.candidates[0].content.parts[0].text }) const factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || ''); return factArray; };
- Abra
page.tsx
no editor do Cloud Shellcloudshell edit ~/codelab-genai/app/page.tsx
- Substitua o código no arquivo
page.tsx
por:'use client' import React, { useState } from "react"; import { getFunFactsAction } from "./actions"; export default function Home() { const [animal, setAnimal] = useState(''); const [funFacts, setFunFacts] = useState<string[]>([]); async function getNewFunFacts() { const funFacts = await getFunFactsAction(animal); setFunFacts(funFacts); } return ( <main> <h1 className="text-xl">Animal Fun Facts!</h1> <label className="text-lg p-2 m-2">Animal</label> <input placeholder="dog" value={animal} onChange={(e) => setAnimal(e.target.value)} className="text-black border-2 p-2 m-2 rounded" /> <button onClick={getNewFunFacts} className="font-bold border-2 p-2 m-2 rounded hover:bg-white hover:text-black" > Get New Fun Facts </button> <ul className="list-disc list-inside"> {funFacts.map(function (thing) { return <li key={thing}>{thing}</li> })} </ul> </main> ); }
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 vários 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 do acesso a dados
Admin read
eData 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 como fazer isso usando o mecanismo de registro nativo do Node.js.
- Reabrir
actions.ts
no editor do Cloud Shellcloudshell edit ~/codelab-genai/app/actions.ts
- Após a chamada para
await generativeModel.generateContent(prompt)
(linha 19), adicione a seguinte linha: Esse código grava informações sobre o conteúdo gerado emconsole.log(JSON.stringify({ severity: 'DEBUG', message: 'Content is generated', prompt: prompt, response: resp.response, }));
stdout
usando o formato registro estruturado. Um agente de registro no Cloud Run captura a saída gerada emstdout
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 mudanças 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
- Aviso: Não é possível desfazer essa ação. Se você quiser excluir tudo no Cloud Shell para liberar espaço, exclua seu 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 fazer de novo em outra linguagem de programação ou framework:
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
- Como usar a API Video Intelligence do Cloud Run Jobs para processar um vídeo cena por cena
- Workshop sob demanda: Integração do Google Kubernetes Engine