Ta strona została przetłumaczona przez Cloud Translation API.

Gemini CLI na GCE z punktem końcowym Private Service Connect

1. Przegląd

Interfejsu wiersza poleceń Gemini możesz używać zarówno w środowisku lokalnym, jak i wirtualnym. Gemini CLI to agent AI o otwartym kodzie źródłowym, który udostępnia możliwości Gemini bezpośrednio w terminalu. Z punktu widzenia sieci, gdy używasz interfejsu Gemini CLI, wywołuje on interfejs Gemini API za pomocą publicznie dostępnego adresu IP interfejsu API.

Co się stanie, jeśli chcesz używać interfejsu Gemini CLI na maszynie Google Compute Engine, ale chcesz połączyć się z interfejsem API prywatnie? W tym module dowiesz się, jak skonfigurować punkt końcowy usługi Private Service Connect w przypadku interfejsów API Google, aby kierować ruch do określonego przez Ciebie wewnętrznego adresu IP.

Konfiguracje będą połączeniem Terraform, gcloud i konsoli.

Z tego modułu dowiesz się, jak:

Konfigurowanie instancji maszyny wirtualnej i Cloud NAT
Instalowanie interfejsu Gemini CLI i uwierzytelnianie
Konfigurowanie punktu końcowego usługi Private Service Connect do łączenia się z Googleapis
Sprawdzanie ścieżki połączenia z *.googleais
Konfigurowanie ręcznych wpisów DNS

W tym module utworzysz ten wzór.

Rysunek 1.

2. Konfigurowanie usług Google Cloud

Samodzielne konfigurowanie środowiska

Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail lub Google Workspace, musisz je utworzyć.

Nazwa projektu to wyświetlana nazwa dla uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Zawsze możesz ją zaktualizować.
Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i nie można go zmienić po ustawieniu. Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się tym przejmować. W większości ćwiczeń z programowania musisz odwoływać się do identyfikatora projektu (zwykle oznaczanego jako PROJECT_ID). Jeśli wygenerowany identyfikator Ci się nie podoba, możesz wygenerować inny losowy identyfikator. Możesz też spróbować własnej nazwy i sprawdzić, czy jest dostępna. Po tym kroku nie można go zmienić i pozostaje on taki przez cały czas trwania projektu.
Warto wiedzieć, że istnieje trzecia wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.

Następnie musisz włączyć rozliczenia w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Wykonanie tego laboratorium nie będzie kosztować dużo, a może nawet nic. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub projekt. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

Uruchamianie Cloud Shell

Google Cloud można obsługiwać zdalnie z laptopa, ale w tym module praktycznym będziesz używać Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.

W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:

Udostępnienie środowiska i połączenie się z nim może zająć tylko kilka chwil. Po zakończeniu powinno wyświetlić się coś takiego:

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i uwierzytelniania. Wszystkie zadania w tym laboratorium możesz wykonać w przeglądarce. Nie musisz niczego instalować.

3. Zadanie 1. Konfigurowanie środowiska za pomocą Terraform

Utworzymy niestandardową sieć VPC z regułami zapory sieciowej i podsiecią. Otwórz konsolę Google Cloud i wybierz projekt, którego będziesz używać.

Otwórz Cloud Shell w prawym górnym rogu konsoli. Sprawdź, czy w Cloud Shell widzisz prawidłowy identyfikator projektu, i potwierdź wszystkie prośby o przyznanie dostępu.
Utwórz folder o nazwie terraform-build i przejdź do niego.

mkdir terraform-build  && cd terraform-build

Utwórz pliki main.tf i variable.tf.

touch main.tf variable.tf

Przełącz się na widok edytora Cloud Shell. Wybierz edytor i zaakceptuj wszystkie niezbędne prośby, aby interfejs mógł się załadować.
Po załadowaniu przejdź do Plik > Otwórz folder i otwórz folder /home/your-user-name/terraform-build. Następnie kliknij OK, aby otworzyć folder w edytorze.
Wybierz plik variable.tf i dodaj te informacje: Zastąp tekst your-project-id-here rzeczywistym identyfikatorem projektu w cudzysłowie.

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

variable "network_id" {
  type = string
  default = "gemini-vpc-net"
}

Następnie otwórz plik main.tf. Dodamy kod Terraform, aby wykonać różne działania opisane poniżej.

