Visão geral

Uma das melhores ferramentas para melhorar a qualidade das respostas de modelos de linguagem grandes (LLMs) é a geração aumentada de recuperação (RAG). RAG é o padrão de recuperação de alguns dados não públicos e uso desses dados para enriquecer o comando enviado ao LLM. A RAG permite que o LLM gere respostas mais precisas com base nos dados incluídos no comando.

Você vai usar o AlloyDB, o banco de dados escalonável e de alto desempenho do Google Cloud compatível com PostgreSQL, para armazenar e pesquisar por um tipo especial de dados de vetores chamados de embeddings de vetores. Embeddings de vetores podem ser recuperados usando uma pesquisa semântica, o que permite a recuperação dos dados disponíveis que melhor correspondem à consulta de linguagem natural de um usuário. Os dados recuperados são então passados para o LLM no comando.

Para recuperar dados do banco de dados, use o MCP Toolbox, um servidor de middleware que expõe operações do banco de dados como um conjunto de ferramentas. O agente se conecta ao Toolbox para executar essas ferramentas. Isso oferece uma maneira segura, escalonável e modular de gerenciar interações com o banco de dados.

Você também vai usar a Vertex AI, a plataforma de desenvolvimento de IA unificada e totalmente gerenciada do Google Cloud para criar e usar a IA generativa. Seu aplicativo usa o Gemini Pro, um modelo de fundação multimodal que aceita a adição de imagens, áudios, vídeos e arquivos PDF em comandos de texto ou chat, além de oferecer suporte à compreensão de contexto longo.

O que você vai aprender

Neste laboratório, você vai aprender:

• Como a RAG aprimora as capacidades do LLM, recuperando informações relevantes de uma base de conhecimento.
• Como o AlloyDB pode ser usado para encontrar informações relevantes usando a pesquisa semântica.
• Como usar a Vertex AI e os modelos de fundação do Google para oferecer capacidade de IA generativa avançada aos aplicativos.

Configuração e requisitos

Antes de clicar no botão "Começar o laboratório"

Importante: leia estas instruções.

Os laboratórios são cronometrados e não podem ser pausados. O timer é iniciado quando você clica em Começar o laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático do Qwiklabs permite que você realize as atividades em um ambiente real de nuvem, não em uma simulação ou demonstração. Você receberá novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

O que é necessário

Veja os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome)
• Tempo disponível para concluir as atividades

Observação: não use seu projeto ou conta pessoal do Google Cloud neste laboratório. Observação: se você estiver usando um Pixelbook, faça o laboratório em uma janela anônima.

Como começar o laboratório e fazer login no console

1. Clique no botão Começar o laboratório. Se for preciso pagar pelo laboratório, você verá um pop-up para selecionar a forma de pagamento. Um painel aparece à esquerda contendo as credenciais temporárias que você precisa usar no laboratório.

   

2. Copie o nome de usuário e clique em Abrir console do Google. O laboratório ativa os recursos e depois abre a página Escolha uma conta em outra guia.

   Observação: abra as guias em janelas separadas, lado a lado.

3. Na página "Escolha uma conta", clique em Usar outra conta. A página de login abre.

   

4. Cole o nome de usuário que foi copiado do painel "Detalhes da conexão". Em seguida, copie e cole a senha.

Observação: é necessário usar as credenciais do painel "Detalhes da conexão". Não use suas credenciais do Google Cloud Ensina. Não use sua conta pessoal do Google Cloud, caso tenha uma neste laboratório (isso evita cobranças).

5. Acesse as próximas páginas:

• Aceite os Termos e Condições.
• Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
• Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Cloud abre nesta guia.

Observação: para acessar a lista dos produtos e serviços do Google Cloud, clique no Menu de navegação no canto superior esquerdo.

Ative o Google Cloud Shell

O Google Cloud Shell é uma máquina virtual com ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud.

O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. No console do Cloud, clique no botão "Abrir o Cloud Shell" na barra de ferramentas superior direita.

   

2. Clique em Continuar.

O provisionamento e a conexão do ambiente podem demorar um pouco. Quando você estiver conectado, já estará autenticado, e o projeto estará definido com seu PROJECT_ID. Exemplo:

A gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

• Para listar o nome da conta ativa, use este comando:

gcloud auth list

Saída:

Credentialed accounts: - @.com (active)

Exemplo de saída:

Credentialed accounts: - google1623327_student@qwiklabs.net

• Para listar o ID do projeto, use este comando:

gcloud config list project

Saída:

[core] project =

Exemplo de saída:

[core] project = qwiklabs-gcp-44776a13dea667a6 Observação: a documentação completa da gcloud está disponível no guia com informações gerais sobre a gcloud CLI .

Tarefa 1: Inicializar o ambiente

Nesta tarefa, você vai instalar o Python, o MCP Toolbox e o cliente do PostgreSQL.

SSH para a VM do app

Uma máquina virtual (VM) foi criada. Essa VM hospeda o aplicativo e o MCP Toolbox.

1. Para se conectar à VM, execute o seguinte comando no Cloud Shell:

   gcloud compute ssh app-vm --zone={{{project_0.default_zone | ZONE }}}

   Se for necessário autorizar, clique em Autorizar.

2. Para cada pergunta feita pelo comando gcloud compute ssh, clique em Enter ou Return para especificar a entrada padrão.

   Depois de uma breve espera, você vai estar logado na VM.

Instalar o Python e o Git

1. Para instalar o Python e o Git, na VM, execute os seguintes comandos:

   sudo apt update sudo apt install -y python3.11-venv git python3 -m venv .venv source ~/.venv/bin/activate pip install --upgrade pip

   Quando a instalação for concluída, você vai ficar no ambiente virtual do Python, com um comando (.venv).

   Se a sessão SSH da VM expirar ou a guia for fechada, você poderá usar o SSH na VM de novo e o comando source ~/.venv/bin/activate para reiniciar o ambiente virtual do Python.

2. Para confirmar a versão do Python, execute o seguinte comando:

   python -V

   Sua resposta deve ser parecida com esta:

   (.venv) student@app-vm:~$ python -V Python 3.11.2 (.venv) student@app-vm:~$

Instalar o cliente do PostgreSQL

1. Para instalar o cliente do PostgreSQL, execute os seguintes comandos na sessão da VM:

   sudo apt install -y postgresql-client Observação: o cliente pode já estar instalado.

Baixar a demonstração e o MCP Toolbox

1. Para clonar o código desta demonstração, execute os seguintes comandos:

   cd ~ git clone https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git cd cymbal-air-toolbox-demo

2. Para baixar o binário do MCP Toolbox, execute os seguintes comandos:

   export MCP_TOOLBOX_VERSION="{{{project_0.startup_script.gcp_mcp_toolbox_version | TOOLBOX_VERSION}}}" curl -O https://storage.googleapis.com/genai-toolbox/v$MCP_TOOLBOX_VERSION/linux/amd64/toolbox chmod +x toolbox

Tarefa 2: Criar o banco de dados de vetores

Nesta tarefa, você vai usar o cliente do PostgreSQL para criar o banco de dados de vetores.

Criar o banco de dados de vetores

Uma instância do AlloyDB já foi criada.

1. Para criar um banco de dados, execute o seguinte comando:

   export PROJECT_ID=$(gcloud config get-value project) export REGION={{{project_0.default_region | REGION }}} export ADBCLUSTER={{{project_0.startup_script.gcp_alloydb_cluster_name | CLUSTER}}} export ADBINSTANCE={{{project_0.startup_script.gcp_alloydb_primary_instance | INSTANCE}}} export INSTANCE_IP=$(gcloud alloydb instances describe $ADBINSTANCE --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)") export PGUSER={{{project_0.startup_script.gcp_alloydb_user | PG_USER}}} export PGPASSWORD={{{project_0.startup_script.gcp_alloydb_password | PG_PASSWORD}}} export PGDATABASE={{{project_0.startup_script.gcp_alloydb_database | DATABASE}}} psql "host=$INSTANCE_IP user=$PGUSER dbname=postgres" -c "CREATE DATABASE $PGDATABASE"

   O psql responde com CREATE DATABASE.

   Para que o banco de dados ofereça suporte a pesquisas semânticas, as entidades precisam ser representadas por embeddings de vetores.

2. Para ativar as embeddings de vetores nesse banco de dados, execute o seguinte comando:

   psql "host=$INSTANCE_IP user=$PGUSER dbname=$PGDATABASE" -c "CREATE EXTENSION vector"

   O psql responde com CREATE EXTENSION.

Clique em Verificar meu progresso para conferir o objetivo.

Crie o banco de dados do AlloyDB e ative a extensão do vetor.

Tarefa 3: Preencher o banco de dados de exemplo

Nesta tarefa, você vai usar o MCP Toolbox para preencher o banco de dados de vetores no AlloyDB com dados de amostra. Esses dados são usados no aplicativo de chat.

Analisar os modelos de dados

1. Para conferir o modelo de dados, execute o seguinte comando:

   cd ~/cymbal-air-toolbox-demo cat models/models.py

   Os modelos de dados em Python são mostrados aqui. O modelo inclui aeroportos, voos, comodidades nos terminais, políticas e passagens.

2. Para conferir um exemplo dos dados do aeroporto, execute os seguintes comandos:

   head -1 data/airport_dataset.csv; grep SFO data/airport_dataset.csv

   Esses comandos mostram o cabeçalho CSV que especifica os nomes de colunas para o conjunto de dados de aeroportos seguido pela linha do Aeroporto Internacional de São Francisco (SFO). Os dados do modelo de aeroporto podem ser recuperados com base no código da Associação Internacional de Transportes Aéreos (IATA) ou por país, cidade e nome do aeroporto. É possível usar a pesquisa por palavra-chave para encontrar linhas nessa tabela, portanto, não há embeddings de vetor para esses dados.

3. Para conferir um exemplo dos dados de voo, execute os seguintes comandos:

   head -1 data/flights_dataset.csv; grep -m10 "SFO" data/flights_dataset.csv

   Esses comandos mostram o cabeçalho CSV que especifica os nomes das colunas para o conjunto de dados de voos, seguido pelas 10 primeiras linhas de voos de ou para SFO. Os dados no modelo de voos podem ser recuperados com base na companhia aérea e no número do voo ou nos códigos dos aeroportos de partida e de chegada.

4. Para conferir um exemplo dos dados de comodidades, execute o seguinte comando:

   head -2 data/amenity_dataset.csv

   Esse comando mostra o cabeçalho CSV que especifica os nomes de colunas para o conjunto de dados de comodidades, seguido pela primeira comodidade.

   A primeira comodidade tem vários valores simples, incluindo nome, descrição, localização, terminal, categoria e horário de funcionamento. O próximo valor é content, que incorpora o nome, a descrição e o local. O último valor é embedding, a embedding de vetor da linha.

   A embedding é uma matriz de 768 números que é usada ao realizar uma pesquisa semântica. Essas embeddings são calculadas usando um modelo de IA fornecido pela Vertex AI. Quando um usuário faz uma consulta, é possível criar uma embedding de vetor a partir dela e recuperar dados com embeddings de vetor próximas à embedding da pesquisa.

   Os dados de política também usam embeddings de vetor de maneira semelhante.

   Observação : o cálculo de embeddings leva um tempo, então as embeddings já foram fornecidas. É possível examinar o script run_generate_embeddings.py para conferir como as embeddings são geradas.

Iniciar o Toolbox

1. Para configurar as variáveis de ambiente necessárias para o MCP Toolbox, execute os seguintes comandos:

   export ALLOYDB_POSTGRES_PROJECT=$(gcloud config get-value project) export ALLOYDB_POSTGRES_REGION={{{project_0.default_region | REGION }}} export ALLOYDB_POSTGRES_CLUSTER={{{project_0.startup_script.gcp_alloydb_cluster_name | CLUSTER}}} export ALLOYDB_POSTGRES_INSTANCE={{{project_0.startup_script.gcp_alloydb_primary_instance | PRIMARY_INSTANCE}}} export ALLOYDB_POSTGRES_DATABASE={{{project_0.startup_script.gcp_alloydb_database | DATABASE}}} export ALLOYDB_POSTGRES_USER={{{project_0.startup_script.gcp_alloydb_user | PG_USER}}} export ALLOYDB_POSTGRES_PASSWORD={{{project_0.startup_script.gcp_alloydb_password | PG_PASSWORD}}} export ALLOYDB_POSTGRES_IP_TYPE=private

   Essas variáveis de ambiente do MCP Toolbox são semelhantes às usadas para o cliente PostgreSQL.

   A próxima etapa é executar o MCP Toolbox.

2. Para executar o MCP Toolbox em segundo plano para inicialização de dados, execute o seguinte comando:

   cd ~/cymbal-air-toolbox-demo ./toolbox --prebuilt alloydb-postgres &

   O "e" comercial (&) faz com que o Toolbox seja executado em segundo plano, permitindo a inicialização do banco de dados na mesma sessão SSH.

Preencher o banco de dados

1. Para instalar as dependências do Python do app de demonstração, execute o seguinte comando:

   source ~/.venv/bin/activate pip install -r requirements.txt

2. Para executar o script do banco de dados, execute os seguintes comandos:

   export PYTHONPATH=~/cymbal-air-toolbox-demo python data/run_database_init.py

   O primeiro comando adiciona um caminho aos módulos do Python, e o script de inicialização preenche o banco de dados.

3. Para verificar os dados preenchidos, execute o seguinte comando:

   psql "host=$INSTANCE_IP user=$PGUSER dbname=$PGDATABASE" -c "SELECT COUNT(*) FROM airports"

   O comando do PostgreSQL retorna o número de aeroportos na tabela "airports".

4. Para encerrar o processo em segundo plano do Toolbox, execute o seguinte comando:

   pkill toolbox

Preencha o banco de dados com o conjunto de amostra de dados.

Tarefa 4: Criar uma conta de serviço para o MCP Toolbox

Nesta tarefa, você vai criar uma conta de serviço para o MCP toolbox.

No nosso app de chat, o MCP Toolbox é responsável por extrair informações relevantes do banco de dados. Ele extrai as informações necessárias do banco de dados com base na solicitação de um aplicativo de IA. Essa conta de serviço é usada como a identidade do serviço do MCP Toolbox em execução no Cloud Run.

Criar conta de serviço

O usuário SSH não tem permissão para que a instância do projeto conceda o papel correto à conta de serviço. Você cria a conta de serviço usando uma nova guia do Cloud Shell.

1. No Cloud Shell, para abrir uma nova guia, clique em Abrir uma nova guia (+).

2. Para criar uma conta de serviço, execute o seguinte comando na nova guia:

   gcloud iam service-accounts create toolbox-identity

   Essa conta de serviço é criada.

   Observação: se um erro for retornado informando que você não tem uma conta ativa selecionada, isso pode ser apenas um atraso na propagação. Execute o comando novamente.

3. Para conceder à conta de serviço os privilégios necessários, execute o seguinte comando:

   export PROJECT_ID=$(gcloud config get-value project) gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/alloydb.client" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/serviceusage.serviceUsageConsumer" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/secretmanager.secretAccessor"

   Essa conta de serviço recebe os seguintes papéis:

   • roles/alloydb.client permite que o Toolbox acesse bancos de dados do AlloyDB.
   • roles/serviceusage.serviceUsageConsumer permite que o Toolbox consuma serviços.
   • roles/secretmanager.secretAccessor permite que o Toolbox recupere secrets armazenados no Secret Manager.

4. Para fechar a nova guia, execute o seguinte comando:

   exit

Crie a identidade de recuperação da conta de serviço.

Tarefa 5: Registrar a tela de permissão OAuth

Nesta tarefa, você vai registrar a tela de permissão OAuth que é apresentada aos usuários que estão fazendo login.

Quando você usa o OAuth 2.0 para autorização, o Google exibe uma tela de permissão para capturar o consentimento do usuário para compartilhar dados com o aplicativo.

1. No console do Google Cloud, selecione o menu de navegação () e depois APIs e serviços > Tela de permissão OAuth.

2. Clique em Primeiros passos.

3. Em Nome do app, digite Cymbal Air.

4. Clique em E-mail de suporte ao usuário, depois no e-mail do estudante e, em seguida, em Próxima.

5. Em Público-alvo, selecione Interno e clique em Próxima.

   Os usuários com acesso ao projeto devem conseguir fazer login no app.

6. No painel esquerdo das instruções do laboratório, copie o Nome de usuário.

   

7. Em Dados de contato, cole o nome de usuário copiado.

8. Clique em Próxima.

9. Clique em Caixa de seleção para aceitar a Política de Dados do Usuário, depois em Continue e em Criar.

   A tela de permissão foi configurada.

Tarefa 6: Criar um ID do cliente para o aplicativo

Nesta tarefa, você vai criar um ID do cliente para o aplicativo.

O aplicativo precisa de um ID do cliente para usar o serviço OAuth do Google. Você configura as origens permitidas que podem fazer essa solicitação e um URI de redirecionamento para onde o app da Web é redirecionado depois que o usuário consente em fazer login.

1. No console do Google Cloud, selecione o Menu de navegação () e depois APIs e serviços > Credenciais.

2. Clique em Criar credenciais e em ID do cliente OAuth.

   Um ID do cliente é usado para identificar um único aplicativo nos servidores OAuth do Google.

3. Em Tipo de aplicativo, selecione Aplicativo da Web.

4. Em Nome, insira Cymbal Air.

   É possível gerar a origem do JavaScript e redirecionar o URI usando o Cloud Shell.

5. No Cloud Shell, para abrir uma nova guia, clique em Abrir uma nova guia (+).

6. Para conseguir o URI de origem e de redirecionamento, na nova guia, execute os seguintes comandos:

   echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"

7. Em Origens JavaScript autorizadas, clique em + Adicionar URI.

   Observação: selecione o botão Adicionar URI em Origens JavaScript autorizadas, não em URIs de redirecionamento autorizados.

8. Copie o URI de origem criado pelo comando "echo" e cole os URIs 1 em URI.

9. Para URIs de redirecionamento autorizados, clique em Adicionar URI.

   Observação: este é o segundo botão Adicionar URI, em URIs de redirecionamento autorizados.

10. Copie o URI de redirecionamento criado pelo comando "echo" e cole os URIs 1 em URI.

11. Para criar a variável de ambiente, mude para a guia SSH do Cloud Shell da VM e cole o seguinte comando sem clicar em Enter:

    export CLIENT_ID= Observação: verifique se você está criando a variável de ambiente CLIENT_ID na sessão da máquina virtual.

12. Na janela Credenciais, clique em Criar.

    O ID e a chave secreta do cliente são criados. Para este aplicativo de teste, use apenas o ID do cliente.

13. Clique em Copiar ID do cliente ().

    O ID do cliente é copiado para a área de transferência.

    Observação: o ID do cliente também pode ser copiado da página Credenciais.

14. Na guia SSH do Cloud Shell da VM, cole o ID do cliente e clique em Enter.

    A exportação vai ficar parecida com esta:

    export CLIENT_ID=937631684809-q7hs2r191jbks7f7dopih2uafuknb92h.apps.googleusercontent.com

Crie um ID do cliente para o aplicativo.

Tarefa 7: Implantar o Toolbox no Cloud Run

Nesta tarefa, você vai implantar o MCP Toolbox no Cloud Run.

Criar o arquivo de configuração para o Toolbox

Um arquivo tools.yaml de exemplo é fornecido para o Toolbox, mas várias configurações precisam ser modificadas.

1. Para conferir as definições de configuração, execute o seguinte comando:

   head -20 ~/cymbal-air-toolbox-demo/tools.yaml

   Esse arquivo YAML contém configurações para o banco de dados e para o OAuth.

   Vamos ter algo parecido com isto:

   sources: my-pg-instance: kind: alloydb-postgres project: retrieval-app-testing region: us-central1 cluster: my-alloydb-cluster instance: my-alloydb-instance database: assistantdemo user: postgres password: postgres authServices: my_google_service: kind: google clientId: 706535509072-qa5v22ur8ik8o513b0538ufo0ne9jfn5.apps.googleusercontent.com

2. Para atualizar as configurações e corresponder ao seu ambiente, execute os seguintes comandos:

   export PROJECT="$(gcloud config get-value project)" export REGION="{{{project_0.default_region | REGION }}}" export CLUSTER="{{{project_0.startup_script.gcp_alloydb_cluster_name | CLUSTER}}}" export INSTANCE="{{{project_0.startup_script.gcp_alloydb_primary_instance | PRIMARY_INSTANCE}}}" export DATABASE="{{{project_0.startup_script.gcp_alloydb_database | DATABASE}}}" export USER="{{{project_0.startup_script.gcp_alloydb_user | PG_USER}}}" export PASSWORD="{{{project_0.startup_script.gcp_alloydb_password | PG_PASSWORD}}}" export IP_TYPE="private" sed \ -e "s/^\( *project:\).*$/\1 $PROJECT/" \ -e "s/^\( *region:\).*$/\1 $REGION/" \ -e "s/^\( *cluster:\).*$/\1 $CLUSTER/" \ -e "s/^\( *instance:\).*$/\1 $INSTANCE/" \ -e "s/^\( *database:\).*$/\1 $DATABASE/" \ -e "s/^\( *user:\).*$/\1 $USER/" \ -e "s/^\( *password:\).*$/\1 $PASSWORD\\n ipType: $IP_TYPE/" \ -e "s/^\( *clientId:\).*$/\1 $CLIENT_ID/" \ ~/cymbal-air-toolbox-demo/tools.yaml > ~/tools.yaml

   Esses comandos usam sed para substituir as configurações específicas no arquivo de exemplo tools.yaml. A linha "ipType" também é adicionada abaixo da linha "password", porque o tipo de IP padrão é público.

3. Para conferir as atualizações de arquivo, execute o seguinte comando:

   head -20 ~/tools.yaml

   A parte de cima do arquivo de configurações agora contém seus valores.

   As configurações sensíveis, em especial a senha do banco de dados e o ID do cliente, precisam ser protegidas como secrets.

Criar um secret para o arquivo tools.yaml

Em vez de fazer check-in de informações sensíveis em um repositório de código ou como parte do app em execução, use o Secret Manager para proteger seus secrets.

1. Para criar um secret, execute o seguinte comando:

   cd ~ gcloud secrets create tools --data-file=tools.yaml

2. Para validar se a chave secreta foi armazenada, execute o seguinte comando:

   gcloud secrets describe tools

   Agora você vai ver que há um secret chamado "tools".

Implantar o Toolbox no Cloud Run

1. Para implantar o Toolbox no Cloud Run, na guia SSH da VM do Cloud Shell, execute os seguintes comandos:

   export REGION={{{project_0.default_region | REGION }}} export MCP_TOOLBOX_VERSION="{{{project_0.startup_script.gcp_mcp_toolbox_version | TOOLBOX_VERSION}}}" export IMAGE="us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$MCP_TOOLBOX_VERSION" gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region $REGION \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ --network default \ --subnet default \ --no-allow-unauthenticated \ --quiet

   Aguarde até que a implantação seja concluída.

2. Para verificar a política, execute o seguinte comando:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud run services list --filter="(toolbox)" --format="value(URL)")

   Se a mensagem "Hello World" aparecer, o serviço estará funcionando e atendendo às solicitações.

Implante o serviço do Toolbox.

Tarefa 8: Executar o aplicativo de amostra

Nesta tarefa, você executa um aplicativo de chat de exemplo que usa o serviço de recuperação.

Executar o aplicativo

1. Para voltar à raiz do aplicativo de chat, na guia SSH da VM do Cloud Shell, execute os seguintes comandos:

   source ~/.venv/bin/activate cd ~/cymbal-air-toolbox-demo

   Antes de iniciar o aplicativo, é preciso configurar algumas variáveis de ambiente. A funcionalidade básica do aplicativo, incluindo a consulta de voos e a devolução de comodidades do aeroporto, exige que uma variável de ambiente chamada TOOLBOX_URL contenha o URL do serviço do Toolbox em execução no Cloud Run.

2. Para especificar o URL do serviço do Toolbox, execute os seguintes comandos:

   export TOOLBOX_URL=$(gcloud run services list --filter="(toolbox)" --format="value(URL)") echo $TOOLBOX_URL

   O URL do Toolbox é usado pelo aplicativo local para acessar bancos de dados pelo MCP Toolbox.

3. Para executar o aplicativo, execute o seguinte comando:

   python run_app.py

   Sua resposta deve ser parecida com esta:

   (.venv) student-03-d87d6b142a95@app-vm:~/cymbal-air-toolbox-demo$ python run_app.py INFO: Started server process [26127] INFO: Waiting for application startup. Carregando o aplicativo... INFO: A inicialização do aplicativo foi concluída. INFO: Uvicorn em execução em http://0.0.0.0:8081 (Pressione CTRL+C para sair)

   Agora o aplicativo está em execução.

Conecte-se à VM

Há várias maneiras de se conectar ao aplicativo em execução na VM. Por exemplo, é possível abrir a porta 8081 na VM pelas regras de firewall na VPC ou criar um balanceador de carga com IP público. Aqui você usa um túnel SSH para a VM, convertendo a porta do Cloud Shell 8080 para a porta da VM 8081.

1. No Cloud Shell, para abrir uma nova guia, clique em Abrir uma nova guia (+).

2. Para criar um túnel SSH para a porta da VM, execute o seguinte comando na nova guia:

   gcloud compute ssh app-vm --zone={{{project_0.default_zone | ZONE }}} -- -L localhost:8080:localhost:8081

   O comando gcloud conecta a porta 8080 no Cloud Shell com a porta 8081 na VM. Ignore a mensagem de erro "Não é possível atribuir o endereço solicitado".

3. Para executar o aplicativo no navegador da Web, clique em Visualização da Web e selecione Visualizar na porta 8080.

   

   Uma nova guia é aberta no navegador e o aplicativo é executado. O aplicativo Cymbal Air mostra a mensagem "Bem-vindo ao Cymbal Air! Como posso ajudar?"

4. Digite a seguinte consulta:

   Quando é o próximo voo para Los Angeles?

   O aplicativo responde com o próximo voo de SFO para LAX ou pede mais informações.

5. Digite a seguinte consulta:

   Para esse voo, quais restaurantes estão perto do portão de embarque?

   O app de chat pode pedir que você informe qual voo, mas ele entende o contexto e responde com restaurantes perto do portão de embarque em SFO.

Tarefa 9: Fazer login no aplicativo (opcional)

Nesta tarefa, você vai fazer o login no aplicativo para reservar o voo.

1. Clique em Fazer login.

   Uma janela pop-up será aberta.

2. Na janela pop-up, selecione o estudante.

3. Para permitir que a Cymbal Air acesse as informações sobre o usuário estudante, clique em Continuar.

   A conta do estudante será logada.

4. Digite a seguinte consulta:

   Reserve esse voo.

   O aplicativo apresenta o voo em questão.

5. Clique em Tudo certo. Reservar.

   O voo foi reservado.

6. Digite a seguinte consulta:

   Quais voos eu reservei?

   O voo que você acabou de reservar é mostrado.

   O app de chat pode ajudar a responder perguntas dos usuários, como:

   • Tem alguma loja de luxo perto do portão D50?
   • Onde posso tomar um café perto do portão A6?

   O aplicativo usa os modelos de fundação mais recentes do Google para gerar respostas e adicionar informações sobre voos e comodidades do banco de dados operacional do AlloyDB. Saiba mais sobre este aplicativo de demonstração na página do GitHub do projeto.

Parabéns!

Você criou um aplicativo de chat que usa modelos de linguagem grandes (LLMs) e geração aumentada de recuperação (RAG) para criar conversas interessantes e informativas.

Próximas etapas / Saiba mais

• Leia mais informações sobre o Serviço de Recuperação de MCP e o aplicativo de amostra.
• Leia mais informações sobre o MCP Toolbox for Databases.

Finalize o laboratório

Clique em Terminar o laboratório após a conclusão. O Google Cloud Ensina remove os recursos usados e limpa a conta por você.

Você vai poder avaliar sua experiência no laboratório. Basta selecionar o número de estrelas, digitar um comentário e clicar em Enviar.

O número de estrelas indica o seguinte:

• 1 estrela = muito insatisfeito
• 2 estrelas = insatisfeito
• 3 estrelas = neutro
• 4 estrelas = satisfeito
• 5 estrelas = muito satisfeito

Feche a caixa de diálogo se não quiser enviar feedback.

Para enviar seu feedback, fazer sugestões ou correções, use a guia Suporte.

Manual atualizado em 13 de outubro de 2025

Laboratório testado em 13 de outubro de 2025

Copyright 2025 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.