Como criar um aplicativo de chat baseado em LLM e RAG usando bancos de dados do Cloud SQL e LangChain

1. Introdução

Neste codelab, você vai aprender a implantar o Serviço de recuperação de bancos de dados de IA generativa e criar um aplicativo de amostra interativo no ambiente implantado.

Confira mais informações sobre o Serviço de recuperação de IA generativa e o aplicativo de amostra aqui.

Pré-requisitos

• Conhecimentos básicos sobre o console do Google Cloud
• Habilidades básicas na interface de linha de comando e no Google Cloud Shell

O que você vai aprender

• Como criar uma instância do Cloud SQL
• Como se conectar à instância
• Como configurar e implantar o Serviço de recuperação de bancos de dados de IA generativa
• Como implantar um aplicativo de amostra com o serviço implantado

O que é necessário

• Uma conta e um projeto do Google Cloud
• Um navegador da Web, como o Chrome

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. 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.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. 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.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

3. Antes de começar

Ativar API

Alguns recursos ativados vão ter custos se você não usar o nível promocional. Em circunstâncias normais, se todos os recursos forem destruídos após a conclusão do laboratório, o custo deles não vai exceder US$ 5. É recomendável conferir o faturamento e confirmar se o exercício é adequado para você.

No Cloud Shell, verifique se o ID do projeto está configurado:

Normalmente, o ID do projeto é mostrado entre parênteses no prompt de comando do Cloud Shell, como mostra a figura:

gcloud config set project [YOUR-PROJECT-ID]

Defina a variável de ambiente PROJECT_ID para o ID do projeto do Google Cloud:

PROJECT_ID=$(gcloud config get-value project)

Ative todos os serviços necessários:

gcloud services enable sqladmin.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ gcloud services enable sqladmin.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com
Operation "operations/acf.p2-404051529011-664c71ad-cb2b-4ab4-86c1-1f3157d70ba1" finished successfully.

4. crie uma instância do Cloud SQL

Crie uma instância do Cloud SQL com suporte a vetores ativado.

Criar uma senha

Defina a senha do usuário padrão do banco de dados. Você pode definir sua própria senha ou usar uma função aleatória para gerar uma.

export CLOUDSQL_PASSWORD=`openssl rand -hex 12`

Anote o valor gerado para a senha.

echo $CLOUDSQL_PASSWORD

MySQL

É possível ativar a flag cloudsql_vector ao criar a instância. No momento, a compatibilidade com vetores é oferecida no MySQL 8.0.36 e 8.0.37.

export region=us-central1
gcloud sql instances create my-cloudsql-instance --region=$region --database-version=MYSQL_8_0_36 --database-flags=cloudsql_vector=ON --root-password=$CLOUDSQL_PASSWORD

Saída esperada do console (endereço IP editado):

student@cloudshell:~ export region=us-central1
gcloud sql instances create my-cloudsql-instance --region=$region --database-version=MYSQL_8_0_36 --database-flags=cloudsql_vector=ON --root-password=$CLOUDSQL_PASSWORD
Creating Cloud SQL instance for MYSQL_8_0_36...done.                                                                                                                                 
Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/test-project-402417/instances/my-cloudsql-instance].
NAME                   DATABASE_VERSION  LOCATION       TIER             PRIMARY_ADDRESS  PRIVATE_ADDRESS  STATUS
my-cloudsql-instance  MYSQL_8_0_36      us-central1-a  db-n1-standard-1  00.000.00.00   -                RUNNABLE

PostgreSQL

A extensão pgvector é oferecida em versões >= 11.

export region=us-central1
gcloud sql instances create my-cloudsql-instance --region=$region --database-version=POSTGRES_15 --tier=db-g1-small

Saída esperada do console (endereço IP editado):

student@cloudshell:~ export region=us-central1
gcloud sql instances create my-cloudsql-instance --region=$region --database-version=POSTGRES_15 --tier=db-g1-small
Creating Cloud SQL instance for POSTGRES_15...done.                                                                                                                                  
Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/test-project-402417/instances/my-cloudsql-instance].
NAME                   DATABASE_VERSION  LOCATION       TIER         PRIMARY_ADDRESS  PRIVATE_ADDRESS  STATUS
my-cloudsql-instance  POSTGRES_15       us-central1-a  db-g1-small  00.000.00.00     -                RUNNABLE

Depois de criar a instância, precisamos definir uma senha para o usuário padrão nela e verificar se é possível se conectar com a senha. Insira sua senha quando o prompt estiver pronto para se conectar.

gcloud sql users set-password postgres \
    --instance=my-cloudsql-instance \
    --password=$CLOUDSQL_PASSWORD
gcloud sql connect my-cloudsql-instance --user=postgres

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud sql users set-password postgres \
    --instance=my-cloudsql-instance \
    --password=$CLOUDSQL_PASSWORD
gcloud sql connect my-cloudsql-instance --user=postgres
Updating Cloud SQL user...done.                                                                                                                                                                                                                                            
Allowlisting your IP for incoming connection for 5 minutes...done.                                                                                                                                                                                                         
Connecting to database with SQL user [postgres].Password: 
psql (16.3 (Ubuntu 16.3-1.pgdg22.04+1), server 15.7)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

Saia da sessão psql:

exit

5. Preparar a máquina virtual do GCE

Criar uma conta de serviço

Como vamos usar a VM para implantar o Serviço de recuperação de bancos de dados de IA generativa e hospedar um aplicativo de amostra, a primeira etapa é criar uma conta de serviço do Google (GSA). A GSA vai ser usada pela VM do GCE, e é preciso conceder os privilégios necessários para trabalhar com outros serviços.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create compute-aip --project $PROJECT_ID
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.editor"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudsql.viewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Implantar a VM do GCE

Crie uma VM do GCE na mesma região e VPC que a instância do Cloud SQL.

No Cloud Shell, execute:

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
  --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ export ZONE=us-central1-a
student@cloudshell:~ (test-project-402417)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.71.192.233
STATUS: RUNNING

Autorizar a VM a se conectar ao Cloud SQL

Precisamos adicionar o IP público da VM à lista de redes autorizadas da instância do Cloud SQL. No Cloud Shell, execute:

O comando a seguir substitui todas as redes autorizadas na instância criada pelo IP externo da VM.

VM_EXTERNAL_IP=$(gcloud compute instances describe instance-1 --zone=us-central1-a --format='get(networkInterfaces[0].accessConfigs[0].natIP)')
gcloud sql instances patch my-cloudsql-instance --authorized-networks=$VM_EXTERNAL_IP

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ export ZONE=us-central1-a
student@cloudshell:~ (test-project-402417)$ VM_EXTERNAL_IP=$(gcloud compute instances describe instance-1 --zone=us-central1-a --format='get(networkInterfaces[0].accessConfigs[0].natIP)')
gcloud sql instances patch my-cloudsql-instance --authorized-networks=$VM_EXTERNAL_IP
When adding a new IP address to authorized networks, make sure to also include any IP addresses that have already been authorized. Otherwise, they will be overwritten and de-authorized.

Do you want to continue (Y/n)?  Y

The following message will be used for the patch API method.
{"name": "my-cloudsql-instance", "project": "test-project-402417", "settings": {"ipConfiguration": {"authorizedNetworks": [{"value": "34.71.252.173"}]}}}
Patching Cloud SQL instance...done.                                                                                                                                                                                     
Updated [https://sqladmin.googleapis.com/sql/v1beta4/projects/test-project-402417/instances/my-cloudsql-instance].

Instalar o cliente de banco de dados

MySQL

Instale o software do cliente MySQL na VM implantada.

Conecte-se à VM:

Observação: a primeira conexão SSH com a VM pode levar mais tempo, porque o processo inclui a criação da Chave RSA para conexão segura e a propagação da parte pública da chave para o projeto.

gcloud compute ssh instance-1 --zone=us-central1-a

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1 5.10.0-26-cloud-amd64 #1 SMP Debian 5.10.197-1 (2023-09-29) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$ 

Instale o comando em execução do software na VM:

sudo apt-get update
sudo apt-get install --yes default-mysql-client

Saída esperada do console:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes mysql-client
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  libconfig-inifiles-perl libdbd-mariadb-perl libdbi-perl libgdbm-compat4 libperl5.32 libterm-readkey-perl mariadb-client-10.5 mariadb-client-core-10.5 perl perl-modules-5.32
Suggested packages:
  libclone-perl libmldbm-perl libnet-daemon-perl libsql-statement-perl perl-doc libterm-readline-gnu-perl | libterm-readline-perl-perl make libtap-harness-archive-perl
The following NEW packages will be installed:
  default-mysql-client libconfig-inifiles-perl libdbd-mariadb-perl libdbi-perl libgdbm-compat4 libperl5.32 libterm-readkey-perl mariadb-client-10.5 mariadb-client-core-10.5 perl
  Perl-modules-5.32
...redacted...
Processing triggers for libc-bin (2.31-13+deb11u10) ...

PostgreSQL

Instale o software do cliente PostgreSQL na VM implantada.

Conecte-se à VM:

Observação: a primeira conexão SSH com a VM pode levar mais tempo, porque o processo inclui a criação da Chave RSA para conexão segura e a propagação da parte pública da chave para o projeto.

gcloud compute ssh instance-1 --zone=us-central1-a

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1 5.10.0-26-cloud-amd64 #1 SMP Debian 5.10.197-1 (2023-09-29) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$ 

Instale o comando em execução do software na VM:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Saída esperada do console:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
Get:4 file:/etc/apt/mirrors/debian-security.list Mirrorlist [39 B]
Hit:7 https://packages.cloud.google.com/apt google-compute-engine-bookworm-stable InRelease
Get:8 https://packages.cloud.google.com/apt cloud-sdk-bookworm InRelease [1652 B]
Get:2 https://deb.debian.org/debian bookworm InRelease [151 kB]
Get:3 https://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/15/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (15+248) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u7) ...

Conectar-se à instância

MySQL

Conecte-se à instância principal pela VM usando o MySQL.

Continue com a sessão SSH aberta na VM. Em caso de desconexão, conecte-se de novo com o mesmo comando acima.

Use o $CLOUDSQL_PASSWORD anotado e o nome da instância para se conectar ao Cloud SQL pela VM do GCE:

export CLOUDSQL_PASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export INSTANCE_NAME=my-cloudsql-instance
export INSTANCE_IP=$(gcloud sql instances list --filter=name:$INSTANCE_NAME --format="value(PRIMARY_ADDRESS)")
mysql --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD

Saída esperada do console:

student@instance-1:~$ export CLOUDSQL_PASSWORD=P9...
student@instance-1:~$ export REGION=us-central1
student@instance-1:~$ export INSTANCE_NAME=my-cloud-sql-instance
student@instance-1:~$ export INSTANCE_IP=$(gcloud sql instances list --filter=name:$INSTANCE_NAME --format="value(PRIMARY_ADDRESS)")
student@instance-1:~$ mysql  –host=$INSTANCE_IP –user=root –password=$CLOUDSQL_PASSWORD –sslmode=require 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MySQL connection id is 2824706
Server version: 8.0.36-google (Google)

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MySQL [(none)]>

Saia da sessão do MySQL, mas mantenha a conexão SSH ativa:

exit

Saída esperada do console:

MySQL [(none)]> exit
Bye
student@instance-1:~$ 

PostgreSQL

Conecte-se à instância principal pela VM com psql.

Continue com a sessão SSH aberta na VM. Em caso de desconexão, conecte-se de novo com o mesmo comando acima.

Use o $CLOUDSQL_PASSWORD anotado e o nome da instância para se conectar ao PostgreSQL pela VM do GCE:

export PGPASSWORD=<Noted password (CLOUDSQL_PASSWORD)>
export CLOUDSQL_PASSWORD=$PGPASSWORD

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export INSTANCE_NAME=my-cloudsql-instance
export INSTANCE_IP=$(gcloud sql instances list --filter=name:$INSTANCE_NAME --format="value(PRIMARY_ADDRESS)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Saída esperada do console:

student@instance-1:~$ export CLOUDSQL_PASSWORD=P9...
student@instance-1:~$ export REGION=us-central1
student@instance-1:~$ export INSTANCE_IP=$(gcloud sql instances list --filter=name:$INSTANCE_NAME --format="value(PRIMARY_ADDRESS)")
student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (13.11 (Debian 13.11-0+deb11u1), server 14.7)
WARNING: psql major version 13, server major version 14.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=> 

Saia da sessão do psql, mas mantenha a conexão SSH ativa:

exit

Saída esperada do console:

postgres=> exit
student@instance-1:~$ 

6. Inicializar o banco de dados

Vamos usar a VM de cliente como plataforma para preencher o banco de dados com dados e hospedar o aplicativo. A primeira etapa é criar um banco de dados para preencher com dados.

Criar banco de dados

MySQL

Crie um banco de dados com o nome "assistantdemo".

Na sessão da VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará redefinir as variáveis de ambiente, como as seguintes:

export CLOUDSQL_PASSWORD=<The noted Cloud SQL password>

export INSTANCE_IP=<Cloud SQL Instance IP>

mysql --host=$INSTANCE_IP  --user=root --password=$CLOUDSQL_PASSWORD -e "CREATE DATABASE assistantdemo"

Saída esperada do console (sem saída):

student@instance-1:~$ mysql --host=$INSTANCE_IP  --user=root --password=$CLOUDSQL_PASSWORD -e "CREATE DATABASE assistantdemo"
student@instance-1:~$  

PostgreSQL

Crie um banco de dados com o nome "assistantdemo".

Na sessão da VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará redefinir as variáveis de ambiente, como as seguintes:

export CLOUDSQL_PASSWORD=<The noted Cloud SQL password>

export INSTANCE_IP=<Cloud SQL Instance IP>

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"  

Saída esperada do console:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"
CREATE DATABASE
student@instance-1:~$  

Ative a extensão pgvector.

psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "CREATE EXTENSION vector"  

Saída esperada do console (sem saída):

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "CREATE EXTENSION vector"
CREATE EXTENSION
student@instance-1:~$

Preparar o ambiente Python

Para continuar, vamos usar scripts Python preparados do repositório do GitHub, mas antes é preciso instalar o software necessário.

Na VM do GCE, execute:

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

Saída esperada do console:

student@instance-1:~$ sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl
Suggested packages:
  git-daemon-run | git-daemon-sysvinit git-doc git-email git-gui gitk gitweb git-cvs git-mediawiki git-svn ed diffutils-doc
The following NEW packages will be installed:
  git git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl python3.11-venv
0 upgraded, 9 newly installed, 0 to remove and 2 not upgraded.
Need to get 12.4 MB of archives.
After this operation, 52.2 MB of additional disk space will be used.
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
...redacted...
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 23.0.1
    Uninstalling pip-23.0.1:
      Successfully uninstalled pip-23.0.1
Successfully installed pip-24.0
(.venv) student@instance-1:~$

Verifique a versão do Python.

Na VM do GCE, execute:

python -V

Saída esperada do console:

(.venv) student@instance-1:~$ python -V
Python 3.11.2
(.venv) student@instance-1:~$ 

Preparar o arquivo de configuração

Clone o repositório do GitHub com o código do serviço de recuperação e do aplicativo de amostra.

Na VM do GCE, execute:

git clone https://github.com/GoogleCloudPlatform/genai-databases-retrieval-app.git

Saída esperada do console:

student@instance-1:~$ git clone https://github.com/GoogleCloudPlatform/genai-databases-retrieval-app.git
Cloning into 'genai-databases-retrieval-app'...
remote: Enumerating objects: 525, done.
remote: Counting objects: 100% (336/336), done.
remote: Compressing objects: 100% (201/201), done.
remote: Total 525 (delta 224), reused 179 (delta 135), pack-reused 189
Receiving objects: 100% (525/525), 46.58 MiB | 16.16 MiB/s, done.
Resolving deltas: 100% (289/289), done.

MySQL

Na VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará definir variáveis de ambiente, como:

export CLOUDSQL_PASSWORD=<Noted password>

REGION=us-central1

INSTANCE_NAME=my-cloud-sql-instance

INSTANCE_IP=$(gcloud sql instances list –filter=name:$INSTANCE_NAME –format="value(PRIMARY_ADDRESS)")

export PROJECT_ID=$(gcloud config get-value project)

cd ~/genai-databases-retrieval-app/retrieval_service
cp example-config-cloudsql.yml config.yml
cp example-config-cloudsql.yml config.yml
sed -i s/engine/mysql/g config.yml
sed -i s/my-project/$PROJECT_ID/g config.yml
sed -i s/my-region/$REGION/g config.yml
sed -i s/my-instance/$INSTANCE_NAME/g config.yml
sed -i s/my-password//g config.yml
sed -i s/my_database/assistantdemo/g config.yml
sed -i s/my-user/root/g config.yml
cat config.yml

Saída esperada do console:

student@instance-1:~$ cd genai-databases-retrieval-app/retrieval_service
cp example-config-cloudsql.yml config.yml
sed -i s/127.0.0.1/$INSTANCE_IP/g config.yml
sed -i s/my-password/$CLOUDSQL_PASSWORD/g config.yml
sed -i s/my_database/assistantdemo/g config.yml
sed -i s/my-user/postgres/g config.yml
cat config.yml
host: 0.0.0.0
# port: 8080
datastore:
  # Example for MySQL
  kind: "cloudsql-mysql"
  host: 10.65.0.2
  # port: 5432
  database: "assistantdemo"
  user: "root"
  password: "P9..."

Postgres

Na VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará definir variáveis de ambiente, como:

export PGPASSWORD=<Noted password>

REGION=us-central1

INSTANCE_NAME=my-cloud-sql-instance

INSTANCE_IP=$(gcloud sql instances list –filter=name:$INSTANCE_NAME –format="value(PRIMARY_ADDRESS)")

export PROJECT_ID=$(gcloud config get-value project)

cd ~/genai-databases-retrieval-app/retrieval_service
cp example-config-cloudsql.yml config.yml
sed -i s/engine/postgres/g config.yml
sed -i s/my-project/$PROJECT_ID/g config.yml
sed -i s/my-region/$REGION/g config.yml
sed -i s/my-instance/$INSTANCE_NAME/g config.yml
sed -i s/my-password/$PGPASSWORD/g config.yml
sed -i s/my_database/assistantdemo/g config.yml
sed -i s/my-user/postgres/g config.yml
cat config.yml

Saída esperada do console:

student@instance-1:~$ cd genai-databases-retrieval-app/retrieval_service
cp example-config-cloudsql.yml config.yml
sed -i s/engine/postgres/g config.yml
sed -i s/my-project/$PROJECT_ID/g config.yml
sed -i s/my-region/$REGION/g config.yml
sed -i s/my-instance/$INSTANCE_NAME/g config.yml
sed -i s/my-password/$CLOUDSQL_PASSWORD/g config.yml
sed -i s/my_database/assistantdemo/g config.yml
sed -i s/my-user/postgres/g config.yml
cat config.yml
host: 0.0.0.0
# port: 8080
datastore:
  # Example for Postgres
  kind: "cloudsql-postgres"
  host: 10.65.0.2
  # port: 5432
  database: "assistantdemo"
  user: "postgres"
  password: "P9..."

Preencher o banco de dados

Preencha o banco de dados com o conjunto de dados de exemplo. O primeiro comando adiciona todos os pacotes necessários ao ambiente virtual do Python, e o segundo preenche o banco de dados com os dados.

Na VM do GCE, execute:

cd ~/genai-databases-retrieval-app/retrieval_service
pip install -r requirements.txt
python run_database_init.py

Saída esperada do console (editada):

student@instance-1:~/genai-databases-retrieval-app/retrieval_service$ pip install -r requirements.txt
python run_database_init.py
Collecting asyncpg==0.28.0 (from -r requirements.txt (line 1))
  Obtaining dependency information for asyncpg==0.28.0 from https://files.pythonhosted.org/packages/77/a4/88069f7935b14c58534442a57be3299179eb46aace2d3c8716be199ff6a6/asyncpg-0.28.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata
  Downloading asyncpg-0.28.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (4.3 kB)
Collecting fastapi==0.101.1 (from -r requirements.txt (line 2))
...
database init done.
student@instance-1:~/genai-databases-retrieval-app/retrieval_service$

7. Implantar o serviço de recuperação no Cloud Run

Agora você pode implantar o serviço de recuperação no Cloud Run. O serviço é responsável por trabalhar com o banco de dados e extrair as informações necessárias com base na solicitação de um aplicativo de IA.

Criar uma conta de serviço

Crie uma conta de serviço para o serviço de recuperação e conceda os privilégios necessários.

Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia do Cloud Shell, execute:

export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create retrieval-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-003)$ gcloud iam service-accounts create retrieval-identity
Created service account [retrieval-identity].

Feche a guia pelo comando de execução "sair" na guia:

exit

Implantar o serviço de recuperação

Implante o serviço para continuar na primeira guia em que você se conectou à VM via SSH.

Na sessão SSH da VM, execute:

cd ~/genai-databases-retrieval-app
gcloud alpha run deploy retrieval-service \
    --source=./retrieval_service/\
    --no-allow-unauthenticated \
    --service-account retrieval-identity \
    --region us-central1 \
    --network=default \
    --quiet

Saída esperada do console:

student@instance-1:~/genai-databases-retrieval-app$ gcloud alpha run deploy retrieval-service \
    --source=./retrieval_service/\
    --no-allow-unauthenticated \
    --service-account retrieval-identity \
    --region us-central1 \
    --network=default
This command is equivalent to running `gcloud builds submit --tag [IMAGE] ./retrieval_service/` and `gcloud run deploy retrieval-service --image [IMAGE]`

Building using Dockerfile and deploying container to Cloud Run service [retrieval-service] in project [gleb-test-short-003] region [us-central1]
X Building and deploying... Done.
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/6ebe74bf-3039-4221-b2e9-7ca8fa8dad8e?project=1012713954588].
  ✓ Creating Revision...
  ✓ Routing traffic...
    Setting IAM Policy...
Completed with warnings:
  Setting IAM policy failed, try "gcloud beta run services remove-iam-policy-binding --region=us-central1 --member=allUsers --role=roles/run.invoker retrieval-service"
Service [retrieval-service] revision [retrieval-service-00002-4pl] has been deployed and is serving 100 percent of traffic.
Service URL: https://retrieval-service-onme64eorq-uc.a.run.app
student@instance-1:~/genai-databases-retrieval-app$

Conferir o serviço

Agora é possível conferir se o serviço está sendo executado corretamente e se a VM tem acesso ao endpoint. Usamos o utilitário gcloud para receber o endpoint do serviço de recuperação. Como alternativa, verifique no console do Cloud e substitua no comando curl "$(gcloud run services list –filter="(retrieval-service)" pelo valor de lá.

Na sessão SSH da VM, execute:

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

Saída esperada do console:

student@instance-1:~/genai-databases-retrieval-app$ curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(retrieval-service)" --format="value(URL)")
{"message":"Hello World"}student@instance-1:~/genai-databases-retrieval-app$

Se a mensagem "Hello World" for mostrada, significa que o serviço está funcionando e atendendo às solicitações.

8. Implantar o aplicativo de amostra

Agora que o serviço de recuperação está em execução, podemos implantar um aplicativo de amostra que vai usar o serviço. O aplicativo pode ser implantado na VM ou em outro serviço, como Cloud Run, Kubernetes ou até mesmo localmente em um laptop. Aqui vamos mostrar como implantar na VM.

Prepare o ambiente

Vamos continuar trabalhando na VM usando a mesma sessão SSH. Para executar o aplicativo, precisamos adicionar alguns módulos Python. O comando será executado no diretório do aplicativo no mesmo ambiente virtual do Python.

Na sessão SSH da VM, execute:

cd ~/genai-databases-retrieval-app/llm_demo
pip install -r requirements.txt

Saída esperada (editada):

student@instance-1:~$ cd ~/genai-databases-retrieval-app/llm_demo
pip install -r requirements.txt
Collecting fastapi==0.104.0 (from -r requirements.txt (line 1))
  Obtaining dependency information for fastapi==0.104.0 from https://files.pythonhosted.org/packages/db/30/b8d323119c37e15b7fa639e65e0eb7d81eb675ba166ac83e695aad3bd321/fastapi-0.104.0-py3-none-any.whl.metadata
  Downloading fastapi-0.104.0-py3-none-any.whl.metadata (24 kB)
...

Preparar o ID do cliente

Para usar a funcionalidade de reserva do aplicativo, precisamos preparar o ID do cliente OAuth 2.0 usando o console do Cloud. Isso vai acontecer quando fizermos login no aplicativo, já que a reserva usa as credenciais dos clientes para registrar os dados no banco de dados.

No console do Cloud, acesse "APIs e serviços", clique em "Tela de permissão OAuth" e escolha o usuário "Interno".

Em seguida, clique em "Criar" e siga as instruções na próxima tela.

Preencha os campos obrigatórios, como "Nome do app" e "E-mail de suporte ao usuário". Você também pode adicionar um domínio que quer mostrar na tela de permissão e, por fim, as "Informações de contato do desenvolvedor".

Em seguida, clique no botão "Salvar e continuar" na parte de baixo da página para acessar a próxima.

Não é necessário mudar nada, a menos que você queira especificar os escopos. Por fim, confirme clicando no botão "Salvar e continuar" novamente. Isso vai configurar a tela de permissão do aplicativo.

A próxima etapa é criar o ID do cliente. No painel à esquerda, clique em "Credenciais", que vai levar você às credenciais do OAuth2.

Clique em "Criar credenciais" na parte de cima e escolha "ID do cliente OAuth". Em seguida, outra tela será aberta.

Escolha "Aplicativo da Web" na lista suspensa de tipo de aplicativo e coloque o URI do aplicativo (e a porta, opcionalmente) como as "Origens JavaScript autorizadas". Além disso, adicione ao "URIs de redirecionamento autorizados" o host do aplicativo com "/login/google" no final para usar a tela pop-up de autorização. Na imagem acima, você pode ver que usei http://localhost como URI do aplicativo base.

Depois de clicar no botão "Criar", uma janela pop-up vai aparecer com as credenciais dos seus clientes.

Vamos precisar do ID do cliente (e, opcionalmente, da chave secreta do cliente) mais tarde para usar com nosso aplicativo.

Executar o aplicativo assistente

Antes de iniciar o aplicativo, é preciso configurar algumas variáveis de ambiente. A funcionalidade básica do aplicativo, como consultar voos e comodidades do aeroporto, exige apenas BASE_URL, que aponta o aplicativo para o serviço de recuperação. Podemos fazer isso usando o comando gcloud .

Na sessão SSH da VM, execute:

export BASE_URL=$(gcloud  run services list --filter="(retrieval-service)" --format="value(URL)")

Saída esperada (editada):

student@instance-1:~/genai-databases-retrieval-app/llm_demo$ export BASE_URL=$(gcloud  run services list --filter="(retrieval-service)" --format="value(URL)")

Para usar recursos mais avançados do aplicativo, como reservar e alterar voos, precisamos fazer login com nossa Conta do Google. Para isso, precisamos fornecer a variável de ambiente CLIENT_ID usando o ID do cliente OAuth do capítulo "Preparar ID do cliente":

export CLIENT_ID=215....apps.googleusercontent.com

Saída esperada (editada):

student@instance-1:~/genai-databases-retrieval-app/llm_demo$ export CLIENT_ID=215....apps.googleusercontent.com

Agora podemos executar o aplicativo:

python run_app.py

Saída esperada:

student@instance-1:~/genai-databases-retrieval-app/llm_demo$ python main.py
INFO:     Started server process [28565]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

Conectar-se ao aplicativo

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. Vamos usar um túnel SSH para a VM, ou seja, converter a porta local 8080 para a porta da VM 8081.

Como se conectar de uma máquina local

Quando queremos nos conectar de uma máquina local, precisamos executar um túnel SSH. Isso pode ser feito usando gcloud compute ssh:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8081:localhost:8081

Saída esperada:

student-macbookpro:~ student$ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
Warning: Permanently added 'compute.7064281075337367021' (ED25519) to the list of known hosts.
Linux instance-1.us-central1-c.c.gleb-test-001.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Agora podemos abrir o navegador e usar http://localhost:8081 para se conectar ao aplicativo. A tela do aplicativo vai aparecer.

Como se conectar usando o Cloud Shell

Outra opção é usar o Cloud Shell para se conectar. Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia do Cloud Shell, inicie o túnel para a VM com este comando gcloud:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081

Ignore a mensagem de erro "Não é possível atribuir o endereço solicitado".

Esta é a saída esperada:

student@cloudshell:~ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
bind [::1]:8081: Cannot assign requested address
inux instance-1.us-central1-a.c.gleb-codelive-01.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Sat May 25 19:15:46 2024 from 35.243.235.73
student@instance-1:~$

Isso abre a porta 8080 no Cloud Shell, que pode ser usada para "Visualização na Web".

Clique no botão "Visualização na Web" na parte superior direita do Cloud Shell e, no menu suspenso, escolha "Visualizar na porta 8080".

Uma nova guia vai ser aberta no navegador da Web com a interface do aplicativo. Você vai ver a página "Assistente de atendimento ao cliente da Cymbal Air". Na barra de endereço da página, vemos o URI da página de visualização. É necessário remover a parte "/?authuser=0&redirectedPreviously=true" no final.

Use a primeira parte do URI, como "https://8080-cs-35704030349-default.cs-us-east1-vpcf.cloudshell.dev/", na janela do navegador e forneça como Origens JavaScript autorizadas e URIs de redirecionamento autorizados para as credenciais criadas no capítulo "Preparar ID do cliente", substituindo ou adicionando aos valores http://localhost:8080 fornecidos originalmente. O valor superior seria semelhante a "https://8080-cs-35704030349-default.cs-us-east1-vpcf.cloudshell.dev", e o inferior seria "https://8080-cs-35704030349-default.cs-us-east1-vpcf.cloudshell.dev/login/google".

Fazer login no aplicativo

Quando tudo estiver configurado e o aplicativo aberto, use o botão "Fazer login" no canto superior direito da tela do aplicativo para fornecer suas credenciais. Isso é opcional e necessário apenas se você quiser testar a funcionalidade de reserva do aplicativo.

Uma janela pop-up será aberta para que possamos escolher nossas credenciais.

Depois de fazer login, o aplicativo estará pronto, e você poderá começar a postar suas solicitações no campo na parte de baixo da janela.

Esta demonstração mostra o assistente de atendimento ao cliente da Cymbal Air. Cymbal Air é uma companhia aérea fictícia. O assistente é um chatbot de IA que ajuda viajantes a gerenciar voos e buscar informações sobre a central da Cymbal Air no Aeroporto Internacional de São Francisco (SFO).

Sem fazer login (sem CLIENT_ID), ele pode ajudar a responder perguntas como estas:

Quando é o próximo voo para Denver?

Tem alguma loja de luxo perto do portão C28?

Onde posso tomar um café perto do portão A6?

Onde posso comprar um presente?

Reserve um voo para Denver saindo às 10h35

Depois de fazer login no aplicativo, você pode testar outros recursos, como reservar voos ou verificar se o assento atribuído a você é na janela ou no corredor.

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 Cloud SQL. Saiba mais sobre este aplicativo de demonstração na página do GitHub do projeto.

9. Limpar o ambiente

Quando todas as tarefas forem concluídas, será possível limpar o ambiente.

Excluir serviço do Cloud Run

No Cloud Shell, execute:

gcloud run services delete retrieval-service --region us-central1

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ gcloud run services delete retrieval-service --region us-central1
Service [retrieval-service] will be deleted.

Do you want to continue (Y/n)?  Y

Deleting [retrieval-service]...done.                                                                                                                                                                                                                 
Deleted service [retrieval-service].

Exclua a conta de serviço do serviço do Cloud Run.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-222]
student@cloudshell:~ (gleb-test-short-004)$ gcloud iam service-accounts delete retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$

Exclua a instância do Cloud SQL

Destrua a instância do Cloud SQL quando terminar o laboratório.

No Cloud Shell, defina o projeto e as variáveis de ambiente se tiver ocorrido uma desconexão e todas as configurações anteriores forem perdidas:

export INSTANCE_NAME=my-cloudsql-instance
export PROJECT_ID=$(gcloud config get-value project)

Exclua a instância:

gcloud sql instances delete $INSTANCE_NAME --project=$PROJECT_ID

Observação: o comando leva de 3 a 5 minutos para ser executado.

Saída esperada do console:

student@cloudshell:~$ gcloud sql instances delete $INSTANCE_NAME --project=$PROJECT_ID
All of the instance data will be lost when the instance is deleted.

Do you want to continue (Y/n)?  y

Deleting Cloud SQL instance...done.                                                                                                                
Deleted [https://sandbox.googleapis.com/v1beta4/projects/test-project-001-402417/instances/my-cloudsql-instance].

Agora você pode destruir a VM.

Excluir a VM do GCE

No Cloud Shell, execute:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted 

Exclua a conta de serviço da VM do GCE e do Serviço de recuperação.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet
Your active configuration is: [cloudshell-222]
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$ 

10. Parabéns

Parabéns por concluir o codelab.

O que vimos

• Como criar uma instância do Cloud SQL
• Como se conectar à instância do Cloud SQL
• Como configurar e implantar o Serviço de recuperação de bancos de dados de IA generativa
• Como implantar um aplicativo de amostra com o serviço implantado

11. Pesquisa

Como você usará este tutorial?

Apenas leitura Leitura e exercícios