*Włączanie interfejsów API*	`resource` `"google_project_service"` `"default"`
*Utwórz sieć VPC o nazwie python-net*	`resource` `"google_compute_network"` `"default"`
*Dodawanie podsieci*	`resource` `"google_compute_subnetwork"` `"default"`
*Dodaj 2 reguły zapory sieciowej*	`resource` `"google_compute_firewall"` `"allow_icmp"resource` `"google_compute_firewall"` `"allow_ssh"`

Skopiuj poniższy kod i wklej go do pliku main .tf.

resource "google_project_service" "default" {
  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 = "192.168.100.0/24"
  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"]
}

Wróć do terminala Cloud Shell, upewnij się, że jesteś w katalogu terraform-build cd terraform-build, i uruchom te polecenia:

terraform init

Inicjuje katalog roboczy. Ten krok pobiera dostawców wymaganych w danej konfiguracji.

terraform plan

Generuje plan wykonania, który pokazuje, jakie działania Terraform podejmie w celu wdrożenia infrastruktury.

Aby utworzyć zasoby, uruchom polecenie terraform apply i wpisz yes.

4. Zadanie 2. Tworzenie bramy NAT i maszyn wirtualnych za pomocą Terraform

Musimy przyznać wychodzący dostęp zewnętrzny do internetu, więc utwórzmy bramę Cloud NAT i dołączmy ją.

Otwórz Cloud Shell, przejdź do folderu terraform-build i utwórz te pliki (w sumie 3 pliki). Później je edytujemy.

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

Przejdź do widoku edytora Cloud Shell, wybierz plik nat-vm.tf i dodaj ten kod Terraform. Spowoduje to utworzenie bramy NAT i 2 maszyn wirtualnych.

Terraform nat-vm.tf

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

 bgp {
  asn = 64514
  }
}

resource "google_compute_router_nat" "default" {
  name                               = "outbound-gw"
  router                             = google_compute_router.default.name
  region                             = google_compute_router.default.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

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

resource "google_compute_instance" "vm1" {
  name         = "cli-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  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
    sudo apt-get update    
  EOF
}

resource "google_compute_instance" "vm2" {
  name         = "monitor-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  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
    sudo apt-get update
    sudo apt-get install python3 python3-dev python3-venv -y
    sudo apt-get install tcpdump dnsutils -y
  EOF
}

Przejdź do terminala Cloud Shell, upewnij się, że jesteś w folderze terraform-build, i uruchom polecenie terraform plan. Wyświetli ono informację, że zostaną dodane 4 elementy. Następnie uruchom polecenie terraform apply i wpisz yes, aby utworzyć bramę NAT i 2 maszyny wirtualne.

5. Zadanie 3. Konfigurowanie maszyn wirtualnych interfejsu wiersza poleceń i testowanie

Otwórz Instancje maszyn wirtualnych. Wybierz maszynę wirtualną zaczynającą się od cli-vm. Wybierz SSH.
Po połączeniu się przez SSH będziesz mieć dostęp do maszyny wirtualnej. Utwórzmy folder, w którym będziemy uruchamiać interfejs wiersza poleceń Gemini.

mkdir geminicli && cd geminicli

Aby zainstalować interfejs Gemini CLI, potrzebujesz Node.js. Zainstaluj Node.js za pomocą tego polecenia:

curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh

Uruchom skrypt

sudo -E bash nodesource_setup.sh

Instalowanie Node.js

sudo apt-get install -y nodejs

Ustawmy kilka zmiennych, które pomogą w użyciu opcji uwierzytelniania Vertex AI do uwierzytelnienia tego narzędzia w celu późniejszego przeprowadzenia testów. PS Zastąp YOUR_PROJECT_ID rzeczywistym project ID

cat <<EOF >> ~/.bashrc 

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-east1" 
export GOOGLE_GENAI_USE_VERTEXAI=true
EOF

Ponowne wczytywanie bash

source ~/.bashrc

Teraz uwierzytelnijmy się. Uruchom w maszynie wirtualnej to polecenie i po wyświetleniu monitu naciśnij y.

gcloud auth application-default login

Następnie skopiuj adres URL zaczynający się od https://, otwórz nową kartę w oknie przeglądarki laboratorium i wklej adres URL. Postępuj zgodnie z wyświetlanymi instrukcjami.
Gdy zobaczysz poniższy tekst, wybierz kopiowanie, wróć do sesji maszyny wirtualnej cli-vm i w sekcji Enter authorization code: (Wpisz kod autoryzacji:) wklej skopiowany kod i naciśnij Enter, aby się uwierzytelnić.

Teraz zainstalujmy wiersz poleceń Gemini. Uruchom to polecenie:

sudo npm install -g @google/gemini-cli

Po zakończeniu wpisz gemini, aby uruchomić interfejs, wybierz preferowany motyw, a w sekcji Wybierz metodę uwierzytelniania kliknij Vertex AI.

Po uwierzytelnieniu możesz zacząć korzystać z Gemini CLI.

Monitorowanie trasy ruchu do Gemini za pomocą monitora maszyny wirtualnej

Otwórz Instancje maszyn wirtualnych. Wybierz maszynę wirtualną zaczynającą się od monitor-vm. Wybierz SSH.
Po połączeniu się z monitor-vm przez SSH będziesz mieć dostęp
Użyjmy polecenia dig, aby przetestować ścieżkę połączenia z interfejsem Gemini API. Użyjemy us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Powinien pojawić się ekran podobny do tego (adres będzie inny). Pamiętaj, że ścieżka prowadzi przez publiczne adresy IP, ponieważ interfejs API jest publiczny.

NIE KOPIUJ

; <<>> DiG 9.18.33-1~deb12u2-Debian <<>> us-east1-aiplatform.googleapis.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58905
;; flags: qr rd ra; QUERY: 1, ANSWER: 14, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;us-east1-aiplatform.googleapis.com. IN A

;; ANSWER SECTION:
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.217.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.204.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.203.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.250.98.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.251.107.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.196.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.216.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.11.95
us-east1-aiplatform.googleapis.com. 300 IN A    192.178.219.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.210.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.212.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.215.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.12.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.26.95

Teraz przeprowadźmy szybki ping test, aby sprawdzić, czy możemy połączyć się z interfejsem Gemini API. To polecenie użyje 4 pingów do us-east1-aiplatform.googleapis.com, więc otrzymamy odpowiedź z publicznego adresu interfejsu API.

ping -c 4 us-east1-aiplatform.googleapis.com

W przyszłości wrócimy do testowania tej maszyny wirtualnej. Zamknij sesję SSH i przejdźmy dalej.

6. Zadanie 4. Tworzenie punktu końcowego PSC dla googleapis za pomocą Terraform

Aby włączyć prywatną łączność z naszym punktem końcowym interfejsu Vertex API, utworzymy punkt końcowy usługi Private Service Connect dla interfejsów API Google. Dzięki temu będziemy mogli używać przypisanego przez nas prywatnego adresu IP do kierowania ruchu do potrzebnych nam interfejsów API Google, w tym przypadku Vertex.

Otwórz Cloud Shell w widoku edytora, jeśli nie jest jeszcze otwarty. Utworzymy te elementy:

Utwórz adres IP dla punktu końcowego PSC 10.10.100.250 (resource "google_compute_global_address" "default")
Tworzenie punktu końcowego PSC dla interfejsów API Google (resource "google_compute_global_forwarding_rule" "default")

Otwórz plik psc.tf w folderze terraform-build. Dodaj do pliku ten kod:

Terraform psc.tf

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

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

Przejdź do terminala Cloud Shell i upewnij się, że jesteś w folderze terraform-build. Następnie uruchom terraform init Następnie uruchom terraform plan, aby zobaczyć, że zostaną dodane 2 elementy,
a potem uruchom terraform apply i wpisz yes, aby utworzyć punkt końcowy interfejsów API Google IP i PSC.
Sprawdzanie, czy punkt końcowy istnieje

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

gcloud compute forwarding-rules describe pscgemini --global

7. Zadanie 5. Tworzenie ręcznego wpisu DNS dla googleapis za pomocą Terraform

Możesz utworzyć ręczny wpis DNS, aby wskazywał punkt końcowy PSC przy użyciu prywatnego DNS. Będzie to miało wpływ na wszystkie sieci, które do niej przypiszesz.

Przejdź do Usług sieciowych i wybierz Cloud DNS.
W strefach powinna być widoczna automatycznie utworzona strefa usługi Private Service Connect dla interfejsów API Google o typie strefy Service Directory. Możesz go użyć do połączenia się z punktem końcowym PSC w formacie **SERVICE-ENDPOINT.p.googleapis.com. Przykład: aiplatform-pscgemini.p.googleapis.com
W tym przypadku chcemy ręcznie utworzyć wpis prywatnego DNS. Konfiguracja będzie wyglądać tak:

Utwórz prywatną strefę DNS o nazwie „googleapis-private” dla domeny „googleapis.com” i ogranicz ją do sieci „python-net”.
Dodaj rekord A, aby przypisać „googleapis.com” do adresu IP „10.10.100.250”.
Dodaj rekord CNAME, aby przekierować wszystkie subdomeny domeny „googleapis.com” (np. www.googleapis.com) na „googleapis.com”.

Otwórz Cloud Shell w widoku edytora, jeśli nie jest jeszcze otwarty. Otwórz plik dns.tf w folderze terraform-build. Dodaj do pliku ten kod.

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 = ["10.10.100.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."]  
}

Przejdź do terminala Cloud Shell i upewnij się, że jesteś w folderze terraform-build. Następnie uruchom terraform plan, aby zobaczyć, które elementy zostaną dodane.
Następnie uruchom terraform apply i wpisz yes, aby utworzyć prywatny wpis DNS.
Powinna pojawić się konfiguracja z rekordem A i rekordem CNAME, jak pokazano poniżej:

Następnie sprawdzamy połączenie po wprowadzeniu tych zmian na maszynie monitor-vm.

8. Zadanie 7. Sprawdzanie łączności punktu końcowego za pomocą adresu IP

Połączmy się z Gemini za pomocą prywatnego punktu końcowego.

Otwórz instancję maszyny wirtualnej monitor-vm. Wybierz SSH i połącz się z maszyną wirtualną przez SSH
Sprawdź ścieżkę połączenia z adresem us-east1-aiplatform.googleapis.com za pomocą polecenia ping. Spowoduje to wysłanie polecenia ping na adres IP w prywatnym DNS, rekord A dla googleapis. Ten adres IP to punkt końcowy PSC, więc pingi nie będą działać.

ping -c 2 us-east1-aiplatform.googleapis.com

Sprawdź ścieżkę połączenia za pomocą ping, korzystając z automatycznie utworzonego wpisu DNS dla interfejsów API Google PSC z aiplatform-pscvertexgemini.p.googleapis.com. Wskazuje to adres IP punktu końcowego PSC, a pingi będą nieudane.

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

Sprawdź ścieżkę połączenia z adresem us-east1-aiplatform.googleapis.com za pomocą polecenia dig. Powinien to być adres IP punktu końcowego PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

Po zakończeniu możesz zamknąć sesję SSH monitor-vm.
Teraz możemy uruchomić zrzut TCP na maszynie wirtualnej cli-vm. Musimy otworzyć 2 sesje SSH na tej samej maszynie wirtualnej. W jednej sesji uruchomimy polecenie tcpdump, a w drugiej użyjemy interfejsu wiersza poleceń Gemini.
Połącz się przez SSH z pierwszą sesją na cli-vm.
Aby sprawdzić łączność w tcpdump, wpisz to polecenie:

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

Teraz połącz się przez SSH z następną sesją na maszynie wirtualnej cli-vm.
Aktywuj interfejs wiersza poleceń Gemini, wpisując gemini
Zadaj pytanie „Jakiego koloru jest niebo?”, aby wygenerować wywołanie interfejsu Gemini API.

Naciśnij Enter, aby uruchomić zapytanie i zobaczyć wynik.
Wróć do pierwszej sesji na cli-vm. Powinien pojawić się wynik tcpdump. Zauważysz, że adres IP maszyny wirtualnej używa adresu IP punktu końcowego PSC do łączenia się z interfejsem Gemini API.

Zamknij wszystkie sesje SSH na instancjach maszyn wirtualnych.

9. Czyszczenie

Otwórz Cloud Shell i upewnij się, że jesteś w katalogu terraform-build cd terraform-build. Uruchom to polecenie terraform destroy i wpisz yes wszystkie zasoby utworzone w projekcie za pomocą Terraform. Zostaną one usunięte.

10. Gratulacje

Gratulacje. Udało Ci się połączyć z interfejsem Gemini CLI zarówno przy użyciu publicznego adresu API, jak i prywatnie przy użyciu punktu końcowego usługi Private Service Connect dla interfejsów Google API. Ta funkcja może rozszerzyć łączność z prywatnym interfejsem API na środowisko lokalne lub inne środowisko w chmurze, które są połączone za pomocą połączenia międzysieciowego, połączenia międzychmurowego i VPC.

Kolejne kroki / Więcej informacji

Więcej informacji o sieci Vertex AI znajdziesz w repozytorium interfejsu wiersza poleceń Gemini.

Przejdź do kolejnego modułu

Kontynuuj naukę w Google Cloud i zapoznaj się z tymi modułami Google Cloud: