Accedere alla chat di Gemini 3 Pro utilizzando l'SDK Python tramite l'endpoint Private Service Connect

1. Panoramica

È possibile accedere all'API Vertex AI su internet, ma nella tua azienda potresti voler accedere all'API Vertex AI in privato senza passare da internet. In questo lab, per prima cosa

  • Accedi all'API Gemini 3 Pro tramite Vertex utilizzando l'SDK Python
  • Verrà eseguito su un'istanza VM
  • La connessione avverrà tramite Cloud NAT alla rete internet pubblica.

Poi creerai un endpoint Private Service Connect per le API di Google e modificherai il flusso di traffico in modo da utilizzare l'endpoint privato per connetterti all'API Gemini Chat. Le configurazioni saranno una combinazione di Terraform, gcloud e console.

In questo lab creerai il seguente pattern.

Figura 1.

304c579d349aec90.png

2. Obiettivo

In questo lab imparerai a:

  • Configura l'istanza VM per utilizzare l'SDK Python
  • Connettersi a Gemini Chat tramite script Python
  • Configura l'endpoint PSC per la connessione a Googleapis
  • Verifica il percorso di connettività a Googleais
  • Configurare le voci DNS manuali

Configurazione dell'ambiente autonoma

  1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Google Workspace, devi crearne uno.

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
  • L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
  • Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
  1. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare l'addebito di costi oltre a quelli previsti da questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono usufruire del programma prova senza costi di 300$.

Avvia Cloud Shell

Anche se Google Cloud può essere utilizzato da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Attiva Cloud Shell

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Screenshot del terminale Google Cloud Shell che mostra che l'ambiente è connesso

Questa macchina virtuale è caricata con tutti gli strumenti di sviluppo di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Attività 1: Configura l'ambiente con Terraform

Creeremo un VPC personalizzato con regole firewall e subnet. Apri la console Cloud e seleziona il progetto che utilizzerai.

  1. Apri Cloud Shell, che si trova in alto a destra nella console, assicurati di visualizzare l'ID progetto corretto in Cloud Shell e conferma le richieste di autorizzazione dell'accesso. b51b80043d3bac90.png
  2. Crea una cartella denominata terraform-build e spostati al suo interno
mkdir terraform-build  && cd terraform-build
  1. Crea un file main.tf e variable.tf.
touch main.tf variable.tf
  1. Passa alla visualizzazione dell'editor di Cloud Shell. Seleziona Editor e assicurati di consentire tutti i prompt necessari per caricare l'interfaccia.
  2. Una volta caricato, vai a File > Apri cartella e vai a /home/your-user-name/terraform-build e seleziona Ok per aprire la cartella nell'editor. 39b3eb9a3e077bfd.png
  3. Seleziona il file variable.tf e aggiungi quanto segue. Sostituisci il testo your-project-id-here con l'ID progetto effettivo tra virgolette.
variable "project_id" {
  type = string
  default = "your-project-id-here"
}

variable "network_id" {
  type = string
  default = "python-net"
}
  1. A questo punto, apri il file main.tf. Aggiungeremo del codice Terraform per eseguire varie azioni, come spiegato di seguito.

Abilita le API

resource "google_project_service" "default"

Crea un VPC chiamato python-net

resource "google_compute_network" "default"

Aggiungere una subnet

resource "google_compute_subnetwork" "default"

Aggiungi due regole firewall

resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

  1. Copia e incolla quanto segue nel file 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"]
}
  1. Torna al terminale Cloud Shell, assicurati di trovarti nella directory terraform-build cd terraform-build ed esegui questi comandi:

terraform init

Inizializza la directory di lavoro. Questo passaggio scarica i provider richiesti per la configurazione specificata.

terraform plan

Genera un piano di esecuzione, che mostra le azioni che Terraform eseguirà per eseguire il deployment dell'infrastruttura.

  1. Ora, per creare le risorse, esegui il comando terraform apply e digita yes per eseguirlo.

4. Attività 2: Crea gateway NAT e VM con Terraform

Dobbiamo concedere l'accesso esterno in uscita a internet, quindi creiamo un gateway Cloud NAT e lo colleghiamo.

  1. Apri Cloud Shell, vai alla cartella terraform-build e crea i seguenti file (tre in totale). Li modificheremo in un secondo momento.
touch nat-vm.tf psc.tf dns.tf
  1. Passa alla visualizzazione Editor di Cloud Shell, seleziona il file nat-vm.tf e aggiungi il seguente codice Terraform. Verrà creato un gateway NAT e due VM.

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
}
  1. Passa al terminale Cloud Shell, assicurati di trovarti nella cartella terraform-build ed esegui terraform plan. Verrà visualizzato che verranno aggiunti 4 elementi. Quindi esegui terraform apply e digita yes per creare il gateway NAT e la VM.

5. Attività 3: Configura le VM e testa

  1. Vai a Istanze VM. Seleziona la VM che inizia con py-vm1. Scegli SSH.
  2. Una volta effettuato l'accesso SSH a py-vm1,attiva l'accesso root digitando sudo -i
  3. Attiva l'ambiente venv:
cd py-gem-env
source env/bin/activate
  1. Ora autentichiamolo per eseguire alcuni test in un secondo momento. Esegui questo comando nella VM e premi y quando richiesto.
gcloud auth application-default login
  1. Copia quindi l'URL che inizia con https://, apri una nuova scheda nella finestra del browser del lab e incolla l'URL. Accetta le richieste.
  2. Quando vedi il seguente messaggio, seleziona Copia, torna alla sessione della VM py-vm1 e, per Inserisci codice di autorizzazione, incolla il codice che hai copiato e premi Invio per eseguire l'autenticazione.

b703db7aa2aa286a.png

  1. Ora eseguiamo un rapido test per verificare se riusciamo a connetterci all'API Vertex, che utilizza *-aiplatform.googleapis.com, quindi eseguiamo un dig a questo indirizzo per vedere come viene instradato il traffico.
dig *-aiplatform.googleapis.com
  1. Dovresti vedere qualcosa di simile (l'indirizzo sarà diverso). Tieni presente che il percorso avviene tramite indirizzi IP pubblici, poiché l'API è un'API pubblica. NON COPIARE
; <<>> 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
  1. Ora utilizziamo Python. Digita ipython per attivare l'interfaccia ipython.
ipython

845ef4291429888a.png

  1. Ora copia e incolla quanto segue. In questo modo, Gemini risponde alle domande "Quali sono tutti i colori del logo Google?" e "Qual è il colore del cielo?" .
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?")
  1. Premi Invio due volte per eseguire il comando e visualizzare il risultato.
  2. Questa richiesta ha eseguito l'accesso a Vertex tramite l'API pubblica.
  3. Chiudi la sessione SSH e continuiamo.

6. Attività 4: Crea l'endpoint PSC per googleapis con Terraform

Per abilitare la connettività privata al nostro endpoint API Vertex, creeremo un endpoint Private Service Connect per le API di Google. In questo modo potremo utilizzare un indirizzo IP privato che assegniamo per indirizzare il traffico alle API di Google di cui abbiamo bisogno, in questo caso Vertex.

  1. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Creeremo quanto segue:
  • Crea un IP per l'endpoint PSC 192.168.255.250 (resource "google_compute_global_address" "default")
  • Crea un endpoint PSC per le API di Google (resource "google_compute_global_forwarding_rule" "default")

Apri il file psc.tf nella cartella terraform-build. Aggiungi il seguente codice al file.

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 = ""
  }
  1. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Quindi esegui terraform init, poi terraform plan, vedrai che verranno aggiunti due elementi,
    quindi esegui terraform apply e digita yes per creare l'endpoint IP e PSC delle API di Google.
  2. Verifica l'esistenza dell'endpoint
gcloud compute addresses list --filter="name=( 'vertex-ip' ...)"

gcloud compute forwarding-rules describe pscvertexgemini --global

7. Attività 5: Crea una voce DNS manuale in googleapis con Terraform

Puoi creare una voce DNS manuale che punti all'endpoint PSC utilizzando il DNS privato. Ciò influirà su tutte le emittenti che gli assegni.

  1. Vai a Servizi di rete e seleziona Cloud DNS.
  2. Nelle zone dovresti visualizzare una zona creata automaticamente per Private Service Connect per le API di Google, con il tipo di zona Service Directory. Può essere utilizzato per connettersi all'endpoint PSC con il formato **SERVICE-ENDPOINT.p.googleapis.com. Esempio: aiplatform-pscvertexgemini.p.googleapis.com
  3. In questo caso vogliamo creare manualmente una voce DNS privata. La configurazione sarà la seguente
  • Crea una zona DNS privata denominata "googleapis-private" per "googleapis.com" e limitala alla rete "python-net".
  • Aggiungi un record A per mappare "googleapis.com" all'indirizzo IP "192.168.255.250".
  • Aggiungi un record CNAME per reindirizzare tutti i sottodomini di "googleapis.com" (ad es. www.googleapis.com) a "googleapis.com".
  1. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Apri il file dns.tf nella cartella terraform-build. Aggiungi il seguente codice al file.

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."]  
}
  1. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Poi esegui terraform plan,che mostra gli elementi che verranno aggiunti.
    Poi esegui terraform apply e digita yes per creare la voce DNS privata.
  2. Dovresti visualizzare una configurazione con un record A e un record CNAME come questo: vedi 6d2fc061460cd983.png
  3. Successivamente, verifichiamo la connettività con queste modifiche su py-vm1

