1. סקירה כללית
אתם יכולים להשתמש ב-Gemini CLI בסביבות מקומיות וגם בסביבות וירטואליות. Gemini CLI הוא סוכן AI בקוד פתוח שמאפשר להשתמש ביכולות של Gemini ישירות במסוף. מבחינת רשת, כשמשתמשים ב-Gemini CLI, מתבצעת קריאה ל-Gemini API דרך כתובת ה-IP של ה-API, שזמינה לציבור.
מה קורה אם רוצים להשתמש ב-Gemini CLI במכונת Google Compute Engine, אבל רוצים להתחבר לממשק ה-API באופן פרטי? ב-codelabs הזה נראה איך להגדיר נקודת קצה של Private Service Connect ל-Google API, כדי לנתב את התנועה לכתובת IP פנימית שאתם מציינים.
ההגדרות יהיו שילוב של Terraform, gcloud והמסוף.
בשיעור ה-Lab הזה תלמדו איך לבצע את המשימה הבאה:
- הגדרה של מופע VM ו-Cloud NAT
- התקנה של Gemini CLI ואימות
- הגדרת נקודת קצה מסוג Private Service Connect כדי להתחבר אל Googleapis
- אימות נתיב הקישוריות אל *.googleais
- הגדרת רשומות DNS ידניות
בשיעור ה-Lab הזה תיצרו את התבנית הבאה.
איור 1.
2. הגדרה של שירותי Google Cloud
הגדרת סביבה בקצב אישי
- נכנסים ל-Google Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, אתם צריכים ליצור חשבון.
- שם הפרויקט הוא השם המוצג למשתתפים בפרויקט. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
- מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית. בדרך כלל לא צריך לדעת מה היא. ברוב המדריכים ללימוד תכנות, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-
PROJECT_ID
). אם לא אהבתם את המזהה שנוצר, תוכלו ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא נשארת לאורך הפרויקט. - לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.
- בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולוודא שלא תחויבו על שימוש בהם אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.
הפעלת Cloud Shell
אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.
ב-Google Cloud Console, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:
יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:
המכונה הווירטואלית הזו כוללת את כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.
3. משימה 1: הגדרת סביבה באמצעות Terraform
ניצור VPC בהתאמה אישית עם כללי חומת אש ותת-רשת. פותחים את מסוף Cloud ובוחרים את הפרויקט שבו רוצים להשתמש.
- פותחים את Cloud Shell בפינה השמאלית העליונה של המסוף, מוודאים שמופיע מזהה הפרויקט הנכון ב-Cloud Shell ומאשרים את כל ההנחיות שמופיעות כדי לאפשר גישה.
- יוצרים תיקייה בשם terraform-build ועוברים לתיקייה
mkdir terraform-build && cd terraform-build
- יוצרים קובץ main.tf וקובץ variable.tf.
touch main.tf variable.tf
- עוברים לתצוגה של Cloud Shell Editor. בוחרים באפשרות עורך ומוודאים שמאשרים את כל ההנחיות הנדרשות כדי שהממשק ייטען.
- אחרי הטעינה, עוברים אל File > Open Folder, אל /home/your-user-name/terraform-build ולוחצים על Ok כדי לפתוח את התיקייה בכלי העריכה.
- בוחרים את הקובץ variable.tf ומוסיפים את הקוד הבא. מחליפים את הטקסט
your-project-id-here
במזהה הפרויקט בפועל בתוך מרכאות.
variable "project_id" { type = string default = "your-project-id-here" } variable "network_id" { type = string default = "gemini-vpc-net" }
- לאחר מכן פותחים את הקובץ main.tf. נוסיף קוד Terraform כדי לבצע פעולות שונות, כמו שמוסבר בהמשך.
הפעלת ממשקי API |
|
יצירת VPC בשם python-net |
|
הוספת תת-רשת |
|
הוספת שני כללים לחומת האש |
|
- מעתיקים את הקוד הבא ומדביקים אותו בקובץ 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"] }
- חוזרים אל מסוף Cloud Shell, מוודאים שאתם בספרייה terraform-build
cd terraform-build
ומריצים את הפקודות הבאות:
terraform init
מאתחלת את ספריית העבודה. בשלב הזה מתבצעת הורדה של הספקים שנדרשים להגדרה הנתונה.
terraform plan
יוצרת תוכנית ביצוע שמראה אילו פעולות Terraform תבצע כדי לפרוס את התשתית.
- כדי ליצור את המשאבים, מריצים את הפקודה
terraform apply
ומקלידיםyes
כדי להריץ.
4. משימה 2: יצירת שער NAT ומכונות וירטואליות באמצעות Terraform
אנחנו צריכים להעניק גישה חיצונית לאינטרנט, אז ניצור שער Cloud NAT ונקשר אותו.
- פותחים את Cloud Shell, עוברים לתיקייה terraform-build ויוצרים את הקבצים הבאים (סה"כ שלושה קבצים). נערוך אותם בהמשך.
touch nat-vm.tf psc.tf dns.tf
- עוברים לתצוגה Cloud Shell editor, בוחרים את הקובץ nat-vm.tf ומוסיפים את קוד Terraform הבא. הפעולה הזו תיצור שער NAT ושתי מכונות וירטואליות.
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
}
- עוברים אל Cloud Shell terminal, מוודאים שאתם בתיקייה terraform-build ומריצים את הפקודה
terraform plan
. הפקודה הזו תראה לכם ש-4 פריטים יתווספו. לאחר מכן מריצים את הפקודהterraform apply
ומקלידיםyes
כדי ליצור את שער ה-NAT ושני מכונות וירטואליות.
5. משימה 3: הגדרת מכונות וירטואליות של CLI ובדיקה
- עוברים אל VM instances (מכונות וירטואליות). בוחרים את המכונה הווירטואלית שמתחילה ב-cli-vm. בוחרים באפשרות SSH.
- אחרי שמתחברים באמצעות SSH, אמורה להיות לכם גישה למכונה הווירטואלית. ניצור תיקייה להרצת Gemini CLI.
mkdir geminicli && cd geminicli
- כדי להתקין את Gemini CLI, צריך Node.js. מתקינים את node JS באמצעות הפקודה הבאה
curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
הרץ את הסקריפט
sudo -E bash nodesource_setup.sh
התקנה של Node js
sudo apt-get install -y nodejs
- בואו נגדיר כמה משתנים שיעזרו לנו להשתמש באפשרות האימות של Vertex AI כדי לאמת את זה ולבצע בדיקות בהמשך. נ.ב. צריך להחליף את
YOUR_PROJECT_ID
בערך האמיתי של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
טעינה מחדש של bash
source ~/.bashrc
- עכשיו נבצע אימות. מריצים את הפקודה הבאה במכונת ה-VM ומקישים על y כשמתבקשים.
gcloud auth application-default login
- לאחר מכן מעתיקים את כתובת ה-URL שמופיעה ומתחילה ב-https://, פותחים כרטיסייה חדשה בחלון הדפדפן של המעבדה ומדביקים את כתובת ה-URL. פועלים לפי ההנחיות.
- כשמופיעה האפשרות 'העתקה', בוחרים בה, חוזרים להפעלה של cli-vm ובשדה Enter authorization code: (הזנת קוד הרשאה) מדביקים את הקוד שהעתקתם ולוחצים על Enter כדי לבצע אימות.
- עכשיו נתקין את Gemini CLI ונריץ את הפקודה
sudo npm install -g @google/gemini-cli
אחרי שמסיימים להקליד gemini
כדי להפעיל את הממשק, בוחרים את העיצוב המועדף ובקטע Select Auth method (בחירת שיטת אימות) בוחרים באפשרות Vertex AI
.
- אחרי האימות, אפשר להתחיל להשתמש ב-Gemini CLI
מעקב אחר נתיב התנועה אל Gemini באמצעות monitor vm
- עוברים אל VM instances (מכונות וירטואליות). בוחרים את המכונה הווירטואלית שמתחילה ב-monitor-vm. בוחרים באפשרות SSH.
- אחרי שמתחברים ב-SSH אל monitor-vm, אמורה להיות לכם גישה
- נשתמש בפקודה
dig
כדי לבדוק את נתיב החיבור ל-Gemini API. נשתמש ב-us-east1-aiplatform.googleapis.com
dig us-east1-aiplatform.googleapis.com
אמורה להופיע כתובת דומה (אבל לא זהה). הערה: הנתיב הוא דרך כתובות IP ציבוריות, כי ה-API הוא API ציבורי.
לא להעתיק
; <<>> 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
- עכשיו נבצע בדיקה מהירה של
ping
כדי לראות אם אפשר להתחבר ל-Gemini API. הפקודה הזו תשתמש ב-4 פינגים ל-us-east1-aiplatform.googleapis.com, כך שנקבל תגובה מהכתובת הציבורית של ה-API.
ping -c 4 us-east1-aiplatform.googleapis.com
- נחזור לבדוק את המכונה הווירטואלית הזו בהמשך. צריך לסגור את סשן ה-SSH כדי להמשיך.
6. משימה 4: יצירת נקודת קצה של PSC ל-googleapis באמצעות Terraform
כדי להפעיל קישוריות פרטית לנקודת הקצה של Vertex API, ניצור נקודת קצה של Private Service Connect לממשקי API של Google. כך נוכל להשתמש בכתובת IP פרטית שהקצנו כדי לנתב תנועה לממשקי Google API שדרושים לנו, במקרה הזה Vertex.
- אם Cloud Shell לא פתוח, פותחים אותו בתצוגת עריכה. אנחנו ניצור את הפריטים הבאים:
- יוצרים כתובת IP לנקודת הקצה של PSC 10.10.100.250 (
resource "google_compute_global_address" "default")
- יצירת נקודת קצה של PSC ל-Google APIs (
resource "google_compute_global_forwarding_rule" "default")
פותחים את הקובץ psc.tf בתיקייה terraform-build. מוסיפים את הקוד הבא לקובץ.
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 = ""
}
- עוברים אל Cloud Shell terminal ומוודאים שאתם נמצאים בתיקייה
terraform-build
. לאחר מכן מריצים את הפקודהterraform init
Then runterraform plan
this will show you that 2 items will be added,
ואז מריצים את הפקודהterraform apply
ומקלידיםyes
כדי ליצור את נקודת הקצה של כתובת ה-IP ושל Google APIs ב-PSC. - אימות קיום של נקודת קצה
gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"
gcloud compute forwarding-rules describe pscgemini --global
7. משימה 5: יצירת רשומת DNS ידנית ל-googleapis באמצעות Terraform
אפשר ליצור רשומת DNS ידנית כדי להפנות לנקודת הקצה של PSC באמצעות DNS פרטי. השינוי ישפיע על כל הרשתות שהוקצו לה.
- עוברים אל Network services (שירותי רשת) ובוחרים באפשרות Cloud DNS.
- באזורים, אמור להופיע אזור שנוצר באופן אוטומטי עבור Private Service Connect ל-Google APIs, עם סוג האזור service directory. אפשר להשתמש בכתובת הזו כדי להתחבר לנקודת הקצה (endpoint) של PSC בפורמט **SERVICE-ENDPOINT.p.googleapis.com לדוגמה:
aiplatform-pscgemini.p.googleapis.com
- במקרה הזה, אנחנו רוצים ליצור באופן ידני רשומה של DNS פרטי. ההגדרה תהיה כדלקמן
- יוצרים אזור DNS פרטי בשם googleapis-private עבור googleapis.com ומגבילים אותו לרשת python-net.
- מוסיפים רשומת A כדי למפות את 'googleapis.com' לכתובת ה-IP '10.10.100.250'.
- מוסיפים רשומת CNAME כדי להפנות את כל תתי-הדומיין של googleapis.com (לדוגמה, www.googleapis.com) אל googleapis.com.
- אם Cloud Shell לא פתוח, פותחים אותו בתצוגת עריכה. פותחים את הקובץ dns.tf בתיקייה terraform-build. מוסיפים את הקוד הבא לקובץ.
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."]
}
- עוברים אל Cloud Shell terminal ומוודאים שאתם נמצאים בתיקייה
terraform-build
. אחר כך מריצים את הפקודהterraform plan
כדי לראות אילו פריטים יתווספו,
ואז מריצים את הפקודהterraform apply
ומקלידיםyes
כדי ליצור את רשומת ה-DNS הפרטית. - ההגדרה אמורה לכלול רשומת A ורשומת CNAME, כמו בדוגמה הבאה
- בשלב הבא, אנחנו מאמתים את הקישוריות עם השינויים האלה ב-monitor-vm
8. משימה 7: אימות הקישוריות של נקודת הקצה באמצעות כתובת IP
נתחבר באמצעות נקודת הקצה הפרטית כדי להתחבר ל-Gemini.
- עוברים אל VM Instance monitor-vm. בוחרים באפשרות SSH ומתחברים למכונה הווירטואלית באמצעות SSH
- בודקים את נתיב הקישוריות אל us-east1-aiplatform.googleapis.com באמצעות הפקודה
ping
. הפעולה הזו תבצע פינג לכתובת ה-IP ב-DNS הפרטי, רשומת A עבור googleapis. כתובת ה-IP הזו היא נקודת קצה של PSC, והפינגים שלכם ייכשלו.
ping -c 2 us-east1-aiplatform.googleapis.com
- בודקים את נתיב הקישוריות באמצעות
ping
באמצעות רשומת ה-DNS שנוצרה אוטומטית עבור Google APIs של PSC עםaiplatform-pscvertexgemini.p.googleapis.com
. היא מצביעה על כתובת ה-IP של נקודת הקצה של PSC, והפינגים שלכם ייכשלו.
ping -c 2 aiplatform-pscgemini.p.googleapis.com
- בודקים את נתיב הקישוריות אל us-east1-aiplatform.googleapis.com באמצעות הפקודה
dig
. זו צריכה להיות כתובת ה-IP של נקודת הקצה (endpoint) של PSC (10.10.100.250).
dig us-east1-aiplatform.googleapis.com
- אחרי שהתהליך מסתיים, אפשר לסגור את סשן ה-SSH של monitor-vm.
- עכשיו אפשר להריץ TCP dump ב-cli-vm. נצטרך לפתוח שני סשנים של SSH לאותה מכונה וירטואלית. בסשן אחד תופעל הפקודה tcpdump, ובסשן השני נשתמש ב-Gemini CLI.
- התחברות ב-SSH לסשן הראשון ב-cli-vm
- מקלידים את הפקודה הבאה כדי לראות את הקישוריות ב-tcpdump
sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com
- עכשיו מתחברים ב-SSH לסשן הבא ב-cli-vm
- מפעילים את Gemini CLI על ידי הקלדת
gemini
- שואלים את השאלה הבאה: מה צבע השמיים, כדי ליצור קריאה ל-Gemini API
- מקישים על Enter כדי להריץ את הפקודה ולראות את התוצאה.
- חוזרים לסשן הראשון ב-cli-vm. אמורה להופיע תוצאה של tcpdump. תראו שהתנועה נכנסת ויוצאת, וכתובת ה-IP של המכונה הווירטואלית משתמשת בכתובת ה-IP של נקודת הקצה של PSC כדי להתחבר אל Gemini API
סגירת כל סשני ה-SSH למכונות וירטואליות
9. הסרת המשאבים
- עוברים אל Cloud Shell, מוודאים שאתם בספרייה terraform-build
cd terraform-build
, מריצים את הפקודה הבאהterraform destroy
ומקלידיםyes
. כל המשאבים שיצרתם בפרויקט באמצעות Terraform יוסרו.
10. מזל טוב
הצלחתם להתחבר ל-Gemini CLI באמצעות כתובת API ציבורית וגם באופן פרטי באמצעות נקודת קצה (endpoint) של Private Service Connect ל-Google APIs. הפונקציונליות הזו יכולה להרחיב את הקישוריות הפרטית של ה-API לסביבה המקומית או לסביבת ענן אחרת שמחוברת באמצעות (Interconnect, Cross-Cloud Interconnect ו-VPC).
השלבים הבאים / מידע נוסף
אפשר לקרוא מידע נוסף על Vertex AI networking ולעיין במאגר Gemini CLI
אל שיעור ה-Lab הבא
אתם יכולים להמשיך את יחידת ה-Quest ב-Google Cloud או לנסות את שיעורי ה-Lab הבאים של Google Cloud: