1. Visão geral
Neste laboratório, você vai criar um agente da IA generativa, conectá-lo ao aplicativo do Cloud Run e integrá-lo ao espaço de trabalho do Slack.
O que você vai aprender
Há várias partes principais no laboratório:
- Implantar o aplicativo do Cloud Run para integração com as APIs Gemini
- Criar e implantar o Vertex AI Agent
- Integrar o agente ao Slack
- Configurar o repositório de dados para perguntas e respostas em documentos PDF
Pré-requisitos
- Para fazer este laboratório, é preciso saber usar o console do Cloud e os ambientes do Cloud Shell.
2. Configuração e requisitos
Configuração do projeto do Cloud
- Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.
- O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
- O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como
PROJECT_ID
. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto. - Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.
- Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.
Configuração do ambiente
Abra o chat do Gemini.
Ative a API Cloud AI Companion:
Clique em Start chatting
e siga uma das perguntas de exemplo ou digite seu próprio comando para testar.
Sugestões de comandos:
- Explicar o Cloud Run em cinco pontos principais.
- Você é gerente de produto do Google Cloud Run e explica o Cloud Run para um estudante em cinco pontos-chave.
- Você é gerente de produto do Google Cloud Run e explica o Cloud Run para um desenvolvedor certificado do Kubernetes em cinco pontos-chave.
- Você é gerente de produto do Google Cloud Run e explica a um desenvolvedor sênior em cinco pontos principais quando usar o Cloud Run em vez do GKE.
Confira o guia de comandos para saber como escrever comandos melhores.
Como o Gemini para o Google Cloud usa seus dados
Compromisso do Google com a privacidade
O Google foi um dos primeiros no setor a publicar um compromisso de privacidade de IA/ML, que descreve que os clientes precisam ter o mais alto nível de segurança e controle sobre os dados armazenados na nuvem.
Dados que você envia e recebe
As perguntas que você faz ao Gemini, incluindo qualquer informação de entrada ou código que você envia para análise ou conclusão, são chamadas de comandos. As respostas ou códigos que você recebe do Gemini são chamados de respostas. O Gemini não usa seus comandos nem as respostas deles como dados para treinar os modelos.
Criptografia de instruções
Quando você envia comandos para o Gemini, os dados são criptografados em trânsito como entrada para o modelo subjacente no Gemini.
Dados do programa gerados pelo Gemini
O Gemini é treinado com base no código próprio do Google Cloud e em códigos de terceiros selecionados. Você é responsável pela segurança, testes e eficácia do seu código, incluindo qualquer preenchimento, geração ou análise de código que o Gemini oferece.
Saiba mais sobre como o Google processa suas solicitações.
3. Opções para testar solicitações
Você tem várias opções para testar comandos.
O Vertex AI Studio faz parte da plataforma Vertex AI do Google Cloud, projetada especificamente para simplificar e acelerar o desenvolvimento e o uso de modelos de IA generativa.
O Google AI Studio é uma ferramenta baseada na Web para prototipagem e experimentação com engenharia de comando e a API Gemini.
- Web app Gemini (gemini.google.com)
O web app Gemini (gemini.google.com) é uma ferramenta baseada na Web projetada para ajudar você a explorar e usar o poder dos modelos de IA do Gemini do Google.
- App Google Gemini para dispositivos móveis no Android e Google app no iOS
4. Clone o repositório
Volte ao console do Google Cloud e ative o Cloud Shell clicando no ícone à direita da barra de pesquisa.
No terminal aberto, execute os seguintes comandos:
git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git
cd genai-for-developers
git checkout slack-agent-jira-lab
Clique em "Abrir editor".
Usando o item de menu "File / Open Folder
", abra "genai-for-developers
".
Abra um novo terminal.
5. Criar a conta de serviço
Crie uma nova conta de serviço e chaves.
Você vai usar essa conta de serviço para fazer chamadas de API para a API Vertex AI Gemini no aplicativo do Cloud Run.
Configure os detalhes do projeto usando os detalhes do projeto do Qwiklabs.
Exemplo: qwiklabs-gcp-00-2c10937585bb
gcloud config set project YOUR_QWIKLABS_PROJECT_ID
Crie uma conta de serviço e conceda papéis.
export LOCATION=us-central1
export PROJECT_ID=$(gcloud config get-value project)
export SERVICE_ACCOUNT_NAME='vertex-client'
export DISPLAY_NAME='Vertex Client'
export KEY_FILE_NAME='vertex-client-key'
gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"
gcloud iam service-accounts keys create $KEY_FILE_NAME.json --iam-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
Se for preciso autorizar, clique em "Autorizar" para continuar.
Ative os serviços necessários para usar as APIs Vertex AI e o chat Gemini.
gcloud services enable \
generativelanguage.googleapis.com \
aiplatform.googleapis.com \
cloudaicompanion.googleapis.com \
run.googleapis.com \
cloudresourcemanager.googleapis.com
Ative os serviços necessários para usar as APIs Vertex AI e o chat Gemini.
gcloud services enable \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
runapps.googleapis.com \
workstations.googleapis.com \
servicemanagement.googleapis.com \
secretmanager.googleapis.com \
containerscanning.googleapis.com
Ativar o Gemini Code Assist
Clique no ícone "Gemini" no canto inferior direito e em "Sign-in
" e "Select Google Cloud project
".
Na janela pop-up, selecione seu projeto do Qwiklabs.
Exemplo:
Abra o arquivo "devai-api/app/routes.py
" e clique com o botão direito do mouse em qualquer lugar do arquivo. Em seguida, selecione "Gemini Code Assist > Explain
this"
" no menu de contexto.
Analise a explicação do Gemini para o arquivo selecionado.
6. Implantar a API Devai no Cloud Run
Verifique se você está na pasta certa.
cd ~/genai-for-developers/devai-api
Neste laboratório, seguimos as práticas recomendadas e usamos o Secret Manager para armazenar e referenciar os valores do token de acesso e da chave da API LangChain no Cloud Run.
Defina variáveis de ambiente.
export JIRA_API_TOKEN=your-jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true
export GITLAB_PERSONAL_ACCESS_TOKEN=your-gitlab-token
export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"
export GITLAB_REPOSITORY="GITLAB-USERID/GITLAB-REPO"
export LANGCHAIN_API_KEY=your-langchain-key
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
Armazene o token de acesso do JIRA no Secret Manager.
echo -n $JIRA_API_TOKEN | \
gcloud secrets create JIRA_API_TOKEN \
--data-file=-
Armazene o token de acesso do GitLab no Secret Manager.
echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
--data-file=-
Armazene a chave da API LangChain no Secret Manager.
echo -n $LANGCHAIN_API_KEY | \
gcloud secrets create LANGCHAIN_API_KEY \
--data-file=-
Implantar o aplicativo no Cloud Run.
gcloud run deploy devai-api \
--source=. \
--region="$LOCATION" \
--allow-unauthenticated \
--service-account vertex-client \
--set-env-vars PROJECT_ID="$PROJECT_ID" \
--set-env-vars LOCATION="$LOCATION" \
--set-env-vars GITLAB_URL="$GITLAB_URL" \
--set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
--set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
--set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
--set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
--set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
--set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
--set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
--set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
--update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
--update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
--update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
--min-instances=1 \
--max-instances=3
Responda Y
para criar o repositório do Docker no Artifact Registry.
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in
region [us-central1] will be created.
Do you want to continue (Y/n)? y
Peça ao Gemini para explicar o comando:
Analise o fluxo gcloud run deploy SERVICE_NAME --source=.
abaixo. Saiba mais.
Nos bastidores, esse comando usa o buildpacks
e o Cloud Build
do Google Cloud para criar automaticamente imagens de contêiner a partir do código-fonte sem ter que instalar o Docker na máquina ou configurar os pacotes de criação ou o Cloud Build. Ou seja, o comando único descrito acima faz o que exigiria os comandos gcloud builds submit
e gcloud run deploy
.
Se você tiver fornecido um Dockerfile(como fizemos neste repositório), o Cloud Build vai usá-lo para criar imagens de contêiner em vez de depender dos buildpacks para detectar e criar imagens de contêiner automaticamente. Para saber mais sobre buildpacks, consulte a documentação.
Revise os registros do Cloud Build no Console.
Revise a imagem Docker criada no Artifact Registry.
Abra cloud-run-source-deploy/devai-api
e analise as vulnerabilidades detectadas automaticamente. Verifique se há correções disponíveis e como elas podem ser corrigidas com base na descrição.
Revise os detalhes da instância do Cloud Run no console do Cloud.
Teste o endpoint executando o comando curl.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"prompt": "PROJECT-100"}' \
$(gcloud run services list --filter="(devai-api)" --format="value(URL)")/generate
Confira a saída:
7. Vertex AI Agent Builder
Pesquise e abra o "Agent Builder".
Ativar APIs
Criar um app de agente:
Digite "Agente" como nome de exibição e clique em "Concordar e criar".
Definir o nome do agente:
Agent
Definir objetivo:
Help user with questions about JIRA project
Instruções do conjunto:
- Greet the users, then ask how you can help them today.
- Summarize the user's request and ask them to confirm that you understood correctly.
- If necessary, seek clarifying details.
- Thank the user for their business and say goodbye.
Clique em "Salvar":
Teste o agente usando o chat do emulador no lado direito:
Abra o menu "Ferramentas" e crie uma nova ferramenta:
Selecione OpenAPI
no menu suspenso "Tipo".
Definir nome da ferramenta:
jira-project-status
Descrição do conjunto:
Returns JIRA project status
Set Schema (YAML): substitua o URL DO SEU CLOUD RUN.
openapi: 3.0.0
info:
title: CR API
version: 1.0.0
description: >-
This is the OpenAPI specification of a service.
servers:
- url: 'https://YOUR CLOUD RUN URL'
paths:
/create-jira-issue:
post:
summary: Request impl
operationId: create-jira-issue
requestBody:
description: Request impl
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
responses:
'200':
description: Generated
content:
application/json:
schema:
type: string
/generate:
post:
summary: Request impl
operationId: generate
requestBody:
description: Request impl
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
responses:
'200':
description: Generated
content:
application/json:
schema:
type: string
/test:
get:
summary: Request impl
operationId: test
responses:
'200':
description: Generated
content:
application/json:
schema:
type: string
components:
schemas:
Prompt:
type: object
required:
- prompt
properties:
prompt:
type: string
Salve a configuração da ferramenta:
Volte à configuração do agente e atualize as instruções para usar a ferramenta:
Adicione instruções para usar a nova ferramenta:
- Use ${TOOL: jira-project-status} to help the user with JIRA project status.
Alterne para a guia "Exemplos" e adicione um novo exemplo:
Definir nome de exibição:
jira-project-flow
Usando o menu na parte de baixo, modele a conversa entre o usuário e o agente:
Configuração de invocação da ferramenta:
Clique em "Salvar e cancelar". Volte para o emulador do agente e teste o fluxo.
Consulte as práticas recomendadas para agentes da Vertex AI.
Configurações do agente
Configurações de registro
Configuração do modelo.
Integração do GitGub para enviar e restaurar a configuração do agente.
Controles do emulador de agente:
8. Integração com o Slack
Abra o menu "Integrations" e clique em "Connect" no bloco do Slack.
Abra o link e crie um novo app do Slack em https://api.slack.com/apps.
Selecione em "Manifesto":
Escolher um espaço de trabalho para desenvolver seu app
Mude para YAML e cole este manifesto:
display_information:
name: Agent
description: Agent
background_color: "#1148b8"
features:
app_home:
home_tab_enabled: false
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: Agent
always_online: true
oauth_config:
scopes:
bot:
- app_mentions:read
- chat:write
- im:history
- im:read
- im:write
- incoming-webhook
settings:
event_subscriptions:
request_url: https://dialogflow-slack-4vnhuutqka-uc.a.run.app
bot_events:
- app_mention
- message.im
org_deploy_enabled: false
socket_mode_enabled: false
token_rotation_enabled: false
Clique em "Criar":
Instalar no Workspace:
Selecione o canal "#general" e clique em "Permitir".
Em "Informações básicas / Credenciais do app", copie "Secret de assinatura" e defina-o na integração do Slack.
Abra "OAuth e permissões", copie "Token de acesso do OAuth do usuário de bot" e defina-o na integração do Slack.
Defina os campos obrigatórios e clique em "Iniciar".
O valor Token de acesso do agente é Token de acesso do usuário do bot do Slack.
O valor do token de assinatura do agente é "Signing Secret" do Slack.
Copie "Webhook URL" e volte para a configuração do app Slack.
Abra a seção "Assinaturas de eventos" e cole o URL.
Salve as alterações.
Abra o Slack e adicione um agente digitando "@Agent".
Por exemplo, adicionar um app com o nome "@CX".
Peça ao agente um resumo do projeto do JIRA.
9. Perguntas e respostas sobre documentos PDF
crie o bucket do Cloud Storage
Abra o GCS no console do Cloud: https://console.cloud.google.com/storage/browser
Crie um bucket.
Para o nome do bucket, digite: "pdf-docs
" + os últimos cinco dígitos do seu projeto do GCP.
Tipo de local: multi-region, us
.
Classe de armazenamento: Standard
Controle de acesso: Uniform
Proteção de dados: uncheck soft delete policy
Clique em "Create
".
Confirme "O acesso público será bloqueado".
Faça o download do relatório em PDF e faça upload dele para o bucket. https://services.google.com/fh/files/misc/exec_guide_gen_ai.pdf
Arquivo do bucket com visualização do arquivo enviado:
Configuração do repositório de dados
Volte ao Agent Console, abra "Agent
", role para baixo e clique em "+ Data store
".
Use os seguintes valores:
Nome da ferramenta: pdf-docs
Tipo: Data store
Descrição: pdf-docs
Clique em "Save
".
Clique em "Create a data store
" na parte de baixo da página.
Clique em "AGREE
" quando a pergunta "Você concorda que seus dados de pesquisa e conversa sejam armazenados na região dos EUA?" for feita.
Digite "Google
" no campo "Fornecer empresa".
Na próxima tela, clique em "CREATE DATA STORE
".
Selecione "Cloud Storage
" como a fonte de dados.
Preparar dados para ingestão
https://cloud.google.com/generative-ai-app-builder/docs/prepare-data
Os arquivos HTML e TXT precisam ter 2,5 MB ou menos.
Os arquivos PDF, PPTX e DOCX precisam ter no máximo 100 MB.
É possível importar até 100.000 arquivos por vez.
Selecionar: unstructured documents
E selecione o bucket/pasta do GCS.
Clique em "Continuar":
Para o nome do repositório de dados, digite: "pdf-docs
"
Selecione "Digital parser
" no menu suspenso.
Ative a divisão avançada.
Ative os títulos ancestrais em blocos.
Clique em "Create
".
Selecione o repositório de dados e clique em "Create
".
Clique no repositório de dados e revise os documentos, a atividade e a configuração de processamento.
A importação vai levar cerca de 5 a 10 minutos.
Opções de análise e fragmentação
É possível controlar a análise do conteúdo das seguintes maneiras:
- Parecedor digital. O analisador digital fica ativado por padrão para todos os tipos de arquivo, a menos que um tipo de analisador diferente seja especificado. O analisador digital processa documentos ingeridos se nenhum outro analisador padrão for especificado para o armazenamento de dados ou se o analisador especificado não oferecer suporte ao tipo de arquivo de um documento ingerido.
- Análise OCR para PDFs. Pré-lançamento público. Se você planeja fazer upload de PDFs digitalizados ou com texto dentro de imagens, ative o analisador de OCR para melhorar a indexação de PDFs. Consulte Sobre a análise de OCR para PDFs.
- Analisador de layout. Pré-lançamento público. Ative o analisador de layout para arquivos HTML, PDF ou DOCX se você planeja usar a Vertex AI para Pesquisa para RAG. Consulte Documentos de divisão para RAG para mais informações sobre esse analisador e como ativá-lo.
Saiba mais sobre a análise e a divisão de documentos.
Configuração da ferramenta
Volte para a guia com a configuração de ferramentas.
Atualize o navegador e selecione "pdf-docs
" no menu suspenso "Unstructured".
Configure o aterramento.
Digite "Google
" para o nome da empresa.
Configurações do payload: marque "Include snippets in the response payload
"
Clique em "Save
".
Configuração das instruções do agente
Volte para a configuração do agente.
Adicionar nova instrução:
- Provide detailed answer to users questions about the exec guide to gen ai using information in the ${TOOL:pdf-docs}
Salve a configuração.
Criar um exemplo para a ferramenta PDF-Docs
Alterne para a guia "Exemplos". Crie um novo exemplo.
Usando as ações "+
":
Adicionar "Entrada do usuário":
What are the main capabilities?
Adicione "Uso da ferramenta".
- Ferramenta e ação: "
pdf-docs
"
Entrada (requestBody)
{
"query": "Main capabilities",
"filter": "",
"userMetadata": {},
"fallback": ""
}
Saída da ferramenta:
{
"answer": "Detailed answer about main capabilities",
"snippets": [
{
"uri": "https://storage.cloud.google.com/pdf-docs-49ca4/exec_guide_gen_ai.pdf",
"text": "Detailed answer about main capabilities",
"title": "exec_guide_gen_ai"
}
]
}
Adicionar "Resposta do agente"
Detailed answer about main capabilities.
https://storage.cloud.google.com/pdf-docs-49ca4/exec_guide_gen_ai.pdf
Exemplo configurado:
Configuração de invocação da ferramenta:
Teste a configuração enviando uma pergunta ao agente no emulador.
Pergunta:
What are the 10 steps in the exec guide?
Selecione "Agent
" e clique em "Save example
".
Dê um nome "user-question-flow
" e salve.
Formate a resposta do agente e inclua o link para o documento PDF na seção de saída da ferramenta.
Salve o exemplo.
Volte ao emulador e clique em "Replay conversation
". Confira o formato da resposta atualizada.
Faça outra pergunta:
What are the main capabilities in the exec guide?
Documento PDF de origem.
Pergunta:
What should I consider when evaluating projects?
Documento PDF de origem.
Pergunta:
What are the priority use cases in Retail and CPG in the exec guide?
Documento PDF de origem.
10. Prebuilt Agents
Confira os agentes pré-criados no menu à esquerda.
Selecione um dos agentes e implante. Confira a configuração, as instruções e as ferramentas do Agente.
11. Parabéns!
Parabéns, você concluiu o laboratório!
O que aprendemos:
- Como implantar o aplicativo do Cloud Run para integrar com as APIs Gemini
- Como criar e implantar o agente da Vertex AI
- Como adicionar a integração do Slack ao agente
- Como configurar o repositório de dados para perguntas e respostas em documentos PDF
O que vem em seguida:
- Consulte as práticas recomendadas para agentes da Vertex AI.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto ou mantenha o projeto e exclua cada um dos recursos.
Excluir o projeto
O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para este tutorial.
©2024 Google LLC Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de empresas e produtos podem ser marcas registradas das empresas a que estão associados.