8. Attività 6: Verifica la connettività dell'endpoint tramite l'indirizzo IP

Connettiamoci utilizzando l'endpoint privato per connetterci a Gemini.

  1. Vai all'istanza VM py-vm1. Seleziona SSH e accedi alla VM tramite SSH
  2. Ottieni l'accesso root digitando sudo -i
  3. Controlla il percorso di connettività a aiplatform.googleapis.com utilizzando il comando ping. Verrà eseguito il ping dell'indirizzo IP nel DNS privato, record A per googleapis. Questo IP è un endpoint PSC e i ping non andranno a buon fine.
ping -c 2 aiplatform.googleapis.com
  1. Controlla il percorso di connettività con un ping utilizzando la voce DNS creata automaticamente per le API di Google PSC con aiplatform-pscvertexgemini.p.googleapis.com. Questo indirizzo punta all'indirizzo IP dell'endpoint PSC e i ping non andranno a buon fine.
ping -c 2 aiplatform-pscvertexgemini.p.googleapis.com
  1. Controlla il percorso di connettività a aiplatform.googleapis.com utilizzando il comando dig. Deve essere l'indirizzo IP dell'endpoint PSC.
dig aiplatform.googleapis.com
  1. Torna alla console e apri un'altra istanza di VM py-vm1. Seleziona SSH e accedi alla VM tramite SSH.
  2. Ottieni l'accesso root digitando sudo -i
  3. Esegui questo comando per visualizzare la connettività in un dump TCP
sudo tcpdump -i any port 53 -n or host aiplatform.googleapis.com
  1. Ora torna alla prima istanza SSH dell'istanza VM py-vm1.
  2. Attiva l'ambiente utilizzando
cd py-gem-env
source env/bin/activate
  1. Ora testiamo Python. Digita ipython per attivare l'interfaccia ipython.
ipython
  1. Ora copia e incolla quanto segue. Chiede a Gemini: "In una breve frase, riassumi che cos'è un tokenizer nel contesto dell'AI?" e "Le balene sono fantastiche o no?".
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?")
  1. Premi Invio due volte per eseguire il comando e visualizzare il risultato.
  2. Torna alla seconda istanza di VM Instance py-vm1. Dovresti vedere il risultato di TCPDUMP. Noterai che in entrata e in uscita l'indirizzo IP della VM utilizza l'indirizzo IP dell'endpoint PSC per connettersi a aiplatform.googleapis.com

Chiudi tutte le sessioni SSH all'istanza VM py-vm1

9. Esegui la pulizia

  1. Vai a Cloud Shell e assicurati di trovarti nella directory terraform-build cd terraform-build
  2. Esegui terraform plan destroy per visualizzare tutte le modifiche che verranno apportate
terraform plan -destroy
  1. Quindi esegui il comando terraform destroy e poi digita yes. Tutte le risorse che hai creato nel tuo progetto con Terraform verranno rimosse.
terraform destroy

10. Complimenti

Congratulazioni, hai eseguito la connessione a Vertex e utilizzato Gemini 3 Pro tramite l'indirizzo API pubblico e in privato utilizzando l'endpoint Private Service Connect per le API di Google. Questa funzionalità può estendere la connettività API privata al tuo ambiente on-premise/altro cloud connesso tramite (Interconnect, Cross-Cloud Interconnect e VPC).

Prossimi passi/Scopri di più

Puoi leggere di più sul networking di Vertex AI.

Codelab: accedi ad Anthropic Claude su Vertex AI con l'SDK Python tramite l'endpoint Private Service Connect

Segui il prossimo lab

Continua la Quest con Google Cloud e dai un'occhiata a questi altri lab Google Cloud Skills Boost: