Acessar a conversa do Gemini 3 Pro usando o SDK Python por um endpoint do Private Service Connect

1. Visão geral

A API Vertex AI pode ser acessada pela Internet. No entanto, na sua empresa, talvez você queira acessar a API Vertex AI de maneira particular, sem usar a Internet. Neste laboratório, você vai:

• Acessar a API Gemini 3 Pro pela Vertex usando o SDK do Python
• Isso será executado em uma instância de VM
• A conexão será via Cloud NAT com a Internet pública.

Em seguida, você vai criar um endpoint do Private Service Connect para as APIs do Google e mudar o fluxo de tráfego para usar o endpoint particular e se conectar à API Gemini Chat. As configurações serão uma combinação de Terraform, gcloud e console.

Neste laboratório, você vai criar o seguinte padrão:

Figura 1.

2. Objetivo

Neste laboratório, você vai aprender a fazer o seguinte:

• Configurar a instância de VM para usar o SDK do Python
• Conectar-se à conversa do Gemini usando um script Python
• Configurar o endpoint do PSC para se conectar a Googleapis
• Verificar o caminho de conectividade com o Googleais
• Configurar entradas DNS manuais

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. Tarefa 1: Configurar o ambiente com o Terraform

Vamos criar uma VPC personalizada com regras de firewall e sub-rede. Abra o console do Cloud e selecione o projeto que você vai usar.

1. Abra o Cloud Shell, localizado na parte superior direita do console. Verifique se o ID do projeto correto aparece no Cloud Shell e confirme todas as solicitações para permitir o acesso.
2. Crie uma pasta chamada "terraform-build" e acesse-a.

mkdir terraform-build  && cd terraform-build

3. Crie um arquivo main.tf e variable.tf.

touch main.tf variable.tf 

4. Mude para a visualização do editor do Cloud Shell. Selecione editor e permita todos os avisos necessários para que a interface possa ser carregada.
5. Depois de carregado, navegue até Arquivo > Abrir pasta e acesse /home/your-user-name/terraform-build. Selecione Ok para abrir a pasta no editor.
6. Selecione o arquivo variable.tf e adicione o seguinte. Substitua o texto your-project-id-here pelo ID do projeto entre aspas.

variable "project_id" {
  type = string
  default = "your-project-id-here"
}

variable "network_id" {
  type = string
  default = "python-net"
}

7. Em seguida, abra o arquivo main.tf. Vamos adicionar um código do Terraform para realizar várias ações, conforme explicado abaixo.

Ativar APIs	resource "google_project_service" "default"
Criar uma VPC chamada python-net	resource "google_compute_network" "default"
Adicionar uma sub-rede	resource "google_compute_subnetwork" "default"
Adicionar duas regras de firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copie e cole o seguinte no arquivo main .tf.

resource "google_project_service" "default" {
  project = var.project_id 
  for_each = toset([
    "dns.googleapis.com",
    "aiplatform.googleapis.com",
    "servicedirectory.googleapis.com"
  ])

  service            = each.value
  disable_on_destroy = false
}

resource "google_compute_network" "default" {
  project                 = var.project_id
  name                    = var.network_id
  auto_create_subnetworks = false
  mtu                     = 1460
  routing_mode            = "GLOBAL"
}

resource "google_compute_subnetwork" "default" {
  name          = "vm1-subnet"
  ip_cidr_range = "10.0.11.0/24"
  project       = var.project_id
  region        = "us-east1"
  stack_type    = "IPV4_ONLY"
  network       = google_compute_network.default.id
}

resource "google_compute_firewall" "allow_icmp" {
  name    = "allow-icmp-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "icmp"
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-icmp"]
}

resource "google_compute_firewall" "allow_ssh" {
  name    = "allow-ssh-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "tcp"
    ports    = ["22"]
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-ssh"]
}

9. Volte para o terminal do Cloud Shell, verifique se você está no diretório terraform-build cd terraform-build e execute os comandos a seguir:

terraform init

Inicializa o diretório de trabalho. Essa etapa faz o download dos provedores necessários para a configuração especificada.

terraform plan

Gera um plano de execução, mostrando quais ações o Terraform vai realizar para implantar sua infraestrutura.

10. Agora, para criar os recursos, execute o comando terraform apply e digite yes para executar.

Verifique sua configuração:confira se o ambiente tem

1 VPC chamada python-net

1 sub-rede

2 regras de firewall

4. Tarefa 2: Criar um gateway NAT e VMs com o Terraform

Precisamos conceder acesso externo de saída à Internet. Portanto, vamos criar e anexar um gateway do Cloud NAT.

1. Abra o Cloud Shell, navegue até a pasta terraform-build e crie os seguintes arquivos (total de três arquivos). Vamos editar isso mais tarde.

touch nat-vm.tf psc.tf dns.tf

2. Mude para a visualização do editor do Cloud Shell, selecione o arquivo nat-vm.tf e adicione o seguinte código do Terraform. Isso vai criar um gateway NAT e duas VMs.

Terraform nat-vm.tf

resource "google_compute_router" "default" {
  name    = "py-outbound-nat"
  region  = "us-east1"
  network = google_compute_network.default.id
  project = var.project_id
  

 bgp {
  asn = 64514
  }
}

resource "google_compute_router_nat" "default" {
  name                               = "py-outbound-nat-gw"
  router                             = google_compute_router.default.name
  region                             = google_compute_router.default.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  project                            = var.project_id
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

  log_config {
    enable = true
    filter = "ERRORS_ONLY"
  }
}

resource "google_compute_instance" "vm1" {
  name         = "py-vm1"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"
  project      = var.project_id

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.default.id  
    stack_type = "IPV4_ONLY"
  }

  tags = ["allow-ssh", "allow-icmp"]

  metadata_startup_script = <<-EOF
    #! /bin/bash
    sudo apt-get update
    sudo apt-get install python3 python3-dev python3-venv git -y
    sudo apt-get install tcpdump dnsutils -y    
    
      mkdir -p ~/py-gem-env
      cd ~/py-gem-env
      python3 -m venv env
      source env/bin/activate
      pip install --upgrade pip
      pip install ipython google-genai
    '
  EOF
}

3. Mude para o terminal do Cloud Shell, verifique se você está na pasta terraform-build e execute terraform plan. Isso vai mostrar que quatro itens serão adicionados. Em seguida, execute terraform apply e digite yes para criar o gateway NAT e a VM.

Verifique sua configuração:confira se o ambiente tem

1 gateway NAT

1 Cloud Router

VM chamada py-vm1

5. Tarefa 3: Configurar VMs e testar

1. Navegue até "Instâncias de VM". Selecione a VM que começa com py-vm1. Escolha SSH.
2. Depois de usar SSH em py-vm1,digite sudo -i para ativar o acesso root.
3. Ative o ambiente venv:

cd py-gem-env
source env/bin/activate

4. Agora vamos autenticar isso para fazer alguns testes mais tarde. Execute o seguinte comando na VM e pressione y quando solicitado.

gcloud auth application-default login

5. Em seguida, copie o URL que aparece começando com https://, abra uma nova guia na janela do navegador do laboratório e cole o URL. Aceite os comandos.
6. Quando você vir a seguinte seleção de cópia, volte para a sessão da VM py-vm1 e, em Insira o código de autorização, cole o código copiado e pressione "Enter" para autenticar.

7. Agora vamos fazer um teste rápido para ver se podemos nos conectar à API Vertex. Isso usa o *-aiplatform.googleapis.com. Portanto, vamos fazer um dig para esse endereço e ver como o tráfego é roteado.

dig *-aiplatform.googleapis.com

8. Você vai ver algo parecido (o endereço será diferente). O caminho é feito por endereços IP públicos, já que a API é pública. NÃO COPIE

; <<>> DiG 9.18.41-1~deb12u1-Debian <<>> *-aiplatform.googleapis.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 60947
;; flags: qr rd ra; QUERY: 1, ANSWER: 16, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;*-aiplatform.googleapis.com.   IN      A

;; ANSWER SECTION:
*-aiplatform.googleapis.com. 300 IN     A       173.194.216.95
*-aiplatform.googleapis.com. 300 IN     A       108.177.11.95
*-aiplatform.googleapis.com. 300 IN     A       192.178.219.95
*-aiplatform.googleapis.com. 300 IN     A       74.125.134.95
*-aiplatform.googleapis.com. 300 IN     A       74.125.139.95
*-aiplatform.googleapis.com. 300 IN     A       108.177.12.95
*-aiplatform.googleapis.com. 300 IN     A       173.194.210.95
*-aiplatform.googleapis.com. 300 IN     A       74.125.26.95
*-aiplatform.googleapis.com. 300 IN     A       173.194.212.95
*-aiplatform.googleapis.com. 300 IN     A       172.217.204.95

9. Agora vamos usar o Python. Digite ipython para ativar a interface ipython.

ipython

10. Copie e cole o seguinte. Isso pergunta ao Gemini: Quais são todas as cores do logotipo do Google? e Qual é a cor do céu?.

from google import genai
from google.genai import types
import os
import sys

LOCATION = "global"
MODEL_ID = "gemini-3-pro-preview" 

try:
    client = genai.Client(vertexai=True, location=LOCATION)
    print(f"Successfully initialized Google Gen AI Client (Vertex AI mode) in {LOCATION}")
except Exception as e:
    print(f"Error initializing client: {e}")
    print("Ensure you have installed the library: `pip install google-genai`")
    print("And authenticated: `gcloud auth application-default login`")
    sys.exit(1)

class SimpleChatSession:
    def __init__(self, model_id):
        self.model_id = model_id
        self.history = [] 

    def send_message(self, prompt, stream=True):
        user_content = types.Content(
            role="user",
            parts=[types.Part(text=prompt)]
        )
        self.history.append(user_content)

        try:
            response_stream = client.models.generate_content_stream(
                model=self.model_id,
                contents=self.history,
                config=types.GenerateContentConfig(
                    temperature=0.7 
                )
            )

            accumulated_text = ""
            
            for chunk in response_stream:
                if chunk.text:
                    yield chunk.text
                    accumulated_text += chunk.text
            
            model_content = types.Content(
                role="model",
                parts=[types.Part(text=accumulated_text)]
            )
            self.history.append(model_content)

        except Exception as e:
            print(f"\n[Error during generation: {e}]")

def get_chat_response(session: SimpleChatSession, prompt: str):
    print(f"\n--- User: {prompt} ---")
    print("--- Model: ", end="")
    
    stream_generator = session.send_message(prompt)
    
    full_text = ""
    for chunk_text in stream_generator:
        full_text += chunk_text
        print(chunk_text, end="", flush=True)

    print() 
    return full_text

if __name__ == "__main__":
    chat_session = SimpleChatSession(MODEL_ID)

    get_chat_response(chat_session, "Hello.")
    get_chat_response(chat_session, "What are all the colors of the Google logo?")
    get_chat_response(chat_session, "What color is the sky?")

11. Pressione Enter duas vezes para executar e conferir o resultado.
12. Essa solicitação acessou a Vertex pela API pública.
13. Feche a sessão SSH para continuar.

Observação:você pode mudar a pergunta do comando para outra coisa.

6. Tarefa 4: Criar o endpoint do PSC para googleapis com o Terraform

Para ativar a conectividade particular com nosso endpoint da API Vertex, vamos criar um endpoint do Private Service Connect para APIs do Google. Isso nos permite usar um endereço IP particular que atribuímos para rotear o tráfego para as APIs do Google necessárias, neste caso, a Vertex.

1. Abra o Cloud Shell na visualização do editor, se ele ainda não estiver aberto. Vamos criar o seguinte:

• Crie um IP para o endpoint do PSC 192.168.255.250 (resource "google_compute_global_address" "default")
• Crie um endpoint do PSC para APIs do Google (resource "google_compute_global_forwarding_rule" "default")

Abra o arquivo psc.tf na pasta terraform-build. Adicione o seguinte código ao arquivo.

Terraform psc.tf

resource "google_compute_global_address" "default" {
  name         = "vertex-ip"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.default.id
  address_type = "INTERNAL"
  address      = "192.168.255.250"
}

resource "google_compute_global_forwarding_rule" "default" {  
  name                  = "pscvertexgemini"
  target                = "all-apis"
  network               = google_compute_network.default.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
  }

2. Mude para o terminal do Cloud Shell e verifique se você está na pasta terraform-build. Em seguida, execute terraform init e terraform plan. Isso vai mostrar que dois itens serão adicionados.
   Depois, execute terraform apply e digite yes para criar o endpoint de APIs do Google de IP e PSC.
3. Verificar se o endpoint existe

gcloud compute addresses list --filter="name=( 'vertex-ip' ...)"

gcloud compute forwarding-rules describe pscvertexgemini --global

7. Tarefa 5: Criar uma entrada DNS manual para googleapis com o Terraform

É possível criar uma entrada DNS manual para apontar para o endpoint da PSC usando DNS particular. Isso afetaria todas as redes atribuídas a ele.

1. Acesse "Serviços de rede" e selecione "Cloud DNS".
2. Nas zonas, você vai encontrar uma zona criada automaticamente para o Private Service Connect para APIs do Google, com o tipo de zona "diretório de serviços". Isso pode ser usado para se conectar ao endpoint do PSC com o formato **SERVICE-ENDPOINT.p.googleapis.com. Exemplo: aiplatform-pscvertexgemini.p.googleapis.com
3. Neste caso, queremos criar manualmente uma entrada de DNS particular. A configuração será a seguinte:

• Crie uma zona de DNS particular chamada "googleapis-private" para "googleapis.com" e restrinja-a à rede "python-net".
• Adicione um registro A para mapear "googleapis.com" para o endereço IP "192.168.255.250".
• Adicione um registro CNAME para redirecionar todos os subdomínios de "googleapis.com" (por exemplo, www.googleapis.com) para "googleapis.com".

4. Abra o Cloud Shell na visualização do editor, se ele ainda não estiver aberto. Abra o arquivo dns.tf na pasta "terraform-build". Adicione o seguinte código ao arquivo.

Terraform dns.tf

resource "google_dns_managed_zone" "private_zone" {
  name        = "googleapis-private"
  dns_name    = "googleapis.com."  
  visibility  = "private"
  project     = var.project_id     

  private_visibility_config {
    networks {
      network_url = google_compute_network.default.id  
    }
  }
}

resource "google_dns_record_set" "a_record" {
  name    = "googleapis.com."  
  type    = "A"
  ttl     = 300
  managed_zone = google_dns_managed_zone.private_zone.name
  project = var.project_id    

  rrdatas = ["192.168.255.250"]
}

resource "google_dns_record_set" "cname_record" {
 name    = "*.googleapis.com."
 type    = "CNAME"
 ttl     = 300
 managed_zone = google_dns_managed_zone.private_zone.name
 project = var.project_id    

 rrdatas = ["googleapis.com."]  
}

5. Mude para o terminal do Cloud Shell e verifique se você está na pasta terraform-build. Em seguida, execute terraform plan. Isso vai mostrar quais itens serão adicionados.
   Depois, execute terraform apply e digite yes para criar a entrada DNS particular.
6. Você vai ver uma configuração com um registro A e um CNAME como este:
7. Em seguida, vamos verificar a conectividade com essas mudanças em py-vm1.

8. Tarefa 6: Verificar a conectividade do endpoint com o endereço IP

Vamos nos conectar usando o endpoint particular para acessar o Gemini.

Observação:não é necessário fazer configurações manuais na VM.

1. Acesse a instância de VM py-vm1. Selecione "SSH" e faça login na VM
2. Para ter acesso root, digite sudo -i
3. Verifique o caminho de conectividade para aiplatform.googleapis.com usando o comando ping. Isso vai fazer ping no endereço IP no DNS particular, registro A para googleapis. Esse IP é um endpoint do PSC, e seus pings não vão funcionar.

ping -c 2 aiplatform.googleapis.com

4. Verifique o caminho de conectividade com um ping usando a entrada DNS criada automaticamente para APIs do Google do PSC com aiplatform-pscvertexgemini.p.googleapis.com. Isso aponta para o endereço IP do endpoint do PSC, e seus pings não vão funcionar.

ping -c 2 aiplatform-pscvertexgemini.p.googleapis.com

5. Verifique o caminho de conectividade para aiplatform.googleapis.com usando o comando dig. Esse é o endereço IP do endpoint do PSC.

dig aiplatform.googleapis.com

6. Volte ao console e abra outra instância de VM py-vm1. Selecione SSH e faça o SSH na VM
7. Para ter acesso root, digite sudo -i
8. Execute o comando a seguir para conferir a conectividade em um despejo de TCP

sudo tcpdump -i any port 53 -n or host aiplatform.googleapis.com

9. Agora volte para a primeira instância SSH da instância de VM py-vm1.
10. Ative o ambiente usando

cd py-gem-env
source env/bin/activate

11. Agora vamos testar o Python. Digite ipython para ativar a interface ipython.

ipython

12. Copie e cole o seguinte. Isso pede ao Gemini para responder a estas perguntas: Em uma frase curta, resuma o que é um tokenizador no contexto da IA? e As baleias são incríveis ou não?.

from google import genai
from google.genai import types
import os
import sys

LOCATION = "global"
MODEL_ID = "gemini-3-pro-preview" 

try:
    client = genai.Client(vertexai=True, location=LOCATION)
    print(f"Successfully initialized Google Gen AI Client (Vertex AI mode) in {LOCATION}")
except Exception as e:
    print(f"Error initializing client: {e}")
    print("Ensure you have installed the library: `pip install google-genai`")
    print("And authenticated: `gcloud auth application-default login`")
    sys.exit(1)

class SimpleChatSession:
    def __init__(self, model_id):
        self.model_id = model_id
        self.history = [] 

    def send_message(self, prompt, stream=True):
        user_content = types.Content(
            role="user",
            parts=[types.Part(text=prompt)]
        )
        self.history.append(user_content)

        try:
            response_stream = client.models.generate_content_stream(
                model=self.model_id,
                contents=self.history,
                config=types.GenerateContentConfig(
                    temperature=0.7 
                )
            )

            accumulated_text = ""
            
            for chunk in response_stream:
                if chunk.text:
                    yield chunk.text
                    accumulated_text += chunk.text
            
            model_content = types.Content(
                role="model",
                parts=[types.Part(text=accumulated_text)]
            )
            self.history.append(model_content)

        except Exception as e:
            print(f"\n[Error during generation: {e}]")

def get_chat_response(session: SimpleChatSession, prompt: str):
    print(f"\n--- User: {prompt} ---")
    print("--- Model: ", end="")
    
    stream_generator = session.send_message(prompt)
    
    full_text = ""
    for chunk_text in stream_generator:
        full_text += chunk_text
        print(chunk_text, end="", flush=True)

    print() 
    return full_text

if __name__ == "__main__":
    chat_session = SimpleChatSession(MODEL_ID)

    get_chat_response(chat_session, "Hello.")
    get_chat_response(chat_session, "In one short sentence summarize what is a tokenizer in the context of AI?")
    get_chat_response(chat_session, "Are whales awesome or not?")

13. Pressione Enter duas vezes para executar e conferir o resultado.
14. Volte para a segunda instância de VM py-vm1. Você vai ver o resultado do TCPDUMP. Você vai notar que o endereço IP da VM está usando o endereço IP do endpoint do PSC para se conectar a aiplatform.googleapis.com.

Feche todas as sessões SSH da instância de VM py-vm1.

9. Limpeza

1. Acesse o Cloud Shell e confira se você está no diretório terraform-build cd terraform-build
2. Execute o comando terraform plan destroy para conferir todas as mudanças que serão feitas.

terraform plan -destroy

3. Em seguida, execute o comando terraform destroy e digite yes. Todos os recursos criados no projeto com o Terraform serão removidos.

terraform destroy 

10. Parabéns

Parabéns! Você se conectou ao Vertex e usou o Gemini 3 Pro com sucesso por um endereço de API pública e de forma privada usando o endpoint do Private Service Connect para APIs do Google. Essa funcionalidade pode estender a conectividade de API particular para seu ambiente local/de outra nuvem conectado via Interconnect, Cross-Cloud Interconnect e VPC.

Próximas etapas / Saiba mais

Leia mais sobre o networking da Vertex AI.

Codelab: Acessar o Anthropic Claude na Vertex AI com o SDK do Python usando um endpoint do Private Service Connect

Comece o próximo laboratório

Continue sua Quest com o Google Cloud e confira estes outros laboratórios do Google Cloud Ensina:

• Noções básicas de rede no Google Cloud
• Descobrindo a IA generativa - Vertex AI
• IA autônoma no Google Cloud